@celestia-island/hikari 0.55.139 → 0.55.141

package/package.json

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

package/src/components/HkFilterChip.scss

@@ -0,0 +1,79 @@
+/**
+ * HkFilterChip chrome — the facet filter chip (trigger) and its popup
+ * body. The pill group itself is HkPillToggleGroup's. Ported from the
+ * wowsp 水表查询 filter bar's grammar: a solid-surface chip (never a
+ * bare alpha tint — a lone chip over wallpaper reads as a hole).
+ */
+
+.hk-filter-chip-anchor {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+.hk-filter-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-6);
+  /* Vertical padding = trigger padding + one track step: the chip shares
+   * its row with segmented HkTabs-style chrome, whose track adds
+   * var(--space-2) around its triggers (the wowsp filter bar's alignment
+   * rule — a bare var(--space-4) chip lands two steps short of the row). */
+  padding: calc(var(--space-4) + var(--space-2)) var(--space-12);
+  font-family: inherit;
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: rgb(var(--color-muted));
+  white-space: nowrap;
+  cursor: pointer;
+  border: 1px solid rgb(var(--color-border) / 25%);
+  border-radius: var(--radius-sm);
+  background: rgb(var(--color-surface));
+  transition:
+    color var(--duration-short) ease,
+    background var(--duration-short) var(--ease-standard),
+    border-color var(--duration-short) var(--ease-standard);
+
+  &:hover {
+    color: rgb(var(--color-text));
+  }
+
+  &:active {
+    transform: scale(0.96);
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(var(--color-primary));
+    outline-offset: 1px;
+  }
+
+  /* Concrete selection — the active trigger's primary ink mixed into the
+   * solid surface (a bare alpha tint would go translucent). */
+  &--on {
+    color: rgb(var(--color-primary));
+    background: color-mix(in srgb, rgb(var(--color-primary)) 12%, rgb(var(--color-surface)));
+    border-color: rgb(var(--color-primary) / 25%);
+
+    &:hover {
+      color: rgb(var(--color-primary));
+    }
+  }
+}
+
+.hk-filter-chip-caret {
+  opacity: 0.6;
+  flex: 0 0 auto;
+}
+
+.hk-filter-chip-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+  max-width: min(92vw, 40rem);
+}
+
+.hk-filter-chip-hint {
+  color: rgb(var(--color-muted));
+  font-size: var(--text-2xs);
+  line-height: 1.4;
+}

package/src/components/HkFilterChip.test.tsx

