@astryxdesign/core 0.7.4-canary.f32572e → 0.7.4

package/src/Overlay/Overlay.spec.md

@@ -0,0 +1,304 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Overlay
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-22
+owners: [cixzhang]
+review_triggers: [public-api, layout, accessibility]
+verified_by:
+  [
+    packages/core/src/Overlay/Overlay.test.tsx,
+    apps/storybook/stories/Overlay.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: [design:bidirectionality]
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:internationalization,
+  ]
+contributing: []
+system_specs: [spec:AST-002/DEC-1, spec:AST-017/FR5, spec:AST-027/FR2]
+---
+
+# Overlay component contract
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+This record governs how several pieces of content are placed over an Overlay's
+surface, each at a preset spot or at fractional coordinates, including the
+stacking of a container that holds such content. Overlay's scrim, reveal modes,
+own `position` values, and alignment remain described by its source, tests, and
+`Overlay.doc.mjs` until a record claims them.
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | New `OverlayRegion` component, exported beside Overlay: `position` (required) is a preset (`'fill' \| 'top' \| 'bottom' \| 'center' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'`) or open placement `{x, y, width?, height?}` in 0–1 fractions; plus `children`, `ref`, `xstyle`, `className`, `style`. |
+| Behavior                | Inside a fill Overlay, a preset region sits at that spot (corners follow the writing direction) and open placement sits at fractions of the media measured from its top-left corner, never mirrored. A sized open region stays inside the media. Regions scale with the media.                                            |
+| End-user impact         | Several captions, tags, badges, or hotspots over one image or video each stay on their spot of the media at every size, in either text direction.                                                                                                                                                                         |
+| Builder impact          | None by default. A builder places content with `OverlayRegion` instead of hand-written absolute positioning; moving a region stays the builder's code.                                                                                                                                                                    |
+| Compatibility/readiness | Additive: a new component and export; an Overlay without a region renders and stacks exactly as before. This record is current authority; `OverlayRegion`, its consumer docs, region tests, and region stories have not shipped yet.                                                                                      |
+| Review checks           | Reject open placement that mirrors in right-to-left, corner presets that do not, JavaScript measurement or observers, drag or resize behavior inside Overlay, a role or focus stop on the region, a theme target on it, or a region placed inside a strip.                                                                |
+| Governing rules         | FR1–FR11 below; `design:bidirectionality/DR3`, `DR5`, `DR6`; `architecture:component-theming-surface/INV4`; `spec:AST-017/FR5`; `spec:AST-027/FR2`.                                                                                                                                                                       |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Overlay layers content over a bounded surface, usually media, and places that
+content as one block: the whole surface or a band at the top or bottom. Some
+surfaces carry several pieces of content, each belonging to its own spot: two
+captions drawn into an image, a badge in a corner beside a caption, a tag on a
+face. A spot is either one of Overlay's familiar places or a point on the media
+described as fractions of its width and height, because the media is shown at
+many sizes and the spot must stay on the same pixels of it. Overlay owns that
+placement because Overlay owns the surface it is measured against.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; an Overlay without a region renders and
+  stacks exactly as before. Only a container that holds a region isolates its
+  stacking (FR10).
+- Compatibility class: additive component and export.
+- Controlled/uncontrolled behavior: not applicable; a region holds no state.
+- Migration decision: none required (`spec:AST-017/FR5`).
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- `OverlayRegion`: its `position` values, their geometry, clamping, scaling, and
+  reference box.
+- The rule that open placement is measured in the media's own physical space.
+- The rule that regions are placed only in fill overlays, and the fallback
+  everywhere else.
+- The stacking isolation of a container that holds a region.
+
+**Does not own / non-goals**
+
+- Moving, dragging, or resizing a region, including pointer capture, keyboard
+  steps, snapping, and when a new position is reported — owned by the product
+  callsite (`component:Overlay/DEC-3`).
+- What a region paints: borders, fills, handles, and text — owned by the
+  region's content.
+- Making the base content fill the surface — owned by the caller, as for every
+  Overlay; fractions are measured against the surface, so media that does not
+  fill it does not line up with them.
+- Overlay's own `position` and `align` — unchanged; a region does not read or
+  alter them beyond FR2.
+- Placement relative to a trigger or outside the surface — owned by the layer
+  runtime (Popover, Tooltip, HoverCard).
+
+## Public concepts
+
+| Concept        | Closed values or states                                                                 | Meaning                                                                                                                                                                                                                             | Availability by variant/orientation/state | Default             | Owner               | Stability | Invalid-value behavior                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
+| Preset         | `fill`, `top`, `bottom`, `center`, `top-start`, `top-end`, `bottom-start`, `bottom-end` | `fill`, `top`, and `bottom` are the places Overlay's own `position` names: the whole surface, or a full-width band at that edge. `center` and the corners hold content-sized boxes at that spot.                                    | Fill overlays (FR2)                       | None; required prop | `component:Overlay` | stable    | Other strings are rejected by the public type                                                           |
+| Open placement | `{x, y, width?, height?}`; each a number from 0 to 1                                    | `x`, `y`: the region's top-left corner as fractions of its reference box, measured from that box's top-left corner. `width`, `height`: the region's size as fractions, extending right and down; omitted means it fits its content. | Fill overlays (FR2)                       | None; required prop | `component:Overlay` | stable    | Values clamped into 0–1; a non-finite coordinate is treated as 0 and a non-finite size as omitted (FR6) |
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                                       | Draft review state |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
+| FR1  | `OverlayRegion` rendered directly in the content of an Overlay or `useOverlay` host with `position="fill"`, the default, MUST position against that host's scrim box, which is the whole base surface: 0 and 1 are the media's edges, and the box matches the Overlay's `ref`. Any element between the region and the scrim that establishes a containing block for absolutely positioned descendants becomes its reference box instead. In this record, the surface means the region's reference box.                                                            | `component:Overlay/DEC-1`                                   | settled            |
+| FR2  | Regions are placed only in fill hosts. A region rendered anywhere else MUST NOT be placed: in the content of an Overlay or `useOverlay` host whose `position` is `"top"` or `"bottom"`, in an Overlay's `children`, or with no Overlay or `useOverlay` host at all, it renders its content as ordinary in-flow content where it stands (in a strip, that content reveals and slides with the strip) and MUST emit one development warning per mount naming the fill-only rule.                                                                                    | `component:Overlay/DEC-4`                                   | settled            |
+| FR3  | A preset region MUST sit at its spot inside Overlay's content inset: `fill` covers the inset box; `top` and `bottom` span its full width at that edge with content height; `center` is content-sized at its center; each corner is content-sized at that corner. Content larger than the inset box is clipped by the container, not shifted.                                                                                                                                                                                                                      | `component:Overlay/DEC-2`                                   | settled            |
+| FR4  | Corner presets MUST resolve `start` and `end` against the writing direction of the region's own context: `top-start` is the top-left corner in left-to-right and the top-right corner in right-to-left. `fill`, `top`, `bottom`, and `center` are symmetric and do not change with direction.                                                                                                                                                                                                                                                                     | `design:bidirectionality/DR3`                               | settled            |
+| FR5  | Open placement MUST measure `x` from the surface's left edge and `y` from its top edge in every writing direction, and MUST NOT mirror in right-to-left. The region's own content follows the ambient direction.                                                                                                                                                                                                                                                                                                                                                  | `design:bidirectionality/DR5`                               | settled            |
+| FR6  | Open coordinates and sizes MUST be clamped into 0–1 before placement. A non-finite coordinate MUST resolve to 0, and a non-finite size MUST resolve to omitted.                                                                                                                                                                                                                                                                                                                                                                                                   | Invalid-value behavior                                      | settled            |
+| FR7  | Open placement puts the region's top-left corner at (`x`, `y`) (`component:Overlay/DEC-6`). On an axis with a size, the region MUST be exactly that fraction of the surface, extending right or down, and MUST sit wholly inside it: its start is clamped between 0 and one minus the size. On an axis without a size, the region MUST fit its content starting at the coordinate, and any overhang past the container's edge is clipped, not shifted inward.                                                                                                     | `component:Overlay/DEC-5`                                   | settled            |
+| FR8  | When the surface changes size, every region MUST keep its spot: presets by their insets, open placement by its fractional position and size, without a re-render.                                                                                                                                                                                                                                                                                                                                                                                                 | `component:Overlay/DEC-1`                                   | settled            |
+| FR9  | A region MUST appear, hide, and become inert with the overlay content that contains it, following Overlay's `showOn` and `isOpen`, and MUST inherit the scrim's media theme. It adds no visibility rule of its own.                                                                                                                                                                                                                                                                                                                                               | Overlay's existing reveal behavior                          | settled            |
+| FR10 | A placed region MUST paint above the fill surface's in-flow overlay content, including positioned in-flow content written after it, and a later placed region MUST paint above an earlier one. A placed region inside a wrapper that forms a stacking context is ordered only among that wrapper's content. An Overlay or `useOverlay` container with a placed region anywhere inside it MUST own an isolated stacking context; a container with no region inside it keeps its stacking unchanged. A placed region MUST NOT take part in the scrim's flow layout. | Absolute positioning within the surface; `spec:AST-027/FR2` | settled            |
+| FR11 | Overlay and `OverlayRegion` MUST NOT move, drag, or resize a region, and MUST NOT attach pointer, keyboard, or gesture handlers to it. A region moves only when its caller passes a new `position`.                                                                                                                                                                                                                                                                                                                                                               | `component:Overlay/DEC-3`                                   | settled            |
+
+### Allowed variation
+
+- **AV1 — Content.** Any content may sit in a region; on an open region each
+  axis is sized or content-sized independently (FR7).
+- **AV2 — Surface size and shape.** The surface may be any size or aspect ratio,
+  and may change size at any time (FR8).
+- **AV3 — Mixed content.** In-flow overlay content, preset regions, and open
+  regions may share one surface (FR10).
+
+### Representative states
+
+| State                                                    | Required invariant                                                                                        | Allowed variation  |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------ |
+| Two captions, `top` and `bottom` presets                 | Each spans the inset width at its edge, like Overlay's own strips.                                        | Caption text.      |
+| `top-start` badge, left-to-right and right-to-left       | Top-left corner in left-to-right; top-right corner in right-to-left.                                      | Badge content.     |
+| Open sized caption near the right edge                   | Box is the given fraction of the image and stays wholly inside, flush with that edge.                     | Which edge.        |
+| Open content-sized pin                                   | Pin starts at its point and extends right and down; overhang past the container is clipped.               | Pin content.       |
+| Open region, right-to-left page                          | Same spot on the media as left-to-right; the region's text reads right-to-left.                           | Writing direction. |
+| Surface resized from 640px to 320px wide                 | Every region keeps its spot, with no re-render.                                                           | Any surface size.  |
+| Region in an Overlay's `children` or outside any Overlay | Is not placed: its content flows where it stands, and it warns once in development.                       | Location.          |
+| Region in a `position="bottom"` Overlay                  | Is not placed: its content flows in the strip like other strip content, and it warns once in development. | Strip content.     |
+| `showOn="hover"` overlay at rest                         | Regions are hidden with the rest of the overlay content.                                                  | Reveal mode.       |
+
+### Transformation and precedence order
+
+- **ORD1 — Placement.** Resolve the reference box (FR1, FR2) → for a preset,
+  place it in the content inset and resolve start/end against direction (FR3,
+  FR4); for open placement, clamp values (FR6) and resolve each axis as sized or
+  content-sized in physical space (FR5, FR7) → express the result as insets and
+  fractions of the box (FR8). Styling inputs compose after placement in the order
+  `architecture:public-component-api/INV6` gives; a caller who overrides inset or
+  size properties owns the result.
+
+### Performance and resources
+
+- **PR1 — CSS geometry only.** Placement, clamping, and scaling MUST be achieved
+  with arithmetic on the given values and CSS: no measurement, observer,
+  listener, state, Effect, or extra render pass. The fill-only check adds no
+  measurement, state, or extra render pass.
+
+## Accessibility contract
+
+- **AR1 — Presentation only.** `OverlayRegion` MUST add no role, accessible name,
+  description, focus stop, or text. Its content keeps its own semantics.
+- **AR2 — Source order is reading order.** Assistive technology and keyboard
+  focus follow the regions' source order, not their position on the surface. A
+  caller renders regions in the order a reader should meet them.
+- **AR3 — Movement offers non-drag paths.** Overlay's documented move pattern
+  for open regions pairs pointer dragging with a single-pointer path that needs
+  no drag, where activating a spot on the media moves the region there, and a
+  keyboard path that moves a region whose content has focus by a fixed step per
+  arrow key, with arrow directions matching the visual axes
+  (`design:bidirectionality/DR6`).
+
+## Design relationships
+
+| Anatomy or state     | Design requirement                                           | Representation authority      | Hierarchy role | Component contract |
+| -------------------- | ------------------------------------------------------------ | ----------------------------- | -------------- | ------------------ |
+| Preset region        | Reads as Overlay's own places, with Overlay's content inset. | Owner direction               | Supporting     | FR3                |
+| Corner preset in RTL | Leading and trailing corners follow reading order.           | `design:bidirectionality/DR3` | Supporting     | FR4                |
+| Open region          | Stays on the same spot of the media at every size.           | Owner direction               | Supporting     | FR7, FR8           |
+| Open region in RTL   | Media is physical content and does not mirror.               | `design:bidirectionality/DR5` | Supporting     | FR5                |
+
+## Family and system relationships
+
+- `design:bidirectionality` owns direction behavior: FR4 applies DR3 to corner
+  presets, FR5 applies DR5 to open placement, and AR3 applies DR6 to movement.
+- `architecture:component-theming-surface/INV4` keeps a non-painting box out of
+  the theme surface: the region is a geometry-only box that paints nothing, so it
+  has no theme target and its content owns its paint.
+- `architecture:public-component-api` owns prop admission and styling-input
+  order; ORD1 applies INV6.
+- `spec:AST-027/FR2` puts the isolation boundary on the surface; FR10 makes the
+  Overlay or `useOverlay` container that holds a region that owner.
+- `spec:AST-017/FR5` classifies this as nonbreaking: it adds a new component,
+  changes no default, and a caller who never renders a region sees no change.
+
+## Verification map
+
+| Contract                      | Verification                                                         | Representative states                                                                                                                             | Mutation or failure expectation                                                                                                                                             | Audit section          |
+| ----------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1, FR2, FR6, FR11           | `Overlay.test.tsx` region suite                                      | Region in Overlay and `useOverlay` content; in a `bottom` Overlay; outside any Overlay; out-of-range and non-finite input; pointer and key events | Unclamped values, a region outside the scrim, a placed region in a strip or a missing warning, or a region that moves on its own fails.                                     | `audit:Overlay/api`    |
+| FR3, FR4, FR5, FR7, FR8, FR10 | Real-Chromium assertions in the Overlay region story's play function | Every preset; open sized, edge-clamped, and content-sized; resized surface; RTL; a region before a positioned control                             | A region off its spot by more than 0.5px, a corner that does not flip or an open region that does, the in-flow control hit at a region's center, or wrong isolation, fails. | `audit:Overlay/layout` |
+| FR9                           | `Overlay.test.tsx` reveal case with a region                         | `isOpen={false}`                                                                                                                                  | A region outside the scrim, or a closed scrim that is not inert, fails.                                                                                                     | `audit:Overlay/api`    |
+| AR1, AR2                      | `Overlay.test.tsx` DOM check of the region element                   | Text content                                                                                                                                      | Any attribute other than `class` and `style` on the region element, or text it adds, fails.                                                                                 | `audit:Overlay/a11y`   |
+| AR3                           | Region move story's play function                                    | Arrow key and single activation on the media, LTR and RTL                                                                                         | ArrowRight moving a region left, or an activation that does not move the region to the activated spot, fails.                                                               | `audit:Overlay/a11y`   |
+| PR1                           | Source review of `OverlayRegion`                                     | All inputs                                                                                                                                        | A ref read, observer, listener, or Effect added for placement fails review.                                                                                                 | `audit:Overlay/layout` |
+
+## Decision log
+
+<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
+
+### DEC-1 — Several placed items are Overlay regions with one `position` prop
+
+**Reference:** `component:Overlay/DEC-1`
+**Decider:** cixzhang, 2026-10-22
+
+Overlay places one content block, so a surface with several spots needs a child
+that places itself. `OverlayRegion` inside Overlay's content inherits Overlay's
+surface, reveal, and media theme with no new Overlay prop, and one `position`
+prop covers both kinds of spot: a named place or open placement. Sizes live
+inside the open placement object, so a region never carries `width` or `height`
+props whose numbers mean fractions while the same names mean pixels on Card,
+Button, and Grid.
+
+Rejected: an object form of Overlay's own `position`, because it still places
+only one block.
+
+### DEC-2 — Presets reuse Overlay's places and add the center and corners
+
+**Reference:** `component:Overlay/DEC-2`
+**Decider:** cixzhang, 2026-10-22
+
+`fill`, `top`, and `bottom` mean on a region what they mean on Overlay, so a
+builder reads one vocabulary. Static badges and labels need the center and the
+corners, which Overlay's single block cannot hold beside other content. Corners
+use `start` and `end` because a leading badge leads in either direction.
+
+### DEC-3 — Moving a region stays at the callsite
+
+**Reference:** `component:Overlay/DEC-3`
+**Decider:** cixzhang, 2026-10-22
+
+What moving a region means differs by product: whether the position commits on
+release or live, the keyboard step, snapping, which regions move, and what
+happens while a new rendering of the media loads. Overlay therefore never moves
+a region; the caller converts pointer and keyboard input into new fractions
+measured against the region's reference box and passes them back.
+
+Rejected: a drag hook on Overlay, because a shared drag primitive needs its own
+record and more than one caller's needs.
+
+### DEC-4 — Regions belong to fill overlays
+
+**Reference:** `component:Overlay/DEC-4`
+**Decider:** cixzhang, 2026-10-22
+
+A spot on the media is meaningless inside a strip whose height follows its own
+content and which slides in and out. A strip is also the containing block of
+everything inside it, so CSS cannot place a region against the media from
+there. In a strip overlay a region therefore renders its content as ordinary
+strip content and warns in development, so the content stays visible. The
+public type cannot enforce the rule, because regions arrive through `content`.
+The same fallback applies outside any fill host, where there is no surface to
+measure against and nothing to isolate a region's paint order.
+
+Rejected: placing a strip's regions against the container, because escaping the
+strip needs a second rendering layer that duplicates Overlay's reveal.
+
+### DEC-5 — Open sized axes are clamped inside; content-sized axes are not
+
+**Reference:** `component:Overlay/DEC-5`
+**Decider:** cixzhang, 2026-10-22
+
+A sized region can be kept inside the surface with arithmetic on the given
+fractions, so it never spills off the media however far it is moved. Keeping a
+content-sized region inside would require measuring it, which PR1 forbids, so
+the container clips any overhang.
+
+### DEC-6 — Open placement names the region's top-left corner
+
+**Reference:** `component:Overlay/DEC-6`
+**Decider:** cixzhang, 2026-10-22
+
+`x` and `y` are the region's top-left corner, and `width` and `height` extend
+right and down. That matches how servers and editors report boxes (left, top,
+width, height) and how CSS insets read, so a reported box passes through with no
+conversion and is clamped with plain arithmetic.
+
+Rejected: the region's center, because every reported box would need converting.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/Thumbnail/Thumbnail.test.tsx

