@yahoo/uds 3.58.2-beta.1 → 3.59.0-beta.1

package/src/components/client/Menu/Menu.Content.tsx

@@ -0,0 +1,391 @@
+import type {
+  MenuProps as AriakitMenuProps,
+  MenuProviderProps as AriakitMenuProviderProps,
+} from '@ariakit/react/menu';
+import { Menu as AriakitMenu, useMenuContext } from '@ariakit/react/menu';
+import { useStoreState } from '@ariakit/react-core/utils/store';
+import { spacingMap } from '@yahoo/uds/fixtures';
+import type { SpacingAlias } from '@yahoo/uds/tokens';
+import { AnimatePresence, m } from 'motion/react';
+import { forwardRef, useEffect, useMemo, useState } from 'react';
+
+import { useNestedBorderRadius } from '../../../hooks/useNestedBorderRadius';
+import { cx } from '../../../styles/styler';
+import type { VStackProps } from '../../VStack';
+import { VStack } from '../../VStack';
+
+const MotionVStack = m.create(VStack);
+
+/* ---------------------------- ANIMATION HELPERS --------------------------- */
+
+// TODO: Move this to a shared location
+type BasePlacement = 'top' | 'bottom' | 'left' | 'right';
+
+const ANIMATION_CONFIG = { distance: 5, scale: 0.97 };
+const variants = {
+  top: { x: 0, y: ANIMATION_CONFIG.distance },
+  bottom: { x: 0, y: -ANIMATION_CONFIG.distance },
+  left: { x: ANIMATION_CONFIG.distance, y: 0 },
+  right: { x: -ANIMATION_CONFIG.distance, y: 0 },
+} as const;
+
+const getMenuAnimationVariants = (placement: AriakitMenuProviderProps['placement'] = 'bottom') => {
+  const [base = 'top'] = placement?.split('-') as [BasePlacement];
+
+  return {
+    closed: { ...variants[base], opacity: 0, scale: ANIMATION_CONFIG.scale },
+    open: { y: 0, x: 0, opacity: 1, scale: 1 },
+  };
+};
+
+const useMenuAnimationVariants = (placement: AriakitMenuProviderProps['placement']) => {
+  return useMemo(() => getMenuAnimationVariants(placement), [placement]);
+};
+
+/* -------------------------------- COMPONENT ------------------------------- */
+
+interface MenuContentProps extends Omit<VStackProps, 'asChild'> {
+  gutter?: SpacingAlias;
+  /** UDS handles nested border radius for the first and last item for you to prevent clipping and visual jank.
+   *  If you need to disable this, set this prop to true.
+   *
+   *  @link https://github.com/yahoo-uds/uds/blob/main/packages/uds/src/hooks/useNestedBorderRadius.ts
+   **/
+  disableAutoBorderRadius?: boolean;
+  /**
+   * `portalRef` is similar to `ref` but is scoped to the portal node. It's
+   * useful when you need to be informed when the portal element is appended to
+   * the DOM or removed from the DOM.
+   *
+   * Live examples:
+   * - [Form with Select](https://ariakit.org/examples/form-select)
+   * @example
+   * ```jsx
+   * const [portalElement, setPortalElement] = useState(null);
+   *
+   * <Portal portalRef={setPortalElement} />
+   * ```
+   */
+  portalRef?: AriakitMenuProps['portalRef'];
+  /**
+   * Determines whether the element should be rendered as a React Portal.
+   *
+   * Live examples:
+   * - [Combobox with integrated
+   *   filter](https://ariakit.org/examples/combobox-filtering-integrated)
+   * - [Dialog with Menu](https://ariakit.org/examples/dialog-menu)
+   * - [Hovercard with keyboard
+   *   support](https://ariakit.org/examples/hovercard-disclosure)
+   * - [Menubar](https://ariakit.org/components/menubar)
+   * - [Standalone Popover](https://ariakit.org/examples/popover-standalone)
+   * - [Animated Select](https://ariakit.org/examples/select-animated)
+   * @default true
+   */
+  portal?: boolean;
+  /**
+   * An HTML element or a memoized callback function that returns an HTML
+   * element to be used as the portal element. By default, the portal element
+   * will be a `div` element appended to the `document.body`.
+   *
+   * Live examples:
+   * - [Navigation Menubar](https://ariakit.org/examples/menubar-navigation)
+   * @example
+   * ```jsx
+   * const [portal, setPortal] = useState(null);
+   *
+   * <Portal portalElement={portal} />
+   * <div ref={setPortal} />
+   * ```
+   * @example
+   * ```jsx
+   * const getPortalElement = useCallback(() => {
+   *   const div = document.createElement("div");
+   *   const portalRoot = document.getElementById("portal-root");
+   *   portalRoot.appendChild(div);
+   *   return div;
+   * }, []);
+   *
+   * <Portal portalElement={getPortalElement} />
+   * ```
+   */
+  portalElement?: AriakitMenuProps['portalElement'];
+  /**
+   * Determines whether the popover should hide when the mouse leaves the
+   * popover or the anchor element and there's no _hover intent_, meaning, the
+   * mouse isn't moving toward the popover.
+   *
+   * This can be either a boolean or a callback receiving the mouse move event
+   * that initiated the behavior. The callback should return a boolean.
+   *
+   * **Note**: This behavior won't be triggered when the popover or any of its
+   * descendants are in focus.
+   * @default true
+   */
+  hideOnHoverOutside?: AriakitMenuProps['hideOnHoverOutside'];
+  /**
+   * Determines if the dialog will hide when the user presses the Escape key.
+   *
+   * This prop can be either a boolean or a function that accepts an event as an
+   * argument and returns a boolean. The event object represents the keydown
+   * event that initiated the hide action, which could be either a native
+   * keyboard event or a React synthetic event.
+   *
+   * **Note**: When placing Ariakit dialogs inside third-party dialogs, using
+   * `event.stopPropagation()` within this function will stop the event from
+   * reaching the third-party dialog, closing only the Ariakit dialog.
+   * @default true
+   */
+  hideOnEscape?: AriakitMenuProps['hideOnEscape'];
+  /**
+   * Determines if the dialog should hide when the user clicks or focuses on an
+   * element outside the dialog.
+   *
+   * This prop can be either a boolean or a function that takes an event as an
+   * argument and returns a boolean. The event object represents the event that
+   * triggered the action, which could be a native event or a React synthetic
+   * event of various types.
+   *
+   * Live examples:
+   * - [Selection Popover](https://ariakit.org/examples/popover-selection)
+   * @default true
+   */
+  hideOnInteractOutside?: AriakitMenuProps['hideOnInteractOutside'];
+  /**
+   * Determines if the pointer events outside of the popover and its anchor
+   * element should be disabled during _hover intent_, that is, when the mouse
+   * is moving toward the popover.
+   *
+   * This is required as these external events may trigger focus on other
+   * elements and close the popover while the user is attempting to hover over
+   * it.
+   *
+   * This can be either a boolean or a callback receiving the mouse event
+   * happening during hover intent. The callback should return a boolean.
+   * @default true
+   */
+  disablePointerEventsOnApproach?: AriakitMenuProps['disablePointerEventsOnApproach'];
+  /**
+   * Object returned by the [`useMenuStore`](https://ariakit.org/reference/use-menu-store) hook.
+   * If not provided, the closest [`Menu.Content`](https://uds.build/docs/components/menu#menu-content) or
+   * [`Menu.Provider`](https://uds.build/docs/components/menu#menu-provider) context will be used.
+   */
+  store?: AriakitMenuProps['store'];
+  /**
+   * Whether the popover should have the same width as the anchor element. This
+   * will be exposed to CSS as
+   * [`--popover-anchor-width`](https://ariakit.org/guide/styling#--popover-anchor-width).
+   * @default false
+   */
+  sameWidth?: AriakitMenuProps['sameWidth'];
+  /**
+   * @see https://ariakit.org/reference/focusable
+   * @default true
+   */
+  focusable?: AriakitMenuProps['focusable'];
+  /**
+   * This is an event handler prop triggered when the dialog's `close` event is
+   * dispatched. The `close` event is similar to the native dialog
+   * [`close`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close_event)
+   * event. The only difference is that this event can be canceled with
+   * `event.preventDefault()`, which will prevent the dialog from hiding.
+   *
+   * It's important to note that this event only fires when the dialog store's
+   * [`open`](https://ariakit.org/reference/use-dialog-store#open) state is set
+   * to `false`. If the controlled
+   * [`open`](https://ariakit.org/reference/dialog#open) prop value changes, or
+   * if the dialog's visibility is altered in any other way (such as unmounting
+   * the dialog without adjusting the open state), this event won't be
+   * triggered.
+   *
+   * Live examples:
+   * - [Dialog with scrollable
+   *   backdrop](https://ariakit.org/examples/dialog-backdrop-scrollable)
+   * - [Dialog with details &
+   *   summary](https://ariakit.org/examples/dialog-details)
+   * - [Warning on Dialog
+   *   hide](https://ariakit.org/examples/dialog-hide-warning)
+   * - [Dialog with Menu](https://ariakit.org/examples/dialog-menu)
+   */
+  onClose?: AriakitMenuProps['onClose'];
+}
+
+/**
+ * **📦 A Menu Content component**
+ *
+ * @componentType Client component
+ *
+ * @description
+ * A content component for the menu, which is used to provide the menu context to the menu items.
+ *
+ * @see The {@link https://uds.build/docs/components/menu-content Menu.Content Docs} for more info
+ *
+ * @example
+ * ```tsx
+ * 'use client'; // Next.js client component
+ *
+ * import { Menu, Button } from "@yahoo/uds";
+ * import { Calendar, Clipboard } from "@yahoo/uds-icons";
+ *
+ * export function MenuProviderExample() {
+ *   return (
+ *     <Menu.Provider>
+ *       <Menu.Trigger asChild>
+ *         <Button>Menu Options</Button>
+ *       </Menu.Trigger>
+ *       <Menu.Content>
+ *         <Menu.Item startIcon={Calendar}>Calendar</Menu.Item>
+ *         <Menu.Item startIcon={Clipboard} endIcon={DiagonalRightUp}>
+ *           Clipboard
+ *         </Menu.Item>
+ *         <Menu.Item active>Active Item</Menu.Item>
+ *       </Menu.Content>
+ *     </Menu.Provider>
+ *   )
+ * }
+ * ```
+ *
+ * @usage
+ * Using Menu.Content is required to use Menu.Item and Menu.ItemCheckbox. It acts as the actual menu container.
+ *
+ * @related [Menu](https://uds.build/docs/components/menu), [Menu.ItemCheckbox](https://uds.build/docs/components/menu-item-checkbox)
+ **/
+const MenuContent = forwardRef<HTMLDivElement, MenuContentProps>(function MenuContent(
+  {
+    // Spacing
+    gap,
+    spacing,
+    spacingBottom,
+    spacingEnd,
+    spacingStart,
+    spacingTop,
+    gutter = '1',
+    // Color
+    backgroundColor = 'primary',
+    borderRadius = 'md',
+    // Borders
+    borderColor,
+    borderWidth = 'thin',
+    overflow,
+    dropShadow = 'lg',
+    // Styles
+    className,
+    // Ariakit props
+    sameWidth,
+    focusable,
+    children,
+    portalElement,
+    portal = true,
+    // Misc
+    disableAutoBorderRadius,
+    // Rest
+    ...props
+  },
+  ref,
+) {
+  const context = useMenuContext();
+  const open = useStoreState(context, 'open');
+  const mounted = useStoreState(context, 'mounted');
+  const currentPlacement = useStoreState(context, 'currentPlacement');
+
+  const placement = useStoreState(context, 'placement');
+  const [prevPlacement, setPrevPlacement] =
+    useState<AriakitMenuProviderProps['placement']>(currentPlacement);
+  const [nextPlacement, setNextPlacement] =
+    useState<AriakitMenuProviderProps['placement']>(currentPlacement);
+
+  // If placement changes (This can happen when the html direction updates)
+  useEffect(() => {
+    if (placement !== nextPlacement) {
+      setNextPlacement(placement);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [placement]);
+
+  // If the placement is updated because of some collision
+  useEffect(() => {
+    if (currentPlacement !== nextPlacement) {
+      setNextPlacement(currentPlacement);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentPlacement]);
+
+  useEffect(() => {
+    if (mounted && nextPlacement !== prevPlacement) {
+      setPrevPlacement(nextPlacement);
+    }
+  }, [mounted, nextPlacement, prevPlacement]);
+
+  // Setup variants
+  const motionState = useMemo(() => {
+    if (!open || !mounted) {
+      return 'closed';
+    }
+    return 'open';
+  }, [open, mounted]);
+
+  // Allows us to animate the shadow when the menu is open
+  const shadowVariant = useMemo(() => (open ? dropShadow : 'none'), [open, dropShadow]);
+
+  const variants = useMenuAnimationVariants(nextPlacement);
+  const borderRadiusClassName = useNestedBorderRadius({ borderRadius, spacing });
+  const gutterValue = useMemo(() => spacingMap[gutter], [gutter]);
+
+  return (
+    <AnimatePresence initial={false}>
+      <AriakitMenu
+        gutter={gutterValue}
+        sameWidth={sameWidth}
+        focusable={focusable}
+        store={context}
+        ref={ref}
+        portalElement={portalElement}
+        portal={portal}
+        {...props}
+        render={
+          <MotionVStack
+            backgroundColor={backgroundColor}
+            gap={gap}
+            spacing={spacing}
+            spacingBottom={spacingBottom}
+            spacingEnd={spacingEnd}
+            spacingStart={spacingStart}
+            spacingTop={spacingTop}
+            borderRadius={borderRadius}
+            borderColor={borderColor}
+            borderWidth={borderWidth}
+            overflow={overflow}
+            animate={motionState}
+            variants={variants}
+            dropShadow={shadowVariant}
+            className={cx(
+              // Base class
+              'uds-menu-content',
+              // Handle shadow animation
+              'transition-shadow',
+              'duration-200',
+              'ease-in-out',
+              // Set a min/max width
+              'min-w-60',
+              'max-w-lg',
+              'max-h-96',
+              'overflow-auto',
+              // Focus ring
+              'uds-ring',
+              'z-10',
+              // Misc
+              'group',
+              !disableAutoBorderRadius && borderRadiusClassName,
+              className,
+            )}
+          >
+            {children}
+          </MotionVStack>
+        }
+      />
+    </AnimatePresence>
+  );
+});
+
+MenuContent.displayName = 'MenuContent';
+
+export { MenuContent, type MenuContentProps };

package/src/components/client/Menu/Menu.Divider.tsx

@@ -0,0 +1,102 @@
+import type { AriaRole } from 'react';
+import { forwardRef } from 'react';
+
+import { getStyles } from '../../../styles/styler';
+import type { DividerProps } from '../../Divider/Divider';
+import { DividerInternal } from '../../Divider/DividerInternal';
+
+interface MenuDividerProps extends Omit<DividerProps, 'variant'> {
+  /**
+   * The role of the divider.
+   * @default 'separator'
+   */
+  role?: AriaRole;
+}
+
+/**
+ * **〰️ A Menu Divider component**
+ *
+ * @componentType Client component
+ *
+ * @description
+ * A divider component for the menu.
+ *
+ * @see The {@link https://uds.build/docs/components/menu-divider Menu.Divider Docs} for more info
+ *
+ * @example
+ * ```tsx
+ * 'use client'; // Next.js client component
+ *
+ * import { Menu, Button } from "@yahoo/uds";
+ *
+ * export function DividerExample() {
+ *   return (
+ *     <Menu>
+ *       <Menu.Trigger asChild>
+ *         <Button>Menu Options</Button>
+ *       </Menu.Trigger>
+ *       <Menu.Content>
+ *         <Menu.Item>Calendar</Menu.Item>
+ *         <Menu.Divider>Other actions</Menu.Divider>
+ *         <Menu.Item>Clipboard</Menu.Item>
+ *         <Menu.Item active>Active Item</Menu.Item>
+ *       </Menu.Content>
+ *     </Menu>
+ *   )
+ * }
+ * ```
+ *
+ * @usage
+ * Use MenuDivider to separate groups of menu items.
+ *
+ * @related [Menu](https://uds.build/docs/components/menu), [Menu.Item](https://uds.build/docs/components/menu-item), [Divider](https://uds.build/docs/components/divider)
+ **/
+const MenuDivider = forwardRef<HTMLDivElement, MenuDividerProps>(function MenuDivider(
+  {
+    role = 'separator',
+    contentPosition = 'start',
+    gap = '4',
+    children,
+    spacingVertical = children ? '2' : '0',
+    spacingHorizontal = children ? '4' : '0',
+    className,
+    ...props
+  },
+  ref,
+) {
+  const layerClassNames = {
+    root: getStyles({
+      menuDividerVariantRoot: 'default',
+      className,
+    }),
+
+    text: getStyles({
+      menuDividerVariantText: 'default',
+    }),
+
+    line: getStyles({
+      menuDividerVariantLine: 'default',
+    }),
+  };
+
+  return (
+    <DividerInternal
+      ref={ref}
+      role={role}
+      variant="inherit"
+      contentPosition={contentPosition}
+      gap={gap}
+      spacingVertical={spacingVertical}
+      spacingHorizontal={spacingHorizontal}
+      className={layerClassNames.root}
+      layerClassNames={layerClassNames}
+      {...props}
+    >
+      {children}
+    </DividerInternal>
+  );
+});
+
+MenuDivider.displayName = 'MenuDivider';
+
+export { MenuDivider, type MenuDividerProps };

package/src/components/client/Menu/Menu.Item.tsx

@@ -0,0 +1,114 @@
+import type { MenuItemProps as AriakitMenuItemProps } from '@ariakit/react/menu';
+import { MenuItem as AriakitMenuItem } from '@ariakit/react/menu';
+import type { UniversalMenuItemProps } from '@yahoo/uds/tokens';
+import type { AriaRole } from 'react';
+import { forwardRef } from 'react';
+
+import { getStyles } from '../../../styles/styler';
+import type { PressableProps } from '../Pressable';
+import { MenuItemBase } from './Menu.ItemBase';
+
+interface MenuItemProps
+  extends Omit<PressableProps, 'asChild'>,
+    Omit<UniversalMenuItemProps, 'name'> {
+  /**
+   * Object returned by the [`useMenuStore`](https://ariakit.org/reference/use-menu-store) hook.
+   * If not provided, the closest [`Menu.Content`](https://uds.build/docs/components/menu#menu-content) or
+   * [`Menu.Provider`](https://uds.build/docs/components/menu#menu-provider) context will be used.
+   */
+  store?: AriakitMenuItemProps['store'];
+  /**
+   * Determines if the menu should hide when this item is clicked.
+   *
+   * **Note**: This behavior isn't triggered if this menu item is rendered as a
+   * link and modifier keys are used to either open the link in a new tab or
+   * download it.
+   *
+   * @default true
+   */
+  hideOnClick?: AriakitMenuItemProps['hideOnClick'];
+  /**
+   * The role of the menu item.
+   *
+   * @default 'menuitem'
+   */
+  role?: AriaRole;
+}
+
+/**
+ * **📋 A Menu Item component for navigation and actions**
+ *
+ * @componentType Client component
+ *
+ * @description
+ * A standard menu item that can be used for navigation, actions, or displaying options in a menu.
+ * Menu items can be styled with active states, icons, and can trigger callbacks when clicked.
+ * They support both visual and functional customization.
+ *
+ * @see The {@link https://uds.build/docs/components/menu-item Menu.Item Docs} for more info
+ *
+ * @example
+ * ```tsx
+ * 'use client'; // Next.js client component
+ *
+ * import { Menu, Button } from "@yahoo/uds";
+ * import { Calendar, Clipboard } from "@yahoo/uds-icons";
+ *
+ * export function MenuItemExample() {
+ *   return (
+ *     <Menu.Provider>
+ *       <Menu.Trigger asChild>
+ *         <Button>Menu Options</Button>
+ *       </Menu.Trigger>
+ *       <Menu.Content>
+ *         <Menu.Item startIcon={Calendar}>Calendar</Menu.Item>
+ *         <Menu.Item startIcon={Clipboard} endIcon={DiagonalRightUp}>
+ *           Clipboard
+ *         </Menu.Item>
+ *         <Menu.Item active>Active Item</Menu.Item>
+ *       </Menu.Content>
+ *     </Menu>
+ *   )
+ * }
+ * ```
+ *
+ * @usage
+ * Use MenuItem for standard menu options that trigger actions or navigate to other parts of the application.
+ * The active prop can be used to highlight the currently selected item.
+ *
+ * @related [Menu](https://uds.build/docs/components/menu), [Menu.ItemCheckbox](https://uds.build/docs/components/menu-item-checkbox)
+ **/
+const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(function MenuItem(
+  { active, hideOnClick, ...props },
+  ref,
+) {
+  const layerClassNames = {
+    root: getStyles({
+      menuItemVariantRoot: 'default',
+      menuItemVariantActiveRoot: active ? 'on' : 'off',
+    }),
+    text: getStyles({
+      menuItemVariantText: 'default',
+      menuItemVariantActiveText: active ? 'on' : 'off',
+    }),
+    startIcon: getStyles({
+      menuItemVariantIcon: 'default',
+      menuItemVariantActiveIcon: active ? 'on' : 'off',
+    }),
+  };
+
+  return (
+    <MenuItemBase
+      ref={ref}
+      as={AriakitMenuItem}
+      active={active}
+      layerClassNames={layerClassNames}
+      rootProps={{ hideOnClick }}
+      {...props}
+    />
+  );
+});
+
+MenuItem.displayName = 'MenuItem';
+
+export { MenuItem, type MenuItemProps };