@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/DropdownMenu/DropdownMenu.tsx

@@ -38,6 +38,7 @@ import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 
 import {renderDropdownItems} from './renderDropdownItems';
+import {MENU_ITEM_ROLES, MENU_ITEM_SELECTOR} from './menuItemRoles';
 import {
   DropdownMenuContext,
   type DropdownMenuContextValue,
@@ -55,6 +56,7 @@ import {
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   dropdown: {
@@ -111,9 +113,7 @@ export interface DropdownMenuSection {
 }
 
 export type DropdownMenuOption =
-  | DropdownMenuItemData
-  | DropdownMenuDivider
-  | DropdownMenuSection;
+  DropdownMenuItemData | DropdownMenuDivider | DropdownMenuSection;
 
 // =============================================================================
 // Props
@@ -149,8 +149,7 @@ interface DropdownMenuCompoundProps extends DropdownMenuBaseProps {
 }
 
 export type DropdownMenuProps =
-  | DropdownMenuDataProps
-  | DropdownMenuCompoundProps;
+  DropdownMenuDataProps | DropdownMenuCompoundProps;
 
 // =============================================================================
 // DropdownMenu
@@ -176,10 +175,13 @@ export type DropdownMenuProps =
  * />
  * ```
  */
-const DEFAULT_BUTTON = {label: 'Menu'} as const;
+// When the consumer doesn't pass `button`, the default label is looked up
+// at render time so it respects the active InternationalizationProvider
+// locale.
+const DEFAULT_BUTTON_I18N_KEY = '@astryx.dropdownMenu.label' as const;
 
 export function DropdownMenu({
-  button = DEFAULT_BUTTON,
+  button: buttonFromProps,
   isMenuOpen: controlledIsOpen,
   onOpenChange,
   menuWidth,
@@ -192,11 +194,14 @@ export function DropdownMenu({
   'data-testid': testId,
   ...props
 }: DropdownMenuProps) {
+  const t = useTranslator();
+  const button = buttonFromProps ?? {label: t(DEFAULT_BUTTON_I18N_KEY)};
+
   const items = ('items' in props ? props.items : undefined) ?? [];
   const children = props.children;
 
   const menuId = useId();
-  const menuSize = button?.size ?? 'md';
+  const menuSize = button.size ?? 'md';
   const buttonRef = useRef<HTMLButtonElement>(null);
 
   // Open state
@@ -251,14 +256,17 @@ export function DropdownMenu({
     popover.hide();
   }, [popover]);
 
-  // Single keyboard navigation path for both modes
+  // Single keyboard navigation path for both modes.
+  // The selector matches plain items plus selectable items
+  // (menuitemradio/menuitemcheckbox) so lab checkbox/radio rows are reachable
+  // and roved to alongside plain items — not just role="menuitem".
   const {
     listRef,
     handleKeyDown: listNavKeyDown,
     focusFirst,
     focusItem,
   } = useListFocus<HTMLDivElement>({
-    itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',
+    itemSelector: MENU_ITEM_SELECTOR,
     wrap: false,
     onEscape: closeMenu,
   });
@@ -269,9 +277,7 @@ export function DropdownMenu({
     (): HTMLElement[] =>
       listRef.current
         ? Array.from(
-            listRef.current.querySelectorAll<HTMLElement>(
-              '[role="menuitem"]:not([aria-disabled="true"])',
-            ),
+            listRef.current.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
           )
         : [],
     [listRef],
@@ -304,7 +310,10 @@ export function DropdownMenu({
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
         const focused = document.activeElement as HTMLElement | null;
-        if (focused?.getAttribute('role') === 'menuitem') {
+        if (
+          focused &&
+          MENU_ITEM_ROLES.has(focused.getAttribute('role') ?? '')
+        ) {
           focused.click();
         }
         return;

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'DropdownMenuCheckboxItem',
+  subComponentOf: 'DropdownMenu',
+  displayName: 'Dropdown Menu Checkbox Item',
+  isHiddenFromOverview: true,
+  description:
+    'A checkable menu item (role="menuitemcheckbox") that toggles an independent boolean. Use for on/off options inside a DropdownMenu; for a one-of-N choice use DropdownMenuRadioGroup.',
+  props: [
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: 'Primary label text identifying the item.',
+    },
+    {
+      name: 'description',
+      type: 'ReactNode',
+      description: 'Secondary description text displayed below the label.',
+    },
+    {
+      name: 'icon',
+      type: 'IconType',
+      description:
+        'Icon to display before the label. See `npx astryx docs icons` for valid semantic names.',
+    },
+    {
+      name: 'value',
+      type: 'boolean',
+      description: 'Whether the item is checked. Controlled — pair with onChange.',
+    },
+    {
+      name: 'onChange',
+      type: '(checked: boolean) => void',
+      description: 'Callback fired with the next checked state when the item is toggled.',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      default: 'false',
+      description:
+        '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.',
+    },
+    {
+      name: 'hasCloseOnSelect',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'Whether toggling the item closes the menu. Checkbox items default to staying open so several can be toggled in a single session.',
+    },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description:
+        'Content to render after the label and description, such as a keyboard shortcut hint or badge.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'DropdownMenuCheckboxItem',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Checkbox Item',
+  description:
+    '可勾选的菜单项（role="menuitemcheckbox"），用于切换独立的布尔值。用于 DropdownMenu 中的开关选项；单选请使用 DropdownMenuRadioGroup。',
+  propDescriptions: {
+    label: '标识该项的主标签文本。',
+    description: '显示在标签下方的次要描述文本。',
+    icon: '显示在标签前的图标。',
+    value: '该项是否被勾选。受控 — 与 onChange 搭配使用。',
+    onChange: '切换该项时以下一个勾选状态触发的回调。',
+    isDisabled: '该项是否禁用。',
+    hasCloseOnSelect: '切换该项是否关闭菜单。默认保持打开。',
+    endContent: '在标签和描述之后渲染的内容。',
+  },
+};
+
+export const docsDense = {
+  name: 'DropdownMenuCheckboxItem',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Checkbox Item',
+  description: 'checkable menu item (menuitemcheckbox); independent boolean toggle',
+  propDescriptions: {
+    label: 'primary label text',
+    description: 'secondary text below label',
+    icon: 'icon before label',
+    value: 'checked state (controlled, w/ onChange)',
+    onChange: 'fired w/ next checked state on toggle',
+    isDisabled: 'disabled; stays focusable via aria-disabled',
+    hasCloseOnSelect: 'close menu on toggle (default false — stays open)',
+    endContent: 'content after label+description',
+  },
+};

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -0,0 +1,237 @@
+// 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 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 {
+  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'],
+      ':hover': 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 astryx 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 '@astryxdesign/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]);
+
+  return (
+    <Item
+      {...rest}
+      role="menuitemcheckbox"
+      aria-checked={value}
+      tabIndex={isDisabled ? undefined : -1}
+      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

@@ -14,11 +14,14 @@
 
 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: 'sm' | 'md' | 'lg';
+  menuSize: DropdownMenuSize;
 }
 
 export const DropdownMenuContext =
@@ -32,3 +35,28 @@ DropdownMenuContext.displayName = 'DropdownMenuContext';
 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

@@ -8,11 +8,17 @@ export const docs = {
   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 `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'label',

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',
+  },
+};