@getvitops/generator 0.6.0 → 0.8.0

package/dist/index.mjs

@@ -62,7 +62,8 @@ const Pattern = desc(z.object({
 	group: desc(z.optional(z.string()), "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`."),
 	overrides: z.optional(desc(CssDecls, "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values.")),
 	element: desc(z.optional(z.string()), "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class)."),
-	class: desc(z.optional(z.string()), "Class name to emit (defaults to the pattern's key)."),
+	class: desc(z.optional(z.string()), "Class name to emit (defaults to the pattern's key when no `element` is set). Combined with `element`, the pattern emits one zero-specificity `:where(<element>, .<class>)` rule so the class works on any tag and any explicit class overrides it."),
+	fill: desc(z.optional(z.boolean()), "Whether this pattern is colour-filled (states/roles drive `background-color` + `on-solid` text) or text-coloured (they drive `color`). Defaults to true when `base` declares a background."),
 	default_role: desc(z.optional(z.string()), "Semantic colour role applied to the bare/default variant."),
 	base: z.optional(desc(CssDecls, "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable.")),
 	states: desc(z.optional(z.record(z.string(), z.record(z.string(), z.unknown()))), "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify fills/text by n emphasis stops), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`."),
@@ -121,13 +122,20 @@ const jsonSchema = {
 	$id: SCHEMA_URL,
 	...z.toJSONSchema(DesignSystemSchema, { target: "draft-2020-12" })
 };
-/** Validate an unknown value against the design-system schema. */
+/**
+* Validate an unknown value against the design-system schema.
+*
+* `warnings` are configurations that parse and generate, but produce output that
+* won't behave as authored — currently only the token-namespace collisions the
+* flat `--<prop>-<name>` grammar makes possible.
+*/
 function validate(input) {
 	const result = z.safeParse(DesignSystemSchema, input);
 	if (!result.success) return {
 		ok: false,
 		data: void 0,
-		errors: result.error.issues
+		errors: result.error.issues,
+		warnings: []
 	};
 	const { palette, roles } = result.data.colors;
 	for (const [role, hue] of Object.entries(roles)) if (palette[hue] == null) return {
@@ -141,12 +149,18 @@ function validate(input) {
 				role
 			],
 			message: `role "${role}" references unknown palette hue "${hue}"`
-		}]
+		}],
+		warnings: []
 	};
+	const warnings = [];
+	const radii = Object.keys(result.data.patterns?.radii ?? {});
+	const items = new Set(Object.keys(result.data.patterns?.items ?? {}));
+	for (const name of radii) if (items.has(name)) warnings.push(`patterns.radii.${name} collides with the "${name}" pattern on --br-${name}; the pattern's override hook wins — rename the radius`);
 	return {
 		ok: true,
 		data: result.data,
-		errors: []
+		errors: [],
+		warnings
 	};
 }
 
