chore: add uw-native-ui migration docs (#404)

apps/native-ui-storybook/components/lab/Actionsheet/Actionsheet.docs.mdx

@@ -75,7 +75,7 @@ The Actionsheet component presents a set of options to the user, overlaid on top
 
 ## Props
 
-### Actionsheet
+### `Actionsheet`
 
 It inherits all the properties of React Native's View component.
 
@@ -94,11 +94,11 @@ It inherits all the properties of React Native's View component.
 | `children`              | `any`                  | The content to display inside the Actionsheet                                                                                                                                                                                                                                                         | -       |
 | `snapPoints`            | `Array<number>`        | The snap points for the Actionsheet The Actionsheet will snap to the point closest to its current position. The default value is 50% of the screen height. The value should be between 0 and 100. Currently, only one snap point is supported. We plan to support multiple snap points in the future. | [50]    |
 
-### ActionsheetBackdrop
+### `ActionsheetBackdrop`
 
 It is React Native's Pressable component, created using @legendapp/motion's createMotionAnimatedComponent function to add animation to the component. You can use any declarative animation library you prefer.
 
-### ActionsheetContent
+### `ActionsheetContent`
 
 It inherits all the properties of @legendapp/motion's Motion.View component. With this Actionsheet component, you have the flexibility to use any declarative animation library that suits your needs.
 
@@ -110,15 +110,15 @@ Props to style child components.
 | -------------------- | ---------------------------------------------------- |
 | `_sectionHeaderText` | Prop to style ActionsheetSectionHeaderText Component |
 
-### ActionsheetDragIndicatorWrapper
+### `ActionsheetDragIndicatorWrapper`
 
 It inherits all the properties of React Native's View component.
 
-### ActionsheetDragIndicator
+### `ActionsheetDragIndicator`
 
 It inherits all the properties of React Native's View component.
 
-### ActionsheetItem
+### `ActionsheetItem`
 
 It inherits all the properties of React Native's Pressable component.
 
@@ -131,31 +131,31 @@ Props to style child components.
 | `_text` | Prop to style ActionsheetItemText Component |
 | `_icon` | Prop to style ActionsheetIcon Component     |
 
-### ActionsheetItemText
+### `ActionsheetItemText`
 
 It inherits all the properties of React Native's Text component.
 
-### ActionsheetIcon
+### `ActionsheetIcon`
 
 It inherits all the properties of React Native's View component.
 
-### ActionsheetScrollView
+### `ActionsheetScrollView`
 
 It inherits all the properties of React Native's ScrollView component.
 
-### ActionsheetVirtualizedList
+### `ActionsheetVirtualizedList`
 
 It inherits all the properties of React Native's VirtualizedList component.
 
-### ActionsheetFlatList
+### `ActionsheetFlatList`
 
 It inherits all the properties of React Native's FlatList component.
 
-### ActionsheetSectionList
+### `ActionsheetSectionList`
 
 It inherits all the properties of React Native's SectionList component.
 
-### ActionsheetSectionHeaderText
+### `ActionsheetSectionHeaderText`
 
 It inherits all the properties of React Native's Text component.
 
@@ -172,7 +172,7 @@ It inherits all the properties of React Native's Text component.
 
 ## Examples
 
-### With ScrollView
+### With `ScrollView`
 
 <Canvas of={Stories.WithScrollView} />
 

apps/native-ui-storybook/docs/components/VariantTitle.tsx

@@ -1,8 +1,8 @@
 import { Box, Text } from '@utilitywarehouse/native-ui';
 
-const VariantTitle = ({ title, children }: any) => (
+const VariantTitle = ({ title, upperCase = true, children }: any) => (
   <Box gap="$2">
-    <Text textTransform="uppercase" size="xs" highlight color="$grey600">
+    <Text textTransform={upperCase ? 'uppercase' : 'none'} size="xs" highlight color="$grey600">
       {title}
     </Text>
     {children}

apps/native-ui-storybook/docs/native-ui/guides/contributing.mdx

@@ -19,7 +19,7 @@ contributions to the codebase and documentation.
 Run setup in the root of the repo. This will install [pnpm](https://pnpm.io/),
 which we use to manage this monorepo.
 
-**Make sure you're using node v16.10+ before running the below commands**
+**Make sure you're using node v18+ before running the below commands**
 
 ```
 npm run setup

apps/native-ui-storybook/docs/native-ui/guides/migration.mdx

@@ -4,4 +4,239 @@ import { Meta } from '@storybook/blocks';
 
 # Migration Guide
 
-Coming Soon
+This guide is intended to help you migrate from our old React Native UI library, UW Native UI (`@utilitywarehouse/uw-native-ui`)
+to Native UI (`@utilitywarehouse/native-ui`). Although you can use both libraries in the same project, it is recommended that you
+migrate to Native UI as UW Native UI is deprecated.
+
+- [Key Info](#key-info)
+- [Migration Steps](#migration-steps)
+  - [Components](#components)
+    - [`Button`](#button)
+    - [`Typography`](#typography)
+    - [`ThemeProvider`](#themeprovider)
+  - [Styles](#styles)
+    - [`StyleSheet`](#stylesheet)
+    - [Dark Mode](#dark-mode)
+  - [Fonts](#fonts)
+  - [Colours](#colours)
+- [Known Issues](#known-issues)
+  - [`TypeError: Cannot read property 'x' of undefined`](#typeerror-cannot-read-property-x-of-undefined)
+- [Support](#support)
+
+## Key Info
+
+- UW Native UI: `@utilitywarehouse/uw-native-ui` - [Repo](https://github.com/utilitywarehouse/uw-native-ui)
+- Native UI: `@utilitywarehouse/native-ui` - [Repo](https://github.com/utilitywarehouse/design-systems/tree/main/packages/native-ui)
+
+- `@utilitywarehouse/uw-native-ui` is deprecated and will not receive any updates.
+- `@utilitywarehouse/native-ui` is the new library and will receive updates and new features.
+- `@utilitywarehouse/native-ui` is a complete rewrite of `@utilitywarehouse/uw-native-ui` and has a different API.
+- `@utilitywarehouse/uw-native-ui` uses `react-native-paper` under the hood.
+- `@utilitywarehouse/native-ui` uses `gluestack-ui` under the hood.
+- `@utilitywarehouse/native-ui` uses `gluestack-style` for styling, this has a similar API to other popular UI
+  libaraies and exposes a `styled` method, utility and props at the component level.
+
+## Migration Steps
+
+### Components
+
+Not all components from `@utilitywarehouse/uw-native-ui` are available in `@utilitywarehouse/native-ui` yet and
+not all components have a 1:1 mapping. Below are the steps to replace the components.
+
+#### `Button`
+
+Replace all `Button` components from `@utilitywarehouse/uw-native-ui` with `@utilitywarehouse/native-ui`.
+
+```tsx
+- import { Button } from '@utilitywarehouse/uw-native-ui';
++ import { Button, ButtonText } from '@utilitywarehouse/native-ui';
+
+...
+
+- <Button onPress={handleClick}>Click me</Button>
++ <Button onPress={handleClick}><ButtonText>Click me</Button></Button>
+```
+
+For more info see the [Button](/docs/native-ui-components-button--docs) documentation.
+
+#### `Typography`
+
+The `Typography` component doesn't map 1:1 with `@utilitywarehouse/uw-native-ui`. You can use the `Text` and `Heading` components
+from `@utilitywarehouse/native-ui` instead.
+
+```tsx
+- import { Typography } from '@utilitywarehouse/uw-native-ui';
++ import { Text, Heading } from '@utilitywarehouse/native-ui';
+
+...
+
+- <Typography variant="h1">Heading 1</Typography>
++ <Heading size="h1">Heading 1</Heading>
+
+- <Typography variant="body">Body text</Typography>
++ <Text>Body text</Text>
+```
+
+For more info see the [Text](/docs/native-ui-components-text--docs) and [Heading](/docs/native-ui-components-heading--docs) documentation.
+
+#### `ThemeProvider`
+
+```tsx
+- import { ThemeProvider } from '@utilitywarehouse/uw-native-ui';
++ import { NativeUIProvider } from '@utilitywarehouse/native-ui';
+```
+
+```tsx
+- <ThemeProvider theme={theme} variant={colorMode}>
++ <NativeUIProvider theme={theme} colorMode={colorMode}>
+```
+
+More info can be found in the [Getting Started](/docs/native-ui-introduction--docs#dark-mode) documentation.
+
+### Styles
+
+`@utilitywarehouse/uw-native-ui` uses `StyleSheet` from `react-native` for styling, whereas `@utilitywarehouse/native-ui` uses
+`gluestack-style` for styles. You can still use the `StyleSheet` from `react-native` with `@utilitywarehouse/native-ui` but
+it is recommended to use the `sx` prop for styling. You can also use the `styled` method and utility props for styling.
+See out [Styling](/docs/native-ui-guides-styling-overview--docs) documentation for more info.
+
+#### `StyleSheet`
+
+```tsx
+- import { StyleSheet } from 'react-native';
+- import { View } from '@utilitywarehouse/uw-native-ui';
++ import { Box } from '@utilitywarehouse/native-ui';
+// or
++ import { styled } from '@utilitywarehouse/native-ui';
+
+- const styles = StyleSheet.create({
+-   container: {
+-     backgroundColor: 'red',
+-   },
+- });
+
+- <View style={styles.container}>
+
++ <Box sx={{ backgroundColor: 'red' }}>
+
+// or
+
++ <Box bg="red" />
+
+// or
+
++ const StyledBox = styled(Box, {
++   backgroundColor: 'red',
++ });
+```
+
+#### Dark Mode
+
+lt the light colour mode is enabled. If you want to enable dark mode, you can pass the `colorMode` prop to the `NativeUIProvider` component. The two options for `colorMode` are `light` and `dark`.
+
+```tsx
+import { ColorSchemeName, useColorScheme } from 'react-native';
+
+const App: React.FC = () => {
+  const colorScheme = useColorScheme();
+
+  return (
+    <NativeUIProvider colorMode={colorScheme as ColorSchemeName}>
+      <App />
+    </NativeUIProvider>
+  );
+};
+```
+
+You can also use the `useColorMode` hook to get the current colour mode of the device.
+
+```tsx
+- import { useDarkMode } from '@utilitywarehouse/uw-native-ui';
++ import { useColorMode } from '@utilitywarehouse/native-ui';
+```
+
+Dark mode is also baked into the styling so you no longer need to use the `DynamicValue` for the colour scheme.
+
+```tsx
+- import { DynamicValue, makeDynamicStyles, Typography } from '@utilitywarehouse/uw-native-ui';
++ import { Box, Text } from '@utilitywarehouse/native-ui';
+
+- const useDynamicStyles = makeDynamicStyles(theme => ({
+-   root: {
+-     backgroundColor: new DynamicValue('white', 'black');
+-     margin: 20,
+-   },
+- }));
+
+const MyComponent = () => {
+- const styles = useDynamicStyles();
+
+  return (
+-    <View style={styles.root}>
++    <Box sx={
++      backgroundColor: '$white',
++      margin: 20,
++      _dark: {
++        backgroundColor: '$black',
++      },
++    }>
+}
+
+-      <Typography>{title}</Typography>
++      <Text>{title}</Text>
+-    </View>
++    </Box>
+  );
+}
+```
+
+### Fonts
+
+If you have followed the [getting started steps](/docs/native-ui-introduction--docs#additional-packages) and are using either
+`npx react-native-asset` or `expo-font` with `expo-xml-font` then you can use the `fontFamily` property like you would on the web
+when writing styles.
+
+```tsx
+const styles = StyleSheet.create({
+  title: {
+    color: '#20232a',
+    textAlign: 'center',
+-   fontFamily: 'Aeonik-Bold',
++   fontFamily: 'Aeonik',
++   fontWeight: '700',
+    fontSize: 30,
+  },
+  body: {
+-   fontFamily: 'WorkSans-Regular',
++   fontFamily: 'Work Sans',
++   fontWeight: '400',
+    fontSize: 16,
+  }
+});
+```
+
+For more info see the [Fonts](/docs/native-ui-guides-styling-fonts--docs) documentation.
+
+### Colours
+
+Please see the colour system [migration docs](/docs/colour-system-migration--docs) for more info on how to migrate your colours.
+
+## Known Issues
+
+### `TypeError: Cannot read property 'x' of undefined`
+
+For the most part both libraries should work together but there may be some issues with the `gluestack-ui` and `react-native-paper`
+and their respective themes. When using both libraries together, specifically using `uw-native-ui` components inside of `native-ui` components
+you may encounter the following error:
+
+```console
+TypeError: Cannot read property 'x' of undefined
+```
+
+If you encounter this issue, you can try to use the `ThemeProvider` from `@utilitywarehouse/uw-native-ui` and wrap the `uw-native-ui`
+component with it. This should fix the issue.
+
+## Support
+
+If you notice any other issues, or have any questions please raise an issue on the respective GitHub repository, contact the Design Systems team on Slack
+on the channels [#help-design-systems](https://utilitywarehouse.slack.com/archives/C04MKBQ34PJ) or [#tool-native-ui](https://utilitywarehouse.slack.com/archives/C03JP9CV77H).

apps/native-ui-storybook/docs/native-ui/guides/styling/color-mode.mdx

@@ -35,8 +35,18 @@ In the below example we are defining styles to be applied in dark mode in `_dark
 <Button $dark-bg="$cyan600" $light-bg="$red600" p="$2">
   <ButtonText>Hello world</ButtonText>
 </Button>
+
 // or
+
 <Button sx={{ backgroundColor: '$red600', p: "$2", _dark: { backgroundColor: '$darkCyan600' }, }}>
   <ButtonText>Hello world</ButtonText>
 </Button>
+
+// or
+
+const StyledButton = styled(Button, {
+  backgroundColor: '$red600',
+  p: "$2",
+  _dark: { backgroundColor: '$darkCyan600' },
+});
 ```

apps/native-ui-storybook/docs/native-ui/guides/styling/descendants.mdx

@@ -42,4 +42,17 @@ In the below example we are applying styles to ButtonText by passing styles `_te
     </Button>
   </Box>
 </Box>
+
+// or
+
+<Button sx={{ backgroundColor: '$grey300', $_text: { color: '$red' } }}>
+  <ButtonText>Button</ButtonText>
+</Button>
+
+// or
+
+const StyledButton = styled(Button, {
+  backgroundColor: '$grey300',
+  _text: { color: '$red' },
+});
 ```