@contractspec/bundle.library 3.9.8 → 3.9.9

package/src/components/docs/libraries/LibrariesDataViewsPage.tsx

@@ -1,37 +1,170 @@
 import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import { HStack, VStack } from '@contractspec/lib.design-system/layout';
+import { List, ListItem } from '@contractspec/lib.design-system/list';
+import {
+	Code,
+	H1,
+	H2,
+	H3,
+	P,
+	Text,
+} from '@contractspec/lib.design-system/typography';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const COLLECTION_DATAVIEW_EXAMPLE = `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,
+        },
+      },
+    },
+  },
+});`;
+
+const PERSONALIZED_RENDERER_EXAMPLE = `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,
+    });
+  }}
+/>;
+`;
+
+const DATAVIEW_AGENT_PROMPT = `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.`;
+
 export function LibrariesDataViewsPage() {
 	return (
-		<div className="space-y-8">
-			<div className="space-y-4">
-				<h1 className="font-bold text-4xl">DataViews Runtime Library</h1>
-				<p className="text-lg text-muted-foreground">
-					The <code>@contractspec/lib.contracts-spec/data-views</code> and{' '}
-					<code>@contractspec/lib.design-system</code> libraries provide the
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<H1 className="font-bold text-4xl">DataViews Runtime Library</H1>
+				<P className="text-lg text-muted-foreground">
+					The <Code>@contractspec/lib.contracts-spec/data-views</Code> and{' '}
+					<Code>@contractspec/lib.design-system</Code> libraries provide the
 					runtime logic and UI components to render DataViews in your
 					application.
-				</p>
-			</div>
+				</P>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Installation</h2>
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Installation</H2>
 				<InstallCommand
 					package={[
 						'@contractspec/lib.contracts-spec',
 						'@contractspec/lib.design-system',
 					]}
 				/>
-			</div>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">DataViewRenderer</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">DataViewRenderer</H2>
+				<P className="text-muted-foreground">
 					The primary component for rendering any DataView. It automatically
 					selects the correct layout (List, Table, Grid, Detail) based on the
 					spec.
-				</p>
+				</P>
 
 				<CodeBlock
 					language="tsx"
@@ -50,51 +183,121 @@ export function UserPage() {
 }`}
 				/>
 
-				<h3 className="font-semibold text-xl">Props</h3>
-				<ul className="list-disc space-y-2 pl-6 text-muted-foreground">
-					<li>
-						<code>spec</code>: The DataViewSpec definition.
-					</li>
-					<li>
-						<code>items</code>: Array of data items to render.
-					</li>
-					<li>
-						<code>filters</code>: Current filter state object.
-					</li>
-					<li>
-						<code>onFilterChange</code>: Callback when typed filters change.
-						Renderers emit <code>DataViewFilterValue</code> objects for numeric,
-						percent, currency, temporal, duration, and boolean filters.
-					</li>
-					<li>
-						<code>pagination</code>: Object with <code>page</code>,{' '}
-						<code>pageSize</code>, <code>total</code>.
-					</li>
-					<li>
-						<code>onPageChange</code>: Callback when page changes.
-					</li>
-					<li>
-						<code>viewMode</code> / <code>defaultViewMode</code>: Controlled
-						or initial collection mode for specs that allow <code>list</code>,{' '}
-						<code>grid</code>, or <code>table</code> projections through{' '}
-						<code>view.collection.viewModes</code>.
-					</li>
-					<li>
-						<code>density</code> / <code>defaultDensity</code>: Controlled or
-						initial density for collection renderers, seeded by{' '}
-						<code>view.collection.density</code> and table{' '}
-						<code>view.density</code>.
-					</li>
-				</ul>
-			</div>
-
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Query Generation</h2>
-				<p className="text-muted-foreground">
-					The <code>DataViewQueryGenerator</code> utility helps translate
+				<H3 className="font-semibold text-xl">Props</H3>
+				<List className="list-disc space-y-2 pl-6 text-muted-foreground">
+					<ListItem>
+						<Text>
+							<Code>spec</Code>: The DataViewSpec definition.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>items</Code>: Array of data items to render.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>filters</Code>: Current filter state object.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>onFilterChange</Code>: Callback when typed filters change.
+							Renderers emit <Code>DataViewFilterValue</Code> objects for
+							numeric, percent, currency, temporal, duration, and boolean
+							filters.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>pagination</Code>: Object with <Code>page</Code>,{' '}
+							<Code>pageSize</Code>, <Code>total</Code>.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>onPageChange</Code>: Callback when page changes.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>viewMode</Code> / <Code>defaultViewMode</Code>: Controlled
+							or initial collection mode for specs that allow <Code>list</Code>,{' '}
+							<Code>grid</Code>, or <Code>table</Code> projections through{' '}
+							<Code>view.collection.viewModes</Code>.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>density</Code> / <Code>defaultDensity</Code>: Controlled or
+							initial density for collection renderers. Host apps can seed this
+							from <Code>@contractspec/lib.personalization</Code> while specs
+							can declare <Code>view.collection.density</Code> and table{' '}
+							<Code>view.density</Code> defaults.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Code>dataDepth</Code> / <Code>defaultDataDepth</Code>: Controlled
+							or initial summary/standard/detailed/exhaustive projection. Fields
+							can declare <Code>visibility.minDataDepth</Code>, and collection
+							specs can opt into <Code>view.collection.personalization</Code>{' '}
+							persistence hints.
+						</Text>
+					</ListItem>
+				</List>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">
+					Collection Defaults And Data Depth
+				</H2>
+				<P className="text-muted-foreground">
+					Use one authored <Code>DataViewSpec</Code> for list, grid, and table
+					experiences. <Code>view.collection</Code> declares allowed modes,
+					toolbar controls, pagination defaults, density, data depth, and
+					persistence hints. <Code>visibility.minDataDepth</Code> lets a field
+					appear only when the renderer is in a detailed or exhaustive mode.
+				</P>
+				<CodeBlock language="typescript" code={COLLECTION_DATAVIEW_EXAMPLE} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Personalization Bridge</H2>
+				<P className="text-muted-foreground">
+					Resolve user preferences in the host app, then pass ordinary renderer
+					props into <Code>DataViewRenderer</Code>. The bridge helper lives in{' '}
+					<Code>@contractspec/lib.personalization</Code>, so the design-system
+					renderer stays portable for apps that do not use personalization. See
+					the{' '}
+					<Link
+						href="/docs/libraries/personalization"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						<Text>personalization library guide</Text>
+					</Link>{' '}
+					for the behavior tracker, analyzer, and DataView preference resolver.
+				</P>
+				<CodeBlock language="tsx" code={PERSONALIZED_RENDERER_EXAMPLE} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Agent Prompt</H2>
+				<P className="text-muted-foreground">
+					Use this prompt when asking an implementation agent to add a
+					preference-aware collection DataView without breaking package
+					boundaries.
+				</P>
+				<CodeBlock language="markdown" code={DATAVIEW_AGENT_PROMPT} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Query Generation</H2>
+				<P className="text-muted-foreground">
+					The <Code>DataViewQueryGenerator</Code> utility helps translate
 					DataView parameters (filters, sorting, pagination) into query
 					arguments for your backend.
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					code={`import { DataViewQueryGenerator } from '@contractspec/lib.contracts-spec/data-views/query-generator';
@@ -114,16 +317,16 @@ const query = generator.generate(params);
 
 // query.input contains skip/take plus the typed filter payloads.`}
 				/>
-			</div>
+			</VStack>
 
-			<div className="flex items-center gap-4 pt-4">
+			<HStack className="items-center gap-4 pt-4">
 				<Link href="/docs/libraries" className="btn-ghost">
-					Back to Libraries
+					<Text>Back to Libraries</Text>
 				</Link>
 				<Link href="/docs/libraries/data-backend" className="btn-primary">
-					Next: Data & Backend <ChevronRight size={16} />
+					<Text>Next: Data & Backend</Text> <ChevronRight size={16} />
 				</Link>
-			</div>
-		</div>
+			</HStack>
+		</VStack>
 	);
 }

