@sableui/react 0.17.0 → 0.18.0

package/dist/components/activity-heatmap/activity-heatmap.js

@@ -0,0 +1,420 @@
+"use client";
+
+// src/components/activity-heatmap/activity-heatmap.tsx
+import {
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { normalizeActivity } from "../../lib/chart/activity.js";
+import { activityGrid, dayNumber, gridPosition, isoDay, localeWeekStart, today, utcDate, weekday } from "../../lib/chart/calendar.js";
+import { ChartLegend } from "../../lib/chart/chart-legend.js";
+import { ChartTooltipContent } from "../../lib/chart/chart-tooltip.js";
+import { centerValueFormat } from "../../lib/chart/format.js";
+import { activityLevels, heatColor, levelNames } from "../../lib/chart/heat.js";
+import { riseTransition, stagger } from "../../lib/chart/motion.js";
+import { categoryStyle, toneColor } from "../../lib/chart/types.js";
+import { useArrival } from "../../lib/chart/use-arrival.js";
+import { cn } from "../../lib/cn.js";
+import { mergeRefs } from "../../lib/refs.js";
+import { useIsomorphicLayoutEffect } from "../../lib/use-isomorphic-layout-effect.js";
+import { useResizeObserver } from "../../lib/use-resize-observer.js";
+import { motionAttribute, useMotionLevel } from "../../motion/MotionProvider.js";
+import { Scroller } from "../scroller/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var CELL_FLOOR = { sm: 10, md: 12, lg: 14 };
+var CELL_MAX = 20;
+var PAD = 4;
+var SHOWN_WEEKDAYS = /* @__PURE__ */ new Set([1, 3, 5]);
+var gapFor = (cell) => Math.max(2, Math.floor(cell * 0.2 * 4) / 4);
+function fitCell(width, weeks, floor, stretch) {
+  if (!stretch || !width) return floor;
+  const fit = (width - PAD * 2) / (weeks * 1.2 + 0.2);
+  return Math.max(floor, Math.min(CELL_MAX, Math.floor(fit * 4) / 4));
+}
+function ActivityHeatmap({
+  label,
+  data,
+  start,
+  end,
+  year,
+  weekStart,
+  levels = 5,
+  levelScale = "quantile",
+  tone = "1",
+  categories,
+  unit,
+  formatValue,
+  tooltip = true,
+  legend = true,
+  legendLabels = ["Less", "More"],
+  monthLabels = true,
+  weekdayLabels = "alternate",
+  size = "md",
+  stretch = true,
+  activeDate,
+  defaultActiveDate = null,
+  onActiveDateChange,
+  selectedDate,
+  onSelectDate,
+  renderCell,
+  loading = false,
+  motion,
+  locale,
+  className,
+  style,
+  ref,
+  ...props
+}) {
+  const uid = useId();
+  const { expressive } = useMotionLevel(motion);
+  const [arrivalRef, inView] = useArrival();
+  const figureRef = useMemo(() => mergeRefs(arrivalRef, ref), [arrivalRef, ref]);
+  const shown = !expressive || inView;
+  const todayN = today();
+  const firstDay = weekStart ?? localeWeekStart(locale);
+  const endN = year != null ? dayNumber(`${year}-12-31`) : end ? dayNumber(end) : todayN;
+  const startN = useMemo(() => {
+    if (year != null) return dayNumber(`${year}-01-01`);
+    if (start) return dayNumber(start);
+    const back = endN - 364;
+    return back - (weekday(back) - firstDay + 7) % 7;
+  }, [year, start, endN, firstDay]);
+  const grid = useMemo(() => activityGrid({ start: startN, end: endN, weekStart: firstDay }), [startN, endN, firstDay]);
+  const last = Math.min(endN, todayN);
+  const navigable = useCallback((n) => n != null && n >= startN && n <= last, [startN, last]);
+  const days = useMemo(() => loading ? /* @__PURE__ */ new Map() : normalizeActivity(data), [data, loading]);
+  const scaleLevels = useMemo(
+    () => activityLevels([...days.values()].map((d) => d.value), { levels, scale: levelScale }),
+    [days, levels, levelScale]
+  );
+  const categoryKeys = categories ? Object.keys(categories) : [];
+  const base = toneColor(tone);
+  const resolve = (n) => {
+    const d = days.get(n);
+    const value = d?.value ?? 0;
+    const level = d?.level != null ? Math.min(levels - 1, Math.max(0, d.level)) : scaleLevels.level(value);
+    const known = d?.category != null && categories?.[d.category] ? d.category : void 0;
+    const cat = known ? categoryStyle(categories, known, categoryKeys.indexOf(known)) : void 0;
+    return { date: isoDay(n), value, level, category: d?.category, color: heatColor(cat?.color ?? base, level, levels), categoryLabel: cat?.label };
+  };
+  const words = useMemo(() => {
+    const long = new Intl.DateTimeFormat(locale, { weekday: "long", month: "long", day: "numeric", year: "numeric", timeZone: "UTC" });
+    const short = new Intl.DateTimeFormat(locale, { weekday: "short", month: "short", day: "numeric", year: "numeric", timeZone: "UTC" });
+    const crossesYear = utcDate(startN).getUTCFullYear() !== utcDate(endN).getUTCFullYear();
+    const monthLong = new Intl.DateTimeFormat(locale, { month: "long", ...crossesYear ? { year: "numeric" } : {}, timeZone: "UTC" });
+    const monthShort = new Intl.DateTimeFormat(locale, { month: "short", timeZone: "UTC" });
+    const dayLong = new Intl.DateTimeFormat(locale, { weekday: "long", timeZone: "UTC" });
+    const dayShort = new Intl.DateTimeFormat(locale, { weekday: "short", timeZone: "UTC" });
+    const plural = new Intl.PluralRules(locale);
+    const number = (v) => formatValue?.(v) ?? new Intl.NumberFormat(locale, centerValueFormat(v)).format(v);
+    const unitWord = (v) => unit == null ? "" : typeof unit === "string" ? unit : plural.select(v) === "one" ? unit.one : unit.other;
+    const none = unit == null ? "no activity" : `no ${typeof unit === "string" ? unit : unit.other}`;
+    return {
+      long: (n) => long.format(utcDate(n)),
+      short: (n) => short.format(utcDate(n)),
+      monthLong: (n) => monthLong.format(utcDate(n)),
+      monthShort: (n) => monthShort.format(utcDate(n)),
+      // 1970-01-04 (day 3) was a Sunday, so day 3 + d is weekday d.
+      dayLong: (d) => dayLong.format(utcDate(3 + d)),
+      dayShort: (d) => dayShort.format(utcDate(3 + d)),
+      number,
+      value: (v) => v > 0 ? [number(v), unitWord(v)].filter(Boolean).join(" ") : none,
+      unitTitle: unit == null ? "Value" : (typeof unit === "string" ? unit : unit.other).replace(/^./, (c) => c.toUpperCase())
+    };
+  }, [locale, startN, endN, formatValue, unit]);
+  const names = levelNames(levels);
+  const areaRef = useRef(null);
+  const scrollRef = useRef(null);
+  const [width, setWidth] = useState(null);
+  const measure = useCallback(() => setWidth(areaRef.current?.clientWidth ?? null), []);
+  useResizeObserver(measure, [areaRef]);
+  const cell = fitCell(width, grid.weeks.length, CELL_FLOOR[size], stretch);
+  const gap = gapFor(cell);
+  const opened = useRef(false);
+  useIsomorphicLayoutEffect(() => {
+    const region = scrollRef.current;
+    if (!region || width == null || opened.current) return;
+    opened.current = true;
+    const latest = last >= startN ? cellAt(last) : null;
+    if (!latest) return;
+    const overshoot = latest.getBoundingClientRect().right - region.getBoundingClientRect().right;
+    region.scrollLeft = Math.max(0, region.scrollLeft + overshoot + PAD + gap);
+  }, [width, cell]);
+  const latestActive = useMemo(() => {
+    for (let n = last; n >= startN; n--) if ((days.get(n)?.value ?? 0) > 0) return n;
+    return last >= startN ? last : null;
+  }, [days, last, startN]);
+  const [focusState, setFocusState] = useState(null);
+  const focusDay = navigable(focusState) ? focusState : latestActive;
+  const [uncontrolledActive, setUncontrolledActive] = useState(defaultActiveDate ? dayNumber(defaultActiveDate) : null);
+  const active = activeDate !== void 0 ? activeDate ? dayNumber(activeDate) : null : uncontrolledActive;
+  const setActive = (n) => {
+    if (n === active) return;
+    if (activeDate === void 0) setUncontrolledActive(n);
+    onActiveDateChange?.(n == null ? null : isoDay(n));
+  };
+  const [dismissed, setDismissed] = useState(false);
+  const selectable = onSelectDate != null;
+  const [uncontrolledSelected, setUncontrolledSelected] = useState(null);
+  const selected = selectedDate !== void 0 ? selectedDate ? dayNumber(selectedDate) : null : uncontrolledSelected;
+  const select = (n) => {
+    if (selectedDate === void 0) setUncontrolledSelected(n);
+    onSelectDate?.(isoDay(n));
+  };
+  const tableRef = useRef(null);
+  const cellAt = (n) => tableRef.current?.querySelector(`[data-date="${isoDay(n)}"]`) ?? null;
+  const dayOf = (target) => {
+    const el = target?.closest?.("td[data-date]");
+    return el?.dataset.date ? dayNumber(el.dataset.date) : null;
+  };
+  const moveFrom = (n, event) => {
+    const { week, row } = gridPosition(grid, n);
+    const inRow = (w) => grid.weeks[w]?.days[row];
+    const inColumn = (r) => grid.weeks[week].days[r];
+    const firstOf = (items, pick) => {
+      for (const item of items) {
+        const d = pick(item);
+        if (navigable(d)) return d;
+      }
+      return null;
+    };
+    const weeks = grid.weeks.map((_, i) => i);
+    const rows = [0, 1, 2, 3, 4, 5, 6];
+    switch (event.key) {
+      case "ArrowUp":
+        return row > 0 ? n - 1 : null;
+      case "ArrowDown":
+        return row < 6 ? n + 1 : null;
+      case "ArrowLeft":
+        return n - 7;
+      case "ArrowRight":
+        return n + 7;
+      case "Home":
+        return event.ctrlKey || event.metaKey ? startN : firstOf(weeks, inRow);
+      case "End":
+        return event.ctrlKey || event.metaKey ? last : firstOf([...weeks].reverse(), inRow);
+      case "PageUp":
+        return firstOf(rows, inColumn);
+      case "PageDown":
+        return firstOf([...rows].reverse(), inColumn);
+      default:
+        return null;
+    }
+  };
+  const onKeyDown = (event) => {
+    const from = dayOf(event.target);
+    if (from == null) return;
+    if (event.key === "Escape") {
+      setDismissed(true);
+      return;
+    }
+    if ((event.key === "Enter" || event.key === " ") && selectable) {
+      event.preventDefault();
+      select(from);
+      return;
+    }
+    const handled = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"].includes(event.key);
+    if (!handled) return;
+    event.preventDefault();
+    const next = moveFrom(from, event);
+    if (!navigable(next)) return;
+    setFocusState(next);
+    const el = cellAt(next);
+    el?.focus({ preventScroll: true });
+    el?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  };
+  const onFocus = (event) => {
+    const n = dayOf(event.target);
+    if (n == null) return;
+    setFocusState(n);
+    setDismissed(false);
+    setActive(n);
+  };
+  const onBlur = (event) => {
+    if (!event.currentTarget.contains(event.relatedTarget)) setActive(null);
+  };
+  const onPointerOver = (event) => {
+    const n = dayOf(event.target);
+    if (!navigable(n)) return;
+    setDismissed(false);
+    setActive(n);
+  };
+  const onPointerLeave = (event) => {
+    const focused = event.currentTarget.contains(document.activeElement) ? dayOf(document.activeElement) : null;
+    setActive(focused);
+  };
+  const bodyRef = useRef(null);
+  const [tip, setTip] = useState(null);
+  const showTip = tooltip !== false && !loading && !dismissed && navigable(active);
+  useIsomorphicLayoutEffect(() => {
+    if (!showTip || active == null) {
+      setTip(null);
+      return;
+    }
+    const place = () => {
+      const el = cellAt(active);
+      const host = bodyRef.current;
+      if (!el || !host) return setTip(null);
+      const c = el.getBoundingClientRect();
+      const h = host.getBoundingClientRect();
+      const x = c.left - h.left + c.width / 2;
+      setTip({ x, y: c.top - h.top, align: x < h.width * 0.2 ? "start" : x > h.width * 0.8 ? "end" : "center" });
+    };
+    place();
+    const region = scrollRef.current;
+    region?.addEventListener("scroll", place, { passive: true });
+    return () => region?.removeEventListener("scroll", place);
+  }, [showTip, active, cell]);
+  const tipDay = active != null && showTip ? resolve(active) : null;
+  const tipContent = tipDay == null ? null : typeof tooltip === "function" ? /* @__PURE__ */ jsx(ChartTooltipContent, { label: tooltip(tipDay), rows: [] }) : /* @__PURE__ */ jsx(
+    ChartTooltipContent,
+    {
+      label: words.short(dayNumber(tipDay.date)),
+      rows: [{ key: "value", label: tipDay.categoryLabel ?? words.unitTitle, value: tipDay.value > 0 ? words.number(tipDay.value) : "0", color: tipDay.color }]
+    }
+  );
+  const weeksCount = grid.weeks.length;
+  const showWeekday = (r) => weekdayLabels === "all" || weekdayLabels === "alternate" && SHOWN_WEEKDAYS.has((firstDay + r) % 7);
+  const vars = { "--heat-cell": `${cell}px`, "--heat-gap": `${gap}px` };
+  return /* @__PURE__ */ jsxs(
+    "figure",
+    {
+      ref: figureRef,
+      "data-reveal": shown ? "in" : "out",
+      "data-motion": motionAttribute(motion),
+      className: cn("m-0 flex w-full min-w-0 flex-col gap-2", className),
+      style: { ...vars, ...style },
+      ...props,
+      children: [
+        /* @__PURE__ */ jsxs("div", { ref: bodyRef, className: "relative flex min-w-0 items-start", children: [
+          weekdayLabels !== "none" ? (
+            // Outside the scroller on purpose: labels that sat inside it, pinned
+            // over the cells, let the weeks slide under them on a phone.
+            /* @__PURE__ */ jsxs("div", { "aria-hidden": true, className: "flex shrink-0 flex-col gap-(--heat-gap) pe-1 pt-[calc(var(--heat-gap)+--spacing(1))] text-caption text-muted-foreground", children: [
+              monthLabels ? /* @__PURE__ */ jsx("span", { className: "h-5" }) : null,
+              [0, 1, 2, 3, 4, 5, 6].map((r) => /* @__PURE__ */ jsx("span", { className: "flex h-(--heat-cell) items-center leading-none", children: showWeekday(r) ? words.dayShort((firstDay + r) % 7) : null }, r))
+            ] })
+          ) : null,
+          /* @__PURE__ */ jsx("div", { ref: areaRef, className: "min-w-0 flex-1", children: /* @__PURE__ */ jsx(Scroller, { ref: scrollRef, orientation: "horizontal", tabIndex: -1, role: "presentation", "aria-label": void 0, children: /* @__PURE__ */ jsx("div", { className: "relative w-max p-1", children: /* @__PURE__ */ jsxs(
+            "table",
+            {
+              ref: tableRef,
+              role: "grid",
+              "aria-readonly": selectable ? void 0 : true,
+              "aria-busy": loading || void 0,
+              "aria-labelledby": `${uid}-caption`,
+              onKeyDown,
+              onFocus,
+              onBlur,
+              onPointerOver,
+              onPointerLeave,
+              onClick: (event) => {
+                const n = dayOf(event.target);
+                if (selectable && navigable(n)) select(n);
+              },
+              className: "border-separate border-spacing-(--heat-gap)",
+              children: [
+                /* @__PURE__ */ jsx("caption", { id: `${uid}-caption`, className: "sr-only", children: label }),
+                monthLabels ? /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+                  /* @__PURE__ */ jsx("td", { className: "sr-only" }),
+                  grid.months.map((m, i) => /* @__PURE__ */ jsxs(
+                    "th",
+                    {
+                      scope: "col",
+                      colSpan: m.span,
+                      className: "h-5 overflow-visible whitespace-nowrap p-0 text-start align-bottom text-caption text-muted-foreground",
+                      children: [
+                        /* @__PURE__ */ jsx("span", { className: "sr-only", children: words.monthLong(m.day) }),
+                        /* @__PURE__ */ jsx("span", { "aria-hidden": true, children: m.span >= 3 || i > 0 && m.span >= 2 ? words.monthShort(m.day) : null })
+                      ]
+                    },
+                    m.day
+                  ))
+                ] }) }) : null,
+                /* @__PURE__ */ jsx("tbody", { children: [0, 1, 2, 3, 4, 5, 6].map((r) => /* @__PURE__ */ jsxs("tr", { children: [
+                  /* @__PURE__ */ jsx("th", { scope: "row", className: "sr-only", children: words.dayLong((firstDay + r) % 7) }),
+                  grid.weeks.map((week, w) => {
+                    const n = week.days[r];
+                    if (n == null) return /* @__PURE__ */ jsx("td", { "aria-hidden": true, className: "p-0" }, w);
+                    if (n > last) {
+                      return /* @__PURE__ */ jsx("td", { "aria-hidden": true, className: "size-(--heat-cell) rounded-xs border border-border-strong p-0" }, w);
+                    }
+                    const day = resolve(n);
+                    const isActive = n === active && showTip;
+                    return /* @__PURE__ */ jsx(
+                      "td",
+                      {
+                        role: "gridcell",
+                        "data-date": day.date,
+                        "data-level": day.level,
+                        "data-active": isActive || void 0,
+                        tabIndex: n === focusDay ? 0 : -1,
+                        "aria-label": `${words.long(n)}: ${words.value(day.value)}${day.categoryLabel ? `, ${day.categoryLabel}` : ""}`,
+                        "aria-describedby": `${uid}-level-${day.level}`,
+                        "aria-selected": selectable ? n === selected : void 0,
+                        className: cn(
+                          "relative size-(--heat-cell) rounded-[min(var(--radius-xs),calc(var(--heat-cell)/4))] p-0 outline-offset-1 outline-ring",
+                          "focus-visible:outline-2 data-active:outline-2 aria-selected:outline-2 aria-selected:outline-foreground",
+                          "[[data-reveal=out]_&]:opacity-0",
+                          // Forced colours flatten every fill to one system colour, so the
+                          // level becomes the size of an inner square instead.
+                          "forced-colors:forced-color-adjust-none forced-colors:bg-[CanvasText] forced-colors:[clip-path:inset(var(--heat-inset))]",
+                          loading && "motion-shimmer"
+                        ),
+                        style: {
+                          backgroundColor: day.color,
+                          "--heat-inset": `${Math.round((levels - 1 - day.level) / Math.max(1, levels - 1) * 40)}%`,
+                          transition: `${riseTransition(stagger(Math.round(w * 24 / Math.max(1, weeksCount - 1))))}, background-color var(--motion-duration-base) var(--motion-ease-standard)`
+                        },
+                        children: renderCell ? /* @__PURE__ */ jsx("span", { className: "absolute inset-0 flex items-center justify-center", children: renderCell(day, { level: day.level, color: day.color, size: cell }) }) : null
+                      },
+                      w
+                    );
+                  })
+                ] }, r)) })
+              ]
+            }
+          ) }) }) }),
+          tip && tipContent ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              "aria-hidden": true,
+              className: "pointer-events-none absolute start-0 top-0 z-10 transition-transform duration-(--motion-duration-fast) ease-standard",
+              style: { transform: `translate(${Math.round(tip.x)}px, ${Math.round(tip.y)}px)` },
+              children: /* @__PURE__ */ jsx(
+                "div",
+                {
+                  className: cn(
+                    "w-max -translate-y-full pb-2",
+                    tip.align === "center" && "-translate-x-1/2",
+                    tip.align === "end" && "-translate-x-full"
+                  ),
+                  children: tipContent
+                }
+              )
+            }
+          ) : null
+        ] }),
+        /* @__PURE__ */ jsx("div", { hidden: true, children: names.map((name, k) => /* @__PURE__ */ jsx("span", { id: `${uid}-level-${k}`, children: name }, name)) }),
+        legend && categories ? /* @__PURE__ */ jsx(
+          ChartLegend,
+          {
+            className: "justify-start",
+            items: categoryKeys.map((key, i) => ({ key, ...categoryStyle(categories, key, i) }))
+          }
+        ) : legend ? /* @__PURE__ */ jsxs("div", { "aria-hidden": true, className: "flex items-center justify-end gap-1 text-caption text-muted-foreground", children: [
+          /* @__PURE__ */ jsx("span", { className: "me-1", children: legendLabels[0] }),
+          names.map((name, k) => /* @__PURE__ */ jsx("span", { className: "size-2.5 rounded-[2px]", style: { backgroundColor: heatColor(base, k, levels) } }, name)),
+          /* @__PURE__ */ jsx("span", { className: "ms-1", children: legendLabels[1] })
+        ] }) : null
+      ]
+    }
+  );
+}
+ActivityHeatmap.displayName = "ActivityHeatmap";
+export {
+  ActivityHeatmap
+};

