mlola-ui 1.0.0

package/registry/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/registry/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/registry/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 };

package/registry/source/packages/components/app-shell/app-shell.tsx

@@ -0,0 +1,186 @@
+"use client";
+
+import * as React from "react";
+import { IconChevronDown, IconMenu } from "@mlola-ui/icons";
+import { Resizable } from "../resizable/resizable";
+import { Sheet } from "../sheet/sheet";
+import { cx } from "../_internal/react";
+
+interface ShellContext {
+  /** Fold the sidebar on wide screens; open the drawer on narrow ones. */
+  toggle: () => void;
+  folded: boolean;
+  narrow: boolean;
+  /** Close the drawer, after a navigation on a phone. */
+  closeDrawer: () => void;
+}
+
+const Context = React.createContext<ShellContext>({ toggle: () => undefined, folded: false, narrow: false, closeDrawer: () => undefined });
+
+/** The shell's controls, for a menu button in a page header or a link that should close the drawer. */
+export const useAppShell = () => React.useContext(Context);
+
+function useNarrow(query: string) {
+  return React.useSyncExternalStore(
+    (notify) => {
+      const list = window.matchMedia(query);
+      list.addEventListener("change", notify);
+      return () => list.removeEventListener("change", notify);
+    },
+    () => window.matchMedia(query).matches,
+    () => false,
+  );
+}
+
+export interface AppShellProps {
+  sidebar: React.ReactNode;
+  children: React.ReactNode;
+  /** Names the navigation region and the drawer. */
+  label?: string;
+  defaultWidth?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  /** Remembers the width and the fold between visits. */
+  storageKey?: string;
+  /** Below this width the sidebar becomes a drawer. */
+  drawerQuery?: string;
+  className?: string;
+}
+
+/**
+ * The frame of an app: a sidebar that resizes and folds, and the page beside
+ * it; on phones the sidebar becomes a drawer. Anything inside can reach the
+ * controls with `useAppShell`, and `AppShellMenuButton` shows itself only
+ * when the sidebar is out of view.
+ */
+export function AppShell({ sidebar, children, label = "Navigation", defaultWidth = 248, minWidth = 200, maxWidth = 360, storageKey, drawerQuery = "(max-width: 48rem)", className }: AppShellProps) {
+  const narrow = useNarrow(drawerQuery);
+  const [folded, setFolded] = React.useState(false);
+  const [drawer, setDrawer] = React.useState(false);
+  const context = React.useMemo<ShellContext>(
+    () => ({ toggle: () => (narrow ? setDrawer(true) : setFolded((value) => !value)), folded, narrow, closeDrawer: () => setDrawer(false) }),
+    [folded, narrow],
+  );
+  React.useEffect(() => {
+    if (!narrow) setDrawer(false);
+  }, [narrow]);
+  return (
+    <Context.Provider value={context}>
+      <div className={cx("ml-app-shell", className)} data-folded={folded || undefined} data-narrow={narrow || undefined}>
+        <Resizable
+          className="ml-app-shell-frame"
+          units="pixels"
+          defaultSize={defaultWidth}
+          min={minWidth}
+          max={maxWidth}
+          collapsible
+          collapsed={folded}
+          onCollapsedChange={setFolded}
+          storageKey={storageKey}
+          label={`Resize ${label.toLowerCase()}`}
+          first={
+            <nav className="ml-app-shell-sidebar" aria-label={label}>
+              {sidebar}
+            </nav>
+          }
+          second={<div className="ml-app-shell-main">{children}</div>}
+        />
+        <Sheet open={drawer} onClose={() => setDrawer(false)} side="left" size="sm" title={label} className="ml-app-shell-drawer">
+          <nav className="ml-app-shell-sidebar" aria-label={label}>
+            {sidebar}
+          </nav>
+        </Sheet>
+      </div>
+    </Context.Provider>
+  );
+}
+
+/** A menu button that appears only when the sidebar is folded or on a phone. */
+export function AppShellMenuButton({ label = "Open navigation", className }: { label?: string; className?: string }) {
+  const { toggle, folded, narrow } = useAppShell();
+  if (!folded && !narrow) return null;
+  return (
+    <button type="button" className={cx("ml-app-shell-menu", className)} aria-label={label} onClick={toggle}>
+      <IconMenu aria-hidden="true" size="1.05em" />
+    </button>
+  );
+}
+
+export function Sidebar({ header, footer, children, className }: { header?: React.ReactNode; footer?: React.ReactNode; children: React.ReactNode; className?: string }) {
+  return (
+    <div className={cx("ml-sidebar", className)}>
+      {header ? <div className="ml-sidebar-header">{header}</div> : null}
+      <div className="ml-sidebar-body">{children}</div>
+      {footer ? <div className="ml-sidebar-footer">{footer}</div> : null}
+    </div>
+  );
+}
+
+/** A titled group of items; with `collapsible`, the title folds it. */
+export function SidebarSection({ title, collapsible = false, defaultOpen = true, children }: { title?: React.ReactNode; collapsible?: boolean; defaultOpen?: boolean; children: React.ReactNode }) {
+  const [open, setOpen] = React.useState(defaultOpen);
+  const id = React.useId();
+  return (
+    <section className="ml-sidebar-section">
+      {title ? (
+        collapsible ? (
+          <button type="button" className="ml-sidebar-title" data-collapsible="" aria-expanded={open} aria-controls={id} onClick={() => setOpen(!open)}>
+            {title}
+            <IconChevronDown aria-hidden="true" size="0.85em" className="ml-sidebar-chevron" />
+          </button>
+        ) : (
+          <h2 className="ml-sidebar-title">{title}</h2>
+        )
+      ) : null}
+      <ul id={id} className="ml-sidebar-list" hidden={!open}>
+        {children}
+      </ul>
+    </section>
+  );
+}
+
+export interface SidebarItemProps {
+  label: string;
+  icon?: React.ReactNode;
+  /** A number at the end: unread, open, due. */
+  count?: number;
+  /** The page being shown. */
+  current?: boolean;
+  href?: string;
+  onClick?: () => void;
+  /** Controls revealed on hover, such as a + or a menu. */
+  actions?: React.ReactNode;
+}
+
+export function SidebarItem({ label, icon, count, current, href, onClick, actions }: SidebarItemProps) {
+  const { narrow, closeDrawer } = useAppShell();
+  const content = (
+    <>
+      {icon ? (
+        <span className="ml-sidebar-icon" aria-hidden="true">
+          {icon}
+        </span>
+      ) : null}
+      <span className="ml-sidebar-label">{label}</span>
+      {count ? <span className="ml-sidebar-count">{count}</span> : null}
+    </>
+  );
+  const choose = () => {
+    onClick?.();
+    if (narrow) closeDrawer();
+  };
+  return (
+    <li className="ml-sidebar-entry">
+      {href ? (
+        <a className="ml-sidebar-item" href={href} aria-current={current ? "page" : undefined} onClick={choose}>
+          {content}
+        </a>
+      ) : (
+        <button type="button" className="ml-sidebar-item" aria-current={current ? "page" : undefined} onClick={choose}>
+          {content}
+        </button>
+      )}
+      {actions ? <span className="ml-sidebar-actions">{actions}</span> : null}
+    </li>
+  );
+}

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

