@mohasinac/appkit 4.27.0 → 4.28.0

package/dist/ui/components/tabs-overflow.js

@@ -0,0 +1,142 @@
+"use client";
+/*
+ * WHY: A tab strip that overflows its container needs a visible affordance,
+ *      and a thin scrollbar is not one on a touch device or a trackpad. The
+ *      arrows this hook drives are in-flow flex siblings of the tablist, which
+ *      is what makes the hysteresis below mandatory rather than a nicety.
+ *
+ * WHAT: Measures whether the tab list overflows, whether it is scrolled to
+ *       either end, and exposes a paging scroll. Consumed only by
+ *       <TabBarShell>.
+ *
+ * EXPORTS: useTabsOverflow, TabsOverflowState
+ *
+ * @tag domain:ui
+ * @tag layer:ui
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:TabBarShell
+ * @tag sideEffects:dom-measurement
+ */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+/**
+ * Slack used by the hysteresis rule below, in px. Matches
+ * 2 x --appkit-tabs-arrow-size (2rem) — the width the two in-flow arrows
+ * reclaim from the list when they unmount.
+ */
+const ARROW_SLACK_PX = 64;
+/** Sub-pixel tolerance: scrollWidth/clientWidth can differ by <1px at some zooms. */
+const EPSILON = 1;
+const INITIAL = { hasArrows: false, atStart: true, atEnd: true };
+function sameState(a, b) {
+    return a.hasArrows === b.hasArrows && a.atStart === b.atStart && a.atEnd === b.atEnd;
+}
+/**
+ * Drives the scroll-arrow affordances on a horizontally scrollable tab list.
+ *
+ * `activeKey` identifies the currently-selected tab. It exists solely to key
+ * the scroll-into-view effect, so the strip repositions when the selection
+ * changes and stays put while the user scrolls.
+ */
+export function useTabsOverflow(listRef, activeKey) {
+    // Starts false and can only become true inside an effect, so the server HTML
+    // never contains arrows and always matches the first client render.
+    const [state, setState] = useState(INITIAL);
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    const measure = useCallback(() => {
+        const el = listRef.current;
+        if (!el)
+            return;
+        const overflow = el.scrollWidth - el.clientWidth;
+        const previous = stateRef.current.hasArrows;
+        /*
+         * 🛑 HYSTERESIS — do not collapse this to a single threshold.
+         *
+         * The arrows are IN-FLOW, so mounting them shrinks the list's clientWidth
+         * by ~ARROW_SLACK_PX, which INCREASES the measured overflow. With one
+         * threshold a strip 10px wider than its container oscillates forever:
+         *   hidden -> overflow 10 -> show -> overflow 74 -> still overflowing
+         *   -> ... -> hide -> overflow -54 -> hide -> widen -> overflow 10 -> show
+         *
+         * Once the arrows are up they may only come down if the content would
+         * STILL fit after reclaiming their width, which by construction leaves
+         * overflow <= 0 afterwards. That makes the rule provably stable.
+         */
+        const hasArrows = previous ? overflow > ARROW_SLACK_PX : overflow > EPSILON;
+        const max = el.scrollWidth - el.clientWidth;
+        // Math.abs: scrollLeft is negative (or inverted) in RTL depending on engine.
+        const position = Math.abs(el.scrollLeft);
+        const next = {
+            hasArrows,
+            atStart: position <= EPSILON,
+            atEnd: max <= EPSILON || position >= max - EPSILON,
+        };
+        setState((current) => (sameState(current, next) ? current : next));
+    }, [listRef]);
+    /*
+     * Content width — a badge appearing, a locale swapping every label, a tab
+     * being added. Deliberately dependency-FREE so it runs after every render:
+     * none of those changes is expressible as a dep, and a ResizeObserver on a
+     * scroll container fires only for its own box, never for its content. The
+     * `sameState` guard in `measure` is what makes this safe — it only calls
+     * setState when a value actually changed, so there is no render loop. The
+     * cost is two layout READS per render (no writes, so no forced reflow).
+     */
+    useLayoutEffect(() => {
+        measure();
+    });
+    // Container width: viewport resize, sidebar collapse, drawer open.
+    useEffect(() => {
+        const el = listRef.current;
+        // jsdom does not implement ResizeObserver; appkit/tests/setup.ts stubs it,
+        // but guard anyway so the hook is safe in any non-DOM runtime.
+        if (!el || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => measure());
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [listRef, measure]);
+    // atStart / atEnd. Passive: this listener never calls preventDefault.
+    useEffect(() => {
+        const el = listRef.current;
+        if (!el)
+            return;
+        const onScroll = () => measure();
+        el.addEventListener("scroll", onScroll, { passive: true });
+        return () => el.removeEventListener("scroll", onScroll);
+    }, [listRef, measure]);
+    // A web-font swap changes every label's width after first paint; without
+    // this the initial measurement is taken against the fallback font.
+    useEffect(() => {
+        let cancelled = false;
+        const fonts = document.fonts;
+        fonts?.ready?.then(() => {
+            if (!cancelled)
+                measure();
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [measure]);
+    /*
+     * Keep the selected tab reachable when it starts off-screen in the strip.
+     * Keyed on `activeKey` and NOT run every render — an
+     * unconditional scrollIntoView would yank the strip back while the user is
+     * mid-scroll, fighting their own input.
+     */
+    useEffect(() => {
+        const active = listRef.current?.querySelector('[aria-selected="true"]');
+        // `block: "nearest"` is essential — the default "start" scrolls the whole
+        // PAGE vertically whenever a tab bar sits below the fold.
+        active?.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+    }, [listRef, activeKey]);
+    const scrollByPage = useCallback((direction) => {
+        const el = listRef.current;
+        // Smoothness comes from `scroll-behavior: smooth` in Tabs.style.css,
+        // which already has a prefers-reduced-motion override — no JS branch.
+        // `?.` because jsdom implements neither scrollBy nor scrollIntoView.
+        el?.scrollBy?.({ left: direction * el.clientWidth * 0.8 });
+    }, [listRef]);
+    return { ...state, scrollByPage };
+}

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

@@ -53,6 +53,44 @@ export declare const ICONS: {
 };
 /** Every valid `iconKey`. A typo is a compile error, not a silent blank. */
 export type IconKey = keyof typeof ICONS;
+/**
+ * The ONLY sanctioned glyph sizes.
+ *
+ * WHY: a sweep of `appkit/src` + `src` found ~217 icon sites each hand-picking
+ * a size, in two spellings with no canonical order (`h-4 w-4` ×104,
+ * `w-5 h-5` ×64, `h-3 w-3` ×23, `h-3.5 w-3.5` ×26) across 105 lucide-importing
+ * files and 63 with an inline `<svg>`. Nothing related a glyph's size to the
+ * control containing it, so a 14px heart could sit in a 44px button and read as
+ * broken — which is exactly the "the wishlist icon is very small" report.
+ *
+ * Pick by ROLE, not by eye:
+ *
+ * | key  | px | use for                                             |
+ * |------|----|-----------------------------------------------------|
+ * | `xs` | 12 | dense meta, inside a badge or a caption row          |
+ * | `sm` | 14 | chrome inside a `size="sm"` control                 |
+ * | `md` | 16 | inline with body text; a `size="md"` control        |
+ * | `lg` | 20 | a standalone icon-only control's glyph              |
+ * | `xl` | 24 | hero, empty-state, feature tile                     |
+ * | `2xl`| 28 | chrome floating on an overlay (lightbox, carousel)  |
+ *
+ * `2xl` exists because ten lightbox/carousel controls had independently and
+ * unanimously picked 28px — that agreement is a real tier, not ten mistakes.
+ * Overlay chrome sits over arbitrary imagery and needs more presence than
+ * inline UI.
+ *
+ * `<Button>` and `<IconButton>` derive their own icon size from these — prefer
+ * letting the control choose over passing a size by hand.
+ */
+export declare const ICON_SIZE: {
+    readonly xs: "h-3 w-3";
+    readonly sm: "h-3.5 w-3.5";
+    readonly md: "h-4 w-4";
+    readonly lg: "h-5 w-5";
+    readonly xl: "h-6 w-6";
+    readonly "2xl": "h-7 w-7";
+};
+export type IconSizeKey = keyof typeof ICON_SIZE;
 /** Narrow an unknown string — for data that crosses a boundary the type cannot. */
 export declare function isIconKey(value: unknown): value is IconKey;
 /**

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

@@ -99,6 +99,43 @@ export const ICONS = {
     expand: ChevronDown,
     user: User,
 };
+/**
+ * The ONLY sanctioned glyph sizes.
+ *
+ * WHY: a sweep of `appkit/src` + `src` found ~217 icon sites each hand-picking
+ * a size, in two spellings with no canonical order (`h-4 w-4` ×104,
+ * `w-5 h-5` ×64, `h-3 w-3` ×23, `h-3.5 w-3.5` ×26) across 105 lucide-importing
+ * files and 63 with an inline `<svg>`. Nothing related a glyph's size to the
+ * control containing it, so a 14px heart could sit in a 44px button and read as
+ * broken — which is exactly the "the wishlist icon is very small" report.
+ *
+ * Pick by ROLE, not by eye:
+ *
+ * | key  | px | use for                                             |
+ * |------|----|-----------------------------------------------------|
+ * | `xs` | 12 | dense meta, inside a badge or a caption row          |
+ * | `sm` | 14 | chrome inside a `size="sm"` control                 |
+ * | `md` | 16 | inline with body text; a `size="md"` control        |
+ * | `lg` | 20 | a standalone icon-only control's glyph              |
+ * | `xl` | 24 | hero, empty-state, feature tile                     |
+ * | `2xl`| 28 | chrome floating on an overlay (lightbox, carousel)  |
+ *
+ * `2xl` exists because ten lightbox/carousel controls had independently and
+ * unanimously picked 28px — that agreement is a real tier, not ten mistakes.
+ * Overlay chrome sits over arbitrary imagery and needs more presence than
+ * inline UI.
+ *
+ * `<Button>` and `<IconButton>` derive their own icon size from these — prefer
+ * letting the control choose over passing a size by hand.
+ */
+export const ICON_SIZE = {
+    xs: "h-3 w-3",
+    sm: "h-3.5 w-3.5",
+    md: "h-4 w-4",
+    lg: "h-5 w-5",
+    xl: "h-6 w-6",
+    "2xl": "h-7 w-7",
+};
 /** Narrow an unknown string — for data that crosses a boundary the type cannot. */
 export function isIconKey(value) {
     return typeof value === "string" && value in ICONS;

package/dist/ui/index.d.ts

@@ -35,6 +35,10 @@ export type { ButtonProps } from "./components/Button";
 export { Button } from "./components/Button";
 export type { IconButtonProps } from "./components/IconButton";
 export { IconButton } from "./components/IconButton";
+export type { IconProps, IconTone } from "./components/Icon";
+export { Icon } from "./components/Icon";
+export type { IconKey, IconSizeKey } from "./icons/icon-registry";
+export { ICONS, ICON_SIZE, isIconKey, resolveIcon, } from "./icons/icon-registry";
 export type { TextLinkProps } from "./components/TextLink";
 export { TextLink } from "./components/TextLink";
 export type { TooltipProps } from "./components/Tooltip";
@@ -153,6 +157,8 @@ export type { NavigationLoaderProps } from "./components/NavigationLoader";
 export { NavigationLoader } from "./components/NavigationLoader";
 export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps, } from "./components/Tabs";
 export { Tabs, TabsList, TabsTrigger, TabsContent } from "./components/Tabs";
+export type { TabBarShellProps, TabBarButtonProps, TabsNavSelectProps, } from "./components/TabBarShell";
+export { TabBarShell, TabBarButton, TabsNavSelect } from "./components/TabBarShell";
 export type { FilterDrawerProps } from "./components/FilterDrawer";
 export { FilterDrawer } from "./components/FilterDrawer";
 export type { RowAction, RowActionMenuProps } from "./components/RowActionMenu";

package/dist/ui/index.js

@@ -20,6 +20,8 @@ export { SiteMark } from "./components/SiteMark";
 export { Skeleton } from "./components/Skeleton";
 export { Button } from "./components/Button";
 export { IconButton } from "./components/IconButton";
+export { Icon } from "./components/Icon";
+export { ICONS, ICON_SIZE, isIconKey, resolveIcon, } from "./icons/icon-registry";
 export { TextLink } from "./components/TextLink";
 export { Tooltip } from "./components/Tooltip";
 export { Accordion, AccordionItem } from "./components/Accordion";
@@ -79,6 +81,7 @@ export { RoleBadge } from "./components/RoleBadge";
 export { SkipToMain } from "./components/SkipToMain";
 export { NavigationLoader } from "./components/NavigationLoader";
 export { Tabs, TabsList, TabsTrigger, TabsContent } from "./components/Tabs";
+export { TabBarShell, TabBarButton, TabsNavSelect } from "./components/TabBarShell";
 export { FilterDrawer } from "./components/FilterDrawer";
 export { RowActionMenu } from "./components/RowActionMenu";
 export { PasswordStrengthIndicator } from "./components/PasswordStrengthIndicator";

package/dist/utils/index.d.ts

@@ -17,5 +17,5 @@ export * from "./business-day";
 export * from "./schema-ui";
 export * from "./listing-params";
 export * from "./action-response";
-export * from "./search-tokens";
+export * from "./search-txt";
 export { splitCartIntoOrderGroups, type OrderType, type OrderGroup, } from "../features/orders/utils/order-splitter";

package/dist/utils/index.js

@@ -17,6 +17,6 @@ export * from "./business-day";
 export * from "./schema-ui";
 export * from "./listing-params";
 export * from "./action-response";
-export * from "./search-tokens";
+export * from "./search-txt";
 // Re-export order utilities for checkout flows
 export { splitCartIntoOrderGroups, } from "../features/orders/utils/order-splitter";

package/dist/utils/media-url.d.ts

@@ -7,17 +7,40 @@
 export declare const FIREBASE_STORAGE_HOST = "firebasestorage.googleapis.com";
 /** Google Cloud Storage host (used by public-asset URLs). */
 export declare const GCS_HOST = "storage.googleapis.com";
+export interface ResolveMediaUrlOptions {
+    /**
+     * When false, a URL we do not own is returned UNCHANGED instead of being sent
+     * to `/api/media/ext`. That proxy is image-only (it 400s on `video/mp4`), so
+     * every non-image caller must pass false — see `resolveVideoUrl`.
+     * @default true
+     */
+    externalProxy?: boolean;
+}
 /**
  * Normalise any image URL so it goes through the watermark proxy:
- *  - /media/<path>         → return as-is (already proxied via Firebase Storage)
+ *  - /media<path>          → return as-is (already proxied via Firebase Storage)
  *  - blob: / data: URI     → return as-is (local-only, never fetchable server-side)
  *  - Firebase Storage URL  → extract /o/ path → /media/<path>
- *  - GCS (storage.googleapis.com) URL → drop the bucket segment → /media/<path>
- *  - Any other absolute URL → /api/media/ext?url=<encoded> (ext watermark proxy)
+ *  - GCS URL for OUR bucket → drop the bucket segment → /media/<path>
+ *  - Any other absolute URL → /api/media/ext?url=<encoded> (ext watermark proxy),
+ *                             or unchanged when `externalProxy: false`
  *  - Relative URI          → return as-is
  *  - Falsy                 → undefined
  */
-export declare function resolveMediaUrl(url: string | null | undefined): string | undefined;
+export declare function resolveMediaUrl(url: string | null | undefined, opts?: ResolveMediaUrlOptions): string | undefined;
+/**
+ * Resolve a VIDEO src.
+ *
+ * Same rules as `resolveMediaUrl` for media we own — a Firebase Storage or
+ * own-bucket GCS URL still becomes `/media/<path>`, and the `[...slug]` proxy
+ * raw-pipes non-images — but a third-party URL is returned untouched rather
+ * than routed through `/api/media/ext`, which is image-only and 400s on
+ * `video/mp4` (Root Cause #27).
+ *
+ * Use this for anything that ends up as a `<video src>`. Posters and thumbnails
+ * are images and stay on `resolveMediaUrl`.
+ */
+export declare function resolveVideoUrl(url: string | null | undefined): string | undefined;
 /**
  * Extracts the 11-char YouTube video ID from a watch/share/embed URL, or
  * `null` when `url` isn't a recognized YouTube URL. A video field can be

package/dist/utils/media-url.js

@@ -10,17 +10,25 @@ export const FIREBASE_STORAGE_HOST = "firebasestorage.googleapis.com";
 /** Google Cloud Storage host (used by public-asset URLs). */
 export const GCS_HOST = "storage.googleapis.com";
 const PROXY_PREFIX = "/media/";
+/**
+ * Our own Storage bucket, as it appears as the first path segment of a
+ * `storage.googleapis.com` URL. Only URLs pointing at THIS bucket may have that
+ * segment stripped and be rewritten to `/media/<path>` — see the GCS branch
+ * below for why assuming every GCS URL is ours is a live 404.
+ */
+const OWN_STORAGE_BUCKET = process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET ?? "";
 /**
  * Normalise any image URL so it goes through the watermark proxy:
- *  - /media/<path>         → return as-is (already proxied via Firebase Storage)
+ *  - /media<path>          → return as-is (already proxied via Firebase Storage)
  *  - blob: / data: URI     → return as-is (local-only, never fetchable server-side)
  *  - Firebase Storage URL  → extract /o/ path → /media/<path>
- *  - GCS (storage.googleapis.com) URL → drop the bucket segment → /media/<path>
- *  - Any other absolute URL → /api/media/ext?url=<encoded> (ext watermark proxy)
+ *  - GCS URL for OUR bucket → drop the bucket segment → /media/<path>
+ *  - Any other absolute URL → /api/media/ext?url=<encoded> (ext watermark proxy),
+ *                             or unchanged when `externalProxy: false`
  *  - Relative URI          → return as-is
  *  - Falsy                 → undefined
  */
-export function resolveMediaUrl(url) {
+export function resolveMediaUrl(url, opts) {
     if (!url)
         return undefined;
     if (url.startsWith(PROXY_PREFIX))
@@ -43,19 +51,42 @@ export function resolveMediaUrl(url) {
             // Path shape: /<bucket>/<object-path...> — drop the bucket segment,
             // proxy the rest like a Firebase Storage URL (consistent watermarking
             // + caching instead of falling through to the external-URL proxy).
+            //
+            // ONLY for our own bucket. This branch used to strip the first segment of
+            // ANY storage.googleapis.com URL, so Google's public sample bucket
+            //   https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4
+            // became /media/sample/BigBuckBunny.mp4 — an object that has never existed
+            // in our bucket — and 404'd on the homepage hero carousel.
             const parts = parsed.pathname.replace(/^\//, "").split("/");
-            if (parts.length > 1) {
+            if (parts.length > 1 && OWN_STORAGE_BUCKET && parts[0] === OWN_STORAGE_BUCKET) {
                 const objectPath = parts.slice(1).join("/");
                 return `${PROXY_PREFIX}${decodeURIComponent(objectPath)}`;
             }
         }
-        return MEDIA_ENDPOINTS.EXT_URL(url);
+        // Not ours. The ext proxy watermarks IMAGES only and 400s on anything else,
+        // so a non-image caller opts out and gets the original URL back.
+        return opts?.externalProxy === false ? url : MEDIA_ENDPOINTS.EXT_URL(url);
     }
     catch (_err) {
         void normalizeError(_err); // URL constructor throws for non-URL strings (e.g., relative paths) — return original
         return url;
     }
 }
+/**
+ * Resolve a VIDEO src.
+ *
+ * Same rules as `resolveMediaUrl` for media we own — a Firebase Storage or
+ * own-bucket GCS URL still becomes `/media/<path>`, and the `[...slug]` proxy
+ * raw-pipes non-images — but a third-party URL is returned untouched rather
+ * than routed through `/api/media/ext`, which is image-only and 400s on
+ * `video/mp4` (Root Cause #27).
+ *
+ * Use this for anything that ends up as a `<video src>`. Posters and thumbnails
+ * are images and stay on `resolveMediaUrl`.
+ */
+export function resolveVideoUrl(url) {
+    return resolveMediaUrl(url, { externalProxy: false });
+}
 const YOUTUBE_HOSTS = new Set([
     "youtube.com",
     "m.youtube.com",

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

@@ -0,0 +1,71 @@
+/**
+ * `searchTxt` — one normalized, partial-match search field per entity.
+ *
+ * ## Why an array and not a string
+ *
+ * Firestore has no LIKE/substring operator. A string field supports `==` and a
+ * range, and a range on a string is a **prefix anchored at the start of the whole
+ * value** — so `"pokemon charizard psa 9"` would match a search for `"pok"` and
+ * never for `"charizard"`. A single text column cannot do partial match here.
+ *
+ * An array of normalized *edge n-grams* can, in one `array-contains` clause:
+ *
+ *   "Pokémon Charizard PSA 9"
+ *     → normalize → "pokemon charizard psa 9"
+ *     → ["po","pok",…,"pokemon","ch","cha","char","chari",…,"charizard","ps","psa"]
+ *
+ * A query for "chari" is then a single equality-shaped clause against one index.
+ * No OR-group, no query-time case folding, no per-sort composite index.
+ *
+ * ## Deliberate limits
+ *
+ * - **Word-prefix, not mid-word.** "ariza" will not match "charizard". True
+ *   mid-word needs trigrams, which multiply index entries several-fold for a
+ *   case users rarely type.
+ * - **One `array-contains` per Firestore query**, so a multi-word search uses the
+ *   most selective term as the clause and AND-refines the rest server-side.
+ * - **Never put PII in here.** These are readable fragments of the source text —
+ *   a `searchTxt` for a person's name IS that name, re-encoded. Encrypted fields
+ *   stay searchable only through their HMAC blind index (exact match).
+ */
+export interface SearchTxtOptions {
+    /**
+     * Emit prefixes for these sources. Use for short, high-signal text (title,
+     * tags, category). Long body text should stay whole-word or it dominates the
+     * token budget.
+     */
+    prefix?: boolean;
+    maxPrefixLength?: number;
+    maxTokens?: number;
+}
+type Source = string | string[] | undefined | null;
+/**
+ * Lowercase, strip accents, collapse everything non-alphanumeric to spaces.
+ *
+ * Accent folding is what makes "Pokemon" find "Pokémon" — a plain lowercase
+ * would leave those as different tokens.
+ */
+export declare function normalizeSearchText(input: string): string;
+/**
+ * Build the stored token array.
+ *
+ * @param sources any mix of strings and string arrays; nullish entries ignored
+ */
+export declare function buildSearchTxt(sources: Source[], options?: SearchTxtOptions): string[];
+/**
+ * Tokenize a user's query into candidate clause values, most selective first.
+ *
+ * Longest term first because only one may become the `array-contains` clause —
+ * the longest is the cheapest proxy for "narrows the result set most" without
+ * keeping per-term cardinality statistics.
+ *
+ * Uses the SAME normalizer as the write side; if the two ever diverge, a query
+ * silently stops matching what was indexed.
+ */
+export declare function parseSearchTxtQuery(query: string): string[];
+/**
+ * Does a document's stored tokens satisfy every term? Used for the AND-refine
+ * pass after the single `array-contains` clause has narrowed the candidates.
+ */
+export declare function matchesAllSearchTerms(searchTxt: readonly string[] | undefined, terms: readonly string[]): boolean;
+export {};

package/dist/utils/search-txt.js

@@ -0,0 +1,118 @@
+/**
+ * `searchTxt` — one normalized, partial-match search field per entity.
+ *
+ * ## Why an array and not a string
+ *
+ * Firestore has no LIKE/substring operator. A string field supports `==` and a
+ * range, and a range on a string is a **prefix anchored at the start of the whole
+ * value** — so `"pokemon charizard psa 9"` would match a search for `"pok"` and
+ * never for `"charizard"`. A single text column cannot do partial match here.
+ *
+ * An array of normalized *edge n-grams* can, in one `array-contains` clause:
+ *
+ *   "Pokémon Charizard PSA 9"
+ *     → normalize → "pokemon charizard psa 9"
+ *     → ["po","pok",…,"pokemon","ch","cha","char","chari",…,"charizard","ps","psa"]
+ *
+ * A query for "chari" is then a single equality-shaped clause against one index.
+ * No OR-group, no query-time case folding, no per-sort composite index.
+ *
+ * ## Deliberate limits
+ *
+ * - **Word-prefix, not mid-word.** "ariza" will not match "charizard". True
+ *   mid-word needs trigrams, which multiply index entries several-fold for a
+ *   case users rarely type.
+ * - **One `array-contains` per Firestore query**, so a multi-word search uses the
+ *   most selective term as the clause and AND-refines the rest server-side.
+ * - **Never put PII in here.** These are readable fragments of the source text —
+ *   a `searchTxt` for a person's name IS that name, re-encoded. Encrypted fields
+ *   stay searchable only through their HMAC blind index (exact match).
+ */
+/** Longest prefix emitted. Nobody types more than this before results narrow. */
+const MAX_PREFIX_LENGTH = 12;
+/** Shortest prefix emitted. 1 keeps single-character searches working. */
+const MIN_PREFIX_LENGTH = 1;
+/**
+ * Ceiling on tokens per document. Firestore allows 40k index entries per doc and
+ * each array element costs one per index containing the field, so a long body
+ * left unbounded is a real limit to hit.
+ */
+const MAX_TOKENS = 600;
+/** Words longer than this contribute whole-word only — no prefix expansion. */
+const LONG_WORD_LIMIT = 24;
+/**
+ * Lowercase, strip accents, collapse everything non-alphanumeric to spaces.
+ *
+ * Accent folding is what makes "Pokemon" find "Pokémon" — a plain lowercase
+ * would leave those as different tokens.
+ */
+export function normalizeSearchText(input) {
+    return input
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function words(sources) {
+    const text = sources
+        .flat()
+        .filter((v) => typeof v === "string" && v.length > 0)
+        .join(" ");
+    const normalized = normalizeSearchText(text);
+    return normalized ? normalized.split(" ").filter(Boolean) : [];
+}
+/**
+ * Build the stored token array.
+ *
+ * @param sources any mix of strings and string arrays; nullish entries ignored
+ */
+export function buildSearchTxt(sources, options = {}) {
+    const { prefix = true, maxPrefixLength = MAX_PREFIX_LENGTH, maxTokens = MAX_TOKENS, } = options;
+    const tokens = new Set();
+    for (const word of words(sources)) {
+        tokens.add(word);
+        if (!prefix || word.length > LONG_WORD_LIMIT)
+            continue;
+        // Inclusive: maxPrefixLength=5 must emit the 5-character prefix. When the
+        // bound equals the word length the last slice is the whole word, which the
+        // Set already holds.
+        const upper = Math.min(word.length, maxPrefixLength);
+        for (let n = MIN_PREFIX_LENGTH; n <= upper; n++) {
+            tokens.add(word.slice(0, n));
+        }
+        if (tokens.size >= maxTokens)
+            break;
+    }
+    return Array.from(tokens).slice(0, maxTokens);
+}
+/**
+ * Tokenize a user's query into candidate clause values, most selective first.
+ *
+ * Longest term first because only one may become the `array-contains` clause —
+ * the longest is the cheapest proxy for "narrows the result set most" without
+ * keeping per-term cardinality statistics.
+ *
+ * Uses the SAME normalizer as the write side; if the two ever diverge, a query
+ * silently stops matching what was indexed.
+ */
+export function parseSearchTxtQuery(query) {
+    const normalized = normalizeSearchText(query ?? "");
+    if (!normalized)
+        return [];
+    return Array.from(new Set(normalized.split(" ").filter(Boolean)))
+        .sort((a, b) => b.length - a.length)
+        .slice(0, 10);
+}
+/**
+ * Does a document's stored tokens satisfy every term? Used for the AND-refine
+ * pass after the single `array-contains` clause has narrowed the candidates.
+ */
+export function matchesAllSearchTerms(searchTxt, terms) {
+    if (terms.length === 0)
+        return true;
+    if (!searchTxt || searchTxt.length === 0)
+        return false;
+    const set = new Set(searchTxt);
+    return terms.every((t) => set.has(t));
+}

package/package.json

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