@celestia-island/hikari 0.55.261 → 0.55.263

package/src/components/HkTimeZoneGlobe.board.test.tsx

@@ -0,0 +1,263 @@
+// AI-generated: developed with the ZCode agent (model GLM-5.3); human-directed.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick, ref, type Ref } from "vue";
+
+/**
+ * HkTimeZoneGlobe × HkBoard3D — the picker's WEBGL branch contract.
+ *
+ * The real board cannot init in happy-dom (no WebGL), so this suite stubs
+ * it and keeps the board's whole props surface addressable. Two product
+ * directions from 2026-11-01 are template-level promises and belong here:
+ *
+ *  - TURNTABLE: the globe passes equal min/max polar bounds (90° - the
+ *    eye's 18° ring tilt) so the board can only spin about the vertical
+ *    axis — the sphere never tips toward a pole or rolls;
+ *  - READOUT: the SELECTED sector's chip is the globe's own always-on
+ *    layer pinned to the top-center of the stage — not a pointer-following
+ *    tooltip (which sat under the finger on a touch drag), not gated on
+ *    hover, and not rewritten by hover either (a drag re-selects without
+ *    moving the pointer, so a hover preview would go stale as it is read).
+ *
+ * The no-WebGL assertions (fallback list, readout stepping aside) live in
+ * HkTimeZoneGlobe.test.tsx, which mounts the real board.
+ */
+
+interface CapturedBoard {
+  minPolarAngle?: number;
+  maxPolarAngle?: number;
+  interactive?: boolean;
+  minimap?: boolean;
+  minimapCollapsible?: boolean;
+  minimapDefaultCollapsed?: boolean;
+  enablePan?: boolean;
+  minDistance?: number;
+  maxDistance?: number;
+  /** The globe's onObjectHover listener (preview a wedge). */
+  onObjectHover: ((id: string | null) => void) | null;
+  /** The globe's onError listener (no-WebGL report). */
+  onError: ((message: string) => void) | null;
+}
+
+const captured = vi.hoisted(() => ({ boards: [] as CapturedBoard[] }));
+
+vi.mock("./HkBoard3D", async () => {
+  const vue = await import("vue");
+  /** Narrow an undeclared-listener attr without a double cast. */
+  function listenerOf<T extends (...args: never[]) => void>(value: unknown): T | null {
+    return typeof value === "function" ? (value as T) : null;
+  }
+  const BoardStub = vue.defineComponent({
+    name: "HkBoard3D",
+    props: {
+      interactive: Boolean,
+      minimap: Boolean,
+      minimapCollapsible: Boolean,
+      minimapDefaultCollapsed: Boolean,
+      hoverBox: Boolean,
+      transparentBackground: Boolean,
+      enablePan: Boolean,
+      minPolarAngle: Number,
+      maxPolarAngle: Number,
+      fov: Number,
+      minDistance: Number,
+      maxDistance: Number,
+      initialPosition: Array,
+      initialTarget: Array,
+    },
+    // Deliberately NO `emits` declaration: the globe's listeners then land
+    // in `attrs`, which is exactly how this suite reaches onObjectHover /
+    // onError without the stub ever calling emit().
+    setup(props, { attrs }) {
+      captured.boards.push({
+        minPolarAngle: props.minPolarAngle,
+        maxPolarAngle: props.maxPolarAngle,
+        interactive: props.interactive,
+        minimap: props.minimap,
+        minimapCollapsible: props.minimapCollapsible,
+        minimapDefaultCollapsed: props.minimapDefaultCollapsed,
+        enablePan: props.enablePan,
+        minDistance: props.minDistance,
+        maxDistance: props.maxDistance,
+        onObjectHover: listenerOf<(id: string | null) => void>(attrs.onObjectHover),
+        onError: listenerOf<(message: string) => void>(attrs.onError),
+      });
+      return () => null;
+    },
+  });
+  return { default: BoardStub };
+});
+
+import HkTimeZoneGlobe from "./HkTimeZoneGlobe";
+import { setLocale } from "../i18n/context";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountGlobe(modelValue = "Asia/Shanghai"): {
+  container: HTMLElement;
+  zone: Ref<string>;
+} {
+  captured.boards.length = 0;
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  // A live modelValue ref, so a test can drive a re-selection the way the
+  // host does (HkSolarLocationSetting writes draftTimeZone).
+  const zone = ref(modelValue);
+  const app = createApp({
+    render: () =>
+      h(HkTimeZoneGlobe, {
+        modelValue: zone.value,
+        "onUpdate:modelValue": (next: string) => {
+          zone.value = next;
+        },
+      }),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return { container, zone };
+}
+
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  await nextTick();
+}
+
+function board(): CapturedBoard {
+  expect(captured.boards, "the globe mounted one board").toHaveLength(1);
+  return captured.boards[0]!;
+}
+
+function readout(): HTMLElement | null {
+  return document.body.querySelector<HTMLElement>('[data-test="hk-timezone-globe-readout"]');
+}
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+afterEach(async () => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  await setLocale("en");
+});
+
+describe("HkTimeZoneGlobe turntable contract", () => {
+  it("locks the board's orbit elevation to the eye ring (equal polar bounds)", async () => {
+    mountGlobe();
+    await settle();
+
+    const { minPolarAngle, maxPolarAngle, interactive } = board();
+    // 90° - EYE_TILT_DEG (18°) = 72°, as a DEGREE-valued board prop.
+    expect(minPolarAngle).toBe(72);
+    expect(maxPolarAngle).toBe(72);
+    expect(minPolarAngle).toBe(maxPolarAngle);
+    // The lock only binds on an INTERACTIVE board: a non-interactive board
+    // deliberately relaxes the elevation window for its external driver,
+    // so the globe must never mount as one.
+    expect(interactive).toBe(true);
+  });
+
+  it("keeps the minimap (collapsible, folded by default) and disables panning", async () => {
+    mountGlobe();
+    await settle();
+
+    const b = board();
+    expect(b.minimap).toBe(true);
+    expect(b.minimapCollapsible).toBe(true);
+    expect(b.minimapDefaultCollapsed).toBe(true);
+    expect(b.enablePan).toBe(false);
+    // The picker still owns its own distance window and framing.
+    expect(b.minDistance).toBe(2.15);
+    expect(b.maxDistance).toBe(3.6);
+  });
+});
+
+describe("HkTimeZoneGlobe pinned readout", () => {
+  it("shows the selected sector with no hover needed (always on)", async () => {
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const el = readout();
+    expect(el, "the readout renders without any pointer interaction").toBeTruthy();
+    expect(el!.textContent).toContain("UTC+8");
+    expect(el!.textContent).toContain("Asia/Shanghai");
+    // A city from the SELECTED band's second line — "Singapore" is not a
+    // substring of the zone id, so only the cities row can satisfy it
+    // ("Shanghai" would have been satisfied by "Asia/Shanghai").
+    const cities = el!.querySelector<HTMLElement>(".hk-timezone-globe__readout-cities");
+    expect(cities, "the cities line renders").toBeTruthy();
+    expect(cities!.textContent).toContain("Singapore");
+    // A live region, so a COMMITTED re-pick is spoken; hover never
+    // rewrites the chip, so hovering cannot flood the announce queue.
+    expect(el!.getAttribute("role")).toBe("status");
+    expect(el!.getAttribute("aria-live")).toBe("polite");
+    expect(el!.getAttribute("aria-atomic")).toBe("true");
+    // The old pointer-following tooltip is gone for good.
+    expect(document.body.querySelector('[data-test="hk-timezone-globe-tooltip"]')).toBeNull();
+  });
+
+  it("follows a committed re-selection when the host writes a new zone", async () => {
+    const { zone } = mountGlobe("Asia/Shanghai");
+    await settle();
+    expect(readout()!.textContent).toContain("Asia/Shanghai");
+
+    // The host's write path (draftTimeZone → modelValue), not a click: the
+    // chip must re-render on the new band, not stay frozen at mount.
+    zone.value = "Africa/Cairo";
+    await settle();
+    expect(readout()!.textContent).toContain("Africa/Cairo");
+    expect(readout()!.textContent).toContain("UTC+2");
+    expect(readout()!.textContent).not.toContain("Asia/Shanghai");
+  });
+
+  it("keeps showing the committed selection while a wedge is hovered", async () => {
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const onObjectHover = board().onObjectHover;
+    expect(onObjectHover, "the globe wired the board's hover event").toBeTruthy();
+    onObjectHover!("sector-20"); // offset +9 → Asia/Tokyo
+    await settle();
+    // The chip is a selection statement: hover only tints the wedge.
+    expect(readout()!.textContent).toContain("Asia/Shanghai");
+    expect(readout()!.textContent).not.toContain("Asia/Tokyo");
+
+    onObjectHover!(null);
+    await settle();
+    expect(readout()!.textContent).toContain("Asia/Shanghai");
+  });
+
+  it("does not repeat an English band name that IS its offset label", async () => {
+    await setLocale("en"); // explicit: this contract is locale-dependent
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const text = readout()!.textContent ?? "";
+    expect(text.match(/UTC\+8/g)).toHaveLength(1);
+    expect(text).toContain("Asia/Shanghai");
+  });
+
+  it("keeps the translated band name where the locale names the band (zh-Hans)", async () => {
+    await setLocale("zh-Hans");
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const text = readout()!.textContent ?? "";
+    expect(text).toContain("UTC+8");
+    expect(text).toContain("东八区");
+  });
+
+  it("steps aside when the board reports no WebGL (the fallback list is the interface)", async () => {
+    mountGlobe("Asia/Shanghai");
+    await settle();
+    expect(readout()).toBeTruthy();
+
+    const onError = board().onError;
+    expect(onError, "the globe wired the board's error event").toBeTruthy();
+    onError!("no webgl (test)");
+    await settle();
+    expect(readout()).toBeNull();
+  });
+});

