@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/TreeList/__tests__/TreeList.a11y.states.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TreeList.a11y.states.ts
+ * @input TreeList's representative tree-view states and the facts TREE_VIEW_PATTERN reads
+ * @output TREE_LIST_BINDING_STATES, the shared item data, and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test, the Chromium spec, and the story (component:TreeList AR1)
+ */
+
+import type {TreeViewStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface TreeListBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** `data-tree-id` of the subject row. */
+  readonly subject: string;
+  /** `data-tree-id` of each relation row the facts say exists. */
+  readonly relations: Readonly<
+    Partial<
+      Record<
+        'first-child' | 'parent' | 'next' | 'previous' | 'typeahead-target',
+        string
+      >
+    >
+  > & {readonly first: string; readonly last: string};
+  readonly facts: TreeViewStateFacts;
+  /** Which parent rows start expanded. */
+  readonly expanded: ReadonlyArray<string>;
+  /** Which rows are disabled. */
+  readonly disabled?: ReadonlyArray<string>;
+  readonly direction?: 'ltr' | 'rtl';
+}
+
+export const TREE_LIST_LABEL = 'Files';
+
+function facts(
+  overrides: Partial<TreeViewStateFacts> = {},
+): TreeViewStateFacts {
+  return {
+    hasChildren: true,
+    expanded: false,
+    disabled: false,
+    tabbable: true,
+    level: 1,
+    position: 1,
+    setSize: 3,
+    hasNext: true,
+    hasPrevious: false,
+    hasParent: false,
+    rtl: false,
+    typeaheadCharacter: 't',
+    enterToggles: true,
+    ...overrides,
+  };
+}
+
+const story = (id: string) => `a11y-treelist-tree-view--${id}`;
+
+export const TREE_LIST_BINDING_STATES = [
+  {
+    id: 'closed-parent-tab-stop',
+    summary: "the closed Documents parent, the tree's one Tab stop",
+    storyId: story('closed-parent-tab-stop'),
+    subject: 'docs',
+    relations: {
+      next: 'photos',
+      first: 'docs',
+      last: 'trash',
+      'first-child': 'annual',
+      'typeahead-target': 'trash',
+    },
+    facts: facts(),
+    expanded: [],
+  },
+  {
+    id: 'open-parent-tab-stop',
+    summary: 'the open Documents parent with its child group',
+    storyId: story('open-parent-tab-stop'),
+    subject: 'docs',
+    relations: {
+      next: 'annual',
+      first: 'docs',
+      last: 'trash',
+      'first-child': 'annual',
+      'typeahead-target': 'trash',
+    },
+    facts: facts({expanded: true}),
+    expanded: ['docs'],
+  },
+  {
+    id: 'end-node',
+    summary: 'the Photos end node, which is not the Tab stop',
+    storyId: story('end-node'),
+    subject: 'photos',
+    relations: {
+      next: 'trash',
+      previous: 'docs',
+      first: 'docs',
+      last: 'trash',
+      'typeahead-target': 'docs',
+    },
+    facts: facts({
+      hasChildren: false,
+      tabbable: false,
+      position: 2,
+      hasPrevious: true,
+      typeaheadCharacter: 'd',
+      enterToggles: false,
+    }),
+    expanded: [],
+  },
+  {
+    id: 'closed-parent-rtl',
+    summary: 'the closed Documents parent in a right-to-left tree',
+    storyId: story('closed-parent-rtl'),
+    subject: 'docs',
+    relations: {
+      next: 'photos',
+      first: 'docs',
+      last: 'trash',
+      'first-child': 'annual',
+      'typeahead-target': 'trash',
+    },
+    facts: facts({rtl: true}),
+    expanded: [],
+    direction: 'rtl',
+  },
+  {
+    id: 'disabled-end-node',
+    summary:
+      'the disabled Trash end node: exposed and positioned, not operable',
+    storyId: story('disabled-end-node'),
+    subject: 'trash',
+    relations: {previous: 'photos', first: 'docs', last: 'trash'},
+    facts: facts({
+      hasChildren: false,
+      disabled: true,
+      tabbable: false,
+      position: 3,
+      hasNext: false,
+      hasPrevious: true,
+      typeaheadCharacter: null,
+      enterToggles: false,
+    }),
+    expanded: [],
+    disabled: ['trash'],
+  },
+] as const satisfies ReadonlyArray<TreeListBindingState>;
+
+export const TREE_LIST_EXCLUSIONS = [
+  {
+    id: 'row-name-composition',
+    owner: 'component:TreeList AR1 and TreeList.test.tsx',
+    reason:
+      "This binding proves each row has a treeitem role and a non-empty name. Which text makes up that name — the label alone, without the chevron toggle, description, or start and end content — is the record's row-naming requirement, proven by TreeList's own name tests and browser evidence rather than by the shared pattern.",
+  },
+  {
+    id: 'selection-keyboard',
+    owner: 'component:TreeList AR1 and DEC-2',
+    reason:
+      'Selection is caller-owned (isSelected) with at most one row selected; the tree adopts no selection keyboard (Shift or Control combinations; Space is activation, covered by the contract) and not the optional * key, so the contract asserts only that the tree makes no multiselect claim.',
+  },
+] as const;

