@terrazzo/plugin-vanilla-extract 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @terrazzo/plugin-vanilla-extract
+
+## 0.0.1
+
+Initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Drew Powers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# ⛋ @terrazzo/plugin-vanilla-extract
+
+Generate [Vanilla Extract](https://vanilla-extract.style) CSS themes from DTCG tokens.
+
+## Setup
+
+Requires [Node.js 20 or later](https://nodejs.org). With that installed, run:
+
+```sh
+npm i -D @terrazzo/cli @terrazzo/plugin-css @terrazzo/plugin-vanilla-extract
+```
+
+Add a `terrazzo.config.js` to the root of your project with:
+
+```ts
+import { defineConfig } from "@terrazzo/cli";
+import css from "@terrazzo/plugin-css";
+import vanillaExtract from "@terrazzo/plugin-vanilla-extract";
+
+export default defineConfig({
+  plugins: [
+    css({
+      // Optional: control the final CSS variable names
+      variableName: (id) => id.replace(/\./g, "-"),
+      // Optional: pass `skipBuild: true` to not generate a .css file if only using Vanilla Extract.
+      skipBuild: false,
+    }),
+
+    vanillaExtract({
+      filename: "themes.css.ts",
+
+      // generate createTheme()
+      themes: [
+        { name: "light", mode: "light" },
+        { name: "dark", mode: "dark" },
+      ],
+
+      // generate createGlobalTheme()
+      globalThemes: [
+        { selector: "@media (prefers-color-scheme: light)", mode: "light" },
+        { selector: "@media (prefers-color-scheme: dark)", mode: "dark" },
+      ],
+    }),
+  ],
+});
+```
+
+This plugin extends [plugin-css](../plugin-css) and always generates [createGlobalThemeContract()](https://vanilla-extract.style/documentation/global-api/create-global-theme-contract/) to match your generated CSS global variable names 1:1. But from there, you can use either locally-scoped ([createThem()](https://vanilla-extract.style/documentation/api/create-theme/)) or globally-scoped ([createGlobalTheme()](https://vanilla-extract.style/documentation/global-api/create-global-theme/)) themes.
+
+[View documentation](https://terrazzo.app/docs/integrations/vanilla-extract)

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { Plugin, TokenTransformed } from "@terrazzo/parser";
+
+//#region src/lib.d.ts
+declare const FORMAT_ID = "vanilla-extract";
+declare const THEME_CONTRACT_VAR = "tzVars";
+interface VanillaExtractPluginOptions {
+  /**
+   * Filename to generate.
+   * @default "theme.css.ts"
+   */
+  filename?: string;
+  /**
+   * - true: use global `createGlobalThemeContract()` API
+   * - false: use scoped `createThemeContract()` API
+   * @default true
+   */
+  globalThemeContract?: boolean;
+  /**
+   * Mapping of exported JS variables to token modes. The key MUST be a valid JS identifier.
+   * @example
+   *
+   * ```js
+   * themes: {
+   *   default: { mode: "." }, // "." refers to the default mode, or no mode
+   *   light: { mode: "light" },
+   *   dark: { mode: "dark" },
+   * }
+   * ```
+   */
+  themes?: Record<string, {
+    mode: string | string[];
+  }>;
+  /**
+   * Mapping of exported JS variables to token modes for global themes. The key MUST be a valid JS identifier.
+   * @example
+   *
+   * ```js
+   * globalThemes: {
+   *   default: { selector: ":root", mode: "." }, // "." refers to the default mode, or no mode
+   *   light: { selector: "[data-color-mode=light]", mode: "light" },
+   *   dark: { selector: "[data-color-mode=dark]" mode: "dark" },
+   * }
+   * ```
+   */
+  globalThemes?: Record<string, {
+    selector: string;
+    mode: string | string[];
+  }>;
+  /**
+   * Change the naming strategy for the createTheme() API’s `[class, vars]` tuple.
+   * @default (name) => [`${name}Class`, name]
+   */
+  themeVarNaming?: (name: string) => [string, string];
+}
+declare const VE: {
+  createTheme: string;
+  createGlobalTheme: string;
+  createThemeContract: string;
+  createGlobalThemeContract: string;
+};
+declare function isJSIdent(ident: unknown): boolean;
+/** Generate createThemeContract() or createGlobalThemeContract() */
+declare function generateThemeContract({
+  tokens,
+  globalThemeContract
+}: {
+  tokens: TokenTransformed[];
+  globalThemeContract: boolean;
+}): string;
+/** Generate createTheme()/createGlobalTheme() */
+declare function generateTheme({
+  name,
+  namingPattern,
+  tokens,
+  selector,
+  globalTheme
+}: {
+  name: string;
+  namingPattern: (name: string) => [string, string];
+  tokens: TokenTransformed[];
+  selector?: string;
+  globalTheme?: boolean;
+}): string;
+/** Encode an alias to a Vanilla Extract token inside a JSON array */
+declare function serializeValue(value: string | number | boolean, tokens: TokenTransformed[]): string;
+/** Decode all aliases from a JSON string */
+declare function deserializeAllValues(json: string): string;
+//# sourceMappingURL=lib.d.ts.map
+//#endregion
+//#region src/index.d.ts
+declare function vanillaExtractPlugin(options: VanillaExtractPluginOptions): Plugin;
+//# sourceMappingURL=index.d.ts.map
+
+//#endregion
+export { FORMAT_ID, THEME_CONTRACT_VAR, VE, VanillaExtractPluginOptions, vanillaExtractPlugin as default, deserializeAllValues, generateTheme, generateThemeContract, isJSIdent, serializeValue };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/lib.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;cAGa,SAAA;cACA,kBAAA;AADA,UAGI,2BAAA,CAHK;EACT;AAEb;;;EAwBiB,QAaA,CAAA,EAAA,MAAA;EAAM;AASvB;AAOA;AAQA;;EAAqC,mBACnC,CAAA,EAAA,OAAA;EAAM;;AAGkB;AA0B1B;;;;;;;;AAS0B;EA2CV,MAAA,CAAA,EAvHL,MAuHK,CAAA,MAAc,EAAA;IAyCd,IAAA,EAAA,MAAA,GAAA,MAAoB,EAAA;;;;AClLX;;;;AAEiE;;;;;;iBD6BzE;;;;;;;;;;cASJ;;;;;;iBAOG,SAAA;;iBAQA,qBAAA;;;;UAIN;;;;iBA0BM,aAAA;;;;;;;;;UASN;;;;;iBA2CM,cAAA,2CAAyD;;iBAyCzD,oBAAA;;;;AA3LH,iBCWW,oBAAA,CDXF,OAAA,ECWgC,2BDXhC,CAAA,ECW8D,MDX9D;AACtB"}