dispersa 0.2.0 → 0.3.0

package/README.md

@@ -118,11 +118,11 @@ for (const output of result.outputs) {
 }
 ```
 
-> For file-based tokens, define JSON files and reference them with `$ref` in your resolver document. See the [`basic` example](./examples/basic/) for a complete setup.
+> For file-based tokens, define JSON files and reference them with `$ref` in your resolver document. See the [`typescript-starter` example](./examples/typescript-starter/) for a complete setup.
 
 ## Output formats
 
-Dispersa ships four builder functions. Each returns an `OutputConfig` that can be passed to `build()`.
+Dispersa ships five builder functions. Each returns an `OutputConfig` that can be passed to `build()`.
 
 ### `css(config)`
 
@@ -139,6 +139,7 @@ Renders CSS custom properties.
 | `minify`             | `boolean`                                | `false`    | Minify output                                |
 | `transforms`         | `Transform[]`                            | --         | Per-output transforms                        |
 | `filters`            | `Filter[]`                               | --         | Per-output filters                           |
+| `hooks`              | `LifecycleHooks`                         | --         | Per-output lifecycle hooks                   |
 
 ### `json(config)`
 
@@ -154,6 +155,7 @@ Renders JSON output.
 | `minify`          | `boolean`                  | --             | Minify output                                |
 | `transforms`      | `Transform[]`              | --             | Per-output transforms                        |
 | `filters`         | `Filter[]`                 | --             | Per-output filters                           |
+| `hooks`           | `LifecycleHooks`           | --             | Per-output lifecycle hooks                   |
 
 ### `js(config)`
 
@@ -170,6 +172,25 @@ Renders JavaScript/TypeScript modules.
 | `minify`         | `boolean`                  | --             | Minify output                                |
 | `transforms`     | `Transform[]`              | --             | Per-output transforms                        |
 | `filters`        | `Filter[]`                 | --             | Per-output filters                           |
+| `hooks`          | `LifecycleHooks`           | --             | Per-output lifecycle hooks                   |
+
+### `tailwind(config)`
+
+Renders Tailwind CSS v4 `@theme` blocks.
+
+| Option          | Type                           | Default    | Description                                  |
+| --------------- | ------------------------------ | ---------- | -------------------------------------------- |
+| `name`          | `string`                       | --         | Unique output identifier                     |
+| `file`          | `string \| function`           | --         | Output path (supports `{modifier}` patterns) |
+| `preset`        | `'bundle' \| 'standalone'`     | `'bundle'` | Output preset                                |
+| `includeImport` | `boolean`                      | --         | Include `@import "tailwindcss"` directive    |
+| `namespace`     | `string`                       | --         | Prefix for CSS variable names                |
+| `selector`      | `string \| SelectorFunction`   | `':root'`  | CSS selector                                 |
+| `mediaQuery`    | `string \| MediaQueryFunction` | --         | Media query wrapper                          |
+| `minify`        | `boolean`                      | `false`    | Minify output                                |
+| `transforms`    | `Transform[]`                  | --         | Per-output transforms                        |
+| `filters`       | `Filter[]`                     | --         | Per-output filters                           |
+| `hooks`         | `LifecycleHooks`               | --         | Per-output lifecycle hooks                   |
 
 ### Experimental: native platform outputs
 
@@ -743,15 +764,16 @@ const dispersa = new Dispersa(options?: DispersaOptions)
 
 ### Subpath exports
 
-| Export                   | Description                                                      |
-| ------------------------ | ---------------------------------------------------------------- |
-| `dispersa`               | `Dispersa` class, builder functions (`css`, `json`, `js`), types |
-| `dispersa/transforms`    | Built-in transform factories                                     |
-| `dispersa/filters`       | Built-in filter factories                                        |
-| `dispersa/builders`      | Output builder functions                                         |
-| `dispersa/renderers`     | Renderer types, `defineRenderer`, and `outputTree` helper        |
-| `dispersa/preprocessors` | Preprocessor type                                                |
-| `dispersa/errors`        | Error classes (`DispersaError`, `TokenReferenceError`, etc.)     |
+| Export                   | Description                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| `dispersa`               | `Dispersa` class, builder functions (`css`, `json`, `js`, `tailwind`), types |
+| `dispersa/transforms`    | Built-in transform factories                                                 |
+| `dispersa/filters`       | Built-in filter factories                                                    |
+| `dispersa/builders`      | Output builder functions                                                     |
+| `dispersa/renderers`     | Renderer types, `defineRenderer`, and `outputTree` helper                    |
+| `dispersa/preprocessors` | Preprocessor type                                                            |
+| `dispersa/errors`        | Error classes (`DispersaError`, `TokenReferenceError`, etc.)                 |
+| `dispersa/config`        | `defineConfig` helper for CLI config files                                   |
 
 Everything outside these entry points is internal and not a stable API contract.
 
@@ -774,13 +796,17 @@ Resolver -> Preprocessors -> $ref resolution -> Parse/flatten -> Alias resolutio
 
 See [`examples/`](./examples/) for complete working projects. Suggested learning path:
 
-| Example                                        | Focus                                         |
-| ---------------------------------------------- | --------------------------------------------- |
-| [`basic`](./examples/basic/)                   | Minimal setup with light/dark themes          |
-| [`no-filesystem`](./examples/no-filesystem/)   | In-memory mode with inline tokens             |
-| [`custom-plugins`](./examples/custom-plugins/) | Custom transforms, filters, and renderers     |
-| [`advanced`](./examples/advanced/)             | Multi-modifier system with all output formats |
-| [`enterprise`](./examples/enterprise/)         | Multi-brand, multi-platform at scale          |
+| Example                                                | Focus                                                     |
+| ------------------------------------------------------ | --------------------------------------------------------- |
+| [`typescript-starter`](./examples/typescript-starter/) | Programmatic build script with themed CSS                 |
+| [`cli-starter`](./examples/cli-starter/)               | Config-file workflow using the dispersa CLI               |
+| [`in-memory`](./examples/in-memory/)                   | In-memory mode with inline tokens                         |
+| [`custom-plugins`](./examples/custom-plugins/)         | Custom transforms, filters, and renderers                 |
+| [`multi-format`](./examples/multi-format/)             | Multi-modifier system with all output formats             |
+| [`multi-brand`](./examples/multi-brand/)               | Multi-brand, multi-platform at scale                      |
+| [`multi-platform`](./examples/multi-platform/)         | CSS, Tailwind, iOS, and Android from one set              |
+| [`split-by-type`](./examples/split-by-type/)           | Filtered outputs split by token category                  |
+| [`atlassian-semantic`](./examples/atlassian-semantic/) | Semantic tokens with density, motion, and theme modifiers |
 
 ## License
 

package/dist/builders.cjs

@@ -210,32 +210,55 @@ function filterTokensBySource(tokens, expectedSource) {
   }
   return filtered;
 }
-function interpolatePattern(pattern, modifierInputs, modifierName, context) {
-  let result = pattern;
-  if (modifierName !== void 0) {
-    result = result.replace(/\{modifierName\}/g, modifierName);
+function filterTokensFromSets(tokens) {
+  const filtered = {};
+  for (const [name, token] of Object.entries(tokens)) {
+    const hasModifierSource = typeof token._sourceModifier === "string" && token._sourceModifier !== "";
+    if (!hasModifierSource) {
+      filtered[name] = token;
+    }
   }
-  if (context !== void 0) {
-    result = result.replace(/\{context\}/g, context);
+  return filtered;
+}
+function resolveBaseFileName(fileName, defaults) {
+  if (typeof fileName === "function") {
+    return fileName({ ...defaults, _base: "true" });
+  }
+  if (/\{.+?\}/.test(fileName)) {
+    const baseInputs = Object.fromEntries(Object.keys(defaults).map((k) => [k, "base"]));
+    return collapseBaseSegments(interpolatePattern(fileName, baseInputs));
+  }
+  const extMatch = fileName.match(/(\.[^.]+)$/);
+  const extension = extMatch ? extMatch[1] : "";
+  const baseName = extension ? fileName.slice(0, -extension.length) : fileName;
+  return `${baseName}-base${extension}`;
+}
+function collapseBaseSegments(value) {
+  let result = value;
+  let previous = "";
+  while (result !== previous) {
+    previous = result;
+    result = result.replace(/\bbase([/-])base\b/, "base");
   }
+  return result;
+}
+function interpolatePattern(pattern, modifierInputs) {
+  let result = pattern;
   for (const [key, value] of Object.entries(modifierInputs)) {
     result = result.replaceAll(`{${key}}`, value);
   }
   return result;
 }
-function resolveFileName(fileName, modifierInputs, modifierName, context) {
+function resolveFileName(fileName, modifierInputs) {
   if (typeof fileName === "function") {
     return fileName(modifierInputs);
   }
   if (/\{.+?\}/.test(fileName)) {
-    return interpolatePattern(fileName, modifierInputs, modifierName, context);
+    return interpolatePattern(fileName, modifierInputs);
   }
   const extMatch = fileName.match(/(\.[^.]+)$/);
   const extension = extMatch ? extMatch[1] : "";
   const baseName = extension ? fileName.slice(0, -extension.length) : fileName;
-  if (modifierName !== void 0 && context !== void 0) {
-    return `${baseName}-${modifierName}-${context}${extension}`;
-  }
   const modifierSuffix = Object.entries(modifierInputs).sort(([keyA], [keyB]) => keyA.localeCompare(keyB)).map(([key, value]) => `${key}-${value}`).join("-");
   if (modifierSuffix) {
     return `${baseName}-${modifierSuffix}${extension}`;
@@ -1350,6 +1373,33 @@ function collectRemainder(tokens, included) {
   }
   return result;
 }
+function buildSetLayerBlocks(tokens, resolver) {
+  const blocks = [];
+  const included = /* @__PURE__ */ new Set();
+  const addBlock = (key, blockTokens, description) => {
+    if (Object.keys(blockTokens).length === 0) {
+      return;
+    }
+    for (const k of Object.keys(blockTokens)) {
+      included.add(k);
+    }
+    blocks.push({ key, description, tokens: blockTokens });
+  };
+  for (const item of resolver.resolutionOrder) {
+    const ref = item.$ref;
+    if (typeof ref !== "string" || !ref.startsWith("#/sets/")) {
+      continue;
+    }
+    const setName = ref.slice("#/sets/".length);
+    addBlock(
+      `Set: ${setName}`,
+      collectSetTokens(tokens, setName, included),
+      resolver.sets?.[setName]?.description
+    );
+  }
+  addBlock("Unattributed", collectRemainder(tokens, included));
+  return blocks;
+}
 function buildDefaultLayerBlocks(tokens, baseModifierInputs, resolver) {
   const blocks = [];
   const included = /* @__PURE__ */ new Set();
@@ -2070,6 +2120,10 @@ var CssRenderer = class _CssRenderer {
       throw new ConfigurationError("Modifier preset requires modifiers to be defined in resolver");
     }
     const files = {};
+    const baseResult = await this.buildModifierBaseFile(context, options);
+    if (baseResult) {
+      files[baseResult.fileName] = baseResult.content;
+    }
     for (const [modifierName, modifierDef] of Object.entries(context.resolver.modifiers)) {
       for (const contextValue of Object.keys(modifierDef.contexts)) {
         const result = await this.buildModifierContextFile(
@@ -2085,6 +2139,59 @@ var CssRenderer = class _CssRenderer {
     }
     return { kind: "outputTree", files };
   }
+  async buildModifierBaseFile(context, options) {
+    const basePermutation = context.permutations.find(
+      ({ modifierInputs }) => this.isBasePermutation(modifierInputs, context.meta.defaults)
+    );
+    if (!basePermutation) {
+      return void 0;
+    }
+    const setTokens = filterTokensFromSets(basePermutation.tokens);
+    if (Object.keys(setTokens).length === 0) {
+      return void 0;
+    }
+    const setBlocks = buildSetLayerBlocks(setTokens, context.resolver);
+    if (setBlocks.length === 0) {
+      return void 0;
+    }
+    const modifiers = context.resolver.modifiers;
+    const firstModifierName = Object.keys(modifiers)[0] ?? "";
+    const firstModifierContext = context.meta.defaults[firstModifierName] ?? "";
+    const baseModifierInputs = { ...context.meta.defaults };
+    const selector = resolveSelector(
+      options.selector,
+      firstModifierName,
+      firstModifierContext,
+      true,
+      baseModifierInputs
+    );
+    const mediaQuery = resolveMediaQuery(
+      options.mediaQuery,
+      firstModifierName,
+      firstModifierContext,
+      true,
+      baseModifierInputs
+    );
+    const referenceTokens = basePermutation.tokens;
+    const cssBlocks = [];
+    for (const block of setBlocks) {
+      const cleanTokens = stripInternalMetadata(block.tokens);
+      const css2 = await this.formatTokens(cleanTokens, {
+        selector,
+        mediaQuery,
+        minify: options.minify ?? false,
+        preserveReferences: options.preserveReferences ?? false,
+        referenceTokens
+      });
+      const header = block.description ? `/* ${block.key} */
+/* ${block.description} */` : `/* ${block.key} */`;
+      cssBlocks.push(`${header}
+${css2}`);
+    }
+    const content = cssBlocks.join("\n");
+    const fileName = context.output.file ? resolveBaseFileName(context.output.file, context.meta.defaults) : `${context.output.name}-base.css`;
+    return { fileName, content };
+  }
   collectTokensForModifierContext(modifierName, contextValue, permutations) {
     const expectedSource = `${modifierName}-${contextValue}`;
     let tokensFromSource = {};
@@ -2131,7 +2238,7 @@ var CssRenderer = class _CssRenderer {
       preserveReferences: options.preserveReferences ?? false,
       referenceTokens
     });
-    const fileName = context.output.file ? resolveFileName(context.output.file, modifierInputs, modifierName, contextValue) : buildInMemoryOutputKey({
+    const fileName = context.output.file ? resolveFileName(context.output.file, modifierInputs) : buildInMemoryOutputKey({
       outputName: context.output.name,
       extension: "css",
       modifierInputs,