package/dist/components/activity-heatmap/activity-heatmap.meta.js

@@ -0,0 +1,142 @@
+// src/components/activity-heatmap/activity-heatmap.meta.ts
+var activityHeatmapMeta = {
+  name: "ActivityHeatmap",
+  summary: "A calendar heatmap: one value per day as a grid of weeks by weekdays \u2014 the GitHub contribution graph, for any daily measure. Levels by quartile, categories by source, a real ARIA grid with one tab stop, and a sideways scroll on narrow screens that opens on the latest week.",
+  keywords: [
+    "heatmap",
+    "calendar heatmap",
+    "contribution graph",
+    "contributions",
+    "activity",
+    "github",
+    "streak",
+    "habit",
+    "daily",
+    "commits",
+    "uptime"
+  ],
+  usage: {
+    description: "Use ActivityHeatmap to show how often something happened day by day over weeks or months: commits, habits kept, orders, uptime. Pass days as ISO dates with a value; levels, colours, labels, keyboard and tooltips work with no further props. Put it inside a Card and compose any totals beside it (NumberTicker, StatRowBlock). For a value over time that a reader needs to compare precisely, use AreaChart or BarChart; for a month calendar with marked days (a streak calendar), use Calendar.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Pass dates as "YYYY-MM-DD" strings. The grid reads them as calendar days, so no time zone can shift a day \u2014 never build them with `new Date(...).toISOString()` from a local date.'
+      },
+      {
+        guidance: "do",
+        description: 'Give it a `unit` ("contribution" / "contributions") so the tooltip and every cell\'s name say what the number counts.'
+      },
+      {
+        guidance: "do",
+        description: "Let the default quantile scale pick levels \u2014 one exceptional day then does not wash every other day out. Pass a day's own `level` when the source already has one (GitHub's API)."
+      },
+      {
+        guidance: "dont",
+        description: "Use it for a handful of values or for values a reader must compare exactly; a heatmap shows rhythm, not amounts. Use BarChart.",
+        instead: ["BarChart", "AreaChart"]
+      },
+      {
+        guidance: "dont",
+        description: "Use it for a single month of marked days with a streak; that is Calendar with modifiers.",
+        instead: ["Calendar"]
+      },
+      {
+        guidance: "dont",
+        description: "Fetch inside the component or call GitHub from the browser with a token. Fetch on your server and pass days in; `@sableui/react/adapters/github` converts GitHub's response."
+      }
+    ],
+    anatomy: [
+      { name: "Weekday labels", required: false, description: "Short weekday names beside the rows, outside the scroller so the weeks never slide under them." },
+      { name: "Month labels", required: false, description: "Short month names over each month's first week; they scroll with their weeks." },
+      { name: "Cell grid", required: true, description: "A role=grid table, one gridcell per day, inside a horizontal Scroller that opens on the latest week." },
+      { name: "Tooltip", required: false, description: "The chart tooltip card, anchored to the hovered, focused or tapped day." },
+      { name: "Legend", required: false, description: "A Less\u2013More ramp for intensity, or swatches for categories." }
+    ]
+  },
+  related: {
+    components: ["Card", "NumberTicker", "BarChart", "Calendar", "Scroller"]
+  },
+  status: "stable",
+  props: [
+    { name: "label", type: "string", description: 'What the grid shows ("Contributions in 2026") \u2014 its caption and accessible name.' },
+    {
+      name: "data",
+      type: "ActivityDay[] | Record<string, number>",
+      description: 'The days: `{ date: "YYYY-MM-DD", value, level?, category? }[]`, or a map of date to value. Sparse is fine \u2014 a missing day is 0; duplicates sum.'
+    },
+    { name: "start", type: "string", default: "53 weeks before end", description: `First day drawn, "YYYY-MM-DD". The default starts at the beginning of that week, as GitHub's does.` },
+    { name: "end", type: "string", default: "today", description: "Last day drawn. Days after today inside the range are drawn hollow and skipped by the keyboard." },
+    { name: "year", type: "number", description: "Draw Jan 1 \u2013 Dec 31 of this year. Wins over start / end." },
+    { name: "weekStart", type: "0 | 1", default: "the locale's", description: "0 puts Sunday on the top row, 1 Monday." },
+    { name: "levels", type: "number", default: "5", description: "How many levels, including the empty level 0." },
+    {
+      name: "levelScale",
+      type: '"quantile" | "linear" | number[] | ((value, stats) => number)',
+      default: '"quantile"',
+      description: "How a value becomes a level. Quantile splits the positive values evenly, as GitHub does; an array gives each level's lower bound from 1 up; a function decides. A day's own `level` always wins."
+    },
+    { name: "tone", type: "ChartTone", default: '"1"', description: 'The hue of the intensity ramp. Decorative tones lead, as on every chart; "success" gives the GitHub look.' },
+    { name: "categories", type: "ChartCategories", description: "Colour days by `day.category` (label, tone or colour per key). Pair with `levels={2}` for flat category colours." },
+    { name: "unit", type: "string | { one: string; other: string }", description: "Names the value in the tooltip and each cell's accessible name, pluralised with Intl.PluralRules." },
+    { name: "formatValue", type: "(value: number) => string", default: "full to 9,999, compact past", description: "Formats a value wherever it is shown or read." },
+    { name: "tooltip", type: "boolean | ((day: ActivityHeatmapDay) => ReactNode)", default: "true", description: "Show the tooltip on hover, focus and tap; a function replaces its content on the same card." },
+    { name: "legend", type: "boolean", default: "true", description: "The Less\u2013More ramp for intensity, swatches for categories." },
+    { name: "legendLabels", type: "[string, string]", default: '["Less", "More"]', description: "The ramp's end words." },
+    { name: "monthLabels", type: "boolean", default: "true", description: "Short month names over each month's first week." },
+    { name: "weekdayLabels", type: '"alternate" | "all" | "none"', default: '"alternate"', description: "Which weekday names to show beside the rows; alternate is Mon, Wed, Fri." },
+    { name: "size", type: '"sm" | "md" | "lg"', default: '"md"', description: "The smallest a cell may get (10, 12, 14 px) before the grid scrolls instead of shrinking." },
+    { name: "stretch", type: "boolean", default: "true", description: "Grow cells to fill the width, up to 20 px. false keeps them at `size`." },
+    { name: "activeDate", type: "string | null", description: "The hovered or focused day, controlled. Pair with defaultActiveDate / onActiveDateChange." },
+    { name: "selectedDate", type: "string | null", description: "The selected day, controlled. Selection is on only when onSelectDate is set." },
+    { name: "onSelectDate", type: "(date: string) => void", description: "Called when a day is clicked or chosen with Enter / Space \u2014 to filter a feed below, as GitHub does." },
+    { name: "renderCell", type: "(day, cell) => ReactNode", description: "Draw something over a cell's fill \u2014 an icon for a milestone, a reward, an outage." },
+    { name: "loading", type: "boolean", default: "false", description: "Draw the empty grid, shimmering, while data loads." },
+    { name: "motion", type: '"full" | "subtle" | "off"', default: '"full"', description: "Turns the arrival down; `subtle` shows the finished grid at once." },
+    { name: "locale", type: "string", default: "runtime locale", description: "Month and weekday names, numbers and plurals." }
+  ],
+  tokensUsed: ["foreground", "muted-foreground", "border-strong", "ring", "tone-1-mark", "tone-2-mark", "tone-3-mark", "success-mark", "tone-info-mark"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "custom",
+      part: "Cell grid",
+      why: "Weeks fade in left to right as the grid first scrolls into view, staggered on the chart motion helpers; expressive, so subtle shows the finished grid."
+    },
+    {
+      slot: "response",
+      recipe: "custom",
+      part: "Cell",
+      why: "The active day takes a ring outline at once and the tooltip glides to it; the other cells stay still \u2014 dimming hundreds of cells reads as a flash."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Cell",
+      why: "When data or the range changes, each cell's fill cross-fades on the base duration token, so the reader sees which days changed."
+    },
+    { slot: "activity", recipe: "motion-shimmer", part: "Cell grid", why: "`loading` shimmers the empty grid until days arrive." }
+  ],
+  a11y: [
+    "The grid is a role=grid table, as GitHub's is: weekday row headers and month column headers carry full names for screen readers, and the caption is `label`.",
+    "One tab stop. Arrows move a day or a week; Home / End go to the ends of the row, Page Up / Page Down to the ends of the column, Ctrl+Home / Ctrl+End to the first and last day. Enter or Space selects when onSelectDate is set; Escape hides the tooltip.",
+    `Each cell is named with its date and value ("Tuesday, October 14, 2026: 12 contributions") and described by its level's words, which the legend repeats visually.`,
+    "Levels rise in lightness, so they read without colour; under forced colours each level draws as a larger inner square."
+  ],
+  examples: [
+    {
+      label: "Contributions, last year",
+      code: 'const days = [\n	{ date: "2026-10-12", value: 4 },\n	{ date: "2026-10-13", value: 11 },\n	{ date: "2026-10-14", value: 2 },\n]\n\n<ActivityHeatmap label="Contributions in the last year" data={days} tone="success" unit={{ one: "contribution", other: "contributions" }} />'
+    },
+    {
+      label: "Two sources, in a card",
+      code: 'const github = [{ date: "2026-10-13", value: 6 }]\nconst codex = [{ date: "2026-10-13", value: 1 }, { date: "2026-10-14", value: 3 }]\n\n<Card>\n	<CardHeader>\n		<CardTitle>Building, day by day</CardTitle>\n	</CardHeader>\n	<CardContent>\n		<ActivityHeatmap\n			label="GitHub and Codex activity in 2026"\n			year={2026}\n			levels={2}\n			data={mergeActivity({ github, codex })}\n			categories={{ github: { label: "GitHub", tone: "success" }, codex: { label: "Codex", tone: "info" }, both: { label: "Both", tone: "2" } }}\n		/>\n	</CardContent>\n</Card>'
+    },
+    {
+      label: "Selecting a day",
+      code: 'const [day, setDay] = useState<string | null>(null)\n\n<ActivityHeatmap label="Orders per day" data={{ "2026-10-13": 18, "2026-10-14": 25 }} unit="orders" selectedDate={day} onSelectDate={setDay} />'
+    }
+  ]
+};
+export {
+  activityHeatmapMeta
+};

