@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/ui/components/Button.js

@@ -5,7 +5,13 @@ import { createPortal } from "react-dom";
 import { twMerge } from "tailwind-merge";
 import { Loader2 } from "lucide-react";
 import { surfaceError } from "../../client/api/surface-error.js";
-import { useToastSafe } from "./Toast.js";
+/*
+ * From `toast-context`, never from `./Toast`. `Toast` renders a `<Button>` as
+ * its dismiss control, so importing the hook from there is a real value cycle
+ * between two primitives — which makes their module initialisation order a
+ * property of the bundler rather than of the code.
+ */
+import { useToastSafe } from "./toast-context.js";
 import { SHADOW_MAP } from "./surface-tokens.js";
 import { resolveIcon, ICON_SIZE } from "../icons/icon-registry.js";
 function spawnRipple(host, clientX, clientY) {

package/dist/ui/components/FilterChipGroup.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { OverflowRowDotTone } from "./OverflowRow";
 /**
  * FilterChipGroup — labelled wrap-group of pill buttons.
  *
@@ -32,6 +33,16 @@ export interface FilterChipGroupTab {
      * and a failed count can never hide a filter that has rows (Root Cause #59).
      */
     count?: number;
+    /**
+     * Leading status dot. Lets a status chip be found by colour before the label
+     * is read, which is the whole job of a status filter bar.
+     *
+     * 🛑 Colour is NEVER the only signal — the label is always rendered beside
+     * it, so the dot is redundant reinforcement rather than information. A chip
+     * identified only by colour is unusable to a colour-blind or screen-reader
+     * user, and the dot is `aria-hidden` for exactly that reason.
+     */
+    dotTone?: OverflowRowDotTone;
 }
 export interface FilterChipGroupProps {
     /** Section label shown above the chips. */

package/dist/ui/components/FilterChipGroup.js

@@ -56,6 +56,6 @@ export function FilterChipGroup({ label, tabs, value, onChange, allId = "All", m
                     return (_jsxs("button", { type: "button", 
                         // Checkboxes report checked state, not pressed state — a screen
                         // reader announcing "pressed" for a filter that stays on is wrong.
-                        role: multiple ? "checkbox" : undefined, "aria-checked": multiple ? isActive : undefined, "aria-pressed": multiple ? undefined : isActive, onClick: () => handleClick(tab.id), className: `${CHIP_BASE_CLS} ${isActive ? ACTIVE_CLS : INACTIVE_CLS}`, children: [tab.label, typeof tab.count === "number" && (_jsx("span", { className: COUNT_CLS, children: tab.count > 99 ? "99+" : tab.count }))] }, tab.id));
+                        role: multiple ? "checkbox" : undefined, "aria-checked": multiple ? isActive : undefined, "aria-pressed": multiple ? undefined : isActive, onClick: () => handleClick(tab.id), className: `${CHIP_BASE_CLS} ${isActive ? ACTIVE_CLS : INACTIVE_CLS}`, children: [tab.dotTone && (_jsx("span", { className: "appkit-overflow-row__dot mr-1.5 inline-block align-middle", "data-tone": tab.dotTone, "aria-hidden": "true" })), tab.label, typeof tab.count === "number" && (_jsx("span", { className: COUNT_CLS, children: tab.count > 99 ? "99+" : tab.count }))] }, tab.id));
                 }) })] }));
 }

package/dist/ui/components/ImageGallery.js

@@ -4,7 +4,12 @@ import { useState, useRef, useEffect } from "react";
 import { Text } from "./Typography.js";
 import { Button } from "./Button.js";
 import { HorizontalScroller } from "./HorizontalScroller.js";
