@celestia-island/hikari 0.55.244 → 0.55.246

package/package.json

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

package/src/components/HkDateTag.scss

@@ -0,0 +1,33 @@
+// AI-generated: developed with the DeepSeek Harness agent (model DeepSeek V4.1 Flash); human-directed.
+
+/* HkDateTag — the locale-aware stacked date capsule (see the component
+ * docblock for the contract). Rows are calendar segments; the year and
+ * the optional time row read as context (muted, a touch smaller), the
+ * month/day figures carry the full text color. */
+
+.hk-date-tag {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  padding: var(--space-2, 2px) var(--space-10, 0.625rem);
+  border-radius: var(--radius-full, 999px);
+  background: rgb(var(--color-text) / 6%);
+  white-space: nowrap;
+}
+
+.hk-date-tag__row {
+  display: block;
+  text-align: center;
+  line-height: 1.25;
+  font-size: var(--text-2xs, 0.625rem);
+  font-variant-numeric: tabular-nums;
+  color: rgb(var(--color-text));
+}
+
+/* Context rows: the year (wherever the locale puts it) and the optional
+ * time row — muted and a touch smaller than the month/day figures. */
+.hk-date-tag__row--year,
+.hk-date-tag__row--time {
+  color: rgb(var(--color-text) / 55%);
+  font-size: calc(var(--text-2xs, 0.625rem) - 1px);
+}

package/src/components/HkDateTag.test.tsx

