blume 2.0.3 → 2.1.1

package/src/theme/palette.ts

@@ -1,21 +1,90 @@
 import type { ResolvedConfig } from "../core/schema.ts";
+import { composite, contrastRatio, parseColor } from "./color.ts";
+import type { Rgba } from "./color.ts";
 
-const FALLBACK_ACCENT = "oklch(0.62 0.16 250)";
+/** Per-mode CSS colors. */
+export interface AccentColors {
+  dark: string;
+  light: string;
+}
+
+/** A color mode. */
+export type ColorMode = keyof AccentColors;
 
 /**
- * Named accent presets mapped to OKLCH values. The single source of truth for
- * preset colors: the theme CSS and the OG card (og/card.ts) both resolve from
- * this table, so a site and its social cards can't disagree about "blue".
+ * Named accent presets mapped to OKLCH values, per mode. The single source of
+ * truth for preset colors: the theme CSS and the OG card (og/card.ts) both
+ * resolve from this table, so a site and its social cards can't disagree
+ * about "blue". Each clears WCAG AA (4.5:1) as text on its mode's page and
+ * under its button label ({@link readableOn}), with room to spare on the
+ * tinted surfaces accent text also sits on: the light shades are dark enough
+ * for white labels, the dark shades light enough to read on the dark page.
  */
 export const ACCENTS = {
-  blue: FALLBACK_ACCENT,
-  green: "oklch(0.6 0.16 150)",
-  orange: "oklch(0.68 0.17 50)",
-  pink: "oklch(0.65 0.2 350)",
-  purple: "oklch(0.58 0.2 290)",
-  red: "oklch(0.58 0.22 25)",
-  teal: "oklch(0.6 0.12 195)",
-} satisfies Record<string, string>;
+  blue: { dark: "oklch(0.62 0.16 250)", light: "oklch(0.55 0.16 250)" },
+  green: { dark: "oklch(0.6 0.16 150)", light: "oklch(0.53 0.16 150)" },
+  orange: { dark: "oklch(0.68 0.17 50)", light: "oklch(0.56 0.17 50)" },
+  pink: { dark: "oklch(0.65 0.2 350)", light: "oklch(0.58 0.2 350)" },
+  purple: { dark: "oklch(0.6 0.2 290)", light: "oklch(0.57 0.2 290)" },
+  red: { dark: "oklch(0.61 0.22 25)", light: "oklch(0.58 0.22 25)" },
+  teal: { dark: "oklch(0.6 0.12 195)", light: "oklch(0.53 0.12 195)" },
+} satisfies Record<string, AccentColors>;
+
+/** The contrast WCAG AA asks of body-size text. */
+export const MIN_TEXT_CONTRAST = 4.5;
+
+/**
+ * The theme's own colors a configured accent is drawn against: each mode's
+ * page background and text, and the dark ink a filled accent can carry.
+ * Mirrors the defaults in `entry.ts`.
+ */
+export const THEME_INKS = {
+  dark: {
+    background: "oklch(0.085 0 0)",
+    foreground: "oklch(0.96 0 0)",
+    ink: "oklch(0.085 0 0)",
+    mutedForeground: "oklch(0.68 0 0)",
+  },
+  light: {
+    background: "oklch(1 0 0)",
+    foreground: "oklch(0.145 0 0)",
+    ink: "oklch(0.145 0 0)",
+    mutedForeground: "oklch(0.53 0 0)",
+  },
+} satisfies Record<ColorMode, Record<string, string>>;
+
+const WHITE = "oklch(1 0 0)";
+
+/** A color this module writes itself, parsed (they all parse). */
+const own = (value: string): Rgba =>
+  parseColor(value) ?? { alpha: 1, blue: 0, green: 0, red: 0 };
+
+/** {@link THEME_INKS}, parsed, for contrast math. */
+export const themeInk = (
+  mode: ColorMode,
+  name: keyof (typeof THEME_INKS)[ColorMode]
+): Rgba => own(THEME_INKS[mode][name]);
+
+/**
+ * The label color for text on a filled `fill` (a button, a step number): white
+ * while it reaches AA, else the mode's dark ink when that reads better, so a
+ * light accent (every dark-mode preset) gets dark text instead of white text
+ * nobody can read.
+ */
+export const labelOn = (fill: Rgba, mode: ColorMode): string => {
+  const opaque = composite(fill, themeInk(mode, "background"));
+  const onWhite = contrastRatio(own(WHITE), opaque);
+  return onWhite >= MIN_TEXT_CONTRAST ||
+    onWhite >= contrastRatio(themeInk(mode, "ink"), opaque)
+    ? WHITE
+    : THEME_INKS[mode].ink;
+};
+
+/** {@link labelOn} for a CSS color; one this module can't parse keeps white. */
+export const readableOn = (fill: string, mode: ColorMode): string => {
+  const color = parseColor(fill);
+  return color ? labelOn(color, mode) : WHITE;
+};
 
 /**
  * Whether a raw config value names an accent preset. `hasOwn` keeps a value
@@ -35,9 +104,11 @@ const CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
 const safeColor = (value: string, fallback: string): string =>
   CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
 
-/** Resolve a named preset or fall back to {@link safeColor}. */
-const presetOrColor = (value: string): string =>
-  isAccentPreset(value) ? ACCENTS[value] : safeColor(value, FALLBACK_ACCENT);
+/** Resolve a named preset in `mode`, or fall back to {@link safeColor}. */
+const presetOrColor = (value: string, mode: ColorMode): string =>
+  isAccentPreset(value)
+    ? ACCENTS[value][mode]
+    : safeColor(value, ACCENTS.blue[mode]);
 
 /** Like {@link safeColor} but drops an unsafe/absent value to `null`. */
 const safeColorOrNull = (value: string | undefined): string | null =>
