@pantoken/utils 0.5.0 → 1.0.0

package/README.md

@@ -47,12 +47,16 @@ const byName = resolveTokens(tokens, { mode: "dark" });
 - **`extractInstuiRefs(text)` / `tokenNames(ir)`** — the primitives the two checks build on,
   exposed for custom assertions.
 - **`colorUtilitiesCss(names, options?)`** — the semantic-colour utility emitter:
-  `.<prefix>-bg-<name>` / `-fg-` / `-border-` from `--instui-color-<family>-<name>`, one per token.
+  `--bg-<name>` / `--text-<name>` / `--border-<name>` from `--instui-color-<family>-<name>`, one per
+  token. `--color-<name>` is emitted as an alias of `--text-<name>` (same declaration).
 - **`tokenUtilitiesCss(groups, options?)`** — the generic token→class emitter: one class per token,
   applied to its CSS property (the `--instui-` tail is the class name). Both emitters carry no
   InstUI-look opinion — the caller supplies the names. `@pantoken/components` feeds them a curated
-  _semantic_ allowlist; `@pantoken/plugin-primitives` feeds the raw palette. `options.prefix` sets the
-  class prefix; any falsy value drops it.
+  _semantic_ allowlist; `@pantoken/plugin-primitives` feeds the raw palette. Every class is a
+  double-dash global modifier built via `globalModifierSelector` — matches standalone or chained onto
+  any component, and wins the cascade deterministically over a same-named component modifier.
+- **`globalModifierSelector(p, name)`** — the shared selector builder behind the two emitters above
+  (and every double-dash utility in `@pantoken/components`): `:where(*).--name.--name.--name`.
 - **`VAR_RE` / `LIGHT_DARK_RE`** — the two token regexes, built with `arkregex`'s `regex()` so
   their capture groups are typed on `.exec()` / `.matchAll()`. They're real `RegExp` instances.
 - **`Mode`, `ResolveOptions`, `Rgba`, `UtilityOptions`, `ColorUtilityNames`, `TokenUtilityGroup`** —

package/dist/index.d.mts

@@ -325,14 +325,19 @@ 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[];
 }
+/**
+ * Build a global-utility modifier selector: `:where(*).--name.--name.--name`. The modifier class
+ * repeated 3x gives the rule (0,3,0) specificity, which deterministically outranks any real 2-class
+ * component-modifier compound (`.instui-view.-mod`, 0,2,0) regardless of source order — the `:where(*)`
+ * wrapper contributes zero specificity of its own, so it's purely documentation that this is a global
+ * modifier, not a scoping condition. A plain class selector already matches standalone (`--mt-lg` with
+ * no other class) or chained onto any component, core or plugin-authored, with no per-component
+ * enumeration needed. Replaces the old bare-class-plus-enumerated-per-component-compound pattern
+ * (`globalSelectors`/`chainTargets`), which couldn't reach plugin-authored components and didn't scale
+ * to high-cardinality utilities like spacing.
+ */
+declare function globalModifierSelector(p: string, name: string): string;
 /** 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`). */
@@ -346,9 +351,10 @@ interface ColorUtilityNames {
 /**
  * Build the semantic-colour utility stylesheet: `.<prefix>-bg-<name>` (background),
  * `.<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`), or an explicit `[name, token]` pair to
- * source a name from a different token than the family's own scale.
+ * colour token. `.<prefix>-color-<name>` is emitted alongside `.<prefix>-text-<name>` as an alias — same
+ * declaration, either class name works. Overrides are therefore only ever token-valid — no primitives,
+ * no arbitrary hex. Pass 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}.
@@ -381,4 +387,4 @@ interface TokenUtilityGroup {
  */
 declare function tokenUtilitiesCss(groups: readonly TokenUtilityGroup[], options?: UtilityOptions): string;
 //#endregion
-export { type ColorUtilityEntry, type ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, type Mode, type ResolveOptions, type Rgba, SPACING_AUTO_STEP, SPACING_STEPS, type SpacingStep, type TokenUtilityGroup, type UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };
+export { type ColorUtilityEntry, type ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, type Mode, type ResolveOptions, type Rgba, SPACING_AUTO_STEP, SPACING_STEPS, type SpacingStep, type TokenUtilityGroup, type UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, globalModifierSelector, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };

package/dist/index.mjs

@@ -444,11 +444,27 @@ const SPACING_AUTO_STEP = {
 //#endregion
 //#region src/utility-css.ts
 /**
+* Build a global-utility modifier selector: `:where(*).--name.--name.--name`. The modifier class
+* repeated 3x gives the rule (0,3,0) specificity, which deterministically outranks any real 2-class
+* component-modifier compound (`.instui-view.-mod`, 0,2,0) regardless of source order — the `:where(*)`
+* wrapper contributes zero specificity of its own, so it's purely documentation that this is a global
+* modifier, not a scoping condition. A plain class selector already matches standalone (`--mt-lg` with
+* no other class) or chained onto any component, core or plugin-authored, with no per-component
+* enumeration needed. Replaces the old bare-class-plus-enumerated-per-component-compound pattern
+* (`globalSelectors`/`chainTargets`), which couldn't reach plugin-authored components and didn't scale
+* to high-cardinality utilities like spacing.
+*/
+function globalModifierSelector(p, name) {
+	const cls = `.--${name}`;
+	return `:where(*)${cls}${cls}${cls}`;
+}
+/**
 * Build the semantic-colour utility stylesheet: `.<prefix>-bg-<name>` (background),
 * `.<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`), or an explicit `[name, token]` pair to
-* source a name from a different token than the family's own scale.
+* colour token. `.<prefix>-color-<name>` is emitted alongside `.<prefix>-text-<name>` as an alias — same
+* declaration, either class name works. Overrides are therefore only ever token-valid — no primitives,
+* no arbitrary hex. Pass 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}.
@@ -459,17 +475,15 @@ const SPACING_AUTO_STEP = {
 function colorUtilitiesCss(names, options = {}) {
 	const prefix = options.prefix || "";
 	const p = prefix ? `${prefix}-` : "";
-	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}; }`;
+		return `${(typeof util === "string" ? [util] : util).map((word) => globalModifierSelector(p, `${word}-${n}`)).join(", ")} { ${prop}: ${value}; }`;
 	}).join("\n");
 	return `/* InstUI semantic colour utilities (@pantoken/utils) — prefix: ${prefix} */\n${[
 		emit("background", "bg", "background", names.background),
-		emit("text", "text", "color", names.text),
+		emit("text", ["text", "color"], "color", names.text),
 		emit("stroke", "border", "border-color", names.stroke)
 	].join("\n")}\n`;
 }
@@ -491,12 +505,10 @@ 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-/, "");
-		const modifier = `.-${name}`;
-		return `${[`.${p}${name}`, ...chainTargets.map((target) => `.${p}${target}${modifier}`)].join(", ")} { ${property}: var(${token}); }`;
+		return `${globalModifierSelector(p, name)} { ${property}: var(${token}); }`;
 	})).join("\n")}\n`;
 }
 //#endregion
-export { ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, SPACING_AUTO_STEP, SPACING_STEPS, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };
+export { ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, SPACING_AUTO_STEP, SPACING_STEPS, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, globalModifierSelector, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantoken/utils",
-  "version": "0.5.0",
+  "version": "1.0.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",