@celestia-island/hikari 0.38.2 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.38.2",
+  "version": "0.39.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

@@ -2,6 +2,7 @@
 // house rule: no SFCs in the tree). Render-only showcase of every exported
 // component; state is local and throwaway.
 import { computed, defineComponent, ref } from "vue";
+import { PackageOpen } from "lucide-vue-next";
 import { HIKARI_FONT_MONO } from "./theme/fontContext";
 import {
   HButton, HIconButton, HTooltip, HBadge, HTag, HIcon, HSpinner,
@@ -360,11 +361,30 @@ export default defineComponent({
 
         <section>
           <h2>HEmptyState</h2>
-          <HEmptyState
-            title="No items"
-            description="Nothing to show here yet."
-            v-slots={{ icon: () => <HIcon name="inbox" size={48} /> }}
-          />
+          <div class="col">
+            <HEmptyState
+              title="No items"
+              description="Nothing to show here yet."
+              v-slots={{ action: () => <HButton size="sm">Create item</HButton> }}
+            />
+            <HEmptyState
+              title="Nothing found"
+              description="Search returned no matches — try a different query."
+              icon={PackageOpen}
+            />
+            <HEmptyState
+              title="Custom icon slot"
+              v-slots={{ icon: () => <HIcon name="inbox" size={48} /> }}
+            />
+            <HEmptyState loading />
+            <div style="height:220px">
+              <HEmptyState
+                title="Panel empty"
+                description={'fit="fill" stretches the card to its host container.'}
+                fit="fill"
+              />
+            </div>
+          </div>
         </section>
 
         <section>

package/src/components/HkEmptyState.scss

@@ -9,6 +9,7 @@
   backdrop-filter: blur(8px);
   border: 1px solid var(--hi-color-border, rgba(0, 0, 0, 0.06));
   border-radius: var(--hi-radius-md, 0.5rem);
+  box-sizing: border-box;
 }
 
 .hk-empty-icon {
@@ -40,3 +41,44 @@
 .hk-empty-action {
   margin-top: var(--hi-space-4, 0.25rem);
 }
+
+/* fit="page" (default): full width on mobile — the page supplies the outer
+   padding — and centered. */
+.hk-empty-state--page {
+  width: 100%;
+  margin-inline: auto;
+}
+
+/* Desktop: the card must not span the page — cap around 30vw with a sane
+   floor/cap (320px … 560px) so tiny and 4K windows stay usable. */
+@media (min-width: 48rem) {
+  .hk-empty-state--page {
+    max-width: clamp(20rem, 30vw, 35rem);
+  }
+}
+
+/* fit="fill": stretch to the host container (panels, split views). */
+.hk-empty-state--fill {
+  width: 100%;
+  height: 100%;
+  min-height: 100%;
+}
+
+/* Loading variant keeps a comfortable spinner area in short hosts. */
+.hk-empty-state--loading {
+  min-height: 10rem;
+}
+
+/* Visually hidden but announced: gives the loading status region text
+   content so screen readers have something to say when it appears. */
+.hk-empty-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/components/HkEmptyState.test.tsx

@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkEmptyState from "./HkEmptyState";
+
+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();
+  }
+});
+
+/* Functional icon stub rendering a node with a distinguishing class so the
+   tests can assert the icon prop component actually mounted. */
+const StubIcon = defineComponent({
+  name: "StubIcon",
+  setup() {
+    return () => h("i", { class: "stub-empty-icon", "data-stub-icon": "true" });
+  },
+});
+
+describe("HkEmptyState", () => {
+  it("renders title and description", () => {
+    const c = mount(
+      h(HkEmptyState, { title: "No items", description: "Nothing here yet." }),
+    );
+    expect((c.querySelector(".hk-empty-title") as HTMLElement).textContent).toBe(
+      "No items",
+    );
+    expect((c.querySelector(".hk-empty-desc") as HTMLElement).textContent).toBe(
+      "Nothing here yet.",
+    );
+  });
+
+  it("renders action slot content inside .hk-empty-action", () => {
+    const c = mount(
+      h(
+        HkEmptyState,
+        { title: "No items" },
+        { action: () => h("button", { class: "stub-action" }, "Retry") },
+      ),
+    );
+    const btn = c.querySelector(".hk-empty-action .stub-action") as HTMLElement;
+    expect(btn).not.toBeNull();
+    expect(btn.textContent).toBe("Retry");
+  });
+
+  it("renders the icon prop component in the icon well", () => {
+    const c = mount(h(HkEmptyState, { title: "No items", icon: StubIcon }));
+    expect(c.querySelector(".hk-empty-icon .stub-empty-icon")).not.toBeNull();
+    // The prop icon replaces the default inline inbox svg.
+    expect(c.querySelector(".hk-empty-icon svg polyline")).toBeNull();
+  });
+
+  it("prefers the icon slot over the icon prop", () => {
+    const c = mount(
+      h(
+        HkEmptyState,
+        { title: "No items", icon: StubIcon },
+        { icon: () => h("b", { class: "slot-icon" }) },
+      ),
+    );
+    expect(c.querySelector(".hk-empty-icon .slot-icon")).not.toBeNull();
+    expect(c.querySelector(".stub-empty-icon")).toBeNull();
+  });
+
+  it("renders the default inline svg when no icon prop and no slot", () => {
+    const c = mount(h(HkEmptyState, { title: "No items" }));
+    expect(c.querySelector(".hk-empty-icon svg polyline")).not.toBeNull();
+  });
+
+  it("loading variant renders only a spinner with status semantics", () => {
+    const c = mount(
+      h(
+        HkEmptyState,
+        { title: "No items", description: "desc", loading: true },
+        { action: () => h("button", "x") },
+      ),
+    );
+    const root = c.querySelector(".hk-empty-state") as HTMLElement;
+    expect(root.className).toContain("hk-empty-state--loading");
+    expect(root.getAttribute("role")).toBe("status");
+    expect(root.getAttribute("aria-busy")).toBe("true");
+    expect(c.querySelector(".hk-spinner")).not.toBeNull();
+    // The status region must carry text content for screen readers.
+    const sr = c.querySelector(".hk-empty-sr-only");
+    expect(sr).not.toBeNull();
+    expect((sr as HTMLElement).textContent).toBe("Loading");
+    expect(c.querySelector(".hk-empty-title")).toBeNull();
+    expect(c.querySelector(".hk-empty-desc")).toBeNull();
+    expect(c.querySelector(".hk-empty-action")).toBeNull();
+  });
+
+  it("defaults to the page fit modifier", () => {
+    const c = mount(h(HkEmptyState, { title: "x" }));
+    const cls = (c.querySelector(".hk-empty-state") as HTMLElement).className;
+    expect(cls).toContain("hk-empty-state--page");
+    expect(cls).not.toContain("hk-empty-state--fill");
+  });
+
+  it("maps fit=fill to the fill modifier", () => {
+    const c = mount(h(HkEmptyState, { title: "x", fit: "fill" }));
+    const cls = (c.querySelector(".hk-empty-state") as HTMLElement).className;
+    expect(cls).toContain("hk-empty-state--fill");
+    expect(cls).not.toContain("hk-empty-state--page");
+  });
+});

