@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/Table/Table.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {act, render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {BaseTable} from './BaseTable';
 import {Table} from './Table';
@@ -837,22 +837,95 @@ describe('Table', () => {
     expect(screen.getAllByRole('row')).toHaveLength(4);
   });
 
-  it('wraps table in a scroll container', () => {
+  it('wraps the table in an observed scroll content box', () => {
     render(<Table data={users} columns={columns} />);
     const table = screen.getByRole('table');
-    const wrapper = table.parentElement;
+    const content = table.parentElement;
+    const wrapper = content?.parentElement;
+    expect(content).toHaveAttribute('data-scroll-content');
     expect(wrapper).toBeTruthy();
     expect(wrapper!.className).toContain('astryx-table-scroll-wrapper');
   });
 
-  it('makes the scroll container keyboard-focusable', () => {
+  it('keeps a fitting scroll container out of the keyboard order', () => {
     render(<Table data={users} columns={columns} />);
-    const table = screen.getByRole('table');
-    const wrapper = table.parentElement;
-    expect(wrapper).toBeTruthy();
-    expect(wrapper!).toHaveAttribute('tabindex', '0');
-    expect(wrapper!).toHaveAttribute('role', 'group');
-    expect(wrapper!).toHaveAttribute('aria-label', 'Table');
+    const wrapper = screen.getByRole('group', {name: 'Table'});
+    expect(wrapper).not.toHaveAttribute('tabindex');
+    expect(wrapper.style.overscrollBehaviorX).toBe('auto');
+  });
+
+  it('preserves scroll-wrapper HTML attributes from plugins', () => {
+    const plugin: TablePlugin<User> = {
+      transformScrollWrapper: props => ({
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          role: 'region',
+          'aria-label': 'Orders',
+          tabIndex: 2,
+        },
+      }),
+    };
+    render(<Table data={users} columns={columns} plugins={{custom: plugin}} />);
+    const wrapper = screen.getByRole('region', {name: 'Orders'});
+    expect(wrapper).toHaveAttribute('tabindex', '2');
+  });
+
+  it('contains overscroll only while the table scrolls', () => {
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn((callback: FrameRequestCallback) => {
+        frames.push(callback);
+        return frames.length;
+      }),
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+
+    try {
+      render(<Table data={users} columns={columns} />);
+      const wrapper = screen.getByRole('group', {name: 'Table'});
+      Object.assign(wrapper.style, {overflowX: 'auto'});
+      for (const [key, value] of Object.entries({
+        clientWidth: 100,
+        clientHeight: 100,
+        scrollWidth: 180,
+        scrollHeight: 100,
+        scrollLeft: 0,
+        scrollTop: 0,
+      })) {
+        Object.defineProperty(wrapper, key, {
+          configurable: true,
+          value,
+          writable: true,
+        });
+      }
+
+      act(() => {
+        wrapper.dispatchEvent(new Event('scroll'));
+        frames.splice(0).forEach(callback => callback(performance.now()));
+      });
+
+      expect(wrapper).toHaveAttribute('tabindex', '0');
+      expect(wrapper).toHaveAttribute('data-scrollable-inline', 'true');
+      expect(wrapper.style.overscrollBehaviorX).toBe('contain');
+
+      Object.defineProperty(wrapper, 'scrollWidth', {
+        configurable: true,
+        value: 100,
+        writable: true,
+      });
+      act(() => {
+        wrapper.dispatchEvent(new Event('scroll'));
+        frames.splice(0).forEach(callback => callback(performance.now()));
+      });
+
+      expect(wrapper).not.toHaveAttribute('tabindex');
+      expect(wrapper).not.toHaveAttribute('data-scrollable-inline');
+      expect(wrapper.style.overscrollBehaviorX).toBe('auto');
+    } finally {
+      vi.unstubAllGlobals();
+    }
   });
 
   it('uses table-layout: auto in children mode', () => {

package/src/Table/Table.tsx

@@ -11,6 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Table/Table.doc.mjs (props table, features, usage examples)
  * - /packages/core/src/Table/Table.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts (browser scroll behavior)
  * - /packages/core/src/Table/index.ts (exports if types change)
  * - /apps/storybook/stories/Table.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
@@ -22,6 +23,7 @@ import {colorVars} from '../theme/tokens.stylex';
 import {BaseTable} from './BaseTable';
 import {TableContext} from './TableContext';
 import {useBaseTablePlugins} from './useBaseTablePlugins';
+import {useScrollableArea} from '../hooks/useScrollableArea';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import type {
@@ -149,30 +151,36 @@ function TableScrollWrapper({
   afterTable?: React.ReactNode;
 }) {
   const t = useTranslator();
+  const label = t('@astryx.table.label');
+  const {getViewportProps, getContentProps, state} = useScrollableArea({
+    axis: 'inline',
+    keyboardAccess: {owner: 'content'},
+    overscroll: 'contain',
+  });
   const {ref, ...restHtmlProps} = htmlProps ?? {};
+  const viewportProps = getViewportProps<HTMLDivElement>({
+    role: 'group',
+    'aria-label': label,
+    ...(state.inline.isScrollable ? {tabIndex: 0} : {}),
+    ...restHtmlProps,
+    ref,
+    ...mergeProps(
+      themeProps('table-scroll-wrapper'),
+      stylex.props(
+        scrollWrapperStyles.base,
+        scrollWrapperStyles.containerBleed,
+        ...(pluginStyles ?? []),
+      ),
+    ),
+  });
+
   return (
-    <div
-      ref={ref}
-      // Keyboard-focusable so keyboard users can scroll a horizontally
-      // overflowing table. Uses role="group" (not "region") so multiple
-      // tables on a page don't create duplicate same-named landmarks
-      // (axe: landmark-unique). Callers may override role/aria-label via
-      // htmlProps.
-      tabIndex={0}
-      role="group"
-      aria-label={t('@astryx.table.label')}
-      {...restHtmlProps}
-      {...mergeProps(
-        themeProps('table-scroll-wrapper'),
-        stylex.props(
-          scrollWrapperStyles.base,
-          scrollWrapperStyles.containerBleed,
-          ...(pluginStyles ?? []),
-        ),
-      )}>
-      {beforeTable}
-      {children}
-      {afterTable}
+    <div {...viewportProps}>
+      <div {...getContentProps<HTMLDivElement>()}>
+        {beforeTable}
+        {children}
+        {afterTable}
+      </div>
     </div>
   );
 }

package/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts

@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TableScroll.a11y.chromium.spec.ts
+ * @input Built responsive Table story and real Chromium wheel input
+ * @output Browser evidence for conditional inline containment and scroll chaining
+ * @position Table integration proof for the shared useScrollableArea behavior
+ */
+
+import {expect, test, type Locator, 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();
+});
+
+async function mount(page: Page) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-table--responsive-scroll&viewMode=story`,
+  );
+  const wrappers = page.locator('.astryx-table-scroll-wrapper');
+  await expect(wrappers).toHaveCount(3);
+  return wrappers;
+}
+
+async function putInsideOuterScroller(
+  page: Page,
+  viewport: Locator,
+  viewportWidth: number,
+  contentWidth: number,
+  tableWidth: number,
+) {
+  await viewport.evaluate(
+    (node, sizes) => {
+      const outer = document.createElement('div');
+      outer.dataset.tableScrollOuter = '';
+      outer.style.inlineSize = `${sizes.viewportWidth}px`;
+      outer.style.overflowX = 'auto';
+      const content = document.createElement('div');
+      content.style.inlineSize = `${sizes.contentWidth}px`;
+      node.parentElement?.insertBefore(outer, node);
+      outer.append(content);
+      content.append(node);
+      (node as HTMLElement).style.inlineSize = `${sizes.tableWidth}px`;
+    },
+    {viewportWidth, contentWidth, tableWidth},
+  );
+  return page.locator('[data-table-scroll-outer]');
+}
+
+async function wheelInline(page: Page, target: Locator) {
+  const box = await target.boundingBox();
+  if (box == null) {
+    throw new Error('Table scroll viewport has no rendered bounds');
+  }
+  await page.mouse.move(box.x + Math.min(box.width / 2, 100), box.y + 20);
+  await page.mouse.wheel(200, 0);
+}
+
+test('an overflowing table contains horizontal wheel input at its edge', async ({
+  page,
+}) => {
+  const wrappers = await mount(page);
+  const tableViewport = wrappers.nth(0);
+  await tableViewport.locator('table').evaluate(table => {
+    const viewport = table.closest<HTMLElement>('.astryx-table-scroll-wrapper');
+    if (viewport != null) {
+      table.style.minWidth = `${viewport.clientWidth + 400}px`;
+    }
+  });
+  await expect(tableViewport).toHaveAttribute('data-scrollable-inline', 'true');
+  await expect(tableViewport).toHaveAttribute('tabindex', '0');
+  await expect
+    .poll(async () =>
+      tableViewport.evaluate(
+        element => getComputedStyle(element).overscrollBehaviorX,
+      ),
+    )
+    .toBe('contain');
+
+  const outer = await putInsideOuterScroller(
+    page,
+    tableViewport,
+    320,
+    800,
+    320,
+  );
+  await tableViewport.evaluate(element => {
+    element.scrollLeft = element.scrollWidth - element.clientWidth;
+  });
+  await wheelInline(page, tableViewport);
+  await expect
+    .poll(async () => outer.evaluate(element => element.scrollLeft))
+    .toBe(0);
+});
+
+test('a fitting table passes horizontal wheel input to its outer scroller', async ({
+  page,
+}) => {
+  const wrappers = await mount(page);
+  const tableViewport = wrappers.nth(2);
+  const outer = await putInsideOuterScroller(
+    page,
+    tableViewport,
+    320,
+    800,
+    800,
+  );
+
+  await expect(tableViewport).not.toHaveAttribute(
+    'data-scrollable-inline',
+    'true',
+  );
+  await expect(tableViewport).not.toHaveAttribute('tabindex');
+  await expect
+    .poll(async () =>
+      tableViewport.evaluate(
+        element => getComputedStyle(element).overscrollBehaviorX,
+      ),
+    )
+    .toBe('auto');
+
+  await wheelInline(page, tableViewport);
+  await expect
+    .poll(async () => outer.evaluate(element => element.scrollLeft))
+    .toBeGreaterThan(0);
+});

package/src/TextArea/TextArea.tsx

@@ -95,9 +95,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-1'],
     paddingInline: 'var(--_textarea-inline-padding)',
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/TextInput/TextInput.test.tsx

@@ -2,7 +2,8 @@
 
 /**
  * @file TextInput.test.tsx
- * @input Uses vitest, @testing-library/react, TextInput component
+ * @input Uses vitest, @testing-library/react, TextInput component, and the
+ *   shared declaredValue StyleX read-back helper
  * @output Unit tests for TextInput component behavior
  * @position Testing; validates TextInput.tsx implementation
  *
@@ -13,6 +14,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
+import {declaredValue} from '../__tests__/stylexDeclarations';
 import {InputGroup} from '../InputGroup';
 import {TextInput} from './TextInput';
 
@@ -1113,3 +1115,20 @@ describe('TextInput clear button focus behavior', () => {
     rafSpy.mockRestore();
   });
 });
+
+describe('TextInput text size', () => {
+  it('renders the theme body size outside the iOS zoom gate', () => {
+    // The 16px floor rides `@supports (-webkit-touch-callout: none)` inside
+    // `@media (pointer: coarse)` — iOS Safari is the browser that zooms on
+    // focus under 16px, so the floor targets it alone instead of every
+    // coarse pointer. jsdom's CSSOM drops at-rule-wrapped declarations it
+    // cannot parse, so the gate itself is pinned against the sources in
+    // inputFontFloor.test.ts; what this asserts is the visible result off
+    // the gate: the plain token size, not a floor.
+    render(<TextInput label="Name" value="" onChange={() => {}} />);
+    expect(declaredValue(screen.getByLabelText('Name'), 'font-size')).toBe(
+      'var(--text-body-size)',
+    );
+  });
+});
+

package/src/TextInput/TextInput.tsx

@@ -58,9 +58,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/TimeInput/TimeInput.tsx

@@ -95,9 +95,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/Timer/Timer.doc.mjs

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Elapsed time',
+    required: true,
+    description:
+      'Semantic time element containing a standardized elapsed duration.',
+  },
+];
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docs = {
+  name: 'Timer',
+  displayName: 'Timer',
+  category: 'Content',
+  keywords: [
+    'timer',
+    'elapsed',
+    'duration',
+    'seconds',
+    'minutes',
+    'hours',
+    'stopwatch',
+    'waiting',
+    'loading',
+    'processing',
+  ],
+  props: [
+    {
+      name: 'startTime',
+      type: 'number',
+      description:
+        "Unix time in milliseconds when the measured operation began. Omit it to start from this Timer's mount.",
+    },
+    {
+      name: 'format',
+      type: "'elapsed' | 'clock'",
+      description:
+        'Standard duration representation. Elapsed uses compact units and drops seconds after one hour; clock uses m:ss or h:mm:ss.',
+      default: "'elapsed'",
+    },
+    {
+      name: 'type',
+      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
+      description:
+        'Semantic text type. Uses the same typography behavior as Timestamp.',
+      default: "'supporting'",
+    },
+    {
+      name: 'size',
+      type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
+      description: 'Explicit font size override. Overrides the size from type.',
+    },
+    {
+      name: 'color',
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
+      description: 'Text color.',
+      default: "'secondary'",
+    },
+    {
+      name: 'weight',
+      type: "'normal' | 'medium' | 'semibold' | 'bold'",
+      description: 'Font weight override.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for the Text wrapper. Must be a stylex.create() value.',
+    },
+    {
+      name: 'className',
+      type: 'string',
+      description:
+        'CSS class name for the Text wrapper. Prefer xstyle for styling.',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        'Inline styles for the Text wrapper. Prefer xstyle for styling.',
+    },
+  ],
+  examples: [
+    {
+      label: 'Elapsed duration',
+      code: '<Timer />',
+    },
+    {
+      label: 'Stopwatch clock',
+      code: '<Timer format="clock" />',
+    },
+    {
+      label: 'Operation that started before mount',
+      code: '<Timer startTime={operationStartedAt} />',
+    },
+    {
+      label: 'Match surrounding text',
+      code: `<Text>
+  Processing for <Timer type="inherit" color="inherit" />
+</Text>`,
+    },
+    {
+      label: 'Prominent elapsed time',
+      code: '<Timer type="body" size="lg" color="primary" weight="semibold" />',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-timer'}],
+  },
+  usage: {
+    anatomy,
+    description:
+      'Displays a standardized elapsed duration for active work without scheduling a React render on every tick. Elapsed format updates by second below one hour and by minute after one hour; clock format remains second-precise.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use elapsed for compact duration text that may span seconds, minutes, or hours.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use clock for stopwatch-like surfaces where seconds remain meaningful after an hour.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass startTime when the operation began before Timer mounted so the display reflects the complete wait.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not use Timer for dates, time zones, or relative calendar language; use Timestamp instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not add aria-live unless hearing an announcement every tick is appropriate for the specific task.',
+      },
+    ],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description:
+    'Standardized elapsed or stopwatch duration with clock-derived, non-rendering DOM updates.',
+  propDescriptions: {
+    startTime:
+      "operation start as Unix milliseconds; omit to count from Timer's mount",
+    format: 'elapsed compact units or clock stopwatch notation',
+    type: 'semantic text type; defaults to supporting like Timestamp',
+    size: 'explicit font size override',
+    color: 'text color; defaults to secondary like Timestamp',
+    weight: 'font weight override',
+    xstyle: 'StyleX styles for the Text wrapper',
+    className: 'CSS class for the Text wrapper',
+    style: 'inline styles for the Text wrapper',
+  },
+  usage: {
+    anatomy,
+    description:
+      'Use for active-operation elapsed time when periodic React renders would add avoidable work.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use elapsed for compact durations and clock for stopwatch UI.',
+      },
+      {
+        guidance: true,
+        description: 'Pass startTime for work that began before mount.',
+      },
+      {
+        guidance: false,
+        description: 'Use Timestamp for dates and relative calendar language.',
+      },
+    ],
+  },
+};