package/src/components/HkTimeZoneGlobe.scss

@@ -1,6 +1,6 @@
-/* HkTimeZoneGlobe — the manual zone picker's globe stage, tooltip and
- * no-WebGL fallback list. AI-generated: developed with the ZCode agent
- * (model GLM-5.3); human-directed. */
+/* HkTimeZoneGlobe — the manual zone picker's globe stage, always-on
+ * readout and no-WebGL fallback list. AI-generated: developed with the
+ * ZCode agent (model GLM-5.3); human-directed. */
 
 .hk-timezone-globe {
   display: flex;
@@ -23,35 +23,64 @@
   touch-action: none;
 }
 
-.hk-timezone-globe__tooltip {
+/* The always-on sector readout: pinned to the TOP-CENTER of the stage
+ * (user direction 2026-11-01). It replaced the pointer-following
+ * tooltip, which on a touch screen sat under the very finger dragging
+ * the globe. A passive HUD layer — pointer-events none, so a drag that
+ * begins on the chip still orbits. */
+.hk-timezone-globe__readout {
   position: absolute;
+  top: var(--space-6, 0.375rem);
+  left: 50%;
   z-index: 2;
-  pointer-events: none;
+  transform: translateX(-50%);
   display: flex;
   flex-direction: column;
-  gap: var(--space-4, 0.25rem);
-  max-width: 15rem;
-  padding: var(--space-8, 0.5rem) var(--space-10, 0.625rem);
+  align-items: center;
+  gap: 1px;
+  max-width: calc(100% - var(--space-16, 1rem));
+  padding: var(--space-4, 0.25rem) var(--space-10, 0.625rem);
   border: 1px solid rgb(var(--color-muted) / 0.35);
   border-radius: var(--radius-sm, 0.375rem);
-  background: rgb(var(--color-background, 22 24 30) / 0.92);
+  background: rgb(var(--color-background, 22 24 30) / 0.88);
   color: inherit;
   font-size: var(--text-xs, 0.75rem);
-  line-height: 1.45;
+  line-height: 1.35;
+  text-align: center;
+  pointer-events: none;
+}
+
+.hk-timezone-globe__readout-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: center;
+  gap: 0 var(--space-6, 0.375rem);
+  white-space: nowrap;
 }
 