package/dist/components/activity-heatmap/index.js

@@ -0,0 +1,9 @@
+// src/components/activity-heatmap/index.ts
+import {
+  ActivityHeatmap
+} from "./activity-heatmap.js";
+import { activityHeatmapMeta } from "./activity-heatmap.meta.js";
+export {
+  ActivityHeatmap,
+  activityHeatmapMeta
+};

package/dist/components/code-block/code-block.js

@@ -25,6 +25,7 @@ function CodeBlock({
   showCopy = true,
   highlight,
   prompt,
+  wrap = false,
   className,
   ...props
 }) {
@@ -73,10 +74,11 @@ function CodeBlock({
           "pre",
           {
             ref: preRef,
-            onScroll: fade.sync,
-            style: fade.style,
+            onScroll: wrap ? void 0 : fade.sync,
+            style: wrap ? void 0 : fade.style,
             className: cn(
-              "overflow-x-auto overscroll-x-contain p-4 text-mono-md text-foreground scrollbar-quiet",
+              "p-4 text-mono-md text-foreground",
+              wrap ? "whitespace-pre-wrap break-words" : "overflow-x-auto overscroll-x-contain scrollbar-quiet",
               copyColumn && "min-w-0 flex-1 pe-2"
             ),
             children: /* @__PURE__ */ jsx("code", { children: highlighter ? highlighter(code) : code })

package/dist/components/code-block/code-block.meta.js

@@ -69,6 +69,12 @@ var codeBlockMeta = {
       name: "prompt",
       type: "string",
       description: 'A shell prompt ("$", ">"). Makes it a one-line command: the prompt is dimmed and unselectable, the line truncates, and copy takes only code.'
+    },
+    {
+      name: "wrap",
+      type: "boolean",
+      default: "false",
+      description: "Wrap long lines instead of scrolling them. For prose in a code face (a prompt to paste into an agent, a log line); code keeps scrolling, since wrapping breaks its indentation."
     }
   ],
   subcomponents: [