@zvk/composite

Drop-in composite React components built from public @zvk/ui primitives.

Import @zvk/ui/styles.css once in the app root, then import @zvk/composite/styles.css after it:

import "@zvk/ui/styles.css";
import "@zvk/composite/styles.css";

Components are UI-only and accept typed props, slots, and callbacks. They do not own routing, persistence, data fetching, authentication, billing, or business rules.

Composite typography inherits the shared @zvk/ui font-family slots: primary for body/control text, secondary for titles and navigation accents, and tertiary wherever composed UI primitives render code or technical values.

Domain Ownership

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
• state: StateSurface, RouteStateFrame
• forms: FormSurface, ConfirmActionDialog
• data: EntityCard, EntityListSection, SummaryMetricGrid, DataTablePageFrame, DataTableControlBar
• workflow: IntegrationStatusCard, WorkflowStatusCard, ProcessListPanel
• settings: SettingsHubList, ParameterEditor, SettingsSectionStack
• ai: ProviderModelSelector, ConversationDirectory, StickyComposer
• activity: ActivityFeed
• detail: DetailInspectorPanel

What Composite Does Not Own

@zvk/composite owns repeated product-surface structure, semantic markup, accessible labels for the UI it renders, token-backed spacing, density-aware layout, and typed slots. It deliberately does not own app policy or runtime orchestration.

Keep these in the consuming app or a more specific package:

• routing, link components, active route state, and query params;
• data fetching, caching, mutations, optimistic updates, polling, subscriptions, and streaming;
• auth, billing, entitlements, permission checks, and organization policy;
• form state, validation, dirty-state detection, persistence, and schema interpretation;
• table engines, sorting, filtering, pagination, row selection, saved-view state, and column visibility;
• AI provider catalogs, model compatibility, prompt state, tool execution, attachments, message history, and AI SDK integration;
• analytics, telemetry, business copy, domain transforms, date formatting, and error classification.

Public Stability

• All current component subpaths and the root export are stable public API.
• Watched surfaces may evolve only through additive, UI-only props, callbacks, and tests; keep them app-agnostic and preserve the current import paths.
• ./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.

App Surface Exports

App surfaces are intentionally router-agnostic and UI-only:

| Surface | Import | Purpose | | --- | --- | --- | | AppWorkspaceShell | @zvk/composite/app-workspace-shell | Product workspace chrome with brand, navigation, switcher, command, header, content, account, and footer slots. | | EntitySwitcherMenu | @zvk/composite/entity-switcher-menu | Searchable context switcher for app-owned workspaces, projects, accounts, repositories, or environments. | | 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. | | SectionedWorkspaceShell | @zvk/composite/sectioned-workspace-shell | Sectioned navigation shell for dense workspace panels. | | 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. | | RouteStateFrame | @zvk/composite/route-state-frame | Route-level view states for loading, empty, error, not-found, and ready. | | EntityCard | @zvk/composite/entity-card | Selectable entity card with icon, title, description, badges, metadata, and actions. | | EntityListSection | @zvk/composite/entity-list-section | List section wrapper with app-owned item rendering. | | SummaryMetricGrid | @zvk/composite/summary-metric-grid | Metric cards for dashboards and operational summaries. | | SettingsHubList | @zvk/composite/settings-hub-list | Settings index list with route-free items, badges, metadata, and disabled state. | | FormSurface | @zvk/composite/form-surface | Native form shell for app-owned fields and submit handling. | | ConfirmActionDialog | @zvk/composite/confirm-action-dialog | Confirmation dialog for destructive, primary, or neutral actions. | | 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. | | 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. | | ProviderModelSelector | @zvk/composite/provider-model-selector | Two-level provider/model, service/variant, or environment/resource selector where catalogs and constraints stay in the app. | | ConversationDirectory | @zvk/composite/conversation-directory | Searchable/selectable conversation or record directory for app-owned AI workspaces. | | StickyComposer | @zvk/composite/sticky-composer | Sticky prompt/input form shell with app-owned state, validation, tools, streaming, and submit effects. | | DetailInspectorPanel | @zvk/composite/detail-inspector-panel | Right-side detail, metadata, review, or audit panel for selected app-owned entities. | | DataTableControlBar | @zvk/composite/data-table-control-bar | Controller-free table toolbar for app-owned search, filters, views, density, columns, selection, and actions. | | DataTablePageFrame | @zvk/composite/data-table-page-frame | Table page frame for app-owned search, filters, rows, pagination, loading, and empty state. | | LinkAction | @zvk/composite/link-action | Anchor styled like a @zvk/ui button, with button variants and sizes. |

