@limonify/zest-ui 0.1.0

package/src/internals/useTransitionStatus.ts

@@ -0,0 +1,93 @@
+'use client';
+import * as React from 'react';
+import { useIsoLayoutEffect } from '../hooks/useIsoLayoutEffect';
+import { AnimationFrame } from '../hooks/useAnimationFrame';
+
+export type TransitionStatus = 'starting' | 'ending' | 'idle' | undefined;
+
+/**
+ * Provides a status string for animations.
+ *
+ * On the web this drives CSS transitions. In React Native there is no CSS, so
+ * components surface `transitionStatus` on their state object and the consumer
+ * drives an `Animated` value from it.
+ *
+ * @param open - a boolean that determines if the element is open.
+ * @param enableIdleState - a boolean that enables the `'idle'` state between `'starting'` and `'ending'`
+ * @param deferEndingState - defers the `'ending'` state by a frame.
+ */
+export function useTransitionStatus(
+  open: boolean,
+  enableIdleState: boolean = false,
+  deferEndingState: boolean = false,
+) {
+  const [transitionStatus, setTransitionStatus] = React.useState<TransitionStatus>(
+    open && enableIdleState ? 'idle' : undefined,
+  );
+  const [mounted, setMounted] = React.useState(open);
+
+  if (open && !mounted) {
+    setMounted(true);
+    setTransitionStatus('starting');
+  }
+
+  if (!open && mounted && transitionStatus !== 'ending' && !deferEndingState) {
+    setTransitionStatus('ending');
+  }
+
+  if (!open && !mounted && transitionStatus === 'ending') {
+    setTransitionStatus(undefined);
+  }
+
+  useIsoLayoutEffect(() => {
+    if (!open && mounted && transitionStatus !== 'ending' && deferEndingState) {
+      const frame = AnimationFrame.request(() => {
+        setTransitionStatus('ending');
+      });
+
+      return () => {
+        AnimationFrame.cancel(frame);
+      };
+    }
+
+    return undefined;
+  }, [open, mounted, transitionStatus, deferEndingState]);
+
+  useIsoLayoutEffect(() => {
+    if (!open || enableIdleState) {
+      return undefined;
+    }
+
+    const frame = AnimationFrame.request(() => {
+      setTransitionStatus(undefined);
+    });
+
+    return () => {
+      AnimationFrame.cancel(frame);
+    };
+  }, [enableIdleState, open]);
+
+  useIsoLayoutEffect(() => {
+    if (!open || !enableIdleState) {
+      return undefined;
+    }
+
+    if (open && mounted && transitionStatus !== 'idle') {
+      setTransitionStatus('starting');
+    }
+
+    const frame = AnimationFrame.request(() => {
+      setTransitionStatus('idle');
+    });
+
+    return () => {
+      AnimationFrame.cancel(frame);
+    };
+  }, [enableIdleState, open, mounted, transitionStatus]);
+
+  return {
+    mounted,
+    setMounted,
+    transitionStatus,
+  };
+}

package/src/menu/arrow/MenuArrow.tsx

@@ -0,0 +1,45 @@
+'use client';
+import type * as React from 'react';
+import { View } from 'react-native';
+import { useMenuRootContext } from '../root/MenuRootContext';
+import { useMenuPositionerContext } from '../positioner/MenuPositionerContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import type { Align, Side } from '../../utils/useAnchorPositioning';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * Displays an element positioned against the menu anchor.
+ * Renders a `<View>`.
+ */
+export function MenuArrow(componentProps: MenuArrow.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const store = useMenuRootContext();
+  const { side, align, arrowRef, arrowStyles } = useMenuPositionerContext();
+
+  const open = store.useState('open');
+
+  const mergedRef = useMergedRefs(ref, arrowRef as React.Ref<unknown>);
+
+  const state: MenuArrowState = { open, side, align };
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref: mergedRef,
+    props: [{ style: { position: 'absolute' as const, ...arrowStyles } }, elementProps],
+  });
+}
+
+export interface MenuArrowState {
+  open: boolean;
+  side: Side;
+  align: Align;
+}
+
+export interface MenuArrowProps extends ZestUIComponentProps<typeof View, MenuArrowState> {}
+
+export namespace MenuArrow {
+  export type State = MenuArrowState;
+  export type Props = MenuArrowProps;
+}