@@ -159,8 +173,9 @@ function validate(input) {
 */
 /**
 * Pattern base geometry props → per-pattern override-hook shorthand. Each hook
-* wraps the authored value (`padding: var(--p-button, 0.6em 1.2em)`) so a
-* consumer restyles one pattern by setting one variable.
+* wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
+* consumer restyles one pattern by setting one variable. The hook is named after
+* the pattern's key, not its class.
 */
 const BASE_HOOK = {
 	padding: "p",
@@ -1012,9 +1027,10 @@ pattern CSS is assembled — token cascade, \`--p-<pattern>\`-style override hoo
 shortcuts — is explained in [/concepts/patterns.md](../concepts/patterns.md).)
 
 - Patterns: ${code(patterns)}.
-- Roles (for coloured patterns like \`badge\`, \`tag\`, \`status\`, \`button\`):
-  ${code(patternRoles)} — e.g. \`badge-success\`, \`button-danger\`. The default (unsuffixed)
-  variant uses the brand-primary role.
+- Roles (for coloured patterns — \`badge\`, \`tag\`, \`status\`, \`cta\`, \`btn\`, …):
+  ${code(patternRoles)} — e.g. \`badge-success\`, \`cta-danger\`. A pattern that also styles an
+  element accepts the bare role class too (\`<button class="danger">\`). The default
+  (unsuffixed) variant uses the pattern's \`default_role\`.
 - Shape primitives: \`--br-<name>\` radii — ${code(radii)}.
 `;
 }
@@ -1343,16 +1359,25 @@ Shared geometry resolves through a variable chain, most-specific first:
 
 ## 2 — Base declarations & override hooks
 
-Each pattern's \`base\` block is emitted on its selector — a class (\`.<class ?? name>\`) or,
-with \`element\`, a **zero-specificity** \`:where(<element>)\` rule so author CSS can always
-override it. Geometry properties are wrapped in a **per-pattern override hook**:
+Each pattern's \`base\` block is emitted on its selector:
+
+- \`class\` only → \`.<class ?? name>\`, at normal class specificity.
+- \`element\` only → a **zero-specificity** \`:where(<element>)\` rule, so author CSS can always
+  override it.
+- **both** → one \`:where(<element>, .<class>)\` rule (e.g. \`:where(button, .btn)\`). The element
+  gets the styling with no class needed, the class carries it to any other tag, and — because the
+  whole thing sits at zero specificity — any explicit class wins, including a louder pattern
+  (\`.cta\`) or a component's own rule (\`.dialog__close\`).
+
+Geometry properties are wrapped in a **per-pattern override hook**:
 
 | base property | hook variable |
 | --- | --- |
 ${hookTable}
 
-e.g. \`padding: var(--p-button, 0.6em 1.2em)\` — a consumer restyles every button by setting
-\`--p-button\` on \`:root\`, without touching the pattern.
+e.g. \`padding: var(--p-btn, 0.4em 0.8em)\` — a consumer restyles every button by setting
+\`--p-btn\` on \`:root\`, without touching the pattern. The hook is named after the pattern's
+**key**, not its class.
 
 ## 3 — States
 
@@ -1374,7 +1399,10 @@ rules are wrapped in \`@media (hover: hover)\` so touch devices never stick.
 ## 4 — Role variants
 
 \`roles\` lists semantic colour variants: class patterns emit \`.<pattern>-<role>\`
-(\`.badge-success\`), element patterns emit \`<element>.<role>\` (\`button.danger\`). Fill
+(\`.badge-success\`). A pattern with an \`element\` emits both the bare role class on the
+element and the \`-<role>\` form (\`:where(button, .btn).danger, .btn-danger\`), so the same
+variant works on a non-element host — both at class specificity, so neither outranks a
+plain class. Fill
 patterns set \`background-color: var(--<role>-solid)\` + \`color: var(--<role>-on-solid)\`;
 text patterns use the role's \`bold\` emphasis stop. \`default_role\` colours the bare,
 unsuffixed pattern. States re-apply per variant with the variant's role.
@@ -1477,6 +1505,22 @@ function generateDocs(ds, assetsDir) {
 * and the pre-built JS bundles) live under `assets/` in this package and are read /
 * copied from there — they are the same for every consumer.
 */
+/**
+* Selector the dark functional-token flip hangs off.
+*
+* `data-brx-theme` is Bricks' own attribute — Bricks sets it, so it's what the
+* WordPress target needs. Nothing sets it anywhere else, which meant the dark
+* flip was unreachable outside Bricks: the shipped `<color-scheme-toggle>` web
+* component writes `documentElement.dataset.theme` (i.e. `data-theme`), so
+* clicking "Dark" changed an attribute no rule matched. Matching both makes the
+* component work on every target without changing what Bricks already does.
+*
+* Note this covers the explicit choice only — there is deliberately no
+* `prefers-color-scheme` block, so the toggle's "System" position currently
+* resolves to light. Adding one would flip every existing consumer site dark for
+* dark-OS users, which is a product decision, not a bug fix.
+*/
+const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
 const DEFAULT_ASSETS = join(dirname(fileURLToPath(import.meta.url)), "..", "assets");
 const UTILITY_PROPS = {
 	bg: "background-color",
@@ -1616,7 +1660,7 @@ function build(ds, format, assetsDir) {
 			if (surfaceRole) fb += `  --overlay: color-mix(in oklch, var(--color-${surfaceRole.hue}-950) 60%, transparent);\n`;
 			if (fb) {
 				css += `/* Functional role tokens (dark) */\n`;
-				css += `:root[data-brx-theme="dark"] {\n  color-scheme: dark;\n${fb}}\n\n`;
+				css += `${DARK_SEL} {\n  color-scheme: dark;\n${fb}}\n\n`;
 			}
 		}
 		const allTokens = [];
@@ -1704,6 +1748,7 @@ function build(ds, format, assetsDir) {
 		generated["typography.css"] = typo;
 	}
 	const stateRules = (sel, role, states, colorProp = "background-color") => {
+		const sels = Array.isArray(sel) ? sel : [sel];
 		let out = "";
 		for (const [state, spec] of Object.entries(states)) {
 			const body = [];
@@ -1721,7 +1766,8 @@ function build(ds, format, assetsDir) {
 			}
 			if (spec.css && typeof spec.css === "object") for (const [k, v] of Object.entries(spec.css)) body.push(`${k}: ${v};`);
 			if (!body.length) continue;
-			const rule = `${sel}${state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`} {\n  ${body.join("\n  ")}\n}\n`;
+			const pseudo = state === "hover" ? ":hover" : state === "active" ? ":active" : state === "focus-visible" ? ":focus-visible" : `:${state}`;
+			const rule = `${sels.map((s) => `${s}${pseudo}`).join(",\n")} {\n  ${body.join("\n  ")}\n}\n`;
 			out += state === "hover" ? `@media (hover: hover) {\n${rule}}\n` : rule;
 		}
 		return out;
@@ -1731,11 +1777,12 @@ function build(ds, format, assetsDir) {
 	for (const [pname, p] of Object.entries(patterns?.items ?? {})) {
 		if (!p.base) continue;
 		const states = p.states ?? {};
-		const isElement = !!p.element;
-		const defaultSel = isElement ? `:where(${p.element})` : `.${p.class ?? pname}`;
+		const cls = p.class ?? (p.element ? void 0 : pname);
+		const elementSel = (extra = "") => `:where(${[p.element, cls && `.${cls}`].filter(Boolean).join(", ")})${extra}`;
+		const defaultSel = p.element ? elementSel() : `.${cls}`;
 		const defaultRole = p.default_role ?? null;
 		const base = { ...p.base };
-		const fills = pname === "button" || pname === "badge" || base["background-color"] != null || base["background"] != null;
+		const fills = p.fill ?? (pname === "button" || pname === "badge" || base["background-color"] != null || base["background"] != null);
 		const colorProp = fills ? "background-color" : "color";
 		pat += `${defaultSel} {\n`;
 		if (Object.keys(states).length > 0) {
@@ -1753,10 +1800,10 @@ function build(ds, format, assetsDir) {
 		pat += decls(wrappedBase) + "\n}\n";
 		pat += stateRules(defaultSel, defaultRole, states, colorProp);
 		for (const role of p.roles ?? []) {
-			const variantSel = isElement ? `${p.element}.${role}` : `.${p.class ?? pname}-${role}`;
+			const variantSels = p.element ? [elementSel(`.${role}`), ...cls ? [`.${cls}-${role}`] : []] : [`.${cls}-${role}`];
 			const variantColorDecl = fills ? `background-color: var(--${role}-solid); color: var(--${role}-on-solid)` : `color: var(--color-${role}-bold)`;
-			pat += `${variantSel} { ${variantColorDecl}; }\n`;
-			pat += stateRules(variantSel, role, states, colorProp);
+			pat += `${variantSels.join(",\n")} { ${variantColorDecl}; }\n`;
+			pat += stateRules(variantSels, role, states, colorProp);
 		}
 		pat += "\n";
 	}
@@ -1918,11 +1965,25 @@ function build(ds, format, assetsDir) {
 		}, null, 2),
 		designManifest: (() => {
 			const reverseIndex = {};
-			for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) reverseIndex[`--color-${name}-${n}`] = `colors.palette.${name}.seed`;
+			for (const [name, hue] of Object.entries(expandedPalette)) for (const n of Object.keys(hue.numeric)) reverseIndex[`--color-${name}-${n}`] = `colors.palette.${name}.anchors.${n}`;
 			const colorRoles = Object.entries(roleMap).map(([name, ramp]) => ({
 				name,
 				ramp
 			}));
+			const roleTokens = Object.fromEntries(Object.entries(expandedPalette).map(([hueName, hue]) => {
+				const def = functionalRole("_", hueName, hue);
+				const sfc = functionalRole("surface", hueName, hue);
+				return [hueName, {
+					default: {
+						light: def.light,
+						dark: def.dark
+					},
+					surface: {
+						light: sfc.light,
+						dark: sfc.dark
+					}
+				}];
+			}));
 			const typoRoles = typography?.roles ?? {};
 			const hooks = {};
 			for (const [key, [prop, sfx]] of Object.entries(TYPO_KEYMAP)) hooks[sfx] = {
@@ -1935,7 +1996,6 @@ function build(ds, format, assetsDir) {
 			const pGroups = patterns?.groups ?? {};
 			const pItems = patterns?.items ?? {};
 			for (const prop of Object.keys(pDefaults)) reverseIndex[`--${prop}-default`] = `patterns.defaults.${prop}`;
-			for (const name of Object.keys(pRadii)) reverseIndex[`--br-${name}`] = `patterns.radii.${name}`;
 			for (const [group, props] of Object.entries(pGroups)) for (const prop of Object.keys(props)) reverseIndex[`--${prop}-${group}`] = `patterns.groups.${group}.${prop}`;
 			const items = Object.entries(pItems).map(([name, p]) => {
 				const base = p.base ?? {};
@@ -1952,12 +2012,14 @@ function build(ds, format, assetsDir) {
 					roles: p.roles ?? []
 				};
 			});
+			for (const name of Object.keys(pRadii)) if (!(`--br-${name}` in reverseIndex)) reverseIndex[`--br-${name}`] = `patterns.radii.${name}`;
 			return JSON.stringify({
 				colors: {
 					ramps: Object.keys(expandedPalette),
 					steps: NUMERIC_STEPS,
 					palette: numericPalette,
-					roles: colorRoles
+					roles: colorRoles,
+					roleTokens
 				},
 				typography: {
 					roles: Object.keys(typoRoles),
@@ -1985,14 +2047,10 @@ function build(ds, format, assetsDir) {
 					items
 				},
 				shadows: shadows ?? {},
-				interaction: {
-					duration: "200ms",
-					easing: "ease"
-				},
 				reverseIndex
 			}, null, 2);
 		})(),
-		tailwind: emitTailwind({
+		tailwind: format !== "tailwind" ? "" : emitTailwind({
 			ds,
 			expandedPalette,
 			scaleRoles,
@@ -2052,7 +2110,7 @@ function emitTailwind(ctx) {
 		const surface = scaleRoles.find((r) => r.role === "surface");
 		if (surface) darkBlock += `  --overlay: color-mix(in oklch, var(--color-${surface.hue}-950) 60%, transparent);\n`;
 	}
-	if (darkBlock) parts.push(`/* Functional role tokens (dark) */\n:root[data-brx-theme="dark"] {\n  color-scheme: dark;\n${darkBlock}}\n`);
+	if (darkBlock) parts.push(`/* Functional role tokens (dark) */\n${DARK_SEL} {\n  color-scheme: dark;\n${darkBlock}}\n`);
 	parts.push("/* State variant for the active flip (hover/focus-visible are built in). */\n@custom-variant is-active (&.is-active, &[data-active]);\n");
 	const util = [];
 	if (scaleRoles.length) {
@@ -2309,6 +2367,7 @@ function loadConfig(input) {
 		const lines = result.errors.slice(0, 12).map((e) => `  • ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
 		throw new Error(`Invalid design-system.json:\n${lines}`);
 	}
+	for (const w of result.warnings) console.warn(`[vitops] ${w}`);
 	return result.data;
 }
 async function generate(options) {
@@ -3087,21 +3146,73 @@ function defaultConfig() {
 				top: 1e3
 			},
 			items: {
-				button: {
+				btn: {
 					group: "control",
 					element: "button",
-					default_role: "brand-primary",
+					class: "btn",
+					fill: false,
+					overrides: {
+						b: "1px solid transparent",
+						fs: "inherit"
+					},
+					base: {
+						display: "inline-flex",
+						"align-items": "center",
+						"justify-content": "center",
+						gap: "0.4em",
+						padding: "var(--p-btn-group)",
+						"border-radius": "var(--br-btn-group)",
+						border: "var(--b-btn-group)",
+						"box-shadow": "var(--ds-btn-group)",
+						background: "transparent",
+						color: "inherit",
+						"font-family": "inherit",
+						"font-size": "var(--fs-btn-group)",
+						"font-weight": "inherit",
+						"text-decoration": "none",
+						cursor: "pointer"
+					},
+					states: {
+						hover: {
+							step: 1,
+							css: { "background-color": "var(--color-surface-muted)" }
+						},
+						"focus-visible": { ring: true }
+					},
+					roles: []
+				},
+				cta: {
+					group: "control",
+					class: "cta",
+					fill: true,
+					default_role: "ui-primary",
+					overrides: {
+						p: "0.75em 1.5em",
+						b: "none",
+						ds: "var(--shadow-sm)",
+						fs: "inherit"
+					},
 					base: {
-						padding: "0.6em 1.2em",
-						"border-radius": "var(--br-control, 0.25rem)",
-						border: "none",
+						display: "inline-flex",
+						"align-items": "center",
+						"justify-content": "center",
+						gap: "0.5em",
+						padding: "var(--p-cta-group)",
+						"border-radius": "var(--br-cta-group)",
+						border: "var(--b-cta-group)",
+						"font-family": "inherit",
+						"font-size": "var(--fs-cta-group)",
 						"font-weight": "600",
-						color: "#fff",
+						"text-decoration": "none",
 						cursor: "pointer",
-						"box-shadow": "var(--shadow-sm)"
+						color: "var(--ui-primary-on-solid)",
+						"box-shadow": "var(--ds-cta-group)"
 					},
 					states: {
-						hover: { step: 1 },
+						hover: {
+							step: 1,
+							lift: "1px"
+						},
 						active: { scale: .97 },
 						"focus-visible": { ring: true }
 					},