@celestia-island/hikari 0.55.87 → 0.55.89

package/package.json

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

package/src/components/HkFilterPanel.scss

@@ -0,0 +1,115 @@
+/**
+ * HkFilterPanel — the condition-row list inside the header filter
+ * affordance. Bounded on BOTH axes by design (user direction
+ * 2026-09-29): never too tall, never too wide, but never so narrow that
+ * the operator symbol group cannot fit — on phones the operator column
+ * narrows to roughly TWO visible symbols and scrolls horizontally
+ * instead.
+ *
+ * Row anatomy: [field label | operator symbol group | value control].
+ * Edits commit LIVE (the desktop panel has no confirm button); the
+ * mobile sheet's single confirm merely closes — the standard HkPopover
+ * sheetOnMobile split renders the same panel in both shapes.
+ */
+
+.hk-filter-panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+  /* Bounded width: wide enough for the operator group, narrow enough to
+   * read as a header dropdown (the popover host clamps to the viewport
+   * edge; this keeps the panel from stretching to meet it). */
+  width: clamp(21rem, 92vw, 27rem);
+  max-width: 100%;
+  /* Bounded height: ~7 rows of breathing room, then internal scroll —
+   * a field-rich page must not grow an unbounded dropdown. */
+  max-height: min(26rem, 60vh);
+  overflow-y: auto;
+  padding: var(--space-4, 0.25rem);
+}
+
+.hk-filter-panel-row {
+  display: grid;
+  grid-template-columns: minmax(4.5rem, auto) minmax(0, auto) minmax(0, 1fr);
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+}
+
+.hk-filter-panel-field {
+  font-size: var(--text-xs, 0.75rem);
+  color: rgb(var(--color-muted, var(--color-text-secondary)));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Operator symbol group: one glyph per toggle button. Scrolls
+ * horizontally when the kind's operator set (or a phone viewport)
+ * outgrows the column; scroll snapping keeps each symbol landing
+ * cleanly under the thumb. */
+.hk-filter-panel-ops {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2, 0.125rem);
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  scroll-snap-type: x proximity;
+  scrollbar-width: none;
+  padding: 1px;
+}
+
+.hk-filter-panel-op {
+  flex: 0 0 auto;
+  scroll-snap-align: center;
+  min-width: 1.75rem;
+  height: 1.75rem;
+  padding: 0 var(--space-6, 0.375rem);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  border-radius: var(--radius-sm, 6px);
+  background: transparent;
+  color: rgb(var(--color-muted, var(--color-text-secondary)));
+  font-size: var(--text-sm, 0.875rem);
+  line-height: 1;
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+.hk-filter-panel-op:hover {
+  background: rgb(var(--color-primary) / 12%);
+  color: rgb(var(--color-text));
+}
+
+.hk-filter-panel-op[aria-pressed="true"] {
+  background: rgb(var(--color-primary) / 18%);
+  color: rgb(var(--color-primary));
+  font-weight: 700;
+}
+
+.hk-filter-panel-op:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.hk-filter-panel-value {
+  min-width: 0;
+}
+
+/* Phones: the operator column narrows hard (about two symbols visible)
+ * and the row lets the value control take the remaining width. The
+ * group itself scrolls — same interaction, smaller footprint. */
+@media (max-width: 767px) {
+  .hk-filter-panel {
+    width: 100%;
+  }
+
+  .hk-filter-panel-row {
+    grid-template-columns: minmax(3.75rem, auto) minmax(3.9rem, auto) minmax(0, 1fr);
+  }
+
+  .hk-filter-panel-ops {
+    max-width: 4.25rem;
+  }
+}

package/src/components/HkFilterPanel.test.tsx

@@ -0,0 +1,152 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkFilterPanel, { sanitizeNumberInput, type HkFilterState } from "./HkFilterPanel";
+
+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 FIELDS = [
+  { key: "tool", label: "Tool", kind: "text" as const, placeholder: "web_automation" },
+  { key: "count", label: "Calls", kind: "number" as const },
+  { key: "agent", label: "Agent", kind: "select" as const, options: [{ value: "a1", label: "Agent One" }] },
+  { key: "since", label: "Since", kind: "date" as const },
+];
+
+describe("HkFilterPanel", () => {
+  it("renders one condition row per declared field", () => {
+    const c = mount(h(HkFilterPanel, { fields: FIELDS, modelValue: {} }));
+    const rows = c.querySelectorAll(".hk-filter-panel-row");
+    expect(rows).toHaveLength(FIELDS.length);
+    const labels = [...c.querySelectorAll(".hk-filter-panel-field")].map((el) => el.textContent);
+    expect(labels).toEqual(["Tool", "Calls", "Agent", "Since"]);
+  });
+
+  it("gives each kind its default operator set (regular 3, numeric 5, select 2, date 2)", () => {
+    const c = mount(h(HkFilterPanel, { fields: FIELDS, modelValue: {} }));
+    const rows = [...c.querySelectorAll(".hk-filter-panel-row")];
+    const opCounts = rows.map(
+      (row) => row.querySelectorAll(".hk-filter-panel-op").length,
+    );
+    // Regular = 3 (equals / not-equals / fuzzy); numeric = the ordered
+    // five with NO not-equals; select = equals / not-equals; date = the
+    // ordered pair.
+    expect(opCounts).toEqual([3, 5, 2, 2]);
+    // Symbols, not words: one glyph per button.
+    const numberOps = [...rows[1]!.querySelectorAll(".hk-filter-panel-op")].map(
+      (b) => b.textContent,
+    );
+    expect(numberOps).toEqual(["<", "≤", "=", "≥", ">"]);
+    // The kind's first operator is the pressed one for an untouched field.
+    const pressed = rows[0]!.querySelector('.hk-filter-panel-op[aria-pressed="true"]');
+    expect(pressed?.textContent).toBe("=");
+  });
+
+  it("emits a new state when an operator is picked (live, no confirm)", () => {
+    let seen: HkFilterState | null = null;
+    const c = mount(
+      h(HkFilterPanel, {
+        fields: FIELDS,
+        modelValue: { tool: { op: "eq", value: "web" } },
+        "onUpdate:modelValue": (s: HkFilterState) => (seen = s),
+      }),
+    );
+    const fuzzy = [...c.querySelectorAll(".hk-filter-panel-row")[0]!.querySelectorAll(".hk-filter-panel-op")]
+      .find((b) => b.textContent === "≈")!;
+    fuzzy.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(seen).not.toBeNull();
+    expect(seen!["tool"]).toEqual({ op: "approx", value: "web" });
+  });
+
+  it("renders numeric fields on the number-variant input (native legal-number filtering)", async () => {
+    let seen: HkFilterState | null = null;
+    const c = mount(
+      h(HkFilterPanel, {
+        fields: FIELDS,
+        modelValue: {},
+        "onUpdate:modelValue": (s: HkFilterState) => (seen = s),
+      }),
+    );
+    // The number row's control is the number-variant input (type=number —
+    // the browser refuses illegal keystrokes); the model side keeps the
+    // shape guard (sanitizeNumberInput) as the belt.
+    const input = c.querySelectorAll<HTMLInputElement>(".hk-filter-panel-row input")[1]!;
+    expect(input.type).toBe("number");
+    input.value = "42.5";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    await Promise.resolve();
+    expect(seen).not.toBeNull();
+    expect(seen!["count"]).toEqual({ op: "lt", value: "42.5" });
+  });
+
+  it("keeps select fields on a popup select and prepends the empty clear row", () => {
+    const c = mount(h(HkFilterPanel, { fields: FIELDS, modelValue: {} }));
+    const selectRow = c.querySelectorAll(".hk-filter-panel-row")[2]!;
+    expect(selectRow.querySelector(".hk-popup-select-trigger")).toBeTruthy();
+  });
+
+  it("prepends a localized empty All row to select fields without one (the clear affordance)", async () => {
+    // The select field's ONLY clear affordance is the empty value row —
+    // there is no reset verb in the header trigger. A page without its
+    // own "all" entry must therefore always find the prepended
+    // {value:"", label:All} row; a page that ships one keeps its own
+    // label. (R1 mutation f2 removed the prepend and NOTHING went red —
+    // this test is that missing pin.)
+    const withOwnEmpty = [
+      { key: "level", label: "Level", kind: "select" as const, options: [{ value: "", label: "Everything" }, { value: "high", label: "High" }] },
+    ];
+    const c = mount(h(HkFilterPanel, { fields: withOwnEmpty, modelValue: {} }));
+    // A page shipping its own empty row keeps it as-is (no duplicate):
+    // the panel prepends only when NO option carries the empty value.
+    const ownTrigger = c.querySelector(".hk-filter-panel-row .hk-popup-select-trigger");
+    expect(ownTrigger).toBeTruthy();
+    // Drive the popup open to count rows: the real HkPopupSelect renders
+    // exactly the options it was given.
+    ownTrigger!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    const items = [...document.body.querySelectorAll(".hk-popup-select-item")].map((el) => el.textContent?.trim());
+    expect(items).toEqual(["Everything", "High"]);
+    document.body.querySelectorAll(".hk-popup-select-item, .hk-select-popout-host").forEach((el) => el.remove());
+
+    const withoutAll = [
+      { key: "level", label: "Level", kind: "select" as const, options: [{ value: "high", label: "High" }] },
+    ];
+    const c2 = mount(h(HkFilterPanel, { fields: withoutAll, modelValue: {} }));
+    const trigger2 = c2.querySelector(".hk-filter-panel-row .hk-popup-select-trigger")!;
+    trigger2.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    const items2 = [...document.body.querySelectorAll(".hk-popup-select-item")].map((el) => el.textContent?.trim());
+    expect(items2[0], "the localized All row is prepended").toBe("All");
+    expect(items2).toEqual(["All", "High"]);
+    document.body.querySelectorAll(".hk-popup-select-item, .hk-select-popout-host").forEach((el) => el.remove());
+  });
+
+  it("marks the panel active when any condition carries a value", () => {
+    const c = mount(h(HkFilterPanel, { fields: FIELDS, modelValue: { count: { op: "gt", value: "3" } } }));
+    expect(c.querySelector(".hk-filter-panel")!.getAttribute("data-active")).toBe("true");
+    const c2 = mount(h(HkFilterPanel, { fields: FIELDS, modelValue: {} }));
+    expect(c2.querySelector(".hk-filter-panel")!.getAttribute("data-active")).toBeNull();
+  });
+
+  it("sanitizes number shapes: sign leading-only, one dot, junk stripped", () => {
+    expect(sanitizeNumberInput("12a.5b9")).toBe("12.59");
+    expect(sanitizeNumberInput("-3-x.1.2")).toBe("-3.12");
+    expect(sanitizeNumberInput("abc")).toBe("");
+    expect(sanitizeNumberInput("1-2")).toBe("12");
+  });
+});

package/src/components/HkFilterPanel.tsx

@@ -0,0 +1,198 @@
+import { computed, defineComponent, type PropType } from "vue";
+
+import HkInput from "./HkInput";
+import HkPopupSelect, { type HkPopupSelectOption } from "./HkPopupSelect";
+import { useI18n } from "../i18n/context";
+import "./HkFilterPanel.scss";
+
+/**
+ * Filter condition operators. The symbol IS the button (one glyph, one
+ * toggle — compact by design): the regular kinds get three (equals /
+ * not-equals / fuzzy), numeric fields get the ordered five (no
+ * not-equals), select fields narrow to equals / not-equals, and date
+ * fields bound with the ordered pair.
+ */
+export type HkFilterOperator = "eq" | "ne" | "approx" | "lt" | "lte" | "gte" | "gt";
+
+/** One filterable field a page declares for the panel. */
+export interface HkFilterFieldDef {
+  /** Condition key — stable, page-owned (maps to the RPC parameter). */
+  key: string;
+  label: string;
+  kind: "text" | "number" | "select" | "date";
+  /** select kind: the offered values. A leading "—" (empty value = no
+   *  filter) row is prepended when the page did not include one. */
+  options?: HkPopupSelectOption[];
+  /** Override the kind's default operator set. */
+  operators?: HkFilterOperator[];
+  placeholder?: string;
+}
+
+/** One condition: the operator and the (string) value. An EMPTY value
+ *  means the field filters nothing — this is also how a condition is
+ *  cleared (re-open the panel, empty the value; there is no separate
+ *  reset verb in the header affordance). */
+export interface HkFilterCondition {
+  op: HkFilterOperator;
+  value: string;
+}
+
+/** Per-field condition state, keyed by the field def's key. Fields the
+ *  record does not mention render with their kind's default operator and
+ *  an empty value. */
+export type HkFilterState = Record<string, HkFilterCondition>;
+
+const OPERATOR_SYMBOL: Record<HkFilterOperator, string> = {
+  eq: "=",
+  ne: "≠",
+  approx: "≈",
+  lt: "<",
+  lte: "≤",
+  gte: "≥",
+  gt: ">",
+};
+
+const OPERATOR_LABEL: Record<HkFilterOperator, { key: string; fallback: string }> = {
+  eq: { key: "hikari::filterPanel.op.eq", fallback: "equals" },
+  ne: { key: "hikari::filterPanel.op.ne", fallback: "not equals" },
+  approx: { key: "hikari::filterPanel.op.approx", fallback: "fuzzy match" },
+  lt: { key: "hikari::filterPanel.op.lt", fallback: "less than" },
+  lte: { key: "hikari::filterPanel.op.lte", fallback: "at most" },
+  gte: { key: "hikari::filterPanel.op.gte", fallback: "at least" },
+  gt: { key: "hikari::filterPanel.op.gt", fallback: "greater than" },
+};
+
+const DEFAULT_OPERATORS: Record<HkFilterFieldDef["kind"], HkFilterOperator[]> = {
+  text: ["eq", "ne", "approx"],
+  number: ["lt", "lte", "eq", "gte", "gt"],
+  select: ["eq", "ne"],
+  date: ["gte", "lte"],
+};
+
+/** Keep only a legal number shape: optional leading minus, digits, one
+ *  decimal point ("只允许输入合法数字" — the input filters the keystrokes
+ *  rather than clamping afterwards). The intermediate fragments "-",
+ *  "." and "-." survive deliberately: rejecting them mid-keystroke would
+ *  make typing a negative or a decimal impossible; no chest page ships a
+ *  number field yet, and one will want Number()-validation at the wire
+ *  boundary when the first does. */
+export function sanitizeNumberInput(raw: string): string {
+  let out = raw.replace(/[^-0-9.]/g, "");
+  // One minus, and only leading.
+  const hasMinus = out.startsWith("-");
+  out = out.replace(/-/g, "");
+  if (hasMinus) out = `-${out}`;
+  // One decimal point.
+  const firstDot = out.indexOf(".");
+  if (firstDot >= 0) {
+    out = out.slice(0, firstDot + 1) + out.slice(firstDot + 1).replace(/\./g, "");
+  }
+  return out;
+}
+
+export default defineComponent({
+  name: "HkFilterPanel",
+  props: {
+    fields: { type: Array as PropType<HkFilterFieldDef[]>, required: true },
+    modelValue: { type: Object as PropType<HkFilterState>, default: () => ({}) },
+    disabled: { type: Boolean, default: false },
+    /** Panel aria-label / heading context (defaults to "Filters"). */
+    label: { type: String, default: undefined },
+  },
+  emits: {
+    "update:modelValue": (_state: HkFilterState) => true,
+  },
+  setup(props, { emit }) {
+    const { t } = useI18n();
+
+    const operatorsFor = (field: HkFilterFieldDef): HkFilterOperator[] =>
+      field.operators ?? DEFAULT_OPERATORS[field.kind];
+
+    const conditionFor = (field: HkFilterFieldDef): HkFilterCondition =>
+      props.modelValue[field.key] ?? { op: operatorsFor(field)[0]!, value: "" };
+
+    function emitCondition(field: HkFilterFieldDef, patch: Partial<HkFilterCondition>) {
+      const next: HkFilterState = { ...props.modelValue };
+      next[field.key] = { ...conditionFor(field), ...patch };
+      emit("update:modelValue", next);
+    }
+
+    const selectOptions = (field: HkFilterFieldDef): HkPopupSelectOption[] => {
+      const options = field.options ?? [];
+      // The empty row IS the clear affordance for select fields (value ""
+      // filters nothing) — pages that ship their own "all" row keep it;
+      // otherwise a LOCALIZED all-row is prepended so an empty-seeded
+      // select reads as "no filter", not as a dash.
+      if (options.some((o) => o.value === "")) return options;
+      return [{ value: "", label: t("hikari::filterPanel.all", "All") }, ...options];
+    };
+
+    /** Active-count signal for the trigger's dot (also exported via the
+     *  panel's own render for testing). */
+    const activeCount = computed(
+      () => props.fields.filter((f) => conditionFor(f).value !== "").length,
+    );
+
+    return () => {
+      const label = props.label ?? t("hikari::filterBar.trigger", "Filters");
+      return (
+        <div class="hk-filter-panel" data-testid="hk-filter-panel" data-active={activeCount.value > 0 || undefined} aria-label={label}>
+          {props.fields.map((field) => {
+            const condition = conditionFor(field);
+            const ops = operatorsFor(field);
+            return (
+              <div key={field.key} class="hk-filter-panel-row" data-kind={field.kind}>
+                <span class="hk-filter-panel-field">{field.label}</span>
+                <div class="hk-filter-panel-ops" role="group" aria-label={`${field.label} — ${label}`}>
+                  {ops.map((op) => (
+                    <button
+                      key={op}
+                      type="button"
+                      class="hk-filter-panel-op"
+                      aria-pressed={condition.op === op}
+                      aria-label={t(OPERATOR_LABEL[op].key, OPERATOR_LABEL[op].fallback)}
+                      title={t(OPERATOR_LABEL[op].key, OPERATOR_LABEL[op].fallback)}
+                      disabled={props.disabled}
+                      onClick={() => emitCondition(field, { op })}
+                    >
+                      {OPERATOR_SYMBOL[op]}
+                    </button>
+                  ))}
+                </div>
+                <div class="hk-filter-panel-value">
+                  {field.kind === "select" ? (
+                    <HkPopupSelect
+                      modelValue={condition.value}
+                      onUpdate:modelValue={(v: string) => emitCondition(field, { value: v })}
+                      label={field.label}
+                      disabled={props.disabled}
+                      options={selectOptions(field)}
+                    />
+                  ) : (
+                    <HkInput
+                      type={field.kind === "date" ? "date" : "text"}
+                      variant={field.kind === "number" ? "number" : "text"}
+                      modelValue={condition.value}
+                      onUpdate:modelValue={(v: string) =>
+                        emitCondition(field, {
+                          // Belt over the browser's native number filtering:
+                          // the stored model keeps a clean number SHAPE only
+                          // (sign, digits, one dot), so pages can hand it to
+                          // RPC params verbatim.
+                          value: field.kind === "number" ? sanitizeNumberInput(v) : v,
+                        })
+                      }
+                      label={field.label}
+                      placeholder={field.placeholder ?? ""}
+                      disabled={props.disabled}
+                    />
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      );
+    };
+  },
+});

package/src/components/HkFilterTrigger.mobile.test.tsx

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h } from "vue";
+
+// The mobile half of the HkFilterTrigger contract (the main test file
+// runs the desktop shape; useBreakpoint cannot be re-mocked per-test).
+vi.mock("../runtime/useBreakpoint", () => ({
+  useBreakpoint: () => ({ isMobile: { value: true } }),
+}));
+
+import HkFilterTrigger from "./HkFilterTrigger";
+
+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();
+  }
+  document.body.querySelectorAll(".hk-popover-scrim, .hk-popover-panel").forEach((el) => el.remove());
+});
+
+const FIELDS = [{ key: "tool", label: "Tool", kind: "text" as const }];
+
+describe("HkFilterTrigger (mobile sheet)", () => {
+  it("shows exactly ONE confirm button (no cancel) and closes on it", async () => {
+    const c = mount(h(HkFilterTrigger, { fields: FIELDS, modelValue: {} }));
+    const btn = c.querySelector<HTMLButtonElement>(".hk-filter-trigger .hk-icon-button")!;
+    btn.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    const footers = document.body.querySelectorAll(".hk-filter-trigger-footer");
+    expect(footers.length, "the mobile confirm footer renders").toBe(1);
+    const confirms = footers[0]!.querySelectorAll("button");
+    // ONE button: the confirm-closes affordance. No cancel row — clearing
+    // a condition is re-opening the panel and emptying the value.
+    expect(confirms).toHaveLength(1);
+    // The panel is up; pressing confirm closes the sheet (the popover
+    // surfaces close through their transition — the TRIGGER's expanded
+    // state is the contract, same assertion grammar as HkFilterBar's).
+    expect(document.body.querySelector(".hk-filter-panel")).toBeTruthy();
+    confirms[0]!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(btn.getAttribute("aria-expanded")).toBe("false");
+  });
+});

package/src/components/HkFilterTrigger.scss

@@ -0,0 +1,34 @@
+/**
+ * HkFilterTrigger chrome: the header icon button, its active-filter dot
+ * and the mobile confirm footer. The panel's own bounded sizing lives in
+ * HkFilterPanel.scss.
+ */
+
+.hk-filter-trigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+/* Active-filter marker: a small primary dot pinned to the button's
+ * top-right corner — visible only while at least one condition carries a
+ * value (the trigger's data-active drives it, so the empty-state panel
+ * never shows the dot). */
+.hk-filter-trigger-dot {
+  position: absolute;
+  top: 1px;
+  right: 1px;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: rgb(var(--color-primary));
+  pointer-events: none;
+}
+
+.hk-filter-trigger-footer {
+  display: flex;
+  justify-content: flex-end;
+  padding-top: var(--space-8, 0.5rem);
+  border-top: 1px solid rgb(var(--color-border) / 10%);
+  margin-top: var(--space-8, 0.5rem);
+}

package/src/components/HkFilterTrigger.test.tsx

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkFilterTrigger from "./HkFilterTrigger";
+
+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();
+  }
+  document.body.querySelectorAll(".hk-popover-scrim, .hk-popover-panel").forEach((el) => el.remove());
+});
+
+const FIELDS = [
+  { key: "tool", label: "Tool", kind: "text" as const },
+  { key: "count", label: "Calls", kind: "number" as const },
+];
+
+const triggerButton = (c: HTMLElement) =>
+  c.querySelector<HTMLButtonElement>(".hk-filter-trigger .hk-icon-button")!;
+
+describe("HkFilterTrigger", () => {
+  it("renders the filter affordance as a ghost/28 icon button (the theme toggle's step)", () => {
+    const c = mount(h(HkFilterTrigger, { fields: FIELDS, modelValue: {} }));
+    const btn = triggerButton(c);
+    expect(btn).toBeTruthy();
+    expect(btn.className).toContain("hk-icon-button-28");
+    expect(btn.className).toContain("hk-icon-button-ghost");
+    expect(btn.getAttribute("aria-haspopup")).toBe("dialog");
+    // No active dot on an untouched state.
+    expect(c.querySelector(".hk-filter-trigger-dot")).toBeNull();
+  });
+
+  it("opens the panel in a popover below the button and edits emit live", async () => {
+    let seen: Record<string, unknown> | null = null;
+    const c = mount(
+      h(HkFilterTrigger, {
+        fields: FIELDS,
+        modelValue: {},
+        "onUpdate:modelValue": (s: Record<string, unknown>) => (seen = s),
+      }),
+    );
+    expect(document.body.querySelector(".hk-filter-panel")).toBeNull();
+    triggerButton(c).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    // HkPopover teleports the surface to the body.
+    const panel = document.body.querySelector(".hk-filter-panel");
+    expect(panel, "panel mounted after the trigger click").toBeTruthy();
+    // Desktop: NO confirm footer (edits are live; dismissal is click-out).
+    expect(document.body.querySelector(".hk-filter-trigger-footer")).toBeNull();
+    // An edit inside the panel reaches the model live.
+    const input = panel!.querySelector<HTMLInputElement>(".hk-filter-panel-row input")!;
+    input.value = "web";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    await Promise.resolve();
+    expect(seen).not.toBeNull();
+    expect((seen! as { tool: { value: string } }).tool.value).toBe("web");
+  });
+
+  it("shows the active dot only while a condition carries a value", () => {
+    const c = mount(
+      h(HkFilterTrigger, { fields: FIELDS, modelValue: { count: { op: "gte", value: "3" } } }),
+    );
+    expect(c.querySelector(".hk-filter-trigger-dot")).toBeTruthy();
+    const empty = mount(h(HkFilterTrigger, { fields: FIELDS, modelValue: {} }));
+    expect(empty.querySelector(".hk-filter-trigger-dot")).toBeNull();
+  });
+});