@@ -0,0 +1,136 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, ref } from "vue";
+
+import HkFilterChip from "./HkFilterChip";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  return mountRendered(() => node);
+}
+
+/** Mount with the vnode built INSIDE the render fn, so reactive props
+ * (a host's open ref) re-render the tree when they change. */
+function mountRendered(build: () => ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => build() });
+  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 OPTIONS = [
+  { value: "deepseek", label: "DeepSeek" },
+  { value: "openai", label: "OpenAI" },
+  { value: "anthropic", label: "Anthropic" },
+  { value: "gemini", label: "Gemini" },
+];
+
+const chipButton = (c: HTMLElement) => c.querySelector<HTMLButtonElement>(".hk-filter-chip")!;
+
+describe("HkFilterChip", () => {
+  it("renders the chip closed, labelled by the all-label when nothing is picked", () => {
+    const c = mount(
+      h(HkFilterChip, { label: "Providers", allLabel: "All providers", options: OPTIONS }),
+    );
+    const btn = chipButton(c);
+    expect(btn.textContent).toContain("All providers");
+    expect(btn.getAttribute("aria-haspopup")).toBe("dialog");
+    expect(btn.getAttribute("aria-expanded")).toBe("false");
+    expect(btn.className).not.toContain("hk-filter-chip--on");
+    // Nothing teleported while closed.
+    expect(document.body.querySelector(".hk-pill-group")).toBeNull();
+  });
+
+  it("opens the pill group in a popover and reports toggle / all", async () => {
+    const open = ref(false);
+    const toggled: string[] = [];
+    const allClicks: number[] = [];
+    const c = mountRendered(
+      () =>
+        h(HkFilterChip, {
+          label: "Providers",
+          allLabel: "All providers",
+          options: OPTIONS,
+          open: open.value,
+          "onUpdate:open": (v: boolean) => (open.value = v),
+          onToggle: (v: string) => toggled.push(v),
+          onAll: () => allClicks.push(1),
+          hint: "Multi-select hint line",
+        }),
+    );
+    chipButton(c).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(open.value).toBe(true);
+    expect(chipButton(c).getAttribute("aria-expanded")).toBe("true");
+
+    // HkPopover teleports the surface to the body — the pill group and
+    // the host-authored hint line live there, not in the anchor.
+    const group = document.body.querySelector(".hk-pill-group");
+    expect(group, "pill group mounted in the popover after the chip click").toBeTruthy();
+    expect(document.body.querySelector(".hk-filter-chip-hint")?.textContent).toContain("Multi-select hint line");
+
+    const pills = [...document.body.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")];
+    expect(pills.length).toBe(OPTIONS.length + 1);
+    pills[2].dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled).toEqual(["openai"]);
+
+    pills[0].dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(allClicks.length).toBe(1);
+    expect(toggled).toEqual(["openai"]);
+  });
+
+  it("mirrors the selection on the chip in canonical option order, capped with a +N tail", async () => {
+    // Canonical order wins over Set insertion order; the 4th pick caps
+    // the label instead of growing the chip without bound.
+    const selected = new Set(["gemini", "openai", "anthropic", "deepseek"]);
+    const c = mount(
+      h(HkFilterChip, {
+        label: "Providers",
+        allLabel: "All providers",
+        options: OPTIONS,
+        selected,
+        open: true,
+      }),
+    );
+    const text = chipButton(c).querySelector(".hk-filter-chip-text")!.textContent;
+    expect(text).toBe("DeepSeek, OpenAI, Anthropic +1");
+    expect(chipButton(c).className).toContain("hk-filter-chip--on");
+    // The accessible name carries the SAME selection the eye sees — an
+    // aria-label of just the category would mask the mirror (R1 P2).
+    expect(chipButton(c).getAttribute("aria-label")).toContain("DeepSeek, OpenAI, Anthropic +1");
+  });
+
+  it("re-renders when the host's selected set changes post-mount", async () => {
+    const selected = ref(new Set<string>());
+    const c = mountRendered(
+      () =>
+        h(HkFilterChip, {
+          label: "Providers",
+          allLabel: "All providers",
+          options: OPTIONS,
+          selected: selected.value,
+          open: false,
+        }),
+    );
+    expect(chipButton(c).querySelector(".hk-filter-chip-text")!.textContent).toBe("All providers");
+    selected.value = new Set(["openai"]);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(chipButton(c).querySelector(".hk-filter-chip-text")!.textContent).toBe("OpenAI");
+    expect(chipButton(c).className).toContain("hk-filter-chip--on");
+    expect(chipButton(c).getAttribute("aria-label")).toContain("OpenAI");
+  });
+});

package/src/components/HkFilterChip.tsx

@@ -0,0 +1,105 @@
+import { computed, defineComponent, ref, type PropType } from "vue";
+import { ChevronDown } from "lucide-vue-next";
+
+import HkPopover, { type PopupPlacement } from "./HkPopover";
+import HkPillToggleGroup, { type HkPillToggleGroupOption } from "./HkPillToggleGroup";
+import "./HkFilterChip.scss";
+
+/**
+ * HkFilterChip — the FACET filter member of the filter family: a chip
+ * trigger that opens a popover (desktop) / bottom sheet (mobile, via
+ * HkPopover's sheetOnMobile) holding an HkPillToggleGroup multi-select —
+ * the 水表查询 filter-bar grammar, upstreamed from wowsp's
+ * FilterCategoryChip (2026-10-11). The sort/direction arrows and the
+ * drag-reorderable chip strip stay host-side there; this is the pure
+ * facet member.
+ *
+ * Semantics ride the thin group contract: `toggle(value)` reports one
+ * option toggled, `all()` reports the all-pill — the HOST decides
+ * whether all means clear or select-everything. The chip label mirrors
+ * the selection: the all-label when nothing is picked, otherwise the
+ * picked labels in canonical option order (capped at three plus a +N
+ * tail, so a wide facet cannot blow up the chip strip's width).
+ */
+export default defineComponent({
+  name: "HkFilterChip",
+  props: {
+    /** Popup title + the trigger's accessible name (the category). */
+    label: { type: String, required: true },
+    /** Chip text with nothing picked, and the all-pill's label. */
+    allLabel: { type: String, required: true },
+    /** Facet values in canonical display order (also the chip-label
+     * order — picked labels mirror it, not the Set's insertion order). */
+    options: {
+      type: Array as PropType<HkPillToggleGroupOption[]>,
+      default: () => [],
+    },
+    /** The picked values — single source of truth, never mutated here. */
+    selected: { type: Object as PropType<Set<string>>, default: () => new Set<string>() },
+    open: { type: Boolean, default: false },
+    placement: { type: String as PropType<PopupPlacement>, default: "bottom-start" },
+    /** Bottom hint line below the pill group. Host-provided on purpose:
+     * the facet's semantics (multi-select? radio? clears what?) are the
+     * host's story to tell. */
+    hint: { type: String, default: undefined },
+  },
+  emits: {
+    "update:open": (_v: boolean) => true,
+    toggle: (_value: string) => true,
+    all: () => true,
+  },
+  setup(props, { emit }) {
+    const anchorRef = ref<HTMLElement | null>(null);
+
+    /** Picked options in canonical order — the chip label's source. */
+    const picked = computed(() => props.options.filter((o) => props.selected.has(o.value)));
+
+    const chipText = computed(() => {
+      if (picked.value.length === 0) return props.allLabel;
+      const names = picked.value.map((o) => o.label);
+      const head = names.slice(0, 3).join(", ");
+      const rest = names.length - 3;
+      return rest > 0 ? `${head} +${rest}` : head;
+    });
+
+    return () => (
+      <span ref={anchorRef} class="hk-filter-chip-anchor">
+        <button
+          type="button"
+          class={["hk-filter-chip", props.selected.size > 0 && "hk-filter-chip--on"]}
+          aria-haspopup="dialog"
+          aria-expanded={props.open ? "true" : "false"}
+          aria-label={
+            picked.value.length > 0 ? `${props.label}: ${chipText.value}` : props.label
+          }
+          title={props.label}
+          onClick={() => emit("update:open", !props.open)}
+        >
+          <span class="hk-filter-chip-text">{chipText.value}</span>
+          <ChevronDown size={12} class="hk-filter-chip-caret" />
+        </button>
+        <HkPopover
+          modelValue={props.open}
+          onUpdate:modelValue={(v: boolean) => emit("update:open", v)}
+          anchorRef={anchorRef.value}
+          placement={props.placement}
+          offset={6}
+          sheetOnMobile
+          title={props.label}
+        >
+          <div class="hk-filter-chip-body">
+            <HkPillToggleGroup
+              label={props.label}
+              options={props.options}
+              selected={props.selected}
+              allLabel={props.allLabel}
+              onToggle={(v: string) => emit("toggle", v)}
+              onAll={() => emit("all")}
+            />
+            {props.hint && <div class="hk-filter-chip-hint">{props.hint}</div>}
+          </div>
+        </HkPopover>
+      </span>
+    );
+  },
+});