@@ -0,0 +1,135 @@
+// AI-generated: developed with the DeepSeek Harness agent (model DeepSeek V4.1 Flash); human-directed.
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import HkDateTagDefault, { HkDateTag } from "./HkDateTag";
+import { setLocale } from "../i18n/context";
+
+/**
+ * HkDateTag — the locale-aware date capsule. These cases pin the
+ * COMPONENT contract: the row order follows the ACTIVE hikari locale
+ * (year on top for zh-Hans, year LAST for en), the order re-derives
+ * live when the host flips the locale, `time` appends the muted
+ * fourth row, and unparseable input renders the empty capsule shell.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+// Built in LOCAL time so the calendar fields (2024-10-06 14:30) survive
+// every CI time zone; the capsule renders local calendar segments.
+const SHIP_DATE = new Date(2024, 9, 6, 14, 30);
+
+function mountTag(props: { value: string | number | Date; time?: boolean }): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => h(HkDateTag, props) });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+function rowsOf(container: HTMLElement): HTMLElement[] {
+  return [...container.querySelectorAll<HTMLElement>(".hk-date-tag__row")];
+}
+
+function capsuleOf(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>(".hk-date-tag");
+  expect(el, "capsule renders").toBeTruthy();
+  return el!;
+}
+
+// setLocale mutates the module-global i18n state — restore the default
+// after every case (the HkSolarLocationSetting suite's idiom).
+afterEach(async () => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  await setLocale("en");
+});
+
+describe("HkDateTag locale ordering", () => {
+  it("renders year/month/day rows top to bottom for zh-Hans", async () => {
+    await setLocale("zh-Hans");
+    const container = mountTag({ value: SHIP_DATE });
+
+    const capsule = capsuleOf(container);
+    expect(capsule.classList.contains("hk-date-tag")).toBe(true);
+    const rows = rowsOf(container);
+    expect(rows.map((r) => r.textContent)).toEqual(["2024", "10", "06"]);
+    // The year row carries its modifier wherever it lands.
+    expect(rows[0].classList.contains("hk-date-tag__row--year")).toBe(true);
+    expect(rows[1].classList.contains("hk-date-tag__row--year")).toBe(false);
+  });
+
+  it("orders month/day/year for en — the year goes LAST", async () => {
+    await setLocale("en");
+    const container = mountTag({ value: SHIP_DATE });
+
+    const rows = rowsOf(container);
+    expect(rows.map((r) => r.textContent)).toEqual(["10", "06", "2024"]);
+    expect(rows[2].classList.contains("hk-date-tag__row--year")).toBe(true);
+  });
+
+  it("re-orders the rows live when the locale flips under a mounted capsule", async () => {
+    await setLocale("zh-Hans");
+    const container = mountTag({ value: SHIP_DATE });
+    expect(rowsOf(container).map((r) => r.textContent)).toEqual(["2024", "10", "06"]);
+
+    await setLocale("en");
+    await nextTick();
+    expect(rowsOf(container).map((r) => r.textContent)).toEqual(["10", "06", "2024"]);
+
+    await setLocale("zh-Hans");
+    await nextTick();
+    expect(rowsOf(container).map((r) => r.textContent)).toEqual(["2024", "10", "06"]);
+  });
+});
+
+describe("HkDateTag time row", () => {
+  it("appends the muted time row only when asked", async () => {
+    await setLocale("zh-Hans");
+    const withTime = rowsOf(mountTag({ value: SHIP_DATE, time: true }));
+    expect(withTime).toHaveLength(4);
+    expect(withTime[3].classList.contains("hk-date-tag__row--time")).toBe(true);
+    expect(withTime[3].textContent).toBe("14:30");
+
+    const withoutTime = rowsOf(mountTag({ value: SHIP_DATE }));
+    expect(withoutTime).toHaveLength(3);
+    expect(withoutTime.some((r) => r.classList.contains("hk-date-tag__row--time"))).toBe(false);
+  });
+
+  it("formats the time row for the active locale", async () => {
+    await setLocale("en");
+    const rows = rowsOf(mountTag({ value: SHIP_DATE, time: true }));
+    expect(rows).toHaveLength(4);
+    expect(rows[3].textContent).toBe("02:30 PM");
+  });
+});
+
+describe("HkDateTag value normalization", () => {
+  it("accepts epoch milliseconds and date strings like the Date form", async () => {
+    await setLocale("en");
+    const expected = ["10", "06", "2024"];
+    expect(rowsOf(mountTag({ value: SHIP_DATE })).map((r) => r.textContent)).toEqual(expected);
+    // A number is epoch MILLISECONDS.
+    expect(rowsOf(mountTag({ value: SHIP_DATE.getTime() })).map((r) => r.textContent)).toEqual(expected);
+    expect(rowsOf(mountTag({ value: "2024-10-06T14:30:00" })).map((r) => r.textContent)).toEqual(expected);
+  });
+
+  it("renders the empty capsule shell for unparseable input", async () => {
+    await setLocale("zh-Hans");
+    const container = mountTag({ value: "not-a-date" });
+
+    const capsule = capsuleOf(container);
+    expect(capsule.children).toHaveLength(0);
+    expect(rowsOf(container)).toHaveLength(0);
+  });
+});
+
+describe("HkDateTag module surface", () => {
+  it("exports the same component as the default and named binding", () => {
+    expect(HkDateTagDefault).toBe(HkDateTag);
+    expect((HkDateTag as unknown as { name: string }).name).toBe("HkDateTag");
+  });
+});

package/src/components/HkDateTag.tsx

@@ -0,0 +1,99 @@
+// AI-generated: developed with the DeepSeek Harness agent (model DeepSeek V4.1 Flash); human-directed.
+import { computed, defineComponent, type PropType } from "vue";
+
+import { activeLocale } from "../i18n/context";
+import "./HkDateTag.scss";
+
+/**
+ * HkDateTag — a locale-aware date capsule: a small pill whose calendar
+ * segments are stacked vertically, ONE PER ROW, each centered, ordered
+ * the way the ACTIVE hikari locale orders dates (zh: year → month → day
+ * top to bottom; en: month → day → year, the year LAST; de: day first …).
+ * With the `time` flag a fourth, muted row carries the locale time
+ * (hour + minute, 2-digit each).
+ *
+ * Generic business part (peer of HkTemplateText / HkMarkdownRenderer,
+ * NOT of the HkInput family): hosts render compact per-row dates in data
+ * tables and cards — wowsp's water-meter ship tables are the first
+ * consumer.
+ *
+ * Contract:
+ *  - `value` accepts a Date, an epoch-MILLISECONDS number or a
+ *    date-ish string, normalized with `new Date(value)` (so a number is
+ *    NEVER seconds — pass what `Date.now()` returns). Unparseable input
+ *    renders NOTHING but the empty capsule shell; the caller owns the
+ *    empty state.
+ *  - The row order is derived from the locale itself, never a hardcoded
+ *    locale→order map: `Intl.DateTimeFormat(activeLocale(), { year,
+ *    month, day }).formatToParts(date)` supplies the year/month/day
+ *    segments in the order that locale writes them. The component is a
+ *    computed over the reactive i18n state, so a host `setLocale`
+ *    re-orders the rows live.
+ *  - `time` (default false) appends the muted time row
+ *    (`hk-date-tag__row--time`) under the date rows.
+ */
+export const HkDateTag = defineComponent({
+  name: "HkDateTag",
+  props: {
+    /** The date to render — Date, epoch milliseconds or a parseable
+     * string. Invalid input renders the empty capsule. */
+    value: {
+      type: [String, Number, Date] as PropType<string | number | Date>,
+      required: true,
+    },
+    /** Append the muted locale time row (hour + minute, 2-digit). */
+    time: { type: Boolean, default: false },
+  },
+  setup(props) {
+    const date = computed<Date | null>(() => {
+      const d = new Date(props.value);
+      return Number.isNaN(d.getTime()) ? null : d;
+    });
+
+    // The locale is read through the reactive i18n state (activeLocale
+    // reads it on every evaluation), so this computed re-runs — and the
+    // rows re-order — whenever the host calls setLocale. One formatter
+    // per shape per locale, rebuilt only on a locale/value change (the
+    // HkCalendarHeatmap idiom).
+    const locale = computed(() => activeLocale());
+
+    /** The year/month/day segments in the locale's own order. */
+    const rows = computed<Intl.DateTimeFormatPart[]>(() => {
+      const d = date.value;
+      if (d === null) return [];
+      return new Intl.DateTimeFormat(locale.value, {
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      })
+        .formatToParts(d)
+        .filter((part) => part.type === "year" || part.type === "month" || part.type === "day");
+    });
+
+    /** The locale time (hour + minute, 2-digit) when the capsule opts
+     * in — null without `time` or for an invalid date. */
+    const timeText = computed<string | null>(() => {
+      const d = date.value;
+      if (!props.time || d === null) return null;
+      return new Intl.DateTimeFormat(locale.value, { hour: "2-digit", minute: "2-digit" }).format(d);
+    });
+
+    return () => (
+      <span class="hk-date-tag">
+        {rows.value.map((part) => (
+          <span
+            key={part.type}
+            class={part.type === "year" ? "hk-date-tag__row hk-date-tag__row--year" : "hk-date-tag__row"}
+          >
+            {part.value}
+          </span>
+        ))}
+        {timeText.value !== null && (
+          <span key="time" class="hk-date-tag__row hk-date-tag__row--time">{timeText.value}</span>
+        )}
+      </span>
+    );
+  },
+});
+
+export default HkDateTag;

