@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/__tests__/pressState.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pressState.ts
+ * @input Uses document.styleSheets (populated by StyleX runtime injection)
+ * @output Exports rulesDeclaredFor and expectPressedArm test helpers
+ * @position Shared test helper for asserting a control paints a pressed state
+ *
+ * jsdom does not compute `:active` (there is no real pointer), so a component
+ * test asserts the next-best thing: that the StyleX dev runtime injected a
+ * rule, keyed to the element's own classes, that paints the design system's
+ * pressed overlay token while the control is pressed. The selector shape is
+ * deliberately not pinned — a press may be read off the element itself
+ * (`.x:active`) or off an ancestor scope marker (`.x:where(.marker:active *)`).
+ *
+ * SYNC: When modified, update this header.
+ */
+
+const PRESSED_TOKEN = '--color-overlay-pressed';
+
+function walk(list: CSSRuleList, visit: (rule: CSSRule) => void): void {
+  for (const rule of Array.from(list)) {
+    visit(rule);
+    const nested = (rule as CSSGroupingRule).cssRules;
+    if (nested != null) {
+      walk(nested, visit);
+    }
+  }
+}
+
+/**
+ * Every injected style rule (rules nested in `@media` included) whose selector
+ * names one of the element's classes, as `selector {declarations}` text.
+ */
+export function rulesDeclaredFor(el: Element): string[] {
+  const classes = el.className
+    .split(/\s+/)
+    .filter(Boolean)
+    .map(name => `.${name}`);
+  const out: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    walk(rules, rule => {
+      if (!(rule instanceof CSSStyleRule)) {
+        return;
+      }
+      const selector = rule.selectorText;
+      if (classes.some(cls => selector.startsWith(cls))) {
+        out.push(`${selector} {${rule.style.cssText}}`);
+      }
+    });
+  }
+  return out;
+}
+
+/** The rules on `el` whose selector matches `pseudo` (e.g. `:active`). */
+export function rulesWithSelector(el: Element, pseudo: string): string[] {
+  return rulesDeclaredFor(el).filter(rule => {
+    const selector = rule.slice(0, rule.indexOf('{'));
+    return selector.includes(pseudo);
+  });
+}
+
+/**
+ * Does one of the element's own rules paint the pressed overlay token while
+ * `pseudo` matches? `pseudo` defaults to `:active`, the arm a mouse press
+ * takes.
+ */
+export function hasPressedArm(el: Element, pseudo = ':active'): boolean {
+  return rulesWithSelector(el, pseudo).some(rule =>
+    rule.includes(PRESSED_TOKEN),
+  );
+}
+
+/**
+ * Does one of the element's own classes paint the pressed overlay token
+ * unconditionally — no pseudo-class, no ancestor scope — because the component
+ * applies the class while it holds the press itself (a dragged slider thumb)?
+ * StyleX's specificity padding (`:not(#\#)`) is not a condition.
+ */
+export function declaresPressedOverlay(el: Element): boolean {
+  return rulesDeclaredFor(el).some(rule => {
+    const selector = rule
+      .slice(0, rule.indexOf('{'))
+      .replaceAll(':not(#\\#)', '');
+    return !selector.includes(':') && rule.includes(PRESSED_TOKEN);
+  });
+}

