@astryxdesign/core 0.6.1 → 0.6.2-canary.176dfa6

package/src/Typeahead/BaseTypeahead.tsx

@@ -533,9 +533,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // Debounce ref
   const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // Monotonic counter incremented on selection and query-clear. Async
-  // searches that resolve after a selection compare their captured
-  // generation to the current value and discard stale results.
+  // Monotonic counter incremented on selection, query-clear, and source
+  // replacement. Async searches that resolve afterwards compare their
+  // captured generation to the current value and discard stale results.
   const searchGenRef = useRef(0);
   // The generation at which results were last populated. handleFocus
   // compares this to searchGenRef — if they differ, the cached results
@@ -543,6 +543,15 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // be re-shown.
   const resultsGenRef = useRef(0);
 
+  // Results still arriving from a replaced source must not land in the new
+  // one's menu.
+  const prevSearchSourceRef = useRef(searchSource);
+  if (prevSearchSourceRef.current !== searchSource) {
+    prevSearchSourceRef.current.cancel?.();
+    prevSearchSourceRef.current = searchSource;
+    searchGenRef.current++;
+  }
+
   // Layer for dropdown
   const handleLayerShow = useCallback(() => {
     onOpenChange?.(true);
@@ -987,15 +996,15 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   const selectedKey =
     value == null ? null : getKey(value.id, () => results.indexOf(value));
 
-  // Cleanup timeout and cancel in-flight searches on unmount
+  // Unmount: clear the pending debounce and cancel in-flight work.
   useEffect(() => {
     return () => {
       if (searchTimeoutRef.current) {
         clearTimeout(searchTimeoutRef.current);
       }
-      searchSource.cancel?.();
+      prevSearchSourceRef.current.cancel?.();
     };
-  }, [searchSource]);
+  }, []);
 
   return (
     <>

package/src/Typeahead/Typeahead.test.tsx

@@ -574,6 +574,59 @@ describe('Typeahead', () => {
       expect(screen.getByText('Apple')).toBeInTheDocument();
       expect(screen.queryByText('Avocado')).not.toBeInTheDocument();
     });
+
+    it('discards a response from a source that was replaced while it was in flight', async () => {
+      let resolveOld: ((items: SearchableItem[]) => void) | null = null;
+      const oldSource: SearchSource = {
+        search: async () =>
+          new Promise<SearchableItem[]>(resolve => {
+            resolveOld = resolve;
+          }),
+        bootstrap: () => [],
+      };
+      const newSource: SearchSource = {
+        search: () => [{id: 'banana', label: 'Banana'}],
+        bootstrap: () => [],
+      };
+
+      const {rerender} = render(
+        <Typeahead
+          label="Fruit"
+          searchSource={oldSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'a'}});
+      await waitFor(() => expect(resolveOld).not.toBeNull());
+
+      // The source is swapped while the old search is still pending and no
+      // new query is typed. The stale response must not populate a menu that
+      // now reads from a different source.
+      rerender(
+        <Typeahead
+          label="Fruit"
+          searchSource={newSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      await act(async () => {
+        resolveOld!([{id: 'apple', label: 'Apple'}]);
+      });
+      expect(screen.queryByText('Apple')).not.toBeInTheDocument();
+
+      // Work started against the new source still lands normally.
+      fireEvent.change(input, {target: {value: 'ba'}});
+      await waitFor(() =>
+        expect(screen.getByText('Banana')).toBeInTheDocument(),
+      );
+    });
   });
 
   it('renders with label', () => {

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');