@contractspec/bundle.library 3.9.7 → 3.9.9

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

@@ -0,0 +1,145 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import { Box, HStack, VStack } from '@contractspec/lib.design-system/layout';
+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 {
+	notificationCenterExample,
+	notificationGuide,
+	refactorPrompt,
+	scratchPrompt,
+	shellParts,
+	shellUsageExample,
+} from './LibrariesApplicationShellPage.content';
+
+export function LibrariesApplicationShellPage() {
+	return (
+		<VStack className="space-y-8">
+			<VStack className="space-y-4">
+				<H1 className="font-bold text-4xl">Application shell</H1>
+				<P className="text-lg text-muted-foreground">
+					A reusable navigation system for product apps: desktop sidebar, topbar
+					breadcrumbs, command search, account actions, mobile adapters, and a
+					Notion-style <Code>PageOutline</Code> for page sections, with
+					prop-driven in-app notifications for web and native shells.
+				</P>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Installation</H2>
+				<InstallCommand package="@contractspec/lib.design-system" />
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">What It Standardizes</H2>
+				<Box className="grid gap-4 md:grid-cols-2">
+					{shellParts.map((part) => (
+						<Box key={part.title} className="card-subtle p-4">
+							<H3 className="font-semibold">{part.title}</H3>
+							<P className="mt-2 text-muted-foreground text-sm leading-7">
+								{part.body}
+							</P>
+						</Box>
+					))}
+				</Box>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Import Surface</H2>
+				<P className="text-muted-foreground">
+					The shell is exposed as a focused design-system subpath so apps can
+					adopt navigation chrome without pulling unrelated documentation or
+					marketing helpers.
+				</P>
+				<CodeBlock
+					language="tsx"
+					filename="app-shell-example.tsx"
+					code={shellUsageExample}
+				/>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">Notification Center Boundary</H2>
+				<P className="text-muted-foreground">
+					Notifications are part of the shell experience, but the design system
+					only renders the affordance. Contracts, runtime helpers, persistence,
+					delivery, auth, and subscriptions stay outside the shell and feed a
+					render-ready <Code>ShellNotificationCenter</Code> into{' '}
+					<Code>AppShell</Code>.
+				</P>
+				<Box className="grid gap-4 md:grid-cols-2">
+					{notificationGuide.map((part) => (
+						<Box key={part.title} className="card-subtle p-4">
+							<H3 className="font-semibold">{part.title}</H3>
+							<P className="mt-2 text-muted-foreground text-sm leading-7">
+								{part.body}
+							</P>
+						</Box>
+					))}
+				</Box>
+				<CodeBlock
+					language="tsx"
+					filename="notification-center-boundary.ts"
+					code={notificationCenterExample}
+				/>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">AI Prompt: Build From Scratch</H2>
+				<P className="text-muted-foreground">
+					Use this prompt when the app does not already have a shell, command
+					surface, page outline, or in-app notification center.
+				</P>
+				<CodeBlock
+					language="markdown"
+					filename="implement-application-shell.md"
+					code={scratchPrompt}
+				/>
+			</VStack>
+
+			<VStack className="space-y-4">
+				<H2 className="font-bold text-2xl">AI Prompt: Refactor An App</H2>
+				<P className="text-muted-foreground">
+					Use this prompt when an app already has custom navigation chrome and
+					notification UI that need to migrate without breaking route behavior,
+					unread counts, or delivery semantics.
+				</P>
+				<CodeBlock
+					language="markdown"
+					filename="refactor-to-application-shell.md"
+					code={refactorPrompt}
+				/>
+			</VStack>
+
+			<VStack className="card-subtle space-y-3 p-6">
+				<H2 className="font-bold text-2xl">Naming</H2>
+				<P className="text-muted-foreground">
+					Use <Code>AppShell</Code> for the whole navigation frame and{' '}
+					<Code>PageOutline</Code> for the in-page navigation helper. The latter
+					is the product-app equivalent of a table of contents, but it is
+					intentionally named for live page sections rather than static
+					documentation. Use <Code>ShellNotifications</Code> for the
+					notification affordance when it is rendered directly, or pass the same
+					data contract through <Code>AppShell</Code> with the{' '}
+					<Code>notifications</Code> prop.
+				</P>
+			</VStack>
+
+			<HStack className="flex flex-wrap items-center gap-3 pt-2">
+				<Link href="/docs/libraries/cross-platform-ui" className="btn-ghost">
+					<Text>Cross-platform UI</Text>
+				</Link>
+				<Link href="/docs/libraries/design-system" className="btn-primary">
+					<Text>Design System</Text> <ChevronRight size={16} />
+				</Link>
+			</HStack>
+		</VStack>
+	);
+}

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,59 +183,150 @@ 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 filters change.
-					</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>
-				</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';
 
 const generator = new DataViewQueryGenerator(MyUserList);
-const query = generator.generate({
+const params = {
   pagination: { page: 1, pageSize: 20 },
-  filters: { role: 'admin' }
-});
+  filters: {
+    role: { kind: 'single', value: 'admin' },
+    revenue: { kind: 'range', from: 1000, to: 5000 },
+    lastSeenAt: { kind: 'single', value: '2026-04-28T08:30:00Z' }
+  }
+};
+
+const errors = generator.validateParams(params);
+const query = generator.generate(params);
 
-// query.input contains { skip: 0, take: 20, role: 'admin' }`}
+// 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>
 	);
 }