@mohasinac/appkit 4.47.0 → 4.48.0

package/dist/tokens/themes/sunset.js

@@ -24,6 +24,23 @@ export const SUNSET_THEME = {
         "appkit-color-primary": "#f59e0b",
         "appkit-color-primary-500": "#f59e0b",
         "appkit-color-primary-600": "#d97706",
+        /*
+         * 🛑 D7 — DARK ink on this primary, declared rather than inherited.
+         *
+         * The light base's `text-on-primary` is `#ffffff`, and white on amber
+         * `#f59e0b` measures **2.15:1** — under the 3:1 AA threshold for
+         * large/UI text, so every primary button, badge and pill in this theme was
+         * unreadable. It survived because the pair was INHERITED: `audit-a11y`
+         * treated a token this theme does not declare as "nothing to check", which
+         * is exactly the pairing a brand theme is most likely to break (a new
+         * brand colour under somebody else's ink).
+         *
+         * `#431407` is this theme's own `text` token, so the fix introduces no new
+         * colour: **7.29:1** on `primary` and **4.91:1** on `primary-600`, which is
+         * the darker shade a hover state uses — both clear AA for normal text, not
+         * just the 3:1 this pair is held to.
+         */
+        "appkit-color-text-on-primary": "#431407",
         "appkit-color-secondary": "#f43f5e",
         "appkit-color-secondary-500": "#f43f5e",
         "appkit-color-bg": "#fff7ed",

package/dist/tokens/tokens.css

@@ -608,6 +608,11 @@
   --appkit-color-text:             #431407;    /* orange-950 */
   --appkit-color-text-muted:       #9a3412;    /* orange-800 */
   --appkit-color-text-faint:       #c2410c;    /* orange-700 */
+  /* D7: dark ink on the amber primary. Inherited white measured 2.15:1 and
+     failed AA for UI text; orange-950 is 7.29:1 on primary and 4.91:1 on
+     primary-600. Declared in BOTH places or the first paint disagrees with
+     the hydrated theme (audit-theme-drift). */
+  --appkit-color-text-on-primary:  #431407;
 
   --appkit-color-success:          #15803d;
   --appkit-color-success-surface:  #f0fdf4;

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

@@ -8,8 +8,15 @@ export interface BreadcrumbItem {
     label: string;
     href?: string;
 }
+export type BreadcrumbTone = "default" | "on-media";
 export interface BreadcrumbProps {
     items: BreadcrumbItem[];
     className?: string;
+    /**
+     * `"on-media"` for a trail drawn over a cover photo — fixed white ink on the
+     * scrim, in both themes. See the tone block in `Breadcrumb.style.css` for why
+     * it is not a theme token.
+     */
+    tone?: BreadcrumbTone;
 }
-export declare function Breadcrumb({ items, className }: BreadcrumbProps): import("react").JSX.Element;
+export declare function Breadcrumb({ items, className, tone }: BreadcrumbProps): import("react").JSX.Element;

package/dist/ui/components/Breadcrumb.js

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

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

@@ -58,3 +58,40 @@
 .dark .appkit-breadcrumb__link:hover {
   color: var(--appkit-color-primary-400);
 }
+
+/*
+ * ── tone="on-media" ─────────────────────────────────────────────────────────
+ *
+ * A trail rendered ON a cover photo. The category hero does exactly this, and
+ * before this tone existed that page hand-rolled its own `<Nav>` with
+ * `text-white/70` conditionals purely to stay readable — which is why the
+ * shared component had no caller there, and why its visible trail (three
+ * crumbs) disagreed with its own JSON-LD (eight).
+ *
+ * 🛑 Fixed white rather than a theme token, deliberately. The backdrop is a
+ * photograph with a dark scrim over it in BOTH themes, so a theme-inverting
+ * token would be invisible in one of them — the trap Root Cause #67 is about.
+ * An alpha on white is the spelling that rule prescribes for a control on a
+ * fixed dark scrim.
+ */
+.appkit-breadcrumb--on-media .appkit-breadcrumb__list,
+.appkit-breadcrumb--on-media .appkit-breadcrumb__text,
+.dark .appkit-breadcrumb--on-media .appkit-breadcrumb__list,
+.dark .appkit-breadcrumb--on-media .appkit-breadcrumb__text {
+  color: rgb(255 255 255 / 0.7);
+}
+
+.appkit-breadcrumb--on-media .appkit-breadcrumb__separator,
+.dark .appkit-breadcrumb--on-media .appkit-breadcrumb__separator {
+  color: rgb(255 255 255 / 0.4);
+}
+
+.appkit-breadcrumb--on-media .appkit-breadcrumb__current,
+.dark .appkit-breadcrumb--on-media .appkit-breadcrumb__current {
+  color: rgb(255 255 255);
+}
+
+.appkit-breadcrumb--on-media .appkit-breadcrumb__link:hover,
+.dark .appkit-breadcrumb--on-media .appkit-breadcrumb__link:hover {
+  color: rgb(255 255 255);
+}

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

@@ -54,7 +54,17 @@ export interface SummaryProps {
     align?: SummaryAlign;
     /** Main-axis distribution — takes effect when `layout` is set. */
     justify?: SummaryJustify;
+    /**
+     * Accessible name for the disclosure control.
+     *
+     * A summary whose visible label is a shorthand ("… 3 more") reads as nothing
+     * useful to a screen reader, and the alternative — padding the visible label
+     * — costs the horizontal space the collapse exists to save. A prop rather
+     * than a caller's raw attribute, because a raw `aria-label` on a primitive is
+     * the className escape hatch by another name (Rule #21).
+     */
+    ariaLabel?: string;
 }
 export declare function Details({ children, defaultOpen, open, onToggle, tone, padding, rounded, name, className, style, }: DetailsProps): import("react").JSX.Element;
-export declare function Summary({ children, className, size, weight, paddingX, paddingY, color, layout, align, justify }: SummaryProps): import("react").JSX.Element;
+export declare function Summary({ children, className, size, weight, paddingX, paddingY, color, layout, align, justify, ariaLabel }: SummaryProps): import("react").JSX.Element;
 export {};

package/dist/ui/components/Details.js

@@ -75,8 +75,8 @@ export function Details({ children, defaultOpen, open, onToggle, tone = "default
             className ?? "",
         ].filter(Boolean).join(" ") || undefined, style: style, children: children }));
 }
