@celestia-island/hikari 0.55.233 → 0.55.235

package/package.json

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

package/src/components/HkAdminShell.tsx

@@ -39,8 +39,10 @@ export const HkAdminShell = defineComponent({
     sidebarWidth: { type: String, default: "224px" },
     /** Desktop icon-rail capability, forwarded to HkFaceShell (see its
      *  prop doc): opt in here and the admin sidebar gains the circular
-     *  hover-reveal toggle, the one-icon rail and the overlay peek
-     *  drawer. Declared on the wrapper on purpose — the same
+     *  hover-reveal toggle STRADDLING the sidebar's content-facing border,
+     *  the one-icon rail and the overlay peek drawer (with the peek
+     *  suppressed while the pointer rests on the toggle, and a pinned
+     *  panel on expand). Declared on the wrapper on purpose — the same
      *  honest-forwarding rule as contentMode (a stray attr must not
      *  reach the inner shell's declared prop through fallthrough). */
     sidebarCollapsible: { type: Boolean, default: false },

package/src/components/HkCalendarHeatmap.barrel.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import * as barrel from "../index";
+
+/**
+ * The public barrel guard for the calendar heatmap's exports (R3 on the
+ * S3-fix wave: deleting any of these lines from index.ts kept the ENTIRE
+ * suite green, because every other test reaches the module through the
+ * direct "./calendarHeatmap" path — only an external consumer would have
+ * noticed). Same shape as HkFaceShell.barrel.test.ts.
+ *
+ * This file deliberately does NOT mock "@celestia-island/hikari": the
+ * package's self-reference resolves to the very same src/index.ts module
+ * as "../index", so a vi.mock here would replace the barrel under test
+ * with the mock's own namespace.
+ */
+describe("the public barrel", () => {
+  it("exports the heatmap component under both family names", () => {
+    const hk = barrel.HkCalendarHeatmap as unknown as { name?: string };
+    expect(hk, "HkCalendarHeatmap must be re-exported").toBeTruthy();
+    expect(hk.name).toBe("HkCalendarHeatmap");
+    // The H- alias rides the HCard/HkCard family convention.
+    expect(barrel.HCalendarHeatmap).toBe(barrel.HkCalendarHeatmap);
+  });
+
+  it("exports the calendar grid math and the fill ladder", () => {
+    for (const name of [
+      "bucketLevel",
+      "calendarGrid",
+      "heatmapCellFill",
+      "heatmapCellOpacity",
+      "monthMarkers",
+      "todayIso",
+      "weekdayIndex",
+      "shiftIso",
+    ] as const) {
+      expect(typeof barrel[name], `${name} must be re-exported`).toBe("function");
+    }
+    expect(Array.isArray(barrel.HEATMAP_LEVEL_OPACITY)).toBe(true);
+    expect(barrel.HEATMAP_LEVEL_OPACITY).toHaveLength(4);
+    expect(typeof barrel.HEATMAP_EMPTY_FILL).toBe("string");
+    // The fill ladder the legend and the cells share: level 0 is the
+    // empty wash, never the primary token.
+    expect(barrel.heatmapCellFill(0)).toBe(barrel.HEATMAP_EMPTY_FILL);
+    expect(barrel.heatmapCellFill(0)).not.toContain("primary");
+    expect(barrel.heatmapCellOpacity(0)).toBeUndefined();
+    expect(barrel.heatmapCellOpacity(4)).toBe(barrel.HEATMAP_LEVEL_OPACITY[3]);
+  });
+});

package/src/components/HkCalendarHeatmap.test.tsx

@@ -2,7 +2,7 @@ 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";
+import { HEATMAP_LEVEL_OPACITY, shiftIso } from "./calendarHeatmap";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
 
@@ -16,6 +16,9 @@ function mount(node: ReturnType<typeof h>) {
 }
 
 afterEach(() => {
+  // A failed assertion inside a fake-clock test must not leak the frozen
+  // clock into the rest of the file.
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
@@ -35,7 +38,7 @@ const daysFrom = (start: string, count: number, value = 0) =>
   });
 
 describe("HkCalendarHeatmap", () => {
-  it("renders the legend (less → more, five swatches) and the grid anatomy", () => {
+  it("renders the legend (less → more, the empty swatch + one per level) and the grid anatomy", () => {
     const c = mount(
       h(HkCalendarHeatmap, {
         days: daysFrom(CLEAN_HEAD_MON, 7),
@@ -51,18 +54,35 @@ describe("HkCalendarHeatmap", () => {
     const legend = c.querySelector('[data-testid="hk-calendar-heatmap-legend"]');
     expect(legend?.textContent).toContain("Less");
     expect(legend?.textContent).toContain("More");
+    // The empty swatch plus one per CONSUMING level.
     expect(c.querySelectorAll("[data-legend-level]")).toHaveLength(
-      HEATMAP_LEVEL_OPACITY.length,
+      1 + HEATMAP_LEVEL_OPACITY.length,
     );
+    const swatches = c.querySelectorAll("[data-legend-level]") as NodeListOf<HTMLElement>;
+    // The empty swatch carries NO opacity step (its wash lives in the
+    // fill, HEATMAP_EMPTY_FILL — happy-dom drops color-mix() values, so
+    // the ladder is asserted through the opacity channel it does keep).
+    expect(swatches[0].style.opacity).toBe("");
+    // The swatch levels run 0..4 in order, empty first.
+    expect(
+      Array.from(swatches, (s) => s.getAttribute("data-legend-level")),
+    ).toEqual(["0", "1", "2", "3", "4"]);
+    // Consuming levels index the table by level - 1: 1 -> [0] … 4 -> [3].
+    expect(swatches[1].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[0]);
+    expect(swatches[2].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[1]);
+    expect(swatches[3].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[2]);
+    expect(swatches[4].style.opacity).toBe(HEATMAP_LEVEL_OPACITY[3]);
     // 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 () => {
+  it("labels the next month on the column carrying its 1st, never the partial head month", async () => {
     const c = mount(
       h(HkCalendarHeatmap, {
-        // Trailing-October tail + November: the partial October head is
-        // unlabeled, November's Monday carries the only marker.
+        // Trailing-October tail + November. October's 1st is not on the
+        // axis, so no slot may carry October; November's 1st (Nov 1, a
+        // Saturday) sits in the HEAD column, which is where its marker
+        // goes.
         days: daysFrom(MID_MONTH_MON, 10),
         first: null,
       }),
@@ -72,8 +92,63 @@ describe("HkCalendarHeatmap", () => {
       ".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
+    const texts = Array.from(markers, (m) => m.textContent);
+    // The head month (its 1st is off-axis) is never labeled.
+    expect(texts.some((t) => t?.startsWith("Oct"))).toBe(false);
+    expect(texts[0]).not.toBe(""); // November's 1st is in this column
+    expect(texts[1]).toBe("");
+  });
+
+  it("labels a month on the column carrying its 1st, not one column late", async () => {
+    // Grid opens Mon Sep 29: Oct 1 (a Wednesday) is in the head column.
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: Array.from({ length: 14 }, (_, i) => ({
+          date: shiftIso("2025-09-29", i),
+          value: 0,
+        })),
+        first: null,
+      }),
+    );
+    await nextTick();
+    const markers = c.querySelectorAll(
+      ".hk-calendar-heatmap-markers > span",
+    ) as NodeListOf<HTMLElement>;
+    expect(markers[0].textContent).not.toBe(""); // October, mid-column
+    expect(markers[1].textContent).toBe("");
+  });
+
+  it("reserves trailing room exactly when the last column carries a marker", async () => {
+    const padOf = async (days: { date: string; value: number }[]) => {
+      const c = mount(h(HkCalendarHeatmap, { days, first: null }));
+      await nextTick();
+      const markersEl = c.querySelector(
+        ".hk-calendar-heatmap-markers",
+      ) as HTMLElement;
+      const texts = Array.from(
+        markersEl.querySelectorAll(":scope > span"),
+        (m) => m.textContent,
+      );
+      return {
+        // Logical property: hikari ships RTL hosts (HkMenu reads
+        // documentElement.dir), so the reserved room rides inline-end
+        // rather than a physical side.
+        pad: markersEl.style.paddingInlineEnd,
+        lastSet: texts.length > 0 && texts[texts.length - 1] !== "",
+      };
+    };
+
+    // Positive branch: a single week opening on Dec 1 leaves the marker
+    // on the LAST column — its ink needs the reserved room.
+    const marked = await padOf(daysFrom(CLEAN_HEAD_MON, 7));
+    expect(marked.lastSet).toBe(true);
+    expect(marked.pad).not.toBe("");
+
+    // Negative branch: ending on Nov 7 (a Friday) pads the axis to
+    // Nov 3–9, so the November marker sits one column in, not last.
+    const unmarked = await padOf(daysFrom("2025-10-27", 12));
+    expect(unmarked.lastSet).toBe(false);
+    expect(unmarked.pad).toBe("");
   });
 
   it("shows the leading month marker when the grid's first column opens its month", async () => {
@@ -90,29 +165,97 @@ describe("HkCalendarHeatmap", () => {
     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();
+  it("fills the cells through the shared ladder: consuming levels primary, level 0 not", () => {
+    // happy-dom drops color-mix() but keeps var(), so the
+    // empty-vs-primary distinction IS observable here — a hardcoded
+    // primary for level 0 (or a hardcoded fill that ignores the
+    // helper) turns this red (R3: the call sites had no pin).
     const c = mount(
       h(HkCalendarHeatmap, {
-        days: [{ date: today, value: 5 }],
-        first: today,
+        days: [
+          { date: CLEAN_HEAD_MON, value: 10 },
+          { date: "2025-12-02", value: 0 },
+        ],
+        first: null,
       }),
     );
     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")),
+    const styleOf = (level: string) =>
+      (grid.querySelector(`[data-level="${level}"]`) as HTMLElement).getAttribute(
+        "style",
+      ) ?? "";
+    expect(styleOf("4")).toContain("var(--hi-color-primary)");
+    expect(styleOf("0")).not.toContain("--hi-color-primary");
+    // The legend rides the same decision: its empty swatch is not
+    // primary, every consuming swatch is.
+    const swatches = c.querySelectorAll(
+      "[data-legend-level]",
+    ) as NodeListOf<HTMLElement>;
+    expect(swatches[0].getAttribute("style") ?? "").not.toContain(
+      "--hi-color-primary",
+    );
+    for (const level of [1, 2, 3, 4]) {
+      expect(swatches[level].getAttribute("style") ?? "").toContain(
+        "var(--hi-color-primary)",
+      );
+    }
+  });
+
+  it("applies the opacity ladder by level - 1, leaving level 0 without an opacity step", () => {
+    // The empty cell's wash lives in its FILL, never in the opacity
+    // table (the old table's index 0 was dead weight) — level 0 must
+    // carry no opacity while every consuming level maps to [level - 1].
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: [
+          { date: CLEAN_HEAD_MON, value: 10 },
+          { date: "2025-12-02", value: 5 },
+          { date: "2025-12-03", value: 0 },
+        ],
+        first: null,
+      }),
     );
-    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");
+    const grid = c.querySelector('[data-testid="hk-calendar-heatmap"]') as HTMLElement;
+    const cellAt = (level: string) =>
+      grid.querySelector(`[data-level="${level}"]`) as HTMLElement;
+    expect(cellAt("4").style.opacity).toBe(HEATMAP_LEVEL_OPACITY[3]);
+    expect(cellAt("2").style.opacity).toBe(HEATMAP_LEVEL_OPACITY[1]);
+    expect(cellAt("0").style.opacity).toBe("");
+  });
+
+  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". The clock is
+    // PINNED to a Wednesday: with the real clock this test carried
+    // both-phase expectations into a Monday (no head padding) or a
+    // Sunday (no tail), so it went red two days out of seven
+    // (R3 2026-10-30, proven with a mocked clock).
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date("2025-12-03T10:00:00Z")); // a Wednesday
+      const c = mount(
+        h(HkCalendarHeatmap, {
+          days: [{ date: "2025-12-03", value: 5 }],
+          first: "2025-12-03",
+        }),
+      );
+      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");
+      }
+    } finally {
+      vi.useRealTimers();
     }
   });
 

package/src/components/HkCalendarHeatmap.tsx

@@ -2,9 +2,9 @@ import { computed, defineComponent, type PropType } from "vue";
 
 import { useI18n } from "../i18n/context";
 import {
-  bucketLevel,
   calendarGrid,
-  HEATMAP_LEVEL_OPACITY,
+  heatmapCellFill,
+  heatmapCellOpacity,
   monthMarkers,
   todayIso,
   type CalendarCell,
@@ -12,6 +12,12 @@ import {
 } from "./calendarHeatmap";
 import "./HkCalendarHeatmap.scss";
 
+/** The legend's five levels, empty first — the same ladder the cells
+ * ride, so the swatches come from the one fill/opacity decision
+ * (`heatmapCellFill` / `heatmapCellOpacity`) rather than a second,
+ * hand-written copy of the colors. */
+const LEGEND_LEVELS = [0, 1, 2, 3, 4] as const;
+
 /** 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. */
@@ -36,11 +42,10 @@ function fill(template: string, vars: Record<string, string | number>): string {
  * 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.
+ * The leading month is never mislabeled: a month is labeled on the
+ * column that carries its 1st, so a window starting mid-month has no
+ * label over its partial head (that month's 1st is not on the axis),
+ * and no month lands one column late.
  *
  * Dumb by design: the caller owns the fetch lifecycle and passes the
  * settled dense series in (`days`, oldest → newest, zero-filled,
@@ -90,33 +95,35 @@ export default defineComponent({
       () => `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).
+    // Locale-reactive formatter cache (the HkDateTimePicker convention):
+    // ONE Intl.DateTimeFormat per shape per locale, held in a computed
+    // over the context's locale — not one per rendered cell, which a
+    // full-year grid would pay ~370 times over. 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 formatters = computed(() => {
+      const loc = locale.value;
+      return {
+        weekday: new Intl.DateTimeFormat(loc, { weekday: "short", timeZone: "UTC" }),
+        month: new Intl.DateTimeFormat(loc, { month: "short", timeZone: "UTC" }),
+        date: new Intl.DateTimeFormat(loc, { dateStyle: "medium", timeZone: "UTC" }),
+      };
+    });
     const weekdayLabel = (idx: number) =>
-      new Intl.DateTimeFormat(locale.value, {
-        weekday: "short",
-        timeZone: "UTC",
-      }).format(
+      formatters.value.weekday.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)));
+      return formatters.value.month.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`));
+      formatters.value.date.format(new Date(`${iso}T00:00:00Z`));
 
     const cellTitle = (d: Extract<CalendarCell, { kind: "day" }>) =>
       fill(
@@ -135,13 +142,24 @@ export default defineComponent({
           }
         : {
             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],
+            background: heatmapCellFill(cell.level),
+            opacity: heatmapCellOpacity(cell.level),
           };
 
+    // A marker may overflow its 14px column into the empty columns
+    // ahead (the GitHub convention — a month label is always followed
+    // by unmarked columns). A marker on the LAST column has nothing
+    // ahead: its ink would be clipped by the scroll container, so that
+    // one case reserves inline-end room for it. The logical property
+    // matters: hikari ships RTL hosts (HkMenu reads
+    // documentElement.dir), and there the label runs the other way.
+    const markersTrailingPad = computed(() => {
+      const m = markers.value;
+      return m.length > 0 && m[m.length - 1] !== ""
+        ? `${props.cellSize * 2 + props.cellGap}px`
+        : undefined;
+    });
+
     return () => (
       <div class="hk-calendar-heatmap">
         {/* The legend row: the scale in the caller's one unit on the
@@ -154,19 +172,16 @@ export default defineComponent({
             data-testid="hk-calendar-heatmap-legend"
           >
             {t("hikari::calendarHeatmap.less", "Less")}
-            {HEATMAP_LEVEL_OPACITY.map((o, i) => (
+            {LEGEND_LEVELS.map((level) => (
               <span
-                key={i}
-                data-legend-level={i}
+                key={level}
+                data-legend-level={level}
                 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,
+                  background: heatmapCellFill(level),
+                  opacity: heatmapCellOpacity(level),
                   display: "inline-block",
                 }}
               />
@@ -199,14 +214,16 @@ export default defineComponent({
             </div>
 
             <div class="hk-calendar-heatmap-cells">
-              {/* Month markers, one slot per week column. A leading
-               * partial month renders its empty slot (see
+              {/* Month markers, one slot per week column. A month is
+               * labeled on the column carrying its 1st; a partial head
+               * month therefore renders an empty slot (see
                * monthMarkers). */}
               <div
                 class="hk-calendar-heatmap-markers"
                 style={{
                   gridTemplateColumns: columns.value,
                   columnGap: `${props.cellGap}px`,
+                  paddingInlineEnd: markersTrailingPad.value,
                 }}
               >
                 {markers.value.map((m, i) => (