@celestia-island/hikari 0.55.14 → 0.55.15

package/package.json

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

package/src/components/HkIconButtonGroup.scss

@@ -33,6 +33,72 @@
   --hk-icon-group-item-size: 3.25rem;
 }
 
+/* ── Visual variants (orthogonal to the semantic mode) ──────────────────
+ *
+ * "track" (the default above) is the bordered inset strip. The two
+ * frameless variants drop the outer chrome — a frame is a host choice,
+ * not part of a group's meaning (2026-09-17 user direction):
+ *  - "plain": independent buttons, still spaced, each tinting itself;
+ *  - "slider": gapless packed row + one thumb pill that slides to the
+ *    active item (single-selection only; the position is the active
+ *    index × the item-size variable, so retuning the size keeps the
+ *    thumb aligned with no JS measurement).
+ */
+
+.hk-icon-group-plain {
+  padding: 0;
+  border: none;
+  background: transparent;
+}
+
+.hk-icon-group-slider {
+  /* A hair of inset so the thumb's rounded corners never clip — nothing
+   * like the track's full frame. */
+  --hk-icon-group-inset: 0.125rem;
+
+  position: relative;
+  padding: var(--hk-icon-group-inset);
+  border: none;
+  background: transparent;
+  gap: 0;
+  flex-wrap: nowrap;
+}
+
+.hk-icon-group-slider .hk-icon-group-item {
+  position: relative;
+  /* Items ride above the thumb so their hit targets and tooltips stay
+   * first-class while the pill glides behind them. */
+  z-index: 1;
+  /* Tooltip-less items are DIRECT flex children here — without this a
+   * width-constrained host could compress them while the thumb keeps
+   * the full item-size width (misalignment). Wrapped items are already
+   * flex:none via .hk-tooltip-wrapper. */
+  flex: none;
+}
+
+/* The active item in slider mode carries no tint of its own — the thumb
+ * IS its highlight (keeps the sliding illusion seamless). Scoped to
+ * single mode: in "multiple" + slider the thumb is suppressed and the
+ * per-item tint is the ONLY active indication left. */
+.hk-icon-group-single.hk-icon-group-slider .hk-icon-group-item[data-active] {
+  background: transparent;
+}
+
+.hk-icon-group-slider-thumb {
+  position: absolute;
+  top: var(--hk-icon-group-inset);
+  left: var(--hk-icon-group-inset);
+  width: var(--hk-icon-group-item-size);
+  height: var(--hk-icon-group-item-size);
+  border-radius: var(--radius-sm, 4px);
+  background: rgb(var(--color-primary, 90 140 255) / 14%);
+  transform: translateX(
+    calc(var(--hk-icon-group-active-index, 0) * var(--hk-icon-group-item-size))
+  );
+  transition: transform var(--duration, 0.18s) ease;
+  pointer-events: none;
+}
+
 /* The HkTooltip wrapper span is the flex child between items — let it
    shrink to the button so the track gap (not the wrapper) spaces them. */
 .hk-icon-group > .hk-tooltip-wrapper {

package/src/components/HkIconButtonGroup.test.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 
@@ -179,4 +181,125 @@ describe("HkIconButtonGroup", () => {
     expect(group.getAttribute("aria-label")).toBe("验证方式");
     expect(group.getAttribute("data-test")).toBe("probe");
   });
+
+  describe("visual variants", () => {
+    it("defaults to the track treatment", () => {
+      const c = mountComp(() => h(HkIconButtonGroup, { options }));
+      const group = c.querySelector<HTMLElement>(".hk-icon-group")!;
+      expect(group.classList.contains("hk-icon-group-track")).toBe(true);
+      expect(c.querySelector(".hk-icon-group-slider-thumb")).toBeNull();
+    });
+
+    it("plain drops the frame class without touching semantics", async () => {
+      const model = ref<string | null>("totp");
+      const c = mountComp(() =>
+        h(HkIconButtonGroup, {
+          options,
+          mode: "single",
+          variant: "plain",
+          modelValue: model.value,
+          "onUpdate:modelValue": (v: string | string[]) => {
+            model.value = v as string;
+          },
+        }),
+      );
+      const group = c.querySelector<HTMLElement>(".hk-icon-group")!;
+      expect(group.classList.contains("hk-icon-group-plain")).toBe(true);
+      expect(group.classList.contains("hk-icon-group-track")).toBe(false);
+      // Selection semantics unchanged.
+      const buttons = [...c.querySelectorAll<HTMLButtonElement>(".hk-icon-group-item")];
+      expect(buttons[0]!.dataset.active).toBe("true");
+      buttons[1]!.click();
+      await nextTick();
+      expect(model.value).toBe("passkey");
+      expect(c.querySelector(".hk-icon-group-slider-thumb")).toBeNull();
+    });
+
+    it("slider renders a thumb that slides to the active index", async () => {
+      const model = ref<string | null>("totp");
+      const c = mountComp(() =>
+        h(HkIconButtonGroup, {
+          options,
+          mode: "single",
+          variant: "slider",
+          modelValue: model.value,
+          "onUpdate:modelValue": (v: string | string[]) => {
+            model.value = v as string;
+          },
+        }),
+      );
+      const group = c.querySelector<HTMLElement>(".hk-icon-group")!;
+      expect(group.classList.contains("hk-icon-group-slider")).toBe(true);
+      const thumb = c.querySelector<HTMLElement>(".hk-icon-group-slider-thumb")!;
+      expect(thumb.getAttribute("aria-hidden")).toBe("true");
+      // Position = active index × item size, expressed through the CSS
+      // variable so a retuned size stays aligned.
+      expect(thumb.getAttribute("style")).toContain("--hk-icon-group-active-index: 0");
+
+      const buttons = [...c.querySelectorAll<HTMLButtonElement>(".hk-icon-group-item")];
+      buttons[1]!.click();
+      await nextTick();
+      const thumbAfter = c.querySelector<HTMLElement>(".hk-icon-group-slider-thumb")!;
+      expect(thumbAfter.getAttribute("style")).toContain("--hk-icon-group-active-index: 1");
+      expect(buttons[1]!.dataset.active).toBe("true");
+    });
+
+    it("slider suppresses the thumb without a single active key", () => {
+      const noSelection = mountComp(() =>
+        h(HkIconButtonGroup, { options, mode: "single", variant: "slider", modelValue: null }),
+      );
+      expect(noSelection.querySelector(".hk-icon-group-slider-thumb")).toBeNull();
+
+      const multiple = mountComp(() =>
+        h(HkIconButtonGroup, {
+          options,
+          mode: "multiple",
+          variant: "slider",
+          modelValue: ["totp"],
+        }),
+      );
+      // "multiple" tints each item instead — one thumb cannot hop
+      // between simultaneous selections.
+      expect(multiple.querySelector(".hk-icon-group-slider-thumb")).toBeNull();
+      const items = [...multiple.querySelectorAll<HTMLElement>(".hk-icon-group-item")];
+      expect(items[0]!.dataset.active).toBe("true");
+
+      const buttons = mountComp(() =>
+        h(HkIconButtonGroup, { options, mode: "buttons", variant: "slider" }),
+      );
+      expect(buttons.querySelector(".hk-icon-group-slider-thumb")).toBeNull();
+    });
+
+    it("keeps the per-item active tint in multiple+slider (SCSS contract)", () => {
+      // jsdom cannot compute styles, so pin the selector itself: the
+      // "active item paints transparent, the thumb is its highlight"
+      // rule must be scoped to single mode — in multiple+slider the
+      // thumb is suppressed and the per-item tint is the only active
+      // indication left (R1 finding: an unscoped rule wiped it).
+      // vitest transforms this file — import.meta.url is not a file:
+      // URL here; resolve from the package root (the runner's cwd).
+      const scss = readFileSync(
+        join(process.cwd(), "src/components/HkIconButtonGroup.scss"),
+        "utf-8",
+      );
+      expect(scss).toContain(
+        ".hk-icon-group-single.hk-icon-group-slider .hk-icon-group-item[data-active]",
+      );
+      // Anchored to line start: the scoped selector CONTAINS the
+      // unscoped substring, so only a BOL match proves the rule lost
+      // its single-mode scoping.
+      expect(scss).not.toMatch(
+        /^\.hk-icon-group-slider \.hk-icon-group-item\[data-active\]/m,
+      );
+      // Same contract, sibling guard (R2 M6): direct-child items must
+      // not flex-shrink under a width-constrained host — the thumb keeps
+      // the full item-size width and would silently misalign behind
+      // compressed items.
+      const itemBlock = scss.match(
+        /\.hk-icon-group-slider \.hk-icon-group-item \{[^}]*\}/,
+      );
+      expect(itemBlock).toBeTruthy();
+      expect(itemBlock![0]).toContain("flex: none");
+    });
+  });
 });

