@celestia-island/hikari 0.55.81 → 0.55.83

package/package.json

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

package/src/components/HkAdminTablePage.test.tsx

@@ -83,6 +83,31 @@ describe("HkAdminTablePage", () => {
     expect(c.querySelector(".probe-retry")).toBeTruthy();
   });
 
+  it("renders the body slot instead of the table card when provided", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "T", rows: [{ name: "a" }], columns: COLS,
+      }, {
+        body: () => h("div", { class: "probe-roster" }, "card-list rows"),
+      }),
+    );
+    expect(c.querySelector(".hk-admin-table-page-body .probe-roster")?.textContent).toBe("card-list rows");
+    // the default table path is fully replaced
+    expect(c.querySelector("table")).toBeNull();
+    // header/empty scaffolding still applies around the body
+    expect(c.querySelector(".hk-page-header-title-text")?.textContent).toBe("T");
+  });
+
+  it("suppresses the stale banner when a hard error replaces the body", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "T", staleError: "stale", error: "hard", rows: [], columns: COLS,
+      }),
+    );
+    expect(c.textContent).toContain("hard");
+    expect(c.textContent).not.toContain("stale");
+  });
+
   it("shows the spinner while loading with no rows yet", () => {
     const c = mount(
       h(HkAdminTablePage, { title: "T", loading: true, rows: [], columns: COLS }),

package/src/components/HkAdminTablePage.tsx

@@ -17,6 +17,9 @@ export interface HTableColumn {
  * spinner + error alert + empty state + HTable. Slots:
  * - `actions`      — header actions (e.g. a "Create" button)
  * - `filter`       — filter chrome (HkFilterBar) between header and table
+ * - `body`         — replaces the default HTable card wholesale (card-list
+ *                    rosters, multi-table compounds); loading/error/empty
+ *                    states still come from the scaffold
  * - `cell-<key>`   — per-column cell templates, forwarded to HTable
  * - `empty-action` — action inside the empty state (Retry, …)
  * - `create-modal` — create dialog, rendered after the table
@@ -72,7 +75,11 @@ export const HkAdminTablePage = defineComponent({
           ) : null}
           {slots.filter ? <div class="hk-admin-table-page-filter">{slots.filter()}</div> : null}
 
-          {props.staleError ? <HAlert message={props.staleError} /> : null}
+          {/* A hard error wins the whole body; the stale banner only rides
+           *  above rows that survived a failed refresh, so it must never
+           *  render alongside the error branch (its precondition — rows on
+           *  screen — is exactly what the error branch removes). */}
+          {props.staleError && !props.error ? <HAlert message={props.staleError} /> : null}
           {props.error ? (
             <HAlert message={props.error} />
           ) : props.loading && !props.rows.length ? (
@@ -85,6 +92,8 @@ export const HkAdminTablePage = defineComponent({
             >
               {emptySlots}
             </HEmptyState>
+          ) : slots.body ? (
+            <div class="hk-admin-table-page-body">{slots.body()}</div>
           ) : (
             <HCard padded={false}>
               <HTable columns={props.columns} rows={props.rows} rowKey={props.rowKey}>

package/src/components/HkAffixPicker.test.tsx

@@ -1,5 +1,8 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, h, nextTick } from "vue";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 import HkAffixPicker, { type HkAffixOption } from "./HkAffixPicker";
 
@@ -474,3 +477,20 @@ describe("HkAffixPicker", () => {
     expect(document.querySelector(".hk-affix-list .hk-scrollbar-track")).toBeNull();
   });
 });
+
+describe("affix side → popup placement contract", () => {
+  it("anchors side=suffix popups to the bottom-end edge", () => {
+    // The suffix side hosts unit pickers (e.g. KiB/MiB/GiB chips on a
+    // number field — shittim-chest quota editor): the popup must anchor
+    // to the END edge so it opens toward the viewport instead of off
+    // the field's right edge. The mapping is one expression in the
+    // component; this source contract pins it against silent edits.
+    const src = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "HkAffixPicker.tsx"),
+      "utf-8",
+    );
+    expect(src).toContain(
+      'props.side === "suffix" ? "bottom-end" : "bottom-start"',
+    );
+  });
+});

package/src/components/HkNumberInput.affix.test.ts

@@ -149,3 +149,36 @@ describe("HkNumberInput affix contract", () => {
     expect(label?.textContent).toBe("轮播间隔");
   });
 });
+
+describe("HkNumberInput suffix slot interactivity — the affix-picker host contract", () => {
+  it("delivers clicks on interactive suffix content (the unit-picker chip)", () => {
+    // The "unit picker" composition (an affix chip riding the suffix
+    // slot — e.g. HkAffixPicker side="suffix" for KiB/MiB/GiB in the
+    // quota editor) mounts a BUTTON inside the suffix span. The span is
+    // a plain flex item. This pins the event WIRING (a listener inside
+    // the suffix slot fires) — synthetic dispatch bypasses CSS
+    // hit-testing, so the pointer-events half of that guarantee lives
+    // in the SCSS source contract below (R1 observation).
+    let clicks = 0;
+    const { container } = mountNumberInput({
+      slots: {
+        suffix: () =>
+          h("button", { class: "suffix-chip-probe", onClick: () => clicks++ }, "MiB"),
+      },
+    });
+    const chip = query(container, ".hk-number-input-suffix .suffix-chip-probe") as HTMLElement;
+    expect(chip, "chip button inside the suffix span must render").not.toBeNull();
+    chip.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    expect(clicks).toBe(1);
+  });
+
+  it("keeps pointer-events off the affix spans themselves (SCSS contract)", () => {
+    // Only the wrapper's `-disabled` state may set pointer-events:none —
+    // the same rule the wrapper uses to disable the whole field. A none
+    // on the affix spans would deaden interactive suffix content while
+    // the field looked enabled.
+    const affixRule =
+      scss.match(/\.hk-number-input-prefix,\s*\.hk-number-input-suffix\s*{[^}]*}/)?.[0] ?? "";
+    expect(affixRule, "affix rule must exist").not.toContain("pointer-events: none");
+  });
+});

