@utilitywarehouse/hearth-react-native 0.8.1 → 0.9.0

package/src/components/Menu/Menu.docs.mdx

@@ -0,0 +1,158 @@
+import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import { BackToTopButton, ViewFigmaButton } from '../../../docs/components';
+import * as Stories from './Menu.stories';
+
+<Meta title="Components / Menu" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens" />
+
+<BackToTopButton />
+
+# Menu
+
+The `Menu` component provides a bottom sheet modal with a list of actions. It's perfect for contextual menus, action sheets, and option lists. The component uses `BottomSheetModal` under the hood and includes `MenuItem` components that can display icons, text, and support different color schemes.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Features](#features)
+- [Examples](#examples)
+  - [Basic Menu](#basic-menu)
+  - [With Destructive Action](#with-destructive-action)
+  - [Icon on Right](#icon-on-right)
+  - [Without Icons](#without-icons)
+  - [With Disabled Items](#with-disabled-items)
+  - [Without Heading](#without-heading)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { useRef } from 'react';
+import { Menu, MenuItem, MenuTrigger } from '@utilitywarehouse/hearth-react-native';
+import { EditSmallIcon, TrashSmallIcon } from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => {
+  const menuRef = useRef(null);
+
+  return (
+    <>
+      <MenuTrigger onPress={() => menuRef.current?.present()}>
+        <Button>Open Menu</Button>
+      </MenuTrigger>
+
+      <Menu ref={menuRef} heading="Actions">
+        <MenuItem icon={EditSmallIcon} text="Edit" onPress={() => console.log('Edit')} />
+        <MenuItem
+          icon={TrashSmallIcon}
+          text="Delete"
+          colorScheme="destructive"
+          onPress={() => console.log('Delete')}
+        />
+      </Menu>
+    </>
+  );
+};
+```
+
+## Props
+
+### Menu
+
+| Prop               | Type                             | Default | Description                                         |
+| ------------------ | -------------------------------- | ------- | --------------------------------------------------- |
+| `heading`          | `string`                         | -       | Heading text displayed at the top of the menu       |
+| `children`         | `ReactNode`                      | -       | Menu items to display                               |
+| `bottomSheetProps` | `Partial<BottomSheetModalProps>` | -       | Optional bottom sheet modal props for customization |
+
+### MenuItem
+
+| Prop           | Type                                     | Default        | Description                        |
+| -------------- | ---------------------------------------- | -------------- | ---------------------------------- |
+| `icon`         | `ComponentType`                          | -              | Icon component to display          |
+| `iconPosition` | `'left' \| 'right'`                      | `'left'`       | Position of the icon               |
+| `text`         | `string`                                 | -              | Text to display in the menu item   |
+| `colorScheme`  | `'functional' \| 'destructive'`          | `'functional'` | Color scheme for the menu item     |
+| `disabled`     | `boolean`                                | `false`        | Whether the menu item is disabled  |
+| `onPress`      | `(event: GestureResponderEvent) => void` | -              | Callback when menu item is pressed |
+
+### MenuTrigger
+
+| Prop       | Type           | Description                                                         |
+| ---------- | -------------- | ------------------------------------------------------------------- |
+| `children` | `ReactElement` | The child element that triggers the menu (must be a single element) |
+| `onPress`  | `() => void`   | Function that opens the menu                                        |
+
+## Features
+
+### Icon Positioning
+
+Icons can be positioned on either the left or right side of the menu item text using the `iconPosition` prop.
+
+### Color Schemes
+
+Menu items support two color schemes:
+
+- `functional` (default): Uses primary text and icon colors
+- `destructive`: Uses danger/destructive colors for actions like delete
+
+### Disabled State
+
+Menu items can be disabled using the `disabled` prop, which applies reduced opacity and prevents interaction.
+
+### Auto-closing
+
+Menu items automatically close the menu when pressed, making it easy to handle actions without manual menu dismissal.
+
+## Examples
+
+### Basic Menu
+
+A simple menu with icon-based actions:
+
+<Canvas of={Stories.BasicMenu} />
+
+### With Destructive Action
+
+Menu with a destructive action styled differently:
+
+<Canvas of={Stories.WithDestructiveAction} />
+
+### Icon on Right
+
+Menu items with icons positioned on the right side:
+
+<Canvas of={Stories.IconOnRight} />
+
+### Without Icons
+
+Simple text-only menu items:
+
+<Canvas of={Stories.WithoutIcons} />
+
+### With Disabled Items
+
+Menu with some items disabled:
+
+<Canvas of={Stories.WithDisabledItems} />
+
+### Without Heading
+
+Menu without a heading section:
+
+<Canvas of={Stories.WithoutHeading} />
+
+## Accessibility
+
+- Menu items have `accessibilityRole="button"` for proper screen reader support
+- Disabled state is communicated via `accessibilityState`
+- Keyboard navigation is supported on web platforms
+- All interactive elements are properly focusable

package/src/components/Menu/Menu.props.ts

@@ -0,0 +1,24 @@
+import type { BottomSheetModalProps } from '@gorhom/bottom-sheet';
+import type { ReactNode } from 'react';
+
+export interface MenuMethods {
+  present: () => void;
+  dismiss: () => void;
+}
+
+export interface MenuProps {
+  /**
+   * Heading text displayed at the top of the menu
+   */
+  heading?: string;
+  /**
+   * Menu items to display
+   */
+  children: ReactNode;
+  /**
+   * Optional bottom sheet modal props to customise the menu behavior
+   */
+  bottomSheetProps?: Partial<BottomSheetModalProps>;
+}
+
+export default MenuProps;

package/src/components/Menu/Menu.stories.tsx

@@ -0,0 +1,292 @@
+import type { Meta, StoryObj } from '@storybook/react-native';
+import {
+  DownloadSmallIcon,
+  EditSmallIcon,
+  SettingsMediumIcon,
+  ShareSmallIcon,
+  TickSmallIcon,
+  TrashSmallIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { useRef } from 'react';
+import { Platform, View } from 'react-native';
+import { Button } from '../Button';
+import { Menu, MenuItem, MenuTrigger } from './';
+import type { MenuMethods } from './Menu.props';
+
+import { ViewWrap } from '../../../docs/components';
+
+const meta: Meta<typeof Menu> = {
+  title: 'Stories / Menu',
+  component: Menu,
+  parameters: {
+    layout: 'centered',
+    noScroll: true,
+  },
+  argTypes: {},
+  args: {
+    heading: 'Menu Options',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: ({ ...args }) => {
+    const menuRef = useRef<MenuMethods>(null);
+
+    const openMenu = () => {
+      menuRef.current?.present();
+    };
+
+    return (
+      <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : { flex: 1 }}>
+        <ViewWrap>
+          <MenuTrigger onPress={openMenu}>
+            <Button>Open Menu</Button>
+          </MenuTrigger>
+
+          <Menu ref={menuRef} {...args}>
+            <MenuItem
+              icon={EditSmallIcon}
+              text="Edit"
+              onPress={() => console.log('Edit pressed')}
+            />
+            <MenuItem
+              icon={ShareSmallIcon}
+              text="Share"
+              onPress={() => console.log('Share pressed')}
+            />
+            <MenuItem
+              icon={DownloadSmallIcon}
+              text="Download"
+              onPress={() => console.log('Download pressed')}
+            />
+            <MenuItem
+              icon={TrashSmallIcon}
+              text="Delete"
+              colorScheme="destructive"
+              onPress={() => console.log('Delete pressed')}
+            />
+          </Menu>
+        </ViewWrap>
+      </View>
+    );
+  },
+};
+
+export const BasicMenu = () => {
+  const menuRef = useRef<MenuMethods>(null);
+
+  const openMenu = () => {
+    menuRef.current?.present();
+  };
+
+  return (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : { flex: 1 }}>
+      <ViewWrap>
+        <MenuTrigger onPress={openMenu}>
+          <Button>Actions</Button>
+        </MenuTrigger>
+
+        <Menu ref={menuRef} heading="Actions">
+          <MenuItem icon={EditSmallIcon} text="Edit" onPress={() => console.log('Edit pressed')} />
+          <MenuItem
+            icon={ShareSmallIcon}
+            text="Share"
+            onPress={() => console.log('Share pressed')}
+          />
+          <MenuItem
+            icon={DownloadSmallIcon}
+            text="Download"
+            onPress={() => console.log('Download pressed')}
+          />
+        </Menu>
+      </ViewWrap>
+    </View>
+  );
+};
+
+export const WithDestructiveAction = () => {
+  const menuRef = useRef<MenuMethods>(null);
+
+  const openMenu = () => {
+    menuRef.current?.present();
+  };
+
+  return (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+      <ViewWrap>
+        <MenuTrigger onPress={openMenu}>
+          <Button>File Options</Button>
+        </MenuTrigger>
+
+        <Menu ref={menuRef} heading="File Options">
+          <MenuItem
+            icon={EditSmallIcon}
+            text="Rename"
+            onPress={() => console.log('Rename pressed')}
+          />
+          <MenuItem
+            icon={ShareSmallIcon}
+            text="Share"
+            onPress={() => console.log('Share pressed')}
+          />
+          <MenuItem
+            icon={DownloadSmallIcon}
+            text="Download"
+            onPress={() => console.log('Download pressed')}
+          />
+          <MenuItem
+            icon={TrashSmallIcon}
+            text="Delete"
+            colorScheme="destructive"
+            onPress={() => console.log('Delete pressed')}
+          />
+        </Menu>
+      </ViewWrap>
+    </View>
+  );
+};
+
+export const IconOnRight = () => {
+  const menuRef = useRef<MenuMethods>(null);
+
+  const openMenu = () => {
+    menuRef.current?.present();
+  };
+
+  return (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+      <ViewWrap>
+        <MenuTrigger onPress={openMenu}>
+          <Button>Settings</Button>
+        </MenuTrigger>
+
+        <Menu ref={menuRef} heading="Settings">
+          <MenuItem
+            icon={TickSmallIcon}
+            iconPosition="right"
+            text="Enable Notifications"
+            onPress={() => console.log('Toggle notifications')}
+          />
+          <MenuItem
+            icon={TickSmallIcon}
+            iconPosition="right"
+            text="Dark Mode"
+            onPress={() => console.log('Toggle dark mode')}
+          />
+          <MenuItem
+            icon={SettingsMediumIcon}
+            iconPosition="right"
+            text="Advanced Settings"
+            onPress={() => console.log('Open advanced settings')}
+          />
+        </Menu>
+      </ViewWrap>
+    </View>
+  );
+};
+
+export const WithoutIcons = () => {
+  const menuRef = useRef<MenuMethods>(null);
+
+  const openMenu = () => {
+    menuRef.current?.present();
+  };
+
+  return (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+      <ViewWrap>
+        <MenuTrigger onPress={openMenu}>
+          <Button>Sort By</Button>
+        </MenuTrigger>
+
+        <Menu ref={menuRef} heading="Sort By">
+          <MenuItem text="Name" onPress={() => console.log('Sort by name')} />
+          <MenuItem text="Date" onPress={() => console.log('Sort by date')} />
+          <MenuItem text="Size" onPress={() => console.log('Sort by size')} />
+          <MenuItem text="Type" onPress={() => console.log('Sort by type')} />
+        </Menu>
+      </ViewWrap>
+    </View>
+  );
+};
+
+export const WithDisabledItems = () => {
+  const menuRef = useRef<MenuMethods>(null);
+
+  const openMenu = () => {
+    menuRef.current?.present();
+  };
+
+  return (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+      <ViewWrap>
+        <MenuTrigger onPress={openMenu}>
+          <Button>Document Actions</Button>
+        </MenuTrigger>
+
+        <Menu ref={menuRef} heading="Document Actions">
+          <MenuItem icon={EditSmallIcon} text="Edit" onPress={() => console.log('Edit pressed')} />
+          <MenuItem
+            icon={ShareSmallIcon}
+            text="Share"
+            disabled
+            onPress={() => console.log('Share pressed')}
+          />
+          <MenuItem
+            icon={DownloadSmallIcon}
+            text="Download"
+            disabled
+            onPress={() => console.log('Download pressed')}
+          />
+          <MenuItem
+            icon={TrashSmallIcon}
+            text="Delete"
+            colorScheme="destructive"
+            onPress={() => console.log('Delete pressed')}
+          />
+        </Menu>
+      </ViewWrap>
+    </View>
+  );
+};
+
+export const WithoutHeading = () => {
+  const menuRef = useRef<MenuMethods>(null);
+
+  const openMenu = () => {
+    menuRef.current?.present();
+  };
+
+  return (
+    <View style={Platform.OS === 'web' ? { width: 400, height: 400 } : {}}>
+      <ViewWrap>
+        <MenuTrigger onPress={openMenu}>
+          <Button>Quick Actions</Button>
+        </MenuTrigger>
+
+        <Menu ref={menuRef}>
+          <MenuItem icon={EditSmallIcon} text="Edit" onPress={() => console.log('Edit pressed')} />
+          <MenuItem
+            icon={ShareSmallIcon}
+            text="Share"
+            onPress={() => console.log('Share pressed')}
+          />
+          <MenuItem
+            icon={DownloadSmallIcon}
+            text="Download"
+            onPress={() => console.log('Download pressed')}
+          />
+          <MenuItem
+            icon={TrashSmallIcon}
+            text="Delete"
+            colorScheme="destructive"
+            onPress={() => console.log('Delete pressed')}
+          />
+        </Menu>
+      </ViewWrap>
+    </View>
+  );
+};

package/src/components/Menu/Menu.tsx

@@ -0,0 +1,54 @@
+import { forwardRef, useCallback, useImperativeHandle, useMemo, useRef } from 'react';
+import { StyleSheet } from 'react-native-unistyles';
+import { BodyText } from '../BodyText';
+import { BottomSheetModal, BottomSheetProps, BottomSheetScrollView } from '../BottomSheet';
+import { MenuContext } from './Menu.context';
+import type MenuProps from './Menu.props';
+import type { MenuMethods } from './Menu.props';
+
+const Menu = forwardRef<MenuMethods, MenuProps>(({ heading, children, bottomSheetProps }, ref) => {
+  const bottomSheetModalRef = useRef<BottomSheetModal>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      present: () => bottomSheetModalRef.current?.present(),
+      dismiss: () => bottomSheetModalRef.current?.dismiss(),
+    }),
+    []
+  );
+
+  const handleClose = useCallback(() => {
+    bottomSheetModalRef.current?.dismiss();
+  }, []);
+
+  const contextValue = useMemo(() => ({ close: handleClose }), [handleClose]);
+
+  return (
+    <BottomSheetModal
+      ref={bottomSheetModalRef}
+      {...(bottomSheetProps as Partial<BottomSheetProps>)}
+    >
+      <BottomSheetScrollView contentContainerStyle={styles.container}>
+        <MenuContext.Provider value={contextValue}>
+          {heading && (
+            <BodyText size="md" weight="semibold">
+              {heading}
+            </BodyText>
+          )}
+          {children}
+        </MenuContext.Provider>
+      </BottomSheetScrollView>
+    </BottomSheetModal>
+  );
+});
+
+Menu.displayName = 'Menu';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    gap: theme.components.bottomSheet.gap,
+  },
+}));
+
+export default Menu;

package/src/components/Menu/MenuItem.props.ts

@@ -0,0 +1,29 @@
+import type { ComponentType } from 'react';
+import type { PressableProps } from 'react-native';
+
+export interface MenuItemProps extends Omit<PressableProps, 'children'> {
+  /**
+   * Icon component to display
+   */
+  icon?: ComponentType;
+  /**
+   * Position of the icon
+   * @default 'left'
+   */
+  iconPosition?: 'left' | 'right';
+  /**
+   * Text to display in the menu item
+   */
+  text: string;
+  /**
+   * Color scheme for the menu item
+   * @default 'functional'
+   */
+  colorScheme?: 'functional' | 'destructive';
+  /**
+   * Whether the menu item is disabled
+   */
+  disabled?: boolean;
+}
+
+export default MenuItemProps;

package/src/components/Menu/MenuItem.tsx

@@ -0,0 +1,145 @@
+import { createPressable } from '@gluestack-ui/pressable';
+import { Pressable } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { BodyText } from '../BodyText';
+import { Icon } from '../Icon';
+import { useMenuContext } from './Menu.context';
+import type MenuItemProps from './MenuItem.props';
+
+const MenuItemRoot = ({
+  icon,
+  iconPosition = 'left',
+  text,
+  colorScheme = 'functional',
+  disabled = false,
+  onPress,
+  states = {},
+  ...props
+}: MenuItemProps & { states?: { active?: boolean; disabled?: boolean } }) => {
+  const { active } = states;
+  const { close } = useMenuContext();
+
+  styles.useVariants({ colorScheme, disabled, iconPosition, active });
+
+  const handlePress = (event: any) => {
+    if (disabled) return;
+    onPress?.(event);
+    close();
+  };
+
+  return (
+    <Pressable
+      {...props}
+      onPress={handlePress}
+      disabled={disabled}
+      style={styles.container}
+      accessibilityRole="button"
+      accessibilityState={{ disabled }}
+    >
+      {!!icon && <Icon as={icon} style={styles.icon} />}
+      <BodyText size="lg" style={styles.text}>
+        {text}
+      </BodyText>
+    </Pressable>
+  );
+};
+
+const MenuItem = createPressable({ Root: MenuItemRoot });
+
+MenuItem.displayName = 'MenuItem';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: theme.components.menu.item.padding,
+    paddingHorizontal: theme.components.menu.mobile.item.padding,
+    gap: theme.components.menu.item.gap,
+    borderRadius: theme.components.menu.item.borderRadius,
+    variants: {
+      active: {
+        true: {
+          backgroundColor: theme.color.interactive.functional.surface.subtle.active,
+        },
+      },
+      disabled: {
+        true: {
+          opacity: theme.opacity.disabled,
+          cursor: 'auto',
+        },
+        false: {
+          _web: {
+            _hover: {
+              backgroundColor: theme.color.interactive.functional.surface.subtle.hover,
+            },
+            _active: {
+              backgroundColor: theme.color.interactive.functional.surface.subtle.active,
+            },
+          },
+        },
+      },
+      iconPosition: {
+        left: {
+          flexDirection: 'row',
+        },
+        right: {
+          flexDirection: 'row-reverse',
+        },
+      },
+      colorScheme: {
+        functional: {},
+        destructive: {},
+      },
+    },
+    compoundVariants: [
+      {
+        colorScheme: 'destructive',
+        active: true,
+        styles: {
+          backgroundColor: theme.color.interactive.destructive.surface.subtle.active,
+        },
+      },
+      {
+        colorScheme: 'destructive',
+        disabled: false,
+        styles: {
+          _web: {
+            _hover: {
+              backgroundColor: theme.color.interactive.destructive.surface.subtle.hover,
+            },
+            _active: {
+              backgroundColor: theme.color.interactive.destructive.surface.subtle.active,
+            },
+          },
+        },
+      },
+    ],
+  },
+  text: {
+    flex: 1,
+    variants: {
+      colorScheme: {
+        functional: {
+          color: theme.color.text.primary,
+        },
+        destructive: {
+          color: theme.color.interactive.destructive.foreground.subtle,
+        },
+      },
+    },
+  },
+  icon: {
+    variants: {
+      colorScheme: {
+        functional: {
+          color: theme.color.icon.primary,
+        },
+        destructive: {
+          color: theme.color.interactive.destructive.foreground.subtle,
+        },
+      },
+    },
+  },
+}));
+
+export default MenuItem;