@pantoken/utils 0.2.6 → 0.4.0

package/dist/index.d.mts

@@ -63,6 +63,23 @@ declare function focusOutlineRules(selector?: string): string;
 //#region src/index.d.ts
 /** The colour mode to collapse `light-dark()` to. */
 type Mode = "light" | "dark";
+/** One entry of the pantoken spacing scale: the short key, the long (word) key, and the shared CSS value. */
+interface SpacingStep {
+  /** The short scale key, e.g. `"sm"` (the zero step's short key is `"0"`). */
+  short: string;
+  /** The long, word-spelled key, e.g. `"small"` (the zero step's long key is `"none"`). */
+  long: string;
+  /** The CSS value — a token reference, or a plain `"0"`/`"auto"`. */
+  value: string;
+}
+/**
+ * The pantoken spacing scale, `none`/`0` → `2xl` — the single shared source for
+ * `@pantoken/components`' spacing/gap utilities and `@pantoken/interactions`' `resolveSpace`, so the
+ * two never drift apart.
+ */
+declare const SPACING_STEPS: readonly SpacingStep[];
+/** The `auto` step — margin only, spelled the same both ways. */
+declare const SPACING_AUTO_STEP: SpacingStep;
 /**
  * Strip `<script>` elements and event-handler attributes from SVG markup.
  *
@@ -267,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}.
@@ -311,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, 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

@@ -121,16 +121,69 @@ function focusOutlineRules(selector = FOCUSABLE_SELECTOR) {
 /**
 * `@pantoken/utils` — shared, upstream-free helpers used across the pantoken packages: the token
 * reference resolver (with `light-dark()` handling), the two token regexes (typed via `arkregex`),
-* kebab→camel case, hex-colour parsing, and the generic token→utility-class emitters
-* ({@link colorUtilitiesCss}, {@link tokenUtilitiesCss}) that both `@pantoken/components` (semantic
-* tier) and `@pantoken/plugin-primitives` (raw-palette tier) build on. Depends only on
-* `@pantoken/model` (types) + `arkregex`, so any package can use it without pulling the GitHub-only
-* upstream.
+* kebab→camel case, hex-colour parsing, the shared spacing scale ({@link SPACING_STEPS}), and the
+* generic token→utility-class emitters ({@link colorUtilitiesCss}, {@link tokenUtilitiesCss}) that
+* both `@pantoken/components` (semantic tier) and `@pantoken/plugin-primitives` (raw-palette tier)
+* build on. Depends only on `@pantoken/model` (types) + `arkregex`, so any package can use it without
+* pulling the GitHub-only upstream.
 *
 * @module
 * @beta
 */
 /**
+* The pantoken spacing scale, `none`/`0` → `2xl` — the single shared source for
+* `@pantoken/components`' spacing/gap utilities and `@pantoken/interactions`' `resolveSpace`, so the
+* two never drift apart.
+*/
+const SPACING_STEPS = [
+	{
+		short: "0",
+		long: "none",
+		value: "var(--instui-component-shared-tokens-spacing-general-space-none)"
+	},
+	{
+		short: "2xs",
+		long: "xx-small",
+		value: "var(--instui-spacing-space2xs)"
+	},
+	{
+		short: "xs",
+		long: "x-small",
+		value: "var(--instui-spacing-space-xs)"
+	},
+	{
+		short: "sm",
+		long: "small",
+		value: "var(--instui-spacing-space-sm)"
+	},
+	{
+		short: "md",
+		long: "medium",
+		value: "var(--instui-spacing-space-md)"
+	},
+	{
+		short: "lg",
+		long: "large",
+		value: "var(--instui-spacing-space-lg)"
+	},
+	{
+		short: "xl",
+		long: "x-large",
+		value: "var(--instui-spacing-space-xl)"
+	},
+	{
+		short: "2xl",
+		long: "xx-large",
+		value: "var(--instui-spacing-space2xl)"
+	}
+];
+/** The `auto` step — margin only, spelled the same both ways. */
+const SPACING_AUTO_STEP = {
+	short: "auto",
+	long: "auto",
+	value: "auto"
+};
+/**
 * Strip `<script>` elements and event-handler attributes from SVG markup.
 *
 * Defense-in-depth for SVG decoded from vendored data URIs or contributed by plugins.
@@ -376,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}.
@@ -389,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`;
 }
@@ -414,10 +475,12 @@ 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
-export { ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, 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, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };

package/package.json

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