@celestia-island/hikari 0.55.76 → 0.55.78

package/src/components/HkStatCard.scss

@@ -80,3 +80,110 @@
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+
+/* ── chip variant ──────────────────────────────────────────────────────
+   Horizontal: tone-tinted icon chip, value over label, optional trailing
+   aside (tier badge / delta). The icon chip carries the tone color the
+   same way the plain variant's dot does — tint on the chip only. */
+.hk-stat-card-chip-body {
+  display: flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  min-width: 0;
+}
+
+.hk-stat-card-chip-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--space-28, 1.75rem);
+  height: var(--space-28, 1.75rem);
+  border-radius: var(--radius-sm, 0.375rem);
+  flex-shrink: 0;
+}
+
+.hk-stat-card-chip-icon-success { background: rgb(var(--color-success) / 12%); color: rgb(var(--color-success)); }
+.hk-stat-card-chip-icon-warning { background: rgb(var(--color-warning) / 12%); color: rgb(var(--color-warning)); }
+.hk-stat-card-chip-icon-error { background: rgb(var(--color-error) / 12%); color: rgb(var(--color-error)); }
+.hk-stat-card-chip-icon-info { background: rgb(var(--color-info, rgb(var(--color-primary))) / 12%); color: rgb(var(--color-info, rgb(var(--color-primary)))); }
+.hk-stat-card-chip-icon-primary { background: rgb(var(--color-primary) / 12%); color: rgb(var(--color-primary)); }
+.hk-stat-card-chip-icon-muted { background: rgb(var(--color-muted) / 12%); color: rgb(var(--color-muted)); }
+
+.hk-stat-card-chip-main {
+  min-width: 0;
+}
+
+.hk-stat-card-chip-value {
+  font-size: var(--text-lg, 1.125rem);
+  font-weight: 700;
+  line-height: 1.35;
+  color: rgb(var(--color-text));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-stat-card-chip-label {
+  font-size: var(--text-xs, 0.75rem);
+  color: rgb(var(--color-muted));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-stat-card-aside {
+  margin-left: auto;
+  flex-shrink: 0;
+}
+
+/* ── ring variant ──────────────────────────────────────────────────────
+   Centered utilization ring; the label (with the icon) sits under the
+   ring and the hint becomes the detail line. */
+.hk-stat-card-ring {
+  align-items: center;
+  text-align: center;
+  gap: 0.375rem;
+}
+
+.hk-stat-card-ring-label {
+  display: flex;
+  align-items: center;
+  gap: var(--space-4, 0.25rem);
+  max-width: 100%;
+  font-size: var(--text-xs, 0.75rem);
+  font-weight: 500;
+  color: rgb(var(--color-text));
+}
+
+.hk-stat-card-ring-label-text {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-stat-card-ring-detail {
+  max-width: 100%;
+}
+
+/* ── bar variant ───────────────────────────────────────────────────────
+   Label + value on one row over a tone-colored bar. */
+.hk-stat-card-bar-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--space-8, 0.5rem);
+}
+
+.hk-stat-card-bar-value {
+  font-size: var(--text-sm, 0.875rem);
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+  color: rgb(var(--color-text));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-stat-card-bar-detail {
+  max-width: 100%;
+}

package/src/components/HkStatCard.tsx

@@ -1,46 +1,198 @@
-import { defineComponent, type PropType } from "vue";
+import { defineComponent, h, type Component, type PropType } from "vue";
 
+import HkGaugeRing from "./HkGaugeRing";
+import HkProgressBar from "./HkProgressBar";
 import "./HkStatCard.scss";
 
 export type StatTone = "success" | "warning" | "error" | "info" | "primary" | "muted";
 
+/**
+ * The standard KPI-cell shapes. Every variant shares the card surface
+ * (border, radius, background) and the tone palette; they differ only in
+ * how the number is presented:
+ *
+ * - `plain` — text-forward: label row with a tone dot, big value, optional
+ *   hint (the original anatomy, still the default).
+ * - `chip`  — horizontal: a tone-tinted icon chip beside value + label,
+ *   with an optional trailing `aside` slot (tier badge, delta, …).
+ * - `ring`  — a single utilization ring with the value inside, the label
+ *   (with the icon) underneath, and the hint as the detail line.
+ * - `bar`   — label + value on one row over a tone-colored progress bar,
+ *   with the hint as the detail line.
+ */
+export type StatVariant = "plain" | "chip" | "ring" | "bar";
+
+/**
+ * Tone → theme-variable CSS color (the exact palette the card paints
+ * itself with). Exported so hosts can match sibling chrome — badge
+ * variants, inline rings, legend dots — to the card's tone without
+ * re-declaring the mapping (and drifting from it).
+ */
+export function statToneColor(tone: StatTone): string {
+  switch (tone) {
+    case "success":
+      return "rgb(var(--color-success))";
+    case "warning":
+      return "rgb(var(--color-warning))";
+    case "error":
+      return "rgb(var(--color-error))";
+    case "info":
+      return "rgb(var(--color-info, rgb(var(--color-primary))))";
+    case "primary":
+      return "rgb(var(--color-primary))";
+    case "muted":
+      return "rgb(var(--color-muted))";
+  }
+}
+
+const clampPct = (pct: number | undefined): number =>
+  pct == null ? 0 : Math.min(100, Math.max(0, pct));
+
 /**
  * HkStatCard — one KPI cell for the admin stat grids.
  *
- * Anatomy: label + value + optional hint, with a tone dot carrying the
- * health semantics (the text hue never changes — tone is expressed by
- * the dot alone, matching the interaction-state precedence rules).
+ * Anatomy (plain, the default): label + value + optional hint, with a
+ * tone dot carrying the health semantics (the text hue never changes —
+ * tone is expressed by the dot alone, matching the interaction-state
+ * precedence rules).
  *
  * ```tsx
- * <HStatCard label="Hub health" value="2/2" tone="success" hint="entelecheia / arona" />
+ * <HkStatCard label="Hub health" value="2/2" tone="success" hint="entelecheia / arona" />
+ * <HkStatCard variant="chip" icon={Cpu} tone="info" label="Running" value={3} />
+ * <HkStatCard variant="ring" tone="success" pct={37.5} value="38%" unit="cores"
+ *             icon={Cpu} label="Cores" hint="12 / 32 · monthly" />
+ * <HkStatCard variant="bar" tone="warning" pct={72} label="Storage" value="72%" hint="47 / 65 GB" />
  * ```
  */
 export const HkStatCard = defineComponent({
   name: "HkStatCard",
   props: {
+    variant: { type: String as PropType<StatVariant>, default: "plain" },
     label: { type: String, required: true },
     value: { type: [String, Number], required: true },
     tone: { type: String as PropType<StatTone>, default: "muted" },
     hint: { type: String, default: undefined },
     /** Whole-card click (drill-through to the owning page). */
     clickable: { type: Boolean, default: false },
+    /** chip/ring: leading icon component (lucide-vue-next style). */
+    icon: { type: Object as PropType<Component>, default: undefined },
+    /** ring/bar: gauge percentage, clamped to 0–100. */
+    pct: { type: Number, default: undefined },
+    /** ring: sub-label rendered inside the ring under the value (the unit). */
+    unit: { type: String, default: undefined },
   },
-  emits: { click: (_e: MouseEvent) => true },
-  setup(props, { emit }) {
-    return () => (
-      <div
-        class={["hk-stat-card", props.clickable && "hk-stat-card-clickable"]}
-        role={props.clickable ? "button" : undefined}
-        tabindex={props.clickable ? 0 : undefined}
-        onClick={props.clickable ? (e: MouseEvent) => emit("click", e) : undefined}
-      >
-        <div class="hk-stat-card-head">
-          <span class="hk-stat-card-label">{props.label}</span>
-          <span class={`hk-stat-card-dot hk-stat-card-dot-${props.tone}`} aria-hidden="true" />
+  emits: { click: (_e: MouseEvent | KeyboardEvent) => true },
+  setup(props, { emit, slots }) {
+    return () => {
+      const shared = {
+        class: [
+          "hk-stat-card",
+          `hk-stat-card-${props.variant}`,
+          props.clickable && "hk-stat-card-clickable",
+        ],
+        role: props.clickable ? "button" : undefined,
+        tabindex: props.clickable ? 0 : undefined,
+        onClick: props.clickable ? (e: MouseEvent) => emit("click", e) : undefined,
+        // role="button" promises keyboard activation (Enter/Space) — the
+        // same contract HkContextRing's clickable ring honors. Key events
+        // bubbling from a focusable INSIDE the card (an aside button) are
+        // left alone so they don't double-fire the card's click.
+        onKeydown: props.clickable
+          ? (e: KeyboardEvent) => {
+              if (e.target !== e.currentTarget) return;
+              if (e.key !== "Enter" && e.key !== " ") return;
+              e.preventDefault();
+              emit("click", e);
+            }
+          : undefined,
+      };
+
+      if (props.variant === "chip") {
+        return (
+          <div {...shared}>
+            <div class="hk-stat-card-chip-body">
+              {props.icon && (
+                <span
+                  class={`hk-stat-card-chip-icon hk-stat-card-chip-icon-${props.tone}`}
+                  aria-hidden="true"
+                >
+                  {h(props.icon, { size: 16 })}
+                </span>
+              )}
+              <div class="hk-stat-card-chip-main">
+                <div class="hk-stat-card-chip-value">{props.value}</div>
+                <div class="hk-stat-card-chip-label">{props.label}</div>
+              </div>
+              {slots.aside && <div class="hk-stat-card-aside">{slots.aside()}</div>}
+            </div>
+            {props.hint && <div class="hk-stat-card-hint">{props.hint}</div>}
+          </div>
+        );
+      }
+
+      if (props.variant === "ring") {
+        return (
+          <div {...shared}>
+            <HkGaugeRing
+              size={104}
+              strokeWidth={7}
+              gap={4}
+              animate={false}
+              rings={[
+                {
+                  pct: clampPct(props.pct),
+                  color: statToneColor(props.tone),
+                  trackColor: "rgb(var(--color-text) / 8%)",
+                },
+              ]}
+              centerValue={String(props.value)}
+              centerLabel={props.unit ?? ""}
+            />
+            <div class="hk-stat-card-ring-label">
+              {props.icon && h(props.icon, { size: 13, "aria-hidden": true })}
+              <span class="hk-stat-card-ring-label-text">{props.label}</span>
+            </div>
+            {props.hint && (
+              <div class="hk-stat-card-hint hk-stat-card-ring-detail" title={props.hint}>
+                {props.hint}
+              </div>
+            )}
+          </div>
+        );
+      }
+
+      if (props.variant === "bar") {
+        return (
+          <div {...shared}>
+            <div class="hk-stat-card-bar-head">
+              <span class="hk-stat-card-label">{props.label}</span>
+              <span class="hk-stat-card-bar-value">{props.value}</span>
+            </div>
+            <HkProgressBar
+              max={100}
+              size="xs"
+              segments={[{ value: clampPct(props.pct), color: statToneColor(props.tone) }]}
+            />
+            {props.hint && (
+              <div class="hk-stat-card-hint hk-stat-card-bar-detail" title={props.hint}>
+                {props.hint}
+              </div>
+            )}
+          </div>
+        );
+      }
+
+      // plain — the original anatomy, unchanged.
+      return (
+        <div {...shared}>
+          <div class="hk-stat-card-head">
+            <span class="hk-stat-card-label">{props.label}</span>
+            <span class={`hk-stat-card-dot hk-stat-card-dot-${props.tone}`} aria-hidden="true" />
+          </div>
+          <div class="hk-stat-card-value">{props.value}</div>
+          {props.hint && <div class="hk-stat-card-hint" title={props.hint}>{props.hint}</div>}
         </div>
-        <div class="hk-stat-card-value">{props.value}</div>
-        {props.hint && <div class="hk-stat-card-hint" title={props.hint}>{props.hint}</div>}
-      </div>
-    );
+      );
+    };
   },
 });

package/src/components/HkStatCard.variants.test.tsx

@@ -0,0 +1,210 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, defineComponent, nextTick } from "vue";
+
+import { HkStatCard, statToneColor } from "./HkStatCard";
+
+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();
+  }
+});
+
+/** A stand-in lucide-style icon component (functional, size prop). */
+const FakeIcon = defineComponent({
+  name: "FakeIcon",
+  props: { size: { type: [Number, String], default: 24 } },
+  setup: (props) => () => h("svg", { "data-fake-icon": "", width: props.size, height: props.size }),
+});
+
+describe("HkStatCard plain (default) — the original anatomy is preserved", () => {
+  it("renders the label/dot/value/hint anatomy without a variant class", () => {
+    const c = mount(h(HkStatCard, { label: "Hub health", value: "2/2", tone: "success", hint: "hubs" }));
+    const card = c.querySelector(".hk-stat-card") as HTMLElement;
+    expect(card.className).toContain("hk-stat-card-plain");
+    expect(c.querySelector(".hk-stat-card-head")).toBeTruthy();
+    expect(c.querySelector(".hk-stat-card-dot-success")).toBeTruthy();
+    expect(c.querySelector(".hk-stat-card-value")?.textContent).toBe("2/2");
+    expect(c.querySelector(".hk-stat-card-hint")?.textContent).toBe("hubs");
+    // plain renders no chip/ring/bar anatomy
+    expect(c.querySelector(".hk-stat-card-chip-body")).toBeNull();
+    expect(c.querySelector(".hk-gauge-ring")).toBeNull();
+    expect(c.querySelector(".hk-progress-bar")).toBeNull();
+  });
+});
+
+describe("HkStatCard chip", () => {
+  it("renders the tinted icon chip beside value-over-label", () => {
+    const c = mount(
+      h(HkStatCard, { variant: "chip", icon: FakeIcon, tone: "info", label: "Running", value: 3 }),
+    );
+    const card = c.querySelector(".hk-stat-card") as HTMLElement;
+    expect(card.className).toContain("hk-stat-card-chip");
+    const chip = c.querySelector(".hk-stat-card-chip-icon") as HTMLElement;
+    expect(chip).toBeTruthy();
+    expect(chip.className).toContain("hk-stat-card-chip-icon-info");
+    expect(chip.querySelector("svg[data-fake-icon]")).toBeTruthy();
+    expect(c.querySelector(".hk-stat-card-chip-value")?.textContent).toBe("3");
+    expect(c.querySelector(".hk-stat-card-chip-label")?.textContent).toBe("Running");
+    // no tone dot on the chip variant — the chip itself carries the tone
+    expect(c.querySelector(".hk-stat-card-dot")).toBeNull();
+  });
+
+  it("omits the icon chip node when no icon is given", () => {
+    const c = mount(h(HkStatCard, { variant: "chip", label: "L", value: 1 }));
+    expect(c.querySelector(".hk-stat-card-chip-icon")).toBeNull();
+  });
+
+  it("renders the aside slot at the trailing edge", () => {
+    const c = mount(
+      h(HkStatCard, { variant: "chip", label: "Balance", value: 20 }, { aside: () => h("span", { class: "aside-probe" }, "basic") }),
+    );
+    expect(c.querySelector(".hk-stat-card-aside .aside-probe")?.textContent).toBe("basic");
+  });
+
+  it("keeps the whole-card click affordance", () => {
+    const c = mount(h(HkStatCard, { variant: "chip", label: "L", value: 1, clickable: true }));
+    const el = c.querySelector(".hk-stat-card") as HTMLElement;
+    expect(el.getAttribute("role")).toBe("button");
+    expect(el.className).toContain("hk-stat-card-clickable");
+  });
+});
+
+describe("HkStatCard ring", () => {
+  it("renders one tone-colored ring with the value and unit inside", () => {
+    const c = mount(
+      h(HkStatCard, {
+        variant: "ring", tone: "success", pct: 37.5, value: "38%", unit: "cores",
+        icon: FakeIcon, label: "Cores", hint: "12 / 32 · monthly",
+      }),
+    );
+    const card = c.querySelector(".hk-stat-card") as HTMLElement;
+    expect(card.className).toContain("hk-stat-card-ring");
+    // exactly one ring block, painted with the tone palette
+    expect(c.querySelectorAll(".hk-gauge-ring").length).toBe(1);
+    expect(c.querySelector(".hk-gauge-ring-value")?.textContent).toBe("38%");
+    expect(c.querySelector(".hk-gauge-ring-label")?.textContent).toBe("cores");
+    expect(c.querySelector(".hk-stat-card-ring-label-text")?.textContent).toBe("Cores");
+    expect(c.querySelector(".hk-stat-card-ring-label svg[data-fake-icon]")).toBeTruthy();
+    expect(c.querySelector(".hk-stat-card-ring-detail")?.textContent).toBe("12 / 32 · monthly");
+  });
+
+  it("clamps an over-range pct to a full gauge", () => {
+    const c = mount(h(HkStatCard, { variant: "ring", pct: 140, value: "140%", label: "L" }));
+    // The dash offset must reflect a clamped 100% fill, not an overshoot:
+    // a clamped ring draws dashoffset 0.
+    const arc = c.querySelector(".hk-gauge-ring circle[stroke-dasharray]") as SVGElement;
+    expect(arc).toBeTruthy();
+    expect(arc.getAttribute("stroke-dashoffset")).toBe("0");
+  });
+
+  it("clamps a negative pct to an empty gauge (the guard HkGaugeRing does not provide)", () => {
+    // HkGaugeRing only clamps the UPPER bound internally (Math.min(pct, 100)),
+    // so a negative pct surviving this component would draw dashoffset
+    // > circumference — an arc longer than the whole ring. This assertion is
+    // what kills a mutation that drops clampPct's lower clamp.
+    const c = mount(h(HkStatCard, { variant: "ring", pct: -20, value: "-20%", label: "L" }));
+    const arc = c.querySelector(".hk-gauge-ring circle[stroke-dasharray]") as SVGElement;
+    expect(arc).toBeTruthy();
+    const circumference = 2 * Math.PI * ((104 - 7) / 2);
+    const offset = Number(arc.getAttribute("stroke-dashoffset"));
+    expect(Math.abs(offset - circumference)).toBeLessThan(0.01);
+  });
+
+  it("treats a missing pct as an empty gauge, not NaN", () => {
+    const c = mount(h(HkStatCard, { variant: "ring", value: "—", label: "L" }));
+    const arc = c.querySelector(".hk-gauge-ring circle[stroke-dasharray]") as SVGElement;
+    expect(arc.getAttribute("stroke-dashoffset")).not.toContain("NaN");
+  });
+
+  it("paints the ring through inline stroke styles, not only the presentation attribute", () => {
+    // var() in an SVG presentation attribute is not substituted on every
+    // engine (Firefox drops the declaration → stroke:none → an invisible
+    // gauge), so the tone color must ALSO ride the inline style — the same
+    // contract HkProgressRing documents for its segment color.
+    const c = mount(
+      h(HkStatCard, { variant: "ring", tone: "info", pct: 40, value: "40%", label: "L" }),
+    );
+    const [track, arc] = c.querySelectorAll(".hk-gauge-ring circle") as NodeListOf<SVGCircleElement>;
+    expect(track.getAttribute("stroke")).toBe("rgb(var(--color-text) / 8%)");
+    expect(track.style.stroke).toBe("rgb(var(--color-text) / 8%)");
+    expect(arc.getAttribute("stroke")).toBe(statToneColor("info"));
+    expect(arc.style.stroke).toBe(statToneColor("info"));
+  });
+});
+
+describe("HkStatCard clickable — role=button keyboard contract", () => {
+  it("activates on Enter and Space like a native button", async () => {
+    const clicks: string[] = [];
+    const c = mount(
+      h(HkStatCard, {
+        variant: "chip", value: 1, label: "L", clickable: true,
+        onClick: (e: MouseEvent | KeyboardEvent) => clicks.push("key" in e ? e.key : "mouse"),
+      }),
+    );
+    const card = c.querySelector(".hk-stat-card") as HTMLElement;
+    for (const key of ["Enter", " "]) {
+      card.dispatchEvent(
+        new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }),
+      );
+      await nextTick();
+    }
+    expect(clicks).toEqual(["Enter", " "]);
+  });
+
+  it("ignores keys bubbling from a focusable inside the card", async () => {
+    const clicks: unknown[] = [];
+    const c = mount(
+      h(HkStatCard, { variant: "chip", value: 1, label: "L", clickable: true, onClick: () => clicks.push(1) }, {
+        aside: () => h("button", { class: "aside-btn-probe" }, "x"),
+      }),
+    );
+    const inner = c.querySelector(".aside-btn-probe") as HTMLElement;
+    inner.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }),
+    );
+    await nextTick();
+    expect(clicks.length).toBe(0);
+  });
+});
+
+describe("HkStatCard bar", () => {
+  it("renders label+value over a tone-colored segmented fill", () => {
+    const c = mount(
+      h(HkStatCard, { variant: "bar", tone: "warning", pct: 72, label: "Storage", value: "72%", hint: "47 / 65 GB" }),
+    );
+    const card = c.querySelector(".hk-stat-card") as HTMLElement;
+    expect(card.className).toContain("hk-stat-card-bar");
+    expect(c.querySelector(".hk-stat-card-bar-head .hk-stat-card-label")?.textContent).toBe("Storage");
+    expect(c.querySelector(".hk-stat-card-bar-value")?.textContent).toBe("72%");
+    const seg = c.querySelector(".hk-progress-bar-seg") as HTMLElement;
+    expect(seg).toBeTruthy();
+    expect(seg.style.width).toBe("72%");
+    expect(seg.style.background).toBe("rgb(var(--color-warning))");
+    expect(c.querySelector(".hk-stat-card-bar-detail")?.textContent).toBe("47 / 65 GB");
+  });
+});
+
+describe("statToneColor", () => {
+  it("maps every tone to the theme-variable palette the card paints with", () => {
+    expect(statToneColor("success")).toBe("rgb(var(--color-success))");
+    expect(statToneColor("warning")).toBe("rgb(var(--color-warning))");
+    expect(statToneColor("error")).toBe("rgb(var(--color-error))");
+    expect(statToneColor("primary")).toBe("rgb(var(--color-primary))");
+    expect(statToneColor("muted")).toBe("rgb(var(--color-muted))");
+    // info falls back to primary when the host palette omits it — the
+    // same fallback the SCSS dot uses.
+    expect(statToneColor("info")).toBe("rgb(var(--color-info, rgb(var(--color-primary))))");
+  });
+});