@pipelex/mthds-form 0.30.0 → 0.32.0

package/README.md

@@ -4,12 +4,13 @@ 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.
 
-## Four entry points
+## Five 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 { layoutCheckProblems } from '@pipelex/mthds-form/generative/headless'; // producing and checking one, on a server
 import { assembleBrand } from '@pipelex/mthds-form/brand'; // a brand, held to the theme contract
 ```
 
@@ -17,7 +18,9 @@ import { assembleBrand } from '@pipelex/mthds-form/brand'; // a brand, held to t
 
 `./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 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).
+`./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 and `./generative/headless` are the only entries that carry json-render, and with `./brand` the only ones that carry 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/headless` is the half of that layer that renders nothing: the designer method's catalog and brief, the prompt pin, the JSONL compiler and the checks a layout is held to. It carries `@json-render/core` and `zod` but no React and no `'use client'` directive, so a host producing layouts calls it on its server, in a server action or a route handler; `./generative` re-exports all of it beside the page.
 
 `./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 also turns up to three seed colours a person picked into colour roles whose text always reads (`deriveBrandRoles`). It renders nothing, fetches nothing and depends on zod alone. See [docs/brand.md](docs/brand.md).
 

package/dist/brand/index.d.ts

@@ -1,54 +1,8 @@
+import { C as ColorTokenName } from '../styles-Bn8byNdo.js';
+export { A as APP_STYLES, a as APP_STYLE_IDS, b as ActionShadow, c as AppStyle, d as AppStyleId, B as BRAND_CONTRACT, e as BodyTypefaceId, f as COLOR_TOKEN_NAMES, g as CONTRAST_PAIRS, h as ContractToken, i as ContractTokenType, j as ContrastPair, M as MIN_CONTRAST, k as MIN_CONTROL_CONTRAST, P as PanelRoles, R as RoleColor, S as StyleRoles, T as TYPEFACES, l as Typeface, m as TypefaceId, n as contractVariable, o as deriveStyleRoles, p as isAppStyle, q as isColorTokenName, r as isTypeface, s as resolveRoleColor } from '../styles-Bn8byNdo.js';
 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;
+import { B as BrandManifest } from '../manifest-D3DLyNEv.js';
+export { b as brandManifestSchema } from '../manifest-D3DLyNEv.js';
 
 declare const srgbColorSchema: z.ZodObject<{
     colorSpace: z.ZodLiteral<"srgb">;
@@ -284,55 +238,6 @@ 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[];
 
-/**
- * Up to three seed colours in, the colour roles a page paints with out.
- *
- * A team brands its pages with at most three colours, each optional, each a
- * `#rrggbb` a person picked: the button colour (`action`), the accent
- * (`accent`) and the header band (`header`). A person picks a colour for how
- * it looks, never for how text reads on it, so nothing here assumes a seed is
- * readable. What this derives is everything a page needs around the seeds,
- * with every text role readable by construction:
- *
- * - **Fills are the seeds, exactly.** `action`, `accent` and `header` come
- *   back as they were given, in lower case, so the button and the band are the
- *   colours the person chose.
- * - **Text on a fill is pure black or pure white**, whichever contrasts more
- *   (`onAction`, `onHeader`). One of the two reaches at least 4.58:1 on any
- *   colour, so every label clears WCAG AA. Only the two extremes carry that
- *   guarantee: a warm near-black or an off-white falls below 4.5:1 on some
- *   mid-tone, so no other colour is ever returned for text.
- * - **The accent as text is ink** (`accentInk`): the accent darkened on a
- *   light page or lightened on a dark one, keeping its hue and saturation,
- *   just until it reads at 4.5:1 on the page and on the pale accent fill, the
- *   two backgrounds a host draws accent text on. An accent that already reads
- *   is its own ink.
- * - **The pale accent fill** (`accentFill`) is the accent laid over the page
- *   at a low strength: a pale tint on a light page, a deep one on a dark page.
- *
- * **An unset seed produces no role.** The roles a seed paints are present
- * when it is set and absent when it is not, so a host keeps its own token for
- * whatever the team left unset: the team's colours where it chose some, and
- * the host's palette everywhere else. The one seed that reaches further is the
- * button colour, which the accent follows when the accent is unset, so a red
- * button never sits beside links in another hue. With no seed at all, there
- * is no colour role to return.
- *
- * The page colour is an argument because every text role is measured against
- * it: a host renders a light and a dark theme, and it calls this once per
- * theme with that theme's page colour and that theme's seeds. Which seeds a
- * theme uses is the host's to decide; `resolveDarkSeeds` is the rule for a
- * dark set that falls back, colour by colour, to the light one.
- *
- * It returns roles, never custom property names: each host maps the roles onto
- * its own tokens. See docs/brand.md § "Three seed colours".
- */
-/**
- * The contrast a control's outline needs against what surrounds it: WCAG 2's
- * level for a user interface component (1.4.11). A button colour below it
- * against the page is a button whose shape is hard to see.
- */
-declare const MIN_CONTROL_CONTRAST = 3;
 /**
  * Up to three seed colours, each `#rrggbb` in any case, or unset. `null` and
  * `undefined` both mean unset, so a host can pass a team's stored colours as
@@ -392,11 +297,12 @@ type BrandRoles = (ActionRoles | Absent<ActionRoles>) & (AccentRoles | Absent<Ac
  * `surfaces` are the other colours accent text sits on besides the page and
  * the pale fill, each `#rrggbb`: a style's panel and the fields inside it
  * (`resolveRoleColor` turns a style's role colour into one), or a canvas
- * behind the page. The ink is moved until it reads on all of them. When
- * there is an accent to derive, a surface on which not even the page's own
- * text extreme, pure black on a light page or pure white on a dark one,
- * reaches 4.5:1 throws, since no ink moving the page's way could read there.
- * With no accent, no ink is derived, and the surfaces are only parsed.
+ * behind the page. The ink is moved until it reads on all of them, and an
+ * accent that already reads on every one is its own ink. When there is an
+ * accent to derive and no shade of it reads on the page, the pale fill and
+ * every surface at once, which a surface on the far side of the page's
+ * lightness can cause, it throws, naming them. With no accent, no ink is
+ * derived, and the surfaces are only parsed.
  */
 declare function deriveBrandRoles(seeds: BrandSeeds | null | undefined, page: string, surfaces?: readonly string[]): BrandRoles;
 /**
@@ -424,156 +330,4 @@ declare function resolveDarkSeeds(colors: BrandSeeds | null | undefined, darkCol
 /** Pure black or pure white, whichever reads better on a `#rrggbb` fill. */
 declare function readableTextOn(fill: string): TextOnFill;
 