@@ -58,20 +129,23 @@ const backgroundImageCss = (image: string): string =>
 const cssToken = (name: string, value?: string | null): string[] =>
   value ? [`  ${name}: ${value};`] : [];
 
+/** One mode's resolved accent and action fills. */
+interface ModeFills {
+  accent: string;
+  action: string | null;
+}
+
 const themeRootCss = (
   theme: ResolvedConfig["theme"],
-  options: {
-    accent: string;
-    action: string | null;
-    radius: string;
-  }
+  options: ModeFills & { radius: string }
 ): string =>
   [
     `  --blume-accent: ${options.accent};`,
+    `  --blume-accent-foreground: ${readableOn(options.accent, "light")};`,
     ...cssToken("--blume-action", options.action),
     ...cssToken(
       "--blume-action-foreground",
-      options.action ? "oklch(1 0 0)" : null
+      options.action ? readableOn(options.action, "light") : null
     ),
     ...cssToken("--blume-background", safeColorOrNull(theme.background?.light)),
     ...cssToken(
@@ -87,10 +161,7 @@ const themeRootCss = (
 
 const themeDarkCss = (
   theme: ResolvedConfig["theme"],
-  options: {
-    accent: string;
-    action: string | null;
-  }
+  options: ModeFills
 ): string => {
   // Mode-shared tokens (accent, action) must be re-declared here: the base
   // stylesheet's own `:root[data-theme="dark"]` block outranks the `:root`
@@ -98,11 +169,11 @@ const themeDarkCss = (
   // silently keep its neutral defaults and ignore the config.
   const tokens = [
     `  --blume-accent: ${options.accent};`,
-    "  --blume-accent-foreground: oklch(1 0 0);",
+    `  --blume-accent-foreground: ${readableOn(options.accent, "dark")};`,
     ...cssToken("--blume-action", options.action),
     ...cssToken(
       "--blume-action-foreground",
-      options.action ? "oklch(1 0 0)" : null
+      options.action ? readableOn(options.action, "dark") : null
     ),
     ...cssToken("--blume-background", safeColorOrNull(theme.background?.dark)),
     ...cssToken(
@@ -118,26 +189,31 @@ ${tokens.join("\n")}
 `;
 };
 
-/** Per-mode accent CSS colors. */
-export interface AccentColors {
-  dark: string;
-  light: string;
-}
-
 /**
  * Resolve the configured accent to per-mode CSS colors. A named accent
- * resolves to its preset; any other value is treated as a raw CSS color so
- * users can pass arbitrary colors without a config change. A string accent
- * has already been normalized by the config schema to the same color for
- * both modes.
+ * resolves to its preset's shade for each mode; any other value is treated as
+ * a raw CSS color so users can pass arbitrary colors without a config change.
+ * A string accent has already been normalized by the config schema to the
+ * same value for both modes.
  */
 export const resolveAccent = (
   theme: ResolvedConfig["theme"]
 ): AccentColors => ({
-  dark: presetOrColor(theme.accent.dark),
-  light: presetOrColor(theme.accent.light),
+  dark: presetOrColor(theme.accent.dark, "dark"),
+  light: presetOrColor(theme.accent.light, "light"),
 });
 
+/** Resolve the configured `action` fill per mode, or `null` when unset. */
+export const resolveAction = (
+  theme: ResolvedConfig["theme"]
+): AccentColors | null =>
+  theme.action
+    ? {
+        dark: presetOrColor(theme.action, "dark"),
+        light: presetOrColor(theme.action, "light"),
+      }
+    : null;
+
 /** Resolve the configured radius preset to a CSS length. */
 export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
   RADII[theme.radius];
@@ -145,20 +221,20 @@ export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
 /**
  * Compile theme config into CSS custom properties. A named accent resolves to
  * its preset; any other value is treated as a raw CSS color so users can pass
- * arbitrary colors without a config change.
+ * arbitrary colors without a config change. Labels on accent and action fills
+ * take whichever of white or dark ink reads ({@link readableOn}).
  */
 export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
   const accent = resolveAccent(theme);
-  const action = theme.action ? presetOrColor(theme.action) : null;
-  const radius = RADII[theme.radius];
+  const action = resolveAction(theme);
   const root = themeRootCss(theme, {
     accent: accent.light,
-    action,
-    radius,
+    action: action?.light ?? null,
+    radius: RADII[theme.radius],
   });
   const dark = themeDarkCss(theme, {
     accent: accent.dark,
-    action,
+    action: action?.dark ?? null,
   });
 
   return `/* Generated by Blume from theme config. */

package/src/translate/prompts.ts

@@ -64,6 +64,7 @@ ${previousTranslation}`;
 Rules:
 - Translate the prose: headings, paragraphs, list items, table cells, admonitions, and image alt text.
 - In the YAML frontmatter, translate ONLY the values of these keys: ${KEY_LIST}. Copy every other frontmatter key and value exactly as written.
+- Keep the frontmatter valid YAML: if a translated value contains a colon followed by a space (\`: \`) or a space followed by \`#\`, or starts with a quote, a backtick, or another YAML indicator character, write it as a double-quoted string and escape any double quotes inside it.
 - Never translate or alter: code blocks, inline code, import/export statements, JSX/MDX component names and their attributes, URLs, link targets, HTML tags, or frontmatter keys.
 - A heading may end with anchor markers: \`[#some-id]\`, \`{#some-id}\` (also written \`\\{#some-id\\}\`), \`[!toc]\`, or \`[toc]\`. Copy every marker exactly as written, in the same position at the end of the translated heading — never translate, reorder, or drop a marker, and never change the id inside \`[#...]\` or \`{#...}\` (anchors must stay identical across languages).
 

package/src/translate/validate.ts

@@ -7,7 +7,8 @@ import { TRANSLATABLE_KEY_PATHS } from "./prompts.ts";
  * structure: the final frontmatter is *reconstructed* from the source (clone
  * the source data, overlay only the translatable string values), so invented
  * keys are dropped, deleted keys are restored, and slugs/icons/orders/dates
- * stay source-verbatim by construction. Only then is the file written.
+ * stay source-verbatim by construction. The one source key left out is
+ * `seo.canonical` (see `dropCanonical`). Only then is the file written.
  */
 
 export type ValidationResult =
@@ -93,6 +94,26 @@ const setPath = (
   parent[path.at(-1) as string] = value;
 };
 
+/**
+ * Drop `seo.canonical`, and `seo` with it when nothing else is left. The
+ * source's canonical names a page in the source language (most often the
+ * source page itself); copied into a translation, it would canonicalize the
+ * translation to another language and take it out of search. Without it the
+ * translation gets Blume's default canonical: its own URL.
+ */
+const dropCanonical = (data: FrontmatterData): void => {
+  const { seo } = data;
+  if (!isKeyedObject(seo) || !("canonical" in seo)) {
+    return;
+  }
+  const { canonical: _canonical, ...rest } = seo;
+  if (Object.keys(rest).length > 0) {
+    data.seo = rest;
+  } else {
+    delete data.seo;
+  }
+};
+
 const ensureTrailingNewline = (text: string): string =>
   text.endsWith("\n") ? text : `${text}\n`;
 
@@ -132,8 +153,14 @@ export const validateTranslation = (
   let parsed: { content: string; data: FrontmatterData };
   try {
     parsed = matter(candidate);
-  } catch {
-    return { ok: false, reason: "frontmatter does not parse as YAML" };
+  } catch (error) {
+    // js-yaml's message leads with the problem and its line:column in the
+    // file, then a multi-line code frame; the first line is enough to act on.
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      reason: `frontmatter does not parse as YAML: ${message.replace(/\n[\s\S]*$/u, "")}`,
+    };
   }
 
   const rawBody = ensureTrailingNewline(parsed.content.replace(/^\r?\n/u, ""));
@@ -175,6 +202,7 @@ export const validateTranslation = (
       setPath(data, path, translated);
     }
   }
+  dropCanonical(data);
 
   return {
     ok: true,

package/src/upgrade/upgrade.ts

@@ -1,8 +1,7 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 
-import { join, relative, resolve } from "pathe";
-import { glob } from "tinyglobby";
+import { join, relative } from "pathe";
 import { z } from "zod";
 
 import {
@@ -10,17 +9,9 @@ import {
   ComponentOverridesError,
 } from "../core/component-overrides.ts";
 import { ConfigValidationError, loadConfig } from "../core/config.ts";
-import { BlumeError, locateFrontmatterKey } from "../core/diagnostics.ts";
-import matter from "../core/frontmatter.ts";
-import { createModuleLoader } from "../core/load-module.ts";
+import { BlumeError } from "../core/diagnostics.ts";
 import { findComponentsFile, findConfigFile } from "../core/project.ts";
-import { pageMetaSchema } from "../core/schema.ts";
-import { baselineScanIgnore } from "../core/sources/watch.ts";
 import type { Diagnostic } from "../core/types.ts";
-import {
-  DEFAULT_CONTENT_EXCLUDE,
-  DEFAULT_CONTENT_INCLUDE,
-} from "../sources/filesystem.ts";
 
 /**
  * `blume upgrade`'s logic, kept out of the command module so it runs (and is
@@ -280,163 +271,6 @@ const scriptFindings = async (root: string): Promise<Diagnostic[]> => {
   });
 };
 
-// ---------------------------------------------------------------------------
-// Removed front matter fields
-// ---------------------------------------------------------------------------
-
-/** Where a project's local content lives, as its config names it. */
-interface ContentGlobs {
-  exclude: string[];
-  include: string[];
-  root: string;
-}
-
-const globFields = {
-  exclude: z.array(z.string()).optional(),
-  include: z.array(z.string()).optional(),
-  root: z.string().optional(),
-};
-
-/**
- * A filesystem source in either form a config being upgraded may hold: the
- * `filesystem()` descriptor, or Blume 1's `{ type: "filesystem" }` object.
- */
-const rawFilesystemSourceSchema = z.union([
-  z
-    .looseObject({
-      kind: z.literal("filesystem"),
-      options: z.looseObject(globFields).default({}),
-    })
-    .transform((source) => source.options),
-  z.looseObject({ type: z.literal("filesystem"), ...globFields }),
-]);
-
-/** The `content` slice of a config as written, before validation. */
-const rawContentSchema = z.looseObject({
-  content: z
-    .looseObject({ ...globFields, sources: z.array(z.unknown()).optional() })
-    .optional(),
-});
-
-/**
- * The content roots to scan, read from the config as written rather than the
- * validated config: the upgrade runs on configs that don't validate yet. Its
- * filesystem sources when it lists any, else the `content.root` shorthand,
- * else the zero-config `docs` folder.
- */
-export const contentGlobs = ({
-  content,
-}: z.infer<typeof rawContentSchema>): ContentGlobs[] => {
-  const sources = (content?.sources ?? []).flatMap((source) => {
-    const filesystem = rawFilesystemSourceSchema.safeParse(source);
-    return filesystem.success ? [filesystem.data] : [];
-  });
-  return (sources.length > 0 ? sources : [content ?? {}]).map((globs) => ({
-    exclude: globs.exclude ?? DEFAULT_CONTENT_EXCLUDE,
-    include: globs.include ?? DEFAULT_CONTENT_INCLUDE,
-    root: globs.root ?? "docs",
-  }));
-};
-
-/** The content roots the project's config names, loaded as written. */
-const configContentGlobs = async (root: string): Promise<ContentGlobs[]> => {
-  const file = findConfigFile(root);
-  let raw: z.infer<typeof rawContentSchema> = {};
-  if (file) {
-    try {
-      const parsed = rawContentSchema.safeParse(
-        await createModuleLoader()(file)
-      );
-      raw = parsed.success ? parsed.data : {};
-    } catch {
-      // A config that won't load is already reported by the config check;
-      // its content still gets the zero-config scan.
-    }
-  }
-  return contentGlobs(raw);
-};
-
-const isPathKey = (segment: PropertyKey): segment is number | string =>
-  typeof segment !== "symbol";
-
-// Zod's own wording for an unknown key; a removed field's hint replaces it.
-const PLAIN_UNKNOWN_KEY = "Unrecognized key";
-
-/**
- * The removed fields among one page's front matter issues, each at its own
- * line. Only issues the page schema words as a removed-field hint count: a
- * key a project declares through `frontmatter.extend` is unknown to the bare
- * schema, and any other invalid value was already an error on Blume 1.
- */
-const removedFieldFindings = (
-  file: string,
-  text: string,
-  issues: readonly z.core.$ZodIssue[]
-): Diagnostic[] =>
-  issues.flatMap((issue) => {
-    if (
-      issue.code !== "unrecognized_keys" ||
-      issue.message.startsWith(PLAIN_UNKNOWN_KEY)
-    ) {
-      return [];
-    }
-    const path = issue.path.filter(isPathKey);
-    const position =
-      locateFrontmatterKey(text, [...path, ...issue.keys.slice(0, 1)]) ??
-      locateFrontmatterKey(text, path);
-    return [
-      {
-        code: "BLUME_FRONTMATTER_INVALID",
-        column: position?.column,
-        file,
-        line: position?.line,
-        message: issue.message,
-        severity: "error",
-      } satisfies Diagnostic,
-    ];
-  });
-
-/** The removed front matter fields in one page, or none it can't parse. */
-const pageFindings = async (file: string): Promise<Diagnostic[]> => {
-  const text = await readFile(file, "utf-8");
-  let parsed: ReturnType<typeof pageMetaSchema.safeParse>;
-  try {
-    parsed = pageMetaSchema.safeParse(matter(text).data);
-  } catch {
-    // Unparseable front matter fails the build with its own diagnostic.
-    return [];
-  }
-  return parsed.success
-    ? []
-    : removedFieldFindings(file, text, parsed.error.issues);
-};
-
-/**
- * A finding for each front matter field Blume 2 removed, across the project's
- * local content. A page with one fails validation and drops out of the build,
- * which the config and components checks alone would report as ready.
- */
-const frontmatterFindings = async (root: string): Promise<Diagnostic[]> => {
-  const roots = await configContentGlobs(root);
-  const matches = await Promise.all(
-    roots.map((globs) => {
-      const cwd = resolve(root, globs.root);
-      return existsSync(cwd)
-        ? glob(globs.include, {
-            absolute: true,
-            cwd,
-            ignore: [...globs.exclude, ...baselineScanIgnore()],
-            onlyFiles: true,
-          })
-        : [];
-    })
-  );
-  // Two sources can share a folder; each page is checked once.
-  const files = [...new Set(matches.flat())].toSorted();
-  const findings = await Promise.all(files.map(pageFindings));
-  return findings.flat();
-};
-
 /**
  * Run one check, turning the {@link BlumeError} it throws into its findings:
  * each config issue or `components.ts` entry on its own, or the one diagnostic
@@ -466,8 +300,8 @@ const findingsOf = async (
  * Check a project against this version of Blume: its config through the
  * loader (every invalid field, each with its line and replacement), its
  * `components.ts` through the static override planner (each entry at its
- * line), its pages' front matter for removed fields, and its package.json
- * scripts for `blume build` flags that no longer exist. Returns the failures;
+ * line), and its package.json scripts for `blume build` flags that no longer
+ * exist. Returns the failures;
  * an empty list means the project is ready.
  */
 export const collectUpgradeFindings = async (
@@ -486,7 +320,6 @@ export const collectUpgradeFindings = async (
           );
         })
       : []),
-    ...(await frontmatterFindings(root)),
     ...(await scriptFindings(root)),
   ];
 };