@celestia-island/hikari 0.55.117 → 0.55.120

package/package.json

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

package/src/components/HkModal.scss

@@ -434,7 +434,10 @@
 //     detail sheet never carries a screenful of dead body)
 //   - never grows past the top band reserved for the secondary-window
 //     breadcrumb strip (--hk-sheet-top-inset; default 4.25rem keeps the
-//     floating breadcrumb visible above a full-height sheet)
+//     floating breadcrumb visible above a full-height sheet, and the
+//     strip itself PUBLISHES this property on <body> while it is up —
+//     its live "own height + one gap above + one gap below" — so the
+//     band tracks the real chrome instead of a static guess)
 //   - rounded top corners only, full width
 // ------
 @media (max-width: 767px) {
@@ -536,12 +539,16 @@
     // inside once the cap is hit); they no longer stretch it.
     // Plain-vh fallback first: dvh-less engines (older Android WebView /
     // Tauri) would drop the whole dvh calc and leave the sheet uncapped.
+    // !important on BOTH: an inline max-height (a host's `style` pass, a
+    // size prop's own cap) must lose to the family band — the strip's
+    // daylight is a guarantee, not a default (HkDrawer parity, 2026-10-05
+    // mobile report: a tall sheet covered the strip's band).
     max-height: calc(
       100vh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
-    );
+    ) !important;
     max-height: calc(
       100dvh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
-    );
+    ) !important;
   }
 
   // Sheet slide reveal replaces the height-clip reveal on mobile.

package/src/components/HkModal.sheetgap.test.ts

@@ -74,6 +74,21 @@ describe("HkModal mobile sheet spacing contract", () => {
       expect(content).not.toMatch(/max-height:\s*none/);
     });
 
