@prestack/thread-ui 0.0.1

package/dist/ui/generators/styles.js

@@ -0,0 +1,502 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { argv, stderr, stdout } from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { exit } from "@prestack/thread/core/invoked";
+import { named as packageOf } from "@prestack/thread/core/scope";
+import { findTree, inTree } from "@prestack/thread/core/tree";
+import { keyframeName, shorthandOf, stopsOf } from "../animations.js";
+import { classOfRole, familyFor, fontStack, fontVariable, setNamed, settingsOf } from "../fonts.js";
+import { sizeNamed, sizeRows, SIZE_PREFIX } from "../icons.js";
+import { compose, keyframesOf } from "../material.js";
+import { checkInteractions, knowSignals } from "../signals.js";
+import { chosen, shifted, themedBy } from "../styleguide.js";
+import { naming, nameOf, sheeted } from "../token.js";
+import { classOf, classOfComposition, classOfElement, classOfScreen, complete, statesOf, structural, under, undeclaredStates, unreacted, boundHeld } from "../variant.js";
+function inside(node) {
+    return [...(node.holds ?? []), ...(node.declares ?? [])];
+}
+const LAYERS = ['token', 'font', 'animation', 'material', 'element', 'variant', 'composition', 'screen'];
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const exported = (id) => id.replace(/-/g, '_').toUpperCase();
+function dashed(property) {
+    return property.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+function block(selector, made, indent) {
+    const properties = Object.keys(made).sort(compare);
+    if (properties.length === 0)
+        return [];
+    const lines = [`${indent}${selector} {`];
+    for (const property of properties)
+        lines.push(`${indent}  ${dashed(property)}: ${made[property] ?? ''};`);
+    lines.push(`${indent}}`, '');
+    return lines;
+}
+function sheet(tokens, guide, materials, variants, modes, themes, screens, compositions, elements, fonts, icons, animations) {
+    const wrong = checkInteractions()[0];
+    if (wrong !== undefined)
+        throw new Error(`${wrong.path}: ${wrong.message}`);
+    const sizes = sizeRows(inside(icons));
+    if (sizes.length === 0) {
+        throw new Error('The icons sheet declares no size row, so nothing says how large a symbol is drawn. The style ' +
+            'guide holds no icon size — one row per size in `icons.ts`, holding a length.');
+    }
+    const values = { ...chosen(guide, tokens), ...Object.fromEntries(sizes.map((one) => [one.id, sheeted(one.id, one.is)])) };
+    const named = new Set(Object.keys(values));
+    const themeIds = new Set(themes.map((theme) => theme.id));
+    const kinds = {};
+    for (const pick of guide.picks)
+        kinds[pick.id] = pick.token;
+    for (const size of sizes)
+        kinds[size.id] = 'icon';
+    const played = (made) => {
+        const out = {};
+        for (const [id, value] of Object.entries(made)) {
+            if (kinds[id] !== 'animation') {
+                out[id] = value;
+                continue;
+            }
+            const animation = animations[value];
+            if (animation === undefined) {
+                const has = Object.keys(animations).sort().map((one) => `\`${one}\``);
+                throw new Error(`\`${id}\` names the animation \`${value}\`, and no row declares one by that name. ` +
+                    (has.length === 0
+                        ? 'The app declares no animations.'
+                        : `The declared animations are ${has.join(', ')}.`));
+            }
+            out[id] = sheeted(value, shorthandOf(animation, named));
+        }
+        return out;
+    };
+    const variables = (made, selector, indent) => {
+        const names = Object.keys(made).sort(compare);
+        if (names.length === 0)
+            return [];
+        const held = [`${indent}${selector} {`];
+        for (const id of names)
+            held.push(`${indent}  ${nameOf(id)}: ${made[id] ?? ''};`);
+        held.push(`${indent}}`, '');
+        return held;
+    };
+    const lines = [
+        '/* GENERATED by thread — do not edit. Change the declarations and regenerate. */',
+        '',
+        `@layer ${LAYERS.join(', ')};`,
+        '',
+        '@layer token {',
+        ...variables(played(values), ':root', '  '),
+    ];
+    for (const mode of modes) {
+        const held = variables(played(shifted(guide, tokens, mode.id, undefined, themeIds)), ':root', '    ');
+        if (held.length === 0)
+            continue;
+        lines.push(`  @media ${mode.is} {`, ...held, '  }', '');
+    }
+    for (const theme of themes) {
+        lines.push(...variables(played(shifted(guide, tokens, undefined, theme.id, themeIds)), themedBy(theme.id), '  '));
+        for (const mode of modes) {
+            const held = variables(played(shifted(guide, tokens, mode.id, theme.id, themeIds)), themedBy(theme.id), '    ');
+            if (held.length === 0)
+                continue;
+            lines.push(`  @media ${mode.is} {`, ...held, '  }', '');
+        }
+    }
+    const asked = modes.map((mode) => mode.id).join(' ');
+    lines.push(...(asked === '' ? [] : ['  :root {', `    color-scheme: ${asked};`, '  }', '']), '  body {', '    background: var(--colour-page);', '    color: var(--colour-ink);', '  }', '');
+    lines.push('}', '');
+    const type = typography(fonts);
+    lines.push('@layer font {', ...type.lines, '}', '');
+    lines.push('@layer animation {');
+    for (const id of Object.keys(animations).sort(compare)) {
+        const animation = animations[id];
+        if (animation === undefined)
+            continue;
+        lines.push(`  @keyframes ${keyframeName(id)} {`);
+        for (const stop of stopsOf(animation, named, tokens, kinds))
+            lines.push(...block(stop.stop, stop.made, '    '));
+        lines.push('  }', '');
+    }
+    lines.push('}', '');
+    const moving = new Map();
+    for (const id of Object.keys(materials).sort(compare)) {
+        const material = materials[id];
+        if (material === undefined)
+            continue;
+        for (const one of keyframesOf(material, named, tokens, kinds)) {
+            const already = moving.get(one.id);
+            if (already !== undefined) {
+                throw new Error(`\`${id}\` and \`${already.by}\` both declare keyframes called \`${one.id}\`, and a ` +
+                    'stylesheet holds one rule per name, so whichever came last would silently win.');
+            }
+            moving.set(one.id, { by: id, stops: one.stops });
+        }
+    }
+    lines.push('@layer material {');
+    for (const name of [...moving.keys()].sort(compare)) {
+        lines.push(`  @keyframes ${name} {`);
+        for (const stop of moving.get(name)?.stops ?? [])
+            lines.push(...block(stop.stop, stop.made, '    '));
+        lines.push('  }', '');
+    }
+    for (const id of Object.keys(materials).sort(compare)) {
+        const material = materials[id];
+        if (material === undefined)
+            continue;
+        const gap = undeclaredStates(material)[0];
+        if (gap !== undefined)
+            throw new Error(`\`${id}\`: ${gap}`);
+        compose(material, named, tokens, kinds);
+        under(material, named, tokens, kinds);
+    }
+    lines.push('}', '');
+    lines.push('@layer variant {');
+    for (const id of Object.keys(variants).sort(compare)) {
+        const variant = variants[id];
+        if (variant === undefined)
+            continue;
+        const whole = statesOf(variant, materials);
+        const first = undeclaredStates(whole)[0];
+        if (first !== undefined)
+            throw new Error(`\`${id}\`: ${first}`);
+        const unclaimed = unreacted(variant, materials)[0];
+        if (unclaimed !== undefined)
+            throw new Error(unclaimed);
+        let typed = {};
+        if (variant.type !== undefined) {
+            const role = type.roles.get(variant.type);
+            if (role === undefined) {
+                const has = [...type.roles.keys()].sort(compare).map((one) => `\`${one}\``);
+                throw new Error(`\`${id}\` sets its wording in the \`${variant.type}\` role, and the fonts sheet declares ` +
+                    `no role by that name. The declared roles are ${has.join(', ')}.`);
+            }
+            typed = role;
+        }
+        const made = { ...typed, ...complete(variant, materials, named, tokens, kinds) };
+        lines.push(...block(`.${classOf(id)}`, made, '  '));
+        lines.push(...playing(`.${classOf(id)}`, variant.plays, named, id));
+        lines.push(...symbols(id, variant.icon, named, made['display'] !== undefined));
+        for (const state of under(whole, named, tokens, kinds)) {
+            lines.push(...block(`.${classOf(id)}${state.marks}`, state.made, '  '));
+        }
+    }
+    lines.push('}', '');
+    for (const held of [
+        { layer: 'element', named: classOfElement, rows: elements },
+        { layer: 'composition', named: classOfComposition, rows: compositions },
+        { layer: 'screen', named: classOfScreen, rows: screens },
+    ]) {
+        lines.push(`@layer ${held.layer} {`);
+        for (const row of [...held.rows].sort((one, two) => compare(one.id, two.id))) {
+            const selector = `.${held.named(row.id)}`;
+            lines.push(...block(selector, resolved(row.sets ?? {}, guide, row.id, row.measures), '  '));
+            lines.push(...playing(selector, row.plays, named, row.id));
+            for (const [id, made] of Object.entries(row.places ?? {})) {
+                if (!PLACE.test(id)) {
+                    throw new Error(`\`${row.id}\` gives a place the name "${id}", and a place is named in the markup as \`at="${id}"\` ` +
+                        'and becomes part of a class, so it has to be lowercase words joined by dashes. Anything else ' +
+                        'produces a class the child can never match, and nothing would look wrong until you saw the screen.');
+                }
+                const looks = Object.fromEntries(Object.entries(made).filter(([key]) => !SAID.has(key)));
+                lines.push(...block(`${selector}-${id}`, resolved(looks, guide, `${row.id} place \`${id}\``, row.measures), '  '));
+            }
+            for (const [id, made] of Object.entries(row.modes ?? {})) {
+                if (typeof made === 'string')
+                    continue;
+                const query = modes.find((one) => one.id === id)?.is;
+                if (query === undefined) {
+                    throw new Error(`\`${row.id}\` arranges itself under "${id}", and no mode by that name is declared, so nothing ` +
+                        'can tell when it applies. A breakpoint is a mode — declare it beside dark and light, with the ' +
+                        'width as its query.');
+                }
+                lines.push(`  @media ${query} {`, ...block(selector, resolved(made, guide, row.id), '    '), '  }', '');
+            }
+        }
+        lines.push('}', '');
+    }
+    return lines.join('\n');
+}
+const LAID = 'layout-flex';
+const CENTRED = 'align-centre';
+function symbols(id, size, named, laid) {
+    if (size === undefined)
+        return [];
+    const row = sizeNamed(size);
+    if (!named.has(row)) {
+        const has = [...named].filter((one) => one.startsWith(SIZE_PREFIX)).sort(compare).map((one) => `\`${one}\``);
+        throw new Error(`\`${id}\` draws the symbol inside it at \`${row}\`, and the icons sheet declares no size by ` +
+            `that name. The declared sizes are ${has.join(', ')}.`);
+    }
+    const drawn = naming(named, row, id, 'the size its symbol is drawn at');
+    const centred = laid || !named.has(LAID) || !named.has(CENTRED)
+        ? []
+        : block(`.${classOf(id)}`, {
+            display: naming(named, LAID, id, 'how what it holds is laid out'),
+            alignItems: naming(named, CENTRED, id, 'where its symbol sits across that'),
+        }, '  ');
+    return [
+        ...centred,
+        ...block(`.${classOf(id)} > svg`, { width: drawn, height: drawn, minWidth: drawn, minHeight: drawn }, '  '),
+    ];
+}
+function typography(node) {
+    const rows = inside(node);
+    const roles = new Map();
+    const picked = rows.find((row) => row.id === 'family-set');
+    if (picked?.is === undefined) {
+        throw new Error('The fonts sheet declares no `family-set` row, so nothing says which set of families the app ' +
+            'draws from. One row, naming a registered set — every face is drawn from it.');
+    }
+    const set = setNamed(picked.is);
+    const faces = {};
+    const classes = [];
+    for (const row of rows) {
+        if (row.id === 'family-set')
+            continue;
+        if (row.sets === undefined) {
+            throw new Error(`\`${row.id}\` is declared a font role and states nothing about how it is set. A role names a ` +
+                'face and states its size, weight, leading and tracking.');
+        }
+        const role = row.sets;
+        const family = familyFor(set, role.face, row.id);
+        faces[role.face] = fontStack(family);
+        const made = settingsOf(row.id, role);
+        roles.set(row.id, made);
+        classes.push(...block(`.${classOfRole(row.id)}`, made, '  '));
+    }
+    const held = ['  :root {'];
+    for (const face of Object.keys(faces).sort(compare))
+        held.push(`    ${fontVariable(face)}: ${faces[face] ?? ''};`);
+    held.push('  }', '');
+    return { lines: [...held, ...classes], roles };
+}
+function playing(selector, plays, named, by) {
+    const held = [];
+    for (const [moment, row, on] of [
+        ['in', plays?.in, `${selector}[data-arriving]`],
+        ['out', plays?.out, `${selector}[data-leaving]`],
+    ]) {
+        if (row === undefined)
+            continue;
+        if (!named.has(row)) {
+            throw new Error(`\`${by}\` plays \`${row}\` on the way ${moment}, and the style guide holds no row by that name. ` +
+                'What a thing plays is a style guide value like any other — name a row, and the row names the animation.');
+        }
+        held.push(...block(on, { animation: naming(named, row, by, `what it plays on the way ${moment}`) }, '  '));
+    }
+    return held;
+}
+const PLACE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const SAID = structural;
+const RAW = /\d\s*(px|rem|em|ch|vh|vw)\b|\d%|#[0-9a-fA-F]{3,8}\b|\brgba?\(|\bhsla?\(/;
+function resolved(sets, guide, by, measures = []) {
+    const made = {};
+    const bound = boundHeld();
+    for (const [property, whole] of Object.entries(sets)) {
+        const words = whole.trim().split(/\s+/);
+        const held = [];
+        for (const value of words) {
+            if (measures.includes(value)) {
+                held.push(`var(--${value})`);
+                continue;
+            }
+            if (RAW.test(value)) {
+                throw new Error(`\`${by}\` sets ${property} to "${value}", and that is a value written where a name belongs. ` +
+                    'An arrangement names a style guide row and the row holds the value — so the whole app moves ' +
+                    'when the row moves. Add a row for it, or name one that exists.');
+            }
+            const row = guide.picks.find((one) => one.id === value);
+            if (row === undefined) {
+                throw new Error(`\`${by}\` sets ${property} to "${value}", and that names neither a style guide row nor one ` +
+                    "of this element's measures. A name that is neither is written into the stylesheet as-is " +
+                    'and thrown away by the browser. Declare it in `measures`, or name a row.');
+            }
+            const kinds = bound[property];
+            if (kinds !== undefined && !kinds.includes(String(row.token))) {
+                throw new Error(`\`${by}\` sets ${property} to \`${value}\`, which is a \`${String(row.token)}\` row. ` +
+                    `${property} takes ${kinds.map((one) => `\`${one}\``).join(' or ')}. A row of the wrong kind ` +
+                    'is written into the stylesheet and dropped by the browser without a word.');
+            }
+            held.push(`var(--${value})`);
+        }
+        made[property] = sheeted(whole, held.join(' '));
+    }
+    return made;
+}
+async function fileFor(root, at, id, what) {
+    const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(root, at)).href)));
+    const one = module[exported(id)];
+    if (one === undefined) {
+        throw new Error(`${what} \`${id}\` is declared at ${at}, and that file exports no \`${exported(id)}\`. ` +
+            'A row names a file, and the file is the thing.');
+    }
+    return one;
+}
+async function loaded(root, node, what) {
+    const found = {};
+    for (const row of inside(node)) {
+        if (row.at === undefined) {
+            throw new Error(`${what} \`${row.id}\` names no file, so there is nothing to read it from.`);
+        }
+        found[row.id] = await fileFor(root, row.at, row.id, what);
+    }
+    return found;
+}
+async function tokensIn(root, node) {
+    const found = {};
+    for (const row of inside(node)) {
+        found[row.id] =
+            row.at === undefined || row.at === node.at
+                ? { id: row.id }
+                : await fileFor(root, row.at, row.id, 'token');
+    }
+    return found;
+}
+function guideIn(node) {
+    return {
+        id: node.id ?? 'styleguide',
+        picks: inside(node).map((row) => {
+            if (row.token === undefined) {
+                throw new Error(`\`${row.id}\` names no token. A style guide row is one value OF a token, so it has to ` +
+                    'say which token it is one of.');
+            }
+            return {
+                id: row.id,
+                token: row.token,
+                ...(row.is === undefined ? {} : { is: row.is }),
+                ...(row.asks === undefined ? {} : { asks: row.asks }),
+                ...(row.modes === undefined
+                    ? {}
+                    : {
+                        modes: Object.fromEntries(Object.entries(row.modes).filter((one) => typeof one[1] === 'string')),
+                    }),
+                ...(row.themes === undefined ? {} : { themes: row.themes }),
+            };
+        }),
+    };
+}
+function pascal(id) {
+    return id
+        .split('-')
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join('');
+}
+function unwearable(variants, elements) {
+    const declared = new Set((elements.declares ?? []).map((row) => pascal(row.id)));
+    const missing = [];
+    for (const row of variants.declares ?? []) {
+        for (const element of row.wears ?? []) {
+            if (declared.has(element))
+                continue;
+            missing.push(`\`${row.id}\` says \`${element}\` accepts it, and no element by that name is declared, ` +
+                'so nothing would ever wear it.');
+        }
+    }
+    return missing;
+}
+function modesIn(node) {
+    return inside(node).map((row) => {
+        if (row.is === undefined) {
+            throw new Error(`\`${row.id}\` is declared a mode and states no query, so nothing could tell when it applies. ` +
+                'A mode is the question a device asks — give it the media query that answers it.');
+        }
+        return { id: row.id, is: row.is };
+    });
+}
+const OWN_AT = '../..';
+async function node(root, file, name) {
+    const own = argv.includes('--own');
+    const at = own ? resolve(fileURLToPath(import.meta.url), OWN_AT, file) : inTree(findTree(), file);
+    if (!own && !existsSync(at)) {
+        stdout.write(`styles: this tree has no ${findTree().name}/${file}, so it declares nothing to style and there is no stylesheet to write or check.\n`);
+        exit(0);
+    }
+    const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(at).href)));
+    const one = module[own ? `${name}S` : name];
+    if (one === undefined) {
+        throw new Error(own ? `this package's own ${file} exports no \`${name}S\`.` : `_threads/${file} exports no \`${name}\`.`);
+    }
+    return one;
+}
+async function run() {
+    const own = argv.includes('--own');
+    const root = own ? resolve(fileURLToPath(import.meta.url), '../../../../..') : findTree().at;
+    knowSignals(inside(await node(root, 'signals.ts', 'SIGNAL')).map((one) => one.id));
+    const tokens = await tokensIn(root, await node(root, 'tokens.ts', 'TOKEN'));
+    const guide = guideIn(await node(root, 'styleguides.ts', 'STYLEGUIDE'));
+    const materials = await loaded(root, await node(root, 'materials.ts', 'MATERIAL'), 'material');
+    const declaring = await node(root, 'variants.ts', 'VARIANT');
+    const variants = await loaded(root, declaring, 'variant');
+    const unworn = unwearable(declaring, await node(root, 'elements.ts', 'ELEMENT'))[0];
+    if (unworn !== undefined)
+        throw new Error(unworn);
+    const fonts = await node(root, 'fonts.ts', 'FONT');
+    const icons = await node(root, `icons.${'ts'}`, 'ICON');
+    const animations = await loaded(root, await node(root, 'animations.ts', 'ANIMATION'), 'animation');
+    const modes = modesIn(await node(root, 'modes.ts', 'MODE'));
+    const themes = inside(await node(root, 'themes.ts', 'THEME'));
+    const screens = (await node(root, 'screens.ts', 'SCREEN')).declares ?? [];
+    const compositions = (await node(root, 'compositions.ts', 'COMPOSITION')).declares ?? [];
+    const elements = ((await node(root, 'elements.ts', 'ELEMENT')).declares ?? []).filter((one) => one.sets !== undefined || one.places !== undefined);
+    const camelOf = (id) => id.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+    const worn = (declaring.declares ?? [])
+        .filter((one) => typeof one.id === 'string' && (one.wears ?? []).length > 0)
+        .map((one) => `    readonly ${camelOf(String(one.id))}: ${(one.wears ?? []).map((e) => `'${e}'`).join(' | ')}`);
+    const asking = ((await node(root, 'signals.ts', 'SIGNAL')).holds ?? []).filter((one) => typeof one.id === 'string');
+    const wearingSource = [
+        '/* GENERATED by thread — do not edit. It is derived from what this app declares. */',
+        '',
+        `declare module '${packageOf('ui')}/checked' {`,
+        ...(worn.length === 0 ? ['  interface Wearing {}'] : ['  interface Wearing {', ...worn, '  }']),
+        '}',
+        '',
+        'export const ASKING = [',
+        ...asking.map((one) => `  { id: '${String(one.id)}', selector: '${one.selector ?? `[data-${String(one.id)}]`}' },`),
+        '] as const',
+        '',
+    ].join('\n');
+    const at = join(root, 'app/_generated/tokens.css');
+    const made = sheet(tokens, guide, materials, variants, modes, themes, screens, compositions, elements, fonts, icons, animations);
+    if (own) {
+        stdout.write(`styles: this framework's own declarations build a stylesheet — ${String(guide.picks.length)} values, ` +
+            `${String(Object.keys(materials).length)} materials, ${String(Object.keys(variants).length)} variants, ` +
+            `${String(Object.keys(animations).length)} animations, every one naming rows that exist. ` +
+            'Nothing is written: a stylesheet belongs to an app, and building it is the check.\n');
+        return 0;
+    }
+    if (argv.includes('--check')) {
+        let current = '';
+        try {
+            current = readFileSync(at, 'utf8');
+        }
+        catch {
+            current = '';
+        }
+        if (current === made) {
+            stdout.write('styles: app/_generated/tokens.css is the bytes the declarations produce\n');
+            return 0;
+        }
+        stderr.write('styles: app/_generated/tokens.css is not what the declarations produce. A derived file that ' +
+            'differs from its generator is a hand edit wearing a generated name, and every reader downstream ' +
+            'believes the wrong one. Run `thread styles` and commit what it writes.\n');
+        return 1;
+    }
+    mkdirSync(dirname(at), { recursive: true });
+    writeFileSync(at, made, 'utf8');
+    writeFileSync(join(root, 'app/_generated/declared.ts'), wearingSource, 'utf8');
+    stdout.write(`thread: wrote app/_generated/tokens.css — ${String(Object.keys(tokens).length)} tokens, ` +
+        `${String(guide.picks.length)} values, ${String(Object.keys(materials).length)} materials, ` +
+        `${String(Object.keys(variants).length)} variants, ${String(inside(fonts).length - 1)} font roles, ` +
+        `${String(Object.keys(animations).length)} animations, ${String(modes.length)} modes, ` +
+        `${String(themes.length)} themes, ${String(compositions.length)} compositions, ${String(screens.length)} screens\n`);
+    return 0;
+}
+if (argv[1] !== undefined)
+    exit(await run());