package/src/components/HkFilterTrigger.tsx

@@ -0,0 +1,117 @@
+import { computed, defineComponent, ref, type PropType } from "vue";
+import { SlidersHorizontal } from "lucide-vue-next";
+
+import HkButton from "./HkButton";
+import HkFilterPanel, {
+  type HkFilterCondition,
+  type HkFilterFieldDef,
+  type HkFilterState,
+} from "./HkFilterPanel";
+import HkIconButton from "./HkIconButton";
+import HkPopover, { type PopupPlacement } from "./HkPopover";
+import "./HkFilterTrigger.scss";
+import { useBreakpoint } from "../runtime/useBreakpoint";
+import { useI18n } from "../i18n/context";
+
+/**
+ * HkFilterTrigger — the header filter affordance: a ghost/28 icon button
+ * (the same step as the theme toggle and the page refresh — the whole
+ * top-right cluster reads as one row of chrome) anchoring the
+ * HkFilterPanel in a popover on desktop and a bottom sheet on mobile
+ * (HkPopover sheetOnMobile).
+ *
+ * Apply semantics (user direction 2026-09-29):
+ * - desktop: NO confirm button — edits commit live and the panel is
+ *   dismissed by clicking out;
+ * - mobile: ONE confirm button ("应用") that closes the sheet — there is
+ *   deliberately no cancel; clearing a condition is done by re-opening
+ *   the panel and emptying the value, never by a header reset verb.
+ *
+ * A small dot on the button marks a panel with at least one non-empty
+ * value, so a filtered page is recognizable with the panel closed.
+ */
+export default defineComponent({
+  name: "HkFilterTrigger",
+  props: {
+    fields: { type: Array as PropType<HkFilterFieldDef[]>, required: true },
+    modelValue: { type: Object as PropType<HkFilterState>, default: () => ({}) },
+    disabled: { type: Boolean, default: false },
+    /** Accessible name / sheet title. Defaults to the localized "Filters". */
+    label: { type: String, default: undefined },
+    placement: { type: String as PropType<PopupPlacement>, default: "bottom-end" },
+  },
+  emits: {
+    "update:modelValue": (_state: HkFilterState) => true,
+  },
+  setup(props, { emit }) {
+    const { t } = useI18n();
+    const { isMobile } = useBreakpoint();
+    const open = ref(false);
+    const anchorRef = ref<HTMLElement | null>(null);
+
+    const active = computed(() =>
+      Object.values(props.modelValue as Record<string, HkFilterCondition>).some(
+        (c) => c && c.value !== "",
+      ),
+    );
+
+    return () => {
+      const label = props.label ?? t("hikari::filterBar.trigger", "Filters");
+      return (
+        <span ref={anchorRef} class="hk-filter-trigger">
+          <HkIconButton
+            size={28}
+            variant="ghost"
+            aria-label={label}
+            aria-haspopup="dialog"
+            aria-expanded={open.value ? "true" : "false"}
+            disabled={props.disabled}
+            data-active={active.value || undefined}
+            onClick={() => {
+              open.value = !open.value;
+            }}
+          >
+            {{ icon: () => <SlidersHorizontal size={16} /> }}
+          </HkIconButton>
+          {active.value && <span class="hk-filter-trigger-dot" aria-hidden="true" />}
+          <HkPopover
+            modelValue={open.value}
+            onUpdate:modelValue={(v: boolean) => (open.value = v)}
+            anchorRef={anchorRef.value}
+            placement={props.placement}
+            offset={6}
+            sheetOnMobile
+            title={label}
+          >
+            <div class="hk-filter-trigger-body">
+              <HkFilterPanel
+                fields={props.fields}
+                modelValue={props.modelValue}
+                disabled={props.disabled}
+                label={label}
+                onUpdate:modelValue={(state: HkFilterState) => emit("update:modelValue", state)}
+              />
+              {isMobile.value && (
+                <div class="hk-filter-trigger-footer">
+                  {/* The sheet's ONE button: confirm = close (edits are
+                   * already live). No cancel — clearing rides inside the
+                   * panel (empty the value). */}
+                  <HkButton
+                    variant="primary"
+                    size="sm"
+                    disabled={props.disabled}
+                    onClick={() => {
+                      open.value = false;
+                    }}
+                  >
+                    {t("hikari::filterBar.apply", "Apply")}
+                  </HkButton>
+                </div>
+              )}
+            </div>
+          </HkPopover>
+        </span>
+      );
+    };
+  },
+});

