An open source design system that's fully customizable and agent ready
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, packages/core/src/Layer/toastHost.test.tsx, packages/core/src/Layer/toastHost.lateRegistration.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 renders the one toast viewport once Toast is imported. 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, except that the toast viewport waits for a Toast import (FR1); 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, except that the toast viewport waits for a Toast import (FR1); 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-059FR6. - Layer hosting, placement, and text defaults — owned by
architecture:layer-runtimeandspec:AST-038. - Toast behavior, including how
toast.insetedges combine withinset— owned bycomponent: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 the toast context. Once Toast is imported, it renders one toast viewport after children, configured by toast.position, toast.maxVisible, toast.inset, and inset; before that, none. |
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
toastandinsetvalues vary.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Root provider | Context supplied; a viewport once Toast loads. | 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-059FR6 owns the inset's meaning.architecture:layer-runtimeINV10 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; for FR1 also toastHost.test.tsx and toastHost.lateRegistration.test.tsx; LayerProvider.test.tsx toast-configuration suite for toast.maxVisible and for a nested provider without inset (one viewport, outer configuration kept, no added element) |
Default, declared inset, nested, toast inset, no Toast import | A default-provider difference, an inset that does not reach its layers, or a viewport with no Toast import fails. | audit:LayerProvider/behavior |
Read from source, with no focused test yet:
- FR1:
toast.positionreaching the viewport.
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.