package/src/components/HkPillToggleGroup.scss

@@ -0,0 +1,129 @@
+/**
+ * HkPillToggleGroup chrome — the segmented pill track. Ported from the
+ * wowsp 水表查询 filter bar's option group (strip chrome and fade
+ * masks token-for-token; the pills keep their pointer cursor — the
+ * strip root carries the grab affordance): shared
+ * chrome around per-option buttons, the active option carrying the
+ * indicator tint directly (multi-select cannot use HkTabs — its sliding
+ * indicator is radio semantics). The track is the ONE-LINE PANNABLE
+ * STRIP: overflow hides under edge fades (data-h-overflow masks, the
+ * HkScrollContainer contract) and pans by wheel / mouse drag / native
+ * touch (the machinery lives in useOptionStrip); phones relax back into
+ * a wrapping group (media query below — the sheet carries full width).
+ */
+
+.hk-pill-group {
+  display: flex;
+  flex-wrap: nowrap;
+  max-width: 100%;
+  gap: var(--space-4, 4px);
+  overflow-x: auto;
+  overflow-y: hidden;
+  touch-action: pan-x;
+  scrollbar-width: none;
+  overscroll-behavior-x: contain;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+
+  --hk-scroll-fade-size: var(--space-24);
+
+  &[data-h-overflow="end"] {
+    -webkit-mask-image: linear-gradient(to left, transparent 0, #000 var(--hk-scroll-fade-size));
+    mask-image: linear-gradient(to left, transparent 0, #000 var(--hk-scroll-fade-size));
+  }
+
+  &[data-h-overflow="start"] {
+    -webkit-mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));
+    mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));
+  }
+
+  &[data-h-overflow="both"] {
+    -webkit-mask-image: linear-gradient(
+      to right,
+      transparent 0,
+      #000 var(--hk-scroll-fade-size),
+      #000 calc(100% - var(--hk-scroll-fade-size)),
+      transparent 100%
+    );
+    mask-image: linear-gradient(
+      to right,
+      transparent 0,
+      #000 var(--hk-scroll-fade-size),
+      #000 calc(100% - var(--hk-scroll-fade-size)),
+      transparent 100%
+    );
+  }
+
+  /* The whole strip drags; clicks still toggle — the 5px pan threshold
+   * keeps plain clicks click-shaped. */
+  cursor: grab;
+
+  &[data-panning] {
+    cursor: grabbing;
+    user-select: none;
+  }
+  padding: 2px;
+  border-radius: var(--radius-sm);
+  border: 1px solid rgb(var(--color-border) / 25%);
+  background: rgb(var(--color-surface) / 60%);
+}
+
+.hk-pill-group-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-6, 6px);
+  padding: var(--space-4) var(--space-12);
+  font-family: inherit;
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: rgb(var(--color-muted));
+  white-space: nowrap;
+  cursor: pointer;
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  outline: none;
+  transition: color var(--duration-short) ease, transform var(--duration-short) ease;
+
+  &:hover {
+    color: rgb(var(--color-text));
+  }
+
+  &:active {
+    transform: scale(0.96);
+  }
+
+  &[data-active] {
+    color: rgb(var(--color-primary));
+    background: rgb(var(--color-primary) / 12%);
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(var(--color-primary));
+    outline-offset: -2px;
+  }
+}
+
+.hk-pill-group-icon {
+  display: inline-flex;
+  align-items: center;
+  /* An icon never widens the hit floor: replaced-element glyphs
+   * contribute nothing to a button's min-content width, so shrink
+   * pressure would collapse them before the label felt it. */
+  flex: 0 0 auto;
+}
+
+/* Phones: the sheet carries the full width, nothing pans there — the
+ * strip relaxes back into the wrapping group (the wowsp filter bar's
+ * rule; the fade masks and the grab affordance name interactions the
+ * track no longer has). */
+@media (max-width: 767px) {
+  .hk-pill-group {
+    flex-wrap: wrap;
+    overflow: visible;
+    touch-action: auto;
+    cursor: default;
+  }
+}