-export function Summary({ children, className, size, weight, paddingX, paddingY, color, layout, align, justify }) {
-    return (_jsx("summary", { className: [
+export function Summary({ children, className, size, weight, paddingX, paddingY, color, layout, align, justify, ariaLabel }) {
+    return (_jsx("summary", { "aria-label": ariaLabel, className: [
             "cursor-pointer select-none font-medium text-[var(--appkit-color-text)] list-none [&::-webkit-details-marker]:hidden focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--appkit-color-focus-ring)] rounded",
             size ? SUMMARY_SIZE_MAP[size] : "",
             weight ? SUMMARY_WEIGHT_MAP[weight] : "",

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

@@ -0,0 +1,43 @@
+import React from "react";
+/** Below this there is nothing to arrange, so the caller should render nothing. */
+export declare const MOSAIC_MIN = 3;
+export interface ImageMosaicProps {
+    /** Image URLs, most important first. Fewer than `MOSAIC_MIN` renders null. */
+    images: readonly string[];
+    /** Describes the SUBJECT, not the images — one alt for a decorative group. */
+    alt: string;
+    className?: string;
+}
+/**
+ * D3 — a mosaic of a collection's own images, for a hero that has no cover
+ * photo of its own.
+ *
+ * ## 🛑 Why this exists and what it replaces
+ *
+ * A category with no `display.coverImage` rendered a flat
+ * `bg-[var(--appkit-color-bg)]` band behind its title — the same empty strip on
+ * every one of the ~1,100 categories that has no photographer. The images were
+ * already on the page (the product grid below it), so the hero was blank beside
+ * a screen full of pictures.
+ *
+ * ## 🛑 It is DECORATIVE, and that decides three things
+ *
+ * 1. **One `alt` for the group, describing the subject** — "Beyblade Burst
+ *    parts", not five filenames. Five alts for five thumbnails of the same
+ *    subject is noise to a screen reader, and `alt=""` on each would leave the
+ *    band unlabelled entirely.
+ * 2. **`aria-hidden` is NOT used**, because the group does carry meaning: it is
+ *    what this category looks like. Hidden decoration plus a labelled group are
+ *    different claims and the second is true here.
+ * 3. **No links.** Every one of these products is linked in the grid below; a
+ *    second set of hit targets over a title is a tap hazard on a phone and
+ *    gives a crawler duplicate links to the same URLs.
+ *
+ * ## 🛑 Deterministic emphasis, never random
+ *
+ * The first image takes the large cell and the rest fill the small ones in
+ * order. `Math.random()` here would make the hero change on every render, which
+ * breaks SSR/hydration agreement and makes the page feel unstable — and it is
+ * the shape Root Cause #25 is about on the seed side.
+ */
+export declare function ImageMosaic({ images, alt, className }: ImageMosaicProps): React.JSX.Element | null;

package/dist/ui/components/ImageMosaic.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MediaImage } from "../../features/media/MediaImage.js";
+import { Div } from "./Div.js";
+/** How many tiles the mosaic draws. More than five reads as a grid, not a hero. */
+const MOSAIC_MAX = 5;
+/** Below this there is nothing to arrange, so the caller should render nothing. */
+export const MOSAIC_MIN = 3;
+/**
+ * D3 — a mosaic of a collection's own images, for a hero that has no cover
+ * photo of its own.
+ *
+ * ## 🛑 Why this exists and what it replaces
+ *
+ * A category with no `display.coverImage` rendered a flat
+ * `bg-[var(--appkit-color-bg)]` band behind its title — the same empty strip on
+ * every one of the ~1,100 categories that has no photographer. The images were
+ * already on the page (the product grid below it), so the hero was blank beside
+ * a screen full of pictures.
+ *
+ * ## 🛑 It is DECORATIVE, and that decides three things
+ *
+ * 1. **One `alt` for the group, describing the subject** — "Beyblade Burst
+ *    parts", not five filenames. Five alts for five thumbnails of the same
+ *    subject is noise to a screen reader, and `alt=""` on each would leave the
+ *    band unlabelled entirely.
+ * 2. **`aria-hidden` is NOT used**, because the group does carry meaning: it is
+ *    what this category looks like. Hidden decoration plus a labelled group are
+ *    different claims and the second is true here.
+ * 3. **No links.** Every one of these products is linked in the grid below; a
+ *    second set of hit targets over a title is a tap hazard on a phone and
+ *    gives a crawler duplicate links to the same URLs.
+ *
+ * ## 🛑 Deterministic emphasis, never random
+ *
+ * The first image takes the large cell and the rest fill the small ones in
+ * order. `Math.random()` here would make the hero change on every render, which
+ * breaks SSR/hydration agreement and makes the page feel unstable — and it is
+ * the shape Root Cause #25 is about on the seed side.
+ */
+export function ImageMosaic({ images, alt, className }) {
+    const tiles = images.filter(Boolean).slice(0, MOSAIC_MAX);
+    if (tiles.length < MOSAIC_MIN)
+        return null;
+    const [lead, ...rest] = tiles;
+    return (_jsxs(Div, { className: `appkit-image-mosaic ${className ?? ""}`, role: "img", "aria-label": alt, children: [_jsx(Div, { className: "appkit-image-mosaic__lead", children: _jsx(MediaImage, { src: lead, alt: "", size: "card" }) }), _jsx(Div, { className: "appkit-image-mosaic__rest", children: rest.map((src, i) => (_jsx(Div, { className: "appkit-image-mosaic__tile", children: _jsx(MediaImage, { src: src, alt: "", size: "thumbnail" }) }, `${src}-${i}`))) })] }));
+}

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

@@ -0,0 +1,69 @@
+/*
+ * D3 — the collection mosaic.
+ *
+ * 🛑 A fixed HEIGHT, not an aspect ratio. This band sits behind a hero title
+ * whose length varies with the category name, and an aspect-ratio box would
+ * change the title's vertical position per category — so the page would jump
+ * around as a visitor moves through the tree. A fixed height per breakpoint is
+ * the one shape that keeps the hero stable.
+ *
+ * 🛑 `overflow: hidden` on the grid and `object-fit: cover` on the images, so a
+ * portrait product photo cannot stretch the band. Every image here is a
+ * thumbnail of unknown aspect ratio; cropping is the only option that does not
+ * distort the subject.
+ */
+.appkit-image-mosaic {
+  display: grid;
+  grid-template-columns: 2fr 1fr;
+  gap: var(--appkit-space-2);
+  height: 180px;
+  overflow: hidden;
+  border-radius: var(--appkit-radius-xl);
+}
+
+@media (min-width: 768px) {
+  .appkit-image-mosaic {
+    height: 260px;
+  }
+}
+
+.appkit-image-mosaic__lead,
+.appkit-image-mosaic__tile {
+  position: relative;
+  overflow: hidden;
+  border-radius: var(--appkit-radius-lg);
+  background: var(--appkit-color-surface);
+}
+
+.appkit-image-mosaic__lead img,
+.appkit-image-mosaic__tile img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.appkit-image-mosaic__rest {
+  display: grid;
+  grid-template-rows: repeat(2, 1fr);
+  gap: var(--appkit-space-2);
+}
+
+/*
+ * The small column holds at most two tiles on a phone — four 60px squares beside
+ * a title is visual noise rather than a preview. The remaining tiles are
+ * dropped by CSS rather than by a second render path, so SSR output is one
+ * shape at every width (no layout shift on hydration).
+ */
+.appkit-image-mosaic__rest .appkit-image-mosaic__tile:nth-child(n + 3) {
+  display: none;
+}
+
+@media (min-width: 768px) {
+  .appkit-image-mosaic__rest {
+    grid-template-rows: repeat(2, 1fr);
+    grid-template-columns: repeat(2, 1fr);
+  }
+  .appkit-image-mosaic__rest .appkit-image-mosaic__tile:nth-child(n + 3) {
+    display: block;
+  }
+}

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

@@ -0,0 +1,34 @@
+export interface SplitTilePane {
+    href: string;
+    label: string;
+    /** A real photo for this pane. Absent panes are never padded with a placeholder. */
+    imageUrl: string;
+    /** A real, already-counted figure — "128 listings", never invented. */
+    countLabel?: string;
+}
+export interface SplitTileProps {
+    left: SplitTilePane;
+    right: SplitTilePane;
+    className?: string;
+}
+/**
+ * D3 — two real options, side by side, each a real photo and a real count.
+ *
+ * ## 🛑 Why exactly two, and why both need a photo
+ *
+ * This exists for the shape a root category with two genuinely distinct
+ * branches has — Beyblade vs Battle Gear under Spinning Tops, Companion
+ * Animals vs Live Plants under Living Collectibles — where "pick one" is a
+ * more honest hero than a uniform grid that treats six branches as
+ * interchangeable. It is NOT a general-purpose N-up component: three or more
+ * options is what the existing sub-category scroller already does, and
+ * `ImageMosaic` is the pattern for "we have no single cover photo but we have
+ * many product photos".
+ *
+ * 🛑 THE CALLER DECIDES WHETHER TO RENDER THIS AT ALL. `SplitTile` takes two
+ * required panes and renders both — it has no "only one pane" fallback and no
+ * placeholder image, because a tile with an invented or missing side is worse
+ * than not showing the pattern. A category with only one photographed branch
+ * falls through to the ordinary sub-category scroller instead.
+ */
+export declare function SplitTile({ left, right, className }: SplitTileProps): import("react").JSX.Element;

package/dist/ui/components/SplitTile.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Anchor } from "./Anchor.js";
+import { Div } from "./Div.js";
+import { Heading, Span } from "./Typography.js";
+import { MediaImage } from "../../features/media/MediaImage.js";
+/**
+ * D3 — two real options, side by side, each a real photo and a real count.
+ *
+ * ## 🛑 Why exactly two, and why both need a photo
+ *
+ * This exists for the shape a root category with two genuinely distinct
+ * branches has — Beyblade vs Battle Gear under Spinning Tops, Companion
+ * Animals vs Live Plants under Living Collectibles — where "pick one" is a
+ * more honest hero than a uniform grid that treats six branches as
+ * interchangeable. It is NOT a general-purpose N-up component: three or more
+ * options is what the existing sub-category scroller already does, and
+ * `ImageMosaic` is the pattern for "we have no single cover photo but we have
+ * many product photos".
+ *
+ * 🛑 THE CALLER DECIDES WHETHER TO RENDER THIS AT ALL. `SplitTile` takes two
+ * required panes and renders both — it has no "only one pane" fallback and no
+ * placeholder image, because a tile with an invented or missing side is worse
+ * than not showing the pattern. A category with only one photographed branch
+ * falls through to the ordinary sub-category scroller instead.
+ */
+export function SplitTile({ left, right, className }) {
+    return (_jsx(Div, { className: `grid grid-cols-1 md:grid-cols-2 gap-[var(--appkit-space-3)] ${className ?? ""}`, children: [left, right].map((pane) => (_jsxs(Anchor, { href: pane.href, underline: "none", className: "group relative block overflow-hidden rounded-xl h-[160px] md:h-[220px]", children: [_jsx(MediaImage, { src: pane.imageUrl, alt: "", size: "banner", className: "absolute inset-0 h-full w-full object-cover transition-transform group-hover:scale-105" }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" }), _jsxs(Div, { className: "absolute inset-0 flex flex-col justify-end p-[var(--appkit-space-4)]", children: [_jsx(Heading, { level: 3, color: "inverse", size: "lg", weight: "bold", children: pane.label }), pane.countLabel && (_jsx(Span, { color: "inverse", size: "xs", className: "mt-[var(--appkit-space-1)] opacity-80", children: pane.countLabel }))] })] }, pane.href))) }));
+}

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

@@ -7,6 +7,7 @@
 @import "./ActionRow.style.css";
 @import "./Accordion.style.css";
 @import "./Breadcrumb.style.css";
+@import "./ImageMosaic.style.css";
 @import "./Badge.style.css";
 @import "./Divider.style.css";
 @import "./TextLink.style.css";

package/dist/ui/index.d.ts

@@ -103,6 +103,10 @@ export type { StarRatingProps } from "./components/StarRating";
 export { StarRating } from "./components/StarRating";
 export type { BreadcrumbProps, BreadcrumbItem } from "./components/Breadcrumb";
 export { Breadcrumb } from "./components/Breadcrumb";
+export { ImageMosaic, MOSAIC_MIN } from "./components/ImageMosaic";
+export type { ImageMosaicProps } from "./components/ImageMosaic";
+export { SplitTile } from "./components/SplitTile";
+export type { SplitTileProps, SplitTilePane } from "./components/SplitTile";
 export type { ImageLightboxProps, LightboxImage, } from "./components/ImageLightbox";
 export { ImageLightbox } from "./components/ImageLightbox";
 export type { TagInputProps } from "./components/TagInput";

package/dist/ui/index.js

@@ -81,6 +81,10 @@ export { QuantityStepper } from "./components/QuantityStepper.js";
 export { ToastProvider, useToast } from "./components/Toast.js";
 export { StarRating } from "./components/StarRating.js";
 export { Breadcrumb } from "./components/Breadcrumb.js";
+/* D3 — the collection mosaic, for a hero with no cover photo of its own. */
+export { ImageMosaic, MOSAIC_MIN } from "./components/ImageMosaic.js";
+/* D3 — two real branches, side by side with real photos and real counts. */
+export { SplitTile } from "./components/SplitTile.js";
 export { ImageLightbox } from "./components/ImageLightbox.js";
 export { TagInput } from "./components/TagInput.js";
 export { StepperNav } from "./components/StepperNav.js";

package/dist/utils/search-txt-query.d.ts

@@ -67,6 +67,69 @@ export declare const SEARCH_REFINE_WINDOW = 250;
  * false last one. Reporting a saturated window as an exact total is the defect
  * above with a bigger number.
  */
+/**
+ * The page fields `beginSearchWindow` overrides.
+ *
+ * Structural rather than importing `SieveModel`, so `utils/` keeps no
+ * dependency on `providers/db-firebase` (`audit-import-cycles`), and NOT
+ * `unknown` — the shapes are the same `number | string` Sieve itself accepts,
+ * and `unknown` here would be a type-level shrug that `audit-unknown-leakage`
+ * correctly refuses.
+ */
+export interface SearchWindowModel {
+    page?: number | string;
+    pageSize?: number | string;
+}
+/**
+ * The three coupled decisions a refined search has to make, in ONE place.
+ *
+ * ## 🛑 Why this exists rather than 13 hand-written copies
+ *
+ * `refineSearchTxt` grew a real-pagination mode, and `products` was the only
+ * caller converted — deliberately, so the other eleven stayed byte-identical.
+ * The conversion is mechanical and has THREE parts that must all happen:
+ *
+ *   1. fetch a bounded WINDOW instead of the requested page;
+ *   2. raise `maxPageSize` to that window, or Sieve clamps the request back to
+ *      its own limit and the window silently becomes a page again — the
+ *      original bug with a larger constant;
+ *   3. pass `{page, pageSize, windowSaturated}` so the refine slices the
+ *      requested page out and reports `truncated`.
+ *
+ * Doing 1 and 3 without 2 reads exactly like a working conversion and is the
+ * half that no-ops. So the three move together here, and a caller cannot have
+ * two of them.
+ *
+ * ```ts
+ * const win = beginSearchWindow(model, plan);
+ * const result = await this.sieveQuery(win.model, FIELDS, {
+ *   baseQuery, defaultPageSize: 20, maxPageSize: win.maxPageSize(100),
+ * });
+ * return win.finish(result);
+ * ```
+ */
+export declare function beginSearchWindow<M extends SearchWindowModel>(model: M, plan: SearchTxtPlan, 
+/**
+ * True when something OTHER than the extra search terms also has to be
+ * refined in memory — a filter Firestore could not express beside the
+ * search clause. Then the window is needed even for a single-term query.
+ */
+opts?: {
+    alsoRefining?: boolean;
+}): {
+    model: M;
+    maxPageSize(normal: number): number;
+    finish<T extends {
+        searchTxt?: string[];
+    }, R extends {
+        items: T[];
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    }>(result: R, also?: (row: T) => boolean): R & {
+        truncated?: boolean;
+    };
+};
 export declare function refineSearchTxt<T extends {
     searchTxt?: string[];
 }, R extends {
@@ -85,6 +148,20 @@ opts?: {
     pageSize: number;
     /** True when the fetch returned a full window, so more may exist. */
     windowSaturated: boolean;
+    /**
+     * One more AND-condition to apply over the same window, for a filter
+     * Firestore could not express alongside the search clause.
+     *
+     * 🛑 It exists so there is ONE refine-and-paginate implementation rather
+     * than a second copy per filter. Firestore permits a single array operator
+     * per query, so when a search and a category filter arrive together the
+     * search takes the clause — and the category then HAS to be refined here
+     * or it is simply not applied (which is exactly what used to happen:
+     * searching inside a category returned matches from the whole catalogue).
+     * The window bookkeeping, the `total`-is-a-floor rule and `truncated` are
+     * identical for both conditions, which is why they share this function.
+     */
+    also?: (row: T) => boolean;
 }): R & {
     truncated?: boolean;
 };

package/dist/utils/search-txt-query.js

@@ -50,38 +50,58 @@ export function emptySearchResult() {
  */
 export const SEARCH_REFINE_WINDOW = 250;
 /**
- * AND-refine the remaining terms, then slice the requested page out.
+ * The three coupled decisions a refined search has to make, in ONE place.
  *
- * ## 🛑 The bug this closes: multi-word search lied about its own totals
+ * ## 🛑 Why this exists rather than 13 hand-written copies
  *
- * This used to filter the ALREADY-PAGINATED page and then set
- * `total = items.length`, `totalPages = 0|1`, `hasMore = false`. Two
- * consequences, both silent:
+ * `refineSearchTxt` grew a real-pagination mode, and `products` was the only
+ * caller converted — deliberately, so the other eleven stayed byte-identical.
+ * The conversion is mechanical and has THREE parts that must all happen:
  *
- *   1. A two-word query could only ever return matches that happened to fall
- *      inside one 50-row window. Rows 51+ that matched both terms were
- *      unreachable — not on page 2, not anywhere, because `hasMore` said there
- *      was no page 2.
- *   2. The pager actively asserted completeness. A search returning 7 of 40
- *      real matches reported "7 results" and disabled Next.
+ *   1. fetch a bounded WINDOW instead of the requested page;
+ *   2. raise `maxPageSize` to that window, or Sieve clamps the request back to
+ *      its own limit and the window silently becomes a page again — the
+ *      original bug with a larger constant;
+ *   3. pass `{page, pageSize, windowSaturated}` so the refine slices the
+ *      requested page out and reports `truncated`.
  *
- * Both render as plausible results with a 200, which is why neither was
- * reported: a search that returns seven relevant rows looks like it worked.
+ * Doing 1 and 3 without 2 reads exactly like a working conversion and is the
+ * half that no-ops. So the three move together here, and a caller cannot have
+ * two of them.
  *
- * ## The fix, and its honest cost
- *
- * The caller over-fetches a bounded WINDOW (`SEARCH_REFINE_WINDOW`), this
- * function refines over it and then slices the requested page. So page 2 of a
- * two-word search exists, and `total` is the refined count over the window
- * rather than over one page.
- *
- * 🛑 `truncated` is NOT optional, and it is the part that keeps this honest.
- * When the window saturated, the refined `total` is a FLOOR, not a total — the
- * same situation the availability queries document — so the renderer must show
- * it as "50+" and `totalPages` must offer one more page rather than claiming a
- * false last one. Reporting a saturated window as an exact total is the defect
- * above with a bigger number.
+ * ```ts
+ * const win = beginSearchWindow(model, plan);
+ * const result = await this.sieveQuery(win.model, FIELDS, {
+ *   baseQuery, defaultPageSize: 20, maxPageSize: win.maxPageSize(100),
+ * });
+ * return win.finish(result);
+ * ```
+ */
+export function beginSearchWindow(model, plan, 
+/**
+ * True when something OTHER than the extra search terms also has to be
+ * refined in memory — a filter Firestore could not express beside the
+ * search clause. Then the window is needed even for a single-term query.
  */
+opts) {
+    const refining = plan.rest.length > 0 || opts?.alsoRefining === true;
+    const page = Math.max(1, Number(model?.page ?? 1) || 1);
+    const pageSize = Math.max(1, Number(model?.pageSize ?? 20) || 20);
+    return {
+        model: refining ? { ...model, page: 1, pageSize: SEARCH_REFINE_WINDOW } : model,
+        maxPageSize: (normal) => (refining ? SEARCH_REFINE_WINDOW : normal),
+        finish: (result, also) => refineSearchTxt(result, plan.rest, refining
+            ? {
+                page,
+                pageSize,
+                // Saturated means more may exist beyond the window, so the
+                // refined `total` is a FLOOR and `truncated` says so.
+                windowSaturated: (result.items?.length ?? 0) >= SEARCH_REFINE_WINDOW,
+                ...(also ? { also } : {}),
+            }
+            : undefined),
+    };
+}
 export function refineSearchTxt(result, rest, 
 /**
  * Supply these to get real pagination. Omitted, the behaviour is the old
@@ -89,9 +109,11 @@ export function refineSearchTxt(result, rest,
  * until each is converted, rather than all of them changing at once.
  */
 opts) {
-    if (rest.length === 0)
+    const also = opts?.also;
+    if (rest.length === 0 && !also)
         return result;
-    const matched = result.items.filter((row) => matchesAllSearchTerms(row.searchTxt, rest));
+    const matched = result.items.filter((row) => (rest.length === 0 || matchesAllSearchTerms(row.searchTxt, rest)) &&
+        (!also || also(row)));
     if (!opts) {
         /*
          * The legacy shape. `total` is this page's count — a floor — and

package/package.json

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