@contractspec/bundle.library 3.9.8 → 3.9.9

package/dist/components/docs/libraries/LibrariesApplicationShellPage.js

@@ -1,12 +1,13 @@
 // @bun
-var v=Object.defineProperty;var f=(t)=>t;function y(t,n){this[t]=f.bind(null,n)}var k=(t,n)=>{for(var s in n)v(t,s,{get:n[s],enumerable:!0,configurable:!0,set:y.bind(n,s)})};var N=(t,n)=>()=>(t&&(n=t(t=0)),n);var d=`import {
+var w=Object.defineProperty;var k=(t)=>t;function N(t,n){this[t]=k.bind(null,n)}var O=(t,n)=>{for(var d in n)w(t,d,{get:n[d],enumerable:!0,configurable:!0,set:N.bind(n,d)})};var C=(t,n)=>()=>(t&&(n=t(t=0)),n);var p=`import {
   AppShell,
-  PageOutline,
-  type AppShellNavigationSection,
+  type ShellCommandGroup,
+  type ShellNavSection,
+  type ShellNotificationCenter,
   type PageOutlineItem,
 } from "@contractspec/lib.design-system/shell";
 
-const navigation: AppShellNavigationSection[] = [
+const navigation: ShellNavSection[] = [
   {
     title: "Workspace",
     items: [
@@ -23,6 +24,16 @@ const navigation: AppShellNavigationSection[] = [
   },
 ];
 
+const commands: ShellCommandGroup[] = [
+  {
+    heading: "Quick actions",
+    items: [
+      { id: "new-contract", label: "New contract", shortcut: "N" },
+      { id: "import", label: "Import existing app" },
+    ],
+  },
+];
+
 const outline: PageOutlineItem[] = [
   {
     id: "architecture",
@@ -35,41 +46,104 @@ const outline: PageOutlineItem[] = [
   },
 ];
 
+const notifications: ShellNotificationCenter = {
+  label: "Notifications",
+  loading: false,
+  unreadCount: 2,
+  items: [
+    {
+      id: "contract-approved",
+      title: "Contract approved",
+      body: "Billing.create is ready to publish.",
+      status: "unread",
+      createdAt: "2026-04-29T09:30:00Z",
+      actionUrl: "/contracts/billing.create",
+      category: "Review",
+    },
+  ],
+  onSelect: (item) => openNotificationTarget(item),
+  onMarkRead: (item) => markNotificationRead(item.id),
+  onMarkAllRead: () => markAllNotificationsRead(),
+};
+
 export function WorkspacePage() {
   return (
     <AppShell
-      brand={{ label: "ContractSpec", href: "/dashboard" }}
+      title="ContractSpec"
+      homeHref="/dashboard"
       navigation={navigation}
+      commands={commands}
       breadcrumbs={[
         { label: "Workspace", href: "/dashboard" },
         { label: "Contracts" },
       ]}
-      command={{
-        placeholder: "Search contracts or run an action",
-        groups: [
-          {
-            title: "Quick actions",
-            actions: [
-              { id: "new-contract", label: "New contract" },
-              { id: "import", label: "Import existing app" },
-            ],
-          },
-        ],
-      }}
-      user={{
-        name: "Ada Lovelace",
-        email: "ada@example.com",
-        actions: [{ label: "Sign out", onSelect: () => signOut() }],
-      }}
-      pageOutline={<PageOutline items={outline} activeId="desktop" />}
+      notifications={notifications}
+      pageOutline={outline}
+      activeHref="/contracts"
+      activeOutlineId="desktop"
+      userMenu={<UserMenu onSignOut={() => signOut()} />}
     >
       <main>{/* route content */}</main>
     </AppShell>
   );
-}`,p=`You are implementing a modern application shell from scratch.
+}`,m=`import {
+  ListNotificationsOutputModel,
+  MarkNotificationReadInputModel,
+} from "@contractspec/lib.contracts-spec/notifications";
+import {
+  notificationsSchemaContribution,
+  renderNotificationTemplate,
+} from "@contractspec/lib.notification";
+import type { ShellNotificationCenter } from "@contractspec/lib.design-system/shell";
+
+type NotificationListResult = {
+  unreadCount: number;
+  notifications: Array<{
+    id: string;
+    title: string;
+    body: string;
+    type: string;
+    status: string;
+    readAt?: string | Date | null;
+    createdAt: string | Date;
+    actionUrl?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+};
+
+export function toShellNotifications(
+  data: NotificationListResult,
+  actions: {
+    open: (id: string) => void;
+    markRead: (input: { notificationId: string }) => void;
+    markAllRead: () => void;
+  }
+): ShellNotificationCenter {
+  return {
+    unreadCount: data.unreadCount,
+    items: data.notifications.map((notification) => ({
+      id: notification.id,
+      title: notification.title,
+      body: notification.body,
+      status: notification.status,
+      createdAt: notification.createdAt,
+      actionUrl: notification.actionUrl,
+      category: notification.type,
+      metadata: notification.metadata,
+    })),
+    onSelect: (item) => actions.open(item.id),
+    onMarkRead: (item) => actions.markRead({ notificationId: item.id }),
+    onMarkAllRead: actions.markAllRead,
+  };
+}
+
+void ListNotificationsOutputModel;
+void MarkNotificationReadInputModel;
+void notificationsSchemaContribution;
+void renderNotificationTemplate;`,u=`You are implementing a modern application shell from scratch.
 
 Goal:
-Build a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, and an in-page section navigator called PageOutline.
+Build a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, in-app notifications, and an in-page section navigator called PageOutline.
 
 Use this architecture:
 - Keep route content independent from navigation chrome.
@@ -77,29 +151,37 @@ Use this architecture:
 - Create a command model with search input, grouped suggestions, quick actions, keyboard shortcut labels, empty state, and loading state.
 - Create a breadcrumb model for the topbar.
 - Create a PageOutline model for right-side in-page navigation with exactly three supported levels. It should render anchors, support active section state, and degrade gracefully when no sections exist.
+- Create a ShellNotificationCenter model with render-ready items, unread count, loading and empty states, onSelect, onMarkRead, onMarkAllRead, and optional custom item rendering.
 - Expose the system from the design system or a dedicated shell module, not from a single app route.
 
+Notification boundary:
+- Use @contractspec/lib.contracts-spec/notifications as the canonical source for notification contracts, operation models, and feature metadata.
+- Use @contractspec/lib.notification for reusable notification entities, schema contribution, channels, templates, and i18n helpers.
+- Keep persistence, polling/subscriptions, delivery providers, and optimistic mutations in the host application or notification runtime layer.
+- Pass only render-ready ShellNotificationCenter state into AppShell so the design system does not import or own notification runtime behavior.
+
 Desktop behavior:
 - Persistent left sidebar with app logo/title, command trigger, grouped navigation, nested submenus, and current user/auth/logout area.
 - Topbar with breadcrumbs and an optional command trigger.
+- Topbar notification trigger with unread badge, loading/empty states, mark-read actions, and item selection.
 - Content area with optional right PageOutline.
 - Keep dimensions stable. Navigation labels must not resize layout on hover or active state.
 
 Mobile web behavior:
 - Use bottom navigation for the primary destinations.
-- Put deeper navigation, command search, auth actions, and secondary actions behind a menu or drawer.
+- Put deeper navigation, command search, notifications, auth actions, and secondary actions behind a menu or drawer when the topbar cannot safely hold them.
 - Keep route content first and make the shell controls reachable without covering important content.
 
 Native behavior:
 - Add .native.tsx entrypoints for Expo/React Native.
-- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation and account actions.
-- Keep the same typed navigation, command, breadcrumb, and PageOutline data contracts across web and native.
+- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation, notifications, and account actions.
+- Keep the same typed navigation, command, breadcrumb, notification, and PageOutline data contracts across web and native.
 
 Implementation constraints:
 - Reuse the existing design-system primitives, tokens, icons, and accessibility patterns.
 - Do not hardcode app-specific routes in the shell component.
 - Do not introduce a new dependency unless the repo already uses it for dialogs, menus, icons, or navigation.
-- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, PageOutline level handling, active section state, and mobile/native adaptation contracts.
+- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, notification unread badge/loading/empty/callback behavior, PageOutline level handling, active section state, and mobile/native adaptation contracts.
 - Update docs and exports so developers can import the shell from a stable public API.
 
 Deliverables:
@@ -107,15 +189,18 @@ Deliverables:
 - Web shell components.
 - Native shell components or adapters.
 - PageOutline component with three-level support.
+- ShellNotifications or equivalent notification center component for web and native shell placement.
 - Usage example.
-- Focused tests and typecheck/build evidence.`,m=`You are refactoring an existing application to use the shared application shell system.
+- Focused tests and typecheck/build evidence.`,h=`You are refactoring an existing application to use the shared application shell system.
 
 Goal:
-Replace app-specific sidebar, topbar, breadcrumb, command palette, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell and PageOutline system.
+Replace app-specific sidebar, topbar, breadcrumb, command palette, notification badge/inbox, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell, ShellNotifications, and PageOutline system.
 
 Start by auditing:
 - Current layout wrappers and route groups.
 - Sidebar, topbar, breadcrumb, command/search, auth menu, and mobile navigation implementations.
+- Existing notification badges, inbox panels, toasts that represent durable in-app items, unread count queries, mark-read actions, and delivery modules.
+- Imports from @contractspec/module.notifications that should migrate to @contractspec/lib.contracts-spec/notifications or @contractspec/lib.notification.
 - Any duplicated navigation arrays, route labels, icon maps, access-control checks, and active-state logic.
 - Any in-page summary/table-of-contents components that should become PageOutline data.
 - Web-only assumptions that would block Expo/React Native adaptation.
@@ -124,25 +209,28 @@ Refactor plan:
 1. Define a single typed navigation source for primary nav, grouped sidebar nav, nested children, labels, icons, badges, disabled states, and permissions.
 2. Map existing command/search behavior into grouped command actions with search text and quick actions.
 3. Map existing route metadata into breadcrumbs.
-4. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.
-5. Wrap app routes in AppShell while keeping page content components route-local.
-6. Move primary mobile destinations into bottom navigation and deeper/account actions into a menu or drawer.
-7. Add or preserve .native.tsx adapters when the app targets Expo.
+4. Move canonical notification contracts to @contractspec/lib.contracts-spec/notifications and reusable helpers to @contractspec/lib.notification; keep the old module shim only for compatibility imports that still need the legacy module id.
+5. Convert notification query results into ShellNotificationCenter items with unreadCount, loading, empty state, onSelect, onMarkRead, and onMarkAllRead callbacks.
+6. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.
+7. Wrap app routes in AppShell while keeping page content components route-local.
+8. Move primary mobile destinations into bottom navigation and deeper/account/notification actions into a menu or drawer.
+9. Add or preserve .native.tsx adapters when the app targets Expo.
 
 Preserve behavior:
 - Existing route URLs and access rules.
 - Existing keyboard shortcuts where they are public behavior.
 - Existing analytics or telemetry events on navigation and command actions.
+- Existing notification delivery semantics, unread count semantics, deep links, and mark-read behavior.
 - Existing auth/logout behavior.
 - Existing responsive breakpoints unless there is a documented design-system breakpoint to adopt.
 
 Quality gates:
 - Add regression tests around current visible navigation before removing old shell code when coverage is missing.
-- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, auth menu, mobile bottom navigation, and PageOutline anchor behavior.
+- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, notification unread badge/loading/empty/callback behavior, auth menu, mobile bottom navigation, and PageOutline anchor behavior.
 - Run lint, typecheck, and the app's relevant test/build command.
 - Remove dead app-specific shell components only after the shared shell path is verified.
 
 Output:
 - List old shell files removed or simplified.
 - List new shared shell integration points.
-- Include before/after route coverage and verification commands.`,u=[{title:"Sidebar",body:"Desktop owns brand, command entry, grouped navigation, nested items, and account actions in one persistent scanning area."},{title:"Topbar",body:"Breadcrumbs stay visible while the current route changes. The command trigger can live here when the sidebar is collapsed or hidden."},{title:"PageOutline",body:"The right-side in-page navigator replaces ad hoc tables of contents. It supports three levels of section anchors and active state."},{title:"Mobile adapters",body:"Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation and account actions."}];import{CodeBlock as l,InstallCommand as w}from"@contractspec/lib.design-system";import{Box as h,HStack as O,VStack as o}from"@contractspec/lib.design-system/layout";import{Code as c,H1 as A,H2 as i,H3 as P,P as r,Text as b}from"@contractspec/lib.design-system/typography";import g from"@contractspec/lib.ui-link";import{ChevronRight as E}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";function K(){return a(o,{className:"space-y-8",children:[a(o,{className:"space-y-4",children:[e(A,{className:"font-bold text-4xl",children:"Application shell"}),a(r,{className:"text-lg text-muted-foreground",children:["A reusable navigation system for product apps: desktop sidebar, topbar breadcrumbs, command search, account actions, mobile adapters, and a Notion-style ",e(c,{children:"PageOutline"})," for page sections."]})]}),a(o,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"Installation"}),e(w,{package:"@contractspec/lib.design-system"})]}),a(o,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"What It Standardizes"}),e(h,{className:"grid gap-4 md:grid-cols-2",children:u.map((t)=>a(h,{className:"card-subtle p-4",children:[e(P,{className:"font-semibold",children:t.title}),e(r,{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.body})]},t.title))})]}),a(o,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"Import Surface"}),e(r,{className:"text-muted-foreground",children:"The shell is exposed as a focused design-system subpath so apps can adopt navigation chrome without pulling unrelated documentation or marketing helpers."}),e(l,{language:"tsx",filename:"app-shell-example.tsx",code:d})]}),a(o,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"AI Prompt: Build From Scratch"}),e(r,{className:"text-muted-foreground",children:"Use this prompt when the app does not already have a shell or when the design-system package needs the reusable primitive first."}),e(l,{language:"markdown",filename:"implement-application-shell.md",code:p})]}),a(o,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"AI Prompt: Refactor An App"}),e(r,{className:"text-muted-foreground",children:"Use this prompt when an app already has custom navigation chrome and needs to migrate without breaking route behavior."}),e(l,{language:"markdown",filename:"refactor-to-application-shell.md",code:m})]}),a(o,{className:"card-subtle space-y-3 p-6",children:[e(i,{className:"font-bold text-2xl",children:"Naming"}),a(r,{className:"text-muted-foreground",children:["Use ",e(c,{children:"AppShell"})," for the whole navigation frame and"," ",e(c,{children:"PageOutline"})," for the in-page navigation helper. The latter is the product-app equivalent of a table of contents, but it is intentionally named for live page sections rather than static documentation."]})]}),a(O,{className:"flex flex-wrap items-center gap-3 pt-2",children:[e(g,{href:"/docs/libraries/cross-platform-ui",className:"btn-ghost",children:e(b,{children:"Cross-platform UI"})}),a(g,{href:"/docs/libraries/design-system",className:"btn-primary",children:[e(b,{children:"Design System"})," ",e(E,{size:16})]})]})]})}export{K as LibrariesApplicationShellPage};
+- Include before/after route coverage and verification commands.`,b=[{title:"Contracts stay canonical",body:"Use @contractspec/lib.contracts-spec/notifications for operation models, feature metadata, and contract-level compatibility."},{title:"Runtime helpers stay reusable",body:"Use @contractspec/lib.notification for schema contribution, channel adapters, templates, and i18n without importing the deprecated module shim in new code."},{title:"Apps own live state",body:"Fetch, subscribe, persist, mutate, and reconcile notification state in the host app or runtime layer where auth and tenancy are known."},{title:"Shell receives view state",body:"Pass AppShell a ShellNotificationCenter with render-ready items, counts, loading state, and callbacks; the design system only renders affordances."}],g=[{title:"Sidebar",body:"Desktop owns brand, command entry, grouped navigation, nested items, and account actions in one persistent scanning area."},{title:"Topbar",body:"Breadcrumbs stay visible while the current route changes. Command search and notification affordances can live here when the sidebar is collapsed or hidden."},{title:"PageOutline",body:"The right-side in-page navigator replaces ad hoc tables of contents. It supports three levels of section anchors and active state."},{title:"Notifications",body:"The shell renders unread badges, item lists, loading/empty states, mark-read actions, and deep-link selection from host-owned notification state."},{title:"Mobile adapters",body:"Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation, notifications, and account actions."}];import{CodeBlock as c,InstallCommand as R}from"@contractspec/lib.design-system";import{Box as l,HStack as A,VStack as i}from"@contractspec/lib.design-system/layout";import{Code as o,H1 as S,H2 as s,H3 as f,P as r,Text as v}from"@contractspec/lib.design-system/typography";import y from"@contractspec/lib.ui-link";import{ChevronRight as M}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";function K(){return a(i,{className:"space-y-8",children:[a(i,{className:"space-y-4",children:[e(S,{className:"font-bold text-4xl",children:"Application shell"}),a(r,{className:"text-lg text-muted-foreground",children:["A reusable navigation system for product apps: desktop sidebar, topbar breadcrumbs, command search, account actions, mobile adapters, and a Notion-style ",e(o,{children:"PageOutline"})," for page sections, with prop-driven in-app notifications for web and native shells."]})]}),a(i,{className:"space-y-4",children:[e(s,{className:"font-bold text-2xl",children:"Installation"}),e(R,{package:"@contractspec/lib.design-system"})]}),a(i,{className:"space-y-4",children:[e(s,{className:"font-bold text-2xl",children:"What It Standardizes"}),e(l,{className:"grid gap-4 md:grid-cols-2",children:g.map((t)=>a(l,{className:"card-subtle p-4",children:[e(f,{className:"font-semibold",children:t.title}),e(r,{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.body})]},t.title))})]}),a(i,{className:"space-y-4",children:[e(s,{className:"font-bold text-2xl",children:"Import Surface"}),e(r,{className:"text-muted-foreground",children:"The shell is exposed as a focused design-system subpath so apps can adopt navigation chrome without pulling unrelated documentation or marketing helpers."}),e(c,{language:"tsx",filename:"app-shell-example.tsx",code:p})]}),a(i,{className:"space-y-4",children:[e(s,{className:"font-bold text-2xl",children:"Notification Center Boundary"}),a(r,{className:"text-muted-foreground",children:["Notifications are part of the shell experience, but the design system only renders the affordance. Contracts, runtime helpers, persistence, delivery, auth, and subscriptions stay outside the shell and feed a render-ready ",e(o,{children:"ShellNotificationCenter"})," into"," ",e(o,{children:"AppShell"}),"."]}),e(l,{className:"grid gap-4 md:grid-cols-2",children:b.map((t)=>a(l,{className:"card-subtle p-4",children:[e(f,{className:"font-semibold",children:t.title}),e(r,{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.body})]},t.title))}),e(c,{language:"tsx",filename:"notification-center-boundary.ts",code:m})]}),a(i,{className:"space-y-4",children:[e(s,{className:"font-bold text-2xl",children:"AI Prompt: Build From Scratch"}),e(r,{className:"text-muted-foreground",children:"Use this prompt when the app does not already have a shell, command surface, page outline, or in-app notification center."}),e(c,{language:"markdown",filename:"implement-application-shell.md",code:u})]}),a(i,{className:"space-y-4",children:[e(s,{className:"font-bold text-2xl",children:"AI Prompt: Refactor An App"}),e(r,{className:"text-muted-foreground",children:"Use this prompt when an app already has custom navigation chrome and notification UI that need to migrate without breaking route behavior, unread counts, or delivery semantics."}),e(c,{language:"markdown",filename:"refactor-to-application-shell.md",code:h})]}),a(i,{className:"card-subtle space-y-3 p-6",children:[e(s,{className:"font-bold text-2xl",children:"Naming"}),a(r,{className:"text-muted-foreground",children:["Use ",e(o,{children:"AppShell"})," for the whole navigation frame and"," ",e(o,{children:"PageOutline"})," for the in-page navigation helper. The latter is the product-app equivalent of a table of contents, but it is intentionally named for live page sections rather than static documentation. Use ",e(o,{children:"ShellNotifications"})," for the notification affordance when it is rendered directly, or pass the same data contract through ",e(o,{children:"AppShell"})," with the"," ",e(o,{children:"notifications"})," prop."]})]}),a(A,{className:"flex flex-wrap items-center gap-3 pt-2",children:[e(y,{href:"/docs/libraries/cross-platform-ui",className:"btn-ghost",children:e(v,{children:"Cross-platform UI"})}),a(y,{href:"/docs/libraries/design-system",className:"btn-primary",children:[e(v,{children:"Design System"})," ",e(M,{size:16})]})]})]})}export{K as LibrariesApplicationShellPage};

package/dist/components/docs/libraries/LibrariesDataViewsPage.js

@@ -1,5 +1,122 @@
 // @bun
-var n=Object.defineProperty;var d=(t)=>t;function l(t,o){this[t]=d.bind(null,o)}var m=(t,o)=>{for(var i in o)n(t,i,{get:o[i],enumerable:!0,configurable:!0,set:l.bind(o,i)})};var g=(t,o)=>()=>(t&&(o=t(t=0)),o);import{CodeBlock as r,InstallCommand as s}from"@contractspec/lib.design-system";import c from"@contractspec/lib.ui-link";import{ChevronRight as p}from"lucide-react";import{jsx as e,jsxs as a}from"react/jsx-runtime";function b(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"DataViews Runtime Library"}),a("p",{className:"text-lg text-muted-foreground",children:["The ",e("code",{children:"@contractspec/lib.contracts-spec/data-views"})," and"," ",e("code",{children:"@contractspec/lib.design-system"})," libraries provide the runtime logic and UI components to render DataViews in your application."]})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Installation"}),e(s,{package:["@contractspec/lib.contracts-spec","@contractspec/lib.design-system"]})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"DataViewRenderer"}),e("p",{className:"text-muted-foreground",children:"The primary component for rendering any DataView. It automatically selects the correct layout (List, Table, Grid, Detail) based on the spec."}),e(r,{language:"tsx",code:`import { DataViewRenderer } from '@contractspec/lib.design-system';
+var Z=Object.defineProperty;var b=(F)=>F;function W(F,K){this[F]=b.bind(null,K)}var O=(F,K)=>{for(var v in K)Z(F,v,{get:K[v],enumerable:!0,configurable:!0,set:W.bind(K,v)})};var B=(F,K)=>()=>(F&&(K=F(F=0)),K);import{CodeBlock as $,InstallCommand as X}from"@contractspec/lib.design-system";import{HStack as g,VStack as Q}from"@contractspec/lib.design-system/layout";import{List as h,ListItem as J}from"@contractspec/lib.design-system/list";import{Code as q,H1 as u,H2 as U,H3 as y,P as Y,Text as z}from"@contractspec/lib.design-system/typography";import G from"@contractspec/lib.ui-link";import{ChevronRight as M}from"lucide-react";import{jsx as f,jsxs as w}from"react/jsx-runtime";var p=`import { defineDataView } from '@contractspec/lib.contracts-spec/data-views';
+
+export const AccountsDataView = defineDataView({
+  meta: {
+    key: 'crm.accounts',
+    version: '1.0.0',
+    title: 'Accounts',
+    description: 'Customer account workspace',
+    domain: 'crm',
+    entity: 'account',
+    owners: ['@crm'],
+    tags: ['crm', 'accounts'],
+    stability: 'stable',
+  },
+  source: {
+    primary: { key: 'crm.accounts.list', version: '1.0.0' },
+  },
+  view: {
+    kind: 'table',
+    fields: [
+      { key: 'name', label: 'Name', dataPath: 'name', sortable: true },
+      { key: 'owner', label: 'Owner', dataPath: 'owner' },
+      { key: 'arr', label: 'ARR', dataPath: 'arr', format: { type: 'currency', currency: 'EUR' } },
+      {
+        key: 'internalNotes',
+        label: 'Internal notes',
+        dataPath: 'internalNotes',
+        visibility: { minDataDepth: 'detailed' },
+      },
+    ],
+    columns: [
+      { field: 'name' },
+      { field: 'owner' },
+      { field: 'arr' },
+      { field: 'internalNotes' },
+    ],
+    collection: {
+      viewModes: {
+        defaultMode: 'table',
+        allowedModes: ['list', 'grid', 'table'],
+      },
+      pagination: {
+        pageSize: 25,
+        pageSizeOptions: [10, 25, 50],
+      },
+      toolbar: {
+        search: true,
+        viewMode: true,
+        filters: true,
+        density: true,
+        dataDepth: true,
+      },
+      density: 'comfortable',
+      dataDepth: 'standard',
+      personalization: {
+        enabled: true,
+        persist: {
+          viewMode: true,
+          density: true,
+          dataDepth: true,
+          pageSize: true,
+        },
+      },
+    },
+  },
+});`,D=`import { DataViewRenderer } from '@contractspec/lib.design-system';
+import { resolveDataViewPreferences } from '@contractspec/lib.personalization/data-view-preferences';
+
+const resolved = resolveDataViewPreferences({
+  spec: AccountsDataView,
+  preferences: profile.canonical,
+  insights,
+  record: savedDataViewPreference,
+});
+
+<DataViewRenderer
+  spec={AccountsDataView}
+  items={accounts}
+  defaultViewMode={resolved.viewMode}
+  defaultDensity={resolved.density}
+  defaultDataDepth={resolved.dataDepth}
+  pagination={{
+    page,
+    pageSize: resolved.pageSize ?? 25,
+    total,
+  }}
+  onViewModeChange={(viewMode) => {
+    tracker.trackDataViewInteraction({
+      dataViewKey: AccountsDataView.meta.key,
+      dataViewVersion: AccountsDataView.meta.version,
+      action: 'view_mode_changed',
+      viewMode,
+    });
+  }}
+  onDensityChange={(density) => {
+    tracker.trackDataViewInteraction({
+      dataViewKey: AccountsDataView.meta.key,
+      action: 'density_changed',
+      density,
+    });
+  }}
+  onDataDepthChange={(dataDepth) => {
+    tracker.trackDataViewInteraction({
+      dataViewKey: AccountsDataView.meta.key,
+      action: 'data_depth_changed',
+      dataDepth,
+    });
+  }}
+/>;
+`,N=`Implement a production DataView for <entity>.
+
+Requirements:
+- Define one canonical DataViewSpec with kind 'table', collection viewModes for list/grid/table, pagination defaults, toolbar search/filter/view mode/density/dataDepth controls, and personalization persist hints.
+- Mark fields that should only appear in richer experiences with visibility.minDataDepth.
+- Render it with DataViewRenderer using plain props from resolveDataViewPreferences.
+- Track user interactions with trackDataViewInteraction for view mode, density, data depth, search, filters, sorting, and pagination.
+- Keep @contractspec/lib.design-system independent from @contractspec/lib.personalization.
+- Add focused tests for default resolution, invalid-mode fallback, data-depth projection, and behavior-derived preferred view mode.`;function l(){return w(Q,{className:"space-y-8",children:[w(Q,{className:"space-y-4",children:[f(u,{className:"font-bold text-4xl",children:"DataViews Runtime Library"}),w(Y,{className:"text-lg text-muted-foreground",children:["The ",f(q,{children:"@contractspec/lib.contracts-spec/data-views"})," and"," ",f(q,{children:"@contractspec/lib.design-system"})," libraries provide the runtime logic and UI components to render DataViews in your application."]})]}),w(Q,{className:"space-y-4",children:[f(U,{className:"font-bold text-2xl",children:"Installation"}),f(X,{package:["@contractspec/lib.contracts-spec","@contractspec/lib.design-system"]})]}),w(Q,{className:"space-y-4",children:[f(U,{className:"font-bold text-2xl",children:"DataViewRenderer"}),f(Y,{className:"text-muted-foreground",children:"The primary component for rendering any DataView. It automatically selects the correct layout (List, Table, Grid, Detail) based on the spec."}),f($,{language:"tsx",code:`import { DataViewRenderer } from '@contractspec/lib.design-system';
 import { MyUserList } from './specs/users.data-view';
 
 export function UserPage() {
@@ -11,7 +128,7 @@ export function UserPage() {
       onPageChange={(page) => fetchPage(page)}
     />
   );
-}`}),e("h3",{className:"font-semibold text-xl",children:"Props"}),a("ul",{className:"list-disc space-y-2 pl-6 text-muted-foreground",children:[a("li",{children:[e("code",{children:"spec"}),": The DataViewSpec definition."]}),a("li",{children:[e("code",{children:"items"}),": Array of data items to render."]}),a("li",{children:[e("code",{children:"filters"}),": Current filter state object."]}),a("li",{children:[e("code",{children:"onFilterChange"}),": Callback when typed filters change. Renderers emit ",e("code",{children:"DataViewFilterValue"})," objects for numeric, percent, currency, temporal, duration, and boolean filters."]}),a("li",{children:[e("code",{children:"pagination"}),": Object with ",e("code",{children:"page"}),","," ",e("code",{children:"pageSize"}),", ",e("code",{children:"total"}),"."]}),a("li",{children:[e("code",{children:"onPageChange"}),": Callback when page changes."]}),a("li",{children:[e("code",{children:"viewMode"})," / ",e("code",{children:"defaultViewMode"}),": Controlled or initial collection mode for specs that allow ",e("code",{children:"list"}),","," ",e("code",{children:"grid"}),", or ",e("code",{children:"table"})," projections through"," ",e("code",{children:"view.collection.viewModes"}),"."]}),a("li",{children:[e("code",{children:"density"})," / ",e("code",{children:"defaultDensity"}),": Controlled or initial density for collection renderers, seeded by"," ",e("code",{children:"view.collection.density"})," and table"," ",e("code",{children:"view.density"}),"."]})]})]}),a("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Query Generation"}),a("p",{className:"text-muted-foreground",children:["The ",e("code",{children:"DataViewQueryGenerator"})," utility helps translate DataView parameters (filters, sorting, pagination) into query arguments for your backend."]}),e(r,{language:"typescript",code:`import { DataViewQueryGenerator } from '@contractspec/lib.contracts-spec/data-views/query-generator';
+}`}),f(y,{className:"font-semibold text-xl",children:"Props"}),w(h,{className:"list-disc space-y-2 pl-6 text-muted-foreground",children:[f(J,{children:w(z,{children:[f(q,{children:"spec"}),": The DataViewSpec definition."]})}),f(J,{children:w(z,{children:[f(q,{children:"items"}),": Array of data items to render."]})}),f(J,{children:w(z,{children:[f(q,{children:"filters"}),": Current filter state object."]})}),f(J,{children:w(z,{children:[f(q,{children:"onFilterChange"}),": Callback when typed filters change. Renderers emit ",f(q,{children:"DataViewFilterValue"})," objects for numeric, percent, currency, temporal, duration, and boolean filters."]})}),f(J,{children:w(z,{children:[f(q,{children:"pagination"}),": Object with ",f(q,{children:"page"}),","," ",f(q,{children:"pageSize"}),", ",f(q,{children:"total"}),"."]})}),f(J,{children:w(z,{children:[f(q,{children:"onPageChange"}),": Callback when page changes."]})}),f(J,{children:w(z,{children:[f(q,{children:"viewMode"})," / ",f(q,{children:"defaultViewMode"}),": Controlled or initial collection mode for specs that allow ",f(q,{children:"list"}),","," ",f(q,{children:"grid"}),", or ",f(q,{children:"table"})," projections through"," ",f(q,{children:"view.collection.viewModes"}),"."]})}),f(J,{children:w(z,{children:[f(q,{children:"density"})," / ",f(q,{children:"defaultDensity"}),": Controlled or initial density for collection renderers. Host apps can seed this from ",f(q,{children:"@contractspec/lib.personalization"})," while specs can declare ",f(q,{children:"view.collection.density"})," and table"," ",f(q,{children:"view.density"})," defaults."]})}),f(J,{children:w(z,{children:[f(q,{children:"dataDepth"})," / ",f(q,{children:"defaultDataDepth"}),": Controlled or initial summary/standard/detailed/exhaustive projection. Fields can declare ",f(q,{children:"visibility.minDataDepth"}),", and collection specs can opt into ",f(q,{children:"view.collection.personalization"})," ","persistence hints."]})})]})]}),w(Q,{className:"space-y-4",children:[f(U,{className:"font-bold text-2xl",children:"Collection Defaults And Data Depth"}),w(Y,{className:"text-muted-foreground",children:["Use one authored ",f(q,{children:"DataViewSpec"})," for list, grid, and table experiences. ",f(q,{children:"view.collection"})," declares allowed modes, toolbar controls, pagination defaults, density, data depth, and persistence hints. ",f(q,{children:"visibility.minDataDepth"})," lets a field appear only when the renderer is in a detailed or exhaustive mode."]}),f($,{language:"typescript",code:p})]}),w(Q,{className:"space-y-4",children:[f(U,{className:"font-bold text-2xl",children:"Personalization Bridge"}),w(Y,{className:"text-muted-foreground",children:["Resolve user preferences in the host app, then pass ordinary renderer props into ",f(q,{children:"DataViewRenderer"}),". The bridge helper lives in"," ",f(q,{children:"@contractspec/lib.personalization"}),", so the design-system renderer stays portable for apps that do not use personalization. See the"," ",f(G,{href:"/docs/libraries/personalization",className:"text-[color:var(--rust)] underline underline-offset-4",children:f(z,{children:"personalization library guide"})})," ","for the behavior tracker, analyzer, and DataView preference resolver."]}),f($,{language:"tsx",code:D})]}),w(Q,{className:"space-y-4",children:[f(U,{className:"font-bold text-2xl",children:"Agent Prompt"}),f(Y,{className:"text-muted-foreground",children:"Use this prompt when asking an implementation agent to add a preference-aware collection DataView without breaking package boundaries."}),f($,{language:"markdown",code:N})]}),w(Q,{className:"space-y-4",children:[f(U,{className:"font-bold text-2xl",children:"Query Generation"}),w(Y,{className:"text-muted-foreground",children:["The ",f(q,{children:"DataViewQueryGenerator"})," utility helps translate DataView parameters (filters, sorting, pagination) into query arguments for your backend."]}),f($,{language:"typescript",code:`import { DataViewQueryGenerator } from '@contractspec/lib.contracts-spec/data-views/query-generator';
 
 const generator = new DataViewQueryGenerator(MyUserList);
 const params = {
@@ -26,4 +143,4 @@ const params = {
 const errors = generator.validateParams(params);
 const query = generator.generate(params);
 
-// query.input contains skip/take plus the typed filter payloads.`})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[e(c,{href:"/docs/libraries",className:"btn-ghost",children:"Back to Libraries"}),a(c,{href:"/docs/libraries/data-backend",className:"btn-primary",children:["Next: Data & Backend ",e(p,{size:16})]})]})]})}export{b as LibrariesDataViewsPage};
+// query.input contains skip/take plus the typed filter payloads.`})]}),w(g,{className:"items-center gap-4 pt-4",children:[f(G,{href:"/docs/libraries",className:"btn-ghost",children:f(z,{children:"Back to Libraries"})}),w(G,{href:"/docs/libraries/data-backend",className:"btn-primary",children:[f(z,{children:"Next: Data & Backend"})," ",f(M,{size:16})]})]})]})}export{l as LibrariesDataViewsPage};

