@contractspec/bundle.library 3.9.5 → 3.9.7

package/src/components/docs/generated/docs-index.workspace-cli.json

@@ -1,10 +1,10 @@
 [
-	{
-		"id": "workspace-cli/workspace-cli",
-		"title": "workspace-cli",
-		"summary": "Core CLI operations for managing ContractSpec workspaces\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: @lssm/core\n- **Tags**: cli, core\n- **File**: `packages/bundles/workspace/src/contracts/features/cli.feature.ts`",
-		"route": "/docs/reference/workspace-cli/workspace-cli",
-		"source": "generated",
-		"contentPath": "workspace-cli/workspace-cli.md"
-	}
-]
+  {
+    "id": "workspace-cli/workspace-cli",
+    "title": "workspace-cli",
+    "summary": "Core CLI operations for managing ContractSpec workspaces\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: stable\n- **Owners**: @lssm/core\n- **Tags**: cli, core\n- **File**: `packages/bundles/workspace/src/contracts/features/cli.feature.ts`",
+    "route": "/docs/reference/workspace-cli/workspace-cli",
+    "source": "generated",
+    "contentPath": "workspace-cli/workspace-cli.md"
+  }
+]

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

@@ -0,0 +1,98 @@
+export const leadCaptureFormCode = `import {
+  defineFormSpec,
+  FormRegistry,
+  responsiveFormColumns,
+} from "@contractspec/lib.contracts-spec/forms";
+import { fromZod } from "@contractspec/lib.schema";
+import { z } from "zod";
+
+const LeadCaptureModel = fromZod(
+  z.object({
+    fullName: z.string().min(1),
+    email: z.string().email(),
+    company: z.string().min(1),
+    intent: z.enum(["demo", "pricing", "pilot"]),
+    notes: z.string().max(1000).optional(),
+    newsletter: z.boolean().optional(),
+  }),
+  { name: "LeadCaptureModel" },
+);
+
+export const LeadCaptureForm = defineFormSpec({
+  meta: {
+    key: "marketing.lead.form",
+    version: "1.0.0",
+    title: "Lead capture form",
+    description: "Collect qualified OSS and Studio leads.",
+    domain: "marketing",
+    owners: ["@growth"],
+    tags: ["forms", "leads"],
+    stability: "experimental",
+  },
+  model: LeadCaptureModel,
+  layout: {
+    columns: responsiveFormColumns(2),
+    gap: "md",
+    flow: {
+      kind: "sections",
+      sections: [
+        { key: "identity", titleI18n: "Who you are", fieldNames: ["fullName", "email", "company"] },
+        { key: "request", titleI18n: "What you need", fieldNames: ["intent", "notes", "newsletter"] },
+      ],
+    },
+  },
+  fields: [
+    { kind: "text", name: "fullName", labelI18n: "Full name", required: true, autoComplete: "name" },
+    { kind: "email", name: "email", labelI18n: "Work email", required: true, autoComplete: "email" },
+    { kind: "text", name: "company", labelI18n: "Company", required: true, autoComplete: "organization" },
+    {
+      kind: "select",
+      name: "intent",
+      labelI18n: "Primary goal",
+      required: true,
+      options: [
+        { labelI18n: "Book a demo", value: "demo" },
+        { labelI18n: "Understand pricing", value: "pricing" },
+        { labelI18n: "Plan a pilot", value: "pilot" },
+      ],
+    },
+    { kind: "textarea", name: "notes", labelI18n: "Context", rows: 4, layout: { colSpan: "full" } },
+    { kind: "checkbox", name: "newsletter", labelI18n: "Send product updates" },
+  ],
+  actions: [{ key: "submit", labelI18n: "Send request", op: { name: "lead.create", version: "1.0.0" } }],
+  policy: { flags: ["lead-capture"], pii: ["fullName", "email", "company", "notes"] },
+  renderHints: { ui: "shadcn", form: "react-hook-form" },
+});
+
+export const formRegistry = new FormRegistry().register(LeadCaptureForm);`;
+
+export const leadCapturePanelCode = `"use client";
+
+import { formRenderer } from "@contractspec/lib.design-system/renderers/form-contract";
+import { LeadCaptureForm } from "../contracts/forms/lead-capture.form";
+
+export function LeadCapturePanel() {
+  return formRenderer.render(LeadCaptureForm, {
+    defaultValues: { newsletter: true },
+    overrides: {
+      onSubmitOverride: async (values, actionKey) => {
+        await fetch("/api/leads", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ actionKey, values }),
+        });
+      },
+    },
+  });
+}`;
+
+export const formShowcaseTemplateCode = `bun add @contractspec/example.form-showcase
+
+# Full form-only example docs
+open https://www.contractspec.io/docs/examples/form-showcase
+
+# Template catalog filtered to forms
+open https://www.contractspec.io/templates?tag=forms
+
+# Sandbox spec preview
+open https://www.contractspec.io/sandbox?template=form-showcase`;

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

