@contractspec/bundle.library 3.9.7 → 3.9.9

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>
+	);
+}

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

@@ -1,4 +1,7 @@
 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, P, Text } from '@contractspec/lib.design-system/typography';
 import Link from '@contractspec/lib.ui-link';
 import { ArrowRight, CheckCircle2, GitBranch } from 'lucide-react';
 
@@ -31,6 +34,13 @@ const guides = [
 		href: '/docs/guides/contract-driven-forms',
 		time: '25 min',
 	},
+	{
+		title: 'Flexible import templates',
+		description:
+			'Accept partner CSV, JSON, and XML files with alternate headers and localized values while preserving a canonical import contract.',
+		href: '/docs/guides/data-exchange-import-templates',
+		time: '25 min',
+	},
 	{
 		title: 'Generate docs and clients',
 		description:
@@ -84,64 +94,61 @@ const guides = [
 
 export function GuidesIndexPage() {
 	return (
-		<div className="space-y-10">
-			<div className="space-y-3">
-				<p className="editorial-kicker">Build</p>
-				<h1 className="font-serif text-4xl tracking-[-0.04em] md:text-5xl">
+		<VStack className="space-y-10">
+			<VStack className="space-y-3">
+				<Text className="editorial-kicker">Build</Text>
+				<H1 className="font-serif text-4xl tracking-[-0.04em] md:text-5xl">
 					Adoption guides for teams that want to keep their code.
-				</h1>
-				<p className="max-w-3xl text-lg text-muted-foreground leading-8">
+				</H1>
+				<P className="max-w-3xl text-lg text-muted-foreground leading-8">
 					These guides assume you are introducing ContractSpec into a real code
 					base. Start with a narrow surface, verify the generated outputs, and
 					expand only after the contract loop feels trustworthy.
-				</p>
-			</div>
+				</P>
+			</VStack>
 
-			<div className="grid gap-4 md:grid-cols-2">
+			<VStack className="grid gap-4 md:grid-cols-2">
 				{guides.map((guide) => (
 					<Link key={guide.href} href={guide.href} className="editorial-panel">
-						<div className="flex items-start justify-between gap-4">
-							<div>
-								<h2 className="font-semibold text-xl">{guide.title}</h2>
-								<p className="mt-2 text-muted-foreground text-sm leading-7">
+						<HStack className="flex items-start justify-between gap-4">
+							<VStack>
+								<H2 className="font-semibold text-xl">{guide.title}</H2>
+								<P className="mt-2 text-muted-foreground text-sm leading-7">
 									{guide.description}
-								</p>
-							</div>
+								</P>
+							</VStack>
 							<ArrowRight className="mt-1 shrink-0" size={18} />
-						</div>
-						<div className="mt-4 flex items-center gap-2 text-muted-foreground text-xs">
+						</HStack>
+						<HStack className="mt-4 flex items-center gap-2 text-muted-foreground text-xs">
 							<CheckCircle2 size={14} />
-							<span>Target time: {guide.time}</span>
-						</div>
+							<Text>Target time: {guide.time}</Text>
+						</HStack>
 					</Link>
 				))}
-			</div>
+			</VStack>
 
-			<div className="editorial-panel space-y-4">
-				<div className="flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]">
+			<VStack className="editorial-panel space-y-4">
+				<HStack className="flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]">
 					<GitBranch size={16} />
-					Working style
-				</div>
-				<ul className="editorial-list">
-					<li>
-						<span className="editorial-list-marker" />
-						<span>Run each guide in a branch or sandboxed workspace.</span>
-					</li>
-					<li>
-						<span className="editorial-list-marker" />
-						<span>
+					<Text>Working style</Text>
+				</HStack>
+				<List className="editorial-list">
+					<ListItem>
+						<Text>Run each guide in a branch or sandboxed workspace.</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
 							Prefer one bounded surface at a time: one endpoint, one workflow,
 							one integration, one unsafe module.
-						</span>
-					</li>
-					<li>
-						<span className="editorial-list-marker" />
-						<span>
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
 							Use the example and reference outputs to verify what changed, not
 							just the narrative page.
-						</span>
-					</li>
-				</ul>
+						</Text>
+					</ListItem>
+				</List>
 				<CodeBlock
 					language="bash"
 					filename="guides-quickstart"
@@ -151,7 +158,7 @@ contractspec examples list
 # validate the examples in this workspace
 contractspec examples validate --repo-root .`}
 				/>
-			</div>
-		</div>
+			</VStack>
+		</VStack>
 	);
 }

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

@@ -4,6 +4,7 @@ export { GuideCIDiffGatingPage } from './GuideCIDiffGatingPage';
 export { GuideConnectInRepoPage } from './GuideConnectInRepoPage';
 export { GuideContractDrivenFormsPage } from './GuideContractDrivenFormsPage';
 export { GuideContractTypesPage } from './GuideContractTypesPage';
+export { GuideDataExchangeImportTemplatesPage } from './GuideDataExchangeImportTemplatesPage';
 export { GuideDocsPipelinePage } from './GuideDocsPipelinePage';
 export { GuideFirstModuleBundlePage } from './GuideFirstModuleBundlePage';
 export { GuideGenerateDocsClientsSchemasPage } from './GuideGenerateDocsClientsSchemasPage';

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

@@ -0,0 +1,283 @@
+export const shellUsageExample = `import {
+  AppShell,
+  type ShellCommandGroup,
+  type ShellNavSection,
+  type ShellNotificationCenter,
+  type PageOutlineItem,
+} from "@contractspec/lib.design-system/shell";
+
+const navigation: ShellNavSection[] = [
+  {
+    title: "Workspace",
+    items: [
+      { label: "Dashboard", href: "/dashboard" },
+      {
+        label: "Contracts",
+        href: "/contracts",
+        children: [
+          { label: "Operations", href: "/contracts/operations" },
+          { label: "Events", href: "/contracts/events" },
+        ],
+      },
+    ],
+  },
+];
+
+const commands: ShellCommandGroup[] = [
+  {
+    heading: "Quick actions",
+    items: [
+      { id: "new-contract", label: "New contract", shortcut: "N" },
+      { id: "import", label: "Import existing app" },
+    ],
+  },
+];
+
+const outline: PageOutlineItem[] = [
+  {
+    id: "architecture",
+    label: "Architecture",
+    level: 1,
+    children: [
+      { id: "desktop", label: "Desktop shell", level: 2 },
+      { id: "mobile", label: "Mobile adaptation", level: 2 },
+    ],
+  },
+];
+
+const notifications: ShellNotificationCenter = {
+  label: "Notifications",
+  loading: false,
+  unreadCount: 2,
+  items: [
+    {
+      id: "contract-approved",
+      title: "Contract approved",
+      body: "Billing.create is ready to publish.",
+      status: "unread",
+      createdAt: "2026-04-29T09:30:00Z",
+      actionUrl: "/contracts/billing.create",
+      category: "Review",
+    },
+  ],
+  onSelect: (item) => openNotificationTarget(item),
+  onMarkRead: (item) => markNotificationRead(item.id),
+  onMarkAllRead: () => markAllNotificationsRead(),
+};
+
+export function WorkspacePage() {
+  return (
+    <AppShell
+      title="ContractSpec"
+      homeHref="/dashboard"
+      navigation={navigation}
+      commands={commands}
+      breadcrumbs={[
+        { label: "Workspace", href: "/dashboard" },
+        { label: "Contracts" },
+      ]}
+      notifications={notifications}
+      pageOutline={outline}
+      activeHref="/contracts"
+      activeOutlineId="desktop"
+      userMenu={<UserMenu onSignOut={() => signOut()} />}
+    >
+      <main>{/* route content */}</main>
+    </AppShell>
+  );
+}`;
+
+export const notificationCenterExample = `import {
+  ListNotificationsOutputModel,
+  MarkNotificationReadInputModel,
+} from "@contractspec/lib.contracts-spec/notifications";
+import {
+  notificationsSchemaContribution,
+  renderNotificationTemplate,
+} from "@contractspec/lib.notification";
+import type { ShellNotificationCenter } from "@contractspec/lib.design-system/shell";
+
+type NotificationListResult = {
+  unreadCount: number;
+  notifications: Array<{
+    id: string;
+    title: string;
+    body: string;
+    type: string;
+    status: string;
+    readAt?: string | Date | null;
+    createdAt: string | Date;
+    actionUrl?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+};
+
+export function toShellNotifications(
+  data: NotificationListResult,
+  actions: {
+    open: (id: string) => void;
+    markRead: (input: { notificationId: string }) => void;
+    markAllRead: () => void;
+  }
+): ShellNotificationCenter {
+  return {
+    unreadCount: data.unreadCount,
+    items: data.notifications.map((notification) => ({
+      id: notification.id,
+      title: notification.title,
+      body: notification.body,
+      status: notification.status,
+      createdAt: notification.createdAt,
+      actionUrl: notification.actionUrl,
+      category: notification.type,
+      metadata: notification.metadata,
+    })),
+    onSelect: (item) => actions.open(item.id),
+    onMarkRead: (item) => actions.markRead({ notificationId: item.id }),
+    onMarkAllRead: actions.markAllRead,
+  };
+}
+
+void ListNotificationsOutputModel;
+void MarkNotificationReadInputModel;
+void notificationsSchemaContribution;
+void renderNotificationTemplate;`;
+
+export const scratchPrompt = `You are implementing a modern application shell from scratch.
+
+Goal:
+Build a reusable application shell for a React/Next.js web app and an Expo React Native app. The shell must provide a desktop sidebar, desktop topbar, command search, breadcrumbs, nested navigation, user/auth actions, in-app notifications, and an in-page section navigator called PageOutline.
+
+Use this architecture:
+- Keep route content independent from navigation chrome.
+- Create a typed navigation model with sections, items, active state, optional children, badges, icons, disabled items, and href/onSelect support.
+- Create a command model with search input, grouped suggestions, quick actions, keyboard shortcut labels, empty state, and loading state.
+- Create a breadcrumb model for the topbar.
+- Create a PageOutline model for right-side in-page navigation with exactly three supported levels. It should render anchors, support active section state, and degrade gracefully when no sections exist.
+- Create a ShellNotificationCenter model with render-ready items, unread count, loading and empty states, onSelect, onMarkRead, onMarkAllRead, and optional custom item rendering.
+- Expose the system from the design system or a dedicated shell module, not from a single app route.
+
+Notification boundary:
+- Use @contractspec/lib.contracts-spec/notifications as the canonical source for notification contracts, operation models, and feature metadata.
+- Use @contractspec/lib.notification for reusable notification entities, schema contribution, channels, templates, and i18n helpers.
+- Keep persistence, polling/subscriptions, delivery providers, and optimistic mutations in the host application or notification runtime layer.
+- Pass only render-ready ShellNotificationCenter state into AppShell so the design system does not import or own notification runtime behavior.
+
+Desktop behavior:
+- Persistent left sidebar with app logo/title, command trigger, grouped navigation, nested submenus, and current user/auth/logout area.
+- Topbar with breadcrumbs and an optional command trigger.
+- Topbar notification trigger with unread badge, loading/empty states, mark-read actions, and item selection.
+- Content area with optional right PageOutline.
+- Keep dimensions stable. Navigation labels must not resize layout on hover or active state.
+
+Mobile web behavior:
+- Use bottom navigation for the primary destinations.
+- Put deeper navigation, command search, notifications, auth actions, and secondary actions behind a menu or drawer when the topbar cannot safely hold them.
+- Keep route content first and make the shell controls reachable without covering important content.
+
+Native behavior:
+- Add .native.tsx entrypoints for Expo/React Native.
+- Prefer bottom tabs for primary destinations and a menu/sheet for deeper navigation, notifications, and account actions.
+- Keep the same typed navigation, command, breadcrumb, notification, and PageOutline data contracts across web and native.
+
+Implementation constraints:
+- Reuse the existing design-system primitives, tokens, icons, and accessibility patterns.
+- Do not hardcode app-specific routes in the shell component.
+- Do not introduce a new dependency unless the repo already uses it for dialogs, menus, icons, or navigation.
+- Include tests for navigation rendering, nested items, command filtering, breadcrumbs, notification unread badge/loading/empty/callback behavior, PageOutline level handling, active section state, and mobile/native adaptation contracts.
+- Update docs and exports so developers can import the shell from a stable public API.
+
+Deliverables:
+- Typed shell models.
+- Web shell components.
+- Native shell components or adapters.
+- PageOutline component with three-level support.
+- ShellNotifications or equivalent notification center component for web and native shell placement.
+- Usage example.
+- Focused tests and typecheck/build evidence.`;
+
+export const refactorPrompt = `You are refactoring an existing application to use the shared application shell system.
+
+Goal:
+Replace app-specific sidebar, topbar, breadcrumb, command palette, notification badge/inbox, account menu, mobile navigation, and in-page table-of-contents code with the shared AppShell, ShellNotifications, and PageOutline system.
+
+Start by auditing:
+- Current layout wrappers and route groups.
+- Sidebar, topbar, breadcrumb, command/search, auth menu, and mobile navigation implementations.
+- Existing notification badges, inbox panels, toasts that represent durable in-app items, unread count queries, mark-read actions, and delivery modules.
+- Imports from @contractspec/module.notifications that should migrate to @contractspec/lib.contracts-spec/notifications or @contractspec/lib.notification.
+- Any duplicated navigation arrays, route labels, icon maps, access-control checks, and active-state logic.
+- Any in-page summary/table-of-contents components that should become PageOutline data.
+- Web-only assumptions that would block Expo/React Native adaptation.
+
+Refactor plan:
+1. Define a single typed navigation source for primary nav, grouped sidebar nav, nested children, labels, icons, badges, disabled states, and permissions.
+2. Map existing command/search behavior into grouped command actions with search text and quick actions.
+3. Map existing route metadata into breadcrumbs.
+4. Move canonical notification contracts to @contractspec/lib.contracts-spec/notifications and reusable helpers to @contractspec/lib.notification; keep the old module shim only for compatibility imports that still need the legacy module id.
+5. Convert notification query results into ShellNotificationCenter items with unreadCount, loading, empty state, onSelect, onMarkRead, and onMarkAllRead callbacks.
+6. Convert page table-of-contents or section summary data into PageOutline items with a maximum of three levels.
+7. Wrap app routes in AppShell while keeping page content components route-local.
+8. Move primary mobile destinations into bottom navigation and deeper/account/notification actions into a menu or drawer.
+9. Add or preserve .native.tsx adapters when the app targets Expo.
+
+Preserve behavior:
+- Existing route URLs and access rules.
+- Existing keyboard shortcuts where they are public behavior.
+- Existing analytics or telemetry events on navigation and command actions.
+- Existing notification delivery semantics, unread count semantics, deep links, and mark-read behavior.
+- Existing auth/logout behavior.
+- Existing responsive breakpoints unless there is a documented design-system breakpoint to adopt.
+
+Quality gates:
+- Add regression tests around current visible navigation before removing old shell code when coverage is missing.
+- Test active nav state, nested nav expansion, command search/action invocation, breadcrumbs, notification unread badge/loading/empty/callback behavior, auth menu, mobile bottom navigation, and PageOutline anchor behavior.
+- Run lint, typecheck, and the app's relevant test/build command.
+- Remove dead app-specific shell components only after the shared shell path is verified.
+
+Output:
+- List old shell files removed or simplified.
+- List new shared shell integration points.
+- Include before/after route coverage and verification commands.`;
+
+export const notificationGuide = [
+	{
+		title: 'Contracts stay canonical',
+		body: 'Use @contractspec/lib.contracts-spec/notifications for operation models, feature metadata, and contract-level compatibility.',
+	},
+	{
+		title: 'Runtime helpers stay reusable',
+		body: 'Use @contractspec/lib.notification for schema contribution, channel adapters, templates, and i18n without importing the deprecated module shim in new code.',
+	},
+	{
+		title: 'Apps own live state',
+		body: 'Fetch, subscribe, persist, mutate, and reconcile notification state in the host app or runtime layer where auth and tenancy are known.',
+	},
+	{
+		title: 'Shell receives view state',
+		body: 'Pass AppShell a ShellNotificationCenter with render-ready items, counts, loading state, and callbacks; the design system only renders affordances.',
+	},
+] as const;
+
+export const shellParts = [
+	{
+		title: 'Sidebar',
+		body: 'Desktop owns brand, command entry, grouped navigation, nested items, and account actions in one persistent scanning area.',
+	},
+	{
+		title: 'Topbar',
+		body: 'Breadcrumbs stay visible while the current route changes. Command search and notification affordances can live here when the sidebar is collapsed or hidden.',
+	},
+	{
+		title: 'PageOutline',
+		body: 'The right-side in-page navigator replaces ad hoc tables of contents. It supports three levels of section anchors and active state.',
+	},
+	{
+		title: 'Notifications',
+		body: 'The shell renders unread badges, item lists, loading/empty states, mark-read actions, and deep-link selection from host-owned notification state.',
+	},
+	{
+		title: 'Mobile adapters',
+		body: 'Small web and native surfaces move primary destinations to bottom navigation and reserve drawers or menus for deep navigation, notifications, and account actions.',
+	},
+] as const;