@celestia-island/hikari 0.55.230 → 0.55.232

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.230",
+  "version": "0.55.232",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkAvatarButton.test.tsx

@@ -1,5 +1,8 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { HkAvatarButton } from "./HkAvatarButton";
 import { HkAdminHeader } from "./HkAdminHeader";
@@ -107,6 +110,61 @@ describe("HkAvatarButton", () => {
   });
 });
 
+describe("HkAvatarButton sheet contract", () => {
+  // happy-dom has no layout engine, so the geometry is pinned at the
+  // source level — the same approach the downstream chest tripwire
+  // (headerAvatarGeometry.test.ts) takes against the INSTALLED sheet.
+  const sheet = readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "..", "styles", "admin-tokens.scss"),
+    "utf8",
+  );
+
+  /** Declarations of the rule whose whole prelude IS `selector`
+   *  (a compound/descendant spelling is a different rule and does not
+   *  match), comments stripped; null when no such rule exists — every
+   *  assertion treats null as a failure, never as "no objection". */
+  function ruleDeclarations(selector: string): Array<[string, string]> | null {
+    const code = sheet
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/(^|[^:])\/\/[^\n]*/gm, "$1");
+    for (let at = code.indexOf(selector); at >= 0; at = code.indexOf(selector, at + 1)) {
+      const open = code.indexOf("{", at + selector.length);
+      if (open < 0) continue;
+      if (code.slice(at + selector.length, open).trim() !== "") continue;
+      let boundary = at - 1;
+      while (boundary >= 0 && !"}{;".includes(code[boundary])) boundary -= 1;
+      if (code.slice(boundary + 1, at).replace(/\s+/g, " ").trim() !== "") continue;
+      const body = code.slice(open + 1, code.indexOf("}", open));
+      const out: Array<[string, string]> = [];
+      for (const part of body.split(";")) {
+        const m = /^\s*([-a-zA-Z]+)\s*:\s*([\s\S]+?)\s*$/.exec(part);
+        if (m) out.push([m[1], m[2].replace(/\s+/g, " ")]);
+      }
+      return out;
+    }
+    return null;
+  }
+
+  it("the trigger is a BLOCK — hosts may nest it in a plain wrapper div", () => {
+    // The chat face wraps HeaderLeft's trigger in a menu-anchor <div>:
+    // an inline-block button there joins a line box and the strut's
+    // descender space lands BELOW it, riding the avatar ~4px high inside
+    // a perfectly centred wrapper (2026-10-30 user report). Removing
+    // this declaration is the mutation this test must catch.
+    const rule = ruleDeclarations(".s-admin-header-avatar");
+    expect(rule, "admin-tokens must declare .s-admin-header-avatar").not.toBeNull();
+    // Positive control for the extractor itself: the geometry pair the
+    // downstream tripwire also reads. If these stop matching, the parser
+    // above is broken — fix it, not the assertion below.
+    expect(rule).toContainEqual(["width", "var(--space-28)"]);
+    expect(rule).toContainEqual(["height", "var(--space-28)"]);
+    expect(rule, "the trigger must not re-enter inline formatting").toContainEqual([
+      "display",
+      "block",
+    ]);
+  });
+});
+
 describe("HkAdminHeader × HkAvatarButton / identity slot", () => {
   it("never renders aria-expanded when no expanded prop is given (drawer-mode contract)", () => {
     // R2 S3-2: menu engines read this pair; a drawer-mode trigger has no

package/src/components/HkCalendarHeatmap.scss

@@ -0,0 +1,90 @@
+// HkCalendarHeatmap — GitHub-style calendar heatmap anatomy.
+//
+// Self-sufficient styling (the component self-sufficiency guard): every
+// class lives here, no host atomic/utility layer. The dynamic geometry
+// (cell size, gap, week-column count, rail row rhythm) stays inline in
+// the component; this sheet owns the static layout and typography.
+
+.hk-calendar-heatmap {
+  // The legend row: scale on the LEFT, toolbar slot on the RIGHT.
+  &-head {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    column-gap: 16px;
+    row-gap: 8px;
+  }
+
+  &-legend {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    font-size: 10px;
+    color: var(--hi-color-muted);
+  }
+
+  // w-max + auto margins center the whole calendar (rail included) on
+  // wide cards while letting narrow screens scroll from the left edge —
+  // auto margins resolve to zero when the content overflows, so mobile
+  // keeps its natural scroll origin.
+  &-scroll {
+    margin-top: 12px;
+    overflow-x: auto;
+    padding-bottom: 4px;
+  }
+
+  &-body {
+    display: flex;
+    width: max-content;
+    margin-inline: auto;
+    gap: 8px;
+  }
+
+  // Weekday rail: the first (Monday) and last (Sunday) rows carry the
+  // labels (the wowsp convention); sticky so it survives horizontal
+  // scroll on narrow screens.
+  &-rail {
+    position: sticky;
+    left: 0;
+    z-index: 1;
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    padding-right: 2px;
+    font-size: 10px;
+    line-height: 14px;
+    color: var(--hi-color-muted);
+    background: var(--hi-color-surface);
+
+    > span {
+      white-space: nowrap;
+    }
+  }
+
+  &-cells {
+    flex: 1;
+    min-width: 0;
+  }
+
+  // Month markers, one slot per week column; labels overflow their
+  // 14px column into the empty cells ahead (the GitHub convention — a
+  // month marker is always followed by unmarked columns), so no
+  // truncating: a clipped "O…" tells nothing.
+  &-markers {
+    display: grid;
+    margin-bottom: 4px;
+    font-size: 10px;
+    line-height: 12px;
+    color: var(--hi-color-muted);
+
+    > span {
+      white-space: nowrap;
+    }
+  }
+
+  // The grid itself: cells flow column-first into 7 rows.
+  &-grid {
+    display: grid;
+  }
+}

package/src/components/HkCalendarHeatmap.test.tsx

@@ -0,0 +1,240 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, reactive } from "vue";
+
+import HkCalendarHeatmap from "./HkCalendarHeatmap";
+import { HEATMAP_LEVEL_OPACITY, todayIso } from "./calendarHeatmap";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+/** A Monday, NOT the 1st — the leading-partial-month shape. */
+const MID_MONTH_MON = "2025-10-27";
+/** A Monday AND the 1st — the clean head shape. */
+const CLEAN_HEAD_MON = "2025-12-01";
+
+const daysFrom = (start: string, count: number, value = 0) =>
+  Array.from({ length: count }, (_, i) => {
+    const d = new Date(`${start}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + i);
+    return { date: d.toISOString().slice(0, 10), value };
+  });
+
+describe("HkCalendarHeatmap", () => {
+  it("renders the legend (less → more, five swatches) and the grid anatomy", () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: daysFrom(CLEAN_HEAD_MON, 7),
+        first: null,
+        unit: "度",
+      }),
+    );
+    const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+    expect(grid).toBeTruthy();
+    expect(grid.getAttribute("role")).toBe("img");
+    // One row of days pads into exactly one week.
+    expect(grid.getAttribute("aria-label")).toContain("1");
+    const legend = c.querySelector('[data-testid="hk-calendar-heatmap-legend"]');
+    expect(legend?.textContent).toContain("Less");
+    expect(legend?.textContent).toContain("More");
+    expect(c.querySelectorAll("[data-legend-level]")).toHaveLength(
+      HEATMAP_LEVEL_OPACITY.length,
+    );
+    // One week of days, all level 0 (no consumption): plain muted cells.
+    expect(grid.querySelectorAll('[data-level="0"]')).toHaveLength(7);
+  });
+
+  it("suppresses the leading month marker when the window starts mid-month", async () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        // Trailing-October tail + November: the partial October head is
+        // unlabeled, November's Monday carries the only marker.
+        days: daysFrom(MID_MONTH_MON, 10),
+        first: null,
+      }),
+    );
+    await nextTick();
+    const markers = c.querySelectorAll(
+      ".hk-calendar-heatmap-markers > span",
+    ) as NodeListOf<HTMLElement>;
+    expect(markers.length).toBeGreaterThanOrEqual(2);
+    expect(markers[0].textContent).toBe(""); // partial October — suppressed
+    expect(markers[1].textContent).not.toBe(""); // November — labeled
+  });
+
+  it("shows the leading month marker when the grid's first column opens its month", async () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: daysFrom(CLEAN_HEAD_MON, 9),
+        first: null,
+      }),
+    );
+    await nextTick();
+    const markers = c.querySelectorAll(
+      ".hk-calendar-heatmap-markers > span",
+    ) as NodeListOf<HTMLElement>;
+    expect(markers[0].textContent).not.toBe(""); // Dec 1 — labeled
+  });
+
+  it("renders gap cells hatched and inert (no tooltip, no level claim)", () => {
+    // A one-day series AT today, anchored at first = today: the head
+    // padding hatches as "before", the tail as "after" — both phases in
+    // one grid, all deterministic against the real clock.
+    const today = todayIso();
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: [{ date: today, value: 5 }],
+        first: today,
+      }),
+    );
+    const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+    const gaps = grid.querySelectorAll("[data-gap]") as NodeListOf<HTMLElement>;
+    expect(gaps.length).toBeGreaterThan(0);
+    const phases = new Set(
+      Array.from(gaps, (gap) => gap.getAttribute("data-gap")),
+    );
+    expect(phases.has("before")).toBe(true);
+    expect(phases.has("after")).toBe(true);
+    for (const gap of gaps) {
+      expect(gap.getAttribute("aria-hidden")).toBe("true");
+      expect(gap.getAttribute("title")).toBeNull();
+      expect(gap.style.pointerEvents).toBe("none");
+    }
+  });
+
+  it("tooltips day cells with the unit when one is given", () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: daysFrom(CLEAN_HEAD_MON, 1, 5),
+        first: null,
+        unit: "度",
+      }),
+    );
+    const cell = c.querySelector('[data-level]:not([data-level="0"])') as HTMLElement;
+    expect(cell).toBeTruthy();
+    // The UTC zone is explicit (R2: a negative-offset host must not
+    // land the tooltip a day off) — the date is TZ-deterministic.
+    expect(cell.getAttribute("title")).toContain("Dec 1, 2025");
+    expect(cell.getAttribute("title")).toContain("5");
+    expect(cell.getAttribute("title")).toContain("度");
+  });
+
+  it("wires the max prop into the cell buckets, not just data-max", () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        // Peak 10 in-window; the pinned max 100 flattens both days to
+        // level 1 (R2 S1: the prop was a dead wire to data-max).
+        days: [{ date: CLEAN_HEAD_MON, value: 10 }, { date: "2025-12-02", value: 1 }],
+        first: null,
+        max: 100,
+      }),
+    );
+    const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+    expect(grid.getAttribute("data-max")).toBe("100");
+    expect(grid.querySelectorAll('[data-level="1"]')).toHaveLength(2);
+    expect(grid.querySelectorAll('[data-level="4"]')).toHaveLength(0);
+  });
+
+  it("tooltips day cells without a dangling separator when unitless", () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: daysFrom(CLEAN_HEAD_MON, 1, 5),
+        first: null,
+      }),
+    );
+    const cell = c.querySelector('[data-level]:not([data-level="0"])') as HTMLElement;
+    // The unitless title ends at the count — no trailing "· <empty>".
+    expect(cell.getAttribute("title")).toMatch(/· 5$/);
+  });
+
+  it("labels the weekday rail on the first and last rows only", () => {
+    const c = mount(
+      h(HkCalendarHeatmap, { days: daysFrom(CLEAN_HEAD_MON, 7), first: null }),
+    );
+    const rail = c.querySelector(".hk-calendar-heatmap-rail") as HTMLElement;
+    const rows = rail.querySelectorAll(":scope > span") as NodeListOf<HTMLElement>;
+    expect(rows).toHaveLength(7);
+    expect(rows[0].textContent).not.toBe(""); // Monday
+    expect(rows[6].textContent).not.toBe(""); // Sunday
+    expect(rows[3].textContent).toBe(""); // middle rows unlabeled
+  });
+
+  it("renders the toolbar slot right of the legend", () => {
+    const Toolbar = defineComponent({
+      name: "FakeToolbar",
+      setup: () => () => h("div", { "data-fake-toolbar": "" }, "tabs"),
+    });
+    const c = mount(
+      h(HkCalendarHeatmap, { days: daysFrom(CLEAN_HEAD_MON, 7), first: null }, {
+        toolbar: () => h(Toolbar),
+      }),
+    );
+    expect(c.querySelector("[data-fake-toolbar]")?.textContent).toBe("tabs");
+  });
+
+  it("renders an empty grid without markers for an empty series", () => {
+    const c = mount(h(HkCalendarHeatmap, { days: [], first: null }));
+    const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+    expect(grid).toBeTruthy();
+    expect(grid.querySelectorAll("[data-level]")).toHaveLength(0);
+    expect(c.querySelectorAll(".hk-calendar-heatmap-markers > span")).toHaveLength(0);
+  });
+
+  it("re-takes today per recompute — a refetch across UTC midnight un-gaps the new today cell", async () => {
+    // R2 S2 + R3 变异留证: today frozen at setup rendered the next
+    // day as an "after" gap even after the caller refetched a series
+    // that includes it. A recompute (the refetch's new `days`) must
+    // re-evaluate todayIso() — the crossed-midnight day becomes a day.
+    // (A rerender with NO dep change legitimately keeps the cached
+    // cells — computed semantics, nothing changed.)
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date("2025-12-01T10:00:00Z"));
+      // Dense series through the mount-time today: Fri 11-28 .. Mon 12-01.
+      const days = daysFrom("2025-11-28", 4);
+      const state = reactive({ days });
+      // The vnode is built INSIDE the render so the reactive `days`
+      // re-renders — the shared eager mount helper would capture one
+      // static vnode.
+      const container = document.createElement("div");
+      document.body.appendChild(container);
+      const app = createApp({
+        render: () => h(HkCalendarHeatmap, { days: state.days, first: null, unit: "度" }),
+      });
+      app.mount(container);
+      mounts.push({ app, container });
+      const grid = container.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+      const tomorrowAtMount = grid.querySelector('[data-date="2025-12-02"]') as HTMLElement;
+      expect(tomorrowAtMount.getAttribute("data-gap")).toBe("after");
+
+      // Cross UTC midnight; the refetched series now includes the new
+      // today (12-02, 3 度) — a new array instance, so the cells
+      // computed recomputes and re-takes today.
+      vi.setSystemTime(new Date("2025-12-02T10:00:00Z"));
+      state.days = [...days, { date: "2025-12-02", value: 3 }];
+      // Two ticks: the parent's render → the child's props update → the
+      // child's re-render land in sequence.
+      await nextTick();
+      await nextTick();
+      const nowToday = grid.querySelector('[data-date="2025-12-02"]') as HTMLElement;
+      expect(nowToday.getAttribute("data-gap")).toBeNull();
+      expect(nowToday.getAttribute("data-level")).toBe("4");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/components/HkCalendarHeatmap.tsx

@@ -0,0 +1,261 @@
+import { computed, defineComponent, type PropType } from "vue";
+
+import { useI18n } from "../i18n/context";
+import {
+  bucketLevel,
+  calendarGrid,
+  HEATMAP_LEVEL_OPACITY,
+  monthMarkers,
+  todayIso,
+  type CalendarCell,
+  type HkCalendarHeatmapDay,
+} from "./calendarHeatmap";
+import "./HkCalendarHeatmap.scss";
+
+/** The no-data cell (before the account's first activity / after
+ * today): muted diagonal hatch over the surface — the wowsp-style
+ * "not yet" cell. Rendered inert: no tooltip, no pointer events. */
+const GAP_HATCH =
+  "repeating-linear-gradient(45deg, color-mix(in srgb, var(--hi-color-muted) 70%, transparent) 0px, color-mix(in srgb, var(--hi-color-muted) 70%, transparent) 2px, transparent 2px, transparent 4px)";
+
+/** Minimal {name} interpolation for the component's i18n strings — the
+ * hikari context serves plain strings (no ICU), the placeholders stay
+ * in the locale bundles so translators keep the full sentence. */
+function fill(template: string, vars: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (_, k: string) => String(vars[k] ?? ""));
+}
+
+/**
+ * HkCalendarHeatmap — a GitHub-style calendar heatmap of daily values.
+ *
+ * Upstreamed from the shittim-chest quota page's degree-usage section
+ * (2026-10 user direction: a calendar heatmap is a big business
+ * component — the rich-text-viewer table — and the leading-month
+ * marker refinement belongs in the library, not the consumer). A
+ * legend (less → more over the primary token), a Monday-first weekday
+ * rail, month markers, and hatched no-data gap cells that never claim
+ * a fake zero.
+ *
+ * The leading month is suppressed when the window starts mid-month:
+ * the first column shows only the tail of its month, so the marker is
+ * rendered only when the grid's first column actually opens its month
+ * (Monday = the 1st) — a label over a partial head would claim a
+ * month start that is not visible.
+ *
+ * Dumb by design: the caller owns the fetch lifecycle and passes the
+ * settled dense series in (`days`, oldest → newest, zero-filled,
+ * inclusive of today) plus the account's first activity date (`first`,
+ * null = never). All math lives in ./calendarHeatmap (pure, pinned by
+ * its own tests). The `toolbar` slot rides right of the legend — the
+ * consumer's range tabs / controls belong there.
+ */
+export default defineComponent({
+  name: "HkCalendarHeatmap",
+  props: {
+    /** The dense daily series, oldest → newest, inclusive of today. */
+    days: {
+      type: Array as PropType<HkCalendarHeatmapDay[]>,
+      required: true,
+    },
+    /** The account's first activity date (null = never). */
+    first: { type: String as PropType<string | null>, default: null },
+    /** The unit the legend/tooltip names ("" = unitless values). */
+    unit: { type: String, default: "" },
+    /** Peak day pinned across windows (reaches the cell buckets, not
+     * just the data-max attribute); null = derive from `days`. */
+    max: { type: Number as PropType<number | null>, default: null },
+    /** Square-cell scale (GitHub-scale: a 53-week grid stays compact). */
+    cellSize: { type: Number, default: 14 },
+    cellGap: { type: Number, default: 3 },
+  },
+  setup(props, { slots }) {
+    const { t } = useI18n();
+
+    // The rendered calendar follows the selected range; `today` is
+    // taken per recompute (R2: frozen at setup, a long-mounted
+    // component crossing UTC midnight rendered its today cell as an
+    // "after" gap until the next remount), and the `max` prop pins the
+    // intensity scale — it must reach the buckets, not just the
+    // data-max attribute.
+    const cells = computed(() =>
+      calendarGrid(props.days, todayIso(), props.first, props.max),
+    );
+    const markers = computed(() => monthMarkers(cells.value));
+    const weeks = computed(() => Math.ceil(cells.value.length / 7));
+    const max = computed(() =>
+      props.max ?? props.days.reduce((m, d) => Math.max(m, d.value), 0),
+    );
+
+    const columns = computed(
+      () => `repeat(${weeks.value}, ${props.cellSize}px)`,
+    );
+
+    // Locale-reactive (the HkDateTimePicker convention): a computed
+    // over the context's locale so a locale switch re-renders the
+    // calendar's Intl-formatted labels. All formatters format the UTC
+    // midnight instant WITH an explicit UTC zone (R2: on a negative-
+    // offset host the weekday rail shifted a full row and tooltips
+    // landed a day off — the series' day boundary is UTC).
+    const locale = computed(() => useI18n().locale);
+    const weekdayLabel = (idx: number) =>
+      new Intl.DateTimeFormat(locale.value, {
+        weekday: "short",
+        timeZone: "UTC",
+      }).format(
+        // Any Monday-first week works — take 2024-01-01 (a Monday).
+        new Date(Date.UTC(2024, 0, 1 + idx)),
+      );
+    const monthLabel = (m: string) => {
+      if (!m) return "";
+      return new Intl.DateTimeFormat(locale.value, {
+        month: "short",
+        timeZone: "UTC",
+      }).format(new Date(Date.UTC(2024, Number(m) - 1, 1)));
+    };
+    const dateLabel = (iso: string) =>
+      new Intl.DateTimeFormat(locale.value, {
+        dateStyle: "medium",
+        timeZone: "UTC",
+      }).format(new Date(`${iso}T00:00:00Z`));
+
+    const cellTitle = (d: Extract<CalendarCell, { kind: "day" }>) =>
+      fill(
+        props.unit
+          ? t("hikari::calendarHeatmap.cellTitle", "{date} · {n} {unit}")
+          : t("hikari::calendarHeatmap.cellTitleNoUnit", "{date} · {n}"),
+        { date: dateLabel(d.date), n: d.value, unit: props.unit },
+      );
+
+    const cellStyle = (cell: CalendarCell) =>
+      cell.kind === "gap"
+        ? {
+            borderRadius: "3px",
+            background: GAP_HATCH,
+            pointerEvents: "none" as const,
+          }
+        : {
+            borderRadius: "3px",
+            background:
+              cell.level === 0
+                ? "color-mix(in srgb, var(--hi-color-muted) 40%, transparent)"
+                : "var(--hi-color-primary)",
+            opacity: cell.level === 0 ? undefined : HEATMAP_LEVEL_OPACITY[cell.level],
+          };
+
+    return () => (
+      <div class="hk-calendar-heatmap">
+        {/* The legend row: the scale in the caller's one unit on the
+         * LEFT, the toolbar slot on the RIGHT — the strip belongs to
+         * the centered grid's tail (2026-10-15 chest user direction,
+         * carried upstream with the component). */}
+        <div class="hk-calendar-heatmap-head">
+          <span
+            class="hk-calendar-heatmap-legend"
+            data-testid="hk-calendar-heatmap-legend"
+          >
+            {t("hikari::calendarHeatmap.less", "Less")}
+            {HEATMAP_LEVEL_OPACITY.map((o, i) => (
+              <span
+                key={i}
+                data-legend-level={i}
+                style={{
+                  width: "10px",
+                  height: "10px",
+                  borderRadius: "2px",
+                  background:
+                    i === 0
+                      ? "color-mix(in srgb, var(--hi-color-muted) 40%, transparent)"
+                      : "var(--hi-color-primary)",
+                  opacity: i === 0 ? undefined : o,
+                  display: "inline-block",
+                }}
+              />
+            ))}
+            {t("hikari::calendarHeatmap.more", "More")}
+          </span>
+          {slots.toolbar?.({})}
+        </div>
+
+        {/* The scroll wrapper centers the whole calendar (rail included)
+         * on wide cards while letting narrow screens scroll from the
+         * left edge (see the SCSS). */}
+        <div class="hk-calendar-heatmap-scroll">
+          <div class="hk-calendar-heatmap-body">
+            {/* Weekday rail: the first (Monday) and last (Sunday) rows
+             * carry the labels, the wowsp convention. */}
+            <div
+              aria-hidden="true"
+              class="hk-calendar-heatmap-rail"
+              style={{ rowGap: `${props.cellGap}px` }}
+            >
+              {[0, 1, 2, 3, 4, 5, 6].map((row) => (
+                <span
+                  key={row}
+                  style={{ height: `${props.cellSize}px`, lineHeight: `${props.cellSize}px` }}
+                >
+                  {row === 0 || row === 6 ? weekdayLabel(row) : ""}
+                </span>
+              ))}
+            </div>
+
+            <div class="hk-calendar-heatmap-cells">
+              {/* Month markers, one slot per week column. A leading
+               * partial month renders its empty slot (see
+               * monthMarkers). */}
+              <div
+                class="hk-calendar-heatmap-markers"
+                style={{
+                  gridTemplateColumns: columns.value,
+                  columnGap: `${props.cellGap}px`,
+                }}
+              >
+                {markers.value.map((m, i) => (
+                  <span key={i}>{monthLabel(m)}</span>
+                ))}
+              </div>
+
+              {/* The grid itself: cells flow column-first into 7 rows. */}
+              <div
+                data-testid="hk-calendar-heatmap"
+                data-max={max.value}
+                role="img"
+                aria-label={fill(
+                  t(
+                    "hikari::calendarHeatmap.summary",
+                    "Daily usage across {weeks} weeks",
+                  ),
+                  { weeks: weeks.value },
+                )}
+                class="hk-calendar-heatmap-grid"
+                style={{
+                  gridTemplateColumns: columns.value,
+                  gridTemplateRows: `repeat(7, ${props.cellSize}px)`,
+                  gridAutoFlow: "column",
+                  gap: `${props.cellGap}px`,
+                }}
+              >
+                {cells.value.map((cell, i) => (
+                  <span
+                    key={i}
+                    {...(cell.kind === "gap"
+                      ? {
+                          "data-gap": cell.phase,
+                          "data-date": cell.date,
+                          "aria-hidden": "true",
+                        }
+                      : {
+                          "data-level": cell.level,
+                          "data-date": cell.date,
+                          title: cellTitle(cell),
+                        })}
+                    style={cellStyle(cell)}
+                  />
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  },
+});

package/src/components/calendarHeatmap.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  bucketLevel,
+  calendarGrid,
+  monthMarkers,
+  shiftIso,
+  todayIso,
+  weekdayIndex,
+  type HkCalendarHeatmapDay,
+} from "./calendarHeatmap";
+
+/** A Monday, for grid-shape assertions. */
+const MON = "2025-12-01";
+
+describe("weekdayIndex", () => {
+  it("rotates getUTCDay to Monday-first", () => {
+    expect(weekdayIndex("2025-12-01")).toBe(0); // Monday
+    expect(weekdayIndex("2025-12-07")).toBe(6); // Sunday
+    expect(weekdayIndex("2025-12-02")).toBe(1); // Tuesday
+  });
+});
+
+describe("shiftIso", () => {
+  it("shifts in UTC without local-timezone leaks", () => {
+    expect(shiftIso("2025-12-01", 7)).toBe("2025-12-08");
+    expect(shiftIso("2025-12-01", -1)).toBe("2025-11-30");
+    expect(shiftIso("2026-01-01", -1)).toBe("2025-12-31"); // year wrap
+  });
+});
+
+describe("todayIso", () => {
+  it("returns a UTC ISO date", () => {
+    expect(todayIso()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+});
+
+describe("bucketLevel", () => {
+  it("keeps zero and negative days at level 0", () => {
+    expect(bucketLevel(0, 10)).toBe(0);
+    expect(bucketLevel(-3, 10)).toBe(0);
+    expect(bucketLevel(5, 0)).toBe(0); // degenerate window
+  });
+
+  it("scales against the window max with a ceil floor of 1", () => {
+    expect(bucketLevel(1, 100)).toBe(1); // smallest consumption shows
+    expect(bucketLevel(50, 100)).toBe(2);
+    expect(bucketLevel(75, 100)).toBe(3);
+    expect(bucketLevel(100, 100)).toBe(4);
+    expect(bucketLevel(1000, 100)).toBe(4); // capped at peak
+  });
+});
+
+describe("calendarGrid maxOverride — the max prop's wire to the buckets", () => {
+  it("pins the intensity scale against the override, not the window's own peak", () => {
+    const days = [{ date: MON, value: 10 }, { date: "2025-12-02", value: 1 }];
+    // Without an override the levels ride the window's own peak (10).
+    expect(calendarGrid(days, "2025-12-03", null).map((c) =>
+      c.kind === "day" ? c.level : -1,
+    )).toEqual([4, 1, 0, ...Array(4).fill(-1)]);
+    // With maxOverride=100 the same days flatten — the caller's pinned
+    // scale reaches the buckets (R2 S1: the prop was a dead wire).
+    expect(calendarGrid(days, "2025-12-03", null, 100).map((c) =>
+      c.kind === "day" ? c.level : -1,
+    )).toEqual([1, 1, 0, ...Array(4).fill(-1)]);
+  });
+
+  it("derives from the days when the override is null or omitted", () => {
+    const days = [{ date: MON, value: 5 }];
+    expect(calendarGrid(days, "2025-12-03", null, null)[0]).toMatchObject({
+      level: 4,
+    });
+  });
+});
+
+describe("calendarGrid", () => {
+  it("pads a one-row series into a full week with real dates", () => {
+    const cells = calendarGrid(
+      [{ date: MON, value: 5 }],
+      "2025-12-03",
+      null,
+    );
+    expect(cells).toHaveLength(7);
+    expect(cells[0]).toMatchObject({ kind: "day", date: MON });
+    // Today and after: the tail of the always-full-year window.
+    expect(cells[2]).toMatchObject({ kind: "day", date: "2025-12-03" });
+    expect(cells[3]).toMatchObject({ kind: "gap", date: "2025-12-04", phase: "after" });
+    expect(cells[6]).toMatchObject({ kind: "gap", phase: "after" });
+  });
+
+  it("hatches the before-first region and never claims a fake zero", () => {
+    const cells = calendarGrid(
+      [{ date: "2025-12-05", value: 5 }],
+      "2025-12-07",
+      "2025-12-05",
+    );
+    // 12-01..12-04: gaps (before); 12-05..12-07: days.
+    expect(cells[0]).toMatchObject({ kind: "gap", phase: "before" });
+    expect(cells[3]).toMatchObject({ kind: "gap", phase: "before" });
+    expect(cells[4]).toMatchObject({ kind: "day", date: "2025-12-05" });
+  });
+
+  it("counts head padding before the series' first row as plain empty days, never gaps", () => {
+    // The server didn't ship 12-01..12-02 (window starts 12-03) — but
+    // no `first` anchor exists, so they are empty days, not "not yet".
+    const cells = calendarGrid(
+      [{ date: "2025-12-03", value: 5 }],
+      "2025-12-03",
+      null,
+    );
+    expect(cells[0]).toMatchObject({ kind: "day", date: "2025-12-01", level: 0 });
+    expect(cells[1]).toMatchObject({ kind: "day", date: "2025-12-02", level: 0 });
+  });
+
+  it("clamps a malformed future `first` to hatch nothing", () => {
+    const cells = calendarGrid(
+      [{ date: MON, value: 5 }],
+      "2025-12-03",
+      "2026-01-01",
+    );
+    expect(cells.some((c) => c.kind === "gap" && c.phase === "before")).toBe(false);
+  });
+
+  it("returns an empty grid for an empty series", () => {
+    expect(calendarGrid([], "2025-12-03", null)).toEqual([]);
+  });
+});
+
+describe("monthMarkers — the leading-month suppression", () => {
+  it("shows the first marker only when the grid's first column opens its month", () => {
+    // Grid starts exactly on Dec 1 (a Monday AND the 1st); one row of
+    // days pads into exactly one week.
+    const cells = calendarGrid(
+      [{ date: MON, value: 0 }],
+      "2025-12-09",
+      null,
+    );
+    expect(cells).toHaveLength(7);
+    expect(cells[0]).toMatchObject({ date: "2025-12-01" });
+    expect(monthMarkers(cells)).toEqual(["12"]);
+  });
+
+  it("suppresses a leading month that starts mid-month; the next month is labeled", () => {
+    // Grid starts Oct 27 (a Monday, NOT the 1st) and runs into November;
+    // two full weeks of cells.
+    const days: HkCalendarHeatmapDay[] = [
+      { date: "2025-10-27", value: 0 },
+      { date: "2025-10-28", value: 0 },
+      { date: "2025-10-29", value: 0 },
+      { date: "2025-10-30", value: 0 },
+      { date: "2025-10-31", value: 0 },
+      { date: "2025-11-01", value: 0 },
+      { date: "2025-11-02", value: 0 },
+      { date: "2025-11-03", value: 0 },
+      { date: "2025-11-04", value: 0 },
+      { date: "2025-11-05", value: 0 },
+    ];
+    const cells = calendarGrid(days, "2025-11-05", null);
+    expect(cells).toHaveLength(14);
+    // The partial October tail is unlabeled; November's Monday opens.
+    expect(monthMarkers(cells)).toEqual(["", "11"]);
+  });
+
+  it("labels no month when the whole grid sits inside one partial month", () => {
+    const cells = calendarGrid(
+      [{ date: "2025-10-13", value: 0 }],
+      "2025-10-20",
+      null,
+    );
+    expect(monthMarkers(cells)).toEqual([""]);
+  });
+
+  it("keeps the later markers honest about consecutive same-month columns", () => {
+    // Two December Mondays: only the first carries the label.
+    const days: HkCalendarHeatmapDay[] = [
+      { date: MON, value: 0 },
+      { date: "2025-12-02", value: 0 },
+      { date: "2025-12-03", value: 0 },
+      { date: "2025-12-04", value: 0 },
+      { date: "2025-12-05", value: 0 },
+      { date: "2025-12-06", value: 0 },
+      { date: "2025-12-07", value: 0 },
+      { date: "2025-12-08", value: 0 },
+      { date: "2025-12-09", value: 0 },
+      { date: "2025-12-10", value: 0 },
+    ];
+    const cells = calendarGrid(days, "2025-12-10", null);
+    expect(monthMarkers(cells)).toEqual(["12", ""]);
+  });
+});

package/src/components/calendarHeatmap.ts

@@ -0,0 +1,139 @@
+/**
+ * Calendar-heatmap math — pure helpers for HkCalendarHeatmap.
+ *
+ * Upstreamed from the shittim-chest quota page's degree-usage section
+ * (2026-10 user direction: a calendar heatmap is a big business
+ * component — the rich-text-viewer table — not a view-local helper).
+ * The server ships a DENSE daily series (oldest → newest, zero-filled,
+ * inclusive of today, plus the account's first activity date).
+ * Everything the component renders — the full-year week grid with its
+ * hatched no-data gaps, the month markers — derives here so each
+ * derivation is unit-testable without a component mount.
+ */
+
+/** Opacity per bucket (0–4) over the primary token; bucket 0 is the
+ * muted empty cell. Five steps so "no consumption" stays visually
+ * distinct from "the smallest consumption on record". Exported for the
+ * component and its tests — the scale is part of the contract. */
+export const HEATMAP_LEVEL_OPACITY = ["0.12", "0.22", "0.42", "0.66", "0.95"] as const;
+
+/** One input day of the dense series. `value` may be negative or zero
+ * (a "no consumption" day) — it still buckets to level 0. */
+export type HkCalendarHeatmapDay = { date: string; value: number };
+
+/** Monday-first weekday index of an ISO date (Mon = 0 … Sun = 6). */
+export function weekdayIndex(iso: string): number {
+  const d = new Date(`${iso}T00:00:00Z`);
+  // getUTCDay: Sun = 0 … Sat = 6 → rotate to Monday-first.
+  return (d.getUTCDay() + 6) % 7;
+}
+
+/** ISO date ± n days (UTC arithmetic only — no local timezone leaks). */
+export function shiftIso(iso: string, days: number): string {
+  const d = new Date(`${iso}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+/** Today as an ISO date (UTC — the series' day boundary). */
+export function todayIso(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * One heatmap cell: a real day of the series, or a gap the account has
+ * no data for — before its first activity, or after today (the rest of
+ * the always-full-year window). Gaps render hatched and inert; they
+ * never claim a fake "0 consumption" for a day that never was.
+ */
+export type CalendarCell =
+  | { kind: "day"; date: string; value: number; level: 0 | 1 | 2 | 3 | 4 }
+  | { kind: "gap"; date: string; phase: "before" | "after" };
+
+/**
+ * Pad the dense series into the week-aligned calendar grid: head cells
+ * back to the window's first Monday, tail cells to Sunday — so a
+ * trailing-year window ALWAYS lands on a full-year-wide grid, however
+ * young the account is. Every cell carries its real calendar date;
+ * cells outside [first … today] become gaps (hatched, inert).
+ *
+ * `maxOverride` pins the intensity scale (R2: the component's `max`
+ * prop must reach the buckets, not just the data-max attribute — a
+ * caller pinning the scale across windows would otherwise get levels
+ * computed against each window's own peak). null = derive from `days`.
+ */
+export function calendarGrid(
+  days: HkCalendarHeatmapDay[],
+  today: string,
+  first: string | null,
+  maxOverride?: number | null,
+): CalendarCell[] {
+  if (days.length === 0) return [];
+  const lead = weekdayIndex(days[0].date);
+  const gridStart = shiftIso(days[0].date, -lead);
+  const total = lead + days.length;
+  const span = total + ((7 - (total % 7)) % 7);
+  const max = maxOverride ?? days.reduce((m, d) => Math.max(m, d.value), 0);
+  const valueByDate = new Map(days.map((d) => [d.date, d.value]));
+  // A malformed `first` from the future hatches nothing (the clamp
+  // keeps the before-check honest).
+  const hatchFrom = first && first <= today ? first : null;
+  const cells: CalendarCell[] = [];
+  for (let i = 0; i < span; i++) {
+    const date = shiftIso(gridStart, i);
+    if (date > today) {
+      cells.push({ kind: "gap", date, phase: "after" });
+      continue;
+    }
+    if (hatchFrom && date < hatchFrom) {
+      cells.push({ kind: "gap", date, phase: "before" });
+      continue;
+    }
+    // Dates in the head padding before the series' first row predate
+    // the requested window (the server didn't ship them) — they count
+    // as plain empty days, never gaps.
+    const value = valueByDate.get(date) ?? 0;
+    cells.push({ kind: "day", date, value, level: bucketLevel(value, max) });
+  }
+  return cells;
+}
+
+/** The heatmap's intensity bucket: 0 (none) … 4 (peak), scaled against
+ * the window's max day. Zero/negative days are bucket 0; every
+ * consuming day lands in 1..4 (ceil, so even the smallest consumption
+ * shows one step above empty). */
+export function bucketLevel(value: number, max: number): 0 | 1 | 2 | 3 | 4 {
+  if (value <= 0 || max <= 0) return 0;
+  return Math.min(4, Math.max(1, Math.ceil((value / max) * 4))) as 0 | 1 | 2 | 3 | 4;
+}
+
+/**
+ * Month markers for the week columns: a short label on each column
+ * whose Monday opens a month, "" otherwise.
+ *
+ * The leading month is the 2026-10 refinement this extraction carries:
+ * a trailing-year window (or any window) usually starts MID-month, so
+ * the first column shows only the tail of its month. A label there
+ * would claim a month whose start is not visible on the chart — the
+ * GitHub convention is to suppress it. The first marker is therefore
+ * shown ONLY when the grid's first column actually opens its month
+ * (its Monday is the 1st); every later marker keeps the previous
+ * rule (this column's Monday opens a month the previous column's
+ * Monday did not). Every grid cell carries a real calendar date, so
+ * the marker can never lie about padding.
+ */
+export function monthMarkers(cells: CalendarCell[]): string[] {
+  const weeks = Math.ceil(cells.length / 7);
+  const markers: string[] = [];
+  let prevMonth = -1;
+  for (let w = 0; w < weeks; w++) {
+    const monday = cells[w * 7];
+    if (!monday) break;
+    const month = Number(monday.date.slice(5, 7));
+    const opensMonth =
+      w === 0 ? monday.date.slice(8, 10) === "01" : month !== prevMonth;
+    markers.push(opensMonth ? String(month) : "");
+    prevMonth = month;
+  }
+  return markers;
+}

package/src/i18n/locales/ar/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "أقل من",
     "hikari::filterPanel.op.lte": "كحد أقصى",
     "hikari::filterPanel.op.gte": "على الأقل",
-    "hikari::filterPanel.op.gt": "أكبر من"
+    "hikari::filterPanel.op.gt": "أكبر من",
+    "hikari::calendarHeatmap.less": "أقل",
+    "hikari::calendarHeatmap.more": "أكثر",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "الاستخدام اليومي على مدى {weeks} أسبوعًا"
   },
   "hikari::affixPicker.unset": "غير محدد",
   "hikari::affixPicker.title": "الخيارات",

package/src/i18n/locales/de/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "kleiner als",
     "hikari::filterPanel.op.lte": "höchstens",
     "hikari::filterPanel.op.gte": "mindestens",
-    "hikari::filterPanel.op.gt": "größer als"
+    "hikari::filterPanel.op.gt": "größer als",
+    "hikari::calendarHeatmap.less": "Weniger",
+    "hikari::calendarHeatmap.more": "Mehr",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "Tägliche Nutzung über {weeks} Wochen"
   },
   "hikari::affixPicker.unset": "Nicht festgelegt",
   "hikari::affixPicker.title": "Optionen",

package/src/i18n/locales/en/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "less than",
     "hikari::filterPanel.op.lte": "at most",
     "hikari::filterPanel.op.gte": "at least",
-    "hikari::filterPanel.op.gt": "greater than"
+    "hikari::filterPanel.op.gt": "greater than",
+    "hikari::calendarHeatmap.less": "Less",
+    "hikari::calendarHeatmap.more": "More",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "Daily usage across {weeks} weeks"
   },
   "hikari::affixPicker.title": "Options",
   "hikari::affixPicker.search": "Search",

package/src/i18n/locales/es/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "menor que",
     "hikari::filterPanel.op.lte": "como máximo",
     "hikari::filterPanel.op.gte": "al menos",
-    "hikari::filterPanel.op.gt": "mayor que"
+    "hikari::filterPanel.op.gt": "mayor que",
+    "hikari::calendarHeatmap.less": "Menos",
+    "hikari::calendarHeatmap.more": "Más",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "Uso diario durante {weeks} semanas"
   },
   "hikari::affixPicker.unset": "Sin establecer",
   "hikari::affixPicker.title": "Opciones",

package/src/i18n/locales/fr/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "inférieur à",
     "hikari::filterPanel.op.lte": "au plus",
     "hikari::filterPanel.op.gte": "au moins",
-    "hikari::filterPanel.op.gt": "supérieur à"
+    "hikari::filterPanel.op.gt": "supérieur à",
+    "hikari::calendarHeatmap.less": "Moins",
+    "hikari::calendarHeatmap.more": "Plus",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "Utilisation quotidienne sur {weeks} semaines"
   },
   "hikari::affixPicker.unset": "Non défini",
   "hikari::affixPicker.title": "Options",

package/src/i18n/locales/ja/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "未満",
     "hikari::filterPanel.op.lte": "以下",
     "hikari::filterPanel.op.gte": "以上",
-    "hikari::filterPanel.op.gt": "より大きい"
+    "hikari::filterPanel.op.gt": "より大きい",
+    "hikari::calendarHeatmap.less": "少",
+    "hikari::calendarHeatmap.more": "多",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "直近 {weeks} 週間の毎日の使用量"
   },
   "hikari::affixPicker.unset": "未設定",
   "hikari::affixPicker.title": "オプション",

package/src/i18n/locales/ko/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "미만",
     "hikari::filterPanel.op.lte": "이하",
     "hikari::filterPanel.op.gte": "이상",
-    "hikari::filterPanel.op.gt": "초과"
+    "hikari::filterPanel.op.gt": "초과",
+    "hikari::calendarHeatmap.less": "적음",
+    "hikari::calendarHeatmap.more": "많음",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "최근 {weeks}주간의 일일 사용량"
   },
   "hikari::affixPicker.unset": "미설정",
   "hikari::affixPicker.title": "옵션",

