@celestia-island/hikari 0.55.44 → 0.55.45

package/package.json

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

package/src/animation/registerAnimations.ts

@@ -106,6 +106,8 @@ registerCssAnimation("hk-placeholder-marquee-scroll", { infinite: true });
 // styles/admin-tokens.scss — admin header emergency-stop chip while
 // engaged (loops forever).
 registerCssAnimation("s-admin-header-emergency-pulse", { infinite: true });
+registerCssAnimation("hk-loading-veil-in");
+registerCssAnimation("hk-loading-veil-spin", { infinite: true });
 // The styles/theme/mixins.scss ambient/glow/entrance keyframes were
 // retired with the legacy Gen-1 sheet vendoring (hikari #476) — their
 // registrar entries went with them.

package/src/components/HkLoadingVeil.scss

@@ -0,0 +1,64 @@
+// HkLoadingVeil — fullscreen semi-transparent blocking overlay.
+// The z-index sits above the toast band (--hk-z-toast) so the veil is
+// the topmost painted surface while active; pointer-events: all on the
+// root swallows every interaction beneath (the blocking contract).
+.hk-loading-veil {
+  position: fixed;
+  inset: 0;
+  z-index: calc(var(--hk-z-toast, 4000) + 100);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  // Semi-transparent backdrop with a slight blur: the page beneath
+  // stays readable (orientation) but clearly inactive.
+  background: rgb(var(--color-background, 214 236 240) / 0.55);
+  backdrop-filter: blur(6px);
+  -webkit-backdrop-filter: blur(6px);
+  pointer-events: all;
+  animation: hk-loading-veil-in 150ms ease-out;
+
+  // Both light and dark themes ride the --color-background token.
+}
+
+.hk-loading-veil-body {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  padding: 24px 32px;
+  border-radius: 12px;
+  background: rgb(var(--color-surface, 240 244 248) / 0.85);
+  box-shadow: 0 8px 32px rgb(0 0 0 / 0.12);
+}
+
+.hk-loading-veil-spinner {
+  display: inline-block;
+  width: 28px;
+  height: 28px;
+  border: 3px solid rgb(var(--color-border, 100 100 100) / 0.4);
+  border-top-color: rgb(var(--color-primary, 122 162 247));
+  border-radius: 50%;
+  animation: hk-loading-veil-spin 0.8s linear infinite;
+}
+
+.hk-loading-veil-label {
+  margin: 0;
+  font-size: 0.875rem;
+  color: rgb(var(--color-text, 30 30 30));
+  text-align: center;
+}
+
+@keyframes hk-loading-veil-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes hk-loading-veil-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}

package/src/components/HkLoadingVeil.test.tsx

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkLoadingVeil from "./HkLoadingVeil";
+
+/**
+ * HkLoadingVeil contract tests:
+ * - nothing renders while inactive (zero DOM footprint)
+ * - active paints the veil root, the spinner, and the label
+ * - no label prop → no label node (spinner-only)
+ * - reactive: active toggles appearance/disappearance
+ * - the root carries role=status / aria-live=polite / the label as
+ *   aria-label (screen readers announce the blocking state)
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils dependency.)
+ */
+
+const mounts: Array<() => void> = [];
+
+function mountVeil(props: { active?: boolean; label?: string } = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const active = ref(props.active ?? false);
+  const app = createApp({
+    setup() {
+      return () =>
+        h(HkLoadingVeil, {
+          active: active.value,
+          label: props.label ?? "",
+        });
+    },
+  });
+  app.mount(container);
+  mounts.push(() => {
+    app.unmount();
+    container.remove();
+  });
+  return { active, container };
+}
+
+afterEach(() => {
+  while (mounts.length) mounts.pop()?.();
+});
+
+describe("HkLoadingVeil", () => {
+  it("renders nothing while inactive", async () => {
+    const { container } = mountVeil({ active: false });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).toBeNull();
+  });
+
+  it("renders the veil, spinner and label while active", async () => {
+    const { container } = mountVeil({ active: true, label: "Opening…" });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).not.toBeNull();
+    expect(container.querySelector(".hk-loading-veil-spinner")).not.toBeNull();
+    const label = container.querySelector(".hk-loading-veil-label");
+    expect(label?.textContent).toBe("Opening…");
+  });
+
+  it("omits the label node when no label is given", async () => {
+    const { container } = mountVeil({ active: true });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil-spinner")).not.toBeNull();
+    expect(container.querySelector(".hk-loading-veil-label")).toBeNull();
+  });
+
+  it("appears and disappears reactively with the active prop", async () => {
+    const { active, container } = mountVeil({ active: false });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).toBeNull();
+    active.value = true;
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).not.toBeNull();
+    active.value = false;
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).toBeNull();
+  });
+
+  it("carries role=status and the label as aria-label", async () => {
+    const { container } = mountVeil({ active: true, label: "Loading backend" });
+    await nextTick();
+    const root = container.querySelector(".hk-loading-veil");
+    expect(root?.getAttribute("role")).toBe("status");
+    expect(root?.getAttribute("aria-label")).toBe("Loading backend");
+    expect(root?.getAttribute("aria-live")).toBe("polite");
+  });
+});

package/src/components/HkLoadingVeil.tsx

@@ -0,0 +1,41 @@
+/**
+ * HkLoadingVeil — a fullscreen semi-transparent blocking overlay for
+ * navigation-span loading (the "one tap, no dead window" pattern).
+ *
+ * While `active`, the veil paints above everything (z-index above the
+ * toast band): a dimmed backdrop with backdrop-blur, a centered spinner
+ * and a one-line label, and it swallows ALL pointer events — the user
+ * cannot double-tap, scroll, or interact with anything beneath. When
+ * `active` turns false the veil fades out (150 ms) and pointer events
+ * return.
+ *
+ * Use it when a click must IMMEDIATELY show progress across a lazy
+ * boundary (the frontend→backend console jump): the toast band is
+ * top-right and non-blocking — callers that need true blocking (one
+ * click, fullscreen feedback, zero interaction until ready) mount this
+ * instead. It is NOT a modal: no scroll lock, no focus trap, no
+ * Esc-close — the caller's flight owns the lifetime.
+ */
+import { defineComponent } from "vue";
+import "./HkLoadingVeil.scss";
+
+export default defineComponent({
+  name: "HkLoadingVeil",
+  props: {
+    /** Paint + block while true; fade out on false. */
+    active: { type: Boolean, default: false },
+    /** One-line label under the spinner (already-localized by caller). */
+    label: { type: String, default: "" },
+  },
+  setup(props) {
+    return () =>
+      props.active ? (
+        <div class="hk-loading-veil" role="status" aria-live="polite" aria-label={props.label || "loading"}>
+          <div class="hk-loading-veil-body">
+            <span class="hk-loading-veil-spinner" aria-hidden="true" />
+            {props.label ? <p class="hk-loading-veil-label">{props.label}</p> : null}
+          </div>
+        </div>
+      ) : null;
+  },
+});

package/src/index.ts

@@ -80,6 +80,7 @@ export { default as HRadio } from "./components/HkRadio";
 export { default as HScrollContainer } from "./components/HkScrollContainer";
 export { default as HSearchInput } from "./components/HkSearchInput";
 export { default as HSplash } from "./components/HkSplash";
+export { default as HkLoadingVeil } from "./components/HkLoadingVeil";
 export { default as HSelect } from "./components/HkSelect";
 export { default as HSelectPanel, type SelectPanelPlacement } from "./components/HkSelectPanel";
 export { default as HSidebar } from "./components/HkSidebar";