@pharos-ds/core 0.1.9

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -0,0 +1,242 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuCheckboxItem.tsx
+ * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @output DropdownMenuCheckboxItem — a standalone checkable menu item.
+ * @position Sub-component; used inside DropdownMenu.
+ *
+ * A menu item that toggles an independent boolean (role="menuitemcheckbox").
+ * Unlike CheckboxInput, there is no nested native <input>: the row itself owns
+ * the role and aria-checked, per the WAI-ARIA menuitemcheckbox pattern.
+ * Keyboard navigation (arrows/typeahead) and Enter/Space activation come from
+ * the parent DropdownMenu's useListFocus + activation path, which matches
+ * menuitemcheckbox alongside plain menuitem rows.
+ *
+ * The square checkbox visual is decorative (aria-hidden) — the row owns the
+ * checked state. Its size is derived from the menu's item size (a `sm` menu
+ * gets the compact control; `md`/`lg` get the standard one) and it swaps to the
+ * inline-end of the row on coarse-pointer (touch) devices via CSS `order`, so
+ * it lands where selection toggles are conventionally placed on mobile. The
+ * checkmark uses the `check` icon from the active theme's icon registry.
+ */
+
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon, renderIconSlot, type IconType} from '../Icon';
+import {Item} from '../Item';
+import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  durationVars,
+  easeVars,
+  borderVars,
+} from '../theme/tokens.stylex';
+import {mergeProps, themeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    borderRadius: `max(0px, calc(var(--_dropdown-menu-radius, ${spacingVars['--spacing-2']}) - var(--_dropdown-menu-padding, ${spacingVars['--spacing-1']})))`,
+    color: colorVars['--color-text-primary'],
+    backgroundColor: {
+      default: 'transparent',
+      ':focus': colorVars['--color-overlay-hover'],
+    },
+    cursor: 'pointer',
+    outline: 'none',
+  },
+  disabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+  },
+  // Rendered in Item's `marker` slot as a raw flex child, so `order` moves it
+  // relative to the label within the row. On touch it moves to the inline-end.
+  box: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    boxSizing: 'border-box',
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderRadius: radiusVars['--radius-inner'],
+    color: colorVars['--color-on-accent'],
+    transitionProperty: 'background-color, border-color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    order: {
+      default: 0,
+      '@media (pointer: coarse)': 1,
+    },
+    marginInlineStart: {
+      default: 0,
+      '@media (pointer: coarse)': 'auto',
+    },
+  },
+  unchecked: {
+    borderColor: colorVars['--color-border-emphasized'],
+    backgroundColor: colorVars['--color-background-surface'],
+  },
+  checked: {
+    borderColor: colorVars['--color-accent'],
+    backgroundColor: colorVars['--color-accent'],
+  },
+});
+
+const boxSizeStyles = stylex.create({
+  sm: {width: 18, height: 18},
+  md: {width: 22, height: 22},
+});
+
+export interface DropdownMenuCheckboxItemProps extends Omit<
+  BaseProps,
+  'onChange' | 'role' | 'aria-checked' | 'tabIndex'
+> {
+  /**
+   * Primary label text identifying the item.
+   */
+  label: ReactNode;
+  /**
+   * Secondary description text displayed below the label.
+   */
+  description?: ReactNode;
+  /**
+   * Icon to display before the label. Accepts a semantic icon name (see
+   * `npx pharos docs icons`) or a rendered node.
+   */
+  icon?: ReactNode | IconType;
+  /**
+   * Whether the item is checked. Controlled — pair with `onChange`.
+   */
+  value: boolean;
+  /**
+   * Callback fired with the next checked state when the item is toggled.
+   */
+  onChange?: (checked: boolean) => void;
+  /**
+   * Whether the item is disabled. Disabled items stay focusable (via
+   * `aria-disabled`) so they remain discoverable by keyboard and assistive
+   * technology, but activation is blocked.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * Whether toggling the item closes the menu. Checkbox items default to
+   * staying open so several can be toggled in a single session, unlike radio
+   * items which default to closing on selection.
+   * @default false
+   */
+  hasCloseOnSelect?: boolean;
+  /**
+   * Content to render after the label and description, such as a keyboard
+   * shortcut hint or badge.
+   */
+  endContent?: ReactNode;
+}
+
+/**
+ * A checkable dropdown menu item (role="menuitemcheckbox").
+ *
+ * Must be used inside a DropdownMenu. Toggles an independent boolean; for a
+ * one-of-N choice use DropdownMenuRadioGroup + DropdownMenuRadioItem instead.
+ *
+ * @example
+ * ```
+ * import {DropdownMenuCheckboxItem} from '@pharos-ds/core/DropdownMenu';
+ * <DropdownMenu button={{label: 'View'}}>
+ *   <DropdownMenuCheckboxItem
+ *     label="Show archived"
+ *     value={showArchived}
+ *     onChange={setShowArchived}
+ *   />
+ * </DropdownMenu>
+ * ```
+ */
+export function DropdownMenuCheckboxItem({
+  label,
+  description,
+  icon,
+  value,
+  onChange,
+  isDisabled = false,
+  hasCloseOnSelect = false,
+  endContent,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: DropdownMenuCheckboxItemProps) {
+  const ctx = useDropdownMenuContext();
+  const menuSize = ctx?.menuSize ?? 'md';
+  const controlSize = menuSize === 'sm' ? 'sm' : 'md';
+
+  const handleClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    onChange?.(!value);
+    if (hasCloseOnSelect) {
+      ctx?.closeMenu();
+    }
+  }, [isDisabled, onChange, value, hasCloseOnSelect, ctx]);
+
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
+  return (
+    <Item
+      {...rest}
+      role="menuitemcheckbox"
+      aria-checked={value}
+      tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
+      marker={
+        <span
+          aria-hidden="true"
+          {...mergeProps(
+            themeProps('dropdown-menu-checkbox', {
+              size: controlSize,
+              checked: value ? 'checked' : null,
+              disabled: isDisabled ? 'disabled' : null,
+            }),
+            stylex.props(
+              styles.box,
+              boxSizeStyles[controlSize],
+              value ? styles.checked : styles.unchecked,
+            ),
+          )}>
+          {value && <Icon icon="check" size="sm" color="inherit" />}
+        </span>
+      }
+      startContent={
+        icon
+          ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})
+          : undefined
+      }
+      label={label}
+      description={description}
+      endContent={endContent}
+      onClick={handleClick}
+      isDisabled={isDisabled}
+      xstyle={[styles.root, isDisabled && styles.disabled, xstyle]}
+      {...mergeProps(themeProps('dropdown-menu-item', {size: menuSize}), {
+        className,
+        style,
+      })}
+    />
+  );
+}
+
+DropdownMenuCheckboxItem.displayName = 'DropdownMenuCheckboxItem';