package/src/components/HkPillToggleGroup.test.tsx

@@ -0,0 +1,177 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkPillToggleGroup from "./HkPillToggleGroup";
+
+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 OPTIONS = [
+  { value: "deepseek", label: "DeepSeek" },
+  { value: "openai", label: "OpenAI" },
+  { value: "anthropic", label: "Anthropic" },
+];
+
+describe("HkPillToggleGroup", () => {
+  it("renders one pill per option plus the all-pill, active state from the selected set", () => {
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "Providers",
+        options: OPTIONS,
+        selected: new Set(["openai"]),
+        allLabel: "All",
+      }),
+    );
+    const pills = [...c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")];
+    expect(pills.map((p) => p.textContent?.trim())).toEqual(["All", "DeepSeek", "OpenAI", "Anthropic"]);
+    // Active tint rides data-active (the segmented grammar — no aria-only state).
+    expect(pills[0].hasAttribute("data-active")).toBe(false);
+    expect(pills[2].hasAttribute("data-active")).toBe(true);
+    // Every pill is a pressed-state toggle button (screen readers hear the set).
+    expect(pills[2].getAttribute("aria-pressed")).toBe("true");
+    expect(pills[1].getAttribute("aria-pressed")).toBe("false");
+    expect(c.querySelector(".hk-pill-group")!.getAttribute("role")).toBe("group");
+  });
+
+  it("marks the all-pill active when nothing is picked, and hides it without allLabel", () => {
+    const withAll = mount(
+      h(HkPillToggleGroup, { label: "P", options: OPTIONS, selected: new Set<string>(), allLabel: "All" }),
+    );
+    expect(withAll.querySelectorAll(".hk-pill-group-pill")[0].hasAttribute("data-active")).toBe(true);
+
+    const bare = mount(h(HkPillToggleGroup, { label: "P", options: OPTIONS, selected: new Set<string>() }));
+    expect(bare.querySelectorAll(".hk-pill-group-pill").length).toBe(OPTIONS.length);
+  });
+
+  it("reports toggle(value) and all() — the set itself is never mutated here", async () => {
+    const seen: string[] = [];
+    const allClicks: number[] = [];
+    const selected = new Set<string>(["deepseek"]);
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "P",
+        options: OPTIONS,
+        selected,
+        allLabel: "All",
+        onToggle: (v: string) => seen.push(v),
+        onAll: () => allClicks.push(1),
+      }),
+    );
+    const pills = [...c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")];
+    pills[2].dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(seen).toEqual(["openai"]);
+    // The host-owned set is untouched — the component only reports.
+    expect([...selected]).toEqual(["deepseek"]);
+
+    pills[0].dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(allClicks.length).toBe(1);
+    expect(seen).toEqual(["openai"]);
+  });
+
+  it("normalizes option icons: components render, junk renders nothing, nothing stringifies", async () => {
+    const { h } = await import("vue");
+    const { Zap } = await import("lucide-vue-next");
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "P",
+        selected: new Set<string>(),
+        options: [
+          { value: "fn", label: "Fn", icon: Zap },
+          { value: "vnode", label: "Vn", icon: h(Zap) },
+          { value: "junk", label: "Jk", icon: 42 },
+        ],
+      }),
+    );
+    await Promise.resolve();
+    const pills = [...c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")];
+    // A raw lucide component FUNCTION must render as its <svg> — the R1
+    // landmine: unnormalized it stringifies into source text.
+    expect(pills[0].querySelector("svg"), "function icon renders").toBeTruthy();
+    expect(pills[0].textContent).not.toContain("h(");
+    // A prebuilt vnode passes through identically.
+    expect(pills[1].querySelector("svg"), "vnode icon renders").toBeTruthy();
+    // Junk (a number) renders nothing — and never its digits.
+    expect(pills[2].querySelector(".hk-pill-group-icon")).toBeNull();
+    expect(pills[2].textContent?.trim()).toBe("Jk");
+  });
+
+  it("strip wiring: a drag pans and swallows its trailing click — a plain click still toggles", async () => {
+    const toggled: string[] = [];
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "P",
+        options: OPTIONS,
+        selected: new Set<string>(),
+        onToggle: (v: string) => toggled.push(v),
+      }),
+    );
+    const group = c.querySelector(".hk-pill-group")!;
+    const pill = c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")[0];
+
+    // Press on a pill, stray past the 5px threshold, release: the strip
+    // flags the pan and the trailing click is swallowed exactly once.
+    pill.dispatchEvent(
+      new PointerEvent("pointerdown", { bubbles: true, pointerType: "mouse", button: 0, clientX: 100, clientY: 50 }),
+    );
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { pointerType: "mouse", clientX: 120, clientY: 52 }),
+    );
+    await Promise.resolve();
+    expect(group.hasAttribute("data-panning")).toBe(true);
+    window.dispatchEvent(new PointerEvent("pointerup", { pointerType: "mouse" }));
+    await Promise.resolve();
+    expect(group.hasAttribute("data-panning")).toBe(false);
+    pill.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled, "the pan's trailing click must not toggle").toEqual([]);
+
+    // The NEXT plain click toggles normally — the swallow is one-shot.
+    pill.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled).toEqual([OPTIONS[0].value]);
+  });
+
+  it("strip wiring: a sub-threshold press never pans and its click toggles", async () => {
+    const toggled: string[] = [];
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "P",
+        options: OPTIONS,
+        selected: new Set<string>(),
+        onToggle: (v: string) => toggled.push(v),
+      }),
+    );
+    const group = c.querySelector(".hk-pill-group")!;
+    const pill = c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")[1];
+
+    pill.dispatchEvent(
+      new PointerEvent("pointerdown", { bubbles: true, pointerType: "mouse", button: 0, clientX: 100, clientY: 50 }),
+    );
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { pointerType: "mouse", clientX: 103, clientY: 51 }),
+    );
+    await Promise.resolve();
+    expect(group.hasAttribute("data-panning"), "3px stays a click").toBe(false);
+    window.dispatchEvent(new PointerEvent("pointerup", { pointerType: "mouse" }));
+    pill.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled).toEqual([OPTIONS[1].value]);
+  });
+});

