@pantoken/utils 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -284,18 +284,30 @@ interface UtilityOptions {
    * falsy value (`null`/`undefined`/`""`) drops the prefix entirely (`.bg-…`).
    */
   prefix?: string | null;
+  /**
+   * Component base-class names (e.g. `"button"`, `"view"`) to also emit a chained alias for, per
+   * rule — `.<prefix>-bg-danger` (bare) plus `.<prefix>-button.-bg-danger` (chained), so the same
+   * modifier works standalone or attached to any component. Omit for bare-only output (unchanged
+   * behavior).
+   */
+  chainTargets?: readonly string[];
 }
-/** The semantic colour token names (without the `--instui-color-<family>-` prefix) per family. */
+/** One semantic colour family entry: a bare name (resolved against `--instui-color-<family>-<name>`)
+ *  or an explicit `[name, value]` pair — the second element is `var()`-wrapped if it's a `--custom-prop`
+ *  name, or used verbatim otherwise (a `light-dark(…)` expression, a raw keyword like `transparent`). */
+type ColorUtilityEntry = string | readonly [name: string, value: string];
+/** The semantic colour token names (or explicit `[name, token]` pairs) per family. */
 interface ColorUtilityNames {
-  background: readonly string[];
-  text: readonly string[];
-  stroke: readonly string[];
+  background: readonly ColorUtilityEntry[];
+  text: readonly ColorUtilityEntry[];
+  stroke: readonly ColorUtilityEntry[];
 }
 /**
  * Build the semantic-colour utility stylesheet: `.<prefix>-bg-<name>` (background),
- * `.<prefix>-fg-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
+ * `.<prefix>-text-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
  * colour token. Overrides are therefore only ever token-valid — no primitives, no arbitrary hex. Pass
- * the token names per family (e.g. from `@pantoken/tokens`).
+ * the token names per family (e.g. from `@pantoken/tokens`), or an explicit `[name, token]` pair to
+ * source a name from a different token than the family's own scale.
  *
  * @param names - {@link ColorUtilityNames}.
  * @param options - {@link UtilityOptions}.
@@ -328,4 +340,4 @@ interface TokenUtilityGroup {
  */
 declare function tokenUtilitiesCss(groups: readonly TokenUtilityGroup[], options?: UtilityOptions): string;
 //#endregion
-export { ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, Mode, ResolveOptions, Rgba, SPACING_AUTO_STEP, SPACING_STEPS, SpacingStep, TokenUtilityGroup, UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };
+export { ColorUtilityEntry, ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, Mode, ResolveOptions, Rgba, SPACING_AUTO_STEP, SPACING_STEPS, SpacingStep, TokenUtilityGroup, UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };

package/dist/index.mjs

@@ -429,9 +429,10 @@ function danglingReferences(css) {
 }
 /**
 * Build the semantic-colour utility stylesheet: `.<prefix>-bg-<name>` (background),
-* `.<prefix>-fg-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
+* `.<prefix>-text-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
 * colour token. Overrides are therefore only ever token-valid — no primitives, no arbitrary hex. Pass
-* the token names per family (e.g. from `@pantoken/tokens`).
+* the token names per family (e.g. from `@pantoken/tokens`), or an explicit `[name, token]` pair to
+* source a name from a different token than the family's own scale.
 *
 * @param names - {@link ColorUtilityNames}.
 * @param options - {@link UtilityOptions}.
@@ -442,10 +443,17 @@ function danglingReferences(css) {
 function colorUtilitiesCss(names, options = {}) {
 	const prefix = options.prefix || "";
 	const p = prefix ? `${prefix}-` : "";
-	const emit = (family, util, prop, list) => list.map((n) => `.${p}${util}-${n} { ${prop}: var(--instui-color-${family}-${n}); }`).join("\n");
+	const chainTargets = options.chainTargets ?? [];
+	const emit = (family, util, prop, list) => list.map((entry) => {
+		const isPair = (e) => typeof e !== "string";
+		const [n, token] = isPair(entry) ? entry : [entry, `--instui-color-${family}-${entry}`];
+		const value = token.startsWith("--") ? `var(${token})` : token;
+		const modifier = `.-${util}-${n}`;
+		return `${[`.${p}${util}-${n}`, ...chainTargets.map((target) => `.${p}${target}${modifier}`)].join(", ")} { ${prop}: ${value}; }`;
+	}).join("\n");
 	return `/* InstUI semantic colour utilities (@pantoken/utils) — prefix: ${prefix} */\n${[
 		emit("background", "bg", "background", names.background),
-		emit("text", "fg", "color", names.text),
+		emit("text", "text", "color", names.text),
 		emit("stroke", "border", "border-color", names.stroke)
 	].join("\n")}\n`;
 }
@@ -467,9 +475,11 @@ function colorUtilitiesCss(names, options = {}) {
 function tokenUtilitiesCss(groups, options = {}) {
 	const prefix = options.prefix || "";
 	const p = prefix ? `${prefix}-` : "";
+	const chainTargets = options.chainTargets ?? [];
 	return `/* InstUI token utilities (@pantoken/utils) — prefix: ${prefix} */\n${groups.flatMap(({ property, tokens }) => tokens.map((token) => {
 		const name = token.replace(/^--instui-/, "");
-		return `.${p}${name} { ${property}: var(${token}); }`;
+		const modifier = `.-${name}`;
+		return `${[`.${p}${name}`, ...chainTargets.map((target) => `.${p}${target}${modifier}`)].join(", ")} { ${property}: var(${token}); }`;
 	})).join("\n")}\n`;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantoken/utils",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared pantoken helpers: token reference resolver, typed regexes (arkregex), name-case, and hex-colour parsing.",
   "homepage": "https://pantoken.iywahl.com",
   "bugs": "https://github.com/thedannywahl/pantoken/issues",