@@ -0,0 +1,143 @@
+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 { StudioPrompt } from '../shared/StudioPrompt';
+import {
+	formShowcaseTemplateCode,
+	leadCaptureFormCode,
+	leadCapturePanelCode,
+} from './GuideContractDrivenFormsPage.content';
+
+export function GuideContractDrivenFormsPage() {
+	return (
+		<VStack className="space-y-8">
+			<VStack className="space-y-3">
+				<H1 className="font-bold text-4xl">Build a contract-driven form</H1>
+				<P className="text-lg text-muted-foreground">
+					Define form data, fields, layout, policy, and submit behavior once,
+					then let your app render from the same ContractSpec surface.
+				</P>
+			</VStack>
+
+			<VStack className="card-subtle space-y-4 p-6">
+				<H2 className="font-bold text-2xl">What you'll build</H2>
+				<List className="space-y-2 text-muted-foreground text-sm">
+					<ListItem>
+						<Text>A schema-backed FormSpec for a lead capture form.</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							A FormRegistry that exposes the latest version by stable key.
+						</Text>
+					</ListItem>
+					<ListItem>
+						<Text>
+							A React renderer that keeps UI, validation, and policy aligned.
+						</Text>
+					</ListItem>
+				</List>
+			</VStack>
+
+			<VStack className="space-y-6">
+				<VStack className="space-y-3">
+					<H2 className="font-bold text-2xl">1) Define the form spec</H2>
+					<P className="text-muted-foreground text-sm">
+						Create <Code>src/contracts/forms/lead-capture.form.ts</Code>:
+					</P>
+					<CodeBlock
+						language="typescript"
+						filename="src/contracts/forms/lead-capture.form.ts"
+						code={leadCaptureFormCode}
+					/>
+				</VStack>
+
+				<VStack className="card-subtle space-y-3 p-6">
+					<H3 className="font-semibold text-lg">Need every form field?</H3>
+					<P className="text-muted-foreground text-sm">
+						Start from the{' '}
+						<Link href="/docs/examples/form-showcase">
+							Form Showcase example
+						</Link>{' '}
+						or the{' '}
+						<Link href="/templates?tag=forms">form template catalog</Link>. It
+						is focused only on forms and covers field kinds, section layouts,
+						step layouts, arrays, groups, conditionals, and validation hints.
+					</P>
+					<CodeBlock
+						language="bash"
+						filename="form-showcase-template"
+						code={formShowcaseTemplateCode}
+					/>
+				</VStack>
+
+				<VStack className="space-y-3">
+					<H2 className="font-bold text-2xl">2) Render from the contract</H2>
+					<P className="text-muted-foreground text-sm">
+						Use the shared renderer, or provide your own driver if your app uses
+						a different component library.
+					</P>
+					<CodeBlock
+						language="tsx"
+						filename="src/components/LeadCapturePanel.tsx"
+						code={leadCapturePanelCode}
+					/>
+				</VStack>
+
+				<VStack className="space-y-3">
+					<H2 className="font-bold text-2xl">3) Validate and evolve</H2>
+					<CodeBlock
+						language="bash"
+						filename="validate-form"
+						code={`contractspec validate src/contracts/forms/lead-capture.form.ts`}
+					/>
+					<P className="text-muted-foreground text-sm">
+						Expected output: <Code>Validation passed</Code>. When the form
+						becomes public contract surface, version changes deliberately
+						instead of editing field meaning in place.
+					</P>
+				</VStack>
+
+				<VStack className="card-subtle space-y-3 p-6">
+					<H3 className="font-semibold text-lg">Repo tutorial</H3>
+					<P className="text-muted-foreground text-sm">
+						The repository guide adds the longer implementation checklist,
+						custom renderer notes, and rollout rules.
+					</P>
+					<CodeBlock
+						language="bash"
+						filename="repo-guide"
+						code={`open docs/tutorials/contract-driven-forms.md`}
+					/>
+				</VStack>
+
+				<StudioPrompt
+					title="Need governed form changes?"
+					body="Studio can connect form edits to customer evidence, approval packets, and rollout checks before teams regenerate public surfaces."
+				/>
+			</VStack>
+
+			<HStack className="flex items-center gap-4 pt-4">
+				<Link
+					href="/docs/guides/generate-docs-clients-schemas"
+					className="btn-primary"
+				>
+					<Text>Next: Generate docs + clients</Text>
+					<ChevronRight size={16} />
+				</Link>
+				<Link href="/docs/guides" className="btn-ghost">
+					<Text>Back to guides</Text>
+				</Link>
+			</HStack>
+		</VStack>
+	);
+}

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

