@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Layer/LayerProvider.spec.md

@@ -0,0 +1,149 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:LayerProvider
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-28
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout]
+verified_by:
+  [
+    packages/core/src/Layer/LayerProvider.test.tsx,
+    apps/storybook/stories/Layer.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture: [architecture:layer-runtime]
+contributing: []
+system_specs: [spec:AST-059, spec:AST-038]
+---
+
+# LayerProvider component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `LayerProvider` with `children`, `toast` (`{position, maxVisible, inset}`), and `inset` (`{blockStart, blockEnd, inlineStart, inlineEnd}`).                                                                                                |
+| Behavior                | The outermost provider supplies layer configuration and mounts the app's one toast viewport around `children`. A nested provider renders its children unchanged, except that a nested `inset` narrows the inset for layers in its subtree. |
+| End-user impact         | Toasts appear in one configured corner, and anchored layers and toasts stay clear of a declared floating bar.                                                                                                                              |
+| Builder impact          | None.                                                                                                                                                                                                                                      |
+| Compatibility/readiness | Records shipped behavior; no public change.                                                                                                                                                                                                |
+| Review checks           | Reject a second toast viewport from a nested provider, a provider that hosts trigger-associated layers, or a default provider that renders layers differently from no provider.                                                            |
+| Governing rules         | `spec:AST-059` FR6 (the inset); `architecture:layer-runtime` INV10–INV11; `component:Toast`.                                                                                                                                               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+LayerProvider is the app-level configuration point for Astryx layers. It is the
+only public component `Layer.doc.mjs` documents, as an inline entry; the rest of
+that doc describes the layer runtime, which `architecture:layer-runtime` owns.
+This record owns what the provider itself renders.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Whether a provider mounts the toast viewport, and what a nested provider
+  passes through (FR1–FR3).
+
+**Does not own / non-goals**
+
+- What the inset does to gutters, caps, and the toast viewport — owned by
+  `spec:AST-059` FR6.
+- Layer hosting, placement, and text defaults — owned by
+  `architecture:layer-runtime` and `spec:AST-038`.
+- Toast behavior, including how `toast.inset` edges combine with `inset` —
+  owned by `component:Toast` (FR6).
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                     | Basis                              |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1 | A provider with no LayerProvider above it supplies the layer context (`toast` configuration and `inset`) and wraps `children` in one toast viewport configured by `toast.position`, `toast.maxVisible`, `toast.inset`, and `inset`.                                                                           | Current source and tests           |
+| FR2 | A provider nested under another mounts no toast viewport. Without `inset` it renders its children unchanged; with `inset`, each edge it declares applies to the layers in its subtree, and it keeps the outer `toast` configuration. What an edge it leaves unset reads in that subtree is uncontracted here. | Current source; `spec:AST-059` FR6 |
+| FR3 | With nothing declared, a provider changes no layer geometry, so layers under a default provider match layers with no provider.                                                                                                                                                                                | `spec:AST-059` FR6; tests          |
+
+### Allowed variation
+
+- **AV1 — Configuration.** The `toast` and `inset` values vary.
+
+### Representative states
+
+| State                | Required invariant                              | Allowed variation |
+| -------------------- | ----------------------------------------------- | ----------------- |
+| Root provider        | One toast viewport; context supplied.           | Toast config.     |
+| Nested without inset | Children unchanged; no second viewport.         | —                 |
+| Nested with inset    | Subtree inset narrowed; toast config unchanged. | Inset.            |
+
+### Transformation and precedence order
+
+- **ORD1 — Inset.** For an edge a nested provider declares, its value applies
+  in its subtree; unset edges are uncontracted (FR2).
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- No accessibility behavior of its own; the toast viewport's is owned by
+  `component:Toast`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                | Representation authority | Hierarchy role | Component contract |
+| ---------------- | --------------------------------- | ------------------------ | -------------- | ------------------ |
+| Provider         | Renders no visual surface itself. | Current source           | Supporting     | FR1                |
+
+`Layer.doc.mjs` declares no anatomy, so no anatomy-theming map is recorded.
+
+## Family and system relationships
+
+- `spec:AST-059` FR6 owns the inset's meaning.
+- `architecture:layer-runtime` INV10 states that the provider is configuration,
+  not a universal layer host.
+
+## Verification map
+
+| Contract | Verification             | Representative states                        | Mutation or failure expectation                                                   | Audit section                  |
+| -------- | ------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------ |
+| FR1–FR3  | `LayerProvider.test.tsx` | Default, declared inset, nested, toast inset | A default-provider difference, or an inset that does not reach its layers, fails. | `audit:LayerProvider/behavior` |
+
+Read from source, with no focused test yet:
+
+- FR1: `toast.position` and `toast.maxVisible` reaching the viewport.
+- FR2: a nested provider without `inset` mounting no second viewport and
+  rendering its children unchanged, and the outer `toast` configuration being kept.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, the inset rules, or the
+layer runtime. It links to their owners.

package/src/Layer/__tests__/LayerReducedMotion.a11y.chromium.spec.ts

@@ -0,0 +1,176 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y always
+
+/**
+ * @file LayerReducedMotion.a11y.chromium.spec.ts
+ * @input The Tooltip and HoverCard Touch Triggers stories in a built
+ *   Storybook, Chromium with Reduce Motion emulated, under a finger (phone
+ *   profile, coarse pointer) and under a mouse (desktop profile)
+ * @output Real-engine proof of the layer entrance under Reduce Motion: under
+ *   a finger the tooltip and the hover card fade in with no travel and no
+ *   scale, in 200 ms or less (design:reduced-motion DR2); under a mouse they
+ *   still appear at once (DR3); without Reduce Motion the entrance is
+ *   unchanged
+ * @position Run with `pnpm test:a11y-contract`. Media queries only resolve
+ *   in a real engine; the entrance itself is layerAnimations.stylex.ts.
+ *   Reduce Motion is emulated per page (`page.emulateMedia`): the project's
+ *   `use.reducedMotion` does not reach `matchMedia` (playwright.config.ts)
+ */
+
+import {expect, test, 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();
+});
+
+const phone = {
+  hasTouch: true,
+  isMobile: true,
+  viewport: {width: 390, height: 844},
+} as const;
+
+const cases = [
+  {
+    name: 'Tooltip',
+    story: 'core-tooltip--touch-triggers',
+    trigger: 'hover-able term',
+    layer: '.astryx-tooltip',
+  },
+  {
+    name: 'HoverCard',
+    story: 'core-hovercard--touch-triggers',
+    trigger: 'Jane Doe',
+    layer: '.astryx-hover-card',
+  },
+];
+
+/**
+ * The open layer's entrance: its animation name and the properties its
+ * keyframes animate (read from the page's style sheets).
+ */
+async function entranceOf(page: Page, selector: string) {
+  await expect(page.locator(`${selector}:popover-open`)).toHaveCount(1);
+  return page.evaluate(sel => {
+    const layer = document.querySelector<HTMLElement>(`${sel}:popover-open`);
+    if (layer == null) {
+      return {name: 'missing', properties: [], duration: NaN};
+    }
+    const computed = getComputedStyle(layer);
+    const name = computed.animationName;
+    // Seconds; the first animation's duration.
+    const duration = parseFloat(computed.animationDuration.split(',')[0]);
+    const properties = new Set<string>();
+    for (const sheet of Array.from(document.styleSheets)) {
+      let rules: CSSRuleList;
+      try {
+        rules = sheet.cssRules;
+      } catch {
+        continue;
+      }
+      const visit = (list: CSSRuleList) => {
+        for (const rule of Array.from(list)) {
+          if (rule instanceof CSSKeyframesRule && rule.name === name) {
+            for (const frame of Array.from(rule.cssRules)) {
+              const style = (frame as CSSKeyframeRule).style;
+              for (let i = 0; i < style.length; i += 1) {
+                properties.add(style.item(i));
+              }
+            }
+          } else if ('cssRules' in rule) {
+            visit((rule as CSSGroupingRule).cssRules);
+          }
+        }
+      };
+      visit(rules);
+    }
+    return {name, properties: Array.from(properties).sort(), duration};
+  }, selector);
+}
+
+async function tapOpen(page: Page, text: string) {
+  const box = await page.getByText(text, {exact: true}).boundingBox();
+  if (box == null) {
+    throw new Error(`no trigger reading ${text}`);
+  }
+  await page.touchscreen.tap(box.x + box.width / 2, box.y + box.height / 2);
+}
+
+for (const {name, story, trigger, layer} of cases) {
+  test.describe(`${name} under a finger with Reduce Motion`, () => {
+    test.use(phone);
+
+    test('fades in, with no travel and no scale, in 200 ms or less', async ({
+      page,
+    }) => {
+      await page.emulateMedia({reducedMotion: 'reduce'});
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=${story}&viewMode=story`,
+      );
+      await tapOpen(page, trigger);
+      const entrance = await entranceOf(page, layer);
+      expect(entrance.name).not.toBe('none');
+      expect(entrance.properties).toEqual(['opacity']);
+      // design:reduced-motion DR2: a cross-fade of 200 ms or less.
+      expect(entrance.duration).toBeGreaterThan(0);
+      expect(entrance.duration).toBeLessThanOrEqual(0.2);
+    });
+  });
+
+  test.describe(`${name} under a finger with Reduce Motion and a slow theme`, () => {
+    test.use(phone);
+
+    test('still cross-fades in 200 ms or less', async ({page}) => {
+      await page.emulateMedia({reducedMotion: 'reduce'});
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=${story}&viewMode=story`,
+      );
+      // A theme whose fast duration is longer than the cap (DR2, DR4: no
+      // theme value keeps a longer fade under Reduce Motion).
+      await page.addStyleTag({
+        content: ':root, [popover] { --duration-fast-max: 400ms !important; }',
+      });
+      await tapOpen(page, trigger);
+      const entrance = await entranceOf(page, layer);
+      expect(entrance.properties).toEqual(['opacity']);
+      expect(entrance.duration).toBeGreaterThan(0);
+      expect(entrance.duration).toBeLessThanOrEqual(0.2);
+    });
+  });
+
+  test.describe(`${name} under a finger without Reduce Motion`, () => {
+    test.use(phone);
+
+    test('keeps its entrance', async ({page}) => {
+      await page.emulateMedia({reducedMotion: 'no-preference'});
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=${story}&viewMode=story`,
+      );
+      await tapOpen(page, trigger);
+      const entrance = await entranceOf(page, layer);
+      expect(entrance.properties).toEqual(['opacity', 'transform']);
+    });
+  });
+
+  test.describe(`${name} under a mouse with Reduce Motion`, () => {
+    test('still appears at once', async ({page}) => {
+      await page.emulateMedia({reducedMotion: 'reduce'});
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=${story}&viewMode=story`,
+      );
+      await page.getByText(trigger, {exact: true}).hover();
+      const entrance = await entranceOf(page, layer);
+      expect(entrance.name).toBe('none');
+    });
+  });
+}

