@pantoken/email 0.1.19 → 0.1.20

package/README.md

@@ -1,8 +1,9 @@
 # @pantoken/email
 
-Instructure design tokens for HTML email. Email clients don't support CSS custom properties and
-often strip `<style>`, so tokens are fully resolved to concrete values for inline styling — colours
-as hex, dimensions with `px`. Icons are excluded.
+Instructure design tokens and email-safe HTML generation. Email clients don't support CSS custom
+properties and often strip `<style>`, so tokens are resolved to concrete inline values. Generated
+component CSS uses a conservative, configurable email policy that omits interactive states and
+unsupported components by default.
 
 ## Install
 
@@ -24,10 +25,42 @@ const t = emailTokens("light");
 The maps are keyed by camelCased token name (the `--instui-` prefix dropped): `--instui-color-
 background-brand` becomes `colorBackgroundBrand`.
 
-## Output
+Generate email-compatible HTML:
 
-Plain `Record<string, string>` maps of concrete token values, ready to interpolate into inline
-`style` attributes. No files are written and there's no CLI target — you import the values.
+```ts
+import { inlineEmailHtml } from "@pantoken/email";
+
+const html = inlineEmailHtml('<button class="instui-button">Save</button>', {
+  theme: "canvas",
+  client: "gmail",
+});
+```
+
+The `client` profile can be `generic`, `outlook`, `gmail`, or `webkit`. Profiles control which
+fallback rules are retained; they do not reconstruct table or VML layouts. Add or remove component
+classes at the email boundary with `allowComponents` and `denyComponents`. Caller-supplied `extraCss`
+is passed through separately.
+
+The compatibility subpath remains available:
+
+```ts
+import { inlineEmailHtml } from "@pantoken/email/inline";
+```
+
+## CLI
+
+```sh
+pantoken generate email -i page.html -o page.email.html --client gmail
+```
+
+Use `--css <file>` to add caller-supplied CSS and `--theme <rebrand|canvas|canvasHighContrast>`
+to select the token theme. The output is one HTML document; client profiles are filtering
+capabilities, not a complete guarantee of rendering parity.
+
+## Token maps
+
+`emailTokens(mode?)`, `light`, and `dark` remain available when callers need to interpolate a
+single token directly into an inline `style` attribute.
 
 ## API
 
@@ -35,6 +68,11 @@ Plain `Record<string, string>` maps of concrete token values, ready to interpola
   or `"dark"`).
 - **`light`** — the concrete light-mode token map.
 - **`dark`** — the concrete dark-mode token map.
+- **`inlineEmailHtml(html, options?): string`** — generate email-compatible HTML with resolved
+  pantoken values and filtered component CSS.
+- **`InlineEmailHtmlOptions`** — theme, mode, client profile, component policy, custom colors, and
+  caller CSS options.
+- **`EmailClient`** — `generic`, `outlook`, `gmail`, or `webkit`.
 
 ## Related
 

package/dist/email-html-CoHCHokB.d.mts