-import { useSwipe, useGesture } from "../../react/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { useSwipe } from "../../react/hooks/useSwipe.js";
+import { useGesture } from "../../react/hooks/useGesture.js";
 import { MediaImage } from "../../features/media/MediaImage.js";
 import { FLEX_CENTER, THEMED_BG_SECONDARY, THEMED_BG_TERTIARY, THEMED_BORDER, THEMED_TEXT_MUTED, THEMED_TEXT_PRIMARY, THEMED_TEXT_SECONDARY, } from "../../_internal/shared/styles/themed.js";
 const themed = {

package/dist/ui/components/ListingLayout.js

@@ -50,24 +50,30 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
     // Must run before the detail-view short-circuit below — hooks cannot sit
     // after a conditional return.
     const bottomChromeSlot = useBottomChromeSlot();
-    // Detail view short-circuit (folded from ListingViewShell)
-    if (detailView) {
-        return _jsx(_Fragment, { children: detailView });
-    }
-    // Portal-derived isDashboard default (folded from ListingViewShell)
-    const effectiveIsDashboard = isDashboard ?? (portal === "admin" || portal === "seller");
-    const l = { ...DEFAULT_LABELS, ...labels };
     /* The mobile toolbar is two stacked rows — search + Filter, then a scrolling
        sort/view/actions chip row — roughly 100px of chrome above the first card.
        It opens collapsed below `lg` and stays as the user left it thereafter.
        `forceExpanded` on a selection is load-bearing: the bulk-action bar renders
        INSIDE this toolbar, so a collapsed one would leave the user no way to act
-       on rows they had just selected. */
+       on rows they had just selected.
+  
+       🛑 ABOVE the `detailView` short-circuit, with the other hooks. These two
+       sat below it — the THIRD time this component has grown a hook after that
+       return, which is what the two comments above are each a record of. Passing
+       `detailView` skipped them, so the hook ORDER changed between renders and
+       React silently reassigned state between the hooks that did run. */
     const toolbarPathname = usePathname();
     const { collapsed: mobileToolbarCollapsed, toggle: toggleMobileToolbar } = useToolbarCollapse({
         id: `listing-layout${toolbarPathname ? `:${toolbarPathname}` : ""}`,
         forceExpanded: selectedCount > 0,
     });
+    // Detail view short-circuit (folded from ListingViewShell)
+    if (detailView) {
+        return _jsx(_Fragment, { children: detailView });
+    }
+    // Portal-derived isDashboard default (folded from ListingViewShell)
+    const effectiveIsDashboard = isDashboard ?? (portal === "admin" || portal === "seller");
+    const l = { ...DEFAULT_LABELS, ...labels };
     const hasFilter = Boolean(filterContent);
     const panelTitle = filterTitle ?? l.filtersTitle;
     const handleMobileApply = () => {

package/dist/ui/components/OverflowRow.d.ts

@@ -0,0 +1,92 @@
+import React from "react";
+import type { IconKey } from "../icons/icon-registry";
+/** Status tones for a leading dot. Mirrors the status colour pairs in tokens.css. */
+export type OverflowRowDotTone = "default" | "primary" | "success" | "warning" | "error" | "info" | "muted";
+/**
+ * Navigation props forwarded to every `href` item's link.
+ *
+ * Deliberately an explicit list rather than `Record<string, unknown>`: a bag
+ * of unknowns at a component boundary type-checks against anything, so a
+ * misspelled `scrollTo` would compile and silently do nothing — the defect
+ * being passed through here is precisely the kind that has no visible symptom.
+ */
+export interface OverflowRowLinkProps {
+    /**
+     * `false` opts the link out of the global `<ScrollToTop>`, which is keyed on
+     * pathname. A tab bar that swaps a panel must pass this or every click
+     * yanks the page to the top.
+     */
+    scroll?: boolean;
+    prefetch?: boolean;
+    replace?: boolean;
+}
+export interface OverflowRowItem {
+    id: string;
+    /**
+     * Plain text. Required even when a visual is present: it is the search
+     * corpus, the collapsed trigger's text, and the accessible name.
+     */
+    label: string;
+    /** Trailing count. `undefined` means "not counted", NOT zero — it is omitted rather than rendered as 0. */
+    count?: number;
+    /**
+     * Leading visual, in precedence order: `imageUrl` → `iconName` → `emoji` →
+     * `dotTone`. Only one renders. All are optional; an item with none renders
+     * label-only and the row stays aligned because the visual box is not
+     * reserved when NO item in the set has one.
+     */
+    imageUrl?: string;
+    iconName?: IconKey;
+    emoji?: string;
+    dotTone?: OverflowRowDotTone;
+    /** Renders the pill as a link. Mutually exclusive with `onSelect`. */
+    href?: string;
+    onSelect?: () => void;
+    disabled?: boolean;
+}
+export interface OverflowRowProps {
+    items: readonly OverflowRowItem[];
+    /** Accessible name for the row and its collapsed dropdown. Required — an unnamed tablist is unusable. */
+    ariaLabel: string;
+    /** Selected item id. Drives `aria-selected`, the active pill, and the collapsed trigger's label. */
+    activeId?: string;
+    /**
+     * `"tabs"` renders `role="tablist"` / `role="tab"`; `"nav"` renders a plain
+     * list of links. Pick by what the items DO: a tab swaps a panel in place, a
+     * nav item navigates away. The collapsed dropdown is a `listbox` either way,
+     * because a `<select>`-shaped control is what a collapsed row reads as.
+     */
+    variant?: "tabs" | "nav";
+    /** Collapsed trigger text when nothing is selected. */
+    placeholder?: string;
+    searchPlaceholder?: string;
+    noResultsText?: string;
+    /**
+     * Skip measurement and always render collapsed. For sets known to be large
+     * at author time; the measured path is the default and is preferred.
+     */
+    alwaysCollapsed?: boolean;
+    /**
+     * Component used to render `href` items. Defaults to `next/link`.
+     *
+     * 🛑 Not a raw `<a>`, and the default is load-bearing: a plain anchor does a
+     * FULL PAGE LOAD, so a row of category links silently drops client-side
+     * navigation and every click re-downloads the document. Override it only to
+     * supply a locale-aware link (the consumer's `@/i18n/navigation` `Link`),
+     * never to go back to an anchor.
+     */
+    linkAs?: React.ElementType;
+    /**
+     * Extra props spread onto every `href` item's link.
+     *
+     * The case this exists for is `scroll={false}`: a tab bar that swaps a panel
+     * must NOT jump the page to the top on every click, and the app mounts a
+     * global `<ScrollToTop>` keyed on pathname, so opting out per-link is the
+     * documented escape hatch. Also carries `prefetch`.
+     */
+    linkProps?: OverflowRowLinkProps;
+    /** Applied to the outer shell. */
+    className?: string;
+}
+export declare function OverflowRow({ items, ariaLabel, activeId, variant, placeholder, searchPlaceholder, noResultsText, alwaysCollapsed, linkAs: Link, linkProps, className, }: OverflowRowProps): React.JSX.Element;
+export default OverflowRow;

package/dist/ui/components/OverflowRow.js

@@ -0,0 +1,203 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * WHY: A pill/tab row that is wider than its container has, until now, been
+ *      solved three different ways in this codebase and badly in all of them:
+ *      seven rows were a bare `overflow-x-auto` with NO affordance (the
+ *      Subcategories row shipped 12 pills on a 1440px viewport with the last
+ *      four simply unreachable), six went through `TabBarShell`'s scroll
+ *      arrows, and `Tabs` collapsed to a native `<select>` on a hard-coded
+ *      count of 5 — a threshold that is wrong in both directions, since four
+ *      long labels overflow a phone and eight short ones fit a desktop.
+ *
+ *      Width is the only honest input. This measures it.
+ *
+ * WHAT: A row of items that renders as pills while they fit and becomes a
+ *       single searchable, keyboard-navigable dropdown when they do not.
+ *       Every item may carry a leading visual (cover image, lucide glyph,
+ *       status dot) which is shown in BOTH states.
+ *
+ * EXPORTS: OverflowRow, OverflowRowProps, OverflowRowItem
+ *
+ * @tag domain:ui
+ * @tag layer:ui
+ * @tag pattern:none
+ * @tag access:client
+ * @tag sideEffects:dom-measurement
+ */
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import NextLink from "next/link.js";
+import { Check, ChevronDown, Search } from "lucide-react";
+import { Avatar } from "./Avatar.js";
+import { Icon } from "./Icon.js";
+import { Input } from "./Input.js";
+import { useRowCollapse } from "./row-collapse.js";
+const UI_OVERFLOW_ROW = {
+    shell: "appkit-overflow-row",
+    row: "appkit-overflow-row__row",
+    pill: "appkit-overflow-row__pill",
+    pillActive: "appkit-overflow-row__pill--active",
+    count: "appkit-overflow-row__count",
+    visual: "appkit-overflow-row__visual",
+    dot: "appkit-overflow-row__dot",
+    emoji: "appkit-overflow-row__emoji",
+    trigger: "appkit-overflow-row__trigger",
+    triggerLabel: "appkit-overflow-row__trigger-label",
+    popover: "appkit-overflow-row__popover",
+    search: "appkit-overflow-row__search",
+    list: "appkit-overflow-row__list",
+    option: "appkit-overflow-row__option",
+    optionActive: "appkit-overflow-row__option--active",
+    optionSelected: "appkit-overflow-row__option--selected",
+    optionLabel: "appkit-overflow-row__option-label",
+    optionCount: "appkit-overflow-row__option-count",
+    empty: "appkit-overflow-row__empty",
+    check: "appkit-overflow-row__check",
+};
+function visualOf(item, size) {
+    if (item.imageUrl) {
+        return (_jsx(Avatar, { src: item.imageUrl, name: item.label, size: "xs", className: UI_OVERFLOW_ROW.visual }));
+    }
+    if (item.iconName) {
+        return _jsx(Icon, { name: item.iconName, size: size === "pill" ? "sm" : "md", tone: "current" });
+    }
+    if (item.emoji) {
+        return (_jsx("span", { className: UI_OVERFLOW_ROW.emoji, "aria-hidden": "true", children: item.emoji }));
+    }
+    if (item.dotTone) {
+        return _jsx("span", { className: UI_OVERFLOW_ROW.dot, "data-tone": item.dotTone, "aria-hidden": "true" });
+    }
+    return null;
+}
+/** Stable signature of the item set — invalidates the cached natural width when the set changes. */
+function signatureOf(items) {
+    return items.map((i) => `${i.id}:${i.label}:${i.count ?? ""}`).join("|");
+}
+export function OverflowRow({ items, ariaLabel, activeId, variant = "tabs", placeholder, searchPlaceholder = "Search…", noResultsText = "No matches", alwaysCollapsed = false, linkAs: Link = NextLink, linkProps, className = "", }) {
+    const shellRef = useRef(null);
+    const rowRef = useRef(null);
+    const triggerRef = useRef(null);
+    const searchRef = useRef(null);
+    const listboxId = useId();
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    const [activeIndex, setActiveIndex] = useState(0);
+    const signature = useMemo(() => signatureOf(items), [items]);
+    const collapsed = useRowCollapse(shellRef, rowRef, signature, {
+        disabled: alwaysCollapsed,
+        initial: alwaysCollapsed,
+    });
+    // Close on outside click.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onDown = (event) => {
+            if (!shellRef.current?.contains(event.target))
+                setOpen(false);
+        };
+        document.addEventListener("mousedown", onDown);
+        return () => document.removeEventListener("mousedown", onDown);
+    }, [open]);
+    // Focus the search field on open — the whole point of collapsing is that the
+    // set is too big to scan, so typing must work without a second click.
+    useEffect(() => {
+        if (open)
+            searchRef.current?.focus();
+        else {
+            setQuery("");
+            setActiveIndex(0);
+        }
+    }, [open]);
+    const filtered = useMemo(() => {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return items;
+        return items.filter((item) => item.label.toLowerCase().includes(q));
+    }, [items, query]);
+    const activeItem = items.find((item) => item.id === activeId);
+    const commit = useCallback((item) => {
+        if (item.disabled)
+            return;
+        item.onSelect?.();
+        setOpen(false);
+    }, []);
+    const onSearchKeyDown = (event) => {
+        const count = filtered.length;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            setOpen(false);
+            triggerRef.current?.focus();
+            return;
+        }
+        if (!count)
+            return;
+        if (event.key === "ArrowDown") {
+            event.preventDefault();
+            setActiveIndex((prev) => (prev + 1) % count);
+            return;
+        }
+        if (event.key === "ArrowUp") {
+            event.preventDefault();
+            setActiveIndex((prev) => (prev - 1 + count) % count);
+            return;
+        }
+        if (event.key === "Home") {
+            event.preventDefault();
+            setActiveIndex(0);
+            return;
+        }
+        if (event.key === "End") {
+            event.preventDefault();
+            setActiveIndex(count - 1);
+            return;
+        }
+        if (event.key === "Enter") {
+            event.preventDefault();
+            const item = filtered[Math.min(activeIndex, count - 1)];
+            if (!item)
+                return;
+            if (item.href) {
+                window.location.assign(item.href);
+                return;
+            }
+            commit(item);
+        }
+    };
+    const hasAnyVisual = items.some((item) => item.imageUrl || item.iconName || item.emoji || item.dotTone);
+    // ── Collapsed: one searchable dropdown ──────────────────────────────────
+    if (collapsed) {
+        return (_jsxs("div", { ref: shellRef, className: [UI_OVERFLOW_ROW.shell, className].filter(Boolean).join(" "), "data-collapsed": "true", children: [_jsxs("button", { ref: triggerRef, type: "button", className: UI_OVERFLOW_ROW.trigger, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listboxId : undefined, "aria-label": ariaLabel, onClick: () => setOpen((prev) => !prev), onKeyDown: (event) => {
+                        if (!open && (event.key === "ArrowDown" || event.key === "Enter")) {
+                            event.preventDefault();
+                            setOpen(true);
+                        }
+                    }, children: [activeItem ? visualOf(activeItem, "pill") : null, _jsx("span", { className: UI_OVERFLOW_ROW.triggerLabel, children: activeItem?.label ?? placeholder ?? ariaLabel }), items.length > 0 && (_jsx("span", { className: UI_OVERFLOW_ROW.count, children: items.length })), _jsx(ChevronDown, { className: "w-4 h-4", "aria-hidden": "true" })] }), open && (_jsxs("div", { className: UI_OVERFLOW_ROW.popover, children: [_jsx("div", { className: UI_OVERFLOW_ROW.search, children: _jsx(Input, { ref: searchRef, type: "search", value: query, placeholder: searchPlaceholder, "aria-label": searchPlaceholder, "aria-controls": listboxId, "aria-activedescendant": filtered[activeIndex] ? `${listboxId}-${filtered[activeIndex].id}` : undefined, icon: _jsx(Search, { className: "w-4 h-4", "aria-hidden": "true" }), onChange: (event) => {
+                                    setQuery(event.target.value);
+                                    setActiveIndex(0);
+                                }, onKeyDown: onSearchKeyDown }) }), _jsxs("div", { id: listboxId, role: "listbox", "aria-label": ariaLabel, className: UI_OVERFLOW_ROW.list, children: [filtered.length === 0 && (_jsx("div", { className: UI_OVERFLOW_ROW.empty, children: noResultsText })), filtered.map((item, index) => {
+                                    const isSelected = item.id === activeId;
+                                    const classes = [
+                                        UI_OVERFLOW_ROW.option,
+                                        index === activeIndex ? UI_OVERFLOW_ROW.optionActive : "",
+                                        isSelected ? UI_OVERFLOW_ROW.optionSelected : "",
+                                    ]
+                                        .filter(Boolean)
+                                        .join(" ");
+                                    const body = (_jsxs(_Fragment, { children: [hasAnyVisual ? visualOf(item, "option") : null, _jsx("span", { className: UI_OVERFLOW_ROW.optionLabel, children: item.label }), typeof item.count === "number" && (_jsx("span", { className: UI_OVERFLOW_ROW.optionCount, children: item.count > 99 ? "99+" : item.count })), isSelected && (_jsx(Check, { className: `w-4 h-4 ${UI_OVERFLOW_ROW.check}`, "aria-hidden": "true" }))] }));
+                                    return item.href ? (_jsx(Link, { ...linkProps, id: `${listboxId}-${item.id}`, role: "option", "aria-selected": isSelected, href: item.href, className: classes, onMouseEnter: () => setActiveIndex(index), children: body }, item.id)) : (_jsx("button", { id: `${listboxId}-${item.id}`, role: "option", type: "button", "aria-selected": isSelected, disabled: item.disabled, className: classes, onClick: () => commit(item), onMouseEnter: () => setActiveIndex(index), children: body }, item.id));
+                                })] })] }))] }));
+    }
+    // ── Expanded: the pill row ──────────────────────────────────────────────
+    return (_jsx("div", { ref: shellRef, className: [UI_OVERFLOW_ROW.shell, className].filter(Boolean).join(" "), "data-collapsed": "false", children: _jsx("div", { ref: rowRef, className: UI_OVERFLOW_ROW.row, role: variant === "tabs" ? "tablist" : undefined, "aria-label": ariaLabel, children: items.map((item) => {
+                const isActive = item.id === activeId;
+                const classes = [
+                    UI_OVERFLOW_ROW.pill,
+                    isActive ? UI_OVERFLOW_ROW.pillActive : "",
+                ]
+                    .filter(Boolean)
+                    .join(" ");
+                const body = (_jsxs(_Fragment, { children: [visualOf(item, "pill"), item.label, typeof item.count === "number" && (_jsx("span", { className: UI_OVERFLOW_ROW.count, children: item.count > 99 ? "99+" : item.count }))] }));
+                return item.href ? (_jsx(Link, { ...linkProps, href: item.href, className: classes, role: variant === "tabs" ? "tab" : undefined, "aria-selected": variant === "tabs" ? isActive : undefined, "aria-current": variant === "nav" && isActive ? "page" : undefined, children: body }, item.id)) : (_jsx("button", { type: "button", className: classes, role: variant === "tabs" ? "tab" : undefined, "aria-selected": variant === "tabs" ? isActive : undefined, disabled: item.disabled, onClick: () => commit(item), children: body }, item.id));
+            }) }) }));
+}
+export default OverflowRow;

