@celestia-island/hikari 0.55.79 → 0.55.80

package/package.json

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

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import { HkAdminTablePage } from "./HkAdminTablePage";
+
+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 COLS = [{ key: "name", title: "Name" }];
+
+describe("HkAdminTablePage", () => {
+  it("forwards title/subtitle/dense to the page header", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "Webhooks", subtitle: "Inbound endpoints", dense: true,
+        rows: [{ name: "a" }], columns: COLS,
+      }),
+    );
+    expect(c.querySelector(".hk-page-header-title-text")?.textContent).toBe("Webhooks");
+    expect(c.querySelector(".hk-page-header-subtitle")?.textContent).toBe("Inbound endpoints");
+    expect((c.querySelector(".hk-page-header") as HTMLElement).className).toContain("hk-page-header-dense");
+    expect(c.querySelector("table")).toBeTruthy();
+  });
+
+  it("renders the filter slot between header and table", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "T", rows: [{ name: "a" }], columns: COLS,
+      }, {
+        filter: () => h("div", { class: "probe-filter" }, "filter-chrome"),
+      }),
+    );
+    const filter = c.querySelector(".hk-admin-table-page-filter .probe-filter");
+    expect(filter).toBeTruthy();
+    // filter sits above the table card, not inside it
+    expect(c.querySelector(".hk-card")?.contains(filter as Node)).toBe(false);
+  });
+
+  it("staleError renders a banner while rows stay on screen", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "T", staleError: "refresh failed", rows: [{ name: "a" }], columns: COLS,
+      }),
+    );
+    expect(c.textContent).toContain("refresh failed");
+    expect(c.querySelector("table")).toBeTruthy();
+  });
+
+  it("hard error still replaces the table", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "T", error: "boom", rows: [], columns: COLS,
+      }),
+    );
+    expect(c.textContent).toContain("boom");
+    expect(c.querySelector("table")).toBeNull();
+  });
+
+  it("empty state carries the empty-action slot", () => {
+    const c = mount(
+      h(HkAdminTablePage, {
+        title: "T", rows: [], columns: COLS, emptyTitle: "Nothing here",
+      }, {
+        "empty-action": () => h("button", { class: "probe-retry" }, "Retry"),
+      }),
+    );
+    expect(c.querySelector(".hk-empty-state")).toBeTruthy();
+    expect(c.querySelector(".probe-retry")).toBeTruthy();
+  });
+
+  it("shows the spinner while loading with no rows yet", () => {
+    const c = mount(
+      h(HkAdminTablePage, { title: "T", loading: true, rows: [], columns: COLS }),
+    );
+    expect(c.querySelector(".hk-spinner-wrapper")).toBeTruthy();
+    expect(c.querySelector("table")).toBeNull();
+  });
+});

package/src/components/HkAdminTablePage.tsx