@@ -0,0 +1,43 @@
+import { PantokenColorNamespace } from "@pantoken/plugin-custom-theme-colors";
+import { Theme } from "@pantoken/model";
+//#region src/email-css.d.ts
+/** Supported email client capability profiles. */
+type EmailClient = "generic" | "outlook" | "gmail" | "webkit";
+/** Options for filtering component CSS for email output. */
+interface EmailCssOptions {
+  /** Client capability profile. Defaults to `generic`. */
+  client?: EmailClient;
+  /** Component names to allow in addition to the default email-safe set. */
+  allowComponents?: readonly string[];
+  /** Component names to remove even when they are in the default or custom allowlist. */
+  denyComponents?: readonly string[];
+}
+//#endregion
+//#region src/email-html.d.ts
+/** Options for generating email-compatible HTML with pantoken styles. */
+interface InlineEmailHtmlOptions {
+  /** Token theme to use. Defaults to `rebrand`. */
+  theme?: Theme;
+  /** Color scheme to resolve. Defaults to `light`. */
+  mode?: "light" | "dark";
+  /** Component class prefix. Defaults to `instui`. */
+  prefix?: string | null;
+  /** Add generated rules for this custom brand color. */
+  customColor?: string;
+  /** Apply one of the plugin's shipped or custom color scales. */
+  color?: PantokenColorNamespace;
+  /** Retain pseudo-class and media-query rules in a style element. Defaults to `false`. */
+  preserveFallbacks?: boolean;
+  /** Email client capability profile. Defaults to `generic`. */
+  client?: EmailClient;
+  /** Component names to allow in addition to the default email-safe set. */
+  allowComponents?: readonly string[];
+  /** Component names to remove from the email output. */
+  denyComponents?: readonly string[];
+  /** Additional caller-supplied CSS. */
+  extraCss?: string;
+}
+/** Inline resolved pantoken tokens and component CSS into HTML email markup. */
+declare function inlineEmailHtml(html: string, options?: InlineEmailHtmlOptions): string;
+//#endregion
+export { EmailCssOptions as i, inlineEmailHtml as n, EmailClient as r, InlineEmailHtmlOptions as t };

package/dist/email-html-Dz8s-HvN.mjs

