@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts

@@ -0,0 +1,296 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FieldLabelAudit.a11y.chromium.spec.ts
+ * @input Exact-head FieldLabel story across semantics, themes, direction, and viewport sizes
+ * @output Screenshots and fail-closed sensor receipts for the FieldLabel whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a FieldLabel 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('field-label-audit-evidence');
+const WIDE = {width: 1024, height: 900};
+const NARROW = {width: 320, height: 900};
+
+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};
+};
+
+type AuditReceipt = {
+  passed: boolean;
+  expected: Record<string, unknown>;
+};
+
+const cases: AuditCase[] = [];
+function addPair(
+  key: string,
+  options: Partial<Omit<AuditCase, 'key' | 'mode'>> = {},
+) {
+  for (const mode of ['light', 'dark'] as const) {
+    cases.push({
+      key: `${key}-${mode}`,
+      mode,
+      direction: options.direction ?? 'ltr',
+      theme: options.theme ?? 'neutral',
+      viewport: options.viewport ?? WIDE,
+    });
+  }
+}
+
+addPair('default');
+addPair('custom-theme', {theme: 'butter'});
+addPair('rtl', {direction: 'rtl'});
+addPair('narrow', {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=core-fieldlabel--states&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 targets = page.locator('.astryx-field-label');
+    await expect(targets).toHaveCount(7);
+    await expect(page.locator('label[for="field-label-default"]')).toHaveText(
+      'Email',
+    );
+    const description = page.locator('#field-label-description-help');
+    await expect(description).toHaveText(
+      'Shown in navigation and invitations.',
+    );
+    await expect(description.locator('xpath=ancestor::label')).toHaveCount(0);
+    await expect(page.locator('#field-label-group-label')).toHaveJSProperty(
+      'tagName',
+      'SPAN',
+    );
+    await expect(
+      page.getByRole('radiogroup', {name: 'Visibility'}),
+    ).toBeVisible();
+    await expect(page.getByText(/Required/)).toBeVisible();
+    await expect(page.getByText(/Optional/)).toBeVisible();
+    await expect(page.getByLabel('Search')).toBeVisible();
+    const tooltipAnchor = page
+      .locator('label[for="field-label-optional"] [aria-describedby]')
+      .first();
+    await expect(tooltipAnchor).toHaveCount(1);
+
+    await settle(page);
+    const observed = await page.evaluate(() => {
+      const labels = Array.from(
+        document.querySelectorAll<HTMLElement>('.astryx-field-label'),
+      ).map(label => {
+        const style = getComputedStyle(label);
+        const box = label.getBoundingClientRect();
+        return {
+          text: label.textContent?.replace(/\s+/g, ' ').trim(),
+          tagName: label.tagName,
+          htmlFor: label.getAttribute('for'),
+          color: style.color,
+          cursor: style.cursor,
+          geometry: {x: box.x, y: box.y, width: box.width, height: box.height},
+        };
+      });
+      const hidden = document.querySelector<HTMLElement>(
+        'label[for="field-label-hidden"]',
+      );
+      const hiddenBox = hidden?.getBoundingClientRect();
+      const firstLabel = document.querySelector<HTMLElement>(
+        '.astryx-field-label',
+      );
+      const currentTooltipAnchor = document.querySelector<HTMLElement>(
+        'label[for="field-label-optional"] [aria-describedby]',
+      );
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: firstLabel ? getComputedStyle(firstLabel).direction : null,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        labels,
+        hiddenGeometry: hiddenBox
+          ? {width: hiddenBox.width, height: hiddenBox.height}
+          : null,
+        tooltipAnchor: currentTooltipAnchor
+          ? {
+              ariaHidden: currentTooltipAnchor.getAttribute('aria-hidden'),
+              ariaLabel: currentTooltipAnchor.getAttribute('aria-label'),
+              describedBy:
+                currentTooltipAnchor.getAttribute('aria-describedby'),
+              tabIndex: currentTooltipAnchor.getAttribute('tabindex'),
+            }
+          : null,
+      };
+    });
+
+    const semanticsPass =
+      observed.labels.length === 7 &&
+      observed.labels.filter(label => label.tagName === 'SPAN').length === 1 &&
+      observed.labels.every(label => label.geometry.width > 0) &&
+      observed.hiddenGeometry?.width === 1 &&
+      observed.hiddenGeometry.height === 1;
+    const knownTooltipGapObserved =
+      observed.tooltipAnchor?.ariaHidden === 'true' &&
+      observed.tooltipAnchor.ariaLabel == null &&
+      observed.tooltipAnchor.tabIndex == null;
+
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: 'core-fieldlabel--states',
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+        targetCount: 7,
+        groupLabelTag: 'SPAN',
+        hiddenGeometry: {width: 1, height: 1},
+        knownGap:
+          'the tooltip anchor is anonymous and nonfocusable on this audited head',
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {semanticsPass, knownTooltipGapObserved},
+      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' &&
+        semanticsPass,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    await context.close();
+  });
+}
+
+test('manifest is complete', async () => {
+  const receiptFiles = fs
+    .readdirSync(OUTPUT)
+    .filter(file => file.endsWith('.sensors.json'));
+  const receipts = receiptFiles.map(
+    (file): AuditReceipt =>
+      JSON.parse(
+        fs.readFileSync(path.join(OUTPUT, file), 'utf8'),
+      ) as AuditReceipt,
+  );
+  fs.writeFileSync(
+    path.join(OUTPUT, 'manifest.json'),
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        component: 'core/FieldLabel',
+        build: checkoutSha,
+        frames: cases.map(item => ({
+          key: item.key,
+          image: `${item.key}.png`,
+          receipt: `${item.key}.sensors.json`,
+        })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  expect(receiptFiles).toHaveLength(cases.length);
+  expect(
+    receipts
+      .filter(receipt => !receipt.passed)
+      .map(receipt => receipt.expected),
+  ).toEqual([]);
+});

package/src/Grid/GridSpan.tsx

@@ -47,6 +47,9 @@ const baseStyles = stylex.create({
     minWidth: 0, // Prevent overflow in grid
     // Make span fill grid cell and stretch children
     display: 'grid',
+    // The implicit `auto` column would grow to a child's min-content width;
+    // a zero minimum keeps it inside the span.
+    gridTemplateColumns: 'minmax(0, 1fr)',
     height: '100%',
   },
 });

package/src/Heading/Heading.test.tsx

@@ -269,3 +269,60 @@ describe('Heading', () => {
     expect(element).not.toHaveAttribute('data-type', 'editorial');
   });
 });