package/src/components/HkIconButtonGroup.tsx

@@ -48,6 +48,19 @@ export interface HkIconButtonGroupOption {
  * (text = the option's label unless overridden), so the hover reveal is
  * built in rather than left to every consumer.
  *
+ * Visual variants (`variant`, orthogonal to the semantic `mode` — the
+ * 2026-09-17 user direction: a frame is not part of a group's meaning,
+ * and hosts must be able to tune it):
+ *  - "track" (default): the bordered inset strip — the HkTabs grammar
+ *    this component shipped with;
+ *  - "plain": no outer frame at all — independent icon buttons packed
+ *    shoulder-to-shoulder, each tinting its own active state;
+ *  - "slider": frameless and gapless with a sliding thumb pill behind
+ *    the active item (single-selection mode; "multiple" falls back to
+ *    per-item tints). The thumb rides a CSS-variable index
+ *    (`--hk-icon-group-active-index`) times the item-size variable, so
+ *    it stays correct when hosts retune the size.
+ *
  * Known a11y limitation (documented 2026-09-13): single mode uses a
  * radiogroup role with every item tabbable, not the full WAI-APG roving
  * tabindex. All-items-tabbable keeps keyboard reachability identical
@@ -63,6 +76,8 @@ export default defineComponent({
      *  active — required/ignored by "buttons" mode. */
     modelValue: { type: [String, Array] as PropType<string | string[] | null>, default: null },
     mode: { type: String as PropType<"buttons" | "single" | "multiple">, default: "buttons" },
+    /** Visual treatment of the strip — see the component doc. */
+    variant: { type: String as PropType<"track" | "plain" | "slider">, default: "track" },
     size: { type: String as PropType<"sm" | "md" | "lg">, default: "md" },
     disabled: { type: Boolean, default: false },
     tooltipPlacement: { type: String as PropType<TooltipPlacement>, default: "top" },
@@ -79,11 +94,36 @@ export default defineComponent({
     const cls = computed(() => [
       "hk-icon-group",
       `hk-icon-group-${props.mode}`,
+      `hk-icon-group-${props.variant}`,
       `hk-icon-group-${props.size}`,
     ]);
 
     const groupRole = computed(() => (props.mode === "single" ? "radiogroup" : "group"));
 
+    /** Index of the single active option, -1 when none — drives the
+     *  slider thumb's CSS-variable position. */
+    const activeIndex = computed(() =>
+      props.options.findIndex((o) => isActive(o.key)),
+    );
+
+    /** The slider thumb exists only for a single-selection strip with an
+     *  active key: "multiple" tints each item instead (one thumb cannot
+     *  hop between simultaneous selections), "buttons" has no selection
+     *  at all. */
+    const showThumb = computed(
+      () =>
+        props.variant === "slider" &&
+        props.mode === "single" &&
+        activeIndex.value >= 0,
+    );
+
+    const thumbStyle = computed(() => ({
+      // The transition lives in the stylesheet; the position is pure
+      // arithmetic on the active index so a retuned item-size variable
+      // keeps the thumb aligned without JS measurement.
+      "--hk-icon-group-active-index": String(Math.max(activeIndex.value, 0)),
+    }));
+
     function isActive(key: string): boolean {
       if (props.mode === "multiple") {
         return Array.isArray(props.modelValue) && props.modelValue.includes(key);
@@ -111,6 +151,13 @@ export default defineComponent({
 
     return () => (
       <div class={cls.value} role={groupRole.value} {...attrs}>
+        {showThumb.value && (
+          <span
+            class="hk-icon-group-slider-thumb"
+            aria-hidden="true"
+            style={thumbStyle.value}
+          />
+        )}
         {props.options.map((option) => {
           const tooltip = option.tooltip !== undefined ? option.tooltip : option.label;
           const active = isActive(option.key);