package/dist/ui/components/OverflowRow.style.css

@@ -0,0 +1,235 @@
+/*
+ * OverflowRow — pill row that becomes a searchable dropdown when it overflows.
+ *
+ * All tokens live here rather than on the call site's className. The expanded
+ * and collapsed states are selected by `[data-collapsed]` written from JS, NOT
+ * by a media query: the decision is a width MEASUREMENT against the row's own
+ * content, which no breakpoint can express (four long labels overflow a phone;
+ * eight short ones fit a desktop).
+ *
+ * 🛑 Do not express the two states as Tailwind `md:`/`lg:` overrides. appkit's
+ * Tailwind build emits NO variant-prefixed utility (see the measured note in
+ * src/tailwind-input.css), so such a rule compiles to nothing and the element
+ * silently keeps its base style.
+ */
+
+.appkit-overflow-row {
+  position: relative;
+  width: 100%;
+  min-width: 0;
+}
+
+/* ── Expanded ─────────────────────────────────────────────────────────── */
+
+.appkit-overflow-row__row {
+  display: flex;
+  align-items: center;
+  gap: var(--appkit-space-2);
+  min-width: 0;
+  /*
+   * No `overflow-x: auto`. A scrollbar here would let the row satisfy its
+   * container at any width, so `scrollWidth` would still exceed `clientWidth`
+   * but nothing would ever look broken enough to collapse — the measurement
+   * and the visible truth must agree.
+   */
+}
+
+.appkit-overflow-row__pill {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  gap: var(--appkit-space-1-5);
+  padding: var(--appkit-space-1-5) var(--appkit-space-4);
+  border: 1px solid var(--appkit-color-border);
+  border-radius: var(--appkit-radius-full);
+  background: var(--appkit-color-surface-elevated);
+  color: var(--appkit-color-text-muted);
+  font-size: var(--appkit-text-sm);
+  font-weight: 500;
+  line-height: 1.25;
+  white-space: nowrap;
+  text-decoration: none;
+  transition: color var(--appkit-duration-fast) var(--appkit-ease-out),
+    border-color var(--appkit-duration-fast) var(--appkit-ease-out),
+    background-color var(--appkit-duration-fast) var(--appkit-ease-out);
+}
+
+.appkit-overflow-row__pill:hover {
+  border-color: var(--appkit-color-primary);
+  color: var(--appkit-color-primary);
+}
+
+.appkit-overflow-row__pill:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.appkit-overflow-row__pill--active {
+  border-color: var(--appkit-color-primary);
+  background: var(--appkit-color-primary-surface);
+  color: var(--appkit-color-primary);
+}
+
+/* ── Leading visuals ──────────────────────────────────────────────────── */
+
+/*
+ * Sized here rather than by Avatar's own `--xs`, which is a face-sized box.
+ * A pill's visual is an identifying mark at text scale: it must not grow the
+ * pill's line-box, or every row in the app gets taller.
+ */
+.appkit-overflow-row__visual {
+  width: 1.125rem;
+  height: 1.125rem;
+  flex-shrink: 0;
+  font-size: var(--appkit-text-2xs);
+}
+
+.appkit-overflow-row__emoji {
+  line-height: 1;
+  flex-shrink: 0;
+}
+
+.appkit-overflow-row__dot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: var(--appkit-radius-full);
+  flex-shrink: 0;
+  background: var(--appkit-color-text-faint);
+}
+
+.appkit-overflow-row__dot[data-tone="primary"] { background: var(--appkit-color-primary); }
+.appkit-overflow-row__dot[data-tone="success"] { background: var(--appkit-color-success); }
+.appkit-overflow-row__dot[data-tone="warning"] { background: var(--appkit-color-warning); }
+.appkit-overflow-row__dot[data-tone="error"]   { background: var(--appkit-color-error); }
+.appkit-overflow-row__dot[data-tone="info"]    { background: var(--appkit-color-info); }
+.appkit-overflow-row__dot[data-tone="muted"]   { background: var(--appkit-color-text-faint); }
+
+/*
+ * `opacity` rather than a literal colour so the count stays legible on both
+ * the inactive (surface) and active (primary tint) pill — a fixed colour is
+ * invisible against one of them in some theme (Root Cause #67).
+ */
+.appkit-overflow-row__count {
+  font-size: var(--appkit-text-xs);
+  font-variant-numeric: tabular-nums;
+  opacity: 0.7;
+}
+
+/* ── Collapsed trigger ────────────────────────────────────────────────── */
+
+.appkit-overflow-row__trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--appkit-space-2);
+  max-width: 100%;
+  padding: var(--appkit-space-2) var(--appkit-space-3);
+  border: 1px solid var(--appkit-color-border);
+  border-radius: var(--appkit-radius-lg);
+  background: var(--appkit-color-surface-elevated);
+  color: var(--appkit-color-text);
+  font-size: var(--appkit-text-sm);
+  font-weight: 500;
+  line-height: 1.25;
+  cursor: pointer;
+}
+
+.appkit-overflow-row__trigger:hover {
+  border-color: var(--appkit-color-primary);
+}
+
+.appkit-overflow-row__trigger-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+/* ── Popover ──────────────────────────────────────────────────────────── */
+
+.appkit-overflow-row__popover {
+  position: absolute;
+  z-index: var(--appkit-z-dropdown);
+  top: calc(100% + var(--appkit-space-1));
+  left: 0;
+  width: min(22rem, 100%);
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--appkit-color-border);
+  border-radius: var(--appkit-radius-lg);
+  background: var(--appkit-color-surface-elevated);
+  box-shadow: var(--appkit-shadow-lg);
+  overflow: hidden;
+}
+
+.appkit-overflow-row__search {
+  padding: var(--appkit-space-2);
+  border-bottom: 1px solid var(--appkit-color-border-subtle);
+}
+
+.appkit-overflow-row__list {
+  max-height: 18rem;
+  overflow-y: auto;
+  padding: var(--appkit-space-1);
+}
+
+.appkit-overflow-row__option {
+  display: flex;
+  align-items: center;
+  gap: var(--appkit-space-2);
+  width: 100%;
+  padding: var(--appkit-space-2) var(--appkit-space-2-5);
+  border: 0;
+  border-radius: var(--appkit-radius-md);
+  background: transparent;
+  color: var(--appkit-color-text);
+  font-size: var(--appkit-text-sm);
+  text-align: left;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.appkit-overflow-row__option:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/*
+ * Hover and keyboard focus resolve to the SAME class, set from `activeIndex`
+ * on both `onMouseEnter` and the arrow keys — two different highlights in one
+ * list is what makes a combobox feel like it has two cursors.
+ */
+.appkit-overflow-row__option--active {
+  background: var(--appkit-color-surface-hover);
+}
+
+.appkit-overflow-row__option--selected {
+  color: var(--appkit-color-primary);
+  font-weight: 600;
+}
+
+.appkit-overflow-row__option-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.appkit-overflow-row__option-count {
+  font-size: var(--appkit-text-xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--appkit-color-text-muted);
+  flex-shrink: 0;
+}
+
+.appkit-overflow-row__check {
+  flex-shrink: 0;
+  color: var(--appkit-color-primary);
+}
+
+.appkit-overflow-row__empty {
+  padding: var(--appkit-space-4);
+  text-align: center;
+  font-size: var(--appkit-text-sm);
+  color: var(--appkit-color-text-muted);
+}

package/dist/ui/components/RecordDetailModal.js

@@ -1,6 +1,19 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ActionRow, Anchor, Badge, Code, Div, Modal, Row, Stack, Text } from "../index.js";
+/*
+ * 🛑 This was `from "../index"` — the component importing its own barrel,
+ * while also importing `features/media/MediaImage`. That made `ui/index.ts`
+ * depend on a module that depends on it, the last two-module knot in
+ * `audit-import-cycles`. Every symbol is one directory away.
+ */
+import { ActionRow } from "./ActionRow.js";
+import { Anchor } from "./Anchor.js";
+import { Badge } from "./Badge.js";
+import { Code } from "./Semantic.js";
+import { Div } from "./Div.js";
+import { Modal } from "./Modal.js";
+import { Row, Stack } from "./Layout.js";
+import { Text } from "./Typography.js";
 import { MediaImage } from "../../features/media/MediaImage.js";
 export function RecordDetailModal({ isOpen, onClose, title, badges, description, fields, items, extra, metadata, footer, }) {
     const hasMetadata = Boolean(metadata && Object.keys(metadata).length > 0);

package/dist/ui/components/RowActionMenu.js

@@ -5,7 +5,11 @@ import { createPortal } from "react-dom";
 import { MoreHorizontal } from "lucide-react";
 import { Button } from "./Button.js";
 import { Span } from "./Typography.js";
-import { useKeyPress } from "../../react/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { useKeyPress } from "../../react/hooks/useKeyPress.js";
 export function RowActionMenu({ actions, align = "right", }) {
     const [open, setOpen] = useState(false);
     const [pos, setPos] = useState(null);