@contractspec/bundle.library 3.9.7 → 3.9.9

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

@@ -0,0 +1,137 @@
+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';
+import {
+	i18nextAdapterExample,
+	ssrHydrationExample,
+	translationRuntimeChecks,
+	translationRuntimeExample,
+	translationRuntimeInstall,
+	translationRuntimeLayers,
+	translationRuntimePrompt,
+} from './LibrariesTranslationRuntimePage.content';
+
+export function LibrariesTranslationRuntimePage() {
+	return (
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<Text className="editorial-kicker">Runtime and adapters</Text>
+				<H1 className="font-serif text-4xl tracking-[-0.04em] md:text-5xl">
+					Translation runtime and i18next adapter
+				</H1>
+				<P className="max-w-3xl text-lg text-muted-foreground leading-8">
+					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.
+				</P>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Install the runtime</H2>
+				<InstallCommand package={translationRuntimeInstall} />
+				<P className="text-muted-foreground">
+					<Text>Add </Text>
+					<Code>i18next</Code>
+					<Text>
+						{' '}
+						only when an app imports the adapter subpath. Core server, React,
+						React Native, CLI, and test code can use the runtime without loading
+						i18next.
+					</Text>
+				</P>
+			</VStack>
+
+			<HStack className="grid gap-4 md:grid-cols-3">
+				{translationRuntimeLayers.map((item) => (
+					<VStack className="card-subtle space-y-2 p-5" key={item.title}>
+						<H3 className="font-semibold text-lg">{item.title}</H3>
+						<P className="text-muted-foreground text-sm leading-7">
+							{item.body}
+						</P>
+					</VStack>
+				))}
+			</HStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Use the ContractSpec runtime</H2>
+				<P className="text-muted-foreground">
+					<Text>The runtime consumes canonical </Text>
+					<Code>TranslationSpec[]</Code>
+					<Text>
+						{' '}
+						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.
+					</Text>
+				</P>
+				<CodeBlock language="typescript" code={translationRuntimeExample} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Project to i18next when needed</H2>
+				<P className="text-muted-foreground">
+					<Text>Import from </Text>
+					<Code>@contractspec/lib.translation-runtime/i18next</Code>
+					<Text>
+						{' '}
+						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.
+					</Text>
+				</P>
+				<CodeBlock language="typescript" code={i18nextAdapterExample} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">SSR, streaming, and hydration</H2>
+				<P className="text-muted-foreground">
+					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.
+				</P>
+				<CodeBlock language="typescript" code={ssrHydrationExample} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Production checklist</H2>
+				<List className="list-disc space-y-2 pl-6 text-muted-foreground">
+					{translationRuntimeChecks.map((item) => (
+						<ListItem key={item}>{item}</ListItem>
+					))}
+				</List>
+			</VStack>
+
+			<VStack className="space-y-4 rounded-xl border border-border p-6">
+				<H2 className="font-bold text-2xl">Agent implementation prompt</H2>
+				<P className="text-muted-foreground">
+					Use this prompt when asking an agent to wire translations into a web,
+					server, or React Native surface without losing ContractSpec ownership.
+				</P>
+				<CodeBlock language="markdown" code={translationRuntimePrompt} />
+			</VStack>
+
+			<HStack className="flex flex-wrap items-center gap-4 pt-4">
+				<Link href="/docs/libraries/contracts" className="btn-ghost">
+					<Text>Translation contracts</Text>
+				</Link>
+				<Link href="/docs/libraries/design-system" className="btn-primary">
+					<Text>Design-system integration</Text>
+					<ChevronRight size={16} />
+				</Link>
+			</HStack>
+		</VStack>
+	);
+}

package/src/components/docs/libraries/index.ts

@@ -1,6 +1,7 @@
 export { LibrariesAccessibilityPage } from './LibrariesAccessibilityPage';
 export { LibrariesAiAgentPage } from './LibrariesAiAgentPage';
 export { LibrariesAnalyticsPage } from './LibrariesAnalyticsPage';
+export { LibrariesApplicationShellPage } from './LibrariesApplicationShellPage';
 export { LibrariesContentGenPage } from './LibrariesContentGenPage';
 export { LibrariesContractsPage } from './LibrariesContractsPage';
 export { LibrariesCostTrackingPage } from './LibrariesCostTrackingPage';
