@pantoken/css 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @pantoken/css
+
+Emit Instructure design tokens as `@property`-typed CSS, with `light-dark()` theming and icon
+data-URIs, from the pantoken IR. Concrete tokens register as typed `@property` rules; themed and
+reference tokens stay as scoped declarations.
+
+## Install
+
+```sh
+npm i @pantoken/css
+```
+
+Also available as `pantoken/css`.
+
+## Usage
+
+```ts
+import { toCss, css } from "@pantoken/css";
+import { byTheme } from "@pantoken/tokens";
+
+css; // the ready-made rebrand stylesheet string
+toCss(byTheme("canvas"), { scope: ":root" }); // build CSS for another theme
+```
+
+Side-effect injection (browser):
+
+```ts
+import "@pantoken/css/inject"; // appends <style data-pantoken> to document.head
+```
+
+Or a plain stylesheet: `@pantoken/css/style.css`.
+
+A plugin's `css` hook can contribute or post-process CSS — for example, inject a focus ring that
+isn't in the source tokens:
+
+```ts
+toCss(tokens, {
+  plugins: [
+    {
+      name: "focus",
+      css: () => ({ append: ":focus-visible { outline: 2px solid var(--instui-focus-color); }" }),
+    },
+  ],
+});
+```
+
+## API
+
+- **`css: string`** — the ready-made `rebrand` stylesheet (also the default export).
+- **`toCss(tokens, options?): string`** — build CSS for any token IR. `options.scope` sets the
+  declaration selector (default `":root"`); `options.plugins` runs `css` hooks after the base build.
+- **`ToCssOptions`** — options for `toCss`.
+- **`buildCssFile(args): string`** — the low-level builder: typed `@property` registrations followed
+  by scoped declaration sections.
+- **`CssSection`** — one scoped block of custom properties, optionally wrapped in an `@layer`.
+- **`inject(doc?): HTMLStyleElement | undefined`** (from `@pantoken/css/inject`) — inject the
+  stylesheet into `document.head` once; no-ops off the DOM.
+- **`./inject`** — a DOM side-effect entry that injects the stylesheet on import.
+- **`./style.css`** — the generated plain stylesheet, for a direct `<link>` or `@import`.
+
+## Related
+
+- Pairs with `@pantoken/tokens` for the underlying token IR.
+- `@pantoken/scss`, `@pantoken/less`, and `@pantoken/stylus` emit the same tokens as preprocessor
+  variables.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,112 @@
+import { PantokenPlugin, PropertyRule, Token } from "@pantoken/model";
+
+//#region src/to-css.d.ts
+/** Options for {@link toCss}. */
+interface ToCssOptions {
+  /** The selector scoped declarations are emitted under (default `":root"`). */
+  scope?: string;
+  /** Plugins whose `css` hooks run after the base CSS is built (default: none). */
+  plugins?: readonly PantokenPlugin[];
+}
+/**
+ * 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); }" }),
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function toCss(tokens: readonly Token[], options?: ToCssOptions): string;
+//#endregion
+//#region src/emit.d.ts
+/** One scoped block of custom properties, optionally wrapped in an `@layer`. */
+interface CssSection {
+  /** Plain layer name (e.g. `"pantoken"`), no `@` prefix. Omit to skip the wrapper. */
+  layer?: string;
+  pairs: [string, string][];
+}
+/**
+ * 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"]] }],
+ * });
+ * ```
+ */
+declare function buildCssFile({
+  comments,
+  scope,
+  properties,
+  sections,
+  inherits
+}: {
+  comments: string[];
+  scope: string;
+  properties?: PropertyRule[];
+  sections: CssSection[];
+  inherits?: boolean;
+}): string;
+//#endregion
+//#region src/index.d.ts
+/**
+ * The ready-made `rebrand` stylesheet string.
+ *
+ * @example
+ * ```ts
+ * import { css } from "@pantoken/css";
+ *
+ * document.head.insertAdjacentHTML("beforeend", `<style>${css}</style>`);
+ * ```
+ */
+declare const css: string;
+//#endregion
+export { type CssSection, type ToCssOptions, buildCssFile, css, css as default, toCss };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as toCss, r as buildCssFile, t as css } from "./src-DnTeei9H.mjs";
+export { buildCssFile, css, css as default, toCss };