package/src/menu/backdrop/MenuBackdrop.tsx

@@ -0,0 +1,51 @@
+'use client';
+import { Pressable, StyleSheet, type GestureResponderEvent } from 'react-native';
+import { useMenuRootContext } from '../root/MenuRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A backdrop for the menu, and the surface that dismisses it.
+ * Renders a `<Pressable>`.
+ */
+export function MenuBackdrop(componentProps: MenuBackdrop.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const store = useMenuRootContext();
+  const open = store.useState('open');
+  const disablePointerDismissal = store.useState('disablePointerDismissal');
+
+  const state: MenuBackdropState = { open };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        style: StyleSheet.absoluteFill,
+        onPress(event: GestureResponderEvent) {
+          if (disablePointerDismissal) {
+            return;
+          }
+
+          store.setOpen(false, createChangeEventDetails(REASONS.outsidePress, event));
+        },
+      },
+      elementProps,
+    ],
+  });
+}
+
+export interface MenuBackdropState {
+  open: boolean;
+}
+
+export interface MenuBackdropProps
+  extends ZestUIComponentProps<typeof Pressable, MenuBackdropState> {}
+
+export namespace MenuBackdrop {
+  export type State = MenuBackdropState;
+  export type Props = MenuBackdropProps;
+}

package/src/menu/checkbox-item/MenuCheckboxItem.tsx

