@theme-registry/refract 0.1.7 → 0.1.9

package/README.md

@@ -45,7 +45,10 @@ 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.
+styled-components adapter or the `.ts` build config, respectively. Install typescript as
+**`typescript@5`**: a bare `npm i -D typescript` now resolves to 7.x, the native port, whose main
+entry exports only a version string — the compiler API a `.ts` config is transpiled with sits behind
+its `./unstable/*` subpaths. A `.mjs` or `.js` config never loads typescript at all.
 
 ## Scaffold a theme
 
@@ -174,6 +177,38 @@ Each target's `emit` picks the output shape (CSS adapter):
 | `subsystem` | a styles+variables pair per subsystem (`colors.css`, `colors.variables.css`, …) |
 | `components` | each component variant flattened into one self-contained file (`inline: true` bakes values; `inline: false` emits `var(--…)` + a tree-shaken `variables.css`) |
 
+### `preview` — see what you built
+
+Set `preview: true` on any target and `refract build` also writes a `preview.html` into its
+`outDir`: a rendered specimen you double-click, forward, or hand a designer. It inlines its
+stylesheets by default, so the page is one self-contained file that survives being moved.
+
+```ts
+{ name: "css", adapter: createCssAdapter(), outDir: "dist/theme", preview: true }
+```
+
+It reads as a style guide, not a token dump: a sticky section rail, colour families as contiguous
+ladders with live WCAG contrast readouts on each `text` pairing, the type ramp set in its own sizes,
+spacing shown as a measure *and* as an applied inset, a **state matrix** per recipe, and a
+copy-on-click identifier beside every specimen. Sections appear only when the theme has tokens of
+that kind.
+
+Token plates render from the format-neutral token export, so **every** adapter gets them. Live
+recipe plates additionally need output a browser can load as-is, which today means CSS; an
+SCSS/styled-components/JSON target still renders every token and names every recipe, and says why it
+can't render them live. (For a live design-review page from an SC or SCSS theme, add a CSS target to
+the same config — same recipes, same core.)
+
+Three things only a compiler's specimen sheet can show: **states** side by side (a CSS pseudo-class
+can't be triggered from markup, so the adapter emits a parallel pinnable rule that is inlined into
+the page and never added to the stylesheet you ship), an **appearance-mode diff** of the tokens that
+actually carry an override, and **composition** broken into its parts — each class in a component's
+identity attributed to the recipe it came from. Bare elements themed by the `globals` subsystem get
+their own prose specimen, since they carry no class at all. Off by default.
+
+Its machine-facing sibling is `guide: true`, which writes an `llms.txt` + `manifest.json`
+consumption guide into the same folder.
+
 ## DTCG round-trip
 
 The `./dtcg` subpath reads/writes the W3C Design Token Community Group `tokens.json`

package/dist/build/config.d.ts

@@ -3,6 +3,7 @@ import type { RawTheme } from "../core/rawTheme";
 import type { MediaConfig } from "../core/media";
 import type { UnitsConfig } from "../core/units";
 import type { GuideConfig } from "./emitTheme";
