@pantoken/utils

Shared, upstream-free helpers used across the pantoken packages: the token reference resolver (with light-dark() handling), the two token regexes, kebab→camel case, hex-colour parsing, the drift/reference-integrity checks, and the generic token→utility-class emitters. Depends only on @pantoken/model (types) and arkregex, so any package can use it without pulling the GitHub-only upstream token source.

Install

npm i @pantoken/utils

Usage

import { makeResolver, resolveTokens } from "@pantoken/utils";
import { tokens } from "@pantoken/tokens";

// Expand var(--x) chains to concrete leaf values, collapsing light-dark() to one branch.
const resolve = makeResolver(tokens, { mode: "light" });
resolve("var(--instui-color-background-base)"); // → "#ffffff"

// Or resolve every token at once, keyed by name.
const byName = resolveTokens(tokens, { mode: "dark" });

API

• makeResolver(base, { mode?, overrides? }) — build a resolver that expands var(--x) references to concrete leaf values against base (plus overrides, which win on name collisions). With mode ("light" / "dark") it collapses light-dark() to that branch; without, it keeps light-dark() intact. Replaces the per-package resolver that used to be copy-pasted across the formats and renderers.
• resolveTokens(base, opts) — makeResolver applied to every token, returned as a name → resolved Map.
• camelCase(kebab) — color-background-brand → colorBackgroundBrand.
• parseHexColor(hex) — parse #rgb / #rrggbb / #rrggbbaa to { r, g, b, a } (r/g/b 0–255, a 0–1), or undefined for a non-hex string.
• unknownReferences(text, ir) — drift check: the --instui-* names in text the IR doesn't define (sorted; empty means no drift). Use for outputs that reference tokens defined elsewhere, such as the docusaurus, vitepress, bootstrap, and shadcn bridges.
• danglingReferences(css) — self-containment check: the --instui-* names referenced via var() that the same stylesheet never defines. Use for self-contained stylesheets (css, pendo).
• 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.
• 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.
• 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 — the supporting types.

For value fidelity (an emitted, resolved value equals the IR's resolved value), compare against resolveTokens(ir, { mode }) directly — see @pantoken/scss's test.

Related

• Types come from @pantoken/model.
• @pantoken/plugin-kit re-exports makeResolver and resolveTokens for plugin authors.

License

MIT