package/src/components/HkPillToggleGroup.tsx

@@ -0,0 +1,109 @@
+import { defineComponent, h, type PropType, type VNode } from "vue";
+
+import { useOptionStrip } from "../composables/useOptionStrip";
+import "./HkPillToggleGroup.scss";
+
+/** One toggleable pill of the group. */
+export interface HkPillToggleGroupOption {
+  /** Stable identity — the value emitted back through `toggle`. */
+  value: string;
+  label: string;
+  /** Optional leading glyph. Accepts EITHER a component (a lucide icon
+   * function, a defineComponent options object) or a prebuilt vnode —
+   * both normalize to a rendered element; anything else is skipped
+   * (never stringified: a raw function child renders as source text,
+   * which is exactly the landmine this normalization defuses). */
+  icon?: unknown;
+}
+
+/** Normalize an option icon to a renderable vnode. A component (function
+ * or options object) is instantiated with `h`; a prebuilt vnode passes
+ * through; anything else (string, number, null) renders nothing. */
+function resolveIcon(icon: unknown): VNode | null {
+  if (icon == null) return null;
+  if (typeof icon === "object") return icon as VNode;
+  if (typeof icon === "function") return h(icon as Parameters<typeof h>[0]);
+  return null;
+}
+
+/**
+ * HkPillToggleGroup — the segmented pill-track multi-select: shared
+ * chrome around per-option toggle buttons, the active option carrying
+ * the indicator tint directly (multi-select cannot use HkTabs — its
+ * sliding indicator is radio semantics). Grammar ported from the wowsp
+ * 水表查询 filter bar's option strip (2026-10-11); the track is the
+ * ONE-LINE PANNABLE STRIP (same-day follow-up direction): overflow
+ * hides under edge fades and pans by wheel / mouse drag / native touch,
+ * exactly the 水表 popups' behavior — a wrapping track always measured
+ * ONE long line inside HkPopover's max-content panel and ran off-screen
+ * (wowsp #667). Phones relax back into a wrapping group (the sheet
+ * carries full width; nothing pans there) via the SCSS media query.
+ *
+ * Deliberately THIN (the host owns the set): `toggle(value)` reports one
+ * pill toggled; the optional leading all-pill reports `all()` and the
+ * HOST decides what that means (clear the facet, or select everything —
+ * both are legitimate; see HkFilterChip and the provider model groups).
+ * `selected` is the single source of truth and is never mutated here.
+ */
+export default defineComponent({
+  name: "HkPillToggleGroup",
+  props: {
+    /** Accessible name of the group (role=group aria-label). */
+    label: { type: String, required: true },
+    options: {
+      type: Array as PropType<HkPillToggleGroupOption[]>,
+      default: () => [],
+    },
+    /** The picked values — single source of truth, never mutated here. */
+    selected: { type: Object as PropType<Set<string>>, default: () => new Set<string>() },
+    /** The leading all-pill's label; omit to hide the all-pill. The pill
+     * wears the active tint exactly when nothing is picked. */
+    allLabel: { type: String, default: undefined },
+  },
+  emits: {
+    toggle: (_value: string) => true,
+    all: () => true,
+  },
+  setup(props, { emit }) {
+    const { stripEl, panning, onPointerDown } = useOptionStrip();
+
+    return () => (
+      <div
+        ref={stripEl}
+        class="hk-pill-group"
+        role="group"
+        aria-label={props.label}
+        data-panning={panning.value || undefined}
+        onPointerdown={onPointerDown}
+      >
+        {props.allLabel != null && (
+          <button
+            type="button"
+            class="hk-pill-group-pill"
+            data-active={props.selected.size === 0 || undefined}
+            aria-pressed={props.selected.size === 0 ? "true" : "false"}
+            onClick={() => emit("all")}
+          >
+            {props.allLabel}
+          </button>
+        )}
+        {props.options.map((o) => {
+          const icon = resolveIcon(o.icon);
+          return (
+            <button
+              type="button"
+              key={o.value}
+              class="hk-pill-group-pill"
+              data-active={props.selected.has(o.value) || undefined}
+              aria-pressed={props.selected.has(o.value) ? "true" : "false"}
+              onClick={() => emit("toggle", o.value)}
+            >
+              {icon != null && <span class="hk-pill-group-icon">{icon}</span>}
+              {o.label}
+            </button>
+          );
+        })}
+      </div>
+    );
+  },
+});

