@celestia-island/hikari 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "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,47 @@
+/* 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);
+}
+
+/* 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 instead of a button-level class. Apps with longer labels
+   widen the label column via `--auth-methods-label-width`. */
+.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,65 @@
+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 component itself is a fragment).
+    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");
+  });
+});

package/src/components/HkAuthMethodList.tsx

@@ -0,0 +1,72 @@
+import { defineComponent, type PropType } 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 (CSS var `--auth-methods-label-width`, default 8em), 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.
+ *
+ * Render it through HkAuthCard's `methods` slot: the card owns the
+ * full-width block layout and the vertical rhythm, and the footer's
+ * checkbox rows keep their centered-group behavior instead of being
+ * dragged full width with the buttons.
+ */
+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 }) {
+    return () => (
+      <>
+        {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>
+        ))}
+      </>
+    );
+  },
+});

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([]);
+  });
+});

package/src/components/HkImageLightbox.tsx

@@ -0,0 +1,87 @@
+import { defineComponent, onBeforeUnmount, watch } from "vue";
+
+import { useI18n } from "../i18n/context";
+import "./HkImageLightbox.scss";
+import HIconButton from "./HkIconButton";
+import HImageViewer from "./HkImageViewer";
+import HModal from "./HkModal";
+
+/**
+ * Immersive fullscreen viewer for a single image — the "special modal"
+ * behind HImagePreview's click-to-enlarge. Built entirely from standard
+ * components: HModal (with the `contentClass` escape hatch for the
+ * immersive layout) hosting an HImageViewer plus a floating close button.
+ *
+ * HModal is opened with `closable={false}`, so its own ESC / overlay-click
+ * guards never close it; the lightbox instead owns a window-level Escape
+ * listener for as long as it is open (removed on close/unmount) and emits
+ * `update:modelValue(false)` from there and from the close button.
+ */
+export default defineComponent({
+  name: "HkImageLightbox",
+  props: {
+    src: { type: String, required: true },
+    alt: { type: String, default: "" },
+    modelValue: { type: Boolean, required: true },
+  },
+  emits: {
+    "update:modelValue": (_value: boolean) => true,
+  },
+  setup(props, { emit }) {
+    const { t } = useI18n();
+
+    function close() {
+      emit("update:modelValue", false);
+    }
+
+    function onWindowKeydown(e: KeyboardEvent) {
+      if (e.key === "Escape") close();
+    }
+
+    watch(
+      () => props.modelValue,
+      (open) => {
+        if (open) window.addEventListener("keydown", onWindowKeydown);
+        else window.removeEventListener("keydown", onWindowKeydown);
+      },
+      { immediate: true },
+    );
+
+    onBeforeUnmount(() => {
+      window.removeEventListener("keydown", onWindowKeydown);
+    });
+
+    return () => (
+      <HModal
+        modelValue={props.modelValue}
+        onUpdate:modelValue={(v: boolean) => emit("update:modelValue", v)}
+        contentClass="hk-image-lightbox"
+        // Match the CSS width so the frame's inline max-width does not
+        // clamp it to HModal's 32rem default.
+        width="min(96vw, 80rem)"
+        closable={false}
+        // Header-less chrome-only surface: name the dialog layer (popup
+        // breadcrumb + aria-label) without rendering a header.
+        surfaceTitle={t("hikari::imageLightbox.title", "Image viewer")}
+      >
+        <div class="hk-image-lightbox-stage">
+          <HImageViewer src={props.src} alt={props.alt} />
+          <HIconButton
+            class="hk-image-lightbox-close"
+            size={32}
+            variant="ghost"
+            aria-label={t("hikari::imageLightbox.close", "Close")}
+            onClick={close}
+          >
+            {{ icon: () => (
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+                <line x1="18" y1="6" x2="6" y2="18" />
+                <line x1="6" y1="6" x2="18" y2="18" />
+              </svg>
+            ) }}
+          </HIconButton>
+        </div>
+      </HModal>
+    );
+  },
+});