@pantoken/utils 1.0.3 → 1.2.0

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, SCOPE_LAYERS, Scheme, THEME_ATTR, colorClass, colorScopeSelector, colorScopeSelectors, isScheme, schemeClass, schemeScopeSelector, schemeScopeSelectors, themeClass, themeScopeSelector, themeScopeSelectors } from "./scope.mjs";
 import { Token } from "@pantoken/model";
 //#region src/declarations.d.ts
 /**
@@ -77,7 +78,8 @@ interface ResolveOptions {
 /**
  * Build a resolver that expands `var(--x)` references to concrete leaf values against `base` (plus
  * any `overrides`). With `mode` it collapses `light-dark()` to that branch; without, it leaves
- * `light-dark()` in place.
+ * `light-dark()` in place. A token carrying a {@link Token.flatValue} resolves through that rather
+ * than its CSS-expression `value`, so callers always land on a real colour.
  *
  * @param base - The token set to resolve references against.
  * @param options - {@link ResolveOptions}.
@@ -387,4 +389,4 @@ interface TokenUtilityGroup {
  */
 export declare function tokenUtilitiesCss(groups: readonly TokenUtilityGroup[], options?: UtilityOptions): string;
 //#endregion
-export type { ColorUtilityEntry, ColorUtilityNames, Mode, ResolveOptions, Rgba, SpacingStep, TokenUtilityGroup, UtilityOptions };
+export { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, type ColorUtilityEntry, type ColorUtilityNames, INSTANCE_ATTR, type Mode, type ResolveOptions, type Rgba, SCHEME_ATTR, SCOPE_ATTRS, SCOPE_LAYERS, type Scheme, type SpacingStep, THEME_ATTR, type TokenUtilityGroup, type UtilityOptions, colorClass, colorScopeSelector, colorScopeSelectors, isScheme, schemeClass, schemeScopeSelector, schemeScopeSelectors, themeClass, themeScopeSelector, themeScopeSelectors };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, SCOPE_LAYERS, THEME_ATTR, colorClass, colorScopeSelector, colorScopeSelectors, isScheme, schemeClass, schemeScopeSelector, schemeScopeSelectors, themeClass, themeScopeSelector, themeScopeSelectors } from "./scope.mjs";
 import { regex } from "arkregex";
 //#region src/declarations.ts
 /**
@@ -134,7 +135,8 @@ const MAX_DEPTH = 12;
 /**
 * Build a resolver that expands `var(--x)` references to concrete leaf values against `base` (plus
 * any `overrides`). With `mode` it collapses `light-dark()` to that branch; without, it leaves
-* `light-dark()` in place.
+* `light-dark()` in place. A token carrying a {@link Token.flatValue} resolves through that rather
+* than its CSS-expression `value`, so callers always land on a real colour.
 *
 * @param base - The token set to resolve references against.
 * @param options - {@link ResolveOptions}.
@@ -185,8 +187,8 @@ const MAX_DEPTH = 12;
 * ```
 */
 function makeResolver(base, options = {}) {
-	const map = new Map(base.map((t) => [t.name, t.value]));
-	for (const t of options.overrides ?? []) map.set(t.name, t.value);
+	const map = new Map(base.map((t) => [t.name, t.flatValue ?? t.value]));
+	for (const t of options.overrides ?? []) map.set(t.name, t.flatValue ?? t.value);
 	const pickMode = (value) => {
 		if (!options.mode) return value;
 		const m = LIGHT_DARK_RE.exec(value.trim());
@@ -223,7 +225,7 @@ function makeResolver(base, options = {}) {
 */
 function resolveTokens(base, options = {}) {
 	const resolve = makeResolver(base, options);
-	return new Map(base.map((t) => [t.name, resolve(t.value)]));
+	return new Map(base.map((t) => [t.name, resolve(t.flatValue ?? t.value)]));
 }
 //#endregion
 //#region src/drift.ts
@@ -258,6 +260,11 @@ function extractInstuiRefs(text) {
 function tokenNames(ir) {
 	return new Set(ir.map((t) => t.name));
 }
+function declaredInstuiProperties(text) {
+	const declared = new Set([...text.matchAll(/@property\s+(--instui-[\w-]+)/g)].map((m) => m[1]));
+	for (const match of text.matchAll(/(--instui-[\w]+(?:-[\w]+)*)\s*:/g)) declared.add(match[1]);
+	return declared;
+}
 /**
 * Drift check: `--instui-*` names in `text` that the IR doesn't define (sorted; empty means no
 * drift). Use for outputs that *reference* tokens defined elsewhere — e.g. the docusaurus/vitepress
@@ -283,7 +290,8 @@ function tokenNames(ir) {
 */
 function unknownReferences(text, ir) {
 	const names = tokenNames(ir);
-	return [...extractInstuiRefs(text)].filter((name) => !names.has(name)).sort();
+	const declared = declaredInstuiProperties(text);
+	return [...extractInstuiRefs(text)].filter((name) => !names.has(name) && !declared.has(name)).sort();
 }
 /**
 * Self-containment check: `--instui-*` names referenced via `var()` in a stylesheet that it never
@@ -308,9 +316,7 @@ function unknownReferences(text, ir) {
 */
 function danglingReferences(css) {
 	const referenced = new Set([...css.matchAll(/var\(\s*?(--instui-[\w-]+)/g)].map((m) => m[1]));
-	const defined = /* @__PURE__ */ new Set();
-	for (const m of css.matchAll(/@property\s+(--instui-[\w-]+)/g)) defined.add(m[1]);
-	for (const m of css.matchAll(/(--instui-[\w]+(?:-[\w]+)*)\s*:/g)) defined.add(m[1]);
+	const defined = declaredInstuiProperties(css);
 	return [...referenced].filter((name) => !defined.has(name)).sort();
 }
 //#endregion
@@ -511,4 +517,4 @@ function tokenUtilitiesCss(groups, options = {}) {
 	})).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, globalModifierSelector, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };
+export { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, ELEVATION_NAMES, FOCUSABLE_SELECTOR, INSTANCE_ATTR, LIGHT_DARK_RE, SCHEME_ATTR, SCOPE_ATTRS, SCOPE_LAYERS, SPACING_AUTO_STEP, SPACING_STEPS, THEME_ATTR, VAR_RE, camelCase, colorClass, colorScopeSelector, colorScopeSelectors, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, globalModifierSelector, isScheme, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, schemeClass, schemeScopeSelector, schemeScopeSelectors, themeClass, themeScopeSelector, themeScopeSelectors, tokenNames, tokenUtilitiesCss, unknownReferences };

package/dist/scope.d.mts

@@ -0,0 +1,53 @@
+//#region src/scope.d.ts
+/**
+ * The scope attribute contract — the single source of truth shared by the CSS emitter
+ * (`@pantoken/css`, which selects on these) and the runtime (`@pantoken/scope`, which writes them).
+ *
+ * Its own module with zero imports, exposed at the `@pantoken/utils/scope` entry, so the browser
+ * runtime can take the names without pulling `arkregex` or the resolver in behind the barrel.
+ *
+ * @module
+ */
+/** Attribute that roots a theme scope. Matches any element, not just `:root`. */
+export declare const THEME_ATTR = "data-pantoken-theme";
+/** Attribute that pins a subtree to a color scheme. */
+export declare const SCHEME_ATTR = "data-pantoken-scheme";
+/** Attribute that selects a custom brand color. */
+export declare const COLOR_ATTR = "data-pantoken-color";
+/** Attribute marking a scope that ancestor resolution must not cross. */
+export declare const BOUNDARY_ATTR = "data-pantoken-boundary";
+/** Attribute carrying the owning instance id, so sibling instances can tell scopes apart. */
+export declare const INSTANCE_ATTR = "data-pantoken-instance";
+/** Every attribute that participates in scope resolution. */
+export declare const SCOPE_ATTRS: readonly ["data-pantoken-theme", "data-pantoken-scheme", "data-pantoken-color", "data-pantoken-boundary", "data-pantoken-instance"];
+/** Cascade layers the scoped sheets emit into, in ascending precedence order. */
+export declare const SCOPE_LAYERS: readonly ["pantoken.base", "pantoken.theme", "pantoken.scheme", "pantoken.color"];
+/** A color scheme a scope can be pinned to. */
+export type Scheme = "light" | "dark";
+/** Narrow an arbitrary value to a {@link Scheme}. */
+export declare function isScheme(value: unknown): value is Scheme;
+/**
+ * Class equivalents of the scope attributes, for hosts that sanitize `data-*` but allow `class` —
+ * Canvas RCE content being the one that forced them. They follow the repo's global-modifier naming
+ * (`.--name`), and the emitter pairs each attribute selector with its class twin.
+ */
+export declare const themeClass: (theme: string) => string;
+/** Class equivalent of `data-pantoken-scheme`. */
+export declare const schemeClass: (scheme: Scheme) => string;
+/** Class equivalent of `data-pantoken-color`. */
+export declare const colorClass: (color: string) => string;
+/** Class equivalent of `data-pantoken-boundary`. */
+export declare const BOUNDARY_CLASS = "--pantoken-boundary";
+/** The selector matching any element that roots `theme`. */
+export declare function themeScopeSelector(theme: string): string;
+/** The selector matching any element pinned to `scheme`. */
+export declare function schemeScopeSelector(scheme: Scheme): string;
+/** The selector matching any element using custom brand color `color`. */
+export declare function colorScopeSelector(color: string): string;
+/** Both forms of the theme scope selector, as a selector list. */
+export declare function themeScopeSelectors(theme: string): string;
+/** Both forms of the scheme scope selector, as a selector list. */
+export declare function schemeScopeSelectors(scheme: Scheme): string;
+/** Both forms of the color scope selector, as a selector list. */
+export declare function colorScopeSelectors(color: string): string;
+//#endregion

package/dist/scope.mjs

@@ -0,0 +1,79 @@
+//#region src/scope.ts
+/**
+* The scope attribute contract — the single source of truth shared by the CSS emitter
+* (`@pantoken/css`, which selects on these) and the runtime (`@pantoken/scope`, which writes them).
+*
+* Its own module with zero imports, exposed at the `@pantoken/utils/scope` entry, so the browser
+* runtime can take the names without pulling `arkregex` or the resolver in behind the barrel.
+*
+* @module
+*/
+/** Attribute that roots a theme scope. Matches any element, not just `:root`. */
+const THEME_ATTR = "data-pantoken-theme";
+/** Attribute that pins a subtree to a color scheme. */
+const SCHEME_ATTR = "data-pantoken-scheme";
+/** Attribute that selects a custom brand color. */
+const COLOR_ATTR = "data-pantoken-color";
+/** Attribute marking a scope that ancestor resolution must not cross. */
+const BOUNDARY_ATTR = "data-pantoken-boundary";
+/** Attribute carrying the owning instance id, so sibling instances can tell scopes apart. */
+const INSTANCE_ATTR = "data-pantoken-instance";
+/** Every attribute that participates in scope resolution. */
+const SCOPE_ATTRS = [
+	THEME_ATTR,
+	SCHEME_ATTR,
+	COLOR_ATTR,
+	BOUNDARY_ATTR,
+	INSTANCE_ATTR
+];
+/** Cascade layers the scoped sheets emit into, in ascending precedence order. */
+const SCOPE_LAYERS = [
+	"pantoken.base",
+	"pantoken.theme",
+	"pantoken.scheme",
+	"pantoken.color"
+];
+const SCHEMES = /* @__PURE__ */ new Set(["light", "dark"]);
+/** Narrow an arbitrary value to a {@link Scheme}. */
+function isScheme(value) {
+	return typeof value === "string" && SCHEMES.has(value);
+}
+/**
+* Class equivalents of the scope attributes, for hosts that sanitize `data-*` but allow `class` —
+* Canvas RCE content being the one that forced them. They follow the repo's global-modifier naming
+* (`.--name`), and the emitter pairs each attribute selector with its class twin.
+*/
+const themeClass = (theme) => `--pantoken-theme-${theme}`;
+/** Class equivalent of `data-pantoken-scheme`. */
+const schemeClass = (scheme) => `--pantoken-scheme-${scheme}`;
+/** Class equivalent of `data-pantoken-color`. */
+const colorClass = (color) => `--pantoken-color-${color}`;
+/** Class equivalent of `data-pantoken-boundary`. */
+const BOUNDARY_CLASS = "--pantoken-boundary";
+/** The selector matching any element that roots `theme`. */
+function themeScopeSelector(theme) {
+	return `[${THEME_ATTR}="${theme}"]`;
+}
+/** The selector matching any element pinned to `scheme`. */
+function schemeScopeSelector(scheme) {
+	return `[${SCHEME_ATTR}="${scheme}"]`;
+}
+/** The selector matching any element using custom brand color `color`. */
+function colorScopeSelector(color) {
+	return `[${COLOR_ATTR}="${color}"]`;
+}
+const classSelector = (cls) => `:where(*).${cls}.${cls}.${cls}`;
+/** Both forms of the theme scope selector, as a selector list. */
+function themeScopeSelectors(theme) {
+	return `${themeScopeSelector(theme)}, ${classSelector(themeClass(theme))}`;
+}
+/** Both forms of the scheme scope selector, as a selector list. */
+function schemeScopeSelectors(scheme) {
+	return `${schemeScopeSelector(scheme)}, ${classSelector(schemeClass(scheme))}`;
+}
+/** Both forms of the color scope selector, as a selector list. */
+function colorScopeSelectors(color) {
+	return `${colorScopeSelector(color)}, ${classSelector(colorClass(color))}`;
+}
+//#endregion
+export { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, SCOPE_LAYERS, THEME_ATTR, colorClass, colorScopeSelector, colorScopeSelectors, isScheme, schemeClass, schemeScopeSelector, schemeScopeSelectors, themeClass, themeScopeSelector, themeScopeSelectors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantoken/utils",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Shared pantoken helpers: token reference resolver, typed regexes (arkregex), name-case, and hex-colour parsing.",
   "homepage": "https://pantoken.app",
   "bugs": "https://github.com/thedannywahl/pantoken/issues",
@@ -18,6 +18,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./token-syntax": "./dist/token-syntax.mjs",
+    "./scope": "./dist/scope.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -25,16 +26,16 @@
     "provenance": true
   },
   "dependencies": {
-    "@pantoken/model": "0.4.0",
+    "@pantoken/model": "0.5.0",
     "arkregex": "^0.0.8",
     "css-tree": "^3.2.1"
   },
   "devDependencies": {
     "@types/css-tree": "^3.2.0",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.3",
     "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
-    "vite-plus": "0.3.2"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0-rc.0",
+    "vite-plus": "1.0.0-rc.0"
   },
   "engines": {
     "node": ">=22.18.0"