package/src/components/HkSidebar.rail.test.tsx

@@ -542,4 +542,36 @@ describe("HkSidebar standalone rail: the menu group fold survives its own swap",
       "the expanded sidebar inherits the closed group",
     ).toBe("false");
   });
+
+  it("keeps the scroll position across density flips (the #44 P3 audit finding)", async () => {
+    vi.useFakeTimers();
+    const c = mountSidebar({ width: "240px", collapsible: true, collapsedWidth: "64px" });
+
+    // Collapse to the rail and settle the dissolve.
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(500);
+    const bodies = () => c.container.querySelectorAll<HTMLElement>(".hk-sidebar-body");
+    const active = () => bodies()[bodies().length - 1]!;
+    expect(bodies().length, "one settled generation").toBe(1);
+
+    // The user scrolls the rail partway down…
+    active().scrollTop = 120;
+
+    // …then a peek flips the density (the shell keys the swap on
+    // `railActive && !peeking`, so every peek open/close is a flip).
+    c.aside().dispatchEvent(new Event("pointerenter"));
+    await vi.advanceTimersByTimeAsync(900);
+    expect(active().scrollTop, "the peek's full generation resumes the scroll").toBe(120);
+
+    // Leaving the peek flips back to the rail dress; the position must
+    // survive that remount too.
+    c.aside().dispatchEvent(new Event("pointerleave"));
+    await vi.advanceTimersByTimeAsync(900);
+    expect(active().scrollTop, "the rail generation resumes the scroll").toBe(120);
+
+    // And a full expand is the same crossing.
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(900);
+    expect(active().scrollTop, "the expanded body resumes the scroll").toBe(120);
+  });
 });

