@mlola-ui/registry 1.0.0

package/snapshot/source/packages/components/toast/toast.tsx

@@ -0,0 +1,317 @@
+"use client";
+
+import * as React from "react";
+import { IconCircleCheck, IconCircleX, IconInfo, IconTriangleAlert, IconX } from "@mlola-ui/icons";
+import { cx } from "../_internal/react";
+
+/** The meaning of the message, from the theme's colour roles. */
+export type ToastTone = "neutral" | "info" | "success" | "warning" | "danger";
+export type ToastPosition = "top-right" | "top-center" | "bottom-right" | "bottom-center";
+
+interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+
+interface ToastOptions {
+  /** A second line under the message. */
+  description?: string;
+  /** Milliseconds on screen. 0 or Infinity keeps it until dismissed. Loading toasts never time out. */
+  duration?: number;
+  position?: ToastPosition;
+  tone?: ToastTone;
+  action?: ToastAction;
+  /** Replaces the tone's icon. `null` shows none. */
+  icon?: React.ReactNode;
+}
+
+interface ToastItem {
+  id: number;
+  message: string;
+  description?: string;
+  tone: ToastTone;
+  /** Waiting on work: a spinner, no timeout, until updated. */
+  loading: boolean;
+  duration: number;
+  position: ToastPosition;
+  action?: ToastAction;
+  icon?: React.ReactNode;
+  /** Bumped on every update, so a changed toast restarts its timer. */
+  revision: number;
+  closing: boolean;
+}
+
+type ToastListener = (toasts: ToastItem[]) => void;
+
+const DEFAULT_DURATION = 5000;
+/** Problems stay longer: they are the toasts people most need to read. */
+const URGENT_DURATION = 8000;
+
+function durationFor(tone: ToastTone, loading: boolean, requested?: number) {
+  if (loading) return Infinity;
+  if (requested !== undefined) return requested;
+  return tone === "danger" || tone === "warning" ? URGENT_DURATION : DEFAULT_DURATION;
+}
+
+/** How long a dismissed toast takes to fold away: the theme's normal duration, which the exit transition uses. */
+function exitMs() {
+  const value = typeof document === "undefined" ? "" : getComputedStyle(document.documentElement).getPropertyValue("--ml-duration-normal");
+  const ms = parseFloat(value);
+  return Number.isFinite(ms) ? ms : 240;
+}
+
+type Options = ToastOptions & { loading?: boolean };
+
+let nextId = 1;
+let store: ToastItem[] = [];
+const listeners = new Set<ToastListener>();
+const emit = () => listeners.forEach((listener) => listener(store));
+
+function pushToast(message: string, options: Options = {}) {
+  const id = nextId++;
+  store = [
+    ...store,
+    {
+      id,
+      message,
+      description: options.description,
+      tone: options.tone ?? "neutral",
+      loading: Boolean(options.loading),
+      duration: durationFor(options.tone ?? "neutral", Boolean(options.loading), options.duration),
+      position: options.position ?? "top-right",
+      action: options.action,
+      icon: options.icon,
+      revision: 0,
+      closing: false,
+    },
+  ];
+  emit();
+  return id;
+}
+
+/** Change a toast in place: a loading toast becoming a success, for example. */
+function updateToast(id: number, message: string, options: Options = {}) {
+  store = store.map((item) =>
+    item.id === id
+      ? {
+          ...item,
+          message,
+          description: options.description,
+          tone: options.tone ?? item.tone,
+          loading: Boolean(options.loading),
+          duration: durationFor(options.tone ?? item.tone, Boolean(options.loading), options.duration),
+          action: options.action,
+          icon: options.icon,
+          revision: item.revision + 1,
+        }
+      : item,
+  );
+  emit();
+}
+
+/** Fold a toast away, or every toast when no id is given. */
+function dismissToast(id?: number) {
+  const targets = store.filter((item) => (id === undefined || item.id === id) && !item.closing).map((item) => item.id);
+  if (!targets.length) return;
+  store = store.map((item) => (targets.includes(item.id) ? { ...item, closing: true } : item));
+  emit();
+  setTimeout(() => {
+    store = store.filter((item) => !targets.includes(item.id));
+    emit();
+  }, exitMs());
+}
+
+type ToastFn = (message: string, options?: Omit<ToastOptions, "tone">) => number;
+
+interface PromiseMessages<T> {
+  loading: string;
+  success: string | ((value: T) => string);
+  error: string | ((error: unknown) => string);
+}
+
+interface ToastApi extends ToastFn {
+  info: ToastFn;
+  success: ToastFn;
+  warning: ToastFn;
+  danger: ToastFn;
+  loading: ToastFn;
+  /** Show a loading toast that becomes a success or a danger toast when the promise settles. */
+  promise: <T>(promise: Promise<T>, messages: PromiseMessages<T>, options?: Omit<ToastOptions, "tone">) => Promise<T>;
+  update: (id: number, message: string, options?: ToastOptions) => void;
+  dismiss: (id?: number) => void;
+}
+
+const toneFn = (tone: ToastTone): ToastFn => (message, options) => pushToast(message, { ...options, tone });
+
+const toast: ToastApi = Object.assign((message: string, options?: Omit<ToastOptions, "tone">) => pushToast(message, options), {
+  info: toneFn("info"),
+  success: toneFn("success"),
+  warning: toneFn("warning"),
+  danger: toneFn("danger"),
+  loading: ((message, options) => pushToast(message, { ...options, loading: true })) as ToastFn,
+  promise<T>(promise: Promise<T>, messages: PromiseMessages<T>, options?: Omit<ToastOptions, "tone">) {
+    const id = pushToast(messages.loading, { ...options, loading: true });
+    promise.then(
+      (value) => updateToast(id, typeof messages.success === "function" ? messages.success(value) : messages.success, { ...options, tone: "success" }),
+      (error) => updateToast(id, typeof messages.error === "function" ? messages.error(error) : messages.error, { ...options, tone: "danger" }),
+    );
+    return promise;
+  },
+  update: updateToast,
+  dismiss: dismissToast,
+});
+
+const TONE_ICONS: Partial<Record<ToastTone, React.ReactNode>> = {
+  success: <IconCircleCheck size="1.125em" />,
+  danger: <IconCircleX size="1.125em" />,
+  warning: <IconTriangleAlert size="1.125em" />,
+  info: <IconInfo size="1.125em" />,
+};
+
+/** Horizontal distance a swipe must travel to dismiss. */
+const SWIPE_DISMISS_PX = 72;
+
+function ToastCard({ item, paused }: { item: ToastItem; paused: boolean }) {
+  const remaining = React.useRef(item.duration);
+  const [drag, setDrag] = React.useState<{ start: number; offset: number } | null>(null);
+
+  // A changed toast (loading → success) gets its full time again.
+  React.useEffect(() => {
+    remaining.current = item.duration;
+  }, [item.revision, item.duration]);
+
+  // The timer counts only while the toast can actually be read: not while
+  // hovered, focused, or in a hidden tab. It resumes where it paused.
+  React.useEffect(() => {
+    if (paused || item.closing || !Number.isFinite(item.duration) || item.duration <= 0) return;
+    const started = Date.now();
+    const timer = window.setTimeout(() => dismissToast(item.id), remaining.current);
+    return () => {
+      window.clearTimeout(timer);
+      remaining.current = Math.max(0, remaining.current - (Date.now() - started));
+    };
+  }, [paused, item.closing, item.duration, item.id, item.revision]);
+
+  const urgent = item.tone === "danger" || item.tone === "warning";
+  const icon = item.loading ? <span className="ml-toast-spinner" /> : item.icon === undefined ? TONE_ICONS[item.tone] : item.icon;
+
+  return (
+    <div className="ml-toast-slot" data-state={item.closing ? "closed" : "open"}>
+      <div
+        role={urgent ? "alert" : "status"}
+        aria-live={urgent ? "assertive" : "polite"}
+        aria-atomic="true"
+        aria-busy={item.loading || undefined}
+        data-tone={item.tone}
+        data-has-description={item.description ? "" : undefined}
+        data-swiping={drag ? "" : undefined}
+        className="ml-toast"
+        style={drag ? { transform: `translateX(${drag.offset}px)`, opacity: Math.max(0.2, 1 - Math.abs(drag.offset) / 200) } : undefined}
+        onPointerDown={(event) => {
+          if (event.pointerType === "mouse" || (event.target as HTMLElement).closest("button")) return;
+          event.currentTarget.setPointerCapture(event.pointerId);
+          setDrag({ start: event.clientX, offset: 0 });
+        }}
+        onPointerMove={(event) => {
+          if (drag) setDrag({ ...drag, offset: event.clientX - drag.start });
+        }}
+        onPointerUp={() => {
+          if (drag && Math.abs(drag.offset) > SWIPE_DISMISS_PX) dismissToast(item.id);
+          setDrag(null);
+        }}
+        onPointerCancel={() => setDrag(null)}
+      >
+        {icon ? (
+          <span aria-hidden="true" className="ml-toast-icon">
+            {icon}
+          </span>
+        ) : null}
+        <div className="ml-toast-content">
+          <p className="ml-toast-message">{item.message}</p>
+          {item.description ? <p className="ml-toast-description">{item.description}</p> : null}
+        </div>
+        {item.action ? (
+          <button
+            type="button"
+            className="ml-toast-action"
+            onClick={() => {
+              item.action?.onClick();
+              dismissToast(item.id);
+            }}
+          >
+            {item.action.label}
+          </button>
+        ) : null}
+        <button type="button" aria-label="Dismiss notification" className="ml-toast-close" onClick={() => dismissToast(item.id)}>
+          <IconX aria-hidden="true" size="0.875em" />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function useDocumentHidden() {
+  return React.useSyncExternalStore(
+    (onChange) => {
+      document.addEventListener("visibilitychange", onChange);
+      return () => document.removeEventListener("visibilitychange", onChange);
+    },
+    () => document.hidden,
+    () => false,
+  );
+}
+
+interface ToasterProps {
+  position?: ToastPosition;
+  /** Overrides the region name. Distinct names keep several Toasters navigable. */
+  label?: string;
+  /** Toasts shown at once; the rest wait their turn. */
+  max?: number;
+  className?: string;
+}
+
+/**
+ * Where toasts appear. The newest sits nearest the screen edge; older ones
+ * step away from it. Hovering or focusing the stack pauses every timer, so
+ * nothing disappears while it is being read.
+ */
+function Toaster({ position = "top-right", label, max = 3, className }: ToasterProps) {
+  const [toasts, setToasts] = React.useState(() => store.filter((item) => item.position === position));
+  const [hovered, setHovered] = React.useState(false);
+  const [focused, setFocused] = React.useState(false);
+  const hidden = useDocumentHidden();
+
+  React.useEffect(() => {
+    const listener: ToastListener = (all) => setToasts(all.filter((item) => item.position === position));
+    listeners.add(listener);
+    listener(store);
+    return () => {
+      listeners.delete(listener);
+    };
+  }, [position]);
+
+  const shown = toasts.slice(-Math.max(1, max));
+  const ordered = position.startsWith("top") ? [...shown].reverse() : shown;
+
+  return (
+    <div
+      role="region"
+      aria-label={label ?? `Notifications (${position.replace("-", " ")})`}
+      data-position={position}
+      className={cx("ml-toaster", className)}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget)) setFocused(false);
+      }}
+    >
+      {ordered.map((item) => (
+        <ToastCard key={item.id} item={item} paused={hovered || focused || hidden} />
+      ))}
+    </div>
+  );
+}
+
+export { toast, dismissToast, Toaster };
+export type { ToastOptions, ToastAction, ToastApi };