package/src/i18n/locales/pt/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "menor que",
     "hikari::filterPanel.op.lte": "no máximo",
     "hikari::filterPanel.op.gte": "pelo menos",
-    "hikari::filterPanel.op.gt": "maior que"
+    "hikari::filterPanel.op.gt": "maior que",
+    "hikari::calendarHeatmap.less": "Menos",
+    "hikari::calendarHeatmap.more": "Mais",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "Uso diário ao longo de {weeks} semanas"
   },
   "hikari::affixPicker.unset": "Não definido",
   "hikari::affixPicker.title": "Opções",

package/src/i18n/locales/ru/components.json

@@ -217,7 +217,12 @@
     "hikari::filterPanel.op.lt": "меньше",
     "hikari::filterPanel.op.lte": "не более",
     "hikari::filterPanel.op.gte": "не менее",
-    "hikari::filterPanel.op.gt": "больше"
+    "hikari::filterPanel.op.gt": "больше",
+    "hikari::calendarHeatmap.less": "Меньше",
+    "hikari::calendarHeatmap.more": "Больше",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "Ежедневное использование за {weeks} недель"
   },
   "hikari::affixPicker.unset": "Не задано",
   "hikari::affixPicker.title": "Параметры",

package/src/i18n/locales/zh-Hans/components.json