package/dist/ui/generators/variants.d.ts

@@ -0,0 +1,12 @@
+import type { Threaded } from '@prestack/thread/core/thread';
+export declare function nameOf(id: string): string;
+export declare function seeds(rows: readonly Threaded[], has: (at: string) => boolean): readonly {
+    readonly path: string;
+    readonly content: string;
+}[];
+export declare function mismatched(rows: readonly Threaded[], loader: (row: Threaded) => Promise<{
+    readonly id?: string;
+} | undefined>): Promise<readonly string[]>;
+export declare function orphaned(rows: readonly Threaded[], strays: readonly string[]): readonly string[];
+export declare function unguarded(rows: readonly Threaded[], read: (at: string) => string): readonly string[];
+export declare function guarding(source: string): string | undefined;

package/dist/ui/generators/variants.js

@@ -0,0 +1,162 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { exit, invoked } from "@prestack/thread/core/invoked";
+import { findTree, inTree, strayFiles } from "@prestack/thread/core/tree";
+export function nameOf(id) {
+    return id.replace(/-/g, '_').toUpperCase();
+}
+function starter(row) {
+    return `import { variant } from '../variant.ts'
+
+export const ${nameOf(row.id)} = variant({
+  id: '${row.id}',
+  sets: [],
+  reacts: [],
+} as const)
+`;
+}
+export function seeds(rows, has) {
+    return rows.filter((row) => !has(row.at)).map((row) => ({ path: row.at, content: starter(row) }));
+}
+export async function mismatched(rows, loader) {
+    const found = [];
+    for (const row of rows) {
+        const variant = await loader(row);
+        if (variant === undefined) {
+            found.push(`\`${row.id}\` is declared at \`${row.at}\`, and that file exports no \`${nameOf(row.id)}\`. ` +
+                'A row names a file, and the file is the thing.');
+            continue;
+        }
+        if (variant.id !== row.id) {
+            found.push(`\`${row.at}\` declares itself \`${String(variant.id)}\`, and the row that names it calls it \`${row.id}\`. ` +
+                "A variant file and the row that names it have to be the same variant — make the file's `id` match the row, or fix the row.");
+        }
+    }
+    return found;
+}
+function extensionOf(path) {
+    const name = basename(path);
+    const at = name.lastIndexOf('.');
+    return at === -1 ? '' : name.slice(at);
+}
+const VAR_PREFIX = /^var_/;
+export function orphaned(rows, strays) {
+    const named = new Set(rows.map((row) => row.at));
+    return strays
+        .filter((one) => !named.has(one))
+        .map((one) => `\`${one}\` is under variants and no row names it — not a variant, a file somebody wrote. ` +
+        'Add a row for it, or delete the file.');
+}
+const GUARDED = /=\s*variant\s*\(/;
+const TYPED = /import type \{ Variant \} from '([^']*)'/;
+const OPENS = /export const ([A-Z0-9_]+) = \{/;
+const CLOSES = /\} as const satisfies Variant/;
+export function unguarded(rows, read) {
+    return rows
+        .filter((row) => !GUARDED.test(read(row.at)))
+        .map((row) => `\`${row.at}\` declares \`${row.id}\` with \`satisfies Variant\`, which accepts a value no ` +
+        'row holds — `satisfies` checks against `string`, so `8px` and `var(--x)` compile. Run ' +
+        '`thread variants` and it rewrites the two lines that wrap the declaration, leaving what is ' +
+        'between them alone.');
+}
+export function guarding(source) {
+    if (GUARDED.test(source))
+        return undefined;
+    const typed = TYPED.exec(source);
+    const opens = OPENS.exec(source);
+    if (typed === null || opens === null || !CLOSES.test(source))
+        return undefined;
+    return source
+        .replace(typed[0], `import { variant } from '${typed[1] ?? ''}'`)
+        .replace(opens[0], `export const ${opens[1] ?? ''} = variant({`)
+        .replace(CLOSES, '} as const)');
+}
+const SHEET = `variants.${'ts'}`;
+const MINE = `variants.${'ts'}`;
+async function run() {
+    const own = argv.includes('--own');
+    const held = own
+        ? (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(fileURLToPath(import.meta.url), '../..', MINE)).href)))
+        : undefined;
+    const tree = own ? undefined : findTree();
+    const root = tree === undefined ? resolve(fileURLToPath(import.meta.url), '../../../../..') : tree.at;
+    if (tree !== undefined && !existsSync(inTree(tree, SHEET))) {
+        stdout.write(`thread: this tree has no ${tree.name}/${SHEET}, so it declares no variant and there is nothing to seed or check.\n`);
+        return 0;
+    }
+    const sheet = tree === undefined
+        ? { VARIANT: held?.VARIANTS }
+        : (await import(__rewriteRelativeImportExtension(pathToFileURL(inTree(tree, SHEET)).href)));
+    if (sheet.VARIANT === undefined) {
+        stdout.write(own
+            ? `variants: this package's own ${MINE} exports no \`VARIANTS\`.\n`
+            : `thread: ${String(tree?.name)}/${SHEET} exports no \`VARIANT\`, so nothing declares a variant here.\n`);
+        return 1;
+    }
+    const rows = sheet.VARIANT.declares ?? [];
+    const checking = argv.includes('--check');
+    const exists = (where) => existsSync(join(root, where));
+    const made = seeds(rows, exists);
+    if (checking) {
+        const unseeded = rows.find((row) => !exists(row.at));
+        if (unseeded !== undefined) {
+            stdout.write(`thread: \`${unseeded.id}\` is declared at \`${unseeded.at}\`, and the file is not there yet. ` +
+                'A row names a file, and `--check` never writes one — run `thread variants` and commit what it seeds.\n');
+            return 1;
+        }
+    }
+    else {
+        for (const seed of made) {
+            mkdirSync(dirname(join(root, seed.path)), { recursive: true });
+            writeFileSync(join(root, seed.path), seed.content, 'utf8');
+            stdout.write(`thread: seeded ${seed.path}\n`);
+        }
+    }
+    const wrong = (await mismatched(rows, async (row) => {
+        const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(join(root, row.at)).href)));
+        return module[nameOf(row.id)];
+    }))[0];
+    if (wrong !== undefined) {
+        stdout.write(`thread: ${wrong}\n`);
+        return 1;
+    }
+    const read = (at) => readFileSync(join(root, at), 'utf8');
+    if (checking) {
+        const loose = unguarded(rows, read)[0];
+        if (loose !== undefined) {
+            stdout.write(`thread: ${loose}\n`);
+            return 1;
+        }
+    }
+    else {
+        for (const row of rows) {
+            const written = guarding(read(row.at));
+            if (written === undefined)
+                continue;
+            writeFileSync(join(root, row.at), written, 'utf8');
+            stdout.write(`thread: ${row.at} now declares through \`variant(...)\`\n`);
+        }
+    }
+    const stray = orphaned(rows, strayFiles(root, 'var_', '.' + 'ts'))[0];
+    if (stray !== undefined) {
+        stdout.write(`thread: ${stray}\n`);
+        return 1;
+    }
+    stdout.write(checking
+        ? `thread: ${String(rows.length)} variant(s) declared, all seeded\n`
+        : `thread: ${String(rows.length)} variant(s) declared, ${String(made.length)} seeded, ` +
+            `${String(rows.length - made.length)} already written\n`);
+    return 0;
+}
+if (invoked(import.meta.url))
+    exit(await run());