@@ -13,19 +13,35 @@ export interface HTableColumn {
 }
 
 /**
- * CRUD table-page scaffold: HkPageHeader + loading spinner + error alert +
- * empty state + HTable. Slots:
+ * CRUD table-page scaffold: HkPageHeader + (filter slot) + loading
+ * spinner + error alert + empty state + HTable. Slots:
  * - `actions`      — header actions (e.g. a "Create" button)
+ * - `filter`       — filter chrome (HkFilterBar) between header and table
  * - `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
  * - `edit-modal`   — edit dialog, rendered after the table
+ *
+ * Error model: `error` is the hard failure (no data — replaces the
+ * table), while `staleError` renders a banner ABOVE rows that are still
+ * on screen after a failed refresh, so a failed reload never hides data
+ * the user already had.
  */
 export const HkAdminTablePage = defineComponent({
   name: "HkAdminTablePage",
   props: {
     title: { type: String, default: "" },
+    /** Forwarded to the page header. */
+    subtitle: { type: String, default: undefined },
+    /** Forwarded to the page header. */
+    icon: { type: Object, default: undefined },
+    /** Compact page header variant. */
+    dense: { type: Boolean, default: false },
     loading: { type: Boolean, default: false },
     error: { type: String as PropType<string | undefined>, default: undefined },
+    /** Refresh failed while rows are still on screen — banner, not a
+     *  replacement of the table. */
+    staleError: { type: String as PropType<string | undefined>, default: undefined },
     rows: { type: Array as PropType<Record<string, unknown>[]>, required: true },
     columns: { type: Array as PropType<HTableColumn[]>, required: true },
     rowKey: { type: String, default: "id" },
@@ -37,10 +53,16 @@ export const HkAdminTablePage = defineComponent({
     return () => {
       const { t } = useI18n();
       const emptyTitle = props.emptyTitle || t("hikari::tablePage.emptyTitle", "No data");
+      // Extracted to an identifier: JSX children given as an inline object
+      // literal are not normalized to slots the way a bound one is (the
+      // chest retrySlots idiom this mirrors relies on the identifier form).
+      const emptySlots = slots["empty-action"]
+        ? { action: () => slots["empty-action"]?.() }
+        : undefined;
       return (
         <div>
           {props.title ? (
-            <HkPageHeader title={props.title}>
+            <HkPageHeader title={props.title} subtitle={props.subtitle} icon={props.icon} dense={props.dense}>
               {{ actions: () => slots.actions?.() }}
             </HkPageHeader>
           ) : slots.actions ? (
@@ -48,12 +70,21 @@ export const HkAdminTablePage = defineComponent({
               {slots.actions()}
             </div>
           ) : null}
+          {slots.filter ? <div class="hk-admin-table-page-filter">{slots.filter()}</div> : null}
+
+          {props.staleError ? <HAlert message={props.staleError} /> : null}
           {props.error ? (
             <HAlert message={props.error} />
           ) : props.loading && !props.rows.length ? (
             <HSpinner center />
           ) : !props.rows.length ? (
-            <HEmptyState boxed title={emptyTitle} description={props.emptyDescription} />
+            <HEmptyState
+              boxed
+              title={emptyTitle}
+              description={props.emptyDescription}
+            >
+              {emptySlots}
+            </HEmptyState>
           ) : (
             <HCard padded={false}>
               <HTable columns={props.columns} rows={props.rows} rowKey={props.rowKey}>

package/src/components/HkCardList.scss

@@ -0,0 +1,68 @@
+/* HkCardList / HkListRow — the standard card list anatomy. */
+
+.hk-card-list {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+
+  /* hairline dividers between rows (the CSS-native divide-y) */
+  > .hk-list-row + .hk-list-row {
+    border-top: 1px solid rgb(var(--color-border) / 10%);
+  }
+}
+
+.hk-list-row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-12, 0.75rem);
+  padding: var(--space-12, 0.75rem) var(--space-16, 1rem);
+  min-width: 0;
+  text-align: left;
+}
+
+.hk-list-row-clickable {
+  cursor: pointer;
+  transition: background-color var(--duration-normal, 0.3s) ease;
+
+  &:hover {
+    background: rgb(var(--color-text) / 4%);
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(var(--color-primary));
+    outline-offset: -2px;
+  }
+}
+
+.hk-list-row-main {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.hk-list-row-title {
+  font-size: var(--text-sm, 0.875rem);
+  font-weight: 600;
+  color: rgb(var(--color-text));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-list-row-subtitle {
+  font-size: var(--text-xs, 0.75rem);
+  color: rgb(var(--color-muted));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-list-row-trailing {
+  margin-left: auto;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+}

package/src/components/HkCardList.test.tsx

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, createCommentVNode, defineComponent, h } from "vue";
+
+import { HkCardList, HkListRow } from "./HkCardList";
+
+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 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("HkCardList", () => {
+  it("renders rows inside an unpadded card list landmark", () => {
+    const c = mount(
+      h(HkCardList, () => h(HkListRow, { title: "A" })),
+    );
+    expect(c.querySelector(".hk-card")).toBeTruthy();
+    expect(c.querySelector(".hk-card-body-unpadded")).toBeTruthy();
+    const list = c.querySelector(".hk-card-list") as HTMLElement;
+    expect(list.getAttribute("role")).toBe("list");
+    expect(list.querySelectorAll(".hk-list-row")).toHaveLength(1);
+  });
+
+  it("renders the empty slot instead of the list when provided without rows", () => {
+    const c = mount(h(HkCardList, null, { empty: () => h("p", { class: "probe-empty" }, "empty") }));
+    expect(c.querySelector(".hk-card-list")).toBeNull();
+    expect(c.querySelector(".probe-empty")?.textContent).toBe("empty");
+  });
+
+  it("falls back to the empty slot when the default slot renders no rows (v-for idiom)", () => {
+    const rows: Array<{ name: string }> = [];
+    const c = mount(
+      h(HkCardList, null, {
+        default: () => rows.map((r) => h(HkListRow, { title: r.name })),
+        empty: () => h("p", { class: "probe-empty" }, "empty"),
+      }),
+    );
+    expect(c.querySelector(".hk-card-list")).toBeNull();
+    expect(c.querySelector(".probe-empty")?.textContent).toBe("empty");
+  });
+
+  it("falls back to the empty slot when the default slot renders null (v-if idiom)", () => {
+    const c = mount(
+      h(HkCardList, null, {
+        default: () => null,
+        empty: () => h("p", { class: "probe-empty" }, "empty"),
+      }),
+    );
+    expect(c.querySelector(".hk-card-list")).toBeNull();
+    expect(c.querySelector(".probe-empty")).toBeTruthy();
+  });
+
+  it("falls back to the empty slot when the default slot is only a comment placeholder", () => {
+    const c = mount(
+      h(HkCardList, null, {
+        default: () => [createCommentVNode("v-if", true)],
+        empty: () => h("p", { class: "probe-empty" }, "empty"),
+      }),
+    );
+    expect(c.querySelector(".hk-card-list")).toBeNull();
+    expect(c.querySelector(".probe-empty")).toBeTruthy();
+  });
+
+  it("keeps the list when rows exist even with the empty slot present", () => {
+    const c = mount(
+      h(HkCardList, null, {
+        default: () => [h(HkListRow, { title: "A" })],
+        empty: () => h("p", { class: "probe-empty" }, "empty"),
+      }),
+    );
+    expect(c.querySelector(".hk-card-list")).toBeTruthy();
+    expect(c.querySelectorAll(".hk-list-row")).toHaveLength(1);
+    expect(c.querySelector(".probe-empty")).toBeNull();
+  });
+});
+
+describe("HkListRow", () => {
+  it("renders icon chip, title, subtitle and the trailing slot", () => {
+    const c = mount(
+      h(HkListRow, { icon: FakeIcon, iconTone: "success", title: "gpu-1", subtitle: "192.168.2.10" }, {
+        trailing: () => h("span", { class: "probe-badge" }, "online"),
+      }),
+    );
+    const row = c.querySelector(".hk-list-row") as HTMLElement;
+    expect(row.getAttribute("role")).toBe("listitem");
+    expect(row.querySelector(".hk-icon-chip-tone-success svg[data-fake-icon]")).toBeTruthy();
+    expect(row.querySelector(".hk-list-row-title")?.textContent).toBe("gpu-1");
+    expect(row.querySelector(".hk-list-row-subtitle")?.textContent).toBe("192.168.2.10");
+    expect(row.querySelector(".hk-list-row-trailing .probe-badge")?.textContent).toBe("online");
+  });
+
+  it("keeps the default slot beside title/subtitle inside the main column", () => {
+    const c = mount(
+      h(HkListRow, { title: "T" }, { default: () => h("div", { class: "probe-extra" }, "extra") }),
+    );
+    expect(c.querySelector(".hk-list-row-main .probe-extra")).toBeTruthy();
+  });
+
+  it("activates on Enter/Space when clickable, ignoring bubbled keys", async () => {
+    const clicks: string[] = [];
+    const c = mount(
+      h(HkListRow, {
+        title: "T",
+        clickable: true,
+        onClick: (e: MouseEvent | KeyboardEvent) => clicks.push("key" in e ? e.key : "mouse"),
+      }),
+    );
+    const row = c.querySelector(".hk-list-row") as HTMLElement;
+    expect(row.getAttribute("tabindex")).toBe("0");
+    for (const key of ["Enter", " "]) {
+      row.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }));
+      await Promise.resolve();
+    }
+    expect(clicks).toEqual(["Enter", " "]);
+  });
+
+  it("is not interactive without clickable", () => {
+    const c = mount(h(HkListRow, { title: "T" }));
+    const row = c.querySelector(".hk-list-row") as HTMLElement;
+    expect(row.className).not.toContain("hk-list-row-clickable");
+    expect(row.getAttribute("tabindex")).toBeNull();
+  });
+});

package/src/components/HkCardList.tsx

@@ -0,0 +1,113 @@
+import { Comment, defineComponent, type Component, type PropType, type VNode } from "vue";
+
+import HkCard from "./HkCard";
+import { HkIconChip } from "./HkIconChip";
+import type { StatTone } from "./HkStatCard";
+import "./HkCardList.scss";
+
+/**
+ * Whether a default slot actually rendered any row. Testing
+ * `slots.default` for truthiness is not enough: the canonical template
+ * idiom (`<HkListRow v-for>` plus `<template #empty>`) always provides a
+ * default slot whose v-for renders zero vnodes, and a `v-if` row renders
+ * a comment placeholder — both would otherwise show an empty bordered
+ * card where the empty state belongs.
+ */
+function renderedRows(nodes: unknown): boolean {
+  if (nodes == null || nodes === false || nodes === "") return false;
+  if (Array.isArray(nodes)) return nodes.some((n) => renderedRows(n));
+  if (typeof nodes === "object") return (nodes as VNode).type !== Comment;
+  return true; // non-empty text content
+}
+
+/**
+ * HkCardList — the standard card list: an unpadded HkCard whose body is
+ * a `role="list"` column of HkListRow entries separated by hairlines.
+ *
+ * This anatomy is what the console family calls "card rows, never raw
+ * ul/ol" (the host's UnoCSS setup has no preflight, so `<ul>` indents
+ * 40px): a bordered card surface, rows at `px-4 py-3` with a 12px gutter,
+ * hairline dividers between them. It was copy-pasted across ten views
+ * before becoming a component.
+ *
+ * ```tsx
+ * <HkCardList>
+ *   <HkListRow icon={Server} title={row.name} subtitle={row.url}
+ *              trailing={() => <HkBadge>{row.status}</HkBadge>} />
+ * </HkCardList>
+ * ```
+ */
+export const HkCardList = defineComponent({
+  name: "HkCardList",
+  setup(_props, { slots }) {
+    return () => {
+      const rows = slots.default?.();
+      return (
+        <HkCard padded={false}>
+          {slots.empty && !renderedRows(rows) ? (
+            slots.empty()
+          ) : (
+            <div class="hk-card-list" role="list">
+              {rows}
+            </div>
+          )}
+        </HkCard>
+      );
+    };
+  },
+});
+
+/**
+ * HkListRow — one entry of an HkCardList: an optional tone-tinted icon
+ * chip, a main column (title / subtitle / free-form default slot), and a
+ * trailing slot pinned to the right edge (badges, switches, actions).
+ *
+ * The row is a list item, not a button — set `clickable` when the whole
+ * row drills through, which adds the cursor/focus/hover contract the
+ * stat cards use.
+ */
+export const HkListRow = defineComponent({
+  name: "HkListRow",
+  props: {
+    /** Leading icon — rendered through the standard HkIconChip. */
+    icon: { type: Object as PropType<Component>, default: undefined },
+    iconTone: { type: String as PropType<StatTone>, default: "primary" },
+    title: { type: String, default: undefined },
+    subtitle: { type: String, default: undefined },
+    /** Whole-row click (drill-through). */
+    clickable: { type: Boolean, default: false },
+  },
+  emits: { click: (_e: MouseEvent | KeyboardEvent) => true },
+  setup(props, { emit, slots }) {
+    return () => (
+      <div
+        class={["hk-list-row", props.clickable && "hk-list-row-clickable"]}
+        role="listitem"
+        tabindex={props.clickable ? 0 : undefined}
+        onKeydown={
+          props.clickable
+            ? (e: KeyboardEvent) => {
+                // role listitem + tabindex promises keyboard activation
+                // only when the row itself is made interactive; keys
+                // bubbling from focusable children are left alone.
+                if (e.target !== e.currentTarget) return;
+                if (e.key !== "Enter" && e.key !== " ") return;
+                e.preventDefault();
+                emit("click", e);
+              }
+            : undefined
+        }
+        onClick={props.clickable ? (e: MouseEvent) => emit("click", e) : undefined}
+
+      >
+        {props.icon ? <HkIconChip icon={props.icon} tone={props.iconTone} /> : null}
+        <div class="hk-list-row-main">
+          {props.title ? <div class="hk-list-row-title">{props.title}</div> : null}
+          {props.subtitle ? <div class="hk-list-row-subtitle">{props.subtitle}</div> : null}
+          {slots.default?.()}
+        </div>
+        {slots.trailing ? <div class="hk-list-row-trailing">{slots.trailing()}</div> : null}
+      </div>
+    );
+  },
+});

package/src/components/HkIconChip.scss

@@ -0,0 +1,27 @@
+/* HkIconChip — the standard leading icon chip.
+ * The tone rules mirror HkStatCard's chip-icon palette verbatim so the
+ * two never drift apart. */
+.hk-icon-chip {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-md, 0.5rem);
+  flex-shrink: 0;
+}
+
+.hk-icon-chip-md {
+  width: var(--space-28, 1.75rem);
+  height: var(--space-28, 1.75rem);
+}
+
+.hk-icon-chip-sm {
+  width: var(--space-24, 1.5rem);
+  height: var(--space-24, 1.5rem);
+}
+
+.hk-icon-chip-tone-success { background: rgb(var(--color-success) / 12%); color: rgb(var(--color-success)); }
+.hk-icon-chip-tone-warning { background: rgb(var(--color-warning) / 12%); color: rgb(var(--color-warning)); }
+.hk-icon-chip-tone-error { background: rgb(var(--color-error) / 12%); color: rgb(var(--color-error)); }
+.hk-icon-chip-tone-info { background: rgb(var(--color-info, rgb(var(--color-primary))) / 12%); color: rgb(var(--color-info, rgb(var(--color-primary)))); }
+.hk-icon-chip-tone-primary { background: rgb(var(--color-primary) / 12%); color: rgb(var(--color-primary)); }
+.hk-icon-chip-tone-muted { background: rgb(var(--color-muted) / 12%); color: rgb(var(--color-muted)); }

package/src/components/HkIconChip.test.tsx

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import { HkIconChip } from "./HkIconChip";
+
+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 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("HkIconChip", () => {
+  it("renders the icon at the md box size by default", () => {
+    const c = mount(h(HkIconChip, { icon: FakeIcon }));
+    const chip = c.querySelector(".hk-icon-chip") as HTMLElement;
+    expect(chip).toBeTruthy();
+    expect(chip.className).toContain("hk-icon-chip-md");
+    expect(chip.className).toContain("hk-icon-chip-tone-primary");
+    expect(chip.getAttribute("aria-hidden")).toBe("true");
+    expect(chip.querySelector("svg[data-fake-icon]")?.getAttribute("width")).toBe("15");
+  });
+
+  it("renders the sm box with a 13px glyph", () => {
+    const c = mount(h(HkIconChip, { icon: FakeIcon, size: "sm" }));
+    const chip = c.querySelector(".hk-icon-chip") as HTMLElement;
+    expect(chip.className).toContain("hk-icon-chip-sm");
+    expect(chip.querySelector("svg[data-fake-icon]")?.getAttribute("width")).toBe("13");
+  });
+
+  it("carries the tone class for every palette entry", () => {
+    for (const tone of ["success", "warning", "error", "info", "primary", "muted"] as const) {
+      const c = mount(h(HkIconChip, { icon: FakeIcon, tone }));
+      expect((c.querySelector(".hk-icon-chip") as HTMLElement).className).toContain(
+        `hk-icon-chip-tone-${tone}`,
+      );
+    }
+  });
+});

package/src/components/HkIconChip.tsx

@@ -0,0 +1,42 @@
+import { defineComponent, h, type Component, type PropType } from "vue";
+
+import type { StatTone } from "./HkStatCard";
+import "./HkIconChip.scss";
+
+/**
+ * HkIconChip — the standard leading icon chip: a small rounded square
+ * painted in a 10% tint of the tone color with the tone color as the
+ * glyph ink. This anatomy was copy-pasted as inline styles across the
+ * consumers (roster rows, card headers, stat strips) before it became a
+ * component; the tone palette is the one HkStatCard owns, so chips always
+ * match the stat card's health colors.
+ *
+ * Purely decorative by contract — the chip is aria-hidden and the icon
+ * meaning must be conveyed by adjacent text (row title, card label).
+ *
+ * ```tsx
+ * <HkIconChip icon={Cpu} tone="info" />
+ * <HkIconChip icon={Coins} size="sm" />
+ * ```
+ */
+export const HkIconChip = defineComponent({
+  name: "HkIconChip",
+  props: {
+    /** Icon component (lucide-vue-next style). */
+    icon: { type: Object as PropType<Component>, required: true },
+    /** Tone drives both the tint background and the glyph ink. */
+    tone: { type: String as PropType<StatTone>, default: "primary" },
+    /** sm = 24px box / 13px glyph, md = 28px box / 15px glyph. */
+    size: { type: String as PropType<"sm" | "md">, default: "md" },
+  },
+  setup(props) {
+    return () => (
+      <span
+        class={["hk-icon-chip", `hk-icon-chip-${props.size}`, `hk-icon-chip-tone-${props.tone}`]}
+        aria-hidden="true"
+      >
+        {h(props.icon, { size: props.size === "sm" ? 13 : 15 })}
+      </span>
+    );
+  },
+});

package/src/components/HkPageHeader.scss

@@ -78,3 +78,22 @@
     height: var(--space-24, 1.5rem);
   }
 }
+
+/* lead — a back affordance (or any leading control) riding before the
+ * title inside the h1 box, keeping the heading semantics intact. */
+.hk-page-header-lead {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+/* titleExtra — inline chips (status badges, mono ids) after the title
+ * text; baseline-aligned with the title, wrapping with it. */
+.hk-page-header-title-extra {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  font-size: var(--text-xs, 0.75rem);
+  font-weight: 400;
+  min-width: 0;
+}

package/src/components/HkPageHeader.test.ts

@@ -64,4 +64,21 @@ describe("HkPageHeader", () => {
       "hk-page-header-dense",
     );
   });
+  it("renders the lead slot before the title icon", () => {
+    const c = mountHeader({ title: "T" }, { lead: () => h("button", { class: "probe-back" }, "Back") });
+    const title = c.querySelector(".hk-page-header-title")!;
+    expect(title.querySelector(".hk-page-header-lead .probe-back")).toBeTruthy();
+    const lead = c.querySelector(".hk-page-header-lead")!;
+    const icon = c.querySelector(".hk-page-header-icon");
+    if (icon) {
+      expect(lead.compareDocumentPosition(icon) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    }
+  });
+
+  it("renders titleExtra inline after the title text", () => {
+    const c = mountHeader({ title: "T" }, { titleExtra: () => h("span", { class: "probe-chip" }, "stable") });
+    const extra = c.querySelector(".hk-page-header-title-text + .hk-page-header-title-extra") ??
+      c.querySelector(".hk-page-header-title-extra");
+    expect(extra?.textContent).toContain("stable");
+  });
 });

package/src/components/HkPageHeader.tsx

@@ -31,12 +31,14 @@ export const HkPageHeader = defineComponent({
       <div class={["hk-page-header", props.dense && "hk-page-header-dense"]}>
         <div class="hk-page-header-main">
           <h1 class="hk-page-header-title">
+            {slots.lead ? <span class="hk-page-header-lead">{slots.lead()}</span> : null}
             {slots.icon
               ? <span class="hk-page-header-icon">{slots.icon()}</span>
               : props.icon
                 ? <span class="hk-page-header-icon">{h(props.icon)}</span>
                 : null}
             <span class="hk-page-header-title-text">{props.title}</span>
+            {slots.titleExtra ? <span class="hk-page-header-title-extra">{slots.titleExtra()}</span> : null}
           </h1>
           {props.subtitle && (
             <p class="hk-page-header-subtitle">{props.subtitle}</p>

package/src/components/HkSectionHeader.scss

@@ -0,0 +1,81 @@
+/* HkSectionHeader — the standard in-card / in-page section header. */
+
+.hk-section-header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4, 0.25rem);
+  min-width: 0;
+}
+
+.hk-section-header-row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  min-width: 0;
+}
+
+.hk-section-header-icon {
+  display: inline-flex;
+  color: rgb(var(--color-muted));
+  flex-shrink: 0;
+}
+
+.hk-section-header-title {
+  margin: 0;
+  font-size: var(--text-sm, 0.875rem);
+  font-weight: 600;
+  color: rgb(var(--color-text));
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-8, 0.5rem);
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.hk-section-header-count {
+  font-size: var(--text-2xs, 0.625rem);
+  font-weight: 400;
+  color: rgb(var(--color-muted));
+  white-space: nowrap;
+}
+
+.hk-section-header-actions {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  flex-shrink: 0;
+}
+
+.hk-section-header-description {
+  margin: 0;
+  font-size: var(--text-xs, 0.75rem);
+  color: rgb(var(--color-muted));
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+}
+
+/* ── dense: tighter rhythm for dense panels ─────────────────────────── */
+.hk-section-header-dense {
+  gap: var(--space-2, 0.125rem);
+}
+
+/* ── micro: tiny uppercase eyebrow label ────────────────────────────── */
+.hk-section-header-micro .hk-section-header-title {
+  font-size: var(--text-2xs, 0.625rem);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: rgb(var(--color-muted));
+}
+
+/* ── mono: mono-caption idiom for ledgers/detail rails ──────────────── */
+.hk-section-header-mono .hk-section-header-title {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: var(--text-xs, 0.75rem);
+  font-weight: 500;
+}
+
+.hk-section-header-mono .hk-section-header-count {
+  font-family: var(--font-mono, ui-monospace, monospace);
+}

package/src/components/HkSectionHeader.test.tsx

@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import { HkSectionHeader } from "./HkSectionHeader";
+
+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 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("HkSectionHeader", () => {
+  it("renders an h3 title by default with the count beside it", () => {
+    const c = mount(h(HkSectionHeader, { title: "Token Usage", count: "12 total" }));
+    const title = c.querySelector("h3.hk-section-header-title") as HTMLElement;
+    expect(title).toBeTruthy();
+    expect(title.textContent).toContain("Token Usage");
+    expect(c.querySelector(".hk-section-header-count")?.textContent).toBe("12 total");
+  });
+
+  it("honors the level prop for the document outline", () => {
+    const c = mount(h(HkSectionHeader, { title: "T", level: "h2" }));
+    expect(c.querySelector("h2.hk-section-header-title")).toBeTruthy();
+    const c2 = mount(h(HkSectionHeader, { title: "T", level: "div" }));
+    expect(c2.querySelector("h2, h3")).toBeNull();
+    expect(c2.querySelector(".hk-section-header-title")).toBeTruthy();
+  });
+
+  it("renders description under the row and actions right-aligned in the row", () => {
+    const c = mount(
+      h(HkSectionHeader, { title: "T", description: "one-liner" }, {
+        actions: () => h("button", { class: "probe-action" }, "Export"),
+      }),
+    );
+    expect(c.querySelector(".hk-section-header-description")?.textContent).toBe("one-liner");
+    expect(c.querySelector(".hk-section-header-row .hk-section-header-actions .probe-action")).toBeTruthy();
+  });
+
+  it("renders the leading icon inside the row", () => {
+    const c = mount(h(HkSectionHeader, { title: "T", icon: FakeIcon }));
+    expect(c.querySelector(".hk-section-header-row .hk-section-header-icon svg[data-fake-icon]")).toBeTruthy();
+  });
+
+  it("applies variant and dense classes", () => {
+    const c = mount(h(HkSectionHeader, { title: "T", variant: "micro", dense: true }));
+    const root = c.querySelector(".hk-section-header") as HTMLElement;
+    expect(root.className).toContain("hk-section-header-micro");
+    expect(root.className).toContain("hk-section-header-dense");
+    const c2 = mount(h(HkSectionHeader, { title: "T", variant: "mono" }));
+    expect((c2.querySelector(".hk-section-header") as HTMLElement).className).toContain("hk-section-header-mono");
+  });
+});

package/src/components/HkSectionHeader.tsx

@@ -0,0 +1,76 @@
+import { defineComponent, h, type Component, type PropType } from "vue";
+
+import "./HkSectionHeader.scss";
+
+export type SectionHeaderVariant = "default" | "micro" | "mono";
+
+/**
+ * HkSectionHeader — the standard in-card / in-page section header.
+ *
+ * The audit that introduced this counted ~89 distinct hand-rolled
+ * treatments for the same anatomy across the consumers: a small
+ * semibold heading, an optional one-line description under (or beside)
+ * it, an optional right-aligned actions cluster, and occasionally a
+ * leading icon or a trailing count badge. One component replaces the
+ * family.
+ *
+ * Variants:
+ * - `default` — `text-sm font-semibold` heading (the dominant idiom).
+ * - `micro`   — tiny uppercase eyebrow label for dense panels.
+ * - `mono`    — mono-caption idiom used by ledgers/detail rails.
+ *
+ * ```tsx
+ * <HkSectionHeader title="Token Usage" description="Per model this range">
+ *   {{ actions: () => <HkButton size="sm">Export</HkButton> }}
+ * </HkSectionHeader>
+ * ```
+ */
+export const HkSectionHeader = defineComponent({
+  name: "HkSectionHeader",
+  props: {
+    title: { type: String, required: true },
+    /** Heading element: h2/h3 keep document outline, div for visual-only. */
+    level: { type: String as PropType<"h2" | "h3" | "div">, default: "h3" },
+    /** One-line description rendered under the heading. */
+    description: { type: String, default: undefined },
+    /** Leading icon component. */
+    icon: { type: Object as PropType<Component>, default: undefined },
+    /** Trailing count badge (e.g. "12 total") rendered beside the title. */
+    count: { type: String, default: undefined },
+    variant: { type: String as PropType<SectionHeaderVariant>, default: "default" },
+    /** Tighter spacing for dense panels. */
+    dense: { type: Boolean, default: false },
+  },
+  setup(props, { slots }) {
+    return () => {
+      const heading = h(
+        props.level,
+        { class: "hk-section-header-title" },
+        [
+          props.title,
+          props.count != null ? <span class="hk-section-header-count">{props.count}</span> : null,
+        ],
+      );
+      return (
+        <div
+          class={[
+            "hk-section-header",
+            `hk-section-header-${props.variant}`,
+            props.dense && "hk-section-header-dense",
+          ]}
+        >
+          <div class="hk-section-header-row">
+            {props.icon ? <span class="hk-section-header-icon">{h(props.icon, { size: 15 })}</span> : null}
+            {heading}
+            {slots.actions ? <div class="hk-section-header-actions">{slots.actions()}</div> : null}
+          </div>
+          {props.description ? (
+            <p class="hk-section-header-description">{props.description}</p>
+          ) : slots.description ? (
+            <p class="hk-section-header-description">{slots.description()}</p>
+          ) : null}
+        </div>
+      );
+    };
+  },
+});

package/src/components/HkStatCard.scss

@@ -187,3 +187,13 @@
 .hk-stat-card-bar-detail {
   max-width: 100%;
 }
+
+/* footer slot — free-form content row under the value/hint (badge rows,
+ * deltas, sparklines). Wraps; does not collapse like the hint. */
+.hk-stat-card-footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  max-width: 100%;
+}

package/src/components/HkStatCard.tsx

@@ -15,6 +15,8 @@ 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,
@@ -126,6 +128,7 @@ export const HkStatCard = defineComponent({
               {slots.aside && <div class="hk-stat-card-aside">{slots.aside()}</div>}
             </div>
             {props.hint && <div class="hk-stat-card-hint">{props.hint}</div>}
+            {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
           </div>
         );
       }
@@ -157,6 +160,7 @@ export const HkStatCard = defineComponent({
                 {props.hint}
               </div>
             )}
+            {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
           </div>
         );
       }
@@ -178,6 +182,7 @@ export const HkStatCard = defineComponent({
                 {props.hint}
               </div>
             )}
+            {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
           </div>
         );
       }
@@ -191,6 +196,7 @@ export const HkStatCard = defineComponent({
           </div>
           <div class="hk-stat-card-value">{props.value}</div>
           {props.hint && <div class="hk-stat-card-hint" title={props.hint}>{props.hint}</div>}
+          {slots.footer && <div class="hk-stat-card-footer">{slots.footer()}</div>}
         </div>
       );
     };

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

@@ -196,6 +196,38 @@ describe("HkStatCard bar", () => {
   });
 });
 
+describe("HkStatCard footer slot (all variants)", () => {
+  it("renders the footer content row under the value on plain", () => {
+    const c = mount(
+      h(HkStatCard, { label: "Total", value: "1.2M" }, { footer: () => h("span", { class: "probe-badge" }, "3 dims") }),
+    );
+    expect(c.querySelector(".hk-stat-card-footer .probe-badge")?.textContent).toBe("3 dims");
+  });
+
+  it("renders the footer row after the detail line on ring and bar", () => {
+    const ring = mount(
+      h(HkStatCard, { variant: "ring", value: "40%", label: "L", pct: 40 }, { footer: () => h("i", { class: "probe-r" }) }),
+    );
+    expect(ring.querySelector(".hk-stat-card-footer .probe-r")).toBeTruthy();
+    const bar = mount(
+      h(HkStatCard, { variant: "bar", value: "72%", label: "L", pct: 72 }, { footer: () => h("i", { class: "probe-b" }) }),
+    );
+    expect(bar.querySelector(".hk-stat-card-footer .probe-b")).toBeTruthy();
+  });
+
+  it("renders the footer row on the chip variant too", () => {
+    const c = mount(
+      h(HkStatCard, { variant: "chip", value: 3, label: "Running" }, { footer: () => h("i", { class: "probe-c" }) }),
+    );
+    expect(c.querySelector(".hk-stat-card-footer .probe-c")).toBeTruthy();
+  });
+
+  it("omits the footer node when the slot is absent", () => {
+    const c = mount(h(HkStatCard, { label: "L", value: 1 }));
+    expect(c.querySelector(".hk-stat-card-footer")).toBeNull();
+  });
+});
+
 describe("statToneColor", () => {
   it("maps every tone to the theme-variable palette the card paints with", () => {
     expect(statToneColor("success")).toBe("rgb(var(--color-success))");

package/src/components/HkSvgVarPresentation.test.tsx

@@ -162,6 +162,15 @@ describe("index export surface smoke", () => {
       "HkEmptyState",
       "HkPageHeader",
       "HkTable",
+      "HkIconChip",
+      "HIconChip",
+      "HkCardList",
+      "HCardList",
+      "HkListRow",
+      "HListRow",
+      "HkSectionHeader",
+      "HSectionHeader",
+      "HkAdminTablePage",
     ] as const) {
       expect(Hk, `missing export: ${name}`).toHaveProperty(name);
     }

package/src/index.ts

@@ -754,6 +754,12 @@ export { HkStatCard as HkStatCard } from "./components/HkStatCard";
 export { statToneColor, type StatTone as StatTone, type StatVariant as StatVariant } from "./components/HkStatCard";
 export { HkStatusPill as HkStatusPill } from "./components/HkStatusPill";
 export { default as HkFilterBar } from "./components/HkFilterBar";
+export { HkIconChip as HkIconChip } from "./components/HkIconChip";
+export { HkIconChip as HIconChip } from "./components/HkIconChip";
+export { HkCardList, HkListRow } from "./components/HkCardList";
+export { HkCardList as HCardList, HkListRow as HListRow } from "./components/HkCardList";
+export { HkSectionHeader, type SectionHeaderVariant } from "./components/HkSectionHeader";
+export { HkSectionHeader as HSectionHeader } from "./components/HkSectionHeader";
 export { default as HFilterBar } from "./components/HkFilterBar";
 export { HkShareBar as HkShareBar } from "./components/HkShareBar";
 export { HkSecretRevealModal as HkSecretRevealModal } from "./components/HkSecretRevealModal";