@mlola-ui/registry 1.0.0

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

@@ -0,0 +1,164 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+import { rovingIndex } from "@mlola-ui/behavior/logic";
+import { IconChevronDown } from "@mlola-ui/icons";
+
+type AccordionType = "single" | "multiple";
+interface AccordionProps extends React.HTMLAttributes<HTMLDivElement> {
+  type?: AccordionType;
+  defaultValue?: string | string[];
+  value?: string | string[];
+  onValueChange?: (value: string | string[] | undefined) => void;
+  collapsible?: boolean;
+}
+interface AccordionContextValue {
+  openValues: string[];
+  toggle: (value: string) => void;
+}
+interface ItemContextValue {
+  open: boolean;
+  disabled: boolean;
+  triggerId: string;
+  contentId: string;
+  toggle: () => void;
+}
+const AccordionContext = React.createContext<AccordionContextValue | null>(null);
+const ItemContext = React.createContext<ItemContextValue | null>(null);
+const normalize = (value: string | string[] | undefined) =>
+  value === undefined || value === "" ? [] : Array.isArray(value) ? value : [value];
+
+const Accordion = React.forwardRef<HTMLDivElement, AccordionProps>(
+  ({ type = "single", defaultValue, value, onValueChange, collapsible = true, className, children, ...props }, ref) => {
+    const controlled = value !== undefined;
+    const [internal, setInternal] = React.useState(() => normalize(defaultValue));
+    const openValues = controlled ? normalize(value) : internal;
+    const rootRef = React.useRef<HTMLDivElement>(null);
+    const setRef = React.useCallback(
+      (node: HTMLDivElement | null) => {
+        rootRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      [ref]
+    );
+    const toggle = React.useCallback((itemValue: string) => {
+      const open = openValues.includes(itemValue);
+      if (type === "single") {
+        if (open && !collapsible) return;
+        const next = open ? [] : [itemValue];
+        if (!controlled) setInternal(next);
+        onValueChange?.(next[0]);
+      } else {
+        const next = open ? openValues.filter((item) => item !== itemValue) : [...openValues, itemValue];
+        if (!controlled) setInternal(next);
+        onValueChange?.(next);
+      }
+    }, [collapsible, controlled, onValueChange, openValues, type]);
+
+    // Arrow, Home and End move focus between triggers. The framework-free
+    // runtime makes the same decision with the same shared function.
+    const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      props.onKeyDown?.(event);
+      if (event.defaultPrevented || !rootRef.current) return;
+      const triggers = [...rootRef.current.querySelectorAll<HTMLButtonElement>(".ml-accordion-trigger")];
+      const target = rovingIndex(
+        triggers.length,
+        triggers.indexOf(document.activeElement as HTMLButtonElement),
+        event.key,
+        { horizontal: false, enabled: (index) => !triggers[index].disabled },
+      );
+      if (target < 0) return;
+      event.preventDefault();
+      triggers[target].focus();
+    };
+
+    return (
+      <AccordionContext.Provider value={{ openValues, toggle }}>
+        <div ref={setRef} className={cx("ml-accordion", className)} onKeyDown={onKeyDown} {...props}>{children}</div>
+      </AccordionContext.Provider>
+    );
+  }
+);
+Accordion.displayName = "Accordion";
+
+interface AccordionItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  value: string;
+  disabled?: boolean;
+}
+const AccordionItem = React.forwardRef<HTMLDivElement, AccordionItemProps>(
+  ({ value, disabled = false, className, children, ...props }, ref) => {
+    const accordion = React.useContext(AccordionContext);
+    if (!accordion) throw new Error("AccordionItem must be used inside Accordion");
+    const open = accordion.openValues.includes(value);
+    const id = React.useId();
+    const item = React.useMemo(() => ({
+      open,
+      disabled,
+      triggerId: `${id}-trigger`,
+      contentId: `${id}-content`,
+      toggle: () => !disabled && accordion.toggle(value),
+    }), [accordion, disabled, id, open, value]);
+    return (
+      <ItemContext.Provider value={item}>
+        <div ref={ref} data-state={open ? "open" : "closed"} data-disabled={disabled ? "" : undefined} className={cx("ml-accordion-item", className)} {...props}>
+          {children}
+        </div>
+      </ItemContext.Provider>
+    );
+  }
+);
+AccordionItem.displayName = "AccordionItem";
+
+interface AccordionTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {}
+const AccordionTrigger = React.forwardRef<HTMLButtonElement, AccordionTriggerProps>(
+  ({ className, children, ...props }, ref) => {
+    const item = React.useContext(ItemContext);
+    if (!item) throw new Error("AccordionTrigger must be used inside AccordionItem");
+    return (
+      <h3 className="ml-accordion-heading">
+        <button
+          ref={ref}
+          id={item.triggerId}
+          type="button"
+          aria-expanded={item.open}
+          aria-controls={item.contentId}
+          disabled={item.disabled}
+          data-state={item.open ? "open" : "closed"}
+          className={cx("ml-accordion-trigger", className)}
+          onClick={item.toggle}
+          {...props}
+        >
+          <span className="ml-accordion-trigger-label">{children}</span>
+          <IconChevronDown aria-hidden="true" className="ml-accordion-chevron" />
+        </button>
+      </h3>
+    );
+  }
+);
+AccordionTrigger.displayName = "AccordionTrigger";
+
+interface AccordionContentProps extends React.HTMLAttributes<HTMLDivElement> {}
+const AccordionContent = React.forwardRef<HTMLDivElement, AccordionContentProps>(
+  ({ className, children, ...props }, ref) => {
+    const item = React.useContext(ItemContext);
+    if (!item) throw new Error("AccordionContent must be used inside AccordionItem");
+    return (
+      <div
+        ref={ref}
+        id={item.contentId}
+        role="region"
+        aria-labelledby={item.triggerId}
+        hidden={!item.open}
+        data-state={item.open ? "open" : "closed"}
+        className={cx("ml-accordion-panel", className)}
+        {...props}
+      >
+        <div className="ml-accordion-panel-inner">{children}</div>
+      </div>
+    );
+  }
+);
+AccordionContent.displayName = "AccordionContent";
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