package/src/components/HkSidebar.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch, nextTick } from "vue";
 
 import "./HkSidebar.scss";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
@@ -143,6 +143,34 @@ export default defineComponent({
     onMounted(attachBodyScrollbar);
     watch([bodyRef, bodyWrapRef], attachBodyScrollbar);
 
+    // Density flips remount the body band (the rail swap renders each
+    // generation's body FRESH), which used to snap the scroll back to the
+    // top on every flip — including each hover-peek open/close, because
+    // the shell keys the swap on `railActive && !peeking` (the #44 P3
+    // audit finding; probed: scrollTop 120 -> peek -> 0 -> back -> 0).
+    // The sidebar's own instance SURVIVES the flip (the swap lives inside
+    // it), so the position only needs to cross the remount. A flip patches
+    // the shared ref old -> null -> new: the null step still sees the
+    // LEAVING element as the old value (its DOM is alive for the
+    // dissolve), which is where the position is read from — an event-only
+    // save would miss programmatic scrolls (no `scroll` event fires for
+    // them), so the read happens on the ref hand-off itself and the
+    // onScroll below merely keeps the value fresh between flips. Raw
+    // scrollTop is an approximation across dresses (rail rows and full
+    // rows have different heights) — an exact restore would need an
+    // item-keyed anchor, not worth it for a nav list; the browser clamps
+    // any overshoot.
+    const savedScrollTop = ref(0);
+    const onBodyScroll = (e: Event): void => {
+      savedScrollTop.value = (e.currentTarget as HTMLElement).scrollTop;
+    };
+    watch(bodyRef, async (body, leaving) => {
+      if (leaving) savedScrollTop.value = leaving.scrollTop;
+      if (!body) return;
+      await nextTick();
+      body.scrollTop = savedScrollTop.value;
+    });
+
     onBeforeUnmount(() => {
       bodyScrollbar?.detach();
       bodyScrollbar = null;
@@ -199,7 +227,7 @@ export default defineComponent({
           <header class="hk-sidebar-header">{slots.header()}</header>
         ) : null}
         <div ref={bodyWrapRef} class="hk-sidebar-body-wrap">
-          <div ref={bodyRef} class="hk-sidebar-body">
+          <div ref={bodyRef} class="hk-sidebar-body" onScroll={onBodyScroll}>
             {/* Scoped params (ignored by plain slots): the density that
                 owns THIS generation so a host renders icon-only rows
                 while collapsed and full rows during a peek, plus the

package/src/index.ts

@@ -555,6 +555,7 @@ export { HkNavSidebar as HNavSidebar } from "./components/HkNavSidebar";
 export { HkThemeToggle as HThemeToggle, type ThemeItemScope } from "./components/HkThemeToggle";
 export { HkThemePanelContent as HThemePanelContent } from "./components/HkThemePanelContent";
 export { HkSolarLocationSetting as HSolarLocationSetting } from "./components/HkSolarLocationSetting";
+export { HkDateTag as HDateTag } from "./components/HkDateTag";
 export { HkAuthCard as HAuthCard } from "./components/HkAuthCard";
 export { default as HAuthMethodList } from "./components/HkAuthMethodList";
 export { HkSignInCard as HSignInCard } from "./components/HkSignInCard";
@@ -836,6 +837,7 @@ export { HkNavSidebar as HkNavSidebar } from "./components/HkNavSidebar";
 export { HkThemeToggle as HkThemeToggle } from "./components/HkThemeToggle";
 export { HkThemePanelContent as HkThemePanelContent } from "./components/HkThemePanelContent";
 export { HkSolarLocationSetting as HkSolarLocationSetting } from "./components/HkSolarLocationSetting";
+export { HkDateTag as HkDateTag } from "./components/HkDateTag";
 export { HkAuthCard as HkAuthCard } from "./components/HkAuthCard";
 export { HkSignInCard as HkSignInCard } from "./components/HkSignInCard";
 export { HkThirdPartySignInCard as HkThirdPartySignInCard } from "./components/HkThirdPartySignInCard";