Use root imports when a file composes several surfaces together:

import {
  AppWorkspaceShell,
  PageScaffold,
  RouteStateFrame,
  WorkspaceHeader
} from "@zvk/composite";

Use focused subpath imports when a file consumes one or two surfaces:

import { FeatureShell } from "@zvk/composite/feature-shell";
import { RouteStateFrame } from "@zvk/composite/route-state-frame";
import { LinkAction } from "@zvk/composite/link-action";

<FeatureShell
  title="Projects"
  description="Use this workspace to review active work."
  actions={<LinkAction href="/projects/new">New project</LinkAction>}
>
  <RouteStateFrame status="ready">...</RouteStateFrame>
</FeatureShell>

These components should stay focused on visual structure, semantics, and affordances; routing, domain mapping, and data orchestration remain in the consuming app.

Future Feature Acceptance

Accept a new composite only when all of these are true:

• [ ] It replaces repeated product-surface structure, not a primitive control or wrapper div.
• [ ] Its name and props stay app-agnostic.
• [ ] It composes public @zvk/ui exports, existing public composites, or local presentational helpers only.
• [ ] Routing, persistence, data fetching, auth, billing, validation, table engines, AI SDKs, analytics, policy checks, and business rules stay in the app or a more specific package.
• [ ] It fits an existing domain owner or clearly justifies a new owner in this README and the composite skill.
• [ ] It can be covered by package export map, root export, internal domain barrel, CSS aggregate, type fixture, SSR import smoke, export validation, tarball inspection, README guidance, preview example, and skill update.
• [ ] It remains SSR-safe at module initialization and deterministic in initial render.

Migration Guide

Migrate repeated app-owned shells into @zvk/composite only when the repeated part is visual structure and interaction affordance, not domain behavior.

| 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 | | Tab-with-sidebar or dense route workspace wrappers | SectionedWorkspaceShell | active route, URL updates, permission gating, tab persistence | | 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 | | 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 | | Selected-row or selected-record inspectors | DetailInspectorPanel | selected entity state, fetching, route params, drawer/sheet state, audit queries |

Sectioned Workspace Shells

SectionedWorkspaceShell is the migration target for repeated tab-with-sidebar or dense workspace wrappers. Use it when an app already owns the active tab, routes, permissions, and data loading, but repeats the same sidebar/header/content frame.

import { SectionedWorkspaceShell } from "@zvk/composite/sectioned-workspace-shell";

<SectionedWorkspaceShell
  activeItemId="runs"
  navLabel="Automation workspace navigation"
  onItemSelect={(itemId) => {
    // Route, persist, or guard in the app.
  }}
  sections={[
    {
      id: "operations",
      label: "Operations",
      items: [
        { id: "runs", label: "Runs", description: "Recent automation history" },
        { id: "logs", label: "Logs", href: "/automation/logs" },
        { id: "limits", label: "Limits", disabled: true }
      ]
    }
  ]}
  sidebarFooter="Route state, permissions, and tab persistence stay in the app."
  title="Automation workspace"
  toolbar="Filters"
>
  ...
</SectionedWorkspaceShell>

When replacing an app-owned *-tab-with-sidebar.tsx wrapper, map repeated shell pieces directly: wrapper title to title, tab/sidebar groups to sections, active route key to activeItemId, app navigation labels to navLabel, and local helper text to sidebarFooter or footer. Keep route objects, loaders, permission checks, query params, and product-specific empty states in the app.

Navigation Accelerators

EntitySwitcherMenu and CommandPaletteShell provide reusable command/navigation shells while leaving persistence, routing, recent-item storage, shortcuts, and side effects in the app:

import { CommandPaletteShell } from "@zvk/composite/command-palette-shell";
import { EntitySwitcherMenu } from "@zvk/composite/entity-switcher-menu";

<EntitySwitcherMenu
  current={{ id: "northline", label: "Northline" }}
  groups={[{ id: "recent", items: [{ id: "northline", label: "Northline" }] }]}
  label="Workspace"
  onSelect={(item) => {
    // Route or persist in the app.
  }}
/>;

<CommandPaletteShell
  groups={[{ id: "navigation", commands: [{ id: "runs", label: "Open runs" }] }]}
  onCommandSelect={(command) => {
    // Execute in the app.
  }}
  onOpenChange={setOpen}
  open={open}
/>;

Status Accelerators

IntegrationStatusCard and WorkflowStatusCard cover repeated provider/API and run/progress panels without owning health checks, polling, queues, retries, logs, or process control:

import { IntegrationStatusCard } from "@zvk/composite/integration-status-card";
import { WorkflowStatusCard } from "@zvk/composite/workflow-status-card";

<IntegrationStatusCard
  actions={<button type="button">Test</button>}
  metadata="Checked 1 minute ago"
  status="Connected"
  statusTone="success"
  title="OpenAI"
/>;

<WorkflowStatusCard
  currentStep="Extracting line items"
  progressLabel="42%"
  progressValue={42}
  status="Running"
  title="Proposal parse"
  tone="running"
/>;

ProcessListPanel turns repeated background-work lists into a reusable shell while keeping grouping, actions, logs, and lifecycle state in the app:

import { ProcessListPanel } from "@zvk/composite/process-list-panel";

<ProcessListPanel
  items={[
    {
      id: "parse-run",
      title: "Proposal parse",
      status: "Running",
      tone: "running",
      progressValue: 42,
      progressLabel: "42%"
    }
  ]}
  title="Background work"
/>;

ActivityFeed provides ordered activity, audit, run history, review, and notification markup without owning event fetching, ordering, date formatting, real-time subscriptions, virtualization, comment mutation, or audit schemas.

import { ActivityFeed } from "@zvk/composite/activity-feed";

<ActivityFeed
  groups={[
    {
      id: "today",
      label: "Today",
      items: [
        {
          id: "run-started",
          title: "Parser run started",
          description: "LandingAI accepted the uploaded plan.",
          meta: "10:30 AM",
          tone: "info"
        },
        {
          id: "review",
          title: "Reviewer commented",
          body: "Confirm the normalized line item group.",
          tone: "warning"
        }
      ]
    }
  ]}
  title="Activity"
/>;

Settings Accelerators

ParameterEditor provides grouped settings rows for numeric, boolean, text, and choice controls passed in as app-owned slots. It does not generate controls from schemas, validate values, persist changes, or encode provider/model-specific parameters.

import { ParameterEditor } from "@zvk/composite/parameter-editor";

<ParameterEditor
  groups={[
    {
      id: "model",
      title: "Model settings",
      rows: [
        {
          id: "temperature",
          label: "Temperature",
          value: "0.7",
          control: <input aria-label="Temperature" type="range" />
        }
      ]
    }
  ]}
/>;

ProviderModelSelector provides the repeated two-level chooser shell for AI provider/model settings, service/variant selection, environment/resource selection, and similar grouped option workflows. The component owns layout, selected presentation, empty/loading states, and disabled styling; the app owns the catalog, filtering, pricing, validation, persistence, and provider checks.

import { ProviderModelSelector } from "@zvk/composite/provider-model-selector";

<ProviderModelSelector
  groups={[
    {
      id: "openai",
      label: "OpenAI",
      description: "Text and reasoning models",
      badge: "Connected",
      items: [{ id: "gpt-5.4", label: "GPT-5.4", metadata: "128k context" }]
    }
  ]}
  selectedGroupId="openai"
  selectedItemId="gpt-5.4"
  selectedSummary="OpenAI / GPT-5.4"
  onItemSelect={(item, group) => {
    // Persist and validate in the app.
  }}
/>;