-.hk-timezone-globe__tooltip-offset {
+.hk-timezone-globe__readout-offset {
   color: rgb(var(--color-text-secondary, var(--color-muted)));
   font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+.hk-timezone-globe__readout-name {
+  font-weight: 600;
 }
 
-.hk-timezone-globe__tooltip-zone {
+.hk-timezone-globe__readout-zone {
+  color: rgb(var(--color-text-secondary, var(--color-muted)));
   font-family: var(--font-mono, ui-monospace, monospace);
   font-size: var(--text-xs, 0.75rem);
 }
 
-.hk-timezone-globe__tooltip-cities {
+.hk-timezone-globe__readout-cities {
+  max-width: 100%;
+  overflow: hidden;
   color: rgb(var(--color-text-secondary, var(--color-muted)));
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .hk-timezone-globe__hint {

package/src/components/HkTimeZoneGlobe.test.tsx

@@ -116,6 +116,9 @@ describe("HkTimeZoneGlobe fallback list", () => {
     const root = document.body.querySelector<HTMLElement>('[data-test="hk-timezone-globe"]')!;
     expect(root.getAttribute("aria-label")).toBe("Time zone globe");
     expect(root.textContent).toContain("Drag to spin the globe");
+    // The pinned HUD is a canvas affordance: without WebGL the list IS the
+    // interface, so the chip must not cover its rows.
+    expect(document.body.querySelector('[data-test="hk-timezone-globe-readout"]')).toBeNull();
   });
 
   it("flows zh-Hans through the sector names and city lists", async () => {
@@ -140,6 +143,36 @@ describe("HkTimeZoneGlobe look contract (source-level)", () => {
     expect(src).toContain("minimapCollapsible");
     expect(src).toContain("minimapDefaultCollapsed");
   });
+
+  it("pins the readout to the stage's TOP-CENTER, pointer-transparent (user direction 2026-11-01)", () => {
+    const scss = readFileSync(join(import.meta.dirname, "HkTimeZoneGlobe.scss"), "utf8");
+    const block = (selector: string): string => {
+      const start = scss.indexOf(selector + " {");
+      expect(start, selector + " exists").toBeGreaterThanOrEqual(0);
+      const end = scss.indexOf("\n}", start);
+      expect(end, selector + " closes").toBeGreaterThan(start);
+      return scss.slice(start, end);
+    };
+
+    // The readout is absolutely positioned, so its containing block must
+    // stay the stage.
+    expect(block(".hk-timezone-globe__stage")).toContain("position: relative");
+
+    const readout = block(".hk-timezone-globe__readout");
+    expect(readout, "a HUD layer over the canvas").toContain("position: absolute");
+    expect(readout, "top-anchored").toMatch(/top:\s*var\(--space-6/);
+    expect(readout, "horizontally centered").toContain("left: 50%");
+    expect(readout, "horizontally centered").toContain("transform: translateX(-50%)");
+    // The board paints an opaque surface later in the DOM, so the chip is
+    // only visible while it stacks above it.
+    expect(readout, "above the board surface").toMatch(/z-index:\s*[1-9]/);
+    // The chip sits over the very surface the user drags; a drag that
+    // begins on it must still reach the canvas.
+    expect(readout, "a passive layer").toContain("pointer-events: none");
+
+    // A long city row must ellipsize inside the chip, not escape it.
+    expect(block(".hk-timezone-globe__readout-cities")).toContain("text-overflow: ellipsis");
+  });
 });
 describe("minimap reset icon contract (user direction 2026-10-31)", () => {
   it("reset buttons use RotateCcw, never the expand-looking Maximize2", () => {

package/src/components/HkTimeZoneGlobe.tsx

@@ -13,14 +13,26 @@
  *    white-alpha, the material tints it with the live theme accent, so
  *    one asset serves dark and light themes;
  *  - SECTORS: 24 pickable wedges of 15 deg longitude (theme/
- *    solarTimeZones.ts) — drag rotates (OrbitControls), settling snaps
- *    the wedge under the eye INTO the selection, clicking a wedge flies
- *    the camera to it; both write the wedge's REPRESENTATIVE IANA zone
+ *    solarTimeZones.ts) — drag spins the globe, settling snaps the wedge
+ *    under the eye INTO the selection, clicking a wedge flies the
+ *    camera to it; both write the wedge's REPRESENTATIVE IANA zone
  *    through update:modelValue (the engine stores exact ids, so a
  *    half-hour config survives until the user actually re-picks);
- *  - TOOLTIP: hovering a wedge surfaces its zone (translated sector
- *    name + the IANA id) and its representative cities — cities only,
- *    never countries (border disputes stay out of a theme picker);
+ *  - TURNTABLE: the board's orbit elevation window is pinned
+ *    (minPolarAngle === maxPolarAngle) to the eye's ring tilt, so the
+ *    sphere can only spin about its vertical axis. It never tips toward
+ *    a pole and never rolls — the north hemisphere keeps its 18° tilt
+ *    (user direction 2026-11-01: "the globe turns in front of you");
+ *  - READOUT: the SELECTED sector stays pinned to the TOP-CENTER of the
+ *    stage — always on, and hover never rewrites it (a drag re-selects
+ *    without moving the pointer, so a hover preview would be stale at
+ *    exactly the moment it is read). It replaced the pointer-following
+ *    tooltip, which on a touch screen landed under the very finger doing
+ *    the drag (user direction 2026-11-01). The head carries the IANA id
+ *    with the translated band name (dropped where the locale's band name
+ *    IS the offset label — English), the second line its representative
+ *    cities: cities only, never countries (border disputes stay out of a
+ *    theme picker);
  *  - MINIMAP: the board pins HkMinimap3D bottom-right — a second,
  *    stereoscopic render of the SAME scene, so the operator always sees
  *    where on the sphere the eye currently sits;
@@ -70,6 +82,11 @@ const DEG = Math.PI / 180;
 /** Eye distance and latitude tilt for the fixed-radius ring orbit. */
 const EYE_DISTANCE = 2.85;
 const EYE_TILT_DEG = 18;
+/** The locked orbit elevation (OrbitControls polar angle, degrees from
+ *  +Y) that pairs with EYE_TILT_DEG: equal min/max polar bounds keep the
+ *  eye on this one ring, so azimuth is the only orbit axis left — the
+ *  globe turns in place instead of tipping. */
+const ORBIT_POLAR_DEG = 90 - EYE_TILT_DEG;
 /** Sphere and wedge radii — the wedges ride slightly above the base to
  *  keep the highlight out of the texture's z-fight band. */
 const GLOBE_RADIUS = 1;
@@ -120,9 +137,12 @@ export default defineComponent({
   setup(props, { emit }) {
     const { t } = useI18n();
     const engine = shallowRef<Board3DEngine | null>(null);
-    const stageRef = ref<HTMLElement | null>(null);
     const hoveredSector = ref<number | null>(null);
-    const tooltipPos = ref({ x: 0, y: 0 });
+    // The stage readout is a HUD for the CANVAS; without WebGL the board's
+    // fallback list is the whole interface (every sector already shows its
+    // zone there), so the HUD steps aside instead of covering its first
+    // rows.
+    const webglFailed = ref(false);
 
     // Per-mount three handles the board does NOT own (we created them,
     // we dispose them — the board never disposes consumer objects).
@@ -138,10 +158,13 @@ export default defineComponent({
 
     const selectedSector = computed(() => sectorIndexForZone(props.modelValue));
 
-    const selectedInfo = computed(() => {
-      const idx = hoveredSector.value ?? selectedSector.value;
-      return SOLAR_TIME_ZONE_SECTORS[idx] ?? null;
-    });
+    // The pinned readout reports the COMMITTED selection, never the
+    // hovered wedge. Hover already answers "what am I pointing at" on the
+    // globe itself (the wedge highlight); the always-on chip must keep
+    // answering "what is selected", because a drag that re-selects does
+    // not move the pointer — a hover preview there would go stale at
+    // exactly the moment the user is looking at it.
+    const selectedInfo = computed(() => SOLAR_TIME_ZONE_SECTORS[selectedSector.value] ?? null);
 
     function citiesLine(sector: { cities: readonly string[] }): string {
       const sep = t("hikari::theme.solar.citySeparator", ", ");
@@ -281,11 +304,8 @@ export default defineComponent({
       hoveredSector.value = m ? parseInt(m[1] ?? "", 10) : null;
     }
 
-    function onPointerMove(ev: PointerEvent): void {
-      const stage = stageRef.value;
-      if (!stage) return;
-      const rect = stage.getBoundingClientRect();
-      tooltipPos.value = { x: ev.clientX - rect.left, y: ev.clientY - rect.top };
+    function onBoardError(): void {
+      webglFailed.value = true;
     }
 
     onBeforeUnmount(() => {
@@ -337,6 +357,11 @@ export default defineComponent({
 
     return () => {
       const info = selectedInfo.value;
+      // In `en`, a band's translated name IS its offset label ("UTC+8"), so
+      // rendering both would read "UTC+8 UTC+8". Keep the name only where
+      // the locale actually names the band differently.
+      const infoOffset = info ? offsetLabel(info.offset) : "";
+      const infoName = info ? t(sectorNameKey(info.offset)) : "";
       const initialEye = ringPosition(sectorCenterLngDeg(
         SOLAR_TIME_ZONE_SECTORS[selectedSector.value]?.offset ?? 0,
       ));
@@ -347,7 +372,25 @@ export default defineComponent({
           aria-label={t("hikari::theme.solar.globeLabel")}
           data-test="hk-timezone-globe"
         >
-          <div class="hk-timezone-globe__stage" ref={stageRef} onPointermove={onPointerMove}>
+          <div class="hk-timezone-globe__stage">
+            {info && !webglFailed.value && (
+              <div
+                class="hk-timezone-globe__readout"
+                data-test="hk-timezone-globe-readout"
+                role="status"
+                aria-live="polite"
+                aria-atomic="true"
+              >
+                <span class="hk-timezone-globe__readout-head">
+                  <span class="hk-timezone-globe__readout-offset">{infoOffset}</span>
+                  {infoName !== infoOffset && (
+                    <span class="hk-timezone-globe__readout-name">{infoName}</span>
+                  )}
+                  <span class="hk-timezone-globe__readout-zone">{info.zone}</span>
+                </span>
+                <span class="hk-timezone-globe__readout-cities">{citiesLine(info)}</span>
+              </div>
+            )}
             <HkBoard3D
               interactive
               minimap
@@ -356,6 +399,10 @@ export default defineComponent({
               hoverBox={false}
               transparentBackground
               enablePan={false}
+              // Turntable: equal polar bounds pin the eye to its ring, so
+              // the globe spins about its vertical axis only.
+              minPolarAngle={ORBIT_POLAR_DEG}
+              maxPolarAngle={ORBIT_POLAR_DEG}
               fov={38}
               minDistance={2.15}
               maxDistance={3.6}
@@ -364,25 +411,10 @@ export default defineComponent({
               onReady={onReady}
               onObjectClick={onObjectClick}
               onObjectHover={onObjectHover}
+              onError={onBoardError}
             >
               {{ fallback: fallbackList }}
             </HkBoard3D>
-            {info && hoveredSector.value !== null && (
-              <div
-                class="hk-timezone-globe__tooltip"
-                data-test="hk-timezone-globe-tooltip"
-                style={{
-                  left: tooltipPos.value.x + 14 + "px",
-                  top: tooltipPos.value.y + 14 + "px",
-                }}
-              >
-                <span class="hk-timezone-globe__tooltip-offset">
-                  {offsetLabel(info.offset)} · {t(sectorNameKey(info.offset))}
-                </span>
-                <span class="hk-timezone-globe__tooltip-zone">{info.zone}</span>
-                <span class="hk-timezone-globe__tooltip-cities">{citiesLine(info)}</span>
-              </div>
-            )}
           </div>
           <p class="hk-timezone-globe__hint">{t("hikari::theme.solar.globeHint")}</p>
         </div>