package/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts

@@ -0,0 +1,200 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y always
+
+/**
+ * @file TouchTrigger.a11y.chromium.spec.ts
+ * @input The `Core/Tooltip` and `Core/HoverCard` Touch Triggers stories in a
+ *   built Storybook, driven by real Chromium touch input (CDP) in a phone-sized
+ *   viewport.
+ * @output Real-engine proof that a hover layer answers a touch only once it is
+ *   a tap: it opens when the finger lifts, stays shut while a finger rests on
+ *   the trigger, never opens for a touch that turns into a scroll, and a
+ *   tap-opened layer closes when a tap outside lifts or a scroll starts
+ *   outside.
+ * @position Run with `pnpm test:a11y-contract`. Only a real engine decides
+ *   whether a touch is a tap, a scroll or a long press, so these outcomes
+ *   cannot be shown in jsdom; the unit suites (Tooltip.test.tsx,
+ *   HoverCard.test.tsx) cover the same rules on synthetic events.
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  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();
+});
+
+test.use({hasTouch: true, isMobile: true, viewport: {width: 390, height: 844}});
+
+interface Finger {
+  down(x: number, y: number): Promise<void>;
+  move(x: number, y: number): Promise<void>;
+  up(): Promise<void>;
+}
+
+async function openStory(page: Page, id: string): Promise<Finger> {
+  await page.goto(`${storybook.origin}/iframe.html?id=${id}&viewMode=story`);
+  // Room to scroll, so a drag is a page scroll the browser takes from us.
+  await page.evaluate(() => {
+    const spacer = document.createElement('div');
+    spacer.style.height = '2000px';
+    document.body.append(spacer);
+  });
+  const cdp: CDPSession = await page.context().newCDPSession(page);
+  return {
+    down: async (x, y) => {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchStart',
+        touchPoints: [{x, y}],
+      });
+    },
+    move: async (x, y) => {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchMove',
+        touchPoints: [{x, y}],
+      });
+    },
+    up: async () => {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchEnd',
+        touchPoints: [],
+      });
+    },
+  };
+}
+
+async function centerOf(target: Locator): Promise<[number, number]> {
+  const box = await target.boundingBox();
+  if (box == null) {
+    throw new Error('the trigger has no layout box');
+  }
+  return [
+    Math.round(box.x + box.width / 2),
+    Math.round(box.y + box.height / 2),
+  ];
+}
+
+/** A blank point of the page, away from every trigger. */
+const OUTSIDE: [number, number] = [360, 700];
+
+const cases = [
+  {
+    name: 'Tooltip',
+    story: 'core-tooltip--touch-triggers',
+    trigger: (page: Page) => page.getByText('hover-able term', {exact: true}),
+    action: (page: Page) => page.getByRole('button', {name: 'Save'}),
+    layer: '.astryx-tooltip:popover-open',
+  },
+  {
+    name: 'HoverCard',
+    story: 'core-hovercard--touch-triggers',
+    trigger: (page: Page) => page.getByText('Jane Doe', {exact: true}),
+    action: (page: Page) => page.getByRole('button', {name: 'Open profile'}),
+    layer: '.astryx-hover-card:popover-open',
+  },
+];
+
+for (const {name, story, trigger, action, layer} of cases) {
+  test.describe(`${name} under a finger`, () => {
+    test('opens when the tap lifts, not when the finger lands', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await page.waitForTimeout(150);
+      // The finger is still down: it may yet be starting a scroll.
+      await expect(page.locator(layer)).toHaveCount(0);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(1);
+    });
+
+    test('never opens for a touch that turns into a scroll', async ({page}) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      for (let step = 1; step <= 8; step += 1) {
+        await finger.move(x, y - step * 10);
+        await page.waitForTimeout(16);
+      }
+      await finger.up();
+      await page.waitForTimeout(300);
+      await expect(page.locator(layer)).toHaveCount(0);
+    });
+
+    test('stays shut while a finger rests on the trigger', async ({page}) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await page.waitForTimeout(900);
+      // Nothing is decided until the finger lifts; whether a long hold still
+      // counts as a tap then is the engine's call (UIKit's own tap allows a
+      // hold of up to 1.5 s).
+      await expect(page.locator(layer)).toHaveCount(0);
+      await finger.up();
+    });
+
+    test('closes when a tap outside lifts, not when it lands', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(1);
+
+      await finger.down(...OUTSIDE);
+      await page.waitForTimeout(150);
+      await expect(page.locator(layer)).toHaveCount(1);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(0);
+    });
+
+    test('closes as soon as a scroll that starts outside takes the touch', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(1);
+
+      const [ox, oy] = OUTSIDE;
+      await finger.down(ox, oy);
+      for (let step = 1; step <= 8; step += 1) {
+        await finger.move(ox, oy - step * 10);
+        await page.waitForTimeout(16);
+      }
+      // Still down: the scroll took the touch, which is the dismissal.
+      await expect(page.locator(layer)).toHaveCount(0);
+      await finger.up();
+    });
+
+    test('leaves a tap on a trigger that acts to that trigger', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(action(page));
+      await finger.down(x, y);
+      await finger.up();
+      await page.waitForTimeout(300);
+      await expect(page.locator(layer)).toHaveCount(0);
+    });
+  });
+}

