@celestia-island/hikari 0.55.281 → 0.55.282

package/package.json

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

package/src/components/HkSolarLocationSetting.scss

@@ -1,10 +1,16 @@
-/* HkSolarLocationSetting — the solar-clock location strategy row and
+/* HkSolarLocationSetting — the solar-clock location strategy card and
  * its editor modal body (see the component docblock for the strategy
  * ladder). AI-generated: developed with the ZCode agent (model
  * GLM-5.3); human-directed. */
 
-/* ── The settings-page row: live summary + Edit button ────────────────── */
+/* ── The settings-page card (HkCard root; header/body classes are the
+ *    card family's own) ─────────────────────────────────────────────── */
 .hk-solar-setting {
+  min-width: 0;
+}
+
+/* ── The card body's live summary + Edit button line ──────────────────── */
+.hk-solar-row {
   display: flex;
   align-items: center;
   gap: var(--space-8, 0.5rem);
@@ -59,6 +65,61 @@
   line-height: 1.5;
 }
 
+/* ── Detected-value readout (timezone / ip panes) ───────────────────────
+ * One info item per line: a fixed label column and a value column of
+ * copyable tags, so long values keep their own row and the two columns
+ * stay aligned across rows. */
+.hk-solar-detected {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+}
+
+.hk-solar-detected-row {
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
+  gap: var(--space-8, 0.5rem);
+  align-items: start;
+}
+
+.hk-solar-detected-label {
+  padding-top: var(--space-1, 0.125rem);
+  font-size: var(--text-xs);
+  color: rgb(var(--color-muted));
+  /* Long localized labels wrap instead of pushing the value column out. */
+  overflow-wrap: anywhere;
+}
+
+.hk-solar-detected-value {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-6, 0.375rem);
+  min-width: 0;
+}
+
+/* Values are labels, not prose — but a readout value that outruns the
+ * modal soft-wraps inside its chip instead of clipping or overflowing. */
+.hk-solar-detected-value .hk-badge {
+  white-space: normal;
+  overflow-wrap: anywhere;
+  text-align: left;
+}
+
+/* Probe status line (IP pane): muted progress / failure note, with the
+ * retry affordance inline after the text. */
+.hk-solar-detected-status {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--space-6, 0.375rem);
+  color: rgb(var(--color-muted));
+  font-size: var(--text-xs);
+}
+
+.hk-solar-detected-retry {
+  flex-shrink: 0;
+}
+
 .hk-solar-manual {
   display: flex;
   flex-direction: column;

package/src/components/HkSolarLocationSetting.test.tsx

@@ -2,12 +2,14 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick } from "vue";
 
