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`
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- solid-layers
- license
- MIT
- sources
- [ "https://stainless-code.com/layers/adapters/solid", "https://github.com/stainless-code/layers/blob/main/docs/architecture.md" ]
- keywords
- [ "tanstack-intent", "solid", "modal", "dialog", "stack", "typescript" ]
- metadata
- { "library": "@stainless-code/solid-layers", "framework": "solid", "library_version": "0.2.4" }
- description
- SolidJS adapter for @stainless-code/solid-layers; open UI from anywhere and manage ordered, named stacks with typed or fire-and-forget `open`
03 SKILL.md 正文
Solid layer/stack UI with @stainless-code/solid-layers
Open any layer from anywhere and manage modal, dialog, drawer, popover, or toast UI as an ordered, named stack. @stainless-code/solid-layers is the SolidJS 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/solid-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-drilling, lifting state, or threading callbacks. - 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/solid-layers
Core is included. solid-js (>=1.6) 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/solid-layers";
export type ConfirmPayload = { title: string };
export type ConfirmResponse = boolean;
function ConfirmDialog(
props: LayerComponentProps<ConfirmPayload, ConfirmResponse>,
) {
return (
<div role="dialog">
<h2>{props.payload.title}</h2>
<button type="button" onClick={() => void props.call.end(true)}>
Yes
</button>
<button type="button" onClick={() => void props.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 {
LayerClient,
LayerClientContext,
StackOutlet,
} from "@stainless-code/solid-layers";
const client = new LayerClient();
function App() {
return (
<LayerClientContext.Provider value={client}>
<StackOutlet stack="confirm" />
</LayerClientContext.Provider>
);
}
// 3. Call & await
import { useLayer } from "@stainless-code/solid-layers";
import { confirm } from "./confirm";
function Opener() {
const c = useLayer(confirm);
return (
<button
type="button"
onClick={async () => {
const ok = await c.open({ title: "Remove?" });
if (ok) deleteItem();
}}
>
Remove
</button>
);
}
Low-level bag-form: useLayerClient() + client.open({ ...confirm, payload }). Idiomatic create* aliases for observe/stack hooks (createStack, createLayerState, createQueuedStack, createLayerQueuedState). Wired handle stays useLayer; headless factory is core createLayer.
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, and 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. StackOutlet keys by id so state changes update props in place; parallel stacks may hold multiple same-key layers.
Wired handle: useLayer
const c = useLayer(confirm);
await c.open({ title: "Remove?" });
// c.state() / c.queued() / c.top() — accessors
Subscribing to stacks
Options-bag + optional trailing client; select (not selector). Call accessors inside JSX or createEffect.
useStack / useQueuedStack
const states = useStack({ stack: "confirm" });
const count = useStack({ stack: "confirm", select: (s) => s.length });
const queued = useQueuedStack({ stack: "confirm" });
useLayerState / useLayerQueuedState
Observe-only; Accessor<LayerState[]> for all same-key instances:
const states = useLayerState({ key: confirm.key, stack: "confirm" });
const top = () => states().at(-1);
StackSubscribe
Isolate a subscription in a render-prop component; children receives an Accessor<T>:
import { StackSubscribe } from "@stainless-code/solid-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). Layers are keyed by id so state changes update props in place without remounting. A missing component renders nothing and warns in development.
StackOutlet renders inline. Wrap it in Portal from solid-js/web when you need a specific DOM target.
Headless: useStackHandles
When you need custom hosts (switch by key, your own wrappers, alternate DOM slots):
import { useStackHandles } from "@stainless-code/solid-layers";
import { For } from "solid-js";
function CustomHost() {
const { states, getCall } = useStackHandles("modal");
return (
<For each={states()}>
{(s) =>
s.key[0] === "sheet" ? (
<Sheet call={getCall(s)} payload={s.payload} />
) : (
<Dialog call={getCall(s)} payload={s.payload} />
)
}
</For>
);
}
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/solid-layers";
const nested = layerOptions<{ label: string }>({
stack: "settings-nested",
key: ["settings", "advanced"],
component: AdvancedPanel,
});
function SettingsDrawer(
props: LayerComponentProps<{ title: string }, boolean>,
) {
const group = useLayerGroup(props.call);
return (
<div role="dialog" aria-label={props.payload.title}>
<button
type="button"
onClick={() =>
void group.open({ ...nested, payload: { label: "Advanced" } })
}
>
Open nested
</button>
<group.Outlet />
<button type="button" onClick={() => void props.call.dismiss(false)}>
Close
</button>
</div>
);
}
Returns { open, dismissAll, states, Outlet, stackId }. open pre-binds the child stack id; states is an Accessor<LayerState[]>.
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/solid-layers";
function ConfirmSave(props: LayerComponentProps<{ name: string }, boolean>) {
const flow = useMutationFlow(props.call);
return (
<div role="dialog">
<p>Save {props.payload.name}?</p>
<button
type="button"
disabled={flow.pending()}
onClick={() =>
void flow
.run(async () => {
await saveToServer(props.payload.name);
})
.orEnd(true)
}
>
{flow.pending() ? "Saving…" : "Save"}
</button>
<button type="button" onClick={() => void props.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/solid-layers";
const { StackProvider, useAppStack, AppHost, AppLayer } = createStackHook({
stack: "modal",
});
function SettingsDialog(props: LayerComponentProps) {
return (
<div role="dialog" aria-label="Settings">
<button type="button" onClick={() => void props.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>
);
}
useAppStack()—{ open, dismissAll, states }withstackpre-bound.statesis anAccessor<LayerState[]>.AppHost— rendersStackOutletfor the bound stack. Its props becomerootProps; an optional configuredHostreceives the same props and wraps the outlet.AppLayer— controlled open/close via props (open,payload,options,onResolved):
function ControlledSettings(props: { open: boolean; onClose: () => void }) {
return (
<AppLayer
options={settingsOpts}
open={props.open}
payload={{ title: "Settings" }}
onResolved={() => props.onClose()}
/>
);
}
Adapter API
| Kind | Name | Signature / shape |
|---|---|---|
| Context | LayerClientContext |
Context<LayerClient | undefined> |
| Hook | useLayerClient |
() => LayerClient |
| Hook | useLayer |
(options, client?) => WiredLayerHandle accessors + state/queued/top |
| Hook | useLayerState |
({ key, stack?, select?, compare? }, client?) => Accessor<LayerState[]> |
| Hook | useLayerQueuedState |
({ key, stack?, select?, compare? }, client?) => Accessor<LayerState[]> |
| Hook | useStack |
({ stack?, select?, compare? }, client?) => Accessor<T> |
| Hook | useQueuedStack |
({ stack?, select?, compare? }, client?) => Accessor<T> |
| Hook | useStackHandles |
(stack?, rootProps?) => StackHandles |
| Component | StackOutlet |
{ stack?, rootProps? } |
| Component | StackSubscribe |
{ stack?, selector, children: (value: Accessor<T>) => JSX } |
| 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 | StackHandles |
{ states: Accessor<LayerState[]>, getCall } |
| Type | MutationRun<R> |
{ orEnd(response) } |
| Type | MutationFlow<R> |
{ pending: Accessor<boolean>, 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/solid-layers, including LayerClient, LayerStack, layerOptions, layerKey, 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.
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`
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.