@kanso-labs/unplugin-style-dictionary 0.7.0 → 0.9.0

package/dist/types.d.ts

@@ -11,12 +11,69 @@ import { Config } from "style-dictionary";
  * build (e.g. `tsdown`/`rolldown build` without `--watch`) only builds once, in
  * `buildStart`.
  *
+ * Everything the plugin says goes through the host rather than to the console:
+ * Vite's `config.logger`, the plugin context under rollup and rolldown, and
+ * `compilation.warnings` under webpack, which is what puts a failed compile in
+ * `stats.toJson()`. A failure is reported on the warning channel and never the
+ * error one — rollup's `this.error` aborts the bundle, and that decision is
+ * `failOnError`'s alone. Where no host offers a channel the console is used,
+ * with colour gated on `NO_COLOR`, `FORCE_COLOR` and whether the stream is a
+ * terminal.
+ *
+ * The three `onBuild*` hooks are called synchronously and their return value
+ * is not awaited, so a build never waits for one. A hook may still be written
+ * `async`: a promise it returns is left to run on its own, and a rejection is
+ * caught and reported rather than reaching the host as an unhandled one. A
+ * hook that throws is reported and does not fail the build that called it.
+ *
+ * They return `Promise<void> | void` rather than `void` for that reason. Both
+ * accept an `async` hook as far as the compiler is concerned, but `void` alone
+ * makes one a `no-misused-promises` error under the type-aware lint rules a
+ * consumer is likely to be running — for a hook this documents as supported.
+ *
  * Rolldown's watch mode is the exception, and it is not about glob patterns.
  * `addWatchFile` is accepted either way, but what happens next differs by
  * platform — on macOS a file registered through it is watched by nothing, while
  * on a Linux runner the same edit reaches a rebuild. Do not rely on a token
  * edit triggering a rebuild there.
  */