@@ -0,0 +1,56 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarStatus = "online" | "offline" | "away" | "busy";
+const initials = (name?: string) => {
+  const words = name?.replace(/[^\p{L}\p{N}\s]/gu, "").trim().split(/\s+/).filter(Boolean) ?? [];
+  return words.length > 1 ? `${words[0][0]}${words[words.length - 1][0]}`.toUpperCase() : words[0]?.slice(0, 2).toUpperCase() ?? "?";
+};
+interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
+  src?: string;
+  alt?: string;
+  name?: string;
+  size?: AvatarSize;
+  status?: AvatarStatus;
+}
+const Avatar = React.forwardRef<HTMLSpanElement, AvatarProps>(
+  ({ src, alt, name, size = "md", status, className, ...props }, ref) => {
+    const [failed, setFailed] = React.useState(false);
+    React.useEffect(() => setFailed(false), [src]);
+    const label = alt ?? name ?? "Avatar";
+    // alt="" marks the avatar as decorative, as it is for images: the name is
+    // already on screen beside it and must not be read twice.
+    const decorative = alt === "";
+    return (
+      <span ref={ref} data-size={size} className={cx("ml-avatar-root", className)} {...props}>
+        <span className="ml-avatar">
+          {src && !failed
+            ? <img src={src} alt={label} loading="lazy" className="ml-avatar-image" onError={() => setFailed(true)} />
+            : <span role={decorative ? undefined : "img"} aria-label={decorative ? undefined : label} aria-hidden={decorative || undefined} className="ml-avatar-fallback">{initials(name)}</span>}
+        </span>
+        {status ? <span role="status" aria-label={`${label} is ${status}`} data-status={status} className="ml-avatar-status" /> : null}
+      </span>
+    );
+  }
+);
+Avatar.displayName = "Avatar";
+
+interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> { max?: number; }
+const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
+  ({ max = 4, className, children, ...props }, ref) => {
+    const items = React.Children.toArray(children);
+    const visible = items.slice(0, Math.max(0, max));
+    const overflow = items.length - visible.length;
+    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}
+      </div>
+    );
+  }
+);
+AvatarGroup.displayName = "AvatarGroup";
+export { Avatar, AvatarGroup };

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

@@ -0,0 +1,39 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+import { IconX } from "@mlola-ui/icons";
+
+/** The meaning of the colour, from the theme's roles. */
+export type BadgeTone = "neutral" | "primary" | "info" | "success" | "warning" | "danger";
+/** The form: a tint, a solid fill, or an outline. */
+export type BadgeVariant = "soft" | "solid" | "outline";
+type BadgeSize = "sm" | "md" | "lg";
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  tone?: BadgeTone;
+  variant?: BadgeVariant;
+  size?: BadgeSize;
+  dot?: boolean;
+  onRemove?: () => void;
+}
+const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
+  ({ tone = "neutral", variant = "soft", size = "md", dot = false, onRemove, className, children, ...props }, ref) => (
+    <span ref={ref} data-tone={tone} data-variant={variant} data-size={size} className={cx("ml-badge", className)} {...props}>
+      {dot ? <span aria-hidden="true" className="ml-badge-dot" /> : null}
+      <span className="ml-badge-label">{children}</span>
+      {onRemove ? (
+        <button
+          type="button"
+          onClick={onRemove}
+          aria-label={`Remove${typeof children === "string" ? ` ${children}` : " badge"}`}
+          className="ml-badge-remove"
+        >
+          <IconX aria-hidden="true" size="0.75em" />
+        </button>
+      ) : null}
+    </span>
+  )
+);
+Badge.displayName = "Badge";
+export { Badge };
+export type { BadgeSize };