@forumone/throughline-design-system 0.0.0 → 1.0.0-next.2

package/dist/testing/checkBlockProps.js

@@ -0,0 +1,241 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { coerceBlock } from '../render/coerce.js';
+/*
+Does a contract describe the props its component takes?
+
+Nothing else checks it. The first site on this package shipped a contract
+declaring a project's `image` as a bare `image` field while the component read
+`image.src` and `image.alt`. Coercion produced a URL string, both properties
+came back `undefined`, and every project rendered an `<img>` with no `src` and
+no `alt`. Every gate passed, each for a defensible reason: the story supplied
+`{ src, alt }`, so it and the axe check were right; manifest validation does not
+compare field types with props; and the renderer's registry is `any` at the
+seam, which is the honest boundary between two generated shapes, so typecheck
+compared nothing.
+
+## How
+
+Per component: build the data Payload would store for its contract, run it
+through the real `coerceBlock` with the host's real overrides, and compare the
+shape of each prop with the component's args file. The args file is the ground
+truth because it is `satisfies <Name>Props` — TypeScript has already checked it
+against the component — so a disagreement is between the contract and the
+component, which is the thing being looked for.
+
+## What it does not do
+
+Only props in *both* the coerced output and the args are compared. Coercion adds
+`<name>SrcSet` and `<name>Sizes` siblings no args file has; args carry code-only
+props no contract has; and an optional field an args file does not exercise
+cannot be compared with anything. Each of those is a legitimate absence, and a
+shape mismatch needs both sides to describe the same prop.
+*/
+/** Marks a value the host rendered to React, so it is not read as a plain object. */
+const NODE = Symbol('rendered-node');
+const renderedNode = () => ({ [NODE]: true });
+/**
+ * Real overrides, stubbed resolvers. Overrides change the *shape* — they omit
+ * fields, rename `body` to `children`, turn an icon name into a glyph — so they
+ * have to be the host's own. The resolvers turn an id into a URL or Lexical
+ * state into React; a stub produces the same shape as the real thing.
+ */
+export function stubCoerceContext(overrides = {}) {
+    return {
+        overrides,
+        resolveMedia: () => ({
+            url: 'https://example.invalid/image.webp',
+            alt: 'alt text',
+            width: 1200,
+            srcSet: 'https://example.invalid/image.webp 1200w',
+            sizes: '100vw',
+        }),
+        resolveHref: () => '/a-path',
+        renderRichText: renderedNode,
+        renderIcon: renderedNode,
+    };
+}
+/** What Payload stores for a field of each type, filled in. */
+export function storedValue(field) {
+    const objectOf = (fields) => {
+        const out = {};
+        for (const child of fields)
+            out[child.name] = storedValue(child);
+        return out;
+    };
+    switch (field.type) {
+        case 'text':
+        case 'select':
+            return 'text';
+        case 'video':
+            return 'https://example.invalid/video.mp4';
+        case 'number':
+            return 1;
+        case 'boolean':
+            return true;
+        case 'richtext':
+            return { root: { type: 'root', children: [] } };
+        case 'link':
+            return { mode: 'external', url: 'https://example.invalid' };
+        case 'image':
+            return { id: 1, url: 'https://example.invalid/image.webp', alt: 'alt text' };
+        case 'group':
+            return field.of ? objectOf(field.of) : undefined;
+        case 'array':
+            // One row is enough to establish the row's shape.
+            return field.of ? [{ id: 'row-1', ...objectOf(field.of) }] : undefined;
+        default:
+            return undefined;
+    }
+}
+/** A whole block's stored data, for one component's fields. */
+export function storedObject(fields) {
+    const out = {};
+    for (const field of fields)
+        out[field.name] = storedValue(field);
+    return out;
+}
+export function kindOf(value) {
+    if (value === undefined || value === null)
+        return 'absent';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'object') {
+        const held = value;
+        // The coerced side holds React through the stubs; the args side as JSX.
+        if (held[NODE] === true || '$$typeof' in held)
+            return 'node';
+        return 'object';
+    }
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    return 'object';
+}
+/**
+ * Compare two values structurally, recording where they disagree. Recurses
+ * into objects and into the first element of an array, where a row's shape
+ * lives; depth-limited, because a contract nests no deeper than an array of
+ * groups and a cycle in an args file must not hang the check.
+ */
+export function compareShapes(component, prop, coerced, args, found, depth = 0) {
+    const a = kindOf(coerced);
+    const b = kindOf(args);
+    if (a === 'absent' || b === 'absent')
+        return;
+    /*
+    A string and a rendered node are interchangeable: a prop typed `ReactNode`
+    takes both, and an args *value* cannot say which the prop declares. The
+    mismatch this exists for — an object where a scalar was produced — is still
+    one.
+    */
+    if ((a === 'string' && b === 'node') || (a === 'node' && b === 'string'))
+        return;
+    if (a !== b) {
+        found.push({ component, prop, coerced: a, args: b });
+        return;
+    }
+    if (depth >= 3)
+        return;
+    if (a === 'object') {
+        const left = coerced;
+        const right = args;
+        for (const key of Object.keys(left)) {
+            if (key in right)
+                compareShapes(component, `${prop}.${key}`, left[key], right[key], found, depth + 1);
+        }
+        return;
+    }
+    if (a === 'array') {
+        const [left] = coerced;
+        const [right] = args;
+        if (left !== undefined && right !== undefined) {
+            compareShapes(component, `${prop}[]`, left, right, found, depth + 1);
+        }
+    }
+}
+/** Coerce every component's contract and compare the props with its args. */
+export async function checkBlockProps(options) {
+    const ctx = stubCoerceContext(options.overrides);
+    const result = { checked: [], skipped: [], mismatches: [] };
+    for (const [name, component] of Object.entries(options.manifest.components)) {
+        const args = await options.loadArgs(name);
+        if (!args) {
+            result.skipped.push(name);
+            continue;
+        }
+        const fields = component.content.fields ?? [];
+        const coerced = coerceBlock(name, fields, storedObject(fields), ctx);
+        for (const prop of Object.keys(coerced)) {
+            if (prop in args)
+                compareShapes(name, prop, coerced[prop], args[prop], result.mismatches);
+        }
+        result.checked.push(name);
+    }
+    return result;
+}
+const ARGS_EXTENSIONS = ['.ts', '.tsx', '.mts', '.js', '.mjs'];
+/**
+ * Finds `<Name>/<name>args.<ext>` — the case is not guessed — in the first of
+ * `componentDirs` that has one, and returns its default export.
+ *
+ * TypeScript args files need a loader that understands them: the
+ * `check-block-props` bin registers `tsx`, and vitest transforms on its own.
+ */
+export function argsFileLoader(componentDirs) {
+    return async (component) => {
+        for (const root of componentDirs) {
+            const dir = path.join(root, component);
+            const entries = await readdir(dir).catch(() => []);
+            const file = entries.find(entry => {
+                const ext = path.extname(entry);
+                return (ARGS_EXTENSIONS.includes(ext) &&
+                    entry.slice(0, -ext.length).toLowerCase() === `${component.toLowerCase()}args`);
+            });
+            if (!file)
+                continue;
+            const loaded = (await import(pathToFileURL(path.join(dir, file)).href));
+            const args = loaded.default;
+            return args && typeof args === 'object' ? args : undefined;
+        }
+        return undefined;
+    };
+}
+/** The report a person reads, and whether it is a failure. */
+export function formatBlockPropsResult(result) {
+    if (result.mismatches.length > 0) {
+        const lines = [
+            '',
+            `  ${result.mismatches.length} contract/component mismatch(es).`,
+            '',
+            '  A contract field produces a prop shape the component does not take. The',
+            '  args file is `satisfies <Name>Props`, so it is the component that is right',
+            '  and the contract that needs changing.',
+            '',
+            ...result.mismatches.map(m => `    ${m.component}.${m.prop}: contract produces ${m.coerced}, component takes ${m.args}`),
+            '',
+        ];
+        return { ok: false, text: lines.join('\n') };
+    }
+    if (result.checked.length === 0) {
+        return {
+            ok: false,
+            text: `No component had an args file, so nothing was compared ` +
+                `(${result.skipped.length} without one). Check the components directory, or that each ` +
+                `component has a <Name>Args.ts default-exporting its props.`,
+        };
+    }
+    return {
+        ok: true,
+        text: `Contracts agree with their components (${result.checked.length} checked` +
+            (result.skipped.length > 0
+                ? `, ${result.skipped.length} without an args file: ${result.skipped.join(', ')}`
+                : '') +
+            ').',
+    };
+}
+//# sourceMappingURL=checkBlockProps.js.map

