@yahoo/uds 3.58.1 → 3.59.0-beta.1

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

@@ -0,0 +1,265 @@
+import type {
+  MenuItem as AriakitMenuItem,
+  MenuItemCheckbox as AriakitMenuItemCheckbox,
+} from '@ariakit/react';
+import type { UniversalMenuItemProps } from '@yahoo/uds/tokens';
+import { AnimatePresence, m } from 'motion/react';
+import { Children, forwardRef, useMemo } from 'react';
+
+import { cx, getStyles } from '../../../styles/styler';
+import { HStack } from '../../HStack';
+import { IconSlot } from '../../IconSlot';
+import type { PressableProps } from '../Pressable';
+import { Pressable } from '../Pressable';
+
+/* -------------------------------------------------------------------------- */
+/*                              TYPE DEFINITIONS                                */
+/* -------------------------------------------------------------------------- */
+
+type MenuItemRootComponent = typeof AriakitMenuItem | typeof AriakitMenuItemCheckbox;
+
+interface MenuItemBaseProps extends Omit<PressableProps, 'asChild'>, UniversalMenuItemProps {
+  /** Whether to show the end icon */
+  hideEndIcon?: boolean;
+  /** The component to render as the root */
+  as: MenuItemRootComponent;
+  /** Additional props to pass to the root component */
+  rootProps?: Record<string, unknown>;
+
+  /** Internal overrides for downstream components. */
+  layerClassNames?: {
+    root?: string;
+    text?: string;
+    startIcon?: string;
+    endIcon?: string;
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*                             CONSTANTS & MAPPINGS                             */
+/* -------------------------------------------------------------------------- */
+
+const ITEM_CLASS_NAME = 'uds-menu-item';
+
+const iconAnimationVariants = {
+  visible: { scale: 1, opacity: 1 },
+  hidden: { scale: 0.7, opacity: 0 },
+};
+/* -------------------------------------------------------------------------- */
+/*                              HELPER FUNCTIONS                                */
+/* -------------------------------------------------------------------------- */
+
+type MenuItemClassesProps = Pick<MenuItemBaseProps, 'active' | 'disabled' | 'className'>;
+
+/** Builds the class names for the menu item */
+const buildMenuItemClasses = ({ active, disabled, className }: MenuItemClassesProps) => {
+  return cx(
+    ITEM_CLASS_NAME,
+    'flex',
+    // hover state - only apply if not active and not disabled
+    // TODO: update hover color to a non-palette color
+    // focus state
+    'focus-visible:text-brand',
+    'focus-visible:bg-brand-secondary',
+    'focus-visible:z-10',
+    'uds-ring',
+    // TODO find a solution that doesn't require !
+    '!-outline-offset-2',
+    // active state
+    active && ['[&:not([aria-checked])]:cursor-default'],
+    // disabled state
+    disabled && 'opacity-25 cursor-not-allowed',
+    // Checked state
+    // 'aria-checked:text-brand',
+    // 'aria-checked:bg-brand-secondary',
+    // 'aria-checked:font-medium',
+    // // TODO: update hover color to a non-palette color
+    // 'aria-checked:hover:bg-purple-2',
+    // Misc
+    'duration-20 transition-[font-variation-settings] ease-in-out',
+    'z-0',
+    className,
+  );
+};
+
+/* -------------------------------------------------------------------------- */
+/*                           MENU ITEM COMPONENT(S)                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * @private This is an internal component shared by [Menu.Item](https://uds.build/docs/components/menu#menu-item) and [Menu.ItemCheckbox](https://uds.build/docs/components/menu#menu-item-checkbox)
+ * and may change without notice. Please do not use this component directly.
+ */
+const MenuItemBase = forwardRef<HTMLDivElement, MenuItemBaseProps>(function MenuItemBase(
+  {
+    spacing = '0',
+    spacingBottom,
+    spacingEnd,
+    spacingHorizontal = '4',
+    spacingStart,
+    spacingTop,
+    spacingVertical = '3.5',
+    columnGap = '2',
+    className,
+    children,
+    endIcon,
+    startIcon,
+    hideEndIcon,
+    active,
+    disabled,
+    as: RootComponent,
+    name,
+    alignItems = 'center',
+    justifyContent = 'space-between',
+    layerClassNames,
+    slots,
+    rootProps,
+    ...props
+  },
+  ref,
+) {
+  const hasMultipleChildren = Children.count(children) > 1;
+  const menuItemClassName = buildMenuItemClasses({ active, disabled, className });
+
+  /**
+   * Get content styles based on children layout needs
+   */
+  const contentStyles = getStyles({
+    // Base styles
+    className: cx(`${ITEM_CLASS_NAME}-content truncate`, layerClassNames?.text),
+    textAlign: 'start',
+    // Layout styles - only apply alignment props if we have multiple children
+    ...(hasMultipleChildren && {
+      columnGap,
+      display: 'flex',
+      alignItems: 'center',
+      width: 'full',
+      justifyContent: 'space-between',
+    }),
+  });
+
+  /**
+   * Styles
+   */
+  const classNames = useMemo(
+    () => ({
+      root: getStyles({
+        menuSizeRoot: 'default',
+        flexDirection: 'row',
+        spacing,
+        spacingBottom,
+        spacingEnd,
+        spacingHorizontal,
+        spacingStart,
+        spacingTop,
+        spacingVertical,
+        columnGap,
+        alignItems,
+        justifyContent,
+        className: cx(menuItemClassName, layerClassNames?.root),
+      }),
+
+      startIcon: getStyles({
+        menuSizeStartIcon: 'default',
+        className: layerClassNames?.startIcon,
+      }),
+
+      endIcon: getStyles({
+        menuSizeEndIcon: 'default',
+        className: layerClassNames?.endIcon,
+      }),
+    }),
+    [
+      alignItems,
+      columnGap,
+      justifyContent,
+      layerClassNames?.endIcon,
+      layerClassNames?.root,
+      layerClassNames?.startIcon,
+      menuItemClassName,
+      spacing,
+      spacingBottom,
+      spacingEnd,
+      spacingHorizontal,
+      spacingStart,
+      spacingTop,
+      spacingVertical,
+    ],
+  );
+
+  // Must follow ariakit extension guidelines:
+  // https://ariakit.org/guide/composition#custom-components-must-be-open-for-extension
+  const rootRender =
+    slots?.root ??
+    ((p) => (
+      <Pressable
+        {...p}
+        {...props}
+        onClick={(e) => {
+          p.onClick?.(e);
+          props.onClick?.(e);
+        }}
+      />
+    ));
+
+  return (
+    <RootComponent
+      ref={ref}
+      name={name ?? ''}
+      {...rootProps}
+      render={rootRender}
+      disabled={disabled}
+      className={classNames.root}
+    >
+      <HStack gap={columnGap} alignItems="center" width="full">
+        <AnimatePresence initial={false}>
+          {startIcon && (
+            <m.span
+              variants={iconAnimationVariants}
+              initial="hidden"
+              animate="visible"
+              exit="hidden"
+              className="uds-start-icon"
+            >
+              <IconSlot
+                icon={startIcon}
+                className={classNames.startIcon}
+                iconProps={{
+                  size: 'sm',
+                  variant: active ? 'fill' : 'outline',
+                  color: 'current',
+                }}
+              />
+            </m.span>
+          )}
+        </AnimatePresence>
+        <span className={contentStyles}>{children}</span>
+      </HStack>
+      <AnimatePresence initial={false} mode="popLayout">
+        {!hideEndIcon && endIcon && (
+          <m.span
+            variants={iconAnimationVariants}
+            initial="hidden"
+            animate="visible"
+            exit="hidden"
+            className="uds-end-icon"
+          >
+            <IconSlot
+              icon={endIcon}
+              className={classNames.endIcon}
+              iconProps={{
+                size: 'sm',
+                variant: active ? 'fill' : 'outline',
+                color: 'current',
+              }}
+            />
+          </m.span>
+        )}
+      </AnimatePresence>
+    </RootComponent>
+  );
+});
+
+MenuItemBase.displayName = 'MenuItemBase';
+
+export { ITEM_CLASS_NAME, MenuItemBase };

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

@@ -0,0 +1,197 @@
+import { useStoreState } from '@ariakit/react';
+import type { MenuItemCheckboxProps as AriakitMenuItemCheckboxProps } from '@ariakit/react/menu';
+import { MenuItemCheckbox as AriakitMenuItemCheckbox, useMenuContext } from '@ariakit/react/menu';
+import type { UniversalMenuItemProps } from '@yahoo/uds/tokens';
+import { Check } from '@yahoo/uds-icons';
+import type { ChangeEvent, HTMLAttributes } from 'react';
+import { forwardRef, useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { cx, getStyles } from '../../../styles/styler';
+import type { PressableProps } from '../Pressable';
+import { MenuItemBase } from './Menu.ItemBase';
+
+type HtmlButtonProps = HTMLAttributes<HTMLButtonElement>;
+
+interface MenuItemCheckboxProps
+  extends Omit<PressableProps, 'asChild'>,
+    HtmlButtonProps,
+    UniversalMenuItemProps {
+  /**
+   * The name of the field in the
+   * [`values`](https://ariakit.org/reference/menu-provider#values) state.
+   *
+   * Live examples at [MenuItemCheckbox](https://ariakit.org/examples/menu-item-checkbox)
+   */
+  name: string;
+  /**
+   * The controlled checked state of the element. It will set the menu
+   * [`values`](https://ariakit.org/reference/menu-provider#values) state if
+   * provided.
+   */
+  checked?: boolean;
+  /**
+   * The default checked state of the element. It will set the default value in
+   * the menu [`values`](https://ariakit.org/reference/menu-provider#values)
+   * state if provided.
+   */
+  defaultChecked?: boolean;
+  /**
+   * 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?: AriakitMenuItemCheckboxProps['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 undefined
+   */
+  hideOnClick?: AriakitMenuItemCheckboxProps['hideOnClick'];
+}
+
+/**
+ * **✅ A Menu Item Checkbox component**
+ *
+ * @componentType Client component
+ *
+ * @description
+ * A checkable menu item that toggles between selected and unselected states. Menu item checkboxes
+ * allow users to select multiple options from a menu, displaying a checkmark when active. They maintain
+ * their state even when the menu is closed and reopened.
+ *
+ * @see The {@link https://uds.build/docs/components/menu-item-checkbox Menu.ItemCheckbox Docs} for more info
+ *
+ * @example
+ * ```tsx
+ * 'use client'; // Next.js client component
+ *
+ * import { Menu, Button } from "@yahoo/uds";
+ *
+ * export function MenuItemCheckboxExample() {
+ *   return (
+ *     <Menu.Provider>
+ *       <Menu.Trigger asChild>
+ *         <Button>Filter Options</Button>
+ *       </Menu.Trigger>
+ *       <Menu.Content>
+ *         <Menu.ItemCheckbox name="showArchived" defaultChecked={false}>
+ *           Show Archived
+ *         </Menu.ItemCheckbox>
+ *         <Menu.ItemCheckbox name="includeComments" defaultChecked={true}>
+ *           Include Comments
+ *         </Menu.ItemCheckbox>
+ *       </Menu.Content>
+ *     </Menu.Provider>
+ *   )
+ * }
+ * ```
+ *
+ * @usage
+ * Use MenuItemCheckbox when you need to provide users with multiple selectable options within a menu.
+ * Unlike radio options, checkboxes allow for multiple simultaneous selections.
+ *
+ * @related [Menu](https://uds.build/docs/components/menu), [Menu.Item](https://uds.build/docs/components/menu-item)
+ **/
+const MenuItemCheckbox = forwardRef<
+  HTMLDivElement,
+  Omit<MenuItemCheckboxProps, 'rootProps' | 'hideEndIcon' | 'active'>
+>(function MenuItemCheckbox(
+  { name, endIcon = Check, checked, defaultChecked, hideOnClick, className, ...props },
+  ref,
+) {
+  const itemName = name;
+  const hasInitialized = useRef(false);
+
+  // Connect to the menu store
+  const context = useMenuContext();
+  const allState = useStoreState(context);
+
+  // Initialize default value in menu store if provided
+  useEffect(() => {
+    if (!hasInitialized.current && defaultChecked !== undefined && context) {
+      context.setValues((prev) => ({ ...prev, [itemName]: defaultChecked }));
+      hasInitialized.current = true;
+    }
+  }, [context, defaultChecked, itemName]);
+
+  // Get checked state from the menu store
+  const isChecked = useMemo(() => {
+    // If controlled, use the checked prop
+    if (checked !== undefined) {
+      return checked;
+    }
+
+    // Check DOM element state first
+    if (allState?.items?.length) {
+      const item = allState?.items.find(
+        (item) => (item.element as HTMLInputElement)?.name === itemName,
+      );
+
+      if (item?.element) {
+        return (item.element as HTMLInputElement).checked;
+      }
+    }
+
+    // Fall back to store value or default
+    const storeValue = allState?.values[itemName];
+    return typeof storeValue === 'boolean' ? storeValue : (defaultChecked ?? false);
+  }, [allState?.items, allState?.values, itemName, checked, defaultChecked]);
+
+  // Update the menu store when the checkbox is interacted with
+  const handleChange = useCallback(
+    (d: ChangeEvent<HTMLInputElement>) => {
+      // Only update store if not controlled
+      if (checked === undefined) {
+        context?.setValues((prev) => ({ ...prev, [itemName]: d.target.checked }));
+      }
+    },
+    [itemName, context, checked],
+  );
+
+  const layerClassNames = {
+    root: getStyles({
+      menuItemCheckboxVariantRoot: 'default',
+      menuItemCheckboxVariantActiveRoot: isChecked ? 'on' : 'off',
+    }),
+    text: getStyles({
+      menuItemCheckboxVariantText: 'default',
+      menuItemCheckboxVariantActiveText: isChecked ? 'on' : 'off',
+    }),
+    startIcon: getStyles({
+      menuItemCheckboxVariantStartIcon: 'default',
+      menuItemCheckboxVariantActiveStartIcon: isChecked ? 'on' : 'off',
+    }),
+    endIcon: getStyles({
+      menuItemCheckboxVariantEndIcon: 'default',
+      menuItemCheckboxVariantActiveEndIcon: isChecked ? 'on' : 'off',
+    }),
+  };
+
+  return (
+    <MenuItemBase
+      ref={ref}
+      as={AriakitMenuItemCheckbox}
+      hideEndIcon={!isChecked}
+      endIcon={endIcon}
+      active={isChecked}
+      className={cx('uds-menu-item-checkbox', className)}
+      layerClassNames={layerClassNames}
+      name={name}
+      rootProps={{
+        onChange: handleChange,
+        defaultChecked,
+        checked: checked !== undefined ? checked : undefined,
+        hideOnClick,
+      }}
+      {...props}
+    />
+  );
+});
+
+MenuItemCheckbox.displayName = 'MenuItemCheckbox';
+
+export { MenuItemCheckbox, type MenuItemCheckboxProps };

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

@@ -0,0 +1,154 @@
+import type { MenuProviderProps as AriakitMenuProviderProps } from '@ariakit/react/menu';
+import { MenuProvider as AriakitMenuProvider } from '@ariakit/react/menu';
+import type { PropsWithChildren } from 'react';
+
+import { useRtl } from '../../../hooks/useRtl';
+import { SpringMotionConfig } from '../SpringMotionConfig';
+import { transformAriakitPlacement } from './utils/transformAriakitPlacement';
+
+/** Valid vertical placement values for the menu */
+type VerticalPlacement = 'top' | 'bottom';
+/** Valid horizontal placement values for the menu */
+type HorizontalPlacement = 'start' | 'end';
+/** Combined placement values for menu positioning */
+type MenuPlacement =
+  | VerticalPlacement
+  | HorizontalPlacement
+  | `${VerticalPlacement}-${HorizontalPlacement}`
+  | `${HorizontalPlacement}-${VerticalPlacement}`;
+
+type MenuProviderProps = PropsWithChildren<{
+  /**
+   * A callback that gets called when the
+   * [`values`](https://ariakit.org/reference/menu-provider#values) state
+   * changes.
+   *
+   * Live examples:
+   * - [`MenuItemCheckbox`](https://uds.build/docs/components/menu-item-checkbox).
+   */
+  setValues?: (values: Record<string, boolean>) => void | AriakitMenuProviderProps['setValues'];
+  /**
+   * A map of names and values that will be used by the
+   * [`MenuItemCheckbox`](https://uds.build/docs/components/menu-item-checkbox).
+   *
+   * Live examples:
+   * - [MenuItemCheckbox](https://uds.build/docs/components/menu-item-checkbox)
+   */
+  values?: AriakitMenuProviderProps['values'];
+  /**
+   * The placement of the Menu.Content.
+   *
+   * @default 'bottom'
+   */
+  placement?: MenuPlacement;
+  /**
+   * 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?: AriakitMenuProviderProps['store'];
+  /**
+   * Whether the menu should be rendered in RTL direction.
+   *
+   * This only affects the some component behavior behavior. You still need to set
+   * `dir="rtl"` on HTML/CSS.
+   * @default false
+   */
+  rtl?: AriakitMenuProviderProps['rtl'];
+  /**
+   * Whether the content is visible.
+   * @default false
+   */
+  open?: AriakitMenuProviderProps['open'];
+  /**
+   * A callback that gets called when the
+   * [`open`](https://ariakit.org/reference/disclosure-provider#open) state
+   * changes.
+   * @example
+   * const [open, setOpen] = useState(false);
+   * const disclosure = useDisclosureStore({ open, setOpen });
+   */
+  setOpen?: AriakitMenuProviderProps['setOpen'];
+  /**
+   * Whether the content should be visible by default.
+   * @default false
+   */
+  defaultOpen?: AriakitMenuProviderProps['defaultOpen'];
+  /**
+   * Determines how the focus behaves when the user reaches the end of the
+   * composite widget.
+   *
+   * Live examples:
+   * - [Command Menu](https://uds.build/docs/components/menu)
+   * @default false
+   */
+  focusLoop?: AriakitMenuProviderProps['focusLoop'];
+  /**
+   * If enabled, moving to the next item from the last one in a row or column
+   * will focus on the first item in the next row or column and vice-versa.
+   * `true` wraps between rows and columns, `horizontal` wraps only between rows, and `vertical` wraps only between columns.
+   *
+   * @default false
+   */
+  focusWrap?: AriakitMenuProviderProps['focusWrap'];
+}>;
+
+/**
+ * **🏗️ A Menu Provider component**
+ *
+ * @componentType Server component
+ *
+ * @description
+ * A provider 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-provider Menu.Provider 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
+ * 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 MenuProvider = function MenuProvider({
+  placement = 'bottom',
+  rtl: explicitRtl,
+  ...props
+}: MenuProviderProps) {
+  const isRtl = useRtl({ explicit: explicitRtl });
+  const ariakitPlacement = transformAriakitPlacement(placement, { rtl: isRtl });
+
+  return (
+    <SpringMotionConfig>
+      <AriakitMenuProvider placement={ariakitPlacement} rtl={isRtl} {...props} />
+    </SpringMotionConfig>
+  );
+};
+
+MenuProvider.displayName = 'MenuProvider';
+
+export { type MenuPlacement, MenuProvider, type MenuProviderProps };