@mlola-ui/registry 1.0.0

package/snapshot/items/components/tooltip.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../schema/registry-item.schema.json",
+  "schemaVersion": 2,
+  "name": "tooltip",
+  "type": "registry:ui",
+  "title": "Tooltip",
+  "description": "Hover and focus tooltip with four placements, delay, and arrow",
+  "category": "overlays",
+  "variants": [],
+  "sizes": [],
+  "placements": [
+    "top",
+    "bottom",
+    "left",
+    "right"
+  ],
+  "tags": [
+    "overlay",
+    "hint",
+    "interactive"
+  ],
+  "usage": {
+    "importPath": "{{aliases.components}}/tooltip",
+    "exportName": "Tooltip",
+    "isDefault": false
+  },
+  "registryDependencies": [],
+  "engineDependencies": {},
+  "files": [
+    {
+      "path": "packages/components/_internal/react.ts",
+      "target": "{{aliases.components}}/_internal/react.ts",
+      "type": "registry:ui",
+      "integrity": "sha256-SH63/haiB4Q93uFjMIMe5xZbaxENu3VI+GcidV8HELM="
+    },
+    {
+      "path": "packages/components/tooltip/tooltip.tsx",
+      "target": "{{aliases.components}}/tooltip.tsx",
+      "type": "registry:ui",
+      "integrity": "sha256-NbaOUmlUbBlUIdovchrWwH2QqzuvXB97DjnJnrHf4Gc="
+    }
+  ],
+  "themeContract": {
+    "attribute": "data-theme",
+    "modeAttribute": "data-mode",
+    "compatibleThemes": [
+      "graphite",
+      "atelier",
+      "machined",
+      "aerogel",
+      "nordic"
+    ]
+  }
+}

package/snapshot/items/components/tour.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "../schema/registry-item.schema.json",
+  "schemaVersion": 2,
+  "name": "tour",
+  "type": "registry:ui",
+  "title": "Tour",
+  "description": "A guided product tour that spotlights parts of the page step by step, with keyboard control and a focus trap",
+  "category": "overlays",
+  "tags": [
+    "tour",
+    "onboarding",
+    "walkthrough",
+    "spotlight",
+    "coach marks"
+  ],
+  "usage": {
+    "importPath": "{{aliases.components}}/tour",
+    "exportName": "Tour",
+    "isDefault": false
+  },
+  "registryDependencies": [],
+  "engineDependencies": {
+    "@mlola-ui/icons": "^1.0.0"
+  },
+  "files": [
+    {
+      "path": "packages/components/_internal/anchor.ts",
+      "target": "{{aliases.components}}/_internal/anchor.ts",
+      "type": "registry:ui",
+      "integrity": "sha256-Jo9N3iIaWnS1CJzYhgTv7vnW+8MLyzL8X4GRNjeEp+g="
+    },
+    {
+      "path": "packages/components/_internal/floating.ts",
+      "target": "{{aliases.components}}/_internal/floating.ts",
+      "type": "registry:ui",
+      "integrity": "sha256-+WxgC4CtAlSr2qA1EkoDTgto535XLIPsvtOfdOK6CHk="
+    },
+    {
+      "path": "packages/components/_internal/react.ts",
+      "target": "{{aliases.components}}/_internal/react.ts",
+      "type": "registry:ui",
+      "integrity": "sha256-SH63/haiB4Q93uFjMIMe5xZbaxENu3VI+GcidV8HELM="
+    },
+    {
+      "path": "packages/components/tour/tour.tsx",
+      "target": "{{aliases.components}}/tour.tsx",
+      "type": "registry:ui",
+      "integrity": "sha256-1aSh7hMVt/DM/kH3WGJzJMGNsNqYEOmnwAZwc8dwRv8="
+    }
+  ],
+  "themeContract": {
+    "attribute": "data-theme",
+    "modeAttribute": "data-mode",
+    "compatibleThemes": [
+      "graphite",
+      "atelier",
+      "machined",
+      "aerogel",
+      "nordic"
+    ]
+  }
+}

