mlola-ui 1.0.4 → 1.0.6

package/registry/source/packages/components/_internal/anchor.ts

@@ -1,54 +1,5 @@
 /**
- * Where a floating layer goes next to its anchor, as a pure function of
- * rectangles: prefer the requested side, flip when it does not fit, and shift
- * along the edge to stay inside the viewport. No DOM, so it is testable.
+ * Where a floating layer goes next to its anchor. The math is shared with the
+ * framework-free runtime, so it lives in @mlola-ui/behavior/logic.
  */
-export type Side = "top" | "bottom" | "left" | "right";
-export type Align = "start" | "center" | "end";
-
-export interface Rect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-export interface Placement {
-  x: number;
-  y: number;
-  side: Side;
-}
-
-const OPPOSITE: Record<Side, Side> = { top: "bottom", bottom: "top", left: "right", right: "left" };
-
-export function placeFloating(
-  anchor: Rect,
-  floating: { width: number; height: number },
-  viewport: { width: number; height: number },
-  { side = "bottom", align = "center", offset = 8, padding = 8 }: { side?: Side; align?: Align; offset?: number; padding?: number } = {},
-): Placement {
-  const room: Record<Side, number> = {
-    top: anchor.y - padding,
-    bottom: viewport.height - (anchor.y + anchor.height) - padding,
-    left: anchor.x - padding,
-    right: viewport.width - (anchor.x + anchor.width) - padding,
-  };
-  const needs = (candidate: Side) => (candidate === "top" || candidate === "bottom" ? floating.height : floating.width) + offset;
-  let chosen = side;
-  if (room[side] < needs(side) && room[OPPOSITE[side]] > room[side]) chosen = OPPOSITE[side];
-
-  const vertical = chosen === "top" || chosen === "bottom";
-  let x: number;
-  let y: number;
-  if (vertical) {
-    y = chosen === "bottom" ? anchor.y + anchor.height + offset : anchor.y - floating.height - offset;
-    x = align === "start" ? anchor.x : align === "end" ? anchor.x + anchor.width - floating.width : anchor.x + anchor.width / 2 - floating.width / 2;
-  } else {
-    x = chosen === "right" ? anchor.x + anchor.width + offset : anchor.x - floating.width - offset;
-    y = align === "start" ? anchor.y : align === "end" ? anchor.y + anchor.height - floating.height : anchor.y + anchor.height / 2 - floating.height / 2;
-  }
-  // Shift along the edge to stay on screen.
-  x = Math.min(Math.max(x, padding), Math.max(padding, viewport.width - floating.width - padding));
-  y = Math.min(Math.max(y, padding), Math.max(padding, viewport.height - floating.height - padding));
-  return { x: Math.round(x), y: Math.round(y), side: chosen };
-}
+export { placeFloating, type Align, type Placement, type Rect, type Side } from "@mlola-ui/behavior/logic";

package/registry/source/packages/components/_internal/dialog.ts

@@ -44,6 +44,24 @@ function hideBackground(portal: HTMLElement) {
   };
 }
 