package/dist/components/docs/libraries/LibrariesDesignSystemPage.js

@@ -1,5 +1,5 @@
 // @bun
-var s=Object.defineProperty;var n=(a)=>a;function c(a,o){this[a]=n.bind(null,o)}var g=(a,o)=>{for(var l in o)s(a,l,{get:o[l],enumerable:!0,configurable:!0,set:c.bind(o,l)})};var f=(a,o)=>()=>(a&&(o=a(a=0)),o);import{CodeBlock as r,InstallCommand as d}from"@contractspec/lib.design-system";import i from"@contractspec/lib.ui-link";import{ChevronRight as m}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";var p=`import { Button, DataTable } from '@contractspec/lib.design-system';
+var c=Object.defineProperty;var s=(o)=>o;function l(o,a){this[o]=s.bind(null,a)}var v=(o,a)=>{for(var n in a)c(o,n,{get:a[n],enumerable:!0,configurable:!0,set:l.bind(a,n)})};var y=(o,a)=>()=>(o&&(a=o(o=0)),a);import{CodeBlock as r,InstallCommand as d}from"@contractspec/lib.design-system";import i from"@contractspec/lib.ui-link";import{ChevronRight as m}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";var p=`import { Button, DataTable } from '@contractspec/lib.design-system';
 import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
 
 import { SHOWCASE_ROWS } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.data';