package/src/i18n/locales/ar/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "مستوى التكبير",
     "hikari::filterBar.trigger": "عوامل التصفية",
     "hikari::filterBar.apply": "تطبيق",
-    "hikari::filterBar.reset": "إعادة تعيين"
+    "hikari::filterPanel.all": "الكل",
+    "hikari::filterBar.reset": "إعادة تعيين",
+    "hikari::filterPanel.op.eq": "يساوي",
+    "hikari::filterPanel.op.ne": "لا يساوي",
+    "hikari::filterPanel.op.approx": "مطابقة تقريبية",
+    "hikari::filterPanel.op.lt": "أقل من",
+    "hikari::filterPanel.op.lte": "كحد أقصى",
+    "hikari::filterPanel.op.gte": "على الأقل",
+    "hikari::filterPanel.op.gt": "أكبر من"
   },
   "hikari::affixPicker.unset": "غير محدد",
   "hikari::affixPicker.title": "الخيارات",

package/src/i18n/locales/de/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "Zoom-Stufe",
     "hikari::filterBar.trigger": "Filter",
     "hikari::filterBar.apply": "Anwenden",
-    "hikari::filterBar.reset": "Zurücksetzen"
+    "hikari::filterPanel.all": "Alle",
+    "hikari::filterBar.reset": "Zurücksetzen",
+    "hikari::filterPanel.op.eq": "gleich",
+    "hikari::filterPanel.op.ne": "ungleich",
+    "hikari::filterPanel.op.approx": "enthält",
+    "hikari::filterPanel.op.lt": "kleiner als",
+    "hikari::filterPanel.op.lte": "höchstens",
+    "hikari::filterPanel.op.gte": "mindestens",
+    "hikari::filterPanel.op.gt": "größer als"
   },
   "hikari::affixPicker.unset": "Nicht festgelegt",
   "hikari::affixPicker.title": "Optionen",

