diff --git a/packages/design-system-react-native/src/components/AvatarAccount/README.md b/packages/design-system-react-native/src/components/AvatarAccount/README.md index 95cf2e707..6a52c5915 100644 --- a/packages/design-system-react-native/src/components/AvatarAccount/README.md +++ b/packages/design-system-react-native/src/components/AvatarAccount/README.md @@ -1,160 +1,174 @@ # AvatarAccount -The `AvatarAccount` component is reserved for representing accounts inside of an avatar. +Avatar reserved for representing accounts inside of an avatar. -_Developer Note: It extends the functionality of [`AvatarBase`](../AvatarBase/) by incorporating an Account and severity levels, making it useful for visually representing statuses, alerts, or simply user avatars with Accounts._ +```tsx +import { AvatarAccount } from '@metamask/design-system-react-native'; ---- +; +``` ## Props +### `address` + +Required address used as a unique identifier to generate the AvatarAccount art. + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | Yes | `undefined` | + +```tsx + +``` + ### `variant` Optional prop to control the variant of the avatar account. +Available variants: + +- `AvatarAccountVariant.Jazzicon` (default) +- `AvatarAccountVariant.Blockies` +- `AvatarAccountVariant.Maskicon` + | TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------------------------------ | +| ---------------------- | -------- | ------------------------------- | | `AvatarAccountVariant` | No | `AvatarAccountVariant.Jazzicon` | -Available severities: +```tsx + +``` -- `Jazzicon` -- `Blockies` -- `Maskicon` +### `size` ---- +The size of the AvatarAccount. -### `address` (Required) +Available sizes: -Required address used as a unique identifier to generate the AvatarAccount art. +- `AvatarBaseSize.Xs` (16px) +- `AvatarBaseSize.Sm` (24px) +- `AvatarBaseSize.Md` (32px) +- `AvatarBaseSize.Lg` (40px) +- `AvatarBaseSize.Xl` (48px) -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | Yes | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `AvatarBaseSize` | No | `AvatarBaseSize.Md` | ---- +```tsx + +``` ### `blockiesProps` -Optional props to be passed to the `Blockies` component when the variant is `Blockies`. +Optional props to be passed to the Blockies component when the variant is Blockies. | TYPE | REQUIRED | DEFAULT | | ------------------------ | -------- | ----------- | | `Partial` | No | `undefined` | -Used to customize the `Blockies` identicon, such as block size or color settings. - ---- +```tsx + +``` ### `jazziconProps` -Optional props to be passed to the `Jazzicon` component when the variant is `Jazzicon`. +Optional props to be passed to the Jazzicon component when the variant is Jazzicon. | TYPE | REQUIRED | DEFAULT | | ------------------------ | -------- | ----------- | | `Partial` | No | `undefined` | -Used to customize the `Jazzicon` identicon, such as diameter or address seed. - ---- +```tsx + +``` ### `maskiconProps` -Optional props to be passed to the `Maskicon` component itself. +Optional props to be passed to the Maskicon component when the variant is Maskicon. | TYPE | REQUIRED | DEFAULT | | ------------------------ | -------- | ----------- | | `Partial` | No | `undefined` | -Useful for forwarding additional `SvgProps`, accessibility attributes, or animation styles. - ---- - -### Other Props - -`AvatarAccount` supports all props from [`AvatarBase`](#) except `children`, `fallbackText`, and `fallbackTextProps`. This includes: - -- `size` – Controls the avatar size. See [AvatarBase documentation](#) for details. -- `shape` – Controls the avatar shape. See [AvatarBase documentation](#) for details. -- `twClassName` – Additional Tailwind class names. -- `style` – Override or extend style properties. - ---- - -## Accessibility - -Since `AvatarAccount` typically represents an account-based avatar. it is important to ensure the component is usable by screen readers and assistive technologies. The following `react-native` accessibility props can be passed: - -- **`accessibilityLabel`**: Use to describe the AvatarAccount. -- **`accessibilityRole`**: - - If interactive (e.g., navigates to account details), set to `button` or another appropriate role. -- **`accessibilityHint`**: Provide context if `AvatarAccount` triggers a navigation or action. -- **`accessible`**: Set to `true` when the avatar is meaningful, so screen readers properly identify it. If the Account is strictly decorative or not essential, it can be set to `false`. - ---- - -## Usage - -### Basic Usage - -```tsx -import React from 'react'; -import AvatarAccount, { - AvatarAccountSeverity, -} from '@metamask/design-system-react-native'; - -; -``` - ---- - -### Setting Variant - ```tsx - - ``` ---- +### `twClassName` + +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -### Changing Size +- Add new styles that don't exist in the default component +- Override the component's default styles when needed + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import { AvatarSize } from '@metamask/design-system-react-native'; +import { AvatarAccount } from '@metamask/design-system-react-native'; +// Add additional styles ; -``` - -See the [AvatarBase README](#) for more details on `size` and `shape`. + twClassName="border-2 border-primary-100" +> + Custom Border + ---- - -## Notes +// Override default styles + + Override Background + +``` -- `AvatarAccount` relies on [`AvatarBase`](#) for its foundational behavior. -- The `variant` prop changes the AvatarAccount art style. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs), the [AvatarBase documentation](#), or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/AvatarBase/README.md b/packages/design-system-react-native/src/components/AvatarBase/README.md index 98bcce846..3f4cc75f9 100644 --- a/packages/design-system-react-native/src/components/AvatarBase/README.md +++ b/packages/design-system-react-native/src/components/AvatarBase/README.md @@ -1,28 +1,18 @@ # AvatarBase -The `AvatarBase` is the base component for avatars. +AvatarBase is the base component for avatars. ---- - -## Props - -### `children` - -Optional prop for the content to be rendered within the `AvatarBase`. +```tsx +import { AvatarBase } from '@metamask/design-system-react-native'; -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `ReactNode` | No | `null` | +AB; +``` ---- +## Props ### `size` -Optional prop to control the size of the `AvatarBase`. - -| TYPE | REQUIRED | DEFAULT | -| :--------------- | :------- | :------------------ | -| `AvatarBaseSize` | No | `AvatarBaseSize.Md` | +The size of the AvatarBase. Available sizes: @@ -32,7 +22,15 @@ Available sizes: - `AvatarBaseSize.Lg` (40px) - `AvatarBaseSize.Xl` (48px) ---- +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `AvatarBaseSize` | No | `AvatarBaseSize.Md` | + +```tsx +Small Avatar +Medium Avatar (default) +Large Avatar +``` ### `shape` @@ -47,7 +45,24 @@ Available shapes: - `AvatarBaseShape.Circle` - `AvatarBaseShape.Square` ---- +```tsx +AB +CD +``` + +### `children` + +The content of the AvatarBase component. + +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------- | +| `ReactNode` | No | `undefined` | + +```tsx +import { AvatarBase } from '@metamask/design-system-react-native'; + +Custom avatar content; +``` ### `fallbackText` @@ -57,7 +72,11 @@ Optional text to be displayed when the avatar content fails to render. | :------- | :------- | :------ | | `string` | No | `null` | ---- +```tsx + + {/* Content that might fail to render */} + +``` ### `fallbackTextProps` @@ -67,97 +86,92 @@ Optional props to customize the fallback text. | :---------------------------- | :------- | :------ | | `Omit` | No | `{}` | ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - ---- - -### `style` - -Optional prop to control the style. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -## Usage - -### Basic Usage - ```tsx -import React from 'react'; -import AvatarBase from '@metamask/design-system-react-native'; - -👤; + + {/* Content that might fail to render */} + ``` ---- +### `backgroundColor` -### Avatar with Fallback Text +Background color of the avatar. -```tsx - -``` - ---- - -### Customizing the Fallback Text +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | --------------------------------------- | +| `BackgroundColor` | No | `BackgroundColor.BackgroundAlternative` | ```tsx - + + Avatar with custom background + ``` ---- +### `borderColor` + +Border color of the avatar. -### Changing Avatar Size +| TYPE | REQUIRED | DEFAULT | +| ------------- | -------- | --------------------------- | +| `BorderColor` | No | `BorderColor.BorderDefault` | ```tsx -👤 + + Avatar with custom border + ``` ---- +### `twClassName` -### Changing Avatar Shape +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -```tsx -👤 -``` - ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Accessibility +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -- Ensure `fallbackText` provides meaningful information when the avatar content is unavailable. -- Use `fallbackTextProps` to style text for better visibility and contrast. +```tsx +import { AvatarBase } from '@metamask/design-system-react-native'; ---- +// Add additional styles + + Custom Border + -### Notes +// Override default styles + + Override Background + +``` -- `AvatarBase` is optimized for handling different avatar states. -- The fallback text ensures a meaningful representation when no image or content is available. -- Custom styling can be applied using `twClassName` and `style` props. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + Custom styled avatar +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/AvatarFavicon/README.md b/packages/design-system-react-native/src/components/AvatarFavicon/README.md index 9d0c7bbda..a0d83b855 100644 --- a/packages/design-system-react-native/src/components/AvatarFavicon/README.md +++ b/packages/design-system-react-native/src/components/AvatarFavicon/README.md @@ -1,161 +1,157 @@ # AvatarFavicon -`AvatarFavicon` is a type of avatar reserved for representing dapps, sites, and other general entities. +Avatar reserved for representing websites and dapps. ---- +```tsx +import { AvatarFavicon } from '@metamask/design-system-react-native'; + +; +``` ## Props ### `src` -Optional prop specifying the source of the favicon image or SVG. +Optional prop for the source of the image or SVG. -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| --------------- | -------- | ------- | ----------------------------------------- | -| `ImageOrSvgSrc` | No | `null` | URI, local asset, or inline SVG component | +| TYPE | REQUIRED | DEFAULT | +| --------------- | -------- | ----------- | +| `ImageOrSvgSrc` | No | `undefined` | ---- +```tsx +// Remote image + -### `name` +// Local image + -Optional string used to derive the fallback text (first character). +// Local SVG component +import FaviconSVG from './favicon.svg'; + +``` -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| -------- | -------- | ------- | -------------------------------------- | -| `string` | No | `null` | Used to create fallback if image fails | +### `name` ---- +Optional prop for favicon name, used to calculate fallback text when image fails to load. -### `imageOrSvgProps` +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -Optional props forwarded to the `ImageOrSvg` component. +```tsx + +``` -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| ----------------- | -------- | ------- | -------------------------------------------------- | -| `ImageOrSvgProps` | No | `null` | Customize image handling, test IDs, alt text, etc. | +### `size` ---- +The size of the AvatarFavicon. -### `size` +Available sizes: -Controls the size of the avatar. Inherits from `AvatarBaseSize`. +- `AvatarFaviconSize.Xs` (16px) +- `AvatarFaviconSize.Sm` (24px) +- `AvatarFaviconSize.Md` (32px) +- `AvatarFaviconSize.Lg` (40px) +- `AvatarFaviconSize.Xl` (48px) | TYPE | REQUIRED | DEFAULT | | ------------------- | -------- | ---------------------- | | `AvatarFaviconSize` | No | `AvatarFaviconSize.Md` | -Available sizes: - -- `Xs` – 16px -- `Sm` – 24px -- `Md` – 32px -- `Lg` – 40px -- `Xl` – 48px - ---- +```tsx + +``` ### `fallbackText` -Optional custom fallback text shown when image fails to load. - -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| -------- | -------- | ----------------------------------------- | --------------------- | -| `string` | No | First character of `name` or empty string | Used when image fails | - ---- - -### `fallbackTextProps` - -Optional props to customize the fallback text appearance. +Optional text to display when the image fails to load. -| TYPE | REQUIRED | DEFAULT | -| -------------------- | -------- | ------- | -| `Partial` | No | `{}` | - ---- - -### `twClassName` - -Optional Tailwind-style utility classes. - -| TYPE | REQUIRED | DEFAULT | -| -------- | -------- | ------- | -| `string` | No | `''` | - ---- - -### Additional Props - -All other props supported by `AvatarBase`, excluding `children`, are also accepted (e.g., `style`, `testID`). - ---- - -## Usage - -### Basic +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx ``` -### Custom Size and Fallback +### `imageOrSvgProps` -```tsx - -``` +Optional props to pass to the underlying ImageOrSvg component. -### Forwarding props to ImageOrSvg +| TYPE | REQUIRED | DEFAULT | +| -------------------------- | -------- | ----------- | +| `Partial` | No | `undefined` | ```tsx console.log('Image loaded'), + onImageError: () => console.log('Image failed to load'), }} /> ``` ---- - -## Behavior +### `twClassName` -- Falls back to the first character of `name` if image fails to load. -- Defaults to `Md` (32px) size. -- Always uses a circular shape. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -## Accessibility +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -- Use `imageOrSvgProps.imageProps.accessibilityLabel` to describe the favicon for screen readers. -- The fallback text is rendered using the `Text` component and can be customized via `fallbackTextProps`. +```tsx +import { AvatarFavicon } from '@metamask/design-system-react-native'; ---- +// Add additional styles + -## Notes +// Override default styles + +``` -- This component uses `AvatarBase` and `ImageOrSvg` under the hood. -- SVGs and raster images are both supported. -- For custom shapes or behaviors, extend `AvatarBase` directly. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs), the [AvatarFavicon documentation](#), or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/AvatarGroup/README.md b/packages/design-system-react-native/src/components/AvatarGroup/README.md index 10c9276dd..ca296c67c 100644 --- a/packages/design-system-react-native/src/components/AvatarGroup/README.md +++ b/packages/design-system-react-native/src/components/AvatarGroup/README.md @@ -1,67 +1,137 @@ # AvatarGroup -`AvatarGroup` is a stacked avatars to represent a group of avatars. +AvatarGroup is a stacked avatars component to represent a group of avatars. ---- +```tsx +import { + AvatarGroup, + AvatarGroupVariant, +} from '@metamask/design-system-react-native'; + +; +``` ## Props -### `variant` (Required) +### `variant` -Determines the type of avatars used within the group. +The type of avatars to display in the group. -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :------ | -| `AvatarGroupVariant` | Yes | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| -------------------- | -------- | ----------- | +| `AvatarGroupVariant` | Yes | `undefined` | Available variants: -- `Account` -- `Favicon` -- `Network` -- `Token` +- `AvatarGroupVariant.Account` +- `AvatarGroupVariant.Favicon` +- `AvatarGroupVariant.Network` +- `AvatarGroupVariant.Token` + +```tsx + +``` + +### `avatarPropsArr` ---- +Array of props for the individual avatar components. The type depends on the variant. -### `avatarPropsArr` (Required) +| TYPE | REQUIRED | DEFAULT | +| -------------------------------------------------------------------------------------------------- | -------- | ----------- | +| `AvatarAccountProps[]` \| `AvatarFaviconProps[]` \| `AvatarNetworkProps[]` \| `AvatarTokenProps[]` | Yes | `undefined` | -An array of props for each avatar within the group. +```tsx +// Account variant + -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :------ | -| `Array` | Yes | `N/A` | +// Favicon variant + -Each avatar follows the prop structure of the corresponding variant component (`AvatarAccount`, `AvatarFavicon`, `AvatarNetwork`, `AvatarToken`). +// Network variant + ---- +// Token variant + +``` ### `size` -Optional prop to control the size of the avatars in the group. +The size of the avatars in the group. -| TYPE | REQUIRED | DEFAULT | -| :----------- | :------- | :-------------- | -| `AvatarSize` | No | `AvatarSize.Md` | +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | -------------------- | +| `AvatarGroupSize` | No | `AvatarGroupSize.Md` | Available sizes: -- `AvatarSize.Xs` -- `AvatarSize.Sm` -- `AvatarSize.Md` -- `AvatarSize.Lg` -- `AvatarSize.Xl` +- `AvatarGroupSize.Xs` (16px) +- `AvatarGroupSize.Sm` (24px) +- `AvatarGroupSize.Md` (32px) +- `AvatarGroupSize.Lg` (40px) +- `AvatarGroupSize.Xl` (48px) ---- +```tsx + +``` ### `max` -Determines the maximum number of avatars to display before showing an overflow indicator. +Maximum number of avatars to display before showing overflow indicator. | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | +| -------- | -------- | ------- | | `number` | No | `4` | ---- +```tsx + +``` ### `isReverse` @@ -71,192 +141,92 @@ Optional prop to reverse the order of avatar stacking. | :-------- | :------- | :------ | | `boolean` | No | `false` | ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - ---- - -### `style` - -Optional prop to control the style of the avatar group container. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -## Usage - -Below are examples illustrating how to structure the `avatarPropsArr` based on each avatar variant. Note that the data shown is purely illustrative. - -### Account Avatars - ```tsx -import React from 'react'; -import AvatarGroup, { - AvatarGroupVariant, -} from '@metamask/design-system-react-native'; -import { AvatarAccountVariant } from '@metamask/design-system-react-native'; - ; + isReverse + avatarPropsArr={[{ address: '0x1234...' }, { address: '0x5678...' }]} +/> ``` ---- +### `overflowTextProps` -### Favicon Avatars +Additional AvatarBase props to pass to the overflow text element. -```tsx -import React from 'react'; -import AvatarGroup, { - AvatarGroupVariant, -} from '@metamask/design-system-react-native'; +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | ----------- | +| `AvatarBaseProps` | No | `undefined` | +```tsx ; +/> ``` ---- - -### Network Avatars - -```tsx -import React from 'react'; -import AvatarGroup, { - AvatarGroupVariant, -} from '@metamask/design-system-react-native'; +### `twClassName` -; -``` +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Token Avatars +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import React from 'react'; -import AvatarGroup, { - AvatarGroupVariant, -} from '@metamask/design-system-react-native'; +import { AvatarGroup } from '@metamask/design-system-react-native'; +// Add additional styles ; -``` - ---- - -### Displaying More Avatars with Overflow + variant={AvatarGroupVariant.Account} + avatarPropsArr={[{ address: '0x1234...' }]} + twClassName="bg-primary-100" +/> -```tsx +// Override default styles ``` -If more than `max` avatars are provided, an overflow counter (e.g., `+1`) will be displayed. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -### Changing Avatar Size +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ```tsx -import AvatarGroup, { - AvatarGroupVariant, - AvatarGroupSize, -} from '@metamask/design-system-react-native'; -; +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); ``` ---- - -## Notes - -- `AvatarGroup` ensures consistent avatar alignment and spacing. -- Overflow avatars are indicated with a counter. -- It supports different avatar types based on the selected variant. - ---- - -## Contributing - -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. - ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/AvatarIcon/README.md b/packages/design-system-react-native/src/components/AvatarIcon/README.md index f3e8915de..9304861db 100644 --- a/packages/design-system-react-native/src/components/AvatarIcon/README.md +++ b/packages/design-system-react-native/src/components/AvatarIcon/README.md @@ -1,13 +1,31 @@ # AvatarIcon -The `AvatarIcon` component is reserved for representing static icons inside of an avatar. +Avatar reserved for representing static icons inside of an avatar. -_Developer Note: This components extends the functionality of [`AvatarBase`](../AvatarBase/) by incorporating an icon and severity levels, making it useful for visually representing statuses, alerts, or simply user avatars with icons._ +```tsx +import { + AvatarIcon, + AvatarIconSeverity, + IconName, +} from '@metamask/design-system-react-native'; ---- +; +``` ## Props +### `name` + +The icon name to display in the avatar. + +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | Yes | `undefined` | + +```tsx + +``` + ### `severity` Optional prop to control the severity of the avatar. @@ -18,114 +36,115 @@ Optional prop to control the severity of the avatar. Available severities: -- `Neutral` -- `Info` -- `Success` -- `Error` -- `Warning` - ---- - -### `iconName` (Required) - -The name of the icon to be displayed. - -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | Yes | `N/A` | - ---- - -### `iconProps` - -Optional props to pass additional properties to the icon. - -| TYPE | REQUIRED | DEFAULT | -| :------------------------ | :------- | :------ | -| `Omit` | No | `{}` | +- `AvatarIconSeverity.Neutral` +- `AvatarIconSeverity.Info` +- `AvatarIconSeverity.Success` +- `AvatarIconSeverity.Error` +- `AvatarIconSeverity.Warning` ---- - -### Other Props +```tsx + + + +``` -`AvatarIcon` supports all props from [`AvatarBase`](#) except `children`, `fallbackText`, and `fallbackTextProps`. This includes: +### `size` -- `size` – Controls the avatar size. See [AvatarBase documentation](#) for details. -- `shape` – Controls the avatar shape. See [AvatarBase documentation](#) for details. -- `twClassName` – Additional Tailwind class names. -- `style` – Override or extend style properties. +The size of the AvatarIcon. ---- +Available sizes: -## Accessibility +- `AvatarBaseSize.Xs` (16px) +- `AvatarBaseSize.Sm` (24px) +- `AvatarBaseSize.Md` (32px) +- `AvatarBaseSize.Lg` (40px) +- `AvatarBaseSize.Xl` (48px) -Since `AvatarIcon` typically represents an icon-based avatar, it is important to ensure the component is usable by screen readers and assistive technologies. The following `react-native` accessibility props can be passed: +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `AvatarBaseSize` | No | `AvatarBaseSize.Md` | -- **`accessibilityLabel`**: Use to describe the AvatarIcon. For example, "Sent" -- **`accessibilityRole`**: - - If interactive (e.g., navigates to account details), set to `button` or another appropriate role. -- **`accessibilityHint`**: Provide context if `AvatarIcon` triggers a navigation or action. -- **`accessible`**: Set to `true` when the avatar is meaningful, so screen readers properly identify it. If the icon is strictly decorative or not essential, it can be set to `false`. +```tsx + + + +``` ---- +### `iconColor` -## Usage +Color of the icon within the avatar. -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------------------- | +| `IconColor` | No | `IconColor.IconDefault` | ```tsx -import React from 'react'; -import AvatarIcon, { - AvatarIconSeverity, -} from '@metamask/design-system-react-native'; - -; + ``` ---- +### `backgroundColor` + +Background color of the avatar. -### Setting Severity +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | --------------------------------------- | +| `BackgroundColor` | No | `BackgroundColor.BackgroundAlternative` | ```tsx - + ``` ---- +### `twClassName` -### Customizing Icon Props +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -```tsx - -``` - ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Changing Size and Shape +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import { AvatarSize, AvatarShape } from '@metamask/design-system-react-native'; - -; +import { AvatarIcon } from '@metamask/design-system-react-native'; + +// Add additional styles + + +// Override default styles + ``` -See the [AvatarBase README](#) for more details on `size` and `shape`. - ---- +### `style` -## Notes +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -- `AvatarIcon` relies on [`AvatarBase`](#) for its foundational behavior. -- The `severity` prop changes the icon color, making it easy to signal statuses. -- You can override icon appearance via `iconProps`. +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ---- - -## Contributing - -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs), the [AvatarBase documentation](#), or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/AvatarNetwork/README.md b/packages/design-system-react-native/src/components/AvatarNetwork/README.md index 52d839647..938f64b33 100644 --- a/packages/design-system-react-native/src/components/AvatarNetwork/README.md +++ b/packages/design-system-react-native/src/components/AvatarNetwork/README.md @@ -1,161 +1,128 @@ # AvatarNetwork -`AvatarNetwork` is reserved for representing networks. +Avatar reserved for representing networks. ---- - -## Props - -### `src` - -Optional prop specifying the source of the network image or SVG. +```tsx +import { AvatarNetwork } from '@metamask/design-system-react-native'; -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| --------------- | -------- | ------- | ----------------------------------------- | -| `ImageOrSvgSrc` | No | `null` | URI, local asset, or inline SVG component | +; +``` ---- +## Props ### `name` -Optional string used to derive the fallback text (first character). - -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| -------- | -------- | ------- | -------------------------------------- | -| `string` | No | `null` | Used to create fallback if image fails | - ---- - -### `imageOrSvgProps` - -Optional props forwarded to the `ImageOrSvg` component. +The network name for the avatar. -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| ----------------- | -------- | ------- | -------------------------------------------------- | -| `ImageOrSvgProps` | No | `null` | Customize image handling, test IDs, alt text, etc. | +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ---- +```tsx + +``` ### `size` -Controls the size of the avatar. Inherits from `AvatarBaseSize`. - -| TYPE | REQUIRED | DEFAULT | -| ------------------- | -------- | ---------------------- | -| `AvatarNetworkSize` | No | `AvatarNetworkSize.Md` | +The size of the AvatarNetwork. Available sizes: -- `Xs` – 16px -- `Sm` – 24px -- `Md` – 32px -- `Lg` – 40px -- `Xl` – 48px - ---- - -### `fallbackText` - -Optional custom fallback text shown when image fails to load. - -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| -------- | -------- | ----------------------------------------- | --------------------- | -| `string` | No | First character of `name` or empty string | Used when image fails | - ---- - -### `fallbackTextProps` - -Optional props to customize the fallback text appearance. - -| TYPE | REQUIRED | DEFAULT | -| -------------------- | -------- | ------- | -| `Partial` | No | `{}` | +- `AvatarBaseSize.Xs` (16px) +- `AvatarBaseSize.Sm` (24px) +- `AvatarBaseSize.Md` (32px) +- `AvatarBaseSize.Lg` (40px) +- `AvatarBaseSize.Xl` (48px) ---- +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `AvatarBaseSize` | No | `AvatarBaseSize.Md` | -### `twClassName` - -Optional Tailwind-style utility classes. - -| TYPE | REQUIRED | DEFAULT | -| -------- | -------- | ------- | -| `string` | No | `''` | - ---- - -### Additional Props - -All other props supported by `AvatarBase`, excluding `children`, are also accepted (e.g., `style`, `testID`). +```tsx + + + +``` ---- +### `src` -## Usage +Custom image source for the network avatar. -### Basic +| TYPE | REQUIRED | DEFAULT | +| --------------- | -------- | ----------- | +| `ImageOrSvgSrc` | No | `undefined` | ```tsx ``` -### Custom Size and Fallback +### `fallbackText` -```tsx - -``` +Text to display when the network image fails to load. -### Forwarding props to ImageOrSvg +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx - + ``` ---- - -## Behavior +### `twClassName` -- Falls back to the first character of `name` if image fails to load. -- Defaults to `Md` (32px) size. -- Always uses a circular shape. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -## Accessibility +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -- Use `imageOrSvgProps.imageProps.accessibilityLabel` to describe the Network for screen readers. -- The fallback text is rendered using the `Text` component and can be customized via `fallbackTextProps`. +```tsx +import { AvatarNetwork } from '@metamask/design-system-react-native'; ---- +// Add additional styles + + Custom Border + -## Notes +// Override default styles + + Override Background + +``` -- This component uses `AvatarBase` and `ImageOrSvg` under the hood. -- SVGs and raster images are both supported. -- For custom shapes or behaviors, extend `AvatarBase` directly. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs), the [AvatarFavicon documentation](#), or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/AvatarToken/README.md b/packages/design-system-react-native/src/components/AvatarToken/README.md index 78c0dc4fc..e16ea9ad0 100644 --- a/packages/design-system-react-native/src/components/AvatarToken/README.md +++ b/packages/design-system-react-native/src/components/AvatarToken/README.md @@ -1,158 +1,128 @@ # AvatarToken -`AvatarToken` is reserved for representing tokens. +Avatar reserved for representing tokens. ---- - -## Props - -### `src` - -Optional prop specifying the source of the token image or SVG. +```tsx +import { AvatarToken } from '@metamask/design-system-react-native'; -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| --------------- | -------- | ------- | ----------------------------------------- | -| `ImageOrSvgSrc` | No | `null` | URI, local asset, or inline SVG component | +; +``` ---- +## Props ### `name` -Optional string used to derive the fallback text (first character). - -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| -------- | -------- | ------- | -------------------------------------- | -| `string` | No | `null` | Used to create fallback if image fails | - ---- +The token name for the avatar. -### `imageOrSvgProps` +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | Yes | `undefined` | -Optional props forwarded to the `ImageOrSvg` component. - -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| ----------------- | -------- | ------- | -------------------------------------------------- | -| `ImageOrSvgProps` | No | `null` | Customize image handling, test IDs, alt text, etc. | - ---- +```tsx + +``` ### `size` -Controls the size of the avatar. Inherits from `AvatarBaseSize`. - -| TYPE | REQUIRED | DEFAULT | -| ----------------- | -------- | -------------------- | -| `AvatarTokenSize` | No | `AvatarTokenSize.Md` | +The size of the AvatarToken. Available sizes: -- `Xs` – 16px -- `Sm` – 24px -- `Md` – 32px -- `Lg` – 40px -- `Xl` – 48px - ---- - -### `fallbackText` - -Optional custom fallback text shown when image fails to load. - -| TYPE | REQUIRED | DEFAULT | DESCRIPTION | -| -------- | -------- | ----------------------------------------- | --------------------- | -| `string` | No | First character of `name` or empty string | Used when image fails | - ---- - -### `fallbackTextProps` - -Optional props to customize the fallback text appearance. - -| TYPE | REQUIRED | DEFAULT | -| -------------------- | -------- | ------- | -| `Partial` | No | `{}` | - ---- +- `AvatarBaseSize.Xs` (16px) +- `AvatarBaseSize.Sm` (24px) +- `AvatarBaseSize.Md` (32px) +- `AvatarBaseSize.Lg` (40px) +- `AvatarBaseSize.Xl` (48px) -### `twClassName` - -Optional Tailwind-style utility classes. - -| TYPE | REQUIRED | DEFAULT | -| -------- | -------- | ------- | -| `string` | No | `''` | - ---- - -### Additional Props - -All other props supported by `AvatarBase`, excluding `children`, are also accepted (e.g., `style`, `testID`). - ---- - -## Usage - -### Basic +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `AvatarBaseSize` | No | `AvatarBaseSize.Md` | ```tsx - + + + ``` -### Custom Size and Fallback +### `src` + +Custom image source for the token avatar. + +| TYPE | REQUIRED | DEFAULT | +| --------------- | -------- | ----------- | +| `ImageOrSvgSrc` | No | `undefined` | ```tsx ``` -### Forwarding props to ImageOrSvg +### `fallbackText` + +Text to display when the token image fails to load. + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx - + ``` ---- - -## Behavior +### `twClassName` -- Falls back to the first character of `name` if image fails to load. -- Defaults to `Md` (32px) size. -- Always uses a circular shape. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -## Accessibility +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -- Use `imageOrSvgProps.imageProps.accessibilityLabel` to describe the Token for screen readers. -- The fallback text is rendered using the `Text` component and can be customized via `fallbackTextProps`. +```tsx +import { AvatarToken } from '@metamask/design-system-react-native'; ---- +// Add additional styles + + Custom Border + -## Notes +// Override default styles + + Override Background + +``` -- This component uses `AvatarBase` and `ImageOrSvg` under the hood. -- SVGs and raster images are both supported. -- For custom shapes or behaviors, extend `AvatarBase` directly. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs), the [AvatarFavicon documentation](#), or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/BadgeCount/README.md b/packages/design-system-react-native/src/components/BadgeCount/README.md index 310af7332..001fa7555 100644 --- a/packages/design-system-react-native/src/components/BadgeCount/README.md +++ b/packages/design-system-react-native/src/components/BadgeCount/README.md @@ -1,141 +1,104 @@ # BadgeCount -`BadgeCount` is a numeric indicator of unread messages or notifications on an app or UI element. +BadgeCount is a numeric indicator of unread messages or notifications on an app or UI element. ---- +```tsx +import { BadgeCount } from '@metamask/design-system-react-native'; -## Props +; +``` -### `count` (Required) +## Props -The number to be displayed in the badge. +### `count` -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `number` | Yes | `N/A` | +The count value to display in the badge. -If `count` exceeds `max`, it will display as `max+`. +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `number` | Yes | `undefined` | ---- +```tsx + +``` ### `max` -Optional prop to set the maximum count before displaying `max+`. +Maximum count to display before showing overflow indicator (e.g., "99+"). | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | +| -------- | -------- | ------- | | `number` | No | `99` | ---- +```tsx + +``` ### `size` -Optional prop to control the size of the badge. +The size of the BadgeCount. | TYPE | REQUIRED | DEFAULT | -| :--------------- | :------- | :------------------ | +| ---------------- | -------- | ------------------- | | `BadgeCountSize` | No | `BadgeCountSize.Md` | -Available sizes: - -- `Md` (14px height) -- `Lg` (20px height) - ---- - -### `textProps` - -Optional props to be passed to the `Text` component inside the badge. - -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :------ | -| `Partial` | No | `{}` | - ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - ---- - -### `style` - -Optional prop to control the style of the badge container. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -## Usage - -### Basic Usage - ```tsx -import React from 'react'; -import BadgeCount from '@metamask/design-system-react-native'; - -; + + ``` ---- - -### Setting a Maximum Count - -```tsx - -``` +### `twClassName` -This will display `99+` instead of `120`. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Changing Badge Size +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import { BadgeCountSize } from '@metamask/design-system-react-native'; - -; +import { BadgeCount } from '@metamask/design-system-react-native'; + +// Add additional styles + + Custom Background + + +// Override default styles + + Override Background + ``` ---- - -### Customizing Text Props - -```tsx - -``` +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -### Applying Tailwind Custom Styles +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ```tsx - +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); ``` ---- - -## Notes - -- `BadgeCount` is useful for indicating unread notifications, message counts, or status indicators. -- The text color and weight are customizable via `textProps`. -- The component ensures that excessively large numbers are represented concisely with `max+`. - ---- - -## Contributing - -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. - ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/BadgeIcon/README.md b/packages/design-system-react-native/src/components/BadgeIcon/README.md index 2204a2765..007c81b1f 100644 --- a/packages/design-system-react-native/src/components/BadgeIcon/README.md +++ b/packages/design-system-react-native/src/components/BadgeIcon/README.md @@ -1,103 +1,117 @@ # BadgeIcon -`BadgeIcon` is a circular indicator that contains an icon, used to provide quick context or visual tagging at a glance. +BadgeIcon is a circular indicator that contains an icon, used to provide quick context or visual tagging at a glance. ---- - -## Props - -### `iconName` (Required) +```tsx +import { BadgeIcon } from '@metamask/design-system-react-native'; -The name of the icon to be displayed. +; +``` -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | Yes | `N/A` | +## Props ---- +### `name` -### `iconProps` +The icon name to display in the badge. -Optional props to customize the appearance of the icon inside the badge. +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | Yes | `undefined` | -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :------------------------------------------------------- | -| `Partial` | No | `{ size: IconSize.Xs, color: IconColor.PrimaryInverse }` | +```tsx + +``` ---- +### `variant` -### `twClassName` +The visual variant of the badge. -Optional prop to add `twrnc` overriding class names. +Available variants: -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | +- `BadgeIconVariant.Success` +- `BadgeIconVariant.Error` +- `BadgeIconVariant.Warning` +- `BadgeIconVariant.Info` ---- +| TYPE | REQUIRED | DEFAULT | +| ------------------ | -------- | -------------------------- | +| `BadgeIconVariant` | No | `BadgeIconVariant.Success` | -### `style` +```tsx + + +``` -Optional prop to control the style of the badge container. +### `size` -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | +The size of the BadgeIcon. ---- +Available sizes: -## Usage +- `BadgeIconSize.Sm` (16px) +- `BadgeIconSize.Md` (20px) -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| --------------- | -------- | ------------------ | +| `BadgeIconSize` | No | `BadgeIconSize.Md` | ```tsx -import React from 'react'; -import BadgeIcon, { IconName } from '@metamask/design-system-react-native'; - -; + + ``` ---- +### `twClassName` -### Adjusting Icon Properties +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -```tsx -import { - IconColor, - IconSize, - IconName, -} from '@metamask/design-system-react-native'; +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -; -``` - ---- - -### Applying Tailwind Custom Styles +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx - -``` +import { BadgeIcon } from '@metamask/design-system-react-native'; ---- +// Add additional styles + + Custom Border + -## Notes +// Override default styles + + Override Background + +``` -- `BadgeIcon` provides a quick visual indication for different actions in the UI. -- You can override the default icon properties using `iconProps`. -- Tailwind classes and custom styles can be applied for further customization. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/BadgeNetwork/README.md b/packages/design-system-react-native/src/components/BadgeNetwork/README.md index adc9cce12..b09d954ef 100644 --- a/packages/design-system-react-native/src/components/BadgeNetwork/README.md +++ b/packages/design-system-react-native/src/components/BadgeNetwork/README.md @@ -1,163 +1,112 @@ # BadgeNetwork -`BadgeNetwork` indicates the network an entity is connected to. +BadgeNetwork indicates the network an entity is connected to. ---- - -## Props - -The `BadgeNetwork` component accepts the following props: - -### `src` (Required) - -The source of the image or SVG. It determines whether a local image, a local SVG component, or a remote image/SVG (via URI) is rendered. - -| TYPE | REQUIRED | DEFAULT | -| :------------------------------------------------------ | :------- | :------ | -| `number \| ComponentType \| { uri?: string }` | Yes | `N/A` | - ---- - -### `name` (Optional) - -Used to generate fallback text when the image or SVG fails to load. +```tsx +import { BadgeNetwork } from '@metamask/design-system-react-native'; -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | -| `string` | No | `undefined` | +; +``` ---- +## Props -### `fallbackText` (Optional) +### `name` -Custom fallback text displayed when the image fails to load. +The network name for the badge. | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | -| `string` | No | `name?.[0]` | - ---- - -### `fallbackTextProps` (Optional) - -Additional props for customizing the fallback text. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `object` | No | `{}` | - ---- - -### `imageProps` (Optional) - -Additional properties for the image component. - -| TYPE | REQUIRED | DEFAULT | -| :----------- | :------- | :-------------------------- | -| `ImageProps` | No | `{ resizeMode: 'contain' }` | - ---- +| -------- | -------- | ----------- | +| `string` | Yes | `undefined` | -### `onImageError` (Optional) - -Callback function triggered when the image fails to load. - -| TYPE | REQUIRED | DEFAULT | -| :------------------------------------------------------- | :------- | :---------- | -| `(e: NativeSyntheticEvent) => void` | No | `undefined` | - ---- +```tsx + +``` -### `onSvgError` (Optional) +### `src` -Callback function triggered when the SVG fails to load. +Custom image source for the network badge. -| TYPE | REQUIRED | DEFAULT | -| :----------------- | :------- | :---------- | -| `(e: any) => void` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| --------------- | -------- | ----------- | +| `ImageOrSvgSrc` | No | `undefined` | ---- +```tsx + +``` -### Other Props +### `variant` -`BadgeNetwork` supports all other props from [`AvatarNetwork`](#) and [`ImageOrSvg`](#), such as: +The visual variant of the badge. -- **`twClassName`** – Tailwind class names for styling. -- **`testID`** – Identifier used for testing purposes. -- **`style`** – Custom styles for the Badge container. +Available variants: ---- +- `BadgeNetworkVariant.Primary` +- `BadgeNetworkVariant.Secondary` -## Accessibility +| TYPE | REQUIRED | DEFAULT | +| --------------------- | -------- | ----------------------------- | +| `BadgeNetworkVariant` | No | `BadgeNetworkVariant.Primary` | -To ensure proper accessibility, the following React Native accessibility props can be passed: +```tsx + + +``` -- **`accessibilityLabel`**: Describes the Badge for screen readers. -- **`accessible`**: Set to `true` if the Badge represents meaningful content. +### `twClassName` ---- +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -## Usage +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import React from 'react'; -import BadgeNetwork from '@metamask/design-system-react-native/badge-network'; - -const App = () => ( - -); - -export default App; +import { BadgeNetwork } from '@metamask/design-system-react-native'; + +// Add additional styles + + Custom Border + + +// Override default styles + + Override Background + ``` ---- +### `style` + +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -### Handling Image Errors +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ```tsx -import React from 'react'; -import BadgeNetwork from '@metamask/design-system-react-native/badge-network'; - -const handleError = () => { - console.log('Image failed to load'); -}; - -const App = () => ( - +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + ); - -export default App; ``` ---- - -## Notes - -- **Fallback Mechanism:** - If an image or SVG fails to load, the component falls back to displaying text derived from the `name` prop. -- **Customization:** - Supports various props for shape, size, and additional styling. - -- **Extensibility:** - Any additional `ImageOrSvg` props are forwarded for greater flexibility. - ---- - -## Contributing - -1. Add tests for any new features or modifications. -2. Update this README to reflect any changes in the API. -3. Follow the project's coding guidelines and best practices. - ---- +## References -For further details, refer to the [React Native documentation](https://reactnative.dev/docs/image). +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/BadgeStatus/README.md b/packages/design-system-react-native/src/components/BadgeStatus/README.md index 86b377f70..02778f5c9 100644 --- a/packages/design-system-react-native/src/components/BadgeStatus/README.md +++ b/packages/design-system-react-native/src/components/BadgeStatus/README.md @@ -1,161 +1,110 @@ # BadgeStatus -`BadgeStatus` indicates the state of an item through color +BadgeStatus indicates the state of an item through color. ---- - -## Props +```tsx +import { BadgeStatus } from '@metamask/design-system-react-native'; -### `status` (Required) +; +``` -Controls the status of the badge. +## Props -| TYPE | REQUIRED | DEFAULT | -| :------------------ | :------- | :------ | -| `BadgeStatusStatus` | Yes | `N/A` | +### `variant` -Available statuses: +The status variant of the badge. -- `Active` (Connected) -- `Inactive` (Connected) -- `Disconnected` -- `New` -- `Attention` +Available variants: -Each status maps to a different background and border color: +- `BadgeStatusVariant.Success` +- `BadgeStatusVariant.Error` +- `BadgeStatusVariant.Warning` +- `BadgeStatusVariant.Info` -| Status | Background Color | Border Color | -| -------------- | -------------------- | ------------------------ | -| `Active` | `bg-success-default` | `border-success-default` | -| `Inactive` | `bg-default` | `border-success-default` | -| `Disconnected` | `bg-icon-muted` | `border-icon-muted` | -| `New` | `bg-primary-default` | `border-primary-default` | -| `Attention` | `bg-error-default` | `border-error-default` | +| TYPE | REQUIRED | DEFAULT | +| -------------------- | -------- | ----------- | +| `BadgeStatusVariant` | Yes | `undefined` | ---- +```tsx + + + + +``` ### `size` -Optional prop to control the size of the badge. - -| TYPE | REQUIRED | DEFAULT | -| :---------------- | :------- | :------------------- | -| `BadgeStatusSize` | No | `BadgeStatusSize.Md` | +The size of the BadgeStatus. Available sizes: -- `Md` (8px) -- `Lg` (10px) - ---- - -### `hasBorder` - -Determines whether the badge has an outer border. - -| TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | -| `boolean` | No | `true` | +- `BadgeStatusSize.Sm` (8px) +- `BadgeStatusSize.Md` (12px) ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - ---- - -### `style` - -Optional prop to control the style of the badge container. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -## Usage - -### Basic Usage - -```tsx -import React from 'react'; -import BadgeStatus, { - BadgeStatusStatus, -} from '@metamask/design-system-react-native'; - -; -``` - ---- - -### Changing Status +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | -------------------- | +| `BadgeStatusSize` | No | `BadgeStatusSize.Md` | ```tsx - + + ``` ---- - -### Adjusting Size - -```tsx -import { BadgeStatusSize } from '@metamask/design-system-react-native'; +### `twClassName` -; -``` +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Adding a Border +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx - -``` +import { BadgeStatus } from '@metamask/design-system-react-native'; ---- - -### Customizing with Tailwind +// Add additional styles + + Custom Border + -```tsx - +// Override default styles + + Override Background + ``` ---- +### `style` -## Accessibility +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -The `BadgeStatus` component supports accessibility through the optional `accessibilityLabel` prop. This allows developers to provide context-specific descriptions for screen readers. +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ```tsx -// Example with custom accessibility label - +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); ``` ---- - -## Notes - -- `BadgeStatus` is useful for indicating statuses such as online/offline states, alerts, or new updates. -- The border color dynamically adjusts based on the `status` value. -- You can override styles using `twClassName` or `style` props. - ---- - -## Contributing - -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. - ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/BadgeWrapper/README.md b/packages/design-system-react-native/src/components/BadgeWrapper/README.md index 38b0e213b..cddd1f7a2 100644 --- a/packages/design-system-react-native/src/components/BadgeWrapper/README.md +++ b/packages/design-system-react-native/src/components/BadgeWrapper/README.md @@ -1,203 +1,125 @@ # BadgeWrapper -The `BadgeWrapper` positions a badge on top of another element. +BadgeWrapper positions a badge on top of another element. ---- - -## Props - -### `children` (Required) - -The main element that the badge will be anchored to. Additional props can be passed to the children container using the `childrenContainerProps` prop. - -| TYPE | REQUIRED | DESCRIPTION | -| ----------------- | -------- | -------------------------------------- | -| `React.ReactNode` | Yes | Anchor element to attach the badge to. | - ---- - -### `badge` (Required) - -The badge element that is positioned relative to the `children`. Additional props can be passed to the badge container using the `badgeContainerProps` prop. - -| TYPE | REQUIRED | DESCRIPTION | -| ----------------- | -------- | ------------------------ | -| `React.ReactNode` | Yes | Badge element to render. | - ---- - -### `position` - -Optional preset to determine badge placement. - -| TYPE | REQUIRED | DEFAULT | -| ---------------------- | -------- | ---------------------------------- | -| `BadgeWrapperPosition` | No | `BadgeWrapperPosition.BottomRight` | - -Options: - -- `TopRight` -- `BottomRight` -- `BottomLeft` -- `TopLeft` - ---- - -### `positionAnchorShape` - -Specifies the shape of the anchor to adjust badge alignment. - -| TYPE | REQUIRED | DEFAULT | -| --------------------------------- | -------- | ------------------------------------------ | -| `BadgeWrapperPositionAnchorShape` | No | `BadgeWrapperPositionAnchorShape.Circular` | - -Options: - -- `Circular` -- `Rectangular` - ---- - -### `positionXOffset` - -Horizontal adjustment for the badge position. - -| TYPE | REQUIRED | DEFAULT | -| -------- | -------- | ------- | -| `number` | No | `0` | - ---- - -### `positionYOffset` - -Vertical adjustment for the badge position. - -| TYPE | REQUIRED | DEFAULT | -| -------- | -------- | ------- | -| `number` | No | `0` | - ---- - -### `customPosition` - -Allows complete control over badge positioning using style values. - -| TYPE | REQUIRED | DEFAULT | -| ---------------------------- | -------- | ----------- | -| `BadgeWrapperCustomPosition` | No | `undefined` | - -Example: +```tsx +import { BadgeWrapper } from '@metamask/design-system-react-native'; -```ts -{ - top: 5, - right: 10, -} +}> + Content with badge +; ``` ---- - -### `twClassName` - -Tailwind class names to apply to the outermost wrapper. +## Props -| TYPE | REQUIRED | DEFAULT | -| -------- | -------- | ------- | -| `string` | No | `''` | +### `children` ---- +The content to wrap with a badge. -### `style` +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------- | +| `ReactNode` | Yes | `undefined` | -Optional style override for the outermost wrapper. +```tsx +import { BadgeWrapper, BadgeCount } from '@metamask/design-system-react-native'; -| TYPE | REQUIRED | DEFAULT | -| ---------------------- | -------- | ------- | -| `StyleProp` | No | `null` | +}> + Wrapped content +; +``` ---- +### `badge` -## Usage +The badge component to display. -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------- | +| `ReactNode` | Yes | `undefined` | ```tsx -}> - +}> + Content ``` ---- +### `position` -### Preset Positions +The position of the badge relative to the wrapped content. -```tsx -} -> - - -``` +Available positions: ---- +- `BadgeWrapperPosition.TopRight` +- `BadgeWrapperPosition.TopLeft` +- `BadgeWrapperPosition.BottomRight` +- `BadgeWrapperPosition.BottomLeft` -### Custom Position +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ------------------------------- | +| `BadgeWrapperPosition` | No | `BadgeWrapperPosition.TopRight` | ```tsx } + badge={} + position={BadgeWrapperPosition.BottomRight} > - + Content ``` ---- +### `twClassName` + +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -### Anchor Shape Adjustment +- Add new styles that don't exist in the default component +- Override the component's default styles when needed + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx +import { BadgeWrapper } from '@metamask/design-system-react-native'; + +// Add additional styles } + badge={} + twClassName="bg-primary-100" > - + Custom Background -``` - ---- -### Offset Adjustments - -```tsx +// Override default styles } + badge={} + twClassName="!relative" > - + Override Position ``` ---- - -## Notes - -- You must wrap both `children` and `badge` elements using this component to ensure proper positioning. -- Positioning logic adjusts based on anchor shape to better align on circular vs. rectangular anchors. -- Offset props are additive and can help nudge badges pixel-perfect into place. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new props or layout logic. -2. Document new functionality in this README. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + } style={styles.custom}> + Custom styled content + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or reach out to the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/Box/README.md b/packages/design-system-react-native/src/components/Box/README.md index c9d4769ea..1a6016af0 100644 --- a/packages/design-system-react-native/src/components/Box/README.md +++ b/packages/design-system-react-native/src/components/Box/README.md @@ -1,652 +1,137 @@ # Box -`Box` is a low level flexbox layout component built on top of the React Native `View` element. It provides a comprehensive set of props for layout control including flexbox properties, spacing (margin and padding), borders, and background colors that map to Tailwind utility classes. - ---- - -## Props - -### Flexbox Properties - -### `flexDirection` - -The flexDirection style of the component for controlling the main axis direction. - -| TYPE | REQUIRED | -| :--------------------------------------- | :------- | -| [BoxFlexDirection](../../types/index.ts) | No | - -### `flexWrap` - -The flexWrap style of the component for controlling item wrapping behavior. - -| TYPE | REQUIRED | -| :---------------------------------- | :------- | -| [BoxFlexWrap](../../types/index.ts) | No | - -### `gap` - -The gap between the component's children. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `alignItems` - -The alignItems style of the component for cross-axis alignment. - -| TYPE | REQUIRED | -| :------------------------------------ | :------- | -| [BoxAlignItems](../../types/index.ts) | No | - -### `justifyContent` - -The justifyContent style of the component for main-axis alignment. - -| TYPE | REQUIRED | -| :---------------------------------------- | :------- | -| [BoxJustifyContent](../../types/index.ts) | No | - -### Margin Properties - -### `margin` - -The margin of the component on all sides. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `marginTop` - -The top margin of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `marginRight` - -The right margin of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `marginBottom` - -The bottom margin of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `marginLeft` - -The left margin of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `marginHorizontal` - -The horizontal margin (left and right) of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `marginVertical` - -The vertical margin (top and bottom) of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### Padding Properties - -### `padding` - -The padding of the component on all sides. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `paddingTop` - -The top padding of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `paddingRight` - -The right padding of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `paddingBottom` - -The bottom padding of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `paddingLeft` - -The left padding of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `paddingHorizontal` - -The horizontal padding (left and right) of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### `paddingVertical` - -The vertical padding (top and bottom) of the component. Use values from the BoxSpacing scale (0-12). - -| TYPE | REQUIRED | -| :--------------------------------- | :------- | -| [BoxSpacing](../../types/index.ts) | No | - -### Border Properties - -### `borderWidth` - -The border width of the component. Use only valid Tailwind CSS border width values (0, 1, 2, 4, 8). - -| TYPE | REQUIRED | -| :------------------------------------- | :------- | -| [BoxBorderWidth](../../types/index.ts) | No | - -### `borderColor` - -The border color of the component. - -| TYPE | REQUIRED | -| :------------------------------------- | :------- | -| [BoxBorderColor](../../types/index.ts) | No | - -### Background Properties - -### `backgroundColor` - -The background color of the component. - -| TYPE | REQUIRED | -| :----------------------------------------- | :------- | -| [BoxBackgroundColor](../../types/index.ts) | No | - -### General Properties - -### `twClassName` - -Optional prop to add twrnc overriding classNames for styling beyond the component's built-in props. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - -### `style` - -Optional style prop forwarded to the underlying `View`. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - -### Additional ViewProps - -All other `ViewProps` are passed directly to the underlying `View` component. - ---- - -## Usage - -### Flexbox Properties - -#### `flexDirection` +Box is a low-level flexbox layout component that provides a focused set of props for building responsive layouts. It maps to Tailwind CSS flexbox utilities and supports the design system's spacing and color tokens. ```tsx -// Horizontal layout (default) - - Item 1 - Item 2 - +import { Box } from '@metamask/design-system-react-native'; -// Vertical layout - - Item 1 - Item 2 - +Default Box; ``` -#### `flexWrap` - -```tsx - - Item 1 - Item 2 - Item 3 - Item 4 - -``` +## Props -#### `gap` +### `children` -```tsx -// Small gap (8px) - - Item 1 - Item 2 - +The content of the Box component. -// Large gap (24px) - - Item 1 - Item 2 - -``` - -#### `alignItems` +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------- | +| `ReactNode` | No | `undefined` | ```tsx -// Center items on cross axis - - Centered content - +import { Box } from '@metamask/design-system-react-native'; -// Stretch items to fill cross axis - - Stretched content - +Custom box content; ``` -#### `justifyContent` - -```tsx -// Space between items - - Left - Right - - -// Center items on main axis - - Centered - -``` +### `backgroundColor` -### Margin Properties +Background color of the box. -#### `margin` +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | ----------------------------- | +| `BackgroundColor` | No | `BackgroundColor.Transparent` | ```tsx -// All sides margin (16px) - - Box with margin - - -// No margin - - Box without margin + + Box with background color ``` -#### Directional Margins - -```tsx -// Different margins on each side - - Box with directional margins - - -// Horizontal and vertical margins - - Box with horizontal and vertical margins - -``` +### `borderColor` -### Padding Properties +Border color of the box. -#### `padding` +| TYPE | REQUIRED | DEFAULT | +| ------------- | -------- | ------------------------- | +| `BorderColor` | No | `BorderColor.Transparent` | ```tsx -// All sides padding (16px) - - Box with padding - - -// Large padding (24px) - - Box with large padding - +Box with border ``` -#### Directional Padding - -```tsx -// Different padding on each side - - Box with directional padding - - -// Horizontal and vertical padding - - Box with horizontal and vertical padding - -``` +### `borderRadius` -### Border Properties +Border radius of the box. -#### `borderWidth` and `borderColor` +| TYPE | REQUIRED | DEFAULT | +| -------------- | -------- | ------------------- | +| `BorderRadius` | No | `BorderRadius.None` | ```tsx -// Basic border - - Box with default border - - -// Thick colored border - - Box with thick primary border - - -// Error state border - - Error state box - +Box with rounded corners ``` -### Background Properties - -#### `backgroundColor` +### `padding` -```tsx -// Primary background - - Box with primary background - +Padding inside the box. -// Muted background - - Box with muted background - +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ------- | +| `number` | No | `0` | -// Success background - - Box with success background - +```tsx +Box with padding ``` -### Combined Usage - -#### Card-like Component +### `margin` -```tsx - - Card Title - - Card content goes here - More content - - -``` +Margin outside the box. -#### Complex Layout +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ------- | +| `number` | No | `0` | ```tsx - - Main Container - - Child 1 - Child 2 - - +Box with margin ``` ### `twClassName` -```tsx -// Custom styling with Tailwind classes - - Custom styled box - +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -// Size and positioning with Tailwind - - Half width, fixed height - -``` +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### `style` +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx - - Box with shadow - -``` - ---- - -## BoxSpacing Values - -The `gap`, `margin`, and `padding` props use the `BoxSpacing` numeric system for consistent spacing scales: - -**Available Values:** 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 - -**Pixel Mapping:** - -- `0` - 0px (none) -- `1` - 4px (extra small) -- `2` - 8px (small) -- `3` - 12px (small-medium) -- `4` - 16px (medium) -- `5` - 20px (medium-large) -- `6` - 24px (large) -- `7` - 28px (extra large) -- `8` - 32px (2x large) -- `9` - 36px (3x large) -- `10` - 40px (4x large) -- `11` - 44px (5x large) -- `12` - 48px (6x large) - -## BoxBorderWidth Values - -The `borderWidth` prop uses the `BoxBorderWidth` type with only valid Tailwind CSS border width values: - -**Available Values:** 0, 1, 2, 4, 8 - -**Pixel Mapping:** - -- `0` - 0px (no border, maps to `border-0`) -- `1` - 1px (default border, maps to `border`) -- `2` - 2px (maps to `border-2`) -- `4` - 4px (maps to `border-4`) -- `8` - 8px (maps to `border-8`) +import { Box } from '@metamask/design-system-react-native'; ---- - -## Color Options - -### BoxBackgroundColor - -Available background colors include: - -- `Default` - Default background color -- `Alternative` - Alternative background color -- `PrimaryDefault` - Primary brand color -- `PrimaryMuted` - Muted primary color -- `ErrorDefault` - Error state color -- `ErrorMuted` - Muted error color -- `WarningDefault` - Warning state color -- `WarningMuted` - Muted warning color -- `SuccessDefault` - Success state color -- `SuccessMuted` - Muted success color -- `InfoDefault` - Info state color -- `InfoMuted` - Muted info color -- `Transparent` - Transparent background - -### BoxBorderColor - -Available border colors include: - -- `Default` - Default border color -- `Muted` - Muted border color -- `PrimaryDefault` - Primary brand border -- `ErrorDefault` - Error state border -- `WarningDefault` - Warning state border -- `SuccessDefault` - Success state border -- `InfoDefault` - Info state border -- `Transparent` - Transparent border - ---- - -## Usage Patterns - -### Basic Horizontal Layout - -```tsx - - Item 1 - Item 2 - Item 3 +// Add additional styles + + Custom Padding and Margin -``` - -### Vertical Stack -```tsx - - Item 1 - Item 2 - Item 3 +// Override default styles + + Override Background ``` -### Space Between Layout +### `style` -```tsx - - Left - Right - -``` +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -### Alert/Notification Component +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ```tsx - - Warning: This is an alert message - +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + Custom styled box +); ``` -### Button-like Component +## References -```tsx - - Button Text - -``` +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/Button/README.md b/packages/design-system-react-native/src/components/Button/README.md index 23552581a..ac6fda326 100644 --- a/packages/design-system-react-native/src/components/Button/README.md +++ b/packages/design-system-react-native/src/components/Button/README.md @@ -1,116 +1,273 @@ -# [Button](https://metamask-consensys.notion.site/Button-88af1ddc075b40e3bb38a6d0c098d9b6) +# Button -![Button](./Button.png) +Button is a labeled element that a user can click or tap to initiate an action. -`Button` is a labeled element that a user can click or tap to initiate an action. +```tsx +import { Button } from '@metamask/design-system-react-native'; -_Developer Note: This component is a union component, which consists of [ButtonTertiary](./variants/ButtonTertiary/ButtonTertiary.tsx), [ButtonPrimary](./variants/ButtonPrimary/ButtonPrimary.tsx), and [ButtonSecondary](./variants/ButtonSecondary/ButtonSecondary.tsx)._ +; +``` + +## Props + +### `children` + +Required prop for the content to be rendered within the Button. + +| TYPE | REQUIRED | DEFAULT | +| --------------------------- | -------- | ----------- | +| `React.ReactNode \| string` | Yes | `undefined` | + +```tsx + + +``` -## ButtonTertiary Props +### `onPress` + +Function to trigger when pressing the button. -### `textVariant` +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | Yes | `undefined` | -Optional props to configure text component variants. +```tsx + +``` -| TYPE | REQUIRED | -| :-------------------------------------------------- | :------------------------------------------------------ | -| [TextVariant](../../../../Texts/Text/Text.types.ts) | No | +### `variant` -## Common Props +The visual variant of the button. -### `label` +Available variants: -ButtonBase text. +- `ButtonVariant.Primary` +- `ButtonVariant.Secondary` +- `ButtonVariant.Tertiary` -| TYPE | REQUIRED | -| :-------------------------------------------------- | :------------------------------------------------------ | -| string | Yes | +| TYPE | REQUIRED | DEFAULT | +| --------------- | -------- | ----------- | +| `ButtonVariant` | Yes | `undefined` | + +```tsx + + +``` ### `size` -Optional prop for the size of the button. +The size of the button. -| TYPE | REQUIRED | DEFAULT | -| :-------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- | -| [ButtonSize](../../Button.types.ts) | Yes | Md | +Available sizes: -### `onPress` +- `ButtonBaseSize.Sm` (32px height) +- `ButtonBaseSize.Md` (40px height) +- `ButtonBaseSize.Lg` (48px height) -Function to trigger when pressing the button. +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `ButtonBaseSize` | No | `ButtonBaseSize.Lg` | -| TYPE | REQUIRED | -| :-------------------------------------------------- | :------------------------------------------------------ | -| Function | Yes | +```tsx + + +``` ### `startIconName` -Optional prop for the icon name of the icon that will be displayed before the label. +Optional icon name to display before the content. -| TYPE | REQUIRED | -| :-------------------------------------------------- | :------------------------------------------------------ | -| [IconName](../Icons/Icon.types.ts) | No | +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | No | `undefined` | + +```tsx + +``` ### `endIconName` -Optional prop for the icon name of the icon that will be displayed after the label. +Optional icon name to display after the content. -| TYPE | REQUIRED | -| :-------------------------------------------------- | :------------------------------------------------------ | -| [IconName](../Icons/Icon.types.ts) | No | +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | No | `undefined` | + +```tsx + +``` ### `isDanger` -Optional boolean to show the danger state of the button. +Whether to show the button in danger state (only available for Primary variant). + +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | + +```tsx + +``` + +### `isInverse` + +Whether to show the button with inverted colors for use on colored backgrounds (only available for Primary variant). -| TYPE | REQUIRED | DEFAULT | -| :-------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- | -| boolean | No | false | +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | -### `width` +```tsx + +``` + +### `isDisabled` + +Whether the button is disabled. + +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | + +```tsx + +``` + +### `isFullWidth` -Optional param to control the width of the button. +Whether the button should take up the full width of its container. -| TYPE | REQUIRED | DEFAULT | -| :-------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- | -| [ButtonWidthTypes](../../Button.types.ts) or number | No | ButtonWidthTypes.Auto | +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | + +```tsx + +``` + +### `isLoading` + +Whether the button is in a loading state, showing a spinner. + +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | + +```tsx + +``` -## Usage +### `loadingText` -```javascript -// ButtonTertiary +Text to display when the button is in loading state. + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | + +```tsx +``` + +### `twClassName` + +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: + +- Add new styles that don't exist in the default component +- Override the component's default styles when needed + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | + +```tsx +import { Button } from '@metamask/design-system-react-native'; + +// Add additional styles + +// Override default styles +``` + +### `style` + +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. + +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | + +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); ``` + +## References + +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/Button/variants/ButtonPrimary/README.md b/packages/design-system-react-native/src/components/Button/variants/ButtonPrimary/README.md index 6d9b1d2c9..f7fab048f 100644 --- a/packages/design-system-react-native/src/components/Button/variants/ButtonPrimary/README.md +++ b/packages/design-system-react-native/src/components/Button/variants/ButtonPrimary/README.md @@ -2,6 +2,12 @@ `ButtonPrimary` is a button for most important and desired action to guide the user. +```tsx +import { ButtonPrimary } from '@metamask/design-system-react-native'; + + {}}>Click Me; +``` + ## Props ### `children` @@ -12,6 +18,24 @@ The content to display inside the button. | ----------------- | ------------ | ----------- | | `React.ReactNode` | Yes | `undefined` | +```tsx + {}}>Button Content +``` + +### `onPress` + +Function to trigger when the button is pressed. + +| **Type** | **Required** | **Default** | +| ------------ | ------------ | ----------- | +| `() => void` | Yes | `undefined` | + +```tsx + console.log('Primary button pressed!')}> + Click Me + +``` + ### `size` Defines the size of the button. @@ -20,6 +44,11 @@ Defines the size of the button. | ------------ | ------------ | --------------- | | `ButtonSize` | No | `ButtonSize.Lg` | +```tsx + {}}>Small Button + {}}>Large Button +``` + ### `isLoading` Indicates whether the button is in a loading state. If `true`, a spinner is displayed, and the button's content is hidden. @@ -28,6 +57,12 @@ Indicates whether the button is in a loading state. If `true`, a spinner is disp | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Loading Button + +``` + ### `loadingText` Text to display alongside the spinner when the button is loading. @@ -36,6 +71,12 @@ Text to display alongside the spinner when the button is loading. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with Loading Text + +``` + ### `isDisabled` Disables the button, preventing interaction. @@ -44,6 +85,12 @@ Disables the button, preventing interaction. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Disabled Button + +``` + ### `isDanger` Renders the button in a danger style to indicate destructive actions. @@ -52,6 +99,12 @@ Renders the button in a danger style to indicate destructive actions. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Danger Button + +``` + ### `isInverse` Renders the button with inverted colors for use on dark backgrounds. @@ -60,6 +113,12 @@ Renders the button with inverted colors for use on dark backgrounds. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Inverse Button + +``` + ### `startIconName` Name of the icon to display at the start of the button. @@ -68,6 +127,12 @@ Name of the icon to display at the start of the button. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with Start Icon + +``` + ### `endIconName` Name of the icon to display at the end of the button. @@ -76,6 +141,12 @@ Name of the icon to display at the end of the button. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with End Icon + +``` + ### `twClassName` TailwindCSS class names to apply custom styling. @@ -84,6 +155,12 @@ TailwindCSS class names to apply custom styling. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Custom Styled Button + +``` + ### `style` Custom styles to apply to the button. @@ -92,30 +169,19 @@ Custom styles to apply to the button. | ---------------------- | ------------ | ----------- | | `StyleProp` | No | `undefined` | -## Usage - ```tsx -import React from 'react'; -import ButtonPrimary from './ButtonPrimary'; - -const App = () => { - return ( - console.log('Primary button pressed!')} - > - Click Me - - ); -}; - -export default App; +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}}> + Custom Styled Button + +); ``` ## Notes diff --git a/packages/design-system-react-native/src/components/Button/variants/ButtonSecondary/README.md b/packages/design-system-react-native/src/components/Button/variants/ButtonSecondary/README.md index 94d5d986e..d05492a74 100644 --- a/packages/design-system-react-native/src/components/Button/variants/ButtonSecondary/README.md +++ b/packages/design-system-react-native/src/components/Button/variants/ButtonSecondary/README.md @@ -2,6 +2,12 @@ `ButtonSecondary` is a button for additional options that are helpful. +```tsx +import { ButtonSecondary } from '@metamask/design-system-react-native'; + + {}}>Click Me; +``` + ## Props ### `children` @@ -12,6 +18,24 @@ Content to display inside the button. | ----------------- | ------------ | ----------- | | `React.ReactNode` | Yes | `undefined` | +```tsx + {}}>Button Content +``` + +### `onPress` + +Function to trigger when the button is pressed. + +| **Type** | **Required** | **Default** | +| ------------ | ------------ | ----------- | +| `() => void` | Yes | `undefined` | + +```tsx + console.log('Secondary button pressed!')}> + Click Me + +``` + ### `size` Defines the size of the button. @@ -20,6 +44,11 @@ Defines the size of the button. | ------------ | ------------ | --------------- | | `ButtonSize` | No | `ButtonSize.Lg` | +```tsx + {}}>Small Button + {}}>Large Button +``` + ### `isLoading` Indicates whether the button is in a loading state. If `true`, a spinner is displayed, and the button's content is hidden. @@ -28,6 +57,12 @@ Indicates whether the button is in a loading state. If `true`, a spinner is disp | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Loading Button + +``` + ### `loadingText` Text to display alongside the spinner when the button is loading. @@ -36,6 +71,12 @@ Text to display alongside the spinner when the button is loading. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with Loading Text + +``` + ### `isDisabled` Disables the button, preventing interaction. @@ -44,6 +85,12 @@ Disables the button, preventing interaction. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Disabled Button + +``` + ### `isDanger` Renders the button in a danger style to indicate destructive actions. @@ -52,6 +99,12 @@ Renders the button in a danger style to indicate destructive actions. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Danger Button + +``` + ### `isInverse` Renders the button with inverted colors for use on dark backgrounds. @@ -60,6 +113,12 @@ Renders the button with inverted colors for use on dark backgrounds. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Inverse Button + +``` + ### `startIconName` Name of the icon to display at the start of the button. @@ -68,6 +127,12 @@ Name of the icon to display at the start of the button. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with Start Icon + +``` + ### `endIconName` Name of the icon to display at the end of the button. @@ -76,6 +141,12 @@ Name of the icon to display at the end of the button. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with End Icon + +``` + ### `twClassName` TailwindCSS class names to apply custom styling. @@ -84,6 +155,12 @@ TailwindCSS class names to apply custom styling. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Custom Styled Button + +``` + ### `style` Custom styles to apply to the button. @@ -92,30 +169,19 @@ Custom styles to apply to the button. | ---------------------- | ------------ | ----------- | | `StyleProp` | No | `undefined` | -## Usage - ```tsx -import React from 'react'; -import ButtonSecondary from './ButtonSecondary'; - -const App = () => { - return ( - console.log('Secondary button pressed!')} - > - Click Me - - ); -}; - -export default App; +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}}> + Custom Styled Button + +); ``` ## Notes diff --git a/packages/design-system-react-native/src/components/Button/variants/ButtonTertiary/README.md b/packages/design-system-react-native/src/components/Button/variants/ButtonTertiary/README.md index 165a7a3eb..5d4d0e2d7 100644 --- a/packages/design-system-react-native/src/components/Button/variants/ButtonTertiary/README.md +++ b/packages/design-system-react-native/src/components/Button/variants/ButtonTertiary/README.md @@ -2,6 +2,12 @@ `ButtonTertiary` is a button for optional and lowest attention. +```tsx +import { ButtonTertiary } from '@metamask/design-system-react-native'; + + {}}>Click Me; +``` + ## Props ### `children` @@ -12,6 +18,24 @@ The content to display inside the button. | ----------------- | ------------ | ----------- | | `React.ReactNode` | Yes | `undefined` | +```tsx + {}}>Button Content +``` + +### `onPress` + +Function to trigger when the button is pressed. + +| **Type** | **Required** | **Default** | +| ------------ | ------------ | ----------- | +| `() => void` | Yes | `undefined` | + +```tsx + console.log('Tertiary button pressed!')}> + Click Me + +``` + ### `size` Defines the size of the button. @@ -20,6 +44,11 @@ Defines the size of the button. | ------------ | ------------ | --------------- | | `ButtonSize` | No | `ButtonSize.Lg` | +```tsx + {}}>Small Button + {}}>Large Button +``` + ### `isLoading` Indicates whether the button is in a loading state. If `true`, a spinner is displayed, and the button's content is hidden. @@ -28,6 +57,12 @@ Indicates whether the button is in a loading state. If `true`, a spinner is disp | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Loading Button + +``` + ### `loadingText` Text to display alongside the spinner when the button is loading. @@ -36,6 +71,12 @@ Text to display alongside the spinner when the button is loading. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with Loading Text + +``` + ### `isDisabled` Disables the button, preventing interaction. @@ -44,6 +85,12 @@ Disables the button, preventing interaction. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Disabled Button + +``` + ### `isDanger` Renders the button in a danger style to indicate destructive actions. @@ -52,6 +99,12 @@ Renders the button in a danger style to indicate destructive actions. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Danger Button + +``` + ### `isInverse` Renders the button with inverted colors for use on dark backgrounds. @@ -60,6 +113,12 @@ Renders the button with inverted colors for use on dark backgrounds. | --------- | ------------ | ----------- | | `boolean` | No | `false` | +```tsx + {}}> + Inverse Button + +``` + ### `startIconName` Name of the icon to display at the start of the button. @@ -68,6 +127,12 @@ Name of the icon to display at the start of the button. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with Start Icon + +``` + ### `endIconName` Name of the icon to display at the end of the button. @@ -76,6 +141,12 @@ Name of the icon to display at the end of the button. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Button with End Icon + +``` + ### `twClassName` TailwindCSS class names to apply custom styling. @@ -84,6 +155,12 @@ TailwindCSS class names to apply custom styling. | -------- | ------------ | ----------- | | `string` | No | `undefined` | +```tsx + {}}> + Custom Styled Button + +``` + ### `style` Custom styles to apply to the button. @@ -92,30 +169,19 @@ Custom styles to apply to the button. | ---------------------- | ------------ | ----------- | | `StyleProp` | No | `undefined` | -## Usage - ```tsx -import React from 'react'; -import ButtonTertiary from './ButtonTertiary'; - -const App = () => { - return ( - console.log('Primary button pressed!')} - > - Click Me - - ); -}; - -export default App; +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}}> + Custom Styled Button + +); ``` ## Notes diff --git a/packages/design-system-react-native/src/components/ButtonBase/README.md b/packages/design-system-react-native/src/components/ButtonBase/README.md index 2d34a46af..1bc9255ba 100644 --- a/packages/design-system-react-native/src/components/ButtonBase/README.md +++ b/packages/design-system-react-native/src/components/ButtonBase/README.md @@ -1,397 +1,148 @@ # ButtonBase -`ButtonBase` is a labeled element that a user can click or tap to initiate an action. - ---- - -## Props - -### `children` (Required) - -The content to be rendered within the `ButtonBase`. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | ----- | -| `ReactNode` | string | Yes | `N/A` | - ---- - -### `textProps` - -Optional props to be passed to the `Text` component when the `children` is a string. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `TextProps` | No | `{}` | - ---- - -### `size` - -Optional prop to control the size of the `ButtonBase`. - -| TYPE | REQUIRED | DEFAULT | -| :--------------- | :------- | :------------------ | -| `ButtonBaseSize` | No | `ButtonBaseSize.Lg` | - -Available sizes: - -- `ButtonBaseSize.Sm` (32px) -- `ButtonBaseSize.Md` (40px) -- `ButtonBaseSize.Lg` (48px) - ---- - -### `isLoading` - -Optional prop that, when `true`, shows a loading spinner. - -| TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | -| `boolean` | No | `false` | - ---- - -### `loadingText` - -Optional text to display when the button is in the loading state. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | -| `string` | No | `"Loading"` | - ---- - -### `spinnerProps` - -Optional props to customize the appearance of the spinner. - -| TYPE | REQUIRED | DEFAULT | -| :------------- | :------- | :------ | -| `SpinnerProps` | No | `{}` | - ---- - -### `startIconName` - -Optional prop to specify an icon to show at the start of the button. - -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | No | `null` | - ---- - -### `startIconProps` - -Optional props to pass additional properties to the start icon. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `IconProps` | No | `{}` | - ---- - -### `startAccessory` - -Optional prop for a custom element to show at the start of the button. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `ReactNode` | No | `null` | - ---- - -### `endIconName` - -Optional prop to specify an icon to show at the end of the button. - -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | No | `null` | - ---- - -### `endIconProps` - -Optional props to pass additional properties to the end icon. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `IconProps` | No | `{}` | - ---- - -### `endAccessory` - -Optional prop for a custom element to show at the end of the button. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `ReactNode` | No | `null` | - ---- - -### `isDisabled` - -Optional prop that, when `true`, disables the button. - -| TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | -| `boolean` | No | `false` | - ---- - -### `isFullWidth` - -Optional prop that, when `true`, makes the button take up the full width of its container. - -| TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | -| `boolean` | No | `false` | - ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - ---- - -### `style` - -Optional prop to control the style. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -## Usage - -### Basic Usage +ButtonBase is a labeled element that a user can click or tap to initiate an action. ```tsx -import React from 'react'; -import ButtonBase from '@metamask/design-system-react-native'; +import { ButtonBase } from '@metamask/design-system-react-native'; - console.log('Pressed!')}>Click Me; + console.log('Pressed')}>Button Content; ``` ---- +## Props -### Button with Icon +### `children` -```tsx -Go Back -``` +The content of the ButtonBase component. ---- - -### Button with Spinner +| TYPE | REQUIRED | DEFAULT | +| --------------------------- | -------- | ----------- | +| `React.ReactNode \| string` | Yes | `undefined` | ```tsx -Loading... -``` - ---- +import { ButtonBase } from '@metamask/design-system-react-native'; -### Customizing the Spinner - -```tsx - - Please wait - + {}}> + Custom button content +; ``` ---- - -### Accessibility +### `onPress` -The `ButtonBase` component is designed to be fully accessible according to WCAG guidelines and React Native accessibility standards. +Function to trigger when pressing the button. -#### Automatic Accessibility Features - -- **Default Role**: Automatically sets `accessibilityRole="button"` -- **Auto-Generated Labels**: Uses string `children` as `accessibilityLabel` when no custom label is provided -- **State Management**: Automatically manages `accessibilityState` for disabled and loading states -- **Loading Announcements**: Provides automatic loading state announcements for screen readers - -#### Accessibility Props - -##### `accessibilityLabel` - -Optional accessibility label to describe the button for screen readers. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------------------------------------------- | -| `string` | No | Auto-generated from `children` or loading state | +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | Yes | `undefined` | ```tsx -Save + console.log('Button pressed')}>Press me ``` -##### `accessibilityHint` +### `isDisabled` -Optional accessibility hint to provide additional context about the button's action. +Whether the button is disabled. -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------------------------------- | -| `string` | No | Auto-generated for loading state | +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | ```tsx - - Submit + {}}> + Disabled Button ``` -##### `accessibilityRole` - -Optional accessibility role. Defaults to 'button' but can be overridden for specific use cases. +### `size` -| TYPE | REQUIRED | DEFAULT | -| :---------------------------------------------------- | :------- | :--------- | -| `'button' \| 'link' \| 'menuitem' \| 'tab' \| 'none'` | No | `'button'` | +The size of the button. -```tsx -View Details -``` - -##### `accessibilityActions` +Available sizes: -Optional accessibility actions for custom interactions. Use sparingly and only when default button behavior is insufficient. +- `ButtonBaseSize.Sm` (32px height) +- `ButtonBaseSize.Md` (40px height) +- `ButtonBaseSize.Lg` (48px height) -| TYPE | REQUIRED | DEFAULT | -| :----------------------------------------- | :------- | :---------- | -| `Array<{ name: string; label?: string; }>` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `ButtonBaseSize` | No | `ButtonBaseSize.Md` | ```tsx - { - if (event.nativeEvent.actionName === 'longpress') { - showContextMenu(); - } - }} -> - Options + {}}> + Small Button + + {}}> + Large Button ``` -##### `onAccessibilityAction` - -Optional callback for handling accessibility action events. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------------------------------------------- | :------- | :---------- | -| `(event: { nativeEvent: { actionName: string } }) => void` | No | `undefined` | - -#### Accessibility State Management - -The component automatically manages `accessibilityState` based on props: - -- **Disabled State**: Set when `isDisabled={true}` or `isLoading={true}` -- **Busy State**: Set when `isLoading={true}` to indicate loading operations +### `borderRadius` -#### Loading State Accessibility +Border radius of the button. -When `isLoading={true}`: - -- Button becomes disabled and announces "busy" state -- Accessibility label prioritizes `loadingText` if provided -- Accessibility hint automatically explains loading state -- Custom `accessibilityHint` overrides automatic loading hint +| TYPE | REQUIRED | DEFAULT | +| -------------- | -------- | ----------------- | +| `BorderRadius` | No | `BorderRadius.MD` | ```tsx -// Automatic loading accessibility - - Save Changes - -// Screen reader announces: "Saving..., button, busy, Button is currently loading, please wait" - -// Custom loading accessibility - - Pay Now + {}}> + Rounded Button ``` -#### Best Practices +### `twClassName` -1. **Descriptive Labels**: Use clear, descriptive text for button content -2. **Meaningful Hints**: Provide hints that explain the button's action or outcome -3. **Loading States**: Always provide `loadingText` for better loading state communication -4. **Icon-Only Buttons**: Always provide `accessibilityLabel` for buttons with only icons -5. **Context-Specific Roles**: Use appropriate `accessibilityRole` (e.g., 'link' for navigation) +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -#### Examples +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -```tsx -// Basic accessible button -Save Changes +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -// Icon-only button with accessibility - - {/* No text content */} - +```tsx +import { ButtonBase } from '@metamask/design-system-react-native'; -// Loading button with custom accessibility +// Add additional styles {}} + twClassName="border-2 border-primary-100" > - Create Account + Custom Border -// Navigation button +// Override default styles navigation.navigate('Profile')} + onPress={() => {}} + twClassName="!bg-error-100" > - View Profile + Override Background ``` ---- - -### Notes - -- `ButtonBase` is optimized for handling different button states (loading, disabled, full width). -- Use `isLoading` to disable user interactions during a loading state. -- Icons and spinners are fully customizable through props. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}} style={styles.custom}> + Custom styled button + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/ButtonIcon/README.md b/packages/design-system-react-native/src/components/ButtonIcon/README.md index 0deb0b2d6..e393489ef 100644 --- a/packages/design-system-react-native/src/components/ButtonIcon/README.md +++ b/packages/design-system-react-native/src/components/ButtonIcon/README.md @@ -1,157 +1,171 @@ # ButtonIcon -A Button Icon is a compact, icon-only button that triggers an action, designed for quick, space-efficient interactions +A Button Icon is a compact, icon-only button that triggers an action, designed for quick, space-efficient interactions. ---- +```tsx +import { ButtonIcon } from '@metamask/design-system-react-native'; + + console.log('Pressed')} />; +``` ## Props -### `size` +### `iconName` -Optional prop to control the size of the `ButtonIcon`. +The icon name to display in the button. -| TYPE | REQUIRED | DEFAULT | -| :--------------- | :------- | :------------------ | -| `ButtonIconSize` | No | `ButtonIconSize.Md` | +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | Yes | `undefined` | -Available sizes: +```tsx + {}} /> +``` -- `ButtonIconSize.Sm` (24px) -- `ButtonIconSize.Md` (32px) -- `ButtonIconSize.Lg` (40px) +### `onPress` ---- +Function to trigger when pressing the button. -### `iconName` (Required) +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | Yes | `undefined` | -The name of the icon to be displayed. +```tsx + console.log('Settings pressed')} +/> +``` -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | Yes | `N/A` | +### `size` ---- +The size of the button. -### `iconProps` +Available sizes: -Optional props to customize the icon. +- `ButtonIconSize.Sm` (32px) +- `ButtonIconSize.Md` (40px) +- `ButtonIconSize.Lg` (48px) -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `IconProps` | No | `{}` | +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ------------------- | +| `ButtonIconSize` | No | `ButtonIconSize.Md` | ---- +```tsx + {}} +/> + {}} +/> +``` ### `isDisabled` -Optional prop that, when `true`, disables the button. +Whether the button is disabled. | TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | +| --------- | -------- | ------- | | `boolean` | No | `false` | ---- +```tsx + {}} /> +``` ### `isInverse` -Optional prop to show the inverse state of the button, typically used for buttons on colored backgrounds. +Whether to show the button with inverted colors for use on colored backgrounds. | TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | +| --------- | -------- | ------- | | `boolean` | No | `false` | ---- +```tsx + {}} /> +``` ### `isFloating` -Optional prop to apply floating button styling. +Whether to show the button in floating/contained state for floating buttons. | TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | +| --------- | -------- | ------- | | `boolean` | No | `false` | -**Note:** This prop applies styling only. There is no positioning logic. - ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | - ---- - -### `style` - -Optional prop to control the style. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -## Usage - -### Basic Usage - ```tsx -import React from 'react'; -import ButtonIcon from '@metamask/design-system-react-native'; - - console.log('Pressed!')} />; + {}} /> ``` ---- +### `iconProps` + +Optional props to pass to the Icon component. -### Custom Icon Size +| TYPE | REQUIRED | DEFAULT | +| -------------------- | -------- | ----------- | +| `Partial` | No | `undefined` | ```tsx - + {}} +/> ``` ---- - -### Disabled Icon Button +### `twClassName` -```tsx - -``` +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Floating Icon Button +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx - +import { ButtonIcon } from '@metamask/design-system-react-native'; + +// Add additional styles + {}} + twClassName="shadow-lg" +/> + +// Override default styles + {}} + twClassName="!bg-error-100" +/> ``` ---- - -### Accessibility - -- Use the `accessibilityLabel` prop to provide meaningful labels for assistive technologies. -- Ensure `iconName` represents a clear visual meaning for users. - ---- - -### Notes - -- `ButtonIcon` is optimized for handling different button states (disabled, floating, inverse). -- Use `isFloating` for styling but apply additional logic if floating positioning is required. -- Icons are fully customizable through props. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}} style={styles.custom} /> +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/Checkbox/README.md b/packages/design-system-react-native/src/components/Checkbox/README.md index 4854db54a..f01c51a7c 100644 --- a/packages/design-system-react-native/src/components/Checkbox/README.md +++ b/packages/design-system-react-native/src/components/Checkbox/README.md @@ -1,157 +1,99 @@ # Checkbox -`Checkbox` allows users to select one or more options from a set of choices. - -_Developer Note: This is a fully controlled component, requiring you to manage the state with `isSelected` and `onChange` props._ +Checkbox allows users to select one or more options from a set of choices. ```tsx import { Checkbox } from '@metamask/design-system-react-native'; -import { useState } from 'react'; - -function MyComponent() { - const [isEnabled, setIsEnabled] = useState(false); - - return ( - setIsEnabled(!isEnabled)} - /> - ); -} + + console.log(value)} />; ``` ## Props ### `isSelected` -Required prop to determine whether the checkbox is currently selected. This component is fully controlled, so you must manage this state in your parent component. +Whether the checkbox is currently selected. | TYPE | REQUIRED | DEFAULT | | --------- | -------- | ----------- | | `boolean` | Yes | `undefined` | ```tsx -const [isSelected, setIsSelected] = useState(true); - - setIsEnabled(!isSelected)} - label="Selected by default" -/>; + {}} /> ``` ---- - -### `isDisabled` +### `onChange` -Optional prop that when true, disables the checkbox. +Function called when the checkbox selection changes. -| TYPE | REQUIRED | DEFAULT | -| --------- | -------- | ------- | -| `boolean` | No | `false` | +| TYPE | REQUIRED | DEFAULT | +| ------------------------------- | -------- | ----------- | +| `(isSelected: boolean) => void` | Yes | `undefined` | ```tsx -const [isSelected, setIsSelected] = useState(false); - setIsEnabled(!isSelected)}} - isDisabled - label="Disabled checkbox" -/>; + isSelected={false} + onChange={(selected) => console.log('Selected:', selected)} +/> ``` ---- - -### `isInvalid` +### `isDisabled` -Optional prop that when true, displays the invalid/error state of the checkbox. +Whether the checkbox is disabled. | TYPE | REQUIRED | DEFAULT | | --------- | -------- | ------- | | `boolean` | No | `false` | ```tsx -const [isSelected, setIsSelected] = useState(false); - - setIsEnabled(!isSelected)}} - isInvalid - label="Invalid checkbox" -/>; + {}} /> ``` ---- - -### `onChange` +### `isInvalid` -Required callback function triggered when the checked state changes. Use this to update your state. +Whether the checkbox is in an invalid/error state. -| TYPE | REQUIRED | DEFAULT | -| ------------------------------- | -------- | ----------- | -| `(isSelected: boolean) => void` | Yes | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | ```tsx -const [isSelected, setIsSelected] = useState(false); - - setIsEnabled(!isSelected)}} label="Check me" />; + {}} /> ``` ---- - ### `label` -Optional label prop that renders text or a React node as a label beside the checkbox. +Label text or React node for the checkbox. -| TYPE | REQUIRED | DEFAULT | -| --------------------- | -------- | ----------- | -| `string \| ReactNode` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| --------------------------- | -------- | ----------- | +| `React.ReactNode \| string` | No | `undefined` | ```tsx -const [isSelected, setIsSelected] = useState(false); - setIsEnabled(!isSelected)}} - label="Agree to terms" -/>; + isSelected={false} + label="Accept terms and conditions" + onChange={() => {}} +/> ``` ---- - ### `labelProps` Optional props to be passed to the label's Text component. -| TYPE | REQUIRED | DEFAULT | -| -------------------- | -------- | ----------- | -| `Partial` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| -------------------------------------- | -------- | ----------- | +| `Omit, 'children'>` | No | `undefined` | ```tsx -const [isSelected, setIsSelected] = useState(false); - setIsEnabled(!isSelected)}} - label="Label" - labelProps={{ variant: 'BodySm', color: 'text-muted' }} -/>; + isSelected={false} + label="Custom label" + labelProps={{ variant: TextVariant.BodySm, color: TextColor.TextMuted }} + onChange={() => {}} +/> ``` ---- - -### `checkboxContainerProps` - -Optional props passed to the container view wrapping the checkbox icon. - -| TYPE | REQUIRED | DEFAULT | -| -------------------- | -------- | ----------- | -| `Partial` | No | `undefined` | - ---- - ### `checkedIconProps` Optional props to be passed to the check Icon component. @@ -160,83 +102,64 @@ Optional props to be passed to the check Icon component. | -------------------- | -------- | ----------- | | `Partial` | No | `undefined` | ---- - -### `ref` - -The Checkbox component exposes an imperative API through refs that allows for programmatic control. The `toggle` method allows a parent component to programmatically toggle the checkbox state. - ```tsx -// Example of using the ref to toggle a checkbox -const [isSelected, setIsSelected] = useState(false); -const checkboxRef = useRef<{ toggle: () => void }>(null); - -// Inside your component render -<> - setIsEnabled(!isSelected)}} - label="Toggle me via ref" - /> - -; + {}} +/> ``` -This can be useful in scenarios where you need to trigger the checkbox programmatically, such as when implementing "Select All" functionality or resetting forms. - ---- - ### `twClassName` -Use the `twClassName` prop to add Tailwind CSS classes to the checkbox container. These classes are merged with the default classes. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: + +- Add new styles that don't exist in the default component +- Override the component's default styles when needed | TYPE | REQUIRED | DEFAULT | | -------- | -------- | ----------- | | `string` | No | `undefined` | ```tsx -const [isSelected, setIsSelected] = useState(false); +import { Checkbox } from '@metamask/design-system-react-native'; +// Add additional styles setIsEnabled(!isSelected)}} - label="Custom BG" - twClassName="bg-primary-100" -/>; -``` + isSelected={false} + onChange={() => {}} + twClassName="p-2" +/> ---- +// Override default styles + {}} + twClassName="!border-error-100" +/> +``` ### `style` -Custom styles for the outer `Pressable` container. +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. | TYPE | REQUIRED | DEFAULT | | ---------------------- | -------- | ----------- | | `StyleProp` | No | `undefined` | ```tsx -const [isSelected, setIsSelected] = useState(false); -const customStyles = { - marginVertical: 10, -}; - - setIsEnabled(!isSelected)}} - label="Styled" - style={customStyles} -/>; +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}} style={styles.custom} /> +); ``` ---- - ## References [MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/Icon/README.md b/packages/design-system-react-native/src/components/Icon/README.md index f0cfdaf26..938337ead 100644 --- a/packages/design-system-react-native/src/components/Icon/README.md +++ b/packages/design-system-react-native/src/components/Icon/README.md @@ -1,29 +1,32 @@ # Icon -The `Icon` component is a customizable SVG icon component for React Native applications, integrating with Tailwind CSS classes via `twrnc`. It allows you to display various icons by name, with optional size and color customizations. +Icons are read-only symbols that represent ideas or objects, offered in standard sizes. + +```tsx +import { Icon } from '@metamask/design-system-react-native'; + +; +``` ## Props ### `name` -**Required**. Specifies which icon to render from the icon set. +The icon name to display. -| TYPE | REQUIRED | -| :------------------------------- | :------- | -| [IconName](./Icon.types.ts#L---) | Yes | +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | Yes | `undefined` | -You can find the full list of available icons in `Icon.types.ts`, under the `IconName` enum. +```tsx + +``` ### `size` -Optional prop that controls the size of the icon in pixels. -All sizes map to numeric pixel values. - -| TYPE | REQUIRED | DEFAULT | -| :------------------------------- | :------- | :------------ | -| [IconSize](./Icon.types.ts#L---) | No | `IconSize.Md` | +The size of the icon. -Available `IconSize` options: +Available sizes: - `IconSize.Xs` (12px) - `IconSize.Sm` (16px) @@ -31,119 +34,92 @@ Available `IconSize` options: - `IconSize.Lg` (24px) - `IconSize.Xl` (32px) -### `color` +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ------------- | +| `IconSize` | No | `IconSize.Md` | -Optional prop to set the icon color using predefined theme classes. - -| TYPE | REQUIRED | DEFAULT | -| :-------------------------------- | :------- | :---------------------- | -| [IconColor](./Icon.types.ts#L---) | No | `IconColor.IconDefault` | - -Available `IconColor` options include: - -- `IconDefault` (text-icon-default) -- `IconAlternative` (text-icon-alternative) -- `IconMuted` (text-icon-muted) -- `OverlayInverse` (text-overlay-inverse) -- `PrimaryDefault` (text-primary-default) -- `PrimaryInverse` (text-primary-inverse) -- `ErrorDefault` (text-error-default) -- `ErrorInverse` (text-error-inverse) -- `SuccessDefault` (text-success-default) -- `SuccessInverse` (text-success-inverse) -- `WarningDefault` (text-warning-default) -- `WarningInverse` (text-warning-inverse) -- `InfoDefault` (text-info-default) -- `InfoInverse` (text-info-inverse) +```tsx + + + +``` -### `twClassName` +### `color` -Optional prop to add custom `twrnc` class names for additional styling overrides. +The color of the icon. -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | +Available colors: -### Additional ViewProps +- `IconColor.IconDefault` +- `IconColor.IconAlternative` +- `IconColor.IconMuted` +- `IconColor.IconPrimary` +- `IconColor.IconSuccess` +- `IconColor.IconError` +- `IconColor.IconWarning` +- `IconColor.IconInfo` -All additional `ViewProps` are spread onto the underlying SVG component for further customization and accessibility. +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------------------- | +| `IconColor` | No | `IconColor.IconDefault` | -## Usage +```tsx + + +``` -```javascript -import React from 'react'; -import Icon from '@metamask/design-system-react-native/lib/components/Icon'; -import { - IconName, - IconSize, - IconColor, -} from '@metamask/design-system-react-native/lib/components/Icon/Icon.types'; +### `twClassName` -// Basic usage -; +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -// Specify size -; +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -// Change color -; +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -// Add custom Tailwind class names -; +```tsx +import { Icon } from '@metamask/design-system-react-native'; -// Combine multiple props +// Add additional styles ; -``` + name="CheckBold" + twClassName="opacity-70" +> + Semi-transparent Icon + -## Example with All Props - -```javascript +// Override default styles + name="CheckBold" + twClassName="!text-error-100" +> + Override Color + ``` -## Notes +### `style` -- The `Icon` component is designed to be flexible and works seamlessly with `twrnc` for styling. -- When using `twClassName`, ensure the class names are compatible with your Tailwind configuration. -- Custom styles can be applied via the `style` prop, which merges with the styles generated from `twClassName` and other props. +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Importing Types +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -If you need to use the enums for `name`, `color`, or `size`, you can import them as follows: +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); -```javascript -import { - IconSize, - IconName, - IconColor, -} from '@metamask/design-system-react-native'; +export const StyleExample = () => ( + +); ``` -## Accessibility - -- Consider using `accessibilityLabel` and other accessibility props to provide a text equivalent for users of assistive technologies. -- Ensure icons that convey information have accessible labels. - -## Contributing - -When contributing to the `Icon` component, please ensure: - -- All new icons are flatten, exported, and optimized properly. -- Make sure to remove colors from new icons. -- Add new icons to the assets folder. -- Run `yarn workspace @metamask/design-system-react-native ts-node scripts/generate-icons.ts` from root. - ---- +## References -For questions or further assistance, refer to the React Native SVG documentation or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/Text/README.md b/packages/design-system-react-native/src/components/Text/README.md index 3e00f564c..356e3eb2b 100644 --- a/packages/design-system-react-native/src/components/Text/README.md +++ b/packages/design-system-react-native/src/components/Text/README.md @@ -1,18 +1,34 @@ # Text -Text is the used to render text and paragraphs within an interface +Text is used to render text and paragraphs within an interface. + +```tsx +import { Text } from '@metamask/design-system-react-native'; + +Default Text; +``` ## Props +### `children` + +Text content to be displayed. + +| TYPE | REQUIRED | DEFAULT | +| --------------------- | -------- | ----------- | +| `string \| ReactNode` | Yes | `undefined` | + +```tsx +import { Text } from '@metamask/design-system-react-native'; + +Sample text content; +``` + ### `variant` Optional enum to select between typography variants. -| TYPE | REQUIRED | DEFAULT | -| :----------------------------- | :------- | :------------------- | -| [TextVariant](./Text.types.ts) | No | `TextVariant.BodyMd` | - -Available `TextVariant` options: +Available variants: - `TextVariant.DisplayLg` - `TextVariant.DisplayMd` @@ -23,187 +39,122 @@ Available `TextVariant` options: - `TextVariant.BodyMd` - `TextVariant.BodySm` - `TextVariant.BodyXs` -- `TextVariant.PageHeading` -- `TextVariant.SectionHeading` -- `TextVariant.ButtonLabelMd` -- `TextVariant.ButtonLabelLg` -- `TextVariant.AmountDisplayLg` -### `children` - -Text content to be displayed. +| TYPE | REQUIRED | DEFAULT | +| ------------- | -------- | -------------------- | +| `TextVariant` | No | `TextVariant.BodyMd` | -| TYPE | REQUIRED | -| :---------------------- | :------- | -| `string` or `ReactNode` | Yes | +```tsx +Large Heading +Small body text +``` ### `color` Optional prop to set the text color. -| TYPE | REQUIRED | DEFAULT | -| :--------------------------- | :------- | :---------------------- | -| [TextColor](./Text.types.ts) | No | `TextColor.TextDefault` | - -Available `TextColor` options: +Available colors: - `TextColor.TextDefault` - `TextColor.TextAlternative` - `TextColor.TextMuted` -- `TextColor.OverlayInverse` - `TextColor.PrimaryDefault` -- `TextColor.PrimaryInverse` - `TextColor.ErrorDefault` -- `TextColor.ErrorAlternative` -- `TextColor.ErrorInverse` - `TextColor.SuccessDefault` -- `TextColor.SuccessInverse` - `TextColor.WarningDefault` -- `TextColor.WarningInverse` - `TextColor.InfoDefault` -- `TextColor.InfoInverse` -- `TextColor.Transparent` + +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------------------- | +| `TextColor` | No | `TextColor.TextDefault` | + +```tsx +Primary colored text +Error text +``` ### `fontWeight` Optional prop to adjust the font weight. -| TYPE | REQUIRED | DEFAULT | -| :---------------------------- | :------- | :------------------- | -| [FontWeight](./Text.types.ts) | No | `FontWeight.Regular` | +Available font weights: -Available `FontWeight` options: +- `FontWeight.Regular` (Weight 400) +- `FontWeight.Medium` (Weight 500) +- `FontWeight.Bold` (Weight 700) -- `FontWeight.Regular` (Weight `400`) -- `FontWeight.Medium` (Weight `500`) -- `FontWeight.Bold` (Weight `700`) +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | -------------------- | +| `FontWeight` | No | `FontWeight.Regular` | + +```tsx +Bold text +Medium weight text +``` ### `fontStyle` Optional prop to adjust the font style. -| TYPE | REQUIRED | DEFAULT | -| :--------------------------- | :------- | :----------------- | -| [FontStyle](./Text.types.ts) | No | `FontStyle.Normal` | - -Available `FontStyle` options: +Available font styles: - `FontStyle.Normal` - `FontStyle.Italic` +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ------------------ | +| `FontStyle` | No | `FontStyle.Normal` | + +```tsx +Italic text +``` + ### `twClassName` -Optional prop to add custom `twrnc` class names for additional styling. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -## Usage +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -```javascript -import React from 'react'; +```tsx import { Text } from '@metamask/design-system-react-native'; -import { - TextVariant, - TextColor, - FontWeight, - FontStyle, -} from '@metamask/design-system-react-native/lib/components/Text/Text.types'; - -// Basic usage with default props -Sample Text; - -// Using a specific variant -Heading Large Text; - -// Applying a text color -Primary Colored Text; - -// Setting font weight to bold -Bold Text; - -// Setting font style to italic -Italic Text; - -// Combining multiple styling props - - Bold Italic Success Text -; - -// Adding custom Tailwind class names -Underlined Text; - -// Passing additional props to the underlying Text component - - This is a very long text that will be truncated at the end. -; - -// Using custom styles alongside twClassName - - Custom Styled Text -; - -// Nested Text components - - This is a nested text example. -; -``` -## Example with All Props - -```javascript - - This is a bold, italic, underlined, centered text with error color. +// Add additional styles + + Underlined centered text -``` - -## Notes - -- The `Text` component is designed to be flexible and works seamlessly with `twrnc` for styling. -- When using `twClassName`, ensure the class names are compatible with your Tailwind configuration. -- The `variant` prop controls the overall typography, including font size and line height. -- Custom styles can be applied via the `style` prop, which merges with the styles generated from `twClassName` and other props. -## Importing Types - -If you need to use the enums for `variant`, `color`, `fontWeight`, or `fontStyle`, you can import them as follows: - -```javascript -import { - TextVariant, - TextColor, - FontWeight, - FontStyle, -} from '@metamask/design-system-react-native/'; +// Override default styles + + Override Text Color + ``` -## Accessibility +### `style` -- The `Text` component sets `accessibilityRole` to `"text"` by default to enhance accessibility support. -- Ensure that any interactive text elements are wrapped appropriately (e.g., within a `TouchableOpacity`) and have the correct accessibility roles and labels. +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -When contributing to the `Text` component, please ensure: +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); -- All new variants, colors, font weights, or styles are added to the respective enums in `Text.types.ts`. -- Updates to the component maintain consistency with the design system guidelines. -- All changes are accompanied by appropriate tests and documentation updates. +export const StyleExample = () => ( + Custom styled text +); +``` ---- +## References -For any questions or further assistance, please refer to the [React Native Text documentation](https://reactnative.dev/docs/text) or reach out to the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/TextButton/README.md b/packages/design-system-react-native/src/components/TextButton/README.md index b6653b52e..5f823a970 100644 --- a/packages/design-system-react-native/src/components/TextButton/README.md +++ b/packages/design-system-react-native/src/components/TextButton/README.md @@ -1,226 +1,221 @@ # TextButton -`TextButton` is used for text-only button actions or hyperlink without padding or background. +TextButton is used for text-only button actions or hyperlink without padding or background. ---- - -## Props - -### `children` (Required) - -The content to be rendered within the `TextButton`. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | Yes | `N/A` | - ---- - -### `textProps` - -Optional props to be passed to the `Text` component when the `children` is a string. - -| TYPE | REQUIRED | DEFAULT | -| :------------------------------------- | :------- | :--------------------------------------------------------------- | -| `Omit, 'children'>` | No | `{ variant: BodyMd, fontWeight: Medium, color: PrimaryDefault }` | - ---- - -### `isLoading` - -Optional prop that, when `true`, shows a loading spinner. +```tsx +import { TextButton } from '@metamask/design-system-react-native'; -| TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | -| `boolean` | No | `false` | + console.log('Pressed')}>Click me; +``` ---- +## Props -### `loadingText` +### `children` -Optional text to display when the button is in the loading state. +The text content of the TextButton component. | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | -| `string` | No | `"Loading"` | - ---- - -### `spinnerProps` - -Optional props to customize the appearance of the spinner. - -| TYPE | REQUIRED | DEFAULT | -| :---------------------- | :------- | :----------------------- | -| `Partial` | No | `{ color: IconDefault }` | - ---- +| -------- | -------- | ----------- | +| `string` | Yes | `undefined` | -### `startIconName` - -Optional prop to specify an icon to show at the start of the button. - -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | No | `null` | - ---- - -### `startIconProps` - -Optional props to pass additional properties to the start icon. - -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :----------------------------------- | -| `Partial` | No | `{ size: Sm, testID: 'start-icon' }` | - ---- - -### `startAccessory` - -Optional prop for a custom element to show at the start of the button. - -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `ReactNode` | No | `null` | - ---- - -### `endIconName` +```tsx +import { TextButton } from '@metamask/design-system-react-native'; -Optional prop to specify an icon to show at the end of the button. + {}}>Custom button text; +``` -| TYPE | REQUIRED | DEFAULT | -| :--------- | :------- | :------ | -| `IconName` | No | `null` | +### `onPress` ---- +Function to trigger when pressing the button. -### `endIconProps` +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | Yes | `undefined` | -Optional props to pass additional properties to the end icon. +```tsx + console.log('Text button pressed')}> + Press me + +``` -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :--------------------------------- | -| `Partial` | No | `{ size: Sm, testID: 'end-icon' }` | +### `size` ---- +The size of the text button. -### `endAccessory` +Available sizes: -Optional prop for a custom element to show at the end of the button. +- `TextButtonSize.Sm` +- `TextButtonSize.Md` +- `TextButtonSize.Lg` -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :------ | -| `ReactNode` | No | `null` | +| TYPE | REQUIRED | DEFAULT | +| ---------------- | -------- | ----------------------- | +| `TextButtonSize` | No | `TextButtonSize.BodyMd` | ---- +```tsx + {}}> + Small Text Button + + {}}> + Large Text Button + +``` ### `isDisabled` -Optional prop that, when `true`, disables the button. +Whether the text button is disabled. | TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | +| --------- | -------- | ------- | | `boolean` | No | `false` | ---- +```tsx + {}}> + Disabled Text Button + +``` ### `isInverse` -Optional prop to show the inverse state of the button, typically used for buttons on colored backgrounds. +Whether to show the button with inverted colors for use on colored backgrounds. | TYPE | REQUIRED | DEFAULT | -| :-------- | :------- | :------ | +| --------- | -------- | ------- | | `boolean` | No | `false` | ---- - -### `twClassName` - -Optional prop to add `twrnc` overriding class names. - -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `''` | +```tsx + {}}> + Inverse Text Button + +``` ---- +### `startIconName` -### `style` +Optional icon name to display before the text. -Optional prop to control the style. +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | No | `undefined` | -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :------ | -| `StyleProp` | No | `null` | +```tsx + {}}> + Back + +``` ---- +### `endIconName` -## Usage +Optional icon name to display after the text. -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| ---------- | -------- | ----------- | +| `IconName` | No | `undefined` | ```tsx -import React from 'react'; -import TextButton from '@metamask/design-system-react-native'; - - console.log('Pressed!')}>Click Me; + {}}> + Continue + ``` ---- +### `startAccessory` + +Optional custom element to show at the start of the button. -### Button with Icon +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | ----------- | +| `React.ReactNode` | No | `undefined` | ```tsx -Go Back +} onPress={() => {}}> + Custom Start + ``` ---- +### `endAccessory` + +Optional custom element to show at the end of the button. -### Button with Spinner +| TYPE | REQUIRED | DEFAULT | +| ----------------- | -------- | ----------- | +| `React.ReactNode` | No | `undefined` | ```tsx -Loading... +} onPress={() => {}}> + Custom End + ``` ---- +### `textProps` -### Customizing the Spinner +Optional props to be passed to the Text component. + +| TYPE | REQUIRED | DEFAULT | +| -------------------------------------- | -------- | ----------- | +| `Omit, 'children'>` | No | `undefined` | ```tsx {}} > - Please wait + Custom Text Styling ``` ---- +### `twClassName` + +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -### Accessibility +- Add new styles that don't exist in the default component +- Override the component's default styles when needed + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -- Use the `accessibilityLabel` prop to provide meaningful labels for assistive technologies. -- Ensure `children` describes the button's purpose or action. +```tsx +import { TextButton } from '@metamask/design-system-react-native'; ---- +// Add additional styles + {}} + twClassName="underline" +> + Underlined Text Button + -### Notes +// Override default styles + {}} + twClassName="!text-error-100" +> + Override Text Color + +``` -- `TextButton` uses the `Text` component as its base to ensure proper inline rendering with other text elements. -- Custom alignment logic is applied to ensure consistent layout of icons and spinners. -- Use `isLoading` to disable user interactions during a loading state. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}} style={styles.custom}> + Custom Text Button + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/Blockies/README.md b/packages/design-system-react-native/src/components/temp-components/Blockies/README.md index cfaac5176..a6b87db7b 100644 --- a/packages/design-system-react-native/src/components/temp-components/Blockies/README.md +++ b/packages/design-system-react-native/src/components/temp-components/Blockies/README.md @@ -1,114 +1,104 @@ # Blockies -The `Blockies` component generates a unique, consistent, and visually distinct icon based on an Ethereum address. It acts as a wrapper around the `Image` component, using [`toDataUrl`](#) to generate a base64-encoded blocky avatar. +Blockies is used to generate unique, consistent blocky avatars based on Ethereum addresses within an interface. ---- +```tsx +import { Blockies } from '@metamask/design-system-react-native'; + +; +``` ## Props -The `Blockies` component accepts the following props: +### `address` -### `address` (Required) +A string address used as a unique identifier to generate the Blockies avatar. -A string address used as a unique identifier to generate the Blockies avatar. This ensures that the same input always produces the same avatar. +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | Yes | `undefined` | -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | Yes | `N/A` | - ---- +```tsx + +``` -### `size` (Optional) +### `size` -Defines the size of the Blockies avatar in pixels. Defaults to `32`. +The size of the Blockies avatar in pixels. | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | +| -------- | -------- | ------- | | `number` | No | `32` | ---- - -### Other Props - -`Blockies` supports all other props from [`Image`](https://reactnative.dev/docs/image) except `source`, `width`, and `height`. This includes: - -- **`resizeMode`** – Controls how the image is resized within the container. -- **`style`** – Custom styles for the image. -- **`testID`** – Identifier used for testing purposes. -- Any other valid `ImageProps`. +```tsx + +``` ---- +### `scale` -## Usage +The scale factor for the blocky pattern. -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ------- | +| `number` | No | `3` | ```tsx -import React from 'react'; -import Blockies from '@your-library/blockies'; - -const App = () => ; - -export default App; + ``` ---- +### `twClassName` -### Custom Size +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -```tsx -import React from 'react'; -import Blockies from '@your-library/blockies'; +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -const App = () => ; +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -export default App; +```tsx +import { Blockies } from '@metamask/design-system-react-native'; + +// Add additional styles + + Custom Border + + +// Override default styles + + Rounded Avatar + ``` ---- +### `style` -### Applying Custom Styles +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -```tsx -import React from 'react'; -import { StyleSheet } from 'react-native'; -import Blockies from '@your-library/blockies'; +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | +```tsx const styles = StyleSheet.create({ - customBlockies: { + custom: { + marginVertical: 8, + marginHorizontal: 16, borderRadius: 10, - borderWidth: 2, - borderColor: 'blue', }, }); -const App = () => ( - +export const StyleExample = () => ( + ); - -export default App; ``` ---- - -## Notes - -- **Unique Avatar Generation:** - `Blockies` ensures each address generates a unique, consistent avatar using [`toDataUrl`](#). -- **Size Customization:** - The `size` prop allows resizing of the avatar while maintaining its resolution. - -- **Extensibility:** - Any additional `Image` props are forwarded to the underlying component for flexibility. - ---- - -## Contributing - -1. Add tests for any new features or modifications. -2. Update this README to reflect any changes in the API. -3. Follow the project's coding guidelines and best practices. - ---- +## References -For further details, refer to the [React Native documentation](https://reactnative.dev/docs/image). +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/ButtonAnimated/README.md b/packages/design-system-react-native/src/components/temp-components/ButtonAnimated/README.md index c30ba4c8a..47ac6ade8 100644 --- a/packages/design-system-react-native/src/components/temp-components/ButtonAnimated/README.md +++ b/packages/design-system-react-native/src/components/temp-components/ButtonAnimated/README.md @@ -1,59 +1,144 @@ # ButtonAnimated -The `ButtonAnimated` component is a React Native button with scale animation for press interactions. It utilizes `react-native-reanimated` for animations. +ButtonAnimated is used to render animated button elements with scale animations within an interface. + +```tsx +import { ButtonAnimated } from '@metamask/design-system-react-native'; + + console.log('Pressed')}> + Click Me +; +``` ## Props +### `children` + +The content of the ButtonAnimated component. + +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------- | +| `ReactNode` | Yes | `undefined` | + +```tsx +import { ButtonAnimated } from '@metamask/design-system-react-native'; + + {}}>Animated Button Content; +``` + +### `onPress` + +Function to trigger when pressing the button. + +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | Yes | `undefined` | + +```tsx + console.log('Button pressed')}> + Press me + +``` + ### `onPressIn` Callback function triggered when the button is pressed in. -| **Type** | **Required** | **Default** | -| ---------- | ------------ | ----------- | -| `function` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | No | `undefined` | + +```tsx + {}} onPressIn={() => console.log('Pressed in')}> + Button with Press In + +``` ### `onPressOut` Callback function triggered when the button is released. -| **Type** | **Required** | **Default** | -| ---------- | ------------ | ----------- | -| `function` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| ------------ | -------- | ----------- | +| `() => void` | No | `undefined` | + +```tsx + {}} + onPressOut={() => console.log('Pressed out')} +> + Button with Press Out + +``` ### `disabled` -Disables button interactions when set to `true`. +Whether the button is disabled. -| **Type** | **Required** | **Default** | -| --------- | ------------ | ----------- | -| `boolean` | No | `false` | +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | -### `...props` +```tsx + {}} disabled> + Disabled Button + +``` + +### `twClassName` -Additional props passed to the underlying `Pressable` component. +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -## Usage +- Add new styles that don't exist in the default component +- Override the component's default styles when needed + +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import React from 'react'; -import ButtonAnimated from './ButtonAnimated'; +import { ButtonAnimated } from '@metamask/design-system-react-native'; + +// Add additional styles + {}} + twClassName="bg-primary-100" +> + Custom Background + + +// Override default styles + {}} + twClassName="!bg-error-100" +> + Override Background + +``` -const App = () => { - return ( - console.log('Pressed In')} - onPressOut={() => console.log('Pressed Out')} - disabled={false} - > - Click Me - - ); -}; +### `style` -export default App; +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. + +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | + +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + {}} style={styles.custom}> + Custom styled animated button + +); ``` -## Notes +## References -- The `ButtonAnimated` component supports scaling animations on press. -- Ensure to wrap the component in an appropriate layout or container for proper spacing. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/ImageOrSvg/README.md b/packages/design-system-react-native/src/components/temp-components/ImageOrSvg/README.md index cdf89f3d6..1e2b8cbe1 100644 --- a/packages/design-system-react-native/src/components/temp-components/ImageOrSvg/README.md +++ b/packages/design-system-react-native/src/components/temp-components/ImageOrSvg/README.md @@ -1,179 +1,152 @@ # ImageOrSvg -The `ImageOrSvg` component is a flexible image component that supports local and remote images, as well as local and remote SVGs, ensuring proper rendering in React Native applications. +ImageOrSvg is used to render flexible image and SVG elements within an interface. ---- +```tsx +import { ImageOrSvg } from '@metamask/design-system-react-native'; + +; +``` ## Props -### `src` (Required) +### `src` -The source of the image or SVG. It determines whether a local image, a local SVG component, or a remote image/SVG (via URI) is rendered. +The source of the image or SVG to render. -| TYPE | REQUIRED | DEFAULT | -| :------------------------------------------------------ | :------- | :------ | -| `number \| ComponentType \| { uri?: string }` | Yes | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| ------------------------------------------------------- | -------- | ----------- | +| `number \| ComponentType \| { uri?: string }` | Yes | `undefined` | ---- +```tsx + + +``` ### `width` -Optional prop to set the width of the image/SVG. -Accepts numbers (pixels) or string values (like percentages). +The width of the image or SVG. -| TYPE | REQUIRED | DEFAULT | -| :----------------- | :------- | :------ | -| `number \| string` | No | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| ------------------ | -------- | ----------- | +| `number \| string` | No | `undefined` | ---- +```tsx + +``` ### `height` -Optional prop to set the height of the image/SVG. -Accepts numbers (pixels) or string values (like percentages). +The height of the image or SVG. -| TYPE | REQUIRED | DEFAULT | -| :----------------- | :------- | :------ | -| `number \| string` | No | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| ------------------ | -------- | ----------- | +| `number \| string` | No | `undefined` | ---- +```tsx + +``` ### `onImageLoad` -Optional callback triggered when the image has loaded successfully. +Callback triggered when the image has loaded successfully. -| TYPE | REQUIRED | DEFAULT | -| :---------------------------------------------------------- | :------- | :------ | -| `(event: NativeSyntheticEvent) => void` | No | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| ----------------------------------------------------------- | -------- | ----------- | +| `(event: NativeSyntheticEvent) => void` | No | `undefined` | ---- +```tsx + console.log('Image loaded')} +/> +``` ### `onImageError` -Optional callback triggered when there is an error rendering the image. +Callback triggered when there is an error loading the image. -| TYPE | REQUIRED | DEFAULT | -| :---------------------------------------------------------------- | :------- | :------ | -| `(errorEvent: NativeSyntheticEvent) => void` | No | `N/A` | +| TYPE | REQUIRED | DEFAULT | +| ----------------------------------------------------------------- | -------- | ----------- | +| `(errorEvent: NativeSyntheticEvent) => void` | No | `undefined` | ---- +```tsx + console.log('Image error')} +/> +``` ### `onSvgError` -Optional callback triggered when there is an error rendering the SVG. - -| TYPE | REQUIRED | DEFAULT | -| :----------------------- | :------- | :------ | -| `(error: Error) => void` | No | `N/A` | - ---- - -### `style` - -Optional prop for style overrides for the image/SVG container. - -| TYPE | REQUIRED | DEFAULT | -| :---------------------- | :------- | :------ | -| `StyleProp` | No | `null` | - ---- - -### `imageProps` - -Additional props to pass to the `Image` component, excluding the `source` prop (which is handled separately). - -| TYPE | REQUIRED | DEFAULT | -| :--------------------------- | :------- | :------ | -| `Omit` | No | `{}` | - ---- +Callback triggered when there is an error loading the SVG. -### `svgProps` - -Additional props to pass to the `Svg` component, excluding the `uri` prop (which is handled separately). - -| TYPE | REQUIRED | DEFAULT | -| :---------------------- | :------- | :------ | -| `Omit` | No | `{}` | - ---- - -## Usage - -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| ------------------------ | -------- | ----------- | +| `(error: Error) => void` | No | `undefined` | ```tsx -import React from 'react'; -import ImageOrSvg from '@metamask/design-system-react-native'; - ; + src={{ uri: 'https://example.com/image.svg' }} + onSvgError={() => console.log('SVG error')} +/> ``` ---- - -### Local Image - -```tsx -import React from 'react'; -import { ImageOrSvg } from '@metamask/design-system-react-native'; -import localImage from '../assets/image.png'; +### `twClassName` -; -``` +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: ---- +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -### Local SVG +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx -import React from 'react'; import { ImageOrSvg } from '@metamask/design-system-react-native'; -import LocalSvg from '../assets/icon.svg'; - -; -``` ---- - -### Handling Errors +// Add additional styles + + Custom Border + -```tsx +// Override default styles console.log('Image failed to load')} - onSvgError={() => console.log('SVG failed to load')} -/> + src={{ uri: 'https://example.com/image.png' }} + twClassName="!rounded-lg" +> + Rounded Image + ``` ---- - -### Accessibility - -- Use meaningful `alt` descriptions for SVGs and images when possible. -- Ensure proper fallback strategies for failed image/SVG loads. - ---- - -### Notes - -- `ImageOrSvg` detects content type dynamically for remote sources. -- Local and remote images and SVGs are supported without additional dependencies. -- Uses `fetch` to determine if a URI corresponds to an SVG when necessary. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Contributing +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for new features. -2. Update this README for any changes to the API. -3. Follow the design system's coding guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + +); +``` ---- +## References -For questions, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/Jazzicon/README.md b/packages/design-system-react-native/src/components/temp-components/Jazzicon/README.md index ac6c6c032..de2dc85a7 100644 --- a/packages/design-system-react-native/src/components/temp-components/Jazzicon/README.md +++ b/packages/design-system-react-native/src/components/temp-components/Jazzicon/README.md @@ -1,132 +1,114 @@ # Jazzicon -The `Jazzicon` component is a lightweight wrapper around [`react-native-jazzicon`](https://github.com/novinyll/react-native-jazzicon) that provides an easy-to-use interface for rendering unique, visually appealing icons based on a seed or address value. This component is especially useful for representing users, tokens, or any entities where a consistent yet unique icon is desired. +Jazzicon is used to render unique, visually appealing identicon avatars based on seed or address values within an interface. ---- +```tsx +import { Jazzicon } from '@metamask/design-system-react-native'; -## Props +; +``` -The `Jazzicon` component accepts all props provided by [`react-native-jazzicon`](#). The key props include: +## Props -### `size` (Optional) +### `size` -Defines the size of the Jazzicon in pixels. +The size of the Jazzicon in pixels. -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | -| `number` | No | `undefined` | +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ------- | +| `number` | No | `40` | ---- +```tsx + +``` -### `address` (Optional) +### `address` -A string address used as a unique identifier to generate the Jazzicon. This provides a consistent and visually unique icon. +A string address used as a unique identifier to generate the Jazzicon. | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | +| -------- | -------- | ----------- | | `string` | No | `undefined` | ---- +```tsx + +``` -### `seed` (Optional) +### `seed` -A unique numeric value used to generate a consistent and unique icon. If both `address` and `seed` are provided, `address` takes precedence. +A unique numeric value used to generate a consistent and unique icon. | TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :---------- | +| -------- | -------- | ----------- | | `number` | No | `undefined` | ---- - -### `containerStyle` (Optional) - -Allows customization of the container's style using a React Native `StyleProp`. - -| TYPE | REQUIRED | DEFAULT | -| :--------------------- | :------- | :---------- | -| `StyleProp` | No | `undefined` | - ---- - -### Other Props - -`Jazzicon` supports all other properties available in [`react-native-jazzicon`](#), such as: - -- **`testID`** – Identifier used for testing purposes. -- Any additional props will be forwarded to the underlying `RNJazzicon` component. +```tsx + +``` ---- +### `diameter` -## Usage +Alternative prop for size (for compatibility with react-native-jazzicon). -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `number` | No | `undefined` | ```tsx -import React from 'react'; -import Jazzicon from '@your-library/jazzicon'; - -const App = () => ; - -export default App; + ``` ---- +### `twClassName` -### Using an Address +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -```tsx -import React from 'react'; -import Jazzicon from '@your-library/jazzicon'; +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -const App = () => ; +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -export default App; +```tsx +import { Jazzicon } from '@metamask/design-system-react-native'; + +// Add additional styles + + Custom Border + + +// Override default styles + + Rounded Jazzicon + ``` ---- +### `style` -### Customizing the Container Style +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -```tsx -import React from 'react'; -import { StyleSheet } from 'react-native'; -import Jazzicon from '@your-library/jazzicon'; +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | +```tsx const styles = StyleSheet.create({ - container: { + custom: { + marginVertical: 8, + marginHorizontal: 16, borderRadius: 10, - padding: 5, - backgroundColor: 'lightgrey', }, }); -const App = () => ( - -); - -export default App; +export const StyleExample = () => ; ``` ---- - -## Notes - -- **Wrapper Functionality:** - `Jazzicon` is a thin wrapper around [`react-native-jazzicon`](#), ensuring that all props are seamlessly passed through to the underlying component. -- **Key Props:** - The `address` or `seed` prop is essential for generating a unique icon, while the `size` defines its dimensions. The optional `containerStyle` prop provides additional styling. - -- **Extensibility:** - Any prop supported by `react-native-jazzicon` can be applied to `Jazzicon`, making it flexible for various use cases. - ---- - -## Contributing - -1. Add tests for any new features or modifications. -2. Update this README to reflect any changes in the API. -3. Follow the project's coding guidelines and best practices. - ---- +## References -For further details, please refer to the [React Native documentation](https://reactnative.dev/docs) or the [`react-native-jazzicon` documentation](https://github.com/novinyll/react-native-jazzicon). +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/Maskicon/README.md b/packages/design-system-react-native/src/components/temp-components/Maskicon/README.md index 05f45c173..1616a6da9 100644 --- a/packages/design-system-react-native/src/components/temp-components/Maskicon/README.md +++ b/packages/design-system-react-native/src/components/temp-components/Maskicon/README.md @@ -1,140 +1,106 @@ # Maskicon -The `Maskicon` component renders a unique SVG identicon derived from a blockchain address. It supports Ethereum and other address formats (e.g., Solana, Bitcoin), and generates consistent visuals using a hash-based algorithm and a fixed color palette. +Maskicon is used to render unique SVG identicons derived from blockchain addresses within an interface. ---- +```tsx +import { Maskicon } from '@metamask/design-system-react-native'; + +; +``` ## Props -### `address` (Required) +### `address` The blockchain address used as the seed to generate the Maskicon. -| TYPE | REQUIRED | DESCRIPTION | -| -------- | -------- | ----------------------------------------------- | -| `string` | Yes | Blockchain address for generating the identicon | +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | Yes | `undefined` | ---- +```tsx + +``` ### `size` -Optional prop to control the size (width and height) of the Maskicon. +The size (width and height) of the Maskicon. | TYPE | REQUIRED | DEFAULT | | -------- | -------- | ------- | | `number` | No | `32` | ---- - -### Additional Props - -Any other props passed to the component will be forwarded to the underlying `SvgXml` element. - -| TYPE | DESCRIPTION | -| ---------- | -------------------------------- | -| `SvgProps` | Custom styling and accessibility | - ---- - -## Usage - -### Basic Usage - -```tsx -import Maskicon from '@metamask/design-system-react-native'; - -; -``` - ---- - -### Custom Size - ```tsx ``` ---- +### `showBorder` -## Internals +Whether to show a border around the Maskicon. -The Maskicon is generated using the following steps: +| TYPE | REQUIRED | DEFAULT | +| --------- | -------- | ------- | +| `boolean` | No | `false` | -1. **Address Namespace Detection** - - - Detects address type (Ethereum, Solana, Bitcoin, etc.) via the `getCaipNamespaceFromAddress` function. - -2. **Seed Generation** - - - Ethereum addresses generate numeric seeds via `generateSeedEthereum`. - - Other address types generate byte-array seeds via `generateSeedNonEthereum`. - -3. **Visual Hashing** - - - Seed is converted to a string and hashed using `sdbmHash`. - - A consistent color pair is selected from a predefined color palette. - - SVG path shapes are determined by the hash to fill a 2x2 grid. - -4. **Caching** - - - Identicons are cached per `(address:size)` to avoid recomputation. - -5. **Rendering** - - An SVG string is constructed and rendered using `SvgXml`. - ---- +```tsx + +``` -## Color Pair Categories +### `twClassName` -Color pairings are designed to provide variety and distinguishability: +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -- **Neutral Pairs**: Basic contrast like orange on white or purple on black. -- **Tonal Pairs**: Tints and shades of the same hue. -- **Complementary Pairs**: Visually opposite hues like purple and green. +- Add new styles that don't exist in the default component +- Override the component's default styles when needed ---- +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | -## Accessibility +```tsx +import { Maskicon } from '@metamask/design-system-react-native'; + +// Add additional styles + + Custom Border + + +// Override default styles + + Rounded Maskicon + +``` -- The `Maskicon` is rendered via `SvgXml` which supports `accessibilityLabel` and other `SvgProps`. -- Use `accessibilityLabel` if a description is needed for screen readers. +### `style` ---- +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -## Example with Multiple Addresses +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | ```tsx -const addresses = [ - '0x50cA820Ff810F7687E7d0aDb23A830e3ac6032C3', - '0x8AceA3A9748294d1B5C25a08EFE37b756AafDFdd', - '0xEC5CE72f2e18B0017C88F7B12d3308119C5Cf129', -]; - -return ( - - {addresses.map((addr) => ( - - ))} - +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + ); ``` ---- - -## Notes - -- Deterministic identicons: same address always produces the same visual. -- Custom color pairs can be extended by modifying the internal `colorPairs` array. -- The `createMaskiconSVG` function is also exported for standalone usage. - ---- - -## Contributing - -1. Add or update test cases for new logic (e.g., color pair updates). -2. Update this README if the visual generation logic changes. -3. Follow best practices for accessibility when rendering SVGs. - ---- +## References -For more guidance, refer to the [React Native SVG documentation](https://github.com/software-mansion/react-native-svg) or the internal design system usage policies. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/Spinner/README.md b/packages/design-system-react-native/src/components/temp-components/Spinner/README.md index 49b441707..701c5b4a7 100644 --- a/packages/design-system-react-native/src/components/temp-components/Spinner/README.md +++ b/packages/design-system-react-native/src/components/temp-components/Spinner/README.md @@ -1,85 +1,76 @@ # Spinner -The `Spinner` component is a loading indicator designed for React Native applications. It displays a spinning icon, optionally accompanied by text, to indicate a loading state. +Spinner is used to render loading indicators within an interface. -## Props - -### `color` +```tsx +import { Spinner } from '@metamask/design-system-react-native'; -Optional prop that sets the color of the spinner icon using predefined theme colors. +; +``` -| TYPE | REQUIRED | DEFAULT | -| :---------- | :------- | :---------------------- | -| `IconColor` | No | `IconColor.IconDefault` | +## Props -Available `IconColor` options include: +### `color` -- `IconDefault` -- `PrimaryDefault` -- `SuccessDefault` -- `ErrorDefault` -- ...and more, as defined in the `IconColor` enum. +The color of the spinner icon. -### `loadingText` +Available colors: -Optional text to display to the right of the spinner, providing additional context or information about the loading state. +- `IconColor.IconDefault` +- `IconColor.IconPrimary` +- `IconColor.IconSuccess` +- `IconColor.IconError` +- `IconColor.IconWarning` -| TYPE | REQUIRED | DEFAULT | -| :------- | :------- | :------ | -| `string` | No | `null` | +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------------------- | +| `IconColor` | No | `IconColor.IconDefault` | -### `loadingTextProps` +```tsx + +``` -Optional props to customize the appearance of the `loadingText`. These are passed directly to the `Text` component. +### `size` -| TYPE | REQUIRED | DEFAULT | -| :------------------- | :------- | :------ | -| `Partial` | No | `{}` | +The size of the spinner. ---- +Available sizes: -## Usage +- `SpinnerSize.Sm` +- `SpinnerSize.Md` +- `SpinnerSize.Lg` -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| ------------- | -------- | ---------------- | +| `SpinnerSize` | No | `SpinnerSize.Md` | ```tsx -import React from 'react'; -import Spinner from '@metamask/design-system-react-native'; - -// Render a spinner with default settings -; + ``` -### Customizing the Spinner Color +### `loadingText` -```tsx - -``` +Optional text to display next to the spinner. -### Adding Loading Text +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ```tsx ``` -### Customizing the Loading Text +### `loadingTextProps` -```tsx - -``` +Optional props to customize the loading text appearance. -### Combining Props +| TYPE | REQUIRED | DEFAULT | +| -------------------- | -------- | ----------- | +| `Partial` | No | `undefined` | ```tsx ``` ---- +### `twClassName` + +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -## Accessibility +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -- Ensure the `loadingText` prop provides meaningful information about the loading state for users of assistive technologies. -- Use the `loadingTextProps` to set accessibility roles or labels if needed. +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ---- +```tsx +import { Spinner } from '@metamask/design-system-react-native'; -## Notes +// Add additional styles + + Semi-transparent Spinner + -- The `Spinner` component uses `react-native-reanimated` for smooth animations. -- The spinning icon animation is implemented using `useSharedValue` and `useAnimatedStyle`. -- For custom styling of the spinner, use the `Icon` component directly if necessary. +// Override default styles + + Override Color + +``` ---- +### `style` -## Contributing +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -When contributing to the `Spinner` component: +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Ensure any new features or props are accompanied by tests. -2. Update this README file to document the changes. -3. Maintain consistency with the design system's guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ; +``` ---- +## References -For questions or further assistance, refer to the [React Native documentation](https://reactnative.dev/docs) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) diff --git a/packages/design-system-react-native/src/components/temp-components/TextOrChildren/README.md b/packages/design-system-react-native/src/components/temp-components/TextOrChildren/README.md index 87fa542ff..8d331161e 100644 --- a/packages/design-system-react-native/src/components/temp-components/TextOrChildren/README.md +++ b/packages/design-system-react-native/src/components/temp-components/TextOrChildren/README.md @@ -1,87 +1,100 @@ # TextOrChildren -The `TextOrChildren` component is a utility component that provides flexibility to render either a `Text` component when the `children` prop is a string or render the provided child components directly. +TextOrChildren is used to render either text or child components flexibly within an interface. -## Props - -### `children` - -**Required**. Specifies the content to render. If the `children` is a string, it will render as a `Text` component with optional `textProps`. Otherwise, the child components are rendered directly. - -| TYPE | REQUIRED | -| :---------------- | :------- | -| `React.ReactNode` | Yes | - -### `textProps` +```tsx +import { TextOrChildren } from '@metamask/design-system-react-native'; -Optional props to configure the `Text` component when `children` is a string. This prop is ignored if `children` is not a string. +String Content; +``` -| TYPE | REQUIRED | DEFAULT | -| :------------------------------------- | :------- | :------ | -| `Partial>` | No | `{}` | +## Props ---- +### `children` -## Usage +The content to render. If a string, renders as Text component; otherwise renders child components directly. -### Basic Usage +| TYPE | REQUIRED | DEFAULT | +| ----------- | -------- | ----------- | +| `ReactNode` | Yes | `undefined` | ```tsx -import React from 'react'; -import TextOrChildren from '@metamask/design-system-react-native/lib/components/TextOrChildren'; +import { TextOrChildren } from '@metamask/design-system-react-native'; // Render string as Text component -String Content; +String Content // Render nested children directly Nested Content -; + ``` -### With `textProps` +### `textProps` + +Optional props to configure the Text component when children is a string. + +| TYPE | REQUIRED | DEFAULT | +| -------------------------------------- | -------- | ----------- | +| `Partial>` | No | `undefined` | ```tsx Styled Text ``` -### Handling Conditional Rendering - -```tsx - - {condition ? 'This is a string' : } - -``` +### `twClassName` ---- +Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: -## Notes +- Add new styles that don't exist in the default component +- Override the component's default styles when needed -- The `TextOrChildren` component ensures that string content adheres to consistent typography by wrapping it in the `Text` component. -- When using `textProps`, ensure the props are valid for the `Text` component. -- If `children` is not a string, all other props are ignored, and the child components are rendered as-is. +| TYPE | REQUIRED | DEFAULT | +| -------- | -------- | ----------- | +| `string` | No | `undefined` | ---- +```tsx +import { TextOrChildren } from '@metamask/design-system-react-native'; -## Accessibility +// Add additional styles + + Centered Content + -- The `Text` component renders with appropriate accessibility props (e.g., `accessibilityRole="text"`) for string content. -- Ensure any custom child components used with `TextOrChildren` have appropriate accessibility attributes. +// Override default styles + + Override Text Color + +``` ---- +### `style` -## Contributing +Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind. -When contributing to the `TextOrChildren` component: +| TYPE | REQUIRED | DEFAULT | +| ---------------------- | -------- | ----------- | +| `StyleProp` | No | `undefined` | -1. Add tests for any new functionality or props. -2. Update the README file to reflect changes. -3. Maintain consistency with the design system's guidelines. +```tsx +const styles = StyleSheet.create({ + custom: { + marginVertical: 8, + marginHorizontal: 16, + }, +}); + +export const StyleExample = () => ( + Custom styled content +); +``` ---- +## References -For questions or further assistance, refer to the [React Native Text documentation](https://reactnative.dev/docs/text) or contact the maintainers of the design system. +[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)