@eifi1/ui-kit 0.17.0 → 0.19.0

package/src/components/account-chips.tsx

@@ -0,0 +1,302 @@
+import type { ReactElement, ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+import { cn } from "../lib/cn";
+import { formatDate, formatRelativeTime, toDate, EMPTY_FORMATTED_VALUE } from "../lib/format";
+import type { DateInput, FormatDateStyle, FormatRelativeTimeOptions } from "../lib/format";
+import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { Chip } from "./chip";
+import type { ChipShape, ChipSize, ChipTone, ChipVariant } from "./chip";
+import { Tooltip } from "./tooltip";
+import type { DataTableColumn } from "./data-table";
+
+/**
+ * The parts an admin roster repeats (0.18.0) — and only those.
+ *
+ * Kurvenschmiede (features/admin/users-panel.tsx, allowlist-panel.tsx) and keksdose
+ * (features/admin/users-panel.tsx, the allowlist card in admin-page.tsx) each built the
+ * same table: name over email, a role, whether the account is active, created, last
+ * login, a row of actions, and an allowlist with a note. What they share is not the
+ * table — the columns around it (keksdose's plan and privacy mode, Kurvenschmiede's
+ * owned-work counts and its role SELECT), the actions and every rule about who may do
+ * what are each app's own. What they share is the vocabulary: both spelled the same
+ * square, uppercase status chip by hand (keksdose's `Badge` with its own tone map,
+ * Kurvenschmiede's inline `<Chip size="xs" shape="square" caps>`), and both formatted
+ * their two date columns by hand (`toLocaleDateString` in one, a "3 days ago" helper
+ * in the other). So: {@link RoleChip}, {@link AccountStateChip} and
+ * {@link dateColumn}, and the roster stays the app's `DataTable`.
+ */
+
+/** The chip look both rosters use: a square, uppercase status tag. Each can be changed. */
+interface AccountChipLook {
+  /** Default `sm` — keksdose's roster; Kurvenschmiede's denser lists pass `xs`. */
+  size?: ChipSize;
+  /** Default `soft`. `dot` for a column of them that should not outshout the names. */
+  variant?: ChipVariant;
+  /** Default `square`: a chip in a table cell, beside square controls. */
+  shape?: ChipShape;
+  /** Default true — the status-badge type. */
+  caps?: boolean;
+  className?: string;
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+/* ── RoleChip ──────────────────────────────────────────────────────────────── */
+
+/** How one role is drawn. `label` is the app's, translated. */
+export interface RoleDefinition {
+  label: string;
+  tone?: ChipTone;
+  /** A lucide component or an element — Kurvenschmiede marks its admins with a shield. */
+  icon?: LucideIcon | ReactElement;
+}
+
+/**
+ * Every role an app has, keyed by the value its API sends. Annotate the app's table
+ * with it (`const ROLES: RoleVocabulary<UserRole> = {…}`) and TypeScript asks for a
+ * label when a role is added.
+ */
+export type RoleVocabulary<R extends string = string> = Readonly<Record<R, RoleDefinition>>;
+
+export interface RoleChipProps<R extends string = string> extends AccountChipLook {
+  /**
+   * The role key as the API sends it. `null` / `undefined` renders nothing. Named
+   * `value`, not `role`, because `role` on a JSX element is the ARIA role — the lint
+   * rule and every reader would take it for one.
+   */
+  value: R | null | undefined;
+  /** What each key is called and how it is toned. A key missing here is shown as the
+   *  key itself, in `neutral`: an unknown role is still a fact the admin should see. */
+  roles: Readonly<Partial<Record<R, RoleDefinition>>>;
+}
+
+/**
+ * A role as a chip: the API's key looked up in the app's {@link RoleVocabulary}.
+ *
+ * The vocabulary is a prop and not kit English, because the roles are the app's —
+ * Kurvenschmiede has admin, member and customer, keksdose admin and user, kastlan its
+ * own — and so are their names. Carries `data-role` with the key, for a test or a
+ * style hook.
+ */
+export function RoleChip<R extends string = string>({
+  value: role,
+  roles,
+  size = "sm",
+  variant,
+  shape = "square",
+  caps = true,
+  className,
+  ...rest
+}: RoleChipProps<R>) {
+  if (role === null || role === undefined || role === "") return null;
+  const def = roles[role];
+  return (
+    <Chip
+      {...rest}
+      data-role={role}
+      tone={def?.tone ?? "neutral"}
+      icon={def?.icon}
+      size={size}
+      variant={variant}
+      shape={shape}
+      caps={caps}
+      className={className}
+    >
+      {def?.label ?? role}
+    </Chip>
+  );
+}
+
+/* ── AccountStateChip ──────────────────────────────────────────────────────── */
+
+/**
+ * The states both rosters show, each as the app's own flag maps onto it:
+ *
+ * - `active` / `inactive` — the account may sign in, or an admin switched it off
+ *   (both apps' `is_active`).
+ * - `invited` — on the allowlist and mailed, not registered yet (an allowlist row).
+ * - `registered` — an allowlist row whose address has an account now (Kurvenschmiede).
+ * - `unverified` — the email address is not confirmed (keksdose).
+ * - `passwordChange` — must set a new password at the next sign-in (keksdose).
+ *
+ * An account can be several at once (inactive AND unverified): render one chip per
+ * state, as keksdose's state column does.
+ */
+export type AccountState = "active" | "inactive" | "invited" | "registered" | "unverified" | "passwordChange";
+
+export type AccountStateLabels = Record<AccountState, string>;
+
+export const DEFAULT_ACCOUNT_STATE_LABELS: AccountStateLabels = {
+  active: "Active",
+  inactive: "Inactive",
+  invited: "Invited",
+  registered: "Registered",
+  unverified: "Unverified",
+  passwordChange: "Must change password",
+};
+
+/** The default tone of each state: green for the normal case, red for switched off,
+ *  amber for something the user still has to do, blue for an open invitation. */
+export const ACCOUNT_STATE_TONES: Readonly<Record<AccountState, ChipTone>> = {
+  active: "success",
+  inactive: "danger",
+  invited: "info",
+  registered: "neutral",
+  unverified: "warning",
+  passwordChange: "warning",
+};
+
+export interface AccountStateChipProps extends AccountChipLook {
+  state: AccountState;
+  /** Over {@link ACCOUNT_STATE_TONES} — Kurvenschmiede draws `inactive` neutral. */
+  tone?: ChipTone;
+  /** Over the label, for an app whose word for the state is its own ("Deactivated"). */
+  children?: ReactNode;
+  /** Prop > `<UiKitProvider labels={{ accountState }}>` > English. */
+  labels?: Partial<AccountStateLabels>;
+}
+
+/**
+ * An account's state as a chip, in the kit's words and tones. Carries `data-state`
+ * with the key.
+ */
+export function AccountStateChip({
+  state,
+  tone,
+  children,
+  labels: labelsProp,
+  size = "sm",
+  variant,
+  shape = "square",
+  caps = true,
+  className,
+  ...rest
+}: AccountStateChipProps) {
+  // An `undefined` in the prop is skipped (the provider's merge does that), so an
+  // optional value cannot blank a default.
+  const labels = useKitLabels("accountState", DEFAULT_ACCOUNT_STATE_LABELS, labelsProp);
+  return (
+    <Chip
+      {...rest}
+      data-state={state}
+      tone={tone ?? ACCOUNT_STATE_TONES[state]}
+      size={size}
+      variant={variant}
+      shape={shape}
+      caps={caps}
+      className={className}
+    >
+      {children ?? labels[state]}
+    </Chip>
+  );
+}
+
+/* ── Date columns ──────────────────────────────────────────────────────────── */
+
+export interface DateMarkProps {
+  value: DateInput;
+  /**
+   * `"date"` (default): the date in `dateStyle` — "Created". `"relative"`: how long
+   * ago — "Last login", where the question is "recently?" — with the full date and
+   * time in a tooltip (keksdose's last-seen column).
+   */
+  display?: "date" | "relative";
+  /** Default `medium`. Under `"relative"`, the style of the tooltip's date (default
+   *  `dateTime`) and of the date `relative.absoluteAfterDays` switches to. */
+  dateStyle?: FormatDateStyle | Intl.DateTimeFormatOptions;
+  /** `formatRelativeTime` options: `numeric`, `style`, `absoluteAfterDays`, `now`. */
+  relative?: Omit<FormatRelativeTimeOptions, "locale" | "empty" | "absoluteStyle">;
+  /** What a missing value reads as. Default "—"; a last-login column passes its
+   *  translated "Never". */
+  empty?: ReactNode;
+  /** Over the provider's locale. */
+  locale?: string;
+  className?: string;
+}
+
+/**
+ * A date in a table cell: a `<time>` with a machine-readable `dateTime`, nowrap and
+ * tabular figures, in the provider's locale — or `empty` when there is none.
+ */
+export function DateMark({
+  value,
+  display = "date",
+  dateStyle,
+  relative,
+  empty = EMPTY_FORMATTED_VALUE,
+  locale: localeProp,
+  className,
+}: DateMarkProps) {
+  const locale = useKitLocale(localeProp);
+  const date = toDate(value);
+  const cls = cn("whitespace-nowrap tabular-nums", className);
+  if (!date) return <span className={cn(cls, "text-[var(--text-muted)]")}>{empty}</span>;
+  if (display === "date") {
+    return (
+      <time dateTime={date.toISOString()} className={cls}>
+        {formatDate(date, dateStyle ?? "medium", { locale })}
+      </time>
+    );
+  }
+  const text = formatRelativeTime(date, { ...relative, locale, absoluteStyle: dateStyle ?? "medium" });
+  return (
+    <Tooltip label={formatDate(date, dateStyle ?? "dateTime", { locale })} lazy>
+      {/* Not a tab stop: a roster of fifty rows would be fifty more of them, and the
+          relative words already answer the column's question; the exact time is extra. */}
+      <time dateTime={date.toISOString()} className={cls}>
+        {text}
+      </time>
+    </Tooltip>
+  );
+}
+
+export interface DateColumnOptions<T> extends Omit<DateMarkProps, "value" | "className"> {
+  key: string;
+  header: ReactNode;
+  /** The value of this row: an ISO string, epoch ms, a Date, or null for none. */
+  value: (row: T) => DateInput;
+  /** Sortable by the instant; rows with no date sort last either way. Default true. */
+  sortable?: boolean;
+  /** Default `desc` — a date column is sorted to find the newest. */
+  firstSort?: "asc" | "desc";
+  /** Add the table's from–to date filter over the column. Default false. */
+  filter?: boolean;
+  /** Further column settings (`mobileHidden`, `headClassName`, …), merged over. */
+  column?: Partial<DataTableColumn<T>>;
+}
+
+/**
+ * A {@link DataTableColumn} for a date: {@link DateMark} cells, sorted by the instant
+ * (newest first on the first click), optionally the date filter. The roster's
+ * "Created" is `dateColumn({ key, header, value })`; its "Last login" adds
+ * `display: "relative", empty: t("never")`.
+ */
+export function dateColumn<T>({
+  key,
+  header,
+  value,
+  sortable = true,
+  firstSort = "desc",
+  filter = false,
+  column,
+  ...mark
+}: DateColumnOptions<T>): DataTableColumn<T> {
+  return {
+    key,
+    header,
+    cell: (row) => <DateMark value={value(row)} {...mark} />,
+    sortBy: sortable ? (row) => toDate(value(row))?.getTime() ?? null : undefined,
+    firstSort: sortable ? firstSort : undefined,
+    filter: filter
+      ? {
+          type: "date",
+          // The filter compares the first ten characters, so hand it an ISO string.
+          getValue: (row) => {
+            const raw = value(row);
+            if (typeof raw === "string") return raw;
+            return toDate(raw)?.toISOString() ?? null;
+          },
+        }
+      : undefined,
+    ...column,
+  };
+}

package/src/components/account-settings-labels.ts

@@ -63,8 +63,16 @@ export interface TwoFactorSettingLabels {
 
 export interface PasskeysSettingLabels {
   title: string;
-  /** The line under the title saying what a passkey is for. */
+  /** The line under the title saying what a passkey is for — `mode="instead"` (the
+   *  default): the passkey stands in for the password. */
   description: string;
+  /**
+   * The same line for `mode="alongside"` (0.18.0): the password keeps working and the
+   * passkey is a second way in. OPTIONAL for the reason `TwoFactorSettingLabels.qrAlt`
+   * is — this interface is annotated at call sites — and filled from the provider's
+   * `accountSettings.passkeys`, then English.
+   */
+  descriptionAlongside?: string;
   empty: string;
   loading: string;
   /** Accessible name of the list. */
@@ -98,8 +106,11 @@ export interface PasskeysSettingLabels {
 export interface AccountSettingsLabels {
   profile: ProfileSettingLabels;
   password: PasswordSettingLabels;
+  // `Required` here, optional on the section interfaces: the namespace is what a full
+  // catalogue (`@eifi1/ui-kit/i18n/<code>`, `missingKitLabels`) is written against, so
+  // it must name the late keys; the section interfaces are annotated at call sites.
   twoFactor: Required<TwoFactorSettingLabels>;
-  passkeys: PasskeysSettingLabels;
+  passkeys: Required<PasskeysSettingLabels>;
 }
 
 export const DEFAULT_ACCOUNT_SETTINGS_LABELS: AccountSettingsLabels = {
@@ -139,6 +150,9 @@ export const DEFAULT_ACCOUNT_SETTINGS_LABELS: AccountSettingsLabels = {
   passkeys: {
     title: "Passkeys",
     description: "Sign in with your fingerprint, face or device PIN instead of a password.",
+    // Kurvenschmiede overrode `description` because "instead of" is false where the
+    // password stays; this is the sentence for those apps, picked by `mode`.
+    descriptionAlongside: "Sign in with your fingerprint, face or device PIN. Your password keeps working too.",
     empty: "No passkeys yet",
     loading: "Loading passkeys…",
     list: "Your passkeys",

package/src/components/chip.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, isValidElement, useId, useRef, useState } from "react";
+import { forwardRef, isValidElement, useCallback, useId, useLayoutEffect, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, KeyboardEvent, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { Check, X } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
@@ -282,6 +282,208 @@ const SIZE: Record<
   },
 };
 
+/* ── Edge snapping (fractional device-pixel ratios) ──────────────────────────
+ *
+ * WHY. At a device-pixel ratio of 1.25 (a 125 % Windows display, or 125 % browser
+ * zoom) Chrome snaps a box to whole CSS pixels and only then scales it, so a 1px
+ * border is 1.25 device pixels wide and starts at a quarter-pixel phase that depends
+ * on where the edge lands. A chip's left edge follows whatever stands before it, its
+ * right edge follows its own text, so the two land on unrelated phases: one rasterises
+ * as a crisp pixel, the other as a two-pixel smear at half strength — and a 60 %-alpha
+ * border (`--danger-border`) makes the smeared side read as a THINNER line (keksdose
+ * dev #576).
+ *
+ * WHAT FIXES IT. The two edges rasterise as mirror images exactly when their device
+ * positions sum to a whole number: `(2·left + width) · dpr` integral, `left` being the
+ * edge's snapped CSS x. Rounding the WIDTH alone to the ratio's grid (4px at 1.25)
+ * makes the phases EQUAL, which is not the same thing: measured with keksdose's
+ * playwright harness across every left phase at 1.25, width-only rounding mirrored the
+ * edges at two of the four phases and left the other two as lopsided as before (mean
+ * peak asymmetry 16.5, worse than the unsnapped 10.9 a random width gets by luck); the
+ * position-aware width below took it to 0 at every phase. Inset rings, whole-pixel
+ * starts, compositing hints and fractional border widths were measured by keksdose
+ * and do not help — Chrome rounds a sub-pixel border back up to 1px.
+ *
+ * So the fix needs the chip's position, which is why it is opt-in (`snapEdges`): it
+ * reads layout. Cheaply — every snapped chip on the page shares one ResizeObserver,
+ * one `resize` listener and one resolution media query, and a pass is batched into a
+ * frame as read-all / write-all, not a forced layout per chip. At an integer ratio,
+ * and at a half one (1.5, 2.5: grid 2 — measured symmetric already, both edges a
+ * pixel and a half on the same pattern), there is nothing to fix and a pass
+ * writes nothing.
+ */
+
+/** The smallest whole CSS-pixel count `n` with `n × dpr` whole — 4 at 1.25, 2 at 1.5,
+ *  1 at an integer ratio. 0 for a ratio no step up to 4px fits (110 % zoom wants 10px;
+ *  a chip growing by up to 9px is a layout change, not a hairline fix). */
+function chipEdgeGrid(dpr: number): number {
+  for (let n = 1; n <= 4; n++) if (Math.abs(n * dpr - Math.round(n * dpr)) < 1e-3) return n;
+  return 0;
+}
+
+/**
+ * The width (whole CSS px, at least `natural`) that mirrors a box's two edges at
+ * `dpr`, for a box whose left edge sits at CSS x `left`. `natural` back when the ratio
+ * needs nothing.
+ */
+function snappedChipEdgeWidth(natural: number, left: number, dpr: number): number {
+  const n = chipEdgeGrid(dpr);
+  if (n <= 2) return natural;
+  const l = Math.round(left);
+  // A hair under a whole pixel is that pixel: 59.999 is a 60px chip, not a 61px one.
+  let w = Math.ceil(natural - 0.01);
+  while ((((2 * l + w) % n) + n) % n !== 0) w++;
+  return w;
+}
+
+const snapped = new Set<HTMLElement>();
+/** The min-width each chip was given by a pass — so a pass only ever clears its own. */
+const written = new WeakMap<HTMLElement, string>();
+let snapFrame = 0;
+let snapObserver: ResizeObserver | null = null;
+let ratioQuery: MediaQueryList | null = null;
+
+function clearOwn(el: HTMLElement) {
+  const own = written.get(el);
+  if (own !== undefined && el.style.minWidth === own) el.style.minWidth = "";
+  written.delete(el);
+}
+
+/**
+ * Re-snap every chip rendered with `snapEdges`, now. The kit already re-snaps when a
+ * chip renders, resizes, or the window or the ratio changes; call this after moving
+ * chips some other way (a side panel sliding in beside a table of status chips),
+ * since a move is not something an observer can see.
+ */
+export function refreshChipEdges(): void {
+  if (snapFrame) {
+    cancelAnimationFrame(snapFrame);
+    snapFrame = 0;
+  }
+  if (typeof window === "undefined" || !snapped.size) return;
+  const dpr = window.devicePixelRatio || 1;
+  const els = [...snapped];
+  // Write: back to the natural width, so what is read below is the chip, not our pin.
+  for (const el of els) clearOwn(el);
+  const n = chipEdgeGrid(dpr);
+  if (n <= 2) return;
+  // A chip whose own end decides where it starts (RTL, `justify-end`) moves when it
+  // grows, so a pass re-reads what it wrote and steps on by a pixel until the edges
+  // agree — `n` steps cover every residue. Each pass is ONE layout for every chip
+  // together. A chip that never agrees (a centred one moves both edges at once) is
+  // given its natural width back rather than kept wider for nothing.
+  let pending = els;
+  for (let pass = 0; pass <= n && pending.length; pass++) {
+    const reads = pending.map((el) => {
+      const r = el.getBoundingClientRect();
+      const label = el.querySelector<HTMLElement>(".truncate");
+      // Not laid out (a hidden ancestor, jsdom), or truncated at its container's edge,
+      // where a wider chip would overflow: leave it alone.
+      if (!r.width || (label && label.scrollWidth > label.clientWidth)) return null;
+      const width = Math.round(r.width * 64) / 64;
+      const target = snappedChipEdgeWidth(width, r.left + window.scrollX, dpr);
+      return target === width ? null : target;
+    });
+    const next: HTMLElement[] = [];
+    pending.forEach((el, i) => {
+      const target = reads[i];
+      if (target == null) return;
+      if (pass === n) {
+        clearOwn(el);
+        return;
+      }
+      const own = written.get(el);
+      const value = `${pass > 0 && own !== undefined ? parseFloat(own) + 1 : target}px`;
+      el.style.minWidth = value;
+      written.set(el, value);
+      next.push(el);
+    });
+    pending = next;
+  }
+}
+
+function scheduleChipEdges() {
+  if (snapFrame || typeof requestAnimationFrame === "undefined") return;
+  snapFrame = requestAnimationFrame(() => {
+    snapFrame = 0;
+    refreshChipEdges();
+  });
+}
+
+/** The resolution query for the CURRENT ratio: it stops matching when the ratio
+ *  changes (a window dragged to another display), which a `resize` need not fire. */
+function watchRatio() {
+  ratioQuery?.removeEventListener("change", onRatioChange);
+  ratioQuery =
+    typeof window.matchMedia === "function"
+      ? window.matchMedia(`(resolution: ${window.devicePixelRatio || 1}dppx)`)
+      : null;
+  ratioQuery?.addEventListener("change", onRatioChange);
+}
+
+function onRatioChange() {
+  watchRatio();
+  scheduleChipEdges();
+}
+
+function registerSnap(el: HTMLElement) {
+  if (snapped.has(el)) return;
+  if (!snapped.size) {
+    if (typeof ResizeObserver !== "undefined") snapObserver = new ResizeObserver(scheduleChipEdges);
+    window.addEventListener("resize", scheduleChipEdges);
+    watchRatio();
+  }
+  snapped.add(el);
+  snapObserver?.observe(el);
+  scheduleChipEdges();
+}
+
+function unregisterSnap(el: HTMLElement) {
+  if (!snapped.delete(el)) return;
+  snapObserver?.unobserve(el);
+  clearOwn(el);
+  if (snapped.size) return;
+  snapObserver?.disconnect();
+  snapObserver = null;
+  window.removeEventListener("resize", scheduleChipEdges);
+  ratioQuery?.removeEventListener("change", onRatioChange);
+  ratioQuery = null;
+}
+
+/** The ref a chip hangs on its visible pill, plus a re-snap after every render (its
+ *  label or its neighbours may have changed). */
+function useSnapEdges(on: boolean) {
+  const node = useRef<HTMLElement | null>(null);
+  const ref = useCallback(
+    (el: HTMLElement | null) => {
+      if (el === node.current) return;
+      const prev = node.current;
+      node.current = el;
+      // React detaches and re-attaches a ref whose callback changed identity (a
+      // consumer's inline ref) — the same element, a moment apart. Unregistering on
+      // the detach would clear the pin and paint one frame unsnapped, so the drop
+      // waits a microtask and is skipped if the element came straight back.
+      if (prev) queueMicrotask(() => node.current !== prev && unregisterSnap(prev));
+      if (el && on) registerSnap(el);
+    },
+    [on],
+  );
+  useLayoutEffect(() => {
+    const el = node.current;
+    if (!el) return;
+    if (on) {
+      registerSnap(el);
+      scheduleChipEdges();
+    } else unregisterSnap(el);
+  });
+  return ref;
+}
+
+function assignRef<T>(target: Ref<T> | undefined, value: T | null) {
+  if (typeof target === "function") target(value);
+  else if (target) (target as { current: T | null }).current = value;
+}
+
 const CHIP_PILL = "inline-flex max-w-full items-center rounded-full border transition-colors";
 // `focus-visible`, not `focus`: a chip commonly receives focus programmatically (the
 // ChipInput moves focus onto one after a removal) and a ring that appears on a
@@ -372,6 +574,23 @@ interface ChipBaseProps {
   id?: string;
   /** A native tooltip. For anything a user must read, prefer the kit's `Tooltip`. */
   title?: string;
+  /**
+   * Even hairlines on fractional-ratio displays (0.18.0). At a device-pixel ratio of
+   * 1.25 — a 125 % Windows display, or 125 % zoom — Chrome draws a chip's two 1px
+   * side borders on different sub-pixel phases, one crisp and one a half-strength
+   * smear that reads as a thinner line (worst on the 60 %-alpha `danger` border).
+   * `snapEdges` widens the chip by under 4px, from where it sits, so the two edges
+   * rasterise as mirror images, and centres its content in the extra.
+   *
+   * Off by default: it reads the chip's position (batched for every snapped chip into
+   * one pass a frame, through one shared observer), and the fix is only as fresh as the
+   * last pass — it re-snaps on render, resize, zoom and ratio change, but not when
+   * something else moves the chip; call {@link refreshChipEdges} then. At an integer
+   * ratio, and at 1.5, it writes nothing. Turn it on for status chips that sit in a
+   * column and are compared side by side; a chip with no visible border (`dot`) has
+   * nothing to snap.
+   */
+  snapEdges?: boolean;
 }
 
 /**
@@ -458,6 +677,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     role,
     onKeyDown,
     onFocus,
+    snapEdges = false,
     ...rest
   },
   ref,
@@ -476,6 +696,17 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     surfaceOf(tone, variant, selected),
     disabled && "cursor-default opacity-50",
   );
+  const snap = snapEdges && !dot;
+  const snapRef = useSnapEdges(snap);
+  // The visible pill carries the snap: the whole chip, or the wrapper of a split one
+  // (whose body gets the forwarded ref instead).
+  const ownRef = useCallback(
+    (el: HTMLElement | null) => {
+      snapRef(el);
+      assignRef(ref, el);
+    },
+    [snapRef, ref],
+  );
   const look = cn(
     CHIP_BASE,
     s.body,
@@ -485,6 +716,8 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     interactive && !disabled && "cursor-pointer hover:brightness-[0.97] dark:hover:brightness-110",
     // An inert dot chip is text in a column: no inset, so it aligns with the header.
     dot && !interactive && "px-0",
+    // The under-4px a snap adds is split between the two sides, not stacked at the end.
+    snap && "justify-center",
     className,
   );
 
@@ -568,7 +801,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
 
   // ── The combined shape: one pill, two interactive siblings inside it.
   const pill = (inner: ReactNode) => (
-    <span className={cn(CHIP_PILL, s.tail, radius, surface, className)}>
+    <span ref={snap ? snapRef : undefined} className={cn(CHIP_PILL, s.tail, radius, surface, snap && "justify-center", className)}>
       {inner}
       {remove}
     </span>
@@ -591,7 +824,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     const onLinkClick = onClick as ChipLinkProps["onClick"];
     const linkProps: ChipLinkProps = {
       ...rest,
-      ref: ref as Ref<HTMLAnchorElement>,
+      ref: (remove ? ref : ownRef) as Ref<HTMLAnchorElement>,
       href,
       onClick: onLinkClick,
       "aria-current": selected ? "true" : undefined,
@@ -605,7 +838,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
       <RenderedLink render={render} {...linkProps} />
     ) : (
       <a
-        ref={ref as React.Ref<HTMLAnchorElement>}
+        ref={(remove ? ref : ownRef) as React.Ref<HTMLAnchorElement>}
         href={href}
         aria-current={selected ? "true" : undefined}
         onClick={onLinkClick}
@@ -624,7 +857,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
     const onButtonClick = onClick as (event: MouseEvent<HTMLButtonElement>) => void;
     const button = (
       <button
-        ref={ref as React.Ref<HTMLButtonElement>}
+        ref={(remove ? ref : ownRef) as React.Ref<HTMLButtonElement>}
         type="button"
         onClick={onButtonClick}
         disabled={disabled}
@@ -650,7 +883,7 @@ export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
        the roving-focus hooks, live only when the container passes `role` and `tabIndex`
        (ChipInput does); the role is a prop, so the rule cannot see it. */
     <span
-      ref={ref as React.Ref<HTMLSpanElement>}
+      ref={ownRef as React.Ref<HTMLSpanElement>}
       className={look}
       tabIndex={tabIndex}
       role={role}