package/src/composables/useOptionStrip.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  WHEEL_LINE_PX,
+  overflowSides,
+  panEngaged,
+  stripWheelDelta,
+} from "./useOptionStrip";
+
+describe("stripWheelDelta", () => {
+  it("lets a real horizontal wheel delta win over the vertical one", () => {
+    expect(stripWheelDelta(0, -120, 40)).toBe(-120);
+  });
+  it("translates a plain vertical notch onto the horizontal axis", () => {
+    expect(stripWheelDelta(0, 0, 80)).toBe(80);
+    expect(stripWheelDelta(0, 0, -80)).toBe(-80);
+  });
+  it("normalizes Firefox line mode to pixels per notch", () => {
+    expect(stripWheelDelta(1, 0, 3)).toBe(3 * WHEEL_LINE_PX);
+    expect(stripWheelDelta(1, -2, 0)).toBe(-2 * WHEEL_LINE_PX);
+  });
+});
+
+describe("panEngaged", () => {
+  it("engages at the threshold on EITHER axis", () => {
+    expect(panEngaged(5, 0, 5)).toBe(true);
+    expect(panEngaged(0, -5, 5)).toBe(true);
+    expect(panEngaged(4, 4, 5)).toBe(false);
+  });
+});
+
+describe("overflowSides", () => {
+  function fake(scrollWidth: number, clientWidth: number, scrollLeft: number): HTMLElement {
+    return { scrollWidth, clientWidth, scrollLeft } as unknown as HTMLElement;
+  }
+  it("reports none when the strip fits", () => {
+    expect(overflowSides(fake(100, 120, 0))).toBe("none");
+  });
+  it("reports the edges that still hide content (sub-pixel resting counts)", () => {
+    expect(overflowSides(fake(200, 100, 0))).toBe("end");
+    expect(overflowSides(fake(200, 100, 100))).toBe("start");
+    expect(overflowSides(fake(200, 100, 40))).toBe("both");
+    expect(overflowSides(fake(200, 100, 0.5))).toBe("end");
+  });
+});

package/src/composables/useOptionStrip.ts

