@mohasinac/appkit 4.30.16 → 4.30.17

package/dist/tokens/tokens.css

@@ -757,10 +757,15 @@
 
 /* --- Grid ------------------------------------------------------------------ */
 :root {
-  /* Minimum column widths for auto-fill grid layouts (used in minmax()) */
+  /* Minimum column widths for auto-fill grid layouts (used in minmax()).
+     `--appkit-grid-min-card` is the canonical card-grid minimum consumed by
+     .appkit-grid--cards. At 260px the lg tier (960px of content inside the
+     max-w-screen-xl container) resolves to 3 columns and the xl tier
+     (1216px, that container's cap) to 4 — i.e. "3 or 4 depending on the
+     available width". Changing it re-columns every listing in the app. */
   --appkit-grid-min-card-xs: 130px;
   --appkit-grid-min-card-sm: 160px;
-  --appkit-grid-min-card:    220px;
+  --appkit-grid-min-card:    260px;
   --appkit-grid-min-card-lg: 300px;
 }
 

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

@@ -106,26 +106,30 @@ export declare const GRID_MAP: {
     /** 2 → 3 → 4 → 5 → 6 */
     readonly 6: "appkit-grid appkit-grid--6";
     /**
-     * Generic card grid — 1 col on portrait mobile → 5 on ultrawide.
-     * Starts at 1 so product cards are readable even on 320 px handsets.
+     * THE canonical card grid — use this for every listing surface.
+     * 1 column on phones → 2 from md → auto-fill (3 at lg, 4 at xl) above,
+     * so the column count follows the grid's own width rather than the
+     * viewport's. See the "Canonical card grid" block in Layout.style.css.
      */
     readonly cards: "appkit-grid appkit-grid--cards";
-    /** Auto-fill product cards — min 200 px */
-    readonly productCards: "appkit-grid appkit-grid--product-cards";
-    /** Auto-fill product cards (compact) — min 220 px */
-    readonly productCardsCompact: "appkit-grid appkit-grid--product-cards-compact";
-    /** Auto-fill store cards — min 220 px */
-    readonly storeCards: "appkit-grid appkit-grid--store-cards";
-    /** Auto-fill category tiles — min 130 px */
-    readonly categoryCards: "appkit-grid appkit-grid--category-cards";
-    /** Auto-fill coupon/promo cards — min 264 px */
-    readonly couponCards: "appkit-grid appkit-grid--coupon-cards";
-    /** Auto-fill address / wide cards — min 300 px */
-    readonly addressCards: "appkit-grid appkit-grid--address-cards";
-    /** Auto-fill KPI/stat tiles — min 180 px */
-    readonly statTiles: "appkit-grid appkit-grid--stat-tiles";
-    /** Auto-fill account nav tiles — min 160 px */
-    readonly navTiles: "appkit-grid appkit-grid--nav-tiles";
+    /** Card ladder at a 300 px floor — wide cards (addresses, coupons). */
+    readonly cardsWide: "appkit-grid appkit-grid--cards appkit-grid--cards-wide";
+    /** @deprecated alias of `cards` — kept so existing callers keep compiling. */
+    readonly productCards: "appkit-grid appkit-grid--cards";
+    /** @deprecated alias of `cards` */
+    readonly productCardsCompact: "appkit-grid appkit-grid--cards";
+    /** @deprecated alias of `cards` */
+    readonly storeCards: "appkit-grid appkit-grid--cards";
+    /** Card ladder at a 130 px floor — category tiles. */
+    readonly categoryCards: "appkit-grid appkit-grid--cards appkit-grid--cards-tile";
+    /** @deprecated alias of `cardsWide` */
+    readonly couponCards: "appkit-grid appkit-grid--cards appkit-grid--cards-wide";
+    /** @deprecated alias of `cardsWide` */
+    readonly addressCards: "appkit-grid appkit-grid--cards appkit-grid--cards-wide";
+    /** Card ladder at a 180 px floor — KPI/stat tiles. */
+    readonly statTiles: "appkit-grid appkit-grid--cards appkit-grid--cards-stat";
+    /** Card ladder at a 160 px floor — account nav tiles. */
+    readonly navTiles: "appkit-grid appkit-grid--cards appkit-grid--cards-nav";
     /** Equal halves on md+ */
     readonly halves: "appkit-grid appkit-grid--halves";
     /** 2fr / 1fr split on md+ */
@@ -346,6 +350,10 @@ export declare function Row({ gap, centered, align, justify, textSize, textWeigh
 export interface GridProps extends React.HTMLAttributes<HTMLElement>, SurfaceProps {
     /**
      * Column preset.
+     * - **`"cards"` → the canonical card grid. Use it for every listing surface**
+     *   (1 col on phones → 2 from md → auto-fill 3–4 above). `"cardsWide"`,
+     *   `"categoryCards"`, `"statTiles"` and `"navTiles"` are the same ladder at
+     *   a different minmax() floor.
      * - Numbers `1`–`6` → mobile-first responsive stacks
      * - `"halves"` → equal 2-col on md+
      * - `"sidebar"` / `"sidebarRight"` / `"sidebarWide"` → fixed+flexible splits
@@ -354,6 +362,11 @@ export interface GridProps extends React.HTMLAttributes<HTMLElement>, SurfacePro
      * - Omit (or `undefined`) to use a raw `grid` base and supply columns via
      *   the `className` prop directly (e.g. `className="grid-cols-2"`). Useful
      *   for fixed non-responsive column counts (form field pairs, button rows).
+     *
+     * 🛑 A `grid-cols-*` className BEATS `cols`. appkit's dist/styles.css is
+     * unlayered and both tailwind configs set `important: true`, so a Tailwind
+     * utility in `@layer utilities` outranks the preset's own rule. Passing both
+     * silently ignores `cols` — pass one or the other, never both.
      */
     cols?: GridCols;
     /** Space between grid cells. Defaults to `"md"` (`gap-4`). */

package/dist/ui/components/Layout.js

@@ -77,6 +77,13 @@ const CONTAINER_MAP = {
     /** `max-w-[1920px]` — ultra-wide / 4K displays */
     ultra: "appkit-container--ultra",
 };
+/**
+ * The canonical card ladder, and its wide-floor variant. Named because several
+ * `GRID_MAP` keys are deliberate aliases of them — see the `@deprecated`
+ * entries below.
+ */
+const CARDS_LADDER = "appkit-grid appkit-grid--cards";
+const CARDS_WIDE_LADDER = `${CARDS_LADDER} appkit-grid--cards-wide`;
 /**
  * Responsive grid column presets.
  * Mirrors THEME_CONSTANTS.grid in the host app.
@@ -95,26 +102,30 @@ export const GRID_MAP = {
     /** 2 → 3 → 4 → 5 → 6 */
     6: "appkit-grid appkit-grid--6",
     /**
-     * Generic card grid — 1 col on portrait mobile → 5 on ultrawide.
-     * Starts at 1 so product cards are readable even on 320 px handsets.
+     * THE canonical card grid — use this for every listing surface.
+     * 1 column on phones → 2 from md → auto-fill (3 at lg, 4 at xl) above,
+     * so the column count follows the grid's own width rather than the
+     * viewport's. See the "Canonical card grid" block in Layout.style.css.
      */
-    cards: "appkit-grid appkit-grid--cards",
-    /** Auto-fill product cards — min 200 px */
-    productCards: "appkit-grid appkit-grid--product-cards",
-    /** Auto-fill product cards (compact) — min 220 px */
-    productCardsCompact: "appkit-grid appkit-grid--product-cards-compact",
-    /** Auto-fill store cards — min 220 px */
-    storeCards: "appkit-grid appkit-grid--store-cards",
-    /** Auto-fill category tiles — min 130 px */
-    categoryCards: "appkit-grid appkit-grid--category-cards",
-    /** Auto-fill coupon/promo cards — min 264 px */
-    couponCards: "appkit-grid appkit-grid--coupon-cards",
-    /** Auto-fill address / wide cards — min 300 px */
-    addressCards: "appkit-grid appkit-grid--address-cards",
-    /** Auto-fill KPI/stat tiles — min 180 px */
-    statTiles: "appkit-grid appkit-grid--stat-tiles",
-    /** Auto-fill account nav tiles — min 160 px */
-    navTiles: "appkit-grid appkit-grid--nav-tiles",
+    cards: CARDS_LADDER,
+    /** Card ladder at a 300 px floor — wide cards (addresses, coupons). */
+    cardsWide: CARDS_WIDE_LADDER,
+    /** @deprecated alias of `cards` — kept so existing callers keep compiling. */
+    productCards: CARDS_LADDER,
+    /** @deprecated alias of `cards` */
+    productCardsCompact: CARDS_LADDER,
+    /** @deprecated alias of `cards` */
+    storeCards: CARDS_LADDER,
+    /** Card ladder at a 130 px floor — category tiles. */
+    categoryCards: `${CARDS_LADDER} appkit-grid--cards-tile`,
+    /** @deprecated alias of `cardsWide` */
+    couponCards: CARDS_WIDE_LADDER,
+    /** @deprecated alias of `cardsWide` */
+    addressCards: CARDS_WIDE_LADDER,
+    /** Card ladder at a 180 px floor — KPI/stat tiles. */
+    statTiles: `${CARDS_LADDER} appkit-grid--cards-stat`,
+    /** Card ladder at a 160 px floor — account nav tiles. */
+    navTiles: `${CARDS_LADDER} appkit-grid--cards-nav`,
     /** Equal halves on md+ */
     halves: "appkit-grid appkit-grid--halves",
     /** 2fr / 1fr split on md+ */

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

@@ -110,15 +110,16 @@
 .appkit-grid--4 { grid-template-columns: repeat(1, minmax(0, 1fr)); }
 .appkit-grid--5 { grid-template-columns: repeat(1, minmax(0, 1fr)); }
 .appkit-grid--6 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
-.appkit-grid--cards { grid-template-columns: repeat(1, minmax(0, 1fr)); }
-.appkit-grid--product-cards { grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1.5rem; }
-.appkit-grid--product-cards-compact { grid-template-columns: repeat(auto-fill, minmax(var(--appkit-grid-min-card), 1fr)); gap: 1rem; }
-.appkit-grid--store-cards { grid-template-columns: repeat(auto-fill, minmax(var(--appkit-grid-min-card), 1fr)); gap: 1.5rem; }
-.appkit-grid--category-cards { grid-template-columns: repeat(auto-fill, minmax(var(--appkit-grid-min-card-xs), 1fr)); gap: 1rem; }
-.appkit-grid--coupon-cards { grid-template-columns: repeat(auto-fill, minmax(264px, 1fr)); gap: 1.5rem; }
-.appkit-grid--address-cards { grid-template-columns: repeat(auto-fill, minmax(var(--appkit-grid-min-card-lg), 1fr)); gap: 1rem; }
-.appkit-grid--stat-tiles { grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 1rem; }
-.appkit-grid--nav-tiles { grid-template-columns: repeat(auto-fill, minmax(var(--appkit-grid-min-card-sm), 1fr)); gap: 1rem; }
+/* .appkit-grid--cards and its density modifiers live in the "Canonical card
+   grid" block at the end of this file — they are a three-step ladder, not a
+   one-liner, and the flat rules that used to sit here (--product-cards,
+   --product-cards-compact, --store-cards, --coupon-cards, --address-cards,
+   --category-cards, --stat-tiles, --nav-tiles) are now GRID_MAP aliases of it.
+
+   Their hardcoded `gap` went with them deliberately: it sat AFTER
+   .appkit-gap--md at equal specificity in this same unlayered file, so it
+   silently beat the `gap` prop. Density belongs in the minmax() floor, not in
+   a gap the caller thinks they control. */
 .appkit-grid--halves { grid-template-columns: repeat(1, minmax(0, 1fr)); }
 .appkit-grid--two-third { grid-template-columns: repeat(1, minmax(0, 1fr)); }
 .appkit-grid--one-third { grid-template-columns: repeat(1, minmax(0, 1fr)); }
@@ -154,8 +155,7 @@
   .appkit-grid--2,
   .appkit-grid--3,
   .appkit-grid--4,
-  .appkit-grid--5,
-  .appkit-grid--cards {
+  .appkit-grid--5 {
     grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 
@@ -165,8 +165,7 @@
 }
 
 @media (min-width: 768px) {
-  .appkit-grid--5,
-  .appkit-grid--cards {
+  .appkit-grid--5 {
     grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 
@@ -190,8 +189,7 @@
 @media (min-width: 1024px) {
   .appkit-grid--3,
   .appkit-grid--4,
-  .appkit-grid--5,
-  .appkit-grid--cards {
+  .appkit-grid--5 {
     grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 
@@ -238,8 +236,7 @@
   }
 
   .appkit-grid--4,
-  .appkit-grid--5,
-  .appkit-grid--cards {
+  .appkit-grid--5 {
     grid-template-columns: repeat(5, minmax(0, 1fr));
   }
 
@@ -252,6 +249,68 @@
   }
 }
 
+/* === Canonical card grid ===================================================
+   ONE ladder for every "cards laid out in a grid" surface — product, store,
+   event, blog, coupon, review, address, category tile, KPI tile, and the
+   admin/seller card views:
+
+     base       1 column   — the card takes the whole content width
+     >= 768px   2 columns
+     >= 1024px  repeat(auto-fill, minmax(--appkit-grid-cards-min, 1fr))
+
+   🛑 `auto-fill`, NEVER `auto-fit`. `auto-fit` collapses the empty tracks in a
+   short final row and lets `1fr` absorb the freed space, so a row holding a
+   single leftover card stretches it across the entire container. `auto-fill`
+   keeps the empty tracks at their computed size, so the lone card in the last
+   row is exactly as wide as its siblings in the row above. That is the whole
+   reason the >=1024px tier is auto-fill rather than a fixed column count — do
+   not "optimise" it to auto-fit.
+
+   auto-fill resolves against the GRID's own content box, not the viewport, so
+   this one class self-corrects inside ListingLayout's desktop filter sidebar
+   (15/16/18rem at lg/xl/2xl — .appkit-listing-layout__content is
+   `flex:1; min-width:0`) and inside the dashboard content rail. No
+   sidebar-aware breakpoints and no container queries are needed. The 1->2 step
+   stays viewport-based on purpose: a phone gets one card whatever its
+   container says.
+
+   Column counts for the default 260px floor:
+     lg  (1024px vp -> 960px content)              -> 3
+     xl+ (max-w-screen-xl caps content at 1216px)  -> 4
+   i.e. "3 or 4 based on the available width" on every public page. Dashboards
+   are capped by max-w-screen-2xl instead and reach 5 on an ultrawide monitor —
+   a wider container genuinely earning another column, at ~275px per card.
+
+   🛑 CASCADE: appkit's dist/styles.css is UNLAYERED and both tailwind configs
+   set `important: true`, so a `.lg\:grid-cols-4` utility in @layer utilities
+   BEATS these rules. A call site using cols="cards" must NOT also carry a
+   grid-cols-* className — it would silently win and this ladder would do
+   nothing. scripts/audit-card-grid-cols.mjs enforces that. */
+
+.appkit-grid--cards {
+  --appkit-grid-cards-min: var(--appkit-grid-min-card);
+  grid-template-columns: repeat(1, minmax(0, 1fr));
+}
+
+/* Density modifiers — each overrides ONLY the local floor; the ladder above is
+   shared, so every card grid changes shape together. */
+.appkit-grid--cards-wide { --appkit-grid-cards-min: var(--appkit-grid-min-card-lg); }
+.appkit-grid--cards-stat { --appkit-grid-cards-min: 180px; }
+.appkit-grid--cards-nav  { --appkit-grid-cards-min: var(--appkit-grid-min-card-sm); }
+.appkit-grid--cards-tile { --appkit-grid-cards-min: var(--appkit-grid-min-card-xs); }
+
+@media (min-width: 768px) {
+  .appkit-grid--cards {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 1024px) {
+  .appkit-grid--cards {
+    grid-template-columns: repeat(auto-fill, minmax(var(--appkit-grid-cards-min), 1fr));
+  }
+}
+
 /* Variant catalogue: divider primitives for Stack/Row. `divide` prop emits a
    themed border-on-children rule that respects the active theme via CSS vars. */
 .appkit-stack--divide > * + * { border-top: 1px solid var(--appkit-color-border); padding-top: var(--appkit-space-3); }

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

@@ -28,6 +28,8 @@ export interface ListingLayoutLabels {
     showFilters?: string;
     hideFilters?: string;
     filterActiveCount?: (count: number) => string;
+    /** Noun in the mobile toolbar's "Show/Hide …" collapse strip. */
+    toolbarLabel?: string;
 }
 export interface ListingLayoutProps {
     headerSlot?: ReactNode;

package/dist/ui/components/ListingLayout.js

@@ -21,6 +21,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 { usePathname } from "next/navigation";
+import { CollapseStrip, useToolbarCollapse } from "./toolbar-collapse";
 import { useBottomChromeSlot } from "./bottom-chrome-slot";
 import { Aside, Nav } from "./Semantic";
 import { Text, Span } from "./Typography";
@@ -36,6 +38,7 @@ const DEFAULT_LABELS = {
     showFilters: "Show filters",
     hideFilters: "Hide filters",
     filterActiveCount: (count) => `${count} active`,
+    toolbarLabel: "Toolbar",
 };
 export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filterActiveCount = 0, onFilterApply, onFilterClear, filterTitle, activeFiltersSlot, resultCountSlot, searchSlot, sortSlot, viewToggleSlot, actionsSlot, selectedCount = 0, onClearSelection, bulkActionItems, toolbarPaginationSlot, paginationSlot, children, isDashboard, defaultSidebarOpen = false, filterPendingCount, className = "", errorSlot, labels, portal, overlays, detailView, }) {
     // useState must run unconditionally on every render — these were
@@ -54,6 +57,17 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
     // Portal-derived isDashboard default (folded from ListingViewShell)
     const effectiveIsDashboard = isDashboard ?? (portal === "admin" || portal === "seller");
     const l = { ...DEFAULT_LABELS, ...labels };
+    /* The mobile toolbar is two stacked rows — search + Filter, then a scrolling
+       sort/view/actions chip row — roughly 100px of chrome above the first card.
+       It opens collapsed below `lg` and stays as the user left it thereafter.
+       `forceExpanded` on a selection is load-bearing: the bulk-action bar renders
+       INSIDE this toolbar, so a collapsed one would leave the user no way to act
+       on rows they had just selected. */
+    const toolbarPathname = usePathname();
+    const { collapsed: mobileToolbarCollapsed, toggle: toggleMobileToolbar } = useToolbarCollapse({
+        id: `listing-layout${toolbarPathname ? `:${toolbarPathname}` : ""}`,
+        forceExpanded: selectedCount > 0,
+    });
     const hasFilter = Boolean(filterContent);
     const panelTitle = filterTitle ?? l.filtersTitle;
     const handleMobileApply = () => {
@@ -78,12 +92,12 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
                 ].join(" "), children: [_jsxs(Div, { className: "appkit-listing-layout__toolbar-row appkit-listing-layout__toolbar-row--desktop", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setSidebarOpen((prev) => !prev), "aria-label": sidebarOpen ? l.hideFilters : l.showFilters, "aria-expanded": sidebarOpen, className: [
                                     "appkit-listing-layout__filter-btn",
                                     sidebarOpen ? "appkit-listing-layout__filter-btn--active" : "",
-                                ].join(" "), children: [_jsx(FilterIcon, {}), l.filtersTitle, filterActiveCount > 0 && (_jsx(Span, { className: "appkit-listing-layout__filter-badge", "aria-label": l.filterActiveCount(filterActiveCount), children: filterActiveCount }))] })), searchSlot && (_jsx(Div, { className: "appkit-listing-layout__search", children: searchSlot })), _jsxs(Div, { className: "appkit-listing-layout__toolbar-actions", children: [sortSlot, viewToggleSlot && (_jsx(Div, { className: "appkit-listing-layout__view-toggle-wrap", children: viewToggleSlot })), actionsSlot] }), toolbarPaginationSlot && (_jsx(Div, { className: "appkit-listing-layout__toolbar-pagination", children: toolbarPaginationSlot }))] }), _jsxs(Div, { className: "appkit-listing-layout__toolbar-row appkit-listing-layout__toolbar-row--mobile", children: [_jsxs(Div, { className: "appkit-listing-layout__mobile-row-1", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setMobileFilterOpen(true), "aria-label": l.filtersTitle, className: [
+                                ].join(" "), children: [_jsx(FilterIcon, {}), l.filtersTitle, filterActiveCount > 0 && (_jsx(Span, { className: "appkit-listing-layout__filter-badge", "aria-label": l.filterActiveCount(filterActiveCount), children: filterActiveCount }))] })), searchSlot && (_jsx(Div, { className: "appkit-listing-layout__search", children: searchSlot })), _jsxs(Div, { className: "appkit-listing-layout__toolbar-actions", children: [sortSlot, viewToggleSlot && (_jsx(Div, { className: "appkit-listing-layout__view-toggle-wrap", children: viewToggleSlot })), actionsSlot] }), toolbarPaginationSlot && (_jsx(Div, { className: "appkit-listing-layout__toolbar-pagination", children: toolbarPaginationSlot }))] }), !mobileToolbarCollapsed && (_jsxs(Div, { className: "appkit-listing-layout__toolbar-row appkit-listing-layout__toolbar-row--mobile", children: [_jsxs(Div, { className: "appkit-listing-layout__mobile-row-1", children: [hasFilter && (_jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setMobileFilterOpen(true), "aria-label": l.filtersTitle, className: [
                                             "appkit-listing-layout__filter-btn",
                                             filterActiveCount > 0
                                                 ? "appkit-listing-layout__filter-btn--active"
                                                 : "",
-                                        ].join(" "), children: [_jsx(FilterIcon, {}), l.filtersTitle, filterActiveCount > 0 && (_jsx(Span, { className: "appkit-listing-layout__filter-badge", "aria-label": l.filterActiveCount(filterActiveCount), children: filterActiveCount }))] })), searchSlot && (_jsx(Div, { className: "appkit-listing-layout__search", children: searchSlot }))] }), (sortSlot || viewToggleSlot || actionsSlot) && (_jsx(Div, { className: "appkit-listing-layout__mobile-row-2", children: _jsxs(Div, { className: "appkit-listing-layout__mobile-row-2__inner", children: [sortSlot, viewToggleSlot, actionsSlot] }) }))] }), selectedCount > 0 && (_jsx(Div, { className: "appkit-listing-layout__bulk-bar", children: _jsx(BulkActionBar, { selectedCount: selectedCount, onClearSelection: onClearSelection, actions: bulkActionItems, labels: {
+                                        ].join(" "), children: [_jsx(FilterIcon, {}), l.filtersTitle, filterActiveCount > 0 && (_jsx(Span, { className: "appkit-listing-layout__filter-badge", "aria-label": l.filterActiveCount(filterActiveCount), children: filterActiveCount }))] })), searchSlot && (_jsx(Div, { className: "appkit-listing-layout__search", children: searchSlot }))] }), (sortSlot || viewToggleSlot || actionsSlot) && (_jsx(Div, { className: "appkit-listing-layout__mobile-row-2", children: _jsxs(Div, { className: "appkit-listing-layout__mobile-row-2__inner", children: [sortSlot, viewToggleSlot, actionsSlot] }) }))] })), selectedCount === 0 && (_jsx(CollapseStrip, { collapsed: mobileToolbarCollapsed, label: l.toolbarLabel, onToggle: toggleMobileToolbar, className: "lg:hidden" })), selectedCount > 0 && (_jsx(Div, { className: "appkit-listing-layout__bulk-bar", children: _jsx(BulkActionBar, { selectedCount: selectedCount, onClearSelection: onClearSelection, actions: bulkActionItems, labels: {
                                 selected: l.filtersTitle, // placeholder — callers provide proper labels
                                 apply: l.applyFilters,
                                 clearSelection: l.clearAll,

package/dist/ui/components/StickyToolbar.js

@@ -1,8 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
-import { ChevronDown } from "lucide-react";
-import { normalizeError } from "../../errors/normalize";
+import { useEffect, useRef } from "react";
+import { CollapseStrip, useToolbarCollapse } from "./toolbar-collapse";
 const TONE_CLS = {
     default: "bg-[var(--appkit-color-surface)]",
     muted: "bg-[var(--appkit-color-bg)]",
@@ -54,47 +53,9 @@ function resolveOffsetClass(offset) {
  * 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")
-        return false;
-    try {
-        return window.sessionStorage.getItem(STORAGE_PREFIX + id) === "1";
-    }
-    catch (_err) {
-        void normalizeError(_err);
-        return false;
-    }
-}
-function writeCollapsed(id, value) {
-    try {
-        if (value)
-            window.sessionStorage.setItem(STORAGE_PREFIX + id, "1");
-        else
-            window.sessionStorage.removeItem(STORAGE_PREFIX + id);
-    }
-    catch (_err) {
-        void normalizeError(_err);
-        // sessionStorage unavailable (private browsing, etc.) — collapse still
-        // 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 { collapsed, toggle } = useToolbarCollapse({ id, enabled: dismissible });
     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
@@ -122,12 +83,6 @@ export function StickyToolbar({ children, offset = "header", tone = "translucent
     const offsetStyle = typeof offset === "number" ? { top: `${offset}px` } : undefined;
     const borderCls = border ? "border-b border-[var(--appkit-color-border)]" : "";
     const zCls = z === "above-toolbar" ? "z-20" : z === "above-content" ? "z-10" : "z-[5]";
-    const toggle = () => {
-        const next = !collapsed;
-        setCollapsed(next);
-        if (id)
-            writeCollapsed(id, next);
-    };
     if (dismissible && id && collapsed) {
         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 }) }));
     }

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

@@ -0,0 +1,44 @@
+/**
+ * Tri-state on purpose: `null` means "the user has never chosen", which is
+ * what lets the viewport supply the default. A plain boolean cannot express
+ * the difference between "they expanded it" and "they have not touched it".
+ */
+export declare function readCollapsedPref(id: string): boolean | null;
+/**
+ * Writes `"0"` for expanded rather than removing the key. Removing it would
+ * leave no stored preference, so on mobile the viewport default would collapse
+ * the toolbar again on the next navigation and the user's choice would read as
+ * not having stuck.
+ */
+export declare function writeCollapsedPref(id: string, value: boolean): void;
+export declare function defaultCollapsedForViewport(): boolean;
+export interface UseToolbarCollapseOptions {
+    /** Stable id — the sessionStorage key. Collapse is disabled without one. */
+    id?: string;
+    /** Set false to opt out entirely (the toolbar is always expanded). */
+    enabled?: boolean;
+    /**
+     * Force the expanded state regardless of preference. Used when the toolbar
+     * holds controls the user cannot reach any other way — `ListingLayout` keeps
+     * it open while rows are selected, since the bulk-action bar renders inside
+     * the toolbar and a collapsed one would leave no way to act on a selection.
+     */
+    forceExpanded?: boolean;
+}
+export interface UseToolbarCollapseResult {
+    collapsed: boolean;
+    toggle: () => void;
+}
+export declare function useToolbarCollapse({ id, enabled, forceExpanded, }: UseToolbarCollapseOptions): UseToolbarCollapseResult;
+/**
+ * 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).
+ */
+export declare function CollapseStrip({ collapsed, label, onToggle, className, }: {
+    collapsed: boolean;
+    label: string;
+    onToggle: () => void;
+    className?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// appkit/src/ui/components/toolbar-collapse.tsx
+import { useCallback, useEffect, useState } from "react";
+import { ChevronDown } from "lucide-react";
+import { normalizeError } from "../../errors/normalize";
+/**
+ * The collapse mechanism shared by `<StickyToolbar dismissible>` and
+ * `<ListingLayout>`'s own mobile toolbar rows.
+ *
+ * It lives here rather than in either component because there are two
+ * unrelated toolbars on listing surfaces — the `StickyToolbar` that
+ * `ListingToolbar`/`DataListingView` mount, and `ListingLayout`'s hand-rolled
+ * `.appkit-listing-layout__toolbar` — and a second copy of "is it collapsed,
+ * and where is that remembered" would drift the first time one of them
+ * changed. One implementation, one sessionStorage key space.
+ */
+const STORAGE_PREFIX = "appkit:sticky-toolbar-collapsed:";
+/** Below this the toolbar defaults to collapsed. Matches the `lg` boundary
+ *  that both toolbars already use to switch between their mobile and desktop
+ *  rows, so the default flips at the same width the layout does. */
+const MOBILE_QUERY = "(max-width: 1023px)";
+/**
+ * Tri-state on purpose: `null` means "the user has never chosen", which is
+ * what lets the viewport supply the default. A plain boolean cannot express
+ * the difference between "they expanded it" and "they have not touched it".
+ */
+export function readCollapsedPref(id) {
+    if (typeof window === "undefined")
+        return null;
+    try {
+        const raw = window.sessionStorage.getItem(STORAGE_PREFIX + id);
+        if (raw === null)
+            return null;
+        return raw === "1";
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        return null;
+    }
+}
+/**
+ * Writes `"0"` for expanded rather than removing the key. Removing it would
+ * leave no stored preference, so on mobile the viewport default would collapse
+ * the toolbar again on the next navigation and the user's choice would read as
+ * not having stuck.
+ */
+export function writeCollapsedPref(id, value) {
+    try {
+        window.sessionStorage.setItem(STORAGE_PREFIX + id, value ? "1" : "0");
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        // sessionStorage unavailable (private browsing, etc.) — collapsing still
+        // works for the current render, it just doesn't survive a re-mount.
+    }
+}
+export function defaultCollapsedForViewport() {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+        return false;
+    }
+    return window.matchMedia(MOBILE_QUERY).matches;
+}
+export function useToolbarCollapse({ id, enabled = true, forceExpanded = false, }) {
+    // Always starts expanded so the server and the first client render agree;
+    // the effect below corrects it after mount. Reading sessionStorage or
+    // matchMedia in the initialiser would be a hydration mismatch.
+    const [collapsed, setCollapsed] = useState(false);
+    useEffect(() => {
+        if (!enabled || !id)
+            return;
+        const stored = readCollapsedPref(id);
+        setCollapsed(stored ?? defaultCollapsedForViewport());
+    }, [enabled, id]);
+    const toggle = useCallback(() => {
+        setCollapsed((prev) => {
+            const next = !prev;
+            if (id)
+                writeCollapsedPref(id, next);
+            return next;
+        });
+    }, [id]);
+    return { collapsed: enabled && !forceExpanded ? collapsed : false, toggle };
+}
+/**
+ * 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).
+ */
+export 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] }) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.30.16",
+  "version": "4.30.17",
   "license": "MIT",
   "publishConfig": {
     "access": "public"