@@ -38,7 +38,12 @@ describe('Thumbnail', () => {
     );
     const img = screen.getByRole('img');
     expect(img).toHaveAttribute('src', '/local.jpg');
-    expect(screen.getByRole('status')).toBeInTheDocument();
+    // The upload Spinner is decorative; the thumbnail announces its busy
+    // start instead (spec:AST-086 FR8).
+    expect(document.querySelector('.astryx-spinner')).toHaveAttribute(
+      'aria-hidden',
+      'true',
+    );
   });
 
   it('exposes the label as an accessible name via a valid group role', () => {

package/src/Thumbnail/Thumbnail.tsx

@@ -25,7 +25,7 @@
  * - /packages/cli/assets/templates/blocks/components/Thumbnail/ (showcase blocks)
  */
 
-import {useState} from 'react';
+import {useRef, useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -40,6 +40,7 @@ import {Skeleton} from '../Skeleton';
 import {Spinner} from '../Spinner';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {useDevWarning} from '../hooks/useDevWarning';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useContainerReveal} from '../hooks/useContainerReveal';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
@@ -352,6 +353,14 @@ export function Thumbnail({
   const showSkeleton = isLoading && !hasSrc;
   const showImage = hasSrc && !showSkeleton && !hasError;
   const showUploadOverlay = isLoading && hasSrc;
+  const uploadOverlayRef = useRef<HTMLDivElement>(null);
+  // The upload Spinner is decorative; the thumbnail announces its busy start
+  // instead (spec:AST-086 FR8).
+  useBusyAnnouncement(
+    showUploadOverlay,
+    t('@astryx.spinner.loading'),
+    uploadOverlayRef,
+  );
   const showPlaceholder = (!isLoading && !hasSrc) || hasError;
   const isInteractive = onClick != null && !isDisabled && !isLoading;
   const hasRemove = onRemove != null && !isDisabled;
@@ -472,8 +481,8 @@ export function Thumbnail({
         )}
         {showImage && <div {...stylex.props(styles.insetBorder)} />}
         {showUploadOverlay && (
-          <div {...stylex.props(styles.uploadOverlay)}>
-            <Spinner size="sm" shade="onMedia" />
+          <div ref={uploadOverlayRef} {...stylex.props(styles.uploadOverlay)}>
+            <Spinner size="sm" shade="onMedia" aria-hidden="true" />
           </div>
         )}
         {removeButtonEl}