@zvk/composite 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @zvk/composite Changelog
 
+## [0.1.4](https://github.com/brandon-schabel/zvk/compare/composite-v0.1.3...composite-v0.1.4) (2026-06-25)
+
+
+### Features
+
+* improve out-of-box DX and UI components ([#24](https://github.com/brandon-schabel/zvk/issues/24)) ([b01272a](https://github.com/brandon-schabel/zvk/commit/b01272a2b35099f5e1fa1dea5883687a0fb4c2e6))
+
 ## [0.1.3](https://github.com/brandon-schabel/zvk/compare/composite-v0.1.2...composite-v0.1.3) (2026-06-20)
 
 

package/README.md

@@ -18,11 +18,11 @@ Composite typography inherits the shared `@zvk/ui` font-family slots: primary fo
 The package is organized around product-surface domains so repeated shell structure stays readable without creating new public import groups. This map is for internal ownership and review; it does not add domain barrel imports to the public API.
 
 - `shell`: `AppWorkspaceShell`, `PageScaffold`, `FeatureShell`
-- `navigation`: `WorkspaceHeader`, `BreadcrumbPageHeader`, `SectionedWorkspaceShell`, `EntitySwitcherMenu`, `CommandPaletteShell`, `LinkAction`
+- `navigation`: `WorkspaceHeader`, `BreadcrumbPageHeader`, `SimpleWorkspaceShell`, `SplitWorkspaceShell`, `SectionedWorkspaceShell`, `ResourceExplorerShell`, `EntitySwitcherMenu`, `CommandPaletteShell`, `LinkAction`
 - `state`: `StateSurface`, `RouteStateFrame`
 - `forms`: `FormSurface`, `ConfirmActionDialog`
 - `data`: `EntityCard`, `EntityListSection`, `SummaryMetricGrid`, `DataTablePageFrame`, `DataTableControlBar`
-- `workflow`: `IntegrationStatusCard`, `WorkflowStatusCard`, `ProcessListPanel`
+- `workflow`: `IntegrationStatusCard`, `WorkflowStatusCard`, `ProcessListPanel`, `WizardShell`
 - `settings`: `SettingsHubList`, `ParameterEditor`, `SettingsSectionStack`
 - `ai`: `ProviderModelSelector`, `ConversationDirectory`, `StickyComposer`
 - `activity`: `ActivityFeed`
@@ -49,7 +49,7 @@ Keep these in the consuming app or a more specific package:
 - `./styles.css` is a stable stylesheet export.
 - `./package.json` is stable metadata and tooling export, not a component surface.
 
-Watched surfaces: `EntitySwitcherMenu`, `CommandPaletteShell`, `ConfirmActionDialog`, `IntegrationStatusCard`, `WorkflowStatusCard`, `ProcessListPanel`, `ActivityFeed`, `ParameterEditor`, `ProviderModelSelector`, `ConversationDirectory`, `StickyComposer`, and `DataTableControlBar`.
+Watched surfaces: `SimpleWorkspaceShell`, `SplitWorkspaceShell`, `ResourceExplorerShell`, `WizardShell`, `EntitySwitcherMenu`, `CommandPaletteShell`, `ConfirmActionDialog`, `IntegrationStatusCard`, `WorkflowStatusCard`, `ProcessListPanel`, `ActivityFeed`, `ParameterEditor`, `ProviderModelSelector`, `ConversationDirectory`, `StickyComposer`, and `DataTableControlBar`.
 
 ## App Surface Exports
 
@@ -62,7 +62,10 @@ App surfaces are intentionally router-agnostic and UI-only:
 | `CommandPaletteShell` | `@zvk/composite/command-palette-shell` | Controlled command palette dialog with grouped commands and app-owned command execution. |
 | `WorkspaceHeader` | `@zvk/composite/workspace-header` | Page header with title, description, status, metadata, and actions. |
 | `BreadcrumbPageHeader` | `@zvk/composite/breadcrumb-page-header` | Breadcrumb-aware page header for nested workspace routes. |
+| `SimpleWorkspaceShell` | `@zvk/composite/simple-workspace-shell` | Generic workspace frame with optional navigation, header, toolbar, actions, aside, footer, and content slots. |
+| `SplitWorkspaceShell` | `@zvk/composite/split-workspace-shell` | Resizable two-pane workspace shell built on `@zvk/ui/splitter` for app-owned resource/detail or editor/preview layouts. |
 | `SectionedWorkspaceShell` | `@zvk/composite/sectioned-workspace-shell` | Sectioned navigation shell for dense workspace panels. |
+| `ResourceExplorerShell` | `@zvk/composite/resource-explorer-shell` | Tree plus result-list explorer shell for app-owned repositories, files, records, resources, or docs. |
 | `PageScaffold` | `@zvk/composite/page-scaffold` | Page layout with toolbar, aside, constrained width, and content slots. |
 | `FeatureShell` | `@zvk/composite/feature-shell` | Reusable feature page layout with title, description, actions, metadata, and toolbar slots. |
 | `StateSurface` | `@zvk/composite/state-surface` | Empty, loading, error, permission, success, and search-empty state panels. |
@@ -76,6 +79,7 @@ App surfaces are intentionally router-agnostic and UI-only:
 | `IntegrationStatusCard` | `@zvk/composite/integration-status-card` | Provider/API/service connection status card with status, badges, metadata, metrics, actions, and errors. |
 | `WorkflowStatusCard` | `@zvk/composite/workflow-status-card` | Workflow, run, import, queue, deploy, or parser status card with progress and current-step slots. |
 | `ProcessListPanel` | `@zvk/composite/process-list-panel` | List panel for app-owned background work items, rendered by default through workflow status cards. |
+| `WizardShell` | `@zvk/composite/wizard-shell` | Step-by-step workflow frame built on `@zvk/ui/stepper`, with app-owned validation, submission, and persistence. |
 | `ActivityFeed` | `@zvk/composite/activity-feed` | Ordered activity, audit, workflow, comment, or notification feed with app-owned ordering and timestamps. |
 | `ParameterEditor` | `@zvk/composite/parameter-editor` | Grouped parameter/settings rows where controls, validation, persistence, and reset actions stay in the app. |
 | `SettingsSectionStack` | `@zvk/composite/settings-section-stack` | Settings page section stack with controlled dirty/save presentation and app-owned forms. |
@@ -135,11 +139,14 @@ Migrate repeated app-owned shells into `@zvk/composite` only when the repeated p
 | Repeated app surface | Composite target | Keep in the app |
 | --- | --- | --- |
 | Product workspace chrome with brand, account, nav, switcher, command, and content slots | `AppWorkspaceShell` | route tree, auth context, workspace persistence, account menu actions |
+| Generic workspace pages with navigation, actions, sidebars, and footer chrome | `SimpleWorkspaceShell` | route tree, permissions, data loading, selected-record state |
+| Split resource/detail, editor/preview, or list/inspector workspaces | `SplitWorkspaceShell` | persistence of pane sizes, route params, selected entity fetching, mobile drawer behavior |
 | Tab-with-sidebar or dense route workspace wrappers | `SectionedWorkspaceShell` | active route, URL updates, permission gating, tab persistence |
+| Tree plus result-list explorers | `ResourceExplorerShell` | search/filter algorithms, repository adapters, file I/O, routing, permissions, preview data fetching |
 | Route/page loading, empty, permission, error, and ready wrappers | `RouteStateFrame` or `StateSurface` | loader state, retry mutations, fetch errors, domain-specific empty data |
 | Page headers and breadcrumb headers | `WorkspaceHeader` or `BreadcrumbPageHeader` | router links, breadcrumb construction, page-level data policy |
 | Settings index pages and settings detail pages | `SettingsHubList` or `SettingsSectionStack` | route anchors, dirty-state calculation, validation, persistence, permission decisions |
-| Provider/API status cards, workflow cards, and process lists | `IntegrationStatusCard`, `WorkflowStatusCard`, or `ProcessListPanel` | health checks, polling, process control, retries, logs, provider credentials |
+| Provider/API status cards, workflow cards, process lists, and setup flows | `IntegrationStatusCard`, `WorkflowStatusCard`, `ProcessListPanel`, or `WizardShell` | health checks, polling, process control, retries, logs, provider credentials, validation, submission |
 | Audit logs, run histories, review threads, and notification feeds | `ActivityFeed` | event fetching, ordering, timestamps, subscriptions, comment mutations, infinite scroll |
 | AI model choices, conversation sidebars, and sticky prompt forms | `ProviderModelSelector`, `ConversationDirectory`, or `StickyComposer` | catalogs, compatibility rules, message fetching, prompt validation, streaming, tools, persistence |
 | Table page wrappers and table control bars | `DataTablePageFrame` or `DataTableControlBar` | table engine adapters, query state, sorting, filters, pagination, row selection, saved views |
@@ -457,6 +464,116 @@ import { DataTableControlBar } from "@zvk/composite/data-table-control-bar";
 />;
 ```
 
+## Local-First Workspace Recipe
+
+For a local-first todo or list workspace, reach for `AppWorkspaceShell` first, then use `FeatureShell` or `PageScaffold` for the page body, `SummaryMetricGrid` for counts, `EntityListSection` for the repeated list, `FormSurface` for the native form, and `StateSurface` for empty/loading/error presentation.
+
+Keep the app-owned parts small and explicit:
+
+- route state, persistence, and server actions stay in the app;
+- fields, details, and validation stay in app-owned primitives or local helpers;
+- shell chrome stays in `@zvk/composite`, not custom page CSS;
+- aim for under 120 lines of app-local CSS before you add another shell wrapper.
+
+```tsx
+import "@zvk/ui/styles.css";
+import "@zvk/composite/styles.css";
+
+import {
+  AppWorkspaceShell,
+  EntityListSection,
+  FeatureShell,
+  FormSurface,
+  StateSurface,
+  SummaryMetricGrid
+} from "@zvk/composite";
+
+type Task = {
+  id: string;
+  title: string;
+  status: "open" | "doing" | "done";
+  dueLabel: string;
+};
+
+async function createTask(formData: FormData) {
+  "use server";
+
+  // App-owned mutation, persistence, and revalidation.
+  void formData;
+}
+
+export function TasksPage({ tasks }: { tasks: readonly Task[] }) {
+  return (
+    <AppWorkspaceShell
+      brand={<strong>Northline</strong>}
+      navigation={<nav aria-label="Workspace navigation">...</nav>}
+    >
+      <FeatureShell
+        actions={<button type="button">Sync</button>}
+        description="Keep the workspace local-first and fast to scan."
+        title="Tasks"
+      >
+        <SummaryMetricGrid
+          columns={3}
+          metrics={[
+            { id: "open", label: "Open", value: 12 },
+            { id: "doing", label: "In progress", value: 4 },
+            { id: "done", label: "Done", value: 31 }
+          ]}
+          title="Today"
+        />
+
+        {tasks.length > 0 ? (
+          <EntityListSection
+            description="App-owned data, routes, and filters stay outside the composite."
+            getItemKey={(task) => task.id}
+            items={tasks}
+            renderItem={(task) => (
+              <article>
+                <h3>{task.title}</h3>
+                <p>
+                  {task.status} · {task.dueLabel}
+                </p>
+              </article>
+            )}
+            title="Backlog"
+          />
+        ) : (
+          <StateSurface
+            description="Add the first task with the form below."
+            state="empty"
+            title="No tasks yet"
+          />
+        )}
+      </FeatureShell>
+
+      <FormSurface
+        action={createTask}
+        description="Native inputs and server actions stay app-owned."
+        footer={<button type="submit">Create task</button>}
+        method="post"
+        title="Add task"
+      >
+        <label>
+          Title
+          <input name="title" required />
+        </label>
+        <label>
+          Notes
+          <textarea name="notes" rows={4} />
+        </label>
+      </FormSurface>
+    </AppWorkspaceShell>
+  );
+}
+```
+
+Checklist:
+
+- use `@zvk/composite` before adding custom shell CSS;
+- keep primitives for fields and details only;
+- prefer native forms and app-owned server actions over custom mutation plumbing.
+
 ## Repo Skill
 
 Use `.codex/skills/use-zvk-composite/SKILL.md` when maintaining this package.

package/dist/domains/navigation.d.ts

@@ -6,5 +6,11 @@ export { EntitySwitcherMenu } from "../navigation/entity-switcher-menu.js";
 export type { EntitySwitcherGroup, EntitySwitcherItem, EntitySwitcherMenuProps, EntitySwitcherMenuSize } from "../navigation/entity-switcher-menu.js";
 export { LinkAction } from "../navigation/link-action.js";
 export type { LinkActionProps } from "../navigation/link-action.js";
+export { ResourceExplorerShell } from "../navigation/resource-explorer-shell.js";
+export type { ResourceExplorerShellProps, ResourceExplorerShellResource } from "../navigation/resource-explorer-shell.js";
 export { SectionedWorkspaceShell } from "../navigation/sectioned-workspace-shell.js";
 export type { SectionedWorkspaceItem, SectionedWorkspaceSection, SectionedWorkspaceShellProps } from "../navigation/sectioned-workspace-shell.js";
+export { SimpleWorkspaceShell } from "../navigation/simple-workspace-shell.js";
+export type { SimpleWorkspaceShellProps } from "../navigation/simple-workspace-shell.js";
+export { SplitWorkspaceShell } from "../navigation/split-workspace-shell.js";
+export type { SplitWorkspaceShellProps } from "../navigation/split-workspace-shell.js";

package/dist/domains/navigation.js

@@ -2,4 +2,7 @@ export { BreadcrumbPageHeader, WorkspaceHeader } from "../navigation/workspace-h
 export { CommandPaletteShell } from "../navigation/command-palette-shell.js";
 export { EntitySwitcherMenu } from "../navigation/entity-switcher-menu.js";
 export { LinkAction } from "../navigation/link-action.js";
+export { ResourceExplorerShell } from "../navigation/resource-explorer-shell.js";
 export { SectionedWorkspaceShell } from "../navigation/sectioned-workspace-shell.js";
+export { SimpleWorkspaceShell } from "../navigation/simple-workspace-shell.js";
+export { SplitWorkspaceShell } from "../navigation/split-workspace-shell.js";

package/dist/domains/workflow.d.ts

@@ -2,5 +2,7 @@ export { IntegrationStatusCard } from "../integrations/integration-status-card.j
 export type { IntegrationStatusCardProps, IntegrationStatusTone } from "../integrations/integration-status-card.js";
 export { ProcessListPanel } from "../workflows/process-list-panel.js";
 export type { ProcessListPanelItem, ProcessListPanelProps } from "../workflows/process-list-panel.js";
+export { WizardShell } from "../workflows/wizard-shell.js";
+export type { WizardShellProps, WizardShellStep, WizardShellStepStatus } from "../workflows/wizard-shell.js";
 export { WorkflowStatusCard } from "../workflows/workflow-status-card.js";
 export type { WorkflowStatusCardProps, WorkflowStatusTone } from "../workflows/workflow-status-card.js";

package/dist/domains/workflow.js

@@ -1,3 +1,4 @@
 export { IntegrationStatusCard } from "../integrations/integration-status-card.js";
 export { ProcessListPanel } from "../workflows/process-list-panel.js";
+export { WizardShell } from "../workflows/wizard-shell.js";
 export { WorkflowStatusCard } from "../workflows/workflow-status-card.js";

package/dist/layout/page-scaffold.js

@@ -1,19 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../utils/cn.js";
+import { hasRenderableShellSlot, ShellHeaderChrome } from "../navigation/shell-slot-rendering.js";
 import { WorkspaceHeader } from "../navigation/workspace-header.js";
 export function PageScaffold({ actions, aside, children, className, description, eyebrow, footer, headerAlign, headingLevel, maxWidth = "xl", ref, state, status, title, toolbar, ...props }) {
-    const hasTitle = title !== undefined && title !== null && title !== false;
-    const hasHeader = Boolean(hasTitle || actions || toolbar);
-    const hasAside = Boolean(aside);
+    const hasActions = hasRenderableShellSlot(actions);
+    const hasAside = hasRenderableShellSlot(aside);
+    const hasDescription = hasRenderableShellSlot(description);
+    const hasEyebrow = hasRenderableShellSlot(eyebrow);
+    const hasFooter = hasRenderableShellSlot(footer);
+    const hasState = hasRenderableShellSlot(state);
+    const hasStatus = hasRenderableShellSlot(status);
+    const hasTitle = hasRenderableShellSlot(title);
+    const hasToolbar = hasRenderableShellSlot(toolbar);
+    const hasHeader = hasTitle || hasEyebrow || hasDescription || hasStatus || hasToolbar || hasActions;
     const headerProps = {
-        ...(actions === undefined ? {} : { actions }),
-        ...(description === undefined ? {} : { description }),
-        ...(eyebrow === undefined ? {} : { eyebrow }),
+        ...(hasActions ? { actions } : {}),
+        ...(hasDescription ? { description } : {}),
+        ...(hasEyebrow ? { eyebrow } : {}),
         ...(headerAlign === undefined ? {} : { align: headerAlign }),
         ...(headingLevel === undefined ? {} : { headingLevel }),
-        ...(status === undefined ? {} : { status }),
-        ...(toolbar === undefined ? {} : { toolbar })
+        ...(hasStatus ? { status } : {}),
+        ...(hasToolbar ? { toolbar } : {})
     };
-    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-page-scaffold", className), "data-max-width": maxWidth, "data-with-aside": hasAside ? "true" : "false", children: [hasTitle ? (_jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-page-scaffold__header", title: title })) : hasHeader ? (_jsxs("div", { className: "zvk-composite-page-scaffold__header zvk-composite-page-scaffold__header--controls-only", children: [toolbar ? _jsx("div", { className: "zvk-composite-page-scaffold__toolbar", children: toolbar }) : null, actions ? _jsx("div", { className: "zvk-composite-page-scaffold__actions", children: actions }) : null] })) : null, state ? _jsx("div", { className: "zvk-composite-page-scaffold__state", children: state }) : null, _jsxs("div", { className: "zvk-composite-page-scaffold__grid", children: [_jsx("main", { className: "zvk-composite-page-scaffold__main", children: children }), hasAside ? _jsx("aside", { className: "zvk-composite-page-scaffold__aside", children: aside }) : null] }), footer ? _jsx("footer", { className: "zvk-composite-page-scaffold__footer", children: footer }) : null] }));
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-page-scaffold", className), "data-max-width": maxWidth, "data-with-aside": hasAside ? "true" : "false", children: [hasHeader && hasTitle ? (_jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-page-scaffold__header", title: title })) : hasHeader ? (_jsx(ShellHeaderChrome, { actions: actions, align: headerAlign, className: "zvk-composite-page-scaffold__header", description: description, eyebrow: eyebrow, status: status, toolbar: toolbar })) : null, hasState ? _jsx("div", { className: "zvk-composite-page-scaffold__state", children: state }) : null, _jsxs("div", { className: "zvk-composite-page-scaffold__grid", children: [_jsx("main", { className: "zvk-composite-page-scaffold__main", children: children }), hasAside ? _jsx("aside", { className: "zvk-composite-page-scaffold__aside", children: aside }) : null] }), hasFooter ? _jsx("footer", { className: "zvk-composite-page-scaffold__footer", children: footer }) : null] }));
 }

package/dist/navigation/command-palette-shell.d.ts

@@ -20,6 +20,7 @@ export interface CommandPaletteShellProps extends Omit<React.HTMLAttributes<HTML
     groups: readonly CommandPaletteGroup[];
     label?: React.ReactNode | undefined;
     loading?: boolean | undefined;
+    loadingLabel?: React.ReactNode | undefined;
     onCommandSelect?: ((command: CommandPaletteCommand) => void) | undefined;
     onOpenChange: (open: boolean) => void;
     onQueryChange?: ((query: string) => void) | undefined;
@@ -28,4 +29,4 @@ export interface CommandPaletteShellProps extends Omit<React.HTMLAttributes<HTML
     query?: string | undefined;
     ref?: React.Ref<HTMLDivElement> | undefined;
 }
-export declare function CommandPaletteShell({ className, defaultQuery, empty, footer, groups, label, loading, onCommandSelect, onOpenChange, onQueryChange, open, placeholder, query, ref, ...props }: CommandPaletteShellProps): React.JSX.Element;
+export declare function CommandPaletteShell({ className, defaultQuery, empty, footer, groups, label, loading, loadingLabel, onCommandSelect, onOpenChange, onQueryChange, open, placeholder, query, ref, ...props }: CommandPaletteShellProps): React.JSX.Element;

package/dist/navigation/command-palette-shell.js

@@ -5,18 +5,8 @@ import * as React from "react";
 import { Command } from "@zvk/ui/command";
 import { Dialog } from "@zvk/ui/dialog";
 import { cn } from "../utils/cn.js";
-function useControllableValue({ defaultValue, onChange, value }) {
-    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
-    const resolvedValue = value ?? uncontrolledValue;
-    const setValue = React.useCallback((nextValue) => {
-        if (value === undefined) {
-            setUncontrolledValue(nextValue);
-        }
-        onChange?.(nextValue);
-    }, [onChange, value]);
-    return [resolvedValue, setValue];
-}
-export function CommandPaletteShell({ className, defaultQuery = "", empty = "No commands found.", footer, groups, label = "Command menu", loading = false, onCommandSelect, onOpenChange, onQueryChange, open, placeholder = "Search commands...", query, ref, ...props }) {
+import { useControllableValue } from "../utils/use-controllable-value.js";
+export function CommandPaletteShell({ className, defaultQuery = "", empty = "No commands found.", footer, groups, label = "Command menu", loading = false, loadingLabel = "Loading...", onCommandSelect, onOpenChange, onQueryChange, open, placeholder = "Search commands...", query, ref, ...props }) {
     const [resolvedQuery, setResolvedQuery] = useControllableValue({
         defaultValue: defaultQuery,
         ...(onQueryChange ? { onChange: onQueryChange } : {}),
@@ -30,7 +20,7 @@ export function CommandPaletteShell({ className, defaultQuery = "", empty = "No
         onCommandSelect?.(command);
         onOpenChange(false);
     }, [onCommandSelect, onOpenChange]);
-    return (_jsx(Dialog, { ...props, ...dialogProps, className: cn("zvk-composite-command-palette-shell", className), onOpenChange: onOpenChange, open: open, children: _jsxs(Dialog.Content, { className: "zvk-composite-command-palette-shell__content", children: [_jsx(Dialog.Title, { className: "zvk-composite-command-palette-shell__title", children: label }), _jsxs(Command, { className: "zvk-composite-command-palette-shell__command", onValueChange: setResolvedQuery, value: resolvedQuery, children: [_jsx(Command.Input, { className: "zvk-composite-command-palette-shell__search", placeholder: placeholder }), _jsxs(Command.List, { className: "zvk-composite-command-palette-shell__list", children: [loading ? (_jsx("div", { className: "zvk-composite-command-palette-shell__state", "data-state": "loading", children: "Loading..." })) : null, !loading && !hasCommands ? (_jsx("div", { className: "zvk-composite-command-palette-shell__state", "data-state": "empty", children: empty })) : null, !loading && hasCommands ? _jsx(Command.Empty, { children: empty }) : null, !loading
+    return (_jsx(Dialog, { ...props, ...dialogProps, className: cn("zvk-composite-command-palette-shell", className), onOpenChange: onOpenChange, open: open, children: _jsxs(Dialog.Content, { className: "zvk-composite-command-palette-shell__content", children: [_jsx(Dialog.Title, { className: "zvk-composite-command-palette-shell__title", children: label }), _jsxs(Command, { className: "zvk-composite-command-palette-shell__command", onValueChange: setResolvedQuery, value: resolvedQuery, children: [_jsx(Command.Input, { className: "zvk-composite-command-palette-shell__search", placeholder: placeholder }), _jsxs(Command.List, { className: "zvk-composite-command-palette-shell__list", children: [loading ? (_jsx("div", { className: "zvk-composite-command-palette-shell__state", "data-state": "loading", children: loadingLabel })) : null, !loading && !hasCommands ? (_jsx("div", { className: "zvk-composite-command-palette-shell__state", "data-state": "empty", children: empty })) : null, !loading && hasCommands ? _jsx(Command.Empty, { children: empty }) : null, !loading
                                     ? groups.map((group) => (_jsx(Command.Group, { className: "zvk-composite-command-palette-shell__group", heading: group.label, children: group.commands.map((command) => {
                                             const commandProps = {
                                                 ...(command.disabled !== undefined ? { disabled: command.disabled } : {}),

package/dist/navigation/entity-switcher-menu.js

@@ -6,17 +6,7 @@ import { Button } from "@zvk/ui/button";
 import { Command } from "@zvk/ui/command";
 import { Popover } from "@zvk/ui/popover";
 import { cn } from "../utils/cn.js";
-function useControllableValue({ defaultValue, onChange, value }) {
-    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
-    const resolvedValue = value ?? uncontrolledValue;
-    const setValue = React.useCallback((nextValue) => {
-        if (value === undefined) {
-            setUncontrolledValue(nextValue);
-        }
-        onChange?.(nextValue);
-    }, [onChange, value]);
-    return [resolvedValue, setValue];
-}
+import { useControllableValue } from "../utils/use-controllable-value.js";
 function hasRenderableNode(value) {
     return value !== undefined && value !== null && value !== false;
 }

package/dist/navigation/resource-explorer-shell.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+export interface ResourceExplorerShellResource {
+    badge?: React.ReactNode | undefined;
+    children?: readonly ResourceExplorerShellResource[] | undefined;
+    description?: React.ReactNode | undefined;
+    disabled?: boolean | undefined;
+    icon?: React.ReactNode | undefined;
+    id: string;
+    label: React.ReactNode;
+    meta?: React.ReactNode | undefined;
+    textValue: string;
+}
+export interface ResourceExplorerShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    activeKey?: string | undefined;
+    empty?: React.ReactNode | undefined;
+    expandedKeys?: readonly string[] | undefined;
+    footer?: React.ReactNode | undefined;
+    label: string;
+    loading?: boolean | undefined;
+    onExpandedKeysChange?: ((keys: string[]) => void) | undefined;
+    onItemAction?: ((id: string, item: ResourceExplorerShellResource) => void) | undefined;
+    onSelectedKeysChange?: ((keys: string[]) => void) | undefined;
+    preview?: React.ReactNode | undefined;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    resultItems?: readonly ResourceExplorerShellResource[] | undefined;
+    search?: React.ReactNode | undefined;
+    selectedKeys?: readonly string[] | undefined;
+    toolbar?: React.ReactNode | undefined;
+    treeItems: readonly ResourceExplorerShellResource[];
+}
+export declare function ResourceExplorerShell({ activeKey, className, empty, expandedKeys, footer, label, loading, onExpandedKeysChange, onItemAction, onSelectedKeysChange, preview, ref, resultItems, search, selectedKeys, toolbar, treeItems, ...props }: ResourceExplorerShellProps): React.JSX.Element;

package/dist/navigation/resource-explorer-shell.js

@@ -0,0 +1,30 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { GridList } from "@zvk/ui/grid-list";
+import { ListRow } from "@zvk/ui/list-row";
+import { TreeView } from "@zvk/ui/tree-view";
+import { cn } from "../utils/cn.js";
+function renderResourceRow(item, selected) {
+    return (_jsxs(ListRow, { selected: selected, variant: "plain", children: [item.icon ? _jsx(ListRow.Leading, { children: item.icon }) : null, _jsxs(ListRow.Content, { children: [_jsx(ListRow.Title, { children: item.label }), item.description ? _jsx(ListRow.Description, { children: item.description }) : null] }), item.meta ? _jsx(ListRow.Meta, { children: item.meta }) : null, item.badge ? _jsx(ListRow.Trailing, { children: item.badge }) : null] }));
+}
+export function ResourceExplorerShell({ activeKey, className, empty = "No resources found.", expandedKeys, footer, label, loading = false, onExpandedKeysChange, onItemAction, onSelectedKeysChange, preview, ref, resultItems, search, selectedKeys, toolbar, treeItems, ...props }) {
+    const records = resultItems ?? treeItems;
+    const selectedProps = {
+        ...(selectedKeys === undefined ? {} : { selectedKeys }),
+        ...(onSelectedKeysChange === undefined ? {} : { onSelectedKeysChange })
+    };
+    const treeProps = {
+        ...(activeKey === undefined ? {} : { activeKey }),
+        ...(expandedKeys === undefined ? { defaultExpandedKeys: treeItems.slice(0, 1).map((item) => item.id) } : {}),
+        ...(expandedKeys === undefined ? {} : { expandedKeys }),
+        ...(onExpandedKeysChange === undefined ? {} : { onExpandedKeysChange }),
+        ...(onItemAction === undefined ? {} : { onItemAction }),
+        ...selectedProps
+    };
+    const gridProps = {
+        ...(onItemAction === undefined ? {} : { onAction: onItemAction }),
+        ...selectedProps
+    };
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-resource-explorer-shell", className), "data-with-preview": preview ? "true" : undefined, children: [_jsxs("aside", { className: "zvk-composite-resource-explorer-shell__tree", children: [_jsx("div", { className: "zvk-composite-resource-explorer-shell__tree-header", children: _jsx("strong", { children: label }) }), search ? _jsx("div", { className: "zvk-composite-resource-explorer-shell__search", children: search }) : null, _jsx(TreeView, { ...treeProps, "aria-label": `${label} tree`, getItemChildren: (item) => item.children, getItemId: (item) => item.id, getItemLabel: (item) => item.textValue, isItemDisabled: (item) => item.disabled === true, items: treeItems, renderItem: (item) => (_jsxs("span", { className: "zvk-composite-resource-explorer-shell__tree-item", children: [item.icon ? _jsx("span", { className: "zvk-composite-resource-explorer-shell__tree-item-icon", children: item.icon }) : null, _jsx("span", { children: item.label })] })), selectionMode: "single" }), footer ? _jsx("div", { className: "zvk-composite-resource-explorer-shell__footer", children: footer }) : null] }), _jsxs("section", { className: "zvk-composite-resource-explorer-shell__results", "aria-label": `${label} results`, children: [toolbar ? _jsx("div", { className: "zvk-composite-resource-explorer-shell__toolbar", children: toolbar }) : null, _jsx(GridList, { ...gridProps, "aria-label": `${label} resources`, emptyState: empty, getItemId: (item) => item.id, getItemTextValue: (item) => item.textValue, isItemDisabled: (item) => item.disabled === true, items: records, loading: loading, loadingState: "Loading resources...", renderItem: (item, state) => renderResourceRow(item, state.selected), selectionMode: "single" })] }), preview ? _jsx("aside", { className: "zvk-composite-resource-explorer-shell__preview", children: preview }) : null] }));
+}

package/dist/navigation/sectioned-workspace-shell.js

@@ -2,26 +2,33 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { SectionedSidebarNav } from "@zvk/ui/sectioned-sidebar-nav";
 import { cn } from "../utils/cn.js";
+import { hasRenderableShellSlot, ShellHeaderChrome } from "./shell-slot-rendering.js";
 import { WorkspaceHeader } from "./workspace-header.js";
 export function SectionedWorkspaceShell({ actions, activeItemId, children, className, description, footer, headingLevel, navLabel = "Workspace navigation", onItemSelect, ref, sections, sidebarFooter, title, toolbar, ...props }) {
-    const hasHeader = Boolean(title || description || actions || toolbar);
+    const hasActions = hasRenderableShellSlot(actions);
+    const hasDescription = hasRenderableShellSlot(description);
+    const hasFooter = hasRenderableShellSlot(footer);
+    const hasSidebarFooter = hasRenderableShellSlot(sidebarFooter);
+    const hasTitle = hasRenderableShellSlot(title);
+    const hasToolbar = hasRenderableShellSlot(toolbar);
+    const hasHeader = hasTitle || hasDescription || hasActions || hasToolbar;
     const navigationProps = {
         ...(activeItemId === undefined ? {} : { activeItemId }),
         ...(onItemSelect === undefined ? {} : { onItemSelect })
     };
     const headerProps = {
-        ...(actions === undefined ? {} : { actions }),
-        ...(description === undefined ? {} : { description }),
+        ...(hasActions ? { actions } : {}),
+        ...(hasDescription ? { description } : {}),
         ...(headingLevel === undefined ? {} : { headingLevel }),
-        ...(toolbar === undefined ? {} : { toolbar })
+        ...(hasToolbar ? { toolbar } : {})
     };
-    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-sectioned-workspace-shell", className), children: [_jsxs("aside", { className: "zvk-composite-sectioned-workspace-shell__sidebar", children: [_jsx(SectionedWorkspaceNavigation, { ...navigationProps, navLabel: navLabel, sections: sections }), sidebarFooter ? (_jsx("div", { className: "zvk-composite-sectioned-workspace-shell__sidebar-footer", children: sidebarFooter })) : null] }), _jsxs("div", { className: "zvk-composite-sectioned-workspace-shell__body", children: [hasHeader ? (_jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-sectioned-workspace-shell__header", title: title ?? "" })) : null, _jsx("main", { className: "zvk-composite-sectioned-workspace-shell__content", children: children }), footer ? _jsx("footer", { className: "zvk-composite-sectioned-workspace-shell__footer", children: footer }) : null] })] }));
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-sectioned-workspace-shell", className), children: [_jsxs("aside", { className: "zvk-composite-sectioned-workspace-shell__sidebar", children: [_jsx(SectionedWorkspaceNavigation, { ...navigationProps, navLabel: navLabel, sections: sections }), hasSidebarFooter ? (_jsx("div", { className: "zvk-composite-sectioned-workspace-shell__sidebar-footer", children: sidebarFooter })) : null] }), _jsxs("div", { className: "zvk-composite-sectioned-workspace-shell__body", children: [hasHeader && hasTitle ? (_jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-sectioned-workspace-shell__header", title: title })) : hasHeader ? (_jsx(ShellHeaderChrome, { actions: actions, className: "zvk-composite-sectioned-workspace-shell__header", description: description, toolbar: toolbar })) : null, _jsx("main", { className: "zvk-composite-sectioned-workspace-shell__content", children: children }), hasFooter ? _jsx("footer", { className: "zvk-composite-sectioned-workspace-shell__footer", children: footer }) : null] })] }));
 }
 function SectionedWorkspaceNavigation({ activeItemId, navLabel, onItemSelect, sections }) {
     return (_jsx(SectionedSidebarNav, { className: "zvk-composite-sectioned-workspace-shell__nav", label: navLabel, children: sections.map((section) => (_jsxs(SectionedSidebarNav.Section, { children: [_jsx(SectionedSidebarNav.SectionTitle, { children: section.label }), _jsx(SectionedSidebarNav.List, { children: section.items.map((item) => (_jsx(SectionedWorkspaceNavigationItem, { active: item.id === activeItemId, item: item, onItemSelect: onItemSelect }, item.id))) })] }, section.id))) }));
 }
 function SectionedWorkspaceNavigationItem({ active, item, onItemSelect }) {
-    const content = (_jsxs("span", { className: "zvk-composite-sectioned-workspace-shell__nav-item-content", children: [_jsx("span", { className: "zvk-composite-sectioned-workspace-shell__nav-item-label", children: item.label }), item.description ? (_jsx("span", { className: "zvk-composite-sectioned-workspace-shell__nav-item-description", children: item.description })) : null] }));
+    const content = (_jsxs("span", { className: "zvk-composite-sectioned-workspace-shell__nav-item-content", children: [_jsx("span", { className: "zvk-composite-sectioned-workspace-shell__nav-item-label", children: item.label }), hasRenderableShellSlot(item.description) ? (_jsx("span", { className: "zvk-composite-sectioned-workspace-shell__nav-item-description", children: item.description })) : null] }));
     const handleSelect = () => onItemSelect?.(item.id);
     const itemProps = {
         ...(item.badge === undefined ? {} : { badge: item.badge }),

package/dist/navigation/shell-slot-rendering.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+import type { WorkspaceHeaderAlign } from "./workspace-header.js";
+export declare function hasRenderableShellSlot(value: React.ReactNode): boolean;
+export interface ShellHeaderChromeProps {
+    actions?: React.ReactNode | undefined;
+    align?: WorkspaceHeaderAlign | undefined;
+    className?: string | undefined;
+    description?: React.ReactNode | undefined;
+    eyebrow?: React.ReactNode | undefined;
+    status?: React.ReactNode | undefined;
+    toolbar?: React.ReactNode | undefined;
+}
+export declare function ShellHeaderChrome({ actions, align, className, description, eyebrow, status, toolbar }: ShellHeaderChromeProps): React.JSX.Element | null;

package/dist/navigation/shell-slot-rendering.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+export function hasRenderableShellSlot(value) {
+    if (value === undefined || value === null || typeof value === "boolean") {
+        return false;
+    }
+    if (typeof value === "string") {
+        return value.trim().length > 0;
+    }
+    return true;
+}
+export function ShellHeaderChrome({ actions, align = "start", className, description, eyebrow, status, toolbar }) {
+    const hasActions = hasRenderableShellSlot(actions);
+    const hasDescription = hasRenderableShellSlot(description);
+    const hasEyebrow = hasRenderableShellSlot(eyebrow);
+    const hasStatus = hasRenderableShellSlot(status);
+    const hasToolbar = hasRenderableShellSlot(toolbar);
+    const hasContent = hasEyebrow || hasStatus || hasDescription;
+    const hasControls = hasToolbar || hasActions;
+    if (!hasContent && !hasControls) {
+        return null;
+    }
+    return (_jsxs("div", { className: cn("zvk-composite-workspace-header", className), "data-align": align, children: [hasContent ? (_jsxs("div", { className: "zvk-composite-workspace-header__content", children: [hasEyebrow || hasStatus ? (_jsxs("div", { className: "zvk-composite-workspace-header__kicker", children: [hasEyebrow ? _jsx("span", { className: "zvk-composite-workspace-header__eyebrow", children: eyebrow }) : null, hasStatus ? _jsx("span", { className: "zvk-composite-workspace-header__status", children: status }) : null] })) : null, hasDescription ? (_jsx("div", { className: "zvk-composite-workspace-header__body", children: _jsx("p", { className: "zvk-composite-workspace-header__description", children: description }) })) : null] })) : (_jsx("div", { className: "zvk-composite-workspace-header__content", "aria-hidden": "true" })), hasControls ? (_jsxs("div", { className: "zvk-composite-workspace-header__controls", children: [hasToolbar ? _jsx("div", { className: "zvk-composite-workspace-header__toolbar", children: toolbar }) : null, hasActions ? _jsx("div", { className: "zvk-composite-workspace-header__actions", children: actions }) : null] })) : null] }));
+}

package/dist/navigation/simple-workspace-shell.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+import type { WorkspaceHeaderHeadingLevel } from "./workspace-header.js";
+export interface SimpleWorkspaceShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    actions?: React.ReactNode | undefined;
+    aside?: React.ReactNode | undefined;
+    children?: React.ReactNode | undefined;
+    description?: React.ReactNode | undefined;
+    footer?: React.ReactNode | undefined;
+    headingLevel?: WorkspaceHeaderHeadingLevel | undefined;
+    navigation?: React.ReactNode | undefined;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    status?: React.ReactNode | undefined;
+    title?: React.ReactNode | undefined;
+    toolbar?: React.ReactNode | undefined;
+}
+export declare function SimpleWorkspaceShell({ actions, aside, children, className, description, footer, headingLevel, navigation, ref, status, title, toolbar, ...props }: SimpleWorkspaceShellProps): React.JSX.Element;

package/dist/navigation/simple-workspace-shell.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { hasRenderableShellSlot, ShellHeaderChrome } from "./shell-slot-rendering.js";
+import { WorkspaceHeader } from "./workspace-header.js";
+export function SimpleWorkspaceShell({ actions, aside, children, className, description, footer, headingLevel, navigation, ref, status, title, toolbar, ...props }) {
+    const hasActions = hasRenderableShellSlot(actions);
+    const hasAside = hasRenderableShellSlot(aside);
+    const hasDescription = hasRenderableShellSlot(description);
+    const hasFooter = hasRenderableShellSlot(footer);
+    const hasNavigation = hasRenderableShellSlot(navigation);
+    const hasStatus = hasRenderableShellSlot(status);
+    const hasTitle = hasRenderableShellSlot(title);
+    const hasToolbar = hasRenderableShellSlot(toolbar);
+    const hasHeader = hasTitle || hasDescription || hasStatus || hasToolbar || hasActions;
+    const headerProps = {
+        ...(hasActions ? { actions } : {}),
+        ...(hasDescription ? { description } : {}),
+        ...(headingLevel === undefined ? {} : { headingLevel }),
+        ...(hasStatus ? { status } : {}),
+        ...(hasToolbar ? { toolbar } : {})
+    };
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-simple-workspace-shell", className), "data-with-aside": hasAside ? "true" : undefined, "data-with-navigation": hasNavigation ? "true" : undefined, children: [hasNavigation ? (_jsx("nav", { className: "zvk-composite-simple-workspace-shell__navigation", "aria-label": "Workspace navigation", children: navigation })) : null, _jsxs("div", { className: "zvk-composite-simple-workspace-shell__body", children: [hasHeader && hasTitle ? (_jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-simple-workspace-shell__header", title: title })) : hasHeader ? (_jsx(ShellHeaderChrome, { actions: actions, className: "zvk-composite-simple-workspace-shell__header", description: description, status: status, toolbar: toolbar })) : null, _jsxs("div", { className: "zvk-composite-simple-workspace-shell__grid", children: [_jsx("main", { className: "zvk-composite-simple-workspace-shell__main", children: children }), hasAside ? _jsx("aside", { className: "zvk-composite-simple-workspace-shell__aside", children: aside }) : null] }), hasFooter ? (_jsx("footer", { className: "zvk-composite-simple-workspace-shell__footer", children: footer })) : null] })] }));
+}

package/dist/navigation/split-workspace-shell.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+import type { SplitterValue } from "@zvk/ui/splitter";
+import type { WorkspaceHeaderHeadingLevel } from "./workspace-header.js";
+export interface SplitWorkspaceShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "title"> {
+    actions?: React.ReactNode | undefined;
+    collapsiblePrimary?: boolean | undefined;
+    defaultValue?: SplitterValue | undefined;
+    description?: React.ReactNode | undefined;
+    footer?: React.ReactNode | undefined;
+    headingLevel?: WorkspaceHeaderHeadingLevel | undefined;
+    maxPrimarySize?: number | undefined;
+    minPrimarySize?: number | undefined;
+    onResizeEnd?: ((value: SplitterValue) => void) | undefined;
+    onValueChange?: ((value: SplitterValue) => void) | undefined;
+    primary: React.ReactNode;
+    primaryLabel?: string | undefined;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    secondary: React.ReactNode;
+    secondaryLabel?: string | undefined;
+    title?: React.ReactNode | undefined;
+    toolbar?: React.ReactNode | undefined;
+    value?: SplitterValue | undefined;
+}
+export declare function SplitWorkspaceShell({ actions, className, collapsiblePrimary, defaultValue, description, footer, headingLevel, maxPrimarySize, minPrimarySize, onResizeEnd, onValueChange, primary, primaryLabel, ref, secondary, secondaryLabel, title, toolbar, value, ...props }: SplitWorkspaceShellProps): React.JSX.Element;

package/dist/navigation/split-workspace-shell.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Splitter } from "@zvk/ui/splitter";
+import { cn } from "../utils/cn.js";
+import { hasRenderableShellSlot, ShellHeaderChrome } from "./shell-slot-rendering.js";
+import { WorkspaceHeader } from "./workspace-header.js";
+export function SplitWorkspaceShell({ actions, className, collapsiblePrimary = false, defaultValue = [32, 68], description, footer, headingLevel, maxPrimarySize, minPrimarySize = 18, onResizeEnd, onValueChange, primary, primaryLabel = "Primary workspace pane", ref, secondary, secondaryLabel = "Secondary workspace pane", title, toolbar, value, ...props }) {
+    const hasActions = hasRenderableShellSlot(actions);
+    const hasDescription = hasRenderableShellSlot(description);
+    const hasFooter = hasRenderableShellSlot(footer);
+    const hasTitle = hasRenderableShellSlot(title);
+    const hasToolbar = hasRenderableShellSlot(toolbar);
+    const hasHeader = hasTitle || hasDescription || hasToolbar || hasActions;
+    const splitterProps = {
+        defaultValue,
+        ...(onResizeEnd === undefined ? {} : { onResizeEnd }),
+        ...(onValueChange === undefined ? {} : { onValueChange }),
+        ...(value === undefined ? {} : { value })
+    };
+    const primaryPanelProps = {
+        ...(maxPrimarySize === undefined ? {} : { maxSize: maxPrimarySize }),
+        minSize: minPrimarySize
+    };
+    const headerProps = {
+        ...(hasActions ? { actions } : {}),
+        ...(hasDescription ? { description } : {}),
+        ...(headingLevel === undefined ? {} : { headingLevel }),
+        ...(hasToolbar ? { toolbar } : {})
+    };
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-split-workspace-shell", className), children: [hasHeader && hasTitle ? (_jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-split-workspace-shell__header", title: title })) : hasHeader ? (_jsx(ShellHeaderChrome, { actions: actions, className: "zvk-composite-split-workspace-shell__header", description: description, toolbar: toolbar })) : null, _jsxs(Splitter, { ...splitterProps, className: "zvk-composite-split-workspace-shell__splitter", children: [_jsx(Splitter.Panel, { ...primaryPanelProps, "aria-label": primaryLabel, className: "zvk-composite-split-workspace-shell__pane", collapsible: collapsiblePrimary, children: primary }), _jsx(Splitter.Handle, { "aria-label": `Resize ${primaryLabel}` }), _jsx(Splitter.Panel, { "aria-label": secondaryLabel, className: "zvk-composite-split-workspace-shell__pane zvk-composite-split-workspace-shell__pane--secondary", children: secondary })] }), hasFooter ? (_jsx("footer", { className: "zvk-composite-split-workspace-shell__footer", children: footer })) : null] }));
+}

package/dist/styles.css

@@ -666,6 +666,95 @@
 }
 
 
+/* src/navigation/resource-explorer-shell.css */
+@layer zvk-composite-components {
+  :where(.zvk-composite-resource-explorer-shell) {
+    color: var(--zvk-ui-color-foreground);
+    container: zvk-composite-resource-explorer-shell / inline-size;
+    display: grid;
+    font-family: var(--zvk-ui-font-family-primary);
+    gap: var(--zvk-ui-space-4);
+    grid-template-columns: minmax(14rem, 18rem) minmax(0, 1fr) minmax(16rem, 22rem);
+    min-block-size: 0;
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-resource-explorer-shell:not([data-with-preview="true"])) {
+    grid-template-columns: minmax(14rem, 18rem) minmax(0, 1fr);
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__tree),
+  :where(.zvk-composite-resource-explorer-shell__results),
+  :where(.zvk-composite-resource-explorer-shell__preview) {
+    background: var(--zvk-ui-color-surface);
+    border: 1px solid var(--zvk-ui-color-border);
+    border-radius: var(--zvk-ui-radius-md);
+    box-shadow: var(--zvk-ui-shadow-xs);
+    display: grid;
+    gap: var(--zvk-ui-space-3);
+    min-block-size: 0;
+    min-inline-size: 0;
+    padding: var(--zvk-ui-space-3);
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__tree-header),
+  :where(.zvk-composite-resource-explorer-shell__toolbar),
+  :where(.zvk-composite-resource-explorer-shell__footer) {
+    color: var(--zvk-ui-color-muted-foreground);
+    font-size: var(--zvk-ui-font-size-sm);
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__tree-header) {
+    color: var(--zvk-ui-color-foreground);
+    font-family: var(--zvk-ui-font-family-secondary);
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__search) {
+    align-items: center;
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--zvk-ui-space-2);
+    min-inline-size: min(100%, 12rem);
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__search > *) {
+    flex: 1 1 12rem;
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__search :is(input, select, textarea, .zvk-ui-input, .zvk-ui-select__trigger)) {
+    inline-size: 100%;
+    max-inline-size: 100%;
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__tree-item) {
+    align-items: center;
+    display: inline-flex;
+    gap: var(--zvk-ui-space-2);
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-resource-explorer-shell__tree-item-icon) {
+    color: var(--zvk-ui-color-muted-foreground);
+    display: inline-flex;
+  }
+
+  @container zvk-composite-resource-explorer-shell (max-width: 72rem) {
+    :where(.zvk-composite-resource-explorer-shell),
+    :where(.zvk-composite-resource-explorer-shell:not([data-with-preview="true"])) {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  @media (max-width: 72rem) {
+    :where(.zvk-composite-resource-explorer-shell),
+    :where(.zvk-composite-resource-explorer-shell:not([data-with-preview="true"])) {
+      grid-template-columns: 1fr;
+    }
+  }
+}
+
+
 /* src/navigation/sectioned-workspace-shell.css */
 @layer zvk-composite-components {
   :where(.zvk-composite-sectioned-workspace-shell) {
@@ -786,6 +875,130 @@
 }
 
 
+/* src/navigation/simple-workspace-shell.css */
+@layer zvk-composite-components {
+  :where(.zvk-composite-simple-workspace-shell) {
+    color: var(--zvk-ui-color-foreground);
+    container: zvk-composite-simple-workspace-shell / inline-size;
+    display: grid;
+    font-family: var(--zvk-ui-font-family-primary);
+    gap: var(--zvk-ui-space-5);
+    grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-simple-workspace-shell:not([data-with-navigation="true"])) {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  :where(.zvk-composite-simple-workspace-shell__navigation),
+  :where(.zvk-composite-simple-workspace-shell__aside) {
+    background: var(--zvk-ui-color-surface);
+    border: 1px solid var(--zvk-ui-color-border);
+    border-radius: var(--zvk-ui-radius-md);
+    box-shadow: var(--zvk-ui-shadow-xs);
+    min-inline-size: 0;
+    padding: var(--zvk-ui-space-3);
+  }
+
+  :where(.zvk-composite-simple-workspace-shell__body) {
+    display: grid;
+    gap: var(--zvk-ui-space-5);
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-simple-workspace-shell__header) {
+    border-block-end: 1px solid var(--zvk-ui-color-border);
+    padding-block-end: var(--zvk-ui-space-4);
+  }
+
+  :where(.zvk-composite-simple-workspace-shell__grid) {
+    align-items: start;
+    display: grid;
+    gap: var(--zvk-ui-space-5);
+    grid-template-columns: minmax(0, 1fr);
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-simple-workspace-shell[data-with-aside="true"] .zvk-composite-simple-workspace-shell__grid) {
+    grid-template-columns: minmax(0, 1fr) minmax(15rem, 22rem);
+  }
+
+  :where(.zvk-composite-simple-workspace-shell__main) {
+    display: grid;
+    gap: var(--zvk-ui-space-4);
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-simple-workspace-shell__footer) {
+    border-block-start: 1px solid var(--zvk-ui-color-border);
+    color: var(--zvk-ui-color-muted-foreground);
+    font-size: var(--zvk-ui-font-size-sm);
+    padding-block-start: var(--zvk-ui-space-4);
+  }
+
+  @container zvk-composite-simple-workspace-shell (max-width: 64rem) {
+    :where(.zvk-composite-simple-workspace-shell),
+    :where(.zvk-composite-simple-workspace-shell[data-with-aside="true"] .zvk-composite-simple-workspace-shell__grid) {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  @media (max-width: 64rem) {
+    :where(.zvk-composite-simple-workspace-shell),
+    :where(.zvk-composite-simple-workspace-shell[data-with-aside="true"] .zvk-composite-simple-workspace-shell__grid) {
+      grid-template-columns: 1fr;
+    }
+  }
+}
+
+
+/* src/navigation/split-workspace-shell.css */
+@layer zvk-composite-components {
+  :where(.zvk-composite-split-workspace-shell) {
+    color: var(--zvk-ui-color-foreground);
+    display: grid;
+    font-family: var(--zvk-ui-font-family-primary);
+    gap: var(--zvk-ui-space-5);
+    min-block-size: 0;
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-split-workspace-shell__header) {
+    border-block-end: 1px solid var(--zvk-ui-color-border);
+    padding-block-end: var(--zvk-ui-space-4);
+  }
+
+  :where(.zvk-composite-split-workspace-shell__splitter) {
+    min-block-size: 28rem;
+  }
+
+  :where(.zvk-composite-split-workspace-shell__pane) {
+    background: var(--zvk-ui-color-surface);
+    border: 1px solid var(--zvk-ui-color-border);
+    border-radius: var(--zvk-ui-radius-md);
+    box-shadow: var(--zvk-ui-shadow-xs);
+    min-block-size: 0;
+    min-inline-size: 0;
+    overflow: auto;
+    padding: var(--zvk-ui-space-4);
+  }
+
+  :where(.zvk-composite-split-workspace-shell__pane--secondary) {
+    background:
+      linear-gradient(180deg, color-mix(in srgb, var(--zvk-ui-color-primary) 5%, transparent), transparent 12rem),
+      var(--zvk-ui-color-surface);
+  }
+
+  :where(.zvk-composite-split-workspace-shell__footer) {
+    border-block-start: 1px solid var(--zvk-ui-color-border);
+    color: var(--zvk-ui-color-muted-foreground);
+    font-size: var(--zvk-ui-font-size-sm);
+    padding-block-start: var(--zvk-ui-space-4);
+  }
+}
+
+
 /* src/navigation/workspace-header.css */
 @layer zvk-composite-components {
   :where(.zvk-composite-workspace-header) {
@@ -2009,6 +2222,45 @@
 }
 
 
+/* src/workflows/wizard-shell.css */
+@layer zvk-composite-components {
+  :where(.zvk-composite-wizard-shell) {
+    color: var(--zvk-ui-color-foreground);
+    display: grid;
+    font-family: var(--zvk-ui-font-family-primary);
+    gap: var(--zvk-ui-space-5);
+    min-inline-size: 0;
+  }
+
+  :where(.zvk-composite-wizard-shell__header),
+  :where(.zvk-composite-wizard-shell__progress),
+  :where(.zvk-composite-wizard-shell__footer) {
+    border-block-end: 1px solid var(--zvk-ui-color-border);
+    padding-block-end: var(--zvk-ui-space-4);
+  }
+
+  :where(.zvk-composite-wizard-shell__content) {
+    background: var(--zvk-ui-color-surface);
+    border: 1px solid var(--zvk-ui-color-border);
+    border-radius: var(--zvk-ui-radius-md);
+    box-shadow: var(--zvk-ui-shadow-xs);
+    display: grid;
+    gap: var(--zvk-ui-space-4);
+    min-inline-size: 0;
+    padding: var(--zvk-ui-space-5);
+  }
+
+  :where(.zvk-composite-wizard-shell__footer) {
+    border-block-end: 0;
+    border-block-start: 1px solid var(--zvk-ui-color-border);
+    color: var(--zvk-ui-color-muted-foreground);
+    font-size: var(--zvk-ui-font-size-sm);
+    padding-block-end: 0;
+    padding-block-start: var(--zvk-ui-space-4);
+  }
+}
+
+
 /* src/settings/parameter-editor.css */
 @layer zvk-composite-components {
   :where(.zvk-composite-parameter-editor) {

package/dist/utils/use-controllable-value.d.ts

@@ -0,0 +1,7 @@
+interface UseControllableValueOptions<Value> {
+    defaultValue: Value;
+    onChange?: ((value: Value) => void) | undefined;
+    value?: Value | undefined;
+}
+export declare function useControllableValue<Value>({ defaultValue, onChange, value }: UseControllableValueOptions<Value>): readonly [Value, (nextValue: Value) => void];
+export {};

package/dist/utils/use-controllable-value.js

@@ -0,0 +1,12 @@
+import * as React from "react";
+export function useControllableValue({ defaultValue, onChange, value }) {
+    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
+    const resolvedValue = value ?? uncontrolledValue;
+    const setValue = React.useCallback((nextValue) => {
+        if (value === undefined) {
+            setUncontrolledValue(nextValue);
+        }
+        onChange?.(nextValue);
+    }, [onChange, value]);
+    return [resolvedValue, setValue];
+}

package/dist/workflows/wizard-shell.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+import type { WorkspaceHeaderHeadingLevel } from "../navigation/workspace-header.js";
+export type WizardShellStepStatus = "idle" | "current" | "complete" | "error" | "disabled";
+export interface WizardShellStep {
+    description?: React.ReactNode | undefined;
+    disabled?: boolean | undefined;
+    id: string;
+    label: React.ReactNode;
+    status?: WizardShellStepStatus | undefined;
+}
+export interface WizardShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSubmit" | "title"> {
+    actions?: React.ReactNode | undefined;
+    children: React.ReactNode;
+    currentStepId: string;
+    description?: React.ReactNode | undefined;
+    footer?: React.ReactNode | undefined;
+    headingLevel?: WorkspaceHeaderHeadingLevel | undefined;
+    onStepChange?: ((stepId: string) => void) | undefined;
+    progress?: React.ReactNode | undefined;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    steps: readonly WizardShellStep[];
+    title: React.ReactNode;
+}
+export declare function WizardShell({ actions, children, className, currentStepId, description, footer, headingLevel, onStepChange, progress, ref, steps, title, ...props }: WizardShellProps): React.JSX.Element;

package/dist/workflows/wizard-shell.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Stepper } from "@zvk/ui/stepper";
+import { cn } from "../utils/cn.js";
+import { WorkspaceHeader } from "../navigation/workspace-header.js";
+function toStepperItem(step) {
+    return {
+        description: step.description,
+        disabled: step.disabled === true || step.status === "disabled",
+        id: step.id,
+        label: step.label
+    };
+}
+function isLinear(steps, currentStepId) {
+    const currentIndex = steps.findIndex((step) => step.id === currentStepId);
+    return steps.every((step, index) => {
+        if (step.status === "complete" || step.status === "current") {
+            return index <= currentIndex;
+        }
+        return true;
+    });
+}
+export function WizardShell({ actions, children, className, currentStepId, description, footer, headingLevel, onStepChange, progress, ref, steps, title, ...props }) {
+    const stepperProps = {
+        ...(onStepChange === undefined ? {} : { onValueChange: onStepChange })
+    };
+    const headerProps = {
+        ...(headingLevel === undefined ? {} : { headingLevel })
+    };
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-wizard-shell", className), children: [_jsx(WorkspaceHeader, { ...headerProps, actions: actions, className: "zvk-composite-wizard-shell__header", description: description, title: title }), _jsx("div", { className: "zvk-composite-wizard-shell__progress", children: progress ?? (_jsx(Stepper, { ...stepperProps, "aria-label": "Wizard progress", interactive: Boolean(onStepChange), items: steps.map(toStepperItem), linear: isLinear(steps, currentStepId), value: currentStepId })) }), _jsx("main", { className: "zvk-composite-wizard-shell__content", children: children }), footer ? _jsx("footer", { className: "zvk-composite-wizard-shell__footer", children: footer }) : null] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvk/composite",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Drop-in composite React components built from @zvk/ui primitives for product workspaces.",
   "private": false,
   "type": "module",
@@ -49,11 +49,26 @@
       "import": "./dist/navigation/command-palette-shell.js",
       "default": "./dist/navigation/command-palette-shell.js"
     },
+    "./resource-explorer-shell": {
+      "types": "./dist/navigation/resource-explorer-shell.d.ts",
+      "import": "./dist/navigation/resource-explorer-shell.js",
+      "default": "./dist/navigation/resource-explorer-shell.js"
+    },
     "./sectioned-workspace-shell": {
       "types": "./dist/navigation/sectioned-workspace-shell.d.ts",
       "import": "./dist/navigation/sectioned-workspace-shell.js",
       "default": "./dist/navigation/sectioned-workspace-shell.js"
     },
+    "./simple-workspace-shell": {
+      "types": "./dist/navigation/simple-workspace-shell.d.ts",
+      "import": "./dist/navigation/simple-workspace-shell.js",
+      "default": "./dist/navigation/simple-workspace-shell.js"
+    },
+    "./split-workspace-shell": {
+      "types": "./dist/navigation/split-workspace-shell.d.ts",
+      "import": "./dist/navigation/split-workspace-shell.js",
+      "default": "./dist/navigation/split-workspace-shell.js"
+    },
     "./workspace-header": {
       "types": "./dist/navigation/workspace-header.d.ts",
       "import": "./dist/navigation/workspace-header.js",
@@ -129,6 +144,11 @@
       "import": "./dist/workflows/process-list-panel.js",
       "default": "./dist/workflows/process-list-panel.js"
     },
+    "./wizard-shell": {
+      "types": "./dist/workflows/wizard-shell.d.ts",
+      "import": "./dist/workflows/wizard-shell.js",
+      "default": "./dist/workflows/wizard-shell.js"
+    },
     "./parameter-editor": {
       "types": "./dist/settings/parameter-editor.d.ts",
       "import": "./dist/settings/parameter-editor.js",
@@ -197,7 +217,7 @@
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@zvk/ui": "^0.1.11"
+    "@zvk/ui": "^0.1.12"
   },
   "tsd": {
     "directory": "tests/types"