+// Safari does not focus a button it clicks, so when a dialog opens with
+// nothing focused, focus returns on close to the control just pressed.
+let lastPressed: HTMLElement | null = null;
+let pressedAt = 0;
+let tracking = false;
+function trackPresses() {
+  if (tracking) return;
+  tracking = true;
+  document.addEventListener(
+    "pointerdown",
+    (event) => {
+      lastPressed = event.target instanceof Element ? event.target.closest<HTMLElement>(FOCUSABLE) : null;
+      pressedAt = performance.now();
+    },
+    true,
+  );
+}
+
 export function useDialogLayer({
   open,
   onClose,
@@ -61,6 +79,7 @@ export function useDialogLayer({
   closeRef.current = onClose;
 
   React.useEffect(() => {
+    trackPresses();
     const node = document.createElement("div");
     node.setAttribute("data-ml-portal", "");
     document.body.appendChild(node);
@@ -73,8 +92,13 @@ export function useDialogLayer({
 
   React.useEffect(() => {
     if (!open || !portal) return;
+    const active = document.activeElement;
     restoreFocusRef.current =
-      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+      active instanceof HTMLElement && active !== document.body
+        ? active
+        : lastPressed?.isConnected && performance.now() - pressedAt < 2000
+          ? lastPressed
+          : null;
     const releaseScroll = lockScroll();
     const restoreBackground = hideBackground(portal);
     const focusPanel = () => {

package/registry/source/packages/components/avatar/avatar.tsx

@@ -47,7 +47,12 @@ const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
     return (
       <div ref={ref} role="group" aria-label={`Avatar group, ${items.length} people`} className={cx("ml-avatar-group", className)} {...props}>
         {visible.map((child, index) => <span key={index} className="ml-avatar-group-item">{child}</span>)}
-        {overflow ? <span aria-label={`${overflow} more people`} className="ml-avatar-overflow">+{overflow}</span> : null}
+        {overflow ? (
+          <span className="ml-avatar-overflow">
+            <span aria-hidden="true">+{overflow}</span>
+            <span className="ml-visually-hidden">{`${overflow} more ${overflow === 1 ? "person" : "people"}`}</span>
+          </span>
+        ) : null}
       </div>
     );
   }

package/registry/source/packages/components/calendar/calendar.tsx

@@ -257,7 +257,8 @@ export function Calendar(props: CalendarProps) {
               ))}
             </div>
             {monthGrid(first, weekStart).map((week) => (
-              <div key={week[0].date} role="row" className="ml-calendar-row">
+              // A week drawn only to keep months aligned has no day to read, so it is hidden whole.
+              <div key={week[0].date} role="row" className="ml-calendar-row" aria-hidden={(week.every(({ inMonth }) => !inMonth) && (!showOutsideDays || months > 1)) || undefined}>
                 {week.map(({ date, inMonth }) => {
                   if (!inMonth && (!showOutsideDays || months > 1)) return <span key={date} role="gridcell" className="ml-calendar-cell" aria-hidden="true" />;
                   const selected = isSelected(date);

package/registry/source/packages/components/kbd/kbd.tsx

@@ -43,12 +43,14 @@ export function Shortcut({ keys, className, ...props }: ShortcutProps) {
   const shown = parts.map((key) => SYMBOLS[key]?.[apple ? "apple" : "other"] ?? key.toUpperCase());
   const spoken = parts.map((key) => (apple ? SYMBOLS[key]?.spoken : SYMBOLS[key]?.spokenOther ?? SYMBOLS[key]?.spoken) ?? key.toUpperCase()).join(" ");
   return (
-    <kbd className={cx("ml-shortcut", className)} aria-label={spoken} {...props}>
+    <kbd className={cx("ml-shortcut", className)} {...props}>
       {shown.map((key, index) => (
         <kbd key={index} className="ml-kbd" aria-hidden="true">
           {key}
         </kbd>
       ))}
+      {/* A kbd cannot carry a label, so the words are text a screen reader reads. */}
+      <span className="ml-visually-hidden">{spoken}</span>
     </kbd>
   );
 }

package/registry/source/packages/components/modal/modal.tsx

@@ -12,6 +12,8 @@ export interface ModalProps {
   open: boolean;
   onClose: () => void;
   size?: ModalSize;
+  /** "alertdialog" for a confirmation that interrupts: it is announced at once, and the backdrop does not dismiss it. */
+  role?: "dialog" | "alertdialog";
   closeOnBackdrop?: boolean;
   closeOnEscape?: boolean;
   label?: string;
@@ -24,7 +26,8 @@ export function Modal({
   open,
   onClose,
   size = "md",
-  closeOnBackdrop = true,
+  role = "dialog",
+  closeOnBackdrop = role !== "alertdialog",
   closeOnEscape = true,
   label = "Dialog",
   description,
@@ -45,7 +48,7 @@ export function Modal({
     >
       <div
         ref={panelRef}
-        role="dialog"
+        role={role}
         aria-modal="true"
         aria-label={label}
         aria-describedby={description ? descriptionId : undefined}

package/registry/source/packages/components/resizable/resizable.tsx

@@ -134,7 +134,8 @@ export function Resizable({
         aria-valuemin={collapsible ? 0 : min}
         aria-valuemax={max}
         aria-valuenow={Math.round(shown)}
-        aria-expanded={collapsible ? !isFolded : undefined}
+        // A separator has no expanded state: folded is its value at 0.
+        aria-valuetext={isFolded ? "Collapsed" : undefined}
         className="ml-resizable-handle"
         onPointerDown={(event) => {
           dragging.current = true;

package/registry/source/packages/components/table/table.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import * as React from "react";
-import { cx } from "../_internal/react";
+import { composeRefs, cx } from "../_internal/react";
 
 type TableSize = "sm" | "md";
 type TableAlign = "left" | "center" | "right";
@@ -9,11 +9,33 @@ export type SortedState = "asc" | "desc" | false;
 interface Sortable { sorted: SortedState; onToggle: () => void; label?: string; }
 interface TableProps extends React.HTMLAttributes<HTMLDivElement> { size?: TableSize; striped?: boolean; }
 const Table = React.forwardRef<HTMLDivElement, TableProps>(
-  ({ size = "md", striped = false, className, children, ...props }, ref) => (
-    <div ref={ref} className={cx("ml-table-container", className)} {...props}>
-      <table data-size={size} data-striped={striped ? "" : undefined} className="ml-table">{children}</table>
-    </div>
-  )
+  ({ size = "md", striped = false, className, children, ...props }, ref) => {
+    // A table wider than its container scrolls sideways, and then the keyboard must reach it too.
+    const container = React.useRef<HTMLDivElement | null>(null);
+    const [scrolls, setScrolls] = React.useState(false);
+    React.useEffect(() => {
+      const element = container.current;
+      if (!element || typeof ResizeObserver === "undefined") return;
+      const measure = () => setScrolls(element.scrollWidth > element.clientWidth + 1);
+      const observer = new ResizeObserver(measure);
+      observer.observe(element);
+      if (element.firstElementChild) observer.observe(element.firstElementChild);
+      measure();
+      return () => observer.disconnect();
+    }, []);
+    const named = Boolean(props["aria-label"] || props["aria-labelledby"]);
+    return (
+      <div
+        ref={composeRefs(ref, container)}
+        className={cx("ml-table-container", className)}
+        tabIndex={scrolls ? 0 : undefined}
+        role={scrolls && named ? "region" : undefined}
+        {...props}
+      >
+        <table data-size={size} data-striped={striped ? "" : undefined} className="ml-table">{children}</table>
+      </div>
+    );
+  }
 );
 Table.displayName = "Table";
 const TableCaption = React.forwardRef<HTMLTableCaptionElement, React.HTMLAttributes<HTMLTableCaptionElement>>(

package/registry/source/packages/components/tag-input/tag-input.tsx

@@ -181,6 +181,7 @@ export const TagInput = React.forwardRef<HTMLInputElement, TagInputProps>(functi
         ref={control}
         className="ml-tag-input-control"
         data-disabled={disabled || undefined}
+        aria-disabled={disabled || undefined}
         data-invalid={message ? "" : undefined}
         onMouseDown={(event) => {
           // Clicking the field's empty space puts the caret in the input.

package/registry/source-manifest.json

@@ -1,6 +1,6 @@
 {
-  "packages/components/_internal/anchor.ts": "sha256-Jo9N3iIaWnS1CJzYhgTv7vnW+8MLyzL8X4GRNjeEp+g=",
-  "packages/components/_internal/dialog.ts": "sha256-Q7DPI2BipgFjPd3T8g2GGicrVal0cp0eMKXWFqcj64k=",
+  "packages/components/_internal/anchor.ts": "sha256-OPm/4Jf4UUo8IG+/4TAKpGDHtYpvxvGwyq3/RSZQIGc=",
+  "packages/components/_internal/dialog.ts": "sha256-796y3oNOVWarLvICTdi+d0/2axqSrzLVJiyBeh9X7bU=",
   "packages/components/_internal/floating.ts": "sha256-+WxgC4CtAlSr2qA1EkoDTgto535XLIPsvtOfdOK6CHk=",
   "packages/components/_internal/match.ts": "sha256-nKBpKWeow5ubAHUhOW8yOjlrKs0lqYdjbaYYfE8VoII=",
   "packages/components/_internal/react.ts": "sha256-SH63/haiB4Q93uFjMIMe5xZbaxENu3VI+GcidV8HELM=",
@@ -10,11 +10,11 @@
   "packages/components/activity-heatmap/calendar.ts": "sha256-NB+AjXY5Xc+KzR8MMTRBgZxdzOeoHhkW0KQOW7WJPuQ=",
   "packages/components/alert/alert.tsx": "sha256-j680akXvCIh4MTVnUo79acvVrv51XyQ3UBJ5FBAy8Dw=",
   "packages/components/app-shell/app-shell.tsx": "sha256-XAq82XOTH3ZR+hxTkYFu8P7Ih2aI6ERy/TpXc2VMUwM=",
-  "packages/components/avatar/avatar.tsx": "sha256-hvZUGhatN95ZyX6p6NBhTRf6h1/rrJ+bJrqBMtIspq0=",
+  "packages/components/avatar/avatar.tsx": "sha256-EjqC8ytKqRtsTVdK6vncaDfhO/i7ICe+jwaYCg5bjIw=",
   "packages/components/badge/badge.tsx": "sha256-flEH8S2jZ/64n3Y/ROhC9+9rvF7wXaN0xLcMMwqNOVQ=",
   "packages/components/breadcrumb/breadcrumb.tsx": "sha256-Mt9mvmwwDgdp5/+mj5byIrh8+hicsp7R6UcvUlK0yog=",
   "packages/components/button/button.tsx": "sha256-khqYxcV3hlZ+Q+cYNTRXEpAfIijDFSvkuDJXMPtlk7g=",
-  "packages/components/calendar/calendar.tsx": "sha256-uE22LI4jpU8ErR/oBmAkeKiu+Rp0bz3IXZVCurycpwc=",
+  "packages/components/calendar/calendar.tsx": "sha256-rWiS4YAueZfVoo6j5Fi3uN7A+yApe5U6HMm1woTVjys=",
   "packages/components/calendar/dates.ts": "sha256-mygYkoC70av2ZQ0vkxf885trwW97Wd10I4dptYQe+4A=",
   "packages/components/card/card.tsx": "sha256-aMKbv5DWYYWq7GZAFR9O1fuYE0H61WCjkvEbRMOd894=",
   "packages/components/carousel/carousel.tsx": "sha256-pamugpB6Ujt9Ylxd37jNF/ZwSb8iRkW/MoYe12nY3i4=",
@@ -30,8 +30,8 @@
   "packages/components/empty-state/empty-state.tsx": "sha256-uCKqYpr9vkozXZHpdl4GFtdX9ijcGOriCHvgyarBqRw=",
   "packages/components/hover-card/hover-card.tsx": "sha256-AyRbxfqDOYBgGlgjgrtQZm5DipArLEzQn6XnzjPd0ro=",
   "packages/components/input/input.tsx": "sha256-lbbheo+ydQTzyujTf0W7DD96TogOjifCyqj9c3h3W0g=",
-  "packages/components/kbd/kbd.tsx": "sha256-wrPqzn1e82zJYoKzO7u94Bgq4+nPc0DXLc8GJ/4/3nY=",
-  "packages/components/modal/modal.tsx": "sha256-vybxgBGYCrMYvJRnO1wDAc2VFQylu+mQIf5OZIcabX4=",
+  "packages/components/kbd/kbd.tsx": "sha256-e8EO2Gw6JiUyrU0YcEZOaQNMel1pe/EcJrxwwgd1Ggk=",
+  "packages/components/modal/modal.tsx": "sha256-rIytVY+hz8aabJ53UGQ0VADgSlW0sAG920iMQaoak+0=",
   "packages/components/number-input/number-input.tsx": "sha256-BDOyvCNtMULD/HK7uWHsYbGg79lrRDrVqtGQQrYHpmM=",
   "packages/components/number-input/number.ts": "sha256-IrHCQrEhI5ein9ifMFuSViSoxQUBoT3tNmmCu/paGGM=",
   "packages/components/otp-input/otp-input.tsx": "sha256-QURn8g5HqCQXBTdeENPbVxoPlqs3ZtoAPLRlFjQDxmI=",
@@ -42,7 +42,7 @@
   "packages/components/progress/progress.tsx": "sha256-9OjecRNPWn7Bfe+C5IyXaKsW1NJae6X5gco1o0X5XkE=",
   "packages/components/radio-group/radio-group.tsx": "sha256-jhnSEBLkdpe8dv5us/Q1sMsQF4sKGRgDXWGKm2JSFew=",
   "packages/components/rating/rating.tsx": "sha256-zgPOQXzAiRE4qGNPQ8qat3SP1XSI/7567kA5VaT51P0=",
-  "packages/components/resizable/resizable.tsx": "sha256-40sK2UyIR9Ek72KAu5nvbr44tKEY6JhC5Ftb++Wf6cI=",
+  "packages/components/resizable/resizable.tsx": "sha256-Yxlq88qElhv2Q5DooPdriZkawRS0QWx08nd6ybz5oeY=",
   "packages/components/segmented-control/segmented-control.tsx": "sha256-MCBG5XHFWCwbACctsYKbqe8mvSSR6pf60tyRgdCDKDA=",
   "packages/components/select/select.tsx": "sha256-m8QmKUGC4386XcklosSntal0XwUAFjKosTBQSF0dduQ=",
   "packages/components/sheet/sheet.tsx": "sha256-EIn3OeRDmXGHbYf/uihRh8aw3LmzarIFiyC9DUsL1jg=",
@@ -51,9 +51,9 @@
   "packages/components/status-icon/labels.ts": "sha256-EE8q+geQBbJUs7I3RmaHZnPwn7Vjk2GjCfxvI4ruXKM=",
   "packages/components/status-icon/status-icon.tsx": "sha256-TtrTeoePyfH1VhKuWC0v12FuwfgND1CHnH5x8fyf4AM=",
   "packages/components/stepper/stepper.tsx": "sha256-uI/dRmkbijlixHiGUceWcpaDzpEixrzQ1UTmoPbGZAY=",
-  "packages/components/table/table.tsx": "sha256-ed1Qn2sIpxRvGdPDAb5ih5AcXr5PmHTHdlrJLYDYRp8=",
+  "packages/components/table/table.tsx": "sha256-xJlWzCH76Lrgg/HrlnVTHkG5dfCkbzjWXEdTVG5Jk4w=",
   "packages/components/tabs/tabs.tsx": "sha256-kWAQjE9mshqZL7V3NJTUiurp6M5Nu3vx5O1LsIgdV5Y=",
-  "packages/components/tag-input/tag-input.tsx": "sha256-EK7xJTe3Y/S5Kn3vS0zBQg9lC+RVoGvky6HOAt+DnAw=",
+  "packages/components/tag-input/tag-input.tsx": "sha256-lc4ofz1/lUnb7B/GlFElVKXLbPwtJFAjE5vWwAY99fA=",
   "packages/components/textarea/textarea.tsx": "sha256-C9jMYZ63w+m6bgdLvHjvULRuoCe26q5zbgS4+ahWzr8=",
   "packages/components/time-picker/time-picker.tsx": "sha256-og8Cbf+e8oFYewfagUgjRzLHSIIlAZh+1OpAn9yNq70=",
   "packages/components/time-picker/times.ts": "sha256-V/4uqFZPn9gVnyx8cB9vwp/RocmTYaPmLxjfy8DPQOI=",

package/src/assets.js

@@ -10,6 +10,9 @@ import { BUNDLED_REGISTRY_ROOT, readJson } from "./registry.js";
  * Their files are not bundled with the CLI: a project wants three of them,
  * not every model. The bundled index lists each file with its integrity; the
  * files download from the site and are checked before anything is written.
+ * Each request names the integrity it expects, and the site answers with
+ * exactly those bytes, kept for every released version: an asset redrawn
+ * after this CLI was published still installs the version this CLI lists.
  *
  * Static files (SVG, GLB, posters) land in the `assets` target, public/mlola
  * by default, so a web app serves them as /mlola/2d/… and /mlola/3d/…. A 2D
@@ -43,7 +46,7 @@ export async function addAssets(cwd, config, ids, { source, fetcher, overwrite =
   for (const id of ids) {
     const item = known.get(id);
     for (const file of item.files) {
-      const url = `${source}/${item.kind}/${item.id}/${file.path}`;
+      const url = `${source}/${item.kind}/${item.id}/${file.path}?integrity=${encodeURIComponent(file.integrity)}`;
       let response;
       try {
         response = await fetcher(url);
@@ -52,7 +55,9 @@ export async function addAssets(cwd, config, ids, { source, fetcher, overwrite =
       }
       if (!response.ok) throw new Error(`Could not download ${url}: the server answered ${response.status}.`);
       const bytes = Buffer.from(await response.arrayBuffer());
-      if (integrityOf(bytes) !== file.integrity) throw new Error(`${item.id}/${file.path} failed integrity validation; nothing was written.`);
+      if (integrityOf(bytes) !== file.integrity) {
+        throw new Error(`${item.id}/${file.path} failed integrity validation; nothing was written. The server has a different version of this file: update the CLI (npx mlola-ui@latest) and try again.`);
+      }
       planned.push({ item, file, bytes, relative: assetTarget(config, item, file) });
     }
   }

package/src/knowledge.js

@@ -117,12 +117,25 @@ export function describeItem(name, { cwd = process.cwd(), includeSource = false
     category: item.category,
     variants: item.variants ?? [],
     sizes: item.sizes ?? [],
+    // Every prop with a fixed set of values, read from the TypeScript source.
+    options: item.options ?? [],
     usage,
     install: `npx mlola-ui add ${name}`,
     dependsOn: item.registryDependencies ?? [],
     engineDependencies: item.engineDependencies ?? {},
-    elements: elementsOf(name),
+    // Every class the component's stylesheet defines, when its example lists them.
+    elements: bundled("examples.json")?.[name]?.elements ?? elementsOf(name),
   };
+  // The same example the docs show: React, the HTML it renders, and the
+  // framework-free markup when @mlola-ui/behavior drives it.
+  const example = bundled("examples.json")?.[name];
+  if (example) {
+    result.example = {
+      react: example.react,
+      html: example.behavior?.html ?? example.html,
+      script: example.needs === "behavior" ? `@mlola-ui/behavior, data-ml="${example.behavior.name}"` : example.needs === "nothing" ? "none" : "React, or your own script setting the attributes",
+    };
+  }
   if (includeSource) {
     result.source = (item.files ?? [])
       .filter((file) => !file.path.includes("/_internal/"))
@@ -159,6 +172,63 @@ const SHARED = new Set(["data-tone", "data-variant", "data-size", "data-state",
 const UTILITY = /^(-?(m|p)[trblxy]?-\d|flex$|grid$|block$|inline|hidden$|items-|justify-|gap-|w-|h-|min-|max-|text-(xs|sm|base|lg|xl|\d|[a-z]+-\d)|font-(bold|medium|semibold|light)|bg-|border-|rounded|shadow|ring-|space-[xy]-|leading-|tracking-|opacity-|z-\d|absolute$|relative$|fixed$|sticky$|overflow-|col-span|row-span|sm:|md:|lg:|xl:|hover:|focus:|dark:)/;
 const COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i;
 
+/** Every opening tag in HTML or JSX, with its string-valued attributes. */
+function tagsOf(markup) {
+  const tags = [];
+  for (const match of markup.matchAll(/<([A-Za-z][\w.-]*)((?:\s+(?:[^\s"'>={}]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}))?))*)\s*\/?>/g)) {
+    const attributes = new Map();
+    for (const attribute of match[2].matchAll(/([^\s"'>={}]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\{(?:[^{}]|\{[^{}]*\})*\})))?/g)) {
+      const [, name, double, single, expression] = attribute;
+      const value = double ?? single ?? (expression ? /^\{\s*["'`]([^"'`$]*)["'`]\s*\}$/.exec(expression)?.[1] ?? null : "");
+      attributes.set(name, value);
+      if (expression) attributes.set(`${name}:raw`, expression);
+    }
+    const classValue = attributes.get("class") ?? attributes.get("className");
+    tags.push({ tag: match[0], attributes, classes: typeof classValue === "string" ? classValue.split(/\s+/).filter(Boolean) : [] });
+  }
+  return tags;
+}
+
+let knownValues = null;
+/**
+ * The values each element may carry on each shared attribute: the ones its
+ * stylesheet draws, the ones its component's props declare, and the ones the
+ * component renders in its example. A default such as data-size="md" is
+ * rendered but not drawn, and is as correct as any other.
+ */
+function valuesByElement() {
+  if (knownValues) return knownValues;
+  knownValues = new Map();
+  const add = (cls, attribute, values) => {
+    if (!knownValues.has(cls)) knownValues.set(cls, new Map());
+    const byAttribute = knownValues.get(cls);
+    if (!byAttribute.has(attribute)) byAttribute.set(attribute, new Set());
+    for (const value of values) byAttribute.get(attribute).add(value);
+  };
+  for (const [cls, attributes] of Object.entries(bundled("contract.json")?.elements ?? {})) {
+    for (const [attribute, values] of Object.entries(attributes)) add(cls, attribute, values);
+  }
+  const examples = bundled("examples.json") ?? {};
+  for (const item of loadRegistry().items) {
+    const classes = examples[item.name]?.elements?.map((element) => element.class) ?? [];
+    for (const option of item.options ?? []) {
+      for (const cls of classes) add(cls, `data-${option.prop}`, option.values);
+    }
+  }
+  for (const example of Object.values(examples)) {
+    for (const html of [example.html, example.behavior?.html]) {
+      if (!html) continue;
+      for (const { attributes, classes } of tagsOf(html)) {
+        for (const [name, value] of attributes) {
+          if (!SHARED.has(name) || typeof value !== "string") continue;
+          for (const cls of classes) if (cls.startsWith("ml-")) add(cls, name, [value]);
+        }
+      }
+    }
+  }
+  return knownValues;
+}
+
 /**
  * Checks HTML or JSX against the element contract. It reads string-valued
  * class, className, style and data-* attributes; expressions in braces are
@@ -169,20 +239,12 @@ export function checkMarkup(markup) {
   const known = new Set(contract?.classes ?? []);
   const proPrefixes = (bundled("catalog.json")?.items ?? []).map((item) => `ml-${item.name}`);
   const themeIds = new Set(themes().map((theme) => theme.id));
+  const tokenNames = new Set((designData()?.tokens ?? []).flatMap((group) => group.names));
+  const values = valuesByElement();
   const issues = [];
   const note = (severity, tag, message, fix) => issues.push({ severity, element: tag.slice(0, 120), message, ...(fix ? { fix } : {}) });
 
-  for (const match of markup.matchAll(/<([A-Za-z][\w.-]*)((?:\s+(?:[^\s"'>={}]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}))?))*)\s*\/?>/g)) {
-    const tag = match[0];
-    const attributes = new Map();
-    for (const attribute of match[2].matchAll(/([^\s"'>={}]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\{(?:[^{}]|\{[^{}]*\})*\})))?/g)) {
-      const [, name, double, single, expression] = attribute;
-      const value = double ?? single ?? (expression ? /^\{\s*["'`]([^"'`$]*)["'`]\s*\}$/.exec(expression)?.[1] ?? null : "");
-      attributes.set(name, value);
-      if (expression) attributes.set(`${name}:raw`, expression);
-    }
-    const classValue = attributes.get("class") ?? attributes.get("className");
-    const classes = typeof classValue === "string" ? classValue.split(/\s+/).filter(Boolean) : [];
+  for (const { tag, attributes, classes } of tagsOf(markup)) {
     const mlola = classes.filter((cls) => cls.startsWith("ml-"));
 
     for (const cls of mlola) {
@@ -210,25 +272,27 @@ export function checkMarkup(markup) {
       }
       if (!SHARED.has(name) || !mlola.length) continue;
       const allowed = new Set();
-      let reacts = false;
-      for (const cls of mlola) {
-        const values = contract?.elements?.[cls]?.[name];
-        if (values) {
-          reacts = true;
-          for (const entry of values) allowed.add(entry);
-        }
-      }
-      if (reacts && allowed.size && !allowed.has(value)) {
-        note("error", tag, `${name}="${value}" is not a value ${mlola.join(" ")} reacts to.`, `Allowed: ${[...allowed].sort().join(", ")}.`);
-      } else if (!reacts && mlola.every((cls) => known.has(cls))) {
+      for (const cls of mlola) for (const entry of values.get(cls)?.get(name) ?? []) allowed.add(entry);
+      if (allowed.size && !allowed.has(value)) {
+        note("error", tag, `${name}="${value}" is not a value ${mlola.join(" ")} takes.`, `Allowed: ${[...allowed].sort().join(", ")}.`);
+      } else if (!allowed.size && mlola.every((cls) => known.has(cls))) {
         note("warning", tag, `${name} has no effect on ${mlola.join(" ")}.`, `See get_component for the attributes it reacts to.`);
       }
     }
 
-    // A style string, or a JSX style object, with a color written into it.
+    // A color written by hand in a style string or a JSX style object. A
+    // component's own custom property carries data (a swatch's color); a
+    // theme token set inline overrides the theme and is flagged too.
     const style = attributes.get("style") ?? attributes.get("style:raw");
-    if (typeof style === "string" && COLOR.test(style)) {
-      note("error", tag, "A color is written by hand in style.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).");
+    if (typeof style === "string") {
+      const overridden = [...style.matchAll(/(--ml-[\w-]+)\s*:/g)].map((match) => match[1]).filter((token) => tokenNames.has(token));
+      const declarations = style.replace(/--[\w-]+\s*:[^;,}]*/g, "");
+      if (COLOR.test(declarations)) {
+        note("error", tag, "A color is written by hand in style.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).");
+      }
+      if (overridden.length) {
+        note("error", tag, `${overridden.join(", ")} is a theme token; setting it inline overrides the theme.`, "Pick a theme, or change the theme's spec (mlola.theme.json), instead of one element's tokens.");
+      }
     }
   }
   return issues;

package/src/mcp.js

@@ -66,7 +66,7 @@ function tools({ cwd, run }) {
     {
       name: "get_component",
       title: "How to use a Mlola component",
-      description: "Everything needed to use one item: import, variants, sizes, the classes it styles and the data-* values each reacts to, dependencies and the install command. Set include_source to read a free component's source.",
+      description: "Everything needed to use one item: import, every prop with fixed values (variant, tone, size, side…) and its default, the classes it styles and the data-* values each reacts to, dependencies and the install command. Set include_source to read a free component's source.",
       inputSchema: {
         type: "object",
         properties: { name: { type: "string" }, include_source: { type: "boolean", default: false } },