@celestia-island/hikari 0.47.0 → 0.48.0

package/package.json

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

package/src/components/HkAuthMethodList.scss

@@ -1,8 +1,12 @@
-/* Alternative sign-in methods as an icon button group (login card). The
-   block container `.s-auth-methods` and its spacing are owned by
-   HkAuthCard's slot styles (styles/admin-tokens.scss); this file only
-   styles the divider and the icon group row the component renders into
-   that slot. */
+/* Alternative sign-in methods as CENTERED INDEPENDENT framed icon tiles
+ * (login card). The block container `.s-auth-methods` and its spacing are
+ * owned by HkAuthCard's slot styles (styles/admin-tokens.scss); this file
+ * only styles the divider and the tile row the component renders into that
+ * slot.
+ *
+ * Deliberately NOT a button group (2026-09-14 user direction): no shared
+ * track, no shared frame — each provider carries its own border so the row
+ * stays as wide as its content, centered in the card. */
 
 /* "Other ways to sign in" divider row between rules. */
 .s-auth-methods-divider {
@@ -24,16 +28,91 @@
 }
 
 /* The component's own wrapper is `display: contents` — layout-wise the
-   divider and the group row remain direct children of HkAuthCard's
+   divider and the tile row remain direct children of HkAuthCard's
    `.s-auth-methods` slot container. */
 .s-auth-methods-list {
   display: contents;
 }
 