package/src/i18n/locales/en/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "Zoom level",
     "hikari::filterBar.trigger": "Filters",
     "hikari::filterBar.apply": "Apply",
-    "hikari::filterBar.reset": "Reset"
+    "hikari::filterPanel.all": "All",
+    "hikari::filterBar.reset": "Reset",
+    "hikari::filterPanel.op.eq": "equals",
+    "hikari::filterPanel.op.ne": "not equals",
+    "hikari::filterPanel.op.approx": "fuzzy match",
+    "hikari::filterPanel.op.lt": "less than",
+    "hikari::filterPanel.op.lte": "at most",
+    "hikari::filterPanel.op.gte": "at least",
+    "hikari::filterPanel.op.gt": "greater than"
   },
   "hikari::affixPicker.title": "Options",
   "hikari::affixPicker.search": "Search",

package/src/i18n/locales/es/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "Nivel de zoom",
     "hikari::filterBar.trigger": "Filtros",
     "hikari::filterBar.apply": "Aplicar",
-    "hikari::filterBar.reset": "Restablecer"
+    "hikari::filterPanel.all": "Todos",
+    "hikari::filterBar.reset": "Restablecer",
+    "hikari::filterPanel.op.eq": "igual a",
+    "hikari::filterPanel.op.ne": "distinto de",
+    "hikari::filterPanel.op.approx": "coincidencia",
+    "hikari::filterPanel.op.lt": "menor que",
+    "hikari::filterPanel.op.lte": "como máximo",
+    "hikari::filterPanel.op.gte": "al menos",
+    "hikari::filterPanel.op.gt": "mayor que"
   },
   "hikari::affixPicker.unset": "Sin establecer",
   "hikari::affixPicker.title": "Opciones",

