@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/brand.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Resolve an optional blueprint `brand` block into a full Theme for
+ * `protoyard generate`. Palette tokens come from `@protoyard/themes`
+ * (`createThemeFromSeed` or a built-in preset); fonts, radius and density
+ * come from the brand and/or a named style profile. Every resolved theme is
+ * checked against WCAG AA text and UI pairs before it is returned.
+ */
+import { type Theme, type ThemeStyleInput } from '@protoyard/core';
+import type { BlueprintBrand } from './schema.ts';
+export interface StyleProfile {
+    id: string;
+    label: string;
+    radius?: string;
+    density?: number;
+    font?: string;
+    style?: ThemeStyleInput;
+}
+/** Named style knobs applied after the palette (or preset) is chosen. */
+export declare const STYLE_PROFILES: readonly StyleProfile[];
+export declare function getStyleProfile(id: string): StyleProfile | undefined;
+export interface ResolveBrandOptions {
+    /** Blueprint product name — used when brand.name / brand.id are omitted. */
+    blueprintName?: string;
+}
+export declare class BrandThemeError extends Error {
+    readonly failures: readonly BrandContrastFailure[];
+    constructor(message: string, failures?: readonly BrandContrastFailure[]);
+}
+export interface BrandContrastFailure {
+    mode: 'light' | 'dark';
+    foreground: string;
+    background: string;
+    minimum: number;
+    ratio: number;
+}
+/**
+ * Up to `limit` ids from `known` nearest to `id`: ids that contain it (or that
+ * it contains) first, then by edit distance, ties in `known` order. Only ids
+ * within half the longer length are suggested, so unrelated names stay out.
+ */
+export declare function closestIds(id: string, known: readonly string[], limit?: number): string[];
+/**
+ * The library theme a brand names (`brand.libraryTheme`), or `undefined` when
+ * the brand builds its own theme. A library brand needs no generated module:
+ * the prototype's `defaultTheme` is the library id and the renderer loads it.
+ * Throws `BrandThemeError` (with the closest ids) when the library does not
+ * know the id.
+ */
+export declare function brandLibraryThemeId(brand: BlueprintBrand): string | undefined;
+/**
+ * Stable theme id from brand or blueprint name (`Acme Labs` → `acme-labs`);
+ * a library brand's id is the library theme id.
+ */
+export declare function brandThemeId(brand: BlueprintBrand, blueprintName?: string): string;
+/**
+ * `acme-labs` → `acmeLabsTheme` for the generated module export. Throws
+ * `BrandThemeError` for an id that cannot become a valid identifier.
+ */
+export declare function brandThemeExportName(themeId: string): string;
+/**
+ * Build a complete Theme from a validated blueprint brand block.
+ * Throws `BrandThemeError` when the result fails AA or a catalog id is unknown,
+ * and for a library brand, which ships by id (see `brandLibraryThemeId`).
+ */
+export declare function resolveBlueprintBrand(brand: BlueprintBrand, options?: ResolveBrandOptions): Theme;
+/**
+ * TypeScript module body for `src/generated/brand-theme.ts` (no header).
+ * The CLI wraps it with the generate hash header.
+ */
+export declare function emitBrandThemeModule(theme: Theme): string;

package/dist/brand.js