@@ -221,7 +221,12 @@
     "hikari::filterPanel.op.lt": "小于",
     "hikari::filterPanel.op.lte": "不超过",
     "hikari::filterPanel.op.gte": "不低于",
-    "hikari::filterPanel.op.gt": "大于"
+    "hikari::filterPanel.op.gt": "大于",
+    "hikari::calendarHeatmap.less": "少",
+    "hikari::calendarHeatmap.more": "多",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "近 {weeks} 周的每日用量"
   },
   "hikari::affixPicker.title": "选项",
   "hikari::affixPicker.search": "搜索",

package/src/i18n/locales/zh-Hant/components.json

@@ -221,7 +221,12 @@
     "hikari::filterPanel.op.lt": "小於",
     "hikari::filterPanel.op.lte": "不超過",
     "hikari::filterPanel.op.gte": "不低於",
-    "hikari::filterPanel.op.gt": "大於"
+    "hikari::filterPanel.op.gt": "大於",
+    "hikari::calendarHeatmap.less": "少",
+    "hikari::calendarHeatmap.more": "多",
+    "hikari::calendarHeatmap.cellTitle": "{date} · {n} {unit}",
+    "hikari::calendarHeatmap.cellTitleNoUnit": "{date} · {n}",
+    "hikari::calendarHeatmap.summary": "近 {weeks} 週的每日用量"
   },
   "hikari::affixPicker.title": "選項",
   "hikari::affixPicker.search": "搜尋",