-/* The icon button group row: fill the card column and center the
-   provider tiles inside it (descendant match off `.s-auth-methods` —
-   the wrapper generates no box of its own). */
-.s-auth-methods .hk-icon-group.s-auth-methods-group {
+/* The tile row: fill the card column and center the independent tiles
+   inside it. The gap between tiles is the INDEPENDENT-action spacing
+   (--space-12) — comfortable air, unlike a group's shoulder-to-shoulder
+   track gap. */
+.s-auth-methods .s-auth-methods-tiles {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-12, 0.75rem);
   width: 100%;
+}
+
+/* The HkTooltip wrapper span is the flex child between tiles — let it
+   shrink to the button so the row gap (not the wrapper) spaces them. */
+.s-auth-methods .s-auth-methods-tiles > .hk-tooltip-wrapper {
+  display: inline-flex;
+  flex: none;
+}
+
+/* One provider tile: a framed 44px square (the login-chooser tile size,
+   same as the icon group's md item). Each tile owns its whole frame —
+   border, hover wash, focus ring — with no track around the row. */
+.s-auth-methods-tile {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.75rem;
+  height: 2.75rem;
+  padding: 0;
+  font: inherit;
+  color: rgb(var(--color-text, 25 30 40));
+  background: rgb(var(--color-surface, 255 255 255) / 55%);
+  border: 1px solid rgb(var(--color-border, 222 224 228) / 55%);
+  border-radius: var(--radius-md, 8px);
+  cursor: pointer;
+  outline: none;
+  transition-property: background-color, border-color, color, box-shadow, opacity, transform;
+  transition-duration: var(--duration-short, 0.15s);
+  transition-timing-function: ease;
+
+  /* A real <button disabled> still matches :hover — guard the dead ones. */
+  &:hover:not(:disabled) {
+    color: rgb(var(--color-text, 25 30 40));
+    background: var(--c-primary-faint, rgb(var(--color-primary, 90 140 255) / 5%));
+    border-color: var(--c-primary-medium, rgb(var(--color-primary, 90 140 255) / 25%));
+  }
+
+  /* Tactile press feedback — the button-family cadence. */
+  &:active:not(:disabled) {
+    transform: scale(0.96);
+  }
+
+  /* Outset double ring, same grammar as .hk-btn. */
+  &:focus-visible {
+    box-shadow:
+      0 0 0 2px rgb(var(--color-surface, 255 255 255)),
+      0 0 0 4px rgb(var(--color-primary, 90 140 255));
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.s-auth-methods-tile-icon {
+  display: inline-flex;
+  align-items: center;
   justify-content: center;
+  line-height: 0;
+  /* Brand marks (svg/img vnodes) at their intrinsic size; lucide comps
+     sized by the host. The box never grows past the square. */
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.s-auth-methods-tile-initial {
+  font-size: var(--text-sm, 0.8125rem);
+  font-weight: 600;
+  line-height: 1;
 }

package/src/components/HkAuthMethodList.test.tsx

@@ -28,27 +28,39 @@ const methods = [
 ];
 
 describe("HkAuthMethodList", () => {
-  it("renders the provider row as an icon button group with an optional divider", () => {
+  it("renders centered independent framed tiles with an optional divider", () => {
     // The card's `methods` slot owns the `.s-auth-methods` container —
-    // reproduce that context here (the divider and the group row are layout
+    // reproduce that context here (the divider and the tile row are layout
     // children of it through the component's display:contents wrapper).
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { divider: "其他方式登录", methods })),
     );
     const divider = c.querySelector(".s-auth-methods-divider");
     expect(divider?.textContent).toContain("其他方式登录");
-    const group = c.querySelector<HTMLElement>(".s-auth-methods .hk-icon-group");
-    expect(group).toBeTruthy();
-    expect(group!.classList.contains("hk-icon-group-buttons")).toBe(true);
-    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-icon-group-item");
-    expect(buttons.length).toBe(2);
+    const tiles = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .s-auth-methods-tile");
+    expect(tiles.length).toBe(2);
     // Icon-only: the label is the accessible name + tooltip, never visible text.
-    expect(buttons[0]!.getAttribute("aria-label")).toBe("GitHub");
-    expect(buttons[1]!.getAttribute("aria-label")).toBe("LinuxDo");
-    expect(buttons[0]!.textContent).not.toContain("GitHub");
+    expect(tiles[0]!.getAttribute("aria-label")).toBe("GitHub");
+    expect(tiles[1]!.getAttribute("aria-label")).toBe("LinuxDo");
+    expect(tiles[0]!.textContent).not.toContain("GitHub");
   });
 
-  it("wraps every item in a tooltip carrying the provider label", () => {
+  it("never wraps the providers in a button-group track", () => {
+    // 2026-09-14 user direction: a shared group frame (one wide bordered
+    // track with the icons floating inside) is NOT this component's
+    // grammar — every provider is an independent framed tile. A regression
+    // back to HkIconButtonGroup (or any .hk-icon-group markup) must fail
+    // here, because the button group is reserved for selectors and tight
+    // action strips.
+    const c = mount(
+      h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })),
+    );
+    expect(c.querySelector(".s-auth-methods .hk-icon-group")).toBeNull();
+    expect(c.querySelector(".s-auth-methods [role='group']")).toBeNull();
+    expect(c.querySelector(".s-auth-methods [role='radiogroup']")).toBeNull();
+  });
+
+  it("wraps every tile in a tooltip carrying the provider label", () => {
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })),
     );
@@ -71,12 +83,12 @@ describe("HkAuthMethodList", () => {
         },
       })),
     );
-    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-icon-group-item");
-    buttons[1]!.click();
+    const tiles = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .s-auth-methods-tile");
+    tiles[1]!.click();
     await nextTick();
     // Both rows are asserted so a constant-literal emit cannot ride an
     // accidental fixture coincidence.
-    buttons[0]!.click();
+    tiles[0]!.click();
     await nextTick();
     expect(picked).toEqual(["linuxdo", "github"]);
   });
@@ -95,15 +107,15 @@ describe("HkAuthMethodList", () => {
         },
       })),
     );
-    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-icon-group-item");
-    expect(buttons.length).toBe(3);
-    // The prebuilt brand vnode renders inside the icon column.
-    expect(buttons[0]!.querySelector(".brand-gh")).toBeTruthy();
+    const tiles = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .s-auth-methods-tile");
+    expect(tiles.length).toBe(3);
+    // The prebuilt brand vnode renders inside the icon box.
+    expect(tiles[0]!.querySelector(".brand-gh")).toBeTruthy();
     // A missing icon falls back to the label initial (never an empty box).
