@mlola-ui/engine 1.0.12 → 1.1.0

package/generated/agents.md

@@ -159,6 +159,7 @@ correct. This table is read out of the stylesheet, so it is never stale.
 | `.ml-button` | `data-size` | `icon`, `lg`, `sm` |
 | `.ml-button` | `data-state` | `success` |
 | `.ml-button` | `data-variant` | `danger`, `link`, `outline`, `primary`, `secondary`, `subtle` |
+| `.ml-button` | `data-width` | `full` |
 | `.ml-calendar-cell` | `data-preview` | _presence only_ |
 | `.ml-calendar-cell` | `data-range` | `end`, `start` |
 | `.ml-calendar-day` | `aria-disabled` | `true` |
@@ -212,6 +213,7 @@ correct. This table is read out of the stylesheet, so it is never stale.
 | `.ml-heatmap-cell` | `data-level` | `1`, `2`, `3`, `4` |
 | `.ml-heatmap-cell` | `data-outside` | _presence only_ |
 | `.ml-input` | `aria-invalid` | `true` |
+| `.ml-input` | `data-invalid` | _presence only_ |
 | `.ml-input` | `data-size` | `lg`, `sm` |
 | `.ml-input` | `data-variant` | `filled`, `subtle` |
 | `.ml-input-control` | `data-leading` | _presence only_ |

package/generated/contract.json

@@ -87,6 +87,9 @@
           "primary",
           "secondary",
           "subtle"