@@ -0,0 +1,175 @@
+'use client';
+import * as React from 'react';
+import { Pressable, type GestureResponderEvent } from 'react-native';
+import { useMenuRootContext } from '../root/MenuRootContext';
+import { useMenuSubmenuRootContext } from '../submenu-root/MenuSubmenuRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import { useCompositeListItem } from '../../internals/composite/list/useCompositeListItem';
+import { useControlled } from '../../hooks/useControlled';
+import type { ZestUIComponentProps } from '../../types';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import { MenuCheckboxItemContext } from './MenuCheckboxItemContext';
+
+/**
+ * A menu item that toggles a setting on and off.
+ * Renders a `<Pressable>`.
+ *
+ * Unlike `Menu.Item`, `closeOnPress` defaults to `false`: ticking a box is
+ * usually not the end of the interaction.
+ */
+export function MenuCheckboxItem(componentProps: MenuCheckboxItem.Props) {
+  const {
+    checked: checkedProp,
+    className,
+    closeOnClick: closeOnClickProp,
+    closeOnPress: closeOnPressProp,
+    defaultChecked = false,
+    disabled = false,
+    onCheckedChange,
+    onPress: onPressProp,
+    render,
+    style,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  // `closeOnPress` is the React Native name; `closeOnPress` is a deprecated
+  // alias kept for Base UI parity.
+  const closeOnPress = closeOnPressProp ?? closeOnClickProp ?? false;
+
+  const store = useMenuRootContext();
+  const submenuRootContext = useMenuSubmenuRootContext();
+
+  const { index, onLayout } = useCompositeListItem();
+
+  const [checked, setCheckedState] = useControlled<boolean>({
+    controlled: checkedProp,
+    default: defaultChecked,
+    name: 'MenuCheckboxItem',
+    state: 'checked',
+  });
+
+  const [pressed, setPressed] = React.useState(false);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const state: MenuCheckboxItemState = { checked, disabled, pressed, index };
+
+  const element = useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        onLayout,
+        accessibilityRole: 'menuitem' as const,
+        accessibilityState: { checked, disabled: disabled || undefined },
+        'aria-checked': checked,
+        onPress(event: GestureResponderEvent) {
+          if (disabled) {
+            return;
+          }
+
+          const nextChecked = !checked;
+          const eventDetails = createChangeEventDetails(REASONS.itemPress, event);
+
+          onCheckedChange?.(nextChecked, eventDetails);
+
+          if (eventDetails.isCanceled) {
+            return;
+          }
+
+          setCheckedState(nextChecked);
+          onPressProp?.(event);
+
+          if (closeOnPress) {
+            store.setOpen(false, createChangeEventDetails(REASONS.itemPress, event));
+            submenuRootContext?.closeAncestors(REASONS.itemPress, event);
+          }
+        },
+        onPressIn() {
+          setPressed(true);
+        },
+        onPressOut() {
+          setPressed(false);
+        },
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+
+  return (
+    <MenuCheckboxItemContext.Provider value={state}>{element}</MenuCheckboxItemContext.Provider>
+  );
+}
+
+export interface MenuCheckboxItemState {
+  /**
+   * Whether the checkbox item is currently ticked.
+   */
+  checked: boolean;
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the item is currently pressed.
+   */
+  pressed: boolean;
+  /**
+   * The item's index in the menu.
+   */
+  index: number;
+}
+
+export interface MenuCheckboxItemProps
+  extends ZestUIComponentProps<typeof Pressable, MenuCheckboxItemState> {
+  /**
+   * Whether the checkbox item is currently ticked.
+   *
+   * To render an uncontrolled checkbox item, use the `defaultChecked` prop instead.
+   */
+  checked?: boolean | undefined;
+  /**
+   * Whether the checkbox item is initially ticked.
+   *
+   * To render a controlled checkbox item, use the `checked` prop instead.
+   * @default false
+   */
+  defaultChecked?: boolean | undefined;
+  /**
+   * Event handler called when the checkbox item is ticked or unticked.
+   */
+  onCheckedChange?:
+    | ((checked: boolean, eventDetails: MenuCheckboxItem.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Whether to close the menu when the item is pressed.
+   * @default false
+   */
+  closeOnPress?: boolean | undefined;
+  /**
+   * @deprecated Use `closeOnPress`. Kept as an alias for Base UI parity.
+   */
+  closeOnClick?: boolean | undefined;
+}
+
+export type MenuCheckboxItemChangeEventReason = typeof REASONS.itemPress | typeof REASONS.none;
+
+export type MenuCheckboxItemChangeEventDetails =
+  ZestChangeEventDetails<MenuCheckboxItemChangeEventReason>;
+
+export namespace MenuCheckboxItem {
+  export type State = MenuCheckboxItemState;
+  export type Props = MenuCheckboxItemProps;
+  export type ChangeEventReason = MenuCheckboxItemChangeEventReason;
+  export type ChangeEventDetails = MenuCheckboxItemChangeEventDetails;
+}

package/src/menu/checkbox-item/MenuCheckboxItemContext.ts

@@ -0,0 +1,18 @@
+'use client';
+import * as React from 'react';
+import type { MenuCheckboxItemState } from './MenuCheckboxItem';
+
+export const MenuCheckboxItemContext = React.createContext<MenuCheckboxItemState | undefined>(
+  undefined,
+);
+
+export function useMenuCheckboxItemContext() {
+  const context = React.useContext(MenuCheckboxItemContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: MenuCheckboxItemContext is missing. Menu.CheckboxItemIndicator must be placed within <Menu.CheckboxItem>.',
+    );
+  }
+
+  return context;
+}

package/src/menu/checkbox-item-indicator/MenuCheckboxItemIndicator.tsx

@@ -0,0 +1,39 @@
+'use client';
+import { View } from 'react-native';
+import { useMenuCheckboxItemContext } from '../checkbox-item/MenuCheckboxItemContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { MenuCheckboxItemState } from '../checkbox-item/MenuCheckboxItem';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * Indicates whether the checkbox item is ticked.
+ * Renders a `<View>`.
+ */
+export function MenuCheckboxItemIndicator(componentProps: MenuCheckboxItemIndicator.Props) {
+  const { render, className, style, keepMounted = false, ref, ...elementProps } = componentProps;
+
+  const state = useMenuCheckboxItemContext();
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: elementProps,
+    enabled: keepMounted || state.checked,
+  });
+}
+
+export interface MenuCheckboxItemIndicatorState extends MenuCheckboxItemState {}
+
+export interface MenuCheckboxItemIndicatorProps
+  extends ZestUIComponentProps<typeof View, MenuCheckboxItemIndicatorState> {
+  /**
+   * Whether to keep the element mounted when the checkbox item is not ticked.
+   * @default false
+   */
+  keepMounted?: boolean | undefined;
+}
+
+export namespace MenuCheckboxItemIndicator {
+  export type State = MenuCheckboxItemIndicatorState;
+  export type Props = MenuCheckboxItemIndicatorProps;
+}

package/src/menu/group/MenuGroup.tsx

