@contractspec/bundle.library 3.9.8 → 3.9.9

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

@@ -1,4 +1,121 @@
-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() {
@@ -10,7 +127,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 = {
@@ -25,4 +142,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/node/components/docs/libraries/LibrariesDesignSystemPage.js

@@ -1,4 +1,4 @@
-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';
@@ -80,6 +80,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};

package/dist/node/components/docs/libraries/LibrariesOverviewPage.js

@@ -1 +1 @@
-var s=Object.defineProperty;var o=(e)=>e;function c(e,t){this[e]=o.bind(null,t)}var p=(e,t)=>{for(var r in t)s(e,r,{get:t[r],enumerable:!0,configurable:!0,set:c.bind(t,r)})};var m=(e,t)=>()=>(e&&(t=e(e=0)),t);import n from"@contractspec/lib.ui-link";import{ChevronRight as l}from"lucide-react";import{jsx as i,jsxs as a}from"react/jsx-runtime";var d=[{title:"Contract and schema foundation",body:"Use these packages to define explicit contracts, schemas, and generated artifacts without inventing a new platform-specific language.",items:[{title:"@contractspec/lib.contracts-spec",description:"Define operations, events, policies, and generated surfaces in TypeScript.",href:"/docs/libraries/contracts"},{title:"@contractspec/lib.schema",description:"Share type-safe schema definitions across validation, clients, and runtime adapters.",href:"/docs/libraries/schema"}]},{title:"Runtime and surface libraries",body:"These packages execute the contract model across UI, data, observability, workflows, and generated runtime behavior.",items:[{title:"@contractspec/lib.runtime",description:"Run typed capability surfaces, execute policies, and connect runtime adapters.",href:"/docs/libraries/runtime"},{title:"@contractspec/lib.ui-kit",description:"Render shared surfaces across web and React Native without forking the contract layer.",href:"/docs/libraries/ui-kit"},{title:"@contractspec/lib.ui-kit-web",description:"Use the raw web primitive layer directly when you want the browser table, accessibility, and interaction model without the design-system shell.",href:"/docs/libraries/ui-kit-web"},{title:"@contractspec/lib.design-system",description:"Build higher-level product surfaces and documented marketing/docs primitives on top of the web and native UI packages.",href:"/docs/libraries/design-system"},{title:"Application shell",description:"Adopt the shared sidebar, topbar, command search, mobile navigation, and PageOutline patterns for product apps.",href:"/docs/libraries/application-shell"},{title:"Cross-platform UI",description:"See how the presentation runtimes, ui-kit-web, ui-kit, and design-system stay compatible across React and React Native.",href:"/docs/libraries/cross-platform-ui"},{title:"@contractspec/lib.data-views",description:"Generate and render list/detail style surfaces that stay aligned with data contracts.",href:"/docs/libraries/data-views"}]},{title:"Operator and system packages",body:"These packages matter once the system is live and you need governance, resilience, and observability.",items:[{title:"@contractspec/lib.observability",description:"Trace, log, and measure contract execution using the same system boundaries.",href:"/docs/libraries/observability"},{title:"@contractspec/lib.resilience",description:"Add circuit breakers, retries, and failure controls without hiding the integration model.",href:"/docs/libraries/resilience"},{title:"@contractspec/lib.multi-tenancy",description:"Keep tenant-specific config, policy, and surface resolution explicit.",href:"/docs/libraries/multi-tenancy"},{title:"@contractspec/lib.workflow-composer",description:"Compose and extend workflows without smearing orchestration concerns across apps.",href:"/docs/libraries/workflow-composer"}]}];function f(){return a("div",{className:"space-y-10",children:[a("div",{className:"space-y-3",children:[i("p",{className:"editorial-kicker",children:"Build"}),i("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"The OSS foundation is a library system, not a closed platform."}),i("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"ContractSpec is assembled from libraries that remain useful on their own and stronger together. Start with the contract and schema foundation, then add runtime, UI, integration, and operator packages as your system grows."})]}),a("div",{className:"editorial-proof-strip",children:[a("div",{className:"editorial-stat",children:[i("span",{className:"editorial-label",children:"Layering rule"}),i("span",{className:"editorial-stat-value",children:"libs → bundles → apps"})]}),i("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Keep reusable behavior in libraries, compose it into bundle-level surfaces, and reserve app packages for concrete delivery shells."})]}),i("div",{className:"space-y-6",children:d.map((e)=>a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[i("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:e.title}),i("p",{className:"text-muted-foreground text-sm leading-7",children:e.body})]}),i("div",{className:"grid gap-4 md:grid-cols-2",children:e.items.map((t)=>a(n,{href:t.href,className:"rounded-[24px] border border-border/75 bg-background/70 p-5 transition-colors hover:border-[color:rgb(162_79_42_/_0.45)]",children:[i("h3",{className:"font-semibold text-lg",children:t.title}),i("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.description}),a("div",{className:"mt-3 flex items-center gap-2 text-[color:var(--rust)] text-sm",children:["Learn more ",i(l,{size:14})]})]},t.title))})]},e.title))})]})}export{f as LibrariesOverviewPage};
+var s=Object.defineProperty;var o=(e)=>e;function n(e,t){this[e]=o.bind(null,t)}var p=(e,t)=>{for(var r in t)s(e,r,{get:t[r],enumerable:!0,configurable:!0,set:n.bind(t,r)})};var m=(e,t)=>()=>(e&&(t=e(e=0)),t);import c from"@contractspec/lib.ui-link";import{ChevronRight as l}from"lucide-react";import{jsx as i,jsxs as a}from"react/jsx-runtime";var d=[{title:"Contract and schema foundation",body:"Use these packages to define explicit contracts, schemas, and generated artifacts without inventing a new platform-specific language.",items:[{title:"@contractspec/lib.contracts-spec",description:"Define operations, events, policies, and generated surfaces in TypeScript.",href:"/docs/libraries/contracts"},{title:"@contractspec/lib.schema",description:"Share type-safe schema definitions across validation, clients, and runtime adapters.",href:"/docs/libraries/schema"}]},{title:"Runtime and surface libraries",body:"These packages execute the contract model across UI, data, observability, workflows, and generated runtime behavior.",items:[{title:"@contractspec/lib.runtime",description:"Run typed capability surfaces, execute policies, and connect runtime adapters.",href:"/docs/libraries/runtime"},{title:"@contractspec/lib.translation-runtime",description:"Resolve ContractSpec TranslationSpec catalogs with ICU formatting, SSR snapshots, BCP 47 locales, overrides, and optional i18next projection.",href:"/docs/libraries/translation-runtime"},{title:"@contractspec/lib.ui-kit",description:"Render shared surfaces across web and React Native without forking the contract layer.",href:"/docs/libraries/ui-kit"},{title:"@contractspec/lib.ui-kit-web",description:"Use the raw web primitive layer directly when you want the browser table, accessibility, and interaction model without the design-system shell.",href:"/docs/libraries/ui-kit-web"},{title:"@contractspec/lib.design-system",description:"Build higher-level product surfaces, actionable object references, adaptive panels, and documented marketing/docs primitives on top of the web and native UI packages.",href:"/docs/libraries/design-system"},{title:"Application shell",description:"Adopt the shared sidebar, topbar, command search, notifications, mobile navigation, and PageOutline patterns for product apps.",href:"/docs/libraries/application-shell"},{title:"Cross-platform UI",description:"See how the presentation runtimes, ui-kit-web, ui-kit, and design-system stay compatible across React and React Native.",href:"/docs/libraries/cross-platform-ui"},{title:"@contractspec/lib.data-views",description:"Generate and render list/detail style surfaces that stay aligned with data contracts.",href:"/docs/libraries/data-views"}]},{title:"Operator and system packages",body:"These packages matter once the system is live and you need governance, resilience, and observability.",items:[{title:"@contractspec/lib.observability",description:"Trace, log, and measure contract execution using the same system boundaries.",href:"/docs/libraries/observability"},{title:"@contractspec/lib.resilience",description:"Add circuit breakers, retries, and failure controls without hiding the integration model.",href:"/docs/libraries/resilience"},{title:"@contractspec/lib.multi-tenancy",description:"Keep tenant-specific config, policy, and surface resolution explicit.",href:"/docs/libraries/multi-tenancy"},{title:"@contractspec/lib.workflow-composer",description:"Compose and extend workflows without smearing orchestration concerns across apps.",href:"/docs/libraries/workflow-composer"}]}];function f(){return a("div",{className:"space-y-10",children:[a("div",{className:"space-y-3",children:[i("p",{className:"editorial-kicker",children:"Build"}),i("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"The OSS foundation is a library system, not a closed platform."}),i("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"ContractSpec is assembled from libraries that remain useful on their own and stronger together. Start with the contract and schema foundation, then add runtime, UI, integration, and operator packages as your system grows."})]}),a("div",{className:"editorial-proof-strip",children:[a("div",{className:"editorial-stat",children:[i("span",{className:"editorial-label",children:"Layering rule"}),i("span",{className:"editorial-stat-value",children:"libs → bundles → apps"})]}),i("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Keep reusable behavior in libraries, compose it into bundle-level surfaces, and reserve app packages for concrete delivery shells."})]}),i("div",{className:"space-y-6",children:d.map((e)=>a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[i("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:e.title}),i("p",{className:"text-muted-foreground text-sm leading-7",children:e.body})]}),i("div",{className:"grid gap-4 md:grid-cols-2",children:e.items.map((t)=>a(c,{href:t.href,className:"rounded-[24px] border border-border/75 bg-background/70 p-5 transition-colors hover:border-[color:rgb(162_79_42_/_0.45)]",children:[i("h3",{className:"font-semibold text-lg",children:t.title}),i("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.description}),a("div",{className:"mt-3 flex items-center gap-2 text-[color:var(--rust)] text-sm",children:["Learn more ",i(l,{size:14})]})]},t.title))})]},e.title))})]})}export{f as LibrariesOverviewPage};