package/snapshot/source/packages/components/toggle/toggle.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import * as React from "react";
+import { cx, useControllableState } from "../_internal/react";
+
+type SwitchSize = "sm" | "md" | "lg";
+interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  size?: SwitchSize;
+  label?: string;
+}
+const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
+  ({ checked, defaultChecked = false, onCheckedChange, disabled = false, size = "md", label, className, id, onClick, "aria-label": ariaLabel, ...props }, ref) => {
+    const [on, setOn] = useControllableState({ value: checked, defaultValue: defaultChecked, onChange: onCheckedChange });
+    const generated = React.useId();
+    const labelId = label ? `${id ?? generated}-label` : undefined;
+    return (
+      <span className="ml-switch-field" data-disabled={disabled ? "" : undefined}>
+        <button
+          ref={ref}
+          id={id}
+          type="button"
+          role="switch"
+          aria-checked={on}
+          aria-labelledby={labelId}
+          aria-label={label ? undefined : ariaLabel ?? "Toggle setting"}
+          disabled={disabled}
+          data-state={on ? "checked" : "unchecked"}
+          data-size={size}
+          className={cx("ml-toggle", className)}
+          onClick={(event) => {
+            onClick?.(event);
+            if (!event.defaultPrevented) setOn(!on);
+          }}
+          {...props}
+        >
+          <span aria-hidden="true" className="ml-toggle-thumb" />
+        </button>
+        {label ? <span id={labelId} className="ml-switch-label">{label}</span> : null}
+      </span>
+    );
+  }
+);
+Switch.displayName = "Switch";
+
+type ToggleSize = "sm" | "md" | "lg";
+interface ToggleProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
+  pressed?: boolean;
+  defaultPressed?: boolean;
+  onPressedChange?: (pressed: boolean) => void;
+  size?: ToggleSize;
+}
+const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
+  ({ pressed, defaultPressed = false, onPressedChange, disabled = false, size = "md", className, children, onClick, ...props }, ref) => {
+    const [on, setOn] = useControllableState({ value: pressed, defaultValue: defaultPressed, onChange: onPressedChange });
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-pressed={on}
+        disabled={disabled}
+        data-state={on ? "on" : "off"}
+        data-size={size}
+        className={cx("ml-toggle-button", className)}
+        onClick={(event) => {
+          onClick?.(event);
+          if (!event.defaultPrevented) setOn(!on);
+        }}
+        {...props}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+Toggle.displayName = "Toggle";
+export { Switch, Toggle };
+export type { SwitchProps, ToggleProps };

package/snapshot/source/packages/components/tooltip/tooltip.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+
+export type TooltipPlacement = "top" | "bottom" | "left" | "right";
+interface TooltipProps {
+  content: React.ReactNode;
+  placement?: TooltipPlacement;
+  delay?: number;
+  children: React.ReactElement<Record<string, unknown>>;
+  className?: string;
+}
+
+function Tooltip({ content, placement = "top", delay = 200, children, className }: TooltipProps) {
+  const [open, setOpen] = React.useState(false);
+  const timer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const id = React.useId();
+  const clear = () => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+  };
+  const show = () => {
+    clear();
+    timer.current = setTimeout(() => setOpen(true), Math.max(0, delay));
+  };
+  const hide = () => {
+    clear();
+    setOpen(false);
+  };
+  React.useEffect(() => clear, []);
+  React.useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") hide();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open]);
+  type Handlers = {
+    onMouseEnter?: React.MouseEventHandler;
+    onMouseLeave?: React.MouseEventHandler;
+    onFocus?: React.FocusEventHandler;
+    onBlur?: React.FocusEventHandler;
+    "aria-describedby"?: string;
+  };
+  const childProps = children.props as Handlers;
+  const trigger = React.cloneElement(children, {
+    onMouseEnter: (event: React.MouseEvent) => { childProps.onMouseEnter?.(event); show(); },
+    onMouseLeave: (event: React.MouseEvent) => { childProps.onMouseLeave?.(event); hide(); },
+    onFocus: (event: React.FocusEvent) => { childProps.onFocus?.(event); show(); },
+    onBlur: (event: React.FocusEvent) => { childProps.onBlur?.(event); hide(); },
+    "aria-describedby": open
+      ? [childProps["aria-describedby"], id].filter(Boolean).join(" ")
+      : childProps["aria-describedby"],
+  } as Record<string, unknown>);
+  return (
+    <span className="ml-tooltip-root" onMouseEnter={clear} onMouseLeave={hide}>
+      {trigger}
+      {open ? (
+        <span id={id} role="tooltip" data-side={placement} data-state="open" className={cx("ml-tooltip", className)}>
+          {content}
+          <span aria-hidden="true" className="ml-tooltip-arrow" />
+        </span>
+      ) : null}
+    </span>
+  );
+}
+export { Tooltip };
+export type { TooltipProps };