package/src/components/HkStatCard.scss

@@ -197,3 +197,50 @@
   gap: var(--space-8, 0.5rem);
   max-width: 100%;
 }
+
+/* ── foot row — the `action` slot's corner anchor ──────────────────────
+   When a card hosts the `action` slot, the hint line is wrapped in a
+   relative foot row and the action content is pinned to the row's
+   trailing edge — the card's bottom-right corner (the per-card "⋯"
+   affordance). Clicks stop at the wrapper (the TSX stops propagation),
+   so an action button never double-fires a clickable card's click. */
+.hk-stat-card-foot {
+  position: relative;
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  max-width: 100%;
+}
+
+/* The ring variant centers its detail line — keep the hint visually
+   centered while the action hugs the trailing edge. The card centers
+   its children (align-items:center), which would leave the foot row
+   fit-content-wide and BOTH of those goals dead: the centering would
+   have nothing to center and the absolutely-positioned action would
+   anchor to the hint's edge instead of the card's corner — so the foot
+   explicitly stretches back to the full card width (R2). */
+.hk-stat-card-ring .hk-stat-card-foot {
+  align-self: stretch;
+  justify-content: center;
+}
+
+/* Reserve the corner: a min-height keeps an action-only foot (no hint)
+   from collapsing onto the content above, and the hint truncates before
+   it can slide under the affordance. */
+.hk-stat-card-foot[data-has-action] {
+  min-height: 1.5rem;
+}
+
+.hk-stat-card-foot[data-has-action] .hk-stat-card-hint {
+  padding-inline-end: 1.75rem;
+}
+
+.hk-stat-card-action {
+  position: absolute;
+  inset-inline-end: calc(-1 * var(--space-4, 0.25rem));
+  top: 50%;
+  transform: translateY(-50%);
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}

package/src/components/HkStatCard.tsx

@@ -15,12 +15,20 @@ export type StatTone = "success" | "warning" | "error" | "info" | "primary" | "m
  *   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, …).