@@ -81,6 +81,105 @@ export function TenantSurface({ children }: { children: React.ReactNode }) {
 import { Select } from '@contractspec/lib.design-system/controls';
 import { FormDialog } from '@contractspec/lib.design-system/forms';
 import { HStack } from '@contractspec/lib.design-system/layout';
+import { AdaptivePanel } from '@contractspec/lib.design-system/components/overlays';
+import { ObjectReferenceHandler } from '@contractspec/lib.design-system/components/object-reference';
 
 // Root imports remain supported:
-import { Button, DataTable } from '@contractspec/lib.design-system';`;function T(){return t("div",{className:"space-y-8",children:[t("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"@contractspec/lib.design-system"}),t("p",{className:"text-muted-foreground",children:["High-level design system components, patterns, and layouts for LSSM applications. Built on top of ",e("code",{children:"@contractspec/lib.ui-kit"}),"."]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Installation"}),e(d,{package:"@contractspec/lib.design-system"})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"What It Provides"}),t("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:[e("strong",{children:"Composite Components"}),": Molecules and Organisms that solve common UI problems"]}),t("li",{children:[e("strong",{children:"Layouts"}),": Ready-to-use page structures for dashboards, marketing sites, and lists"]}),t("li",{children:[e("strong",{children:"Data Views"}),": Standardized renderers for lists, tables, and detail views"]}),t("li",{children:[e("strong",{children:"Forms"}),": Zod-integrated form layouts and components"]}),t("li",{children:[e("strong",{children:"Code Display"}),": Syntax-highlighted code blocks with package manager tabs"]}),t("li",{children:[e("strong",{children:"Platform Utilities"}),": Hooks for responsive and adaptive design"]}),t("li",{children:[e("strong",{children:"Theme Bridge"}),": ThemeSpec to Tailwind variables, presets, CSS text, and runtime light/dark mode"]}),t("li",{children:[e("strong",{children:"Legal Templates"}),": Compliant templates for Terms, Privacy, and GDPR"]})]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"ThemeSpec to Tailwind"}),t("p",{className:"text-muted-foreground",children:["The theme bridge keeps ",e("code",{children:"ThemeSpec"})," as the source of truth and exposes no-generation Tailwind helpers, optional CSS text serialization, runtime CSS variables, light/dark modes, and OKLCH color pass-through."]}),e(r,{language:"tsx",code:u})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Focused import surfaces"}),e("p",{className:"text-muted-foreground",children:"New code can use focused subpaths for theme, controls, forms, and layout while existing root imports remain compatible."}),e(r,{language:"tsx",code:h})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Data table example"}),t("p",{className:"text-muted-foreground",children:["This is the composed lane from the canonical"," ",e(i,{href:"/docs/examples/data-grid-showcase",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Data Grid Showcase"}),". The design-system wrapper owns title, description, header actions, and the opinionated card shell on top of the raw web primitive."]}),e(r,{language:"tsx",code:p})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Key Exports"}),t("div",{className:"grid gap-4 md:grid-cols-2",children:[t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Organisms"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"AppShell, PageOutline"}),e("li",{children:"AppLayout, AppHeader, AppSidebar"}),e("li",{children:"MarketingLayout, HeroSection"}),e("li",{children:"ListCardPage, ListTablePage"})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Data & Forms"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"DataTable"}),e("li",{children:"DataViewTable"}),e("li",{children:"DataViewRenderer"}),e("li",{children:"ZodForm"}),e("li",{children:"FormLayout, FormDialog"})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Code Display"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"CodeBlock (syntax highlighting)"}),e("li",{children:"CommandTabs (package manager tabs)"}),e("li",{children:"InstallCommand (convenience wrapper)"}),e("li",{children:"CopyButton"})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Providers"}),e("ul",{className:"space-y-1 text-muted-foreground text-sm",children:e("li",{children:"PackageManagerProvider"})})]})]})]}),t("div",{className:"card-subtle space-y-3 p-6",children:[e("h2",{className:"font-bold text-2xl",children:"Where this layer fits"}),t("p",{className:"text-muted-foreground",children:["Read"," ",e(i,{href:"/docs/libraries/application-shell",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Application shell"})," ","for the shared sidebar, topbar, command search, mobile navigation, and"," ",e("code",{children:"PageOutline"})," pattern. Read"," ",e(i,{href:"/docs/libraries/cross-platform-ui",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Cross-platform UI"})," ","for the package split between shared runtime controllers, leaf platform primitives, and this composed design-system layer."]})]}),t("div",{className:"flex items-center gap-4 pt-4",children:[e(i,{href:"/docs/libraries/ui-kit-web",className:"btn-ghost",children:"Previous: UI Kit Web"}),t(i,{href:"/docs/libraries/accessibility",className:"btn-primary",children:["Next: Accessibility ",e(m,{size:16})]})]})]})}export{T as LibrariesDesignSystemPage};
+import { Button, DataTable } from '@contractspec/lib.design-system';`,f=`import {
+  ObjectReferenceHandler,
+  createDefaultObjectReferenceActions,
+  createMapsReferenceActions,
+  type ObjectReferenceDescriptor,
+  type ObjectReferenceOpenHrefHandler,
+} from '@contractspec/lib.design-system';
+
+const customerContact: ObjectReferenceDescriptor = {
+  id: 'user.amina',
+  kind: 'user',
+  label: 'Amina Laurent',
+  description: 'Customer success owner',
+  href: '/customers/acme/users/amina',
+  properties: [
+    {
+      id: 'user.amina.email',
+      kind: 'email',
+      label: 'Email',
+      value: 'amina@example.com',
+    },
+    {
+      id: 'user.amina.phone',
+      kind: 'phone',
+      label: 'Phone',
+      value: '+33 1 23 45 67 89',
+    },
+  ],
+  sections: [
+    {
+      id: 'customer-site',
+      title: 'Primary site',
+      properties: [
+        {
+          id: 'customer-site.address',
+          kind: 'address',
+          label: 'Paris office',
+          value: '10 rue de Rivoli, 75001 Paris',
+          actions: createMapsReferenceActions({
+            id: 'customer-site.address',
+            kind: 'address',
+            label: 'Paris office',
+            value: '10 rue de Rivoli, 75001 Paris',
+          }),
+        },
+      ],
+    },
+  ],
+};
+
+const openHref: ObjectReferenceOpenHrefHandler = (href, _event, options) => {
+  if (options.target === 'new-page') {
+    window.open(href, '_blank', 'noopener,noreferrer');
+    return;
+  }
+
+  window.location.assign(href);
+};
+
+<ObjectReferenceHandler
+  reference={customerContact}
+  actions={createDefaultObjectReferenceActions(customerContact)}
+  interactivityVisibility="icon"
+  openTarget="same-page"
+  panelMode="responsive"
+  mobilePanelMode="drawer"
+  desktopPanelMode="sheet"
+  responsiveBreakpoint="md"
+  openHref={openHref}
+/>;`,g=`import { AdaptivePanel } from '@contractspec/lib.design-system/components/overlays';
+
+<AdaptivePanel
+  open={open}
+  onOpenChange={setOpen}
+  trigger={<button type="button">Edit</button>}
+  title="Edit customer"
+  description="Update contact and site details."
+  mode="responsive"
+  mobileMode="drawer"
+  desktopMode="sheet"
+  breakpoint="md"
+  sheetSide="right"
+  drawerDirection="bottom"
+>
+  {content}
+</AdaptivePanel>;`,b=`Find every user-facing address, phone number, email, user, customer, file, URL, and tenant-specific object reference currently rendered as inert text.
+
+Replace each one with ObjectReferenceHandler from @contractspec/lib.design-system. Keep descriptors data-only: id, kind, label, value, href, openTarget, properties, sections, metadata, iconKey, and ariaLabel are allowed; React callbacks belong in handler props only.
+
+Use properties and sections for rich references. For example, a user reference can expose email, phone, address, files, and customer links in one panel instead of rendering separate disconnected strings.
+
+Use panelMode="responsive" by default. Let desktop render a sheet and small screens render a bottom drawer through AdaptivePanel. Do not call Sheet or Drawer directly for this interaction unless a lower-level primitive is being implemented.
+
+Use openTarget="same-page" unless product requirements explicitly require a new page. Put custom copy, navigation, analytics, permissions, or tenant-specific actions in copyHandler, openHref, actionHandlers, onAction, and onActionError.
+
+For addresses, use createMapsReferenceActions so users can choose Google Maps, Apple Maps, or Waze. For email and phone references, prefer createDefaultObjectReferenceActions unless a product-specific action set is required.
+
+After replacing references, verify keyboard access, visible affordance choice (none, underline, or icon), safe href behavior, mobile drawer layout, and desktop sheet layout.`;function k(){return t("div",{className:"space-y-8",children:[t("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"@contractspec/lib.design-system"}),t("p",{className:"text-muted-foreground",children:["High-level design system components, patterns, and layouts for LSSM applications. Built on top of ",e("code",{children:"@contractspec/lib.ui-kit"}),"."]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Installation"}),e(d,{package:"@contractspec/lib.design-system"})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"What It Provides"}),t("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:[e("strong",{children:"Composite Components"}),": Molecules and Organisms that solve common UI problems"]}),t("li",{children:[e("strong",{children:"Layouts"}),": Ready-to-use page structures for dashboards, marketing sites, and lists"]}),t("li",{children:[e("strong",{children:"Data Views"}),": Standardized renderers for lists, tables, and detail views"]}),t("li",{children:[e("strong",{children:"Forms"}),": Zod-integrated form layouts and components"]}),t("li",{children:[e("strong",{children:"Code Display"}),": Syntax-highlighted code blocks with package manager tabs"]}),t("li",{children:[e("strong",{children:"Platform Utilities"}),": Hooks for responsive and adaptive design"]}),t("li",{children:[e("strong",{children:"Object References"}),": Clickable references for addresses, phone numbers, users, customers, files, URLs, and custom objects"]}),t("li",{children:[e("strong",{children:"Adaptive Panels"}),": One panel API that resolves to a desktop sheet or mobile drawer"]}),t("li",{children:[e("strong",{children:"Theme Bridge"}),": ThemeSpec to Tailwind variables, presets, CSS text, and runtime light/dark mode"]}),t("li",{children:[e("strong",{children:"Legal Templates"}),": Compliant templates for Terms, Privacy, and GDPR"]})]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"ThemeSpec to Tailwind"}),t("p",{className:"text-muted-foreground",children:["The theme bridge keeps ",e("code",{children:"ThemeSpec"})," as the source of truth and exposes no-generation Tailwind helpers, optional CSS text serialization, runtime CSS variables, light/dark modes, and OKLCH color pass-through."]}),e(r,{language:"tsx",code:u})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Focused import surfaces"}),e("p",{className:"text-muted-foreground",children:"New code can use focused subpaths for theme, controls, forms, and layout while existing root imports remain compatible."}),e(r,{language:"tsx",code:h})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Actionable object references"}),t("p",{className:"text-muted-foreground",children:["Use ",e("code",{children:"ObjectReferenceHandler"})," whenever a product surface renders an object that may need quick interaction: addresses, phone numbers, emails, users, customers, files, URLs, and tenant-specific objects. The goal is to avoid inert references while keeping the descriptor contract declarative enough for OSS consumers and future contract-generated surfaces."]}),t("div",{className:"grid gap-4 md:grid-cols-2",children:[t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Descriptor model"}),t("ul",{className:"list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:["References use data-only descriptors: ",e("code",{children:"id"}),","," ",e("code",{children:"kind"}),", ",e("code",{children:"label"}),", ",e("code",{children:"value"}),","," ",e("code",{children:"href"}),", ",e("code",{children:"openTarget"}),","," ",e("code",{children:"metadata"}),", ",e("code",{children:"iconKey"}),", and"," ",e("code",{children:"ariaLabel"}),"."]}),t("li",{children:["Rich references use nested ",e("code",{children:"properties"})," and"," ",e("code",{children:"sections"}),", so one user or customer can expose email, phone, address, files, and links inside the same panel."]}),t("li",{children:["Reference kinds are ",e("code",{children:"address"}),", ",e("code",{children:"email"}),","," ",e("code",{children:"phone"}),", ",e("code",{children:"user"}),", ",e("code",{children:"customer"}),","," ",e("code",{children:"file"}),", ",e("code",{children:"url"}),", and ",e("code",{children:"custom"}),"."]})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Runtime behavior"}),t("ul",{className:"list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:["Choose visibility with ",e("code",{children:"interactivityVisibility"}),":",e("code",{children:"none"}),", ",e("code",{children:"underline"}),", or ",e("code",{children:"icon"}),"."]}),t("li",{children:["Detail navigation defaults to ",e("code",{children:"same-page"}),"; set"," ",e("code",{children:'openTarget="new-page"'})," on the handler, reference, or action when a new page is required."]}),t("li",{children:["Host apps provide behavior through ",e("code",{children:"copyHandler"}),","," ",e("code",{children:"openHref"}),", ",e("code",{children:"actionHandlers"}),","," ",e("code",{children:"onAction"}),", and ",e("code",{children:"onActionError"}),"."]})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Default actions"}),t("ul",{className:"list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:[e("code",{children:"createDefaultObjectReferenceActions"})," adds copy, open, email, phone, and map actions when the descriptor supports them."]}),t("li",{children:[e("code",{children:"createMapsReferenceActions"})," creates Google Maps, Apple Maps, Waze, or geo actions for address references."]}),e("li",{children:"Safe href handling allows expected app, web, email, phone, and map URLs while rejecting unsafe schemes."})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Extension points"}),t("ul",{className:"list-inside list-disc space-y-1 text-muted-foreground text-sm",children:[t("li",{children:["Use ",e("code",{children:"renderTrigger"}),", ",e("code",{children:"renderDetail"}),","," ",e("code",{children:"renderAction"}),", ",e("code",{children:"renderProperty"}),","," ",e("code",{children:"renderSection"}),", and ",e("code",{children:"iconRenderer"})," to wrap or overload presentation."]}),e("li",{children:"Keep tenant-specific permissions, analytics, and integration side effects at the host boundary through runtime handlers."})]})]})]}),e(r,{language:"tsx",code:f})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Adaptive panels"}),t("p",{className:"text-muted-foreground",children:[e("code",{children:"AdaptivePanel"})," is the shared overlay decision for surfaces that should feel native on both desktop and small screens. Its default responsive mode renders a sheet at the configured desktop breakpoint and a drawer below it. ",e("code",{children:"ObjectReferenceHandler"})," uses this panel contract through ",e("code",{children:"panelMode"}),","," ",e("code",{children:"mobilePanelMode"}),", ",e("code",{children:"desktopPanelMode"}),", and"," ",e("code",{children:"responsiveBreakpoint"}),"."]}),e(r,{language:"tsx",code:g})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Prompt for adoption work"}),e("p",{className:"text-muted-foreground",children:"Use this prompt when asking an agent or downstream OSS consumer to replace inert references across an application."}),e(r,{language:"text",code:b})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Data table example"}),t("p",{className:"text-muted-foreground",children:["This is the composed lane from the canonical"," ",e(i,{href:"/docs/examples/data-grid-showcase",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Data Grid Showcase"}),". The design-system wrapper owns title, description, header actions, and the opinionated card shell on top of the raw web primitive."]}),e(r,{language:"tsx",code:p})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Key Exports"}),t("div",{className:"grid gap-4 md:grid-cols-2",children:[t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Organisms"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"AppShell, PageOutline"}),e("li",{children:"AppLayout, AppHeader, AppSidebar"}),e("li",{children:"MarketingLayout, HeroSection"}),e("li",{children:"ListCardPage, ListTablePage"})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Data & Forms"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"DataTable"}),e("li",{children:"DataViewTable"}),e("li",{children:"DataViewRenderer"}),e("li",{children:"ZodForm"}),e("li",{children:"FormLayout, FormDialog"})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Code Display"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"CodeBlock (syntax highlighting)"}),e("li",{children:"CommandTabs (package manager tabs)"}),e("li",{children:"InstallCommand (convenience wrapper)"}),e("li",{children:"CopyButton"})]})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"Providers"}),e("ul",{className:"space-y-1 text-muted-foreground text-sm",children:e("li",{children:"PackageManagerProvider"})})]}),t("div",{className:"card-subtle p-4",children:[e("h3",{className:"mb-2 font-semibold",children:"References & Overlays"}),t("ul",{className:"space-y-1 text-muted-foreground text-sm",children:[e("li",{children:"ObjectReferenceHandler"}),e("li",{children:"createDefaultObjectReferenceActions"}),e("li",{children:"createMapsReferenceActions"}),e("li",{children:"AdaptivePanel"})]})]})]})]}),t("div",{className:"card-subtle space-y-3 p-6",children:[e("h2",{className:"font-bold text-2xl",children:"Where this layer fits"}),t("p",{className:"text-muted-foreground",children:["Read"," ",e(i,{href:"/docs/libraries/application-shell",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Application shell"})," ","for the shared sidebar, topbar, command search, mobile navigation, and"," ",e("code",{children:"PageOutline"})," pattern. Read"," ",e(i,{href:"/docs/libraries/cross-platform-ui",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Cross-platform UI"})," ","for the package split between shared runtime controllers, leaf platform primitives, and this composed design-system layer."]})]}),t("div",{className:"flex items-center gap-4 pt-4",children:[e(i,{href:"/docs/libraries/ui-kit-web",className:"btn-ghost",children:"Previous: UI Kit Web"}),t(i,{href:"/docs/libraries/accessibility",className:"btn-primary",children:["Next: Accessibility ",e(m,{size:16})]})]})]})}export{k as LibrariesDesignSystemPage};