@astryxdesign/core 0.7.4 → 0.7.5-canary.0026f37

package/src/Tokenizer/__tests__/TokenizerEndLane.a11y.chromium.spec.ts

@@ -0,0 +1,471 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TokenizerEndLane.a11y.chromium.spec.ts
+ * @input `Core/Tokenizer` and `Core/PowerSearch` stories in a built Storybook.
+ * @output Real-engine proof that tokens, the overflow count and the input's
+ *   text box never paint under the end lane (clear-all and busy indicator),
+ *   across field widths, both writing directions and both overflow modes.
+ * @position Run with `pnpm test:a11y-contract`. The lane is absolutely
+ *   positioned, so whether a token reaches it depends on how rows wrap at a
+ *   given width, which only a shipping layout engine can show.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+type Direction = 'ltr' | 'rtl';
+
+async function open(
+  page: Page,
+  id: string,
+  direction: Direction,
+  args = '',
+): Promise<void> {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${id}&viewMode=story&globals=direction:${direction}${args ? `&args=${args}` : ''}`,
+    {waitUntil: 'load'},
+  );
+  await page
+    .locator('button[aria-label="Clear all"]')
+    .first()
+    .waitFor({state: 'attached'});
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+  });
+}
+
+/**
+ * Sets the story's sizing container to `width` and, for every field with a
+ * visible clear-all lane, returns each visible box that intersects the lane:
+ * tokens, the "+N more" count, and the input's content box (where its text
+ * and caret paint).
+ */
+async function overlapsAt(page: Page, width: number): Promise<string[]> {
+  return page.evaluate(async width => {
+    // The story decorator's fixed-width box; the layer mode's popover takes
+    // its width from the in-flow field inside it.
+    const host = document.querySelector<HTMLElement>(
+      '#storybook-root [style*="width"]',
+    );
+    if (!host) {
+      throw new Error('No sizing container in the story');
+    }
+    host.style.width = `${width}px`;
+    for (let frame = 0; frame < 4; frame++) {
+      await new Promise(resolve => requestAnimationFrame(resolve));
+    }
+
+    const isShown = (el: Element) =>
+      el.checkVisibility({visibilityProperty: true}) &&
+      !el.closest('[aria-hidden="true"]');
+    const lanes = [
+      ...document.querySelectorAll('button[aria-label="Clear all"]'),
+    ]
+      .filter(isShown)
+      .map(clear => clear.parentElement)
+      .filter(lane => lane?.parentElement != null) as HTMLElement[];
+    if (lanes.length === 0) {
+      throw new Error('No clear-all lane is visible');
+    }
+
+    return lanes.flatMap((lane, fieldIndex) => {
+      const field = lane.parentElement as HTMLElement;
+      const boxes: {name: string; rect: DOMRect}[] = [];
+      field.querySelectorAll('.astryx-token').forEach((token, index) => {
+        if (isShown(token)) {
+          boxes.push({
+            name: `token ${index}`,
+            rect: token.getBoundingClientRect(),
+          });
+        }
+      });
+      field.querySelectorAll('span').forEach(span => {
+        if (/^\+\d+ more$/.test(span.textContent ?? '') && isShown(span)) {
+          boxes.push({
+            name: 'overflow count',
+            rect: span.getBoundingClientRect(),
+          });
+        }
+      });
+      const input = field.querySelector<HTMLInputElement>('[role="combobox"]');
+      if (input && isShown(input) && getComputedStyle(input).opacity !== '0') {
+        const style = getComputedStyle(input);
+        const rect = input.getBoundingClientRect();
+        const left = rect.left + parseFloat(style.paddingLeft);
+        const right = rect.right - parseFloat(style.paddingRight);
+        if (right > left) {
+          boxes.push({
+            name: 'input text box',
+            rect: new DOMRect(left, rect.top, right - left, rect.height),
+          });
+        }
+      }
+
+      const laneRect = lane.getBoundingClientRect();
+      return boxes.flatMap(({name, rect}) => {
+        const x =
+          Math.min(rect.right, laneRect.right) -
+          Math.max(rect.left, laneRect.left);
+        const y =
+          Math.min(rect.bottom, laneRect.bottom) -
+          Math.max(rect.top, laneRect.top);
+        return x > 0.5 && y > 0.5
+          ? [
+              `${width}px field ${fieldIndex}: ${name} overlaps the end lane by ${x.toFixed(1)}px`,
+            ]
+          : [];
+      });
+    });
+  }, width);
+}
+
+async function sweep(page: Page, from: number, to: number): Promise<string[]> {
+  const found: string[] = [];
+  for (let width = from; width <= to; width += 4) {
+    found.push(...(await overlapsAt(page, width)));
+  }
+  return found;
+}
+
+/**
+ * The same sweep with a search in flight at every width. The busy Spinner joins
+ * the lane only while a search runs, so each width is measured while the
+ * combobox reports `aria-busy`, typing again whenever the last search settled.
+ */
+async function sweepWhileBusy(
+  page: Page,
+  from: number,
+  to: number,
+): Promise<string[]> {
+  const search = page.getByRole('combobox');
+  const found: string[] = [];
+  for (let width = from; width <= to; width += 4) {
+    for (;;) {
+      if ((await search.getAttribute('aria-busy')) !== 'true') {
+        await search.press('a');
+        await expect(search).toHaveAttribute('aria-busy', 'true');
+      }
+      const overlaps = await overlapsAt(page, width);
+      if ((await search.getAttribute('aria-busy')) === 'true') {
+        found.push(...overlaps);
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Sizes the story container (a pixel width, or `max-content` for a
+ * content-sized field) and returns the field's border box.
+ */
+async function fieldBoxAt(
+  page: Page,
+  width: string,
+): Promise<{width: number; height: number}> {
+  return page.evaluate(async width => {
+    const host = document.querySelector<HTMLElement>(
+      '#storybook-root [style*="width"]',
+    );
+    const field = document.querySelector('button[aria-label="Clear all"]')
+      ?.parentElement?.parentElement;
+    if (!host || !field) {
+      throw new Error('Field or sizing container did not render');
+    }
+    host.style.width = width;
+    for (let frame = 0; frame < 4; frame++) {
+      await new Promise(resolve => requestAnimationFrame(resolve));
+    }
+    const {width: w, height: h} = field.getBoundingClientRect();
+    return {
+      width: Math.round(w * 100) / 100,
+      height: Math.round(h * 100) / 100,
+    };
+  }, width);
+}
+
+/** Adds tokens through the menu, as a person would. */
+async function addTokens(page: Page, names: string[]): Promise<void> {
+  const search = page.getByRole('combobox');
+  for (const name of names) {
+    await search.fill(name.split(' ')[0]);
+    await page.getByRole('option', {name}).click();
+    await expect(search).not.toHaveAttribute('aria-busy', 'true');
+  }
+}
+
+/**
+ * The field's box with a search settled and again with one in flight. The
+ * query is non-empty both times, so only the busy state differs.
+ */
+async function settledAndBusy(
+  page: Page,
+  width: string,
+): Promise<string | null> {
+  const search = page.getByRole('combobox');
+  await search.fill('a');
+  await expect(search).not.toHaveAttribute('aria-busy', 'true');
+  const settled = await fieldBoxAt(page, width);
+  await search.press('b');
+  await expect(search).toHaveAttribute('aria-busy', 'true');
+  const busy = await fieldBoxAt(page, width);
+  const stillBusy = (await search.getAttribute('aria-busy')) === 'true';
+  if (!stillBusy) {
+    throw new Error(`The search settled before ${width} was measured`);
+  }
+  return settled.width === busy.width && settled.height === busy.height
+    ? null
+    : `${width}: settled ${settled.width}x${settled.height}, busy ${busy.width}x${busy.height}`;
+}
+
+/**
+ * With four tokens on the Loading story, every width from 200px to 400px and a
+ * content-sized container where the field's box differs settled vs busy.
+ */
+async function busyLayoutChanges(page: Page, step: number): Promise<string[]> {
+  await addTokens(page, ['Bob Smith', 'Charlie Brown', 'Diana Prince']);
+  await expect(page.locator('.astryx-token')).toHaveCount(4);
+  const changed: string[] = [];
+  for (let width = 200; width <= 400; width += step) {
+    const change = await settledAndBusy(page, `${width}px`);
+    if (change) {
+      changed.push(change);
+    }
+  }
+  // Content-sized: the field may not widen while busy (input-fields FR1).
+  const contentSized = await settledAndBusy(page, 'max-content');
+  if (contentSized) {
+    changed.push(contentSized);
+  }
+  return changed;
+}
+
+/**
+ * The blurred, collapsed field at `width`: its border box, how many tokens
+ * show, and the "+N more" count.
+ */
+async function collapsedRowAt(page: Page, width: string): Promise<string> {
+  const box = await fieldBoxAt(page, width);
+  const row = await page.evaluate(() => {
+    const field = document.querySelector('button[aria-label="Clear all"]')
+      ?.parentElement?.parentElement;
+    if (!field) {
+      throw new Error('Field did not render');
+    }
+    const shown = [...field.querySelectorAll('.astryx-token')].filter(
+      token =>
+        token.checkVisibility({visibilityProperty: true}) &&
+        !token.closest('[aria-hidden="true"]'),
+    ).length;
+    const count = [...field.querySelectorAll('span')].find(span =>
+      /^\+\d+ more$/.test(span.textContent ?? ''),
+    );
+    return `${shown} tokens, ${count?.textContent ?? 'no count'}`;
+  });
+  return `${box.width}x${box.height}, ${row}`;
+}
+
+for (const direction of ['ltr', 'rtl'] as const) {
+  test.describe(direction, () => {
+    test('PowerSearch tokens (custom renderToken) wrap before the end lane', async ({
+      page,
+    }) => {
+      await open(page, 'core-powersearch--near-full-token-row', direction);
+      expect(await sweep(page, 160, 640)).toEqual([]);
+    });
+
+    test('a token wider than the row truncates short of the end lane', async ({
+      page,
+    }) => {
+      await open(page, 'core-tokenizer--long-token-end-lane', direction);
+      expect(await sweep(page, 160, 400)).toEqual([]);
+    });
+
+    test('default Tokenizer tokens wrap before the end lane', async ({
+      page,
+    }) => {
+      await open(
+        page,
+        'core-tokenizer--with-preselected',
+        direction,
+        'hasClear:!true',
+      );
+      expect(await sweep(page, 160, 400)).toEqual([]);
+    });
+
+    test('tokens stay clear of the lane while a search is busy', async ({
+      page,
+    }) => {
+      await open(page, 'core-tokenizer--loading', direction);
+      await page.getByRole('combobox').focus();
+      expect(await sweepWhileBusy(page, 200, 400)).toEqual([]);
+    });
+
+    test('a search starting does not move the field or its token rows', async ({
+      page,
+    }) => {
+      test.setTimeout(240_000);
+      await open(page, 'core-tokenizer--loading', direction);
+      expect(await busyLayoutChanges(page, 4)).toEqual([]);
+    });
+
+    test('the reserved Spinner costs no frames and stays silent while idle', async ({
+      page,
+    }) => {
+      await open(page, 'core-tokenizer--loading', direction);
+      const search = page.getByRole('combobox');
+      const cdp = await page.context().newCDPSession(page);
+      await cdp.send('Performance.enable');
+      // Style recalculations over a short window: a ticking ring animation
+      // recalculates every frame (about 30 in 500ms), an unrendered one does
+      // not. The idle allowance absorbs a stray one-off recalculation.
+      const recalcsOver = async (ms: number) => {
+        const count = async () => {
+          const {metrics} = await cdp.send('Performance.getMetrics');
+          return metrics.find(m => m.name === 'RecalcStyleCount')?.value ?? 0;
+        };
+        const before = await count();
+        await page.waitForTimeout(ms);
+        return (await count()) - before;
+      };
+      const spinnerState = async () =>
+        page.evaluate(() => {
+          const spinner = document
+            .querySelector('button[aria-label="Clear all"]')
+            ?.parentElement?.querySelector('.astryx-spinner');
+          if (!spinner) {
+            throw new Error('The lane holds no Spinner');
+          }
+          return {
+            hidden: spinner.getAttribute('aria-hidden') === 'true',
+            width: spinner.getBoundingClientRect().width,
+          };
+        });
+      const idle = await spinnerState();
+      expect(idle.hidden).toBe(true);
+      expect(await recalcsOver(500)).toBeLessThanOrEqual(2);
+      await search.focus();
+      await search.press('a');
+      await expect(search).toHaveAttribute('aria-busy', 'true');
+      const busy = await spinnerState();
+      expect(busy.hidden).toBe(false);
+      expect(await recalcsOver(500)).toBeGreaterThanOrEqual(10);
+      expect(busy.width).toBe(idle.width);
+    });
+
+    test('the idle Spinner paints nothing, even when a theme styles its box', async ({
+      page,
+    }) => {
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=core-tokenizer--loading&viewMode=story&globals=direction:${direction};astryxTheme:probe`,
+        {waitUntil: 'load'},
+      );
+      await page
+        .locator('button[aria-label="Clear all"]')
+        .waitFor({state: 'attached'});
+      const search = page.getByRole('combobox');
+      const spinnerPaint = async () =>
+        page.evaluate(() => {
+          const spinner = document
+            .querySelector('button[aria-label="Clear all"]')
+            ?.parentElement?.querySelector('.astryx-spinner');
+          if (!spinner) {
+            throw new Error('The lane holds no Spinner');
+          }
+          const style = getComputedStyle(spinner);
+          return {
+            visible: spinner.checkVisibility({visibilityProperty: true}),
+            visibility: style.visibility,
+            background: style.backgroundColor,
+          };
+        });
+      const idle = await spinnerPaint();
+      // The probe theme paints the Spinner's own box, so a box that is only
+      // content-skipped would still show beside Clear all.
+      expect(idle.background).not.toBe('rgba(0, 0, 0, 0)');
+      expect(idle.visibility).toBe('hidden');
+      expect(idle.visible).toBe(false);
+      await search.focus();
+      await search.press('a');
+      await expect(search).toHaveAttribute('aria-busy', 'true');
+      expect((await spinnerPaint()).visible).toBe(true);
+    });
+
+    test('a themed, larger Spinner keeps its space too', async ({page}) => {
+      test.setTimeout(240_000);
+      await open(page, 'core-tokenizer--loading', direction);
+      // The public size var a theme sets for a named Spinner size.
+      await page.addStyleTag({
+        content: '.astryx-spinner { --spinner-diameter: 24px !important; }',
+      });
+      expect(await busyLayoutChanges(page, 8)).toEqual([]);
+    });
+
+    test('a search settling after blur does not change the collapsed row', async ({
+      page,
+    }) => {
+      test.setTimeout(240_000);
+      await open(
+        page,
+        'core-tokenizer--loading',
+        direction,
+        'tokenOverflowBehavior:unfocusedInline',
+      );
+      const search = page.getByRole('combobox');
+      await search.focus();
+      await addTokens(page, ['Bob Smith', 'Charlie Brown', 'Diana Prince']);
+      const changed: string[] = [];
+      for (let width = 200; width <= 400; width += 8) {
+        await search.focus();
+        await search.fill('');
+        await search.press('a');
+        await expect(search).toHaveAttribute('aria-busy', 'true');
+        await search.blur();
+        const busy = await collapsedRowAt(page, `${width}px`);
+        await expect(search).not.toHaveAttribute('aria-busy', 'true');
+        const settled = await collapsedRowAt(page, `${width}px`);
+        if (busy !== settled) {
+          changed.push(`${width}px: busy ${busy}, settled ${settled}`);
+        }
+      }
+      expect(changed).toEqual([]);
+    });
+
+    for (const mode of ['overflow-inline', 'overflow-layer']) {
+      test(`${mode}: blurred and focused tokens stay clear of the end lane`, async ({
+        page,
+      }) => {
+        await open(page, `core-powersearch--${mode}`, direction);
+        // Blurred: only the inline mode keeps its lane on the page.
+        if (mode === 'overflow-inline') {
+          expect(await sweep(page, 320, 640)).toEqual([]);
+        }
+        // The field's own corner, clear of every token: the click a person
+        // makes to start typing, which expands both modes.
+        await page
+          .locator('.astryx-tokenizer')
+          .first()
+          .click({position: {x: 1, y: 1}});
+        await expect(page.getByRole('combobox')).toBeFocused();
+        expect(await sweep(page, 320, 640)).toEqual([]);
+      });
+    }
+  });
+}

