@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/ui/components/Accordion.js

@@ -12,7 +12,7 @@ function toArray(value) {
     return Array.isArray(value) ? value : [value];
 }
 function renderLegacyAccordion({ title, children, open, className = "", titleClassName = "", contentClassName = "", }) {
-    return (_jsxs("details", { open: open, className: `appkit-accordion appkit-accordion--legacy ${className}`, children: [_jsxs("summary", { className: `appkit-accordion__summary ${titleClassName}`, children: [title, _jsx("span", { className: "appkit-accordion__chevron", "aria-hidden": "true", children: "\u25BE" })] }), _jsx("div", { className: `appkit-accordion__content ${contentClassName}`, "data-section": "accordion-div-447", children: children })] }));
+    return (_jsxs("details", { open: open, className: `appkit-accordion ${className}`, children: [_jsxs("summary", { className: `appkit-accordion__summary ${titleClassName}`, children: [title, _jsx("span", { className: "appkit-accordion__chevron", "aria-hidden": "true", children: "\u25BE" })] }), _jsx("div", { className: `appkit-accordion__content ${contentClassName}`, "data-section": "accordion-div-447", children: children })] }));
 }
 export function Accordion({ title, children, open = false, className = "", titleClassName = "", contentClassName = "", type = "single", defaultValue, value, onChange, }) {
     // useMemo/useState must run unconditionally on every render — they were

package/dist/ui/components/Breadcrumb.js

@@ -4,7 +4,7 @@ import { Nav, Ol, Li } from "./Semantic.js";
 import { Span } from "./Typography.js";
 import { TextLink } from "./TextLink.js";
 export function Breadcrumb({ items, className = "", tone = "default" }) {
-    return (_jsx(Nav, { "aria-label": "Breadcrumb", className: `appkit-breadcrumb ${tone === "on-media" ? "appkit-breadcrumb--on-media" : ""} ${className}`, children: _jsx(Ol, { className: "appkit-breadcrumb__list", children: items.map((item, i) => {
+    return (_jsx(Nav, { "aria-label": "Breadcrumb", className: `${tone === "on-media" ? "appkit-breadcrumb--on-media" : ""} ${className}`, children: _jsx(Ol, { className: "appkit-breadcrumb__list", children: items.map((item, i) => {
                 const isLast = i === items.length - 1;
                 return (_jsxs(Li, { className: "appkit-breadcrumb__item", children: [i > 0 && (_jsx(ChevronRight, { className: "appkit-breadcrumb__separator", "aria-hidden": "true" })), isLast || !item.href ? (_jsx(Span, { className: isLast
                                 ? "appkit-breadcrumb__current"

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/DetailPageGallery.js

@@ -24,7 +24,6 @@ export function DetailPageGallery({ images, title, aspect = "square", fallback,
     const [activeIndex, setActiveIndex] = useState(Math.min(Math.max(initialIndex, 0), Math.max(images.length - 1, 0)));
     if (!images.length) {
         return (_jsx(Div, { className: [
-                "appkit-detail-gallery",
                 "w-full overflow-hidden rounded-2xl bg-[var(--appkit-color-surface)]",
                 ASPECT_CLASS[aspect],
                 className,
@@ -34,7 +33,6 @@ export function DetailPageGallery({ images, title, aspect = "square", fallback,
     }
     const active = images[activeIndex] ?? images[0];
     return (_jsxs(Div, { className: [
-            "appkit-detail-gallery",
             "w-full space-y-2",
             className,
         ]

package/dist/ui/components/DetailPageHero.js

@@ -13,7 +13,6 @@ import { Heading, Text } from "./Typography.js";
  */
 export function DetailPageHero({ title, eyebrow, subtitle, metaRow, description, mediaSlot, actionsSlot, belowActions, className, }) {
     return (_jsxs(Row, { gap: "lg", align: "start", className: [
-            "appkit-detail-hero",
             "flex-col md:flex-row",
             className,
         ]

package/dist/ui/components/DetailPageTabs.js

@@ -11,7 +11,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "./Tabs.js";
  * W1-14 — extracted 2026-05-23.
  */
 export function DetailPageTabs({ tabs, activeTab, defaultTab, onTabChange, className, }) {
-    return (_jsxs(Tabs, { value: activeTab, defaultValue: defaultTab ?? tabs[0]?.id ?? "", onChange: onTabChange, className: ["appkit-detail-tabs", "space-y-4", className].filter(Boolean).join(" "), children: [_jsx(TabsList, { children: tabs.map((tab) => {
+    return (_jsxs(Tabs, { value: activeTab, defaultValue: defaultTab ?? tabs[0]?.id ?? "", onChange: onTabChange, className: ["space-y-4", className].filter(Boolean).join(" "), children: [_jsx(TabsList, { children: tabs.map((tab) => {
                     const label = typeof tab.label === "string" ? tab.label : undefined;
                     return (_jsx(TabsTrigger, { value: tab.id, disabled: tab.disabled, badge: tab.count, label: label, children: tab.label }, tab.id));
                 }) }), tabs.map((tab) => (_jsx(TabsContent, { value: tab.id, children: _jsx(Div, { children: tab.content }) }, tab.id)))] }));

package/dist/ui/components/Divider.js

@@ -2,10 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Span } from "./Typography.js";
 export function Divider({ label, orientation = "horizontal", className = "", }) {
     if (orientation === "vertical") {
-        return (_jsx("div", { className: `appkit-divider appkit-divider--vertical ${className}`, role: "separator", "aria-orientation": "vertical" }));
+        return (_jsx("div", { className: `appkit-divider--vertical ${className}`, role: "separator", "aria-orientation": "vertical" }));
     }
     if (label) {
-        return (_jsxs("div", { className: `appkit-divider appkit-divider--labeled ${className}`, role: "separator", "data-section": "divider-div-479", children: [_jsx("div", { className: "appkit-divider__line" }), _jsx(Span, { className: "appkit-divider__label", children: label }), _jsx("div", { className: "appkit-divider__line" })] }));
+        return (_jsxs("div", { className: `appkit-divider--labeled ${className}`, role: "separator", "data-section": "divider-div-479", children: [_jsx("div", { className: "appkit-divider__line" }), _jsx(Span, { className: "appkit-divider__label", children: label }), _jsx("div", { className: "appkit-divider__line" })] }));
     }
-    return (_jsx("div", { className: `appkit-divider appkit-divider--horizontal ${className}`, role: "separator", "aria-orientation": "horizontal" }));
+    return (_jsx("div", { className: `appkit-divider--horizontal ${className}`, role: "separator", "aria-orientation": "horizontal" }));
 }

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/GatedPrice.js

@@ -18,6 +18,10 @@ import { useCanSeePrices } from "../../react/hooks/useCanSeePrices.js";
  * It is rendered in EVERY state — signed in, signed out and resolving — because
  * the markup describes the region, not the refusal.
  */
+// A SELECTOR TARGET, not a style — gatedPriceWebPageJsonLd names it in
+// `hasPart.cssSelector` so a crawler can see the gate is declared. It must
+// stay rule-less: styling it would change what the markup describes.
+// audit-dead-css-ok: selector target for the paywall JSON-LD, never styled
 export const GATED_PRICE_CLASS = "appkit-gated-price";
 const DEFAULT_LABEL = "Sign in to see price";
 /**
@@ -76,5 +80,5 @@ export function GatedPrice({ amount, currency = getDefaultCurrency(), originalAm
     const originalClass = variant === "detail"
         ? "appkit-price-display__original appkit-price-display__original--detail"
         : "appkit-price-display__original appkit-price-display__original--compact";
-    return (_jsxs(Row, { wrap: true, align: "baseline", gap: "xs", className: `appkit-price-display ${rootClass}`, children: [_jsx(Span, { className: priceClass, children: formatCurrency(amount, currency) }), hasDiscount && (_jsxs(_Fragment, { children: [_jsx(Span, { className: originalClass, children: formatCurrency(originalAmount, currency) }), _jsxs(Span, { className: "appkit-price-display__discount", children: ["-", formatPercentage(discountPct, 0)] })] }))] }));
+    return (_jsxs(Row, { wrap: true, align: "baseline", gap: "xs", className: rootClass, children: [_jsx(Span, { className: priceClass, children: formatCurrency(amount, currency) }), hasDiscount && (_jsxs(_Fragment, { children: [_jsx(Span, { className: originalClass, children: formatCurrency(originalAmount, currency) }), _jsxs(Span, { className: "appkit-price-display__discount", children: ["-", formatPercentage(discountPct, 0)] })] }))] }));
 }

package/dist/ui/components/HorizontalScroller.js

@@ -153,7 +153,7 @@ export function HorizontalScroller({ children, className = "", gap = 16, snapToI
     // Grid mode: group items into slides of (rows × colCount) cards.
     Array.from({ length: gridSlideCount }, (_, slideIndex) => {
         const slideItems = normalizedItems.slice(slideIndex * gridCardsPerSlide, (slideIndex + 1) * gridCardsPerSlide);
-        return (_jsx("div", { className: "appkit-hscroller__slide", style: {
+        return (_jsx("div", { style: {
                 display: "grid",
                 gridTemplateColumns: `repeat(${gridCols}, 1fr)`,
                 gap: `${gap}px`,

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 = () => {
@@ -89,10 +95,10 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
                     effectiveIsDashboard
                         ? "appkit-listing-layout__toolbar--dashboard"
                         : "appkit-listing-layout__toolbar--page",
-                ].join(" "), children: [_jsxs(Div, { className: "appkit-listing-layout__toolbar-row appkit-listing-layout__toolbar-row--desktop", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setSidebarOpen((prev) => !prev), "aria-label": sidebarOpen ? l.hideFilters : l.showFilters, "aria-expanded": sidebarOpen, className: [
+                ].join(" "), children: [_jsxs(Div, { className: "appkit-listing-layout__toolbar-row--desktop", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setSidebarOpen((prev) => !prev), "aria-label": sidebarOpen ? l.hideFilters : l.showFilters, "aria-expanded": sidebarOpen, className: [
                                     "appkit-listing-layout__filter-btn",
                                     sidebarOpen ? "appkit-listing-layout__filter-btn--active" : "",
-                                ].join(" "), children: [_jsx(FilterIcon, {}), l.filtersTitle, filterActiveCount > 0 && (_jsx(Span, { className: "appkit-listing-layout__filter-badge", "aria-label": l.filterActiveCount(filterActiveCount), children: filterActiveCount }))] })), searchSlot && (_jsx(Div, { className: "appkit-listing-layout__search", children: searchSlot })), _jsxs(Div, { className: "appkit-listing-layout__toolbar-actions", children: [sortSlot, viewToggleSlot && (_jsx(Div, { className: "appkit-listing-layout__view-toggle-wrap", children: viewToggleSlot })), actionsSlot] }), toolbarPaginationSlot && (_jsx(Div, { className: "appkit-listing-layout__toolbar-pagination", children: toolbarPaginationSlot }))] }), !mobileToolbarCollapsed && (_jsxs(Div, { className: "appkit-listing-layout__toolbar-row appkit-listing-layout__toolbar-row--mobile", children: [_jsxs(Div, { className: "appkit-listing-layout__mobile-row-1", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setMobileFilterOpen(true), "aria-label": l.filtersTitle, className: [
+                                ].join(" "), children: [_jsx(FilterIcon, {}), l.filtersTitle, filterActiveCount > 0 && (_jsx(Span, { className: "appkit-listing-layout__filter-badge", "aria-label": l.filterActiveCount(filterActiveCount), children: filterActiveCount }))] })), searchSlot && (_jsx(Div, { className: "appkit-listing-layout__search", children: searchSlot })), _jsxs(Div, { className: "appkit-listing-layout__toolbar-actions", children: [sortSlot, viewToggleSlot && (_jsx(Div, { className: "appkit-listing-layout__view-toggle-wrap", children: viewToggleSlot })), actionsSlot] }), toolbarPaginationSlot && (_jsx(Div, { className: "appkit-listing-layout__toolbar-pagination", children: toolbarPaginationSlot }))] }), !mobileToolbarCollapsed && (_jsxs(Div, { className: "appkit-listing-layout__toolbar-row--mobile", children: [_jsxs(Div, { className: "appkit-listing-layout__mobile-row-1", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setMobileFilterOpen(true), "aria-label": l.filtersTitle, className: [
                                             "appkit-listing-layout__filter-btn",
                                             filterActiveCount > 0
                                                 ? "appkit-listing-layout__filter-btn--active"
@@ -111,7 +117,7 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
                                 : "appkit-listing-layout__sidebar--collapsed",
                         ].join(" "), children: _jsxs(Div, { className: "appkit-listing-layout__sidebar-panel", children: [_jsxs(Div, { className: "appkit-listing-layout__sidebar-header", children: [_jsx(Text, { weight: "semibold", size: "sm", children: panelTitle }), filterActiveCount > 0 && (_jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: onFilterClear, className: "text-xs text-primary hover:text-primary/80 hover:underline p-0 h-auto leading-none font-medium", children: l.clearAll }))] }), _jsx(Div, { className: "appkit-listing-layout__sidebar-facets", children: filterContent }), _jsx(Div, { className: "appkit-listing-layout__sidebar-footer", children: _jsx(Button, { type: "button", variant: "primary", className: "w-full rounded-xl", size: "sm", onClick: onFilterApply, children: filterPendingCount != null && filterPendingCount > 0
                                             ? `${l.applyFilters} (${filterPendingCount})`
-                                            : l.applyFilters }) })] }) })), _jsxs(Div, { className: "appkit-listing-layout__content", children: [activeFiltersSlot, resultCountSlot && (_jsx(Div, { className: "appkit-listing-layout__result-count", children: resultCountSlot })), errorSlot ? (errorSlot) : (_jsxs(_Fragment, { children: [children, paginationSlot && (_jsx(Div, { className: "appkit-listing-layout__pagination", children: paginationSlot }))] }))] })] }), toolbarPaginationSlot &&
+                                            : l.applyFilters }) })] }) })), _jsxs(Div, { className: "appkit-listing-layout__content", children: [activeFiltersSlot, resultCountSlot && (_jsx(Div, { children: resultCountSlot })), errorSlot ? (errorSlot) : (_jsxs(_Fragment, { children: [children, paginationSlot && (_jsx(Div, { className: "appkit-listing-layout__pagination", children: paginationSlot }))] }))] })] }), toolbarPaginationSlot &&
                 bottomChromeSlot &&
                 createPortal(_jsx(Nav, { "aria-label": "Pagination", className: "appkit-listing-layout__mobile-pagination", children: toolbarPaginationSlot }), bottomChromeSlot), hasFilter && (_jsx(Drawer, { isOpen: mobileFilterOpen, onClose: () => setMobileFilterOpen(false), side: "bottom", title: filterActiveCount > 0
                     ? `${panelTitle} (${filterActiveCount})`

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

@@ -0,0 +1,81 @@
+/*
+ * Media source/segment tab strips — MediaPickerModal and MediaUploadField.
+ *
+ * 🛑 Both strips shipped with NO rules at all. `MediaPickerModal` ("Upload file"
+ * / "Choose existing") and `MediaUploadField` ("Upload" / "YouTube" /
+ * "External URL") each render raw `<button>`s carrying `appkit-media-*` class
+ * names, and no stylesheet ever defined them — so the one control that tells a
+ * seller which media SOURCE they are using rendered as bare browser buttons,
+ * with no indication of which was active. Found 2026-10-19 by
+ * `audit-dead-css-classes` once the blanket `appkit-` exemption came off.
+ *
+ * The two families are kept DISTINCT rather than collapsed into one
+ * `appkit-tab-strip`: renaming would mean editing both components plus any
+ * consumer override keyed on the old names, for no behavioural gain. They
+ * share declarations through the selector lists below instead, so the two
+ * strips cannot drift apart visually.
+ *
+ * Colours come from tokens, never a palette literal — a hardcoded `zinc-100`
+ * fill is the same near-white in every theme (Recurrent Root Cause #79).
+ */
+
+.appkit-media-picker__tabs,
+.appkit-media-upload__source-tabs {
+  display: inline-flex;
+  align-items: stretch;
+  gap: 0;
+  border: 1px solid var(--appkit-color-border);
+  border-radius: var(--appkit-radius-lg);
+  background: var(--appkit-color-surface-input);
+  padding: 2px;
+  overflow: hidden;
+  max-width: 100%;
+}
+
+.appkit-media-picker__tab-btn,
+.appkit-media-upload__source-tab {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  white-space: nowrap;
+  padding: var(--appkit-space-1-5) var(--appkit-space-3);
+  border-radius: var(--appkit-radius-md);
+  font-size: var(--appkit-text-sm);
+  font-weight: 500;
+  line-height: 1.25rem;
+  color: var(--appkit-color-text-muted);
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+
+.appkit-media-picker__tab-btn:hover:not(:disabled),
+.appkit-media-upload__source-tab:hover:not(:disabled) {
+  background: var(--appkit-color-surface-hover);
+  color: var(--appkit-color-text);
+}
+
+.appkit-media-picker__tab-btn:focus-visible,
+.appkit-media-upload__source-tab:focus-visible {
+  outline: 2px solid var(--appkit-color-focus-ring);
+  outline-offset: -2px;
+}
+
+/*
+ * The active tab is the only one that gets a raised surface. `--active` must
+ * win over `:hover` for the selected tab, so it is declared after the hover
+ * rule rather than relying on specificity.
+ */
+.appkit-media-picker__tab-btn--active,
+.appkit-media-upload__source-tab--active,
+.appkit-media-picker__tab-btn--active:hover,
+.appkit-media-upload__source-tab--active:hover {
+  background: var(--appkit-color-surface);
+  color: var(--appkit-color-text);
+  box-shadow: var(--appkit-shadow-sm);
+}
+
+.appkit-media-picker__tab-btn:disabled,
+.appkit-media-upload__source-tab:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}

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;