- *   Every variant also takes a `footer` slot — a free-form content row
- *   under the value/hint for badge rows and deltas.
  * - `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.
+ *
+ * Every variant also takes a `footer` slot — a free-form content row
+ * under the value/hint for badge rows and deltas — and an `action`
+ * slot: a corner affordance
+ * (typically an icon button) pinned to the trailing edge of the hint
+ * line — the card's bottom-right corner. Hosts use it for per-card
+ * controls ("⋯" customization buttons) that must live on the KPI cell
+ * itself. Clicks inside the action wrapper stop at the wrapper, so an
+ * action button never double-fires a `clickable` card's click. Without
+ * the slot the hint renders exactly as before (no wrapper node).
  */
 export type StatVariant = "plain" | "chip" | "ring" | "bar";
 
@@ -109,6 +117,35 @@ export const HkStatCard = defineComponent({
           : undefined,
       };
 
+      // The hint line, optionally hosting the `action` slot at the foot
+      // row's trailing edge (the card's bottom-right corner). WITHOUT an
+      // action slot the hint renders exactly as before — the foot wrapper
+      // exists only when a corner affordance needs the anchor, and each
+      // variant keeps its pre-slot attributes (the chip variant's hint
+      // never carried a title — R1), so hosts not using the slot see a
+      // byte-identical DOM.
+      const renderHint = (detailClass?: string, titled = true) => {
+        const hintEl = props.hint && (
+          <div
+            class={detailClass ? ["hk-stat-card-hint", detailClass] : "hk-stat-card-hint"}
+            title={titled ? props.hint : undefined}
+          >
+            {props.hint}
+          </div>
+        );
+        if (!slots.action) return hintEl;
+        return (
+          <div class="hk-stat-card-foot" data-has-action="">
+            {hintEl}
+            {/* The corner affordance stops clicks here: an action button
+                must never double-fire a clickable card's click. */}
+            <div class="hk-stat-card-action" onClick={(e: MouseEvent) => e.stopPropagation()}>
+              {slots.action()}
+            </div>
+          </div>
+        );
+      };
+
       if (props.variant === "chip") {
         return (
           <div {...shared}>
@@ -127,7 +164,7 @@ export const HkStatCard = defineComponent({
               </div>
               {slots.aside && <div class="hk-stat-card-aside">{slots.aside()}</div>}
             </div>
-            {props.hint && <div class="hk-stat-card-hint">{props.hint}</div>}
+            {renderHint(undefined, false)}
             {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
           </div>
         );
@@ -155,11 +192,7 @@ export const HkStatCard = defineComponent({
               {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>
-            )}
+            {renderHint("hk-stat-card-ring-detail")}
             {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
           </div>
         );
@@ -177,11 +210,7 @@ export const HkStatCard = defineComponent({
               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>
-            )}
+            {renderHint("hk-stat-card-bar-detail")}
             {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
           </div>
         );
@@ -195,7 +224,7 @@ export const HkStatCard = defineComponent({
             <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>}
+          {renderHint()}
           {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
         </div>
       );

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

@@ -1,5 +1,8 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, h, defineComponent, nextTick } from "vue";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 import { HkStatCard, statToneColor } from "./HkStatCard";
 
@@ -240,3 +243,128 @@ describe("statToneColor", () => {
     expect(statToneColor("info")).toBe("rgb(var(--color-info, rgb(var(--color-primary))))");
   });
 });
+
+describe("HkStatCard action slot — the corner affordance", () => {
+  it("hosts the action at the foot row's trailing edge on ring, hint stays centered-class", () => {
+    const c = mount(
+      h(
+        HkStatCard,
+        {
+          variant: "ring", tone: "success", pct: 37.5, value: "38%", unit: "cores",
+          icon: FakeIcon, label: "Cores", hint: "12 / 32 · monthly",
+        },
+        { action: () => h("button", { class: "action-probe" }, "⋯") },
+      ),
+    );
+    // The action content rides the dedicated wrapper inside the foot row.
+    const foot = c.querySelector(".hk-stat-card-foot") as HTMLElement;
+    expect(foot).toBeTruthy();
+    expect(foot.hasAttribute("data-has-action")).toBe(true);
+    expect(c.querySelector(".hk-stat-card-action .action-probe")?.textContent).toBe("⋯");
+    // The hint keeps its anatomy classes inside the foot — it is wrapped,
+    // not replaced.
+    expect(c.querySelector(".hk-stat-card-foot .hk-stat-card-hint")?.textContent).toBe(
+      "12 / 32 · monthly",
+    );
+    expect(c.querySelector(".hk-stat-card-foot .hk-stat-card-ring-detail")).toBeTruthy();
+  });
+
+  it("wraps the hint on plain, chip and bar the same way", () => {
+    for (const variant of ["plain", "chip", "bar"] as const) {
+      const c = mount(
+        h(HkStatCard, { variant, value: "v", label: "L", hint: "detail" }, {
+          action: () => h("span", { class: "action-probe-generic" }, "⋯"),
+        }),
+      );
+      expect(c.querySelector(".hk-stat-card-foot[data-has-action]")).toBeTruthy();
+      expect(c.querySelector(".hk-stat-card-action .action-probe-generic")).toBeTruthy();
+      expect(c.querySelector(".hk-stat-card-foot .hk-stat-card-hint")?.textContent).toBe("detail");
+    }
+  });
+
+  it("keeps the hint DOM bare (no foot wrapper) when the slot is absent", () => {
+    // The wrapper exists ONLY for the action anchor: a host not using the
+    // slot must see the exact pre-slot DOM. This kills an "always wrap"
+    // mutation, which would silently re-nest every existing hint.
+    for (const variant of ["plain", "chip", "ring", "bar"] as const) {
+      const c = mount(h(HkStatCard, { variant, value: "v", label: "L", hint: "detail" }));
+      expect(c.querySelector(".hk-stat-card-foot")).toBeNull();
+      expect(c.querySelector(".hk-stat-card > .hk-stat-card-hint")?.textContent).toBe("detail");
+    }
+  });
+
+  it("keeps each variant's pre-slot hint attributes when the slot is absent", () => {
+    // R1 finding: the chip variant's hint never carried a title before
+    // the action slot existed — "byte-identical without the slot" must
+    // hold attribute-for-attribute, not just structure-for-structure.
+    // plain/ring/bar always titled their hint; chip never did.
+    const titled = (variant: "plain" | "chip" | "ring" | "bar") => {
+      const c = mount(h(HkStatCard, { variant, value: "v", label: "L", hint: "detail" }));
+      const hint = c.querySelector(".hk-stat-card > .hk-stat-card-hint") as HTMLElement;
+      return hint.hasAttribute("title");
+    };
+    expect(titled("chip")).toBe(false);
+    expect(titled("plain")).toBe(true);
+    expect(titled("ring")).toBe(true);
+    expect(titled("bar")).toBe(true);
+  });
+
+  it("keeps the action-corner SCSS contract (source pin)", () => {
+    // happy-dom never applies the stylesheet, so the data-has-action
+    // layout rules (corner clearance + action-only min-height) are
+    // otherwise removable with zero red (R1 mutation c). The house
+    // source-contract style pins them.
+    const scss = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "HkStatCard.scss"),
+      "utf-8",
+    );
+    const foot = scss.match(/\.hk-stat-card-foot\[data-has-action\]\s*{[^}]*}/)?.[0] ?? "";
+    expect(foot, "action-only foot min-height rule must exist").toContain("min-height");
+    const clearance = scss.match(
+      /\.hk-stat-card-foot\[data-has-action\] \.hk-stat-card-hint\s*{[^}]*}/,
+    )?.[0];
+    expect(clearance, "hint corner-clearance rule must exist").toBeTruthy();
+    expect(clearance).toContain("padding-inline-end");
+    // The ring card centers its children, which would leave the foot
+    // fit-content-wide — dead centering AND a hint-edge-anchored action
+    // (R2 Major). The stretch is what puts the corner back.
+    const ringFoot = scss.match(
+      /\.hk-stat-card-ring \.hk-stat-card-foot\s*{[^}]*}/,
+    )?.[0];
+    expect(ringFoot, "ring foot stretch rule must exist").toBeTruthy();
+    expect(ringFoot).toContain("align-self: stretch");
+    expect(ringFoot).toContain("justify-content: center");
+  });
+
+  it("stops action clicks from double-firing a clickable card's click", async () => {
+    const clicks: number[] = [];
+    const c = mount(
+      h(
+        HkStatCard,
+        { variant: "ring", value: "38%", label: "L", pct: 38, clickable: true, onClick: () => clicks.push(1) },
+        { action: () => h("button", { class: "action-btn-probe" }, "⋯") },
+      ),
+    );
+    const btn = c.querySelector(".action-btn-probe") as HTMLElement;
+    btn.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(clicks).toEqual([]);
+    // …while a click on the card surface itself still fires.
+    const card = c.querySelector(".hk-stat-card") as HTMLElement;
+    card.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(clicks).toEqual([1]);
+  });
+
+  it("renders an action-only foot (no hint) without collapsing onto the card body", () => {
+    const c = mount(
+      h(HkStatCard, { variant: "ring", value: "38%", label: "L", pct: 38 }, {
+        action: () => h("span", { class: "action-only-probe" }, "⋯"),
+      }),
+    );
+    const foot = c.querySelector(".hk-stat-card-foot") as HTMLElement;
+    expect(foot).toBeTruthy();
+    expect(foot.querySelector(".hk-stat-card-hint")).toBeNull();
+    expect(c.querySelector(".hk-stat-card-action .action-only-probe")).toBeTruthy();
+  });
+});