package/snapshot/source/packages/components/tour/tour.tsx

@@ -0,0 +1,193 @@
+"use client";
+
+import * as React from "react";
+import { createPortal } from "react-dom";
+import { IconX } from "@mlola-ui/icons";
+import { cx } from "../_internal/react";
+import { usePortalNode, type Side } from "../_internal/floating";
+import { placeFloating } from "../_internal/anchor";
+
+export interface TourStep {
+  /** A CSS selector or a ref for the element to point at; none shows the card centred. */
+  target?: string | React.RefObject<HTMLElement | null>;
+  title: string;
+  body?: React.ReactNode;
+  side?: Side;
+}
+
+export interface TourProps {
+  steps: TourStep[];
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  step?: number;
+  defaultStep?: number;
+  onStepChange?: (step: number) => void;
+  /** Called when the reader reaches the end, not when they skip. */
+  onFinish?: () => void;
+  label?: string;
+  className?: string;
+}
+
+const PAD = 6;
+
+function resolve(target: TourStep["target"]) {
+  if (!target) return null;
+  if (typeof target === "string") return typeof document === "undefined" ? null : document.querySelector<HTMLElement>(target);
+  return target.current;
+}
+
+/**
+ * A guided tour: the page dims, a spotlight opens on one element at a time,
+ * and a card beside it explains what it is for. Back, Next and the arrow
+ * keys move through the steps; Escape or Skip ends it. Each step scrolls its
+ * element into view and follows it as the page moves.
+ */
+export function Tour({ steps, open, onOpenChange, step: stepProp, defaultStep = 0, onStepChange, onFinish, label = "Tour", className }: TourProps) {
+  const portal = usePortalNode();
+  const [inner, setInner] = React.useState(defaultStep);
+  const index = Math.min(steps.length - 1, Math.max(0, stepProp ?? inner));
+  const setIndex = (next: number) => {
+    if (stepProp === undefined) setInner(next);
+    onStepChange?.(next);
+  };
+  const [rect, setRect] = React.useState<DOMRect | null>(null);
+  const card = React.useRef<HTMLDivElement>(null);
+  const titleId = React.useId();
+  const current = steps[index];
+
+  // Place the card beside the spotlight whenever the target moves; centre it when there is none.
+  React.useLayoutEffect(() => {
+    const element = card.current;
+    if (!element) return;
+    if (!rect) {
+      element.style.left = "";
+      element.style.top = "";
+      return;
+    }
+    const place = placeFloating(
+      { x: rect.left - PAD, y: rect.top - PAD, width: rect.width + PAD * 2, height: rect.height + PAD * 2 },
+      { width: element.offsetWidth, height: element.offsetHeight },
+      { width: window.innerWidth, height: window.innerHeight },
+      { side: current?.side ?? "bottom", align: "center", offset: 14 },
+    );
+    element.style.left = `${place.x}px`;
+    element.style.top = `${place.y}px`;
+  });
+
+  // Bring the step's element into view, then keep the spotlight on it.
+  React.useEffect(() => {
+    if (!open) return;
+    const element = resolve(current?.target);
+    if (!element) {
+      setRect(null);
+      return;
+    }
+    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    element.scrollIntoView({ block: "center", inline: "nearest", behavior: reduce ? "auto" : "smooth" });
+    let frame = 0;
+    const measure = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => setRect(element.getBoundingClientRect()));
+    };
+    measure();
+    window.addEventListener("scroll", measure, true);
+    window.addEventListener("resize", measure);
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+    observer?.observe(element);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("scroll", measure, true);
+      window.removeEventListener("resize", measure);
+      observer?.disconnect();
+    };
+  }, [open, index, current?.target]);
+
+  React.useEffect(() => {
+    if (open) requestAnimationFrame(() => card.current?.focus({ preventScroll: true }));
+  }, [open, index]);
+
+  const finish = () => {
+    onOpenChange(false);
+    onFinish?.();
+  };
+  const next = () => (index === steps.length - 1 ? finish() : setIndex(index + 1));
+  const back = () => index > 0 && setIndex(index - 1);
+
+  if (!open || !portal || !current) return null;
+
+  return createPortal(
+    <div className={cx("ml-tour", className)}>
+      <div className="ml-tour-scrim" data-spotlight={rect ? "" : undefined} aria-hidden="true" />
+      {rect ? (
+        <div
+          className="ml-tour-spotlight"
+          aria-hidden="true"
+          style={{ left: rect.left - PAD, top: rect.top - PAD, width: rect.width + PAD * 2, height: rect.height + PAD * 2 }}
+        />
+      ) : null}
+      <div
+        ref={card}
+        className="ml-tour-card"
+        data-centred={rect ? undefined : ""}
+        role="dialog"
+        aria-modal="true"
+        aria-label={`${label}: step ${index + 1} of ${steps.length}`}
+        aria-describedby={titleId}
+        tabIndex={-1}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onOpenChange(false);
+          } else if (event.key === "ArrowRight") {
+            event.preventDefault();
+            next();
+          } else if (event.key === "ArrowLeft") {
+            event.preventDefault();
+            back();
+          } else if (event.key === "Tab") {
+            // Focus stays in the card while the tour is open.
+            const focusable = [...(card.current?.querySelectorAll<HTMLElement>("button") ?? [])];
+            const first = focusable[0];
+            const last = focusable[focusable.length - 1];
+            if (event.shiftKey && document.activeElement === first) {
+              event.preventDefault();
+              last?.focus();
+            } else if (!event.shiftKey && document.activeElement === last) {
+              event.preventDefault();
+              first?.focus();
+            }
+          }
+        }}
+      >
+        <div className="ml-tour-head">
+          <span className="ml-tour-count">
+            {index + 1} of {steps.length}
+          </span>
+          <button type="button" className="ml-tour-skip" aria-label="End the tour" onClick={() => onOpenChange(false)}>
+            <IconX aria-hidden="true" size="0.95em" />
+          </button>
+        </div>
+        <h2 id={titleId} className="ml-tour-title">
+          {current.title}
+        </h2>
+        {current.body ? <div className="ml-tour-body">{current.body}</div> : null}
+        <div className="ml-tour-foot">
+          <span className="ml-tour-dots" aria-hidden="true">
+            {steps.map((_, position) => (
+              <span key={position} className="ml-tour-dot" data-active={position === index || undefined} />
+            ))}
+          </span>
+          {index > 0 ? (
+            <button type="button" className="ml-tour-button" onClick={back}>
+              Back
+            </button>
+          ) : null}
+          <button type="button" className="ml-tour-button" data-primary="" onClick={next}>
+            {index === steps.length - 1 ? "Done" : "Next"}
+          </button>
+        </div>
+      </div>
+    </div>,
+    portal,
+  );
+}