@@ -0,0 +1,294 @@
+/**
+ * Resolve an optional blueprint `brand` block into a full Theme for
+ * `protoyard generate`. Palette tokens come from `@protoyard/themes`
+ * (`createThemeFromSeed` or a built-in preset); fonts, radius and density
+ * come from the brand and/or a named style profile. Every resolved theme is
+ * checked against WCAG AA text and UI pairs before it is returned.
+ */
+import { defineTheme } from '@protoyard/core';
+import { ALL_LIBRARY_THEME_IDS, BUILTIN_THEMES, contrastRatio, createThemeFromSeed, getFontPairing, isLibraryThemeId, TEXT_CONTRAST_PAIRS, UI_CONTRAST_PAIRS, } from '@protoyard/themes';
+import { z } from 'zod';
+/** Named style knobs applied after the palette (or preset) is chosen. */
+export const STYLE_PROFILES = [
+    {
+        id: 'soft',
+        label: 'Soft',
+        radius: '0.75rem',
+        density: 1.05,
+        style: { elevation: 'soft', shape: { radiusScale: 1.2 } },
+    },
+    {
+        id: 'crisp',
+        label: 'Crisp',
+        radius: '0.375rem',
+        density: 0.9,
+        style: { elevation: 'crisp', shape: { radiusScale: 0.6, borderWidth: '1px' } },
+    },
+    {
+        id: 'flat',
+        label: 'Flat',
+        radius: '0.5rem',
+        density: 1,
+        style: { elevation: 'flat', shape: { borderWidth: '1px' } },
+    },
+    {
+        id: 'rounded',
+        label: 'Rounded',
+        radius: '1rem',
+        density: 1.05,
+        style: { elevation: 'soft', shape: { radiusScale: 1.6 }, surface: 'solid' },
+    },
+    {
+        id: 'editorial',
+        label: 'Editorial',
+        radius: '0.25rem',
+        density: 1.05,
+        font: 'editorial',
+        style: {
+            elevation: 'soft',
+            typography: {
+                scaleRatio: 1.25,
+                weights: { body: 400, medium: 500, heading: 600, bold: 700 },
+                tracking: { body: '0.01em', heading: '-0.02em' },
+            },
+        },
+    },
+    {
+        id: 'mono',
+        label: 'Mono',
+        radius: '0.375rem',
+        density: 0.9,
+        font: 'mono',
+        style: {
+            elevation: 'crisp',
+            surface: 'solid',
+            shape: { radiusScale: 0.6, borderWidth: '1px' },
+            typography: { tracking: { body: '0', heading: '-0.02em' } },
+        },
+    },
+];
+export function getStyleProfile(id) {
+    return STYLE_PROFILES.find((profile) => profile.id === id);
+}
+export class BrandThemeError extends Error {
+    failures;
+    constructor(message, failures = []) {
+        super(message);
+        this.name = 'BrandThemeError';
+        this.failures = failures;
+    }
+}
+/** Edit distance between two short ids (single-row Levenshtein). */
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = row[j];
+            row[j] = Math.min(above + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length];
+}
+/**
+ * Up to `limit` ids from `known` nearest to `id`: ids that contain it (or that
+ * it contains) first, then by edit distance, ties in `known` order. Only ids
+ * within half the longer length are suggested, so unrelated names stay out.
+ */
+export function closestIds(id, known, limit = 3) {
+    return known
+        .map((candidate, index) => {
+        const contains = candidate.includes(id) || id.includes(candidate);
+        return { candidate, index, distance: contains ? 0 : editDistance(id, candidate) };
+    })
+        .filter(({ candidate, distance }) => distance <= Math.ceil(Math.max(id.length, candidate.length) / 2))
+        .sort((a, b) => a.distance - b.distance || a.index - b.index)
+        .slice(0, limit)
+        .map(({ candidate }) => candidate);
+}
+/**
+ * The library theme a brand names (`brand.libraryTheme`), or `undefined` when
+ * the brand builds its own theme. A library brand needs no generated module:
+ * the prototype's `defaultTheme` is the library id and the renderer loads it.
+ * Throws `BrandThemeError` (with the closest ids) when the library does not
+ * know the id.
+ */
+export function brandLibraryThemeId(brand) {
+    const id = brand.libraryTheme;
+    if (id === undefined || isLibraryThemeId(id))
+        return id;
+    const near = closestIds(id, ALL_LIBRARY_THEME_IDS);
+    throw new BrandThemeError(`Unknown library theme "${id}"${near.length > 0 ? ` (closest: ${near.join(', ')})` : ''}.`);
+}
+/**
+ * Stable theme id from brand or blueprint name (`Acme Labs` → `acme-labs`);
+ * a library brand's id is the library theme id.
+ */
+export function brandThemeId(brand, blueprintName) {
+    if (brand.libraryTheme)
+        return brand.libraryTheme;
+    if (brand.id)
+        return brand.id;
+    const source = brand.name ?? blueprintName ?? 'brand';
+    const slug = source
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (slug.length === 0)
+        return 'brand';
+    // Theme ids (and so export names) start with a letter: `3D Print` → `brand-3d-print`.
+    const id = /^[a-z]/.test(slug) ? slug : `brand-${slug}`;
+    return id.slice(0, 40).replace(/-+$/, '');
+}
+const EXPORT_NAME = /^[A-Za-z_$][\w$]*$/;
+/**
+ * `acme-labs` → `acmeLabsTheme` for the generated module export. Throws
+ * `BrandThemeError` for an id that cannot become a valid identifier.
+ */
+export function brandThemeExportName(themeId) {
+    const camel = themeId.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+    const name = `${camel}Theme`;
+    if (!EXPORT_NAME.test(name)) {
+        throw new BrandThemeError(`Brand theme id "${themeId}" does not map to a valid export name; use lowercase kebab-case.`);
+    }
+    return name;
+}
+function themeDisplayName(brand, blueprintName) {
+    const raw = (brand.name ?? blueprintName ?? 'Brand').trim();
+    return raw.slice(0, 40) || 'Brand';
+}
+function assertAa(theme) {
+    const failures = [];
+    for (const mode of ['light', 'dark']) {
+        const palette = theme[mode];
+        for (const [foreground, background] of TEXT_CONTRAST_PAIRS) {
+            try {
+                const ratio = contrastRatio(palette[foreground], palette[background]);
+                if (ratio < 4.5) {
+                    failures.push({ mode, foreground, background, minimum: 4.5, ratio });
+                }
+            }
+            catch {
+                failures.push({ mode, foreground, background, minimum: 4.5, ratio: 0 });
+            }
+        }
+        for (const [foreground, background] of UI_CONTRAST_PAIRS) {
+            try {
+                const ratio = contrastRatio(palette[foreground], palette[background]);
+                if (ratio < 3) {
+                    failures.push({ mode, foreground, background, minimum: 3, ratio });
+                }
+            }
+            catch {
+                failures.push({ mode, foreground, background, minimum: 3, ratio: 0 });
+            }
+        }
+    }
+    if (failures.length > 0) {
+        throw new BrandThemeError(`Brand theme "${theme.id}" fails WCAG AA (${failures.length} pair(s)).`, failures);
+    }
+    return theme;
+}
+function applyFinishes(theme, brand, profile) {
+    const fontId = brand.font ?? profile?.font;
+    const pairing = fontId ? getFontPairing(fontId) : undefined;
+    if (fontId && !pairing) {
+        throw new BrandThemeError(`Unknown font pairing "${fontId}".`);
+    }
+    const radius = brand.radius ?? profile?.radius;
+    const density = brand.density ?? profile?.density;
+    const style = profile?.style;
+    return defineTheme({
+        id: theme.id,
+        name: theme.name,
+        description: theme.description,
+        light: theme.light,
+        dark: theme.dark,
+        fontFamily: pairing?.fontFamily ?? theme.fontFamily,
+        ...(pairing?.fontFamilyHeading !== undefined
+            ? { fontFamilyHeading: pairing.fontFamilyHeading }
+            : theme.fontFamilyHeading
+                ? { fontFamilyHeading: theme.fontFamilyHeading }
+                : {}),
+        fontFamilyMono: pairing?.fontFamilyMono ?? theme.fontFamilyMono,
+        radius: radius ?? theme.radius,
+        density: density ?? theme.density,
+        ...(style || theme.style ? { style: { ...(theme.style ?? {}), ...(style ?? {}) } } : {}),
+    });
+}
+/**
+ * Build a complete Theme from a validated blueprint brand block.
+ * Throws `BrandThemeError` when the result fails AA or a catalog id is unknown,
+ * and for a library brand, which ships by id (see `brandLibraryThemeId`).
+ */
+export function resolveBlueprintBrand(brand, options = {}) {
+    try {
+        return buildBrandTheme(brand, options);
+    }
+    catch (error) {
+        // A theme the core schema rejects is a blueprint problem, not an internal error.
+        if (error instanceof z.ZodError || error?.name === 'ZodError') {
+            const issue = error.issues[0];
+            throw new BrandThemeError(`Brand theme is invalid: ${issue ? `${issue.path.map(String).join('.') || '(root)'} — ${issue.message}` : 'unknown error'}`);
+        }
+        throw error;
+    }
+}
+function buildBrandTheme(brand, options) {
+    if (brand.libraryTheme) {
+        throw new BrandThemeError(`Brand uses library theme "${brand.libraryTheme}"; it ships by id, so there is no theme to build.`);
+    }
+    const id = brandThemeId(brand, options.blueprintName);
+    const name = themeDisplayName(brand, options.blueprintName);
+    const profile = brand.styleProfile ? getStyleProfile(brand.styleProfile) : undefined;
+    if (brand.styleProfile && !profile) {
+        throw new BrandThemeError(`Unknown style profile "${brand.styleProfile}".`);
+    }
+    let base;
+    if (brand.seed) {
+        base = createThemeFromSeed({
+            id,
+            name,
+            seed: brand.seed,
+            ...(brand.secondary ? { secondary: brand.secondary } : {}),
+            ...(profile?.style ? { style: profile.style } : {}),
+        });
+    }
+    else {
+        const presetId = brand.preset;
+        const preset = BUILTIN_THEMES.find((theme) => theme.id === presetId);
+        if (!preset) {
+            throw new BrandThemeError(`Unknown theme preset "${presetId}".`);
+        }
+        base = defineTheme({
+            ...preset,
+            id,
+            name,
+            description: `Brand theme from the ${preset.name} preset.`,
+            light: { ...preset.light },
+            dark: { ...preset.dark },
+            ...(preset.style ? { style: { ...preset.style } } : {}),
+        });
+    }
+    // When seed already applied profile.style via createThemeFromSeed, still
+    // apply font/radius/density (and style again is idempotent via merge).
+    const finished = applyFinishes(base, brand, profile);
+    return assertAa(finished);
+}
+/**
+ * TypeScript module body for `src/generated/brand-theme.ts` (no header).
+ * The CLI wraps it with the generate hash header.
+ */
+export function emitBrandThemeModule(theme) {
+    const exportName = brandThemeExportName(theme.id);
+    return `import { defineTheme, type Theme } from '@protoyard/core';
+
+/** On-brand theme derived from blueprint.json \`brand\` (Task 128). */
+export const ${exportName}: Theme = defineTheme(${JSON.stringify(theme, null, 2)});
+
+export default ${exportName};
+`;
+}