+
+// With hasTruncateTooltip={false} nothing reads the measured overflow, so a
+// long table of truncated cells must not pay a layout read per cell.
+function countScrollWidthReads(run: () => void): number {
+  const proto = window.HTMLElement.prototype;
+  const original = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');
+  let reads = 0;
+  Object.defineProperty(proto, 'scrollWidth', {
+    configurable: true,
+    get() {
+      reads += 1;
+      return 0;
+    },
+  });
+  try {
+    run();
+  } finally {
+    if (original) {
+      Object.defineProperty(proto, 'scrollWidth', original);
+    } else {
+      delete (proto as {scrollWidth?: number}).scrollWidth;
+    }
+  }
+  return reads;
+}
+
+describe('Heading maxLines without a truncation tooltip', () => {
+  it('takes no truncation measurement when hasTruncateTooltip is false', () => {
+    const reads = countScrollWidthReads(() => {
+      render(
+        <>
+          {Array.from({length: 20}, (_, index) => (
+            <Heading
+              level={3}
+              maxLines={1}
+              hasTruncateTooltip={false}
+              key={index}>
+              Cell {index} with text far wider than its column
+            </Heading>
+          ))}
+        </>,
+      );
+    });
+    expect(reads).toBe(0);
+  });
+
+  it('still measures when the tooltip is enabled', () => {
+    const reads = countScrollWidthReads(() => {
+      render(
+        <Heading level={3} maxLines={1}>
+          Text far wider than its column
+        </Heading>,
+      );
+    });
+    expect(reads).toBeGreaterThan(0);
+  });
+});

package/src/Heading/Heading.tsx