+/**
+ * What the host is doing, handed to the function form of `config` so it can
+ * decide what to build.
+ *
+ * Only Vite reports all three. Where a host does not say, the value is
+ * derived rather than guessed at, and each field below says how.
+ */
+export interface StyleDictionaryConfigContext {
+  /**
+   * Whether the host is serving or building.
+   *
+   * `'serve'` comes from Vite's own `config.command` and is the dev server.
+   * Every other target builds, so it is `'build'` there — rollup, rolldown and
+   * webpack have no serving mode of their own to report.
+   */
+  command: 'build' | 'serve';
+  /**
+   * The host's mode, as it names it.
+   *
+   * Vite reports its `config.mode` — `'development'` serving,
+   * `'production'` building, or whatever `--mode` named. webpack reports its
+   * `mode` option. rollup and rolldown have no such concept, so the value
+   * follows `command`: `'development'` when serving, `'production'` when
+   * building.
+   */
+  mode: string;
+  /**
+   * Whether the host will keep rebuilding.
+   *
+   * `true` under Vite's dev server, `rollup --watch`, `rolldown.watch()` and
+   * `webpack --watch`; `false` for a one-shot build. It is read from the
+   * host — the plugin context's `meta.watchMode` on the three rollup-shaped
+   * targets, and `compiler.watchMode` on webpack — rather than inferred from
+   * `command`, because `rollup --watch` both watches and builds.
+   */
+  watch: boolean;
+}
 export interface UnpluginStyleDictionaryOptions {
   /**
    * Whether a configuration whose output is already up to date may skip its
@@ -57,12 +114,54 @@ export interface UnpluginStyleDictionaryOptions {
    * - A function that returns a config or array of configs (or resolves to them).
    *   Useful for calling `StyleDictionary.registerFormat()` (or other `register*`
    *   methods) before returning a config that references the custom format by name.
+   *   It is handed a `StyleDictionaryConfigContext` describing what the host is
+   *   doing, so an expensive platform can be built only when it is wanted —
+   *   skipped under the dev server, built by `vite build`. A function taking no
+   *   arguments stays valid: TypeScript accepts one of fewer parameters, and
+   *   JavaScript ignores the extra argument.
    *
    * If not provided, the root directory is searched for 'sd.config.json',
    * 'config.json', 'sd.config.js' and 'sd.config.mjs', in that order. The
-   * first one that exists wins, and the rest are not looked at.
+   * first one that *looks like a Style Dictionary configuration* wins — it has
+   * to declare at least one of `platforms`, `source`, `include` or `tokens` —
+   * and the path it picked is announced, so which file a build used is
+   * answerable from the console. A candidate that fails that check is reported
+   * and skipped rather than adopted, because `config.json` is an extremely
+   * common name for something else entirely.
+   *
+   * **`false` turns discovery off.** Two of the four names are modules rather
+   * than data, and reading a module means running it: a `sd.config.js` in the
+   * root is imported, freshly, on every watch event. Validation cannot prevent
+   * that, because the check can only look at what the import returned — so a
+   * project that names its configuration explicitly, or has none, should say
+   * `config: false` rather than rely on there being nothing to find.
+   */
+  config?: ((context: StyleDictionaryConfigContext) => Config | Config[] | Promise<Config | Config[]>) | Config | Config[] | false | string | string[];
+  /**
+   * Whether a failed rebuild is pushed to Vite's error overlay.
+   *
+   * A rebuild that fails under the dev server used to reach the browser
+   * nowhere: the page went on rendering the last good generated file, and the
+   * only trace was one red terminal line the developer may not have been
+   * looking at. With this on, the failure is sent to the page as an error
+   * frame naming this plugin, and the overlay is dismissed on the next
+   * rebuild that succeeds.
+   *
+   * This is Vite's overlay, so it does nothing on the other three targets,
+   * and nothing under `vite build` — there is no page to draw on.
+   *
+   * It is not `failOnError`'s job, and the two are independent. `failOnError`
+   * decides whether the host stops; this decides whether the browser is told.
+   * A dev server deliberately keeps serving through a failed rebuild, which is
+   * precisely the case where the overlay is the only thing that can say so.
+   *
+   * A failure Style Dictionary raises before this plugin can catch it — a
+   * token file that is not valid JSON, which rejects out of band — reaches
+   * neither the overlay nor this option.
+   *
+   * @default true
    */
-  config?: (() => Config | Config[] | Promise<Config | Config[]>) | Config | Config[] | string | string[];
+  errorOverlay?: boolean;
   /**
    * Whether a compile that fails should throw rather than only be reported.
    *
@@ -101,10 +200,99 @@ export interface UnpluginStyleDictionaryOptions {
    * A compile that fails is reported at every level, so there is no
    * `'error'`: `'silent'` is the quietest and still reports a failure.
    *
+   * This option governs what the plugin says, not where it goes. The messages
+   * are handed to the host — Vite's `config.logger`, the rollup and rolldown
+   * plugin context, webpack's `compilation` — so a host silenced by its own
+   * log level suppresses them after this option has let them through. A
+   * failure still stops the build whenever `failOnError` says it should,
+   * printed or not.
+   *
    * @default undefined, which prints the plugin's own lines and leaves the
    * configuration's `log.verbosity` alone
    */
   logLevel?: 'info' | 'silent' | 'verbose' | 'warn';
+  /**
+   * Called once a build has finished, with every file it declares and how long
+   * it took in milliseconds.
+   *
+   * The paths are absolute and platform-native, sorted so two runs of the same
+   * configuration hand back the same order. They are what the build declares
+   * rather than what it wrote this time: a configuration skipped by `cache`
+   * contributes its destinations too, because they are on disk and current,
+   * and a post-processing step that ignored them would leave half the output
+   * untouched on a rebuild that changed one file.
+   *
+   * This is where formatting the generated files, type-checking them, or
+   * telling something else they have landed belongs.
+   *
+   * @default undefined
+   */
+  onBuildEnd?: (files: string[], durationMs: number) => Promise<void> | void;
+  /**
+   * Called when a build fails, with whatever was thrown.
+   *
+   * It fires whatever `failOnError` is set to, and before that option decides
+   * whether to rethrow — the two answer different questions, and under a dev
+   * server the default is not to throw at all.
+   *
+   * The failure is reported to the console either way, so this is for reacting
+   * to one rather than for noticing it.
+   *
+   * @default undefined
+   */
+  onBuildError?: (error: unknown) => Promise<void> | void;
+  /**
+   * Called before a build begins, once per build.
+   *
+   * A watch-triggered rebuild is a build, so this fires again for each one.
+   *
+   * @default undefined
+   */
+  onBuildStart?: () => Promise<void> | void;
+  /**
+   * Which platforms to build, by the names the configuration defines.
+   *
+   * Every rebuild used to compile every platform. Measured on a six-platform
+   * configuration (css, scss, js, ios, android, flutter), with the timer around
+   * the build call alone:
+   *
+   * ```
+   * tokens   all platforms   css only   saved
+   *    500          12 ms       1 ms    10 ms
+   *   3000          36 ms       2 ms    34 ms
+   *  10000         103 ms       4 ms    99 ms
+   *  30000         330 ms      12 ms   319 ms
+   * ```
+   *
+   * So a dev server serving a web app paid for Objective-C headers, Android
+   * XML and Dart classes on every token save, and the cost grows with the
+   * token count.
+   *
+   * Two shapes. An array selects the same platforms for every build. An object
+   * splits the first compile from the watch rebuilds, which is the common
+   * want — build everything once, then rebuild only what the page uses:
+   *
+   * ```typescript
+   * platforms: ['css']
+   * platforms: { watch: ['css'] }
+   * ```
+   *
+   * An omitted key means every platform, so `{ watch: ['css'] }` builds all of
+   * them once and then only css. A name the configuration does not define is an
+   * error, matching Style Dictionary's own CLI — "Must be defined in the
+   * config".
+   *
+   * **Unselected platforms keep whatever they last wrote.** Their files are not
+   * removed and not refreshed, so a one-shot build that scopes platforms ships
+   * stale output for the rest. Scope the watch half rather than the build half
+   * unless that is what you want.
+   *
+   * @default undefined, which builds every platform
+   */
+  platforms?: string[] | {
+    build?: string[];
+    watch?: string[];
+  };
   /**
    * Whether the table of generated files and their sizes is produced.
    *

package/dist/vite.d.ts

@@ -1,6 +1,6 @@
-import { UnpluginStyleDictionaryOptions } from "./types.js";
+import { StyleDictionaryConfigContext, UnpluginStyleDictionaryOptions } from "./types.js";
 //#region src/vite.d.ts
 declare const _default: (options?: UnpluginStyleDictionaryOptions | undefined) => import("vite").Plugin<any>;
 //#endregion
-export { type UnpluginStyleDictionaryOptions, _default as default };
+export { type StyleDictionaryConfigContext, type UnpluginStyleDictionaryOptions, _default as default };
 //# sourceMappingURL=vite.d.ts.map

package/dist/webpack.d.ts

@@ -1,6 +1,6 @@
-import { UnpluginStyleDictionaryOptions } from "./types.js";
+import { StyleDictionaryConfigContext, UnpluginStyleDictionaryOptions } from "./types.js";
 //#region src/webpack.d.ts
 declare const _default: (options?: UnpluginStyleDictionaryOptions | undefined) => import("webpack").WebpackPluginInstance;
 //#endregion
-export { type UnpluginStyleDictionaryOptions, _default as default };
+export { type StyleDictionaryConfigContext, type UnpluginStyleDictionaryOptions, _default as default };
 //# sourceMappingURL=webpack.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanso-labs/unplugin-style-dictionary",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Compile Style Dictionary design tokens ahead of your bundler (Vite, Rolldown, Rollup, or Webpack) from a single unplugin-based plugin, with automatic watching and rebuilding under Vite",
   "keywords": [
     "unplugin",