@theme-registry/refract 0.1.6 → 0.1.8

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,27 @@ 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 }
+```
+
+Token plates — colours, the type ramp, spacing, radii, shadows, breakpoints — 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.) The page follows the target's `emit` mode, and gains a light/dark toggle when the theme
+declares modes plus frame-width buttons when it declares breakpoints. 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,73 @@
+/**
+ * Human-facing preview (Node-only) — render a single `preview.html` 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`, so a new subsystem's tokens show up 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.
+ *
+ * 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. `inline: false` serves the dev loop, where the page should reflect a
+ * rebuilt stylesheet on refresh.
+ */
+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 `"<format> theme preview"`). */
+    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. A name missing here falls back to a `<link>`. */
+    readonly contents?: Readonly<Record<string, string>>;
+    /** The normalized emit plan — reported in the header 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 and breakpoints for the page controls. */
+    readonly model: ThemeModel;
+}
+/** Distinct appearance modes across every property's `modes` list, in first-appearance order. */
+export declare function collectModes(model: ThemeModel): string[];
+/**
+ * Build the preview artifact. Pure — returns `filename → contents` for the build layer to write.
+ *
+ * The adapter's declared `stylesheets` are intersected with `options.files` (what was actually
+ * written), so a descriptor that drifts from `emit()` degrades to tokens-only instead of producing a
+ * page that silently references a file that isn't there.
+ */
+export declare function buildPreview(source: PreviewSource, options: PreviewOptions): PreviewOutput;