@contractspec/bundle.library 3.9.8 → 3.9.9

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

@@ -1,31 +1,93 @@
 import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import { HStack, VStack } from '@contractspec/lib.design-system/layout';
+import {
+	Code,
+	H1,
+	H2,
+	P,
+	Text,
+} from '@contractspec/lib.design-system/typography';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
+const DATA_VIEW_PREFERENCE_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: savedAccountViewPreference,
+});
+
+return (
+  <DataViewRenderer
+    spec={AccountsDataView}
+    items={accounts}
+    defaultViewMode={resolved.viewMode}
+    defaultDensity={resolved.density}
+    defaultDataDepth={resolved.dataDepth}
+    pagination={{
+      page,
+      pageSize: resolved.pageSize ?? 25,
+      total,
+    }}
+  />
+);`;
+
+const DATA_VIEW_TRACKING_EXAMPLE = `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',
+});`;
+
+const DATA_VIEW_PERSONALIZATION_PROMPT = `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.`;
+
 export function LibrariesPersonalizationPage() {
 	return (
-		<div className="space-y-8">
-			<div className="space-y-4">
-				<h1 className="font-bold text-4xl">
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<H1 className="font-bold text-4xl">
 					@contractspec/lib.personalization
-				</h1>
-				<p className="text-lg text-muted-foreground">
+				</H1>
+				<P className="text-lg text-muted-foreground">
 					Track field/feature/workflow usage, analyze drop-offs, and convert
 					insights into OverlaySpecs or workflow tweaks.
-				</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.personalization" />
-			</div>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Tracker</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Tracker</H2>
+				<P className="text-muted-foreground">
 					Buffer events per tenant/user and emit OpenTelemetry counters
 					automatically.
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					code={`import { createBehaviorTracker } from '@contractspec/lib.personalization';
@@ -38,29 +100,65 @@ const tracker = createBehaviorTracker({
 tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'items' });
 tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`}
 				/>
-			</div>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">DataView Preferences</H2>
+				<P className="text-muted-foreground">
+					Use <Code>resolveDataViewPreferences</Code> 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{' '}
+					<Link
+						href="/docs/libraries/data-views"
+						className="text-[color:var(--rust)] underline underline-offset-4"
+					>
+						<Text>DataViews runtime guide</Text>
+					</Link>{' '}
+					when you need the contract and renderer shape.
+				</P>
+				<CodeBlock language="tsx" code={DATA_VIEW_PREFERENCE_EXAMPLE} />
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Analyzer</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">DataView Interaction Events</H2>
+				<P className="text-muted-foreground">
+					Track <Code>data_view_interaction</Code> 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.
+				</P>
+				<CodeBlock language="typescript" code={DATA_VIEW_TRACKING_EXAMPLE} />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Analyzer</H2>
+				<P className="text-muted-foreground">
 					Summarize events and highlight unused UI, frequent fields, and
 					workflow bottlenecks.
-				</p>
+				</P>
 				<CodeBlock
 					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: [...] }`}
+// {
+//   unusedFields: ['internalNotes'],
+//   workflowBottlenecks: [...],
+//   dataViewPreferences: {
+//     'crm.accounts': { preferredViewMode: 'grid' }
+//   }
+// }`}
 				/>
-			</div>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">Adapter</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Adapter</H2>
+				<P className="text-muted-foreground">
 					Convert insights into overlays or workflow extension hints.
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					code={`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
@@ -71,16 +169,28 @@ const overlay = insightsToOverlaySuggestion(insights, {
   capability: 'billing.createOrder',
 });`}
 				/>
-			</div>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Agent Prompt</H2>
+				<P className="text-muted-foreground">
+					Use this when asking an agent to wire DataView preferences while
+					preserving the personalization/design-system boundary.
+				</P>
+				<CodeBlock
+					language="markdown"
+					code={DATA_VIEW_PERSONALIZATION_PROMPT}
+				/>
+			</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/overlay-engine" className="btn-primary">
-					Next: Overlay Engine <ChevronRight size={16} />
+					<Text>Next: Overlay Engine</Text> <ChevronRight size={16} />
 				</Link>
-			</div>
-		</div>
+			</HStack>
+		</VStack>
 	);
 }

package/src/components/docs/libraries/LibrariesTranslationRuntimePage.content.ts

@@ -0,0 +1,78 @@
+export const translationRuntimeInstall = [
+	'@contractspec/lib.contracts-spec',
+	'@contractspec/lib.translation-runtime',
+];
+
+export const translationRuntimeExample = `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',
+});`;
+
+export const i18nextAdapterExample = `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);`;
+
+export const ssrHydrationExample = `// 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 });`;
+
+export const translationRuntimeChecks = [
+	'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.',
+];
+
+export const translationRuntimePrompt = `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.`;
+
+export const translationRuntimeLayers = [
+	{
+		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.',
+	},
+];

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

@@ -24,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';