package/src/i18n/locales/fr/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "Niveau de zoom",
     "hikari::filterBar.trigger": "Filtres",
     "hikari::filterBar.apply": "Appliquer",
-    "hikari::filterBar.reset": "Réinitialiser"
+    "hikari::filterPanel.all": "Tous",
+    "hikari::filterBar.reset": "Réinitialiser",
+    "hikari::filterPanel.op.eq": "égal à",
+    "hikari::filterPanel.op.ne": "différent de",
+    "hikari::filterPanel.op.approx": "correspond à",
+    "hikari::filterPanel.op.lt": "inférieur à",
+    "hikari::filterPanel.op.lte": "au plus",
+    "hikari::filterPanel.op.gte": "au moins",
+    "hikari::filterPanel.op.gt": "supérieur à"
   },
   "hikari::affixPicker.unset": "Non défini",
   "hikari::affixPicker.title": "Options",

package/src/i18n/locales/ja/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "ズーム倍率",
     "hikari::filterBar.trigger": "絞り込み",
     "hikari::filterBar.apply": "適用",
-    "hikari::filterBar.reset": "リセット"
+    "hikari::filterPanel.all": "すべて",
+    "hikari::filterBar.reset": "リセット",
+    "hikari::filterPanel.op.eq": "等しい",
+    "hikari::filterPanel.op.ne": "等しくない",
+    "hikari::filterPanel.op.approx": "部分一致",
+    "hikari::filterPanel.op.lt": "未満",
+    "hikari::filterPanel.op.lte": "以下",
+    "hikari::filterPanel.op.gte": "以上",
+    "hikari::filterPanel.op.gt": "より大きい"
   },
   "hikari::affixPicker.unset": "未設定",
   "hikari::affixPicker.title": "オプション",

