An open source design system that's fully customizable and agent ready
TypeScript
spec(Overlay): OverlayRegion places content at a preset or fractional position over media (#7951)
Cindy Zhangd32951564e14
diff --git a/packages/core/src/Overlay/Overlay.spec.md b/packages/core/src/Overlay/Overlay.spec.mdnew file mode 100644index 0000000000..075f73508b--- /dev/null+++ b/packages/core/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.