@pantoken/css 0.3.11 → 0.4.0

package/dist/src-h17qjVzD.mjs

@@ -0,0 +1,417 @@
+import { checkPlugins, definePlugin } from "@pantoken/plugin-kit";
+import { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, SCHEME_ATTR, SCOPE_LAYERS, THEME_ATTR, colorClass, elevationDeclarations, focusOutlineDeclarations, schemeClass, schemeScopeSelector, schemeScopeSelectors, themeClass, themeScopeSelector, themeScopeSelectors } from "@pantoken/utils";
+import { byTheme } from "@pantoken/tokens";
+//#region src/foundation.ts
+/**
+* The elevation (`--instui-elevation-*`) and focus-outline (`--instui-focus-outline-*`) composite
+* custom properties shared by the ready-made token sheets and docs-only themed token sheet.
+*/
+const foundationPlugin = definePlugin({
+	name: "pantoken-foundation",
+	css: () => ({
+		marker: "pantoken foundation — elevation + focus-outline custom properties",
+		declarations: [...elevationDeclarations(), ...focusOutlineDeclarations()]
+	})
+});
+//#endregion
+//#region src/theme-variants.ts
+const ICON_TOKEN_PREFIX = "--instui-icon-";
+function withoutIcons(tokens) {
+	return tokens.filter((t) => !t.name.startsWith(ICON_TOKEN_PREFIX));
+}
+/** Split the top-level comma of a `light-dark(light, dark)` value; `null` when it isn't one. */
+function splitLightDark(value) {
+	const trimmed = value.trim();
+	if (!trimmed.startsWith("light-dark(") || !trimmed.endsWith(")")) return null;
+	const inner = trimmed.slice(11, -1);
+	let depth = 0;
+	for (let i = 0; i < inner.length; i += 1) {
+		const char = inner[i];
+		if (char === "(") depth += 1;
+		else if (char === ")") depth = Math.max(0, depth - 1);
+		else if (char === "," && depth === 0) return [inner.slice(0, i).trim(), inner.slice(i + 1).trim()];
+	}
+	return null;
+}
+/** The light branch of a `light-dark()` value, or `null` when the value isn't one. */
+function lightBranch(value) {
+	return splitLightDark(value)?.[0] ?? null;
+}
+/** The dark branch of a `light-dark()` value, or `null` when the value isn't one. */
+function darkBranch(value) {
+	return splitLightDark(value)?.[1] ?? null;
+}
+function collapseScheme(tokens, scheme) {
+	const pick = scheme === "light" ? lightBranch : darkBranch;
+	return tokens.map((token) => {
+		const branch = pick(token.value);
+		if (!branch) return token;
+		return {
+			...token,
+			value: branch,
+			themed: false
+		};
+	});
+}
+/**
+* The tokens whose value actually changes when a theme is pinned to `scheme` — i.e. the ones written
+* with `light-dark()`. This is the minimal forcing block for `[data-pantoken-scheme]`.
+*/
+function schemeOverrideTokens(theme, scheme) {
+	const source = byTheme(theme);
+	return collapseScheme(source, scheme).filter((token, i) => token.value !== source[i]?.value);
+}
+/** Build a theme token set with optional icon removal and light/dark collapse. */
+function themedTokens(theme, options) {
+	const { includeIcons = true, lightOnly = false, scheme } = options ?? {};
+	const pinned = scheme ?? (lightOnly ? "light" : void 0);
+	const themeTokens = byTheme(theme);
+	const modeTokens = pinned ? collapseScheme(themeTokens, pinned) : themeTokens;
+	return includeIcons ? modeTokens : withoutIcons(modeTokens);
+}
+//#endregion
+//#region src/emit.ts
+function renderSection(scope, { layer, pairs }) {
+	const declarations = [
+		`  ${scope} {`,
+		...pairs.map(([name, val]) => `    ${name}: ${val.trim()};`),
+		"  }"
+	];
+	return layer ? [
+		`@layer ${layer} {`,
+		...declarations,
+		"}"
+	].join("\n") : declarations.join("\n");
+}
+function renderProperty({ name, syntax, value }, inherits) {
+	return [
+		`@property ${name} {`,
+		`  syntax: "${syntax}";`,
+		`  inherits: ${inherits};`,
+		`  initial-value: ${value.trim()};`,
+		`}`
+	].join("\n");
+}
+/**
+* Build a CSS file string: typed `@property` registrations (top-level, theme-agnostic) followed by
+* one or more scoped declaration sections (whose selector the consuming build may rewrite).
+*
+* @example Register one typed property and emit a scoped declaration
+* ```ts
+* import { buildCssFile } from "@pantoken/css";
+*
+* buildCssFile({
+*   comments: ["/* my tokens *\/"],
+*   scope: ":root",
+*   properties: [{ name: "--instui-color-brand", syntax: "<color>", value: "#0374b5" }],
+*   sections: [{ pairs: [["--instui-color-text-base", "var(--instui-color-brand)"]] }],
+* });
+* ```
+*
+* @example Wrap a section in a CSS cascade layer
+* ```ts
+* import { buildCssFile } from "@pantoken/css";
+*
+* buildCssFile({
+*   comments: [],
+*   scope: ":root",
+*   sections: [{ layer: "pantoken", pairs: [["--instui-spacing-space-md", "1rem"]] }],
+* });
+* ```
+*/
+function buildCssFile({ comments, scope, properties = [], sections, inherits = true }) {
+	const blocks = [properties.map((p) => renderProperty(p, inherits)).join("\n\n"), ...sections.filter((s) => s.pairs.length > 0).map((s) => renderSection(scope, s))].filter(Boolean);
+	return [
+		`/* DO NOT EDIT — generated by @pantoken/css */`,
+		"",
+		...comments,
+		"",
+		...blocks,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/to-css.ts
+/**
+* `toCss` — turn the token IR into CSS: concrete tokens become typed `@property` registrations,
+* themed/reference tokens become scoped declarations. Plugins can contribute or post-process CSS.
+*
+* @module
+*/
+/** True when a value cannot be a typed `@property` initial-value (`var()` / `light-dark()`). */
+function isContextual(value) {
+	return /var\(|light-dark\(/.test(value);
+}
+function marked(marker, css) {
+	return marker ? `/* ${marker} */\n${css}` : css;
+}
+/**
+* Emit CSS for a token IR.
+*
+* @param tokens - The IR (e.g. from `@pantoken/tokens`).
+* @param options - {@link ToCssOptions}.
+* @returns The CSS string.
+*
+* @example Build the default stylesheet
+* ```ts
+* import { toCss } from "@pantoken/css";
+* import { tokens } from "@pantoken/tokens";
+*
+* const stylesheet = toCss(tokens); // declarations under :root
+* ```
+*
+* @example Scope declarations to a class and build another theme
+* ```ts
+* import { toCss } from "@pantoken/css";
+* import { byTheme } from "@pantoken/tokens";
+*
+* toCss(byTheme("canvas"), { scope: '[class*="instui"]' });
+* ```
+*
+* @example Post-process with a plugin css hook
+* ```ts
+* import { toCss } from "@pantoken/css";
+* import { tokens } from "@pantoken/tokens";
+*
+* toCss(tokens, {
+*   plugins: [
+*     {
+*       name: "focus",
+*       css: () => ({ append: ":focus-visible { outline: 2px solid var(--instui-focus-color); }" }),
+*     },
+*   ],
+* });
+* ```
+*/
+function toCss(tokens, options = {}) {
+	const { scope = ":root", layer, emit = "all", declareAll = false, plugins = [] } = options;
+	const properties = [];
+	const declarations = [];
+	for (const token of tokens) if (declareAll || isContextual(token.value)) declarations.push([token.name, token.value]);
+	else properties.push({
+		name: token.name,
+		syntax: token.syntax,
+		value: token.value
+	});
+	let css = buildCssFile({
+		comments: ["/* Instructure design tokens + icon set (pantoken) */", "/* Concrete tokens are registered with @property; themed/reference tokens are declarations. */"],
+		scope,
+		properties: emit === "declarations" ? [] : properties,
+		sections: emit === "properties" ? [] : [{
+			layer,
+			pairs: declarations
+		}]
+	});
+	const prepends = [];
+	const appends = [];
+	for (const plugin of checkPlugins(plugins, "css")) {
+		const c = plugin.css?.({
+			tokens,
+			css
+		});
+		if (!c) continue;
+		appendContribution(c, prepends, appends, {
+			scope,
+			emit,
+			declareAll
+		});
+	}
+	return [
+		...prepends,
+		css,
+		...appends
+	].filter(Boolean).join("\n\n");
+}
+function appendContribution(c, prepends, appends, { scope, emit, declareAll }) {
+	if (c.prepend && emit !== "properties") prepends.push(marked(c.marker, c.prepend));
+	const typedProps = [];
+	const declPairs = [...c.declarations ?? []];
+	for (const p of c.properties ?? []) if (declareAll || isContextual(p.value)) declPairs.push([p.name, p.value]);
+	else typedProps.push(p);
+	const extraProps = emit === "declarations" ? "" : typedProps.map((p) => `@property ${p.name} {\n  syntax: "${p.syntax}";\n  inherits: true;\n  initial-value: ${p.value};\n}`).join("\n\n");
+	const emitDecls = emit !== "properties";
+	const block = [
+		extraProps,
+		emitDecls && declPairs.length ? `${scope} {\n${declPairs.map(([n, v]) => `  ${n}: ${v};`).join("\n")}\n}` : "",
+		emitDecls ? c.append : ""
+	].filter(Boolean).join("\n\n");
+	if (block) appends.push(marked(c.marker, block));
+}
+//#endregion
+//#region src/scoped.ts
+/**
+* Multi-scope sheets: token blocks keyed to an attribute on *any* element rather than `:root`, so
+* several themes and color schemes can be active in one document at once.
+*
+* Three things make that work:
+*
+* 1. `@property` registrations are document-global, so they are emitted once by {@link propertiesCss}
+*    and every theme block is declarations only.
+* 2. A scope block declares the *complete* token set, not a diff against the default. A diff block
+*    nested inside another theme's subtree would inherit the enclosing theme's values for every
+*    token it omitted.
+* 3. Theme, scheme, and color blocks live in separate cascade layers so that when all three
+*    attributes sit on the same element the more specific intent wins deterministically.
+*
+* @module
+*/
+/** Cascade layers this module emits into, in ascending precedence order. */
+const LAYERS = SCOPE_LAYERS;
+/** The `@layer` statement that fixes layer precedence. Must come before any layered rule. */
+const layerOrderCss = () => `@layer ${LAYERS.join(", ")};`;
+/**
+* The document-global `@property` registrations, with no declarations. Load this once per document;
+* every theme sheet below is declarations only, so loading a second theme cannot clobber it.
+*/
+function propertiesCss(theme, options = {}) {
+	const { includeIcons = true, plugins = [] } = options;
+	return toCss(themedTokens(theme, { includeIcons }), {
+		emit: "properties",
+		plugins
+	});
+}
+/**
+* One theme's complete token set, scoped to any element carrying `data-pantoken-theme="<theme>"` or
+* the equivalent `.--pantoken-theme-<theme>` class.
+*
+* Every token is emitted as a declaration — including the concrete ones that would normally become
+* `@property` initial-values — because an initial-value is document-global and cannot vary per scope.
+*/
+function scopedThemeCss(theme, options = {}) {
+	const { includeIcons = true, plugins = [] } = options;
+	return toCss(themedTokens(theme, { includeIcons }), {
+		scope: themeScopeSelectors(theme),
+		layer: "pantoken.theme",
+		emit: "declarations",
+		declareAll: true,
+		plugins
+	});
+}
+/**
+* Pin a subtree's color scheme.
+*
+* `color-scheme` is an ordinary inherited property, so one rule keyed to the scope attribute (or its
+* class twin) resolves every `light-dark()` token below it. No token needs flattening: this sheet is
+* a couple of hundred bytes, not the ~87kb an explicit per-token override table would cost.
+*/
+function scopedSchemeCss(scheme) {
+	return [
+		"@layer pantoken.scheme {",
+		`  ${schemeScopeSelectors(scheme)} {`,
+		`    color-scheme: ${scheme};`,
+		"  }",
+		"}"
+	].join("\n");
+}
+/**
+* The light and dark scheme pins, as a standalone sheet. Theme-independent — the scheme only decides
+* which branch of `light-dark()` wins, which the browser does for us.
+*
+* @example
+* ```ts
+* import { schemesCss } from "@pantoken/css";
+*
+* schemesCss();
+* ```
+*/
+function schemesCss() {
+	return [scopedSchemeCss("light"), scopedSchemeCss("dark")].join("\n\n");
+}
+/**
+* The complete multi-scope sheet: layer order, one set of `@property` registrations, a shared base
+* block, a token block per theme, and the light/dark `color-scheme` pins.
+*
+* Tokens are partitioned by whether their value actually varies across `themes`. Invariant tokens go
+* in the shared base block once; varying tokens are repeated in full in *every* theme block. That
+* second half is what makes nesting safe — a theme block that omitted a varying token would inherit
+* the enclosing scope's value for it.
+*
+* @example
+* ```ts
+* import { multiScopeCss } from "@pantoken/css";
+*
+* multiScopeCss({ themes: ["rebrand", "canvas"], defaultTheme: "rebrand" });
+* ```
+*/
+function multiScopeCss(options) {
+	const { themes, defaultTheme, schemes = true, includeIcons = true, plugins = [] } = options;
+	const perTheme = new Map(themes.map((t) => [t, themedTokens(t, { includeIcons })]));
+	const varying = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Map();
+	for (const tokens of perTheme.values()) for (const token of tokens) {
+		const previous = seen.get(token.name);
+		if (previous === void 0) seen.set(token.name, token.value);
+		else if (previous !== token.value) varying.add(token.name);
+	}
+	const baseTokens = (perTheme.get(defaultTheme) ?? []).filter((t) => !varying.has(t.name));
+	const blocks = [
+		layerOrderCss(),
+		propertiesCss(defaultTheme, {
+			includeIcons,
+			plugins
+		}),
+		toCss(baseTokens, {
+			scope: ":root",
+			layer: "pantoken.base",
+			emit: "declarations",
+			plugins
+		})
+	];
+	for (const theme of themes) {
+		const tokens = (perTheme.get(theme) ?? []).filter((t) => varying.has(t.name));
+		blocks.push(toCss(tokens, {
+			scope: themeScopeSelectors(theme),
+			layer: "pantoken.theme",
+			emit: "declarations",
+			declareAll: true
+		}));
+	}
+	if (schemes) blocks.push(schemesCss());
+	return blocks.filter(Boolean).join("\n\n");
+}
+//#endregion
+//#region src/index.ts
+/**
+* `@pantoken/css` — emit Instructure design tokens as `@property`-typed CSS.
+*
+* {@link toCss} turns any token IR into CSS; {@link css} is the ready-made `rebrand` stylesheet and
+* {@link leanCss} is a lean variant that drops the full `--instui-icon-*` set (the ~1,777 icon data-URIs
+* that dominate the sheet) for CDN/embed delivery — ~a sixth the size over the wire. Both carry the
+* elevation + focus-outline foundation (composite custom properties whose pure builders live in
+* `@pantoken/utils`), so a component sheet resolves its shadows and focus ring against the token sheet
+* alone. A DOM side-effect entry lives at `@pantoken/css/inject`; static files at
+* `@pantoken/css/style.css` and `@pantoken/css/style.lean.css`.
+*
+* @module
+* @beta
+*/
+function themedCss(theme, options) {
+	return toCss(themedTokens(theme, options), { plugins: [foundationPlugin] });
+}
+/**
+* The ready-made `rebrand` stylesheet string (typed: concrete tokens as `@property` registrations).
+*
+* @example
+* ```ts
+* import { css } from "@pantoken/css";
+*
+* document.head.insertAdjacentHTML("beforeend", `<style>${css}</style>`);
+* ```
+*/
+const css = themedCss("rebrand");
+/**
+* The lean `rebrand` stylesheet string — the full sheet minus the `--instui-icon-*` glyph tokens (the
+* ~1,777 icon data-URIs that make up most of {@link css}). Roughly a sixth the size over the wire; the
+* recommended foundation for CDN/embed delivery. Components reference only a handful of icons, shipped
+* separately as `@pantoken/components`'s `component-icons.css`; consumers who use `var(--instui-icon-*)`
+* broadly should load the full {@link css} (or the `icons.css` glyph sheet). See
+* `@pantoken/css/style.lean.css`.
+*
+* @example
+* ```ts
+* import { leanCss } from "@pantoken/css";
+* ```
+*/
+const leanCss = toCss(themedTokens("rebrand", { includeIcons: false }), { plugins: [foundationPlugin] });
+//#endregion
+export { buildCssFile as C, themedTokens as D, schemeOverrideTokens as E, toCss as S, lightBranch as T, scopedSchemeCss as _, COLOR_ATTR as a, themeScopeSelector as b, THEME_ATTR as c, multiScopeCss as d, propertiesCss as f, schemesCss as g, schemeScopeSelectors as h, BOUNDARY_CLASS as i, colorClass as l, schemeScopeSelector as m, leanCss as n, LAYERS as o, schemeClass as p, BOUNDARY_ATTR as r, SCHEME_ATTR as s, css as t, layerOrderCss as u, scopedThemeCss as v, darkBranch as w, themeScopeSelectors as x, themeClass as y };