+        ],
+        "data-width": [
+          "full"
         ]
       },
       "ml-calendar-cell": {
@@ -283,6 +286,7 @@
         "aria-invalid": [
           "true"
         ],
+        "data-invalid": [],
         "data-size": [
           "lg",
           "sm"

package/generated/recipes.css

@@ -1513,6 +1513,7 @@ button.ml-breadcrumb-link {
 .ml-button {
   position: relative;
   display: inline-flex;
+  max-width: 100%;
   min-height: var(--ml-control-md);
   align-items: center;
   justify-content: center;
@@ -1528,7 +1529,6 @@ button.ml-breadcrumb-link {
   line-height: 1;
   letter-spacing: -.006em;
   text-decoration: none;
-  white-space: nowrap;
   cursor: pointer;
   user-select: none;
   -webkit-tap-highlight-color: transparent;
@@ -1649,10 +1649,22 @@ button.ml-breadcrumb-link {
   padding: 0;
 }
 
+/* A label too long for the space wraps onto balanced lines instead of
+   spilling out. The taller line height is taken back by the margins, so a
+   one-line button is exactly as tall as before. */
 .ml-button-label {
   display: inline-flex;
   align-items: center;
   gap: var(--ml-space-1-5);
+  margin-block: -.1em;
+  line-height: 1.2;
+  text-align: center;
+  text-wrap: balance;
+}
+
+.ml-button[data-width="full"] {
+  display: flex;
+  width: 100%;
 }
 
 .ml-button[data-state="success"] {
@@ -3493,13 +3505,16 @@ button.ml-breadcrumb-link {
   font-size: var(--ml-type-md);
 }
 
+/* A field that is a button or a group says it is invalid with data-invalid: aria-invalid belongs to inputs. */
 .ml-input-field[data-invalid] .ml-input,
-.ml-input[aria-invalid="true"] {
+.ml-input[aria-invalid="true"],
+.ml-input[data-invalid] {
   border-color: var(--ml-danger);
 }
 
 .ml-input-field[data-invalid] .ml-input:focus,
-.ml-input[aria-invalid="true"]:focus {
+.ml-input[aria-invalid="true"]:focus,
+.ml-input[data-invalid]:focus {
   box-shadow: 0 0 0 3px color-mix(in oklab,var(--ml-danger) 20%,transparent);
 }
 
@@ -6532,8 +6547,12 @@ button.ml-stepper-target:focus-visible {
   font-size: var(--ml-type-xs);
   font-weight: 500;
   line-height: 1.4;
-  white-space: nowrap;
+  /* One line when it fits; a long tip wraps within the window instead of running past it. */
+  width: max-content;
+  max-width: min(20rem, calc(100vw - 2 * var(--ml-space-2)));
+  white-space: normal;
   pointer-events: none;
+  /* Placement uses `translate`, so the pop-in's transform adds to it instead of replacing it mid-animation. */
   animation: ml-pop-in var(--ml-duration-fast) var(--ml-ease-spring);
 }
 
@@ -6541,25 +6560,25 @@ button.ml-stepper-target:focus-visible {
 .ml-tooltip:not([data-side]) {
   bottom: calc(100% + var(--ml-space-2));
   left: 50%;
-  transform: translateX(-50%);
+  translate: calc(-50% + var(--ml-tooltip-shift, 0px)) 0;
 }
 
 .ml-tooltip[data-side="bottom"] {
   top: calc(100% + var(--ml-space-2));
   left: 50%;
-  transform: translateX(-50%);
+  translate: calc(-50% + var(--ml-tooltip-shift, 0px)) 0;
 }
 
 .ml-tooltip[data-side="left"] {
   right: calc(100% + var(--ml-space-2));
   top: 50%;
-  transform: translateY(-50%);
+  translate: 0 calc(-50% + var(--ml-tooltip-shift, 0px));
 }
 
 .ml-tooltip[data-side="right"] {
   left: calc(100% + var(--ml-space-2));
   top: 50%;
-  transform: translateY(-50%);
+  translate: 0 calc(-50% + var(--ml-tooltip-shift, 0px));
 }
 
 .ml-tooltip-arrow {
@@ -6574,13 +6593,26 @@ button.ml-stepper-target:focus-visible {
 .ml-tooltip:not([data-side]) .ml-tooltip-arrow {
   bottom: -.2rem;
   left: 50%;
-  margin-left: calc(var(--ml-space-1) * -1);
+  margin-left: calc(var(--ml-space-1) * -1 - var(--ml-tooltip-shift, 0px));
 }
 
 .ml-tooltip[data-side="bottom"] .ml-tooltip-arrow {
   top: -.2rem;
   left: 50%;
-  margin-left: calc(var(--ml-space-1) * -1);
+  margin-left: calc(var(--ml-space-1) * -1 - var(--ml-tooltip-shift, 0px));
+}
+
+/* The arrow slides back by the tooltip's shift, so it keeps pointing at the trigger. */
+.ml-tooltip[data-side="left"] .ml-tooltip-arrow {
+  right: -.2rem;
+  top: 50%;
+  margin-top: calc(var(--ml-space-1) * -1 - var(--ml-tooltip-shift, 0px));
+}
+
+.ml-tooltip[data-side="right"] .ml-tooltip-arrow {
+  left: -.2rem;
+  top: 50%;
+  margin-top: calc(var(--ml-space-1) * -1 - var(--ml-tooltip-shift, 0px));
 }
 
 /* components/tour */

package/generated/theme-spec.schema.json

@@ -105,6 +105,14 @@
           ],
           "description": "Optional different seed for dark mode."
         },
+        "primaryForeground": {
+          "enum": [
+            "auto",
+            "light",
+            "dark"
+          ],
+          "description": "The label on primary fills in light mode. \"auto\" lets the engine choose; \"light\" or \"dark\" moves the fill as far as it must for that label to meet contrast."
+        },
         "neutral": {
           "type": "object",
           "properties": {

package/generated/themes.json

@@ -35,6 +35,7 @@
         "color": {
           "primary": "oklch(0.21 0.006 286)",
           "primaryDark": null,
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 286,
             "chroma": 0.004
@@ -83,6 +84,7 @@
         "color": {
           "primary": "oklch(0.55 0.16 58)",
           "primaryDark": "oklch(0.75 0.16 68)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 80,
             "chroma": 0.016
@@ -134,6 +136,7 @@
         "color": {
           "primary": "oklch(0.22 0.01 240)",
           "primaryDark": "oklch(0.78 0.15 210)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 240,
             "chroma": 0.004
@@ -185,6 +188,7 @@
         "color": {
           "primary": "oklch(0.55 0.24 285)",
           "primaryDark": "oklch(0.75 0.2 285)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 260,
             "chroma": 0.018
@@ -236,6 +240,7 @@
         "color": {
           "primary": "oklch(0.5 0.14 150)",
           "primaryDark": "oklch(0.72 0.15 150)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 135,
             "chroma": 0.018

package/generated/tokens.css

@@ -69,7 +69,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 742;
+  --ml-display-weight: 700;
   --ml-body-leading: 1.495;
   --ml-tracking: -0.0088em;
   --ml-icon-stroke: 1.974;
@@ -235,7 +235,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-newsreader, "Newsreader"), "Iowan Old Style", Georgia, serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 828;
+  --ml-display-weight: 800;
   --ml-body-leading: 1.536;
   --ml-tracking: -0.0133em;
   --ml-icon-stroke: 1.687;
@@ -399,7 +399,7 @@
   --ml-font-sans: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
   --ml-font-display: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 723;
+  --ml-display-weight: 700;
   --ml-body-leading: 1.47;
   --ml-tracking: -0.0076em;
   --ml-icon-stroke: 2.049;
@@ -563,7 +563,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 782;
+  --ml-display-weight: 800;
   --ml-body-leading: 1.558;
   --ml-tracking: -0.009em;
   --ml-icon-stroke: 1.736;
@@ -727,7 +727,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 792;
+  --ml-display-weight: 800;
   --ml-body-leading: 1.541;
   --ml-tracking: -0.011em;
   --ml-icon-stroke: 1.834;

package/generated/tokens.json

@@ -145,6 +145,7 @@
           "color": {
             "primary": "oklch(0.21 0.006 286)",
             "primaryDark": null,
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 286,
               "chroma": 0.004
@@ -1187,6 +1188,7 @@
           "color": {
             "primary": "oklch(0.55 0.16 58)",
             "primaryDark": "oklch(0.75 0.16 68)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 80,
               "chroma": 0.016
@@ -2232,6 +2234,7 @@
           "color": {
             "primary": "oklch(0.22 0.01 240)",
             "primaryDark": "oklch(0.78 0.15 210)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 240,
               "chroma": 0.004
@@ -3277,6 +3280,7 @@
           "color": {
             "primary": "oklch(0.55 0.24 285)",
             "primaryDark": "oklch(0.75 0.2 285)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 260,
               "chroma": 0.018
@@ -4322,6 +4326,7 @@
           "color": {
             "primary": "oklch(0.5 0.14 150)",
             "primaryDark": "oklch(0.72 0.15 150)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 135,
               "chroma": 0.018

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlola-ui/engine",
-  "version": "1.0.12",
+  "version": "1.1.0",
   "description": "Framework-free CSS, spring easings, and the machine-readable contract for Mlola UI",
   "type": "module",
   "sideEffects": [
@@ -21,7 +21,11 @@
     "./motion.css": "./generated/motion.css",
     "./accessibility.css": "./generated/accessibility.css",
     "./tokens.json": "./generated/tokens.json",
-    "./manifest.json": "./generated/manifest.json"
+    "./manifest.json": "./generated/manifest.json",
+    "./theme": {
+      "types": "./src/theme.d.ts",
+      "default": "./src/theme.mjs"
+    }
   },
   "scripts": {
     "build": "node build.mjs",

package/src/declarations.mjs

@@ -92,7 +92,9 @@ export function themeDeclarations(spec) {
     `--ml-font-sans: ${fonts.sans}`,
     `--ml-font-display: ${fonts.display}`,
     `--ml-font-mono: ${fonts.mono}`,
-    `--ml-display-weight: ${derived.displayWeight}`,
+    // Written as a whole hundred: a font that ships only static weights
+    // (400, 700, 900) would render 737 as the next weight up, often a heavy 900.
+    `--ml-display-weight: ${Math.round(derived.displayWeight / 100) * 100}`,
     `--ml-body-leading: ${round(derived.bodyLeading)}`,
     `--ml-tracking: ${round(derived.tracking, 4)}em`,
     `--ml-icon-stroke: ${round(derived.iconStroke)}`,

package/src/palette.mjs

@@ -63,22 +63,28 @@ const inkOn = (hue) => ({ L: 0.18, C: 0.02, H: hue });
 
 /**
  * Pick whichever of white or dark ink reads better on `fill`. If neither
- * reaches the target, move the fill until the better one does.
+ * reaches the target, move the fill until the better one does: it is the
+ * closer of the two, so the fill moves least. `preferDark` settles a tie.
  */
-function fillPair(fill, target, preferLight) {
-  let base = fill;
+function fillPair(fill, target, preferDark) {
   const dark = inkOn(fill.H);
-  const light = contrast(WHITE, base);
-  const deep = contrast(dark, base);
-  if (Math.max(light, deep) >= target) {
-    return { fill: base, foreground: light >= deep ? WHITE : dark };
-  }
-  if (preferLight ? deep > light : light >= deep) {
-    base = solveLightness(base, dark, target, "lighter");
-    return { fill: base, foreground: dark };
-  }
-  base = solveLightness(base, WHITE, target, "darker");
-  return { fill: base, foreground: WHITE };
+  const light = contrast(WHITE, fill);
+  const deep = contrast(dark, fill);
+  const useDark = deep > light || (deep === light && preferDark);
+  if (Math.max(light, deep) >= target) return { fill, foreground: useDark ? dark : WHITE };
+  if (useDark) return { fill: solveLightness(fill, dark, target, "lighter"), foreground: dark };
+  return { fill: solveLightness(fill, WHITE, target, "darker"), foreground: WHITE };
+}
+
+/**
+ * The label a theme asked for, and the fill moved (darker for white, lighter
+ * for dark ink) only as far as that label needs to meet the target. Light
+ * mode only: at night a fill dark enough for white would sink into the page.
+ */
+function fillFor(fill, foreground, target) {
+  const ink = foreground === "light" ? WHITE : inkOn(fill.H);
+  const moved = contrast(ink, fill) >= target ? fill : solveLightness(fill, ink, target, foreground === "light" ? "darker" : "lighter");
+  return { fill: moved, foreground: ink };
 }
 
 const tint = (hue, chroma, L) => ({ L, C: chroma, H: hue });
@@ -156,7 +162,9 @@ function primaryFor(spec, mode, neutrals) {
     fill = solveLightness(fill, neutrals.background, TARGETS.separation, mode === "light" ? "darker" : "lighter");
   }
   fill = deepenForWhite(fill, mode);
-  const pair = fillPair(fill, TARGETS.body, mode === "dark");
+  const pair = mode === "light" && spec.color.primaryForeground && spec.color.primaryForeground !== "auto"
+    ? fillFor(fill, spec.color.primaryForeground, TARGETS.body)
+    : fillPair(fill, TARGETS.body, mode === "dark");
   // Links and focus rings follow the brand. A monochrome brand inverted for
   // the night reads as the inverted ink, not a mid gray lifted from the day's.
   const textSeed = mode === "dark" && !spec.color.primaryDark && isAchromatic(seed) ? fill : seed;

package/src/spec.mjs

@@ -133,6 +133,9 @@ export const PALETTE_TOKENS = [
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{0,47}$/;
 
+/** What a theme may ask for on primary fills: the engine's choice, white, or dark ink. */
+const FOREGROUNDS = ["auto", "light", "dark"];
+
 const DEFAULT_SPEC = {
   specVersion: SPEC_VERSION,
   id: "custom",
@@ -141,6 +144,7 @@ const DEFAULT_SPEC = {
   color: {
     primary: "oklch(0.21 0.006 286)",
     primaryDark: null,
+    primaryForeground: "auto",
     neutral: { hue: 286, chroma: 0.004 },
     ink: null,
   },
@@ -227,6 +231,7 @@ export function normalizeSpec(input = {}, base = DEFAULT_SPEC) {
     color: {
       primary: readColor(color.primary ?? legacySignal, base.color.primary),
       primaryDark: readColor(color.primaryDark ?? legacySignalDark, base.color.primaryDark ?? null),
+      primaryForeground: FOREGROUNDS.includes(color.primaryForeground) ? color.primaryForeground : (base.color.primaryForeground ?? "auto"),
       neutral: readTint(color.neutral, base.color.neutral),
       ink: color.ink === null ? null : readTint(color.ink, base.color.ink ?? null),
     },
@@ -255,6 +260,9 @@ export function validateSpec(input) {
   if (input.color?.primaryDark != null && !parseColor(input.color.primaryDark)) {
     problems.push("color.primaryDark must be an oklch() or hex color, or null.");
   }
+  if (input.color?.primaryForeground !== undefined && !FOREGROUNDS.includes(input.color.primaryForeground)) {
+    problems.push(`color.primaryForeground must be one of ${FOREGROUNDS.join(", ")}.`);
+  }
   const neutral = input.color?.neutral;
   if (!neutral || typeof neutral.hue !== "number" || typeof neutral.chroma !== "number" || neutral.chroma < 0 || neutral.chroma > 0.06) {
     problems.push("color.neutral needs a hue and a chroma from 0 to 0.06.");
@@ -302,6 +310,10 @@ export function renderSpecSchema() {
         properties: {
           primary: { type: "string", description: "Seed for the primary color, oklch() or hex. Lightness is adjusted to meet contrast." },
           primaryDark: { type: ["string", "null"], description: "Optional different seed for dark mode." },
+          primaryForeground: {
+            enum: FOREGROUNDS,
+            description: "The label on primary fills in light mode. \"auto\" lets the engine choose; \"light\" or \"dark\" moves the fill as far as it must for that label to meet contrast.",
+          },
           neutral: { ...tint, description: "Tint of the page and surfaces." },
           ink: { anyOf: [tint, { type: "null" }], description: "Tint of text and dark-mode surfaces. Defaults to neutral." },
         },

package/src/theme.d.ts

@@ -0,0 +1,17 @@
+/** A project theme: a theme spec plus `inherit`, `scale` and `extend`. See https://ui.mlola.com/docs/theming#custom. */
+export type ThemeInput = Record<string, unknown>;
+
+export interface ProjectTheme extends Record<string, unknown> {
+  /** The theme's id: its `data-theme` value. */
+  id: string;
+  label: string;
+  /** The canonical theme whose decisions fill what the file leaves out. */
+  inherit: string;
+}
+
+export const THEME_CHANNELS: readonly string[];
+/** The spec with every default filled in. */
+export function defineTheme(input?: ThemeInput): ProjectTheme;
+/** The theme's CSS, on the same `data-theme` contract as every canonical theme. */
+export function renderThemeCss(input: ThemeInput): string;
+export function renderThemeManifest(projectThemeInput?: ThemeInput | null): Array<Record<string, unknown>>;