ConversationDirectory provides the repeated conversation/sidebar directory shell for AI workspaces, activity workbenches, and other record-selection panels. It owns grouped list layout, selected/disabled/pinned/unread/archived presentation, empty/loading states, and item selection callbacks. The app owns persistence, search/filter logic, routes, unread-count calculation, archive/delete actions, message fetching, streaming, and AI SDK integration.

import { ConversationDirectory } from "@zvk/composite/conversation-directory";

<ConversationDirectory
  actions={<button type="button">New</button>}
  groups={[
    {
      id: "today",
      label: "Today",
      items: [
        {
          id: "release-plan",
          title: "Release planning",
          description: "Package rollout notes",
          meta: "12 messages",
          selected: true,
          unread: true
        }
      ]
    }
  ]}
  label="Conversation history"
  onItemSelect={(item) => {
    // Route, persist, and fetch messages in the app.
  }}
/>;

StickyComposer provides the repeated sticky composer frame for chat, AI prompt, command, and workbench input areas. It owns the native form container, sticky layout, tool slots, submit slot, status/error/footer placement, and loading/disabled presentation. The app owns input state, validation, files, tools, streaming, submit side effects, keyboard shortcuts beyond native form behavior, and persistence.

import { StickyComposer } from "@zvk/composite/sticky-composer";
import { Conversation } from "@zvk/ui/conversation";

<StickyComposer
  aria-label="Message composer"
  footer="State, validation, streaming, and persistence stay in the app."
  input={<Conversation.PromptInputTextarea aria-label="Message" />}
  leadingTools={<button type="button">Attach</button>}
  onSubmit={(event) => {
    event.preventDefault();
    // Submit in the app.
  }}
  status="Ready"
  submit={<Conversation.PromptInputSubmit>Send</Conversation.PromptInputSubmit>}
/>;

SettingsSectionStack groups settings-page sections, alerts, actions, disabled presentation, and a controlled save bar. It does not detect dirty state, validate values, persist changes, manage route anchors, or own form field state.

import { SettingsSectionStack } from "@zvk/composite/settings-section-stack";

<SettingsSectionStack
  dirty
  saveBar="Unsaved changes"
  sections={[
    {
      id: "profile",
      title: "Profile",
      description: "App-owned controls passed as content.",
      content: "Profile fields",
      actions: "Reset"
    },
    {
      id: "billing",
      title: "Billing",
      content: "Billing controls",
      disabled: true
    }
  ]}
  title="Workspace settings"
/>;

Detail Panels

DetailInspectorPanel gives PageScaffold aside slots and split views a reusable selected-item inspector. It owns header, status, metadata, section layout, empty/loading presentation, and footer placement. The app owns selected item state, fetching, route params, audit queries, and any drawer or sheet wrapper.

import { DetailInspectorPanel } from "@zvk/composite/detail-inspector-panel";

<DetailInspectorPanel
  actions={<button type="button">Open full page</button>}
  description="Selected workflow run"
  footer="Drawer state and data loading stay in the app."
  metadata="Updated 1 minute ago"
  sections={[
    {
      id: "summary",
      title: "Summary",
      content: "Parser is extracting line items."
    },
    {
      id: "audit",
      title: "Audit",
      content: "Queued by Codex"
    }
  ]}
  status="Running"
  title="Run details"
/>;

Data Table Controls

DataTableControlBar complements DataTablePageFrame when a table page repeats search, filters, saved views, density, column, selection, bulk-action, and action placement. It does not own search state, filter schemas, saved-view persistence, column visibility, row selection, sorting, pagination, data fetching, or table engine adapters.

import { DataTableControlBar } from "@zvk/composite/data-table-control-bar";

<DataTableControlBar
  actions={<button type="button">Refresh</button>}
  bulkActions={<button type="button">Archive selected</button>}
  columnControl={<button type="button">Columns</button>}
  densityControl={<button type="button">Compact</button>}
  filters={<button type="button">Status</button>}
  savedView={<button type="button">Saved view</button>}
  search={<input aria-label="Search rows" />}
  selectionSummary="3 selected"
/>;

Repo Skill

Use .codex/skills/use-zvk-composite/SKILL.md when maintaining this package.