package/src/i18n/locales/ko/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "확대 수준",
     "hikari::filterBar.trigger": "필터",
     "hikari::filterBar.apply": "적용",
-    "hikari::filterBar.reset": "초기화"
+    "hikari::filterPanel.all": "전체",
+    "hikari::filterBar.reset": "초기화",
+    "hikari::filterPanel.op.eq": "같음",
+    "hikari::filterPanel.op.ne": "같지 않음",
+    "hikari::filterPanel.op.approx": "부분 일치",
+    "hikari::filterPanel.op.lt": "미만",
+    "hikari::filterPanel.op.lte": "이하",
+    "hikari::filterPanel.op.gte": "이상",
+    "hikari::filterPanel.op.gt": "초과"
   },
   "hikari::affixPicker.unset": "미설정",
   "hikari::affixPicker.title": "옵션",

package/src/i18n/locales/pt/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "Nível de zoom",
     "hikari::filterBar.trigger": "Filtros",
     "hikari::filterBar.apply": "Aplicar",
-    "hikari::filterBar.reset": "Redefinir"
+    "hikari::filterPanel.all": "Todos",
+    "hikari::filterBar.reset": "Redefinir",
+    "hikari::filterPanel.op.eq": "igual a",
+    "hikari::filterPanel.op.ne": "diferente de",
+    "hikari::filterPanel.op.approx": "correspondência",
+    "hikari::filterPanel.op.lt": "menor que",
+    "hikari::filterPanel.op.lte": "no máximo",
+    "hikari::filterPanel.op.gte": "pelo menos",
+    "hikari::filterPanel.op.gt": "maior que"
   },
   "hikari::affixPicker.unset": "Não definido",
   "hikari::affixPicker.title": "Opções",

