@astryxdesign/core 0.7.2-canary.55d8dff → 0.7.2-canary.577a62e

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'value',

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -98,7 +98,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**

package/src/DropdownMenu/DropdownMenuGroup.doc.mjs

@@ -13,25 +13,86 @@ export const docs = {
     defaults: {title: 'Version history'},
   },
   description:
-    'A titled group of rows in a compound menu. Renders role="group" named by its heading; the heading is plain text, not a menuitem, so arrow keys and typeahead skip it. The data-driven equivalent is the `{type: "section", title, items}` entry in `items`; the heading shares its typography and theme target.',
+    '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.',
+  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:
-        "Heading shown above the rows and used as the group's accessible name. Omit for an unnamed group.",
+        "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 rows of the group: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuSubMenu.',
+        'The grouped rows: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, or DropdownMenuSubMenu.',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
-        'StyleX styles applied to the group wrapper. Must be a stylex.create() value: not an inline style object like style={{}}.',
+        '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: {
@@ -39,15 +100,113 @@ export const docs = {
   },
 };
 
-export const docsDense = {
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docsZh = {
   name: 'DropdownMenuGroup',
-  isHiddenFromOverview: true,
+  subComponentOf: 'DropdownMenu',
   displayName: 'Dropdown Menu Group',
+  isHiddenFromOverview: true,
+  description:
+    '复合菜单中的一组菜单行。可见标题通过 aria-labelledby 为 role="group" 命名；省略标题时该组没有名称。标题不是 menuitem，因此方向键和预输入会跳过它。标题内容应保持非交互；控件应放在 DropdownMenu 的 header 或 footer 中。',
+  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:
-    'titled role="group" of rows for compound menus; compound peer of the data API\'s {type: "section"}',
+    '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: 'heading above the rows; names the group',
-    children: 'the rows of the group',
-    xstyle: 'StyleX styles applied to the group wrapper',
+    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',
   },
 };

package/src/DropdownMenu/DropdownMenuGroup.tsx

