@digital-gravy/etch-public-api 0.3.3 → 0.3.4

package/README.md

@@ -81,14 +81,23 @@ const classStyles = etch.styles.list({ type: "class" });
 const myStyle = etch.styles.list().find((s) => s.selector === ".lead");
 console.log(myStyle?.id); // the id you pass to blocks.addClass etc.
 
-// Global CSS custom properties
+// Global CSS custom properties (default collection)
 etch.styles.setVariable("--brand", "#0af");
 etch.styles.getVariable("--brand"); // "#0af"
+
+// Variable methods accept an optional collection for multi-collection :root setups
+etch.styles.setVariable("--brand", "#0af", "theme-a");
+etch.styles.getVariable("--brand", "theme-a"); // "#0af"
+etch.styles.listVariables("theme-a");
+etch.styles.removeVariable("--brand", "theme-a");
 ```
 
-> **Note:** The `collection` field on style objects is an internal implementation
-> detail. Always omit the `collection` argument — the default collection is the
-> only one supported via the public API.
+> **Note:** The `collection` field on style **objects** (`StyleSummary`) and the
+> `collection` argument on `create` / `update` are internal implementation
+> details — always omit them for regular styles. The four `:root` variable
+> methods (`listVariables`, `getVariable`, `setVariable`, `removeVariable`) are
+> the exception: they accept an optional `collection` parameter, defaulting to
+> `"default"` when omitted.
 
 ### Component edit mode
 

package/dist/index.d.cts

@@ -610,14 +610,26 @@ interface EtchStylesApi {
     update(styleId: string, patch: StylePatch): void;
     /** Delete a style rule by id. */
     delete(styleId: string): void;
-    /** All global CSS custom properties as a `name -> value` record. */
-    listVariables(): Record<string, string>;
-    /** Read one global CSS custom property, or `undefined` when unset. */
-    getVariable(name: string): string | undefined;
-    /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
-    setVariable(name: string, value: string): void;
-    /** Remove a global CSS custom property. */
-    removeVariable(name: string): void;
+    /**
+     * All global CSS custom properties as a `name -> value` record.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    listVariables(collection?: string): Record<string, string>;
+    /**
+     * Read one global CSS custom property, or `undefined` when unset.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    getVariable(name: string, collection?: string): string | undefined;
+    /**
+     * Set a global CSS custom property (e.g. `('--brand', '#0af')`).
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    setVariable(name: string, value: string, collection?: string): void;
+    /**
+     * Remove a global CSS custom property.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    removeVariable(name: string, collection?: string): void;
 }
 
 /**

package/dist/index.d.ts

@@ -610,14 +610,26 @@ interface EtchStylesApi {
     update(styleId: string, patch: StylePatch): void;
     /** Delete a style rule by id. */
     delete(styleId: string): void;
-    /** All global CSS custom properties as a `name -> value` record. */
-    listVariables(): Record<string, string>;
-    /** Read one global CSS custom property, or `undefined` when unset. */
-    getVariable(name: string): string | undefined;
-    /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
-    setVariable(name: string, value: string): void;
-    /** Remove a global CSS custom property. */
-    removeVariable(name: string): void;
+    /**
+     * All global CSS custom properties as a `name -> value` record.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    listVariables(collection?: string): Record<string, string>;
+    /**
+     * Read one global CSS custom property, or `undefined` when unset.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    getVariable(name: string, collection?: string): string | undefined;
+    /**
+     * Set a global CSS custom property (e.g. `('--brand', '#0af')`).
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    setVariable(name: string, value: string, collection?: string): void;
+    /**
+     * Remove a global CSS custom property.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    removeVariable(name: string, collection?: string): void;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital-gravy/etch-public-api",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
   "license": "MIT",
   "type": "module",
@@ -43,4 +43,4 @@
     "typescript": "^5.7.2",
     "vitest": "^3.0.5"
   }
-}
+}