package/src/TreeList/__tests__/TreeList.a11y.test.tsx

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file TreeList.a11y.test.tsx
+ * @input TREE_VIEW_PATTERN bound to TreeList's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for component:TreeList AR1 (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TREE_VIEW_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderTreeListState} from './TreeList.a11y.renders';
+import {
+  TREE_LIST_BINDING_STATES,
+  TREE_LIST_EXCLUSIONS,
+  type TreeListBindingState,
+} from './TreeList.a11y.states';
+
+function row(id: string): Element {
+  const element = document.querySelector(
+    `[role="treeitem"][data-tree-id="${id}"]`,
+  );
+  if (element == null) {
+    throw new Error(`no treeitem row "${id}"`);
+  }
+  return element;
+}
+
+function relatedFor(
+  state: TreeListBindingState,
+): Readonly<Record<string, Element>> {
+  const related: Record<string, Element> = {
+    tree: screen.getByRole('tree'),
+    before: screen.getByRole('button', {name: 'Before the tree'}),
+    after: screen.getByRole('button', {name: 'After the tree'}),
+  };
+  for (const [name, id] of Object.entries(state.relations)) {
+    const element = document.querySelector(
+      `[role="treeitem"][data-tree-id="${id}"]`,
+    );
+    if (element != null) {
+      related[name] = element;
+    }
+  }
+  const group = row(state.subject).querySelector('[role="group"]');
+  if (group != null) {
+    related.group = group;
+  }
+  return related;
+}
+
+async function checkState(state: TreeListBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TREE_VIEW_PATTERN,
+    binding: 'TreeList',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderTreeListState(state));
+      return createJsdomHarness({
+        subject: row(state.subject),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('TreeList — tree-view pattern, jsdom lane', () => {
+  it.each(
+    TREE_LIST_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TREE_VIEW_PATTERN,
+      binding: 'TreeList',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderTreeListState(state));
+      },
+      subject: () => row(state.subject),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TREE_LIST_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TREE_VIEW_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('TreeList tree-view binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TREE_LIST_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps row-name composition and selection ownership explicit', () => {
+    expect(TREE_LIST_EXCLUSIONS.map(exclusion => exclusion.id)).toEqual([
+      'row-name-composition',
+      'selection-keyboard',
+    ]);
+    for (const exclusion of TREE_LIST_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the subject row, the tree, and the first/last rows for every state', () => {
+    for (const state of TREE_LIST_BINDING_STATES) {
+      render(renderTreeListState(state));
+      expect(row(state.subject), state.id).toBeTruthy();
+      const related = relatedFor(state);
+      expect(Object.keys(related), state.id).toEqual(
+        expect.arrayContaining(['tree', 'before', 'after', 'first', 'last']),
+      );
+      cleanup();
+    }
+  });
+});

package/src/TreeList/__tests__/TreeListRowNames.a11y.chromium.spec.ts

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TreeListRowNames.a11y.chromium.spec.ts
+ * @input The built TreeList row-names story in real Chromium
+ * @output Proof that the browser names every treeitem by its label alone and describes it by its description — the chevron toggle and inner link/button do not leak into the row's name
+ * @position Chromium evidence for component:TreeList AR1 (component:TreeList's row-naming implementation gap, closed)
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const STORY_ID = 'a11y-treelist-row-names--row-names';
+
+const ROWS = [
+  {id: 'docs', name: 'Documents', description: 'Shared with the team'},
+  // Carries start content and an end-content button: neither joins the name.
+  {id: 'budget', name: 'Budget', description: 'Updated yesterday'},
+  {id: 'report', name: 'Report', description: 'Opens the report'},
+  {id: 'export', name: 'Export', description: 'Downloads a file'},
+] as const;
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+async function mount(page: Page): Promise<void> {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${STORY_ID}&viewMode=story`,
+    {waitUntil: 'load'},
+  );
+  await holdMotionStill(page);
+  await page.locator('[role="tree"]').waitFor({state: 'attached'});
+}
+
+for (const row of ROWS) {
+  test(`the browser names the "${row.name}" row by its label and describes it by its description`, async ({
+    page,
+  }) => {
+    await mount(page);
+    const cdp = await page.context().newCDPSession(page);
+    const harness = createChromiumHarness({
+      page,
+      cdp,
+      subject: page.locator(`[role="treeitem"][data-tree-id="${row.id}"]`),
+    });
+    const computed = await (await harness.subject()).computed();
+    expect(computed.role).toBe('treeitem');
+    expect(computed.name).toBe(row.name);
+    expect(computed.description).toBe(row.description);
+  });
+}
+
+test('typing a letter matches the label, so a row whose text begins with start content is reachable', async ({
+  page,
+}) => {
+  await mount(page);
+  const docsRow = page.locator('[role="treeitem"][data-tree-id="docs"]');
+  await docsRow.focus();
+  // The Budget row's text begins with its start content ("3"), so a
+  // whole-text match never finds it under "b"; the label match does.
+  await page.keyboard.press('b');
+  await expect(
+    page.locator('[role="treeitem"][data-tree-id="budget"]'),
+  ).toBeFocused();
+});

package/src/hooks/useScrollOverflow.test.tsx

@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useScrollOverflow.test.tsx
+ * @input Uses vitest, @testing-library/react, useScrollOverflow
+ * @output Unit tests for the hook's measurement and its rendered-only gate
+ * @position Testing; jsdom lays nothing out, so the scroll box is faked and
+ *   `checkVisibility` is stubbed per element.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {act, renderHook} from '@testing-library/react';
+import {useScrollOverflow} from './useScrollOverflow';
+
+// jsdom has no ResizeObserver. This one hands the test the shared observer's
+// callback so a resize can be delivered on demand; the registration-time
+// measurement comes from `observeResize` itself.
+let deliverResize: ((entries: ResizeObserverEntry[]) => void) | null = null;
+
+class FakeResizeObserver implements ResizeObserver {
+  constructor(callback: ResizeObserverCallback) {
+    deliverResize = entries => callback(entries, this);
+  }
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn();
+}
+
+// The shared observer reads only `target` off an entry.
+function resizeEntry(target: Element): ResizeObserverEntry {
+  return {target} as unknown as ResizeObserverEntry;
+}
+
+type Reads = {scrollWidth: number; clientWidth: number; scrollLeft: number};
+
+// Fakes an overflowing scroll box and counts every layout read on it.
+function fakeScrollBox(
+  el: HTMLElement,
+  box: {scrollWidth: number; clientWidth: number; scrollLeft?: number},
+): Reads {
+  const reads: Reads = {scrollWidth: 0, clientWidth: 0, scrollLeft: 0};
+  const values: Reads = {scrollLeft: 0, ...box};
+  for (const name of Object.keys(reads) as (keyof Reads)[]) {
+    Object.defineProperty(el, name, {
+      configurable: true,
+      get() {
+        reads[name] += 1;
+        return values[name];
+      },
+    });
+  }
+  return reads;
+}
+
+function totalReads(reads: Reads): number {
+  return reads.scrollWidth + reads.clientWidth + reads.scrollLeft;
+}
+
+function stubRendered(el: HTMLElement, rendered: boolean | undefined) {
+  Object.defineProperty(el, 'checkVisibility', {
+    configurable: true,
+    value: rendered === undefined ? undefined : () => rendered,
+  });
+}
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', FakeResizeObserver);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  deliverResize = null;
+});
+
+describe('useScrollOverflow', () => {
+  it('measures a rendered container when the ref attaches', () => {
+    const el = document.createElement('div');
+    const reads = fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
+    stubRendered(el, true);
+    const {result, unmount} = renderHook(() => useScrollOverflow());
+
+    act(() => {
+      result.current.scrollRef(el);
+    });
+
+    expect(result.current.hasOverflow).toBe(true);
+    expect(result.current.overflowStart).toBe(false);
+    expect(result.current.overflowEnd).toBe(true);
+    expect(totalReads(reads)).toBeGreaterThan(0);
+    unmount();
+  });
+
+  it('reads no layout while the container is not rendered', () => {
+    const el = document.createElement('div');
+    const reads = fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
+    stubRendered(el, false);
+    const {result, unmount} = renderHook(() => useScrollOverflow());
+
+    act(() => {
+      result.current.scrollRef(el);
+    });
+    // A resize delivered for the hidden box (a `display: none` or a
+    // `content-visibility: hidden` ancestor reports a zero box) is skipped
+    // too; a scroll is not (the next case).
+    act(() => {
+      deliverResize?.([resizeEntry(el)]);
+    });
+
+    expect(totalReads(reads)).toBe(0);
+    expect(result.current.hasOverflow).toBe(false);
+    expect(result.current.overflowEnd).toBe(false);
+    unmount();
+  });
+
+  it('keeps the last state while hidden and measures again on the reveal', () => {
+    const el = document.createElement('div');
+    const reads = fakeScrollBox(el, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 150,
+    });
+    stubRendered(el, true);
+    const {result, unmount} = renderHook(() => useScrollOverflow());
+
+    act(() => {
+      result.current.scrollRef(el);
+    });
+    expect(result.current.overflowStart).toBe(true);
+    expect(result.current.overflowEnd).toBe(true);
+
+    stubRendered(el, false);
+    const readsBeforeHide = totalReads(reads);
+    act(() => {
+      deliverResize?.([resizeEntry(el)]);
+    });
+    expect(totalReads(reads)).toBe(readsBeforeHide);
+    expect(result.current.overflowStart).toBe(true);
+    expect(result.current.overflowEnd).toBe(true);
+
+    // Revealed at the end edge with a new size: the resize that follows the
+    // reveal measures (a reveal at the same size has no resize, and relies on
+    // the scroll having been measured: the next case).
+    stubRendered(el, true);
+    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300, scrollLeft: 300});
+    act(() => {
+      deliverResize?.([resizeEntry(el)]);
+    });
+    expect(result.current.overflowStart).toBe(true);
+    expect(result.current.overflowEnd).toBe(false);
+    unmount();
+  });
+
+  it('measures a scroll while hidden, so a reveal at the same size is already right', () => {
+    const el = document.createElement('div');
+    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
+    stubRendered(el, true);
+    const {result, unmount} = renderHook(() => useScrollOverflow());
+
+    act(() => {
+      result.current.scrollRef(el);
+    });
+    expect(result.current.overflowStart).toBe(false);
+    expect(result.current.overflowEnd).toBe(true);
+
+    // Hidden, then scrolled by script to the end edge (a selected tab's
+    // reveal under a hidden panel): the scroll is measured.
+    stubRendered(el, false);
+    const scrolled = fakeScrollBox(el, {
+      scrollWidth: 600,
+      clientWidth: 300,
+      scrollLeft: 300,
+    });
+    act(() => {
+      el.dispatchEvent(new Event('scroll'));
+    });
+    expect(totalReads(scrolled)).toBeGreaterThan(0);
+    expect(result.current.overflowStart).toBe(true);
+    expect(result.current.overflowEnd).toBe(false);
+
+    // Revealed at the same size: no resize observation comes, and none is
+    // needed.
+    stubRendered(el, true);
+    expect(result.current.overflowStart).toBe(true);
+    expect(result.current.overflowEnd).toBe(false);
+    unmount();
+  });
+
+  it('measures in a browser without checkVisibility', () => {
+    const el = document.createElement('div');
+    const reads = fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
+    stubRendered(el, undefined);
+    const {result, unmount} = renderHook(() => useScrollOverflow());
+
+    act(() => {
+      result.current.scrollRef(el);
+    });
+
+    expect(result.current.hasOverflow).toBe(true);
+    expect(totalReads(reads)).toBeGreaterThan(0);
+    unmount();
+  });
+
+  it('follows a scroll on a rendered container', () => {
+    const el = document.createElement('div');
+    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
+    stubRendered(el, true);
+    const {result, unmount} = renderHook(() => useScrollOverflow());
+
+    act(() => {
+      result.current.scrollRef(el);
+    });
+    expect(result.current.overflowStart).toBe(false);
+
+    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300, scrollLeft: 300});
+    act(() => {
+      el.dispatchEvent(new Event('scroll'));
+    });
+    expect(result.current.overflowStart).toBe(true);
+    expect(result.current.overflowEnd).toBe(false);
+    unmount();
+  });
+});