@@ -0,0 +1,45 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useId } from '../../hooks/useId';
+import type { ZestUIComponentProps } from '../../types';
+import { MenuGroupContext } from './MenuGroupContext';
+
+/**
+ * Groups related menu items with the corresponding label.
+ * Renders a `<View>`.
+ */
+export function MenuGroup(componentProps: MenuGroup.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const labelId = useId();
+
+  const contextValue: MenuGroupContext = React.useMemo(() => ({ labelId }), [labelId]);
+
+  const state: MenuGroupState = {};
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        role: 'group' as const,
+        accessibilityLabelledBy: labelId,
+        'aria-labelledby': labelId,
+      },
+      elementProps,
+    ],
+  });
+
+  return <MenuGroupContext.Provider value={contextValue}>{element}</MenuGroupContext.Provider>;
+}
+
+export interface MenuGroupState {}
+
+export interface MenuGroupProps extends ZestUIComponentProps<typeof View, MenuGroupState> {}
+
+export namespace MenuGroup {
+  export type State = MenuGroupState;
+  export type Props = MenuGroupProps;
+}

package/src/menu/group/MenuGroupContext.ts

@@ -0,0 +1,22 @@
+'use client';
+import * as React from 'react';
+
+export interface MenuGroupContext {
+  /**
+   * The id the group is labelled by; `Menu.GroupLabel` renders it.
+   */
+  labelId: string | undefined;
+}
+
+export const MenuGroupContext = React.createContext<MenuGroupContext | undefined>(undefined);
+
+export function useMenuGroupContext() {
+  const context = React.useContext(MenuGroupContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: MenuGroupContext is missing. <Menu.GroupLabel> must be placed within <Menu.Group>.',
+    );
+  }
+
+  return context;
+}

package/src/menu/group-label/MenuGroupLabel.tsx

@@ -0,0 +1,33 @@
+'use client';
+import { Text } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useMenuGroupContext } from '../group/MenuGroupContext';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * An accessible label that is automatically associated with its parent group.
+ * Renders a `<Text>`.
+ */
+export function MenuGroupLabel(componentProps: MenuGroupLabel.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const { labelId } = useMenuGroupContext();
+
+  const state: MenuGroupLabelState = {};
+
+  return useRenderElement(Text, componentProps, {
+    state,
+    ref,
+    props: [{ nativeID: labelId, role: 'heading' as const }, elementProps],
+  });
+}
+
+export interface MenuGroupLabelState {}
+
+export interface MenuGroupLabelProps
+  extends ZestUIComponentProps<typeof Text, MenuGroupLabelState> {}
+
+export namespace MenuGroupLabel {
+  export type State = MenuGroupLabelState;
+  export type Props = MenuGroupLabelProps;
+}

package/src/menu/index.parts.ts

@@ -0,0 +1,20 @@
+export { MenuRoot as Root } from './root/MenuRoot';
+export { createMenuHandle as createHandle, MenuHandle as Handle } from './store/MenuHandle';
+export { MenuTrigger as Trigger } from './trigger/MenuTrigger';
+export { MenuPortal as Portal } from './portal/MenuPortal';
+export { MenuBackdrop as Backdrop } from './backdrop/MenuBackdrop';
+export { MenuPositioner as Positioner } from './positioner/MenuPositioner';
+export { MenuPopup as Popup } from './popup/MenuPopup';
+export { MenuArrow as Arrow } from './arrow/MenuArrow';
+export { MenuItem as Item } from './item/MenuItem';
+export { MenuLinkItem as LinkItem } from './link-item/MenuLinkItem';
+export { MenuCheckboxItem as CheckboxItem } from './checkbox-item/MenuCheckboxItem';
+export { MenuCheckboxItemIndicator as CheckboxItemIndicator } from './checkbox-item-indicator/MenuCheckboxItemIndicator';
+export { MenuRadioGroup as RadioGroup } from './radio-group/MenuRadioGroup';
+export { MenuRadioItem as RadioItem } from './radio-item/MenuRadioItem';
+export { MenuRadioItemIndicator as RadioItemIndicator } from './radio-item-indicator/MenuRadioItemIndicator';
+export { MenuGroup as Group } from './group/MenuGroup';
+export { MenuGroupLabel as GroupLabel } from './group-label/MenuGroupLabel';
+export { MenuSubmenuRoot as SubmenuRoot } from './submenu-root/MenuSubmenuRoot';
+export { MenuSubmenuTrigger as SubmenuTrigger } from './submenu-trigger/MenuSubmenuTrigger';
+export { Separator } from '../separator/Separator';

