react-layers
React adapter for @stainless-code/react-layers; open UI from anywhere and manage ordered, named stacks with typed or fire-and-forget `open`
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- react-layers
- license
- MIT
- sources
- [ "https://stainless-code.com/layers/adapters/react", "https://github.com/stainless-code/layers/blob/main/docs/architecture.md" ]
- keywords
- [ "tanstack-intent", "react", "modal", "dialog", "stack", "typescript" ]
- metadata
- { "library": "@stainless-code/react-layers", "framework": "react", "library_version": "0.2.4" }
- description
- React adapter for @stainless-code/react-layers; open UI from anywhere and manage ordered, named stacks with typed or fire-and-forget `open`
03 SKILL.md 正文
React layer/stack UI with @stainless-code/react-layers
Open any layer from anywhere and manage modal, dialog, drawer, popover, or toast UI as an ordered, named stack. @stainless-code/react-layers is the React adapter for @stainless-code/layers; awaiting a typed result is optional, and fire-and-forget invocation (void client.open(...)) is equally first-class.
Named stacks, singletons with upsert and live update, serial queues, nested stacks, transitions, dismissal blockers, payload validation, and headless rendering each provide standalone value. The package re-exports @stainless-code/layers, so adapter and core APIs share one import path. For engine internals, use the layers core skill.
When to use this skill
- Reach for
@stainless-code/react-layersto open overlay UI imperatively from anywhere—components, effects, route guards, or non-UI code—and manage it as an ordered, named stack instead of prop-drillingisOpen, lifting state, or threadingonConfirmcallbacks. - It fits when you need any of: open/close from anywhere; await a typed result or fire-and-forget (both first-class); named/ordered stacks, singletons (
upsert) with liveupdate, or one-at-a-time queues; nested stacks (useLayerGroup), enter/exit animations, dismissal guards (blockers), payload validation, or headless rendering (useStackHandles).
Skip it only when: you have a single, always-local overlay opened from one component, with no return, stacking, queue, animation, or guard needs and no wish for a global registry.
Full fit matrix: When to use Layers.
Install
bun add @stainless-code/react-layers
Core is included. react is a required peer; install it separately if the app does not provide it.
Declare → Mount → Call
// 1. Declare a layer
import {
layerOptions,
type LayerComponentProps,
} from "@stainless-code/react-layers";
export type ConfirmPayload = { title: string };
export type ConfirmResponse = boolean;
function ConfirmDialog({
call,
payload,
}: LayerComponentProps<ConfirmPayload, ConfirmResponse>) {
return (
<div role="dialog">
<h2>{payload.title}</h2>
<button type="button" onClick={() => void call.end(true)}>
Yes
</button>
<button type="button" onClick={() => void call.end(false)}>
No
</button>
</div>
);
}
export const confirm = layerOptions<ConfirmPayload, ConfirmResponse>({
stack: "confirm",
key: ["confirm", "remove"],
component: ConfirmDialog,
exitingDelay: 200,
});
// 2. Mount the stack outlet once, high in the tree
import { StackProvider, StackOutlet } from "@stainless-code/react-layers";
function App() {
return (
<StackProvider>
<StackOutlet stack="confirm" />
</StackProvider>
);
}
// 3. Call & await
import { useLayer } from "@stainless-code/react-layers";
import { confirm } from "./confirm";
function Opener() {
const c = useLayer(confirm);
return (
<button
type="button"
onClick={async () => {
const ok: boolean = await c.open({ title: "Remove?" });
if (ok) deleteItem();
}}
>
Remove
</button>
);
}
Low-level: client.open({ ...confirm, payload }) or core createLayer(confirm, client).
The call context
Each layer component receives call (end/dismiss/update/setRunning/settle/ended/index/stackSize/root/stackId/layerId/addBlocker), payload, data, error, phase, transition, actionStatus, dismissing. Use await call.end(response) to resolve the caller's await and dismiss the layer (Promise<boolean> — false if a blocker vetoes). When undefined extends R (e.g. void toasts), omit the arg — call.end() / call.dismiss(). setRunning(true|false) flips actionStatus manually; useMutationFlow (below) wraps setRunning + end for the common save-then-close case.
Key vs id: key is the logical identity (find/upsert/gcTime); each mount gets a unique instance id. Use s.id for React list keys; parallel stacks may hold multiple same-key layers.
Wired handle: useLayer
import { useLayer } from "@stainless-code/react-layers";
import { confirm } from "./confirm";
function Opener() {
const c = useLayer(confirm);
return (
<button type="button" onClick={() => void c.open({ title: "Remove?" })}>
Remove
</button>
);
}
Validated I/O: glossary.
Subscribing to stacks
useStack / useQueuedStack
Options-bag + optional trailing client. select (not selector) projects the snapshot; compare defaults to Object.is:
import { useStack, useQueuedStack } from "@stainless-code/react-layers";
function ConfirmList() {
const states = useStack({ stack: "confirm" });
const queued = useQueuedStack({ stack: "confirm" });
return (
<ul>
{states.map((s) => (
<li key={s.id}>{String(s.payload)}</li>
))}
</ul>
);
}
const count = useStack({ stack: "confirm", select: (s) => s.length });
const top = useStack({ stack: "confirm", select: (s) => s.at(-1) ?? null });
useLayerState / useLayerQueuedState
Observe-only (no control). Returns LayerState[] for all same-key mounted / queued instances:
import {
useLayerState,
useLayerQueuedState,
} from "@stainless-code/react-layers";
import { confirm, type ConfirmPayload } from "./confirm";
function ActiveConfirm() {
const states = useLayerState<typeof confirm.key, ConfirmPayload>({
key: confirm.key,
stack: "confirm",
});
const top = states.at(-1);
if (!top) return null;
return <span>{top.payload.title}</span>;
}
StackSubscribe
Isolate a subscription in a render-prop component and pass its selected value to children:
import { StackSubscribe } from "@stainless-code/react-layers";
<StackSubscribe stack="confirm" selector={(s) => s.length}>
{(count) => <span>{count} open</span>}
</StackSubscribe>;
Rendering layers
StackOutlet is the default host. It maps each state to its registered component with full props (call, payload, data, error, phase, transition, actionStatus, dismissing). A missing component renders nothing and warns in development.
StackOutlet renders inline. Wrap it in your own createPortal (web) or root sibling / single host Modal / navigator overlay (React Native — same package, no react-dom peer) if you need a different target; sidecar and nested-portal hosting are consumer concerns, not built into the adapter.
Headless: useStackHandles
When you need custom hosts (switch by key, your own wrappers, alternate DOM slots):
import { useStackHandles } from "@stainless-code/react-layers";
function CustomHost() {
const { states, getCall } = useStackHandles("modal");
return states.map((s) =>
s.key[0] === "sheet" ? (
<Sheet key={s.id} call={getCall(s)} payload={s.payload} />
) : (
<Dialog key={s.id} call={getCall(s)} payload={s.payload} />
),
);
}
Nested layers
Inside a layer component, useLayerGroup(call) owns a child stack scoped to the parent's lifetime — parent dismiss / unmount cancelAlls it (LayerCancelledError).
import {
useLayerGroup,
layerOptions,
type LayerComponentProps,
} from "@stainless-code/react-layers";
const nested = layerOptions<{ label: string }>({
stack: "settings-nested",
key: ["settings", "advanced"],
component: AdvancedPanel,
});
function SettingsDrawer({
call,
payload,
}: LayerComponentProps<{ title: string }, boolean>) {
const group = useLayerGroup(call);
return (
<div role="dialog" aria-label={payload.title}>
<button
type="button"
onClick={() =>
void group.open({ ...nested, payload: { label: "Advanced" } })
}
>
Open nested
</button>
<group.Outlet />
<button type="button" onClick={() => void call.dismiss(false)}>
Close
</button>
</div>
);
}
Returns { open, dismissAll, states, Outlet, stackId }. open pre-binds the child stack id.
Async actions
Drive a layer's actionStatus while an async mutation runs, then end the layer on success:
import {
useMutationFlow,
type LayerComponentProps,
} from "@stainless-code/react-layers";
function ConfirmSave({
call,
payload,
}: LayerComponentProps<{ name: string }, boolean>) {
const flow = useMutationFlow(call);
return (
<div role="dialog">
<p>Save {payload.name}?</p>
<button
type="button"
disabled={flow.pending}
onClick={() =>
void flow
.run(async () => {
await saveToServer(payload.name);
})
.orEnd(true)
}
>
{flow.pending ? "Saving…" : "Save"}
</button>
<button type="button" onClick={() => void call.end(false)}>
Cancel
</button>
</div>
);
}
If the mutation throws, orEnd restores the idle status, leaves the layer open, and rethrows.
App chrome: createStackHook
Bind a stack id, optional client, and optional host wrapper once:
import {
createStackHook,
type LayerComponentProps,
} from "@stainless-code/react-layers";
const { StackProvider, useAppStack, AppHost, AppLayer } = createStackHook({
stack: "modal",
});
function SettingsDialog({ call }: LayerComponentProps) {
return (
<div role="dialog" aria-label="Settings">
<button type="button" onClick={() => void call.dismiss()}>
Close
</button>
</div>
);
}
function App() {
return (
<StackProvider>
<AppHost />
<ModalTrigger />
</StackProvider>
);
}
function ModalTrigger() {
const { open } = useAppStack();
return (
<button
type="button"
onClick={() =>
void open({
key: ["modal", "settings"],
component: SettingsDialog,
})
}
>
Open settings
</button>
);
}
Here, payload and response are both optional: open omits payload, is not
awaited, and SettingsDialog dismisses without a response.
useAppStack()—{ open, dismissAll, states }withstackpre-bound.AppHost— rendersStackOutletfor the bound stack. Its props becomerootProps; an optional configuredHostreceives the same props and the outlet aschildren.AppLayer— controlled open/close via props (open,payload,options,onResolved):
function ControlledSettings({
open,
onClose,
}: {
open: boolean;
onClose: () => void;
}) {
return (
<AppLayer
options={settingsOpts}
open={open}
payload={{ title: "Settings" }}
onResolved={() => onClose()}
/>
);
}
Adapter API
| Kind | Name | Signature / shape |
|---|---|---|
| Component | StackProvider |
{ client?, children } |
| Hook | useLayerClient |
() => LayerClient |
| Hook | useLayer |
(options, client?) => WiredLayerHandle + state/queued/top |
| Hook | useLayerState |
({ key, stack?, select?, compare? }, client?) => LayerState[] |
| Hook | useLayerQueuedState |
({ key, stack?, select?, compare? }, client?) => LayerState[] |
| Hook | useStack |
({ stack?, select?, compare? }, client?) => T |
| Hook | useQueuedStack |
({ stack?, select?, compare? }, client?) => T |
| Hook | useStackHandles |
(stack?, rootProps?) => StackHandles |
| Component | StackOutlet |
{ stack?, rootProps? } |
| Component | StackSubscribe |
{ stack?, selector, children } |
| Hook | useMutationFlow |
<P, R, RootProps?>(call) => MutationFlow<R> |
| Hook | useLayerGroup |
<P, R, RootProps?>(call, options?) => LayerGroup |
| Factory | createStackHook |
<HostProps>({ stack?, client?, Host? }) => StackHook<HostProps> |
| Type | WiredLayerHandle |
LayerHandle + state/queued/top |
| Type | WiredValidatedLayerHandle |
validated WiredLayerHandle |
| Type | StackHandles |
{ states, getCall } |
| Type | MutationRun<R> |
{ orEnd(response) } |
| Type | MutationFlow<R> |
{ pending, run } |
| Type | ScopedOpen |
open with stack pre-bound |
| Type | LayerGroup |
{ open, dismissAll, states, Outlet, stackId } |
| Type | AppStack |
{ open, dismissAll, states } |
| Type | AppLayerProps<P, R> |
{ options, open, payload, onResolved? } |
| Type | StackHook<HostProps> |
{ StackProvider, useAppStack, AppHost, AppLayer } |
Core re-exports (same import path)
Core exports are available from @stainless-code/react-layers, including LayerClient, LayerStack, layerOptions, layerKey, createLayer, LayerHandle, ValidatedLayerHandle, LayerState, LayerComponentProps, LayerCallContext, createLayerGroup, DataTag, ResponseOf, and ErrorOf:
- Key inference:
layerOptions/layerKeyDataTagbranding —await client.open(...)infersR. - Singleton + live updates:
upsert: trueonopen;client.getStack(id).update(layer, patch). - Serial scope:
new LayerClient({ defaultStackOptions: { confirm: { scope: { strategy: "serial" } } } }). - Validation:
validateonlayerOptionsoropen; narrowPayloadValidationErrorviaisPayloadValidationError. - Blockers:
call.addBlocker/stack.addBlocker;dismissingflag;dismissAllmodes.
See the layers skill for full engine coverage (transitions, blockers, validation, serial scope, multi-stack).
04 同仓库更多 Skills
vue-layers
Vue adapter for @stainless-code/vue-layers; open UI from anywhere and manage ordered, named stacks with typed or fire-and-forget `open`
svelte-layers
Svelte bindings for @stainless-code/svelte-layers (runes + stores). Use to open overlay UI imperatively from anywhere, manage ordered named stacks, choose the Svelte 5.7+ runes or Svelte 3+ stores entry, and wire layer context or stack outlets.
solid-layers
SolidJS adapter for @stainless-code/solid-layers; open UI from anywhere and manage ordered, named stacks with typed or fire-and-forget `open`
preact-layers
Preact adapter for @stainless-code/preact-layers — use for awaitable confirm flows, singleton toasts, nested drawers, stack subscriptions, and custom layer hosts
lit-layers
Lit adapter for @stainless-code/lit-layers; open UI from anywhere and manage ordered, named stacks with typed or fire-and-forget `open` via Reactive Controllers and custom elements
layers
UI-agnostic layer stack engine for @stainless-code/layers. Use for opening layers imperatively from anywhere, ordered named stacks, typed await or fire-and-forget calls, lifecycle control, blockers, validation, singleton updates, serial or nested layers, multi-stack orchestration, or building a library/framework adapter.