package/snapshot/items/components/virtual-list.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../schema/registry-item.schema.json",
+  "schemaVersion": 2,
+  "name": "virtual-list",
+  "type": "registry:ui",
+  "title": "Virtual List",
+  "description": "A long list that renders only what is on screen, measures rows of any height and loads more near the end",
+  "category": "data",
+  "tags": [
+    "virtual",
+    "list",
+    "infinite",
+    "scroll",
+    "performance"
+  ],
+  "usage": {
+    "importPath": "{{aliases.components}}/virtual-list",
+    "exportName": "VirtualList",
+    "isDefault": false
+  },
+  "registryDependencies": [],
+  "engineDependencies": {},
+  "files": [
+    {
+      "path": "packages/components/_internal/react.ts",
+      "target": "{{aliases.components}}/_internal/react.ts",
+      "type": "registry:ui",
+      "integrity": "sha256-SH63/haiB4Q93uFjMIMe5xZbaxENu3VI+GcidV8HELM="
+    },
+    {
+      "path": "packages/components/virtual-list/virtual-list.tsx",
+      "target": "{{aliases.components}}/virtual-list.tsx",
+      "type": "registry:ui",
+      "integrity": "sha256-raGEFn4HlAOIohqZcy0DgptsnUIPS/6bWLYeTe+M9E8="
+    },
+    {
+      "path": "packages/components/virtual-list/virtual.ts",
+      "target": "{{aliases.components}}/virtual-list/virtual.ts",
+      "type": "registry:ui",
+      "integrity": "sha256-PyDIj3C2Vwb1i4ZssxSlYjgKmZPBIFLZFNq8YCW2Z78="
+    }
+  ],
+  "themeContract": {
+    "attribute": "data-theme",
+    "modeAttribute": "data-mode",
+    "compatibleThemes": [
+      "graphite",
+      "atelier",
+      "machined",
+      "aerogel",
+      "nordic"
+    ]
+  }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+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 };
+}

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