-/**
- * The app styles and the typefaces, as data, and the roles a team's choice of
- * the two sets.
- *
- * A style is a small set of design values a team picks from a closed list, on
- * top of its own colours and logo: how its headings, its panels, its corners,
- * its call to action and its rhythm look. A typeface is picked from a short
- * list beside it, and replaces the style's body face, and its heading face
- * wherever the style's headings follow the body. Neither adds a colour: every
- * fill, edge and ink a style uses is a role the theme contract already has,
- * named here by that role (`RoleColor`), or a shadow.
- *
- * `deriveStyleRoles` returns roles, never custom property names, the way
- * `deriveBrandRoles` does for the seed colours: each host maps them onto its
- * own tokens, and the kernel's controls and the generative layer read the few
- * optional tokens docs/theming.md lists, each with today's look as its
- * fallback. A role a choice does not set is not a key, so a host keeps its own
- * value there; `quiet` with no typeface sets nothing at all, which is what
- * makes "no style" and "the default style" one state.
- *
- * See docs/brand.md § "App styles and typefaces".
- */
-/** The faces of the closed list, all on Google Fonts under the SIL Open Font License. */
-type TypefaceId = 'inter' | 'dm-sans' | 'plus-jakarta-sans' | 'manrope' | 'ibm-plex-sans' | 'source-sans-3' | 'work-sans' | 'space-grotesk' | 'newsreader';
-/** The faces a team may pick as its typeface: every face but a style's own heading face. */
-type BodyTypefaceId = Exclude<TypefaceId, 'newsreader'>;
-interface Typeface {
-    id: TypefaceId;
-    /** The family name, as a stylesheet and a font service name it. */
-    family: string;
-    category: 'sans-serif' | 'serif';
-    /** The weights a host loads it in: from the host's own light titles (300) to the boldest a style sets (700). */
-    weights: readonly number[];
-    /** The generic stack that renders while the face loads, or when it never does. */
-    fallback: string;
-    /** The face first, then its fallback: a whole `font-family` value. */
-    stack: string;
-    /** Whether a team may pick it (`body`), or a style uses it for its headings only (`heading`). */
-    use: 'body' | 'heading';
-}
-/**
- * Every face a style or a team can set. The body faces are the list a team
- * picks from; Newsreader is the `editorial` style's heading face, listed so a
- * host loads it, and is not a team's choice. Frozen, like `APP_STYLES`: a
- * process serves many teams, so the catalogue one of them reads cannot be
- * one another has edited.
- */
-declare const TYPEFACES: readonly Typeface[];
-/** Whether `value` names a face a team may pick: a body face of `TYPEFACES`. */
-declare function isTypeface(value: unknown): value is BodyTypefaceId;
-/**
- * A colour a style paints with, named by the role of the theme contract it
- * is: never a colour of its own, so a team's palette and the host's theme
- * stay the only sources of colour, and their readability guarantees hold.
- */
-interface RoleColor {
-    role: ColorTokenName;
-    /** Mixed toward another role, in Oklab, by `share` (0 to 1): the card a little toward the foreground. */
-    toward?: {
-        role: ColorTokenName;
-        share: number;
-    };
-    /** Its opacity over what lies behind it, 0 to 1; absent, opaque. */
-    alpha?: number;
-}
-/** How a style draws a panel - a host's composer, a designed page's rail or card - in one theme. */
-interface PanelRoles {
-    fill: RoleColor;
-    /** The edge's colour, or `null` for no visible edge (the width is kept, so a panel's box does not move). */
-    edge: RoleColor | null;
-    /** The edge's width, in CSS pixels. */
-    edgeWidth: number;
-    /** A CSS `box-shadow` in a neutral ink, or `null` for none. */
-    shadow: string | null;
-    /**
-     * The fill of the fields set into the panel, where the host's field fill
-     * would sink into it; absent, the host's own.
-     */
-    field?: RoleColor;
-}
-/** The call to action's shadow: a CSS shadow's geometry, in pixels, tinted with a role. */
-interface ActionShadow {
-    x: number;
-    y: number;
-    blur: number;
-    spread: number;
-    color: RoleColor;
-}
-/**
- * The roles a style and a typeface set. An absent role is not a key: a host
- * keeps its own value there.
- */
-interface StyleRoles {
-    /** The face of everything on the page. */
-    bodyFace?: Typeface;
-    /** The face of the page's titles and its sections' and panels' headings. */
-    headingFace?: Typeface;
-    headingWeight?: number;
-    /** The headings' letter spacing, in `em`. */
-    headingTracking?: string;
-    /** A control's corner radius, in CSS pixels; a panel takes one and a half of it. */
-    radius?: number;
-    /** The panel treatment in each theme: a shadow that reads on a light page is lost on a dark one. */
-    panel?: {
-        light: PanelRoles;
-        dark: PanelRoles;
-    };
-    /**
-     * The call to action's shadow in each theme, or `none` for a plain fill: a
-     * shadow in the button colour that lifts a button on a light page smears
-     * under it on a dark one.
-     */
-    actionShadow?: {
-        light: ActionShadow | 'none';
-        dark: ActionShadow | 'none';
-    };
-    /** The rhythm: a multiple of the host's own margins, paddings and gaps around the form. Never a control's size. */
-    density?: number;
-}
-type AppStyleId = 'quiet' | 'soft' | 'editorial' | 'bold';
-interface AppStyle {
-    id: AppStyleId;
-    name: string;
-    /** The direction, in one sentence, as a designer reads it. */
-    direction: string;
-    /** The roles the style sets when the team picks no typeface. */
-    roles: StyleRoles;
-}
-declare const APP_STYLE_IDS: readonly AppStyleId[];
-/** Whether `value` names one of the app styles. */
-declare function isAppStyle(value: unknown): value is AppStyleId;
-/**
- * The roles a team's choice sets: its style and its typeface, each a stored
- * id or nothing. An unknown or absent style is `quiet`, which sets nothing;
- * an unknown typeface, or one a team may not pick, is no typeface, so the
- * style's own face (or the host's) stays. The team's typeface replaces the
- * style's body face, and its heading face wherever the style's headings
- * follow the body.
- */
-declare function deriveStyleRoles(style: string | null | undefined, typeface?: string | null): StyleRoles;
-/** The styles, each with its own roles: what it sets for a team that picked no typeface. */
-declare const APP_STYLES: Readonly<Record<AppStyleId, AppStyle>>;
-/**
- * A role colour as a `#rrggbb` hex over the palette it names, to measure a
- * surface a style draws: the ink a team's accent needs on a style's panel
- * (`deriveBrandRoles`' `surfaces`). The mix is Oklab's, as CSS `color-mix()`
- * computes it. A translucent colour is laid over `behind`; without it, it
- * throws, since a translucent colour has no one value. Throws, too, for a
- * role the palette does not hold or a palette colour that is not a hex.
- */
-declare function resolveRoleColor(color: RoleColor, palette: Partial<Record<ColorTokenName, string>>, behind?: string): string;
-
-export { APP_STYLES, APP_STYLE_IDS, type ActionShadow, type AppStyle, type AppStyleId, type AssembleResult, type AssembledBrand, BRAND_CONTRACT, BRAND_PRODUCERS, BRAND_VARIABLES, type BodyTypefaceId, BrandManifest, type BrandProducer, type BrandProvenance, type BrandRoles, type BrandSeeds, 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, MIN_CONTROL_CONTRAST, type PanelRoles, type RoleColor, type SrgbColor, type StatedFacts, type StyleRoles, TYPEFACES, type TextOnFill, type TokensValidation, type Typeface, type TypefaceId, assembleBrand, brandProducerId, brandProvenanceSchema, brandScope, colorHex, colorIsHex, compileBrand, contractVariable, contrastRatio, deriveBrandRoles, deriveStyleRoles, isAccentAdjusted, isActionFaint, isAppStyle, isColorTokenName, isTypeface, readableTextOn, resolveColor, resolveDarkSeeds, resolveRoleColor, srgbColorSchema, statedFactProblems, statedFactsSchema, validateBrandTokens };
+export { type AssembleResult, type AssembledBrand, BRAND_PRODUCERS, BRAND_VARIABLES, BrandManifest, type BrandProducer, type BrandProvenance, type BrandRoles, type BrandSeeds, type BrandSource, type BrandTokens, type ColorMode, type ColorToken, ColorTokenName, type ColorValue, type DimensionToken, type FontFamilyToken, type SrgbColor, type StatedFacts, type TextOnFill, type TokensValidation, assembleBrand, brandProducerId, brandProvenanceSchema, brandScope, colorHex, colorIsHex, compileBrand, contrastRatio, deriveBrandRoles, isAccentAdjusted, isActionFaint, readableTextOn, resolveColor, resolveDarkSeeds, srgbColorSchema, statedFactProblems, statedFactsSchema, validateBrandTokens };