Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
7.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */

export const docs = {
  name: 'DropdownMenuGroup',
  subComponentOf: 'DropdownMenu',
  displayName: 'Dropdown Menu Group',
  isHiddenFromOverview: true,
  playground: {
    // A standalone group has no required props, so the properties-tab preview
    // would render an empty box. Seed a title so the heading shows.
    defaults: {title: 'Version history'},
  },
  description:
    'A group of rows in a compound menu. A visible title names role="group" through aria-labelledby; an omitted title leaves the group unnamed. The heading is not a menuitem, so arrow keys and typeahead skip it. Keep title content non-interactive and place controls in DropdownMenu header or footer. The data-driven equivalent is the `{type: "section", title, items}` entry in `items`; both forms share the heading treatment and theme target. Host attributes and DOM handlers (id, data-*, aria-*) reach the group element; its role, and its name while it has a title, stay component-owned.',
  usage: {
    description:
      'Use DropdownMenuGroup to give related compound-menu rows one visible and programmatic name. Use an untitled group only when a separate name would not help people understand the rows.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Use short, descriptive title content that explains what the grouped rows have in common.',
      },
      {
        guidance: true,
        description:
          'Keep the title non-interactive so every available action remains in the menu arrow-key order.',
      },
      {
        guidance: false,
        description:
          'Place buttons, links, fields, or other controls in title. Put them in DropdownMenu header or footer instead.',
      },
      {
        guidance: false,
        description:
          'Wrap rows that do not form a meaningful set; a group adds structure only when its relationship helps users.',
      },
    ],
    anatomy: [
      {
        name: 'Group',
        required: true,
        description:
          'The role="group" wrapper containing the heading and menu rows.',
      },
      {
        name: 'Heading',
        required: false,
        description:
          'Visible non-interactive title content that names the group and carries the dropdown-menu-section-heading theme target.',
      },
      {
        name: 'Rows',
        required: false,
        description:
          'Menu items, selectable items, radio groups, or submenus owned by DropdownMenu.',
      },
    ],
  },
  props: [
    {
      name: 'title',
      type: 'ReactNode',
      description:
        "Non-interactive heading content shown above the rows and used as the group's accessible name. Omit for an unnamed group; place controls in DropdownMenu header or footer.",
    },
    {
      name: 'children',
      type: 'ReactNode',
      description:
        'The grouped rows: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, or DropdownMenuSubMenu.',
    },
    {
      name: 'xstyle',
      type: 'StyleXStyles',
      description:
        'StyleX styles applied to the role="group" wrapper. Must be a stylex.create() value, not an inline style object.',
    },
    {
      name: 'className',
      type: 'string',
      description: 'CSS class name applied to the role="group" wrapper.',
    },
    {
      name: 'style',
      type: 'React.CSSProperties',
      description: 'Inline styles applied to the role="group" wrapper.',
    },
    {
      name: 'ref',
      type: 'React.Ref<HTMLDivElement>',
      description: 'Ref forwarded to the role="group" wrapper.',
    },
  ],
  theming: {
    targets: [{className: 'astryx-dropdown-menu-section-heading'}],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docsZh = {
  name: 'DropdownMenuGroup',
  subComponentOf: 'DropdownMenu',
  displayName: 'Dropdown Menu Group',
  isHiddenFromOverview: true,
  description:
    '复合菜单中的一组菜单行。可见标题通过 aria-labelledby 为 role="group" 命名;省略标题时该组没有名称。标题不是 menuitem,因此方向键和预输入会跳过它。标题内容应保持非交互;控件应放在 DropdownMenu 的 header 或 footer 中。宿主属性和 DOM 事件处理函数(id、data-*、aria-*)会传到分组元素上;其 role 以及有标题时的名称由组件控制。',
  usage: {
    description:
      '使用 DropdownMenuGroup 为相关的复合菜单行提供同一个可见名称和无障碍名称。只有当名称能帮助理解这些菜单行时才使用分组。',
    bestPractices: [
      {guidance: true, description: '使用简短且能说明菜单行关系的标题。'},
      {
        guidance: true,
        description: '保持标题非交互,让所有操作都位于菜单的方向键顺序中。',
      },
      {
        guidance: false,
        description:
          '在标题中放置按钮、链接或输入控件;应改用 DropdownMenu 的 header 或 footer。',
      },
      {guidance: false, description: '对没有共同含义的菜单行进行分组。'},
    ],
    anatomy: [
      {
        name: '组',
        required: true,
        description: '包含标题和菜单行的 role="group" 包装元素。',
      },
      {
        name: '标题',
        required: false,
        description: '用于命名分组的可见非交互标题内容。',
      },
      {
        name: '菜单行',
        required: false,
        description: '由 DropdownMenu 持有的菜单项、可选项、单选组或子菜单。',
      },
    ],
  },
  props: [
    {
      name: 'title',
      type: 'ReactNode',
      description:
        '显示在菜单行上方并作为分组无障碍名称的非交互标题内容。省略时分组无名称;控件应放在 DropdownMenu 的 header 或 footer 中。',
    },
    {name: 'children', type: 'ReactNode', description: '该分组中的菜单行。'},
    {
      name: 'xstyle',
      type: 'StyleXStyles',
      description: '应用于 role="group" 包装元素的 StyleX 样式。',
    },
    {
      name: 'className',
      type: 'string',
      description: '应用于 role="group" 包装元素的 CSS 类名。',
    },
    {
      name: 'style',
      type: 'React.CSSProperties',
      description: '应用于 role="group" 包装元素的内联样式。',
    },
    {
      name: 'ref',
      type: 'React.Ref<HTMLDivElement>',
      description: '转发到 role="group" 包装元素的 ref。',
    },
  ],
  theming: {
    targets: [{className: 'astryx-dropdown-menu-section-heading'}],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'named role="group" of compound-menu rows; compound peer of the data API\'s {type: "section"}',
  usage: {
    description:
      'Use to give related compound-menu rows one visible and programmatic name.',
    bestPractices: [
      {
        guidance: true,
        description: "Short title that explains the rows' relationship.",
      },
      {
        guidance: true,
        description:
          'Non-interactive title keeps every action in menu arrow navigation.',
      },
      {
        guidance: false,
        description:
          'Controls in title. Put them in DropdownMenu header or footer instead.',
      },
      {guidance: false, description: 'Group unrelated rows.'},
    ],
  },
  propDescriptions: {
    title: 'non-interactive heading above the rows; names the group',
    children: 'the grouped menu rows',
    xstyle: 'StyleX styles on the role="group" wrapper',
    className: 'CSS class on the role="group" wrapper',
    style: 'inline styles on the role="group" wrapper',
    ref: 'ref forwarded to the role="group" wrapper',
  },
};