@@ -53,7 +53,8 @@ export interface DropdownMenuGroupProps extends Pick<
 > {
   /**
    * Heading shown above the group's rows and used as the group's accessible
-   * name (`aria-labelledby`). Omit it for an unnamed group.
+   * name (`aria-labelledby`). Omit it for an unnamed group. Keep this content
+   * non-interactive; controls belong in DropdownMenu's `header` or `footer`.
    */
   title?: ReactNode;
   /** The rows of the group: menu items, selectable items, sub-menus. */
@@ -65,9 +66,10 @@ export interface DropdownMenuGroupProps extends Pick<
 /**
  * A titled group of menu rows.
  *
- * Renders `role="group"` named by its heading. The heading is plain text, not
- * a `menuitem`, so it is never a stop in the menu's arrow-key order and
- * typeahead never lands on it. The compound peer of
+ * Renders `role="group"` named by its heading. The heading is not a
+ * `menuitem`, so arrow-key navigation and typeahead skip it. Keep heading
+ * content non-interactive; place controls in DropdownMenu's `header` or
+ * `footer`. The compound peer of
  * `{type: 'section', title, items}` in the `items` data API.
  *
  * @example

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -43,7 +43,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'isDisabled',

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -93,7 +93,7 @@ export interface DropdownMenuRadioItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**

package/src/DropdownMenu/__tests__/DropdownMenuGroupAudit.a11y.chromium.spec.ts

@@ -0,0 +1,334 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuGroupAudit.a11y.chromium.spec.ts
+ * @input Exact-head DropdownMenuGroup story across themes, color modes, direction, and viewport widths
+ * @output Screenshots and fail-closed sensor receipts for the DropdownMenuGroup component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DropdownMenuGroup audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('dropdown-menu-group-audit-evidence');
+const STORY_ID = 'core-dropdownmenugroup--named-and-unnamed-groups';
+const WIDE = {width: 1024, height: 768};
+const NARROW = {width: 320, height: 720};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+type AuditCase = {
+  key: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+};
+
+const cases: AuditCase[] = [
+  {
+    key: 'neutral-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'neutral-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-light',
+    mode: 'light',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-dark',
+    mode: 'dark',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'narrow-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+  {
+    key: 'narrow-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+];
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+  return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+  fs.rmSync(OUTPUT, {recursive: true, force: true});
+  fs.mkdirSync(OUTPUT, {recursive: true});
+  checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+  const expected = process.env.ASTRYX_HEAD_SHA;
+  if (expected && expected !== checkoutSha) {
+    throw new Error(
+      `checkout ${checkoutSha} does not match expected head ${expected}`,
+    );
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!response.ok) {
+    throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+  }
+  storybookSha = (await response.text()).trim();
+  if (storybookSha !== checkoutSha) {
+    throw new Error(
+      `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+    );
+  }
+});
+
+test.afterAll(async () => {
+  await server?.close();
+});
+
+for (const item of cases) {
+  test(item.key, async ({browser}) => {
+    const context = await browser.newContext({
+      viewport: item.viewport,
+      colorScheme: item.mode,
+      reducedMotion: 'reduce',
+    });
+    const page = await context.newPage();
+    const pageErrors: string[] = [];
+    page.on('pageerror', error => pageErrors.push(String(error)));
+    await page.goto(storyUrl(item), {waitUntil: 'load'});
+    await page.locator('#storybook-root').waitFor();
+
+    const menu = page.getByRole('menu').last();
+    await expect(menu).toBeVisible();
+    const groups = menu.getByRole('group');
+    await expect(groups).toHaveCount(2);
+    const namedGroup = menu.getByRole('group', {name: 'Version history'});
+    const unnamedGroup = groups.nth(1);
+    await expect(namedGroup).toBeVisible();
+    await expect(unnamedGroup).not.toHaveAttribute('aria-labelledby');
+    const heading = namedGroup.getByText('Version history', {exact: true});
+    await expect(heading).toBeVisible();
+    const headingId = await heading.getAttribute('id');
+    if (headingId == null) {
+      throw new Error('named group heading has no id');
+    }
+    await expect(namedGroup).toHaveAttribute('aria-labelledby', headingId);
+    await settle(page);
+
+    const menuItems = menu.getByRole('menuitem');
+    await expect(menuItems).toHaveCount(3);
+    await menu.focus();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.first()).toBeFocused();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.nth(1)).toBeFocused();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.last()).toBeFocused();
+    await page.keyboard.press('v');
+    await expect(menuItems.last()).toBeFocused();
+    await expect(namedGroup).not.toBeFocused();
+    await expect(heading).not.toBeFocused();
+
+    const observed = await namedGroup.evaluate(element => {
+      const headingId = element.getAttribute('aria-labelledby');
+      const currentHeading = headingId
+        ? document.getElementById(headingId)
+        : null;
+      const groupBox = element.getBoundingClientRect();
+      const headingBox = currentHeading?.getBoundingClientRect() ?? null;
+      const groupStyle = getComputedStyle(element);
+      const headingStyle = currentHeading
+        ? getComputedStyle(currentHeading)
+        : null;
+      const currentMenu = element.closest('[role="menu"]');
+      const currentGroups = currentMenu?.querySelectorAll('[role="group"]');
+      const currentUnnamed = currentGroups?.item(1) ?? null;
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: groupStyle.direction,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        named: {
+          role: element.getAttribute('role'),
+          labelledBy: headingId,
+          accessibleText: currentHeading?.textContent?.trim() ?? null,
+          headingRole: currentHeading?.getAttribute('role') ?? null,
+          headingTabIndex: currentHeading?.getAttribute('tabindex') ?? null,
+          headingTarget:
+            currentHeading?.classList.contains(
+              'astryx-dropdown-menu-section-heading',
+            ) ?? false,
+        },
+        unnamed: {
+          role: currentUnnamed?.getAttribute('role') ?? null,
+          labelledBy: currentUnnamed?.getAttribute('aria-labelledby') ?? null,
+          ariaLabel: currentUnnamed?.getAttribute('aria-label') ?? null,
+        },
+        geometry: {
+          group: {
+            x: groupBox.x,
+            y: groupBox.y,
+            width: groupBox.width,
+            height: groupBox.height,
+          },
+          heading:
+            headingBox === null
+              ? null
+              : {
+                  x: headingBox.x,
+                  y: headingBox.y,
+                  width: headingBox.width,
+                  height: headingBox.height,
+                },
+        },
+        headingPaint:
+          headingStyle === null
+            ? null
+            : {
+                color: headingStyle.color,
+                fontFamily: headingStyle.fontFamily,
+                fontSize: headingStyle.fontSize,
+                lineHeight: headingStyle.lineHeight,
+                paddingInlineStart: headingStyle.paddingInlineStart,
+                paddingInlineEnd: headingStyle.paddingInlineEnd,
+              },
+      };
+    });
+
+    const semanticsPass =
+      observed.named.role === 'group' &&
+      observed.named.labelledBy !== null &&
+      observed.named.accessibleText === 'Version history' &&
+      observed.named.headingRole === null &&
+      observed.named.headingTabIndex === null &&
+      observed.named.headingTarget &&
+      observed.unnamed.role === 'group' &&
+      observed.unnamed.labelledBy === null &&
+      observed.unnamed.ariaLabel === null;
+    const geometryPass =
+      observed.geometry.group.width > 0 &&
+      observed.geometry.group.height > 0 &&
+      observed.geometry.heading !== null &&
+      observed.geometry.heading.width > 0 &&
+      observed.geometry.heading.height > 0;
+    const paintPass =
+      observed.headingPaint !== null &&
+      observed.headingPaint.color !== 'rgba(0, 0, 0, 0)' &&
+      observed.headingPaint.fontSize !== '0px' &&
+      observed.headingPaint.lineHeight !== '0px' &&
+      observed.headingPaint.paddingInlineStart ===
+        observed.headingPaint.paddingInlineEnd;
+
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: STORY_ID,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        groupCount: await groups.count(),
+        menuItemCount: await menuItems.count(),
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {semanticsPass, geometryPass, paintPass},
+      passed:
+        storybookSha === checkoutSha &&
+        pageErrors.length === 0 &&
+        observed.theme === item.theme &&
+        observed.mode === item.mode &&
+        observed.direction === item.direction &&
+        observed.viewport.width === item.viewport.width &&
+        observed.viewport.height === item.viewport.height &&
+        observed.reducedMotion &&
+        !observed.horizontalOverflow &&
+        observed.fonts === 'loaded' &&
+        (await groups.count()) === 2 &&
+        (await menuItems.count()) === 3 &&
+        semanticsPass &&
+        geometryPass &&
+        paintPass,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    expect(receipt.passed).toBe(true);
+    await context.close();
+  });
+}