package/src/i18n/locales/ru/components.json

@@ -192,7 +192,15 @@
     "hikari::zoomToolbar.zoomSlider": "Уровень масштаба",
     "hikari::filterBar.trigger": "Фильтры",
     "hikari::filterBar.apply": "Применить",
-    "hikari::filterBar.reset": "Сбросить"
+    "hikari::filterPanel.all": "Все",
+    "hikari::filterBar.reset": "Сбросить",
+    "hikari::filterPanel.op.eq": "равно",
+    "hikari::filterPanel.op.ne": "не равно",
+    "hikari::filterPanel.op.approx": "приблизительно",
+    "hikari::filterPanel.op.lt": "меньше",
+    "hikari::filterPanel.op.lte": "не более",
+    "hikari::filterPanel.op.gte": "не менее",
+    "hikari::filterPanel.op.gt": "больше"
   },
   "hikari::affixPicker.unset": "Не задано",
   "hikari::affixPicker.title": "Параметры",

package/src/i18n/locales/zh-Hans/components.json

@@ -196,7 +196,15 @@
     "hikari::statusBar.region.TW": "中国台湾",
     "hikari::filterBar.trigger": "筛选",
     "hikari::filterBar.apply": "应用",
-    "hikari::filterBar.reset": "重置"
+    "hikari::filterPanel.all": "全部",
+    "hikari::filterBar.reset": "重置",
+    "hikari::filterPanel.op.eq": "等于",
+    "hikari::filterPanel.op.ne": "不等于",
+    "hikari::filterPanel.op.approx": "模糊匹配",
+    "hikari::filterPanel.op.lt": "小于",
+    "hikari::filterPanel.op.lte": "不超过",
+    "hikari::filterPanel.op.gte": "不低于",
+    "hikari::filterPanel.op.gt": "大于"
   },
   "hikari::affixPicker.title": "选项",
   "hikari::affixPicker.search": "搜索",