package/src/DropdownMenu/DropdownMenuContext.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuContext.tsx
+ * @output Exports context and hook for compound-component menu coordination
+ * @position Internal; used by DropdownMenu and DropdownMenuItem
+ *
+ * Provides menu state (close callback, size) to compound children.
+ * Keyboard navigation is handled by useListFocus on the menu container —
+ * items don't need to register themselves.
+ */
+
+import {createContext, use} from 'react';
+
+/** Menu size, derived from the trigger button size. */
+export type DropdownMenuSize = 'sm' | 'md' | 'lg';
+
+export interface DropdownMenuContextValue {
+  /** Close the menu and return focus to trigger */
+  closeMenu: () => void;
+  /** Menu size derived from button size */
+  menuSize: DropdownMenuSize;
+}
+
+export const DropdownMenuContext =
+  createContext<DropdownMenuContextValue | null>(null);
+DropdownMenuContext.displayName = 'DropdownMenuContext';
+
+/**
+ * Hook for compound menu items to access menu state.
+ * Returns null outside of a DropdownMenu.
+ */
+export function useDropdownMenuContext(): DropdownMenuContextValue | null {
+  return use(DropdownMenuContext);
+}
+
+// =============================================================================
+// Radio group coordination
+// =============================================================================
+
+export interface DropdownMenuRadioGroupContextValue {
+  /** The currently selected value in the group. */
+  value: string | undefined;
+  /** Select a value. Called by a DropdownMenuRadioItem on activation. */
+  onChange: (value: string) => void;
+  /** Whether selecting an item should close the menu. @default true */
+  hasCloseOnSelect: boolean;
+}
+
+export const DropdownMenuRadioGroupContext =
+  createContext<DropdownMenuRadioGroupContextValue | null>(null);
+DropdownMenuRadioGroupContext.displayName = 'DropdownMenuRadioGroupContext';
+
+/**
+ * Read the enclosing radio group's selection state.
+ * Returns null when used outside a DropdownMenuRadioGroup.
+ */
+export function useDropdownMenuRadioGroupContext(): DropdownMenuRadioGroupContextValue | null {
+  return use(DropdownMenuRadioGroupContext);
+}

