@theme-registry/refract 0.1.2 → 0.1.4

package/README.md

@@ -47,6 +47,21 @@ npm install @theme-registry/refract
 `styled-components` and `typescript` are **optional** peers — only needed if you use the
 styled-components adapter or the `.ts` build config, respectively.
 
+## Scaffold a theme
+
+Don't start from a blank file. One seed colour becomes a full theme — palettes with tonal ladders,
+semantic colours, a type scale with derived leading, a spacing ramp — with every colour checked
+against **WCAG contrast before the file is written**:
+
+```bash
+npx refract create                 # in an existing project → theme.raw.ts
+npm create refract-theme my-theme  # from nothing → a publishable theme package
+```
+
+The generator runs **once**; what it writes is an ordinary theme file you own and edit. It emits
+**tokens only** — no recipes, so nothing composes into a class list yet. That's the next step, and
+it's design work: see [Recipes](https://theme-registry.github.io/refract/r-recipes).
+
 ## Quick start
 
 `createTheme(raw, { adapter })` builds the theme. The `adapter` is **required** — core
@@ -126,7 +141,8 @@ Write your own with `defineAdapter(spec)` — you fill four primitives (`recipeN
 ## Build to disk (CLI)
 
 ```bash
-npx refract init      # scaffold a theme.config.(ts|js|mjs)
+npx refract create    # design a theme.raw.(ts|js|json) from one seed colour
+npx refract init      # scaffold a theme.config.(ts|js|mjs) — imports theme.raw.* if present
 npx refract build     # load the config → write every target's files to its outDir
 npx refract tokens    # export theme.tokens as a DTCG tokens.json (adapter-free)
 ```

package/dist/build/createCommand.d.ts

@@ -0,0 +1,47 @@
+import { type ScaffoldAnswers, type ScaffoldReport } from "./scaffold";
+import type { RawTheme } from "../core";
+/** The file flavours `create` can emit. */
+export type RawFormat = "ts" | "js" | "json";
+export declare const DEFAULT_RAW_BASENAME = "theme.raw";
+export interface CreateOptions extends ScaffoldAnswers {
+    /** Project dir to write into (default `process.cwd()`). */
+    readonly cwd?: string;
+    /** Which flavour to write (default `"ts"`). */
+    readonly format?: RawFormat;
+    /** Output filename, relative to `cwd` (default `theme.raw.<format>`). */
+    readonly out?: string;
+    /** Overwrite an existing file instead of refusing (default `false`). */
+    readonly force?: boolean;
+    /** Package name the `.ts`/`.js` type import points at (default: this package's own `name`). */
+    readonly packageName?: string;
+}
+export interface CreateResult {
+    /** Absolute path of the written file. */
+    readonly path: string;
+    readonly format: RawFormat;
+    /** The generated theme, so callers can compile it without re-reading the file. */
+    readonly raw: RawTheme;
+    /** What the generator derived — the CLI prints this as its summary. */
+    readonly report: ScaffoldReport;
+    /** Count of emitted top-level subsystem slices. */
+    readonly sections: readonly string[];
+}
+/**
+ * Serialize a generated theme to source text.
+ *
+ * `ts` and `js` share one body and differ only in how the type is attached (a real `satisfies` vs a
+ * JSDoc cast), so a JS user gets the same editor completion without adding a compile step. `json`
+ * carries no types and no shared `ladder` const — it is the portable flavour, and for a scaffolded
+ * theme it is exactly as faithful, because nothing here is a function or a recipe.
+ */
+export declare function renderRawTheme(raw: RawTheme, options: {
+    format: RawFormat;
+    packageName: string;
+    seed: string;
+    detail: string;
+}): string;
+/**
+ * Generate and write the raw theme. Throws when the target exists and `force` is not set — the same
+ * guard `init` and `import` use, so no command in this CLI can silently destroy authored work.
+ */
+export declare function runCreate(options: CreateOptions): CreateResult;

package/dist/build/createInterview.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The `refract create` interview (Node-only) — the question flow, separated from both CLIs that run it.
+ *
+ * `refract create` asks it to write a theme into an existing project; `create-refract-theme` asks it
+ * while scaffolding a whole new package. Two entry points, one script of questions — because an
+ * interview duplicated across two packages is an interview that drifts.
+ *
+ * Every answer can be supplied up front (a flag, or a caller's default), and every prompt is
+ * non-interactive-safe, so the same function serves a human at a terminal and a scripted run.
+ */
+import type { Prompter } from "./prompt";
+import { type ScaffoldAnswers } from "./scaffold";
+import type { CreateResult, RawFormat } from "./createCommand";
+/** What each harmony scheme is for, in one line — the names mean nothing to most people. */
+export declare const SCHEME_HINTS: Readonly<Record<string, string>>;
+/**
+ * Ratio choices, tightest to most dramatic, each showing the ladder it produces from 16px. The ratio
+ * is the most consequential typographic choice in the theme and its name carries no information, so
+ * the numbers do the explaining.
+ */
+export declare const TYPE_SCALE_CHOICES: ReadonlyArray<readonly [string, string]>;
+/** Answers a caller already has — from CLI flags, or a host tool's own defaults. */
+export interface InterviewGiven {
+    readonly seed?: string;
+    /** Brand count in auto mode, or a comma-separated colour list in manual mode. */
+    readonly colors?: string;
+    readonly scheme?: string;
+    readonly manual?: boolean;
+    readonly feel?: string;
+    readonly ratio?: string;
+    readonly baseSize?: string | number;
+    readonly contrast?: string;
+    readonly reset?: string;
+    readonly format?: string;
+    readonly noSemantics?: boolean;
+    readonly noNeutral?: boolean;
+    readonly noShadows?: boolean;
+}
+/** The fully-resolved answer set, ready for `runCreate`. */
+export type InterviewAnswers = ScaffoldAnswers & {
+    readonly format: RawFormat;
+};
+/**
+ * Run the interview. Anything present in `given` is taken as answered and never asked.
+ *
+ * The scheme question only appears when the brand count admits more than one rotation set — which is
+ * only at three colours. Two is a complement, four a tetradic, five a pentadic: asking would be a
+ * prompt with a single option.
+ */
+export declare function promptCreateAnswers(p: Prompter, given?: InterviewGiven): Promise<InterviewAnswers>;
+/**
+ * The post-generation summary: what the contrast pass did, and what landed. Returned as lines rather
+ * than printed so each host can frame them — the standalone command and the project scaffolder put
+ * different things around the same facts.
+ */
+export declare function createReportLines(result: CreateResult, variableCount: number): string[];

package/dist/build/index.d.ts

@@ -12,6 +12,10 @@ export * from "./emitTheme";
 export * from "./emit";
 export * from "./config";
 export * from "./init";
+export * from "./scaffold";
+export * from "./createCommand";
+export * from "./createInterview";
+export * from "./prompt";
 export * from "./importCommand";
 export * from "./buildCommand";
 export * from "./tokensCommand";

package/dist/build/init.d.ts

@@ -13,6 +13,11 @@ export interface InitOptions {
     readonly force?: boolean;
     /** Package name to import from in the scaffold (default: this package's own `name`). */
     readonly packageName?: string;
+    /**
+     * Override the raw-theme detection: a {@link DetectedRawTheme} to wire up regardless of what's on
+     * disk, or `null` to force the self-contained starter config. Omit to detect (the normal path).
+     */
+    readonly rawTheme?: DetectedRawTheme | null;
 }
 export interface InitResult {
     /** Absolute path of the written config. */
@@ -20,9 +25,46 @@ export interface InitResult {
     readonly variant: ConfigVariant;
     /** The package name the scaffold imports from. */
     readonly packageName: string;
+    /** The raw theme the config was wired to, or `undefined` when it carries its own starter palette. */
+    readonly rawTheme?: DetectedRawTheme;
 }
 /** Read this package's own `name` (so the scaffold imports the currently-installed package name). */
 export declare function readOwnPackageName(): string;
+/** A raw theme found next to the config, and how a config should reach it. */
+export interface DetectedRawTheme {
+    /** Absolute path of the file found. */
+    readonly path: string;
+    /** Its basename, e.g. `theme.raw.json`. */
+    readonly filename: string;
+    /** The extension, including the dot. */
+    readonly ext: string;
+}
+/**
+ * Look for an authored raw theme in `fromDir`.
+ *
+ * This is the seam between `create` and `init`: `create` designs the theme, `init` wires the build.
+ * When a theme is already there, `init` must not invent a second one — a project with two sources of
+ * truth for its tokens is worse than a project with none.
+ */
+export declare const findRawTheme: (fromDir?: string) => DetectedRawTheme | undefined;
+/**
+ * The import line (or lines) a config uses to reach a detected raw theme.
+ *
+ * `.ts` is graph-compiled alongside the config, so an extensionless specifier resolves and the
+ * transformer rewrites it. `.mjs`/`.js` are imported by Node directly, so they keep their extension.
+ * `.json` is read rather than imported: an import attribute (`with { type: "json" }`) would work on
+ * current Node but pins the scaffolded config to a version floor for no benefit, and `readFileSync`
+ * behaves identically in every flavour.
+ */
+export declare function rawThemeImport(detected: DetectedRawTheme): {
+    head: string;
+    expression: string;
+};
+/**
+ * The config body when a raw theme already exists — it imports that theme instead of carrying one.
+ * Deliberately short: everything about the design lives in the theme file, and this is only wiring.
+ */
+export declare function scaffoldConfigForRaw(packageName: string, detected: DetectedRawTheme): string;
 /** The scaffolded config body — one shared ESM template across ts/js/mjs. */
 export declare function scaffoldConfig(packageName: string): string;
 /**

package/dist/build/prompt.d.ts

@@ -0,0 +1,76 @@
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+/** One choice in a `select` / `multiselect`. */
+export interface Choice<T> {
+    readonly value: T;
+    readonly label: string;
+    /** Trailing grey note — what this option means. */
+    readonly hint?: string;
+}
+/** The keys a list prompt understands, after decoding an stdin chunk. */
+export type ListKey = "up" | "down" | "space" | "submit" | "all" | "cancel" | "none";
+/** Decode a raw stdin chunk into a {@link ListKey}. Arrows arrive as escape sequences; j/k mirror vim. */
+export declare function decodeKey(chunk: string): ListKey;
+/**
+ * Split one stdin chunk into the keys it contains.
+ *
+ * A held-down arrow key, or fast typing, delivers several sequences in a single `data` event — so
+ * decoding the chunk as one key would swallow all but the first and make the list feel like it drops
+ * input. Escape sequences (`ESC [ <letter>`) are taken as a unit; everything else is one key each.
+ */
+export declare function decodeKeys(chunk: string): ListKey[];
+/** Where a list prompt currently stands. */
+export interface ListState {
+    readonly cursor: number;
+    readonly selected: ReadonlySet<number>;
+    readonly done: boolean;
+    readonly cancelled: boolean;
+}
+/**
+ * Advance a list prompt by one key. Pure — no I/O — so navigation is testable without a terminal.
+ *
+ * The cursor **wraps** at both ends: with six options, up from the first should land on the last
+ * rather than stick. `space` and `a` toggle only in multi mode; in single mode Enter is the commit,
+ * so space would be ambiguous.
+ */
+export declare function applyKey(state: ListState, key: ListKey, count: number, multi: boolean): ListState;
+/**
+ * A prompt session. Holds at most one readline interface, so stdin is opened and closed once;
+ * `interactive` is false when there's no TTY, and every ask short-circuits to its default.
+ */
+export declare class Prompter {
+    private rl;
+    readonly interactive: boolean;
+    constructor(interactive?: boolean);
+    private get io();
+    close(): void;
+    private question;
+    /** Raw write, no newline — for cursor control during a live render. */
+    private out;
+    /** Print a line. Kept on the prompter so command code never touches `process.stdout`. */
+    write(line?: string): void;
+    /** Free-text, with a default shown in the prompt. Blank input takes the default. */
+    text(label: string, fallback: string, validate?: (v: string) => string | undefined): Promise<string>;
+    /** A number, validated as finite. */
+    number(label: string, fallback: number, validate?: (v: number) => string | undefined): Promise<number>;
+    /** Pick one — arrows to move, Enter to choose. */
+    select<T>(label: string, choices: readonly Choice<T>[], defaultIndex?: number): Promise<T>;
+    /** Pick any — arrows to move, space to toggle, `a` for all/none, Enter to confirm. */
+    multiselect<T>(label: string, choices: readonly Choice<T>[], preselected: readonly number[]): Promise<T[]>;
+    /**
+     * The raw-mode list loop. Renders in place: each keypress rewinds over the block just drawn and
+     * repaints it, so the list stays put instead of scrolling the terminal away.
+     *
+     * Any readline interface is closed first — it would otherwise swallow the keystrokes we need.
+     * `cleanup` always restores the terminal (raw mode off, cursor shown), including on cancel, so a
+     * Ctrl-C can't leave the shell in a state where typing is invisible.
+     */
+    private runList;
+    /** Line-mode fallback: pick one by number. */
+    private selectByNumber;
+    /** Line-mode fallback: pick any by comma-separated numbers. */
+    private multiselectByNumber;
+}

package/dist/build/scaffold.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Guided raw-theme generator (Node-only, pure) — the engine behind `refract create`.
+ *
+ * Turns a seed colour plus a handful of answers into a complete `RawTheme`. Deliberately split from
+ * the prompting (`cli.ts`) and from the file writing (`createCommand.ts`) so the whole generator is
+ * testable without a TTY and reusable programmatically.
+ *
+ * The governing rule for what lands in the output:
+ *
+ *   **Bake a literal** where the value came from an opinion the engine does not hold — the harmony
+ *   rotation, the contrast nudge, the leading/tracking curves. Those are this module's taste, and a
+ *   scaffolded theme is a style guide the user then owns, so it must hold still.
+ *
+ *   **Write the declaration** where the engine already synthesizes — `fontSize.ratio`,
+ *   `layout.spacing.step`. Baking those would throw the intent away: re-tuning a scale should stay a
+ *   one-word edit, not a regeneration of eight numbers.
+ *
+ * Nothing here changes the palette model. It calls the colour helpers the package already ships
+ * (`rotateHue`/`darken`, and `audit` for the contrast gate) and writes down what they return, once.
+ * Callers who want a companion that *re-derives* on `override()` should use `colors.harmony` instead —
+ * that is the other tool, for the other job.
+ */
+import type { RawTheme } from "../core";
+import type { WcagLevel } from "../subsystems/colors/audit";
+/**
+ * Hue rotations per scheme. Aligned with the colours subsystem's own `HARMONY_SCHEMES` where they
+ * overlap, so a scaffolded literal and an authored `harmony:` key agree. `pentadic` is local — the
+ * subsystem has no five-way scheme, and the scaffolder needs one to reach five brand colours.
+ */
+declare const SCHEME_ROTATIONS: Readonly<Record<string, readonly number[]>>;
+export type Feel = "neutral" | "compact" | "editorial" | "technical";
+interface FeelPreset {
+    readonly label: string;
+    readonly blurb: string;
+    /** `fontFamily` base + the `mono` variant (system stacks only — a CLI can't install fonts). */
+    readonly fontFamily: {
+        readonly base: string;
+        readonly mono: string;
+    };
+    /** Multiplier map for the linear spacing curve (`step: 4`). */
+    readonly spacing: Readonly<Record<string, number>>;
+    /** Radius base + variants. */
+    readonly radius: {
+        readonly base: number;
+        readonly variants: Readonly<Record<string, number | string>>;
+    };
+    /** Suggested type ratio when the user takes the default. */
+    readonly ratio: string;
+}
+export declare const FEEL_PRESETS: Readonly<Record<Feel, FeelPreset>>;
+export type BrandScheme = keyof typeof SCHEME_ROTATIONS;
+export type ResetPreset = "preflight" | "normalize" | "none";
+export type ContrastTarget = "AA" | "AAA" | "none";
+export interface ScaffoldAnswers {
+    /** The seed colour — any form `parseColor` accepts (hex, `rgb()`, `oklch()`). */
+    readonly seed: string;
+    /** `auto` derives colours 2…N by hue rotation; `manual` takes them verbatim from `extraColors`. */
+    readonly mode?: "auto" | "manual";
+    /** Total brand colours including the primary, 1–5. Default 2. */
+    readonly brandCount?: number;
+    /** Which rotation set to use. Ignored unless `mode: "auto"`; defaulted from `brandCount`. */
+    readonly scheme?: BrandScheme;
+    /** `mode: "manual"` — the colours after the primary, in order. */
+    readonly extraColors?: readonly string[];
+    /** Add success / info / warning / danger. Default true. */
+    readonly semantics?: boolean;
+    /** Add the neutral ramp. Default true. */
+    readonly neutral?: boolean;
+    /** Add shadow ink + alpha tints, and the effects ramp that references them. Default true. */
+    readonly shadows?: boolean;
+    /** Contrast bar for the text-on-base pass. Default `"AA"`; `"none"` skips the pass entirely. */
+    readonly contrast?: ContrastTarget;
+    /** Base font size in px. Default 16. */
+    readonly baseFontSize?: number;
+    /** Named type ratio. Defaults to the feel preset's suggestion. */
+    readonly ratio?: string;
+    /** Type family + density + corners, moved together. Default `"neutral"`. */
+    readonly feel?: Feel;
+    /** Which normalization layer `globals.preset` gets. Default `"preflight"`. */
+    readonly reset?: ResetPreset;
+}
+/** What the contrast pass did to one palette — surfaced so the CLI can report it honestly. */
+export interface ContrastAdjustment {
+    readonly name: string;
+    /** The colour before the pass. */
+    readonly seed: string;
+    /** The colour written to the file. */
+    readonly final: string;
+    /** OKLCH lightness points removed (0 when untouched). */
+    readonly nudge: number;
+    /** Ratio before, and after. */
+    readonly ratioBefore: number;
+    readonly ratioAfter: number;
+    readonly levelAfter: WcagLevel;
+    /** True when the pass ran out of room without reaching the bar. */
+    readonly unresolved: boolean;
+}
+export interface ScaffoldReport {
+    /** The seed's OKLCH lightness, 0–100. */
+    readonly seedLightness: number;
+    /** The ladder label the seed sits nearest — `base` stays canonical, this is orientation only. */
+    readonly nearestStep: number;
+    /** Brand palettes in order, with the hue rotation that produced each (0 for the primary/manual). */
+    readonly brand: ReadonlyArray<{
+        readonly name: string;
+        readonly hex: string;
+        readonly rotation: number;
+    }>;
+    /** Every palette the contrast pass looked at. Empty when `contrast: "none"`. */
+    readonly contrast: readonly ContrastAdjustment[];
+    /** Derived per-step leading and tracking, for the CLI's summary line. */
+    readonly type: ReadonlyArray<{
+        readonly step: string;
+        readonly px: number;
+        readonly leading: number;
+        readonly tracking: string;
+    }>;
+    /** The resolved spacing ramp in px, for the CLI's summary line. */
+    readonly spacing: ReadonlyArray<{
+        readonly step: string;
+        readonly px: number;
+    }>;
+}
+export interface ScaffoldResult {
+    readonly raw: RawTheme;
+    readonly report: ScaffoldReport;
+}
+/** Leading for a size, from the curve above. */
+export declare const deriveLeading: (sizePx: number) => number;
+/** Tracking (em) for a size, from the curve above. */
+export declare const deriveTracking: (sizePx: number) => string;
+/**
+ * The ladder label a colour's lightness sits nearest. `base` stays the brand colour — this exists so
+ * the CLI can tell you which stops are your hover and active shades without moving the hex you typed.
+ */
+export declare const nearestLadderStep: (lightness: number) => number;
+/** Which scheme a brand count implies when the caller doesn't name one. */
+export declare const defaultSchemeFor: (brandCount: number) => BrandScheme | undefined;
+/** Schemes that produce exactly `brandCount − 1` members — the valid choices at that count. */
+export declare const schemesFor: (brandCount: number) => readonly BrandScheme[];
+/**
+ * Build a complete `RawTheme` from the interview answers. Pure — no filesystem, no prompting, no
+ * randomness — so the same answers always produce the same theme.
+ */
+export declare function scaffoldTheme(answers: ScaffoldAnswers): ScaffoldResult;
+export {};