package/dist/brief/archetypes.d.ts

@@ -0,0 +1,28 @@
+import type { BlueprintArchetypeInput } from '../archetypes/schema.ts';
+import type { BlueprintInput } from '../schema.ts';
+/**
+ * Product archetypes the brief synthesizer starts from. Each one carries the
+ * keywords that select it and a small entity graph whose fields drive the
+ * screens (enums → boards, dates → calendars and timelines, geo → maps,
+ * money → dashboards and analytics). The first entity is the focus: brief-wide
+ * cues (a location, a price, a deadline) land on it. All names are fictional.
+ */
+export type EntityInput = BlueprintInput['entities'][number];
+export type FieldInput = EntityInput['fields'][number];
+export interface Archetype {
+    id: string;
+    /** Product noun used in generated names ("Help Desk"). */
+    label: string;
+    /** Single words or phrases, matched as whole words in the brief. */
+    keywords: readonly string[];
+    /** High-signal cues can select a kit archetype with one unambiguous phrase. */
+    strongCues?: readonly string[];
+    /** Portable runtime binding emitted when this brief seed is selected. */
+    kitArchetype?: BlueprintArchetypeInput;
+    entities: readonly EntityInput[];
+}
+/** Ordered: on equal keyword scores the earlier archetype wins. */
+export declare const ARCHETYPES: readonly Archetype[];
+/** Used when no keyword matches: a plain tracker the extracted nouns extend. */
+export declare const GENERIC_ARCHETYPE: Archetype;
+export declare const ARCHETYPE_IDS: readonly [...string[], string];