package/src/DropdownMenu/DropdownMenuItem.doc.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'DropdownMenuItem',
+  subComponentOf: 'DropdownMenu',
+  displayName: 'Dropdown Menu Item',
+  isHiddenFromOverview: true,
+  description: 'Helper component for custom item rendering with consistent styling.',
+  playground: {
+    // Standalone DropdownMenuItem has no required props, so the properties-tab
+    // preview renders an empty row without seeded content. Seed a label and
+    // description so the preview is meaningful.
+    defaults: {label: 'Edit', description: 'Modify this item'},
+  },
+  props: [
+    {
+      name: 'icon',
+      type: 'IconType',
+      description: 'Icon to display before the label. See `pharos docs icons` for valid semantic names.',
+    },
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: 'Primary label text.',
+    },
+    {
+      name: 'description',
+      type: 'ReactNode',
+      description: 'Secondary description text displayed below the label.',
+    },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description: 'Additional content rendered after the label and description.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'DropdownMenuItem',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Item',
+  description: '用于自定义项渲染的辅助组件，提供一致的样式。',
+  props: [
+    {
+      name: 'icon',
+      type: 'IconType',
+      description: '显示在标签前的图标。',
+    },
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: '主标签文本。',
+    },
+    {
+      name: 'description',
+      type: 'ReactNode',
+      description: '显示在标签下方的次要描述文本。',
+    },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description: '在标签和描述之后渲染的附加内容。',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: '根容器的 StyleX 样式。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'DropdownMenuItem',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Item',
+  description: 'helper for custom item rendering w/ consistent styling',
+  propDescriptions: {
+    icon: 'icon before label',
+    label: 'primary label text',
+    description: 'secondary text below label',
+    endContent: 'additional content after label+description',
+    xstyle: 'StyleX styles for root container',
+  },
+};

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuItem.tsx
+ * @output Exports DropdownMenuItem component
+ * @position Sub-component; used inside DropdownMenu
+ *
+ * Interactive menu item with role="menuitem". Keyboard navigation
+ * is handled by useListFocus on the parent menu container.
+ *
+ * Composes Item for the shared start content + label + description + end content layout.
+ * Passes role="menuitem" so Item puts onClick on the root div instead of
+ * creating an invisible button (keyboard access is provided by the parent menu).
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+ * - /packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
+ * - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+ * - /packages/core/src/DropdownMenu/index.ts
+ * - /apps/storybook/stories/DropdownMenu.stories.tsx
+ * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ */
+
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {renderIconSlot, type IconType} from '../Icon';
+import {Item} from '../Item';
+import {
+  colorVars,
+  spacingVars,
+  typographyVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
+import {themeProps} from '../utils/themeProps';
+
+const menuItemStyles = stylex.create({
+  root: {
+    boxSizing: 'border-box',
+    width: '100%',
+    paddingBlock: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-2'],
+    borderRadius: `max(0px, calc(var(--_dropdown-menu-radius, ${spacingVars['--spacing-2']}) - var(--_dropdown-menu-padding, ${spacingVars['--spacing-1']})))`,
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-label-size'],
+    color: colorVars['--color-text-primary'],
+    backgroundColor: {
+      default: 'transparent',
+      ':focus': colorVars['--color-overlay-hover'],
+    },
+    border: 'none',
+    cursor: 'pointer',
+    textAlign: 'start',
+    outline: 'none',
+  },
+  disabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+  },
+});
+
+const itemSizeStyles = stylex.create({
+  sm: {
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: spacingVars['--spacing-2'],
+  },
+  md: {
+    paddingBlock: spacingVars['--spacing-1-5'],
+  },
+  lg: {},
+});
+
+export interface DropdownMenuItemProps extends Pick<
+  BaseProps,
+  'xstyle' | 'className' | 'style'
+> {
+  /** Icon to display before the label. */
+  icon?: ReactNode | IconType;
+  /** Primary label text. */
+  label: ReactNode;
+  /** Secondary description text displayed below the label. */
+  description?: ReactNode;
+  /** Callback when the item is selected. */
+  onClick?: () => void;
+  /** Whether the item is disabled. @default false */
+  isDisabled?: boolean;
+  /** Additional content to render after the label/description. */
+  endContent?: ReactNode;
+}
+
+/**
+ * An interactive dropdown menu item with icon, label, and optional description.
+ *
+ * Must be used inside DropdownMenu. Keyboard navigation is provided
+ * automatically by the parent via useListFocus.
+ *
+ * @example
+ * ```
+ * <DropdownMenu button={{ label: 'Actions' }}>
+ *   <DropdownMenuItem icon={PencilIcon} label="Edit" onClick={handleEdit} />
+ *   <DropdownMenuItem label="Delete" endContent={<Badge label="⌘D" />} onClick={handleDelete} />
+ * </DropdownMenu>
+ * ```
+ */
+export function DropdownMenuItem({
+  icon,
+  label,
+  description,
+  onClick,
+  isDisabled = false,
+  endContent,
+  xstyle,
+  className,
+  style,
+}: DropdownMenuItemProps) {
+  const ctx = useDropdownMenuContext();
+  const menuSize = ctx?.menuSize ?? 'md';
+
+  const handleClick = useCallback(() => {
+    if (isDisabled || !onClick) {
+      return;
+    }
+    onClick();
+    ctx?.closeMenu();
+  }, [isDisabled, onClick, ctx]);
+
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
+  return (
+    <Item
+      role="menuitem"
+      tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
+      startContent={
+        icon
+          ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})
+          : undefined
+      }
+      label={label}
+      description={description}
+      endContent={endContent}
+      onClick={handleClick}
+      isDisabled={isDisabled}
+      xstyle={[
+        menuItemStyles.root,
+        itemSizeStyles[menuSize],
+        isDisabled && menuItemStyles.disabled,
+        xstyle,
+      ]}
+      {...mergeProps(themeProps('dropdown-menu-item', {size: menuSize}), {
+        className,
+        style,
+      })}
+    />
+  );
+}
+
+DropdownMenuItem.displayName = 'DropdownMenuItem';

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'DropdownMenuRadioGroup',
+  subComponentOf: 'DropdownMenu',
+  displayName: 'Dropdown Menu Radio Group',
+  isHiddenFromOverview: true,
+  description:
+    'A single-select group of radio menu items (role="group" of menuitemradio). Owns the selected value and lays its items out with the menu\'s inter-item gap.',
+  props: [
+    {
+      name: 'value',
+      type: 'string | undefined',
+      description:
+        'The currently selected value in the group. Pass undefined when nothing is selected yet.',
+    },
+    {
+      name: 'onChange',
+      type: '(value: string) => void',
+      description: 'Callback fired when the selected value changes.',
+    },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        'Accessible label for the group. Required (or aria-labelledby) so screen readers announce the radios as a named set, e.g. "Sort by".',
+    },
+    {
+      name: 'aria-labelledby',
+      type: 'string',
+      description:
+        'The id of an element that labels the group, as an alternative to aria-label.',
+    },
+    {
+      name: 'hasCloseOnSelect',
+      type: 'boolean',
+      default: 'true',
+      description:
+        'Whether selecting a value closes the menu. Radio items default to closing on selection (a single-choice commit).',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'The DropdownMenuRadioItems that make up the group.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'DropdownMenuRadioGroup',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Radio Group',
+  description:
+    '单选的单选菜单项组（menuitemradio 的 role="group"）。持有所选值，并以菜单的项间距布局其子项。',
+  propDescriptions: {
+    value: '组中当前选中的值。尚无选中项时传 undefined。',
+    onChange: '所选值变化时触发的回调。',
+    'aria-label': '组的无障碍标签。必需（或 aria-labelledby），以便屏幕阅读器将单选项作为命名集合朗读。',
+    'aria-labelledby': '标记该组的元素 id，作为 aria-label 的替代。',
+    hasCloseOnSelect: '选择某值是否关闭菜单。默认关闭。',
+    children: '组成该组的 DropdownMenuRadioItem。',
+  },
+};
+
+export const docsDense = {
+  name: 'DropdownMenuRadioGroup',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Radio Group',
+  description: 'single-select group of menuitemradio; owns selected value',
+  propDescriptions: {
+    value: 'selected value (undefined = none)',
+    onChange: 'fired when selected value changes',
+    'aria-label': 'accessible group name (or aria-labelledby); required',
+    'aria-labelledby': 'id of labelling element (alt to aria-label)',
+    hasCloseOnSelect: 'close menu on select (default true)',
+    children: 'the DropdownMenuRadioItems',
+  },
+};