glossary.md

Glossary

Ubiquitous language for the @stainless-code/layers domain. Keep terms stable across code, docs, and issues.

• Layer — one frame in a stack; a modal, dialog, drawer, popover, toast, etc. Owned by a LayerStack; carries a key, payload, optional data (from loadFn), a phase, and a caller-facing promise.
• Stack (LayerStack) — ordered collection of active layers for one surface ("confirm", "drawer", "toast"). Identified by id; subscribed via subscribe/getSnapshot (mountable layers) and getQueuedSnapshot (serial-waiting layers).
• Client (LayerClient) — app-wide orchestrator owning named stacks; open() returns a typed Promise<Response>.
• #dispatch — internal LayerStack choke point: label a snapshot-changing mutation, apply it, #flush. Not public; feeds subscribeNotify.
• StackNotifyEvent — JSON-safe record of one observable stack transition (action + active/queued views + optional projected payload). Emitted by core; Devtools bridges to TanStack EventClient.
• subscribeNotify — LayerClient: (listener) => unsubscribe for StackNotifyEvents. Distinct from subscribe / subscribeStacks (snapshot / stack-created).
• seedNotify — LayerClient: re-emit a register StackNotifyEvent for one stack, or all when omitted (Devtools attach / late subscribers).
• Key — the logical identity of a layer (find/upsert/gcTime operate on keySignature(key)). Must be JSON-safe (string | boolean | null | finite number | plain objects/arrays of those); invalid segments throw LayerKeyError. Multiple live layers may share a key in a parallel stack.
• Instance id (LayerState.id) — the physical, unique id of one Layer instance (`${hashKey(key)}#n`); used for rendering keys and instance lookup/removal (getLayer, #remove).
• Phase — resolution lifecycle axis: pending → active → dismissed; or queued (serial-waiting, not mounted); or error. Does not include exiting — animation is on transition. Distinct from actionStatus and transition.
• Transition — animation axis (entering | settled | exiting), orthogonal to phase (like actionStatus). dismissed + exiting = playing exit anim; dismissed + settled = cached/done.
• Entering — transition: "entering" while a layer mounts/opens; may coincide with phase: "pending" (loading) or phase: "active".
• Settled — transition: "settled" when enter/exit animation is done (or instant, delay 0).
• settle (call.settle()) — resolve the current transition early: entering → settled (clears enter timer; phase untouched); exiting → remove (clears exit timer); no-op if already settled. Completion is whichever of { delay elapsed, call.settle() } fires first.
• enteringDelay — ms the enter transition runs before settling; 0 (default) = instant. call.settle() finishes early.
• exitingDelay — ms the exit transition runs before removal; 0 (default) = instant. call.settle() removes early.
• Action status — independent axis (idle | running) for in-layer mutations, separate from phase and transition.
• Call context (LayerCallContext) — imperative handle handed to a layer component: end/dismiss (async — resolve the caller's await; return Promise<boolean>), addBlocker, update (patch payload live), setRunning (drives actionStatus), settle (drives transition), ended, index, stackSize, root, stackId, layerId. Built by createCallContext.
• open — push a layer onto a stack; returns Promise<R> resolved by dismiss, or rejected by loadFn / validation / cancelAll. The caller awaits the user's decision.
• dismiss — async (Promise<boolean>): consult blockers (unless { force: true }), then resolve the layer's promise with a response, flip ended, set phase: "dismissed" + transition: "exiting", then remove after exitingDelay or call.settle() (whichever first). Return true if dismissed, false if vetoed.
• cancelAll — force-clear a stack; reject every open/queued caller with LayerCancelledError (skips blockers). Used for parent-dismiss child drain, group dispose, and host disconnect — distinct from dismissAll(response) which completes with R.
• cancelQueued — resolve and remove a serial queued layer without mounting; skips blockers. Omit { id } → FIFO head for the key; pass { id } → exact queued instance.
• blocker — consumer predicate gating user-intent dismissal; true = allow, falsy = veto. Instance (call.addBlocker) or stack (stack.addBlocker) scope; multiple allowed; async-capable; throw/reject = veto (fail-closed).
• addBlocker — register a blocker; returns a disposer. call.addBlocker(fn) — instance scope (() => boolean | Promise<boolean>). stack.addBlocker(fn) — stack policy ((layer) => boolean | Promise<boolean>).
• dismissing — LayerState.dismissing: true while a user-intent dismiss is consulting blockers; false on veto or removal. Use to disable close UI during async confirm.
• dismiss mode — DismissAllMode for stack.dismissAll: "skipBlocked" (default — close permitted, leave blocked open), "stopAtBlocked" (halt at first blocked), "force" (bypass blockers). Default per stack via StackOptions.dismissAllMode.
• upsert — reusing an active key updates its payload instead of stacking (singleton toasts/progress).
• scope — per-stack queueing on StackOptions: scope: { strategy: "serial" | "parallel", onLoadError?: "block" | "advance" } (parallel / block when omitted); serial = one occupying layer at a time, parallel = stack freely. Serial onLoadError: block keeps a failed loadFn as phase: "error" until dismiss; advance removes it and drains the queue.
• gcTime — keep dismissed layers in a cache so re-opening the same key restores data without re-running loadFn. One slot per key (last-dismissed-wins); evicted after gcTime with explicit teardown.
• loadFn — optional async load run on open; cancelable via AbortController; pending → active with data on success, error on throw.
• Observer / selector — adapters subscribe to LayerStack.getSnapshot() and project via a selector (React/Preact useSyncExternalStore, Solid from, Angular signal, Vue shallowRef, Lit reactive controllers, Alpine Alpine.reactive / data states, Svelte runes).
• Options helper (layerOptions) — identity function carrying <P, R, E, D> generics so LayerClient.open infers the response type end-to-end.
• Outlet — renders the active stack. React, Preact, and Solid ship StackOutlet; Angular exposes renderStack(vcr); Vue ships StackOutlet; Lit ships <stack-outlet>; Alpine ships x-layer-outlet + $layer; Svelte renders from useStack().current + callFor. See adapter ergonomics.
• Stack handles (useStackHandles) — headless { states, getCall } for custom hosts (React/Preact/Solid/Angular/Vue/Lit; Alpine Rank-2 = subscribe + render yourself via layerStack + callFor; Svelte's useStack() already returns .current + callFor). StackOutlet is the registered-component convenience built on it where shipped.
• Layer group — a child stack owned by a parent layer and tied to its lifetime: created via createLayerGroup / adapter useLayerGroup; when the parent dismisses, the group's stack is cancelAll'd (reason: "parentDismiss"). Same LayerClient, no second client.
• Child stack — the stack a layer group opens onto; id derived from the parent's stackId + layerId via childStackId (`${parentStackId}~${parentLayerId}~${name}`).
• Validator (validate) — a Standard Schema or sync (input) => output fn that parses/validates a layer's payload at open; the layer stores the parsed output. Failure rejects open with a PayloadValidationError.
• createLayer — core factory: options + client → headless LayerHandle / ValidatedLayerHandle (layer ops + stack/client/options/current escapes; no reactive field).
• LayerHandle — return of plain createLayer. open/upsert take payload only; dismiss takes { id?, force? }; update / cancelQueued take { id? } (see cancelQueued).
• ValidatedLayerHandle — when options.validate is set: open/upsert = schema input; current/update = parsed output. Wired adapters also expose reactive state/queued/top as output.
• useLayer — adapter wired handle (createLayer + reactive state/queued/top). Svelte: createLayer; Angular: injectLayer.
• useLayerState / useLayerQueuedState / useQueuedStack — observe-only (mounted per-key / queued per-key / queued whole-stack); return LayerState[] (or framework wrappers). Renamed/added vs the old singular useLayer(key, …).
• current — live-checked bound instance on a handle (Layer | null); correlation + explicit { id } — not a hidden control default.