@@ -144,10 +144,10 @@ bun run validate`}
 
 			<div className="flex items-center gap-4 pt-4">
 				<Link
-					href="/docs/guides/generate-docs-clients-schemas"
+					href="/docs/guides/contract-driven-forms"
 					className="btn-primary"
 				>
-					Next: Generate docs + clients <ChevronRight size={16} />
+					Next: Contract-driven forms <ChevronRight size={16} />
 				</Link>
 				<Link href="/docs/guides" className="btn-ghost">
 					Back to guides

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

@@ -24,6 +24,13 @@ const guides = [
 		href: '/docs/guides/spec-validation-and-typing',
 		time: '20 min',
 	},
+	{
+		title: 'Build a contract-driven form',
+		description:
+			'Use FormSpec to keep data shape, fields, layout, policy, and submit behavior aligned.',
+		href: '/docs/guides/contract-driven-forms',
+		time: '25 min',
+	},
 	{
 		title: 'Generate docs and clients',
 		description:

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

@@ -37,6 +37,18 @@ Create a single OperationSpec, register it, and expose it through a Next.js App
 		body: `# Spec-driven validation and typing
 
 Define command/query specs that enforce validation and generate types without rewriting your app.`,
+	},
+	{
+		id: 'docs.guides.contract-driven-forms',
+		title: 'Contract-driven forms',
+		summary: 'Define schema-backed FormSpec surfaces and render them safely.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/guides/contract-driven-forms',
+		tags: ['guides', 'forms', 'ui'],
+		body: `# Build a contract-driven form
+
+Define a FormSpec with model, fields, layout, policy, and actions, then render it through a shared or app-specific renderer.`,
 	},
 	{
 		id: 'docs.guides.docs-clients-schemas',

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

@@ -2,6 +2,7 @@ import './guides.docblocks';
 
 export { GuideCIDiffGatingPage } from './GuideCIDiffGatingPage';
 export { GuideConnectInRepoPage } from './GuideConnectInRepoPage';
+export { GuideContractDrivenFormsPage } from './GuideContractDrivenFormsPage';
 export { GuideContractTypesPage } from './GuideContractTypesPage';
 export { GuideDocsPipelinePage } from './GuideDocsPipelinePage';
 export { GuideFirstModuleBundlePage } from './GuideFirstModuleBundlePage';

package/src/libs/posthog/client.ts

@@ -29,25 +29,26 @@ const shouldCaptureAnalytics = () => {
 	return dnt !== '1' && dnt !== 'yes';
 };
 
+const isDevelopment = () => process.env.NODE_ENV === 'development';
+
 export function initPosthog() {
 	if (typeof window === 'undefined') return;
+	if (isDevelopment()) return;
 	if (!posthogKey) {
 		console.warn('[PostHog] NEXT_PUBLIC_CONTRACTSPEC_POSTHOG_KEY is missing');
 		return;
 	}
 	if (!shouldCaptureAnalytics()) return;
 
-	const isDev = process.env.NODE_ENV === 'development';
-
 	posthog.init(posthogKey, {
 		api_host: posthogHost,
-		autocapture: !isDev,
-		capture_dead_clicks: !isDev,
-		capture_performance: !isDev,
-		capture_pageview: !isDev,
-		capture_heatmaps: !isDev,
-		capture_exceptions: !isDev,
-		debug: process.env.NODE_ENV === 'development',
+		autocapture: true,
+		capture_dead_clicks: true,
+		capture_performance: true,
+		capture_pageview: true,
+		capture_heatmaps: true,
+		capture_exceptions: true,
+		debug: false,
 	});
 }
 
@@ -56,6 +57,7 @@ export function captureAnalyticsEvent(
 	properties?: Record<string, unknown>
 ) {
 	if (!posthogKey) return;
+	if (isDevelopment()) return;
 	if (!shouldCaptureAnalytics()) return;
 	try {
 		const globalPosthog = (globalThis as { posthog?: PostHogInstance }).posthog;