@pipelex/mthds-form 0.14.1 → 0.15.0

package/README.md

@@ -4,19 +4,22 @@ The input form for MTHDS methods, as a library: a headless kernel that maps the
 
 It exists because "the form" is one problem that keeps being solved separately. A method declares its inputs; something has to decide what widget each input deserves, whether the Run button may light up, what shape the values take on the wire, and what a validation failure says to a person. That logic belongs in one place with tests around it, not copied into each surface that happens to need a form.
 
-## Three entry points
+## Four entry points
 
 ```ts
 import { buildRunFields, computeReadiness } from '@pipelex/mthds-form'; // headless
 import { FieldRenderer } from '@pipelex/mthds-form/react'; // the controls
 import { GenerativePage } from '@pipelex/mthds-form/generative'; // a produced layout
+import { assembleBrand } from '@pipelex/mthds-form/brand'; // a brand, held to the theme contract
 ```
 
 `.` is the kernel: no React, no design system, no framework. Its only runtime dependency is `ajv`, which the gate validates through. It runs in a browser, in Node, in a worker.
 
 `./react` is the control set — one control per field kind behind a single dispatch point, styled with Tailwind classes over standard shadcn/ui tokens. `react` and `react-dom` are optional peer dependencies, so a consumer that only wants the kernel never installs them.
 
