@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/ui/components/SideDrawer.js

@@ -7,7 +7,11 @@ import { Button } from "./Button.js";
 import { ActionRow } from "./ActionRow.js";
 import { Row } from "./Layout.js";
 import { Heading, Span } from "./Typography.js";
-import { useSwipe } 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 { Text } from "./Typography.js";
 import { SPRING_SNAPPY } from "../../tokens/motion.js";
 import { useHandMode } from "../../_internal/client/hand-mode/index.js";

package/dist/ui/components/SideModal.js

@@ -2,7 +2,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import { motion, AnimatePresence, useReducedMotion } from "motion/react";
-import { Button, Div, Heading } from "../index.js";
+/*
+ * 🛑 This was `from ".."` — a component importing its own barrel, which is the
+ * tightest possible cycle: `ui/index.ts` exports `SideModal`, so the module
+ * depended on the file that depends on it. Nothing needed the barrel; all
+ * three symbols are one directory away.
+ */
+import { Button } from "./Button.js";
+import { Div } from "./Div.js";
+import { Heading } from "./Typography.js";
 import { ActionRow } from "./ActionRow.js";
 import { SPRING_SNAPPY } from "../../tokens/motion.js";
 import { useHandMode } from "../../_internal/client/hand-mode/index.js";

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,7 @@
 @import "./RowActionMenu.style.css";
 @import "./Div.style.css";
 @import "./Menu.style.css";
+@import "./OverflowRow.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,12 @@ 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 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;