package/dist/node/components/docs/libraries/LibrariesPersonalizationPage.js

@@ -1,4 +1,52 @@
-var l=Object.defineProperty;var c=(a)=>a;function s(a,t){this[a]=c.bind(null,t)}var m=(a,t)=>{for(var o in t)l(a,o,{get:t[o],enumerable:!0,configurable:!0,set:s.bind(t,o)})};var f=(a,t)=>()=>(a&&(t=a(a=0)),t);import{CodeBlock as i,InstallCommand as d}from"@contractspec/lib.design-system";import n from"@contractspec/lib.ui-link";import{ChevronRight as p}from"lucide-react";import{jsx as e,jsxs as r}from"react/jsx-runtime";function u(){return r("div",{className:"space-y-8",children:[r("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"@contractspec/lib.personalization"}),e("p",{className:"text-lg text-muted-foreground",children:"Track field/feature/workflow usage, analyze drop-offs, and convert insights into OverlaySpecs or workflow tweaks."})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Installation"}),e(d,{package:"@contractspec/lib.personalization"})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Tracker"}),e("p",{className:"text-muted-foreground",children:"Buffer events per tenant/user and emit OpenTelemetry counters automatically."}),e(i,{language:"typescript",code:`import { createBehaviorTracker } from '@contractspec/lib.personalization';
+var u=Object.defineProperty;var v=(e)=>e;function w(e,g){this[e]=v.bind(null,g)}var $=(e,g)=>{for(var o in g)u(e,o,{get:g[o],enumerable:!0,configurable:!0,set:w.bind(g,o)})};var F=(e,g)=>()=>(e&&(g=e(e=0)),g);import{CodeBlock as m,InstallCommand as y}from"@contractspec/lib.design-system";import{HStack as z,VStack as f}from"@contractspec/lib.design-system/layout";import{Code as r,H1 as B,H2 as h,P as l,Text as p}from"@contractspec/lib.design-system/typography";import q from"@contractspec/lib.ui-link";import{ChevronRight as J}from"lucide-react";import{jsx as b,jsxs as d}from"react/jsx-runtime";var Q=`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: savedAccountViewPreference,
+});
+
+return (
+  <DataViewRenderer
+    spec={AccountsDataView}
+    items={accounts}
+    defaultViewMode={resolved.viewMode}
+    defaultDensity={resolved.density}
+    defaultDataDepth={resolved.dataDepth}
+    pagination={{
+      page,
+      pageSize: resolved.pageSize ?? 25,
+      total,
+    }}
+  />
+);`,U=`tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  dataViewVersion: AccountsDataView.meta.version,
+  action: 'view_mode_changed',
+  viewMode: 'grid',
+});
+
+tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  action: 'data_depth_changed',
+  dataDepth: 'detailed',
+});
+
+tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  action: 'filter_changed',
+  filterKey: 'status',
+});`,Y=`Add DataView personalization for <screen>.
+
+Acceptance criteria:
+- Resolve viewMode, density, dataDepth, and pageSize with resolveDataViewPreferences.
+- Apply resolved values to DataViewRenderer as default or controlled props.
+- Track opened, view_mode_changed, density_changed, data_depth_changed, search_changed, filter_changed, sort_changed, and page_changed actions with trackDataViewInteraction.
+- Persist only the dimensions allowed by view.collection.personalization.persist.
+- Ignore behavior-derived modes that are not allowed by view.collection.viewModes.allowedModes.
+- Do not import React or design-system code into @contractspec/lib.personalization helpers.`;function i(){return d(f,{className:"space-y-8",children:[d(f,{className:"space-y-4",children:[b(B,{className:"font-bold text-4xl",children:"@contractspec/lib.personalization"}),b(l,{className:"text-lg text-muted-foreground",children:"Track field/feature/workflow usage, analyze drop-offs, and convert insights into OverlaySpecs or workflow tweaks."})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Installation"}),b(y,{package:"@contractspec/lib.personalization"})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Tracker"}),b(l,{className:"text-muted-foreground",children:"Buffer events per tenant/user and emit OpenTelemetry counters automatically."}),b(m,{language:"typescript",code:`import { createBehaviorTracker } from '@contractspec/lib.personalization';
 
 const tracker = createBehaviorTracker({
   store,
@@ -6,14 +54,20 @@ const tracker = createBehaviorTracker({
 });
 
 tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'items' });
-tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Analyzer"}),e("p",{className:"text-muted-foreground",children:"Summarize events and highlight unused UI, frequent fields, and workflow bottlenecks."}),e(i,{language:"typescript",code:`import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
+tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"DataView Preferences"}),d(l,{className:"text-muted-foreground",children:["Use ",b(r,{children:"resolveDataViewPreferences"})," when a collection DataView should honor a user's preferred list/grid/table mode, compact or comfortable density, data depth, and page size. The helper returns plain values that can be passed into the renderer without coupling the design-system package to personalization. Start from the"," ",b(q,{href:"/docs/libraries/data-views",className:"text-[color:var(--rust)] underline underline-offset-4",children:b(p,{children:"DataViews runtime guide"})})," ","when you need the contract and renderer shape."]}),b(m,{language:"tsx",code:Q})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"DataView Interaction Events"}),d(l,{className:"text-muted-foreground",children:["Track ",b(r,{children:"data_view_interaction"})," events for view mode, density, data depth, search, filters, sorting, and pagination. The in-memory store summarizes those events, and the analyzer can derive a scoped preferred collection mode from valid interaction counts."]}),b(m,{language:"typescript",code:U})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Analyzer"}),b(l,{className:"text-muted-foreground",children:"Summarize events and highlight unused UI, frequent fields, and workflow bottlenecks."}),b(m,{language:"typescript",code:`import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
 
 const analyzer = new BehaviorAnalyzer(store);
 const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'ops-42' });
-// { unusedFields: ['internalNotes'], workflowBottlenecks: [...] }`})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Adapter"}),e("p",{className:"text-muted-foreground",children:"Convert insights into overlays or workflow extension hints."}),e(i,{language:"typescript",code:`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
+// {
+//   unusedFields: ['internalNotes'],
+//   workflowBottlenecks: [...],
+//   dataViewPreferences: {
+//     'crm.accounts': { preferredViewMode: 'grid' }
+//   }
+// }`})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Adapter"}),b(l,{className:"text-muted-foreground",children:"Convert insights into overlays or workflow extension hints."}),b(m,{language:"typescript",code:`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
 
 const overlay = insightsToOverlaySuggestion(insights, {
   overlayId: 'acme-order-form',
   tenantId: 'acme',
   capability: 'billing.createOrder',
-});`})]}),r("div",{className:"flex items-center gap-4 pt-4",children:[e(n,{href:"/docs/libraries",className:"btn-ghost",children:"Back to Libraries"}),r(n,{href:"/docs/libraries/overlay-engine",className:"btn-primary",children:["Next: Overlay Engine ",e(p,{size:16})]})]})]})}export{u as LibrariesPersonalizationPage};
+});`})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Agent Prompt"}),b(l,{className:"text-muted-foreground",children:"Use this when asking an agent to wire DataView preferences while preserving the personalization/design-system boundary."}),b(m,{language:"markdown",code:Y})]}),d(z,{className:"items-center gap-4 pt-4",children:[b(q,{href:"/docs/libraries",className:"btn-ghost",children:b(p,{children:"Back to Libraries"})}),d(q,{href:"/docs/libraries/overlay-engine",className:"btn-primary",children:[b(p,{children:"Next: Overlay Engine"})," ",b(J,{size:16})]})]})]})}export{i as LibrariesPersonalizationPage};

package/dist/node/components/docs/libraries/LibrariesTranslationRuntimePage.content.js

@@ -0,0 +1,42 @@
+var n=Object.defineProperty;var s=(e)=>e;function o(e,t){this[e]=s.bind(null,t)}var r=(e,t)=>{for(var a in t)n(e,a,{get:t[a],enumerable:!0,configurable:!0,set:o.bind(t,a)})};var i=(e,t)=>()=>(e&&(t=e(e=0)),t);var l=["@contractspec/lib.contracts-spec","@contractspec/lib.translation-runtime"],p=`import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';
+import { checkoutMessages } from './translations/checkout.messages';
+
+const runtime = createTranslationRuntime({
+  catalogs: [checkoutMessages],
+  locale: 'fr-FR',
+  fallbackLocales: ['fr', 'en-US'],
+  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),
+});
+
+const label = runtime.t('checkout.pay', {
+  amount: 4200,
+  currency: 'EUR',
+});`,d=`import { createInstance } from 'i18next';
+import {
+  createI18nextInitOptions,
+  exportContractSpecToI18next,
+} from '@contractspec/lib.translation-runtime/i18next';
+
+const exported = exportContractSpecToI18next([checkoutMessages], {
+  locale: 'en-US',
+  assumeIcuFormatter: true,
+});
+const { options, diagnostics } = createI18nextInitOptions(exported, {
+  lng: 'en-US',
+});
+
+const i18next = createInstance();
+await i18next.init(options);
+reportAdapterDiagnostics(diagnostics);`,m=`// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.
+const runtime = createTranslationRuntime({
+  catalogs,
+  locale: negotiatedLocale,
+  fallbackLocales,
+});
+const snapshot = runtime.createSnapshot();
+
+// Client: hydrate from the same snapshot so locale, resources, and fallback state match.
+const hydratedRuntime = createTranslationRuntime({ snapshot });`,u=["Keep TranslationSpec as the source of truth; do not flatten metadata into i18next JSON as the canonical model.","Keep stable bundle identity in TranslationSpec.meta.key and keep BCP 47 language tags in TranslationSpec.locale.","Use ICU messages for plural, select, selectordinal, number, date, currency, list, and relative-time formatting.","Create one runtime per SSR request when tenant, project, or user overrides are involved.","Serialize the same runtime snapshot or exported adapter resources used by the server for hydration.","Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU messages through i18next.","Treat adapter diagnostics as release blockers in production pipelines instead of silently rendering raw keys."],h=`You are integrating ContractSpec translations into a production app.
+Use @contractspec/lib.contracts-spec/translations as the canonical contract layer and @contractspec/lib.translation-runtime as the runtime layer.
+Keep locale variants separate from stable bundle keys, support BCP 47 tags, preserve ICU plural/select/selectordinal messages, and use request-scoped runtime instances for SSR.
+If the app already uses i18next, use @contractspec/lib.translation-runtime/i18next only as a downstream adapter. Do not make i18next the canonical translation model. Include diagnostics, fallback behavior, tenant/user override isolation, and hydration snapshot handling in the implementation and tests.`,g=[{title:"Spec layer",body:"TranslationSpec owns keys, locales, domains, versions, owners, fallback declarations, direction, and validation metadata."},{title:"Runtime layer",body:"Runtime instances negotiate locales, apply fallback chains, resolve overrides, cache compiled messages, report diagnostics, and serialize SSR snapshots."},{title:"Adapter layer",body:"The i18next adapter projects ContractSpec specs or snapshots to resources and manifests for caller-owned i18next instances."}];export{h as translationRuntimePrompt,g as translationRuntimeLayers,l as translationRuntimeInstall,p as translationRuntimeExample,u as translationRuntimeChecks,m as ssrHydrationExample,d as i18nextAdapterExample};

package/dist/node/components/docs/libraries/LibrariesTranslationRuntimePage.js

@@ -0,0 +1,42 @@
+var v=Object.defineProperty;var S=(a)=>a;function R(a,r){this[a]=S.bind(null,r)}var M=(a,r)=>{for(var l in r)v(a,l,{get:r[l],enumerable:!0,configurable:!0,set:R.bind(r,l)})};var O=(a,r)=>()=>(a&&(r=a(a=0)),r);var d=["@contractspec/lib.contracts-spec","@contractspec/lib.translation-runtime"],u=`import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';
+import { checkoutMessages } from './translations/checkout.messages';
+
+const runtime = createTranslationRuntime({
+  catalogs: [checkoutMessages],
+  locale: 'fr-FR',
+  fallbackLocales: ['fr', 'en-US'],
+  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),
+});
+
+const label = runtime.t('checkout.pay', {
+  amount: 4200,
+  currency: 'EUR',
+});`,m=`import { createInstance } from 'i18next';
+import {
+  createI18nextInitOptions,
+  exportContractSpecToI18next,
+} from '@contractspec/lib.translation-runtime/i18next';
+
+const exported = exportContractSpecToI18next([checkoutMessages], {
+  locale: 'en-US',
+  assumeIcuFormatter: true,
+});
+const { options, diagnostics } = createI18nextInitOptions(exported, {
+  lng: 'en-US',
+});
+
+const i18next = createInstance();
+await i18next.init(options);
+reportAdapterDiagnostics(diagnostics);`,h=`// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.
+const runtime = createTranslationRuntime({
+  catalogs,
+  locale: negotiatedLocale,
+  fallbackLocales,
+});
+const snapshot = runtime.createSnapshot();
+
+// Client: hydrate from the same snapshot so locale, resources, and fallback state match.
+const hydratedRuntime = createTranslationRuntime({ snapshot });`,g=["Keep TranslationSpec as the source of truth; do not flatten metadata into i18next JSON as the canonical model.","Keep stable bundle identity in TranslationSpec.meta.key and keep BCP 47 language tags in TranslationSpec.locale.","Use ICU messages for plural, select, selectordinal, number, date, currency, list, and relative-time formatting.","Create one runtime per SSR request when tenant, project, or user overrides are involved.","Serialize the same runtime snapshot or exported adapter resources used by the server for hydration.","Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU messages through i18next.","Treat adapter diagnostics as release blockers in production pipelines instead of silently rendering raw keys."],f=`You are integrating ContractSpec translations into a production app.
+Use @contractspec/lib.contracts-spec/translations as the canonical contract layer and @contractspec/lib.translation-runtime as the runtime layer.
+Keep locale variants separate from stable bundle keys, support BCP 47 tags, preserve ICU plural/select/selectordinal messages, and use request-scoped runtime instances for SSR.
+If the app already uses i18next, use @contractspec/lib.translation-runtime/i18next only as a downstream adapter. Do not make i18next the canonical translation model. Include diagnostics, fallback behavior, tenant/user override isolation, and hydration snapshot handling in the implementation and tests.`,b=[{title:"Spec layer",body:"TranslationSpec owns keys, locales, domains, versions, owners, fallback declarations, direction, and validation metadata."},{title:"Runtime layer",body:"Runtime instances negotiate locales, apply fallback chains, resolve overrides, cache compiled messages, report diagnostics, and serialize SSR snapshots."},{title:"Adapter layer",body:"The i18next adapter projects ContractSpec specs or snapshots to resources and manifests for caller-owned i18next instances."}];import{CodeBlock as s,InstallCommand as U}from"@contractspec/lib.design-system";import{HStack as y,VStack as n}from"@contractspec/lib.design-system/layout";import{List as w,ListItem as C}from"@contractspec/lib.design-system/list";import{Code as p,H1 as z,H2 as c,H3 as D,P as i,Text as o}from"@contractspec/lib.design-system/typography";import I from"@contractspec/lib.ui-link";import{ChevronRight as K}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";function G(){return t(n,{className:"space-y-8",children:[t(n,{className:"space-y-4",children:[e(o,{className:"editorial-kicker",children:"Runtime and adapters"}),e(z,{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Translation runtime and i18next adapter"}),e(i,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"Use ContractSpec as the canonical translation contract layer, then resolve and format messages through a framework-independent runtime. i18next is supported as an optional downstream adapter, not as the source of truth."})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Install the runtime"}),e(U,{package:d}),t(i,{className:"text-muted-foreground",children:[e(o,{children:"Add "}),e(p,{children:"i18next"}),t(o,{children:[" ","only when an app imports the adapter subpath. Core server, React, React Native, CLI, and test code can use the runtime without loading i18next."]})]})]}),e(y,{className:"grid gap-4 md:grid-cols-3",children:b.map((a)=>t(n,{className:"card-subtle space-y-2 p-5",children:[e(D,{className:"font-semibold text-lg",children:a.title}),e(i,{className:"text-muted-foreground text-sm leading-7",children:a.body})]},a.title))}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Use the ContractSpec runtime"}),t(i,{className:"text-muted-foreground",children:[e(o,{children:"The runtime consumes canonical "}),e(p,{children:"TranslationSpec[]"}),t(o,{children:[" ","catalogs, supports BCP 47 tags such as en-US, ar-EG, and zh-Hans, and delegates ICU parsing/formatting to a mature formatter engine instead of a custom parser."]})]}),e(s,{language:"typescript",code:u})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Project to i18next when needed"}),t(i,{className:"text-muted-foreground",children:[e(o,{children:"Import from "}),e(p,{children:"@contractspec/lib.translation-runtime/i18next"}),t(o,{children:[" ","to export resources by locale, namespace, and message key. The namespace defaults to the stable bundle key, dotted message keys stay flat with keySeparator false, and metadata remains in a sidecar manifest."]})]}),e(s,{language:"typescript",code:m})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"SSR, streaming, and hydration"}),e(i,{className:"text-muted-foreground",children:"Negotiate locale on the server, preload catalogs needed for streamed content, and hydrate the client from the same serialized state. Never let client-only language detection choose a different locale after the server has rendered."}),e(s,{language:"typescript",code:h})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Production checklist"}),e(w,{className:"list-disc space-y-2 pl-6 text-muted-foreground",children:g.map((a)=>e(C,{children:a},a))})]}),t(n,{className:"space-y-4 rounded-xl border border-border p-6",children:[e(c,{className:"font-bold text-2xl",children:"Agent implementation prompt"}),e(i,{className:"text-muted-foreground",children:"Use this prompt when asking an agent to wire translations into a web, server, or React Native surface without losing ContractSpec ownership."}),e(s,{language:"markdown",code:f})]}),t(y,{className:"flex flex-wrap items-center gap-4 pt-4",children:[e(I,{href:"/docs/libraries/contracts",className:"btn-ghost",children:e(o,{children:"Translation contracts"})}),t(I,{href:"/docs/libraries/design-system",className:"btn-primary",children:[e(o,{children:"Design-system integration"}),e(K,{size:16})]})]})]})}export{G as LibrariesTranslationRuntimePage};