@getvitops/generator 8.3.0-alpha.0 → 8.3.0-alpha.2

package/dist/index.mjs

@@ -6,6 +6,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { transform } from "lightningcss";
+import { pickOn } from "@getvitops/utils/color";
 import { AD_PLATFORMS, AD_PROVIDER_KEYS } from "@getvitops/utils/ads";
 import { generateIconInclude, nodesToHtml, resolveIcon, t } from "@getvitops/utils";
 import { resolveSitemapUrl } from "@getvitops/utils/indexing";
@@ -49,7 +50,7 @@ const TIERS = {
 		use: "`<Tree items={…} />` — it emits `<wc-tree>` itself, so do NOT add your own wrapper."
 	},
 	carousel: {
-		emdash: ["vitops.carousel"],
+		emdash: ["vitops_carousel"],
 		css: c([
 			"carousel",
 			"carousel__track",
@@ -67,7 +68,7 @@ const TIERS = {
 		use: "`<Carousel slides={…} label=\"…\" />` — it emits `<wc-carousel>` itself, so do NOT add your own wrapper. `.carousel` is the shell and `.carousel__track` the scroller; add `loop` for the cloned infinite strip (`autoplay` implies it)."
 	},
 	gallery: {
-		emdash: ["vitops.gallery"],
+		emdash: ["vitops_gallery"],
 		css: c([
 			"gallery",
 			"gallery__item",
@@ -83,7 +84,7 @@ const TIERS = {
 		use: "`<Gallery images={…} label=\"…\" />` — it emits `<wc-gallery>` wrapping a `<Carousel />` (which emits its own `<wc-carousel>`) itself, so do NOT add your own wrapper around either. Each thumbnail is a plain `<a href=\"#slide-id\">` into the carousel's own `<li id=\"slide-id\">` inside a single `<dialog class=\"lightbox-dialog\">` (see `lightbox`), so it is a working modal lightbox — WITH prev/next — before any script runs. Stepping between images is the carousel's job, not the gallery's."
 	},
 	entries: {
-		emdash: ["vitops.entries"],
+		emdash: ["vitops_entries"],
 		css: c([
 			"entries__table",
 			"entries__scroll",
@@ -99,7 +100,7 @@ const TIERS = {
 		use: "`<Entries entries={[{ heading, pairs: [{ term, value }] }]} />` — it emits `<wc-entries>` itself, so do NOT add your own wrapper. By hand: `<wc-entries>` around `<h3>` + `<dl>` pairs. The tier-2 exemplar: semantic pairs with no JS, a table with it."
 	},
 	copy: {
-		emdash: ["vitops.copyButton"],
+		emdash: ["vitops_copyButton"],
 		css: c([
 			"copy",
 			"copy__button",
@@ -115,7 +116,7 @@ const TIERS = {
 		use: "`<wc-copy>` around the content and a `[data-copy]` button."
 	},
 	dismissable: {
-		emdash: ["vitops.banner"],
+		emdash: ["vitops_banner"],
 		css: c(["banner__close", "notification__close"], "patterns/banner.css"),
 		wc: {
 			tag: "wc-dismissable",
@@ -141,7 +142,7 @@ const TIERS = {
 		use: "`<wc-split-panel>` with two children. Unenhanced they simply stack."
 	},
 	"image-compare": {
-		emdash: ["vitops.imageCompare"],
+		emdash: ["vitops_imageCompare"],
 		css: c([
 			"image-compare",
 			"image-compare__before",
@@ -156,7 +157,7 @@ const TIERS = {
 		use: "`<wc-image-compare>` with two images. Both are visible without JS."
 	},
 	marquee: {
-		emdash: ["vitops.marquee"],
+		emdash: ["vitops_marquee"],
 		css: c([
 			"marquee",
 			"marquee__content",
@@ -188,12 +189,13 @@ const TIERS = {
 			"section__sub",
 			"section__body",
 			"section--split",
-			"section--center"
+			"section--center",
+			"block-anchor"
 		], "patterns/section.css"),
 		use: "`.section.region` > `.centered` > `.section__inner` holding `.section__head` (kicker, heading, sub) and `.section__body`. `.section--split` puts the head beside the body when wide. In EmDash it is a block TYPE (`vitops_section`) with a Portable Text body that accepts any other block — see `vitopsBlockTypes()`."
 	},
 	steps: {
-		emdash: ["vitops.steps"],
+		emdash: ["vitops_steps"],
 		css: c([
 			"steps",
 			"steps__item",
@@ -205,7 +207,7 @@ const TIERS = {
 		use: "`<ol class=\"steps tone\">` of `<li class=\"steps__item\">` each holding a `.steps__body` with a real heading. The number is a CSS counter and the connector line a pseudo-element; `.steps--row` runs it sideways when wide."
 	},
 	stats: {
-		emdash: ["vitops.stats"],
+		emdash: ["vitops_stats"],
 		css: c([
 			"stats",
 			"stats__item",
@@ -218,7 +220,7 @@ const TIERS = {
 		use: "`<ul class=\"stats\">` of `.stats__item`, each figure a `<Counter>`. `.stats--tiles` adds `.stats__group` and `.stats__delta`; `data-state=\"up|down\"` colours the delta through the success/danger roles."
 	},
 	callout: {
-		emdash: ["vitops.callout"],
+		emdash: ["vitops_callout"],
 		css: c([
 			"callout",
 			"callout__body",
@@ -230,16 +232,17 @@ const TIERS = {
 		use: "`.callout.tone` with a `.callout__body` and `.callout__actions`. A call-to-action band that stays on the page — NOT `banner`, which is a dismissible announcement."
 	},
 	logos: {
-		emdash: ["vitops.logos"],
+		emdash: ["vitops_logos"],
 		css: c([
 			"logos",
 			"logos__item",
+			"logos__name",
 			"logos--grayscale"
 		], "patterns/logos.css"),
-		use: "`<ul class=\"logos\">` of `.logos__item` images (alt text = the name). A still grid; `marquee` is the scrolling version."
+		use: "`<ul class=\"logos\">` of `.logos__item` images (alt text = the name), or `.logos__name` text when there is no image. A still grid; `marquee` is the scrolling version."
 	},
 	embed: {
-		emdash: ["vitops.embed"],
+		emdash: ["vitops_embed"],
 		css: c([
 			"embed",
 			"embed__frame",
@@ -248,7 +251,7 @@ const TIERS = {
 		use: "`.embed` around an `<iframe class=\"embed__frame\" data-consent=\"marketing\" data-consent-src=\"…\">` with NO `src`, and a `.embed__placeholder`. The consent runtime assigns the address after the grant; the placeholder holds a real link. Never give the iframe a live `src`."
 	},
 	counter: {
-		emdash: ["vitops.stats"],
+		emdash: ["vitops_stats"],
 		css: c([
 			"counter",
 			"counter__value",
@@ -263,7 +266,7 @@ const TIERS = {
 		use: "`<Counter value=\"94%\" />` — it emits `<wc-counter>` itself, so do NOT add your own wrapper. The final value is parsed from the fallback text, never passed separately."
 	},
 	"multi-field": {
-		emdashExempt: "repeats rows a visitor adds at submit time (several phone numbers, guests); `vitops.form` has a fixed, editor-defined field list and no such field type",
+		emdashExempt: "repeats rows a visitor adds at submit time (several phone numbers, guests); `vitops_form` has a fixed, editor-defined field list and no such field type",
 		css: c([
 			"form-group",
 			"input-group",
@@ -278,14 +281,14 @@ const TIERS = {
 		use: "`<wc-multi-field>` around a field template. One row submits fine with no JS."
 	},
 	turnstile: {
-		emdash: ["vitops.form"],
+		emdash: ["vitops_form"],
 		css: c(["form-group"], "patterns/forms.css"),
 		wc: {
 			tag: "wc-turnstile",
 			registered: true,
 			adds: "loads Cloudflare Turnstile on first interaction with the form and holds a submit until its token arrives"
 		},
-		use: "`<wc-turnstile sitekey=\"…\">` inside a `<form>`, around a paragraph saying the spam check needs JavaScript. Pair it with `createConversionRoute({ turnstile })`; the `vitops.form` block does both."
+		use: "`<wc-turnstile sitekey=\"…\">` inside a `<form>`, around a paragraph saying the spam check needs JavaScript. Pair it with `createConversionRoute({ turnstile })`; the `vitops_form` block does both."
 	},
 	"color-scheme-toggle": {
 		emdashExempt: "site chrome (header/footer), not page content; belongs in the nav/layout",
@@ -374,7 +377,7 @@ const TIERS = {
 		use: "Not shipped. See `color-wheel`."
 	},
 	details: {
-		emdash: ["vitops.details", "vitops.accordion"],
+		emdash: ["vitops_details", "vitops_accordion"],
 		css: c([
 			"details",
 			"details-trigger",
@@ -412,7 +415,7 @@ const TIERS = {
 		use: "`<NavShell>` with a `nav` slot, plus `<NavShellToggle>` if the toggle must live outside the shell."
 	},
 	subgrid: {
-		emdash: ["vitops.pricing"],
+		emdash: ["vitops_pricing"],
 		css: c([
 			"subgrid",
 			"subgrid-card",
@@ -422,8 +425,8 @@ const TIERS = {
 		use: "`<Subgrid>` — emits `<ul class=\"subgrid\" role=\"list\">`; author `<li class=\"card subgrid-card\">` items yourself, so tranches align across the set."
 	},
 	card: {
-		emdash: ["vitops.cards"],
-		css: c(["card"], "patterns/card.css", true),
+		emdash: ["vitops_cards"],
+		css: c(["card", "card__title"], "patterns/card.css", true),
 		wc: {
 			tag: "wc-cards",
 			registered: true,
@@ -443,7 +446,7 @@ const TIERS = {
 		use: "`<Icon name=\"menu\" />`. Names are semantic and resolve per configured set; a name containing `:` passes through."
 	},
 	split: {
-		emdash: ["vitops.hero"],
+		emdash: ["vitops_hero"],
 		css: c([
 			"split",
 			"split-1-2",
@@ -471,9 +474,9 @@ const TIERS = {
 			"navlist--columns"
 		], "patterns/sitenav.css"),
 		astro: [...a("SiteNav", "css"), ...a("SiteFooter", "css")],
-		emdash: ["vitops.nav"],
+		emdash: ["vitops_nav"],
 		bricks: "vitops-sitenav",
-		use: "`.sitenav` with `--bp-*` and a drawer direction. `<details>` + Invoker Commands, no JS. In Astro: `<SiteNav {...await loadNavMenus(getMenu)} />` renders EmDash menu `primary` (the default: dropdowns from `md`, drawer below) and, if they exist, `primary-mobile` (depth-1 nav below `md`) and `primary-mega` (mega panels from `xl`) — adding the menu in the admin is the whole change. An item's `titleAttr` is its description. `<SiteFooter sitemap legal name>` renders `footer-sitemap` + `footer-legal` + the copyright line. For a menu inside page content (a site map, a section's links, footer-style columns) use `.navlist` — plain nested lists, `--inline` / `--columns` — or, in EmDash, the `vitops.nav` block (menu, layout `list|inline|columns|sitenav`, depth 1–3, heading, tone). Name each `<nav>` uniquely: the header is `Primary` and the footer `Site map` / `Legal`, and the block never reuses those."
+		use: "`.sitenav` with `--bp-*` and a drawer direction. `<details>` + Invoker Commands, no JS. In Astro: `<SiteNav {...await loadNavMenus(getMenu)} />` renders EmDash menu `primary` (the default: dropdowns from `md`, drawer below) and, if they exist, `primary-mobile` (depth-1 nav below `md`) and `primary-mega` (mega panels from `xl`) — adding the menu in the admin is the whole change. An item's `titleAttr` is its description. `<SiteFooter sitemap legal name>` renders `footer-sitemap` + `footer-legal` + the copyright line. For a menu inside page content (a site map, a section's links, footer-style columns) use `.navlist` — plain nested lists, `--inline` / `--columns` — or, in EmDash, the `vitops_nav` block (menu, layout `list|inline|columns|sitenav`, depth 1–3, heading, tone). Name each `<nav>` uniquely: the header is `Primary` and the footer `Site map` / `Legal`, and the block never reuses those."
 	},
 	"split-link": {
 		css: c([
@@ -485,17 +488,17 @@ const TIERS = {
 		use: "`.split-link` — a link plus a disclosure toggle. No JS."
 	},
 	btn: {
-		emdash: ["vitops.actionLink"],
+		emdash: ["vitops_actionLink"],
 		css: c(["btn"], void 0, true),
 		use: "`<button>` gets it with no class; `.btn` carries it to other tags. `fill: false`, so states drive `color`."
 	},
 	cta: {
-		emdash: ["vitops.actionLink"],
+		emdash: ["vitops_actionLink"],
 		css: c(["cta", "cta-danger"], void 0, true),
 		use: "`.cta` on any element — usually `<a>`, since a CTA navigates. Filled, with role variants."
 	},
 	link: {
-		emdash: ["vitops.actionLink"],
+		emdash: ["vitops_actionLink"],
 		css: c([
 			"link",
 			"skip-link",
@@ -505,9 +508,19 @@ const TIERS = {
 		use: "`<a>` gets it at zero specificity; `.link` for other tags. `.stretched-link` makes one link cover its positioned ancestor (whole-card click, no JS — but the card text stops being selectable); `.raised` lifts content back above that overlay."
 	},
 	badge: {
+		emdash: ["vitops_badges"],
 		css: c(["badge", "badge-indicator"], "patterns/tag.css", true),
 		use: "`.badge` — a STATIC label. Use `tag` if it is dismissable or editable."
 	},
+	"widget-area": {
+		emdash: ["vitops_widgetArea"],
+		css: c([
+			"widget-area",
+			"widget__title",
+			"widget__menu"
+		], "patterns/widget-area.css"),
+		use: "Editor-managed regions: `<VitopsWidgetArea name=\"footer-columns\" />` (`@getvitops/emdash/astro`) renders an area from Widgets in the admin — titled groups, a menu as a labelled `<nav>`, content as Portable Text. In a page, the `vitops_widgetArea` block places one. An area holding a `core:*` component widget falls back to EmDash's own renderer, and an area cannot hold another. Prerendered pages show an edit after the next deploy."
+	},
 	tag: {
 		css: c([
 			"tag",
@@ -570,8 +583,8 @@ const TIERS = {
 			"review__source"
 		], "patterns/review.css", true),
 		astro: a("ReviewCard", "css"),
-		emdash: ["vitops.reviews"],
-		use: "`<ReviewCard review={…} />` — one card, from `vitops reviews`' `.vitops/reviews.json` cache. Put several inside `<Carousel>` slides or `<Marquee>` items; there is no group component and no `wc-review`. In EmDash, `vitops.reviews` is that whole row: it reads the cache as a build-time import (`virtual:getvitops/reviews`, served by `vitops()`; empty when the file is absent), picks reviews with `selectReviews()`, and lays them out as a grid, carousel or marquee. A new review appears after `vitops reviews` is re-run, committed and the site rebuilt."
+		emdash: ["vitops_reviews"],
+		use: "`<ReviewCard review={…} />` — one card, from `vitops reviews`' `.vitops/reviews.json` cache. Put several inside `<Carousel>` slides or `<Marquee>` items; there is no group component and no `wc-review`. In EmDash, `vitops_reviews` is that whole row: it reads the cache as a build-time import (`virtual:getvitops/reviews`, served by `vitops()`; empty when the file is absent), picks reviews with `selectReviews()`, and lays them out as a grid, carousel or marquee. A new review appears after `vitops reviews` is re-run, committed and the site rebuilt."
 	},
 	tabs: {
 		css: c(["tabs"], void 0, true),
@@ -595,7 +608,7 @@ const TIERS = {
 		use: "`.navbar` with `--start/--center/--end`."
 	},
 	banner: {
-		emdash: ["vitops.banner"],
+		emdash: ["vitops_banner"],
 		css: c([
 			"banner",
 			"banner__content",
@@ -2494,7 +2507,7 @@ ${bricks}
 Portable Text block ${code("_type")}s from ${code("@getvitops/emdash")}. Repeating patterns are
 repeater fields. A Portable Text block cannot contain other blocks, so a pattern that must hold
 them is a schema-level block TYPE with a Portable Text body instead — ${code("vitops_section")},
-from ${code("vitopsBlockTypes()")}. Its body accepts every ${code("vitops.*")} block below.
+from ${code("vitopsBlockTypes()")}. Its body accepts every ${code("vitops_*")} block below.
 
 | Block | Pattern | Renders via |
 | --- | --- | --- |
@@ -4418,7 +4431,7 @@ function toHtmlFragment(blocks) {
 * Two deliberate mappings:
 *  - the `# ` heading is **dropped** — in EmDash the page title is a field
 *    (`data.title`), and repeating it as the first content block renders twice;
-*  - the review blockquote becomes a `vitops.banner` with `tone: "warning"`,
+*  - the review blockquote becomes a `vitops_banner` with `tone: "warning"`,
 *    which is exactly the block the hand-written placeholder pages used.
 *
 * `_key`s are derived from position rather than randomness, so regenerating an
@@ -4431,7 +4444,7 @@ function toPortableText(blocks, prefix) {
 		if (b.kind === "heading" && b.level === 1) return;
 		if (b.kind === "quote") {
 			out.push({
-				_type: "vitops.banner",
+				_type: "vitops_banner",
 				_key: key,
 				message: b.spans.map((s) => s.text).join(""),
 				tone: "warning",
@@ -4483,7 +4496,7 @@ const REVIEW_NOTICE = "> Generated from this site's configuration. It is a start
 * designated and is published, that a privacy impact assessment precedes any
 * communication outside Quebec, that consent mechanics match the Act, and — easy
 * to miss — that content directed at Quebec consumers is available in French. It
-* is a second blockquote (a second `vitops.banner` in Portable Text) so it cannot
+* is a second blockquote (a second `vitops_banner` in Portable Text) so it cannot
 * be skimmed past as part of the first.
 */
 const QC_REVIEW_NOTICE = "> Quebec (Law 25): this document is written for the Quebec privacy regime and has NOT been reviewed by counsel. Before publishing, have a lawyer confirm that a person in charge of the protection of personal information is designated, that any transfer of information outside Quebec is preceded by a privacy impact assessment, that your consent and cookie mechanisms match the Act, and whether a French version is required for your audience. It is not legal advice.";
@@ -5223,6 +5236,18 @@ function generateLegal(cfg, opts = {}) {
 */
 const HERE = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ASSETS = join(HERE, "..", "assets");
+/**
+* `--color-<hue>-<step>-on`: the readable text colour for a fill at that step, computed with the
+* same APCA pick as `text-on-<role>`. A role has one (`--color-text-on-<role>`); a raw hue step
+* did not, so a block filling with `color: amber-500` had no site-defined foreground to use. These
+* live in a plain `:root`, never `@theme`: a `--color-*` theme key would mint `text-<hue>-<step>-on`
+* utilities nobody asked for.
+*/
+function hueOnTokens(palette) {
+	const out = [];
+	for (const [name, hue] of Object.entries(palette)) for (const [n, hex] of Object.entries(hue.numeric)) out.push(`--color-${name}-${n}-on: ${pickOn(hex)};`);
+	return out;
+}
 const UTILITY_PROPS = {
 	bg: "background-color",
 	text: "color",
@@ -5511,6 +5536,8 @@ function build(ds, format, assetsDir, buildOpts = {}) {
 		css += `  color-scheme: ${buildOpts.darkOnly ? "dark" : "light"};\n`;
 		css += `  /* Hue scales (numeric steps, 50 = tinted near-white … 950 = tinted near-black) */\n`;
 		for (const [name, hue] of Object.entries(expandedPalette)) for (const [n, hex] of Object.entries(hue.numeric)) css += `  --color-${name}-${n}: ${hex};\n`;
+		css += `\n  /* Foreground for a fill at a hue step (--color-<hue>-<step>-on) */\n`;
+		for (const line of hueOnTokens(expandedPalette)) css += `  ${line}\n`;
 		css += `\n  /* Role tokens (the public API) */\n`;
 		for (const fr of scaleRoles) for (const [t, val] of Object.entries(fr.light)) css += `  ${tokenVar(fr.role, t)}: ${val};\n`;
 		if (focusRole) {
@@ -5970,6 +5997,7 @@ function build(ds, format, assetsDir, buildOpts = {}) {
 			assetsDir,
 			utilities: UTILITIES,
 			systemColorScheme: buildOpts.systemColorScheme === true,
+			sources: buildOpts.sources ?? [],
 			darkOnly: buildOpts.darkOnly === true
 		}),
 		designMd: format !== "design" ? "" : emitDesignMd({
@@ -5990,7 +6018,9 @@ function emitTailwind(ctx) {
 	const cssDir = join(assetsDir, "css");
 	const nl = (arr) => arr.filter(Boolean).join("\n");
 	const parts = ["/* GENERATED for Tailwind v4 (Astro) — do not edit by hand.\n   Class reference: npx vitops docs classes  ·  All topics: npx vitops docs\n   Fonts below are STACKS ONLY — this file loads no webfonts. Load them with\n   Astro's fonts: config and point the token at the family's cssVariable. */"];
-	parts.push(`@import "tailwindcss";\n`);
+	parts.push(`@import "tailwindcss";`);
+	for (const src of ctx.sources) parts.push(`@source ${JSON.stringify(src)};`);
+	parts.push("");
 	const theme = [];
 	theme.push(`  /* Hue scales → bg-<hue>-<step> text-* border-* (numeric, 50…950) */`);
 	for (const [name, hue] of Object.entries(expandedPalette)) for (const [n, hex] of Object.entries(hue.numeric)) theme.push(`  --color-${name}-${n}: ${hex};`);
@@ -6020,6 +6050,7 @@ function emitTailwind(ctx) {
 			fn += `  --surface-glass: color-mix(in oklch, var(--color-bg-surface) 72%, transparent);\n`;
 			fn += `  --overlay: color-mix(in oklch, var(--color-${surface.hue}-950) 45%, transparent);\n`;
 		}
+		for (const line of hueOnTokens(expandedPalette)) fn += `  ${line}\n`;
 		if (ctx.darkOnly) fn = `  color-scheme: dark;\n${fn}`;
 		parts.push(`/* Role tokens (the public API) */\n:root {\n${fn}}\n`);
 	}
@@ -6515,7 +6546,8 @@ async function generate(options) {
 	const config = options.site != null ? loadConfigFile(options.site, options.siteEnv) : embedded;
 	const built = build(ds, format, assetsDir, {
 		systemColorScheme: options.systemColorScheme ?? config?.designSystem?.defaultColorScheme === "system",
-		darkOnly: config?.designSystem?.defaultColorScheme === "dark"
+		darkOnly: config?.designSystem?.defaultColorScheme === "dark",
+		...options.sources?.length ? { sources: options.sources } : {}
 	});
 	mkdirSync(outDir, { recursive: true });
 	const written = [];