@@ -23,6 +24,7 @@ export { LibrariesSchemaPage } from './LibrariesSchemaPage';
 export { LibrariesSLOPage } from './LibrariesSLOPage';
 export { LibrariesSupportBotPage } from './LibrariesSupportBotPage';
 export { LibrariesTestingPage } from './LibrariesTestingPage';
+export { LibrariesTranslationRuntimePage } from './LibrariesTranslationRuntimePage';
 export { LibrariesUIKitPage } from './LibrariesUIKitPage';
 export { LibrariesUIKitWebPage } from './LibrariesUIKitWebPage';
 export { LibrariesWorkflowComposerPage } from './LibrariesWorkflowComposerPage';

package/src/components/docs/specs/SpecsDataViewsPage.tsx

@@ -1,3 +1,14 @@
+import { CodeBlock } 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';
 
@@ -45,7 +56,76 @@ export const DataGridShowcaseDataView = defineDataView({
       { key: 'account', label: 'Account', dataPath: 'account', sortable: true },
       { key: 'owner', label: 'Owner', dataPath: 'owner', sortable: true },
       { key: 'status', label: 'Status', dataPath: 'status', sortable: true },
-      { key: 'notes', label: 'Notes', dataPath: 'notes' },
+      {
+        key: 'arr',
+        label: 'ARR',
+        dataPath: 'arr',
+        sortable: true,
+        format: { type: 'currency', currency: 'USD', rounded: true },
+      },
+      {
+        key: 'healthScore',
+        label: 'Health score',
+        dataPath: 'healthScore',
+        format: { type: 'percent', valueScale: 'fraction', maximumFractionDigits: 1 },
+      },
+      {
+        key: 'lastActivityAt',
+        label: 'Last activity',
+        dataPath: 'lastActivityAt',
+        format: { type: 'datetime', dateStyle: 'medium', timeStyle: 'short' },
+      },
+      {
+        key: 'notes',
+        label: 'Notes',
+        dataPath: 'notes',
+        visibility: { minDataDepth: 'detailed' },
+      },
+    ],
+    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,
+        },
+      },
+    },
+    filters: [
+      { key: 'status', label: 'Status', field: 'status', type: 'enum' },
+      {
+        key: 'arr',
+        label: 'ARR',
+        field: 'arr',
+        type: 'currency',
+        valueMode: 'range',
+      },
+      {
+        key: 'lastActivityAt',
+        label: 'Last activity',
+        field: 'lastActivityAt',
+        type: 'datetime',
+        valueMode: 'range',
+      },
     ],
   },
 });`;
@@ -58,163 +138,245 @@ export const DataGridShowcaseDataView = defineDataView({
 
 export function SpecsDataViewsPage() {
 	return (
-		<div className="space-y-8">
-			<div className="space-y-4">
-				<h1 className="font-bold text-4xl">DataViews</h1>
-				<p className="text-muted-foreground">
-					A <strong>DataViewSpec</strong> describes how data should be queried,
-					filtered, sorted, and presented to users. Runtime adapters execute
-					optimized database queries and serve list views, detail views, and
-					search interfaces while respecting policy constraints.
-				</p>
-			</div>
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<H1 className="font-bold text-4xl">DataViews</H1>
+				<P className="text-muted-foreground">
+					A <Text className="font-semibold">DataViewSpec</Text> describes how
+					data should be queried, filtered, sorted, and presented to users.
+					Runtime adapters execute optimized database queries and serve list
+					views, detail views, and search interfaces while respecting policy
+					constraints.
+				</P>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Core concepts</h2>
-				<div className="space-y-3">
-					<div>
-						<h3 className="font-semibold text-lg">Data sources</h3>
-						<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Core concepts</H2>
+				<VStack className="space-y-3">
+					<VStack>
+						<H3 className="font-semibold text-lg">Data sources</H3>
+						<P className="text-muted-foreground">
 							A DataView connects to one or more data sources—databases, APIs,
 							or other capabilities. You specify the source and the fields you
 							want to expose.
-						</p>
-					</div>
-					<div>
-						<h3 className="font-semibold text-lg">Filtering</h3>
-						<p className="text-muted-foreground">
+						</P>
+					</VStack>
+					<VStack>
+						<H3 className="font-semibold text-lg">Filtering</H3>
+						<P className="text-muted-foreground">
 							Define filters that users can apply to narrow down results.
-							Filters can be simple (e.g., "status equals 'active'") or complex
-							(e.g., "created within the last 30 days AND assigned to current
-							user").
-						</p>
-					</div>
-					<div>
-						<h3 className="font-semibold text-lg">Sorting</h3>
-						<p className="text-muted-foreground">
+							Filters are typed as search, enum, number, percent, currency,
+							date, time, datetime, duration, or boolean so renderers and query
+							helpers can validate values before execution.
+						</P>
+					</VStack>
+					<VStack>
+						<H3 className="font-semibold text-lg">Sorting</H3>
+						<P className="text-muted-foreground">
 							Specify which fields can be sorted and the default sort order.
 							ContractSpec generates efficient database queries with proper
 							indexes.
-						</p>
-					</div>
-					<div>
-						<h3 className="font-semibold text-lg">Pagination</h3>
-						<p className="text-muted-foreground">
+						</P>
+					</VStack>
+					<VStack>
+						<H3 className="font-semibold text-lg">Pagination</H3>
+						<P className="text-muted-foreground">
 							DataViews automatically support pagination to handle large
 							datasets. You can configure page size limits and cursor-based or
 							offset-based pagination.
-						</p>
-					</div>
-					<div>
-						<h3 className="font-semibold text-lg">Aggregations</h3>
-						<p className="text-muted-foreground">
-							Compute aggregates like counts, sums, averages, and group-by
-							operations. These are useful for dashboards and summary views.
-						</p>
-					</div>
-				</div>
-			</div>
+						</P>
+					</VStack>
+					<VStack>
+						<H3 className="font-semibold text-lg">
+							Collection modes and data depth
+						</H3>
+						<P className="text-muted-foreground">
+							List, grid, and table views can share a single{' '}
+							<Code>view.collection</Code> contract. It declares allowed view
+							modes, toolbar controls, page-size defaults, density, data depth,
+							and persistence hints. Fields can use{' '}
+							<Code>visibility.minDataDepth</Code> so summary views stay light
+							while detailed views expose richer context.
+						</P>
+					</VStack>
+					<VStack>
+						<H3 className="font-semibold text-lg">Personalization hints</H3>
+						<P className="text-muted-foreground">
+							The contract layer stays neutral: it can opt into persistence with{' '}
+							<Code>view.collection.personalization</Code>, but it does not
+							import the personalization runtime. Host apps resolve preferences
+							and behavior insights into renderer props.
+						</P>
+					</VStack>
+				</VStack>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Example DataViewSpec</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Example DataViewSpec</H2>
+				<P className="text-muted-foreground">
 					Here is the canonical table contract used by the live{' '}
 					<Link
 						href="/docs/examples/data-grid-showcase"
 						className="text-[color:var(--rust)] underline underline-offset-4"
 					>
-						Data Grid Showcase
+						<Text>Data Grid Showcase</Text>
 					</Link>
 					:
-				</p>
-				<div className="overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm">
-					<pre>{SPECS_DATAVIEWS_EXAMPLE}</pre>
-				</div>
-				<p className="text-muted-foreground text-sm">
+				</P>
+				<CodeBlock language="typescript" code={SPECS_DATAVIEWS_EXAMPLE} />
+				<P className="text-muted-foreground text-sm">
 					This one contract drives the DataView lane, while the same rows and
 					controller also feed the raw web primitive, native-first primitive,
 					and composed design-system demos.
-				</p>
-			</div>
+				</P>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Policy integration</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Policy integration</H2>
+				<P className="text-muted-foreground">
 					DataViews automatically enforce{' '}
 					<Link
 						href="/docs/specs/policy"
 						className="text-violet-400 hover:text-violet-300"
 					>
-						PolicySpecs
+						<Text>PolicySpecs</Text>
 					</Link>
 					. If a user doesn't have permission to see certain fields, those
 					fields are automatically filtered out or redacted. If a user can only
 					see their own data, the query is automatically scoped.
-				</p>
-				<p className="text-muted-foreground">
+				</P>
+				<P className="text-muted-foreground">
 					This means you define the data view once, and it works correctly for
 					all users based on their permissions—no need to write separate queries
 					for different roles.
-				</p>
-			</div>
+				</P>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Personalized Rendering Pattern</H2>
+				<P className="text-muted-foreground">
+					To personalize a DataView, keep the spec declarative and resolve
+					user-specific defaults at the app boundary. Use{' '}
+					<Code>resolveDataViewPreferences</Code> from{' '}
+					<Code>@contractspec/lib.personalization/data-view-preferences</Code>
+					to compute <Code>viewMode</Code>, <Code>density</Code>,{' '}
+					<Code>dataDepth</Code>, and <Code>pageSize</Code>. Pass those values
+					to <Code>DataViewRenderer</Code> as controlled or default props, then
+					record UI changes with <Code>trackDataViewInteraction</Code>.
+				</P>
+				<CodeBlock
+					language="tsx"
+					code={`const resolved = resolveDataViewPreferences({
+  spec: DataGridShowcaseDataView,
+  preferences: profile.canonical,
+  insights,
+  record: savedPreference,
+});
+
+<DataViewRenderer
+  spec={DataGridShowcaseDataView}
+  items={rows}
+  defaultViewMode={resolved.viewMode}
+  defaultDensity={resolved.density}
+  defaultDataDepth={resolved.dataDepth}
+/>;`}
+				/>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Served outputs</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Served outputs</H2>
+				<P className="text-muted-foreground">
 					From a DataViewSpec, ContractSpec serves:
-				</p>
-				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
-					<li>
-						<strong>Database queries</strong> – Optimized SQL or NoSQL queries
-						executed at runtime
-					</li>
-					<li>
-						<strong>API endpoints</strong> – RESTful or GraphQL endpoints for
-						fetching data
-					</li>
-					<li>
-						<strong>UI components</strong> – List views, tables, cards, and
-						detail views
-					</li>
-					<li>
-						<strong>Search interfaces</strong> – Full-text search with
-						autocomplete
-					</li>
-					<li>
-						<strong>Export functions</strong> – CSV, JSON, or Excel exports
-					</li>
-				</ul>
-			</div>
+				</P>
+				<List className="list-inside list-disc space-y-2 text-muted-foreground">
+					<ListItem>
+						<Text>
+							<Text className="font-semibold">Database queries</Text> –
+							Optimized SQL or NoSQL queries executed at runtime
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Text className="font-semibold">API endpoints</Text> – RESTful or
+							GraphQL endpoints for fetching data
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Text className="font-semibold">UI components</Text> – List views,
+							tables, cards, and detail views
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Text className="font-semibold">Personalized defaults</Text> –
+							Plain renderer props for preferred mode, density, data depth, and
+							page size
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Text className="font-semibold">Search interfaces</Text> –
+							Full-text search with autocomplete
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							<Text className="font-semibold">Export functions</Text> – CSV,
+							JSON, or Excel exports
+						</Text>
+					</ListItem>
+				</List>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Best practices</h2>
-				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
-					<li>
-						Only expose fields that users actually need—this improves
-						performance and security.
-					</li>
-					<li>Use appropriate indexes for sortable and filterable fields.</li>
-					<li>
-						Set reasonable pagination limits to prevent performance issues.
-					</li>
-					<li>
-						Use aggregations sparingly—they can be expensive on large datasets.
-					</li>
-					<li>
-						Test DataViews with realistic data volumes to ensure they perform
-						well.
-					</li>
-				</ul>
-			</div>
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Best practices</H2>
+				<List className="list-inside list-disc space-y-2 text-muted-foreground">
+					<ListItem>
+						<Text>
+							Only expose fields that users actually need—this improves
+							performance and security.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Use appropriate indexes for sortable and filterable fields.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Set reasonable pagination limits to prevent performance issues.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Use <Code>allowedModes</Code> to constrain mode switching to
+							layouts that the fields and row actions can support.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Store preferences only for dimensions enabled by{' '}
+							<Code>view.collection.personalization.persist</Code>.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Test DataViews with realistic data volumes to ensure they perform
+							well.
+						</Text>
+					</ListItem>
+				</List>
+			</VStack>
 
-			<div className="flex items-center gap-4 pt-4">
+			<HStack className="items-center gap-4 pt-4">
 				<Link href="/docs/specs/capabilities" className="btn-ghost">
-					Previous: Capabilities
+					<Text>Previous: Capabilities</Text>
 				</Link>
 				<Link href="/docs/specs/workflows" className="btn-primary">
-					Next: Workflows <ChevronRight size={16} />
+					<Text>Next: Workflows</Text> <ChevronRight size={16} />
 				</Link>
-			</div>
-		</div>
+			</HStack>
+		</VStack>
 	);
 }