@celestia-island/hikari 0.55.331 → 0.55.334

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.331",
+  "version": "0.55.334",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",
@@ -62,23 +62,23 @@
     "prepublishOnly": "vue-tsc --noEmit"
   },
   "peerDependencies": {
-    "@types/three": "^*",
+    "@types/three": "^0.185",
     "three": "^0.185",
-    "vue": "^*"
+    "vue": "^3"
   },
   "dependencies": {
-    "@celestia-island/tairitsu-transport": "^0.2.0",
-    "@xterm/addon-fit": "^0.*",
+    "@celestia-island/tairitsu-transport": "^0.2",
+    "@xterm/addon-fit": "^0.11",
     "@xterm/addon-image": "^0.10.0-beta.301",
     "@xterm/xterm": "^6.1.0-beta.304",
-    "dompurify": "^*",
-    "highlight.js": "^*",
-    "lucide-vue-next": "^*",
-    "marked": "^*"
+    "dompurify": "^3",
+    "highlight.js": "^11",
+    "lucide-vue-next": "^1",
+    "marked": "^18"
   },
   "devDependencies": {
     "@types/node": "^*",
-    "@types/three": "^*",
+    "@types/three": "^0.185",
     "@vitejs/plugin-vue": "^*",
     "@vitejs/plugin-vue-jsx": "^*",
     "@vue/server-renderer": "^*",

package/src/components/HkProgressBar.scss

@@ -111,6 +111,57 @@
   background: rgb(var(--color-primary));
 }
 
+// ── overspend (max + overValue) ─────────────────────────────────────
+// The track grows to `max + overValue`: the main fill keeps the quota's
+// share, the overspend stretch takes the rest to the inline end, and the
+// 1px divider is CARVED out of the stretch's inline-start edge — the track
+// background shows through the seam. A painted line would need a colour of
+// its own (and could not sit correctly over the translucent track); the
+// carved gap is one geometry that also mirrors correctly in RTL.
+.hk-progress-bar-overspend {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  // Square on the seam side, rounded at the track's end: the 1px gap then
+  // reads as a divider over the whole track height instead of a lens
+  // between two round caps.
+  border-start-start-radius: 0;
+  border-end-start-radius: 0;
+  border-start-end-radius: var(--radius-full);
+  border-end-end-radius: var(--radius-full);
+  transition:
+    width var(--duration-normal) var(--ease-standard),
+    inset-inline-start var(--duration-normal) var(--ease-standard);
+
+  &-muted {
+    background: rgb(var(--color-muted));
+  }
+
+  &-danger {
+    background: rgb(var(--color-error));
+  }
+}
+
+// While an overspend stretch follows it, the main fill squares its
+// inline-end corners so the seam divider stays exactly 1px wide.
+.hk-progress-bar-track--overspend .hk-progress-bar-fill {
+  border-start-end-radius: 0;
+  border-end-end-radius: 0;
+}
+
+// Overspend caption ("超支 0.8 度"), riding the label row after the value.
+.hk-progress-bar-overspend-label {
+  margin-inline-start: var(--space-6);
+
+  &-muted {
+    color: rgb(var(--color-muted));
+  }
+
+  &-danger {
+    color: rgb(var(--color-error));
+  }
+}
+
 // Keyframes animate the logical inset so the sweep mirrors in RTL together
 // with the fill/secondary anchoring (LTR-identical).
 @keyframes hk-progress-indeterminate {
@@ -138,6 +189,7 @@
   // (house guard: the family bar-fill pattern).
   .hk-progress-bar-fill,
   .hk-progress-bar-secondary,
+  .hk-progress-bar-overspend,
   .hk-progress-bar-seg {
     transition: none;
   }

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

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * Source contract for the overspend stretch's look. vitest cannot see
+ * stylesheets (happy-dom loads no SCSS), so a deleted rule would leave the
+ * DOM geometry guards green while the stretch painted as another primary
+ * fill — the whole point of the second segment is that it reads as PAST
+ * quota.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkProgressBar.scss"), "utf8");
+
+/** The DECLARATIONS of a rule, comments stripped (a comment that names a
+ *  property must not satisfy a guard about it). */
+function ruleBlock(selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const head = new RegExp(`${escaped}\\s*\\{`).exec(scss);
+  if (!head) throw new Error(`no rule for ${selector}`);
+  // Nested SCSS blocks: walk braces to the matching close.
+  const open = head.index + head[0].length - 1;
+  let depth = 0;
+  let end = open;
+  for (; end < scss.length; end++) {
+    if (scss[end] === "{") depth += 1;
+    else if (scss[end] === "}") {
+      depth -= 1;
+      if (depth === 0) break;
+    }
+  }
+  return scss.slice(open + 1, end)
+    .split("\n")
+    .filter((line) => {
+      const t = line.trim();
+      return !t.startsWith("*") && !t.startsWith("/*") && !t.startsWith("//");
+    })
+    .join("\n");
+}
+
+describe("HkProgressBar overspend sheet contract", () => {
+  it("positions the stretch as an inline-end block on the stretched track", () => {
+    const rule = ruleBlock(".hk-progress-bar-overspend");
+    expect(rule).toMatch(/position:\s*absolute/);
+    // Logical anchoring — the stretch sits at the inline end in RTL too.
+    expect(scss).not.toMatch(/\.hk-progress-bar-overspend[^{]*\{[^}]*\b(?:left|right):/);
+  });
+
+  it("tones the stretch muted by default and error-toned for danger", () => {
+    const block = ruleBlock(".hk-progress-bar-overspend");
+    expect(block).toMatch(/&-muted\s*\{[^}]*background:\s*rgb\(var\(--color-muted\)\)/);
+    expect(block).toMatch(/&-danger\s*\{[^}]*background:\s*rgb\(var\(--color-error\)\)/);
+  });
+
+  it("squares both sides of the 1px seam so it reads as a divider", () => {
+    const block = ruleBlock(".hk-progress-bar-overspend");
+    expect(block).toMatch(/border-start-start-radius:\s*0/);
+    expect(block).toMatch(/border-end-start-radius:\s*0/);
+    const fill = ruleBlock(".hk-progress-bar-track--overspend .hk-progress-bar-fill");
+    expect(fill).toMatch(/border-start-end-radius:\s*0/);
+    expect(fill).toMatch(/border-end-end-radius:\s*0/);
+  });
+
+  it("moves with the family cadence and stops under reduced motion", () => {
+    const block = ruleBlock(".hk-progress-bar-overspend");
+    expect(block).toMatch(/transition:[\s\S]*width var\(--duration-normal\)/);
+    const media = /@media \(prefers-reduced-motion: reduce\) \{([\s\S]*?)\n\}/.exec(scss);
+    expect(media, "reduced-motion guard").not.toBeNull();
+    expect(media![1]!).toMatch(/\.hk-progress-bar-overspend[\s\S]*transition:\s*none/);
+  });
+
+  it("co-locates the caption with the value label row", () => {
+    const rule = ruleBlock(".hk-progress-bar-overspend-label");
+    expect(rule).toMatch(/margin-inline-start:\s*var\(--space-6\)/);
+    expect(rule).toMatch(/&-danger\s*\{[^}]*color:\s*rgb\(var\(--color-error\)\)/);
+  });
+});

package/src/components/HkProgressBar.test.tsx

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
-import { createApp, h } from "vue";
+import { createApp, h, nextTick } from "vue";
 
 import HkProgressBar from "./HkProgressBar";
 
@@ -84,3 +84,204 @@ describe("HkProgressBar single-value mode (backward compat)", () => {
     expect(c.querySelector(".hk-progress-bar-indeterminate")).not.toBeNull();
   });
 });