+    // 2026-10-05 mobile report: a tall sheet covered the breadcrumb's band.
+    // The drawer cap has carried !important for exactly this reason (the
+    // inline maxHeight from a `size` prop must lose to the family band —
+    // HkDrawer.sheetfamily pins its side); the modal cap must not be the
+    // weak sibling. Any host style/prop pass writing max-height inline
+    // would silently uncap the sheet and swallow the strip's band.
+    it("beats inline max-heights with !important on both caps", () => {
+      // [^;]+ runs to the declaration's own semicolon, so the assertion
+      // sees whatever sits between the closing paren and it.
+      const vh = content.match(/max-height: calc\(\s*100vh - var\(--hk-sheet-top-inset[^;]+/)?.[0] ?? "";
+      const dvh = content.match(/max-height: calc\(\s*100dvh - var\(--hk-sheet-top-inset[^;]+/)?.[0] ?? "";
+      expect(vh, "plain-vh fallback cap").toContain("!important");
+      expect(dvh, "dvh cap").toContain("!important");
+    });
+
     // 2026-09-21 phone-sheet transition contract (two Xiaomi WebView
     // chest reports the same day): the mobile list carries ONLY the
     // clip-path reveal.

package/src/components/HkModalBreadcrumb.test.tsx

@@ -18,6 +18,9 @@ afterEach(async () => {
     manager.unregister(entry.id);
   }
   document.body.style.overflow = "";
+  // The strip publishes its sheet top band on <body> inline while up —
+  // strip it here too, or one test's band leaks into the next.
+  document.body.style.removeProperty("--hk-sheet-top-inset");
   window.innerWidth = originalWidth;
   // happy-dom never fires transitionend, so a popover's leave never settles
   // and its teleported panel lingers on <body> — strip it, or the next
@@ -680,6 +683,11 @@ describe("HkModalBreadcrumb overflow fold", () => {
       // zoom) / 2 = 24, and the clearance 12 + (88 visual / 2 zoom) / 2 =
       // 34 — the clearance sits lower and wins.
       expect(strip()!.style.top).toBe("44px");
+      // The published sheet band rides the same conversions: strip centre
+      // 44 + its local half-height (88 visual / 2 zoom) / 2 = 22 + one gap
+      // 12 — a zoom-blind band would read 78 ± (zoom−1)·Δ and drift the
+      // sheet cap against the strip on zoomed hosts.
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("78px");
     } finally {
       vi.restoreAllMocks();
       app.remove();
@@ -731,6 +739,51 @@ describe("HkModalBreadcrumb overflow fold", () => {
     }
   });
 
+  it("publishes the sheet top band while up and clears it with the strip", async () => {
+    // The strip is the authority on its own band: while it is up, mobile
+    // bottom sheets must stop below "strip bottom edge + one more gap" —
+    // the sheet family consumes --hk-sheet-top-inset as exactly that
+    // line, so the strip PUBLISHES it on <body> (inline beats a host's
+    // :root token while up) and withdraws it when the strip goes away.
+    // Boxless DOM → fallback geometry: band = topPx + 43/2 + gap.
+    const app = document.createElement("div");
+    app.id = "app";
+    document.body.appendChild(app);
+    const unmountAll = () => {
+      for (const a of mounts.splice(0)) a.unmount();
+    };
+    try {
+      setViewport(1200);
+      manager.register("modal", true, "第一层");
+      manager.register("modal", true, "第二层");
+      await mountStrip();
+      // 0 (app top) + max(24, 12 + 21.5) + 21.5 + 12.
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("67px");
+
+      // Unmounting a visible strip withdraws the band synchronously
+      // (onBeforeUnmount) — a stale band must not outlive its publisher
+      // (mutation round M5: removing the unmount clear passed everything
+      // else green).
+      unmountAll();
+      await nextTick();
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("");
+
+      // A host wanting more air raises the gap; the band follows it.
+      await mountStrip({ topGap: 40 });
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("123px");
+
+      // The promise lives with the strip: drop back to a single layer and
+      // the property is withdrawn — the host token rules again.
+      const entries = [...manager.registry.value.values()];
+      manager.unregister(entries[entries.length - 1].id);
+      await until(() => strip() === null);
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("");
+    } finally {
+      unmountAll();
+      app.remove();
+    }
+  });
+
   it("paints the fallback position before any resync can run", async () => {
     // A host whose app root id never resolves leaves resyncTop at its
     // early-return, so the strip paints the INITIAL ref: that line must
@@ -745,11 +798,16 @@ describe("HkModalBreadcrumb overflow fold", () => {
     manager.register("modal", true, "第二层");
     await mountStrip({ appRootId: "no-such-root" });
     expect(strip()!.style.top).toBe("33.5px");
+    // The band promise holds on the fallbacks too (no app root is no
+    // excuse for going quiet while the sheets are watching):
+    // 33.5 + 43/2 + 12.
+    expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("67px");
     for (const a of mounts.splice(0)) a.unmount();
 
     // The init follows the prop the same way the resync does.
     await mountStrip({ appRootId: "no-such-root", topGap: 0 });
     expect(strip()!.style.top).toBe("21.5px");
+    expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("43px");
   });
 
   it("writes the viewport fence in the strip's own px", async () => {

package/src/components/HkModalBreadcrumb.tsx

@@ -407,9 +407,32 @@ export default defineComponent({
      *  layout fallbacks (48px header, 43px strip). The first nextTick
      *  resync replaces it with measured numbers. */
     const topPx = ref(topGapPx.value + STRIP_HEIGHT_PX / 2);
+
+    /** Publish the sheet top band: while the strip is up, mobile bottom
+     *  sheets must stop BELOW the strip's bottom edge plus one more gap —
+     *  "the strip's own height, with one gap above and one below". The
+     *  sheet family consumes this exact custom property as its mobile
+     *  max-height inset (--hk-sheet-top-inset), so publishing it here
+     *  turns every host's static guess into the strip's live geometry.
+     *  Written on <body> inline (beats a host's :root token while up;
+     *  removed when the strip goes away so the host token rules again),
+     *  in the strip's LOCAL px — the sheets teleport into the same zoomed
+     *  subtree, so one px space is shared. */
+    function publishBand(bandPx: number | null): void {
+      if (typeof document === "undefined") return;
+      if (bandPx == null) document.body.style.removeProperty("--hk-sheet-top-inset");
+      else document.body.style.setProperty("--hk-sheet-top-inset", `${bandPx}px`);
+    }
+
     function resyncTop() {
       const app = document.getElementById(props.appRootId);
-      if (!app) return;
+      if (!app) {
+        // No app root to measure: the strip still paints on the fallback
+        // geometry (the init ref), so keep the band promise on those same
+        // fallbacks instead of going quiet while the sheets are watching.
+        publishBand(topPx.value + STRIP_HEIGHT_PX / 2 + topGapPx.value);
+        return;
+      }
       // The strip teleports to <body> — inside any root CSS zoom subtree
       // — so its inline top is LOCAL px. Keep every term in that local
       // space: the app root's computed top is already local, while the
@@ -442,6 +465,9 @@ export default defineComponent({
       // viewport top can no longer push the strip's upper half against
       // (or past) the top edge.
       topPx.value = appTop + Math.max(headerH / 2, topGapPx.value + stripH / 2);
+      // The band: strip bottom edge plus one more gap — the lowest line a
+      // bottom sheet may reach while the strip is up.
+      publishBand(topPx.value + stripH / 2 + topGapPx.value);
     }
 
     /** Viewport fence, in the strip's OWN px. The stylesheet cap is
@@ -524,6 +550,9 @@ export default defineComponent({
           menuOpen.value = false;
           revealed.value = null;
           hiddenCount.value = 0;
+          // The band is the strip's live promise to the sheet family: with
+          // the strip gone the host's own static token rules again.
+          publishBand(null);
         }
       },
       { immediate: true },
@@ -553,6 +582,9 @@ export default defineComponent({
       if (handle) handle.disconnect();
       window.removeEventListener("resize", onViewportChange);
       releaseClone();
+      // A mounted-but-gone strip must not leave its band behind: the host's
+      // static token rules again (same contract as the visible flip).
+      publishBand(null);
     });
 
     const itemClass = (crumb: Crumb) =>

package/src/components/HkSectionCard.scss

@@ -0,0 +1,22 @@
+/* HkSectionCard — the standard titled section: heading + hint above one
+ * card. The ONLY spacing definition for that anatomy; consumers must not
+ * add their own margins/wrappers around it (2026-10-05 unification: two
+ * tabs of one page had drifted apart in hint position and body padding). */
+.hk-section-card {
+  display: flex;
+  flex-direction: column;
+  /* Heading block → body. One token, both axes of the rhythm (the header
+     carries its own 4px title→hint gap). */
+  gap: var(--space-12, 0.75rem);
+  min-width: 0;
+}
+
+/* Trailing notes under the card (the section's own footnote slot). No font
+   override: a footer may carry prose or a control — it only owns the
+   rhythm, so consumers stop inventing their own top margin. */
+.hk-section-card-footer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4, 0.25rem);
+  min-width: 0;
+}

package/src/components/HkSectionCard.styles.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Style contract (house pattern: HkAboutModal.styles.test.ts) — the
+ * section card's class↔rule wiring. `sheetCompile.test.ts` proves every
+ * sheet COMPILES; nothing else proves the classes the component emits are
+ * the ones the sheet styles, so a rename on either side would silently
+ * orphan the rule (the #493 failure mode).
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const tsx = readFileSync(join(here, "HkSectionCard.tsx"), "utf-8");
+const scss = readFileSync(join(here, "HkSectionCard.scss"), "utf-8");
+
+/** Every `hk-section-card*` class the component emits. */
+function emittedClasses(): string[] {
+  const found = new Set<string>();
+  for (const m of tsx.matchAll(/"(hk-section-card[a-z-]*)"/g)) found.add(m[1]!);
+  for (const m of tsx.matchAll(/\bhk-section-card[a-z-]*\b/g)) found.add(m[0]);
+  return [...found].sort();
+}
+
+describe("HkSectionCard styles", () => {
+  it("emits at least the wrapper and the footer (the guard is not vacuous)", () => {
+    const classes = emittedClasses();
+    expect(classes).toContain("hk-section-card");
+    expect(classes).toContain("hk-section-card-footer");
+  });
+
+  it("styles every class the component emits", () => {
+    for (const cls of emittedClasses()) {
+      expect(scss, `${cls} must have a rule`).toMatch(new RegExp(`\\.${cls}\\s*\\{`));
+    }
+  });
+
+  it("keeps the intra-section rhythm token on the wrapper and the footer", () => {
+    expect(scss).toMatch(/\.hk-section-card\s*\{[^}]*gap:\s*var\(--space-12/);
+    expect(scss).toMatch(/\.hk-section-card-footer\s*\{[^}]*gap:\s*var\(--space-4/);
+  });
+});

package/src/components/HkSectionCard.test.tsx

@@ -0,0 +1,156 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import { HkSectionCard } from "./HkSectionCard";
+
+/**
+ * HkSectionCard contract — the section-level chrome standard:
+ * - the heading block carries the title and the hint (its ONLY place: the
+ *   drift this component exists to end was one section printing its hint
+ *   above the table and another below it)
+ * - the body is ONE card: flush for tables (padded default false), padded
+ *   when the body is not a table
+ * - `error` replaces the body with an alert and `loading` with a spinner,
+ *   both inside a PADDED card — a state is content, not a table
+ * - the optional `actions` slot reaches the header (the heading row's
+ *   trailing affordances), not the card
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+function mountCard(props: Record<string, unknown>, slots: Record<string, () => unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () => h(HkSectionCard, props as never, slots as never),
+  });
+  mounts.push({ app, container });
+  app.mount(container);
+  return container;
+}
+
+describe("HkSectionCard", () => {
+  it("renders the title and the hint in the heading block, above the card", () => {
+    const c = mountCard({ title: "Public domains", hint: "Where this instance is reachable." }, {
+      default: () => h("table", { class: "body-table" }, h("tbody")),
+    });
+    const header = c.querySelector(".hk-section-header")!;
+    expect(header.textContent).toContain("Public domains");
+    expect(header.textContent).toContain("Where this instance is reachable.");
+    // The hint belongs to the HEADER, never to the card body.
+    const card = c.querySelector(".hk-card")!;
+    expect(card.textContent).not.toContain("Where this instance is reachable.");
+    expect(card.querySelectorAll(".body-table")).toHaveLength(1);
+    // Header precedes the card in document order (the one rhythm).
+    expect(header.compareDocumentPosition(card) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  it("keeps a table body flush in the card and pads a non-table body on request", () => {
+    const flush = mountCard({ title: "T" }, { default: () => h("span", "row") });
+    // HkCard spells "no padding" as a body modifier — the body carries the
+    // padding decision, not the card shell.
+    expect(flush.querySelector(".hk-card-body")!.className).toContain("hk-card-body-unpadded");
+    const padded = mountCard({ title: "T", padded: true }, { default: () => h("span", "row") });
+    // HkCard carries the padding itself — no caller wrapper.
+    expect(padded.querySelector(".hk-card-body")!.className).not.toContain("hk-card-body-unpadded");
+  });
+
+  it("replaces the body with an alert on error, inside a padded card", () => {
+    const c = mountCard({ title: "T", error: "boom" }, { default: () => h("span", "row") });
+    expect(c.querySelector(".hk-alert")).not.toBeNull();
+    expect(c.textContent).toContain("boom");
+    expect(c.querySelector(".hk-card-body")!.className).not.toContain("hk-card-body-unpadded");
+    expect(c.textContent).not.toContain("row");
+  });
+
+  it("replaces the body with a centred spinner while loading", () => {
+    const c = mountCard({ title: "T", loading: true }, { default: () => h("span", "row") });
+    expect(c.querySelector(".hk-spinner")).not.toBeNull();
+    expect(c.querySelector(".hk-card-body")!.className).not.toContain("hk-card-body-unpadded");
+    expect(c.textContent).not.toContain("row");
+  });
+
+  it("lets error win when both error and loading are set", () => {
+    const c = mountCard({ title: "T", error: "boom", loading: true }, {
+      default: () => h("span", "row"),
+    });
+    expect(c.querySelector(".hk-alert")).not.toBeNull();
+    expect(c.querySelector(".hk-spinner")).toBeNull();
+    expect(c.textContent).toContain("boom");
+  });
+
+  it("forwards the description slot into the hint position", () => {
+    const c = mountCard({ title: "T" }, { description: () => h("span", "own hint") });
+    const header = c.querySelector(".hk-section-header")!;
+    expect(header.querySelector(".hk-section-header-description")!.textContent).toContain("own hint");
+    expect(c.querySelector(".hk-card")!.textContent).not.toContain("own hint");
+  });
+
+  it("forwards icon, level and dense to the heading", () => {
+    const Icon = () => h("svg", { class: "own-icon" });
+    const c = mountCard({ title: "T", icon: Icon, level: "h2", dense: true });
+    const header = c.querySelector(".hk-section-header")!;
+    expect(header.classList.contains("hk-section-header-dense")).toBe(true);
+    expect(header.querySelector("h2")).not.toBeNull();
+    expect(header.querySelector(".own-icon")).not.toBeNull();
+    const plain = mountCard({ title: "T" });
+    expect(plain.querySelector(".hk-section-header h3")).not.toBeNull();
+  });
+
+  it("forwards the actions slot into the heading row", () => {
+    const c = mountCard({ title: "T" }, { actions: () => h("button", { class: "hdr-act" }, "x") });
+    expect(c.querySelector(".hk-section-header")!.querySelector(".hdr-act")).not.toBeNull();
+    expect(c.querySelector(".hk-card")!.querySelector(".hdr-act")).toBeNull();
+  });
+
+  it("renders the footer under the card — and nothing when no footer is given", () => {
+    const c = mountCard({ title: "T" }, {
+      default: () => h("span", "row"),
+      footer: () => h("p", { class: "note" }, "keep this"),
+    });
+    const footer = c.querySelector(".hk-section-card-footer")!;
+    expect(footer.querySelector(".note")!.textContent).toBe("keep this");
+    // Under the CARD, not inside it, and after it in document order.
+    const card = c.querySelector(".hk-card")!;
+    expect(card.querySelector(".note")).toBeNull();
+    expect(card.compareDocumentPosition(footer) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+
+    const bare = mountCard({ title: "T" });
+    expect(bare.querySelector(".hk-section-card-footer")).toBeNull();
+  });
+
+  it("renders no empty header wrapper when only one of the two slots is given", () => {
+    // R3 finding: forwarding an absent slot as a function returning
+    // undefined left an empty `.hk-section-header-actions` /
+    // `.hk-section-header-description` node behind — and in the column-flex
+    // heading a zero-height item still eats a gap slot.
+    const actionsOnly = mountCard({ title: "T" }, { actions: () => h("button", "x") });
+    expect(actionsOnly.querySelector(".hk-section-header-actions")).not.toBeNull();
+    expect(actionsOnly.querySelector(".hk-section-header-description")).toBeNull();
+
+    const descriptionOnly = mountCard({ title: "T" }, { description: () => h("span", "hint") });
+    expect(descriptionOnly.querySelector(".hk-section-header-description")).not.toBeNull();
+    expect(descriptionOnly.querySelector(".hk-section-header-actions")).toBeNull();
+
+    const neither = mountCard({ title: "T" });
+    expect(neither.querySelector(".hk-section-header-actions")).toBeNull();
+    expect(neither.querySelector(".hk-section-header-description")).toBeNull();
+  });
+
+  it("carries the count into the title and renders no hint paragraph when none is given", () => {
+    const c = mountCard({ title: "T", count: "3" });
+    expect(c.querySelector(".hk-section-header-count")!.textContent).toBe("3");
+    expect(c.querySelector(".hk-section-header-description")).toBeNull();
+  });
+});

package/src/components/HkSectionCard.tsx

@@ -0,0 +1,122 @@
+import { defineComponent, type Component, type PropType } from "vue";
+
+import HkAlert from "./HkAlert";
+import HkCard from "./HkCard";
+import { HkSectionHeader } from "./HkSectionHeader";
+import HkSpinner from "./HkSpinner";
+import "./HkSectionCard.scss";
+
+/**
+ * HkSectionCard — the standard titled SECTION: a heading (with an optional
+ * hint line) above ONE card that carries the body.
+ *
+ * This is the section-level twin of the page-level scaffold
+ * (`HkAdminTablePage`): a page whose content is several lists (settings
+ * categories, tab panels, dashboards) renders each as an HkSectionCard, so
+ * the heading→body rhythm, the hint typography and the body padding come
+ * from ONE definition instead of every caller hand-rolling `mt-3`,
+ * `p-4`/`padded={false}` wrappers and its own hint classes — the drift the
+ * 2026-10-05 audit found between two tabs of the same page (one table flush
+ * in the card with its hint above, the other wrapped in a padded div with
+ * its hint below).
+ *
+ * The body states follow `HkAdminTablePage`'s contract: `error` replaces
+ * the body with an alert, `loading` with a centred spinner — both inside a
+ * PADDED card (a state is content, not a table), while the normal body
+ * honours `padded` (default false: tables carry their own cell padding and
+ * sit flush in the card). `error` wins when both are set, as on the
+ * scaffold.
+ *
+ * The section owns the INTRA-section rhythm only (heading block → card). The
+ * page owns the gap BETWEEN sections: several siblings on one page need the
+ * parent's own `gap` (a flex/grid column), because this component adds no
+ * outer margin by design — otherwise a page that renders three sections
+ * would stack them flush.
+ *
+ * A `footer` slot renders trailing notes under the card (placeholder
+ * grammars, "what this list feeds" details) with the same rhythm, so those
+ * notes stop being a per-consumer margin.
+ *
+ * One deliberate difference from the scaffold: `loading` replaces the body
+ * whenever it is true, where `HkAdminTablePage` only replaces an EMPTY body
+ * (`loading && !rows.length`) and keeps populated rows on screen through a
+ * refresh. A section therefore passes `loading` for its FIRST load, not for
+ * every refetch — or it blanks a table the user is reading.
+ *
+ * ```tsx
+ * <HkSectionCard title={t("…")} hint={t("…")} loading={loading}>
+ *   <HkTable columns={columns} rows={rows} rowKey="id">{…}</HkTable>
+ * </HkSectionCard>
+ * ```
+ */
+export const HkSectionCard = defineComponent({
+  name: "HkSectionCard",
+  props: {
+    title: { type: String, required: true },
+    /** Explanatory line under the heading — the standard place for the
+     *  "what this list is for" copy every section used to spell its own. */
+    hint: { type: String, default: undefined },
+    icon: { type: [Object, Function] as PropType<Component>, default: undefined },
+    /** Heading level only; the visual size is fixed by the header styles. */
+    level: { type: String as PropType<"h2" | "h3" | "div">, default: "h3" },
+    /** Trailing count beside the title (e.g. "3"). */
+    count: { type: String, default: undefined },
+    /** Tighter header spacing for dense panels. */
+    dense: { type: Boolean, default: false },
+    /** Hard failure: replaces the body with an alert. */
+    error: { type: String, default: undefined },
+    /** In-flight: replaces the body with a centred spinner. */
+    loading: { type: Boolean, default: false },
+    /** Body padding for non-table content (tables stay flush). */
+    padded: { type: Boolean, default: false },
+  },
+  setup(props, { slots }) {
+    return () => {
+      const state = props.error ? "error" : props.loading ? "loading" : "body";
+      // Hoisted to an identifier: the CONDITIONAL inline form
+      // (`{slots.actions ? { actions: … } : undefined}` as children) lands in
+      // a child array, where the plain object is no longer normalized to
+      // slots and the button silently disappears. Hoisting fixes it; the
+      // bare inline literal happens to work, which is exactly why the
+      // conditional one is a trap.
+      // Each slot is spread CONDITIONALLY: forwarding an absent one as a
+      // function that returns undefined defeats HkSectionHeader's own
+      // empty-node guard, which renders an empty wrapper (and, in the
+      // column-flex heading, a phantom gap slot) — a whitespace-only
+      // regression the R3 review caught.
+      const headerSlots =
+        slots.actions || slots.description
+          ? {
+              ...(slots.actions ? { actions: () => slots.actions?.() } : {}),
+              ...(slots.description ? { description: () => slots.description?.() } : {}),
+            }
+          : undefined;
+      return (
+        <section class="hk-section-card">
+          <HkSectionHeader
+            title={props.title}
+            description={props.hint}
+            icon={props.icon}
+            level={props.level}
+            count={props.count}
+            dense={props.dense}
+          >
+            {headerSlots}
+          </HkSectionHeader>
+          <HkCard padded={state === "body" ? props.padded : true}>
+            {state === "error" ? (
+              <HkAlert message={props.error!} />
+            ) : state === "loading" ? (
+              <HkSpinner center />
+            ) : (
+              slots.default?.()
+            )}
+          </HkCard>
+          {slots.footer ? <div class="hk-section-card-footer">{slots.footer()}</div> : null}
+        </section>
+      );
+    };
+  },
+});
+
+export default HkSectionCard;

package/src/index.ts

@@ -818,6 +818,8 @@ 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 { HkSectionCard } from "./components/HkSectionCard";
+export { HkSectionCard as HSectionCard } from "./components/HkSectionCard";
 export { default as HFilterBar } from "./components/HkFilterBar";
 export { HkShareBar as HkShareBar } from "./components/HkShareBar";
 export { HkSecretRevealModal as HkSecretRevealModal } from "./components/HkSecretRevealModal";