docs: Add UNSAFE documentation to mobile Button and Text (#2392)

* start to update Button Docs regarding UNSAFE in mobile component * update Button Implement tab with UNSAFE info * remove UNSAFE example from mobile Button story * add Text Implement tab with UNSAFE docs * update prop description to no longer link to storybook * update prop description to no longer link to storybook in Button, Text, Popover * show inline styles example * reference correct component Co-authored-by: Nazarii L <[email protected]> * re add links to prop description * update prop description * update Popover UNSAFE prop description * update UNSAFE_classname in popover --------- Co-authored-by: Nazarii L <[email protected]>
GetJobber · Feb 24, 2025 · a53fc34 · a53fc34
1 parent 7b5a8c9
commit a53fc34
Show file tree

Hide file tree

Showing 11 changed files with 127 additions and 23 deletions.
diff --git a/docs/components/Text/Text.stories.mdx b/docs/components/Text/Text.stories.mdx
@@ -199,17 +199,3 @@ provided.
 <Canvas>
   <Text size="small">What is this, a font for 🐜s?</Text>
 </Canvas>
-
-## Platform Considerations (Mobile)
-
-### Notes
-
-Text uses the core component [Text](https://reactnative.dev/docs/text) from
-`react-native`.
-
-### Copying text
-
-There are a few caveats around copying text on Android and iOS that you can read
-under the
-[Typography](../?path=/docs/components-text-and-typography-typography--docs#platform-considerations)
-documentation.
diff --git a/packages/components-native/src/Button/Button.tsx b/packages/components-native/src/Button/Button.tsx
@@ -81,7 +81,7 @@ interface CommonButtonProps {
   /**
    * **Use at your own risk:** Custom style for specific elements. This should only be used as a
    * **last resort**. Using this may result in unexpected side effects.
-   * More information [here](https://atlantis.getjobber.com/storybook/?path=/docs/guides-customizing-components--docs#unsafe_-props).
+   * More information in the [Customizing components Guide](https://atlantis.getjobber.com/guides/customizing-components).
    */
   readonly UNSAFE_style?: ButtonUnsafeStyle;
 }

diff --git a/packages/components-native/src/Text/Text.tsx b/packages/components-native/src/Text/Text.tsx
@@ -90,7 +90,7 @@ export interface TextProps
   /**
    * **Use at your own risk:** Custom style for specific elements. This should only be used as a
    * **last resort**. Using this may result in unexpected side effects.
-   * More information [here](https://atlantis.getjobber.com/storybook/?path=/docs/guides-customizing-components--docs#unsafe_-props).
+   * More information in the [Customizing components Guide](https://atlantis.getjobber.com/guides/customizing-components).
    */
   readonly UNSAFE_style?: TypographyUnsafeStyle;
 }

diff --git a/packages/components/src/Popover/Popover.tsx b/packages/components/src/Popover/Popover.tsx
@@ -37,7 +37,7 @@ export interface PopoverProps {
   /**
    * **Use at your own risk:** Custom class names for specific elements. This should only be used as a
    * **last resort**. Using this may result in unexpected side effects.
-   * More information [here](https://atlantis.getjobber.com/storybook/?path=/docs/guides-customizing-components--docs#unsafe_-props).
+   * More information in the [Customizing components Guide](https://atlantis.getjobber.com/guides/customizing-components).
    */
   readonly UNSAFE_className?: {
     container?: string;
@@ -48,7 +48,7 @@ export interface PopoverProps {
   /**
    * **Use at your own risk:** Custom style for specific elements. This should only be used as a
    * **last resort**. Using this may result in unexpected side effects.
-   * More information [here](https://atlantis.getjobber.com/storybook/?path=/docs/guides-customizing-components--docs#unsafe_-props).
+   * More information in the [Customizing components Guide](https://atlantis.getjobber.com/guides/customizing-components).
    */
   readonly UNSAFE_style?: {
     container?: CSSProperties;

diff --git a/packages/site/src/content/Button/Button.props-mobile.json b/packages/site/src/content/Button/Button.props-mobile.json
diff --git a/packages/site/src/content/Button/ButtonNotes.mdx b/packages/site/src/content/Button/ButtonNotes.mdx
@@ -17,3 +17,65 @@ allowed. See
 
 Since this type of `Button` will only be used to submit a form, it does not make
 sense to allow the `external`, `onClick`, `to`, or `url` props.
+
+## Component customization
+
+### UNSAFE\_ props (advanced usage)
+
+General information for using `UNSAFE_` props can be found
+[here](/guides/customizing-components).
+
+**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
+considered a **last resort**. Future Button updates may lead to unintended
+breakages.
+
+#### UNSAFE_style (mobile)
+
+The mobile Button component has four elements that can be targeted with styles.
+These are the container, content container, icon container, and action label
+container.
+
+React Native does not support className. Instead, you can use `UNSAFE_style` to
+apply styles either inline or through a StyleSheet.
+
+##### Inline styles
+
+```tsx
+UNSAFE_style: {
+    container: { backgroundColor: tokens["color-purple--light"] },
+    contentContainer: {
+      backgroundColor: tokens["color-purple--lighter"],
+      borderRadius: tokens["radius-large"],
+    },
+    iconContainer: { backgroundColor: tokens["color-purple"] },
+    actionLabelContainer: { paddingLeft: tokens["space-larger"] },
+  },
+```
+
+##### StyleSheet
+
+```tsx
+// Button.tsx
+  UNSAFE_style={{
+    container: styles.customContainer,
+    contentContainer: styles.customContentContainer,
+    iconContainer: styles.customIconContainer,
+    actionLabelContainer: styles.customActionLabelContainer,
+  }}
+
+// Button.style.ts
+export const styles = StyleSheet.create({
+  customContainer: {
+    backgroundColor: tokens["color-purple--light"],
+  },
+  customContentContainer: {
+    borderRadius: tokens["radius-large"],
+  },
+  customIconContainer: {
+    backgroundColor: tokens["color-purple--lighter"],
+  },
+  customActionLabelContainer: {
+    paddingLeft: tokens["space-larger"],
+  },
+});
+```
diff --git a/packages/site/src/content/Popover/Popover.props.json b/packages/site/src/content/Popover/Popover.props.json
diff --git a/packages/site/src/content/Popover/PopoverNotes.mdx b/packages/site/src/content/Popover/PopoverNotes.mdx
@@ -3,7 +3,7 @@
 ### UNSAFE\_ props (advanced usage)
 
 General information for using `UNSAFE_` props can be found
-[here](https://atlantis.getjobber.com/storybook/?path=/docs/guides-customizing-components--docs#unsafe_-props).
+[here](/guides/customizing-components).
 
 Popover has three elements that can be targeted with classes or styles. These
 are the container, the dismiss button container, and the arrow.

diff --git a/packages/site/src/content/Text/Text.props-mobile.json b/packages/site/src/content/Text/Text.props-mobile.json
diff --git a/packages/site/src/content/Text/TextNotes.mdx b/packages/site/src/content/Text/TextNotes.mdx
@@ -0,0 +1,54 @@
+## Component customization
+
+### UNSAFE\_ props (advanced usage)
+
+General information for using `UNSAFE_` props can be found
+[here](/guides/customizing-components).
+
+**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
+considered a **last resort**. Future Text updates may lead to unintended
+breakages.
+
+#### UNSAFE_style (mobile)
+
+The mobile Text component can be custom styled using the `textStyle` type via
+the `UNSAFE_style` prop.
+
+React Native does not support className. Instead, you can use `UNSAFE_style` to
+apply styles either inline or through a StyleSheet.
+
+##### Inline styles
+
+```tsx
+UNSAFE_style={{ textStyle: { color: tokens["color-purple--light"] } }}
+```
+
+##### StyleSheet
+
+```tsx
+// Text.tsx
+  UNSAFE_style={{
+    textStyle: styles.customTextStyle,
+  }}
+
+// Text.style.ts
+export const styles = StyleSheet.create({
+  customTextStyle: {
+    color: tokens["color-purple--light"],
+  },
+});
+```
+
+## Platform Considerations (Mobile)
+
+### Notes
+
+Text uses the core component [Text](https://reactnative.dev/docs/text) from
+`react-native`.
+
+### Copying text
+
+There are a few caveats around copying text on Android and iOS that you can read
+under the
+[Typography](../?path=/docs/components-text-and-typography-typography--docs#platform-considerations)
+documentation.
diff --git a/packages/site/src/content/Text/index.tsx b/packages/site/src/content/Text/index.tsx
@@ -1,6 +1,7 @@
 import Content from "@atlantis/docs/components/Text/Text.stories.mdx";
 import Props from "./Text.props.json";
 import MobileProps from "./Text.props-mobile.json";
+import Notes from "./TextNotes.mdx";
 import { ContentExport } from "../../types/content";
 import { getStorybookUrl } from "../../layout/getStorybookUrl";
 
@@ -21,4 +22,5 @@ export default {
       ),
     },
   ],
+  notes: () => <Notes />,
 } as const satisfies ContentExport;