package/src/components/docs/libraries/LibrariesDesignSystemPage.tsx

@@ -88,10 +88,115 @@ const FOCUSED_SUBPATHS_EXAMPLE = `import { themeSpecToTailwindPreset } from '@co
 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';`;
 
+const OBJECT_REFERENCE_EXAMPLE = `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}
+/>;`;
+
+const ADAPTIVE_PANEL_EXAMPLE = `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>;`;
+
+const OBJECT_REFERENCE_PROMPT = `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.`;
+
 export function LibrariesDesignSystemPage() {
 	return (
 		<div className="space-y-8">
@@ -134,6 +239,15 @@ export function LibrariesDesignSystemPage() {
 						<strong>Platform Utilities</strong>: Hooks for responsive and
 						adaptive design
 					</li>
+					<li>
+						<strong>Object References</strong>: Clickable references for
+						addresses, phone numbers, users, customers, files, URLs, and custom
+						objects
+					</li>
+					<li>
+						<strong>Adaptive Panels</strong>: One panel API that resolves to a
+						desktop sheet or mobile drawer
+					</li>
 					<li>
 						<strong>Theme Bridge</strong>: ThemeSpec to Tailwind variables,
 						presets, CSS text, and runtime light/dark mode
@@ -165,6 +279,118 @@ export function LibrariesDesignSystemPage() {
 				<CodeBlock language="tsx" code={FOCUSED_SUBPATHS_EXAMPLE} />
 			</div>
 
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Actionable object references</h2>
+				<p className="text-muted-foreground">
+					Use <code>ObjectReferenceHandler</code> 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.
+				</p>
+				<div className="grid gap-4 md:grid-cols-2">
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Descriptor model</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								References use data-only descriptors: <code>id</code>,{' '}
+								<code>kind</code>, <code>label</code>, <code>value</code>,{' '}
+								<code>href</code>, <code>openTarget</code>,{' '}
+								<code>metadata</code>, <code>iconKey</code>, and{' '}
+								<code>ariaLabel</code>.
+							</li>
+							<li>
+								Rich references use nested <code>properties</code> and{' '}
+								<code>sections</code>, so one user or customer can expose email,
+								phone, address, files, and links inside the same panel.
+							</li>
+							<li>
+								Reference kinds are <code>address</code>, <code>email</code>,{' '}
+								<code>phone</code>, <code>user</code>, <code>customer</code>,{' '}
+								<code>file</code>, <code>url</code>, and <code>custom</code>.
+							</li>
+						</ul>
+					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Runtime behavior</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								Choose visibility with <code>interactivityVisibility</code>:
+								<code>none</code>, <code>underline</code>, or <code>icon</code>.
+							</li>
+							<li>
+								Detail navigation defaults to <code>same-page</code>; set{' '}
+								<code>openTarget="new-page"</code> on the handler, reference, or
+								action when a new page is required.
+							</li>
+							<li>
+								Host apps provide behavior through <code>copyHandler</code>,{' '}
+								<code>openHref</code>, <code>actionHandlers</code>,{' '}
+								<code>onAction</code>, and <code>onActionError</code>.
+							</li>
+						</ul>
+					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Default actions</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								<code>createDefaultObjectReferenceActions</code> adds copy,
+								open, email, phone, and map actions when the descriptor supports
+								them.
+							</li>
+							<li>
+								<code>createMapsReferenceActions</code> creates Google Maps,
+								Apple Maps, Waze, or geo actions for address references.
+							</li>
+							<li>
+								Safe href handling allows expected app, web, email, phone, and
+								map URLs while rejecting unsafe schemes.
+							</li>
+						</ul>
+					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">Extension points</h3>
+						<ul className="list-inside list-disc space-y-1 text-muted-foreground text-sm">
+							<li>
+								Use <code>renderTrigger</code>, <code>renderDetail</code>,{' '}
+								<code>renderAction</code>, <code>renderProperty</code>,{' '}
+								<code>renderSection</code>, and <code>iconRenderer</code> to
+								wrap or overload presentation.
+							</li>
+							<li>
+								Keep tenant-specific permissions, analytics, and integration
+								side effects at the host boundary through runtime handlers.
+							</li>
+						</ul>
+					</div>
+				</div>
+				<CodeBlock language="tsx" code={OBJECT_REFERENCE_EXAMPLE} />
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Adaptive panels</h2>
+				<p className="text-muted-foreground">
+					<code>AdaptivePanel</code> 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. <code>ObjectReferenceHandler</code> uses this
+					panel contract through <code>panelMode</code>,{' '}
+					<code>mobilePanelMode</code>, <code>desktopPanelMode</code>, and{' '}
+					<code>responsiveBreakpoint</code>.
+				</p>
+				<CodeBlock language="tsx" code={ADAPTIVE_PANEL_EXAMPLE} />
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Prompt for adoption work</h2>
+				<p className="text-muted-foreground">
+					Use this prompt when asking an agent or downstream OSS consumer to
+					replace inert references across an application.
+				</p>
+				<CodeBlock language="text" code={OBJECT_REFERENCE_PROMPT} />
+			</div>
+
 			<div className="space-y-4">
 				<h2 className="font-bold text-2xl">Data table example</h2>
 				<p className="text-muted-foreground">
@@ -218,6 +444,15 @@ export function LibrariesDesignSystemPage() {
 							<li>PackageManagerProvider</li>
 						</ul>
 					</div>
+					<div className="card-subtle p-4">
+						<h3 className="mb-2 font-semibold">References & Overlays</h3>
+						<ul className="space-y-1 text-muted-foreground text-sm">
+							<li>ObjectReferenceHandler</li>
+							<li>createDefaultObjectReferenceActions</li>
+							<li>createMapsReferenceActions</li>
+							<li>AdaptivePanel</li>
+						</ul>
+					</div>
 				</div>
 			</div>
 

package/src/components/docs/libraries/LibrariesOverviewPage.tsx

@@ -30,6 +30,12 @@ const libraryGroups = [
 					'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:
@@ -45,13 +51,13 @@ const libraryGroups = [
 			{
 				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.',
+					'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, mobile navigation, and PageOutline patterns for product apps.',
+					'Adopt the shared sidebar, topbar, command search, notifications, mobile navigation, and PageOutline patterns for product apps.',
 				href: '/docs/libraries/application-shell',
 			},
 			{