@samva/markup 0.13.0 → 0.14.0

package/dist/{theme-css-CEUrDpqq.js → theme-css-s9QwD5Ko.js}

@@ -1,3 +1,4 @@
+import { r as isDarkSchemeQuery } from "./dark-scheme-CbCwGDWH.js";
 import { generate, parse, walk } from "css-tree";
 import { Result } from "better-result";
 //#region src/email/css-color.ts
@@ -322,14 +323,15 @@ const BRAND_NAMESPACES = [
 	"--text-",
 	"--leading-",
 	"--tracking-",
-	"--radius-",
+	"--radius",
 	"--spacing",
 	"--container-",
 	"--shadow-"
 ];
+/** `--color-` names a prefix; `--radius` is the variable itself or a `--radius-*` prefix. */
+const inNamespace = (property, namespace) => namespace.endsWith("-") ? property.startsWith(namespace) : property === namespace || property.startsWith(`${namespace}-`);
 const BRAND_PROPERTY = /^--[a-z][a-z0-9-]*$/;
 const BRAND_UNSAFE_VALUE = /[{};<>\\@]|url\s*\(|expression\s*\(|\/\*/i;
-const BRAND_DARK_MEDIA = /^\(\s*prefers-color-scheme\s*:\s*dark\s*\)$/i;
 const BRAND_FONT_DESCRIPTORS = /* @__PURE__ */ new Set([
 	"font-family",
 	"src",
@@ -338,8 +340,6 @@ const BRAND_FONT_DESCRIPTORS = /* @__PURE__ */ new Set([
 	"font-display",
 	"unicode-range"
 ]);
-/** The theme variable a dark-mode color lowers to: `--color-brand` → `--color-brand-dark`. */
-const darkVariableName = (property) => `${property}-dark`;
 const spanOfNode = (node) => ({
 	start: node.loc?.start.offset ?? 0,
 	end: node.loc?.end.offset ?? 0
@@ -390,7 +390,7 @@ const parseBrandCss = (css) => {
 				report("brand-css-property", `${property} is not a theme variable; name theme variables --namespace-name.`, span);
 				continue;
 			}
-			if (!BRAND_NAMESPACES.some((namespace) => property.startsWith(namespace))) {
+			if (!BRAND_NAMESPACES.some((namespace) => inNamespace(property, namespace))) {
 				report("brand-css-namespace", `${property} is outside the brand namespaces (${BRAND_NAMESPACES.map((namespace) => namespace.endsWith("-") ? `${namespace}*` : namespace).join(", ")}).`, span);
 				continue;
 			}
@@ -476,7 +476,7 @@ const parseBrandCss = (css) => {
 				readFontFace(node);
 				continue;
 			}
-			if (name === "media" && node.prelude !== null && BRAND_DARK_MEDIA.test(generate(node.prelude).trim())) {
+			if (name === "media" && node.prelude !== null && isDarkSchemeQuery(generate(node.prelude))) {
 				for (const child of node.block.children) if (child.type === "Atrule" && child.name.toLowerCase() === "theme") readTheme(child, dark, "dark");
 				else report("brand-css-unsupported", "The dark-mode block may contain only @theme.", spanOfNode(child));
 				continue;
@@ -484,10 +484,6 @@ const parseBrandCss = (css) => {
 		}
 		report("brand-css-unsupported", "A brand theme contains only @theme, a dark-mode @theme (@media (prefers-color-scheme: dark)), and @font-face.", spanOfNode(node));
 	}
-	for (const property of Object.keys(dark)) if (darkVariableName(property) in variables) report("brand-css-dark-conflict", `${darkVariableName(property)} and the dark-mode ${property} name the same theme variable; keep one.`, {
-		start: 0,
-		end: 0
-	});
 	return diagnostics.length > 0 ? Result.err(diagnostics) : Result.ok({
 		variables,
 		dark,
@@ -518,9 +514,92 @@ const printBrandCss = (brand) => {
 	];
 	return blocks.length === 0 ? "" : `${blocks.join("\n\n")}\n`;
 };
-/** The brand color, and the text color that sits on it. */
-const BRAND_COLOR_VARIABLE = "--color-brand";
-const BRAND_FOREGROUND_VARIABLE = "--color-brand-foreground";
+/**
+* The semantic color tokens, as Tailwind color names (`bg-card`,
+* `text-primary-foreground`, `border-border`), each with the role a block uses
+* it for. A block reads only these, so swapping the theme reskins it.
+*/
+const THEME_COLOR_ROLES = {
+	background: "The page, behind everything.",
+	foreground: "Text on the page.",
+	card: "A surface that groups the message's content.",
+	"card-foreground": "Text on a card.",
+	primary: "The main action's fill (a button), and links.",
+	"primary-foreground": "Text on a primary fill.",
+	secondary: "A quieter action's fill.",
+	"secondary-foreground": "Text on a secondary fill.",
+	muted: "A subdued surface: a code block, a table header.",
+	"muted-foreground": "Secondary text on the page, a card or a muted surface: labels, captions, the footer.",
+	accent: "A highlighted surface: a callout, a selected row.",
+	"accent-foreground": "Text on an accent surface.",
+	border: "Rules, dividers and outlines."
+};
+const THEME_COLORS = Object.keys(THEME_COLOR_ROLES);
+/**
+* The non-color tokens: the corner radius (`rounded`; `rounded-sm` to `rounded-xl` follow it) and
+* the body and heading families (`font-sans`, `font-heading`).
+*/
+const THEME_TOKENS = [
+	"--radius",
+	"--font-sans",
+	"--font-heading"
+];
+const colorVariables = (colors) => Object.fromEntries(THEME_COLORS.map((name) => [`--color-${name}`, colors[name]]));
+/**
+* The theme every project compiles with, beneath its own: a neutral light and
+* dark palette, an 8px radius and the system sans-serif stack. A project's
+* `theme.css`, its imported stylesheets and its brand layer over it.
+*/
+const DEFAULT_THEME = {
+	variables: {
+		...colorVariables({
+			background: "#ffffff",
+			foreground: "#0a0a0a",
+			card: "#ffffff",
+			"card-foreground": "#0a0a0a",
+			primary: "#171717",
+			"primary-foreground": "#fafafa",
+			secondary: "#f5f5f5",
+			"secondary-foreground": "#171717",
+			muted: "#f5f5f5",
+			"muted-foreground": "#737373",
+			accent: "#f5f5f5",
+			"accent-foreground": "#171717",
+			border: "#e5e5e5"
+		}),
+		"--radius": "8px",
+		"--radius-sm": "calc(var(--radius) - 4px)",
+		"--radius-md": "calc(var(--radius) - 2px)",
+		"--radius-lg": "var(--radius)",
+		"--radius-xl": "calc(var(--radius) + 4px)",
+		"--font-sans": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif",
+		"--font-heading": "var(--font-sans)"
+	},
+	dark: colorVariables({
+		background: "#0a0a0a",
+		foreground: "#fafafa",
+		card: "#171717",
+		"card-foreground": "#fafafa",
+		primary: "#fafafa",
+		"primary-foreground": "#171717",
+		secondary: "#262626",
+		"secondary-foreground": "#fafafa",
+		muted: "#262626",
+		"muted-foreground": "#a3a3a3",
+		accent: "#262626",
+		"accent-foreground": "#fafafa",
+		border: "#2e2e2e"
+	}),
+	fontFaces: []
+};
+/** `DEFAULT_THEME` as theme CSS. */
+const DEFAULT_THEME_CSS = printBrandCss(DEFAULT_THEME);
+/** The fills whose text color a brand may leave out: `--color-primary` and `--color-primary-foreground`, and so on. */
+const FILL_COLORS = [
+	"primary",
+	"secondary",
+	"accent"
+];
 /** WCAG relative luminance of an sRGB channel triple in 0–1. */
 const relativeLuminance = (r, g, b) => {
 	const linear = (channel) => {
@@ -545,41 +624,24 @@ const contrastForeground = (color) => {
 	return 1.05 / (luminance + .05) > (luminance + .05) / .05 ? "#ffffff" : "#000000";
 };
 /**
-* The text-on-brand colors a brand gets when it leaves them out: for the light
-* theme and, when the brand sets a dark-mode brand color, for dark mode. Each
-* is the `contrastForeground` of the brand color it sits on. A brand that sets
-* the foreground, or whose brand color does not evaluate, gets no default.
-*/
-const brandForegroundDefaults = (brand) => {
-	const light = brand.variables["--color-brand-foreground"] === void 0 && brand.variables["--color-brand"] !== void 0 ? contrastForeground(brand.variables[BRAND_COLOR_VARIABLE]) : void 0;
-	const darkBrand = brand.dark[BRAND_COLOR_VARIABLE];
-	return {
-		light,
-		dark: darkBrand !== void 0 && brand.dark["--color-brand-foreground"] === void 0 && brand.variables[darkVariableName("--color-brand-foreground")] === void 0 ? contrastForeground(darkBrand) : void 0
-	};
-};
-/**
-* A brand theme as flat theme variables, the way a build compiles it. Email
-* inlining resolves `var()` once, so a dark-mode `@theme` cannot switch a
-* value at run time; each dark color lowers to its `-dark` theme variable,
-* which `dark:` utilities read (`dark:bg-brand-dark`). A text-on-brand color
-* the brand leaves out is filled in by `brandForegroundDefaults`, so every
-* build compiles the same default and the stored CSS never carries it.
+* The text colors a theme layer gets for the fills it sets without one: for
+* each of `FILL_COLORS`, the `contrastForeground` of the fill, in light mode
+* and, where the layer's dark-mode block sets the fill, in dark mode. A layer
+* that sets the foreground, or whose fill does not evaluate, gets no default.
+* Every build lowers each theme layer with these, so stored theme CSS never
+* carries them.
 */
-const brandThemeVariables = (brand) => {
-	const defaults = brandForegroundDefaults(brand);
+const foregroundDefaults = (light, dark) => {
+	const defaults = (colors) => Object.fromEntries(FILL_COLORS.flatMap((fill) => {
+		const color = colors[`--color-${fill}`];
+		const foreground = `--color-${fill}-foreground`;
+		const picked = color === void 0 || colors[foreground] !== void 0 ? void 0 : contrastForeground(color);
+		return picked === void 0 ? [] : [[foreground, picked]];
+	}));
 	return {
-		...brand.variables,
-		...defaults.light === void 0 ? {} : { [BRAND_FOREGROUND_VARIABLE]: defaults.light },
-		...Object.fromEntries(Object.entries(brand.dark).map(([property, value]) => [darkVariableName(property), value])),
-		...defaults.dark === void 0 ? {} : { [darkVariableName(BRAND_FOREGROUND_VARIABLE)]: defaults.dark }
+		light: defaults(light),
+		dark: defaults(dark)
 	};
 };
-/** The stylesheet Tailwind compiles for the theme's brand import: `brandThemeVariables` and the font faces. */
-const brandTailwindCss = (brand) => printBrandCss({
-	fontFaces: brand.fontFaces,
-	variables: brandThemeVariables(brand),
-	dark: {}
-});
 //#endregion
-export { brandThemeVariables as a, parseBrandCss as c, formatColor as d, parseColor as f, brandTailwindCss as i, printBrandCss as l, BRAND_FOREGROUND_VARIABLE as n, contrastForeground as o, brandForegroundDefaults as r, darkVariableName as s, BRAND_COLOR_VARIABLE as t, downlevelColors as u };
+export { THEME_COLOR_ROLES as a, foregroundDefaults as c, downlevelColors as d, formatColor as f, THEME_COLORS as i, parseBrandCss as l, DEFAULT_THEME_CSS as n, THEME_TOKENS as o, parseColor as p, FILL_COLORS as r, contrastForeground as s, DEFAULT_THEME as t, printBrandCss as u };

package/generated/contract.json

@@ -164,7 +164,14 @@
         {
           "name": "backgroundColor",
           "type": "string",
-          "optional": true
+          "optional": true,
+          "description": "The page color, painted across the whole body and, as `bgcolor`, on the wrapper table for clients that drop body styles. Defaults to the theme's `--color-background`, which switches in dark mode."
+        },
+        {
+          "name": "gutter",
+          "type": "number",
+          "optional": true,
+          "description": "Pixels of space each side of the content, so it never touches the screen edge on a narrow viewport. Defaults to 16; `0` lets content run edge to edge."
         },
         {
           "name": "style",
@@ -197,7 +204,8 @@
         {
           "name": "width",
           "type": "number | string",
-          "optional": true
+          "optional": true,
+          "description": "The band's width. A pixel width (`600`) is a maximum: the band fills a narrower screen, and classic Outlook, which ignores `max-width`, draws it at that width."
         },
         {
           "name": "bgcolor",
@@ -259,6 +267,18 @@
           "optional": true,
           "description": "With `each`, the cells in a row; each chunk of items is its own `Columns` table."
         },
+        {
+          "name": "stack",
+          "type": "boolean",
+          "optional": true,
+          "description": "Stack the cells into one column, each full width, on a viewport narrower than 600px. On by default; `stack={false}` keeps a row of small cells (icons, a price beside a label) side by side. Clients that ignore media queries keep the row."
+        },
+        {
+          "name": "gap",
+          "type": "number",
+          "optional": true,
+          "description": "Pixels between the cells of a row. A stacked row puts the same space between the stacked cells instead, so a gap needs no padding on the cells that would misalign them when stacked. The cells must be written out and always render."
+        },
         {
           "name": "children",
           "type": "EmailChild | ((item: Item, index: number) => EmailChild)",
@@ -1274,10 +1294,143 @@
   "styles": {
     "dialect": "Tailwind classes plus theme.css tokens. Classes must be literal.",
     "themeLayers": [
+      "the default theme",
       "@import \"./starter.css\";",
       "@import \"samva:brand\";",
       "the project's own @theme"
     ],
+    "theme": {
+      "colors": [
+        {
+          "name": "background",
+          "variable": "--color-background",
+          "role": "The page, behind everything.",
+          "light": "#ffffff",
+          "dark": "#0a0a0a"
+        },
+        {
+          "name": "foreground",
+          "variable": "--color-foreground",
+          "role": "Text on the page.",
+          "light": "#0a0a0a",
+          "dark": "#fafafa"
+        },
+        {
+          "name": "card",
+          "variable": "--color-card",
+          "role": "A surface that groups the message's content.",
+          "light": "#ffffff",
+          "dark": "#171717"
+        },
+        {
+          "name": "card-foreground",
+          "variable": "--color-card-foreground",
+          "role": "Text on a card.",
+          "light": "#0a0a0a",
+          "dark": "#fafafa"
+        },
+        {
+          "name": "primary",
+          "variable": "--color-primary",
+          "role": "The main action's fill (a button), and links.",
+          "light": "#171717",
+          "dark": "#fafafa"
+        },
+        {
+          "name": "primary-foreground",
+          "variable": "--color-primary-foreground",
+          "role": "Text on a primary fill.",
+          "light": "#fafafa",
+          "dark": "#171717"
+        },
+        {
+          "name": "secondary",
+          "variable": "--color-secondary",
+          "role": "A quieter action's fill.",
+          "light": "#f5f5f5",
+          "dark": "#262626"
+        },
+        {
+          "name": "secondary-foreground",
+          "variable": "--color-secondary-foreground",
+          "role": "Text on a secondary fill.",
+          "light": "#171717",
+          "dark": "#fafafa"
+        },
+        {
+          "name": "muted",
+          "variable": "--color-muted",
+          "role": "A subdued surface: a code block, a table header.",
+          "light": "#f5f5f5",
+          "dark": "#262626"
+        },
+        {
+          "name": "muted-foreground",
+          "variable": "--color-muted-foreground",
+          "role": "Secondary text on the page, a card or a muted surface: labels, captions, the footer.",
+          "light": "#737373",
+          "dark": "#a3a3a3"
+        },
+        {
+          "name": "accent",
+          "variable": "--color-accent",
+          "role": "A highlighted surface: a callout, a selected row.",
+          "light": "#f5f5f5",
+          "dark": "#262626"
+        },
+        {
+          "name": "accent-foreground",
+          "variable": "--color-accent-foreground",
+          "role": "Text on an accent surface.",
+          "light": "#171717",
+          "dark": "#fafafa"
+        },
+        {
+          "name": "border",
+          "variable": "--color-border",
+          "role": "Rules, dividers and outlines.",
+          "light": "#e5e5e5",
+          "dark": "#2e2e2e"
+        }
+      ],
+      "tokens": [
+        {
+          "variable": "--radius",
+          "default": "8px"
+        },
+        {
+          "variable": "--font-sans",
+          "default": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+        },
+        {
+          "variable": "--font-heading",
+          "default": "var(--font-sans)"
+        }
+      ],
+      "darkMode": "One mechanism: the theme's @media (prefers-color-scheme: dark) { @theme { --color-*: … } } block. Write each token's utility once (bg-card); every declaration that reads a color the dark block sets switches in dark mode. Use dark: only to pick a different token in dark mode. Opacity modifiers (bg-primary/10) keep the light value.",
+      "layering": "Each layer owns the colors it sets: a color a layer sets in light mode and not in its dark block keeps that value in dark mode.",
+      "fillForegrounds": "A layer that sets --color-primary, --color-secondary, --color-accent without its -foreground gets black or white, whichever contrasts more, in each mode."
+    },
+    "contrast": {
+      "textError": 3,
+      "textWarning": 4.5,
+      "largePx": 24,
+      "largeBoldPx": 18.5,
+      "shapeError": 1.5,
+      "shapeWarning": 3,
+      "border": 3
+    },
+    "primitives": {
+      "classes": {
+        "email": "sml-email",
+        "button": "sml-button",
+        "link": "sml-link",
+        "divider": "sml-divider",
+        "stack": "sml-stack"
+      },
+      "stackBelowPx": 600,
+      "defaults": "Primitive defaults sit beneath utilities: a class on a primitive overrides its default; a prop is an inline style and overrides both."
+    },
     "fonts": "WOFF2 files in the project through @font-face; a stack must end in a generic family."
   },
   "channels": {
@@ -1367,6 +1520,12 @@
       "summary": "A prop that sizes layout at compile time is not a number literal.",
       "fix": "Write the number literally, for example height={44}."
     },
+    {
+      "code": "email-contrast",
+      "summary": "Text, or a filled button against its surroundings, falls below the contrast ratio in light or dark mode (below 1.5:1 a button is indistinguishable from its surface; WCAG 1.4.11 asks 3:1).",
+      "fix": "Pair background and text tokens (bg-primary with text-primary-foreground), give the theme's dark-mode @theme a value for the token, or choose colors that reach the required ratio.",
+      "upgrade": "Move the project's theme onto the theme vocabulary with one dark-mode block. In starter.css and theme.css, rename each color token to the vocabulary name for its role (reference.md, Theme): a page color to --color-background, the main text to --color-foreground, a surface to --color-card with --color-card-foreground, the brand or action color to --color-primary with --color-primary-foreground, subdued text to --color-muted-foreground, a highlight to --color-accent with --color-accent-foreground, rules to --color-border, body and heading fonts to --font-sans and --font-heading, and a corner radius to --radius. Keep every value.\n\nMove each --color-<name>-dark value into @media (prefers-color-scheme: dark) { @theme { --color-<name>: <value>; } } under the renamed token, and delete the -dark tokens. In every template and partial, rename the utilities to match (bg-surface to bg-card, text-muted to text-muted-foreground, and so on) and delete each dark:…-dark class whose token now has a dark value; keep a dark: class only where it picks a different token in dark mode.\n\nThen fix what email-contrast still reports at its location: pair each fill with its -foreground token, or give the dark block a value that reaches the ratio. Do not weaken the design to pass: keep the brand's colors and adjust the paired token.\n\nCompile every entry and render every fixture in light and dark mode; confirm the light render is unchanged apart from fixes. Resolve errors before requesting one saved version for the whole project, approved by the user; do not publish."
+    },
     {
       "code": "email-font-fallback",
       "summary": "A font stack names a project font without a generic fallback.",
@@ -1453,11 +1612,21 @@
       "summary": "<Columns each> is not a list from the input.",
       "fix": "Write each={input.items} with a callback returning <Column>."
     },
+    {
+      "code": "invalid-columns-gap",
+      "summary": "<Columns gap> is set on a Columns whose cells are repeated with each or rendered conditionally.",
+      "fix": "Write each Column out unconditionally, or pad the cells instead of using gap."
+    },
     {
       "code": "invalid-columns-per",
       "summary": "<Columns per> is not a positive integer literal.",
       "fix": "Write per={2}."
     },
+    {
+      "code": "invalid-columns-stack",
+      "summary": "<Columns stack> is not a true or false literal.",
+      "fix": "Write stack={false}, or leave it out to stack on narrow screens."
+    },
     {
       "code": "invalid-content",
       "summary": "An element holds content its content model does not allow.",
@@ -1473,6 +1642,11 @@
       "summary": "The template's default locale is not a string literal.",
       "fix": "Write locale: \"en-US\"."
     },
+    {
+      "code": "invalid-number-prop",
+      "summary": "A primitive's numeric prop, such as <Email gutter>, is not a finite number in range.",
+      "fix": "Pass a finite number the message allows, for example gutter={16}."
+    },
     {
       "code": "invalid-preheader",
       "summary": "The preheader is not a string.",