-`./generative` renders a **layout** — a data file a model wrote once for a method, naming paths in the same descriptor and restating nothing about what a field is. It is the only entry that carries json-render and zod, so a host that renders an ordinary form pays for neither. When there is no layout, or the one on file no longer fits the method, the page falls back to the kernel's own form. See [docs/generative-ui.md](docs/generative-ui.md).
+`./generative` renders a **layout** — a data file a model wrote once for a method, naming paths in the same descriptor and restating nothing about what a field is. It is the only entry that carries json-render, and with `./brand` the only one that carries zod, so a host that renders an ordinary form pays for neither. When there is no layout, or the one on file no longer fits the method, the page falls back to the kernel's own form. See [docs/generative-ui.md](docs/generative-ui.md).
+
+`./brand` holds a **brand** (a product's colours, radius, typefaces and logos, as a DTCG token file and a manifest) to the theme contract the controls are styled against, and compiles it into a stylesheet scoped to one class. It renders nothing, fetches nothing and depends on zod alone. See [docs/brand.md](docs/brand.md).
 
 `mthds` is an ordinary dependency rather than a peer, but it is **types only**: the wire types of `pipe_io_contracts` belong to the MTHDS standard, so this package re-exports the standard's declarations instead of restating them. Every import of it is an `import type` and is erased at build, so it costs an install entry and no shipped bytes. It is not a peer because pnpm does not install an unmet one, and an absent `mthds` degrades the re-exported types silently rather than failing. See [docs/dependency-budget.md](docs/dependency-budget.md).
 

package/dist/brand/index.d.ts

@@ -0,0 +1,285 @@
+import { z } from 'zod';
+import { B as BrandManifest } from '../manifest-DUeAWeqa.js';
+export { b as brandManifestSchema } from '../manifest-DUeAWeqa.js';
+
+/**
+ * The brand contract, as data: which token of a brand's `tokens.json` sets
+ * which custom property, and what that property paints.
+ *
+ * It is the theme contract seen from the other side. `src/styles/theme.css`
+ * states it as a working default and `docs/theming.md` in prose; this is the
+ * same list as a table a build can read, and a brand is exactly these tokens
+ * and no others - the validator refuses a file that adds one, because a token
+ * nothing consumes is a value with no way to be looked at.
+ *
+ * The colour and radius rows are not a second list kept beside `theme.css`:
+ * they are held to it, by `__tests__/contract.test.ts` over the source and by
+ * `scripts/assert-bundle.mjs` over the build. The two typography rows are the
+ * exception, and on purpose. `--font-sans` and `--font-mono` are the names of
+ * Tailwind's own theme variables, which the prebuilt sheet already declares,
+ * so `theme.css` does not define them: it is unlayered, and a value there
+ * would override the typeface of every host that loads it. The stock
+ * typeface is therefore the host's own, and only a brand's scope sets these
+ * two. See docs/brand.md.
+ */
+type ContractTokenType = 'color' | 'dimension' | 'fontFamily';
+interface ContractToken {
+    /** The DTCG token id, `color.background`. */
+    id: string;
+    /** The custom property it sets, `--background`. */
+    variable: string;
+    type: ContractTokenType;
+    /** What the property paints, in the words a producer is told. */
+    paints: string;
+}
+/** The colour tokens, in the order `theme.css` states them. */
+declare const COLOR_TOKEN_NAMES: readonly ["background", "foreground", "card", "card-foreground", "popover", "popover-foreground", "primary", "primary-foreground", "secondary", "secondary-foreground", "muted", "muted-foreground", "accent", "accent-foreground", "destructive", "destructive-foreground", "border", "input", "ring"];
+type ColorTokenName = (typeof COLOR_TOKEN_NAMES)[number];
+declare function isColorTokenName(name: string): name is ColorTokenName;
+declare const BRAND_CONTRACT: readonly ContractToken[];
+/**
+ * The pairs that must clear WCAG AA in both modes, as they render: the canvas
+ * opaque, the ink blended over it by its alpha.
+ */
+declare const CONTRAST_PAIRS: readonly {
+    foreground: ColorTokenName;
+    background: ColorTokenName;
+}[];
+/** The minimum contrast ratio those pairs must reach: WCAG 2 AA for normal text. */
+declare const MIN_CONTRAST = 4.5;
+/** The custom property a token sets, or a loud failure for a token the contract does not name. */
+declare function contractVariable(id: string): string;
+
+declare const srgbColorSchema: z.ZodObject<{
+    colorSpace: z.ZodLiteral<"srgb">;
+    components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    alpha: z.ZodNumber;
+    hex: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type SrgbColor = z.infer<typeof srgbColorSchema>;
+declare const colorValueSchema: z.ZodUnion<readonly [z.ZodObject<{
+    colorSpace: z.ZodLiteral<"srgb">;
+    components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    alpha: z.ZodNumber;
+    hex: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodString]>;
+type ColorValue = z.infer<typeof colorValueSchema>;
+declare const colorTokenSchema: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodObject<{
+        colorSpace: z.ZodLiteral<"srgb">;
+        components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        alpha: z.ZodNumber;
+        hex: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodString]>;
+    $description: z.ZodString;
+    $extensions: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodObject<{
+            dark: z.ZodUnion<readonly [z.ZodObject<{
+                colorSpace: z.ZodLiteral<"srgb">;
+                components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                alpha: z.ZodNumber;
+                hex: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodString]>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ColorToken = z.infer<typeof colorTokenSchema>;
+declare const dimensionTokenSchema: z.ZodObject<{
+    $value: z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodEnum<{
+            rem: "rem";
+            px: "px";
+        }>;
+    }, z.core.$strict>;
+    $description: z.ZodString;
+}, z.core.$strict>;
+type DimensionToken = z.infer<typeof dimensionTokenSchema>;
+declare const fontFamilyTokenSchema: z.ZodObject<{
+    $value: z.ZodArray<z.ZodString>;
+    $description: z.ZodString;
+}, z.core.$strict>;
+type FontFamilyToken = z.infer<typeof fontFamilyTokenSchema>;
+/** The token file, typed: the contract's groups and tokens, nothing else. */
+interface BrandTokens {
+    color: {
+        $type: 'color';
+    } & Record<ColorTokenName, ColorToken>;
+    radius: {
+        $type: 'dimension';
+        base: DimensionToken;
+    };
+    font: {
+        $type: 'fontFamily';
+        sans: FontFamilyToken;
+        mono: FontFamilyToken;
+    };
+}
+type TokensValidation = {
+    ok: true;
+    tokens: BrandTokens;
+} | {
+    ok: false;
+    problems: string[];
+};
+type ColorMode = 'light' | 'dark';
+/** `#rrggbb` for a colour, its alpha dropped: each channel the byte the compiler writes. */
+declare function colorHex(color: SrgbColor): string;
+/**
+ * Whether a colour compiles to the hex. The hex is what a brand ships for the
+ * colour, so any slack here would let a stated accent ship as its neighbour.
+ */
+declare function colorIsHex(color: SrgbColor, hex: string): boolean;
+/** The colour a token resolves to in a mode, through its aliases; null when a chain is broken. */
+declare function resolveColor(tokens: BrandTokens, name: ColorTokenName, mode: ColorMode): SrgbColor | null;
+/** WCAG 2 contrast ratio between two colours, taken as opaque. */
+declare function contrastRatio(a: SrgbColor, b: SrgbColor): number;
+/** Every problem with the file at once, so a producer's repair round sees the whole list. */
+declare function validateBrandTokens(doc: unknown): TokensValidation;
+
+declare const statedFactsSchema: z.ZodObject<{
+    accent: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodString>;
+        dark: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    logo: z.ZodOptional<z.ZodObject<{
+        onLight: z.ZodOptional<z.ZodURL>;
+        onDark: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type StatedFacts = z.infer<typeof statedFactsSchema>;
+/**
+ * Where the brand does not carry what the person stated, in the words a repair
+ * round is told. Only the modes and canvases that were stated are checked.
+ */
+declare function statedFactProblems(stated: StatedFacts | undefined, manifest: BrandManifest, tokens: BrandTokens): string[];
+
+/**
+ * A brand's `provenance.json`: who produced it, on which model, from which
+ * contract and which facts.
+ *
+ * A brand follows the rules a captured layout follows: produced by a pass,
+ * committed with its provenance, and titled by what made it and by nothing
+ * else. The provenance is a record, so it is never rewritten to make a check
+ * pass. A brand's directory is named by `brandProducerId`, the same recipe a
+ * layout fixture's id uses, so the tree and the record cannot disagree about
+ * who made a brand.
+ */
+/** How a brand came to be. */
+declare const BRAND_PRODUCERS: readonly ["pipelex-method", "claude-code-subagent", "claude-code-session"];
+type BrandProducer = (typeof BRAND_PRODUCERS)[number];
+declare const brandProvenanceSchema: z.ZodObject<{
+    producer: z.ZodEnum<{
+        "pipelex-method": "pipelex-method";
+        "claude-code-subagent": "claude-code-subagent";
+        "claude-code-session": "claude-code-session";
+    }>;
+    model: z.ZodString;
+    date: z.ZodString;
+    brief: z.ZodString;
+    contractHash: z.ZodString;
+    seed: z.ZodOptional<z.ZodString>;
+    stated: z.ZodOptional<z.ZodObject<{
+        accent: z.ZodOptional<z.ZodObject<{
+            light: z.ZodOptional<z.ZodString>;
+            dark: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        logo: z.ZodOptional<z.ZodObject<{
+            onLight: z.ZodOptional<z.ZodURL>;
+            onDark: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    siteFacts: z.ZodOptional<z.ZodString>;
+    rounds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+type BrandProvenance = z.infer<typeof brandProvenanceSchema>;
+/** The id a brand's directory is named by: `producer--model[--seeded]`. */
+declare function brandProducerId(provenance: Pick<BrandProvenance, 'producer' | 'model' | 'seed'>): string;
+/**
+ * The scope class a brand's stylesheet sets its tokens on: `brand-<brand>-<producerId>`,
+ * with every character outside `[a-z0-9-]` replaced, because a model id
+ * carries dots and a dot ends a class selector.
+ *
+ * The replacement folds: `claude-4.8-opus` and `claude-4-8-opus` share a
+ * scope, and so do two ids that differ only in case. A set of brands loaded on
+ * one page must therefore check its scopes are distinct, or the later
+ * stylesheet silently takes the earlier brand's place.
+ */
+declare function brandScope(brand: string, producerId: string): string;
+
+/**
+ * One brand's three files in - the manifest, the tokens, the provenance - and
+ * either the brand, validated and compiled, or every problem with it.
+ *
+ * This is the verdict on whether a brand is VALID under the contract as it is
+ * now: the manifest, the tokens with their contrast, and the facts the person
+ * stated. It is a hard verdict, and a brand that fails it is not compiled.
+ * Whether a brand was produced against the current brief is a different
+ * question and never a reason to refuse one - an older brand stays a valid
+ * brand - so the provenance's contract hash is recorded here and judged by
+ * the producer, not by this function.
+ *
+ * The problems come in the order a producer would want to be told: the
+ * manifest and the provenance first, because they are cheap and their errors
+ * exact, then the tokens, then the stated facts, which can only be checked
+ * against files that parsed. Each names the file and the path.
+ */
+interface BrandSource {
+    /** The brand's directory name: `pipelex`. */
+    brand: string;
+    /** The producer's directory name under it: `pipelex-method--claude-4.8-opus`. */
+    producerId: string;
+    manifest: unknown;
+    tokens: unknown;
+    provenance: unknown;
+}
+interface AssembledBrand extends BrandProvenance {
+    brand: string;
+    producerId: string;
+    manifest: BrandManifest;
+    tokens: BrandTokens;
+    /** The class a page root carries; the stylesheet is scoped to it. */
+    scope: string;
+    /** The compiled stylesheet. */
+    css: string;
+}
+type AssembleResult = {
+    ok: true;
+    brand: AssembledBrand;
+} | {
+    ok: false;
+    problems: string[];
+};
+declare function assembleBrand(source: BrandSource): AssembleResult;
+
+/**
+ * A validated `tokens.json` in, the brand's stylesheet out.
+ *
+ * What comes out is exactly the contract, scoped: a `.<scope>` block setting
+ * every custom property the contract names, and a `.dark .<scope>` block
+ * restating every colour with its dark value. The `.dark` ancestor is the
+ * package's own dark-mode convention (`theme.css`, the `dark` variant), so a
+ * branded page inside a dark pane picks its dark values up with nothing else
+ * to wire.
+ *
+ * The scope block also sets `font-family: var(--font-sans)`. Tailwind's
+ * preflight resolves the page's typeface once, at `<html>`, so a scope that
+ * only set `--font-sans` lower in the tree would change no text; declaring the
+ * family where the scope is makes the brand's typeface reach everything under
+ * it - the produced page and the plain form alike - while a page with no brand
+ * keeps the host's own typeface untouched.
+ *
+ * The contract is closed - a fixed set of tokens, colours in sRGB only, one
+ * length, two font stacks - so compiling a file the validator accepted is this
+ * function and no dependency. It takes the file as `validateBrandTokens`
+ * returned it; anything else is the caller's mistake, and `assembleBrand` is
+ * the route that cannot make it. The output stays comparable with what a
+ * standard DTCG tool writes for the same file: `__tests__/terrazzo.test.ts`
+ * compiles every committed brand through Terrazzo and compares the
+ * declarations.
+ */
+declare function compileBrand(tokens: BrandTokens, scope: string): string;
+/** Every custom property a compiled brand sets on its scope, in contract order. */
+declare const BRAND_VARIABLES: readonly string[];
+
+export { type AssembleResult, type AssembledBrand, BRAND_CONTRACT, BRAND_PRODUCERS, BRAND_VARIABLES, BrandManifest, type BrandProducer, type BrandProvenance, type BrandSource, type BrandTokens, COLOR_TOKEN_NAMES, CONTRAST_PAIRS, type ColorMode, type ColorToken, type ColorTokenName, type ColorValue, type ContractToken, type ContractTokenType, type DimensionToken, type FontFamilyToken, MIN_CONTRAST, type SrgbColor, type StatedFacts, type TokensValidation, assembleBrand, brandProducerId, brandProvenanceSchema, brandScope, colorHex, colorIsHex, compileBrand, contractVariable, contrastRatio, isColorTokenName, resolveColor, srgbColorSchema, statedFactProblems, statedFactsSchema, validateBrandTokens };