package/dist/testing/checkBlockProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkBlockProps.js","sourceRoot":"","sources":["../../src/testing/checkBlockProps.ts"],"names":[],"mappings":"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"}

package/dist/testing/checkBlockPropsCli.d.ts

@@ -0,0 +1,12 @@
+export interface CliArgs {
+    manifest: string;
+    componentDirs: string[];
+    overrides?: string;
+    /** Applied by the bin when it registers tsx; recorded here so it parses. */
+    tsconfig?: string;
+}
+/** Parse argv, or return the reason it cannot be. */
+export declare function parseArgs(argv: readonly string[]): CliArgs | string;
+/** Run the check; resolves to the process exit code. */
+export declare function main(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=checkBlockPropsCli.d.ts.map

package/dist/testing/checkBlockPropsCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkBlockPropsCli.d.ts","sourceRoot":"","sources":["../../src/testing/checkBlockPropsCli.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,GAAG,MAAM,CA8BnE;AAcD,wDAAwD;AACxD,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBnE"}

package/dist/testing/checkBlockPropsCli.js

@@ -0,0 +1,86 @@
+/* eslint-disable no-console -- a command-line tool: the console is its output. */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { argsFileLoader, checkBlockProps, formatBlockPropsResult, } from './checkBlockProps.js';
+const USAGE = `Usage: check-block-props <manifest.json> <components-dir> [<components-dir>...] [--overrides <module>] [--tsconfig <file>]
+
+  manifest.json    the design system's built manifest
+  components-dir   a directory holding one directory per component, each with a
+                   <Name>Args.ts default-exporting props that satisfy <Name>Props.
+                   Give several for a design system split across layers.
+  --overrides      a module exporting the site's Overrides, as \`overrides\` or
+                   default — the same object the generator and renderer use.
+  --tsconfig       the tsconfig that compiles the args files, for its \`jsx\`
+                   setting — e.g. a design system's tsconfig.app.json. Read by
+                   the bin before anything loads; stylesheets are stubbed.`;
+/** Parse argv, or return the reason it cannot be. */
+export function parseArgs(argv) {
+    const positional = [];
+    let overrides;
+    let tsconfig;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h')
+            return USAGE;
+        if (arg === '--overrides') {
+            overrides = argv[index + 1];
+            if (!overrides)
+                return `--overrides needs a module path.\n\n${USAGE}`;
+            index += 1;
+            continue;
+        }
+        if (arg === '--tsconfig') {
+            tsconfig = argv[index + 1];
+            if (!tsconfig)
+                return `--tsconfig needs a file path.\n\n${USAGE}`;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--'))
+            return `Unknown option ${arg}.\n\n${USAGE}`;
+        positional.push(arg);
+    }
+    const [manifest, ...componentDirs] = positional;
+    if (!manifest || componentDirs.length === 0)
+        return USAGE;
+    return {
+        manifest,
+        componentDirs,
+        ...(overrides ? { overrides } : {}),
+        ...(tsconfig ? { tsconfig } : {}),
+    };
+}
+async function loadOverrides(file) {
+    const loaded = (await import(pathToFileURL(path.resolve(file)).href));
+    const overrides = loaded.overrides ?? loaded.default;
+    if (!overrides || typeof overrides !== 'object') {
+        throw new Error(`${file} exports no \`overrides\` (named or default).`);
+    }
+    return overrides;
+}
+/** Run the check; resolves to the process exit code. */
+export async function main(argv) {
+    const args = parseArgs(argv);
+    if (typeof args === 'string') {
+        console.error(args);
+        return 2;
+    }
+    const manifest = JSON.parse(await readFile(path.resolve(args.manifest), 'utf8'));
+    if (!manifest.components || typeof manifest.components !== 'object') {
+        console.error(`${args.manifest} has no "components"; is it a design-system manifest?`);
+        return 2;
+    }
+    const result = await checkBlockProps({
+        manifest,
+        loadArgs: argsFileLoader(args.componentDirs.map(dir => path.resolve(dir))),
+        overrides: args.overrides ? await loadOverrides(args.overrides) : {},
+    });
+    const report = formatBlockPropsResult(result);
+    if (report.ok)
+        console.warn(report.text);
+    else
+        console.error(report.text);
+    return report.ok ? 0 : 1;
+}
+//# sourceMappingURL=checkBlockPropsCli.js.map

package/dist/testing/checkBlockPropsCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkBlockPropsCli.js","sourceRoot":"","sources":["../../src/testing/checkBlockPropsCli.ts"],"names":[],"mappings":"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"}

package/dist/testing/contractDefaults.d.ts

@@ -0,0 +1,21 @@
+import type { Block } from 'payload';
+import type { ContentField } from '../generate/fields.js';
+/** A generated default that disagrees with the contract. */
+export interface DefaultMismatch {
+    /** `Block.group.field` */
+    path: string;
+    /** What the contract says the default is. */
+    contract: unknown;
+    /** What the generated field will store. */
+    generated: unknown;
+    message: string;
+}
+/**
+ * Every generated default in one block that disagrees with its contract.
+ *
+ * Walks the contract, not the block: a field an override omits or retypes is
+ * the host's decision and is not reported, and fields the generator adds of its
+ * own — a link's mode and new-tab box — are not the contract's to declare.
+ */
+export declare function defaultMismatches(block: Block, contractFields: readonly ContentField[]): DefaultMismatch[];
+//# sourceMappingURL=contractDefaults.d.ts.map

package/dist/testing/contractDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contractDefaults.d.ts","sourceRoot":"","sources":["../../src/testing/contractDefaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,SAAS,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAyCzD,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAA;IACjB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,EACZ,cAAc,EAAE,SAAS,YAAY,EAAE,GACtC,eAAe,EAAE,CAEnB"}

package/dist/testing/contractDefaults.js

@@ -0,0 +1,65 @@
+const isNamed = (field) => 'name' in field && typeof field.name === 'string';
+/**
+ * A field list's named fields, looking through presentational wrappers — the
+ * generator arranges fields into rows and collapsibles, which store nothing.
+ */
+function namedFields(fields) {
+    return fields.flatMap(field => {
+        if (isNamed(field))
+            return [field];
+        if (field.type === 'tabs')
+            return field.tabs.flatMap(tab => namedFields(tab.fields));
+        return 'fields' in field && Array.isArray(field.fields) ? namedFields(field.fields) : [];
+    });
+}
+/**
+ * Every generated default in one block that disagrees with its contract.
+ *
+ * Walks the contract, not the block: a field an override omits or retypes is
+ * the host's decision and is not reported, and fields the generator adds of its
+ * own — a link's mode and new-tab box — are not the contract's to declare.
+ */
+export function defaultMismatches(block, contractFields) {
+    return walk(contractFields, block.fields, block.slug);
+}
+function walk(contractFields, generatedFields, path) {
+    const found = [];
+    const generated = namedFields(generatedFields);
+    for (const field of contractFields) {
+        const match = generated.find(candidate => candidate.name === field.name);
+        if (!match)
+            continue;
+        const here = `${path}.${field.name}`;
+        if (field.type === 'boolean' && match.type === 'checkbox') {
+            const expected = field.defaultValue ?? false;
+            if (match.defaultValue !== expected) {
+                found.push({
+                    path: here,
+                    contract: field.defaultValue,
+                    generated: match.defaultValue,
+                    message: `${here} starts ${String(match.defaultValue)} in the CMS, and its contract says ` +
+                        `${field.defaultValue === undefined ? 'nothing, which means false' : String(field.defaultValue)}. ` +
+                        `A checkbox is never undefined, so the component's own default never applies.`,
+                });
+            }
+        }
+        // Text only. A select's default is a choice among the component's own
+        // options, not copy, and the contract has no way to declare one yet.
+        if (field.type === 'text' &&
+            typeof match.defaultValue === 'string' &&
+            match.defaultValue !== '') {
+            found.push({
+                path: here,
+                contract: undefined,
+                generated: match.defaultValue,
+                message: `${here} has the string default "${match.defaultValue}": content nobody typed, ` +
+                    `written into every block anybody adds.`,
+            });
+        }
+        if ((field.type === 'group' || field.type === 'array') && field.of && 'fields' in match) {
+            found.push(...walk(field.of, match.fields, here));
+        }
+    }
+    return found;
+}
+//# sourceMappingURL=contractDefaults.js.map

package/dist/testing/contractDefaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contractDefaults.js","sourceRoot":"","sources":["../../src/testing/contractDefaults.ts"],"names":[],"mappings":"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"}

package/dist/testing/describeBlockInvariants.d.ts

@@ -0,0 +1,39 @@
+import type { Block } from 'payload';
+import type { GeneratedBlock, ManifestLike } from '../generate/blocks.js';
+export interface BlockInvariantOptions {
+    /**
+     * Where to find each block's contract when `blocks` are plain Payload
+     * blocks. Not needed for the `GeneratedBlock[]` that `generateBlocks`
+     * returns, which carry their contract.
+     */
+    manifest?: ManifestLike;
+    /**
+     * The fewest blocks the list may hold. A manifest that failed to load would
+     * make every assertion vacuous, so set this near the library's real size.
+     * Defaults to 1.
+     */
+    minBlocks?: number;
+    /** The suite's name. Defaults to "design-system block invariants". */
+    title?: string;
+}
+type BlockInput = Block | GeneratedBlock;
+/**
+ * Registers a vitest suite asserting what every generated block must hold:
+ *
+ * - **Untouched blocks validate.** Every field `validate` passes the data
+ *   Payload stores for a freshly-added block, and again with one empty row in
+ *   every array.
+ * - **Contract defaults survive.** Every generated checkbox starts where its
+ *   contract says, and no generated text field has a string default.
+ *
+ * ```ts
+ * import { designSystemBlocks } from './index.js'
+ * describeBlockInvariants(designSystemBlocks, { manifest, minBlocks: 40 })
+ * ```
+ *
+ * No database and no Payload instance: a block config is a value, and a
+ * `validate` is a function on it.
+ */
+export declare function describeBlockInvariants(input: readonly BlockInput[], options?: BlockInvariantOptions): void;
+export {};
+//# sourceMappingURL=describeBlockInvariants.d.ts.map

package/dist/testing/describeBlockInvariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describeBlockInvariants.d.ts","sourceRoot":"","sources":["../../src/testing/describeBlockInvariants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAKzE,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,KAAK,UAAU,GAAG,KAAK,GAAG,cAAc,CAAA;AAKxC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,OAAO,GAAE,qBAA0B,GAClC,IAAI,CAiEN"}

package/dist/testing/describeBlockInvariants.js

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { defaultMismatches } from './contractDefaults.js';
+import { runValidateCase, untouchedCases } from './untouchedBlocks.js';
+const isGenerated = (input) => 'block' in input && 'component' in input;
+/**
+ * Registers a vitest suite asserting what every generated block must hold:
+ *
+ * - **Untouched blocks validate.** Every field `validate` passes the data
+ *   Payload stores for a freshly-added block, and again with one empty row in
+ *   every array.
+ * - **Contract defaults survive.** Every generated checkbox starts where its
+ *   contract says, and no generated text field has a string default.
+ *
+ * ```ts
+ * import { designSystemBlocks } from './index.js'
+ * describeBlockInvariants(designSystemBlocks, { manifest, minBlocks: 40 })
+ * ```
+ *
+ * No database and no Payload instance: a block config is a value, and a
+ * `validate` is a function on it.
+ */
+export function describeBlockInvariants(input, options = {}) {
+    const blocks = input.map(item => (isGenerated(item) ? item.block : item));
+    const contracts = new Map();
+    for (const item of input) {
+        if (isGenerated(item))
+            contracts.set(item.block.slug, item.component.content.fields);
+    }
+    if (options.manifest) {
+        for (const block of blocks) {
+            const component = options.manifest.components[block.slug];
+            if (component && !contracts.has(block.slug))
+                contracts.set(block.slug, component.content.fields);
+        }
+    }
+    describe(options.title ?? 'design-system block invariants', () => {
+        it('has the whole library, not an empty list', () => {
+            expect(blocks.length).toBeGreaterThanOrEqual(Math.max(1, options.minBlocks ?? 1));
+        });
+        for (const rows of ['none', 'one']) {
+            describe(`a block added and saved with ${rows === 'none' ? 'no array rows' : 'one empty array row'}`, () => {
+                const cases = untouchedCases(blocks, rows);
+                if (cases.length === 0) {
+                    // Nothing to call is a fact worth seeing, not a failure: a library
+                    // with no optional groups or links has no generated validate.
+                    it.skip('no generated field carries a validate');
+                    return;
+                }
+                it.each(cases.map(found => [found.path, found]))('%s validates', async (path, found) => {
+                    const result = await runValidateCase(found);
+                    expect(result, `${path} refuses an untouched block: "${String(result)}". An author would see that ` +
+                        'on a block they have just added and not yet typed into.').toBe(true);
+                });
+            });
+        }
+        describe('contract defaults survive into the CMS', () => {
+            it('knows the contract of every block', () => {
+                const unknown = blocks.filter(block => !contracts.has(block.slug)).map(block => block.slug);
+                expect(unknown, 'pass the GeneratedBlock[] from generateBlocks, or the manifest as options.manifest').toEqual([]);
+            });
+            const withContracts = blocks.filter(block => contracts.has(block.slug));
+            if (withContracts.length === 0)
+                return;
+            it.each(withContracts.map(block => [block.slug, block]))('%s starts where its contract says', (_slug, block) => {
+                const mismatches = defaultMismatches(block, contracts.get(block.slug) ?? []);
+                expect(mismatches.map(mismatch => mismatch.message)).toEqual([]);
+            });
+        });
+    });
+}
+//# sourceMappingURL=describeBlockInvariants.js.map

package/dist/testing/describeBlockInvariants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describeBlockInvariants.js","sourceRoot":"","sources":["../../src/testing/describeBlockInvariants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAG7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAqBtE,MAAM,WAAW,GAAG,CAAC,KAAiB,EAA2B,EAAE,CACjE,OAAO,IAAI,KAAK,IAAI,WAAW,IAAI,KAAK,CAAA;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA4B,EAC5B,UAAiC,EAAE;IAEnC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACzE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmC,CAAA;IAC5D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,WAAW,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACtF,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACzD,IAAI,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBACzC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACvD,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,gCAAgC,EAAE,GAAG,EAAE;QAC/D,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;YAClD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAA;QACnF,CAAC,CAAC,CAAA;QAEF,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,CAAU,EAAE,CAAC;YAC5C,QAAQ,CAAC,gCAAgC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,qBAAqB,EAAE,EAAE,GAAG,EAAE;gBACzG,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;gBAE1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,mEAAmE;oBACnE,8DAA8D;oBAC9D,EAAE,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAA;oBAChD,OAAM;gBACR,CAAC;gBAED,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAU,CAAC,CAAC,CACvD,cAAc,EACd,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;oBACpB,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,CAAA;oBAC3C,MAAM,CACJ,MAAM,EACN,GAAG,IAAI,iCAAiC,MAAM,CAAC,MAAM,CAAC,8BAA8B;wBAClF,yDAAyD,CAC5D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACd,CAAC,CACF,CAAA;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,QAAQ,CAAC,wCAAwC,EAAE,GAAG,EAAE;YACtD,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;gBAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAC3F,MAAM,CACJ,OAAO,EACP,oFAAoF,CACrF,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;YACf,CAAC,CAAC,CAAA;YAEF,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;YACvE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAM;YAEtC,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAU,CAAC,CAAC,CAC/D,mCAAmC,EACnC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBACf,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;gBAC5E,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;YAClE,CAAC,CACF,CAAA;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Test helpers for a site's generated blocks, as
+ * `@forumone/throughline-design-system/testing`.
+ *
+ * Kept apart from the package root and `./generate`, which run inside
+ * `payload.config.ts`, because `describeBlockInvariants` imports `vitest` — an
+ * optional peer a running site never loads. The contract/component check is
+ * also a bin, `check-block-props`.
+ */
+export { describeBlockInvariants } from './describeBlockInvariants.js';
+export type { BlockInvariantOptions } from './describeBlockInvariants.js';
+export { checkUntouchedBlocks, untouchedData, validateCases, validateOptions, } from './untouchedBlocks.js';
+export type { UntouchedFailure, UntouchedRows, ValidateCase } from './untouchedBlocks.js';
+export { defaultMismatches } from './contractDefaults.js';
+export type { DefaultMismatch } from './contractDefaults.js';
+export { argsFileLoader, checkBlockProps, compareShapes, formatBlockPropsResult, kindOf, storedObject, storedValue, stubCoerceContext, } from './checkBlockProps.js';
+export type { CheckBlockPropsOptions, CheckBlockPropsResult, PropKind, PropMismatch, PropsManifest, } from './checkBlockProps.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,YAAY,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,MAAM,EACN,YAAY,EACZ,WAAW,EACX,iBAAiB,GAClB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,QAAQ,EACR,YAAY,EACZ,aAAa,GACd,MAAM,sBAAsB,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,14 @@
+/**
+ * Test helpers for a site's generated blocks, as
+ * `@forumone/throughline-design-system/testing`.
+ *
+ * Kept apart from the package root and `./generate`, which run inside
+ * `payload.config.ts`, because `describeBlockInvariants` imports `vitest` — an
+ * optional peer a running site never loads. The contract/component check is
+ * also a bin, `check-block-props`.
+ */
+export { describeBlockInvariants } from './describeBlockInvariants.js';
+export { checkUntouchedBlocks, untouchedData, validateCases, validateOptions, } from './untouchedBlocks.js';
+export { defaultMismatches } from './contractDefaults.js';
+export { argsFileLoader, checkBlockProps, compareShapes, formatBlockPropsResult, kindOf, storedObject, storedValue, stubCoerceContext, } from './checkBlockProps.js';
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAEtE,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAEzD,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,MAAM,EACN,YAAY,EACZ,WAAW,EACX,iBAAiB,GAClB,MAAM,sBAAsB,CAAA"}