-    expect(buttons[2]!.querySelector<HTMLElement>(".hk-icon-group-item-initial")?.textContent).toBe("F");
+    expect(tiles[2]!.querySelector<HTMLElement>(".s-auth-methods-tile-initial")?.textContent).toBe("F");
     // Disabled entries render dead and swallow clicks.
-    expect(buttons[1]!.disabled).toBe(true);
-    buttons[1]!.click();
+    expect(tiles[1]!.disabled).toBe(true);
+    tiles[1]!.click();
     await nextTick();
     expect(picked).toBe("");
   });

package/src/components/HkAuthMethodList.tsx

@@ -1,23 +1,27 @@
 import { defineComponent } from "vue";
-import HkIconButtonGroup from "./HkIconButtonGroup";
+import HkTooltip from "./HkTooltip";
 import "./HkAuthMethodList.scss";
 
 /**
  * HkAuthMethodList — the auth card's third-party sign-in block (the
  * "other ways to sign in" row under the credentials form).
  *
- * Since 2026-09-13 (user direction) the block renders as the ICON
- * BUTTON GROUP by default: one centered `HkIconButtonGroup` row of
- * icon-only provider buttons (mode "buttons", size md) instead of the
- * stacked full-width [icon | label] buttons. Provider identity is
- * revealed on hover — every item wraps itself in an HkTooltip with the
- * provider label — which matches the platform login-chooser pattern
- * (Windows/macOS account tiles) and keeps the card compact when a
- * deployment offers several providers. The `select` event carries the
- * provider `key` exactly as before, so consumers swap rendering
- * without touching their OAuth flow.
+ * Since 2026-09-14 (user direction) the block renders as CENTERED
+ * INDEPENDENT icon tiles: every provider is its own framed 44px icon
+ * button with its own tooltip — NOT a button group. A group track (one
+ * shared frame stretched across the card with the icons floating in
+ * the middle) reads as an oversized empty box; the button-group
+ * component is reserved for its two fundamental jobs — a selector
+ * (single/multiple) and a tight action strip (see HkIconButtonGroup).
  *
- * The wrapper stays `display: contents`: the divider and the group row
+ * Provider identity is revealed on hover: each tile wraps itself in an
+ * HkTooltip carrying the provider label, which matches the platform
+ * login-chooser pattern (Windows/macOS account tiles) and keeps the
+ * card compact when a deployment offers several providers. The
+ * `select` event carries the provider `key` exactly as before, so
+ * consumers swap rendering without touching their OAuth flow.
+ *
+ * The wrapper stays `display: contents`: the divider and the tile row
  * remain layout children of HkAuthCard's `.s-auth-methods` slot
  * container (it owns the side padding and vertical rhythm).
  */
@@ -35,11 +39,11 @@ export default defineComponent({
         /** Accessible name + tooltip text (the hover reveal). */
         label: string;
         /** Prebuilt icon vnode (brand SVG, <img>, …) rendered inside the
-         *  icon-only button. Typed loose on purpose (same as
-         *  HkIconButtonGroup options): hosts materialize hikari against
-         *  their own vue store, and a hard VNode type breaks typecheck
-         *  whenever the host's vue minor differs. A missing icon falls
-         *  back to the label's initial. */
+         *  framed tile. Typed loose on purpose (same as HkIconButtonGroup
+         *  options): hosts materialize hikari against their own vue store,
+         *  and a hard VNode type breaks typecheck whenever the host's vue
+         *  minor differs. A missing icon falls back to the label's
+         *  initial. */
         icon?: unknown;
         disabled?: boolean;
       }>,
@@ -47,7 +51,7 @@ export default defineComponent({
     },
   },
   emits: {
-    /** A provider button was clicked. */
+    /** A provider tile was clicked. */
     select: (_key: string) => true,
   },
   setup(props, { emit }) {
@@ -58,18 +62,42 @@ export default defineComponent({
             <span>{props.divider}</span>
           </div>
         )}
-        <HkIconButtonGroup
-          class="s-auth-methods-group"
-          mode="buttons"
-          size="md"
-          options={props.methods.map((method) => ({
-            key: method.key,
-            label: method.label,
-            icon: method.icon,
-            disabled: method.disabled === true,
-          }))}
-          onSelect={(key: string) => emit("select", key)}
-        />
+        {/* A plain row, deliberately NOT role="group": every tile is an
+            independent action (its own frame, its own tooltip), and the
+            divider above names the section for sighted users. Group
+            semantics belong to the selector/tight-strip components. */}
+        <div class="s-auth-methods-tiles">
+          {props.methods.map((method) => {
+            const tile = (
+              <button
+                key={method.key}
+                type="button"
+                class="s-auth-methods-tile"
+                data-key={method.key}
+                aria-label={method.label}
+                title={undefined} // the HkTooltip popup owns the hover text
+                disabled={method.disabled === true}
+                onClick={() => emit("select", method.key)}
+              >
+                <span class="s-auth-methods-tile-icon" aria-hidden="true">
+                  {method.icon != null
+                    ? method.icon
+                    : (
+                      <span class="s-auth-methods-tile-initial">
+                        {method.label.charAt(0).toUpperCase()}
+                      </span>
+                    )
+                  }
+                </span>
+              </button>
+            );
+            return (
+              <HkTooltip key={method.key} text={method.label} placement="top" delay={300}>
+                {tile}
+              </HkTooltip>
+            );
+          })}
+        </div>
       </div>
     );
   },