+import type { PreviewConfig } from "./preview";
 /** One emit target: an adapter + where to write it, plus which shared vendored helpers it wants. */
 export interface EmitTarget {
     readonly adapter: ThemeAdapter;
@@ -19,6 +20,14 @@ export interface EmitTarget {
      * file names or adds a `packageName` for a by-specifier import overlay. Off by default.
      */
     readonly guide?: boolean | GuideConfig;
+    /**
+     * §20 — emit a human-facing `preview.html` specimen into this target's `outDir`: token plates
+     * rendered from the format-neutral export (so every adapter gets them) plus live recipe plates
+     * when the adapter's output is browser-loadable (CSS today). The audience-flipped sibling of
+     * `guide`. `true` uses defaults; an object tunes the filename/title or opts out of inlining.
+     * Off by default.
+     */
+    readonly preview?: boolean | PreviewConfig;
 }
 /** The `theme.config` shape: the raw theme + one or more emit targets. */
 export interface ThemeConfig {

package/dist/build/emitTheme.d.ts

@@ -2,6 +2,7 @@ import type { ThemeAdapter, Emit } from "../core/ThemeAdapter";
 import type { RawTheme } from "../core/rawTheme";
 import type { MediaConfig } from "../core/media";
 import type { UnitsConfig } from "../core/units";
+import { type PreviewConfig } from "./preview";
 /** Opt-in self-documenting output config (§C). `true` uses defaults; the object tunes names/overlay. */
 export type GuideConfig = {
     /** Published package specifier — adds a by-specifier import overlay to the guide (else relative-only). */
@@ -30,6 +31,8 @@ export interface EmitThemeOptions {
     readonly baseFontSize?: number;
     /** §C — emit a self-documenting `llms.txt` + `manifest.json` into `outDir`. Off by default. */
     readonly guide?: boolean | GuideConfig;
+    /** §20 — emit a human-facing `preview.html` specimen into `outDir`. Off by default. */
+    readonly preview?: boolean | PreviewConfig;
 }
 export interface EmitThemeResult {
     readonly outDir: string;

package/dist/build/index.d.ts

@@ -8,6 +8,7 @@
 export * from "./vendor";
 export * from "./paths";
 export * from "./guide";
+export * from "./preview";
 export * from "./emitTheme";
 export * from "./emit";
 export * from "./config";

package/dist/build/preview.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Human-facing preview (Node-only) — render a single `preview.html` **style-guide specimen** of a
+ * built theme.
+ *
+ * The audience-flipped sibling of `guide.ts`: that one writes `llms.txt` + `manifest.json` for a
+ * downstream *agent*; this one writes a page a person opens, forwards, or hands a designer to answer
+ * "what does this theme actually look like?". Both are opt-in per emit target and land in the same
+ * `outDir`, so they travel with any distribution form.
+ *
+ * Two plate tiers, split by CAPABILITY rather than by adapter name:
+ *
+ *  - **Token plates (universal).** Rendered from the format-neutral DTCG export — the same document
+ *    `guide` embeds — so they depend on nothing the adapter emitted. Every adapter, including a
+ *    third-party one that has never heard of previews, gets these on day one. The walk is generic
+ *    over `$type` with per-group specimen overrides, so a new subsystem's tokens still appear (in a
+ *    catch-all section) without touching this file.
+ *
+ *  - **Recipe plates (live).** Require the emitted artifacts to be browser-loadable as-is, which the
+ *    adapter alone can answer — see {@link PreviewDescriptor}. Today that means CSS; SCSS needs
+ *    compiling, styled-components emits JS modules, JSON has no rendered form. Those adapters say so
+ *    in their own words and the page degrades to tokens-only rather than rendering unstyled boxes.
+ *
+ * Two rules the layout is built on, both learned the hard way:
+ *
+ *  1. **The chrome is chromatically silent.** The theme owns every saturated pixel; the tool around
+ *     it is neutral, and specimen geometry uses a dedicated mid-tone (`--rfp-spec`) rather than the
+ *     nearest neutral to hand. Filling a swatch with the page ground makes it vanish the moment the
+ *     ground and the stage converge — which is exactly what happens in dark mode.
+ *  2. **Never assume the theme is light.** The emitted stylesheet is inlined, so a theme with a
+ *     `dark` mode restyles itself under the toggle; the chrome has to survive both, and the page
+ *     must not hard-code a light ground under it.
+ *
+ * Distribution convention deliberately INVERTS `guide`'s: the page **inlines** its stylesheets by
+ * default (`inline: false` opts out). `guide` is machine-facing and lives next to the code it
+ * documents, so relative references are right there; a preview gets moved, attached, and forwarded,
+ * and has to keep working.
+ */
+import type { ThemeModel } from "../core/model/model";
+import type { NormalizedEmit, PreviewDescriptor, UsageDescriptor } from "../core/ThemeAdapter";
+/** Opt-in preview config (`EmitTarget.preview`). `true` uses every default. */
+export type PreviewConfig = {
+    /** Output filename (default `"preview.html"`). */
+    readonly file?: string;
+    /**
+     * Inline the emitted stylesheets into the page so it is a single shareable file (default `true`).
+     * `false` emits relative `<link>`s instead — the page then only works beside its `outDir`, but it
+     * reflects a rebuilt stylesheet on refresh.
+     */
+    readonly inline?: boolean;
+    /** Page heading + `<title>` (default the theme name, else `"<format> theme"`). */
+    readonly title?: string;
+};
+export interface PreviewOptions extends PreviewConfig {
+    /** The file names actually written for this target — the guard against referencing a missing artifact. */
+    readonly files: readonly string[];
+    /** Emitted file contents by name, for inlining + the byte counts in the masthead. */
+    readonly contents?: Readonly<Record<string, string>>;
+    /** The normalized emit plan — reported in the masthead and used for layout semantics only. */
+    readonly plan: NormalizedEmit;
+}
+export interface PreviewOutput {
+    /** filename → contents, ready for the build layer to write into `outDir`. */
+    readonly files: Record<string, string>;
+}
+export interface PreviewSource {
+    /** The adapter's usage descriptor — supplies the format id and the real recipe identities. */
+    readonly usage: UsageDescriptor;
+    /** The adapter's preview descriptor, or `undefined` when it doesn't implement `describePreview`. */
+    readonly preview?: PreviewDescriptor;
+    /** A DTCG document (from `toDTCG`) — the token-plate source. */
+    readonly tokens: unknown;
+    /** The built model — supplies appearance modes, breakpoints, and the globals element selectors. */
+    readonly model: ThemeModel;
+}
+/** Distinct appearance modes across every property's `modes` list, in first-appearance order. */
+export declare function collectModes(model: ThemeModel): string[];
+export declare function buildPreview(source: PreviewSource, options: PreviewOptions): PreviewOutput;