+
+/** Settled innerHTML of a fresh mount — the regression fixtures compare it. */
+async function renderHtml(props: Record<string, unknown>) {
+  const c = mount(props);
+  await nextTick();
+  return c.innerHTML;
+}
+
+function overspendBlock(c: HTMLElement): HTMLElement | null {
+  return c.querySelector<HTMLElement>(".hk-progress-bar-overspend");
+}
+
+/**
+ * The overspend block's inline geometry, split back into its numbers. The
+ * seam is the `+ 1px` / `- 1px` pair: the block starts one pixel past the
+ * quota edge and loses that pixel from its own width, so the visible
+ * divider is exactly 1px at any track width (and the pair always sums back
+ * to a full track when quota is exhausted).
+ */
+function overspendGeometry(c: HTMLElement) {
+  const block = overspendBlock(c);
+  expect(block, "overspend block").not.toBeNull();
+  const start = block!.style.getPropertyValue("inset-inline-start");
+  const width = block!.style.width;
+  const startMatch = /^calc\(([\d.]+)% \+ 1px\)$/.exec(start);
+  const widthMatch = /^calc\(([\d.]+)% - 1px\)$/.exec(width);
+  expect(startMatch, `start seam ${start}`).not.toBeNull();
+  expect(widthMatch, `width seam ${width}`).not.toBeNull();
+  return {
+    edge: Number.parseFloat(startMatch![1]!),
+    over: Number.parseFloat(widthMatch![1]!),
+  };
+}
+
+describe("HkProgressBar overspend mode (CONTRACT §9 fixtures)", () => {
+  it("0 — an empty bar grows no overspend block", () => {
+    const c = mount({ value: 0, max: 100 });
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("0%");
+    expect(overspendBlock(c)).toBeNull();
+    expect(c.querySelector(".hk-progress-bar-track--overspend")).toBeNull();
+  });
+
+  it("half — a half bar grows no overspend block", () => {
+    const c = mount({ value: 50, max: 100 });
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("50%");
+    expect(overspendBlock(c)).toBeNull();
+  });
+
+  it("full — exactly at quota there is still no overspend block", () => {
+    const c = mount({ value: 100, max: 100 });
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("100%");
+    expect(overspendBlock(c)).toBeNull();
+  });
+
+  it("over 1% — the quota edge keeps the fill and the stretch follows it", () => {
+    const c = mount({ value: 100, max: 100, overValue: 1 });
+    // Track total = 101: 100/101 keeps the quota edge, 1/101 is overspend.
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("99.0099%");
+    const g = overspendGeometry(c);
+    expect(g.edge).toBe(99.0099);
+    expect(g.over).toBe(0.9901);
+    expect(g.edge + g.over).toBeCloseTo(100, 4);
+    expect(overspendBlock(c)!.className).toContain("hk-progress-bar-overspend-muted");
+    expect(overspendBlock(c)!.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("over 50% — half again as much as quota, in the danger tone", () => {
+    const c = mount({ value: 100, max: 100, overValue: 50, overspendTone: "danger" });
+    // Track total = 150: 100/150 quota edge, 50/150 overspend.
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("66.6667%");
+    const g = overspendGeometry(c);
+    expect(g.edge).toBe(66.6667);
+    expect(g.over).toBe(33.3333);
+    expect(g.edge + g.over).toBeCloseTo(100, 4);
+    expect(overspendBlock(c)!.className).toContain("hk-progress-bar-overspend-danger");
+    expect(overspendBlock(c)!.className).not.toContain("hk-progress-bar-overspend-muted");
+  });
+
+  it("max=0 — a bar with no quota at all is entirely overspend", () => {
+    const c = mount({ value: 0, max: 0, overValue: 5 });
+    // No quota slice: total = overValue, so the fill is 0% and the stretch
+    // takes the whole track (minus the 1px seam).
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("0%");
+    const g = overspendGeometry(c);
+    expect(g.edge).toBe(0);
+    expect(g.over).toBe(100);
+  });
+
+  it("derives overValue when the value itself runs past max", () => {
+    const c = mount({ value: 105, max: 100 });
+    // total = 105: 100/105 quota edge, 5/105 overspend.
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("95.2381%");
+    const g = overspendGeometry(c);
+    expect(g.edge).toBe(95.2381);
+    expect(g.over).toBe(4.7619);
+  });
+
+  it("derives exactly what the clamped quota-card shape states explicitly", () => {
+    // chest's card passes value = min(used, quota) + overValue = used - quota;
+    // a caller handing the raw value must paint the same picture.
+    const derived = overspendGeometry(mount({ value: 105, max: 100 }));
+    const explicit = overspendGeometry(mount({ value: 100, max: 100, overValue: 5 }));
+    expect(derived).toEqual(explicit);
+    const card = overspendGeometry(mount({ value: 100, max: 100, overValue: 4 }));
+    expect(card.edge).toBe(96.1538);
+    expect(card.over).toBe(3.8462);
+  });
+
+  it("keeps the legacy fill when overValue is explicitly 0 even past max", () => {
+    const c = mount({ value: 140, max: 100, overValue: 0 });
+    expect(overspendBlock(c)).toBeNull();
+    expect((c.querySelector(".hk-progress-bar-fill") as HTMLElement).style.width).toBe("100%");
+  });
+
+  it("renders the caption with its tone beside the value label", () => {
+    const c = mount({
+      value: 100, max: 100, overValue: 2, showLabel: true,
+      overspendLabel: "超支 2.0 度", overspendTone: "danger",
+    });
+    expect(c.querySelector(".hk-progress-bar-label")!.textContent).toBe("100%超支 2.0 度");
+    const caption = c.querySelector(".hk-progress-bar-overspend-label")!;
+    expect(caption.textContent).toBe("超支 2.0 度");
+    expect(caption.className).toContain("hk-progress-bar-overspend-label-danger");
+  });
+
+  it("shows the caption alone when showLabel is off, and never without overspend", () => {
+    const alone = mount({ value: 100, max: 100, overValue: 1, overspendLabel: "超支 1.0 度" });
+    expect(alone.querySelector(".hk-progress-bar-overspend-label")!.textContent).toBe("超支 1.0 度");
+    // The value label itself stays off — only the caption row rendered.
+    expect(alone.querySelector(".hk-progress-bar-label")!.textContent).toBe("超支 1.0 度");
+
+    const dormant = mount({ value: 50, max: 100, overspendLabel: "超支 1.0 度" });
+    expect(dormant.querySelector(".hk-progress-bar-overspend-label")).toBeNull();
+  });
+
+  it("scales the secondary overlay onto the stretched track", () => {
+    const c = mount({ value: 100, max: 100, overValue: 50, secondary: 75 });
+    // secondary 75 of the stretched total 150 — not of the old 100 max.
+    expect((c.querySelector(".hk-progress-bar-secondary") as HTMLElement).style.width).toBe("50%");
+  });
+
+  it("ignores overspend in segmented mode (segments cannot exceed 100%)", () => {
+    const c = mount({ segments: [{ value: 50 }], overValue: 10 });
+    expect(overspendBlock(c)).toBeNull();
+    expect((c.querySelector(".hk-progress-bar-seg") as HTMLElement).style.width).toBe("50%");
+  });
+
+  it("ignores overspend on the indeterminate sweep (no quantity to overrun)", () => {
+    const c = mount({ overValue: 10 });
+    expect(c.querySelector(".hk-progress-bar-indeterminate")).not.toBeNull();
+    expect(overspendBlock(c)).toBeNull();
+  });
+
+  it("never emits NaN widths for a degenerate (non-positive) total", () => {
+    const c = mount({ value: 5, max: -10, overValue: 5 });
+    expect(overspendBlock(c)).toBeNull();
+    expect(c.innerHTML).not.toContain("NaN");
+  });
+});
+
+/**
+ * The no-overspend render must stay BYTE-identical to the pre-overspend
+ * implementation. These markup strings were recorded from master e6263f45
+ * (the commit this change branches from) BEFORE the component grew the
+ * overspend branch; the `<!---->` placeholders are Vue's own v-if anchors,
+ * so an extra conditional layer or a changed class list shows up here as a
+ * diff, not just as a "close enough" layout. That is the pixel-equivalence
+ * guard the contract asks for.
+ */
+describe("HkProgressBar no-overspend regression (byte-identical render)", () => {
+  const RECORDED: Array<[string, Record<string, unknown>, string]> = [
+    ["0", { value: 0, max: 100 },
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track"><!----><div class="hk-progress-bar-fill hk-progress-bar-fill-loading" style="width: 0%;"></div></div></div>'],
+    ["half", { value: 50, max: 100 },
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track"><!----><div class="hk-progress-bar-fill hk-progress-bar-fill-loading" style="width: 50%;"></div></div></div>'],
+    ["full", { value: 100, max: 100 },
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track"><!----><div class="hk-progress-bar-fill hk-progress-bar-fill-loading" style="width: 100%;"></div></div></div>'],
+    ["indeterminate", {},
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track"><div class="hk-progress-bar-indeterminate hk-progress-bar-indeterminate-loading"></div></div></div>'],
+    ["secondary + label + size + status", { value: 40, max: 100, secondary: 80, status: "done", size: "md", showLabel: true },
+      '<div class="hk-progress-bar" data-size="md"><span class="hk-progress-bar-label">40%</span><div class="hk-progress-bar-track"><div class="hk-progress-bar-secondary hk-progress-bar-secondary-done" style="width: 80%;"></div><div class="hk-progress-bar-fill hk-progress-bar-fill-done" style="width: 40%;"></div></div></div>'],
+    ["segments", { segments: [{ value: 30, color: "#f00" }, { value: 20, class: "b" }] },
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track hk-progress-bar-track--segments"><div class="hk-progress-bar-seg" style="width: 30%; background: #f00;"></div><div class="hk-progress-bar-seg b" style="width: 20%;"></div></div></div>'],
+    ["max=0 (the legacy NaN-width quirk stays put)", { value: 0, max: 0 },
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track"><!----><div class="hk-progress-bar-fill hk-progress-bar-fill-loading"></div></div></div>'],
+    ["custom label never leaks without showLabel", { value: 65, max: 100, label: "自定义" },
+      '<div class="hk-progress-bar" data-size="sm"><!----><div class="hk-progress-bar-track"><!----><div class="hk-progress-bar-fill hk-progress-bar-fill-loading" style="width: 65%;"></div></div></div>'],
+    ["xs + error status", { value: 12, max: 100, size: "xs", status: "error" },
+      '<div class="hk-progress-bar" data-size="xs"><!----><div class="hk-progress-bar-track"><!----><div class="hk-progress-bar-fill hk-progress-bar-fill-error" style="width: 12%;"></div></div></div>'],
+  ];
+
+  for (const [name, props, golden] of RECORDED) {
+    it(`renders exactly the pre-overspend markup: ${name}`, async () => {
+      expect(await renderHtml(props)).toBe(golden);
+    });
+  }
+
+  it("treats an explicit overValue: 0 as the legacy full bar", async () => {
+    expect(await renderHtml({ value: 140, max: 100, overValue: 0 })).toBe(RECORDED[2]![2]);
+  });
+});

package/src/components/HkProgressBar.tsx

@@ -1,9 +1,15 @@
-import { computed, defineComponent, type PropType } from "vue";
+import { computed, defineComponent, type PropType, type VNode } from "vue";
 
 import "./HkProgressBar.scss";
 
 type ProgressBarStatus = "loading" | "done" | "error";
 
+/**
+ * Tone of the overspend block: the muted track grey (default) or the
+ * error colour, for a window that is already meaningfully past quota.
+ */
+export type OverspendTone = "muted" | "danger";
+
 /**
  * One block of a segmented progress bar. `value` is a percentage (0-100);
  * blocks are laid left-to-right in order and their values must not sum
@@ -20,6 +26,19 @@ export interface HProgressBarSegment {
   class?: string;
 }
 
+/** Keep percentage widths stable across float noise (4 decimals ≈ 0.1px on a 1000px track). */
+const clampPct = (n: number) => Math.min(100, Math.max(0, n));
+const roundPct = (n: number) => Math.round(n * 1e4) / 1e4;
+
+interface OverspendGeometry {
+  /** The stretched track: `max + overValue`. */
+  total: number;
+  /** Quota-edge position, as a percentage of `total`. */
+  mainPct: number;
+  /** Overspend block width, as a percentage of `total`. */
+  overPct: number;
+}
+
 export default defineComponent({
   name: "HkProgressBar",
   props: {
@@ -37,6 +56,21 @@ export default defineComponent({
      * segments are present.
      */
     segments: { type: Array as PropType<HProgressBarSegment[]>, default: undefined },
+    /**
+     * Overspend amount, in the same unit as `value`/`max`: how far the
+     * measured quantity runs past `max`. Pass it explicitly when the caller
+     * clamps `value` itself (`value = min(used, quota)`, the quota-card
+     * shape); a `value` already past `max` derives `value - max` instead.
+     * `0` (or omitted) keeps the legacy single-fill bar untouched.
+     */
+    overValue: { type: Number, default: null },
+    /**
+     * Caption for the overspend stretch ("超支 0.8 度"). Rendered next to
+     * the value label while overspend is active, in the overspend tone.
+     */
+    overspendLabel: { type: String, default: undefined },
+    /** Overspend block tone; see {@link OverspendTone}. */
+    overspendTone: { type: String as PropType<OverspendTone>, default: "muted" },
   },
   setup(props) {
     const segmented = computed(() => props.segments != null);
@@ -46,9 +80,40 @@ export default defineComponent({
       return Math.min(100, Math.max(0, (props.value / props.max) * 100));
     });
 
+    /**
+     * Overspend geometry, or `null` on every legacy path.
+     *
+     * The track grows to `max + overValue` so the quota edge stays at a
+     * fixed visual share while the overspend stretch occupies the rest —
+     * the same reading the quota card needs (a bar at 100% of quota keeps
+     * filling, just in the muted "past quota" tone). Segments cannot sum
+     * past 100% and the indeterminate sweep has no quantity at all, so
+     * neither enters this path; `overValue: 0` does not either, which is
+     * what keeps the no-overspend render byte-identical to the legacy one.
+     */
+    const overspendGeometry = computed<OverspendGeometry | null>(() => {
+      if (segmented.value || props.value == null) return null;
+      const value = props.value;
+      const over = Math.max(0, props.overValue != null ? props.overValue : value - props.max);
+      if (!(over > 0)) return null;
+      const total = props.max + over;
+      // A degenerate max/over pair (negative or zero total) has no
+      // meaningful split — leave it to the legacy fill rather than emit
+      // NaN widths.
+      if (!(total > 0)) return null;
+      return {
+        total,
+        // Quota edge: the consumed amount capped at `max`, so a value past
+        // quota never paints past the divider.
+        mainPct: roundPct(clampPct((Math.min(value, props.max) / total) * 100)),
+        overPct: roundPct(clampPct((over / total) * 100)),
+      };
+    });
+
     const secondaryPct = computed(() => {
       if (props.secondary == null) return null;
-      return Math.min(100, Math.max(0, (props.secondary / props.max) * 100));
+      const total = overspendGeometry.value?.total ?? props.max;
+      return Math.min(100, Math.max(0, (props.secondary / total) * 100));
     });
 
     const displayLabel = computed(() => {
@@ -60,17 +125,56 @@ export default defineComponent({
       return `${Math.round(pct.value)}%`;
     });
 
+    const overspendCaption = computed(() =>
+      overspendGeometry.value != null && props.overspendLabel ? props.overspendLabel : null,
+    );
+
     const segWidth = (value: number) => `${Math.min(100, Math.max(0, value))}%`;
 
+    /**
+     * Label row. With no overspend caption this renders exactly the legacy
+     * `<span class="hk-progress-bar-label">label</span>` (one text child),
+     * or nothing at all — the byte-identity the regression fixture pins.
+     */
+    function renderLabel(): VNode | null {
+      if (!props.showLabel && overspendCaption.value == null) return null;
+      if (overspendCaption.value == null) {
+        return <span class="hk-progress-bar-label">{displayLabel.value}</span>;
+      }
+      return (
+        <span class="hk-progress-bar-label">
+          {props.showLabel ? displayLabel.value : ""}
+          <span
+            class={[
+              "hk-progress-bar-overspend-label",
+              `hk-progress-bar-overspend-label-${props.overspendTone}`,
+            ]}
+          >
+            {overspendCaption.value}
+          </span>
+        </span>
+      );
+    }
+
+    /** The secondary overlay (same node in both fill modes). */
+    function renderSecondary(): VNode | null {
+      if (secondaryPct.value == null) return null;
+      return (
+        <div
+          class={["hk-progress-bar-secondary", `hk-progress-bar-secondary-${props.status}`]}
+          style={{ width: `${secondaryPct.value}%` }}
+        />
+      );
+    }
+
     return () => (
       <div class="hk-progress-bar" data-size={props.size}>
-        {props.showLabel && (
-          <span class="hk-progress-bar-label">{displayLabel.value}</span>
-        )}
+        {renderLabel()}
         <div
           class={[
             "hk-progress-bar-track",
             segmented.value ? "hk-progress-bar-track--segments" : "",
+            overspendGeometry.value ? "hk-progress-bar-track--overspend" : "",
           ]}
         >
           {segmented.value ? (
@@ -84,23 +188,44 @@ export default defineComponent({
                 }}
               />
             ))
+          ) : overspendGeometry.value ? (
+            <>
+              {renderSecondary()}
+              <div
+                class={["hk-progress-bar-fill", `hk-progress-bar-fill-${props.status}`]}
+                style={{ width: `${overspendGeometry.value.mainPct}%` }}
+              />
+              {/*
+                The 1px divider is carved OUT of the overspend block's
+                inline-start edge rather than painted as its own line: the
+                track's background shows through the seam, so the separator
+                needs no colour of its own and the same geometry mirrors in
+                RTL. `calc` keeps the seam exactly 1px whatever the track
+                width; a sub-pixel overspend ends up 0 wide, which is the
+                honest picture of a sliver past quota.
+              */}
+              <div
+                class={[
+                  "hk-progress-bar-overspend",
+                  `hk-progress-bar-overspend-${props.overspendTone}`,
+                ]}
+                style={{
+                  insetInlineStart: `calc(${overspendGeometry.value.mainPct}% + 1px)`,
+                  width: `calc(${overspendGeometry.value.overPct}% - 1px)`,
+                }}
+                aria-hidden="true"
+              />
+            </>
+          ) : pct.value != null ? (
+            <>
+              {renderSecondary()}
+              <div
+                class={["hk-progress-bar-fill", `hk-progress-bar-fill-${props.status}`]}
+                style={{ width: `${pct.value}%` }}
+              />
+            </>
           ) : (
-            pct.value != null ? (
-              <>
-                {secondaryPct.value != null && (
-                  <div
-                    class={["hk-progress-bar-secondary", `hk-progress-bar-secondary-${props.status}`]}
-                    style={{ width: `${secondaryPct.value}%` }}
-                  />
-                )}
-                <div
-                  class={["hk-progress-bar-fill", `hk-progress-bar-fill-${props.status}`]}
-                  style={{ width: `${pct.value}%` }}
-                />
-              </>
-            ) : (
-              <div class={["hk-progress-bar-indeterminate", `hk-progress-bar-indeterminate-${props.status}`]} />
-            )
+            <div class={["hk-progress-bar-indeterminate", `hk-progress-bar-indeterminate-${props.status}`]} />
           )}
         </div>
       </div>

package/src/components/HkTooltip.scss

@@ -55,6 +55,35 @@
   }
 }
 
+/* Click-trigger confirm mode (trigger="click"): the bubble carries the
+   decision — its actions live inside it — so it must take pointer events,
+   unlike the hover annotation (pointer-transparent: it can never eat the
+   pointer that summoned it). Armed only while VISIBLE: the popup node
+   survives a close (lazy-mount contract), and an opacity-0 fixed box that
+   still hit-tests would swallow clicks in its last footprint. */
+.hk-tooltip-popup--click {
+  pointer-events: none;
+}
+
+.hk-tooltip-popup--click.hk-tooltip-visible {
+  pointer-events: auto;
+}
+
+/* In click mode `text` is the confirm title: weight it and give the body
+   below (the `content` slot) room, so the popup reads as a decision rather
+   than a one-line label. */
+.hk-tooltip-popup--click .hk-tooltip-content {
+  font-weight: 600;
+  margin-block-end: var(--space-6);
+}
+
+/* The dialog surface receives focus on open (tabIndex -1): a keyboard user
+   must see where focus went before Tabbing on to the actions. */
+.hk-tooltip-popup--click:focus-visible {
+  outline: 2px solid rgb(var(--color-primary));
+  outline-offset: 2px;
+}
+
 /* Light mode needs no override — the base rule above already is the
    light palette; only dark re-inks the popup. */
 [data-mode="dark"] .hk-tooltip-popup {

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

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * Source contract for the click-trigger confirm surface. vitest cannot see
+ * stylesheets, and the load-bearing bit is a NEGATIVE one: the hover bubble
+ * must stay pointer-transparent (it can never eat the pointer that summoned
+ * it), while the click popup must take events only while visible — the node
+ * survives a close, so an armed hidden box would swallow clicks in its last
+ * footprint.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkTooltip.scss"), "utf8");
+
+function ruleBlock(selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`${escaped}\\s*\\{([^}]*)\\}`).exec(scss);
+  if (!match) throw new Error(`no rule for ${selector}`);
+  return match[1]!
+    .split("\n")
+    .filter((line) => {
+      const t = line.trim();
+      return !t.startsWith("*") && !t.startsWith("/*") && !t.startsWith("//");
+    })
+    .join("\n");
+}
+
+describe("HkTooltip click-trigger sheet contract", () => {
+  it("keeps the hover bubble pointer-transparent (annotation, not a control)", () => {
+    expect(ruleBlock(".hk-tooltip-popup")).toMatch(/pointer-events:\s*none/);
+  });
+
+  it("arms pointer events on the click popup only while visible", () => {
+    expect(ruleBlock(".hk-tooltip-popup--click")).toMatch(/pointer-events:\s*none/);
+    expect(ruleBlock(".hk-tooltip-popup--click.hk-tooltip-visible")).toMatch(
+      /pointer-events:\s*auto/,
+    );
+  });
+
+  it("weights the confirm title and leaves the actions room", () => {
+    const rule = ruleBlock(".hk-tooltip-popup--click .hk-tooltip-content");
+    expect(rule).toMatch(/font-weight:\s*600/);
+    expect(rule).toMatch(/margin-block-end:\s*var\(--space-6\)/);
+  });
+
+  it("rings the focused dialog surface", () => {
+    const rule = ruleBlock(".hk-tooltip-popup--click:focus-visible");
+    expect(rule).toMatch(/outline:\s*2px solid rgb\(var\(--color-primary\)\)/);
+  });
+});

package/src/components/HkTooltip.test.tsx

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick } from "vue";
 
-import HkTooltip, { type HkTooltipSlotProps } from "./HkTooltip";
+import HkTooltip, { type HkTooltipConfirmSlotProps, type HkTooltipSlotProps } from "./HkTooltip";
 import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "../runtime/usePopupManager";
 
 /**
@@ -426,3 +426,250 @@ describe("HkTooltip anchoring", () => {
     expect(popup().style.width).toBe("max-content");
   });
 });
+
+/**
+ * Click-trigger confirm mode (`trigger="click"`): the chest billing flow
+ * needs the "this will overspend your window — continue?" decision attached
+ * to the confirm BUTTON, not to a radio. The hover tooltip stays exactly
+ * what it was; this mode adds an anchored dialog surface with actions.
+ */
+function mountClick(
+  props: Record<string, unknown> = {},
+  content?: (slotProps: HkTooltipConfirmSlotProps) => unknown,
+) {
+  const container = document.createElement("div");
+  (document.querySelector("#hk-overlay-root") ?? document.body).appendChild(container);
+  const defaultSlot = () =>
+    h("button", { class: "trigger-btn", type: "button" }, "确认");
+  const app = createApp({
+    render: () =>
+      h(
+        HkTooltip,
+        { trigger: "click", text: "确认继续？", ...props } as never,
+        content
+          ? {
+            default: defaultSlot,
+            content: (slotProps: HkTooltipConfirmSlotProps) => content(slotProps),
+          }
+          : { default: defaultSlot },
+      ),
+  });
+  app.mount(container);
+  const entry = { app, container };
+  mounts.push(entry);
+  return entry;
+}
+
+function triggerButton(container: HTMLElement): HTMLElement {
+  return container.querySelector<HTMLElement>(".trigger-btn")!;
+}
+
+describe("HkTooltip click-trigger confirm mode", () => {
+  it("opens on a trigger click (ignoring the hover delay) and toggles closed", async () => {
+    const { container } = mountClick({ delay: 5000 });
+    const btn = triggerButton(container);
+    btn.click();
+    await nextTick();
+    expect(popup().className).toContain("hk-tooltip-visible");
+    // The click is the intent — no 5s hover delay is waited out.
+    btn.click();
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("never opens on hover or focus, unlike the hover mode", async () => {
+    const { container } = mountClick();
+    wrapper(container).dispatchEvent(new MouseEvent("mouseenter"));
+    container
+      .querySelector(".hk-tooltip-trigger")!
+      .dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    await settle();
+    // Not even the lazy popup mount ran: the hover path is fully gated.
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+  });
+
+  it("renders the text title plus the slot body and two actions", async () => {
+    let cancelled = 0;
+    const { container } = mountClick({}, ({ close }) =>
+      h("div", { class: "confirm-body" }, [
+        h("button", { class: "cancel-btn", type: "button", onClick: () => { cancelled += 1; close(); } }, "取消"),
+        h("button", { class: "confirm-btn", type: "button" }, "继续"),
+      ]));
+    triggerButton(container).click();
+    await nextTick();
+    const p = popup();
+    expect(p.querySelector(".hk-tooltip-content")!.textContent).toBe("确认继续？");
+    expect(p.querySelectorAll(".confirm-body button")).toHaveLength(2);
+    expect((p.querySelector(".confirm-btn") as HTMLElement).textContent).toBe("继续");
+
+    (p.querySelector(".cancel-btn") as HTMLElement).click();
+    await nextTick();
+    expect(cancelled).toBe(1);
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("gives the trigger dialog affordances and the popup dialog semantics", async () => {
+    const { container } = mountClick();
+    const anchor = wrapper(container);
+    expect(anchor.getAttribute("aria-haspopup")).toBe("dialog");
+    expect(anchor.getAttribute("aria-expanded")).toBe("false");
+    // A hover tooltip describes; a click confirm does not (it opens a dialog).
+    expect(anchor.getAttribute("aria-describedby")).toBeNull();
+
+    triggerButton(container).click();
+    await nextTick();
+    const p = popup();
+    expect(p.getAttribute("role")).toBe("dialog");
+    expect(p.className).toContain("hk-tooltip-popup--click");
+    expect(p.getAttribute("tabindex")).toBe("-1");
+    // Focus lands on the dialog surface so a keyboard user Tabs to the
+    // actions, not around the trigger.
+    expect(document.activeElement).toBe(p);
+    const titleId = p.getAttribute("aria-labelledby");
+    expect(titleId).toBeTruthy();
+    expect(p.querySelector(".hk-tooltip-content")!.getAttribute("id")).toBe(titleId);
+    expect(anchor.getAttribute("aria-expanded")).toBe("true");
+  });
+
+  it("dismisses on an outside pointerdown but not on one inside the popup", async () => {
+    const { container } = mountClick();
+    triggerButton(container).click();
+    await nextTick();
+    const p = popup();
+
+    // A press on the actions must not dismiss before their click fires.
+    p.querySelector(".hk-tooltip-content")!.dispatchEvent(
+      new PointerEvent("pointerdown", { bubbles: true }),
+    );
+    await nextTick();
+    expect(popup().className).toContain("hk-tooltip-visible");
+
+    document.body.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("dismisses on Escape, consumes the key and returns focus to the trigger", async () => {
+    const { container } = mountClick();
+    const btn = triggerButton(container);
+    btn.focus();
+    btn.click();
+    await nextTick();
+    expect(document.activeElement).toBe(popup());
+
+    const esc = new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true });
+    document.dispatchEvent(esc);
+    await nextTick();
+    await nextTick();
+    expect(esc.defaultPrevented).toBe(true);
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+    expect(document.activeElement).toBe(btn);
+  });
+
+  it("hands focus back from the slot's close() too", async () => {
+    const { container } = mountClick({}, ({ close }) =>
+      h("button", { class: "cancel-btn", type: "button", onClick: close }, "取消"));
+    const btn = triggerButton(container);
+    btn.focus();
+    btn.click();
+    await nextTick();
+    (popup().querySelector(".cancel-btn") as HTMLElement).click();
+    await nextTick();
+    await nextTick();
+    expect(document.activeElement).toBe(btn);
+  });
+
+  it("drops its document listeners when unmounted while open", async () => {
+    const entry = mountClick();
+    triggerButton(entry.container).click();
+    await nextTick();
+    entry.app.unmount();
+    mounts.splice(mounts.indexOf(entry), 1);
+    entry.container.remove();
+    // A stale listener would touch the detached popup ref; both gestures
+    // must be inert after unmount.
+    expect(() => {
+      document.body.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    }).not.toThrow();
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+  });
+
+  it("omits the empty title block when the slot owns the whole body", async () => {
+    const { container } = mountClick({ text: "" }, ({ close }) =>
+      h("div", { class: "confirm-body" }, [
+        h("button", { class: "cancel-btn", type: "button", onClick: close }, "取消"),
+      ]));
+    triggerButton(container).click();
+    await nextTick();
+    const p = popup();
+    // No text → no padded title block, and therefore no dangling
+    // aria-labelledby either; the slot body carries the popup.
+    expect(p.querySelector(".hk-tooltip-content")).toBeNull();
+    expect(p.getAttribute("aria-labelledby")).toBeNull();
+    expect(p.querySelector(".confirm-body")).not.toBeNull();
+  });
+
+  it("leaves the hover tooltip's shape untouched (no click affordances)", async () => {
+    const { container } = mount({ text: "hover tip", delay: 0 });
+    const anchor = wrapper(container);
+    expect(anchor.hasAttribute("aria-haspopup")).toBe(false);
+    expect(anchor.hasAttribute("aria-expanded")).toBe(false);
+    enter(container);
+    await settle();
+    const p = popup();
+    expect(p.getAttribute("role")).toBe("tooltip");
+    expect(p.className).not.toContain("hk-tooltip-popup--click");
+    expect(p.hasAttribute("tabindex")).toBe(false);
+    expect(p.querySelector(".hk-tooltip-content")!.textContent).toBe("hover tip");
+    // The describedby contract stays the hover one.
+    expect(anchor.getAttribute("aria-describedby")).toBe(p.getAttribute("id"));
+    leave(container);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+});
+
+describe("HkTooltip closed-popup reachability (R2 S2)", () => {
+  it("keeps a closed click popup's actions out of the tab order (inert)", async () => {
+    const { container } = mountClick({}, ({ close }) =>
+      h("div", { class: "confirm-body" }, [
+        h("button", { class: "cancel-btn", type: "button", onClick: close }, "取消"),
+        h("button", { class: "confirm-btn", type: "button" }, "继续"),
+      ]));
+    triggerButton(container).click();
+    await nextTick();
+    const p = popup();
+    // Open: the actions are real tab stops.
+    expect(p.hasAttribute("inert")).toBe(false);
+    expect(document.activeElement).toBe(p);
+
+    (p.querySelector(".cancel-btn") as HTMLElement).click();
+    await nextTick();
+    // The node (and its buttons) survive the lazy-mount contract — that is
+    // exactly why the reachability gate has to live on the popup itself…
+    expect(popup()).toBe(p);
+    expect(p.querySelector(".confirm-btn")).not.toBeNull();
+    expect(p.className).not.toContain("hk-tooltip-visible");
+    // …and a closed confirm surface must leave both the tab order and the
+    // a11y tree, or a keyboard user tabs into an invisible "继续".
+    expect(p.hasAttribute("inert")).toBe(true);
+  });
+
+  it("leaves the hover tooltip non-inert (it has no actions to hide)", async () => {
+    const { container } = mount({ text: "hover tip", delay: 0 });
+    enter(container);
+    await settle();
+    expect(popup().hasAttribute("inert")).toBe(false);
+    leave(container);
+    await nextTick();
+    expect(popup().hasAttribute("inert")).toBe(false);
+  });
+
+  it("stays silent for a text-less hover trigger (no empty bubble)", async () => {
+    const { container } = mount({ text: "", delay: 0 });
+    enter(container);
+    await settle();
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+  });
+});

package/src/components/HkTooltip.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, onBeforeUnmount, ref, Teleport, type CSSProperties, type PropType, type SlotsType } from "vue";
+import { computed, defineComponent, nextTick, onBeforeUnmount, ref, Teleport, type CSSProperties, type PropType, type SlotsType } from "vue";
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { applyTooltipPosition, type TooltipPlacement } from "../runtime/tooltipPosition";
 import { armTouchHint } from "../runtime/touchHint";
@@ -17,29 +17,69 @@ export interface HkTooltipSlotProps {
   visible: boolean;
 }
 
+/**
+ * The `content` slot payload — the click-trigger confirm body.
+ *
+ * `close()` hides the popup and hands focus back to the trigger; wire it to
+ * both actions (cancel and confirm) so one decision ends the popup. The
+ * caller keeps ownership of what "confirm" DOES — this component only owns
+ * the confirm surface, never the side effect.
+ */
+export interface HkTooltipConfirmSlotProps {
+  close: () => void;
+}
+
+/** Hover hints follow the pointer; click popups own an explicit decision. */
+export type TooltipTrigger = "hover" | "click";
+
 let popupSeq = 0;
 
 export default defineComponent({
   name: "HkTooltip",
   props: {
-    text: { type: String, required: true },
+    /** The hint/caption text. In click mode it is the confirm popup's title;
+     *  omit it when a `content` slot carries its own heading. */
+    text: { type: String, default: "" },
     placement: { type: String as PropType<TooltipPlacement>, default: "top" },
     delay: { type: Number, default: 300 },
     maxWidth: { type: String, default: undefined },
+    /**
+     * `"hover"` (default) is the classic annotation: shows on hover/focus
+     * after `delay`, hides on leave, never takes pointer events.
+     *
+     * `"click"` turns the same anchored bubble into an explicit-decision
+     * surface: the trigger's click toggles it, no hover/focus path opens or
+     * closes it, the popup takes pointer events (so it can hold buttons),
+     * outside pointerdown and Escape dismiss it, and focus moves into it on
+     * open and back to the trigger on an Escape/`close()` dismissal. This is
+     * the "are you sure?" shape a confirm-on-submit flow needs; `delay` is
+     * ignored in this mode.
+     */
+    trigger: { type: String as PropType<TooltipTrigger>, default: "hover" },
   },
   slots: Object as SlotsType<{
     default?: (props: HkTooltipSlotProps) => unknown;
+    /** Click mode: the popup body below `text` (actions included). */
+    content?: (props: HkTooltipConfirmSlotProps) => unknown;
   }>,
   setup(props, { slots }) {
     const visible = ref(false);
+    const clickMode = computed(() => props.trigger === "click");
     // Stable id for the aria-describedby link from the trigger wrapper to
     // the popup (set while the popup is visible, mirroring the tooltip
     // bridge's contract).
     const popupId = `hk-tooltip-${++popupSeq}`;
+    const titleId = `${popupId}-title`;
     const wrapperRef = ref<HTMLElement | null>(null);
     const popupRef = ref<HTMLElement | null>(null);
     let showTimer: ReturnType<typeof setTimeout> | null = null;
     let positionFrame: number | null = null;
+    // Click mode owns its own dismissal wiring: listeners exist only while
+    // the popup is open, and the trigger focus is remembered so a dismissal
+    // decision can hand focus back.
+    let dismissPointer: ((event: PointerEvent) => void) | null = null;
+    let dismissEscape: ((event: KeyboardEvent) => void) | null = null;
+    let restoreFocusEl: HTMLElement | null = null;
 
     // The band handle and the popup DOM are both LAZY (dense-list contract,
     // 2026-10-05): a tooltip that is never engaged — the overwhelming
@@ -96,6 +136,14 @@ export default defineComponent({
     }
 
     function show() {
+      // Hover/focus entry only: the click-trigger wrapper passes NO
+      // hover/focus handlers at all (see the render below), so a confirm
+      // surface can never pop open from a pointer passing over it.
+      //
+      // `text` is optional now (click mode may title from it or not), so a
+      // text-less hover trigger must stay silent like the touch-hint path
+      // does — an empty bubble is a worse answer than no bubble.
+      if (!props.text.trim()) return;
       clearShowTimer();
       ensureEngaged();
       showTimer = setTimeout(() => {
@@ -104,13 +152,89 @@ export default defineComponent({
       }, props.delay);
     }
 
-    function hide() {
+    function detachDismissal() {
+      if (dismissPointer) {
+        document.removeEventListener("pointerdown", dismissPointer, true);
+        dismissPointer = null;
+      }
+      if (dismissEscape) {
+        document.removeEventListener("keydown", dismissEscape, true);
+        dismissEscape = null;
+      }
+    }
+
+    /**
+     * Click mode dismissal wiring, live only while the popup is open:
+     * - a pointerdown OUTSIDE both the trigger and the popup dismisses (an
+     *   outside click already moves focus elsewhere, so no focus hand-back);
+     * - Escape dismisses and hands focus back to the trigger, consuming the
+     *   key only when it actually closed the popup — the same one-press-one-
+     *   thing rule HkSelect uses for triggers hosted inside a dialog.
+     */
+    function attachDismissal() {
+      if (dismissPointer || dismissEscape) return;
+      dismissPointer = (event: PointerEvent) => {
+        const target = event.target as Node | null;
+        if (target == null) return;
+        // The actions and the trigger keep the popup open; the trigger's
+        // own click handler toggles it.
+        if (popupRef.value?.contains(target) || wrapperRef.value?.contains(target)) return;
+        hide();
+      };
+      dismissEscape = (event: KeyboardEvent) => {
+        if (event.key !== "Escape" || !visible.value) return;
+        event.preventDefault();
+        event.stopPropagation();
+        hide({ restoreFocus: true });
+      };
+      document.addEventListener("pointerdown", dismissPointer, true);
+      document.addEventListener("keydown", dismissEscape, true);
+    }
+
+    function hide(opts: { restoreFocus?: boolean } = {}) {
       clearShowTimer();
+      const wasVisible = visible.value;
       visible.value = false;
       stopPositionTracking();
       // A hide means the hover/focus gesture is over — a touch hint
       // armed in parallel (pen press while hovering) retires with it.
       cancelTouchHint();
+      detachDismissal();
+      const restore = opts.restoreFocus === true ? restoreFocusEl : null;
+      restoreFocusEl = null;
+      if (restore && wasVisible) {
+        // Hand focus back only when it still lives on the popup/trigger:
+        // a dismissal that already moved focus (outside click, caller
+        // navigation) must not yank it back.
+        const active = document.activeElement;
+        const stillOurs = active == null || active === document.body || active === restore
+          || popupRef.value?.contains(active) === true
+          || wrapperRef.value?.contains(active) === true;
+        if (stillOurs) nextTick(() => restore.focus());
+      }
+    }
+
+    /** Click mode: the trigger toggles the popup (open immediately). */
+    function onTriggerClick() {
+      if (visible.value) {
+        hide();
+        return;
+      }
+      clearShowTimer();
+      ensureEngaged();
+      visible.value = true;
+      trackPositionWhileVisible();
+      // A keyboard activation must land on the actions rather than staying
+      // on the trigger; remember the origin for the focus hand-back.
+      const active = document.activeElement;
+      restoreFocusEl = active instanceof HTMLElement ? active : null;
+      attachDismissal();
+      nextTick(() => popupRef.value?.focus());
+    }
+
+    /** The confirm slot's `close`: dismiss and hand focus back. */
+    function closeFromPopup() {
+      hide({ restoreFocus: true });
     }
 
     function clearShowTimer() {
@@ -146,6 +270,9 @@ export default defineComponent({
     }
 
     function onPointerdown(e: PointerEvent) {
+      // Click mode owns touch too: a tap opens the confirm popup, so the
+      // long-press hint bar would be a second, conflicting surface.
+      if (clickMode.value) return;
       if (e.pointerType !== "touch" && e.pointerType !== "pen") return;
       if (!props.text.trim()) return; // nothing to hint
       lastTouchAt = performance.now();
@@ -165,6 +292,7 @@ export default defineComponent({
       clearShowTimer();
       stopPositionTracking();
       cancelTouchHint();
+      detachDismissal();
       if (popupHandle) {
         manager.unregister(popupHandle.id);
         popupHandle = null;
@@ -174,6 +302,7 @@ export default defineComponent({
     const tooltipCls = computed(() => [
       "hk-tooltip-popup",
       `hk-tooltip-${props.placement}`,
+      clickMode.value ? "hk-tooltip-popup--click" : "",
       visible.value ? "hk-tooltip-visible" : "",
     ]);
 
@@ -184,23 +313,53 @@ export default defineComponent({
       zIndex.value != null ? { zIndex: zIndex.value } : {},
     );
 
+    /**
+     * Popup children as an array: absent halves must not leave a comment
+     * placeholder behind, so the hover tooltip's DOM stays exactly the
+     * pre-click-mode shape (the `content` slot is click mode only).
+     */
+    function popupChildren(): unknown[] {
+      const kids: unknown[] = [];
+      // A text-only tooltip keeps its content block even when `text` is
+      // empty (the legacy bubble); with a `content` slot and no text the
+      // slot owns the body and an empty padded block would be dead space.
+      if (props.text !== "" || !slots.content) {
+        kids.push(
+          <div class="hk-tooltip-content" id={clickMode.value ? titleId : undefined}>
+            {props.text}
+          </div>,
+        );
+      }
+      if (slots.content) kids.push(slots.content({ close: closeFromPopup }));
+      return kids;
+    }
+
     return () => (
       <span
         ref={wrapperRef}
         class="hk-tooltip-wrapper"
         data-position={props.placement}
-        aria-describedby={visible.value ? popupId : undefined}
+        // Hover hints describe their trigger; a click confirm announces the
+        // dialog it will open instead.
+        aria-describedby={!clickMode.value && visible.value ? popupId : undefined}
+        aria-haspopup={clickMode.value ? "dialog" : undefined}
+        aria-expanded={clickMode.value ? visible.value : undefined}
+        onClick={clickMode.value ? onTriggerClick : undefined}
         onPointerdown={onPointerdown}
-        onMouseenter={() => {
-          // Synthetic mouseenter right after a touch press must not
-          // flash the anchored popup the touch mode never shows — the
-          // top hint bar owns touch.
-          if (performance.now() - lastTouchAt < 600) return;
-          show();
-        }}
-        onMouseleave={hide}
-        onFocusin={show}
-        onFocusout={hide}
+        onMouseenter={
+          clickMode.value
+            ? undefined
+            : () => {
+              // Synthetic mouseenter right after a touch press must not
+              // flash the anchored popup the touch mode never shows — the
+              // top hint bar owns touch.
+              if (performance.now() - lastTouchAt < 600) return;
+              show();
+            }
+        }
+        onMouseleave={clickMode.value ? undefined : () => hide()}
+        onFocusin={clickMode.value ? undefined : show}
+        onFocusout={clickMode.value ? undefined : () => hide()}
       >
         <span class="hk-tooltip-trigger">
           {slots.default?.({ popupId, visible: visible.value })}
@@ -210,11 +369,21 @@ export default defineComponent({
             <div
               ref={popupRef}
               id={popupId}
-              role="tooltip"
+              role={clickMode.value ? "dialog" : "tooltip"}
               class={tooltipCls.value}
               style={popupStyle.value}
+              // Click mode keeps the popup node mounted after a close (lazy
+              // contract), but its actions must not stay reachable: an
+              // invisible button is still a tab stop and still speaks. `inert`
+              // is the platform's own "out of the tab order and out of the
+              // a11y tree" switch, armed exactly while the popup is closed.
+              inert={clickMode.value ? !visible.value : undefined}
+              // A dialog surface takes focus so keyboard users land on the
+              // actions (the slot's buttons are the next Tab stops).
+              tabindex={clickMode.value ? -1 : undefined}
+              aria-labelledby={clickMode.value && props.text !== "" ? titleId : undefined}
             >
-              <div class="hk-tooltip-content">{props.text}</div>
+              {popupChildren()}
             </div>
           )}
         </Teleport>

package/src/index.ts

@@ -874,7 +874,11 @@ export { default as HkToast } from "./components/HkToast";
 export { default as HkPersistentToast, type PersistentToastTone } from "./components/HkPersistentToast";
 export { default as HkPersistentToastGroup } from "./components/HkPersistentToastGroup";
 export { default as HkTooltip } from "./components/HkTooltip";
-export { type HkTooltipSlotProps } from "./components/HkTooltip";
+export {
+  type HkTooltipConfirmSlotProps,
+  type HkTooltipSlotProps,
+  type TooltipTrigger,
+} from "./components/HkTooltip";
 export { default as HkTree } from "./components/HkTree";
 export { default as HkWindowedItem } from "./components/HkWindowedItem";
 export { default as HkWaterfall } from "./components/HkWaterfall";