package/src/components/HkBlockingToast.scss

@@ -9,7 +9,9 @@
 .hk-blocking-toast-container {
   position: fixed;
   top: 4rem;
-  inset-inline-end: 1rem;
+  /* Same viewport gutter the anchored popups clamp to (16px desktop /
+   * 8px mobile) — the toast stack is a floating layer too. */
+  inset-inline-end: var(--viewport-gutter, 1rem);
   z-index: var(--hk-z-toast, 4000);
   max-width: 24rem;
   pointer-events: none;

package/src/components/HkIconButtonGroup.tsx

@@ -25,13 +25,21 @@ export interface HkIconButtonGroupOption {
  * HkIconButtonGroup — the icon-only variant of the button-group family
  * (the same centered strip grammar as HkTabs, minus the text).
  *
- * Three working modes:
- *   - "buttons"  a plain action group (no selection state) — the auth
- *                card's OAuth provider row
- *   - "single"   a radiogroup: one active key (v-model), re-clicking the
- *                active key is a no-op — radio semantics
- *   - "multiple" a toggle group: v-model is a string[] of active keys,
- *                every item carries aria-pressed
+ * The group has exactly TWO fundamental jobs (2026-09-14 user direction
+ * — a group is a semantic component, not a generic box to throw buttons
+ * into), carried by three working modes:
+ *   - a SELECTOR: "single" (radiogroup: one active key via v-model,
+ *     re-clicking the active key is a no-op — radio semantics) or
+ *     "multiple" (toggle set: v-model is a string[] of active keys,
+ *     every item carries aria-pressed)
+ *   - a TIGHT ACTION STRIP: "buttons" (no selection state) — related
+ *     actions packed shoulder-to-shoulder in ONE shared track, the
+ *     toolbar grammar
+ *
+ * Anything else is NOT a group: independent actions that merely live on
+ * the same row (e.g. a login card's third-party provider tiles) render
+ * as separate framed buttons with comfortable spacing — see
+ * HkAuthMethodList for the reference pattern.
  *
  * Every item is icon-only and rides one size taller than a standard
  * icon button (md = 44px vs the 32px icon button / 40px text button) —

package/src/components/HkMenu.tsx

@@ -14,6 +14,7 @@ import { Check, ChevronRight } from "lucide-vue-next";
 
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { ancestorZoom } from "../runtime/cssZoom";
+import { viewportGutterPx } from "../runtime/viewportGutter";
 import HkSelectPanel, { type SelectPanelPlacement } from "./HkSelectPanel";
 import "./HkMenu.scss";
 
@@ -58,8 +59,6 @@ export interface HkMenuItem {
   children?: HkMenuItem[];
 }
 
-/** Viewport padding mirrored from HkSelectPanel's popout geometry. */
-const VIEWPORT_PAD = 8;
 /** Width estimate used ONLY to pick a cascade's flip side; the real
  *  panel box is measured by HkSelectPanel itself. */
 const CASCADE_PANEL_W = 224;
@@ -415,8 +414,10 @@ export default defineComponent({
             const r = row.getBoundingClientRect();
             if (!r.width && !r.height) return pointRect(0, 0); // detached
             const cascadeW = CASCADE_PANEL_W * ancestorZoom(document.body);
-            const openRight = r.right + cascadeW <= window.innerWidth - VIEWPORT_PAD;
-            const left = openRight ? r.right : Math.max(VIEWPORT_PAD, r.left - cascadeW);
+            // Shared viewport gutter (--viewport-gutter: 8 mobile / 16 desktop).
+            const pad = viewportGutterPx();
+            const openRight = r.right + cascadeW <= window.innerWidth - pad;
+            const left = openRight ? r.right : Math.max(pad, r.left - cascadeW);
             return pointRect(left, r.top);
           },
           contains: (node) => !!rowRefs.value[id]?.contains(node),
@@ -438,11 +439,13 @@ export default defineComponent({
           if (!r.width && !r.height) return pointRect(0, 0);
           const gap = props.offset; // visual-space gap, same as the native placements
           const cascadeW = CASCADE_PANEL_W * ancestorZoom(document.body);
-          const openRight = r.right + gap + cascadeW <= window.innerWidth - VIEWPORT_PAD;
+          // Shared viewport gutter (--viewport-gutter: 8 mobile / 16 desktop).
+          const pad = viewportGutterPx();
+          const openRight = r.right + gap + cascadeW <= window.innerWidth - pad;
           const left =
             side === "right" && openRight
               ? r.right + gap
-              : Math.max(VIEWPORT_PAD, r.left - cascadeW - gap);
+              : Math.max(pad, r.left - cascadeW - gap);
           return pointRect(left, r.top);
         },
         contains: (node) => !!props.anchorRef?.contains(node),

package/src/components/HkModal.tsx

@@ -115,6 +115,20 @@ export function resolveModalWidth(width: string): string {
   return value;
 }
 
+/**
+ * Cap the resolved max-width so the centered desktop frame always keeps
+ * the shared viewport gutter (--viewport-gutter: 16px desktop / 8px
+ * mobile) clear on both sides — a frame wider than the window can spare
+ * used to run edge-to-edge. `100%` resolves against the fixed frame's
+ * containing block (the initial containing block), so the cap tracks the
+ * live window; the ≤767px sheet branch overrides max-width with
+ * `100% !important` in the SCSS, so the intentional full-bleed mobile
+ * sheet is untouched.
+ */
+export function modalFrameMaxWidth(resolved: string): string {
+  return `min(${resolved}, calc(100% - 2 * var(--viewport-gutter, 16px)))`;
+}
+
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
@@ -194,7 +208,9 @@ export default defineComponent({
 
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
-    const resolvedWidth = computed(() => resolveModalWidth(props.width));
+    const resolvedWidth = computed(() =>
+      modalFrameMaxWidth(resolveModalWidth(props.width)),
+    );
     // Layer/dialog name: the explicit surface name wins over the header
     // title (which header-less surfaces never pass).
     const resolvedSurfaceName = computed(() => props.surfaceTitle ?? props.title);

package/src/components/HkModal.width.test.tsx

@@ -104,11 +104,15 @@ describe("HkModal width rendering", () => {
 
   it("renders a named preset as the frame's max-width", async () => {
     const content = await mountModal("sm");
-    expect(content.style.maxWidth).toBe("32rem");
+    expect(content.style.maxWidth).toBe(
+      "min(32rem, calc(100% - 2 * var(--viewport-gutter, 16px)))",
+    );
   });
 
   it("renders an arbitrary CSS length as the frame's max-width", async () => {
     const content = await mountModal("560px");
-    expect(content.style.maxWidth).toBe("560px");
+    expect(content.style.maxWidth).toBe(
+      "min(560px, calc(100% - 2 * var(--viewport-gutter, 16px)))",
+    );
   });
 });

package/src/components/HkPopover.scss

@@ -9,7 +9,7 @@
 
 .hk-popover-panel {
   min-width: 0;
-  max-height: min(70vh, calc(100vh - 2 * 8px));
+  max-height: min(70vh, calc(100vh - 2 * var(--viewport-gutter, 16px)));
   /* Width MUST be position-independent (max-content, viewport-capped).
    * The anchored panel is fixed-positioned with shrink-to-fit sizing,
    * and computePosition places it as `left = anchorEnd - panelWidth`
@@ -21,9 +21,10 @@
    * wider frame by frame (demo.dev field report 2026-09-07). Pinning
    * the width to max-content breaks the loop: the panel sizes to its
    * content wherever it sits, and positioning converges in one pass.
-   * VIEWPORT_PAD is 8 (script side). */
+   * The script-side pad reads the same --viewport-gutter token
+   * (runtime/viewportGutter). */
   width: max-content;
-  max-width: calc(100vw - 2 * 8px);
+  max-width: calc(100vw - 2 * var(--viewport-gutter, 16px));
 }
 
 /* Pop motion family tokens (--hk-pop-* in theme.scss) — the reference

package/src/components/HkPopover.sheet-maxwidth.test.ts

@@ -6,8 +6,9 @@
  * / HkSelectPanel sheets, hence "some have it, some don't").
  *
  * Root cause: the base `.hk-popover-panel` rule sets
- * `max-width: calc(100vw - 2 * 8px)` (the anchored panel's
- * anti-ratchet clamp, #421). The mobile sheet branch overrides
+ * `max-width: calc(100vw - 2 * <viewport pad>)` (the anchored panel's
+ * anti-ratchet clamp, #421; today the shared `--viewport-gutter` token).
+ * The mobile sheet branch overrides
  * `width: auto` but inherited the max-width, over-constraining the
  * inline `left: 0; right: 0` docking — the used width resolved to
  * 100vw - 16px and LTR dropped the `right` constraint. Pinned here so

package/src/components/HkPopover.surfacevars.test.ts

@@ -27,7 +27,9 @@ describe("HkPopover glass layer surface hooks", () => {
   it("pins the anchored panel width to max-content and resets the sheet", () => {
     const base = src.match(/\.hk-popover-panel\s*{[^}]*}/)![0];
     expect(base).toContain("width: max-content");
-    expect(base).toContain("max-width: calc(100vw - 2 * 8px)");
+    // The viewport caps ride the shared --viewport-gutter token (16px
+    // desktop / 8px mobile) — the same value the script-side clamp reads.
+    expect(base).toContain("max-width: calc(100vw - 2 * var(--viewport-gutter, 16px))");
     const sheet = src.match(/\.hk-popover-panel\.hk-is-sheet\s*{[^}]*}/)![0];
     expect(sheet).toContain("width: auto");
   });

package/src/components/HkPopover.tsx

@@ -15,6 +15,7 @@ import {
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { ancestorZoom } from "../runtime/cssZoom";
+import { clampWithGutter, viewportGutterPx } from "../runtime/viewportGutter";
 import { useI18n } from "../i18n/context";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
@@ -39,8 +40,6 @@ function parsePlacement(p: PopupPlacement): { side: BaseSide; align: Align } {
   return { side, align: align ?? "center" };
 }
 
-const VIEWPORT_PAD = 8;
-
 export default defineComponent({
   name: "HkPopover",
   props: {
@@ -323,6 +322,10 @@ export default defineComponent({
       }
       const vw = window.innerWidth;
       const vh = window.innerHeight;
+      // The shared viewport gutter (--viewport-gutter: 8px mobile / 16px
+      // desktop) — read per reposition so a viewport crossing the
+      // breakpoint re-clamps with the right value on the next pass.
+      const pad = viewportGutterPx();
 
       let { side } = parsePlacement(props.placement);
       const { align } = parsePlacement(props.placement);
@@ -331,25 +334,25 @@ export default defineComponent({
         if (side === "bottom") {
           const spaceBelow = vh - anchorRect.bottom;
           const spaceAbove = anchorRect.top;
-          if (spaceBelow < panelRect.height + VIEWPORT_PAD && spaceAbove > spaceBelow) {
+          if (spaceBelow < panelRect.height + pad && spaceAbove > spaceBelow) {
             side = "top";
           }
         } else if (side === "top") {
           const spaceAbove = anchorRect.top;
           const spaceBelow = vh - anchorRect.bottom;
-          if (spaceAbove < panelRect.height + VIEWPORT_PAD && spaceBelow > spaceAbove) {
+          if (spaceAbove < panelRect.height + pad && spaceBelow > spaceAbove) {
             side = "bottom";
           }
         } else if (side === "right") {
           const spaceRight = vw - anchorRect.right;
           const spaceLeft = anchorRect.left;
-          if (spaceRight < panelRect.width + VIEWPORT_PAD && spaceLeft > spaceRight) {
+          if (spaceRight < panelRect.width + pad && spaceLeft > spaceRight) {
             side = "left";
           }
         } else if (side === "left") {
           const spaceLeft = anchorRect.left;
           const spaceRight = vw - anchorRect.right;
-          if (spaceLeft < panelRect.width + VIEWPORT_PAD && spaceRight > spaceLeft) {
+          if (spaceLeft < panelRect.width + pad && spaceRight > spaceLeft) {
             side = "right";
           }
         }
@@ -374,7 +377,7 @@ export default defineComponent({
       } else {
         crossPos = anchorStart + (anchorSize - panelSize) / 2;
       }
-      crossPos = Math.max(VIEWPORT_PAD, Math.min(crossPos, viewportSize - panelSize - VIEWPORT_PAD));
+      crossPos = clampWithGutter(crossPos, panelSize, viewportSize, pad);
 
       if (side === "bottom") {
         c.top = anchorRect.bottom + off;
@@ -391,13 +394,13 @@ export default defineComponent({
       }
 
       if (side === "bottom") {
-        c.top = Math.max(VIEWPORT_PAD, Math.min(c.top!, vh - panelRect.height - VIEWPORT_PAD));
+        c.top = clampWithGutter(c.top!, panelRect.height, vh, pad);
       } else if (side === "top") {
-        c.bottom = Math.max(VIEWPORT_PAD, Math.min(c.bottom ?? 0, vh - panelRect.height - VIEWPORT_PAD));
+        c.bottom = clampWithGutter(c.bottom ?? 0, panelRect.height, vh, pad);
       } else if (side === "right") {
-        c.left = Math.max(VIEWPORT_PAD, Math.min(c.left!, vw - panelRect.width - VIEWPORT_PAD));
+        c.left = clampWithGutter(c.left!, panelRect.width, vw, pad);
       } else {
-        c.right = Math.max(VIEWPORT_PAD, Math.min(c.right ?? 0, vw - panelRect.width - VIEWPORT_PAD));
+        c.right = clampWithGutter(c.right ?? 0, panelRect.width, vw, pad);
       }
 
       coords.value = c;

package/src/components/HkSelect.scss

@@ -119,6 +119,17 @@
   position: fixed;
   min-width: 180px;
 
+  /* Width is position-independent (same contract as .hk-popover-panel):
+   * max-content sizes the popout to its rows wherever it sits, instead
+   * of shrink-to-fitting against `viewport - left` — an anchor near the
+   * right screen edge used to squeeze the panel down to the leftover
+   * space. The viewport cap (2 × the --viewport-gutter token, 16px
+   * desktop / 8px mobile) bounds it on both edges; the inline
+   * matchAnchorWidth min-width still wins over both, as documented
+   * above. */
+  width: max-content;
+  max-width: calc(100vw - 2 * var(--viewport-gutter, 16px));
+
   /* Pop motion family — the popout grows out of the anchor edge (or
    * midpoint, for the -center placements) it sits on (data-side/data-align
    * are set by HkSelectPanel from the RESOLVED placement, including after