@contractspec/bundle.library 3.9.8 → 3.9.9

package/src/components/docs/getting-started/DataViewTutorialPage.tsx

@@ -1,4 +1,13 @@
 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 {
+	H1,
+	H2,
+	H3,
+	P,
+	Text,
+} from '@contractspec/lib.design-system/typography';
 import Link from '@contractspec/lib.ui-link';
 import { ChevronRight } from 'lucide-react';
 
@@ -64,8 +73,41 @@ export const TransactionHistory = defineDataView({
         dataPath: 'processingMinutes',
         format: { type: 'duration', unit: 'minute', display: 'digital' },
       },
-      { key: 'notes', label: 'Notes', dataPath: 'notes' },
+      {
+        key: 'notes',
+        label: 'Notes',
+        dataPath: 'notes',
+        visibility: { minDataDepth: 'detailed' },
+      },
     ],
+    collection: {
+      viewModes: {
+        defaultMode: 'table',
+        allowedModes: ['list', 'grid', 'table'],
+      },
+      toolbar: {
+        search: true,
+        viewMode: true,
+        filters: true,
+        density: true,
+        dataDepth: true,
+      },
+      pagination: {
+        pageSize: 25,
+        pageSizeOptions: [10, 25, 50],
+      },
+      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' },
       {
@@ -88,20 +130,20 @@ export const TransactionHistory = defineDataView({
 
 export function DataViewTutorialPage() {
 	return (
-		<div className="space-y-8">
-			<div className="space-y-4">
-				<h1 className="font-bold text-4xl">Display Data with DataViews</h1>
-				<p className="text-lg text-muted-foreground">
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<H1 className="font-bold text-4xl">Display Data with DataViews</H1>
+				<P className="text-lg text-muted-foreground">
 					Define a filterable, sortable transaction history view that works
 					across web and mobile without duplicating UI code.
-				</p>
-			</div>
+				</P>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">1. Define the underlying query</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">1. Define the underlying query</H2>
+				<P className="text-muted-foreground">
 					First, create a query operation to fetch the data:
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					filename="lib/specs/billing/list-transactions.ts"
@@ -120,35 +162,35 @@ export const ListTransactions = defineQuery({
   policy: { auth: 'user' },
 });`}
 				/>
-			</div>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">2. Define the DataView spec</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">2. Define the DataView spec</H2>
+				<P className="text-muted-foreground">
 					Wrap your query with presentation metadata:
-				</p>
+				</P>
 				<CodeBlock
 					language="typescript"
 					filename="lib/specs/billing/transaction-history.data-view.ts"
 					code={DATAVIEW_TUTORIAL_EXAMPLE}
 				/>
-				<p className="text-muted-foreground text-sm">
+				<P className="text-muted-foreground text-sm">
 					The live version of this pattern is available in the canonical{' '}
 					<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>
+				</P>
+			</VStack>
 
-			<div className="space-y-4">
-				<h2 className="font-bold text-2xl">3. Render on the frontend</h2>
-				<p className="text-muted-foreground">
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">3. Render on the frontend</H2>
+				<P className="text-muted-foreground">
 					Use the runtime renderer in your React or React Native app:
-				</p>
+				</P>
 				<CodeBlock
 					language="tsx"
 					filename="app/dashboard/transactions/page.tsx"
@@ -169,8 +211,11 @@ export function TransactionsPage() {
       <h1 className="text-3xl font-bold mb-6">Payment History</h1>
       <DataViewRenderer
         spec={TransactionHistory}
-        data={data?.items ?? []}
+        items={data?.items ?? []}
         loading={isLoading}
+        defaultViewMode="table"
+        defaultDensity="comfortable"
+        defaultDataDepth="standard"
         onFilterChange={(filters) => {
           // refetch with new filters
         }}
@@ -179,34 +224,120 @@ export function TransactionsPage() {
   );
 }`}
 				/>
-			</div>
-
-			<div className="card-subtle space-y-4 p-6">
-				<h3 className="font-bold">Why DataViews?</h3>
-				<ul className="space-y-2 text-muted-foreground text-sm">
-					<li>Same spec renders on web (React) and mobile (React Native)</li>
-					<li>Filters, sorting, and pagination handled automatically</li>
-					<li>
-						Column visibility, pinning, resizing, and row expansion stay
-						contract-driven
-					</li>
-					<li>
-						Typed format rules for numbers, percent values, currency, dates,
-						times, datetimes, and durations applied consistently
-					</li>
-					<li>Export to CSV/PDF using the same spec</li>
-					<li>A/B test different layouts without touching the backend</li>
-				</ul>
-			</div>
-
-			<div className="flex items-center gap-4 pt-4">
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">4. Add personalization</H2>
+				<P className="text-muted-foreground">
+					When the app has a user profile or behavior insights, resolve DataView
+					preferences before rendering. The renderer receives plain props;
+					personalization stays in the app/runtime boundary.
+				</P>
+				<CodeBlock
+					language="tsx"
+					filename="app/dashboard/transactions/PersonalizedTransactions.tsx"
+					code={`'use client';
+
+import { DataViewRenderer } from '@contractspec/lib.design-system';
+import { resolveDataViewPreferences } from '@contractspec/lib.personalization/data-view-preferences';
+import { createBehaviorTracker } from '@contractspec/lib.personalization';
+
+const tracker = createBehaviorTracker({
+  store,
+  context: { tenantId: tenant.id, userId: user.id },
+});
+
+const resolved = resolveDataViewPreferences({
+  spec: TransactionHistory,
+  preferences: profile.canonical,
+  insights,
+  record: savedTransactionViewPreference,
+});
+
+<DataViewRenderer
+  spec={TransactionHistory}
+  items={transactions}
+  defaultViewMode={resolved.viewMode}
+  defaultDensity={resolved.density}
+  defaultDataDepth={resolved.dataDepth}
+  pagination={{ page, pageSize: resolved.pageSize ?? 25, total }}
+  onViewModeChange={(viewMode) =>
+    tracker.trackDataViewInteraction({
+      dataViewKey: TransactionHistory.meta.key,
+      action: 'view_mode_changed',
+      viewMode,
+    })
+  }
+  onDataDepthChange={(dataDepth) =>
+    tracker.trackDataViewInteraction({
+      dataViewKey: TransactionHistory.meta.key,
+      action: 'data_depth_changed',
+      dataDepth,
+    })
+  }
+/>;`}
+				/>
+			</VStack>
+
+			<VStack className="card-subtle space-y-4 p-6">
+				<H3 className="font-bold">Why DataViews?</H3>
+				<List className="space-y-2 text-muted-foreground text-sm">
+					<ListItem>
+						<Text>
+							Same spec renders on web (React) and mobile (React Native)
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>Filters, sorting, and pagination handled automatically</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Column visibility, pinning, resizing, and row expansion stay
+							contract-driven
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							List, grid, and table modes can share one collection config with
+							toolbar and pagination defaults
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Data depth lets summary screens hide detailed fields without
+							forking the spec
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Typed format rules for numbers, percent values, currency, dates,
+							times, datetimes, and durations applied consistently
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							Personalization helpers can seed preferred view mode, density,
+							data depth, and page size from user preferences or behavior
+							insights
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>Export to CSV/PDF using the same spec</Text>
+					</ListItem>
+					<ListItem>
+						<Text>A/B test different layouts without touching the backend</Text>
+					</ListItem>
+				</List>
+			</VStack>
+
+			<HStack className="items-center gap-4 pt-4">
 				<Link href="/docs/libraries/data-views" className="btn-primary">
-					DataView API Reference <ChevronRight size={16} />
+					<Text>DataView API Reference</Text> <ChevronRight size={16} />
 				</Link>
 				<Link href="/docs/specs/workflows" className="btn-ghost">
-					Next: Workflows
+					<Text>Next: Workflows</Text>
 				</Link>
-			</div>
-		</div>
+			</HStack>
+		</VStack>
 	);
 }

package/src/components/docs/guides/GuideDataExchangeImportTemplatesPage.content.ts

@@ -0,0 +1,185 @@
+export const accountImportTemplateCode = `import {
+  createImportPlan,
+  createRecordBatch,
+  defineDataExchangeTemplate,
+  previewImport,
+} from "@contractspec/lib.data-exchange-core";
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+const AccountImportSchema = defineSchemaModel({
+  name: "AccountImport",
+  fields: {
+    id: { type: ScalarTypeEnum.ID(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    amount: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    active: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    tags: { type: ScalarTypeEnum.JSON(), isOptional: true },
+  },
+});
+
+const accountImportTemplate = defineDataExchangeTemplate({
+  key: "accounts.import",
+  version: "1.0.0",
+  title: "Account import",
+  columns: [
+    {
+      key: "id",
+      label: "Account ID",
+      targetField: "id",
+      required: true,
+      sourceAliases: ["Account Identifier", "External ID", "No compte"],
+    },
+    {
+      key: "status",
+      label: "Status",
+      targetField: "status",
+      required: true,
+      sourceAliases: ["Statut", "State"],
+      format: { kind: "text", trim: true, case: "lowercase" },
+    },
+    {
+      key: "amount",
+      label: "Amount",
+      targetField: "amount",
+      required: true,
+      sourceAliases: ["Montant", "Balance"],
+      format: { kind: "number", decimalSeparator: ",", thousandsSeparator: "." },
+    },
+    {
+      key: "active",
+      label: "Active",
+      targetField: "active",
+      sourceAliases: ["Actif", "Enabled"],
+      format: { kind: "boolean", trueValues: ["yes", "oui"], falseValues: ["no", "non"] },
+    },
+    {
+      key: "tags",
+      label: "Tags",
+      targetField: "tags",
+      format: { kind: "split", delimiter: ";" },
+    },
+  ],
+});
+
+const sourceBatch = createRecordBatch([
+  {
+    "No compte": "acc-1",
+    Statut: " Active ",
+    Montant: "1.234,50",
+    Actif: "oui",
+    Tags: "vip; beta",
+  },
+]);
+
+const preview = previewImport(
+  createImportPlan({
+    source: { kind: "memory", batch: sourceBatch, format: "csv" },
+    target: { kind: "memory", format: "json" },
+    schema: AccountImportSchema,
+    sourceBatch,
+    template: accountImportTemplate,
+  }),
+);
+
+console.log(preview.plan.mappingSource); // "template"
+console.log(preview.normalizedRecords[0]);`;
+
+export const serverDryRunCode = `import { defineDataExchangeTemplate } from "@contractspec/lib.data-exchange-core";
+import { dryRunImport, executeImport } from "@contractspec/lib.data-exchange-server";
+
+const template = defineDataExchangeTemplate({
+  key: "accounts.import",
+  version: "1.0.0",
+  columns: [
+    { key: "id", label: "Account ID", targetField: "id", required: true, sourceAliases: ["Account Identifier"] },
+    { key: "amount", label: "Amount", targetField: "amount", format: { kind: "currency", currencySymbol: "€", decimalSeparator: "," } },
+  ],
+});
+
+const partnerSource = {
+  kind: "file",
+  path: "partner-accounts.csv",
+  format: "csv",
+  codecOptions: { csv: { delimiter: ";", skipRows: 1 } },
+} as const;
+
+const formatProfile = {
+  columns: {
+    amount: { kind: "currency", currencySymbol: "€", decimalSeparator: "," },
+  },
+} as const;
+
+const preview = await dryRunImport({
+  source: partnerSource,
+  target: { kind: "memory", format: "json" },
+  schema: AccountImportSchema,
+  template,
+  formatProfile,
+});
+
+const blockingIssues = preview.issues.filter((issue) => issue.severity === "error");
+
+if (blockingIssues.length === 0) {
+  await executeImport({
+    source: partnerSource,
+    target: { kind: "memory", format: "json" },
+    schema: AccountImportSchema,
+    template,
+    formatProfile,
+  });
+}`;
+
+export const clientReviewCode = `"use client";
+
+import { useDataExchangeController } from "@contractspec/lib.data-exchange-client";
+
+export function ImportMappingReview({ preview }) {
+  const controller = useDataExchangeController({ preview });
+  const replacementSourceColumn = controller.model.ignoredSourceColumns[0];
+
+  return (
+    <section>
+      {controller.model.templateRows.map((row) => (
+        <button
+          key={row.id}
+          type="button"
+          disabled={!replacementSourceColumn}
+          onClick={() => {
+            if (!replacementSourceColumn) return;
+            controller.selectAlias(row.targetField, replacementSourceColumn);
+          }}
+        >
+          {row.label}: {row.sourceField || "Unmatched"} -> {row.targetField}
+          {row.required ? " required" : ""}
+          {row.formatLabel ? \` (\${row.formatLabel})\` : ""}
+        </button>
+      ))}
+      {controller.model.unmatchedRequiredRows.length > 0 ? (
+        <p>Resolve required columns before import.</p>
+      ) : null}
+    </section>
+  );
+}`;
+
+export const developerPrompt = `You are adding an import flow to a ContractSpec app.
+
+Define a reusable data-exchange template for this canonical schema:
+- target fields, required flags, and display labels
+- known partner column aliases
+- value formats for numbers, dates, booleans, JSON, split/join lists, currency, and percentages
+
+Wire the template into core preview planning and server dry-run execution. Keep explicit mappings higher precedence than template resolution. Return the template, preview call, server dry-run call, and tests for alias matching plus localized formatting.`;
+
+export const partnerPrompt = `A partner sent a CSV/JSON/XML file that does not match our recommended import template.
+
+Compare the incoming headers and value samples against this ContractSpec data-exchange template. Propose:
+- source-to-target column matches with confidence
+- missing required target fields
+- ignored source columns
+- format overrides for localized numbers, booleans, dates, JSON, split/join lists, currency, or percentages
+
+Do not execute the import. Produce a dry-run plan and the user-facing review copy.`;
+
+export const verificationCode = `cd packages/libs/data-exchange-core && bun test && bun run typecheck && bun run lint:check
+cd packages/libs/data-exchange-client && bun test && bun run typecheck && bun run lint:check
+cd packages/libs/data-exchange-server && bun test && bun run typecheck && bun run lint:check`;

package/src/components/docs/guides/GuideDataExchangeImportTemplatesPage.tsx

@@ -0,0 +1,186 @@
+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';
+import {
+	accountImportTemplateCode,
+	clientReviewCode,
+	developerPrompt,
+	partnerPrompt,
+	serverDryRunCode,
+	verificationCode,
+} from './GuideDataExchangeImportTemplatesPage.content';
+
+const mappingRules = [
+	'Explicit mappings win first, so existing integrations can keep their current mapping arrays.',
+	'Template resolution checks exact headers, aliases, normalized labels, and SchemaModel fallback inference.',
+	'Format profiles can override formats by target field or template column key without changing the template.',
+	'Required template columns become visible preview issues when no source column can be matched.',
+];
+
+const formatKinds = [
+	'text trim and case normalization',
+	'localized numbers with decimal and thousands separators',
+	'custom true/false boolean labels',
+	'dates and datetimes with accepted input formats',
+	'JSON parsing, empty-as-null, and default values',
+	'split/join delimiters, currency symbols, and percentages',
+];
+
+export function GuideDataExchangeImportTemplatesPage() {
+	return (
+		<VStack className="space-y-8">
+			<VStack className="space-y-3">
+				<Text className="editorial-kicker">Build</Text>
+				<H1 className="font-bold text-4xl">
+					Import flexible files with data-exchange templates
+				</H1>
+				<P className="max-w-3xl text-lg text-muted-foreground leading-8">
+					Publish one recommended import shape, then let users import
+					CSV/JSON/XML files with partner-specific headers, skipped rows,
+					localized values, and alternate metadata layouts.
+				</P>
+			</VStack>
+
+			<VStack className="card-subtle space-y-4 p-6">
+				<H2 className="font-bold text-2xl">What you&apos;ll build</H2>
+				<List className="space-y-2 text-muted-foreground text-sm">
+					<ListItem>
+						<Text>
+							A canonical template with target fields, aliases, and formats.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							A dry-run import that reports confidence, gaps, and ignored
+							columns.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							A client review state where users remap, update formats, or accept
+							inferred mappings.
+						</Text>
+					</ListItem>
+				</List>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">1) Define the template</H2>
+				<P className="text-muted-foreground text-sm leading-7">
+					Use <Code>defineDataExchangeTemplate</Code> for neutral import/export
+					naming. <Code>defineImportTemplate</Code> and{' '}
+					<Code>defineExportTemplate</Code> remain available aliases.
+				</P>
+				<CodeBlock
+					language="typescript"
+					filename="src/data-exchange/accounts-import.ts"
+					code={accountImportTemplateCode}
+				/>
+			</VStack>
+
+			<VStack className="grid gap-4 md:grid-cols-2">
+				<VStack className="card-subtle space-y-3 p-6">
+					<H3 className="font-bold text-xl">Mapping precedence</H3>
+					<List className="space-y-2 text-muted-foreground text-sm">
+						{mappingRules.map((rule) => (
+							<ListItem key={rule}>
+								<Text>{rule}</Text>
+							</ListItem>
+						))}
+					</List>
+				</VStack>
+				<VStack className="card-subtle space-y-3 p-6">
+					<H3 className="font-bold text-xl">Supported value formats</H3>
+					<List className="space-y-2 text-muted-foreground text-sm">
+						{formatKinds.map((format) => (
+							<ListItem key={format}>
+								<Text>{format}</Text>
+							</ListItem>
+						))}
+					</List>
+				</VStack>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">
+					2) Dry-run partner CSV, JSON, or XML files on the server
+				</H2>
+				<P className="text-muted-foreground text-sm leading-7">
+					File, HTTP, and storage adapters accept codec options. CSV can set
+					delimiters, quotes, skipped rows, header rows, or explicit columns.
+					JSON can read records and metadata from custom keys. XML can use
+					custom root, record, metadata, and attribute fields.
+				</P>
+				<CodeBlock
+					language="typescript"
+					filename="src/server/import-accounts.ts"
+					code={serverDryRunCode}
+				/>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">3) Let users review the mapping</H2>
+				<P className="text-muted-foreground text-sm leading-7">
+					The shared controller exposes template rows, matched source columns,
+					confidence, required status, formatting summaries, unmatched required
+					rows, and ignored source columns. Actions let users remap columns,
+					select aliases, update field formats, reset to the template, or accept
+					inferred mappings.
+				</P>
+				<CodeBlock
+					language="tsx"
+					filename="src/components/ImportMappingReview.tsx"
+					code={clientReviewCode}
+				/>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">4) Verify the package stack</H2>
+				<CodeBlock
+					language="bash"
+					filename="verification"
+					code={verificationCode}
+				/>
+			</VStack>
+
+			<VStack className="grid gap-4 md:grid-cols-2">
+				<VStack className="card-subtle space-y-3 p-6">
+					<H3 className="font-bold text-xl">Prompt: build a template</H3>
+					<CodeBlock
+						language="markdown"
+						filename="template-authoring.prompt.md"
+						code={developerPrompt}
+					/>
+				</VStack>
+				<VStack className="card-subtle space-y-3 p-6">
+					<H3 className="font-bold text-xl">Prompt: inspect a partner file</H3>
+					<CodeBlock
+						language="markdown"
+						filename="partner-import-review.prompt.md"
+						code={partnerPrompt}
+					/>
+				</VStack>
+			</VStack>
+
+			<HStack className="flex flex-wrap items-center gap-4 pt-4">
+				<Link href="/llms/lib.data-exchange-core" className="btn-primary">
+					<Text>Core package guide</Text>
+					<ChevronRight size={16} />
+				</Link>
+				<Link href="/llms/lib.data-exchange-server" className="btn-ghost">
+					<Text>Server package guide</Text>
+				</Link>
+			</HStack>
+		</VStack>
+	);
+}