@contractspec/bundle.library 3.9.8 → 3.9.9

package/dist/node/components/docs/guides/GuideDataExchangeImportTemplatesPage.js

@@ -0,0 +1,175 @@
+var S=Object.defineProperty;var A=(r)=>r;function I(r,o){this[r]=A.bind(null,o)}var O=(r,o)=>{for(var m in o)S(r,m,{get:o[m],enumerable:!0,configurable:!0,set:I.bind(o,m)})};var R=(r,o)=>()=>(r&&(o=r(r=0)),o);var g=`import {
+  createImportPlan,
+  createRecordBatch,
+  defineDataExchangeTemplate,
+  previewImport,
+} from "@contractspec/lib.data-exchange-core";
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+const AccountImportSchema = defineSchemaModel({
+  name: "AccountImport",
+  fields: {
+    id: { type: ScalarTypeEnum.ID(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    amount: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    active: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    tags: { type: ScalarTypeEnum.JSON(), isOptional: true },
+  },
+});
+
+const accountImportTemplate = defineDataExchangeTemplate({
+  key: "accounts.import",
+  version: "1.0.0",
+  title: "Account import",
+  columns: [
+    {
+      key: "id",
+      label: "Account ID",
+      targetField: "id",
+      required: true,
+      sourceAliases: ["Account Identifier", "External ID", "No compte"],
+    },
+    {
+      key: "status",
+      label: "Status",
+      targetField: "status",
+      required: true,
+      sourceAliases: ["Statut", "State"],
+      format: { kind: "text", trim: true, case: "lowercase" },
+    },
+    {
+      key: "amount",
+      label: "Amount",
+      targetField: "amount",
+      required: true,
+      sourceAliases: ["Montant", "Balance"],
+      format: { kind: "number", decimalSeparator: ",", thousandsSeparator: "." },
+    },
+    {
+      key: "active",
+      label: "Active",
+      targetField: "active",
+      sourceAliases: ["Actif", "Enabled"],
+      format: { kind: "boolean", trueValues: ["yes", "oui"], falseValues: ["no", "non"] },
+    },
+    {
+      key: "tags",
+      label: "Tags",
+      targetField: "tags",
+      format: { kind: "split", delimiter: ";" },
+    },
+  ],
+});
+
+const sourceBatch = createRecordBatch([
+  {
+    "No compte": "acc-1",
+    Statut: " Active ",
+    Montant: "1.234,50",
+    Actif: "oui",
+    Tags: "vip; beta",
+  },
+]);
+
+const preview = previewImport(
+  createImportPlan({
+    source: { kind: "memory", batch: sourceBatch, format: "csv" },
+    target: { kind: "memory", format: "json" },
+    schema: AccountImportSchema,
+    sourceBatch,
+    template: accountImportTemplate,
+  }),
+);
+
+console.log(preview.plan.mappingSource); // "template"
+console.log(preview.normalizedRecords[0]);`,h=`import { defineDataExchangeTemplate } from "@contractspec/lib.data-exchange-core";
+import { dryRunImport, executeImport } from "@contractspec/lib.data-exchange-server";
+
+const template = defineDataExchangeTemplate({
+  key: "accounts.import",
+  version: "1.0.0",
+  columns: [
+    { key: "id", label: "Account ID", targetField: "id", required: true, sourceAliases: ["Account Identifier"] },
+    { key: "amount", label: "Amount", targetField: "amount", format: { kind: "currency", currencySymbol: "€", decimalSeparator: "," } },
+  ],
+});
+
+const partnerSource = {
+  kind: "file",
+  path: "partner-accounts.csv",
+  format: "csv",
+  codecOptions: { csv: { delimiter: ";", skipRows: 1 } },
+} as const;
+
+const formatProfile = {
+  columns: {
+    amount: { kind: "currency", currencySymbol: "€", decimalSeparator: "," },
+  },
+} as const;
+
+const preview = await dryRunImport({
+  source: partnerSource,
+  target: { kind: "memory", format: "json" },
+  schema: AccountImportSchema,
+  template,
+  formatProfile,
+});
+
+const blockingIssues = preview.issues.filter((issue) => issue.severity === "error");
+
+if (blockingIssues.length === 0) {
+  await executeImport({
+    source: partnerSource,
+    target: { kind: "memory", format: "json" },
+    schema: AccountImportSchema,
+    template,
+    formatProfile,
+  });
+}`,f=`"use client";
+
+import { useDataExchangeController } from "@contractspec/lib.data-exchange-client";
+
+export function ImportMappingReview({ preview }) {
+  const controller = useDataExchangeController({ preview });
+  const replacementSourceColumn = controller.model.ignoredSourceColumns[0];
+
+  return (
+    <section>
+      {controller.model.templateRows.map((row) => (
+        <button
+          key={row.id}
+          type="button"
+          disabled={!replacementSourceColumn}
+          onClick={() => {
+            if (!replacementSourceColumn) return;
+            controller.selectAlias(row.targetField, replacementSourceColumn);
+          }}
+        >
+          {row.label}: {row.sourceField || "Unmatched"} -> {row.targetField}
+          {row.required ? " required" : ""}
+          {row.formatLabel ? \` (\${row.formatLabel})\` : ""}
+        </button>
+      ))}
+      {controller.model.unmatchedRequiredRows.length > 0 ? (
+        <p>Resolve required columns before import.</p>
+      ) : null}
+    </section>
+  );
+}`,b=`You are adding an import flow to a ContractSpec app.
+
+Define a reusable data-exchange template for this canonical schema:
+- target fields, required flags, and display labels
+- known partner column aliases
+- value formats for numbers, dates, booleans, JSON, split/join lists, currency, and percentages
+
+Wire the template into core preview planning and server dry-run execution. Keep explicit mappings higher precedence than template resolution. Return the template, preview call, server dry-run call, and tests for alias matching plus localized formatting.`,y=`A partner sent a CSV/JSON/XML file that does not match our recommended import template.
+
+Compare the incoming headers and value samples against this ContractSpec data-exchange template. Propose:
+- source-to-target column matches with confidence
+- missing required target fields
+- ignored source columns
+- format overrides for localized numbers, booleans, dates, JSON, split/join lists, currency, or percentages
+
+Do not execute the import. Produce a dry-run plan and the user-facing review copy.`,v=`cd packages/libs/data-exchange-core && bun test && bun run typecheck && bun run lint:check
+cd packages/libs/data-exchange-client && bun test && bun run typecheck && bun run lint:check
+cd packages/libs/data-exchange-server && bun test && bun run typecheck && bun run lint:check`;import{CodeBlock as c}from"@contractspec/lib.design-system";import{HStack as k,VStack as a}from"@contractspec/lib.design-system/layout";import{List as s,ListItem as l}from"@contractspec/lib.design-system/list";import{Code as d,H1 as E,H2 as i,H3 as u,P as p,Text as n}from"@contractspec/lib.design-system/typography";import w from"@contractspec/lib.ui-link";import{ChevronRight as D}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";var F=["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."],q=["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"];function U(){return t(a,{className:"space-y-8",children:[t(a,{className:"space-y-3",children:[e(n,{className:"editorial-kicker",children:"Build"}),e(E,{className:"font-bold text-4xl",children:"Import flexible files with data-exchange templates"}),e(p,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"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."})]}),t(a,{className:"card-subtle space-y-4 p-6",children:[e(i,{className:"font-bold text-2xl",children:"What you'll build"}),t(s,{className:"space-y-2 text-muted-foreground text-sm",children:[e(l,{children:e(n,{children:"A canonical template with target fields, aliases, and formats."})}),e(l,{children:e(n,{children:"A dry-run import that reports confidence, gaps, and ignored columns."})}),e(l,{children:e(n,{children:"A client review state where users remap, update formats, or accept inferred mappings."})})]})]}),t(a,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"1) Define the template"}),t(p,{className:"text-muted-foreground text-sm leading-7",children:["Use ",e(d,{children:"defineDataExchangeTemplate"})," for neutral import/export naming. ",e(d,{children:"defineImportTemplate"})," and"," ",e(d,{children:"defineExportTemplate"})," remain available aliases."]}),e(c,{language:"typescript",filename:"src/data-exchange/accounts-import.ts",code:g})]}),t(a,{className:"grid gap-4 md:grid-cols-2",children:[t(a,{className:"card-subtle space-y-3 p-6",children:[e(u,{className:"font-bold text-xl",children:"Mapping precedence"}),e(s,{className:"space-y-2 text-muted-foreground text-sm",children:F.map((r)=>e(l,{children:e(n,{children:r})},r))})]}),t(a,{className:"card-subtle space-y-3 p-6",children:[e(u,{className:"font-bold text-xl",children:"Supported value formats"}),e(s,{className:"space-y-2 text-muted-foreground text-sm",children:q.map((r)=>e(l,{children:e(n,{children:r})},r))})]})]}),t(a,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"2) Dry-run partner CSV, JSON, or XML files on the server"}),e(p,{className:"text-muted-foreground text-sm leading-7",children:"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."}),e(c,{language:"typescript",filename:"src/server/import-accounts.ts",code:h})]}),t(a,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"3) Let users review the mapping"}),e(p,{className:"text-muted-foreground text-sm leading-7",children:"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."}),e(c,{language:"tsx",filename:"src/components/ImportMappingReview.tsx",code:f})]}),t(a,{className:"space-y-4",children:[e(i,{className:"font-bold text-2xl",children:"4) Verify the package stack"}),e(c,{language:"bash",filename:"verification",code:v})]}),t(a,{className:"grid gap-4 md:grid-cols-2",children:[t(a,{className:"card-subtle space-y-3 p-6",children:[e(u,{className:"font-bold text-xl",children:"Prompt: build a template"}),e(c,{language:"markdown",filename:"template-authoring.prompt.md",code:b})]}),t(a,{className:"card-subtle space-y-3 p-6",children:[e(u,{className:"font-bold text-xl",children:"Prompt: inspect a partner file"}),e(c,{language:"markdown",filename:"partner-import-review.prompt.md",code:y})]})]}),t(k,{className:"flex flex-wrap items-center gap-4 pt-4",children:[t(w,{href:"/llms/lib.data-exchange-core",className:"btn-primary",children:[e(n,{children:"Core package guide"}),e(D,{size:16})]}),e(w,{href:"/llms/lib.data-exchange-server",className:"btn-ghost",children:e(n,{children:"Server package guide"})})]})]})}export{U as GuideDataExchangeImportTemplatesPage};

