@contractspec/bundle.library 0.0.0-canary-20260206014742

package/dist/components/docs/specs/SpecsDataViewsPage.js

@@ -0,0 +1,210 @@
+import { ChevronRight } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/specs/SpecsDataViewsPage.tsx
+function SpecsDataViewsPage() {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "space-y-8",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "text-4xl font-bold",
+					children: "DataViews"
+				}), /* @__PURE__ */ jsxs("p", {
+					className: "text-muted-foreground",
+					children: [
+						"A ",
+						/* @__PURE__ */ jsx("strong", { children: "DataViewSpec" }),
+						" describes how data should be queried, filtered, sorted, and presented to users. Runtime adapters execute optimized database queries and serve list views, detail views, and search interfaces while respecting policy constraints."
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "Core concepts"
+				}), /* @__PURE__ */ jsxs("div", {
+					className: "space-y-3",
+					children: [
+						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+							className: "text-lg font-semibold",
+							children: "Data sources"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-muted-foreground",
+							children: "A DataView connects to one or more data sources—databases, APIs, or other capabilities. You specify the source and the fields you want to expose."
+						})] }),
+						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+							className: "text-lg font-semibold",
+							children: "Filtering"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-muted-foreground",
+							children: "Define filters that users can apply to narrow down results. Filters can be simple (e.g., \"status equals 'active'\") or complex (e.g., \"created within the last 30 days AND assigned to current user\")."
+						})] }),
+						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+							className: "text-lg font-semibold",
+							children: "Sorting"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-muted-foreground",
+							children: "Specify which fields can be sorted and the default sort order. ContractSpec generates efficient database queries with proper indexes."
+						})] }),
+						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+							className: "text-lg font-semibold",
+							children: "Pagination"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-muted-foreground",
+							children: "DataViews automatically support pagination to handle large datasets. You can configure page size limits and cursor-based or offset-based pagination."
+						})] }),
+						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+							className: "text-lg font-semibold",
+							children: "Aggregations"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-muted-foreground",
+							children: "Compute aggregates like counts, sums, averages, and group-by operations. These are useful for dashboards and summary views."
+						})] })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Example DataViewSpec"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Here's a DataView for listing orders in TypeScript:"
+					}),
+					/* @__PURE__ */ jsx("div", {
+						className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
+						children: /* @__PURE__ */ jsx("pre", { children: `import { defineDataView } from '@contractspec/lib.contracts';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+export const OrderList = defineDataView({
+  meta: {
+    key: 'order.list',
+    version: '1.0.0',
+    description: 'List of recent orders',
+  },
+  source: {
+    type: 'database',
+    table: 'orders',
+  },
+  fields: [
+    { name: 'orderId', type: 'uuid', sortable: true },
+    { name: 'customerName', type: 'string', searchable: true },
+    { name: 'total', type: 'number', sortable: true },
+    { 
+      name: 'status', 
+      type: 'enum', 
+      values: ['pending', 'processing', 'shipped'],
+      filterable: true 
+    },
+    { 
+      name: 'createdAt', 
+      type: 'timestamp', 
+      sortable: true, 
+      defaultSort: 'desc' 
+    },
+  ],
+  filters: [
+    { name: 'status', field: 'status', operator: 'in' },
+    { name: 'dateRange', field: 'createdAt', operator: 'between' },
+    { name: 'minTotal', field: 'total', operator: 'gte' },
+  ],
+  pagination: {
+    type: 'cursor',
+    defaultPageSize: 50,
+    maxPageSize: 200,
+  },
+});` })
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Policy integration"
+					}),
+					/* @__PURE__ */ jsxs("p", {
+						className: "text-muted-foreground",
+						children: [
+							"DataViews automatically enforce",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/specs/policy",
+								className: "text-violet-400 hover:text-violet-300",
+								children: "PolicySpecs"
+							}),
+							". If a user doesn't have permission to see certain fields, those fields are automatically filtered out or redacted. If a user can only see their own data, the query is automatically scoped."
+						]
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "This means you define the data view once, and it works correctly for all users based on their permissions—no need to write separate queries for different roles."
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Served outputs"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "From a DataViewSpec, ContractSpec serves:"
+					}),
+					/* @__PURE__ */ jsxs("ul", {
+						className: "text-muted-foreground list-inside list-disc space-y-2",
+						children: [
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Database queries" }), " – Optimized SQL or NoSQL queries executed at runtime"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "API endpoints" }), " – RESTful or GraphQL endpoints for fetching data"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "UI components" }), " – List views, tables, cards, and detail views"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Search interfaces" }), " – Full-text search with autocomplete"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Export functions" }), " – CSV, JSON, or Excel exports"] })
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "Best practices"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "text-muted-foreground list-inside list-disc space-y-2",
+					children: [
+						/* @__PURE__ */ jsx("li", { children: "Only expose fields that users actually need—this improves performance and security." }),
+						/* @__PURE__ */ jsx("li", { children: "Use appropriate indexes for sortable and filterable fields." }),
+						/* @__PURE__ */ jsx("li", { children: "Set reasonable pagination limits to prevent performance issues." }),
+						/* @__PURE__ */ jsx("li", { children: "Use aggregations sparingly—they can be expensive on large datasets." }),
+						/* @__PURE__ */ jsx("li", { children: "Test DataViews with realistic data volumes to ensure they perform well." })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-4 pt-4",
+				children: [/* @__PURE__ */ jsx(Link, {
+					href: "/docs/specs/capabilities",
+					className: "btn-ghost",
+					children: "Previous: Capabilities"
+				}), /* @__PURE__ */ jsxs(Link, {
+					href: "/docs/specs/workflows",
+					className: "btn-primary",
+					children: ["Next: Workflows ", /* @__PURE__ */ jsx(ChevronRight, { size: 16 })]
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { SpecsDataViewsPage };
+//# sourceMappingURL=SpecsDataViewsPage.js.map

package/dist/components/docs/specs/SpecsDataViewsPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecsDataViewsPage.js","names":[],"sources":["../../../../src/components/docs/specs/SpecsDataViewsPage.tsx"],"sourcesContent":["import Link from '@contractspec/lib.ui-link';\nimport { ChevronRight } from 'lucide-react';\n\n// export const metadata = {\n//   title: 'DataViews: ContractSpec Docs',\n//   description:\n//     'Learn how to define data views for querying, filtering, and presenting data in ContractSpec.',\n// };\n\nexport function SpecsDataViewsPage() {\n  return (\n    <div className=\"space-y-8\">\n      <div className=\"space-y-4\">\n        <h1 className=\"text-4xl font-bold\">DataViews</h1>\n        <p className=\"text-muted-foreground\">\n          A <strong>DataViewSpec</strong> describes how data should be queried,\n          filtered, sorted, and presented to users. Runtime adapters execute\n          optimized database queries and serve list views, detail views, and\n          search interfaces while respecting policy constraints.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Core concepts</h2>\n        <div className=\"space-y-3\">\n          <div>\n            <h3 className=\"text-lg font-semibold\">Data sources</h3>\n            <p className=\"text-muted-foreground\">\n              A DataView connects to one or more data sources—databases, APIs,\n              or other capabilities. You specify the source and the fields you\n              want to expose.\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Filtering</h3>\n            <p className=\"text-muted-foreground\">\n              Define filters that users can apply to narrow down results.\n              Filters can be simple (e.g., \"status equals 'active'\") or complex\n              (e.g., \"created within the last 30 days AND assigned to current\n              user\").\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Sorting</h3>\n            <p className=\"text-muted-foreground\">\n              Specify which fields can be sorted and the default sort order.\n              ContractSpec generates efficient database queries with proper\n              indexes.\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Pagination</h3>\n            <p className=\"text-muted-foreground\">\n              DataViews automatically support pagination to handle large\n              datasets. You can configure page size limits and cursor-based or\n              offset-based pagination.\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Aggregations</h3>\n            <p className=\"text-muted-foreground\">\n              Compute aggregates like counts, sums, averages, and group-by\n              operations. These are useful for dashboards and summary views.\n            </p>\n          </div>\n        </div>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Example DataViewSpec</h2>\n        <p className=\"text-muted-foreground\">\n          Here's a DataView for listing orders in TypeScript:\n        </p>\n        <div className=\"bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm\">\n          <pre>{`import { defineDataView } from '@contractspec/lib.contracts';\nimport { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';\n\nexport const OrderList = defineDataView({\n  meta: {\n    key: 'order.list',\n    version: '1.0.0',\n    description: 'List of recent orders',\n  },\n  source: {\n    type: 'database',\n    table: 'orders',\n  },\n  fields: [\n    { name: 'orderId', type: 'uuid', sortable: true },\n    { name: 'customerName', type: 'string', searchable: true },\n    { name: 'total', type: 'number', sortable: true },\n    { \n      name: 'status', \n      type: 'enum', \n      values: ['pending', 'processing', 'shipped'],\n      filterable: true \n    },\n    { \n      name: 'createdAt', \n      type: 'timestamp', \n      sortable: true, \n      defaultSort: 'desc' \n    },\n  ],\n  filters: [\n    { name: 'status', field: 'status', operator: 'in' },\n    { name: 'dateRange', field: 'createdAt', operator: 'between' },\n    { name: 'minTotal', field: 'total', operator: 'gte' },\n  ],\n  pagination: {\n    type: 'cursor',\n    defaultPageSize: 50,\n    maxPageSize: 200,\n  },\n});`}</pre>\n        </div>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Policy integration</h2>\n        <p className=\"text-muted-foreground\">\n          DataViews automatically enforce{' '}\n          <Link\n            href=\"/docs/specs/policy\"\n            className=\"text-violet-400 hover:text-violet-300\"\n          >\n            PolicySpecs\n          </Link>\n          . If a user doesn't have permission to see certain fields, those\n          fields are automatically filtered out or redacted. If a user can only\n          see their own data, the query is automatically scoped.\n        </p>\n        <p className=\"text-muted-foreground\">\n          This means you define the data view once, and it works correctly for\n          all users based on their permissions—no need to write separate queries\n          for different roles.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Served outputs</h2>\n        <p className=\"text-muted-foreground\">\n          From a DataViewSpec, ContractSpec serves:\n        </p>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Database queries</strong> – Optimized SQL or NoSQL queries\n            executed at runtime\n          </li>\n          <li>\n            <strong>API endpoints</strong> – RESTful or GraphQL endpoints for\n            fetching data\n          </li>\n          <li>\n            <strong>UI components</strong> – List views, tables, cards, and\n            detail views\n          </li>\n          <li>\n            <strong>Search interfaces</strong> – Full-text search with\n            autocomplete\n          </li>\n          <li>\n            <strong>Export functions</strong> – CSV, JSON, or Excel exports\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Best practices</h2>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            Only expose fields that users actually need—this improves\n            performance and security.\n          </li>\n          <li>Use appropriate indexes for sortable and filterable fields.</li>\n          <li>\n            Set reasonable pagination limits to prevent performance issues.\n          </li>\n          <li>\n            Use aggregations sparingly—they can be expensive on large datasets.\n          </li>\n          <li>\n            Test DataViews with realistic data volumes to ensure they perform\n            well.\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"flex items-center gap-4 pt-4\">\n        <Link href=\"/docs/specs/capabilities\" className=\"btn-ghost\">\n          Previous: Capabilities\n        </Link>\n        <Link href=\"/docs/specs/workflows\" className=\"btn-primary\">\n          Next: Workflows <ChevronRight size={16} />\n        </Link>\n      </div>\n    </div>\n  );\n}\n"],"mappings":";;;;;AASA,SAAgB,qBAAqB;AACnC,QACE,qBAAC;EAAI,WAAU;;GACb,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAc,EACjD,qBAAC;KAAE,WAAU;;MAAwB;MACjC,oBAAC,sBAAO,iBAAqB;;;MAI7B;KACA;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAkB,EACrD,qBAAC;KAAI,WAAU;;MACb,qBAAC,oBACC,oBAAC;OAAG,WAAU;iBAAwB;QAAiB,EACvD,oBAAC;OAAE,WAAU;iBAAwB;QAIjC,IACA;MACN,qBAAC,oBACC,oBAAC;OAAG,WAAU;iBAAwB;QAAc,EACpD,oBAAC;OAAE,WAAU;iBAAwB;QAKjC,IACA;MACN,qBAAC,oBACC,oBAAC;OAAG,WAAU;iBAAwB;QAAY,EAClD,oBAAC;OAAE,WAAU;iBAAwB;QAIjC,IACA;MACN,qBAAC,oBACC,oBAAC;OAAG,WAAU;iBAAwB;QAAe,EACrD,oBAAC;OAAE,WAAU;iBAAwB;QAIjC,IACA;MACN,qBAAC,oBACC,oBAAC;OAAG,WAAU;iBAAwB;QAAiB,EACvD,oBAAC;OAAE,WAAU;iBAAwB;QAGjC,IACA;;MACF;KACF;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAyB;KAC5D,oBAAC;MAAE,WAAU;gBAAwB;OAEjC;KACJ,oBAAC;MAAI,WAAU;gBACb,oBAAC,mBAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCL;OACG;;KACF;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAuB;KAC1D,qBAAC;MAAE,WAAU;;OAAwB;OACH;OAChC,oBAAC;QACC,MAAK;QACL,WAAU;kBACX;SAEM;;;OAIL;KACJ,oBAAC;MAAE,WAAU;gBAAwB;OAIjC;;KACA;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAmB;KACtD,oBAAC;MAAE,WAAU;gBAAwB;OAEjC;KACJ,qBAAC;MAAG,WAAU;;OACZ,qBAAC,mBACC,oBAAC,sBAAO,qBAAyB,6DAE9B;OACL,qBAAC,mBACC,oBAAC,sBAAO,kBAAsB,yDAE3B;OACL,qBAAC,mBACC,oBAAC,sBAAO,kBAAsB,sDAE3B;OACL,qBAAC,mBACC,oBAAC,sBAAO,sBAA0B,6CAE/B;OACL,qBAAC,mBACC,oBAAC,sBAAO,qBAAyB,sCAC9B;;OACF;;KACD;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAmB,EACtD,qBAAC;KAAG,WAAU;;MACZ,oBAAC,kBAAG,wFAGC;MACL,oBAAC,kBAAG,gEAAgE;MACpE,oBAAC,kBAAG,oEAEC;MACL,oBAAC,kBAAG,wEAEC;MACL,oBAAC,kBAAG,4EAGC;;MACF;KACD;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAK,MAAK;KAA2B,WAAU;eAAY;MAErD,EACP,qBAAC;KAAK,MAAK;KAAwB,WAAU;gBAAc,oBACzC,oBAAC,gBAAa,MAAM,KAAM;MACrC;KACH;;GACF"}

package/dist/components/docs/specs/SpecsOverlaysPage.d.ts

@@ -0,0 +1,7 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/docs/specs/SpecsOverlaysPage.d.ts
+declare function SpecsOverlaysPage(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { SpecsOverlaysPage };
+//# sourceMappingURL=SpecsOverlaysPage.d.ts.map

package/dist/components/docs/specs/SpecsOverlaysPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecsOverlaysPage.d.ts","names":[],"sources":["../../../../src/components/docs/specs/SpecsOverlaysPage.tsx"],"mappings":";;;iBASgB,iBAAA,CAAA,GAAiB,kBAAA,CAAA,GAAA,CAAA,OAAA"}

package/dist/components/docs/specs/SpecsOverlaysPage.js

@@ -0,0 +1,244 @@
+import { ChevronRight } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/specs/SpecsOverlaysPage.tsx
+function SpecsOverlaysPage() {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "space-y-8",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "text-4xl font-bold",
+					children: "Overlays"
+				}), /* @__PURE__ */ jsxs("p", {
+					className: "text-muted-foreground",
+					children: [
+						"An ",
+						/* @__PURE__ */ jsx("strong", { children: "OverlaySpec" }),
+						" allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities."
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Why overlays matter"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use."
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies."
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "What overlays can do"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "text-muted-foreground list-inside list-disc space-y-2",
+					children: [
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Hide or show fields" }), " – Remove fields from forms or detail views (but only if the user has permission to see them in the first place)"] }),
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Reorder fields" }), " – Change the order in which fields appear"] }),
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Rename labels" }), " – Use different terminology that's more familiar to the user"] }),
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Change layouts" }), " – Switch between list, grid, or card views"] }),
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Add help text" }), " – Provide context-specific guidance"] }),
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Set default values" }), " – Pre-fill forms with tenant-specific defaults"] }),
+						/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Apply branding" }), " – Customize colors, logos, and styling (within approved themes)"] })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Example OverlaySpec"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Here's an overlay that customizes an order form:"
+					}),
+					/* @__PURE__ */ jsx("div", {
+						className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
+						children: /* @__PURE__ */ jsx("pre", { children: `overlayId: acme-order-form
+version: '1.0.0'.0.0
+appliesTo:
+  capability: createOrder
+  tenantId: acme-corp
+  
+modifications:
+  - type: hideField
+    field: internalNotes
+    reason: "ACME doesn't use internal notes"
+    
+  - type: renameLabel
+    field: customerReference
+    newLabel: "PO Number"
+    
+  - type: reorderFields
+    fields:
+      - customerReference
+      - items
+      - shippingAddress
+      - billingAddress
+      - paymentMethod
+      
+  - type: setDefault
+    field: paymentMethod
+    value: "net30"
+    
+  - type: addHelpText
+    field: customerReference
+    text: "Enter your purchase order number from your procurement system"
+    
+  - type: makeRequired
+    field: customerReference
+    
+signature:
+  algorithm: EdDSA
+  publicKey: "acme-corp-overlay-key"
+  signature: "base64-encoded-signature"` })
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Safety guarantees"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:"
+					}),
+					/* @__PURE__ */ jsxs("ul", {
+						className: "text-muted-foreground list-inside list-disc space-y-2",
+						children: [
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Overlays cannot grant new permissions" }), " – They can only hide or rearrange what the user is already allowed to see"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Overlays cannot bypass validation" }), " – Field types, constraints, and business rules from the underlying spec still apply"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Overlays must be signed" }), " – Only authorized parties (typically tenant admins) can create overlays"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Overlays are versioned" }), " – Changes to overlays are tracked and can be rolled back"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Overlays are audited" }), " – Every overlay application is logged"] })
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Creating overlays"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Overlays can be created through:"
+					}),
+					/* @__PURE__ */ jsxs("ul", {
+						className: "text-muted-foreground list-inside list-disc space-y-2",
+						children: [
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Visual editor" }), " – A drag-and-drop interface for non-technical users"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "TypeScript/JSON" }), " – For developers who prefer code"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "API" }), " – Programmatically create overlays for automation"] })
+						]
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay."
+					}),
+					/* @__PURE__ */ jsxs("p", {
+						className: "text-muted-foreground",
+						children: [
+							"See",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/libraries/overlay-engine",
+								className: "text-violet-400 underline",
+								children: "Overlay Engine docs"
+							}),
+							" ",
+							"and the",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/advanced/overlay-editor",
+								className: "text-violet-400 underline",
+								children: "Overlay Editor guide"
+							}),
+							" ",
+							"for end-to-end workflows."
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Overlay scope"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Overlays can be scoped to:"
+					}),
+					/* @__PURE__ */ jsxs("ul", {
+						className: "text-muted-foreground list-inside list-disc space-y-2",
+						children: [
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Tenant" }), " – All users in a tenant see the same overlay"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "User" }), " – Individual users can have personal overlays"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Role" }), " – All users with a specific role see the overlay"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Device" }), " – Different overlays for mobile vs desktop"] })
+						]
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays)."
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "Best practices"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "text-muted-foreground list-inside list-disc space-y-2",
+					children: [
+						/* @__PURE__ */ jsx("li", { children: "Start with the default UI and only create overlays when users request specific changes." }),
+						/* @__PURE__ */ jsx("li", { children: "Document why each overlay modification was made—this helps when reviewing or updating overlays." }),
+						/* @__PURE__ */ jsx("li", { children: "Test overlays thoroughly to ensure they don't break workflows or confuse users." }),
+						/* @__PURE__ */ jsx("li", { children: "Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences." }),
+						/* @__PURE__ */ jsx("li", { children: "Regularly review overlays to remove ones that are no longer needed." }),
+						/* @__PURE__ */ jsx("li", { children: "Protect overlay signing keys carefully—they control what customizations are allowed." })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-4 pt-4",
+				children: [/* @__PURE__ */ jsx(Link, {
+					href: "/docs/specs/policy",
+					className: "btn-ghost",
+					children: "Previous: Policy"
+				}), /* @__PURE__ */ jsxs(Link, {
+					href: "/docs/safety",
+					className: "btn-primary",
+					children: ["Next: Safety ", /* @__PURE__ */ jsx(ChevronRight, { size: 16 })]
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { SpecsOverlaysPage };
+//# sourceMappingURL=SpecsOverlaysPage.js.map

package/dist/components/docs/specs/SpecsOverlaysPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecsOverlaysPage.js","names":[],"sources":["../../../../src/components/docs/specs/SpecsOverlaysPage.tsx"],"sourcesContent":["import Link from '@contractspec/lib.ui-link';\nimport { ChevronRight } from 'lucide-react';\n\n// export const metadata = {\n//   title: 'Overlays: ContractSpec Docs',\n//   description:\n//     'Learn how OverlaySpecs enable safe, signed customization of UI layouts and field visibility in ContractSpec.',\n// };\n\nexport function SpecsOverlaysPage() {\n  return (\n    <div className=\"space-y-8\">\n      <div className=\"space-y-4\">\n        <h1 className=\"text-4xl font-bold\">Overlays</h1>\n        <p className=\"text-muted-foreground\">\n          An <strong>OverlaySpec</strong> allows tenants or users to customize\n          UI layouts and field visibility without modifying the underlying\n          application code. Overlays are cryptographically signed to ensure they\n          respect policy boundaries and cannot introduce security\n          vulnerabilities.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Why overlays matter</h2>\n        <p className=\"text-muted-foreground\">\n          Different users have different needs. A power user might want to see\n          all available fields and actions, while a casual user prefers a\n          simplified interface. A tenant in a multi-tenant application might\n          want to brand the UI or hide features they don't use.\n        </p>\n        <p className=\"text-muted-foreground\">\n          Traditional approaches require either building multiple UIs or adding\n          complex configuration logic throughout the codebase. OverlaySpecs\n          provide a safer, more maintainable solution: users can customize their\n          experience, but only within the bounds allowed by the underlying specs\n          and policies.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">What overlays can do</h2>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Hide or show fields</strong> – Remove fields from forms or\n            detail views (but only if the user has permission to see them in the\n            first place)\n          </li>\n          <li>\n            <strong>Reorder fields</strong> – Change the order in which fields\n            appear\n          </li>\n          <li>\n            <strong>Rename labels</strong> – Use different terminology that's\n            more familiar to the user\n          </li>\n          <li>\n            <strong>Change layouts</strong> – Switch between list, grid, or card\n            views\n          </li>\n          <li>\n            <strong>Add help text</strong> – Provide context-specific guidance\n          </li>\n          <li>\n            <strong>Set default values</strong> – Pre-fill forms with\n            tenant-specific defaults\n          </li>\n          <li>\n            <strong>Apply branding</strong> – Customize colors, logos, and\n            styling (within approved themes)\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Example OverlaySpec</h2>\n        <p className=\"text-muted-foreground\">\n          Here's an overlay that customizes an order form:\n        </p>\n        <div className=\"bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm\">\n          <pre>{`overlayId: acme-order-form\nversion: '1.0.0'.0.0\nappliesTo:\n  capability: createOrder\n  tenantId: acme-corp\n  \nmodifications:\n  - type: hideField\n    field: internalNotes\n    reason: \"ACME doesn't use internal notes\"\n    \n  - type: renameLabel\n    field: customerReference\n    newLabel: \"PO Number\"\n    \n  - type: reorderFields\n    fields:\n      - customerReference\n      - items\n      - shippingAddress\n      - billingAddress\n      - paymentMethod\n      \n  - type: setDefault\n    field: paymentMethod\n    value: \"net30\"\n    \n  - type: addHelpText\n    field: customerReference\n    text: \"Enter your purchase order number from your procurement system\"\n    \n  - type: makeRequired\n    field: customerReference\n    \nsignature:\n  algorithm: EdDSA\n  publicKey: \"acme-corp-overlay-key\"\n  signature: \"base64-encoded-signature\"`}</pre>\n        </div>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Safety guarantees</h2>\n        <p className=\"text-muted-foreground\">\n          Overlays are powerful, but they must not compromise security or data\n          integrity. ContractSpec enforces several guarantees:\n        </p>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Overlays cannot grant new permissions</strong> – They can\n            only hide or rearrange what the user is already allowed to see\n          </li>\n          <li>\n            <strong>Overlays cannot bypass validation</strong> – Field types,\n            constraints, and business rules from the underlying spec still apply\n          </li>\n          <li>\n            <strong>Overlays must be signed</strong> – Only authorized parties\n            (typically tenant admins) can create overlays\n          </li>\n          <li>\n            <strong>Overlays are versioned</strong> – Changes to overlays are\n            tracked and can be rolled back\n          </li>\n          <li>\n            <strong>Overlays are audited</strong> – Every overlay application is\n            logged\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Creating overlays</h2>\n        <p className=\"text-muted-foreground\">\n          Overlays can be created through:\n        </p>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Visual editor</strong> – A drag-and-drop interface for\n            non-technical users\n          </li>\n          <li>\n            <strong>TypeScript/JSON</strong> – For developers who prefer code\n          </li>\n          <li>\n            <strong>API</strong> – Programmatically create overlays for\n            automation\n          </li>\n        </ul>\n        <p className=\"text-muted-foreground\">\n          Once created, overlays must be signed using a private key. The\n          corresponding public key is registered with ContractSpec, which\n          verifies the signature before applying the overlay.\n        </p>\n        <p className=\"text-muted-foreground\">\n          See{' '}\n          <Link\n            href=\"/docs/libraries/overlay-engine\"\n            className=\"text-violet-400 underline\"\n          >\n            Overlay Engine docs\n          </Link>{' '}\n          and the{' '}\n          <Link\n            href=\"/docs/advanced/overlay-editor\"\n            className=\"text-violet-400 underline\"\n          >\n            Overlay Editor guide\n          </Link>{' '}\n          for end-to-end workflows.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Overlay scope</h2>\n        <p className=\"text-muted-foreground\">Overlays can be scoped to:</p>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Tenant</strong> – All users in a tenant see the same overlay\n          </li>\n          <li>\n            <strong>User</strong> – Individual users can have personal overlays\n          </li>\n          <li>\n            <strong>Role</strong> – All users with a specific role see the\n            overlay\n          </li>\n          <li>\n            <strong>Device</strong> – Different overlays for mobile vs desktop\n          </li>\n        </ul>\n        <p className=\"text-muted-foreground\">\n          If multiple overlays apply to the same user, they are merged in order\n          of specificity (user overlays override role overlays, which override\n          tenant overlays).\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Best practices</h2>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            Start with the default UI and only create overlays when users\n            request specific changes.\n          </li>\n          <li>\n            Document why each overlay modification was made—this helps when\n            reviewing or updating overlays.\n          </li>\n          <li>\n            Test overlays thoroughly to ensure they don't break workflows or\n            confuse users.\n          </li>\n          <li>\n            Use tenant-level overlays for organizational customizations and\n            user-level overlays for personal preferences.\n          </li>\n          <li>\n            Regularly review overlays to remove ones that are no longer needed.\n          </li>\n          <li>\n            Protect overlay signing keys carefully—they control what\n            customizations are allowed.\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"flex items-center gap-4 pt-4\">\n        <Link href=\"/docs/specs/policy\" className=\"btn-ghost\">\n          Previous: Policy\n        </Link>\n        <Link href=\"/docs/safety\" className=\"btn-primary\">\n          Next: Safety <ChevronRight size={16} />\n        </Link>\n      </div>\n    </div>\n  );\n}\n"],"mappings":";;;;;AASA,SAAgB,oBAAoB;AAClC,QACE,qBAAC;EAAI,WAAU;;GACb,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAa,EAChD,qBAAC;KAAE,WAAU;;MAAwB;MAChC,oBAAC,sBAAO,gBAAoB;;;MAK7B;KACA;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAwB;KAC3D,oBAAC;MAAE,WAAU;gBAAwB;OAKjC;KACJ,oBAAC;MAAE,WAAU;gBAAwB;OAMjC;;KACA;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAyB,EAC5D,qBAAC;KAAG,WAAU;;MACZ,qBAAC,mBACC,oBAAC,sBAAO,wBAA4B,wHAGjC;MACL,qBAAC,mBACC,oBAAC,sBAAO,mBAAuB,kDAE5B;MACL,qBAAC,mBACC,oBAAC,sBAAO,kBAAsB,qEAE3B;MACL,qBAAC,mBACC,oBAAC,sBAAO,mBAAuB,mDAE5B;MACL,qBAAC,mBACC,oBAAC,sBAAO,kBAAsB,4CAC3B;MACL,qBAAC,mBACC,oBAAC,sBAAO,uBAA2B,uDAEhC;MACL,qBAAC,mBACC,oBAAC,sBAAO,mBAAuB,wEAE5B;;MACF;KACD;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAwB;KAC3D,oBAAC;MAAE,WAAU;gBAAwB;OAEjC;KACJ,oBAAC;MAAI,WAAU;gBACb,oBAAC,mBAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAqC+B;OACjC;;KACF;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAsB;KACzD,oBAAC;MAAE,WAAU;gBAAwB;OAGjC;KACJ,qBAAC;MAAG,WAAU;;OACZ,qBAAC,mBACC,oBAAC,sBAAO,0CAA8C,kFAEnD;OACL,qBAAC,mBACC,oBAAC,sBAAO,sCAA0C,4FAE/C;OACL,qBAAC,mBACC,oBAAC,sBAAO,4BAAgC,gFAErC;OACL,qBAAC,mBACC,oBAAC,sBAAO,2BAA+B,iEAEpC;OACL,qBAAC,mBACC,oBAAC,sBAAO,yBAA6B,8CAElC;;OACF;;KACD;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAsB;KACzD,oBAAC;MAAE,WAAU;gBAAwB;OAEjC;KACJ,qBAAC;MAAG,WAAU;;OACZ,qBAAC,mBACC,oBAAC,sBAAO,kBAAsB,4DAE3B;OACL,qBAAC,mBACC,oBAAC,sBAAO,oBAAwB,yCAC7B;OACL,qBAAC,mBACC,oBAAC,sBAAO,QAAY,0DAEjB;;OACF;KACL,oBAAC;MAAE,WAAU;gBAAwB;OAIjC;KACJ,qBAAC;MAAE,WAAU;;OAAwB;OAC/B;OACJ,oBAAC;QACC,MAAK;QACL,WAAU;kBACX;SAEM;OAAC;OAAI;OACJ;OACR,oBAAC;QACC,MAAK;QACL,WAAU;kBACX;SAEM;OAAC;OAAI;;OAEV;;KACA;GAEN,qBAAC;IAAI,WAAU;;KACb,oBAAC;MAAG,WAAU;gBAAqB;OAAkB;KACrD,oBAAC;MAAE,WAAU;gBAAwB;OAA8B;KACnE,qBAAC;MAAG,WAAU;;OACZ,qBAAC,mBACC,oBAAC,sBAAO,WAAe,qDACpB;OACL,qBAAC,mBACC,oBAAC,sBAAO,SAAa,sDAClB;OACL,qBAAC,mBACC,oBAAC,sBAAO,SAAa,yDAElB;OACL,qBAAC,mBACC,oBAAC,sBAAO,WAAe,mDACpB;;OACF;KACL,oBAAC;MAAE,WAAU;gBAAwB;OAIjC;;KACA;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAmB,EACtD,qBAAC;KAAG,WAAU;;MACZ,oBAAC,kBAAG,4FAGC;MACL,oBAAC,kBAAG,oGAGC;MACL,oBAAC,kBAAG,oFAGC;MACL,oBAAC,kBAAG,kHAGC;MACL,oBAAC,kBAAG,wEAEC;MACL,oBAAC,kBAAG,yFAGC;;MACF;KACD;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAK,MAAK;KAAqB,WAAU;eAAY;MAE/C,EACP,qBAAC;KAAK,MAAK;KAAe,WAAU;gBAAc,iBACnC,oBAAC,gBAAa,MAAM,KAAM;MAClC;KACH;;GACF"}

package/dist/components/docs/specs/SpecsOverviewPage.d.ts

@@ -0,0 +1,7 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/docs/specs/SpecsOverviewPage.d.ts
+declare function SpecsOverviewPage(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { SpecsOverviewPage };
+//# sourceMappingURL=SpecsOverviewPage.d.ts.map

package/dist/components/docs/specs/SpecsOverviewPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecsOverviewPage.d.ts","names":[],"sources":["../../../../src/components/docs/specs/SpecsOverviewPage.tsx"],"mappings":";;;iBASgB,iBAAA,CAAA,GAAiB,kBAAA,CAAA,GAAA,CAAA,OAAA"}