package/snapshot/source/packages/components/activity-heatmap/activity-heatmap.tsx

@@ -0,0 +1,204 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+import { buildCalendar, type DayCount, type HeatCell } from "./calendar";
+
+export type { DayCount, HeatCell };
+
+export interface ActivityHeatmapProps extends Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> {
+  /** Counts per day, YYYY-MM-DD. Missing days are zero. */
+  data: DayCount[];
+  /** Last day shown. Defaults to the latest day in `data`, so server and client agree. */
+  end?: string;
+  weeks?: number;
+  /** 1 starts weeks on Monday, 0 on Sunday. */
+  weekStart?: 0 | 1;
+  /** What is counted, in the plural: "tokens", "commits". */
+  unit?: string;
+  /** Formats a count for the tooltip and labels. */
+  formatCount?: (count: number) => string;
+  tone?: "primary" | "info" | "success" | "warning";
+  onSelect?: (cell: HeatCell) => void;
+  /** Left of the legend. Defaults to the total over the range. */
+  caption?: React.ReactNode;
+  showLegend?: boolean;
+  locale?: string;
+  label?: string;
+}
+
+const today = (data: DayCount[]) => data.reduce((latest, day) => (day.date > latest ? day.date : latest), data[0]?.date ?? "1970-01-01");
+
+/**
+ * Activity by day, the way GitHub draws contributions: a week per column, a
+ * shade per level. Levels are quantiles of the active days, so one huge day
+ * never washes the rest out. It is a real grid: arrows move between days,
+ * each day is announced with its count, and hovering or focusing shows it.
+ */
+export function ActivityHeatmap({
+  data,
+  end,
+  weeks = 26,
+  weekStart = 1,
+  unit = "activities",
+  formatCount,
+  tone = "primary",
+  onSelect,
+  caption,
+  showLegend = true,
+  locale = "en",
+  label = "Activity",
+  className,
+  style,
+  ...props
+}: ActivityHeatmapProps) {
+  const last = end ?? today(data);
+  const calendar = React.useMemo(() => buildCalendar(data, { end: last, weeks, weekStart, locale }), [data, last, weeks, weekStart, locale]);
+  const format = React.useMemo(() => formatCount ?? ((count: number) => new Intl.NumberFormat(locale).format(count)), [formatCount, locale]);
+  const dayName = React.useMemo(() => new Intl.DateTimeFormat(locale, { weekday: "short", timeZone: "UTC" }), [locale]);
+  const fullDate = React.useMemo(() => new Intl.DateTimeFormat(locale, { weekday: "long", month: "long", day: "numeric", year: "numeric", timeZone: "UTC" }), [locale]);
+  const shortDate = React.useMemo(() => new Intl.DateTimeFormat(locale, { weekday: "short", month: "short", day: "numeric", timeZone: "UTC" }), [locale]);
+
+  const lastWeek = calendar.weeks.length - 1;
+  const lastDay = Math.max(0, (calendar.weeks[lastWeek] ?? []).map((cell) => !cell.outside).lastIndexOf(true));
+  const [focus, setFocus] = React.useState<[number, number]>([lastWeek, lastDay]);
+  const [shown, setShown] = React.useState<[number, number] | null>(null);
+  const root = React.useRef<HTMLDivElement>(null);
+  const tip = React.useRef<HTMLDivElement>(null);
+  const cells = React.useRef(new Map<string, HTMLElement>());
+  const key = (week: number, day: number) => `${week}:${day}`;
+
+  // Place the tooltip over its cell, kept inside the component's edges.
+  React.useLayoutEffect(() => {
+    if (!shown || !root.current || !tip.current) return;
+    const cell = cells.current.get(key(...shown));
+    if (!cell) return;
+    const box = root.current.getBoundingClientRect();
+    const rect = cell.getBoundingClientRect();
+    const half = tip.current.offsetWidth / 2;
+    const center = rect.left - box.left + rect.width / 2;
+    tip.current.style.left = `${Math.min(Math.max(center, half), box.width - half)}px`;
+    tip.current.style.top = `${rect.top - box.top}px`;
+  }, [shown]);
+
+  const move = (week: number, day: number) => {
+    const target = calendar.weeks[week]?.[day];
+    if (!target || target.outside) return;
+    setFocus([week, day]);
+    setShown([week, day]);
+    cells.current.get(key(week, day))?.focus();
+  };
+
+  const onKeyDown = (event: React.KeyboardEvent, week: number, day: number) => {
+    const moves: Record<string, [number, number]> = {
+      ArrowLeft: [week - 1, day],
+      ArrowRight: [week + 1, day],
+      ArrowUp: [week, day - 1],
+      ArrowDown: [week, day + 1],
+      Home: [0, day],
+      End: [lastWeek, day],
+    };
+    if (moves[event.key]) {
+      event.preventDefault();
+      let [nextWeek, nextDay] = moves[event.key];
+      // Home and End land on the nearest day inside the range.
+      if (event.key === "Home") while (calendar.weeks[nextWeek]?.[nextDay]?.outside && nextWeek < lastWeek) nextWeek += 1;
+      if (event.key === "End") while (calendar.weeks[nextWeek]?.[nextDay]?.outside && nextWeek > 0) nextWeek -= 1;
+      move(nextWeek, nextDay);
+    } else if ((event.key === "Enter" || event.key === " ") && onSelect) {
+      event.preventDefault();
+      onSelect(calendar.weeks[week][day]);
+    }
+  };
+
+  const count = (value: number) => `${format(value)} ${unit}`;
+  const active = shown ? calendar.weeks[shown[0]]?.[shown[1]] : null;
+
+  return (
+    <div
+      {...props}
+      ref={root}
+      className={cx("ml-heatmap", className)}
+      data-tone={tone}
+      style={{ ["--ml-heatmap-weeks" as string]: calendar.weeks.length, ...style }}
+      onPointerLeave={() => setShown(null)}
+    >
+      <div role="grid" aria-label={label} aria-readonly="true" className="ml-heatmap-grid">
+        <div className="ml-heatmap-months" aria-hidden="true">
+          {calendar.months.map((month) => (
+            <span key={`${month.label}-${month.week}`} className="ml-heatmap-month" style={{ gridColumn: month.week + 2 }}>
+              {month.label}
+            </span>
+          ))}
+        </div>
+        {Array.from({ length: 7 }, (_, day) => {
+          const name = dayName.format(new Date(`${calendar.weeks[0][day].date}T00:00:00Z`));
+          const labelled = [1, 3, 5].includes(new Date(`${calendar.weeks[0][day].date}T00:00:00Z`).getUTCDay());
+          return (
+            <div key={day} role="row" className="ml-heatmap-row">
+              <span role="rowheader" className="ml-heatmap-weekday" style={{ gridRow: day + 2 }}>
+                <span aria-hidden={!labelled || undefined} data-hidden={!labelled || undefined}>
+                  {name}
+                </span>
+              </span>
+              {calendar.weeks.map((column, week) => {
+                const cell = column[day];
+                const focused = focus[0] === week && focus[1] === day;
+                return (
+                  <span
+                    key={cell.date}
+                    ref={(element) => {
+                      if (element) cells.current.set(key(week, day), element);
+                      else cells.current.delete(key(week, day));
+                    }}
+                    role="gridcell"
+                    className="ml-heatmap-cell"
+                    data-level={cell.level}
+                    data-outside={cell.outside || undefined}
+                    data-active={shown?.[0] === week && shown?.[1] === day ? "" : undefined}
+                    aria-label={cell.outside ? undefined : `${count(cell.count)} on ${fullDate.format(new Date(`${cell.date}T00:00:00Z`))}`}
+                    aria-hidden={cell.outside || undefined}
+                    tabIndex={cell.outside ? undefined : focused ? 0 : -1}
+                    style={{ gridColumn: week + 2, gridRow: day + 2 }}
+                    onPointerEnter={() => !cell.outside && setShown([week, day])}
+                    onFocus={() => {
+                      setFocus([week, day]);
+                      setShown([week, day]);
+                    }}
+                    onBlur={() => setShown(null)}
+                    onClick={() => !cell.outside && onSelect?.(cell)}
+                    onKeyDown={(event) => onKeyDown(event, week, day)}
+                  />
+                );
+              })}
+            </div>
+          );
+        })}
+      </div>
+
+      <div ref={tip} className="ml-heatmap-tooltip" role="presentation" hidden={!active}>
+        {active ? (
+          <>
+            <strong>{active.count ? count(active.count) : `No ${unit}`}</strong>
+            <span>{shortDate.format(new Date(`${active.date}T00:00:00Z`))}</span>
+          </>
+        ) : null}
+      </div>
+
+      {showLegend || caption !== null ? (
+        <div className="ml-heatmap-footer">
+          <span className="ml-heatmap-caption">{caption === undefined ? `${count(calendar.total)} over ${calendar.activeDays} active days` : caption}</span>
+          {showLegend ? (
+            <span className="ml-heatmap-legend" aria-hidden="true">
+              Less
+              {[0, 1, 2, 3, 4].map((level) => (
+                <span key={level} className="ml-heatmap-cell" data-level={level} />
+              ))}
+              More
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/snapshot/source/packages/components/activity-heatmap/calendar.ts

@@ -0,0 +1,92 @@
+/**
+ * The calendar behind an activity heatmap: whole weeks as columns ending on
+ * `end`, a level per day, and where each month's label goes. Levels come from
+ * quantiles of the active days, so one extreme day cannot wash every other
+ * day out to the palest shade.
+ */
+export interface DayCount {
+  /** YYYY-MM-DD */
+  date: string;
+  count: number;
+}
+
+export interface HeatCell {
+  date: string;
+  count: number;
+  level: 0 | 1 | 2 | 3 | 4;
+  /** Outside the requested range (padding in the first or last week). */
+  outside: boolean;
+}
+
+export interface HeatCalendar {
+  weeks: HeatCell[][];
+  /** Month labels with the week column they start in. */
+  months: Array<{ label: string; week: number }>;
+  total: number;
+  activeDays: number;
+  max: number;
+}
+
+const DAY = 86_400_000;
+const iso = (time: number) => new Date(time).toISOString().slice(0, 10);
+const utc = (date: string) => Date.parse(`${date}T00:00:00Z`);
+
+/** Thresholds splitting non-zero counts into four equal-sized groups. */
+export function quantileThresholds(counts: number[]): [number, number, number] {
+  const active = counts.filter((count) => count > 0).sort((a, b) => a - b);
+  if (!active.length) return [1, 1, 1];
+  const at = (fraction: number) => active[Math.min(active.length - 1, Math.floor(fraction * active.length))];
+  return [at(0.25), at(0.5), at(0.75)];
+}
+
+export function levelFor(count: number, [q1, q2, q3]: [number, number, number]): HeatCell["level"] {
+  if (count <= 0) return 0;
+  if (count <= q1) return 1;
+  if (count <= q2) return 2;
+  if (count <= q3) return 3;
+  return 4;
+}
+
+export function buildCalendar(
+  data: DayCount[],
+  { end, weeks = 26, weekStart = 1, locale = "en" }: { end: string; weeks?: number; weekStart?: 0 | 1; locale?: string },
+): HeatCalendar {
+  const counts = new Map(data.map((day) => [day.date, day.count]));
+  const endTime = utc(end);
+  const endWeekday = (new Date(endTime).getUTCDay() - weekStart + 7) % 7;
+  const lastColumnEnd = endTime + (6 - endWeekday) * DAY;
+  const firstDay = lastColumnEnd - (weeks * 7 - 1) * DAY;
+  const rangeStart = endTime - (weeks * 7 - 1 - (6 - endWeekday)) * DAY;
+  const inRange = data.filter((day) => utc(day.date) >= rangeStart && utc(day.date) <= endTime).map((day) => day.count);
+  const thresholds = quantileThresholds(inRange);
+  const format = new Intl.DateTimeFormat(locale, { month: "short", timeZone: "UTC" });
+
+  const columns: HeatCell[][] = [];
+  const months: HeatCalendar["months"] = [];
+  let lastMonth = -1;
+  for (let week = 0; week < weeks; week += 1) {
+    const column: HeatCell[] = [];
+    for (let day = 0; day < 7; day += 1) {
+      const time = firstDay + (week * 7 + day) * DAY;
+      const date = iso(time);
+      const count = counts.get(date) ?? 0;
+      const outside = time > endTime || time < rangeStart;
+      column.push({ date, count: outside ? 0 : count, level: outside ? 0 : levelFor(count, thresholds), outside });
+    }
+    const month = new Date(firstDay + week * 7 * DAY).getUTCMonth();
+    if (month !== lastMonth) {
+      // Skip a label squeezed into the very first column by a partial month.
+      if (week > 0 || new Date(firstDay).getUTCDate() <= 7) months.push({ label: format.format(new Date(firstDay + week * 7 * DAY)), week });
+      lastMonth = month;
+    }
+    columns.push(column);
+  }
+  const active = columns.flat().filter((cell) => !cell.outside && cell.count > 0);
+  return {
+    weeks: columns,
+    months,
+    total: active.reduce((sum, cell) => sum + cell.count, 0),
+    activeDays: active.length,
+    max: active.reduce((max, cell) => Math.max(max, cell.count), 0),
+  };
+}

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

@@ -0,0 +1,83 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+import { IconCircleCheck, IconCircleX, IconInfo, IconTriangleAlert, IconX } from "@mlola-ui/icons";
+
+/** The meaning of the message, from the theme's colour roles. */
+export type AlertTone = "neutral" | "info" | "success" | "warning" | "danger";
+/** "card" is a neutral card with a solid icon mark; "soft" tints the whole alert, for banners across a page. */
+export type AlertVariant = "card" | "soft";
+interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
+  tone?: AlertTone;
+  variant?: AlertVariant;
+  onDismiss?: () => void;
+  action?: React.ReactNode;
+  /** Replaces the tone's icon. `null` shows none. */
+  icon?: React.ReactNode;
+}
+
+const TONE_ICONS: Record<AlertTone, React.ReactNode> = {
+  neutral: <IconInfo size="1em" />,
+  info: <IconInfo size="1em" />,
+  success: <IconCircleCheck size="1em" />,
+  warning: <IconTriangleAlert size="1em" />,
+  danger: <IconCircleX size="1em" />,
+};
+
+/**
+ * A message in the page. Only warnings and errors interrupt a screen reader
+ * (role="alert"); calmer notices are announced politely when they appear.
+ * It eases in when it appears and, when dismissed, eases out before
+ * `onDismiss` runs, so the layout closes smoothly around it.
+ */
+const Alert = React.forwardRef<HTMLDivElement, AlertProps>(
+  ({ tone = "neutral", variant = "card", onDismiss, action, icon, className, children, ...props }, ref) => {
+    const [leaving, setLeaving] = React.useState(false);
+    const timer = React.useRef<number | undefined>(undefined);
+    React.useEffect(() => () => window.clearTimeout(timer.current), []);
+    const dismiss = () => {
+      if (!onDismiss || leaving) return;
+      if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return onDismiss();
+      setLeaving(true);
+      timer.current = window.setTimeout(onDismiss, 200);
+    };
+    return (
+      <div
+        ref={ref}
+        role={tone === "danger" || tone === "warning" ? "alert" : "status"}
+        data-tone={tone}
+        data-variant={variant}
+        data-state={leaving ? "closing" : "open"}
+        className={cx("ml-alert", className)}
+        {...props}
+      >
+        {icon === null ? <span aria-hidden="true" /> : <span aria-hidden="true" className="ml-alert-icon">{icon ?? TONE_ICONS[tone]}</span>}
+        <div className="ml-alert-content">{children}</div>
+        {action || onDismiss ? (
+          <div className="ml-alert-actions">
+            {action}
+            {onDismiss ? (
+              <button type="button" onClick={dismiss} aria-label="Dismiss alert" className="ml-alert-dismiss">
+                <IconX aria-hidden="true" size="1em" />
+              </button>
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+    );
+  }
+);
+Alert.displayName = "Alert";
+// Not a heading: an alert sits inside whatever outline the page already has,
+// so it must not claim a level. Wrap it in a heading yourself when it needs one.
+const AlertTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, ...props }, ref) => <p ref={ref} className={cx("ml-alert-title", className)} {...props} />
+);
+AlertTitle.displayName = "AlertTitle";
+const AlertDescription = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => <div ref={ref} className={cx("ml-alert-description", className)} {...props} />
+);
+AlertDescription.displayName = "AlertDescription";
+export { Alert, AlertTitle, AlertDescription };
+export type { AlertProps };