package/src/components/HkEmptyState.tsx

@@ -1,40 +1,78 @@
-import { defineComponent } from "vue";
+import { defineComponent, h, type Component, type PropType } from "vue";
 
+import { useI18n } from "../i18n/context";
+import HSpinner from "./HkSpinner";
 import "./HkEmptyState.scss";
 
 export default defineComponent({
   name: "HkEmptyState",
   props: {
-    title: { type: String, required: true },
+    /** Heading text. Optional — the loading variant renders without a title. */
+    title: { type: String, default: undefined },
     description: { type: String, default: undefined },
+    /** Icon component (lucide-vue-next style); rendered via h() at size 32. */
+    icon: { type: Object as PropType<Component>, default: undefined },
+    /** Loading variant: only a centered spinner, exposed as a status region. */
+    loading: { type: Boolean, default: false },
+    /** page = bounded, centered card on desktop; fill = stretch to the host. */
+    fit: {
+      type: String as PropType<"page" | "fill">,
+      default: "page",
+    },
   },
   setup(props, { slots }) {
+    const { t } = useI18n();
     return () => (
-      <div class="hk-empty-state">
-        <div class="hk-empty-icon">
-          {slots.icon ? (
-            slots.icon()
-          ) : (
-            <svg
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              stroke-width="1.5"
-              stroke-linecap="round"
-              stroke-linejoin="round"
-              width="48"
-              height="48"
-            >
-              <polyline points="22 12 16 12 14 15 10 15 8 12 2 12" />
-              <path d="M5.45 5.11L2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
-            </svg>
-          )}
-        </div>
-        <p class="hk-empty-title">{props.title}</p>
-        {props.description ? (
-          <p class="hk-empty-desc">{props.description}</p>
-        ) : null}
-        <div class="hk-empty-action">{slots.action?.()}</div>
+      <div
+        class={[
+          "hk-empty-state",
+          props.fit === "fill" ? "hk-empty-state--fill" : "hk-empty-state--page",
+          props.loading && "hk-empty-state--loading",
+        ]}
+        role={props.loading ? "status" : undefined}
+        aria-busy={props.loading ? "true" : undefined}
+      >
+        {props.loading ? (
+          <>
+            {/* The status region needs text content, or screen readers
+                announce an empty live region when the spinner appears. */}
+            <span class="hk-empty-sr-only">
+              {t("hikari::emptyState.loading", "Loading")}
+            </span>
+            <HSpinner center />
+          </>
+        ) : (
+          <>
+            <div class="hk-empty-icon">
+              {slots.icon ? (
+                slots.icon()
+              ) : props.icon ? (
+                h(props.icon, { size: 32, "aria-hidden": true })
+              ) : (
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="1.5"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                  width="48"
+                  height="48"
+                >
+                  <polyline points="22 12 16 12 14 15 10 15 8 12 2 12" />
+                  <path d="M5.45 5.11L2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
+                </svg>
+              )}
+            </div>
+            {props.title ? <p class="hk-empty-title">{props.title}</p> : null}
+            {props.description ? (
+              <p class="hk-empty-desc">{props.description}</p>
+            ) : null}
+          </>
+        )}
+        {!props.loading && (
+          <div class="hk-empty-action">{slots.action?.()}</div>
+        )}
       </div>
     );
   },