@mohasinac/appkit 4.52.5 → 4.53.1

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

@@ -25,6 +25,17 @@ export interface TabBarShellProps {
      * and the arrows work regardless.
      */
     activeKey?: string;
+    /**
+     * Optional external ref onto the `role="tablist"` element itself.
+     *
+     * Exists so a caller can MEASURE the real tab row without wrapping
+     * `{children}` in a box of its own — a wrapper between the tablist and its
+     * tabs breaks the accessibility tree, since a `role="tablist"` may only
+     * contain `role="tab"` elements. `TabsList` uses this to decide whether the
+     * row fits; the shell keeps driving its own scroll arrows from the same
+     * node.
+     */
+    listRef?: React.RefObject<HTMLDivElement | null>;
     children?: React.ReactNode;
 }
 /**
@@ -34,7 +45,7 @@ export interface TabBarShellProps {
  * -tree children stay exactly the `role="tab"` elements — no `aria-owns`, no
  * invalid-child warnings.
  */
-export declare function TabBarShell({ className, ariaLabel, leading, activeKey, children, }: TabBarShellProps): React.JSX.Element;
+export declare function TabBarShell({ className, ariaLabel, leading, activeKey, listRef: externalListRef, children, }: TabBarShellProps): React.JSX.Element;
 export interface TabBarButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "role" | "aria-selected"> {
     selected: boolean;
 }

package/dist/ui/components/TabBarShell.js