-import { HkSolarLocationSetting } from "./HkSolarLocationSetting";
+import { HkSolarLocationSetting, solarOffsetText, solarTimezoneDetectedRows } from "./HkSolarLocationSetting";
 import { setLocale } from "../i18n/context";
 import {
   SOLAR_LOCATION_STRATEGY_STORAGE_KEY,
   SOLAR_MANUAL_LOCATION_STORAGE_KEY,
   manualLocationOf,
+  probeSolarIpInsight,
+  resetSolarIpInsight,
   setSolarLocationStrategy,
   setSolarManualLocation,
   solarLocationStrategy,
@@ -15,15 +17,36 @@ import {
   systemTimeZoneId,
   type SolarLocationStrategy,
 } from "../theme/useSolarTime";
+import { cityKey, sectorForZone, sectorNameKey, standardOffsetHours } from "../theme/solarTimeZones";
+
+// The locale dictionaries, loaded the same way the locales-coverage suite
+// reads them (import.meta.glob; readFileSync resolves wrong under vitest's
+// transform) — the same bundles the component renders, so readout
+// expectations stay exact on any runtime zone (CI runners sit in UTC; dev
+// machines often sit in Asia/Shanghai).
+const localeModules = import.meta.glob<{ default: Record<string, Record<string, string>> }>(
+  "../i18n/locales/*/platform.json",
+  { eager: true },
+);
+
+/** The locale's solar strings. platform.json nests legacy domain
+ *  sections ("platform", "auth" — same layout the locales-coverage
+ *  suite walks); flatten them so dotted `hikari::…` keys read directly. */
+function localeBundle(locale: string): Record<string, string> {
+  const entry = Object.entries(localeModules).find(([path]) => path.includes(`/${locale}/`));
+  expect(entry, `bundle for ${locale} loads`).toBeTruthy();
+  return Object.assign({}, ...Object.values(entry![1].default));
+}
 
 /**
- * HkSolarLocationSetting — the solar clock's location-strategy row.
+ * HkSolarLocationSetting — the solar clock's location-strategy card.
  * The strategy engine (theme/useSolarTime.ts) has its own suite; these
- * cases pin the COMPONENT contract: the live summary row, the secondary
- * HkModal editor (strategy tabs / time-zone globe / explicit
- * hemisphere), OK applying through setSolarManualLocation →
- * setSolarLocationStrategy → refreshThemeClock with storage evidence,
- * and cancel leaving the engine untouched.
+ * cases pin the COMPONENT contract: the standard card with the live
+ * strategy summary, the secondary HkModal editor (strategy tabs /
+ * detected-value readout / time-zone globe / explicit hemisphere), OK
+ * applying through setSolarManualLocation → setSolarLocationStrategy →
+ * refreshThemeClock with storage evidence, and cancel leaving the
+ * engine untouched.
  */
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
@@ -44,6 +67,7 @@ function resetEngineState(): void {
   // the engine's own reset surface (they heal refs AND storage).
   setSolarLocationStrategy("timezone");
   setSolarManualLocation(null);
+  resetSolarIpInsight();
 }
 
 function mountSetting(): HTMLElement {
@@ -126,12 +150,35 @@ function clickStrategy(key: "timezone" | "ip" | "manual"): void {
   clickStrategyTab({ timezone: "Time zone", ip: "IP location", manual: "Manual" }[key]);
 }
 
+/** The editor's detected-value readout (timezone / ip panes). */
+function detectedSection(): HTMLElement {
+  const el = document.body.querySelector<HTMLElement>('[data-test="hk-solar-detected"]');
+  expect(el, "detected-value readout renders").toBeTruthy();
+  return el!;
+}
+
+/** Label → value rows of the readout, keyed by their label text. */
+function detectedRows(): Map<string, string> {
+  const rows = new Map<string, string>();
+  for (const row of detectedSection().querySelectorAll<HTMLElement>(".hk-solar-detected-row")) {
+    const label = row.querySelector<HTMLElement>(".hk-solar-detected-label")?.textContent?.trim();
+    rows.set(label ?? "", row.querySelector<HTMLElement>(".hk-solar-detected-value")?.textContent ?? "");
+  }
+  return rows;
+}
+
+/** Poll budget for the manual pane's defineAsyncComponent globe chunk.
+ *  Full-suite runs queue the chunk's transform behind hundreds of other
+ *  files, so the wait must tolerate a starved importer (≈ 120 settled
+ *  ticks ≈ 3s), not just a warm isolated run. */
+const GLOBE_POLL_BUDGET = 120;
+
 /** Picks a zone on the manual pane's globe (the fallback sector list in
  * the test DOM — happy-dom has no WebGL). */
 async function pickTimeZone(zone: string): Promise<void> {
   // The picker is a defineAsyncComponent chunk — wait it in.
   let option: HTMLButtonElement | undefined;
-  for (let i = 0; i < 20 && !option; i++) {
+  for (let i = 0; i < GLOBE_POLL_BUDGET && !option; i++) {
     option = document.body.querySelector<HTMLButtonElement>(
       '[data-test="hk-timezone-globe-option"][data-zone="' + zone + '"]',
     ) ?? undefined;
@@ -169,17 +216,17 @@ afterEach(async () => {
   await setLocale("en");
 });
 
-describe("HkSolarLocationSetting row", () => {
-  it("renders the live summary with the strategy icon and the edit button", async () => {
+describe("HkSolarLocationSetting card", () => {
+  it("renders the standardized summary with the strategy icon and the edit button", async () => {
     const container = mountSetting();
     await settle();
 
     const summary = rowSummary(container);
     expect(summary.getAttribute("data-strategy")).toBe("timezone");
-    // Offline default: the summary names the strategy AND the live
-    // system zone id (systemTimeZoneId), so the row is self-explaining.
-    expect(summary.textContent).toContain("Time zone");
-    expect(summary.textContent).toContain(systemTimeZoneId());
+    // Offline default: the summary names the POLICY in a fixed shape —
+    // no zone id in the summary (that lives in the editor's readout).
+    expect(summary.textContent).toContain("Auto · By time zone");
+    expect(summary.textContent).not.toContain(systemTimeZoneId());
     expect(summary.querySelector("svg"), "strategy glyph renders").toBeTruthy();
 
     const btn = editButton(container);
@@ -188,6 +235,38 @@ describe("HkSolarLocationSetting row", () => {
     expect(document.body.querySelector(".hk-solar-editor")).toBeNull();
   });
 
+  it("is a standard hikari card: localized default title, overridable, hideable", async () => {
+    const container = mountSetting();
+    await settle();
+
+    const card = container.querySelector<HTMLElement>(".hk-card.hk-solar-setting");
+    expect(card, "the row renders as an HkCard").toBeTruthy();
+    const title = card!.querySelector<HTMLElement>(".hk-card-title");
+    expect(title?.textContent?.trim()).toBe("Daylight location");
+
+    // An explicit title replaces the default; an empty string hides the
+    // header (hosts that label their own section around the card).
+    for (const [titleProp, expectedHeader] of [
+      ["Custom title", "Custom title"],
+      ["", null],
+    ] as const) {
+      const host = document.createElement("div");
+      document.body.appendChild(host);
+      const app = createApp({
+        render: () => h(HkSolarLocationSetting, { title: titleProp }),
+      });
+      app.mount(host);
+      mounts.push({ app, container: host });
+      await settle();
+      const header = host.querySelector(".hk-card-header");
+      if (expectedHeader === null) {
+        expect(header, "empty title hides the header").toBeNull();
+      } else {
+        expect(header?.textContent?.trim()).toBe(expectedHeader);
+      }
+    }
+  });
+
   it("reflects the manual strategy in the row once applied", async () => {
     setSolarManualLocation({ timeZone: "Australia/Sydney", hemisphere: "south" });
     setSolarLocationStrategy("manual");
@@ -196,13 +275,77 @@ describe("HkSolarLocationSetting row", () => {
 
     const summary = rowSummary(container);
     expect(summary.getAttribute("data-strategy")).toBe("manual");
-    expect(summary.textContent).toContain("Australia/Sydney");
-    expect(summary.textContent).toContain("Southern");
+    expect(summary.textContent).toContain("Manual · Australia/Sydney · Southern");
+  });
+
+  it("never probes on mount or on the timezone pane — the offline-first contract", async () => {
+    // The strategy card's own promise: a fresh environment must not
+    // issue a network request (nor touch permissions) until the user
+    // deliberately enters the IP pane (or applies the ip strategy).
+    const fetchMock = vi.mocked(globalThis.fetch);
+    const container = mountSetting();
+    await settle();
+    expect(fetchMock, "mounting the card stays offline").not.toHaveBeenCalled();
+
+    await openEditor(container);
+    await settle();
+    expect(fetchMock, "opening the editor on the timezone pane stays offline").not.toHaveBeenCalled();
+
+    // Switching away and back (timezone ⇄ manual) never probes either.
+    clickStrategy("manual");
+    await settle();
+    clickStrategy("timezone");
+    await settle();
+    expect(fetchMock, "timezone ⇄ manual switches stay offline").not.toHaveBeenCalled();
+  });
+});
+
+describe("solarTimezoneDetectedRows + solarOffsetText (pure builders)", () => {
+  const en = localeBundle("en");
+  const translate = (key: string): string => en[key] ?? key;
+
+  function rowOf(rows: ReturnType<typeof solarTimezoneDetectedRows>, label: string): string | undefined {
+    return rows.find((row) => row.label === label)?.badges[0]?.text;
+  }
+
+  it("bands + example cities only for zones whose offset IS a wheel sector", () => {
+    const rows = solarTimezoneDetectedRows("Asia/Shanghai", translate);
+    expect(rowOf(rows, "Time zone ID")).toBe("Asia/Shanghai");
+    expect(rowOf(rows, "Time zone")).toBe(en["hikari::theme.solar.sector.p8"]);
+    expect(rowOf(rows, "Example cities")).toContain(en["hikari::theme.solar.city.shanghai"]);
+  });
+
+  it("falls back to the exact offset outside the wheel — never a mislabeled band", () => {
+    // Half-hour zone: no whole-hour band.
+    const kolkata = solarTimezoneDetectedRows("Asia/Kolkata", translate);
+    expect(rowOf(kolkata, "UTC offset")).toBe("UTC+05:30");
+    // Whole-hour zones OUTSIDE the −11…+12 wheel: +13 (Samoa/Tonga/Line
+    // Islands) and POSIX-inverted Etc/GMT+12 (standard −12) must not
+    // borrow the nearest sector's band or cities.
+    for (const zone of ["Pacific/Apia", "Pacific/Kiritimati", "Etc/GMT+12"]) {
+      const rows = solarTimezoneDetectedRows(zone, translate);
+      expect(rows.find((row) => row.label === "Time zone"), zone).toBeUndefined();
+      expect(rows.find((row) => row.label === "Example cities"), zone).toBeUndefined();
+      expect(rowOf(rows, "UTC offset"), zone).toMatch(/^UTC[+-]\d{2}:\d{2}$/);
+    }
+    expect(rowOf(solarTimezoneDetectedRows("Pacific/Apia", translate), "UTC offset")).toBe("UTC+13:00");
+    expect(rowOf(solarTimezoneDetectedRows("Etc/GMT+12", translate), "UTC offset")).toBe("UTC-12:00");
+    expect(rowOf(solarTimezoneDetectedRows("Pacific/Kiritimati", translate), "UTC offset")).toBe("UTC+14:00");
+  });
+
+  it("offsetText pins the exact sign and fraction formatting", () => {
+    expect(solarOffsetText(0)).toBe("UTC");
+    expect(solarOffsetText(8)).toBe("UTC+08:00");
+    expect(solarOffsetText(5.5)).toBe("UTC+05:30");
+    expect(solarOffsetText(5.75)).toBe("UTC+05:45");
+    expect(solarOffsetText(12.75)).toBe("UTC+12:45");
+    expect(solarOffsetText(-3.5)).toBe("UTC-03:30");
+    expect(solarOffsetText(-12)).toBe("UTC-12:00");
   });
 });
 
 describe("HkSolarLocationSetting editor", () => {
-  it("opens the secondary modal with the three strategy tabs and the offline-first hint", async () => {
+  it("opens the secondary modal with the three strategy tabs, the principle hint, and the detected readout", async () => {
     const container = mountSetting();
     await openEditor(container);
 
@@ -221,9 +364,89 @@ describe("HkSolarLocationSetting editor", () => {
     }
 
     const editor = document.body.querySelector<HTMLElement>(".hk-solar-editor");
-    expect(editor!.textContent).toContain("No network request, no permission prompt");
+    expect(editor!.textContent).toContain("no network request and no permission prompt");
     // Manual controls stay hidden while the draft is not manual.
     expect(document.body.querySelector(".hk-solar-manual")).toBeNull();
+
+    // The detected-value readout: one info item per line, each value a
+    // copyable badge — the device zone id, then the translated band and
+    // example cities (whole-hour zones) or the exact UTC offset
+    // (half-hour zones, which have no whole-hour band).
+    const zone = systemTimeZoneId();
+    const sector = sectorForZone(zone);
+    const en = localeBundle("en");
+    const rows = detectedRows();
+    expect(rows.get("Time zone ID")).toContain(zone);
+    if (sector && sector.offset === standardOffsetHours(zone)) {
+      expect(rows.get("Time zone")).toContain(en[sectorNameKey(sector.offset)]!);
+      expect(rows.get("Example cities")).toContain(en[cityKey(sector.cities[0]!)]!);
+    } else {
+      expect(rows.get("UTC offset")).toMatch(/UTC[+-]\d{2}:\d{2}/);
+      expect(rows.has("Example cities")).toBe(false);
+    }
+    for (const badge of detectedSection().querySelectorAll<HTMLElement>(".hk-badge.hk-copy-badge")) {
+      expect(badge.getAttribute("role"), "values are copyable tag buttons").toBe("button");
+    }
+    expect(detectedSection().querySelector(".hk-solar-detected-status")).toBeNull();
+  });
+
+  it("the ip pane probes on entry, shows a retry affordance on failure, and lists the insight", async () => {
+    const container = mountSetting();
+    await openEditor(container);
+    clickStrategy("ip");
+    await settle();
+
+    // The suite's fetch stub answers { ok: false } — the probe fails.
+    await vi.waitFor(() => {
+      expect(detectedSection().querySelector('[data-state="failed"]')).toBeTruthy();
+    });
+    const retry = detectedSection().querySelector<HTMLButtonElement>(".hk-solar-detected-retry");
+    expect(retry, "the failed probe offers a retry").toBeTruthy();
+    expect(retry!.textContent?.trim()).toBe("Retry");
+
+    // A successful re-probe fills the readout: one valid info item per
+    // line, all copyable.
+    vi.stubGlobal("fetch", vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        ip: "203.0.113.7",
+        asn: "AS4134",
+        org: "Chinanet",
+        country_name: "China",
+        region: "Shanghai",
+        city: "Shanghai",
+        timezone: "Asia/Shanghai",
+      }),
+    })));
+    retry!.click();
+    await settle();
+    await vi.waitFor(() => {
+      expect(detectedSection().querySelector('[data-state="failed"]')).toBeNull();
+    });
+    const rows = detectedRows();
+    expect(rows.get("IP address")).toContain("203.0.113.7");
+    expect(rows.get("Autonomous system")).toContain("AS4134");
+    expect(rows.get("Organization")).toContain("Chinanet");
+    expect(rows.get("Network region")).toContain("China · Shanghai · Shanghai");
+    expect(rows.get("IP time zone")).toContain("Asia/Shanghai");
+    // Long prose values render as soft-wrapping chips (not pills).
+    const regionBadge = [...detectedSection().querySelectorAll<HTMLElement>(".hk-badge")]
+      .find((badge) => badge.textContent?.includes("China · Shanghai"));
+    expect(regionBadge?.getAttribute("data-pill")).toBe("false");
+
+    // A failed REFRESH keeps the last known values on the rows — the
+    // status copy must say "refresh failed", not contradict them with
+    // the first-probe failure text. (With state=ok the readout shows no
+    // status line at all; the forced engine probe is exactly what the
+    // retry button would drive.)
+    vi.stubGlobal("fetch", vi.fn(async () => ({ ok: false })));
+    await probeSolarIpInsight(true);
+    await vi.waitFor(() => {
+      expect(detectedSection().querySelector('[data-state="failed"]')).toBeTruthy();
+    });
+    expect(detectedSection().textContent).toContain("Refresh failed — showing the last known values");
+    expect(detectedRows().get("IP address")).toContain("203.0.113.7");
+    expect(detectedSection().querySelector(".hk-solar-detected-retry")).toBeTruthy();
   });
 
   it("switching strategies swaps the hint and reveals the manual pane", async () => {
@@ -243,7 +466,7 @@ describe("HkSolarLocationSetting editor", () => {
     expect(document.body.querySelector(".hk-solar-manual")).toBeTruthy();
     // The globe is a defineAsyncComponent chunk — wait it in.
     let globe: HTMLElement | null = null;
-    for (let i = 0; i < 20 && !globe; i++) {
+    for (let i = 0; i < GLOBE_POLL_BUDGET && !globe; i++) {
       globe = document.body.querySelector<HTMLElement>('[data-test="hk-timezone-globe"]');
       if (!globe) await settle();
     }
@@ -340,13 +563,16 @@ describe("HkSolarLocationSetting editor", () => {
 });
 
 describe("HkSolarLocationSetting i18n", () => {
-  it("flows zh-Hans messages through the row and the editor", async () => {
+  it("flows zh-Hans messages through the card and the editor", async () => {
     await setLocale("zh-Hans");
     const container = mountSetting();
     await settle();
 
+    // The card's localized default title and the standardized summary.
+    const card = container.querySelector<HTMLElement>(".hk-card.hk-solar-setting");
+    expect(card?.querySelector(".hk-card-title")?.textContent?.trim()).toBe("日照位置");
     const summary = rowSummary(container);
-    expect(summary.textContent).toContain("时区");
+    expect(summary.textContent).toContain("自动 · 基于时区");
     expect(editButton(container).textContent?.trim()).toBe("编辑");
 
     await openEditor(container);
@@ -356,6 +582,19 @@ describe("HkSolarLocationSetting i18n", () => {
       "IP 定位",
       "手动",
     ]);
+    // The detected readout in zh-Hans: the translated band and example
+    // cities (whole-hour zones) or the exact offset (half-hour zones).
+    const zone = systemTimeZoneId();
+    const sector = sectorForZone(zone);
+    const zh = localeBundle("zh-Hans");
+    const rows = detectedRows();
+    expect(rows.get("时区 ID")).toContain(zone);
+    if (sector && sector.offset === standardOffsetHours(zone)) {
+      expect(rows.get("时区")).toContain(zh[sectorNameKey(sector.offset)]!);
+      expect(rows.get("代表城市")).toContain(zh[cityKey(sector.cities[0]!)]!);
+    } else {
+      expect(rows.get("UTC 偏移")).toMatch(/UTC[+-]\d{2}:\d{2}/);
+    }
 
     clickStrategyTab("手动");
     await settle();