@celestia-island/hikari 0.30.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/DemoApp.tsx

@@ -13,11 +13,12 @@ import {
   HAlert, HEmptyState, HExpansionPanel,
   HTabs, HCard, HTable, HTimeline,
   HMediaSlider, HMediaPlayer, HImageViewer,
+  HImagePreview,
   HZoomToolbar, HMinimap, HTrendChart,
   type TrendPen, type MinimapBox,
 } from "@celestia-island/hikari";
 
-const totalComponents = 64;
+const totalComponents = 66;
 
 const icons = ["home", "settings", "user", "search", "bell", "heart", "star", "mail", "download", "upload", "trash", "edit", "plus", "check", "x"];
 
@@ -444,6 +445,15 @@ export default defineComponent({
           <HImageViewer src={demoImageSrc} alt="Hikari demo image" />
         </section>
 
+        <section>
+          <h2>HImagePreview</h2>
+          <h3>zoomable (click to open the lightbox) + fixed, contain-fit</h3>
+          <div class="row" style="max-width:720px">
+            <HImagePreview src={demoImageSrc} alt="Zoomable demo image" ratio="16 / 9" style="flex:1" />
+            <HImagePreview src={demoImageSrc} alt="Fixed demo image" zoomable={false} objectFit="contain" ratio="4 / 3" style="flex:1" />
+          </div>
+        </section>
+
         <section>
           <h2>HZoomToolbar / HMinimap</h2>
           <div style="position:relative;height:200px;border-radius:8px;overflow:hidden;background:rgba(0,0,0,0.35)">

package/src/animation/registerAnimations.ts

@@ -78,6 +78,8 @@ registerCssAnimation("hk-modal-breadcrumb-in");
 registerCssAnimation("hk-toast-spin", { infinite: true });
 // components/HkSkeleton.scss — skeleton shimmer (loops forever).
 registerCssAnimation("hk-skeleton-shimmer", { infinite: true });
+// components/HkImagePreview.scss — thumbnail loading shimmer (loops forever).
+registerCssAnimation("hk-image-preview-shimmer", { infinite: true });
 // components/HkProgressBar.scss — indeterminate bar sweep (loops forever).
 registerCssAnimation("hk-progress-indeterminate", { infinite: true });
 // components/HkPasswordInput.scss — caps-lock warning flash (plays once).

package/src/components/HkAuthCard.tsx

@@ -6,6 +6,12 @@ import { defineComponent, type PropType } from "vue";
  * form body.
  *
  * Slot layout contract:
+ * - `methods` renders into a full-width block between the form and the
+ *   footer (typically `HkAuthMethodList`): alternative sign-in buttons
+ *   that must line up with the form inputs. Keeping them OUT of the
+ *   footer is what lets the footer's checkbox rows stay a centered,
+ *   fit-content group instead of being dragged full width with the
+ *   buttons.
  * - `footer` renders into `.s-auth-footer`, a flex column sized to its
  *   widest row and centered in the card: every slot child is its own row
  *   (remember-me, protocol consent, a sign-in link…) and the rows share
@@ -39,6 +45,11 @@ export const HkAuthCard = defineComponent({
         <div class="s-auth-form">
           {slots.default?.()}
         </div>
+        {slots.methods && (
+          <div class="s-auth-methods">
+            {slots.methods()}
+          </div>
+        )}
         {slots.footer && (
           <div class="s-auth-footer">
             {slots.footer()}

package/src/components/HkAuthMethodList.scss

@@ -0,0 +1,57 @@
+/* Full-width stacked alternative sign-in buttons (login card). The block
+   container `.s-auth-methods` and its spacing are owned by HkAuthCard's
+   slot styles (styles/admin-tokens.scss); this file only styles the
+   divider and the buttons the component renders into that slot. */
+
+/* "Other ways to sign in" divider row between rules. */
+.s-auth-methods-divider {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  margin: 0 0 var(--space-4, 0.25rem);
+  color: var(--hi-color-muted, #999);
+  font-size: var(--text-xs, 0.75rem);
+  text-align: center;
+}
+
+.s-auth-methods-divider::before,
+.s-auth-methods-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: var(--hi-color-border, #ddd);
+}
+
+/* The component's own wrapper is `display: contents` (measurement anchor +
+   CSS-var inheritance) — layout-wise the buttons remain direct children of
+   HkAuthCard's `.s-auth-methods` slot container. */
+.s-auth-methods-list {
+  display: contents;
+}
+
+/* Fixed icon + label columns: the two spans keep the same width on every
+   row, so icons and labels align across buttons while each button stays a
+   centered hk-btn-block. HkButton has a fragment root, so inbound classes
+   don't fall through — scope everything off the `.s-auth-methods`
+   container (descendant match: the component wrapper is display:contents).
+   The label column width is MEASURED by the component (widest label text,
+   published as `--auth-methods-label-width` on its wrapper, inherited into
+   the rows); the 8em fallback only covers the pre-measure frame, and apps
+   may still override the var explicitly. */
+.s-auth-methods .hk-btn .s-auth-methods-icon {
+  width: 20px;
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.s-auth-methods .hk-btn .s-auth-methods-label {
+  width: var(--auth-methods-label-width, 8em);
+  flex: none;
+  text-align: start;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

package/src/components/HkAuthMethodList.test.tsx

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import HkAuthMethodList from "./HkAuthMethodList";
+
+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();
+  }
+});
+
+const methods = [
+  { key: "github", label: "GitHub" },
+  { key: "linuxdo", label: "LinuxDo" },
+];
+
+describe("HkAuthMethodList", () => {
+  it("renders one fixed-column button per method and an optional divider", () => {
+    // The card's `methods` slot owns the `.s-auth-methods` container —
+    // reproduce that context here (the buttons are layout children of it
+    // through the component's display:contents wrapper).
+    const c = mount(
+      h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { divider: "其他方式登录", methods })),
+    );
+    const divider = c.querySelector(".s-auth-methods-divider");
+    expect(divider?.textContent).toContain("其他方式登录");
+    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-btn");
+    expect(buttons.length).toBe(2);
+    const labels = [...buttons].map(
+      (b) => b.querySelector<HTMLElement>(".s-auth-methods-label")?.textContent,
+    );
+    expect(labels).toEqual(["GitHub", "LinuxDo"]);
+    for (const b of buttons) {
+      expect(b.querySelector(".s-auth-methods-icon")).toBeTruthy();
+      expect(b.classList.contains("hk-btn-block")).toBe(true);
+    }
+  });
+
+  it("emits select with the method key on click", async () => {
+    let picked = "";
+    const c = mount(
+      h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, {
+        methods,
+        onSelect: (key: string) => {
+          picked = key;
+        },
+      })),
+    );
+    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-btn");
+    buttons[1]!.click();
+    await nextTick();
+    expect(picked).toBe("linuxdo");
+  });
+
+  it("publishes the widest label text as the label-column custom property", async () => {
+    const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
+    await nextTick();
+    const wrapper = c.querySelector<HTMLElement>(".s-auth-methods-list")!;
+    expect(wrapper).toBeTruthy();
+    // Layout engines in test DOM report zero text metrics; stub scrollWidth
+    // on the label spans to a deterministic widest-wins pair (LinuxDo wider).
+    const spans = [...wrapper.querySelectorAll<HTMLElement>(".s-auth-methods-label")];
+    expect(spans.length).toBe(2);
+    Object.defineProperty(spans[0]!, "scrollWidth", { configurable: true, value: 61 });
+    Object.defineProperty(spans[1]!, "scrollWidth", { configurable: true, value: 59 });
+    // Trigger the measurement through a fresh label change (watch path).
+    await nextTick();
+    const { app } = mounts[mounts.length - 1]!;
+    // Re-run measurement via a re-mount-less route: the component exposes
+    // measure() — reach it through the rendered component instance.
+    const instance = (wrapper as unknown as { __vueParentComponent?: { exposed?: Record<string, unknown> } })
+      .__vueParentComponent?.exposed;
+    expect(typeof instance?.measure).toBe("function");
+    (instance!.measure as () => void)();
+    expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("61px");
+    void app;
+  });
+
+  it("leaves the column fallback intact when no text metrics are available", async () => {
+    const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
+    await nextTick();
+    const wrapper = c.querySelector<HTMLElement>(".s-auth-methods-list")!;
+    // Zero scrollWidth (no layout) must not publish a 0px column.
+    expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("");
+  });
+});

package/src/components/HkAuthMethodList.tsx

@@ -0,0 +1,113 @@
+import { defineComponent, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import HkButton from "./HkButton";
+import "./HkAuthMethodList.scss";
+
+/**
+ * HkAuthMethodList — full-width stacked third-party sign-in buttons for
+ * auth cards (the ERP login's provider-button grammar, componentized).
+ *
+ * Every button renders [icon | label] with a FIXED icon column and a FIXED
+ * label column, so the icons and the label text start at the same x on
+ * every row regardless of label length; because every content block is
+ * then the same width, the row can stay centered like any HkButton
+ * without the columns drifting.
+ *
+ * The label column is auto-sized: after mount (and whenever the label set
+ * or the document fonts change) the component measures the widest label
+ * text and publishes it as `--auth-methods-label-width` on its wrapper,
+ * so the aligned text region hugs the longest label instead of a blind
+ * hardcoded width. Consumers can still override the var explicitly.
+ *
+ * The wrapper is `display: contents`: the component keeps a DOM node for
+ * measurement and CSS-var inheritance while the buttons remain direct
+ * layout children of HkAuthCard's `.s-auth-methods` slot container.
+ */
+export default defineComponent({
+  name: "HkAuthMethodList",
+  props: {
+    /** Optional divider text rendered above the buttons, e.g. "其他方式登录".
+     *  Consumer-localized on purpose: hikari ships no dictionary dependency
+     *  onto hosts here. */
+    divider: { type: String, default: "" },
+    /** Provider entries, in render order. */
+    methods: {
+      type: Array as unknown as () => Array<{
+        key: string;
+        label: string;
+        /** Prebuilt icon vnode (brand SVG, <img>, …) — `null` renders an
+         *  empty fixed-width column so the labels still align. Typed loose
+         *  on purpose (same as HkAltSignIn entries): hosts materialize
+         *  hikari against their own vue store, and a hard VNode type
+         *  breaks typecheck whenever the host's vue minor differs. The
+         *  value renders as-is inside the fixed-size column. */
+        icon?: unknown;
+        disabled?: boolean;
+      }>,
+      required: true,
+    },
+  },
+  emits: {
+    /** A method button was clicked. */
+    select: (_key: string) => true,
+  },
+  setup(props, { emit, expose }) {
+    const listRef = ref<HTMLDivElement | null>(null);
+
+    /** Measure the widest label text and publish it as the label-column
+     *  width custom property. `scrollWidth` reports the text width even
+     *  while the fixed column clips it, so this is correct both before
+     *  the variable is first set and after any label change. */
+    function measure() {
+      const root = listRef.value;
+      if (!root) return;
+      let widest = 0;
+      for (const label of root.querySelectorAll<HTMLElement>(".s-auth-methods-label")) {
+        widest = Math.max(widest, label.scrollWidth);
+      }
+      if (widest > 0) root.style.setProperty("--auth-methods-label-width", `${widest}px`);
+    }
+
+    onMounted(() => {
+      void nextTick(measure);
+      // Webfonts change text metrics after first paint; re-measure when
+      // they finish loading (no-op in environments without document.fonts).
+      if (typeof document !== "undefined" && document.fonts?.ready) {
+        void document.fonts.ready.then(measure).catch(() => {});
+      }
+    });
+    onBeforeUnmount(() => {
+      listRef.value?.style.removeProperty("--auth-methods-label-width");
+    });
+    watch(
+      () => props.methods.map((method) => method.label).join("\u0000"),
+      () => {
+        void nextTick(measure);
+      },
+    );
+
+    expose({ measure });
+
+    return () => (
+      <div class="s-auth-methods-list" ref={listRef}>
+        {props.divider && (
+          <div class="s-auth-methods-divider">
+            <span>{props.divider}</span>
+          </div>
+        )}
+        {props.methods.map((method) => (
+          <HkButton
+            key={method.key}
+            variant="outline"
+            size="md"
+            block
+            disabled={method.disabled === true}
+            onClick={() => emit("select", method.key)}
+          >
+            <span class="s-auth-methods-icon">{method.icon}</span>
+            <span class="s-auth-methods-label">{method.label}</span>
+          </HkButton>
+        ))}
+      </div>
+    );
+  },
+});

package/src/components/HkImageLightbox.scss

@@ -0,0 +1,124 @@
+// ------
+// HkImageLightbox
+// Immersive layout override for HModal (attached via the modal's
+// `contentClass` escape hatch). Selectors are doubled as
+// `.hk-modal-content.hk-image-lightbox` so the overrides win the cascade
+// over HkModal's own rules regardless of stylesheet import order.
+//
+// The frame is a fixed-size stage; the body chain (body → scroll →
+// inner) is flattened to pure flex so the HImageViewer fills it, and the
+// floating close button rides on top of the stage.
+// ------
+
+.hk-modal-content.hk-image-lightbox {
+  width: min(96vw, 80rem);
+  height: min(90vh, 56rem);
+
+  // The body fills the frame; nothing scrolls here — the viewer pans
+  // internally, so the modal's scroll region is inert.
+  .hk-modal-body {
+    flex: 1;
+    min-height: 0;
+    max-height: none;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .hk-modal-body-scroll {
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  .hk-modal-body-inner {
+    flex: 1;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+    padding: 0;
+  }
+}
+
+.hk-image-lightbox-stage {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  padding: var(--space-12, 0.75rem);
+
+  // The viewer fills the stage; its own overflow: hidden + rounded
+  // corners clip the panning image into an inset "canvas".
+  .hk-image-viewer {
+    flex: 1;
+    min-width: 0;
+    height: auto;
+    min-height: 0;
+    border-radius: var(--radius-md, 8px);
+  }
+}
+
+// ------
+// Floating close button — legible on any image: translucent dark chip
+// with a blur, light glyph. Colors ride HIconButton's variable layer
+// (--hi-icon-button-*) so the icon span picks them up too.
+// ------
+
+.hk-image-lightbox-close.hk-icon-button {
+  --hi-icon-button-bg: rgb(0 0 0 / 45%);
+  --hi-icon-button-bg-active: rgb(0 0 0 / 65%);
+  --hi-icon-button-icon-color: rgb(255 255 255 / 92%);
+  --hi-icon-button-icon-color-active: #fff;
+
+  position: absolute;
+  top: var(--space-12, 0.75rem);
+  right: var(--space-12, 0.75rem);
+  z-index: 2;
+  background: var(--hi-icon-button-bg);
+  color: var(--hi-icon-button-icon-color);
+  backdrop-filter: blur(6px);
+
+  &:hover {
+    --hi-icon-button-bg: rgb(0 0 0 / 65%);
+    --hi-icon-button-icon-color: #fff;
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(255 255 255 / 80%);
+    outline-offset: 2px;
+  }
+}
+
+// ------
+// Mobile (≤767px, matches HkModal's bottom-sheet breakpoint): the
+// lightbox has no header/footer chrome to dock, so the sheet form
+// (top inset + bottom gap + rounded corners) would only cost viewing
+// area — go true fullscreen instead. HkModal's own `max-width: 100%
+// !important` beats the inline max-width on phones, so plain width/height
+// finish the job without fighting that rule.
+// ------
+
+@media (max-width: 767px) {
+  .hk-modal-content.hk-image-lightbox {
+    top: 0;
+    bottom: auto;
+    left: 0;
+    width: 100vw;
+    // Plain-vh fallback first for dvh-less engines (older Android
+    // WebView / Tauri), then the dynamic-viewport height.
+    height: 100vh;
+    height: 100dvh;
+    max-height: none;
+    border: 0;
+    border-radius: 0;
+  }
+
+  .hk-image-lightbox-stage {
+    padding: var(--space-8, 0.5rem);
+  }
+
+  .hk-image-lightbox-close.hk-icon-button {
+    // Keep the close button clear of notches / home-bar gesture areas.
+    top: calc(var(--space-8, 0.5rem) + env(safe-area-inset-top, 0px));
+    right: calc(var(--space-8, 0.5rem) + env(safe-area-inset-right, 0px));
+  }
+}

package/src/components/HkImageLightbox.test.tsx

@@ -0,0 +1,155 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkImageLightbox from "./HkImageLightbox";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+});
+
+interface Setup {
+  dialog: () => HTMLElement | null;
+  closeButton: () => HTMLButtonElement;
+  emitted: boolean[];
+}
+
+function mountLightbox(initialOpen: boolean): Setup {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const open = ref(initialOpen);
+  const emitted: boolean[] = [];
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkImageLightbox, {
+          src: "/test-wallpaper.svg",
+          alt: "wallpaper",
+          modelValue: open.value,
+          "onUpdate:modelValue": (v: boolean) => { emitted.push(v); open.value = v; },
+        });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+
+  return {
+    dialog: () => document.body.querySelector<HTMLElement>(".hk-modal-content.hk-image-lightbox"),
+    closeButton: () => {
+      const btn = document.body.querySelector<HTMLButtonElement>(".hk-image-lightbox-close");
+      if (!btn) throw new Error("lightbox close button not rendered");
+      return btn;
+    },
+    emitted,
+  };
+}
+
+describe("HkImageLightbox", () => {
+  it("renders the immersive dialog (viewer + close button) while open", () => {
+    const s = mountLightbox(true);
+
+    const dialog = s.dialog();
+    expect(dialog).not.toBeNull();
+    expect(dialog!.querySelector(".hk-image-viewer")).not.toBeNull();
+    expect(dialog!.querySelector(".hk-image-viewer-img")).not.toBeNull();
+
+    const btn = s.closeButton();
+    expect(btn.getAttribute("aria-label")).toBe("Close");
+  });
+
+  it("renders nothing while closed", () => {
+    const s = mountLightbox(false);
+    expect(s.dialog()).toBeNull();
+  });
+
+  it("the close button emits update:modelValue false", async () => {
+    const s = mountLightbox(true);
+
+    s.closeButton().click();
+    await nextTick();
+
+    expect(s.emitted).toEqual([false]);
+  });
+
+  it("Escape closes via the lightbox's own window listener", async () => {
+    const s = mountLightbox(true);
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await nextTick();
+
+    expect(s.emitted).toEqual([false]);
+  });
+
+  it("the Escape listener is removed once closed (no stray closes)", async () => {
+    const s = mountLightbox(true);
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await nextTick();
+    expect(s.emitted).toEqual([false]);
+
+    // The modelValue watch removed the window listener on close — a
+    // second Escape must not emit another update.
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await nextTick();
+    expect(s.emitted).toEqual([false]);
+  });
+
+  it("names the dialog via surfaceTitle without rendering a header or a dev warning", () => {
+    // The spy must be live before mount: the popup manager warns (DEV
+    // builds) the moment an untitled layer registers.
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const s = mountLightbox(true);
+
+      const dialog = s.dialog();
+      expect(dialog).not.toBeNull();
+      // surfaceTitle names the dialog…
+      expect(dialog!.getAttribute("aria-label")).toBe("Image viewer");
+      // …without conjuring header chrome.
+      expect(dialog!.querySelector(".hk-modal-header")).toBeNull();
+      // …and without tripping the untitled-popup dev warning.
+      expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("popup registered without a title"));
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("unmounting while open removes the window Escape listener", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const open = ref(true);
+    const emitted: boolean[] = [];
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkImageLightbox, {
+            src: "/test-wallpaper.svg",
+            modelValue: open.value,
+            "onUpdate:modelValue": (v: boolean) => { emitted.push(v); open.value = v; },
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-content.hk-image-lightbox")).not.toBeNull();
+
+    // Tear the whole component down while the dialog is open…
+    app.unmount();
+    await nextTick();
+
+    // …a stray Escape must reach nobody.
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await nextTick();
+    expect(emitted).toEqual([]);
+  });
+});