package/src/Tokenizer/useEndLaneReserve.ts

@@ -81,8 +81,9 @@ const reserveStyles = stylex.create({
  *
  * Takes the lane's inset from the field's inline-end border, as the CSS
  * expression that positions it. Returns a ref callback for the lane, and the
- * ordinary input reserve style. Tokenizer's compact input reads the same custom
- * property directly so its empty-query hit surface can stop before the lane.
+ * ordinary input reserve style. With tokens, Tokenizer's field wrapper reads the
+ * same custom property directly so every token row, and the input after the
+ * last token, stops before the lane.
  * With no lane mounted the variable is absent and either rule resolves to its
  * no-lane fallback, so neither path needs to know whether a search is running.
  */

package/src/VisuallyHidden/VisuallyHidden.doc.mjs

@@ -23,7 +23,7 @@ export const docs = {
     },
   ],
   usage: {
-    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props; the whole point is to stay invisible.',
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props; the whole point is to stay invisible. `xstyle` is still accepted and ignored, only so code written against 0.7.2 keeps compiling; a planned minor removes it.',
     bestPractices: [
       { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
       { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },

package/src/VisuallyHidden/VisuallyHidden.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {createRef} from 'react';
+import * as stylex from '@stylexjs/stylex';
 import {VisuallyHidden} from './VisuallyHidden';
 
 describe('VisuallyHidden', () => {
@@ -64,6 +65,44 @@ describe('VisuallyHidden', () => {
     expect(el).toHaveAttribute('role', 'status');
   });
 
+  it('does not forward the styling props its own contract omits', () => {
+    // `className` and `style` are off the interface, and they are reached here
+    // through an untyped spread, which is how they get past the `Omit` in
+    // practice: a cast, a `{...consumerProps}` object, or plain JavaScript. The
+    // type is only the first line of defence here.
+    const stylingProps: Record<string, unknown> = {
+      xstyle: {color: 'red'},
+      className: 'consumer-track',
+      style: {position: 'static'},
+    };
+    render(<VisuallyHidden {...stylingProps}>Hidden</VisuallyHidden>);
+    const el = screen.getByText('Hidden');
+
+    // VisuallyHidden documents itself as styling-free and its clip block as
+    // non-overridable, but the implementation spreads leftover props onto the
+    // element: `xstyle` reaches the DOM as the literal string "[object Object]",
+    // and a cast `style` wins the last-word race for `position`, un-hiding the
+    // node (or clipping real content) while keeping the a11y semantics.
+    expect(el).not.toHaveAttribute('xstyle');
+    expect(el.getAttribute('class') ?? '').not.toContain('consumer-track');
+    expect(el.getAttribute('style') ?? '').not.toContain('static');
+  });
+
+  it('still accepts a typed xstyle, and ignores it', () => {
+    // Released 0.7.2 accepted `xstyle` through `BaseProps`, so narrowing it out
+    // of `VisuallyHiddenProps` would make code that compiles today stop
+    // compiling. It stays declared and documented as ignored, and the runtime
+    // drop is what keeps the stray attribute off the element. Written as a typed
+    // prop on purpose: this line is the tripwire if the interface is ever
+    // narrowed early.
+    const overrides = stylex.create({tint: {color: 'red'}});
+    render(<VisuallyHidden xstyle={overrides.tint}>Hidden</VisuallyHidden>);
+    const el = screen.getByText('Hidden');
+
+    expect(el).not.toHaveAttribute('xstyle');
+    expect(el.getAttribute('style') ?? '').not.toContain('color');
+  });
+
   it('gives an icon-only control an accessible name', () => {
     render(
       <button type="button">

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -16,14 +16,23 @@
 
 import {createElement, type ElementType, type ReactNode, type Ref} from 'react';
 import type {BaseProps} from '../BaseProps';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import * as stylex from '@stylexjs/stylex';
 
 /**
  * VisuallyHidden is deliberately styling-free: it exists to *not* be seen, so it
- * intentionally omits `xstyle`/`className`/`style`. The clip block is fixed and
- * non-overridable — styling a visually-hidden node is always a mistake. The
- * accessibility pass-throughs from `BaseProps` (`aria-*`, `role`, `id`,
- * `data-*`, event handlers) remain, since the live-region use case needs them.
+ * omits `className`/`style` and applies a fixed, non-overridable clip block —
+ * styling a visually-hidden node is always a mistake. The accessibility
+ * pass-throughs from `BaseProps` (`aria-*`, `role`, `id`, `data-*`, event
+ * handlers) remain, since the live-region use case needs them.
+ *
+ * `xstyle` stays declared and documented as ignored, because released 0.7.2
+ * accepted it through `BaseProps`: narrowing the interface would force every
+ * consumer to edit code, which is a `[breaking]` change for a planned minor
+ * (`spec:AST-017/FR53`). It carries no `@deprecated` marker either — under
+ * `spec:AST-017/FR28` a patch may only deprecate a surface it ships an exact
+ * migration for, and this fix ships none. Dropping the prop from the interface,
+ * with the migration being to delete it, belongs to a planned minor.
  */
 export interface VisuallyHiddenProps extends Omit<
   BaseProps<HTMLElement>,
@@ -44,6 +53,16 @@ export interface VisuallyHiddenProps extends Omit<
    * @default 'span'
    */
   as?: ElementType;
+
+  /**
+   * Ignored: VisuallyHidden has no styling surface. The clip block is the only
+   * style applied, and nothing a caller passes can displace it.
+   *
+   * Accepted only so that code written against 0.7.2 keeps compiling. It is not
+   * applied to the element, and a planned minor removes it — the migration is to
+   * delete the prop.
+   */
+  xstyle?: StyleXStyles;
 }
 
 const styles = stylex.create({
@@ -90,8 +109,22 @@ export function VisuallyHidden({
   children,
   as: element = 'span',
   ref,
-  ...props
+  ...rest
 }: VisuallyHiddenProps) {
+  // `className` and `style` are off the interface, and the ignored `xstyle`
+  // is off by intent. Take all three back off at runtime so a cast cannot reach
+  // the element either: `xstyle` is not a valid attribute, so spreading it writes
+  // xstyle="[object Object]" into the DOM, and a cast `style` keeps the last word
+  // on `position` and un-hides the node.
+  const {
+    xstyle: _xstyle,
+    className: _className,
+    style: _style,
+    ...props
+  } = rest as typeof rest & {
+    className?: unknown;
+    style?: unknown;
+  };
   return createElement(
     element,
     {