@zvk/composite 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @zvk/composite Changelog
 
+## [0.1.3](https://github.com/brandon-schabel/zvk/compare/composite-v0.1.2...composite-v0.1.3) (2026-06-20)
+
+
+### Features
+
+* improve package release workflow and repo maintainability ([#22](https://github.com/brandon-schabel/zvk/issues/22)) ([a41cb66](https://github.com/brandon-schabel/zvk/commit/a41cb66554496f241c5a8e30b29a76c8b8ca92b3))
+
+## [0.1.2](https://github.com/brandon-schabel/zvk/compare/composite-v0.1.1...composite-v0.1.2) (2026-06-19)
+
+
+### Features
+
+* add theme presets and package improvements ([#19](https://github.com/brandon-schabel/zvk/issues/19)) ([867f955](https://github.com/brandon-schabel/zvk/commit/867f9556f7a60144cad4e747f2c032f2d5ede353))
+
 ## [0.1.1](https://github.com/brandon-schabel/zvk/compare/composite-v0.1.0...composite-v0.1.1) (2026-06-16)
 
 

package/README.md

@@ -10,3 +10,453 @@ 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:
+
+```tsx
+import {
+  AppWorkspaceShell,
+  PageScaffold,
+  RouteStateFrame,
+  WorkspaceHeader
+} from "@zvk/composite";
+```
+
+Use focused subpath imports when a file consumes one or two surfaces:
+
+```tsx
+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.
+
+```tsx
+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:
+
+```tsx
+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:
+
+```tsx
+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:
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.

package/dist/activity/activity-feed.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+export type ActivityFeedTone = "neutral" | "info" | "success" | "warning" | "danger";
+export interface ActivityFeedItem {
+    readonly id: string;
+    readonly title: React.ReactNode;
+    readonly description?: React.ReactNode;
+    readonly meta?: React.ReactNode;
+    readonly body?: React.ReactNode;
+    readonly icon?: React.ReactNode;
+    readonly actions?: React.ReactNode;
+    readonly tone?: ActivityFeedTone;
+}
+export interface ActivityFeedGroup {
+    readonly id: string;
+    readonly label?: React.ReactNode;
+    readonly items: readonly ActivityFeedItem[];
+}
+export interface ActivityFeedProps extends Omit<React.ComponentPropsWithoutRef<"section">, "title" | "children"> {
+    readonly title?: React.ReactNode;
+    readonly description?: React.ReactNode;
+    readonly groups: readonly ActivityFeedGroup[];
+    readonly empty?: React.ReactNode;
+    readonly loading?: boolean;
+    readonly footer?: React.ReactNode;
+    readonly ref?: React.Ref<HTMLElement>;
+}
+export declare function ActivityFeed({ className, description, empty, footer, groups, loading, ref, title, ...props }: ActivityFeedProps): React.JSX.Element;

package/dist/activity/activity-feed.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Spinner } from "@zvk/ui/spinner";
+import { cn } from "../utils/cn.js";
+function hasValue(value) {
+    return value !== null && value !== undefined && value !== false;
+}
+function hasItems(groups) {
+    return groups.some((group) => group.items.length > 0);
+}
+function renderActivityItem(item) {
+    const tone = item.tone ?? "neutral";
+    const showAside = hasValue(item.actions);
+    const showDescription = hasValue(item.description);
+    const showMeta = hasValue(item.meta);
+    const showBody = hasValue(item.body);
+    const showIcon = hasValue(item.icon);
+    return (_jsx("article", { className: "zvk-composite-activity-feed__entry", "data-tone": tone, children: _jsxs("div", { className: "zvk-composite-activity-feed__shell", children: [showIcon ? _jsx("div", { className: "zvk-composite-activity-feed__icon", children: item.icon }) : null, _jsxs("div", { className: "zvk-composite-activity-feed__content", children: [_jsxs("div", { className: "zvk-composite-activity-feed__header", children: [_jsxs("div", { className: "zvk-composite-activity-feed__copy", children: [_jsx("h4", { className: "zvk-composite-activity-feed__title", children: item.title }), showDescription ? (_jsx("p", { className: "zvk-composite-activity-feed__description", children: item.description })) : null] }), showAside ? _jsx("div", { className: "zvk-composite-activity-feed__actions", children: item.actions }) : null] }), showMeta ? _jsx("div", { className: "zvk-composite-activity-feed__meta", children: item.meta }) : null, showBody ? _jsx("div", { className: "zvk-composite-activity-feed__body", children: item.body }) : null] })] }) }));
+}
+export function ActivityFeed({ className, description, empty = "No activity yet.", footer, groups, loading = false, ref, title, ...props }) {
+    const showHeader = hasValue(title) || hasValue(description);
+    const showItems = !loading && hasItems(groups);
+    const showEmptyState = !loading && !showItems;
+    return (_jsxs("section", { ...props, ref: ref, "aria-busy": loading ? true : props["aria-busy"], className: cn("zvk-composite-activity-feed", className), "data-loading": loading ? "" : undefined, children: [showHeader ? (_jsx("div", { className: "zvk-composite-activity-feed__header", children: _jsxs("div", { className: "zvk-composite-activity-feed__copy", children: [hasValue(title) ? _jsx("h3", { className: "zvk-composite-activity-feed__title", children: title }) : null, hasValue(description) ? (_jsx("p", { className: "zvk-composite-activity-feed__description", children: description })) : null] }) })) : null, _jsxs("div", { className: "zvk-composite-activity-feed__sections", children: [loading ? (_jsxs("div", { className: "zvk-composite-activity-feed__state", "data-state": "loading", children: [_jsx(Spinner, { label: "Loading activity feed", size: "sm", tone: "muted" }), _jsx("span", { children: "Loading activity feed..." })] })) : null, showEmptyState ? (_jsx("div", { className: "zvk-composite-activity-feed__state", "data-state": "empty", children: empty })) : null, showItems ? (_jsx("div", { className: "zvk-composite-activity-feed__groups", children: groups.map((group) => {
+                            if (group.items.length === 0) {
+                                return null;
+                            }
+                            return (_jsxs("section", { className: "zvk-composite-activity-feed__group", children: [hasValue(group.label) ? (_jsx("div", { className: "zvk-composite-activity-feed__group-label", children: group.label })) : null, _jsx("ul", { className: "zvk-composite-activity-feed__list", children: group.items.map((item) => (_jsx("li", { className: "zvk-composite-activity-feed__item", children: renderActivityItem(item) }, item.id))) })] }, group.id));
+                        }) })) : null] }), hasValue(footer) ? _jsx("div", { className: "zvk-composite-activity-feed__footer", children: footer }) : null] }));
+}

package/dist/ai/conversation-directory.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+export interface ConversationDirectoryItem {
+    readonly id: string;
+    readonly title: React.ReactNode;
+    readonly description?: React.ReactNode;
+    readonly meta?: React.ReactNode;
+    readonly badge?: React.ReactNode;
+    readonly selected?: boolean;
+    readonly disabled?: boolean;
+    readonly pinned?: boolean;
+    readonly unread?: boolean;
+    readonly archived?: boolean;
+}
+export interface ConversationDirectoryGroup {
+    readonly id: string;
+    readonly label?: React.ReactNode;
+    readonly items: readonly ConversationDirectoryItem[];
+}
+export interface ConversationDirectoryProps extends Omit<React.ComponentPropsWithoutRef<"aside">, "children"> {
+    readonly label: string;
+    readonly groups: readonly ConversationDirectoryGroup[];
+    readonly search?: React.ReactNode;
+    readonly actions?: React.ReactNode;
+    readonly empty?: React.ReactNode;
+    readonly loading?: boolean;
+    readonly onItemSelect?: (item: ConversationDirectoryItem) => void;
+    readonly renderItem?: (item: ConversationDirectoryItem) => React.ReactNode;
+    readonly footer?: React.ReactNode;
+    readonly ref?: React.Ref<HTMLElement>;
+}
+export declare function ConversationDirectory({ actions, className, empty, footer, groups, label, loading, onItemSelect, ref, renderItem, search, ...props }: ConversationDirectoryProps): React.JSX.Element;

package/dist/ai/conversation-directory.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Spinner } from "@zvk/ui/spinner";
+import { cn } from "../utils/cn.js";
+function hasValue(value) {
+    return value !== null && value !== undefined && value !== false;
+}
+function renderNode(value) {
+    return hasValue(value) ? value : null;
+}
+function renderItemFlags(item) {
+    const flags = [];
+    if (item.pinned === true) {
+        flags.push(_jsx("span", { className: "zvk-composite-conversation-directory__item-state", "data-kind": "pinned", children: "Pinned" }, "pinned"));
+    }
+    if (item.unread === true) {
+        flags.push(_jsx("span", { className: "zvk-composite-conversation-directory__item-state", "data-kind": "unread", children: "Unread" }, "unread"));
+    }
+    if (item.archived === true) {
+        flags.push(_jsx("span", { className: "zvk-composite-conversation-directory__item-state", "data-kind": "archived", children: "Archived" }, "archived"));
+    }
+    return flags.length > 0 ? _jsx(_Fragment, { children: flags }) : null;
+}
+function renderDefaultItemContent(item) {
+    const flags = renderItemFlags(item);
+    return (_jsxs("div", { className: "zvk-composite-conversation-directory__item-copy", children: [_jsxs("div", { className: "zvk-composite-conversation-directory__item-heading", children: [_jsx("span", { className: "zvk-composite-conversation-directory__item-title", children: item.title }), hasValue(item.badge) ? _jsx("span", { className: "zvk-composite-conversation-directory__item-badge", children: item.badge }) : null] }), hasValue(item.description) ? (_jsx("span", { className: "zvk-composite-conversation-directory__item-description", children: item.description })) : null, hasValue(item.meta) || item.pinned === true || item.unread === true || item.archived === true ? (_jsxs("span", { className: "zvk-composite-conversation-directory__item-meta-row", children: [hasValue(item.meta) ? _jsx("span", { className: "zvk-composite-conversation-directory__item-meta", children: item.meta }) : null, flags !== null ? _jsx("span", { className: "zvk-composite-conversation-directory__item-states", children: flags }) : null] })) : null] }));
+}
+export function ConversationDirectory({ actions, className, empty = "No conversations available.", footer, groups, label, loading = false, onItemSelect, ref, renderItem, search, ...props }) {
+    const visibleGroups = groups.filter((group) => group.items.length > 0);
+    const showEmptyState = !loading && visibleGroups.length === 0;
+    const showLoader = loading;
+    return (_jsxs("aside", { ...props, ref: ref, "aria-busy": loading ? true : props["aria-busy"], "aria-label": label, className: cn("zvk-composite-conversation-directory", className), "data-empty": showEmptyState ? "" : undefined, "data-loading": loading ? "" : undefined, children: [_jsxs("header", { className: "zvk-composite-conversation-directory__header", children: [_jsx("div", { className: "zvk-composite-conversation-directory__header-copy", children: _jsx("h2", { className: "zvk-composite-conversation-directory__title", children: label }) }), hasValue(search) || hasValue(actions) ? (_jsxs("div", { className: "zvk-composite-conversation-directory__header-actions", children: [hasValue(search) ? _jsx("div", { className: "zvk-composite-conversation-directory__search", children: search }) : null, hasValue(actions) ? _jsx("div", { className: "zvk-composite-conversation-directory__actions", children: actions }) : null] })) : null] }), showLoader ? (_jsxs("div", { className: "zvk-composite-conversation-directory__state", "data-state": "loading", children: [_jsx(Spinner, { label: "Loading conversations", size: "sm", tone: "muted" }), _jsx("span", { children: "Loading conversations..." })] })) : null, showEmptyState ? (_jsx("div", { className: "zvk-composite-conversation-directory__state", "data-state": "empty", children: renderNode(empty) })) : null, !showLoader && !showEmptyState ? (_jsx("div", { className: "zvk-composite-conversation-directory__groups", children: visibleGroups.map((group) => (_jsxs("section", { "aria-label": typeof group.label === "string" ? group.label : undefined, className: "zvk-composite-conversation-directory__group", children: [hasValue(group.label) ? (_jsx("div", { className: "zvk-composite-conversation-directory__group-header", children: _jsx("h3", { className: "zvk-composite-conversation-directory__group-title", children: group.label }) })) : null, _jsx("ul", { className: "zvk-composite-conversation-directory__list", children: group.items.map((item) => {
+                                const isDisabled = item.disabled === true;
+                                const isSelected = item.selected === true;
+                                const itemBody = renderItem !== undefined ? renderItem(item) : renderDefaultItemContent(item);
+                                return (_jsx("li", { className: "zvk-composite-conversation-directory__list-item", children: _jsx("button", { "aria-pressed": isSelected, className: "zvk-composite-conversation-directory__item", "data-archived": item.archived === true ? "" : undefined, "data-disabled": isDisabled ? "" : undefined, "data-pinned": item.pinned === true ? "" : undefined, "data-selected": isSelected ? "" : undefined, "data-unread": item.unread === true ? "" : undefined, disabled: isDisabled, type: "button", onClick: () => {
+                                            if (isDisabled) {
+                                                return;
+                                            }
+                                            onItemSelect?.(item);
+                                        }, children: _jsx("div", { className: "zvk-composite-conversation-directory__item-content", children: itemBody }) }) }, item.id));
+                            }) })] }, group.id))) })) : null, hasValue(footer) ? _jsx("div", { className: "zvk-composite-conversation-directory__footer", children: footer }) : null] }));
+}

package/dist/ai/provider-model-selector.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+export interface ProviderModelItem {
+    readonly id: string;
+    readonly label: React.ReactNode;
+    readonly description?: React.ReactNode;
+    readonly badge?: React.ReactNode;
+    readonly metadata?: React.ReactNode;
+    readonly disabled?: boolean;
+}
+export interface ProviderModelGroup {
+    readonly id: string;
+    readonly label: React.ReactNode;
+    readonly description?: React.ReactNode;
+    readonly badge?: React.ReactNode;
+    readonly disabled?: boolean;
+    readonly items: readonly ProviderModelItem[];
+}
+export interface ProviderModelSelectorProps extends React.HTMLAttributes<HTMLDivElement> {
+    readonly groups: readonly ProviderModelGroup[];
+    readonly selectedGroupId?: string;
+    readonly selectedItemId?: string;
+    readonly onGroupSelect?: (group: ProviderModelGroup) => void;
+    readonly onItemSelect?: (item: ProviderModelItem, group: ProviderModelGroup) => void;
+    readonly search?: React.ReactNode;
+    readonly selectedSummary?: React.ReactNode;
+    readonly advancedSettings?: React.ReactNode;
+    readonly empty?: React.ReactNode;
+    readonly loading?: boolean;
+    readonly ref?: React.Ref<HTMLDivElement>;
+}
+export declare function ProviderModelSelector({ advancedSettings, className, empty, groups, loading, onGroupSelect, onItemSelect, ref, search, selectedGroupId, selectedItemId, selectedSummary, ...props }: ProviderModelSelectorProps): React.JSX.Element;