@mlola-ui/engine 1.0.0

package/src/contract.mjs

@@ -0,0 +1,103 @@
+import { renderAllLibraryCss, renderCatalogCss, renderLibraryRecipesCss } from "./library-recipes.mjs";
+import { behaviors } from "./behavior-spec.mjs";
+
+/**
+ * The portable contract.
+ *
+ * Styling is already framework-free: recipes react only to `data-*` and
+ * `aria-*`. So the attribute half of the contract is derived from the CSS
+ * rather than written by hand, which means it cannot drift from what the
+ * library actually renders. Any renderer in any language that emits these
+ * classes and attributes gets the correct visuals.
+ *
+ * The behaviour half — which attribute flips on which event, and the keyboard
+ * map — cannot be read out of CSS, so it is authored in behavior-spec.mjs and
+ * audited against this derived data.
+ */
+
+const SELECTOR_ATTRIBUTES =
+  /\.(ml-[a-z0-9-]+)((?:\[[a-zA-Z-]+(?:=(?:"[^"]*"|'[^']*'))?\])+)/g;
+const SINGLE_ATTRIBUTE = /\[([a-zA-Z-]+)(?:=(?:"([^"]*)"|'([^']*)'))?\]/g;
+
+function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+function selectorsOf(css) {
+  const selectors = [];
+  for (const match of stripComments(css).matchAll(/([^{}]+)\{[^{}]*\}/g)) {
+    const head = match[1].trim();
+    if (!head || head.startsWith("@")) continue;
+    for (const part of head.split(",")) selectors.push(part.trim());
+  }
+  return selectors;
+}
+
+/**
+ * class -> attribute -> sorted values ("" means the attribute is a flag).
+ * By default it reads the published stylesheet: the free library. Audits pass
+ * the whole library, Pro included.
+ */
+export function deriveAttributeContract(css = renderLibraryRecipesCss()) {
+  const contract = new Map();
+  for (const selector of selectorsOf(css)) {
+    for (const match of selector.matchAll(SELECTOR_ATTRIBUTES)) {
+      const [, className, attributeBlock] = match;
+      for (const attribute of attributeBlock.matchAll(SINGLE_ATTRIBUTE)) {
+        const name = attribute[1];
+        if (!name.startsWith("data-") && !name.startsWith("aria-")) continue;
+        const value = attribute[2] ?? attribute[3] ?? "";
+        if (!contract.has(className)) contract.set(className, new Map());
+        const attributes = contract.get(className);
+        if (!attributes.has(name)) attributes.set(name, new Set());
+        if (value) attributes.get(name).add(value);
+      }
+    }
+  }
+  return contract;
+}
+
+function toElements(derived) {
+  const elements = {};
+  for (const [className, attributes] of [...derived].sort(([a], [b]) => a.localeCompare(b))) {
+    const entry = {};
+    for (const [name, values] of [...attributes].sort(([a], [b]) => a.localeCompare(b))) {
+      entry[name] = [...values].sort();
+    }
+    elements[className] = entry;
+  }
+  return elements;
+}
+
+/** The published contract: every class and attribute of the free library. */
+export function renderContract() {
+  const elements = toElements(deriveAttributeContract());
+  return {
+    $schema: "./contract.schema.json",
+    version: 1,
+    description:
+      "Classes and the data-/aria- attributes the stylesheet reacts to. Emit these from any language or framework and the visuals are correct. Derived from the stylesheet, not hand written.",
+    styling: { attributeSource: "data-theme, data-mode", elements },
+    behavior: behaviors,
+  };
+}
+
+/**
+ * The Pro contract: only the classes the free library does not style. It is
+ * written beside the Pro catalog, never into the published engine, so the
+ * shape of Pro's API travels with Pro source.
+ */
+export function proAttributeContract() {
+  // A class the published stylesheet names at all is public, attributes or not.
+  const published = new Set([...stripComments(renderLibraryRecipesCss()).matchAll(/\.(ml-[a-z0-9-]+)/g)].map((match) => match[1]));
+  const everything = deriveAttributeContract(`${renderAllLibraryCss()}\n${renderCatalogCss()}`);
+  return new Map([...everything].filter(([className]) => !published.has(className)));
+}
+
+export function renderProContract() {
+  return {
+    version: 1,
+    description: "Mlola Pro classes and the data-/aria- attributes their stylesheets react to. Not published; delivered with Pro source.",
+    styling: { attributeSource: "data-theme, data-mode", elements: toElements(proAttributeContract()) },
+  };
+}

package/src/contrast.mjs

@@ -0,0 +1,68 @@
+/**
+ * Colour math for the accessibility gate.
+ *
+ * The palettes are curated by hand, so "meets WCAG AA" has to be a measured
+ * fact rather than a comment. This converts the engine's OKLCH tokens to sRGB,
+ * composites translucent surfaces over their backdrop, and returns a contrast
+ * ratio the way WCAG 2.2 defines it.
+ */
+
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+
+/** `oklch(L C H / A)` (alpha optional) to OKLab. */
+export function parseOklch(value) {
+  const match = String(value).match(
+    /^oklch\(\s*([\d.]+%?)\s+([\d.]+%?)\s+([\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+%?))?\s*\)$/i,
+  );
+  if (!match) return null;
+  const read = (raw, scale = 1) =>
+    raw.endsWith("%") ? (Number.parseFloat(raw) / 100) * scale : Number.parseFloat(raw);
+  return {
+    L: read(match[1], 1),
+    C: read(match[2], 0.4),
+    H: Number.parseFloat(match[3]),
+    alpha: match[4] === undefined ? 1 : read(match[4], 1),
+  };
+}
+
+/** OKLCH to gamma-encoded sRGB, clamped into gamut. */
+export function oklchToSrgb({ L, C, H }) {
+  const radians = (H * Math.PI) / 180;
+  const a = C * Math.cos(radians);
+  const b = C * Math.sin(radians);
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+  return linear.map((channel) => {
+    const encoded = channel <= 0.0031308 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;
+    return clamp01(encoded);
+  });
+}
+
+/** Composite a possibly translucent colour over an opaque backdrop. */
+function composite([top, alpha], [bottom]) {
+  return top.map((channel, index) => channel * alpha + bottom[index] * (1 - alpha));
+}
+
+/** WCAG relative luminance from gamma-encoded sRGB. */
+export function relativeLuminance([r, g, b]) {
+  const lin = (channel) => (channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+export function contrastRatio(foreground, background) {
+  const fg = parseOklch(foreground);
+  const bg = parseOklch(background);
+  if (!fg || !bg) return null;
+  const backdrop = oklchToSrgb(bg);
+  const top = oklchToSrgb(fg);
+  const color = fg.alpha < 1 ? composite([top, fg.alpha], [backdrop, 1]) : top;
+  const lighter = Math.max(relativeLuminance(color), relativeLuminance(backdrop));
+  const darker = Math.min(relativeLuminance(color), relativeLuminance(backdrop));
+  return (lighter + 0.05) / (darker + 0.05);
+}

package/src/declarations.mjs

@@ -0,0 +1,131 @@
+import { derive } from "./config.mjs";
+import { CHANNELS, resolveFonts } from "./spec.mjs";
+
+/**
+ * The derived custom properties a theme emits, besides its palette.
+ *
+ * Canonical themes, project themes and prompt-generated themes all come
+ * through here, so every theme gets the same radius, density, depth, motion
+ * and material tokens. Recipes read only these tokens — never a theme's name —
+ * which is what lets a theme nobody has seen yet look finished.
+ */
+
+const round = (value, places = 3) => Number(value.toFixed(places));
+const px = (value) => `${round(value)}px`;
+const rem = (value) => `${round(value, 4)}rem`;
+const ms = (value) => `${Math.round(value)}ms`;
+
+/**
+ * Dark surfaces swallow shadow, so the same elevation needs a denser one to
+ * read at all. One multiplier keeps the two modes on the same curve.
+ */
+const DARK_SHADOW_GAIN = 2.6;
+
+/**
+ * Layered elevation: a tight contact shadow that anchors the surface, plus an
+ * ambient one that grows with the step. A single blurred shadow reads as a
+ * glow; two read as an object resting on a plane.
+ */
+export function shadowDeclarations(derived, gain = 1) {
+  const alpha = (factor) => `oklch(0 0 0 / ${round(Math.min(0.6, derived.shadowAlpha * factor * gain), 4)})`;
+  const { shadowY: y, shadowBlur: blur } = derived;
+  return [
+    `--ml-shadow-xs: 0 1px 2px ${alpha(0.55)}`,
+    `--ml-shadow-sm: 0 1px 2px ${alpha(0.45)}, 0 ${px(y * 0.3)} ${px(blur * 0.4)} -1px ${alpha(0.6)}`,
+    `--ml-shadow-md: 0 1px 2px ${alpha(0.4)}, 0 ${px(y * 0.6)} ${px(blur * 0.9)} -2px ${alpha(0.8)}`,
+    `--ml-shadow-lg: 0 2px 4px ${alpha(0.35)}, 0 ${px(y * 1.2)} ${px(blur * 1.6)} -4px ${alpha(1)}`,
+    `--ml-shadow-xl: 0 4px 8px ${alpha(0.3)}, 0 ${px(y * 2.2)} ${px(blur * 2.8)} -8px ${alpha(1.25)}`,
+  ];
+}
+
+export function darkShadowDeclarations(vector) {
+  return shadowDeclarations(derive({ vector }), DARK_SHADOW_GAIN);
+}
+
+/**
+ * Surface material as tokens. Every surface recipe applies all four, so a
+ * theme's material changes cards, menus, dialogs and bars at once without a
+ * single theme-specific selector.
+ */
+export function materialDeclarations(material, vector) {
+  const none = {
+    "--ml-surface-alpha": "100%",
+    "--ml-surface-blur": "none",
+    "--ml-surface-grain": "none",
+    "--ml-surface-highlight": "0 0 #0000",
+  };
+  const tokens = { ...none };
+  if (material === "glass") {
+    tokens["--ml-surface-alpha"] = "78%";
+    tokens["--ml-surface-blur"] = `blur(${px(10 + 12 * vector.depth)}) saturate(150%)`;
+    tokens["--ml-surface-highlight"] = "inset 0 1px color-mix(in oklab, oklch(1 0 0) 22%, transparent)";
+  } else if (material === "paper") {
+    tokens["--ml-surface-grain"] =
+      "radial-gradient(color-mix(in srgb, var(--ml-text) calc(var(--ml-texture-opacity) * 100%), transparent) 0.6px, transparent 0.7px)";
+  } else if (material === "anodized") {
+    tokens["--ml-surface-highlight"] = "inset 0 1px color-mix(in oklab, var(--ml-text) 10%, transparent)";
+  }
+  return [`--ml-material: ${material}`, ...Object.entries(tokens).map(([name, value]) => `${name}: ${value}`)];
+}
+
+/** Geometry, type, density, motion, depth and material for one spec. */
+export function themeDeclarations(spec) {
+  const derived = derive(spec);
+  const fonts = resolveFonts(spec.fonts);
+  const control = derived.controlHeight;
+  return [
+    `--ml-theme: "${spec.id}"`,
+    ...CHANNELS.map((channel) => `--ml-theme-${channel}: ${spec.vector[channel]}`),
+    `--ml-radius-xs: ${px(Math.max(2, derived.radius * 0.38))}`,
+    `--ml-radius-sm: ${px(derived.radius * 0.68)}`,
+    `--ml-radius-md: ${px(derived.radius)}`,
+    `--ml-radius-lg: ${px(derived.radius * 1.48)}`,
+    `--ml-radius-pill: 9999px`,
+    `--ml-border-width: ${derived.border >= 1.4 ? "1.5px" : "1px"}`,
+    `--ml-control-sm: ${rem(control - 0.25)}`,
+    `--ml-control-md: ${rem(control)}`,
+    `--ml-control-lg: ${rem(control + 0.5)}`,
+    `--ml-panel-padding: ${rem(derived.panelPadding)}`,
+    `--ml-target-min: 2.75rem`,
+    `--ml-font-sans: ${fonts.sans}`,
+    `--ml-font-display: ${fonts.display}`,
+    `--ml-font-mono: ${fonts.mono}`,
+    `--ml-display-weight: ${derived.displayWeight}`,
+    `--ml-body-leading: ${round(derived.bodyLeading)}`,
+    `--ml-tracking: ${round(derived.tracking, 4)}em`,
+    `--ml-icon-stroke: ${round(derived.iconStroke)}`,
+    `--ml-duration-fast: ${ms(derived.durationFast)}`,
+    `--ml-duration-normal: ${ms(derived.durationNormal)}`,
+    `--ml-duration-slow: ${ms(derived.durationSlow)}`,
+    `--ml-duration-reveal: ${ms(derived.durationReveal)}`,
+    `--ml-ease-standard: cubic-bezier(0.2, 0, 0, 1)`,
+    `--ml-ease-spring: cubic-bezier(0.16, 1, 0.3, 1)`,
+    `--ml-ease-bounce: cubic-bezier(0.34, 1.4, 0.64, 1)`,
+    `--ml-texture-opacity: ${round(derived.textureOpacity, 4)}`,
+    ...materialDeclarations(spec.material, spec.vector),
+    ...shadowDeclarations(derived),
+  ];
+}
+
+/**
+ * Tokens that are pure functions of the palette. Same formula in every theme
+ * and mode, so they are declared once per block instead of stored per palette.
+ */
+export const PALETTE_DERIVED = [
+  "--ml-focus: var(--ml-primary-text)",
+  // Hover and pressed fills move a colour toward the page, so they lighten in
+  // light mode and darken in dark mode without a second palette.
+  "--ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background))",
+  "--ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent)",
+  "--ml-fill-active: color-mix(in oklab, var(--ml-text) 9%, transparent)",
+  // A soft, translucent track for switches, meters and sliders that stays
+  // visible on any surface it sits on.
+  "--ml-track: color-mix(in oklab, var(--ml-text) 12%, transparent)",
+  // Checkbox, radio and similar boundaries must reach 3:1 against the page.
+  "--ml-control-border: var(--ml-text-faint)",
+  "--ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent)",
+  // The veil behind overlays: the page's own background taken near black, so
+  // it carries the theme's tint, and more opaque the darker the page, so it
+  // reads as a light veil by day and still separates layers at night.
+  "--ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28))",
+];

package/src/deprecations.mjs

@@ -0,0 +1,29 @@
+/**
+ * Legacy aliases, tracked with a removal version.
+ *
+ * A compatibility alias without a deadline is a permanent second API. Each
+ * entry here is emitted today and must be gone by `removeIn`; the test in
+ * `tests/deprecations.test.mjs` fails if the package version reaches that
+ * version with the alias still present, or if the alias is already gone but the
+ * ledger entry remains.
+ */
+
+export const CURRENT_VERSION = "0.3.0";
+
+export const DEPRECATIONS = [
+  // 1.0 removed data-skin, the shadcn --background/--chart-*/--sidebar-*
+  // aliases, the .ml-button-* class variants and every other duplicate
+  // spelling in one break. New aliases go here with a removal version.
+];
+
+/** Numeric semver comparison. Returns -1, 0, or 1. */
+export function compareVersions(left, right) {
+  const parse = (value) => String(value).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const diff = (a[index] ?? 0) - (b[index] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}

package/src/library-recipes.mjs

@@ -0,0 +1,105 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Assemble the library's stylesheets from the CSS files their owners keep.
+ *
+ * Each component carries its own `<name>.css` next to its source, so a
+ * component's markup, behaviour and styling are reviewed and copied together.
+ * The engine only concatenates them, in a stable order, into the published
+ * layers:
+ *
+ *   - recipes: the engine's composition primitives (`css/base.css`) and every
+ *     free component. This ships in `@mlola-ui/engine`.
+ *   - Pro: Pro components' styles, and the catalog's, are assembled into the
+ *     unpublished catalog stylesheet or loaded by the component itself; they
+ *     never ship in the engine.
+ *   - catalog: blocks, pages and templates. These are the commercial catalog,
+ *     so their CSS is assembled separately and never published by the engine.
+ *
+ * Node-only: this reads the filesystem at build time. Browser code renders
+ * themes through `theme-css.mjs`, which has no such dependency.
+ */
+
+const engineDirectory = dirname(dirname(fileURLToPath(import.meta.url)));
+const packagesDirectory = dirname(engineDirectory);
+
+function ownedCss(root) {
+  let entries = [];
+  try {
+    entries = readdirSync(root).sort();
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".") || entry === "node_modules") continue;
+    const folder = join(root, entry);
+    if (!statSync(folder).isDirectory()) continue;
+    const own = join(folder, `${entry.replace(/^_/, "")}.css`);
+    try {
+      files.push({ owner: `${root.split("/").pop()}/${entry}`, css: readFileSync(own, "utf8") });
+    } catch {
+      // A folder without its own stylesheet contributes nothing.
+    }
+  }
+  return files;
+}
+
+const section = ({ owner, css }) => `/* ${owner} */\n${css.trim()}`;
+
+export function readEngineCss(name) {
+  return readFileSync(join(engineDirectory, "css", `${name}.css`), "utf8").trim();
+}
+
+/**
+ * Pro components are the ones the commercial catalog's index lists. Their
+ * styles never ship in the published engine: they travel with Pro source.
+ */
+function proComponents() {
+  try {
+    return new Set(JSON.parse(readFileSync(join(packagesDirectory, "registry", "catalog", "index.json"), "utf8")).components ?? []);
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * A component that imports its own stylesheet (`import "./name.css"`) loads
+ * it only where it renders, so no aggregate carries it. The canvas family does
+ * this; such a stylesheet wraps itself in the recipes layer.
+ */
+function loadsOwnCss(name) {
+  try {
+    return readFileSync(join(packagesDirectory, "components", name, `${name}.tsx`), "utf8").includes(`import "./${name}.css"`);
+  } catch {
+    return false;
+  }
+}
+
+const componentCss = () => ownedCss(join(packagesDirectory, "components"));
+const componentName = (owner) => owner.split("/").pop();
+
+/** Composition primitives and every free component: the published, critical bundle. */
+export function renderLibraryRecipesCss() {
+  const pro = proComponents();
+  const parts = [{ owner: "engine/base", css: readEngineCss("base") }, ...componentCss().filter((part) => !pro.has(componentName(part.owner)))];
+  return `/* Library recipes — owned by Mlola, no utility framework. */\n\n${parts.map(section).join("\n\n")}\n`;
+}
+
+/** Every component stylesheet, free and Pro, unlayered: what audits and the contract read. */
+export function renderAllLibraryCss() {
+  const parts = [{ owner: "engine/base", css: readEngineCss("base") }, ...componentCss()];
+  return `${parts.map(section).join("\n\n")}\n`;
+}
+
+/** Pro components (those not loading their own CSS), blocks, pages and templates: the Pro styles. */
+export function renderCatalogCss() {
+  const pro = proComponents();
+  const parts = [
+    ...componentCss().filter((part) => pro.has(componentName(part.owner)) && !loadsOwnCss(componentName(part.owner))),
+    ...["blocks", "pages", "templates"].flatMap((group) => ownedCss(join(packagesDirectory, group))),
+  ];
+  return `/* Mlola Pro styles — Pro components, blocks, pages and templates. Not published by @mlola-ui/engine. */\n@layer mlola.recipes {\n\n${parts.map(section).join("\n\n")}\n\n}\n`;
+}