@astryxdesign/core 0.6.1 → 0.6.2-canary.2b2113d

package/src/Spinner/Spinner.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Spinner.tsx
- * @input Uses React, StyleX, SVG rendering
+ * @input Uses React, i18n (useTranslator), StyleX, SVG rendering
  * @output Exports Spinner component, SpinnerProps, SpinnerSize, SpinnerShade types
  * @position Core implementation of spinner loading indicator
  *
@@ -22,6 +22,7 @@ import {colorVars, durationVars, spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Text} from '../Text/Text';
 import {mergeProps} from '../utils';
+import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -29,20 +30,17 @@ import {themeProps} from '../utils/themeProps';
 // =============================================================================
 
 /**
- * Fraction of the ring the moving arc covers. The canvas ring this replaces
- * swept 135deg, not the 270deg its constant's comment claimed.
+ * Default fraction of the ring the moving arc covers. The canvas ring this
+ * replaces swept 135deg, not the 270deg its constant's comment claimed.
+ *
+ * Themeable via `--spinner-arc-fraction`, declared alongside the other public
+ * vars in `sizeStyles` below. Only the inline `strokeDasharray` attribute
+ * (the pre-stylesheet render — see its own comment) still reads this
+ * constant directly; the CSS side composes the dash from the live var.
  */
 const ARC_FRACTION = 0.375;
 
-/**
- * The dash pattern, per unit of diameter: one arc, then the gap that closes
- * the circle. The circumference is `pi x diameter`, so multiplying the
- * resolved diameter by these two constants gives exactly the lengths the
- * default render has always used, and scales them with a themed diameter.
- */
 const PI = 3.141592653589793;
-const ARC_DASH = PI * ARC_FRACTION;
-const ARC_GAP = PI * (1 - ARC_FRACTION);
 
 const SIZES = {
   sm: {diameter: 10, border: 2},
@@ -322,10 +320,16 @@ const styles = stylex.create({
   // of the circle — 87.398 against the 87.965 of pi x 28 — which shortens the
   // default arc by 0.64% and moves the cap by half a pixel. Composing the
   // lengths keeps the default byte-identical to what it drew before.
+  //
+  // The fraction itself also rides a public var (`--spinner-arc-fraction`),
+  // unregistered like the other three color/geometry public vars — it is
+  // read as a bare `<number>` multiplier here, never summed with a unitless
+  // `0` the way the registered length pair guards against, so it needs no
+  // registration.
   arc: {
     stroke: 'var(--spinner-color)',
     transform: 'rotate(-90deg)',
-    strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${ARC_DASH}) calc(var(${RESOLVED_DIAMETER}) * ${ARC_GAP})`,
+    strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${PI} * var(--spinner-arc-fraction)) calc(var(${RESOLVED_DIAMETER}) * ${PI} * (1 - var(--spinner-arc-fraction)))`,
   },
   track: {stroke: 'var(--spinner-track-color)'},
 });
@@ -348,22 +352,30 @@ const styles = stylex.create({
 // cost of its own — with nothing declaring the var,
 // `theme-var-reachability.js` cannot find an element to check, so a documented
 // var reads as unreachable.
+// Arc fraction is not itself size-dependent, but it declares alongside the
+// two vars that are, on the same per-size condition (`!hasLabel` gate at the
+// call site) — it needs a home on whichever element carries the theme
+// target, and this is the object already wired to be there.
 const sizeStyles = stylex.create({
   sm: {
     '--spinner-diameter': `${SIZES.sm.diameter}px`,
     '--spinner-stroke-width': `${SIZES.sm.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
   md: {
     '--spinner-diameter': `${SIZES.md.diameter}px`,
     '--spinner-stroke-width': `${SIZES.md.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
   lg: {
     '--spinner-diameter': `${SIZES.lg.diameter}px`,
     '--spinner-stroke-width': `${SIZES.lg.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
   xl: {
     '--spinner-diameter': `${SIZES.xl.diameter}px`,
     '--spinner-stroke-width': `${SIZES.xl.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
 });
 
@@ -484,6 +496,7 @@ export function Spinner({
   const arcLength = circumference * ARC_FRACTION;
   const hasLabel = label != null;
   const labelId = useId();
+  const t = useTranslator();
 
   // When a visible string label renders (and no explicit aria-label is set),
   // name the status element from the visible Text via aria-labelledby instead
@@ -492,9 +505,13 @@ export function Spinner({
   const namedByVisibleLabel =
     hasLabel && typeof label === 'string' && ariaLabel == null;
 
-  // Resolve accessible name: explicit aria-label > string label > "Loading"
+  // Resolve accessible name: explicit aria-label > string label > the
+  // localized default. The fallback is AT-facing text, so it goes through the
+  // translation runtime like visible text does.
   const resolvedAriaLabel =
-    ariaLabel ?? (typeof label === 'string' ? label : undefined) ?? 'Loading';
+    ariaLabel ??
+    (typeof label === 'string' ? label : undefined) ??
+    t('@astryx.spinner.loading');
 
   const spinner = (
     <span

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