@@ -0,0 +1,142 @@
+import * as React from "react";
+import { lockScroll } from "@mlola-ui/behavior/document";
+
+const FOCUSABLE =
+  'a[href],area[href],button:not([disabled]),input:not([disabled]):not([type="hidden"]),select:not([disabled]),textarea:not([disabled]),iframe,[contenteditable="true"],[tabindex]:not([tabindex="-1"])';
+
+type HiddenSnapshot = {
+  count: number;
+  inert: boolean;
+  ariaHidden: string | null;
+};
+
+const hiddenElements = new Map<HTMLElement, HiddenSnapshot>();
+
+function hideBackground(portal: HTMLElement) {
+  const children = Array.from(document.body.children).filter(
+    (child): child is HTMLElement => child instanceof HTMLElement && child !== portal
+  );
+  for (const element of children) {
+    const existing = hiddenElements.get(element);
+    if (existing) {
+      existing.count += 1;
+      continue;
+    }
+    hiddenElements.set(element, {
+      count: 1,
+      inert: element.inert,
+      ariaHidden: element.getAttribute("aria-hidden"),
+    });
+    element.inert = true;
+    element.setAttribute("aria-hidden", "true");
+  }
+  return () => {
+    for (const element of children) {
+      const snapshot = hiddenElements.get(element);
+      if (!snapshot) continue;
+      snapshot.count -= 1;
+      if (snapshot.count > 0) continue;
+      element.inert = snapshot.inert;
+      if (snapshot.ariaHidden === null) element.removeAttribute("aria-hidden");
+      else element.setAttribute("aria-hidden", snapshot.ariaHidden);
+      hiddenElements.delete(element);
+    }
+  };
+}
+
+export function useDialogLayer({
+  open,
+  onClose,
+  closeOnEscape,
+  panelRef,
+}: {
+  open: boolean;
+  onClose: () => void;
+  closeOnEscape: boolean;
+  panelRef: React.RefObject<HTMLElement | null>;
+}) {
+  const [portal, setPortal] = React.useState<HTMLDivElement | null>(null);
+  const restoreFocusRef = React.useRef<HTMLElement | null>(null);
+  const closeRef = React.useRef(onClose);
+  closeRef.current = onClose;
+
+  React.useEffect(() => {
+    const node = document.createElement("div");
+    node.setAttribute("data-ml-portal", "");
+    document.body.appendChild(node);
+    setPortal(node);
+    return () => {
+      node.remove();
+      setPortal(null);
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (!open || !portal) return;
+    restoreFocusRef.current =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const releaseScroll = lockScroll();
+    const restoreBackground = hideBackground(portal);
+    const focusPanel = () => {
+      const panel = panelRef.current;
+      if (!panel) return;
+      const first = panel.querySelector<HTMLElement>(FOCUSABLE);
+      (first ?? panel).focus();
+    };
+    const frame = requestAnimationFrame(focusPanel);
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      const panel = panelRef.current;
+      if (!panel) return;
+      if (event.key === "Escape" && closeOnEscape) {
+        event.preventDefault();
+        closeRef.current();
+        return;
+      }
+      if (event.key !== "Tab") return;
+      const focusables = Array.from(panel.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+        (element) =>
+          !element.hidden &&
+          element.getAttribute("aria-hidden") !== "true" &&
+          element.tabIndex >= 0
+      );
+      if (focusables.length === 0) {
+        event.preventDefault();
+        panel.focus();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      if (event.shiftKey && (document.activeElement === first || document.activeElement === panel)) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    const onFocusIn = (event: FocusEvent) => {
+      const panel = panelRef.current;
+      if (!panel || !(event.target instanceof Element) || panel.contains(event.target)) return;
+      // Menus and lists opened from inside the dialog live in their own layer on <body>; focus may go there.
+      const layer = event.target.closest("[data-ml-portal]");
+      if (layer && layer !== portal) return;
+      focusPanel();
+    };
+
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("focusin", onFocusIn);
+    return () => {
+      cancelAnimationFrame(frame);
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("focusin", onFocusIn);
+      releaseScroll();
+      restoreBackground();
+      const target = restoreFocusRef.current;
+      if (target?.isConnected) requestAnimationFrame(() => target.focus());
+    };
+  }, [open, portal, closeOnEscape, panelRef]);
+
+  return portal;
+}

package/snapshot/source/packages/components/_internal/floating.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import * as React from "react";
+import { placeFloating, type Align, type Side } from "./anchor";
+
+export type { Align, Side };
+
+/**
+ * Keep a fixed-position layer next to its anchor while open: on open, on
+ * scroll anywhere, on resize, and whenever either element changes size.
+ * Writes styles directly, so following a scroll never re-renders React.
+ */
+export function useFloating(
+  anchor: React.RefObject<Element | null>,
+  floating: React.RefObject<HTMLElement | null>,
+  open: boolean,
+  options: { side?: Side; align?: Align; offset?: number },
+) {
+  const { side, align, offset } = options;
+  React.useLayoutEffect(() => {
+    const layer = floating.current;
+    if (!open || !layer) return;
+    let frame = 0;
+    // A layer on <body> takes the theme of the place it opened from, which may be a themed canvas rather than the page.
+    const themed = anchor.current?.closest<HTMLElement>("[data-theme]");
+    const moded = anchor.current?.closest<HTMLElement>("[data-mode]");
+    if (themed?.dataset.theme) layer.dataset.theme = themed.dataset.theme;
+    if (moded?.dataset.mode) layer.dataset.mode = moded.dataset.mode;
+    const update = () => {
+      const target = anchor.current;
+      if (!target || !layer.isConnected) return;
+      const rect = target.getBoundingClientRect();
+      const place = placeFloating(
+        { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+        { width: layer.offsetWidth, height: layer.offsetHeight },
+        { width: window.innerWidth, height: window.innerHeight },
+        { side, align, offset },
+      );
+      layer.style.left = `${place.x}px`;
+      layer.style.top = `${place.y}px`;
+      layer.dataset.side = place.side;
+    };
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(update);
+    };
+    update();
+    window.addEventListener("scroll", schedule, true);
+    window.addEventListener("resize", schedule);
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+    observer?.observe(layer);
+    if (anchor.current) observer?.observe(anchor.current);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("scroll", schedule, true);
+      window.removeEventListener("resize", schedule);
+      observer?.disconnect();
+    };
+  }, [anchor, floating, open, side, align, offset]);
+}
+
+/** A node on <body> for layers that must escape overflow and stacking. */
+export function usePortalNode() {
+  const [node, setNode] = React.useState<HTMLElement | null>(null);
+  React.useEffect(() => {
+    const element = document.createElement("div");
+    element.setAttribute("data-ml-portal", "");
+    document.body.appendChild(element);
+    setNode(element);
+    return () => element.remove();
+  }, []);
+  return node;
+}

package/snapshot/source/packages/components/_internal/match.ts

@@ -0,0 +1,39 @@
+/**
+ * Rank a command against a query the way people type: a prefix beats the
+ * start of a later word, which beats a substring, which beats letters in
+ * order ("dkm" → "Dark mode"). Returns null for no match, and the matched
+ * character positions so the view can bold them.
+ */
+export interface CommandMatch {
+  score: number;
+  positions: number[];
+}
+
+export function matchCommand(label: string, query: string, keywords: string[] = []): CommandMatch | null {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return { score: 0, positions: [] };
+  const text = label.toLowerCase();
+  const range = (start: number) => Array.from({ length: needle.length }, (_, index) => start + index);
+
+  if (text.startsWith(needle)) return { score: 100 - text.length * 0.1, positions: range(0) };
+  const wordStart = text.search(new RegExp(`\\b${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`));
+  if (wordStart > 0) return { score: 80 - wordStart * 0.5, positions: range(wordStart) };
+  const inside = text.indexOf(needle);
+  if (inside >= 0) return { score: 60 - inside * 0.5, positions: range(inside) };
+  if (keywords.some((keyword) => keyword.toLowerCase().includes(needle))) return { score: 45, positions: [] };
+
+  // Letters in order, preferring word starts and runs.
+  const positions: number[] = [];
+  let from = 0;
+  let bonus = 0;
+  for (const char of needle) {
+    const found = text.indexOf(char, from);
+    if (found < 0) return null;
+    if (found === 0 || text[found - 1] === " ") bonus += 3;
+    if (positions.length && found === positions[positions.length - 1] + 1) bonus += 2;
+    positions.push(found);
+    from = found + 1;
+  }
+  const spread = positions[positions.length - 1] - positions[0];
+  return { score: 20 + bonus - spread * 0.2, positions };
+}

package/snapshot/source/packages/components/_internal/react.ts

@@ -0,0 +1,40 @@
+import * as React from "react";
+
+export type ClassNameValue = string | false | null | undefined;
+
+export function cx(...values: ClassNameValue[]): string {
+  return values.filter(Boolean).join(" ");
+}
+
+export function composeRefs<T>(
+  ...refs: Array<React.ForwardedRef<T> | undefined>
+): (node: T | null) => void {
+  return (node) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    }
+  };
+}
+
+export function useControllableState<T>({
+  value,
+  defaultValue,
+  onChange,
+}: {
+  value: T | undefined;
+  defaultValue: T;
+  onChange?: (value: T) => void;
+}): [T, (value: T) => void] {
+  const [internal, setInternal] = React.useState(defaultValue);
+  const controlled = value !== undefined;
+  const current = controlled ? value : internal;
+  const setValue = React.useCallback(
+    (next: T) => {
+      if (!controlled) setInternal(next);
+      onChange?.(next);
+    },
+    [controlled, onChange]
+  );
+  return [current, setValue];
+}

package/snapshot/source/packages/components/_internal/scroll.ts

@@ -0,0 +1,15 @@
+/**
+ * Bring `element` into view inside `scroller` only. Unlike scrollIntoView, it
+ * never scrolls the page or any other ancestor, so a component that follows
+ * its active item cannot move the reader's place on first render.
+ */
+export function revealIn(scroller: HTMLElement | null, element: HTMLElement | null, axis: "x" | "y" = "y") {
+  if (!scroller || !element) return;
+  const box = scroller.getBoundingClientRect();
+  const rect = element.getBoundingClientRect();
+  if (axis === "x") {
+    if (rect.left < box.left) scroller.scrollLeft -= box.left - rect.left;
+    else if (rect.right > box.right) scroller.scrollLeft += rect.right - box.right;
+  } else if (rect.top < box.top) scroller.scrollTop -= box.top - rect.top;
+  else if (rect.bottom > box.bottom) scroller.scrollTop += rect.bottom - box.bottom;
+}