package/dist/node/components/docs/guides/GuidesIndexPage.js

@@ -1,5 +1,5 @@
-var r=Object.defineProperty;var s=(t)=>t;function o(t,a){this[t]=s.bind(null,a)}var u=(t,a)=>{for(var n in a)r(t,n,{get:a[n],enumerable:!0,configurable:!0,set:o.bind(a,n)})};var f=(t,a)=>()=>(t&&(a=t(t=0)),a);import{CodeBlock as d}from"@contractspec/lib.design-system";import c from"@contractspec/lib.ui-link";import{ArrowRight as l,CheckCircle2 as m,GitBranch as p}from"lucide-react";import{jsx as e,jsxs as i}from"react/jsx-runtime";var h=[{title:"Adopt one endpoint in Next.js",description:"Start inside a live app with one operation, one generated surface, and one clearly bounded change.",href:"/docs/guides/nextjs-one-endpoint",time:"25 min"},{title:"Import an existing codebase",description:"Stabilize what already exists instead of treating adoption as a rewrite project.",href:"/docs/guides/import-existing-codebases",time:"20 min"},{title:"Validation and typing",description:"Keep runtime validation and TypeScript behavior aligned from the same source definitions.",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:"Publish stable docs, schemas, and client-facing artifacts from the contract layer.",href:"/docs/guides/generate-docs-clients-schemas",time:"20 min"},{title:"Docs pipeline",description:"Feed generated reference material into the docs site without confusing ownership.",href:"/docs/guides/docs-generation-pipeline",time:"20 min"},{title:"Build a first module bundle",description:"Define one bundle spec, resolve a surface plan, and render it through the React host layer.",href:"/docs/guides/first-module-bundle",time:"20 min"},{title:"Host the Builder workbench",description:"Wire a Builder workspace snapshot, common commands, runtime modes, and mobile review links into the reusable host.",href:"/docs/guides/host-builder-workbench",time:"20 min"},{title:"Use Connect in a repo",description:"Enable Connect, verify agent actions locally, and inspect the resulting review and replay artifacts.",href:"/docs/guides/connect-in-a-repo",time:"15 min"},{title:"Author release capsules",description:"Pair changesets with structured release capsules and generate the artifacts that changelog and upgrade flows consume.",href:"/docs/guides/release-capsules",time:"15 min"},{title:"CI diff gating",description:"Use deterministic checks to catch drift and risky changes before they ship.",href:"/docs/guides/ci-contract-diff-gating",time:"15 min"}];function y(){return i("div",{className:"space-y-10",children:[i("div",{className:"space-y-3",children:[e("p",{className:"editorial-kicker",children:"Build"}),e("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Adoption guides for teams that want to keep their code."}),e("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"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."})]}),e("div",{className:"grid gap-4 md:grid-cols-2",children:h.map((t)=>i(c,{href:t.href,className:"editorial-panel",children:[i("div",{className:"flex items-start justify-between gap-4",children:[i("div",{children:[e("h2",{className:"font-semibold text-xl",children:t.title}),e("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.description})]}),e(l,{className:"mt-1 shrink-0",size:18})]}),i("div",{className:"mt-4 flex items-center gap-2 text-muted-foreground text-xs",children:[e(m,{size:14}),i("span",{children:["Target time: ",t.time]})]})]},t.href))}),i("div",{className:"editorial-panel space-y-4",children:[i("div",{className:"flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]",children:[e(p,{size:16}),"Working style"]}),i("ul",{className:"editorial-list",children:[i("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Run each guide in a branch or sandboxed workspace."})]}),i("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Prefer one bounded surface at a time: one endpoint, one workflow, one integration, one unsafe module."})]}),i("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Use the example and reference outputs to verify what changed, not just the narrative page."})]})]}),e(d,{language:"bash",filename:"guides-quickstart",code:`# list example systems
+var N=Object.defineProperty;var O=(q)=>q;function Q(q,z){this[q]=O.bind(null,z)}var G=(q,z)=>{for(var F in z)N(q,F,{get:z[F],enumerable:!0,configurable:!0,set:Q.bind(z,F)})};var R=(q,z)=>()=>(q&&(z=q(q=0)),z);import{CodeBlock as U}from"@contractspec/lib.design-system";import{HStack as J,VStack as E}from"@contractspec/lib.design-system/layout";import{List as W,ListItem as K}from"@contractspec/lib.design-system/list";import{H1 as X,H2 as Y,P as M,Text as D}from"@contractspec/lib.design-system/typography";import Z from"@contractspec/lib.ui-link";import{ArrowRight as _,CheckCircle2 as $,GitBranch as w}from"lucide-react";import{jsx as f,jsxs as v}from"react/jsx-runtime";var A=[{title:"Adopt one endpoint in Next.js",description:"Start inside a live app with one operation, one generated surface, and one clearly bounded change.",href:"/docs/guides/nextjs-one-endpoint",time:"25 min"},{title:"Import an existing codebase",description:"Stabilize what already exists instead of treating adoption as a rewrite project.",href:"/docs/guides/import-existing-codebases",time:"20 min"},{title:"Validation and typing",description:"Keep runtime validation and TypeScript behavior aligned from the same source definitions.",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:"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:"Publish stable docs, schemas, and client-facing artifacts from the contract layer.",href:"/docs/guides/generate-docs-clients-schemas",time:"20 min"},{title:"Docs pipeline",description:"Feed generated reference material into the docs site without confusing ownership.",href:"/docs/guides/docs-generation-pipeline",time:"20 min"},{title:"Build a first module bundle",description:"Define one bundle spec, resolve a surface plan, and render it through the React host layer.",href:"/docs/guides/first-module-bundle",time:"20 min"},{title:"Host the Builder workbench",description:"Wire a Builder workspace snapshot, common commands, runtime modes, and mobile review links into the reusable host.",href:"/docs/guides/host-builder-workbench",time:"20 min"},{title:"Use Connect in a repo",description:"Enable Connect, verify agent actions locally, and inspect the resulting review and replay artifacts.",href:"/docs/guides/connect-in-a-repo",time:"15 min"},{title:"Author release capsules",description:"Pair changesets with structured release capsules and generate the artifacts that changelog and upgrade flows consume.",href:"/docs/guides/release-capsules",time:"15 min"},{title:"CI diff gating",description:"Use deterministic checks to catch drift and risky changes before they ship.",href:"/docs/guides/ci-contract-diff-gating",time:"15 min"}];function p(){return v(E,{className:"space-y-10",children:[v(E,{className:"space-y-3",children:[f(D,{className:"editorial-kicker",children:"Build"}),f(X,{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Adoption guides for teams that want to keep their code."}),f(M,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"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."})]}),f(E,{className:"grid gap-4 md:grid-cols-2",children:A.map((q)=>v(Z,{href:q.href,className:"editorial-panel",children:[v(J,{className:"flex items-start justify-between gap-4",children:[v(E,{children:[f(Y,{className:"font-semibold text-xl",children:q.title}),f(M,{className:"mt-2 text-muted-foreground text-sm leading-7",children:q.description})]}),f(_,{className:"mt-1 shrink-0",size:18})]}),v(J,{className:"mt-4 flex items-center gap-2 text-muted-foreground text-xs",children:[f($,{size:14}),v(D,{children:["Target time: ",q.time]})]})]},q.href))}),v(E,{className:"editorial-panel space-y-4",children:[v(J,{className:"flex items-center gap-2 font-semibold text-[color:var(--rust)] text-sm uppercase tracking-[0.2em]",children:[f(w,{size:16}),f(D,{children:"Working style"})]}),v(W,{className:"editorial-list",children:[f(K,{children:f(D,{children:"Run each guide in a branch or sandboxed workspace."})}),f(K,{children:f(D,{children:"Prefer one bounded surface at a time: one endpoint, one workflow, one integration, one unsafe module."})}),f(K,{children:f(D,{children:"Use the example and reference outputs to verify what changed, not just the narrative page."})})]}),f(U,{language:"bash",filename:"guides-quickstart",code:`# list example systems
 contractspec examples list
 
 # validate the examples in this workspace
-contractspec examples validate --repo-root .`})]})]})}export{y as GuidesIndexPage};
+contractspec examples validate --repo-root .`})]})]})}export{p as GuidesIndexPage};