package/src/index.ts

@@ -644,6 +644,20 @@ export { default as HkDivider } from "./components/HkDivider";
 export { default as HkDiffViewer } from "./components/HkDiffViewer";
 export { parseUnifiedDiff, computeGaps } from "./components/diffParse";
 export type { DiffLine, DiffHunk, ParsedDiff, UnchangedGap } from "./components/diffParse";
+export { default as HkCalendarHeatmap } from "./components/HkCalendarHeatmap";
+// The H- alias rides the HCard/HkCard family convention: consumers
+// import either name, one component underneath.
+export { default as HCalendarHeatmap } from "./components/HkCalendarHeatmap";
+export {
+  bucketLevel,
+  calendarGrid,
+  HEATMAP_LEVEL_OPACITY,
+  monthMarkers,
+  todayIso,
+  weekdayIndex,
+  shiftIso,
+} from "./components/calendarHeatmap";
+export type { CalendarCell, HkCalendarHeatmapDay } from "./components/calendarHeatmap";
 export { default as HkDockBar } from "./components/HkDockBar";
 export { default as HkDrawer } from "./components/HkDrawer";
 export { default as HkEmptyState } from "./components/HkEmptyState";

package/src/styles/admin-tokens.scss

@@ -574,6 +574,16 @@
 }
 
 .s-admin-header-avatar {
+  /* Block, never the UA's inline-block: hosts may nest the trigger in a
+   * plain block wrapper (the chat face's menu-anchor <div> around
+   * HeaderLeft's HkAvatarButton), and an inline-block button there joins
+   * a line box — its baseline (the bottom margin edge, because of
+   * `overflow: hidden`) sits on the strut's baseline, so the strut's
+   * descender space lands BELOW the avatar and the button rides ~4px
+   * high inside a perfectly centred wrapper (2026-10-30 user report:
+   * 前台头像略微偏上，后台正中). A direct flex/grid parent blockifies
+   * this away, so the console face is unaffected either way. */
+  display: block;
   position: relative;
   width: var(--space-28);
   height: var(--space-28);