package/src/hooks/scrollKeyboardDelegation.test.ts

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollKeyboardDelegation.test.ts
+ * @input Private delegation behavior, explicit visibility, and focus event sequences
+ * @output Eligibility, keyboard intent, observer cost, and cleanup regressions
+ * @position DOM-level policy proof; browser tests own native Tab and scroll evidence
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {attachScrollKeyboardDelegation} from './scrollKeyboardDelegation';
+import {FOCUSABLE_SELECTOR} from './focusableSelector';
+
+let detach: (() => void) | undefined;
+let before: HTMLButtonElement;
+let viewport: HTMLDivElement;
+let content: HTMLDivElement;
+
+beforeEach(() => {
+  vi.spyOn(HTMLElement.prototype, 'getClientRects').mockReturnValue([
+    new DOMRect(0, 0, 20, 20),
+  ] as unknown as DOMRectList);
+  before = document.createElement('button');
+  viewport = document.createElement('div');
+  viewport.tabIndex = 0;
+  content = document.createElement('div');
+  viewport.append(content);
+  // The pinned jsdom selector engine orders this comma-separated selector by
+  // selector group. Browsers return document order; normalize only the emulator.
+  const query = content.querySelectorAll.bind(content);
+  vi.spyOn(content, 'querySelectorAll').mockImplementation(selector => {
+    const result = query(selector);
+    return selector === FOCUSABLE_SELECTOR
+      ? ([...result].sort((a, b) =>
+          a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
+            ? -1
+            : 1,
+        ) as unknown as NodeListOf<Element>)
+      : result;
+  });
+  document.body.append(before, viewport);
+  detach = attachScrollKeyboardDelegation(viewport, content);
+});
+
+afterEach(() => {
+  detach?.();
+  before.remove();
+  viewport.remove();
+  vi.restoreAllMocks();
+});
+
+// jsdom supplies no Tab default action. Complete dispatch before focusing to
+// model the browser's event boundary; real traversal is tested in both engines.
+function enter() {
+  before.focus();
+  before.dispatchEvent(
+    new KeyboardEvent('keydown', {key: 'Tab', bubbles: true}),
+  );
+  viewport.focus();
+}
+
+describe('scroll keyboard delegation', () => {
+  it('inspects content only on keyboard entry and leaves mutation observation untouched', () => {
+    content.innerHTML = '<button>Action</button>';
+    const scan = vi.spyOn(content, 'querySelectorAll');
+    const observe = vi.spyOn(MutationObserver.prototype, 'observe');
+    viewport.focus();
+    content.firstElementChild?.setAttribute('data-state', 'changed');
+    viewport.dispatchEvent(new Event('scroll'));
+    expect(scan).not.toHaveBeenCalled();
+    expect(observe).not.toHaveBeenCalled();
+    enter();
+    expect(scan).toHaveBeenCalledTimes(1);
+    expect(document.activeElement).toBe(content.firstElementChild);
+    expect(viewport.tabIndex).toBe(0);
+  });
+
+  it.each([
+    '<input aria-label="Input"><button>Later action</button>',
+    '<button role="radio">Radio</button><button>Later action</button>',
+    '<div role="toolbar"><button>Toolbar action</button></div>',
+    '<div contenteditable="true"><button>Editor action</button></div>',
+    '<button aria-haspopup="menu">Open menu</button>',
+    '<button aria-disabled="true">Unavailable</button>',
+    '<button aria-hidden="true">Hidden from AT</button><button>Later action</button>',
+    '<button>Zero</button><button tabindex="1">Earlier positive stop</button>',
+    '<div tabindex="0">Custom target</div><button>Later action</button>',
+  ])('does not skip an excluded first target: %s', markup => {
+    content.innerHTML = markup;
+    enter();
+    expect(document.activeElement).toBe(viewport);
+  });
+
+  it.each(['disabled', 'hidden', 'tabindex="-2"', 'style="visibility:hidden"'])(
+    'skips a nonsequential target (%s)',
+    attributes => {
+      content.innerHTML = `<button ${attributes}>Skipped</button><button>Action</button>`;
+      enter();
+      expect(document.activeElement).toBe(content.lastElementChild);
+    },
+  );
+
+  it('rechecks ancestor eligibility on the next entry', () => {
+    content.innerHTML = '<div><button>Action</button></div>';
+    enter();
+    expect(document.activeElement).toBe(content.querySelector('button'));
+    content.firstElementChild?.setAttribute('role', 'menu');
+    enter();
+    expect(document.activeElement).toBe(viewport);
+  });
+
+  it('retains programmatic focus during a Tab handler even without preventDefault', () => {
+    content.innerHTML = '<button>Action</button>';
+    before.addEventListener('keydown', () => viewport.focus(), {once: true});
+    before.focus();
+    before.dispatchEvent(
+      new KeyboardEvent('keydown', {key: 'Tab', bubbles: true}),
+    );
+    expect(document.activeElement).toBe(viewport);
+  });
+
+  it('does not retain canceled keyboard intent', () => {
+    content.innerHTML = '<button>Action</button>';
+    before.addEventListener('keydown', event => event.preventDefault(), {
+      once: true,
+    });
+    before.focus();
+    before.dispatchEvent(
+      new KeyboardEvent('keydown', {
+        key: 'Tab',
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    viewport.focus();
+    expect(document.activeElement).toBe(viewport);
+  });
+
+  it('restores the skipped viewport on cancellation and cleans up pending work', () => {
+    content.innerHTML = '<button>Action</button><button>Last</button>';
+    enter();
+    const first = content.firstElementChild as HTMLElement;
+    (content.lastElementChild as HTMLElement).focus();
+    first.focus();
+    first.dispatchEvent(
+      new KeyboardEvent('keydown', {key: 'Tab', shiftKey: true, bubbles: true}),
+    );
+    expect(viewport.tabIndex).toBe(-1);
+    detach?.();
+    detach = undefined;
+    expect(viewport.tabIndex).toBe(0);
+    enter();
+    expect(document.activeElement).toBe(viewport);
+  });
+});

package/src/hooks/scrollKeyboardDelegation.ts

@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollKeyboardDelegation.ts
+ * @input A named, overflowing viewport and its real content box
+ * @output Focus-time delegation with native forward and reverse Tab traversal
+ * @position Private useScrollableArea keyboard behavior; no DOM observers or scrolling
+ */
+
+import {FOCUSABLE_SELECTOR} from './focusableSelector';
+import {getRegisteredScrollOwnerState} from './scrollOwnerRegistry';
+
+// Structural roles may contain ordinary links/buttons. Unknown or interactive
+// roles are deliberately excluded until their navigation contract is proven.
+const PASSIVE_ROLES = new Set([
+  'article',
+  'banner',
+  'complementary',
+  'contentinfo',
+  'definition',
+  'directory',
+  'document',
+  'figure',
+  'form',
+  'generic',
+  'group',
+  'heading',
+  'list',
+  'listitem',
+  'main',
+  'navigation',
+  'none',
+  'note',
+  'paragraph',
+  'presentation',
+  'region',
+  'section',
+  'status',
+  'table',
+  'term',
+]);
+
+function isSequential(element: HTMLElement): boolean {
+  if (
+    element.tabIndex < 0 ||
+    element.matches(':disabled') ||
+    element.closest('[inert], [hidden]') != null ||
+    element.getClientRects().length === 0
+  ) {
+    return false;
+  }
+  const visibility = getComputedStyle(element).visibility;
+  return visibility !== 'hidden' && visibility !== 'collapse';
+}
+
+function firstDelegationTarget(
+  viewport: HTMLElement,
+  content: HTMLElement,
+): HTMLElement | null {
+  const candidates = content.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+  let first =
+    content.matches(FOCUSABLE_SELECTOR) && isSequential(content)
+      ? content
+      : null;
+  for (const candidate of candidates) {
+    // After finding the first target, only positive tabindex can precede it.
+    // Ordinary trailing controls need no visibility or layout reads.
+    if (first != null && candidate.tabIndex <= 0) {
+      continue;
+    }
+    if (!isSequential(candidate)) {
+      continue;
+    }
+    // Positive tabindex participates before the zero-index viewport. Do not
+    // revisit it or skip its ordering by delegating to a later zero-index child.
+    if (candidate.tabIndex > 0) {
+      return null;
+    }
+    first ??= candidate;
+  }
+  if (
+    first == null ||
+    first.tabIndex !== 0 ||
+    !first.matches('a[href], button') ||
+    first.closest('[aria-hidden="true"]') != null ||
+    first.matches(
+      '[aria-disabled="true"], [aria-haspopup]:not([aria-haspopup="false"])',
+    )
+  ) {
+    return null;
+  }
+
+  let ancestor: HTMLElement | null = first;
+  while (ancestor != null && ancestor !== viewport) {
+    const role: string | undefined = ancestor
+      .getAttribute('role')
+      ?.trim()
+      .toLowerCase();
+    const nativeRole: boolean =
+      ancestor === first &&
+      ((role === 'button' && first.localName === 'button') ||
+        (role === 'link' && first.localName === 'a'));
+    if (
+      (role != null &&
+        role !== '' &&
+        !nativeRole &&
+        !PASSIVE_ROLES.has(role)) ||
+      (ancestor === first && role != null && role !== '' && !nativeRole) ||
+      ancestor.hasAttribute('aria-activedescendant') ||
+      ancestor.isContentEditable ||
+      ancestor.matches('[contenteditable]:not([contenteditable="false"])') ||
+      getRegisteredScrollOwnerState(ancestor) != null
+    ) {
+      return null;
+    }
+    // Also respect native scroll owners that have not adopted the shared hook.
+    const style = getComputedStyle(ancestor);
+    if (
+      (/^(auto|scroll|overlay)$/.test(style.overflowX) &&
+        ancestor.scrollWidth > ancestor.clientWidth + 1) ||
+      (/^(auto|scroll|overlay)$/.test(style.overflowY) &&
+        ancestor.scrollHeight > ancestor.clientHeight + 1)
+    ) {
+      return null;
+    }
+    ancestor = ancestor.parentElement;
+  }
+  return ancestor === viewport ? first : null;
+}
+
+/** Attach only while automatic ownership has an effective scroll axis. */
+export function attachScrollKeyboardDelegation(
+  viewport: HTMLElement,
+  content: HTMLElement,
+): () => void {
+  const document = viewport.ownerDocument;
+  const window = document.defaultView;
+  if (window == null) {
+    return () => {};
+  }
+  let entry: KeyboardEvent | null = null;
+  let origin: EventTarget | null = null;
+  let delegated: HTMLElement | null = null;
+  let timer: number | undefined;
+  let restoreTabStop: (() => void) | undefined;
+
+  const reset = () => {
+    entry = null;
+    origin = null;
+    window.clearTimeout(timer);
+    restoreTabStop?.();
+    restoreTabStop = undefined;
+  };
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    reset();
+    if (event.key !== 'Tab' || event.ctrlKey || event.metaKey) {
+      return;
+    }
+    // Keep the actual event: focus() during keydown is programmatic (nonzero
+    // eventPhase), whereas native Tab focus follows completed event dispatch.
+    entry = event;
+    origin = event.target;
+    if (
+      event.shiftKey &&
+      delegated != null &&
+      document.activeElement === delegated &&
+      viewport.contains(delegated)
+    ) {
+      const tabIndex = viewport.getAttribute('tabindex');
+      viewport.tabIndex = -1;
+      restoreTabStop = () => {
+        if (viewport.getAttribute('tabindex') === '-1') {
+          if (tabIndex == null) {
+            viewport.removeAttribute('tabindex');
+          } else {
+            viewport.setAttribute('tabindex', tabIndex);
+          }
+        }
+      };
+    }
+    // A canceled Tab, focus leaving the document, or a held key must not leave
+    // stale keyboard intent for a later pointer/programmatic focus operation.
+    timer = window.setTimeout(reset, 0);
+  };
+
+  const onFocusIn = (event: FocusEvent) => {
+    const keyboardEntry = entry;
+    const previous = origin;
+    reset();
+    if (event.target !== viewport) {
+      if (!viewport.contains(event.target as Node | null)) {
+        delegated = null;
+      }
+      return;
+    }
+    delegated = null;
+    if (
+      keyboardEntry == null ||
+      keyboardEntry.shiftKey ||
+      keyboardEntry.defaultPrevented ||
+      keyboardEntry.eventPhase !== 0 ||
+      (event.relatedTarget != null && event.relatedTarget !== previous)
+    ) {
+      return;
+    }
+    const target = firstDelegationTarget(viewport, content);
+    if (target == null) {
+      return;
+    }
+    delegated = target;
+    // Let native focus reveal the action. Arrow/Page scrolling remains entirely
+    // browser-owned, including scroll chaining and the full viewport range.
+    target.focus();
+    if (document.activeElement !== target) {
+      delegated = null;
+    }
+  };
+
+  document.addEventListener('keydown', onKeyDown, true);
+  document.addEventListener('keyup', reset, true);
+  document.addEventListener('pointerdown', reset, true);
+  document.addEventListener('focusin', onFocusIn, true);
+  window.addEventListener('blur', reset);
+  return () => {
+    reset();
+    document.removeEventListener('keydown', onKeyDown, true);
+    document.removeEventListener('keyup', reset, true);
+    document.removeEventListener('pointerdown', reset, true);
+    document.removeEventListener('focusin', onFocusIn, true);
+    window.removeEventListener('blur', reset);
+  };
+}

package/src/hooks/useScrollableArea.doc.mjs

@@ -1,5 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/**
+ * @file useScrollableArea.doc.mjs
+ * @input Shared scroll hook's fixed and entry-time keyboard policies
+ * @output Consumer guidance for named viewports and safe focus delegation
+ * @position Hook documentation consumed by the CLI and docsite
+ */
+
 /** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useScrollableArea',
@@ -18,7 +25,7 @@ export const docs = {
       name: 'options',
       type: 'UseScrollableAreaOptions',
       description:
-        'Logical scroll intent, keyboard owner, overscroll policy, and fitting Sticky containment.',
+        'Logical scroll intent, fixed or automatic keyboard owner, overscroll policy, and fitting Sticky containment.',
       required: true,
     },
   ],
@@ -59,7 +66,12 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use content keyboard ownership when an existing focusable descendant gives keyboard users access to all overflowed content.',
+          'Use contentOrViewport to delegate forward Tab entry to the first sequential native link or button when it preserves native scroll keys. Inputs, composite widgets, and nested scroll areas retain the named viewport stop. Shift+Tab from the delegated first child skips the viewport; pointer and programmatic focus stay on it.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use content keyboard ownership when your integration already supplies keyboard access to the full scroll range. Automatic delegation checks current content at each keyboard entry without continuously tracking its focusability.',
       },
       {
         guidance: true,
@@ -85,7 +97,7 @@ export const docsDense = {
     'Composes logical-axis scrolling into caller-owned viewport/content elements with stable effective-axis and edge state.',
   paramDescriptions: {
     options:
-      'axis, keyboard owner, allow/contain overscroll policy, and fitting Sticky containment.',
+      'axis, fixed/automatic keyboard owner, allow/contain overscroll policy, and fitting Sticky containment.',
   },
   returnDescriptions: {
     getViewportProps:

package/src/hooks/useScrollableArea.test.tsx

@@ -1,8 +1,15 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/**
+ * @file useScrollableArea.test.tsx
+ * @input Shared scroll hook, mocked geometry, and observed DOM changes
+ * @output Regression coverage for measurement, composition, and stable viewport access
+ * @position DOM-level hook contract; native traversal is verified in browser tests
+ */
+
 import {act, render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
-import {useRef, type Ref} from 'react';
+import {useRef, type ReactNode, type Ref} from 'react';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import {
   useScrollableArea,
@@ -194,6 +201,57 @@ describe('useScrollableArea', () => {
     expect(viewport.getAttribute('style')).toContain('--x-overflowY: hidden');
   });
 
+  it('keeps the named viewport available while content eligibility changes', () => {
+    function AdaptiveFixture({children}: {children?: ReactNode}) {
+      const area = useScrollableArea({
+        axis: 'block',
+        keyboardAccess: {
+          owner: 'contentOrViewport',
+          label: 'Adaptive results',
+          role: 'region',
+        },
+      });
+      return (
+        <div data-testid="adaptive-viewport" {...area.getViewportProps()}>
+          <div data-testid="adaptive-content" {...area.getContentProps()}>
+            {children}
+          </div>
+        </div>
+      );
+    }
+
+    vi.spyOn(HTMLElement.prototype, 'getClientRects').mockReturnValue([
+      new DOMRect(0, 0, 20, 20),
+    ] as unknown as DOMRectList);
+    const {rerender} = render(<AdaptiveFixture>Plain text</AdaptiveFixture>);
+    const viewport = screen.getByTestId('adaptive-viewport');
+    const content = screen.getByTestId('adaptive-content');
+    makeMeasurable(viewport);
+    setGeometry(viewport, {scrollHeight: 180});
+
+    void act(() => viewport.dispatchEvent(new Event('scroll')));
+    flushFrame();
+    expect(viewport).toHaveAttribute('role', 'region');
+    expect(viewport).toHaveAccessibleName('Adaptive results');
+    expect(viewport).toHaveAttribute('tabindex', '0');
+
+    viewport.focus();
+    rerender(
+      <AdaptiveFixture>
+        <button type="button">Use existing action</button>
+      </AdaptiveFixture>,
+    );
+    void act(() => content.dispatchEvent(new Event('transitionend')));
+    flushFrame();
+    expect(viewport).toHaveAttribute('tabindex', '0');
+    expect(viewport).toHaveFocus();
+
+    rerender(<AdaptiveFixture>Plain text again</AdaptiveFixture>);
+    void act(() => content.dispatchEvent(new Event('transitionend')));
+    flushFrame();
+    expect(viewport).toHaveAttribute('tabindex', '0');
+  });
+
   it('requires scroll-capable computed overflow and more than 1px excess geometry', () => {
     render(<Fixture />);
     const viewport = screen.getByTestId('viewport');