@@ -0,0 +1,209 @@
+/**
+ * useOptionStrip — the one-line pannable option track behind
+ * HkPillToggleGroup's strip mode. Upstreamed from wowsp's optionStrip
+ * (the 水表 filter bar's nation popup and every FilterCategoryChip
+ * popup, 2026-10-11 direction: the pill groups must pan with edge
+ * fades, not wrap). One module owns:
+ *
+ *   - the wheel→horizontal pan rule (a real horizontal delta wins; a
+ *     vertical notch is translated onto the strip; Firefox line mode is
+ *     normalized — mirrors HkScrollContainer's wheel rule);
+ *   - the mouse drag-pan (pointer capture + the 5px click/pan threshold;
+ *     the click a pan leaves behind is swallowed exactly once, so panning
+ *     never toggles an option);
+ *   - the overflow-side sensing behind the edge fades: the strip mirrors
+ *     HkScrollContainer's `data-h-overflow` contract (which inline edges
+ *     still hide content), and the host SCSS turns the value into the
+ *     matching mask-image gradients.
+ *
+ * The track element itself stays owned by the host component (its
+ * classes and sheet-mode overrides live there); the composable only
+ * wires listeners while the element is mounted.
+ */
+import { onBeforeUnmount, ref, watch, type Ref } from "vue";
+
+/** Firefox line-height wheel mode (deltaMode 1): one notch reports ~3
+ *  lines, not pixels — normalized here so a notch pans a wheel-like
+ *  distance on every engine (40px/line, the classic WebKit line height).
+ *  Page mode (deltaMode 2, effectively extinct) passes through raw. */
+export const WHEEL_LINE_PX = 40;
+
+/** Horizontal pan distance for a wheel gesture over the strip: a real
+ *  horizontal wheel/trackpad swipe (deltaX — shift+wheel reports as
+ *  deltaX natively too) wins; a plain vertical wheel notch is translated
+ *  onto the horizontal axis instead. */
+export function stripWheelDelta(deltaMode: number, deltaX: number, deltaY: number): number {
+  const raw = deltaX !== 0 ? deltaX : deltaY;
+  return deltaMode === 1 ? raw * WHEEL_LINE_PX : raw;
+}
+
+/** Press→pan decision for the strip drag: once the pointer strays
+ *  ≥ threshold px on EITHER axis the press turns into a pan; below it the
+ *  gesture stays a click (and clicks must keep toggling options). */
+export function panEngaged(dx: number, dy: number, threshold: number): boolean {
+  return Math.abs(dx) >= threshold || Math.abs(dy) >= threshold;
+}
+
+/** Which inline edges of a strip still hide content — the value mirrored
+ *  onto the element as `data-h-overflow` (HkScrollContainer's contract;
+ *  the SCSS maps each value to its edge-fade mask). Sub-pixel scroll
+ *  offsets count as resting at the edge. RTL flips the visual sides; the
+ *  family ships LTR only. */
+export type OverflowSides = "none" | "start" | "end" | "both";
+
+export function overflowSides(el: HTMLElement): OverflowSides {
+  const max = el.scrollWidth - el.clientWidth;
+  if (max <= 0) return "none";
+  const EDGE_PX = 1;
+  const atStart = el.scrollLeft <= EDGE_PX;
+  const atEnd = max - el.scrollLeft <= EDGE_PX;
+  if (atStart && atEnd) return "none";
+  return atStart ? "end" : atEnd ? "start" : "both";
+}
+
+/** Wire one strip element with the pan + fade machinery. The host binds
+ *  `stripEl` (template ref), mirrors `panning` into `data-panning`, and
+ *  attaches `onPointerDown`; the non-passive wheel listener, the
+ *  capture-phase click swallow and the overflow sensing ride the ref
+ *  transitions here (a JSX onWheel prop is passive in some paths and
+ *  could not preventDefault, and JSX has no capture-phase click prop). */
+export function useOptionStrip() {
+  const stripEl: Ref<HTMLElement | null> = ref(null);
+  const panning = ref(false);
+  const PAN_THRESHOLD = 5;
+  let pressX = 0;
+  let pressY = 0;
+  let lastX = 0;
+  let armed = false;
+  /** Set when a gesture turned into a pan: the trailing click (and only
+   *  that one) must not toggle an option. */
+  let dragged = false;
+  let resizeObserver: ResizeObserver | null = null;
+  let mutationObserver: MutationObserver | null = null;
+
+  /** Re-read the overflow sides and mirror them onto the element. Fires
+   *  on scroll, on element resizes and on content mutations (options
+   *  re-rendering can change the track's scroll width). */
+  function sense() {
+    const el = stripEl.value;
+    if (!el) return;
+    const sides = overflowSides(el);
+    if (sides === "none") delete el.dataset.hOverflow;
+    else el.dataset.hOverflow = sides;
+  }
+
+  function onWheel(e: WheelEvent) {
+    const el = stripEl.value;
+    if (!el || el.scrollWidth <= el.clientWidth) return;
+    const delta = stripWheelDelta(e.deltaMode, e.deltaX, e.deltaY);
+    if (delta === 0) return;
+    const prev = el.scrollLeft;
+    el.scrollLeft += delta;
+    // A saturated edge lets the wheel keep scrolling the page behind.
+    if (el.scrollLeft !== prev) e.preventDefault();
+  }
+
+  function onPointerDown(e: PointerEvent) {
+    if (e.pointerType !== "mouse" || e.button !== 0) return;
+    // A pan released off-strip leaves no click behind; clear the stale
+    // swallow flag so this press's own click always lands.
+    dragged = false;
+    pressX = lastX = e.clientX;
+    pressY = e.clientY;
+    armed = false;
+    window.addEventListener("pointermove", onPointerMove);
+    window.addEventListener("pointerup", onPointerUp, { once: true });
+    window.addEventListener("pointercancel", onPointerCancel, { once: true });
+  }
+
+  function onPointerMove(e: PointerEvent) {
+    if (!armed) {
+      if (!panEngaged(e.clientX - pressX, e.clientY - pressY, PAN_THRESHOLD)) return;
+      // Engage: capture the pointer so the pan keeps tracking off-panel,
+      // flag the strip (grabbing cursor + selection off) and arm the
+      // one-shot click swallow — with capture held, the trailing click
+      // retargets to the strip anyway, never onto an option.
+      armed = true;
+      panning.value = true;
+      dragged = true;
+      stripEl.value?.setPointerCapture(e.pointerId);
+    }
+    e.preventDefault();
+    const el = stripEl.value;
+    if (!el) return;
+    el.scrollLeft -= e.clientX - lastX;
+    lastX = e.clientX;
+  }
+
+  function teardownPress() {
+    armed = false;
+    panning.value = false;
+    window.removeEventListener("pointermove", onPointerMove);
+  }
+
+  function onPointerUp() {
+    teardownPress();
+  }
+
+  function onPointerCancel() {
+    // A cancelled gesture never leaves a click — no swallow to hold.
+    dragged = false;
+    teardownPress();
+  }
+
+  /** The click a completed pan leaves behind must never toggle an
+   *  option: swallowed exactly once, capture phase (ahead of every
+   *  option handler). Plain clicks pass untouched. */
+  function onClickCapture(e: MouseEvent) {
+    if (!dragged) return;
+    dragged = false;
+    e.stopPropagation();
+  }
+
+  /** A host popup that closed before the pan's trailing click (window
+   *  blur mid-drag — pointerup lost) must not carry the swallow flag
+   *  into the reopened panel. */
+  function resetDragged() {
+    dragged = false;
+  }
+
+  watch(stripEl, (el, prev) => {
+    prev?.removeEventListener("wheel", onWheel);
+    prev?.removeEventListener("click", onClickCapture, true);
+    prev?.removeEventListener("scroll", sense);
+    resizeObserver?.disconnect();
+    resizeObserver = null;
+    mutationObserver?.disconnect();
+    mutationObserver = null;
+    if (el) {
+      el.addEventListener("wheel", onWheel, { passive: false });
+      el.addEventListener("click", onClickCapture, true);
+      el.addEventListener("scroll", sense, { passive: true });
+      if (typeof ResizeObserver !== "undefined") {
+        resizeObserver = new ResizeObserver(sense);
+        resizeObserver.observe(el);
+      }
+      if (typeof MutationObserver !== "undefined") {
+        mutationObserver = new MutationObserver(sense);
+        mutationObserver.observe(el, { childList: true, subtree: true });
+      }
+      sense();
+    }
+  });
+  onBeforeUnmount(() => {
+    teardownPress();
+    // Full listener teardown: a component unmounting mid-pan must not
+    // leave listeners behind on the strip element or the window's
+    // once-listeners unheld.
+    const el = stripEl.value;
+    el?.removeEventListener("wheel", onWheel);
+    el?.removeEventListener("click", onClickCapture, true);
+    el?.removeEventListener("scroll", sense);
+    window.removeEventListener("pointerup", onPointerUp);
+    window.removeEventListener("pointercancel", onPointerCancel);
+    resizeObserver?.disconnect();
+    mutationObserver?.disconnect();
+  });
+
+  return { stripEl, panning, onPointerDown, resetDragged };
+}

package/src/index.ts

@@ -830,6 +830,9 @@ 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 { default as HkFilterChip } from "./components/HkFilterChip";
+export { default as HkPillToggleGroup } from "./components/HkPillToggleGroup";
+export type { HkPillToggleGroupOption } from "./components/HkPillToggleGroup";
 export { HkIconChip as HkIconChip } from "./components/HkIconChip";
 export { HkIconChip as HIconChip } from "./components/HkIconChip";
 export { HkCardList, HkListRow } from "./components/HkCardList";