@mohasinac/appkit 4.13.1 → 4.14.0

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

@@ -217,13 +217,28 @@
  * That is exactly what happened to every image-tile button in the app when
  * the ripple landed.
  *
- * `justify-content` / `gap` are inherited so the button's own `justify` and
- * `gap` props keep reaching the real children now that they sit one level
- * deeper than the flex container that declares them.
+ * ALL FOUR flex-container properties must be inherited — `flex-direction` and
+ * `align-items` as much as `justify-content` and `gap` — because the real
+ * children now sit one level deeper than the container declaring them. The
+ * first pass at this fix inherited only two and hard-coded `align-items:
+ * center`, so a Button asking for `flex-col` silently still laid its children
+ * out in a row: the prize-draw collage, the media picker and the concern card
+ * each rendered an image tile BESIDE its caption instead of above it, at a
+ * fraction of the intended width. `inherit` is behaviour-identical for every
+ * ordinary button — `.appkit-button` declares `align-items: center` and never
+ * declares `flex-direction`, so it computes to the initial `row`.
+ *
+ * One thing this CSS cannot defend against: a caller putting a bare `block` /
+ * `flex` / `hidden` Tailwind utility on the Button. The consumer's globals.css
+ * declares those un-layered and `!important`, which beats `.appkit-button`'s
+ * `display: inline-flex` — and every rule below applies only to a flex ITEM, so
+ * the whole contract goes inert and fill children collapse to 0x0 again. That
+ * is guarded from the call-site side by scripts/audit-primitive-child-wrappers.mjs.
  */
 .appkit-button__content {
   display: inline-flex;
-  align-items: center;
+  flex-direction: inherit;
+  align-items: inherit;
   justify-content: inherit;
   gap: inherit;
   flex: 1 1 auto;

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

@@ -5,6 +5,22 @@ export interface CollapsibleSectionProps {
     onToggle: () => void;
     /** Optional right-aligned content next to the title (badges, counts). */
     renderHeaderExtra?: () => React.ReactNode;
+    /**
+     * Keep collapsed children mounted (hidden via CSS) instead of unmounting them.
+     *
+     * `<Collapse>` renders `{isOpen && <motion.div>}` — collapsing therefore
+     * UNMOUNTS the subtree and destroys any uncommitted state inside it. That is
+     * harmless for inputs driven entirely off a parent `values` object, but it
+     * discards in-flight work for anything holding its own: a `useMediaUpload`
+     * transfer, a rich-text editor buffer, a partially-filled multi-select.
+     *
+     * Set this on any section that can hold uncommitted state. The trade-off is
+     * that hidden children still render, so don't enable it for expensive
+     * subtrees that are purely presentational.
+     */
+    keepMounted?: boolean;
+    /** Anchor id on the section root — lets a caller scroll/link to it. */
+    id?: string;
     className?: string;
     children?: React.ReactNode;
 }
@@ -12,4 +28,4 @@ export interface CollapsibleSectionProps {
  * per-user, accordion-scoped collapse state (see that hook for the
  * server-side merge/default-collapsed semantics). Purely presentational
  * here: isCollapsed/onToggle are always controlled by the caller. */
-export declare function CollapsibleSection({ title, isCollapsed, onToggle, renderHeaderExtra, className, children, }: CollapsibleSectionProps): React.JSX.Element;
+export declare function CollapsibleSection({ title, isCollapsed, onToggle, renderHeaderExtra, keepMounted, id, className, children, }: CollapsibleSectionProps): React.JSX.Element;

package/dist/ui/components/CollapsibleSection.js

@@ -8,6 +8,10 @@ import { Collapse } from "./Motion";
  * per-user, accordion-scoped collapse state (see that hook for the
  * server-side merge/default-collapsed semantics). Purely presentational
  * here: isCollapsed/onToggle are always controlled by the caller. */
-export function CollapsibleSection({ title, isCollapsed, onToggle, renderHeaderExtra, className = "", children, }) {
-    return (_jsxs(Div, { className: className, rounded: "xl", border: "default", surface: "default", children: [_jsxs(Row, { align: "center", justify: "between", paddingX: "x-md", paddingY: "y-sm", children: [_jsx(Button, { type: "button", variant: "ghost", onClick: onToggle, paddingX: "none", paddingY: "none", rounded: "none", className: "min-w-0 flex-1", "aria-expanded": !isCollapsed, children: _jsxs(Row, { align: "center", justify: "between", className: "w-full", children: [_jsx(Span, { weight: "semibold", size: "sm", children: title }), _jsx("svg", { className: `w-4 h-4 transition-transform duration-150 ${isCollapsed ? "" : "rotate-180"}`, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M19 9l-7 7-7-7" }) })] }) }), renderHeaderExtra && _jsx(Div, { className: "ml-3 shrink-0", children: renderHeaderExtra() })] }), _jsx(Collapse, { isOpen: !isCollapsed, children: _jsx(Div, { padding: "md", border: "top", children: children }) })] }));
+export function CollapsibleSection({ title, isCollapsed, onToggle, renderHeaderExtra, keepMounted = false, id, className = "", children, }) {
+    return (_jsxs(Div, { id: id, className: className, rounded: "xl", border: "default", surface: "default", children: [_jsxs(Row, { align: "center", justify: "between", paddingX: "x-md", paddingY: "y-sm", children: [_jsx(Button, { type: "button", variant: "ghost", onClick: onToggle, paddingX: "none", paddingY: "none", rounded: "none", className: "min-w-0 flex-1", "aria-expanded": !isCollapsed, children: _jsxs(Row, { align: "center", justify: "between", className: "w-full", children: [_jsx(Span, { weight: "semibold", size: "sm", children: title }), _jsx("svg", { className: `w-4 h-4 transition-transform duration-150 ${isCollapsed ? "" : "rotate-180"}`, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M19 9l-7 7-7-7" }) })] }) }), renderHeaderExtra && _jsx(Div, { className: "ml-3 shrink-0", children: renderHeaderExtra() })] }), keepMounted ? (
+            // No <Collapse>: it unmounts on close, which would discard uncommitted
+            // child state (see `keepMounted` docs). `hidden` keeps the subtree
+            // mounted and removes it from the a11y tree at the same time.
+            _jsx(Div, { padding: "md", border: "top", hidden: isCollapsed, children: children })) : (_jsx(Collapse, { isOpen: !isCollapsed, children: _jsx(Div, { padding: "md", border: "top", children: children }) }))] }));
 }

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

@@ -22,6 +22,16 @@ import React from "react";
 export interface FilterChipGroupTab {
     id: string;
     label: string;
+    /**
+     * Rows matching this chip within the surface's current scope. Rendered as a
+     * trailing count and, with `hideEmpty`, used to drop chips that would return
+     * nothing.
+     *
+     * `undefined` means "not counted / count failed" — NOT zero. Such a chip is
+     * always kept, so a surface that supplies no counts behaves exactly as before
+     * and a failed count can never hide a filter that has rows (Root Cause #59).
+     */
+    count?: number;
 }
 export interface FilterChipGroupProps {
     /** Section label shown above the chips. */
@@ -52,7 +62,21 @@ export interface FilterChipGroupProps {
      * same state that every caller would have to remember to clear.
      */
     multiple?: boolean;
+    /**
+     * Drop chips whose `count` is exactly 0 — a filter that can only ever return
+     * an empty list is noise.
+     *
+     * Opt-in (default `false`) because most of this component's ~45 call sites
+     * supply no counts at all, and because it is only ever correct for a FILTER
+     * over existing rows. Never enable it on a picker that CREATES something: a
+     * seller with no auctions yet must still be able to make their first one.
+     *
+     * A chip whose count is `undefined` is always kept — see `FilterChipGroupTab.count`.
+     * The currently-selected chip is also always kept, so an active filter can
+     * never vanish from under the user mid-interaction.
+     */
+    hideEmpty?: boolean;
     /** Optional className spread onto the outer wrapper. */
     className?: string;
 }
-export declare function FilterChipGroup({ label, tabs, value, onChange, allId, multiple, className, }: FilterChipGroupProps): React.JSX.Element;
+export declare function FilterChipGroup({ label, tabs, value, onChange, allId, multiple, hideEmpty, className, }: FilterChipGroupProps): React.JSX.Element;

package/dist/ui/components/FilterChipGroup.js

@@ -6,16 +6,33 @@ const ACTIVE_CLS = "bg-[var(--appkit-color-primary)] text-white border-[var(--ap
 const INACTIVE_CLS = "border-[var(--appkit-color-border)] text-[var(--appkit-color-text-muted)] hover:bg-zinc-50 hover:bg-[var(--appkit-color-surface-elevated)]";
 const CHIP_BASE_CLS = "rounded-full px-3 py-1 text-xs font-medium border transition-colors";
 const LABEL_CLS = "text-xs font-semibold uppercase tracking-widest text-[var(--appkit-color-text-muted)]";
+// `opacity-70` rather than a fixed colour so the count stays legible against
+// both the active (primary fill) and inactive (surface) chip backgrounds —
+// a literal text colour would be invisible on one of them in some theme
+// (Root Cause #67).
+const COUNT_CLS = "ml-1.5 tabular-nums opacity-70";
 /** Split a pipe-joined multi-select value into its ids. */
 function parseMulti(value) {
     return value ? value.split("|").filter(Boolean) : [];
 }
-export function FilterChipGroup({ label, tabs, value, onChange, allId = "All", multiple = false, className, }) {
+export function FilterChipGroup({ label, tabs, value, onChange, allId = "All", multiple = false, hideEmpty = false, className, }) {
     const selected = new Set(multiple ? parseMulti(value) : []);
     const current = value || allId;
     // In multi-select the "All" sentinel is redundant with an empty selection —
     // see the `multiple` prop docs.
-    const visibleTabs = multiple ? tabs.filter((t) => t.id !== allId) : tabs;
+    const allTabs = multiple ? tabs.filter((t) => t.id !== allId) : tabs;
+    const visibleTabs = hideEmpty
+        ? allTabs.filter((t) => {
+            // Never hide the "All" sentinel, and never hide a chip the user has
+            // already picked — a filter disappearing while it is applied would
+            // leave the URL holding a value with no way to clear it.
+            if (t.id === allId)
+                return true;
+            if (multiple ? selected.has(t.id) : current === t.id)
+                return true;
+            return t.count === undefined || t.count > 0;
+        })
+        : allTabs;
     const handleClick = (tabId) => {
         if (!multiple) {
             onChange(tabId === allId ? "" : tabId);
@@ -36,9 +53,9 @@ export function FilterChipGroup({ label, tabs, value, onChange, allId = "All", m
     };
     return (_jsxs(Div, { className: `space-y-2 ${className ?? ""}`.trim(), children: [_jsx(Text, { as: "p", className: LABEL_CLS, children: label }), _jsx(Div, { className: "flex flex-wrap gap-2", role: multiple ? "group" : undefined, "aria-label": multiple ? label : undefined, children: visibleTabs.map((tab) => {
                     const isActive = multiple ? selected.has(tab.id) : current === tab.id;
-                    return (_jsx("button", { type: "button", 
+                    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 }, 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.label, typeof tab.count === "number" && (_jsx("span", { className: COUNT_CLS, children: tab.count > 99 ? "99+" : tab.count }))] }, tab.id));
                 }) })] }));
 }

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

@@ -0,0 +1,47 @@
+/* Hand-mode mirroring — CSS-only, driven by `<html data-hand>`.
+ *
+ * `data-hand` is written before first paint by the blocking script in the
+ * consumer's root layout, so these rules apply on the FIRST paint: no flash,
+ * no server/client hydration mismatch (`HandModeProvider` reads localStorage
+ * in its useState initialiser, so a className derived from `hand` would
+ * differ server vs client), and no "use client" forced onto server-safe
+ * primitives (Root Cause #12). These are hand-authored classes, not Tailwind
+ * output, so they also survive the consumer's `@source not "../../appkit"`
+ * purge (Root Cause #3).
+ *
+ * NOTE: both appkit's and the consumer's Tailwind builds set
+ * `important: true`. Any call site using these classes MUST NOT also carry
+ * the equivalent utility (`flex-row-reverse`, `-right-*`) — an !important
+ * declaration in @layer utilities beats these unlayered rules, so the class
+ * would silently do nothing.
+ */
+
+/* Mirror a flex row's VISUAL order only. DOM order — and therefore reading
+   order, aria-* and the focus sequence — is unchanged. */
+[data-hand="left"] .appkit-hand-mirror {
+  flex-direction: row-reverse;
+}
+
+/* Corner count badge hugging the OUTER top corner of its icon: top-right by
+   default, top-left in left-hand mode. Owns the HORIZONTAL axis only — the
+   vertical offset stays a `-top-*` utility at the call site.
+
+   The offset comes from `--appkit-badge-offset`, declared only by the size
+   modifiers below. That matters: a `--lg { right: -0.5rem }` variant would be
+   specificity (0,1,0) and would LOSE to `[data-hand="left"] .appkit-hand-badge`
+   at (0,2,0), so left-hand mode would silently fall back to the small offset.
+   A custom property has no such race. */
+.appkit-hand-badge {
+  right: calc(var(--appkit-badge-offset, 0.125rem) * -1);
+  left: auto;
+}
+
+[data-hand="left"] .appkit-hand-badge {
+  left: calc(var(--appkit-badge-offset, 0.125rem) * -1);
+  right: auto;
+}
+
+/* 0.5rem inset — the offset the bottom-nav badges expressed as `-right-2`. */
+.appkit-hand-badge--lg {
+  --appkit-badge-offset: var(--appkit-space-2, 0.5rem);
+}

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

@@ -281,8 +281,15 @@ export interface RowProps extends React.HTMLAttributes<HTMLElement>, SurfaceProp
     wrap?: boolean;
     /** Reverse the visual order of children (`flex-direction: row-reverse`) without
      * touching DOM/source order. Used for hand-mode-aware layouts (e.g. moving a
-     * close button to the opposite header edge) — replaces raw `flex-row-reverse`. */
-    reverse?: boolean;
+     * close button to the opposite header edge) — replaces raw `flex-row-reverse`.
+     *
+     * `true` reverses unconditionally. `"hand"` defers the decision to the
+     * `data-hand` preference: it mirrors only in left-hand mode, entirely in CSS
+     * (`HandMode.style.css`), so `Row` stays hook-free and server-safe and the
+     * flip lands on the FIRST paint — no flash, no hydration mismatch. Prefer
+     * `"hand"` over `useHandMode()` + `reverse={hand === "left"}` for anything
+     * rendered above the fold. */
+    reverse?: boolean | "hand";
     /** Zebra-stripe pattern when this Row is a repeating list element (rendered with `even:bg-*`). */
     oddEven?: "none" | "zebra";
     /**

package/dist/ui/components/Layout.js

@@ -235,7 +235,7 @@ export function Row({ gap = "md", centered = false, align = "center", justify =
     const Tag = (as ?? "div");
     const classes = [
         "appkit-row",
-        reverse ? "appkit-row--reverse" : "",
+        reverse === "hand" ? "appkit-hand-mirror" : reverse ? "appkit-row--reverse" : "",
         centered ? "appkit-row--centered" : align !== "center" ? ITEMS_MAP[align] : "",
         !centered && justify !== "start" ? JUSTIFY_MAP[justify] : "",
         GAP_MAP[gap],

package/dist/ui/components/ListingLayout.js

@@ -20,6 +20,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  *  └----------┴-------------------------------------------------------┘
  */
 import { useState } from "react";
+import { createPortal } from "react-dom";
+import { useBottomChromeSlot } from "./bottom-chrome-slot";
 import { Aside, Nav } from "./Semantic";
 import { Text, Span } from "./Typography";
 import { Button } from "./Button";
@@ -42,6 +44,9 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
     // Rules of Hooks.
     const [sidebarOpen, setSidebarOpen] = useState(defaultSidebarOpen);
     const [mobileFilterOpen, setMobileFilterOpen] = useState(false);
+    // 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 });
@@ -92,14 +97,9 @@ 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 && (_jsx(Nav, { "aria-label": "Pagination", className: [
-                    "appkit-listing-layout__mobile-pagination",
-                    effectiveIsDashboard
-                        ? "appkit-listing-layout__mobile-pagination--dashboard"
-                        : selectedCount > 0
-                            ? "appkit-listing-layout__mobile-pagination--bulk"
-                            : "appkit-listing-layout__mobile-pagination--default",
-                ].join(" "), children: toolbarPaginationSlot })), hasFilter && (_jsx(Drawer, { isOpen: mobileFilterOpen, onClose: () => setMobileFilterOpen(false), side: "bottom", title: filterActiveCount > 0
+                                            : 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 &&
+                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})`
                     : panelTitle, footer: _jsxs(Div, { className: "appkit-listing-layout__mobile-overlay-footer", children: [_jsx(Button, { type: "button", variant: "secondary", className: "flex-1 rounded-xl", onClick: () => onFilterClear?.(), children: l.clearAll }), _jsx(Button, { type: "button", variant: "primary", className: "flex-1 rounded-xl", onClick: handleMobileApply, children: filterPendingCount != null && filterPendingCount > 0
                                 ? `${l.applyFilters} (${filterPendingCount})`

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

@@ -376,11 +376,10 @@
 
 /* -- Mobile sticky pagination bar ------------------- */
 
+/* Positioned by <BottomChrome>, the shell's bottom-edge tier — this element is
+   a flex child of it, so it owns no position, offset or z-index of its own. */
 .appkit-listing-layout__mobile-pagination {
-  position: fixed;
-  left: 0;
-  right: 0;
-  z-index: 39;
+  pointer-events: auto;
   background: rgba(255, 255, 255, 0.9);
   backdrop-filter: blur(12px);
   border-top: 1px solid rgba(228, 228, 231, 0.8);
@@ -406,9 +405,11 @@
   box-shadow: 0 -2px 8px rgba(0, 0, 0, 0.2);
 }
 
-.appkit-listing-layout__mobile-pagination--dashboard { bottom: 0; }
-.appkit-listing-layout__mobile-pagination--default   { bottom: var(--bottom-nav-height, 4rem); }
-.appkit-listing-layout__mobile-pagination--bulk      { bottom: calc(var(--bottom-nav-height, 4rem) + 3.5rem); }
+/* The --dashboard / --default / --bulk offset modifiers are gone. --bulk only
+   ever meant "the CTA bar is up", expressed as "rows are selected", and it
+   hardcoded 3.5rem for that bar's height; --dashboard's `bottom: 0` only
+   existed because the dashboard nav published no height. The tier answers both
+   questions directly now. */
 
 /* -- Mobile filter overlay --------------------------- */
 

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

@@ -12,7 +12,9 @@ import { type ReactNode } from "react";
  * Dismiss/hide: pass `dismissible` (with a stable `id`) to let the user
  * collapse the bar to a thin re-expand strip for the rest of the browser
  * session — a viewport-annoyance-avoidance toggle, not a durable
- * preference, so it resets on reload rather than persisting forever. This
+ * preference, so it resets on reload rather than persisting forever. Both
+ * directions render the same centred, labelled strip ("Hide Toolbar" /
+ * "Show Toolbar") so the control is symmetric and self-describing. This
  * is what closes the mobile-overlap complaint the sticky toolbar pattern
  * caused across listing pages: at narrow widths, any sticky bar competing
  * with page content for vertical space needs a way out that doesn't require

package/dist/ui/components/StickyToolbar.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { ChevronDown } from "lucide-react";
 import { normalizeError } from "../../errors/normalize";
 const TONE_CLS = {
@@ -24,19 +24,22 @@ function resolveOffsetClass(offset) {
         return "top-[calc(var(--header-height,0px)+var(--appkit-navbar-height,2.5rem))]";
     }
     if (offset === "header+pagination") {
-        // Matches the sticky pagination-row offset repeated verbatim across
-        // every DataListingView-style index listing (64px = the ListingToolbar
-        // row height above it — py-3/py-3.5 padding + its ~38px content row) —
-        // consolidated here instead of copy-pasted. Keep in sync with
-        // ListingToolbar's own padding classes; a mismatch makes the pagination
-        // row overlap/hide behind the toolbar (the "too compact when sticky"
-        // regression fixed 2026-08-19).
-        return "top-[calc(var(--header-height,0px)+64px)]";
+        // The sticky pagination-row offset repeated verbatim across every
+        // DataListingView-style index listing — consolidated here instead of
+        // copy-pasted. It tracks the toolbar's REAL height via
+        // --appkit-toolbar-height, which a dismissible StickyToolbar publishes
+        // from its own ResizeObserver (see TOOLBAR_HEIGHT_VAR below). A fixed
+        // constant can only ever be right in one state: the toolbar is ~64px
+        // expanded but ~20px collapsed, so hard-coding 64px left a ~44px gap
+        // through which page content scrolled between the two pinned bars.
+        // The 64px fallback is the expanded height, used on any page whose
+        // toolbar isn't dismissible and therefore publishes nothing.
+        return "top-[calc(var(--header-height,0px)+var(--appkit-toolbar-height,64px))]";
     }
     if (offset === "header+bulk-actions") {
-        // Matches the sticky bulk-action-bar offset that stacks below both the
-        // filter toolbar (64px) and the pagination row above it (~52px more).
-        return "top-[calc(var(--header-height,0px)+116px)]";
+        // Stacks below both the filter toolbar (same variable as above) and the
+        // pagination row between them (~52px).
+        return "top-[calc(var(--header-height,0px)+var(--appkit-toolbar-height,64px)+52px)]";
     }
     // Numeric offsets are applied via inline style instead (see below) —
     // Tailwind's static scanner can never see a dynamically-interpolated
@@ -44,6 +47,13 @@ function resolveOffsetClass(offset) {
     // generated for it in the compiled stylesheet.
     return "";
 }
+/**
+ * Written to `<html>` by every dismissible StickyToolbar from a
+ * ResizeObserver, and consumed by the `header+pagination` /
+ * `header+bulk-actions` offsets so a bar stacked underneath tracks the real
+ * height in both the expanded and collapsed states.
+ */
+const TOOLBAR_HEIGHT_VAR = "--appkit-toolbar-height";
 const STORAGE_PREFIX = "appkit:sticky-toolbar-collapsed:";
 function readCollapsed(id) {
     if (typeof window === "undefined")
@@ -69,12 +79,45 @@ function writeCollapsed(id, value) {
         // works for the current render, just doesn't survive a re-mount.
     }
 }
+/**
+ * The collapse/expand control — one component for both states so the two
+ * halves of the affordance can't drift apart (the collapsed strip read
+ * "Show Toolbar" while the expanded one was a bare, unlabelled chevron
+ * pinned to the far right until 2026-08-24).
+ */
+function CollapseStrip({ collapsed, label, onToggle, className, }) {
+    return (_jsx("div", { className: `flex justify-center ${className ?? ""}`, children: _jsxs("button", { type: "button", onClick: onToggle, "aria-label": `${collapsed ? "Show" : "Hide"} ${label}`, "aria-expanded": !collapsed, className: "flex items-center gap-1 px-4 py-0.5 text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: [_jsx(ChevronDown, { className: `h-3.5 w-3.5 transition-transform duration-150 ${collapsed ? "" : "rotate-180"}`, "aria-hidden": "true" }), collapsed ? "Show" : "Hide", " ", label] }) }));
+}
 export function StickyToolbar({ children, offset = "header", tone = "translucent", border = true, padding = "toolbar", z = "above-content", role, className, dataTestId, dismissible = false, id, label = "Toolbar", }) {
     const [collapsed, setCollapsed] = useState(false);
+    const rootRef = useRef(null);
     useEffect(() => {
         if (dismissible && id)
             setCollapsed(readCollapsed(id));
     }, [dismissible, id]);
+    // Publish the rendered height so a bar stacked below (sticky pagination,
+    // bulk-action bar) can offset itself against what's actually on screen.
+    // `collapsed` is a dependency because the two states are distinct elements
+    // — React remounts the node, so the observer must re-attach to the new one.
+    useEffect(() => {
+        if (!dismissible || !id)
+            return;
+        const el = rootRef.current;
+        if (!el)
+            return;
+        const write = () => {
+            document.documentElement.style.setProperty(TOOLBAR_HEIGHT_VAR, `${Math.round(el.getBoundingClientRect().height)}px`);
+        };
+        write();
+        const observer = new ResizeObserver(write);
+        observer.observe(el);
+        return () => {
+            observer.disconnect();
+            // Drop it on unmount so a route with no dismissible toolbar falls back
+            // to the 64px default instead of inheriting the previous page's value.
+            document.documentElement.style.removeProperty(TOOLBAR_HEIGHT_VAR);
+        };
+    }, [dismissible, id, collapsed]);
     const offsetCls = resolveOffsetClass(offset);
     const offsetStyle = typeof offset === "number" ? { top: `${offset}px` } : undefined;
     const borderCls = border ? "border-b border-[var(--appkit-color-border)]" : "";
@@ -86,15 +129,14 @@ export function StickyToolbar({ children, offset = "header", tone = "translucent
             writeCollapsed(id, next);
     };
     if (dismissible && id && collapsed) {
-        return (_jsx("div", { "data-testid": dataTestId, style: offsetStyle, className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} flex justify-center`, children: _jsxs("button", { type: "button", onClick: toggle, "aria-label": `Show ${label}`, "aria-expanded": false, className: "flex items-center gap-1 px-4 py-0.5 text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: [_jsx(ChevronDown, { className: "h-3.5 w-3.5", "aria-hidden": "true" }), "Show ", label] }) }));
+        return (_jsx("div", { ref: rootRef, "data-testid": dataTestId, style: offsetStyle, className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls}`, children: _jsx(CollapseStrip, { collapsed: true, label: label, onToggle: toggle }) }));
     }
-    return (_jsxs("div", { role: role, "data-testid": dataTestId, style: offsetStyle, 
+    return (_jsxs("div", { ref: rootRef, role: role, "data-testid": dataTestId, style: offsetStyle, 
         // for the translucent sticky-toolbar pattern. The header offset is
         // sourced from --header-height (set by AppLayoutShell at runtime).
-        // `relative` only when dismissible — the absolutely-positioned toggle
-        // button anchors to it without disturbing the existing internal
-        // layout of `children` (each of the 27+ migrated call sites has its
-        // own Row/Div structure; a flex wrapper here would double-nest and
-        // risk breaking their centering).
-        className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} ${PADDING_CLS[padding]} ${dismissible ? "relative pr-8" : ""} ${className ?? ""}`, children: [children, dismissible && id && (_jsx("button", { type: "button", onClick: toggle, "aria-label": `Hide ${label}`, "aria-expanded": true, className: "absolute right-1.5 top-1/2 -translate-y-1/2 rounded p-1 text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-surface-elevated)] hover:text-[var(--appkit-color-text)]", children: _jsx(ChevronDown, { className: "h-3.5 w-3.5 rotate-180 transition-transform duration-150", "aria-hidden": "true" }) }))] }));
+        // The collapse control is a full-width strip appended AFTER `children`
+        // rather than an element positioned over them, so it never competes
+        // with the internal Row/Div layout each of the 27+ migrated call sites
+        // brings of its own.
+        className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} ${PADDING_CLS[padding]} ${className ?? ""}`, children: [children, dismissible && id && (_jsx(CollapseStrip, { collapsed: false, label: label, onToggle: toggle, className: "mt-1.5" }))] }));
 }

package/dist/ui/components/bottom-chrome-slot.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The portal target inside `<BottomChrome>` — the middle tier of the bottom
+ * edge, between the nav bar and BackToTop.
+ *
+ * Bars that live in the app shell (BottomActions) are rendered as children of
+ * the tier directly. Bars authored deep in the tree (ListingLayout's mobile
+ * pagination) portal into this node instead, so the tier still measures them
+ * and every offset above stays correct.
+ *
+ * This lives in `ui/` rather than next to `<BottomChrome>` in `features/layout/`
+ * on purpose: `features/layout` imports from `ui`, so a `ui` component reaching
+ * back into `features/layout` would close an import cycle through the `ui`
+ * barrel. Nothing here imports anything but React.
+ */
+export declare const BOTTOM_CHROME_SLOT_ID = "appkit-bottom-chrome-slot";
+/**
+ * Resolves the tier's 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 useBottomChromeSlot(): HTMLElement | null;

package/dist/ui/components/bottom-chrome-slot.js

@@ -0,0 +1,29 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * The portal target inside `<BottomChrome>` — the middle tier of the bottom
+ * edge, between the nav bar and BackToTop.
+ *
+ * Bars that live in the app shell (BottomActions) are rendered as children of
+ * the tier directly. Bars authored deep in the tree (ListingLayout's mobile
+ * pagination) portal into this node instead, so the tier still measures them
+ * and every offset above stays correct.
+ *
+ * This lives in `ui/` rather than next to `<BottomChrome>` in `features/layout/`
+ * on purpose: `features/layout` imports from `ui`, so a `ui` component reaching
+ * back into `features/layout` would close an import cycle through the `ui`
+ * barrel. Nothing here imports anything but React.
+ */
+export const BOTTOM_CHROME_SLOT_ID = "appkit-bottom-chrome-slot";
+/**
+ * Resolves the tier's 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 useBottomChromeSlot() {
+    const [slot, setSlot] = useState(null);
+    useEffect(() => {
+        setSlot(document.getElementById(BOTTOM_CHROME_SLOT_ID));
+    }, []);
+    return slot;
+}

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

@@ -74,3 +74,6 @@
 @import "./UnsavedChangesModal.style.css";
 @import "../DataTable.style.css";
 @import "../rich-text/RichText.style.css";
+/* Last on purpose: hand-mode rules are cross-cutting overrides keyed on
+   `[data-hand]`, not a component's own base styles. */
+@import "./HandMode.style.css";

package/dist/ui/forms/FormShell.d.ts

@@ -1,19 +1,37 @@
 import React, { type ReactNode } from "react";
 import type { FormValues } from "../../schemas/types";
 /**
- * A step descriptor. The step-wizard *rendering* this once drove
- * (`<FormShell steps={…}>`) was deleted 2026-08-09 as dead code — the real
- * wizard chrome is `features/shell/FormShell.tsx` + `StepForm.tsx`. This type
- * survives because `FormShellContextValue.steps` still carries the shape for
- * any context consumer that reads it (FormShellProvider/useFormShellState
- * both populate it as `[]` since neither is step-aware).
+ * A navigable form segment — a wizard step historically, a `<SectionForm>`
+ * section today. `FormShellContextValue.steps` carries these purely so
+ * `<FormErrorSummary>` can name the segment that owns an error and offer a
+ * jump link.
+ *
+ * `content` is optional because the common producer (`useSectionFormNav`)
+ * builds descriptors from section metadata alone — it has an id and a label
+ * to render in the summary, and no node to hand over. Requiring a node here
+ * is what previously forced both context producers to give up and populate
+ * `steps: []`, which silently disabled the jump link everywhere.
  */
 export interface FormShellStep {
     id: string;
     label: string;
     /** Field names required in this step — drives publish gate + error badge */
     requiredFields?: string[];
-    content: React.ReactNode;
+    content?: React.ReactNode;
+}
+/**
+ * Navigation wiring for a form split into steps or collapsible sections.
+ *
+ * Supplying this is what makes `<FormErrorSummary>`'s "jump to section" link
+ * work: it needs `sections` to name the owning segment and `onGoToSection` to
+ * actually move there. Omit it for single-segment forms — the summary then
+ * renders a flat list, which is correct for them.
+ */
+export interface FormShellNav {
+    sections?: FormShellStep[];
+    onGoToSection?: (index: number) => void;
+    /** Maps a (dotted) error key to the index of the section that owns it. */
+    fieldToSectionIndex?: Record<string, number>;
 }
 export interface FormShellContextValue {
     errors: Record<string, string>;
@@ -73,12 +91,17 @@ export declare function applyZodIssues(issues: ReadonlyArray<{
     message: string;
 }>, setFieldError: (name: string, error: string | null) => void): void;
 /**
- * `useFormShellState(schema?)` — caller-owned form state with optional Zod
- * validation. When a schema is supplied, `validate(values)` runs it and pipes
- * issues into the FormShellContext error map. `audit-form-schema` requires
- * every callsite to pass a schema.
+ * `useFormShellState(schema?, nav?)` — caller-owned form state with optional
+ * Zod validation. When a schema is supplied, `validate(values)` runs it and
+ * pipes issues into the FormShellContext error map. `audit-form-schema`
+ * requires every callsite to pass a schema.
+ *
+ * Pass `nav` when the form is split into sections (see `useSectionFormNav`)
+ * so `<FormErrorSummary>` can name the owning section and jump to it. Omit it
+ * for single-segment forms; the summary renders a flat list, which is right
+ * for them.
  */
-export declare function useFormShellState<TSchema extends import("zod").ZodTypeAny = import("zod").ZodTypeAny>(schema?: TSchema): UseFormShellStateResult;
+export declare function useFormShellState<TSchema extends import("zod").ZodTypeAny = import("zod").ZodTypeAny>(schema?: TSchema, nav?: FormShellNav): UseFormShellStateResult;
 export interface FormShellProviderProps {
     children: ReactNode;
     /** Called on debounced auto-save when isDirty changes */
@@ -105,5 +128,12 @@ export interface FormShellProviderProps {
     fieldToStepIndex?: Record<string, number>;
     /** Wired into `FormShellContextValue.goToStep` when the caller has real step navigation to drive (e.g. a step-wizard's `setCurrentStep`). */
     onGoToStep?: (n: number) => void;
+    /**
+     * The navigable segments this form is split into, in order. Without these
+     * `<FormErrorSummary>` can call `goToStep(i)` but has no label to render for
+     * segment `i`, so it silently falls back to a flat list — which is why this
+     * used to be hardcoded `[]`. Supply alongside `fieldToStepIndex`.
+     */
+    sections?: FormShellStep[];
 }
-export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, }: FormShellProviderProps): React.JSX.Element;
+export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, sections, }: FormShellProviderProps): React.JSX.Element;