package/src/i18n/locales/zh-Hant/components.json

@@ -196,7 +196,15 @@
     "hikari::statusBar.region.TW": "中國台灣",
     "hikari::filterBar.trigger": "篩選",
     "hikari::filterBar.apply": "套用",
-    "hikari::filterBar.reset": "重設"
+    "hikari::filterPanel.all": "全部",
+    "hikari::filterBar.reset": "重設",
+    "hikari::filterPanel.op.eq": "等於",
+    "hikari::filterPanel.op.ne": "不等於",
+    "hikari::filterPanel.op.approx": "模糊匹配",
+    "hikari::filterPanel.op.lt": "小於",
+    "hikari::filterPanel.op.lte": "不超過",
+    "hikari::filterPanel.op.gte": "不低於",
+    "hikari::filterPanel.op.gt": "大於"
   },
   "hikari::affixPicker.title": "選項",
   "hikari::affixPicker.search": "搜尋",

package/src/index.ts

@@ -756,6 +756,9 @@ 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 { default as HkFilterPanel, sanitizeNumberInput } from "./components/HkFilterPanel";
+export type { HkFilterOperator, HkFilterFieldDef, HkFilterCondition, HkFilterState } from "./components/HkFilterPanel";
+export { default as HkFilterTrigger } from "./components/HkFilterTrigger";
 export { HkIconChip as HkIconChip } from "./components/HkIconChip";
 export { HkIconChip as HIconChip } from "./components/HkIconChip";
 export { HkCardList, HkListRow } from "./components/HkCardList";