Explore doc-gen

docs/bpk-appearance.md

@@ -0,0 +1,326 @@
+
+# Reference
+
+
+## Api
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+-   [BpkDynamicStyleSheet][1]
+-   [isBpkDynamicValue][2]
+    -   [Parameters][3]
+-   [useBpkAppearance][4]
+-   [unpackBpkDynamicValue][5]
+    -   [Parameters][6]
+    -   [Examples][7]
+-   [useBpkColorScheme][8]
+-   [BpkAppearanceConsumer][9]
+    -   [Parameters][10]
+    -   [Examples][11]
+-   [withBpkAppearance][12]
+    -   [Parameters][13]
+    -   [Examples][14]
+-   [useBpkDynamicValue][15]
+    -   [Parameters][16]
+    -   [Examples][17]
+-   [unpackBpkDynamicStyle][18]
+    -   [Parameters][19]
+    -   [Examples][20]
+-   [useBpkDynamicStyle][21]
+    -   [Parameters][22]
+    -   [Examples][23]
+-   [useBpkDynamicStyleSheet][24]
+    -   [Parameters][25]
+    -   [Examples][26]
+-   [create][27]
+    -   [Parameters][28]
+    -   [Examples][29]
+
+## BpkDynamicStyleSheet
+
+## isBpkDynamicValue
+
+Check if a value is a `BpkDynamicValue`
+
+### Parameters
+
+-   `value` **mixed** the value to be checked
+
+Returns **[boolean][30]** true if is a `BpkDynamicValue` or false otherwise
+
+## useBpkAppearance
+
+Fetch the current appearance as provided by the nearest [BpkAppearanceProvider]
+
+Returns **BpkAppearancePreferences** the current appearance
+
+## unpackBpkDynamicValue
+
+Takes in a `BpkDynamicValue` and returns the correct value for provided appearance.
+
+### Parameters
+
+-   `value` **mixed** a dynamic value.
+-   `appearance` **[Object][31]** the appearance preferences.
+
+### Examples
+
+```javascript
+const color = unpackBpkDynamicValue({ light: 'black', dark: 'white' }, bpkAppearance)
+```
+
+Returns **mixed** the value for the current color scheme.
+                 If `value` is not a valid dynamic value it will be returned back
+
+## useBpkColorScheme
+
+Fetch the current color scheme as provided by the nearest [BpkAppearanceProvider]
+
+Returns **ColorSchemeName** the current color scheme
+
+## BpkAppearanceConsumer
+
+-   **See: [https://reactjs.org/docs/render-props.html][32]**
+
+A render prop component that provides the current BpkAppearance
+as provided by the nearest [BpkAppearanceProvider].
+
+NOTE: This component should mainly be used in class components, for
+functional components we recommend using the provided hooks.
+
+### Parameters
+
+-   `children` **[Function][33]** Function that will receive the current appearance and should return a react Node.
+    -   `children.children`
+
+### Examples
+
+```javascript
+<BpkAppearanceConsumer>
+  {({ bpkAppearance }) => {
+   const logo = unpackDynamicValue({ light: 'light.png', dark: 'dark.png' }, bpkAppearance);
+   return <BpkImage style={styles.image} alt="image title" source={{uri: logo}} />
+  }}
+</BpkAppearanceConsumer>
+```
+
+Returns **[Node][34]** a react Node.
+
+## withBpkAppearance
+
+This HOC wraps a component and provides the current `BpkAppearancePreferences`
+as provided by the nearest `BpkAppearanceProvider`.
+
+NOTE: If you are using a functional component use one of the provided hooks instead.
+
+### Parameters
+
+-   `Component` **Component** the component to be wrapped
+
+### Examples
+
+```javascript
+import React, { type Config } from 'react';
+import { type WithBpkAppearanceInjectedProps, withBpkAppearance } from '../../bpk-appearance';
+
+class MyComponent extends Component<Props & WithBpkAppearanceInjectedProps> {
+ render() {
+   const { bpkAppearance, ...rest } = this.props;
+   ....
+ }
+}
+
+export default withBpkAppearance<Config<Props, DefaultProps>>(MyComponent);
+```
+
+Returns **Component** the wrapped component with an extra `bpkAppearance` prop.
+
+## useBpkDynamicValue
+
+Takes in a `BpkDynamicValue` and returns the correct value for the
+current color scheme as provided by the nearest [BpkAppearanceProvider]
+
+### Parameters
+
+-   `value` **[Object][31]** a dynamic value.
+
+### Examples
+
+```javascript
+const color = useBpkDynamicValue({ light: 'black', dark: 'white' })
+```
+
+Returns **mixed** the value for the current color scheme.
+                 If `value` is not a valid dynamic value it will be returned back
+
+## unpackBpkDynamicStyle
+
+Takes in a style object and returns the correct value for all properties,
+based on the current color scheme as provided by the nearest [BpkAppearanceProvider]
+
+### Parameters
+
+-   `style` **[Object][31]** the style object
+-   `appearance` **[Object][31]** the appearance preferences.
+
+### Examples
+
+```javascript
+const style = unpackBpkDynamicStyle(
+ {
+   color: { light: 'black', dark: 'white' },
+   flex: 1,
+ },
+ appearance
+);
+```
+
+Returns **[Object][31]** object with mapped properties for the current color scheme
+
+## useBpkDynamicStyle
+
+Takes in a style object and returns the correct value for all properties,
+based on the current color scheme as provided by the nearest [BpkAppearanceProvider]
+
+### Parameters
+
+-   `style` **[Object][31]** the style object
+
+### Examples
+
+```javascript
+const color = useBpkDynamicStyle({
+ color: { light: 'black', dark: 'white' },
+ flex: 1,
+});
+```
+
+Returns **[Object][31]** object with mapped properties for the current color scheme
+
+## useBpkDynamicStyleSheet
+
+Takes in a `BpkDynamicStyleSheet` and returns the correct value for
+the current color scheme as provided by the nearest [BpkAppearanceProvider]
+
+### Parameters
+
+-   `style` **BpkDynamicStyle** the dynamic stylesheet
+
+### Examples
+
+```javascript
+const dynamicStyles = BpkDynamicStyleSheet.create({
+ color: { light: 'black', dark: 'white' },
+ flex: 1,
+})
+const styles = useBpkDynamicStyleSheet(dynamicStyles);
+```
+
+Returns **BpkDynamicStyleProp** the current stylesheet
+
+## create
+
+Creates a new dynamic stylesheet that transforms all `BpkDynamicValues` into
+a plain `StyleSheet` for each color scheme.
+
+This should generally be used in conjunction with `useBpkDynamicStyleSheet` hook.
+
+### Parameters
+
+-   `obj` **[Object][31]** a style containing dynamic values
+
+### Examples
+
+```javascript
+BpkDynamicStyleSheet.create({
+  view: {
+    shadowColor: { light: '#fff', dark: '#ff0' },
+  }
+});
+```
+
+```javascript
+BpkDynamicStyleSheet.create({
+  view: {
+    light: {
+      borderWidth: 1,
+      borderColor: '#d6d7da',
+    },
+    dark: {
+      backgroundColor: 'rgb(205, 205, 215)'
+    },
+  }
+});
+```
+
+Returns **BpkDynamicStyle** an object containing a plain stylesheet for each color scheme.
+
+[1]: #bpkdynamicstylesheet
+
+[2]: #isbpkdynamicvalue
+
+[3]: #parameters
+
+[4]: #usebpkappearance
+
+[5]: #unpackbpkdynamicvalue
+
+[6]: #parameters-1
+
+[7]: #examples
+
+[8]: #usebpkcolorscheme
+
+[9]: #bpkappearanceconsumer
+
+[10]: #parameters-2
+
+[11]: #examples-1
+
+[12]: #withbpkappearance
+
+[13]: #parameters-3
+
+[14]: #examples-2
+
+[15]: #usebpkdynamicvalue
+
+[16]: #parameters-4
+
+[17]: #examples-3
+
+[18]: #unpackbpkdynamicstyle
+
+[19]: #parameters-5
+
+[20]: #examples-4
+
+[21]: #usebpkdynamicstyle
+
+[22]: #parameters-6
+
+[23]: #examples-5
+
+[24]: #usebpkdynamicstylesheet
+
+[25]: #parameters-7
+
+[26]: #examples-6
+
+[27]: #create
+
+[28]: #parameters-8
+
+[29]: #examples-7
+
+[30]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[32]: https://reactjs.org/docs/render-props.html
+
+[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[34]: https://developer.mozilla.org/docs/Web/API/Node/nextSibling