@@ -44,8 +44,9 @@ const UI_TAB_BAR = {
  * -tree children stay exactly the `role="tab"` elements — no `aria-owns`, no
  * invalid-child warnings.
  */
-export function TabBarShell({ className = "", ariaLabel = "Tabs", leading, activeKey = "", children, }) {
-    const listRef = useRef(null);
+export function TabBarShell({ className = "", ariaLabel = "Tabs", leading, activeKey = "", listRef: externalListRef, children, }) {
+    const internalListRef = useRef(null);
+    const listRef = externalListRef ?? internalListRef;
     const { hasArrows, atStart, atEnd, scrollByPage } = useTabsOverflow(listRef, activeKey);
     /*
      * The arrows are aria-hidden + tabIndex={-1} deliberately. They duplicate

package/dist/ui/components/Tabs.js

@@ -1,22 +1,14 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { createContext, useContext, useMemo, useState } from "react";
-import { TabBarShell, TabsNavSelect } from "./TabBarShell.js";
+import React, { createContext, useContext, useMemo, useRef, useState } from "react";
+import { TabBarShell } from "./TabBarShell.js";
+import { OverflowRow } from "./OverflowRow.js";
+import { useRowCollapse } from "./row-collapse.js";
 const UI_TABS = {
     trigger: "appkit-tabs-trigger",
     content: "appkit-tabs-content",
     badge: "appkit-tabs-trigger__badge",
 };
-/** Past this many items, TabsList renders a dropdown instead of a horizontal
- * row — a scrollable row of 6+ tabs is unreadable/unreachable on mobile
- * widths.
- *
- * The dropdown is styled as NAVIGATION, not as a form field: see
- * `TabsNavSelect` and the `.appkit-tabs-dropdown` rules in Tabs.style.css. It
- * used to render a raw `<Select bare>`, which carried the full
- * `.appkit-select__trigger` input chrome (bordered, rounded, surface-filled,
- * 40px tall) — which is exactly why a tab bar read as an input. */
-const TABS_DROPDOWN_THRESHOLD = 5;
 const TabsContext = createContext({
     active: "",
     setActive: () => { },
@@ -37,20 +29,40 @@ export function Tabs({ defaultValue = "", value, onChange, className = "", child
 }
 export function TabsList({ className = "", children }) {
     const { active, setActive } = useContext(TabsContext);
+    const shellRef = useRef(null);
+    const rowRef = useRef(null);
     const items = React.Children.toArray(children).filter((child) => React.isValidElement(child));
-    if (items.length > TABS_DROPDOWN_THRESHOLD) {
-        const options = items.map((item) => {
-            const baseLabel = item.props.label ??
-                (typeof item.props.children === "string" ? item.props.children : item.props.value);
-            return {
-                value: item.props.value,
-                label: item.props.badge ? `${baseLabel} (${item.props.badge})` : baseLabel,
-                disabled: item.props.disabled,
-            };
-        });
-        return (_jsx(TabsNavSelect, { ariaLabel: "Tabs", role: "tablist", options: options, value: active, onValueChange: setActive, className: className }));
+    /*
+     * The collapsed label must be PLAIN TEXT: `children` may render a badge
+     * pill, and a ReactNode cannot be searched, measured as a signature, or put
+     * in an option's accessible name. `label` is the explicit escape hatch for
+     * that case; `value` is the last resort.
+     */
+    const overflowItems = items.map((item) => ({
+        id: item.props.value,
+        label: item.props.label ??
+            (typeof item.props.children === "string" ? item.props.children : item.props.value),
+        count: item.props.badge,
+        disabled: item.props.disabled,
+        onSelect: () => setActive(item.props.value),
+    }));
+    const signature = overflowItems.map((i) => `${i.id}:${i.label}:${i.count ?? ""}`).join("|");
+    const collapsed = useRowCollapse(shellRef, rowRef, signature);
+    /*
+     * Collapsed renders `OverflowRow` in its already-collapsed state rather than
+     * the old `TabsNavSelect`, which was a native `<select>` — so the collapsed
+     * tab bar is now SEARCHABLE and keyboard-navigable. That matters most
+     * exactly where it collapses: a 30-tab bar on a phone was a 30-row native
+     * picker with no way to type at it.
+     *
+     * The EXPANDED state deliberately stays `TabBarShell`, so the underline rail
+     * every tab surface in the app shares is untouched. Only the overflow
+     * behaviour changed, never the resting appearance.
+     */
+    if (collapsed) {
+        return (_jsx("div", { ref: shellRef, className: className, children: _jsx(OverflowRow, { items: overflowItems, ariaLabel: "Tabs", activeId: active, alwaysCollapsed: true, searchPlaceholder: "Search tabs\u2026" }) }));
     }
-    return (_jsx(TabBarShell, { className: className, ariaLabel: "Tabs", activeKey: active, children: children }));
+    return (_jsx("div", { ref: shellRef, children: _jsx(TabBarShell, { className: className, ariaLabel: "Tabs", activeKey: active, listRef: rowRef, children: children }) }));
 }
 export function TabsTrigger({ value, disabled, className = "", children, badge, }) {
     const { active, setActive } = useContext(TabsContext);

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

@@ -1,30 +1,9 @@
 import React from "react";
-export type ToastVariant = "success" | "error" | "warning" | "info" | "loading";
-export type ToastPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
-interface ToastContextValue {
-    /**
-     * Show a toast. Returns the `dismissId` so long-running ops can later finalize
-     * via `updateToast(id, "success" | "error", finalMessage)`. For the "loading"
-     * variant pass `duration: 0` to keep it pinned until finalized.
-     */
-    showToast: (message: string, variant?: ToastVariant, duration?: number, action?: {
-        label: string;
-        onClick: () => void;
-    }) => string;
-    hideToast: (id: string) => void;
-    /** Replace an existing toast's variant + message (used to finalize loading toasts). */
-    updateToast: (id: string, variant: ToastVariant, message?: string, duration?: number) => void;
-}
-export declare function useToast(): ToastContextValue;
-/**
- * Like `useToast` but returns `undefined` when no `ToastProvider` is mounted
- * instead of throwing. Use in primitives (e.g. `Button`) that must be safe to
- * render outside a toast context.
- */
-export declare function useToastSafe(): ToastContextValue | undefined;
+import { type ToastPosition } from "./toast-context";
+export type { ToastVariant, ToastPosition, ToastItem, ToastContextValue, } from "./toast-context";
+export { useToast, useToastSafe } from "./toast-context";
 export interface ToastProviderProps {
     children: React.ReactNode;
     position?: ToastPosition;
 }
 export declare function ToastProvider({ children, position, }: ToastProviderProps): React.JSX.Element;
-export {};

package/dist/ui/components/Toast.js

@@ -4,26 +4,9 @@ import React from "react";
 import { motion, AnimatePresence, useReducedMotion } from "motion/react";
 import { Button } from "./Button.js";
 import { Text } from "./Typography.js";
+import { ToastContext, buildToastId, } from "./toast-context.js";
 import { SPRING_SNAPPY } from "../../tokens/motion.js";
-const ToastContext = React.createContext(undefined);
-function buildToastId() {
-    return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-}
-export function useToast() {
-    const context = React.useContext(ToastContext);
-    if (!context) {
-        throw new Error("useToast must be used within ToastProvider");
-    }
-    return context;
-}
-/**
- * Like `useToast` but returns `undefined` when no `ToastProvider` is mounted
- * instead of throwing. Use in primitives (e.g. `Button`) that must be safe to
- * render outside a toast context.
- */
-export function useToastSafe() {
-    return React.useContext(ToastContext);
-}
+export { useToast, useToastSafe } from "./toast-context.js";
 const UI_TOAST = {
     container: "appkit-toast-container",
     positions: {

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

@@ -0,0 +1,15 @@
+import React from "react";
+export interface TopBannerPortalProps {
+    children: React.ReactNode;
+}
+/**
+ * Renders `children` into the layout's top-banner slot — the band above the
+ * sticky header. See `top-banner-slot.ts` for why that slot exists and why it
+ * sits outside the measured header wrapper.
+ *
+ * Renders nothing until the slot resolves after mount. That is not a loading
+ * state to paper over: the banner is dismissible and server-rendering it into
+ * a layout that may already have a dismissal recorded would flash it at someone
+ * who closed it last week.
+ */
+export declare function TopBannerPortal({ children }: TopBannerPortalProps): React.ReactPortal | null;

package/dist/ui/components/TopBannerPortal.js

@@ -0,0 +1,19 @@
+"use client";
+import { createPortal } from "react-dom";
+import { useTopBannerSlot } from "./top-banner-slot.js";
+/**
+ * Renders `children` into the layout's top-banner slot — the band above the
+ * sticky header. See `top-banner-slot.ts` for why that slot exists and why it
+ * sits outside the measured header wrapper.
+ *
+ * Renders nothing until the slot resolves after mount. That is not a loading
+ * state to paper over: the banner is dismissible and server-rendering it into
+ * a layout that may already have a dismissal recorded would flash it at someone
+ * who closed it last week.
+ */
+export function TopBannerPortal({ children }) {
+    const slot = useTopBannerSlot();
+    if (!slot)
+        return null;
+    return createPortal(children, slot);
+}

package/dist/ui/components/UnsavedChangesModal.js

@@ -2,7 +2,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { eventBus } from "../../core/EventBus.js";
-import { UNSAVED_CHANGES_EVENT } 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 { UNSAVED_CHANGES_EVENT } from "../../react/hooks/useUnsavedChanges.js";
 import { Button } from "./Button.js";
 import { Card } from "./Card.js";
 import { Heading, Text } from "./Typography.js";

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

@@ -74,6 +74,8 @@
 @import "./RowActionMenu.style.css";
 @import "./Div.style.css";
 @import "./Menu.style.css";
+@import "./OverflowRow.style.css";
+@import "./MediaTabs.style.css";
 @import "./Semantic.style.css";
 @import "./UnsavedChangesModal.style.css";
 @import "../DataTable.style.css";

package/dist/ui/components/row-collapse.d.ts

@@ -0,0 +1,15 @@
+export interface UseRowCollapseOptions {
+    /** Skip measurement entirely and pin the result. */
+    disabled?: boolean;
+    /** Start collapsed. The server never measures, so this must match the SSR markup. */
+    initial?: boolean;
+}
+/**
+ * True when `rowRef`'s content is wider than `shellRef`'s box.
+ *
+ * `signature` must change whenever the row's content changes (item ids,
+ * labels, counts). A new item set has a different natural width, so the
+ * cached one becomes a lie and has to be discarded — without this a row that
+ * grew from 3 items to 30 would stay expanded against a stale measurement.
+ */
+export declare function useRowCollapse(shellRef: React.RefObject<HTMLElement | null>, rowRef: React.RefObject<HTMLElement | null>, signature: string, { disabled, initial }?: UseRowCollapseOptions): boolean;

package/dist/ui/components/row-collapse.js

@@ -0,0 +1,127 @@
+"use client";
+/*
+ * WHY: Deciding "does this row fit" by COUNTING items is wrong in both
+ *      directions, and this codebase shipped that mistake for a long time:
+ *      `TabsList` collapsed past five tabs, so four long labels still
+ *      overflowed a phone and eight short ones collapsed a desktop that had
+ *      room to spare. Width is the only input that answers the question.
+ *
+ *      The hard part is that collapsing DESTROYS the evidence. Once the row is
+ *      replaced by a trigger there is no row left to measure, so a naive
+ *      implementation can never expand again on a wider viewport — it is a
+ *      one-way door. This caches the row's natural width while it is still
+ *      rendered, which is what makes the decision reversible.
+ *
+ * WHAT: Measures whether a row's content is wider than its container, and
+ *       stays correct across resizes in BOTH directions. Consumed by
+ *       <OverflowRow> and <TabsList>.
+ *
+ * EXPORTS: useRowCollapse
+ *
+ * @tag domain:ui
+ * @tag layer:ui
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:OverflowRow,TabsList
+ * @tag sideEffects:dom-measurement
+ */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+/** Sub-pixel tolerance — scrollWidth/clientWidth differ by <1px at some zoom levels. */
+const EPSILON = 1;
+/**
+ * Extra room required to EXPAND again, in px.
+ *
+ * 🛑 Deliberately not symmetric with the collapse threshold, and must not be
+ * made so. Collapsing removes the row, so the only width left to compare
+ * against is the cached natural width — which makes the two states adjacent:
+ * at exactly the boundary the row collapses, the shell reflows a few px wider
+ * without the row's own padding, the cached width now "fits", it expands, the
+ * padding returns, it overflows, it collapses… forever.
+ *
+ * Requiring a clear margin to come back makes the rule provably stable. This
+ * is the same hysteresis `tabs-overflow.ts` needs for its in-flow arrows, for
+ * the same underlying reason.
+ */
+const EXPAND_SLACK_PX = 48;
+/**
+ * True when `rowRef`'s content is wider than `shellRef`'s box.
+ *
+ * `signature` must change whenever the row's content changes (item ids,
+ * labels, counts). A new item set has a different natural width, so the
+ * cached one becomes a lie and has to be discarded — without this a row that
+ * grew from 3 items to 30 would stay expanded against a stale measurement.
+ */
+export function useRowCollapse(shellRef, rowRef, signature, { disabled = false, initial = false } = {}) {
+    // Starts at `initial` and can only change inside an effect, so the server
+    // HTML and the first client render always agree.
+    const [collapsed, setCollapsed] = useState(initial);
+    const naturalWidthRef = useRef(null);
+    const lastSignatureRef = useRef(signature);
+    if (lastSignatureRef.current !== signature) {
+        lastSignatureRef.current = signature;
+        naturalWidthRef.current = null;
+    }
+    const measure = useCallback(() => {
+        if (disabled)
+            return;
+        const shell = shellRef.current;
+        if (!shell)
+            return;
+        const available = shell.clientWidth;
+        // A zero-width container means "not laid out yet" (display:none, a closed
+        // drawer). Measuring it would collapse every row on the page.
+        if (available <= 0)
+            return;
+        const row = rowRef.current;
+        if (row) {
+            const natural = row.scrollWidth;
+            naturalWidthRef.current = natural;
+            if (natural > available + EPSILON)
+                setCollapsed(true);
+            return;
+        }
+        // Collapsed: the row is gone. The cached width is the only evidence of
+        // what expanding would cost.
+        const natural = naturalWidthRef.current;
+        if (natural == null)
+            return;
+        if (available >= natural + EXPAND_SLACK_PX)
+            setCollapsed(false);
+    }, [disabled, shellRef, rowRef]);
+    /*
+     * Content width — a count appearing, a locale swapping every label.
+     * Dependency-free so it runs after every render: none of those is
+     * expressible as a dep, and a ResizeObserver on the shell fires for its own
+     * box, never for its content. Safe because `measure` only calls setState on
+     * an actual change, so there is no render loop. Two layout READS per render,
+     * no writes, so no forced reflow.
+     */
+    useLayoutEffect(() => {
+        measure();
+    });
+    // Container width: viewport resize, sidebar collapse, drawer open.
+    useEffect(() => {
+        const shell = shellRef.current;
+        // jsdom does not implement ResizeObserver; guard so the hook is safe in
+        // any non-DOM runtime.
+        if (!shell || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => measure());
+        observer.observe(shell);
+        return () => observer.disconnect();
+    }, [shellRef, measure]);
+    // A web-font swap changes every label's width after first paint; without
+    // this the initial measurement is taken against the fallback font.
+    useEffect(() => {
+        let cancelled = false;
+        const fonts = document.fonts;
+        fonts?.ready?.then(() => {
+            if (!cancelled)
+                measure();
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [measure]);
+    return disabled ? initial : collapsed;
+}

package/dist/ui/components/toast-context.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The toast CONTEXT, split out of `Toast.tsx`.
+ *
+ * ## Why this module exists
+ *
+ * `Button` reads `useToastSafe()` so a `<Button action={…}>` with a
+ * confirmation can report the outcome, and `Toast` renders a `<Button>` as its
+ * dismiss control. Both edges are real VALUE imports, so `Button.tsx` and
+ * `Toast.tsx` formed a genuine two-module import cycle — not a type-only one
+ * that the compiler erases. `audit-import-cycles` carried it as component 3.
+ *
+ * A cycle between two primitives is worse than untidy: module initialisation
+ * order becomes whichever one the bundler happens to reach first, so a future
+ * top-level `const` in either file could read the other's export before it is
+ * initialised. Splitting the context out gives both a single direction to
+ * depend in — `Button → toast-context` and `Toast → toast-context + Button`.
+ *
+ * 🛑 `"use client"` must stay the FIRST line: this file creates a React
+ * context and exports hooks, and without the directive Next treats it as a
+ * Server Component and the recovery render crashes (Root Cause #12).
+ *
+ * 🛑 ONE `createContext` call, in this file only. The provider and both hooks
+ * must resolve to the same object or `useContext` reads an empty context —
+ * which is the dual-instance failure mode of Root Cause #19, reachable here by
+ * copy-paste rather than by a duplicated package.
+ */
+import React from "react";
+export type ToastVariant = "success" | "error" | "warning" | "info" | "loading";
+export type ToastPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+export interface ToastItem {
+    id: string;
+    message: string;
+    variant: ToastVariant;
+    duration: number;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+export interface ToastContextValue {
+    /**
+     * Show a toast. Returns the `dismissId` so long-running ops can later finalize
+     * via `updateToast(id, "success" | "error", finalMessage)`. For the "loading"
+     * variant pass `duration: 0` to keep it pinned until finalized.
+     */
+    showToast: (message: string, variant?: ToastVariant, duration?: number, action?: {
+        label: string;
+        onClick: () => void;
+    }) => string;
+    hideToast: (id: string) => void;
+    /** Replace an existing toast's variant + message (used to finalize loading toasts). */
+    updateToast: (id: string, variant: ToastVariant, message?: string, duration?: number) => void;
+}
+export declare const ToastContext: React.Context<ToastContextValue | undefined>;
+export declare function buildToastId(): string;
+export declare function useToast(): ToastContextValue;
+/**
+ * Like `useToast` but returns `undefined` when no `ToastProvider` is mounted
+ * instead of throwing. Use in primitives (e.g. `Button`) that must be safe to
+ * render outside a toast context — library code that adjusts for its
+ * surroundings must not require a provider (Root Cause #20).
+ */
+export declare function useToastSafe(): ToastContextValue | undefined;

package/dist/ui/components/toast-context.js

@@ -0,0 +1,48 @@
+"use client";
+/**
+ * The toast CONTEXT, split out of `Toast.tsx`.
+ *
+ * ## Why this module exists
+ *
+ * `Button` reads `useToastSafe()` so a `<Button action={…}>` with a
+ * confirmation can report the outcome, and `Toast` renders a `<Button>` as its
+ * dismiss control. Both edges are real VALUE imports, so `Button.tsx` and
+ * `Toast.tsx` formed a genuine two-module import cycle — not a type-only one
+ * that the compiler erases. `audit-import-cycles` carried it as component 3.
+ *
+ * A cycle between two primitives is worse than untidy: module initialisation
+ * order becomes whichever one the bundler happens to reach first, so a future
+ * top-level `const` in either file could read the other's export before it is
+ * initialised. Splitting the context out gives both a single direction to
+ * depend in — `Button → toast-context` and `Toast → toast-context + Button`.
+ *
+ * 🛑 `"use client"` must stay the FIRST line: this file creates a React
+ * context and exports hooks, and without the directive Next treats it as a
+ * Server Component and the recovery render crashes (Root Cause #12).
+ *
+ * 🛑 ONE `createContext` call, in this file only. The provider and both hooks
+ * must resolve to the same object or `useContext` reads an empty context —
+ * which is the dual-instance failure mode of Root Cause #19, reachable here by
+ * copy-paste rather than by a duplicated package.
+ */
+import React from "react";
+export const ToastContext = React.createContext(undefined);
+export function buildToastId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function useToast() {
+    const context = React.useContext(ToastContext);
+    if (!context) {
+        throw new Error("useToast must be used within ToastProvider");
+    }
+    return context;
+}
+/**
+ * Like `useToast` but returns `undefined` when no `ToastProvider` is mounted
+ * instead of throwing. Use in primitives (e.g. `Button`) that must be safe to
+ * render outside a toast context — library code that adjusts for its
+ * surroundings must not require a provider (Root Cause #20).
+ */
+export function useToastSafe() {
+    return React.useContext(ToastContext);
+}

package/dist/ui/components/top-banner-slot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The portal target ABOVE the sticky header, published by `AppLayoutShell`.
+ *
+ * This is the page's topmost band: a dismissible announcement or promo strip
+ * that a PAGE owns but that must render above the title bar, which only the
+ * layout can place. A page cannot render into the layout's header by returning
+ * JSX, so it portals here instead.
+ *
+ * ── 🛑 Why this exists rather than an `overlay` prop ───────────────────────
+ *
+ * `AnnouncementBar` used to take `overlay`, which positioned it `absolute
+ * inset-x-0 top-0` over the homepage's first section. That reserves no space
+ * by design, so the banner painted ON TOP of the hero — the whole reason the
+ * component carried a measured-overlap comment about phone widths. Moving it
+ * into the real document flow above the header removes the overlap as a class
+ * of bug rather than tuning the breakpoint it happens at.
+ *
+ * ── 🛑 The slot is deliberately OUTSIDE the sticky wrapper ────────────────
+ *
+ * `AppLayoutShell` measures its sticky header into `--header-height`, and every
+ * `StickyToolbar offset="header"` in the app reads that. A banner placed inside
+ * that wrapper would inflate the number for as long as it is on screen and
+ * shrink it the moment someone dismisses it — so every sticky toolbar on the
+ * page would jump. Outside the wrapper, the banner scrolls away with the page,
+ * `--header-height` never changes, and dismissal costs no relayout below.
+ *
+ * Lives in `ui/` for the same reason as `bottom-chrome-slot`: `features/layout`
+ * imports from `ui`, so the reverse would close an import cycle through the
+ * `ui` barrel. Nothing here imports anything but React.
+ */
+export declare const TOP_BANNER_SLOT_ID = "appkit-top-banner-slot";
+/**
+ * Resolves the top-banner portal target. Returns `null` until after mount, so a
+ * consumer never touches the DOM during render — render nothing while it is
+ * null, and portal into it once it resolves.
+ */
+export declare function useTopBannerSlot(): HTMLElement | null;

package/dist/ui/components/top-banner-slot.js

@@ -0,0 +1,45 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * The portal target ABOVE the sticky header, published by `AppLayoutShell`.
+ *
+ * This is the page's topmost band: a dismissible announcement or promo strip
+ * that a PAGE owns but that must render above the title bar, which only the
+ * layout can place. A page cannot render into the layout's header by returning
+ * JSX, so it portals here instead.
+ *
+ * ── 🛑 Why this exists rather than an `overlay` prop ───────────────────────
+ *
+ * `AnnouncementBar` used to take `overlay`, which positioned it `absolute
+ * inset-x-0 top-0` over the homepage's first section. That reserves no space
+ * by design, so the banner painted ON TOP of the hero — the whole reason the
+ * component carried a measured-overlap comment about phone widths. Moving it
+ * into the real document flow above the header removes the overlap as a class
+ * of bug rather than tuning the breakpoint it happens at.
+ *
+ * ── 🛑 The slot is deliberately OUTSIDE the sticky wrapper ────────────────
+ *
+ * `AppLayoutShell` measures its sticky header into `--header-height`, and every
+ * `StickyToolbar offset="header"` in the app reads that. A banner placed inside
+ * that wrapper would inflate the number for as long as it is on screen and
+ * shrink it the moment someone dismisses it — so every sticky toolbar on the
+ * page would jump. Outside the wrapper, the banner scrolls away with the page,
+ * `--header-height` never changes, and dismissal costs no relayout below.
+ *
+ * Lives in `ui/` for the same reason as `bottom-chrome-slot`: `features/layout`
+ * imports from `ui`, so the reverse would close an import cycle through the
+ * `ui` barrel. Nothing here imports anything but React.
+ */
+export const TOP_BANNER_SLOT_ID = "appkit-top-banner-slot";
+/**
+ * Resolves the top-banner portal target. Returns `null` until after mount, so a
+ * consumer never touches the DOM during render — render nothing while it is
+ * null, and portal into it once it resolves.
+ */
+export function useTopBannerSlot() {
+    const [slot, setSlot] = useState(null);
+    useEffect(() => {
+        setSlot(document.getElementById(TOP_BANNER_SLOT_ID));
+    }, []);
+    return slot;
+}

package/dist/ui/icons/icon-registry.d.ts

@@ -58,6 +58,13 @@ export declare const ICONS: {
     readonly themeLight: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly themeDark: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly deals: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly preOrder: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly prizeDraw: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly digitalCode: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly art: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly stickers: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly spares: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly live: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 };
 /** Every valid `iconKey`. A typo is a compile error, not a silent blank. */
 export type IconKey = keyof typeof ICONS;

package/dist/ui/icons/icon-registry.js

@@ -39,7 +39,7 @@
  * @tag consumers:Button,RowActionMenu,BulkActionBar,action-registry
  * @tag sideEffects:none
  */
-import { Archive, ArrowLeft, Ban, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, } from "lucide-react";
+import { Archive, ArrowLeft, Ban, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, CalendarClock, Gift, KeyRound, Palette, Sticker, Puzzle, PawPrint, } from "lucide-react";
 /**
  * Semantic name → component.
  *
@@ -110,6 +110,30 @@ export const ICONS = {
     themeLight: Sun,
     themeDark: Moon,
     deals: Tag,
+    /*
+     * Listing-type glyphs — one per `ListingType`, consumed by
+     * `ListingTypePlugin.iconKey` so a type chip can carry a leading visual.
+     *
+     * 🛑 Four of the nine reuse an existing verb rather than minting a new icon:
+     * `standard` is `order` (Package), `auction` is `bid` (Gavel), `classified`
+     * is `deals` (Tag), `live` is the only animal glyph here. This registry's
+     * header is explicit that it is deliberately small and not a re-export of
+     * lucide — so a type earns a new entry only when nothing already means it.
+     */
+    preOrder: CalendarClock,
+    prizeDraw: Gift,
+    digitalCode: KeyRound,
+    art: Palette,
+    stickers: Sticker,
+    /*
+     * Nothing in the registry meant "a part", so this is minted rather than
+     * reused. `Puzzle` over `Cog`/`Wrench` because the semantic is "a piece that
+     * fits into something" — which is exactly what the spares feature is about,
+     * right down to the glossary's "Fits: …" cross-sell. A cog reads as
+     * machinery or settings, and `settings` already owns that glyph.
+     */
+    spares: Puzzle,
+    live: PawPrint,
 };
 /**
  * The ONLY sanctioned glyph sizes.