package/src/Layer/layerAnimations.stylex.ts

@@ -82,8 +82,20 @@ const enterStartRtl = stylex.keyframes({
   to: {opacity: 1, transform: 'translateX(0) scale(1)'},
 });
 
+// Reduce Motion under a finger: the same entrance without its travel. A touch
+// presentation substitutes a cross-fade for motion, never a jump.
+const fadeIn = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
 const animationBase = {
-  animationDuration: durationVars['--duration-fast-max'],
+  animationDuration: {
+    default: durationVars['--duration-fast-max'],
+    // The cross-fade is 200 ms or less, whatever the theme's duration
+    // (design:reduced-motion DR2).
+    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-fast-max']}, 200ms)`,
+  },
   animationTimingFunction: easeVars['--ease-standard'],
   animationFillMode: 'backwards' as const,
 };
@@ -96,13 +108,18 @@ const animationBase = {
  *
  * Each entry disables its keyframe animation under
  * `prefers-reduced-motion: reduce` so the layer appears instantly instead of
- * translating/scaling in (infra-6).
+ * translating/scaling in (infra-6). Under a finger (the primary pointer is
+ * coarse) it fades in instead, opacity only and in 200 ms or less: on a touch
+ * screen Reduce Motion replaces motion with a cross-fade rather than a jump
+ * (design:reduced-motion DR2, DR3), as iOS does for its menus, popovers and
+ * tips.
  */
 export const layerAnimations = stylex.create({
   below: {
     animationName: {
       default: enterBelow,
       '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
   },
@@ -110,6 +127,7 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterAbove,
       '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
   },
@@ -118,6 +136,7 @@ export const layerAnimations = stylex.create({
       default: enterEnd,
       ':is([dir="rtl"] *)': enterEndRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
   },
@@ -126,6 +145,7 @@ export const layerAnimations = stylex.create({
       default: enterStart,
       ':is([dir="rtl"] *)': enterStartRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
   },

package/src/Layer/layerDismissalInvariants.test.tsx

@@ -440,11 +440,20 @@ describe('a standalone BottomSheet is one more layer', () => {
   }
 
   beforeEach(() => {
+    // A non-modal sheet is a manual popover in the top layer (show() below
+    // the Popover API floor); jsdom's stand-ins keep the `open` marker the
+    // census reads.
     HTMLDialogElement.prototype.show = vi.fn(function (
       this: HTMLDialogElement,
     ) {
       this.setAttribute('open', '');
     });
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      this.setAttribute('open', '');
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      this.removeAttribute('open');
+    });
   });
 
   it('peels a Dialog opened inside the sheet before the sheet', () => {