@@ -0,0 +1,194 @@
+import { byTheme } from "@pantoken/tokens";
+import { resolveTokens } from "@pantoken/utils";
+import { componentsCss } from "@pantoken/components";
+import { load } from "cheerio";
+import { COLOR_KEYS, CUSTOM_COLOR_KEY, customThemeColorsCss } from "@pantoken/plugin-custom-theme-colors";
+import { inlineHtml } from "@pantoken/inline-styles/html";
+import postcss from "postcss";
+//#region src/email-css.ts
+const DEFAULT_COMPONENTS = /* @__PURE__ */ new Set([
+	"alert",
+	"avatar",
+	"badge",
+	"billboard",
+	"breadcrumb",
+	"breadcrumb-link",
+	"button",
+	"byline",
+	"form-field",
+	"form-field-group",
+	"form-field-messages",
+	"heading",
+	"img",
+	"link",
+	"list",
+	"list-item",
+	"metric",
+	"pill",
+	"table",
+	"table-body",
+	"table-cell",
+	"table-col-header",
+	"table-head",
+	"table-row",
+	"table-row-header",
+	"tag",
+	"text"
+]);
+const STATE_SELECTOR = /:(?:active|checked|disabled|focus|focus-visible|hover|invalid|visited)(?:\b|\()/iu;
+const COMPONENT_CLASS = /(?:^|[\s>+~.(,])\.([A-Za-z0-9_-]+)/gu;
+const clientRules = {
+	generic: { preserveMedia: false },
+	outlook: { preserveMedia: false },
+	gmail: { preserveMedia: false },
+	webkit: { preserveMedia: true }
+};
+function componentNames(selector) {
+	return [...selector.matchAll(COMPONENT_CLASS)].map((match) => match[1]).filter((name) => name !== void 0).filter((name) => name.startsWith("instui-")).map((name) => name.slice(7));
+}
+function splitSelectors(selectors) {
+	const result = [];
+	let start = 0;
+	let parentheses = 0;
+	let brackets = 0;
+	let quote = "";
+	for (let index = 0; index < selectors.length; index += 1) {
+		const character = selectors[index];
+		if (quote) {
+			if (character === "\\") index += 1;
+			else if (character === quote) quote = "";
+			continue;
+		}
+		if (character === "\"" || character === "'") quote = character;
+		else if (character === "(") parentheses += 1;
+		else if (character === ")") parentheses -= 1;
+		else if (character === "[") brackets += 1;
+		else if (character === "]") brackets -= 1;
+		else if (character === "," && parentheses === 0 && brackets === 0) {
+			result.push(selectors.slice(start, index).trim());
+			start = index + 1;
+		}
+	}
+	result.push(selectors.slice(start).trim());
+	return result.filter(Boolean);
+}
+function selectorAllowed(selector, allowed) {
+	if (STATE_SELECTOR.test(selector)) return false;
+	const names = componentNames(selector);
+	return names.length === 0 || names.some((name) => allowed.has(name));
+}
+function filterContainer(container, allowed, preserveMedia) {
+	for (const node of container.nodes?.slice() ?? []) {
+		if (node.type === "rule") {
+			const rule = node;
+			const selectors = splitSelectors(rule.selector).filter((selector) => selectorAllowed(selector, allowed));
+			if (selectors.length === 0) node.remove();
+			else {
+				rule.selector = selectors.join(", ");
+				filterContainer(rule, allowed, preserveMedia);
+			}
+			continue;
+		}
+		if (node.type === "atrule") {
+			const atRule = node;
+			const name = atRule.name.toLowerCase();
+			if (name === "media" && !preserveMedia) {
+				node.remove();
+				continue;
+			}
+			if ([
+				"supports",
+				"container",
+				"layer",
+				"keyframes",
+				"-webkit-keyframes"
+			].includes(name)) {
+				node.remove();
+				continue;
+			}
+			if (atRule.nodes) filterContainer(atRule, allowed, preserveMedia);
+		}
+	}
+}
+/** Filter generated component CSS to the selected email client capabilities. */
+function filterEmailCss(css, options = {}) {
+	const { client = "generic", allowComponents = [], denyComponents = [] } = options;
+	const profile = clientRules[client];
+	if (!profile) throw new Error(`Unknown email client profile: ${client}`);
+	const allowed = new Set(DEFAULT_COMPONENTS);
+	for (const component of allowComponents) allowed.add(component.replace(/^instui-/, ""));
+	for (const component of denyComponents) allowed.delete(component.replace(/^instui-/, ""));
+	const root = postcss.parse(css);
+	filterContainer(root, allowed, profile.preserveMedia);
+	return root.toString();
+}
+//#endregion
+//#region src/email-html.ts
+function modeValue(value, mode) {
+	const start = value.indexOf("light-dark(");
+	if (start < 0) return value;
+	let depth = 1;
+	let comma = -1;
+	let end = -1;
+	for (let index = start + 11; index < value.length; index += 1) if (value[index] === "(") depth += 1;
+	else if (value[index] === ")") {
+		depth -= 1;
+		if (depth === 0) {
+			end = index;
+			break;
+		}
+	} else if (value[index] === "," && depth === 1 && comma < 0) comma = index;
+	if (comma < 0 || end < 0) return value;
+	const selected = mode === "light" ? value.slice(start + 11, comma) : value.slice(comma + 1, end);
+	return `${value.slice(0, start)}${modeValue(selected.trim(), mode)}${value.slice(end + 1)}`;
+}
+function resolvedThemeTokens(theme, mode) {
+	const tokens = byTheme(theme).map((token) => ({
+		...token,
+		value: modeValue(token.value, mode),
+		flatValue: token.flatValue ? modeValue(token.flatValue, mode) : void 0
+	}));
+	return {
+		tokens,
+		resolved: resolveTokens(tokens)
+	};
+}
+function tokenStylesheet(tokens, resolved) {
+	return `:root {\n${tokens.filter((token) => token.meta?.kind !== "icon").map((token) => `  ${token.name}: ${resolved.get(token.name) ?? token.value};`).join("\n")}\n}`;
+}
+function markColorScope(html, color) {
+	const $ = load(html, {}, false);
+	const documentRoot = $("html").first();
+	(documentRoot.length ? documentRoot : $.root().children().filter((_, node) => node.type === "tag")).attr("data-pantoken-color", color);
+	return $.html();
+}
+/** Inline resolved pantoken tokens and component CSS into HTML email markup. */
+function inlineEmailHtml(html, options = {}) {
+	const { theme = "rebrand", mode = "light", prefix = "instui", customColor, color, preserveFallbacks = false, client = "generic", allowComponents = [], denyComponents = [], extraCss = "" } = options;
+	const activeColor = color ?? (customColor ? CUSTOM_COLOR_KEY : void 0);
+	if (activeColor && activeColor !== CUSTOM_COLOR_KEY && !COLOR_KEYS.includes(activeColor)) throw new Error(`Unknown pantoken color scale: ${activeColor}`);
+	if (activeColor === CUSTOM_COLOR_KEY && !customColor) throw new Error("The \"custom\" color scale requires a customColor hex value.");
+	const { tokens, resolved } = resolvedThemeTokens(theme, mode);
+	const css = [
+		tokenStylesheet(tokens, resolved),
+		customThemeColorsCss(resolved, {
+			custom: customColor,
+			selector: ""
+		}),
+		filterEmailCss(componentsCss({
+			theme,
+			prefix
+		}), {
+			client,
+			allowComponents,
+			denyComponents
+		}),
+		extraCss
+	].join("\n");
+	return inlineHtml(activeColor ? markColorScope(html, activeColor) : html, css, {
+		resolveCSSVariables: true,
+		preserveFallbacks
+	});
+}
+//#endregion
+export { inlineEmailHtml as t };

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { i as EmailCssOptions, n as inlineEmailHtml, r as EmailClient, t as InlineEmailHtmlOptions } from "./email-html-CoHCHokB.mjs";
 //#region src/index.d.ts
 type Mode = "light" | "dark";
 /**
@@ -41,4 +42,5 @@ export declare const dark: Record<string, string>;
  * ```
  */
 export declare function emailTokens(mode?: Mode): Record<string, string>;
-//#endregion
+//#endregion
+export { type EmailClient, type EmailCssOptions, type InlineEmailHtmlOptions, inlineEmailHtml };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { t as inlineEmailHtml } from "./email-html-Dz8s-HvN.mjs";
 import { tokens } from "@pantoken/tokens";
 import { camelCase, resolveTokens } from "@pantoken/utils";
 //#region src/index.ts
@@ -64,4 +65,4 @@ function emailTokens(mode = "light") {
 	return mode === "dark" ? dark : light;
 }
 //#endregion
-export { dark, emailTokens, light };
+export { dark, emailTokens, inlineEmailHtml, light };

package/dist/inline.d.mts

@@ -0,0 +1,2 @@
+import { i as EmailCssOptions, n as inlineEmailHtml, r as EmailClient, t as InlineEmailHtmlOptions } from "./email-html-CoHCHokB.mjs";
+export { type EmailClient, type EmailCssOptions, type InlineEmailHtmlOptions, inlineEmailHtml };

package/dist/inline.mjs

@@ -0,0 +1,2 @@
+import { t as inlineEmailHtml } from "./email-html-Dz8s-HvN.mjs";
+export { inlineEmailHtml };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pantoken/email",
-  "version": "0.1.19",
-  "description": "Instructure design tokens for HTML email: concrete, inline-friendly token values (no CSS vars).",
+  "version": "0.1.20",
+  "description": "Instructure design tokens and email-safe HTML generation with concrete inline values.",
   "homepage": "https://pantoken.app",
   "bugs": "https://github.com/thedannywahl/pantoken/issues",
   "license": "MIT",
@@ -17,6 +17,7 @@
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.mjs",
+    "./inline": "./dist/inline.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -24,9 +25,14 @@
     "provenance": true
   },
   "dependencies": {
+    "@pantoken/components": "2.0.0",
+    "@pantoken/inline-styles": "0.1.1",
     "@pantoken/model": "0.5.0",
+    "@pantoken/plugin-custom-theme-colors": "0.3.1",
     "@pantoken/tokens": "0.7.0",
-    "@pantoken/utils": "1.2.0"
+    "@pantoken/utils": "1.2.0",
+    "cheerio": "^1.2.0",
+    "postcss": "^8.5.28"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",