package/src/menu/index.ts

@@ -0,0 +1,24 @@
+export * as Menu from './index.parts';
+
+export type * from './root/MenuRoot';
+export { createMenuHandle, MenuHandle } from './store/MenuHandle';
+export type * from './trigger/MenuTrigger';
+export type * from './portal/MenuPortal';
+export type * from './backdrop/MenuBackdrop';
+export type * from './positioner/MenuPositioner';
+export type * from './popup/MenuPopup';
+export type * from './arrow/MenuArrow';
+export type * from './item/MenuItem';
+export type * from './link-item/MenuLinkItem';
+export type * from './checkbox-item/MenuCheckboxItem';
+export type * from './checkbox-item-indicator/MenuCheckboxItemIndicator';
+export type * from './radio-group/MenuRadioGroup';
+export type * from './radio-item/MenuRadioItem';
+export type * from './radio-item-indicator/MenuRadioItemIndicator';
+export { useMenuRadioGroupContext } from './radio-group/MenuRadioGroupContext';
+export type * from './group/MenuGroup';
+export type * from './group-label/MenuGroupLabel';
+export type * from './submenu-root/MenuSubmenuRoot';
+export type * from './submenu-trigger/MenuSubmenuTrigger';
+export { useMenuSubmenuRootContext } from './submenu-root/MenuSubmenuRootContext';
+export { useMenuRootContext } from './root/MenuRootContext';

package/src/menu/item/MenuItem.tsx

@@ -0,0 +1,118 @@
+'use client';
+import * as React from 'react';
+import { Pressable, type GestureResponderEvent } from 'react-native';
+import { useMenuRootContext } from '../root/MenuRootContext';
+import { useMenuSubmenuRootContext } from '../submenu-root/MenuSubmenuRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import { useCompositeListItem } from '../../internals/composite/list/useCompositeListItem';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * An individual interactive item in the menu.
+ * Renders a `<Pressable>`.
+ *
+ * Upstream exposes a `highlighted` state driven by roving focus. There is no
+ * keyboard to rove with on React Native, so the state here is `pressed`.
+ */
+export function MenuItem(componentProps: MenuItem.Props) {
+  const {
+    className,
+    closeOnClick: closeOnClickProp,
+    closeOnPress: closeOnPressProp,
+    disabled = false,
+    onPress: onPressProp,
+    render,
+    style,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  // `closeOnPress` is the React Native name; `closeOnPress` is a deprecated
+  // alias kept for Base UI parity.
+  const closeOnPress = closeOnPressProp ?? closeOnClickProp ?? true;
+
+  const store = useMenuRootContext();
+  const submenuRootContext = useMenuSubmenuRootContext();
+
+  const { index, onLayout } = useCompositeListItem();
+
+  const [pressed, setPressed] = React.useState(false);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const state: MenuItemState = { disabled, pressed, index };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        onLayout,
+        accessibilityRole: 'menuitem' as const,
+        accessibilityState: { disabled: disabled || undefined },
+        onPress(event: GestureResponderEvent) {
+          if (disabled) {
+            return;
+          }
+
+          onPressProp?.(event);
+
+          if (closeOnPress) {
+            store.setOpen(false, createChangeEventDetails(REASONS.itemPress, event));
+            // Choosing an item dismisses the whole menu, not just the submenu it
+            // happens to sit in.
+            submenuRootContext?.closeAncestors(REASONS.itemPress, event);
+          }
+        },
+        onPressIn() {
+          setPressed(true);
+        },
+        onPressOut() {
+          setPressed(false);
+        },
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+}
+
+export interface MenuItemState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the item is currently pressed.
+   */
+  pressed: boolean;
+  /**
+   * The item's index in the menu, in visual order.
+   */
+  index: number;
+}
+
+export interface MenuItemProps extends ZestUIComponentProps<typeof Pressable, MenuItemState> {
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Whether to close the menu when the item is pressed.
+   * @default true
+   */
+  closeOnPress?: boolean | undefined;
+  /**
+   * @deprecated Use `closeOnPress`. Kept as an alias for Base UI parity.
+   */
+  closeOnClick?: boolean | undefined;
+}
+
+export namespace MenuItem {
+  export type State = MenuItemState;
+  export type Props = MenuItemProps;
+}