package/dist/inject.d.mts

@@ -0,0 +1,22 @@
+//#region src/inject.d.ts
+/**
+ * Inject the pantoken stylesheet into `document.head` once. Returns the created element, if any.
+ *
+ * @example Inject on the default document
+ * ```ts
+ * import { inject } from "@pantoken/css/inject";
+ *
+ * const style = inject(); // <style data-pantoken> appended to document.head
+ * ```
+ *
+ * @example Inject into a specific document (e.g. an iframe)
+ * ```ts
+ * import { inject } from "@pantoken/css/inject";
+ *
+ * const frame = document.querySelector("iframe")!;
+ * inject(frame.contentDocument ?? undefined);
+ * ```
+ */
+declare function inject(doc?: Document | undefined): HTMLStyleElement | undefined;
+//#endregion
+export { inject };

package/dist/inject.mjs

@@ -0,0 +1,39 @@
+import { t as css } from "./src-DnTeei9H.mjs";
+//#region src/inject.ts
+/**
+* `@pantoken/css/inject` — a DOM side-effect entry. Importing it injects the pantoken stylesheet
+* into `document.head`. Safe to import in non-DOM environments (it no-ops).
+*
+* @module
+*/
+/**
+* Inject the pantoken stylesheet into `document.head` once. Returns the created element, if any.
+*
+* @example Inject on the default document
+* ```ts
+* import { inject } from "@pantoken/css/inject";
+*
+* const style = inject(); // <style data-pantoken> appended to document.head
+* ```
+*
+* @example Inject into a specific document (e.g. an iframe)
+* ```ts
+* import { inject } from "@pantoken/css/inject";
+*
+* const frame = document.querySelector("iframe")!;
+* inject(frame.contentDocument ?? undefined);
+* ```
+*/
+function inject(doc = globalThis.document) {
+	if (!doc) return void 0;
+	const existing = doc.querySelector("style[data-pantoken]");
+	if (existing) return existing;
+	const style = doc.createElement("style");
+	style.setAttribute("data-pantoken", "css");
+	style.textContent = css;
+	doc.head.append(style);
+	return style;
+}
+inject();
+//#endregion
+export { inject };

package/dist/src-DnTeei9H.mjs

@@ -0,0 +1,181 @@
+import { tokens } from "@pantoken/tokens";
+import { checkPlugins } from "@pantoken/plugin-kit";
+//#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", plugins = [] } = options;
+	const properties = [];
+	const declarations = [];
+	for (const token of tokens) if (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,
+		sections: [{ 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);
+	}
+	return [
+		...prepends,
+		css,
+		...appends
+	].filter(Boolean).join("\n\n");
+}
+function appendContribution(c, prepends, appends) {
+	if (c.prepend) prepends.push(marked(c.marker, c.prepend));
+	const block = [
+		(c.properties ?? []).map((p) => `@property ${p.name} {\n  syntax: "${p.syntax}";\n  inherits: true;\n  initial-value: ${p.value};\n}`).join("\n\n"),
+		c.declarations?.length ? `:root {\n${c.declarations.map(([n, v]) => `  ${n}: ${v};`).join("\n")}\n}` : "",
+		c.append
+	].filter(Boolean).join("\n\n");
+	if (block) appends.push(marked(c.marker, block));
+}
+//#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.
+* A DOM side-effect entry lives at `@pantoken/css/inject`, and a static file at
+* `@pantoken/css/style.css`.
+*
+* @module
+* @beta
+*/
+/**
+* The ready-made `rebrand` stylesheet string.
+*
+* @example
+* ```ts
+* import { css } from "@pantoken/css";
+*
+* document.head.insertAdjacentHTML("beforeend", `<style>${css}</style>`);
+* ```
+*/
+const css = toCss(tokens);
+//#endregion
+export { toCss as n, buildCssFile as r, css as t };