@@ -253,8 +253,12 @@ export function Heading({
   // the closed built-in StyleX maps with an unknown name.
   const builtinType = type && isBuiltinHeadingType(type) ? type : undefined;
 
-  // Truncation detection
-  const truncation = useTruncation({maxLines});
+  // Truncation detection. Only the tooltip reads the measured overflow, so
+  // with the tooltip off the text is clipped by CSS alone and nothing is
+  // measured or observed.
+  const truncation = useTruncation({
+    maxLines: hasTruncateTooltip === false ? 0 : maxLines,
+  });
 
   // Tooltip for truncated text
   const tooltipPlacement: LayerPlacement =

package/src/HoverCard/HoverCard.test.tsx

@@ -109,6 +109,64 @@ describe('useHoverCard identity', () => {
   });
 });
 
+// A card closed while the pointer rests on it unmounts without a mouseleave,
+// so the hook must not keep believing the pointer is over the card: if it
+// does, the next open of the same trigger never closes on leave.
+describe('useHoverCard closing while the pointer is on the card', () => {
+  function Harness() {
+    const card = useHoverCard({delay: 0, hideDelay: 0});
+    return (
+      <div>
+        <span ref={card.ref}>Trigger</span>
+        <output data-testid="state">{card.isOpen ? 'open' : 'closed'}</output>
+        {card.renderHoverCard(
+          <button type="button" onClick={card.hide}>
+            Pick
+          </button>,
+        )}
+      </div>
+    );
+  }
+
+  async function openThenRestOnCard() {
+    const state = screen.getByTestId('state');
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    const pick = screen.getByRole('button', {name: 'Pick', hidden: true});
+    fireEvent.mouseLeave(screen.getByText('Trigger'));
+    fireEvent.mouseEnter(pick.parentElement!);
+    return {state, pick};
+  }
+
+  async function expectNextOpenClosesOnLeave(state: HTMLElement) {
+    const trigger = screen.getByText('Trigger');
+    fireEvent.mouseEnter(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    fireEvent.mouseLeave(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+  }
+
+  it('closes the next open on leave after hide() from inside the card', async () => {
+    render(<Harness />);
+    const {state, pick} = await openThenRestOnCard();
+
+    fireEvent.click(pick);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+
+  it('closes the next open on leave after Escape dismisses the card', async () => {
+    render(<Harness />);
+    const {state} = await openThenRestOnCard();
+
+    fireEvent.keyDown(document.body, {key: 'Escape'});
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+});
+
 describe('HoverCard', () => {
   it('renders trigger element', () => {
     render(

package/src/HoverCard/useHoverCard.tsx

@@ -345,6 +345,14 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
+  // The imperative hide. A card closed while the pointer rests on it unmounts
+  // without a mouseleave, so the content-hover latch is cleared here; left set,
+  // it would keep the trigger's next hover-open from closing on leave.
+  const hide = useCallback(() => {
+    isHoveringContentRef.current = false;
+    hideLayer();
+  }, [hideLayer]);
+
   const {
     isTouchPointerRef,
     isTouchInteraction,
@@ -508,7 +516,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           ? null
           : document.getElementById(layerId);
       const hadFocus = card?.contains(document.activeElement) ?? false;
-      hideLayer();
+      hide();
       if (hadFocus) {
         isEscapeDismissingRef.current = true;
         triggerRef.current?.focus();
@@ -720,6 +728,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     isOpen: isLayerOpen,
     renderHoverCard,
     show: showLayer,
-    hide: hideLayer,
+    hide,
   };
 }

package/src/Icon/Icon.doc.mjs

@@ -23,6 +23,42 @@ export const docs = {
     'pictogram',
     'graphic',
     'vector',
+    'arrow',
+    'chevron',
+    'caret',
+    'checkmark',
+    'cross',
+    'gear',
+    'cog',
+    'broom',
+    'sparkle',
+    'sparkles',
+    'star',
+    'heart',
+    'bell',
+    'trash',
+    'pencil',
+    'magnifyingglass',
+    'paperclip',
+    'house',
+    'flame',
+    'rocket',
+    'lightning',
+    'bolt',
+    'globe',
+    'sun',
+    'moon',
+    'bookmark',
+    'thumbsup',
+    'smiley',
+    'emoji',
+    'lock',
+    'eye',
+    'cloud',
+    'hourglass',
+    'trophy',
+    'gift',
+    'camera',
   ],
   playground: {
     // `icon` is required and its type can't be auto-generated, so the

package/src/IconButton/IconButton.doc.mjs

@@ -46,7 +46,7 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and disables interaction.',
+      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
@@ -141,7 +141,7 @@ export const docsDense = {
     variant: 'visual style variant',
     size: 'size variant',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner + disables interaction',
+    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
     isDisabled: 'disables button',
     tooltip: 'tooltip text shown on hover',
     onClick: 'standard click handler',

package/src/IconButton/IconButton.test.tsx

@@ -124,7 +124,9 @@ describe('IconButton', () => {
   it('shows loading state', () => {
     render(<IconButton label="Save" icon={<span>💾</span>} isLoading />);
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('forwards ref correctly', () => {

package/src/Item/Item.doc.mjs

@@ -49,7 +49,7 @@ export const docs = {
       {
         name: '--_item-inset-inline',
         description:
-          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to cancel the inset when edgeCompensation="inline". Set paddingInline on `item` in a theme and both stay in sync.',
+          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to place rows for its edge treatments (edge="flush", "outset", and "bleed"). Set paddingInline on `item` in a theme and both stay in sync.',
         default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")',
         private: true,
       },
@@ -118,8 +118,9 @@ export const docs = {
         },
         {
           name: 'align',
-          type: "'center' | 'start'",
-          description: 'Vertical alignment of start/end content slots.',
+          type: "'center' | 'start' | 'first-line'",
+          description:
+            "Vertical alignment of start/end content slots. 'center' centers each slot on the whole text block; 'start' lines up slot tops with the text's top; 'first-line' centers each slot on the label's first line, so a small mark stays level with the first line of a wrapped label. A slot taller than that line moves the text down. The `item` theme target reflects the value as `align`.",
           default: "'center'",
         },
         {
@@ -248,7 +249,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use align="start" when start or end content is taller than a single line of text.',
+          'Use align="first-line" when a wrapping label sits beside a small mark (a status dot, a radio, a timestamp) that belongs to its first line. Use align="start" to line up the tops of a tall slot and the text.',
       },
       {
         guidance: true,
@@ -321,7 +322,8 @@ export const docsZh = {
         endContent:
           '在标签/描述区域之后渲染的内容，例如徽章、元数据、时间戳或操作按钮。',
         as: '根元素的 HTML 元素。',
-        align: '起始/结束内容插槽的垂直对齐方式。',
+        align:
+          "起始/结束内容插槽的垂直对齐方式：'center'（默认）、'start'（顶部对齐）或 'first-line'（以标签第一行为中心）。",
         density:
           '间距密度。"compact" 使用 4px 块内距，"balanced" 使用 8px，"spacious" 使用 12px 块内距和内联内距。',
         labelLines: '标签截断前的最大行数。',
@@ -363,7 +365,8 @@ export const docsZh = {
       },
       {
         guidance: true,
-        description: '当起始或结束内容高于单行文本时使用 align="start"。',
+        description:
+          '当换行标签旁边是属于其第一行的小标记（状态点、单选按钮、时间戳）时，使用 align="first-line"。使用 align="start" 让较高插槽与文本顶部对齐。',
       },
       {
         guidance: false,
@@ -426,7 +429,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'align="start" when start/end content is taller than one text line.',
+          'align="first-line" for a small mark beside a wrapping label; align="start" to top-align a tall slot with the text.',
       },
       {
         guidance: false,
@@ -458,7 +461,8 @@ export const docsDense = {
         endContent:
           'Content after label/description: badges, timestamps, actions.',
         as: 'Root HTML element.',
-        align: 'Vertical alignment of start/end content slots.',
+        align:
+          "Start/end slot alignment: 'center' (default), 'start' (tops), or 'first-line' (centered on the label's first line).",
         density:
           'Spacing: "compact" (4px), "balanced" (8px), or "spacious" (12px).',
         labelLines: 'Max label lines before truncation.',