@zvk/composite 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @zvk/composite Changelog
+
+## [0.1.1](https://github.com/brandon-schabel/zvk/compare/composite-v0.1.0...composite-v0.1.1) (2026-06-16)
+
+
+### Features
+
+* add composite component package ([dc0920f](https://github.com/brandon-schabel/zvk/commit/dc0920fe77dd2bd63015a40b3d7675fe8f1d0067))
+
+
+### Bug Fixes
+
+* harden popup positioning ([efb8c8a](https://github.com/brandon-schabel/zvk/commit/efb8c8a98c2b759f4e84a60f5ae292b1e8900907))
+
+## 0.1.0
+
+- Initial package scaffold for composite workspace components.

package/LICENSE.md

@@ -0,0 +1,3 @@
+# License
+
+See the repository license for terms.

package/README.md

@@ -0,0 +1,12 @@
+# @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:
+
+```tsx
+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.

package/dist/data/data-table-page-frame.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+export interface DataTablePageFrameProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    bulkActions?: React.ReactNode;
+    description?: React.ReactNode;
+    empty?: React.ReactNode;
+    filters?: React.ReactNode;
+    footer?: React.ReactNode;
+    loading?: boolean;
+    loadingLabel?: React.ReactNode;
+    pagination?: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement>;
+    search?: React.ReactNode;
+    table?: React.ReactNode;
+    title: React.ReactNode;
+}
+export declare function DataTablePageFrame({ bulkActions, className, description, empty, filters, footer, loading, loadingLabel, pagination, ref, search, table, title, ...props }: DataTablePageFrameProps): React.JSX.Element;

package/dist/data/data-table-page-frame.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Card } from "@zvk/ui/card";
+import { Table } from "@zvk/ui/table";
+import { cn } from "../utils/cn.js";
+export function DataTablePageFrame({ bulkActions, className, description, empty, filters, footer, loading = false, loadingLabel = "Loading data", pagination, ref, search, table, title, ...props }) {
+    const hasToolbar = Boolean(search || filters || bulkActions);
+    const hasFooter = Boolean(pagination || footer);
+    return (_jsxs("section", { ...props, ref: ref, className: cn("zvk-composite-data-table-page-frame", className), children: [_jsx("div", { className: "zvk-composite-data-table-page-frame__header", children: _jsxs("div", { className: "zvk-composite-data-table-page-frame__heading", children: [_jsx("h2", { className: "zvk-composite-data-table-page-frame__title", children: title }), description ? _jsx("p", { className: "zvk-composite-data-table-page-frame__description", children: description }) : null] }) }), _jsxs(Card, { className: "zvk-composite-data-table-page-frame__card", padding: "none", variant: "outline", children: [hasToolbar ? (_jsxs("div", { className: "zvk-composite-data-table-page-frame__toolbar", children: [search ? _jsx("div", { className: "zvk-composite-data-table-page-frame__search", children: search }) : null, filters ? _jsx("div", { className: "zvk-composite-data-table-page-frame__filters", children: filters }) : null, bulkActions ? (_jsx("div", { className: "zvk-composite-data-table-page-frame__bulk-actions", children: bulkActions })) : null] })) : null, _jsx(Card.Content, { className: "zvk-composite-data-table-page-frame__content", children: loading ? (_jsx("div", { className: "zvk-composite-data-table-page-frame__state", role: "status", children: loadingLabel })) : table ? (_jsx(Table.Container, { className: "zvk-composite-data-table-page-frame__table", children: table })) : empty ? (_jsx("div", { className: "zvk-composite-data-table-page-frame__state", children: empty })) : null }), hasFooter ? (_jsxs(Card.Footer, { className: "zvk-composite-data-table-page-frame__footer", children: [footer ? _jsx("div", { className: "zvk-composite-data-table-page-frame__footer-content", children: footer }) : null, pagination ? (_jsx("div", { className: "zvk-composite-data-table-page-frame__pagination", children: pagination })) : null] })) : null] })] }));
+}

package/dist/forms/confirm-action-dialog.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+export type ConfirmActionDialogTone = "destructive" | "warning" | "primary";
+export interface ConfirmActionDialogProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    cancelLabel?: React.ReactNode;
+    confirmLabel: React.ReactNode;
+    defaultOpen?: boolean;
+    description: React.ReactNode;
+    disabled?: boolean;
+    onConfirm: () => void;
+    onOpenChange?: (open: boolean) => void;
+    open?: boolean;
+    ref?: React.Ref<HTMLDivElement>;
+    title: React.ReactNode;
+    tone?: ConfirmActionDialogTone;
+    trigger: React.ReactNode;
+}
+export declare function ConfirmActionDialog({ cancelLabel, className, confirmLabel, defaultOpen, description, disabled, onConfirm, onOpenChange, open, ref, title, tone, trigger, ...props }: ConfirmActionDialogProps): React.JSX.Element;

package/dist/forms/confirm-action-dialog.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { AlertDialog } from "@zvk/ui/alert-dialog";
+import { Button } from "@zvk/ui/button";
+import { cn } from "../utils/cn.js";
+function getConfirmVariant(tone) {
+    if (tone === "destructive") {
+        return "destructive";
+    }
+    return "primary";
+}
+export function ConfirmActionDialog({ cancelLabel = "Cancel", className, confirmLabel, defaultOpen, description, disabled = false, onConfirm, onOpenChange, open, ref, title, tone = "destructive", trigger, ...props }) {
+    const rootProps = {
+        ...(defaultOpen !== undefined ? { defaultOpen } : {}),
+        ...(onOpenChange ? { onOpenChange } : {}),
+        ...(open !== undefined ? { open } : {})
+    };
+    const triggerContent = React.isValidElement(trigger) ? (trigger) : (_jsx(Button, { className: "zvk-composite-confirm-action-dialog__trigger", disabled: disabled, type: "button", variant: tone === "destructive" ? "destructive" : "primary", children: trigger }));
+    return (_jsxs(AlertDialog, { ...props, ...rootProps, ...(ref !== undefined ? { ref } : {}), className: cn("zvk-composite-confirm-action-dialog", className), "data-tone": tone, children: [_jsx(AlertDialog.Trigger, { asChild: true, disabled: disabled, children: triggerContent }), _jsxs(AlertDialog.Content, { className: "zvk-composite-confirm-action-dialog__content", children: [_jsx(AlertDialog.Title, { className: "zvk-composite-confirm-action-dialog__title", children: title }), _jsx(AlertDialog.Description, { className: "zvk-composite-confirm-action-dialog__description", children: description }), _jsxs(AlertDialog.Footer, { className: "zvk-composite-confirm-action-dialog__footer", children: [_jsx(AlertDialog.Cancel, { asChild: true, children: _jsx(Button, { type: "button", variant: "secondary", children: cancelLabel }) }), _jsx(AlertDialog.Action, { asChild: true, disabled: disabled, onClick: onConfirm, children: _jsx(Button, { className: "zvk-composite-confirm-action-dialog__confirm", disabled: disabled, type: "button", variant: getConfirmVariant(tone), children: confirmLabel }) })] })] })] }));
+}

package/dist/forms/form-surface.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+export interface FormSurfaceProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "children" | "title"> {
+    actions?: React.ReactNode;
+    alert?: React.ReactNode;
+    children?: React.ReactNode;
+    description?: React.ReactNode;
+    footer?: React.ReactNode;
+    ref?: React.Ref<HTMLFormElement>;
+    title: React.ReactNode;
+}
+export declare function FormSurface({ actions, alert, children, className, description, footer, ref, title, ...props }: FormSurfaceProps): React.JSX.Element;

package/dist/forms/form-surface.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Card } from "@zvk/ui/card";
+import { cn } from "../utils/cn.js";
+export function FormSurface({ actions, alert, children, className, description, footer, ref, title, ...props }) {
+    return (_jsx("form", { ...props, ref: ref, className: cn("zvk-composite-form-surface", className), children: _jsxs(Card, { className: "zvk-composite-form-surface__card", padding: "none", variant: "outline", children: [_jsxs(Card.Header, { className: "zvk-composite-form-surface__header", children: [_jsxs("div", { className: "zvk-composite-form-surface__heading", children: [_jsx(Card.Title, { className: "zvk-composite-form-surface__title", children: title }), description ? (_jsx(Card.Description, { className: "zvk-composite-form-surface__description", children: description })) : null] }), actions ? _jsx(Card.Action, { className: "zvk-composite-form-surface__actions", children: actions }) : null] }), alert ? _jsx("div", { className: "zvk-composite-form-surface__alert", children: alert }) : null, _jsx(Card.Content, { className: "zvk-composite-form-surface__content", children: children }), footer ? _jsx(Card.Footer, { className: "zvk-composite-form-surface__footer", children: footer }) : null] }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export { PageScaffold } from "./layout/page-scaffold.js";
+export type { PageScaffoldMaxWidth, PageScaffoldProps } from "./layout/page-scaffold.js";
+export { AppWorkspaceShell } from "./navigation/app-workspace-shell.js";
+export type { AppWorkspaceShellProps } from "./navigation/app-workspace-shell.js";
+export { BreadcrumbPageHeader, WorkspaceHeader } from "./navigation/workspace-header.js";
+export type { BreadcrumbPageHeaderProps, BreadcrumbPageHeaderItem, WorkspaceHeaderAlign, WorkspaceHeaderHeadingLevel, WorkspaceHeaderProps } from "./navigation/workspace-header.js";
+export { SectionedWorkspaceShell } from "./navigation/sectioned-workspace-shell.js";
+export type { SectionedWorkspaceItem, SectionedWorkspaceSection, SectionedWorkspaceShellProps } from "./navigation/sectioned-workspace-shell.js";
+export { StateSurface } from "./state/state-surface.js";
+export type { StateSurfaceAlign, StateSurfaceProps, StateSurfaceSize, StateSurfaceState } from "./state/state-surface.js";
+export { EntityCard } from "./lists/entity-card.js";
+export type { EntityCardProps } from "./lists/entity-card.js";
+export { EntityListSection } from "./lists/entity-list-section.js";
+export type { EntityListSectionProps } from "./lists/entity-list-section.js";
+export { SummaryMetricGrid } from "./lists/summary-metric-grid.js";
+export type { SummaryMetric, SummaryMetricGridActionPosition, SummaryMetricGridColumns, SummaryMetricGridProps } from "./lists/summary-metric-grid.js";
+export { SettingsHubList } from "./lists/settings-hub-list.js";
+export type { SettingsHubItem, SettingsHubListProps } from "./lists/settings-hub-list.js";
+export { ConfirmActionDialog } from "./forms/confirm-action-dialog.js";
+export type { ConfirmActionDialogProps, ConfirmActionDialogTone } from "./forms/confirm-action-dialog.js";
+export { FormSurface } from "./forms/form-surface.js";
+export type { FormSurfaceProps } from "./forms/form-surface.js";
+export { DataTablePageFrame } from "./data/data-table-page-frame.js";
+export type { DataTablePageFrameProps } from "./data/data-table-page-frame.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export { PageScaffold } from "./layout/page-scaffold.js";
+export { AppWorkspaceShell } from "./navigation/app-workspace-shell.js";
+export { BreadcrumbPageHeader, WorkspaceHeader } from "./navigation/workspace-header.js";
+export { SectionedWorkspaceShell } from "./navigation/sectioned-workspace-shell.js";
+export { StateSurface } from "./state/state-surface.js";
+export { EntityCard } from "./lists/entity-card.js";
+export { EntityListSection } from "./lists/entity-list-section.js";
+export { SummaryMetricGrid } from "./lists/summary-metric-grid.js";
+export { SettingsHubList } from "./lists/settings-hub-list.js";
+export { ConfirmActionDialog } from "./forms/confirm-action-dialog.js";
+export { FormSurface } from "./forms/form-surface.js";
+export { DataTablePageFrame } from "./data/data-table-page-frame.js";

package/dist/layout/page-scaffold.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+import type { WorkspaceHeaderAlign, WorkspaceHeaderHeadingLevel } from "../navigation/workspace-header.js";
+export type PageScaffoldMaxWidth = "sm" | "md" | "lg" | "xl" | "full";
+export interface PageScaffoldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    actions?: React.ReactNode | undefined;
+    aside?: React.ReactNode | undefined;
+    children?: React.ReactNode | undefined;
+    description?: React.ReactNode | undefined;
+    eyebrow?: React.ReactNode | undefined;
+    footer?: React.ReactNode | undefined;
+    headerAlign?: WorkspaceHeaderAlign | undefined;
+    headingLevel?: WorkspaceHeaderHeadingLevel | undefined;
+    maxWidth?: PageScaffoldMaxWidth | undefined;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    state?: React.ReactNode | undefined;
+    status?: React.ReactNode | undefined;
+    title?: React.ReactNode | undefined;
+    toolbar?: React.ReactNode | undefined;
+}
+export declare function PageScaffold({ actions, aside, children, className, description, eyebrow, footer, headerAlign, headingLevel, maxWidth, ref, state, status, title, toolbar, ...props }: PageScaffoldProps): React.JSX.Element;

package/dist/layout/page-scaffold.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../utils/cn.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 headerProps = {
+        ...(actions === undefined ? {} : { actions }),
+        ...(description === undefined ? {} : { description }),
+        ...(eyebrow === undefined ? {} : { eyebrow }),
+        ...(headerAlign === undefined ? {} : { align: headerAlign }),
+        ...(headingLevel === undefined ? {} : { headingLevel }),
+        ...(status === undefined ? {} : { status }),
+        ...(toolbar === undefined ? {} : { 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] }));
+}

package/dist/lists/entity-card.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+export interface EntityCardProps extends Omit<React.HTMLAttributes<HTMLElement>, "title" | "onSelect"> {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    icon?: React.ReactNode;
+    badges?: React.ReactNode;
+    meta?: React.ReactNode;
+    actions?: React.ReactNode;
+    href?: string;
+    onSelect?: () => void;
+    selected?: boolean;
+    disabled?: boolean;
+    loading?: boolean;
+    error?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+}
+export declare function EntityCard({ actions, badges, className, description, disabled, error, href, icon, loading, meta, onSelect, ref, selected, title, ...props }: EntityCardProps): React.JSX.Element;

package/dist/lists/entity-card.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } 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;
+}
+export function EntityCard({ actions, badges, className, description, disabled = false, error, href, icon, loading = false, meta, onSelect, ref, selected = false, title, ...props }) {
+    const interactive = Boolean(href || onSelect);
+    const classNames = cn("zvk-composite-entity-card", className);
+    const { onClick, ...restProps } = props;
+    const content = (_jsxs(_Fragment, { children: [hasValue(icon) ? _jsx("div", { className: "zvk-composite-entity-card__icon", children: icon }) : null, _jsxs("div", { className: "zvk-composite-entity-card__body", children: [_jsxs("div", { className: "zvk-composite-entity-card__heading", children: [_jsx("h3", { className: "zvk-composite-entity-card__title", children: title }), hasValue(badges) ? _jsx("div", { className: "zvk-composite-entity-card__badges", children: badges }) : null] }), hasValue(description) ? _jsx("p", { className: "zvk-composite-entity-card__description", children: description }) : null, hasValue(meta) ? _jsx("div", { className: "zvk-composite-entity-card__meta", children: meta }) : null, hasValue(error) ? _jsx("div", { className: "zvk-composite-entity-card__error", children: error }) : null] }), loading ? (_jsx("div", { className: "zvk-composite-entity-card__status", children: _jsx(Spinner, { label: "Loading", size: "sm", tone: "muted" }) })) : null, hasValue(actions) ? _jsx("div", { className: "zvk-composite-entity-card__actions", children: actions }) : null] }));
+    const sharedProps = {
+        ...restProps,
+        "aria-busy": loading ? true : props["aria-busy"],
+        "aria-current": selected ? "true" : props["aria-current"],
+        "aria-disabled": disabled ? true : props["aria-disabled"],
+        className: classNames
+    };
+    if (href) {
+        const handleAnchorClick = (event) => {
+            onClick?.(event);
+            if (disabled) {
+                event.preventDefault();
+            }
+        };
+        return (_jsx("a", { ...sharedProps, "data-disabled": disabled ? "" : undefined, "data-interactive": interactive ? "" : undefined, "data-loading": loading ? "" : undefined, "data-selected": selected ? "" : undefined, href: href, onClick: handleAnchorClick, ref: ref, children: content }));
+    }
+    if (onSelect) {
+        const handleButtonClick = (event) => {
+            onClick?.(event);
+            if (!disabled) {
+                onSelect();
+            }
+        };
+        return (_jsx("button", { ...sharedProps, "data-disabled": disabled ? "" : undefined, "data-interactive": interactive ? "" : undefined, "data-loading": loading ? "" : undefined, "data-selected": selected ? "" : undefined, disabled: disabled, onClick: handleButtonClick, ref: ref, type: "button", children: content }));
+    }
+    return (_jsx("article", { ...sharedProps, "data-disabled": disabled ? "" : undefined, "data-interactive": interactive ? "" : undefined, "data-loading": loading ? "" : undefined, "data-selected": selected ? "" : undefined, ref: ref, children: content }));
+}

package/dist/lists/entity-list-section.d.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+export interface EntityListSectionProps<T> extends Omit<React.ComponentPropsWithoutRef<"section">, "title" | "children"> {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    toolbar?: React.ReactNode;
+    actions?: React.ReactNode;
+    empty?: React.ReactNode;
+    loading?: boolean;
+    loadingLabel?: React.ReactNode;
+    footer?: React.ReactNode;
+    classNames?: {
+        header?: string;
+        copy?: string;
+        title?: string;
+        description?: string;
+        actions?: string;
+        toolbar?: string;
+        list?: string;
+        item?: string;
+        state?: string;
+        footer?: string;
+    };
+    items: readonly T[];
+    getItemKey: (item: T, index: number) => React.Key;
+    renderItem: (item: T, index: number) => React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+}
+export declare function EntityListSection<T>({ actions, className, classNames, description, empty, footer, getItemKey, items, loading, loadingLabel, ref, renderItem, title, toolbar, ...props }: EntityListSectionProps<T>): React.JSX.Element;

package/dist/lists/entity-list-section.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { StateSurface } from "../state/state-surface.js";
+import { cn } from "../utils/cn.js";
+export function EntityListSection({ actions, className, classNames, description, empty, footer, getItemKey, items, loading = false, loadingLabel = "Loading", ref, renderItem, title, toolbar, ...props }) {
+    const hasItems = items.length > 0;
+    return (_jsxs("section", { ...props, ref: ref, className: cn("zvk-composite-entity-list-section", className), children: [_jsxs("div", { className: cn("zvk-composite-entity-list-section__header", classNames?.header), children: [_jsxs("div", { className: cn("zvk-composite-entity-list-section__copy", classNames?.copy), children: [_jsx("h2", { className: cn("zvk-composite-entity-list-section__title", classNames?.title), children: title }), description ? _jsx("p", { className: cn("zvk-composite-entity-list-section__description", classNames?.description), children: description }) : null] }), actions ? _jsx("div", { className: cn("zvk-composite-entity-list-section__actions", classNames?.actions), children: actions }) : null] }), toolbar ? _jsx("div", { className: cn("zvk-composite-entity-list-section__toolbar", classNames?.toolbar), children: toolbar }) : null, loading ? (_jsx(StateSurface, { align: "center", className: cn("zvk-composite-entity-list-section__state", classNames?.state), size: "sm", state: "loading", title: loadingLabel })) : hasItems ? (_jsx("ul", { className: cn("zvk-composite-entity-list-section__list", classNames?.list), children: items.map((item, index) => (_jsx("li", { className: cn("zvk-composite-entity-list-section__item", classNames?.item), children: renderItem(item, index) }, getItemKey(item, index)))) })) : (empty ?? (_jsx(StateSurface, { align: "center", className: cn("zvk-composite-entity-list-section__state", classNames?.state), size: "sm", state: "empty", title: "No items" }))), footer ? _jsx("div", { className: cn("zvk-composite-entity-list-section__footer", classNames?.footer), children: footer }) : null] }));
+}

package/dist/lists/settings-hub-list.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+export interface SettingsHubListItem {
+    id: React.Key;
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    icon?: React.ReactNode;
+    badge?: React.ReactNode;
+    meta?: React.ReactNode;
+    href?: string;
+    onSelect?: () => void;
+    disabled?: boolean;
+}
+export type SettingsHubItem = SettingsHubListItem;
+export interface SettingsHubListProps extends Omit<React.ComponentPropsWithoutRef<"section">, "title" | "children"> {
+    items: readonly SettingsHubListItem[];
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    actions?: React.ReactNode;
+    empty?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+}
+export declare function SettingsHubList({ actions, className, description, empty, items, ref, title, ...props }: SettingsHubListProps): React.JSX.Element;

package/dist/lists/settings-hub-list.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Badge } from "@zvk/ui/badge";
+import { EntityCard } from "./entity-card.js";
+import { StateSurface } from "../state/state-surface.js";
+import { cn } from "../utils/cn.js";
+function renderBadge(badge) {
+    if (badge === null || badge === undefined || badge === false) {
+        return null;
+    }
+    if (React.isValidElement(badge)) {
+        return badge;
+    }
+    return _jsx(Badge, { children: badge });
+}
+export function SettingsHubList({ actions, className, description, empty, items, ref, title, ...props }) {
+    const showHeader = title !== undefined || description !== undefined || actions !== undefined;
+    return (_jsxs("section", { ...props, ref: ref, className: cn("zvk-composite-settings-hub-list", className), children: [showHeader ? (_jsxs("div", { className: "zvk-composite-settings-hub-list__header", children: [_jsxs("div", { className: "zvk-composite-settings-hub-list__copy", children: [title ? _jsx("h2", { className: "zvk-composite-settings-hub-list__title", children: title }) : null, description ? _jsx("p", { className: "zvk-composite-settings-hub-list__description", children: description }) : null] }), actions ? _jsx("div", { className: "zvk-composite-settings-hub-list__actions", children: actions }) : null] })) : null, items.length > 0 ? (_jsx("ul", { className: "zvk-composite-settings-hub-list__list", children: items.map((item) => (_jsx("li", { className: "zvk-composite-settings-hub-list__item", children: _jsx(EntityCard, { badges: renderBadge(item.badge), description: item.description, icon: item.icon, meta: item.meta, title: item.title, ...(item.disabled === undefined ? {} : { disabled: item.disabled }), ...(item.href === undefined ? {} : { href: item.href }), ...(item.onSelect === undefined ? {} : { onSelect: item.onSelect }) }) }, item.id))) })) : (empty ?? (_jsx(StateSurface, { align: "center", className: "zvk-composite-settings-hub-list__empty", size: "sm", state: "empty", title: "No settings" })))] }));
+}

package/dist/lists/summary-metric-grid.d.ts

@@ -0,0 +1,34 @@
+import * as React from "react";
+import { type StatTone } from "@zvk/ui/stat";
+export type SummaryMetricGridColumns = 1 | 2 | 3 | 4;
+export type SummaryMetricGridActionPosition = "footer" | "top";
+export interface SummaryMetric {
+    id: React.Key;
+    label: React.ReactNode;
+    value: React.ReactNode;
+    description?: React.ReactNode;
+    trend?: React.ReactNode;
+    tone?: StatTone;
+    action?: React.ReactNode;
+}
+export interface SummaryMetricGridProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    metrics: readonly SummaryMetric[];
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    actions?: React.ReactNode;
+    columns?: SummaryMetricGridColumns;
+    actionPosition?: SummaryMetricGridActionPosition;
+    classNames?: {
+        header?: string;
+        copy?: string;
+        title?: string;
+        description?: string;
+        actions?: string;
+        metrics?: string;
+        card?: string;
+        stat?: string;
+        action?: string;
+    };
+    ref?: React.Ref<HTMLDivElement>;
+}
+export declare function SummaryMetricGrid({ actionPosition, actions, className, classNames, columns, description, metrics, ref, title, ...props }: SummaryMetricGridProps): React.JSX.Element;

package/dist/lists/summary-metric-grid.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Card } from "@zvk/ui/card";
+import { Stat } from "@zvk/ui/stat";
+import { cn } from "../utils/cn.js";
+export function SummaryMetricGrid({ actionPosition = "footer", actions, className, classNames, columns = 4, description, metrics, ref, title, ...props }) {
+    const showHeader = title !== undefined || description !== undefined || actions !== undefined;
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-summary-metric-grid", className), "data-columns": columns, children: [showHeader ? (_jsxs("div", { className: cn("zvk-composite-summary-metric-grid__header", classNames?.header), children: [_jsxs("div", { className: cn("zvk-composite-summary-metric-grid__copy", classNames?.copy), children: [title ? _jsx("h2", { className: cn("zvk-composite-summary-metric-grid__title", classNames?.title), children: title }) : null, description ? _jsx("p", { className: cn("zvk-composite-summary-metric-grid__description", classNames?.description), children: description }) : null] }), actions ? _jsx("div", { className: cn("zvk-composite-summary-metric-grid__actions", classNames?.actions), children: actions }) : null] })) : null, _jsx("div", { className: cn("zvk-composite-summary-metric-grid__metrics", classNames?.metrics), children: metrics.map((metric) => (_jsxs(Card, { className: cn("zvk-composite-summary-metric-grid__card", classNames?.card), "data-action-position": actionPosition, padding: "none", variant: "outline", children: [metric.action && actionPosition === "top" ? (_jsx("div", { className: cn("zvk-composite-summary-metric-grid__action", classNames?.action), "data-position": "top", children: metric.action })) : null, _jsx(Stat, { className: cn("zvk-composite-summary-metric-grid__stat", classNames?.stat), description: metric.description, label: metric.label, trend: metric.trend, value: metric.value, ...(metric.tone === undefined ? {} : { tone: metric.tone }) }), metric.action && actionPosition === "footer" ? (_jsx("div", { className: cn("zvk-composite-summary-metric-grid__action", classNames?.action), "data-position": "footer", children: metric.action })) : null] }, metric.id))) })] }));
+}

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

@@ -0,0 +1,14 @@
+import * as React from "react";
+export interface AppWorkspaceShellProps extends React.HTMLAttributes<HTMLDivElement> {
+    accountMenu?: React.ReactNode | undefined;
+    brand: React.ReactNode;
+    children?: React.ReactNode | undefined;
+    commandPalette?: React.ReactNode | undefined;
+    footer?: React.ReactNode | undefined;
+    header?: React.ReactNode | undefined;
+    mobileNavigationLabel?: string | undefined;
+    navigation: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    workspaceSwitcher?: React.ReactNode | undefined;
+}
+export declare function AppWorkspaceShell({ accountMenu, brand, children, className, commandPalette, footer, header, mobileNavigationLabel, navigation, ref, workspaceSwitcher, ...props }: AppWorkspaceShellProps): React.JSX.Element;

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

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { SidebarShell } from "@zvk/ui/sidebar-shell";
+import { cn } from "../utils/cn.js";
+export function AppWorkspaceShell({ accountMenu, brand, children, className, commandPalette, footer, header, mobileNavigationLabel = "Navigation", navigation, ref, workspaceSwitcher, ...props }) {
+    const hasTopbar = Boolean(header || commandPalette || workspaceSwitcher || accountMenu);
+    const shellProps = {
+        ...props,
+        ...(ref === undefined ? {} : { ref })
+    };
+    return (_jsxs(SidebarShell, { ...shellProps, className: cn("zvk-composite-app-workspace-shell", className), width: "md", children: [_jsxs(SidebarShell.Sidebar, { className: "zvk-composite-app-workspace-shell__sidebar", "aria-label": "Workspace", children: [_jsx("div", { className: "zvk-composite-app-workspace-shell__brand", children: brand }), workspaceSwitcher ? (_jsx("div", { className: "zvk-composite-app-workspace-shell__workspace-switcher", children: workspaceSwitcher })) : null, _jsx("div", { className: "zvk-composite-app-workspace-shell__navigation", children: navigation })] }), _jsxs(SidebarShell.Main, { className: "zvk-composite-app-workspace-shell__main", children: [_jsxs("details", { className: "zvk-composite-app-workspace-shell__mobile-nav", children: [_jsx("summary", { className: "zvk-composite-app-workspace-shell__mobile-nav-summary", children: mobileNavigationLabel }), _jsxs("div", { className: "zvk-composite-app-workspace-shell__mobile-nav-content", children: [_jsxs("div", { className: "zvk-composite-app-workspace-shell__mobile-nav-context", children: [_jsx("div", { className: "zvk-composite-app-workspace-shell__brand", children: brand }), workspaceSwitcher ? (_jsx("div", { className: "zvk-composite-app-workspace-shell__workspace-switcher", children: workspaceSwitcher })) : null] }), navigation] })] }), hasTopbar ? (_jsxs(SidebarShell.Header, { className: "zvk-composite-app-workspace-shell__header", children: [header ? _jsx("div", { className: "zvk-composite-app-workspace-shell__header-content", children: header }) : null, commandPalette ? (_jsx("div", { className: "zvk-composite-app-workspace-shell__command-palette", children: commandPalette })) : null, accountMenu ? _jsx("div", { className: "zvk-composite-app-workspace-shell__account-menu", children: accountMenu }) : null] })) : null, _jsx(SidebarShell.Content, { className: "zvk-composite-app-workspace-shell__content", children: children }), footer ? (_jsx(SidebarShell.Footer, { className: "zvk-composite-app-workspace-shell__footer", children: footer })) : null] })] }));
+}

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

@@ -0,0 +1,33 @@
+import * as React from "react";
+import type { WorkspaceHeaderHeadingLevel } from "./workspace-header.js";
+export interface SectionedWorkspaceShellItem {
+    badge?: React.ReactNode | undefined;
+    description?: React.ReactNode | undefined;
+    disabled?: boolean | undefined;
+    href?: string | undefined;
+    icon?: React.ReactNode | undefined;
+    id: string;
+    label: React.ReactNode;
+}
+export interface SectionedWorkspaceShellSection {
+    id: string;
+    items: SectionedWorkspaceShellItem[];
+    label: React.ReactNode;
+}
+export interface SectionedWorkspaceShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    actions?: React.ReactNode | undefined;
+    activeItemId?: string | undefined;
+    children?: React.ReactNode | undefined;
+    description?: React.ReactNode | undefined;
+    footer?: React.ReactNode | undefined;
+    headingLevel?: WorkspaceHeaderHeadingLevel | undefined;
+    navLabel?: string | undefined;
+    onItemSelect?: ((itemId: string) => void) | undefined;
+    ref?: React.Ref<HTMLDivElement> | undefined;
+    sections: SectionedWorkspaceShellSection[];
+    title?: React.ReactNode | undefined;
+    toolbar?: React.ReactNode | undefined;
+}
+export type SectionedWorkspaceItem = SectionedWorkspaceShellItem;
+export type SectionedWorkspaceSection = SectionedWorkspaceShellSection;
+export declare function SectionedWorkspaceShell({ actions, activeItemId, children, className, description, footer, headingLevel, navLabel, onItemSelect, ref, sections, title, toolbar, ...props }: SectionedWorkspaceShellProps): React.JSX.Element;

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

@@ -0,0 +1,36 @@
+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 { WorkspaceHeader } from "./workspace-header.js";
+export function SectionedWorkspaceShell({ actions, activeItemId, children, className, description, footer, headingLevel, navLabel = "Workspace navigation", onItemSelect, ref, sections, title, toolbar, ...props }) {
+    const hasHeader = Boolean(title || description || actions || toolbar);
+    const navigationProps = {
+        ...(activeItemId === undefined ? {} : { activeItemId }),
+        ...(onItemSelect === undefined ? {} : { onItemSelect })
+    };
+    const headerProps = {
+        ...(actions === undefined ? {} : { actions }),
+        ...(description === undefined ? {} : { description }),
+        ...(headingLevel === undefined ? {} : { headingLevel }),
+        ...(toolbar === undefined ? {} : { toolbar })
+    };
+    return (_jsxs("div", { ...props, ref: ref, className: cn("zvk-composite-sectioned-workspace-shell", className), children: [_jsx("aside", { className: "zvk-composite-sectioned-workspace-shell__sidebar", children: _jsx(SectionedWorkspaceNavigation, { ...navigationProps, navLabel: navLabel, sections: sections }) }), _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] })] }));
+}
+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 handleSelect = () => onItemSelect?.(item.id);
+    const itemProps = {
+        ...(item.badge === undefined ? {} : { badge: item.badge }),
+        ...(item.disabled === undefined ? {} : { disabled: item.disabled }),
+        ...(item.icon === undefined ? {} : { icon: item.icon }),
+        onClick: handleSelect
+    };
+    if (item.href) {
+        return (_jsx(SectionedSidebarNav.Item, { ...itemProps, active: active, href: item.href, children: content }));
+    }
+    return (_jsx(SectionedSidebarNav.Item, { ...itemProps, active: active, children: content }));
+}

package/dist/navigation/workspace-header.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+export type WorkspaceHeaderAlign = "start" | "center";
+export type WorkspaceHeaderHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface WorkspaceHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    actions?: React.ReactNode | undefined;
+    align?: WorkspaceHeaderAlign | undefined;
+    description?: React.ReactNode | undefined;
+    eyebrow?: React.ReactNode | undefined;
+    headingLevel?: WorkspaceHeaderHeadingLevel | undefined;
+    meta?: React.ReactNode | undefined;
+    ref?: React.Ref<HTMLElement> | undefined;
+    status?: React.ReactNode | undefined;
+    title: React.ReactNode;
+    toolbar?: React.ReactNode | undefined;
+}
+export interface BreadcrumbPageHeaderItem {
+    current?: boolean | undefined;
+    href?: string | undefined;
+    label: React.ReactNode;
+}
+export interface BreadcrumbPageHeaderProps extends Omit<WorkspaceHeaderProps, "eyebrow"> {
+    breadcrumbs: BreadcrumbPageHeaderItem[];
+}
+export declare function WorkspaceHeader({ actions, align, className, description, eyebrow, headingLevel, meta, ref, status, title, toolbar, ...props }: WorkspaceHeaderProps): React.JSX.Element;
+export declare function BreadcrumbPageHeader({ breadcrumbs, className, ...headerProps }: BreadcrumbPageHeaderProps): React.JSX.Element;

package/dist/navigation/workspace-header.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Breadcrumbs } from "@zvk/ui/breadcrumbs";
+import { cn } from "../utils/cn.js";
+function getHeadingTag(headingLevel) {
+    switch (headingLevel) {
+        case 1:
+            return "h1";
+        case 2:
+            return "h2";
+        case 3:
+            return "h3";
+        case 4:
+            return "h4";
+        case 5:
+            return "h5";
+        case 6:
+            return "h6";
+    }
+}
+export function WorkspaceHeader({ actions, align = "start", className, description, eyebrow, headingLevel = 1, meta, ref, status, title, toolbar, ...props }) {
+    const hasKicker = Boolean(eyebrow || status);
+    const hasBody = Boolean(description || meta);
+    const hasControls = Boolean(actions || toolbar);
+    const Heading = getHeadingTag(headingLevel);
+    return (_jsxs("header", { ...props, ref: ref, className: cn("zvk-composite-workspace-header", className), "data-align": align, children: [_jsxs("div", { className: "zvk-composite-workspace-header__content", children: [hasKicker ? (_jsxs("div", { className: "zvk-composite-workspace-header__kicker", children: [eyebrow ? _jsx("span", { className: "zvk-composite-workspace-header__eyebrow", children: eyebrow }) : null, status ? _jsx("span", { className: "zvk-composite-workspace-header__status", children: status }) : null] })) : null, _jsx(Heading, { className: "zvk-composite-workspace-header__title", children: title }), hasBody ? (_jsxs("div", { className: "zvk-composite-workspace-header__body", children: [description ? _jsx("p", { className: "zvk-composite-workspace-header__description", children: description }) : null, meta ? _jsx("div", { className: "zvk-composite-workspace-header__meta", children: meta }) : null] })) : null] }), hasControls ? (_jsxs("div", { className: "zvk-composite-workspace-header__controls", children: [toolbar ? _jsx("div", { className: "zvk-composite-workspace-header__toolbar", children: toolbar }) : null, actions ? _jsx("div", { className: "zvk-composite-workspace-header__actions", children: actions }) : null] })) : null] }));
+}
+export function BreadcrumbPageHeader({ breadcrumbs, className, ...headerProps }) {
+    return (_jsxs("div", { className: cn("zvk-composite-breadcrumb-page-header", className), children: [_jsx(Breadcrumbs, { children: breadcrumbs.map((breadcrumb, index) => {
+                    const breadcrumbProps = {
+                        ...(breadcrumb.current === undefined ? {} : { current: breadcrumb.current }),
+                        ...(breadcrumb.href === undefined ? {} : { href: breadcrumb.href })
+                    };
+                    return (_jsx(Breadcrumbs.Item, { ...breadcrumbProps, children: breadcrumb.label }, `${String(breadcrumb.label)}-${index}`));
+                }) }), _jsx(WorkspaceHeader, { ...headerProps, className: "zvk-composite-breadcrumb-page-header__header" })] }));
+}

package/dist/state/state-surface.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+export type StateSurfaceState = "loading" | "empty" | "error" | "not-found" | "permission" | "search-empty" | "success";
+export type StateSurfaceSize = "sm" | "md" | "lg";
+export type StateSurfaceAlign = "start" | "center";
+export interface StateSurfaceClassNames {
+    emptyState?: string;
+    footer?: string;
+}
+export interface StateSurfaceProps extends Omit<React.ComponentPropsWithoutRef<"section">, "title"> {
+    state: StateSurfaceState;
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    icon?: React.ReactNode;
+    actions?: React.ReactNode;
+    footer?: React.ReactNode;
+    classNames?: StateSurfaceClassNames;
+    size?: StateSurfaceSize;
+    align?: StateSurfaceAlign;
+    ref?: React.Ref<HTMLElement>;
+}
+export declare function StateSurface({ actions, align, className, classNames, description, footer, icon, ref, size, state, title, ...props }: StateSurfaceProps): React.JSX.Element;