@mohasinac/appkit 4.26.0 → 4.28.0

package/dist/features/cart/utils/line-total.d.ts

@@ -0,0 +1,25 @@
+import { type PricedCartLine } from "../../../_internal/shared/checkout/order-math";
+/**
+ * What one cart line contributes to a subtotal, computed on the CLIENT — where
+ * no `ProductDocument` is available.
+ *
+ * Delegates to `lineTotalFor(item, null)` so the priority order that actually
+ * matters stays in one place (`order-math.ts`): a `lockedPrice` beats
+ * everything, a bundle is charged its own discounted price and is checked
+ * BEFORE its members, a grouped line is the sum of what the buyer picked, and
+ * anything else falls back to the cart's snapshotted price.
+ *
+ * 🛑 Do not re-derive this at a call site. That rule has been hand-rolled six
+ * times already and two of the copies silently omitted the `lockedPrice`
+ * branch, so an accepted offer was charged at the seller's list price
+ * (Recurrent Root Cause #75).
+ *
+ * The one thing it cannot know is a live listing price that has moved since the
+ * line was added — `lineTotalFor` would read that off the product document.
+ * That is fine for the surfaces this serves (the cart and the checkout
+ * add-ons/fees step): both exist to render immediately with a good figure, and
+ * the server pricing preview overwrites it with the authoritative one the
+ * moment it lands.
+ */
+export declare function clientLineTotal(item: PricedCartLine): number;
+export type { PricedCartLine };

package/dist/features/cart/utils/line-total.js

@@ -0,0 +1,26 @@
+import { lineTotalFor } from "../../../_internal/shared/checkout/order-math";
+/**
+ * What one cart line contributes to a subtotal, computed on the CLIENT — where
+ * no `ProductDocument` is available.
+ *
+ * Delegates to `lineTotalFor(item, null)` so the priority order that actually
+ * matters stays in one place (`order-math.ts`): a `lockedPrice` beats
+ * everything, a bundle is charged its own discounted price and is checked
+ * BEFORE its members, a grouped line is the sum of what the buyer picked, and
+ * anything else falls back to the cart's snapshotted price.
+ *
+ * 🛑 Do not re-derive this at a call site. That rule has been hand-rolled six
+ * times already and two of the copies silently omitted the `lockedPrice`
+ * branch, so an accepted offer was charged at the seller's list price
+ * (Recurrent Root Cause #75).
+ *
+ * The one thing it cannot know is a live listing price that has moved since the
+ * line was added — `lineTotalFor` would read that off the product document.
+ * That is fine for the surfaces this serves (the cart and the checkout
+ * add-ons/fees step): both exist to render immediately with a good figure, and
+ * the server pricing preview overwrites it with the authoritative one the
+ * moment it lands.
+ */
+export function clientLineTotal(item) {
+    return lineTotalFor(item, null);
+}

package/dist/features/catalogue/repository/catalogue.repository.d.ts

@@ -1,3 +1,4 @@
+import type { DocumentSnapshot } from "firebase-admin/firestore";
 /**
  * Personal Catalogue Repository (Feature B).
  */
@@ -12,6 +13,17 @@ export interface CatalogueWriteContext {
     note?: string;
 }
 export declare class CatalogueRepository extends BaseRepository<CatalogueItemDocument> {
+    /**
+     * `ownerEmail` only — NOT `ownerName`.
+     *
+     * Per decision D1 names stay partial-match searchable, and catalogue items are
+     * searchable by owner in the admin approvals queue. `CATALOGUE_HISTORY_PII_FIELDS`
+     * lists both, but that constant scrubs status *history*, which has no search
+     * requirement — the two lists are intentionally different.
+     */
+    protected piiFields: readonly ["ownerEmail"];
+    /** Decrypt on read so callers see the shape they wrote. */
+    protected mapDoc<D = CatalogueItemDocument>(snap: DocumentSnapshot): D;
     constructor();
     create(input: CatalogueItemCreateInput): Promise<CatalogueItemDocument>;
     /**

package/dist/features/catalogue/repository/catalogue.repository.js

@@ -1,3 +1,4 @@
+import { decryptPiiFields } from "../../../security/pii-encrypt";
 /**
  * Personal Catalogue Repository (Feature B).
  */
@@ -5,8 +6,22 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { CATALOGUE_COLLECTION, CATALOGUE_FIELDS, CATALOGUE_TRACKED_FIELDS, CATALOGUE_HISTORY_PII_FIELDS, createCatalogueItemId, } from "../schemas/firestore";
 import { withHistory } from "../../../_internal/shared/history/index";
 export class CatalogueRepository extends BaseRepository {
+    /** Decrypt on read so callers see the shape they wrote. */
+    mapDoc(snap) {
+        const raw = super.mapDoc(snap);
+        return decryptPiiFields(raw, [...this.piiFields]);
+    }
     constructor() {
         super(CATALOGUE_COLLECTION);
+        /**
+         * `ownerEmail` only — NOT `ownerName`.
+         *
+         * Per decision D1 names stay partial-match searchable, and catalogue items are
+         * searchable by owner in the admin approvals queue. `CATALOGUE_HISTORY_PII_FIELDS`
+         * lists both, but that constant scrubs status *history*, which has no search
+         * requirement — the two lists are intentionally different.
+         */
+        this.piiFields = ["ownerEmail"];
     }
     async create(input) {
         const id = createCatalogueItemId({ ownerSlug: input.ownerId, title: input.title });

package/dist/features/categories/components/CategoryTree.js

@@ -10,7 +10,7 @@ function CategoryTreeNode({ item, children = [], activeId, onSelect, depth = 0,
     const DEPTH_PL = ["pl-2", "pl-6", "pl-10", "pl-14", "pl-[72px]"];
     const depthPl = DEPTH_PL[Math.min(depth, 4)];
     return (_jsxs(Div, { children: [_jsxs(Row, { textWeight: "semibold", textSize: "sm", role: "treeitem", "aria-expanded": hasChildren ? expanded : undefined, "aria-selected": isActive, tabIndex: 0, onKeyDown: (e) => {
-                    if (e.key === "Enter" || e.key === " ") {
+                    if (e.key === "Enter" || e.key === "") {
                         if (hasChildren)
                             setExpanded((p) => !p);
                         onSelect?.(item);
@@ -20,7 +20,7 @@ function CategoryTreeNode({ item, children = [], activeId, onSelect, depth = 0,
                     if (hasChildren)
                         setExpanded((p) => !p);
                     onSelect?.(item);
-                }, className: `cursor-pointer py-[var(--appkit-space-1-5)] transition select-none ${depthPl} ${isActive ? "bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-400" : "text-neutral-700 hover:bg-neutral-50 text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-surface-elevated)]"}`, align: "center", gap: "xs", padding: "x-xs", rounded: "md", children: [hasChildren && (_jsx(Span, { size: "xs", "aria-hidden": "true", className: `transition-transform duration-150 ${expanded ? "rotate-90" : ""}`, color: "faint", children: "\u25B6" })), !hasChildren && _jsx(Span, { className: "w-3" }), item.display?.icon && (_jsx(Span, { size: "base", "aria-hidden": "true", className: "flex-shrink-0", children: item.display.icon })), _jsx(Text, { className: "flex-1 truncate", children: item.name }), item.metrics && (_jsx(Span, { size: "xs", className: "ml-auto flex-shrink-0 tabular-nums", color: "faint", children: item.metrics.productCount }))] }), hasChildren && expanded && (_jsx(Div, { role: "group", children: children.map((child) => (_jsx(CategoryTreeNode, { item: child, activeId: activeId, onSelect: onSelect, depth: depth + 1 }, child.id))) }))] }));
+                }, className: `cursor-pointer py-[var(--appkit-space-1-5)] transition select-none ${depthPl} ${isActive ? "bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-400" : " hover:bg-surface-hover text-[var(--appkit-color-text-muted)]"}`, align: "center", gap: "xs", padding: "x-xs", rounded: "md", children: [hasChildren && (_jsx(Span, { size: "xs", "aria-hidden": "true", className: `transition-transform duration-150 ${expanded ? "rotate-90" : ""}`, color: "faint", children: "\u25B6" })), !hasChildren && _jsx(Span, { className: "w-3" }), item.display?.icon && (_jsx(Span, { size: "base", "aria-hidden": "true", className: "flex-shrink-0", children: item.display.icon })), _jsx(Text, { className: "flex-1 truncate", children: item.name }), item.metrics && (_jsx(Span, { size: "xs", className: "ml-auto flex-shrink-0 tabular-nums", color: "faint", children: item.metrics.productCount }))] }), hasChildren && expanded && (_jsx(Div, { role: "group", children: children.map((child) => (_jsx(CategoryTreeNode, { item: child, activeId: activeId, onSelect: onSelect, depth: depth + 1 }, child.id))) }))] }));
 }
 /**
  * CategoryTree — hierarchical expandable navigation for categories.

package/dist/features/contact/components/ContactForm.js

@@ -68,7 +68,7 @@ export function ContactForm({ onSubmit, labels = {}, className = "", }) {
     if (submitted) {
         return (_jsxs(Div, { className: `text-center ${className}`, padding: "y-3xl", children: [_jsx(Div, { textSize: "5xl", className: "mb-4", children: "\u2705" }), _jsx(Heading, { level: 2, className: "mb-2", children: labels.successTitle ?? "Message Sent!" }), _jsx(Text, { variant: "secondary", className: "mb-6", children: labels.successDescription ?? "We'll get back to you shortly." }), _jsx(Button, { type: "button", variant: "outline", onClick: () => setSubmitted(false), children: labels.sendAnotherButton ?? "Send another message" })] }));
     }
-    const field = (id, label, placeholder, multiline) => (_jsxs(Stack, { gap: "xs", children: [_jsx("label", { htmlFor: id, className: "text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)]", children: label }), multiline ? (_jsx(Textarea, { id: id, value: form[id], onChange: (e) => setForm((f) => ({ ...f, [id]: e.target.value })), placeholder: placeholder, rows: 5, className: "w-full rounded-lg border border-neutral-200 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] outline-none focus:ring-2 ring-primary/20 transition" })) : (_jsx(Input, { id: id, type: id === "email" ? "email" : "text", value: form[id], onChange: (e) => setForm((f) => ({ ...f, [id]: e.target.value })), placeholder: placeholder, className: "h-10" })), errors[id] && _jsx(Span, { size: "xs", className: CLS_FIELD_ERROR, children: errors[id] })] }));
+    const field = (id, label, placeholder, multiline) => (_jsxs(Stack, { gap: "xs", children: [_jsx("label", { htmlFor: id, className: "text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)]", children: label }), multiline ? (_jsx(Textarea, { id: id, value: form[id], onChange: (e) => setForm((f) => ({ ...f, [id]: e.target.value })), placeholder: placeholder, rows: 5, className: "w-full rounded-lg border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] outline-none focus:ring-2 ring-primary/20 transition" })) : (_jsx(Input, { id: id, type: id === "email" ? "email" : "text", value: form[id], onChange: (e) => setForm((f) => ({ ...f, [id]: e.target.value })), placeholder: placeholder, className: "h-10" })), errors[id] && _jsx(Span, { size: "xs", className: CLS_FIELD_ERROR, children: errors[id] })] }));
     return (_jsx(FormShellContext.Provider, { value: shellCtx, children: _jsxs(Form, { onSubmit: handleSubmit, noValidate: true, className: className, spacing: "md", children: [_jsx(Heading, { level: 2, className: "mb-6", children: labels.title ?? "Send us a message" }), submitError && (_jsx(Div, { className: CLS_ERROR_BANNER, children: submitError })), field("name", labels.nameLabel ?? "Your Name", labels.namePlaceholder ?? "Enter your name"), field("email", labels.emailLabel ?? "Email", labels.emailPlaceholder ?? "your@email.com"), field("subject", labels.subjectLabel ?? "Subject", labels.subjectPlaceholder ?? "How can we help?"), field("message", labels.messageLabel ?? "Message", labels.messagePlaceholder ?? "Tell us more…", true), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "submit", variant: "primary", disabled: isSubmitting, className: "w-full sm:w-auto", children: isSubmitting
                         ? (labels.submittingButton ?? "Sending…")
                         : (labels.submitButton ?? "Send Message") })] }) }));

package/dist/features/copilot/hooks/useCopilotFeedback.d.ts

@@ -9,7 +9,7 @@ export interface UseCopilotFeedbackOptions {
  * Sends thumbs-up / thumbs-down feedback on a copilot response.
  * The consumer injects the endpoint builder so appkit stays route-agnostic.
  */
-export declare function useCopilotFeedback({ feedbackEndpoint, }: UseCopilotFeedbackOptions): import("@tanstack/react-query").UseMutationResult<void, import("@mohasinac/appkit/client").ApiError, {
+export declare function useCopilotFeedback({ feedbackEndpoint, }: UseCopilotFeedbackOptions): import("@tanstack/react-query").UseMutationResult<void, import("../../../client").ApiError, {
     logId: string;
     feedback: CopilotFeedback;
 }, unknown>;

package/dist/features/copilot/hooks/useCopilotFeedback.js

@@ -1,4 +1,4 @@
-import { useApiMutation } from "@mohasinac/appkit/client";
+import { useApiMutation } from "../../../client/api/useApiMutation";
 import { apiClient } from "../../../http";
 /**
  * useCopilotFeedback

package/dist/features/events/components/AdminEventEditorView.js

@@ -8,6 +8,7 @@ import { Alert, Button, Div, Grid, Heading, Input, Label, RichTextEditor, Row, S
 import { FormShellContext, useFormShellState, applyZodIssues, FormErrorSummary } from "../../../ui/forms";
 import { apiClient } from "../../../http";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { ALL_EVENT_TYPES, EVENT_TYPE_LABELS } from "../types";
 import { SectionForm, useSectionFormNav } from "../../shell";
 import { eventDraftSchema } from "../schemas/event-form";
 import { ProductInlineSelect } from "../../seller/components/ProductInlineSelect";
@@ -31,15 +32,21 @@ const CLS_REMOVE_BTN_LG = "text-zinc-400 hover:text-error text-[length:var(--app
 const CLS_RAFFLE_PANEL = "border border-warning bg-warning-surface dark:border-warning dark:bg-warning-surface";
 const CLS_RAFFLE_HEADING = "text-warning dark:text-warning";
 const CLS_RAFFLE_BODY = "text-warning dark:text-warning";
-const EVENT_TYPE_OPTIONS = [
-    { label: "Sale", value: "sale" },
-    { label: "Offer / Coupon", value: "offer" },
-    { label: "Poll", value: "poll" },
-    { label: "Survey", value: "survey" },
-    { label: "Feedback", value: "feedback" },
-    { label: "Raffle", value: "raffle" },
-    { label: "Spin Wheel", value: "spin_wheel" },
-];
+/*
+ * DERIVED. This was a hand-written 7-entry array and `EVENT_TYPE_LABELS`
+ * — a `Record<EventType, string>` sitting one import away — already held the
+ * same labels for all 8. It was missing `lottery`, and `allowedTypes` filters
+ * AGAINST this list, so passing `"lottery"` in still could not surface it:
+ * lottery events had no create path in the UI at all and could only come from
+ * `npm run seed`.
+ *
+ * Deriving from the Record means a new EventType cannot be omitted here
+ * without failing to compile (Root Cause #61).
+ */
+const EVENT_TYPE_OPTIONS = ALL_EVENT_TYPES.map((value) => ({
+    value,
+    label: EVENT_TYPE_LABELS[value],
+}));
 const RAFFLE_TYPE_OPTIONS = [
     { label: "Open raffle (all confirmed entries)", value: "open_raffle" },
     { label: "Top N scorers", value: "top_n_scorers" },

package/dist/features/events/components/AdminEventEntriesView.js

@@ -9,6 +9,9 @@ import { normalizeError } from "../../../errors/normalize";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
 import { DataListingView } from "../../admin/components/DataListingView";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { buildEventEntryDetailFields } from "./event-entry-detail-fields";
+import { TextLink } from "../../../ui";
+import { ROUTES } from "../../../constants/index";
 const CLS_RESPONSE_TEXT = "whitespace-pre-wrap break-words";
 const REVIEW_STATUS_OPTIONS = [
     { label: "All", value: "all" },
@@ -151,19 +154,10 @@ export function AdminEventEntriesView({ eventId, entriesEndpoint, entryReviewEnd
         toolbarExtra: eventId ? (_jsx(Button, { variant: "ghost", action: ACTIONS.ADMIN["export-event-entries"], onClick: handleExportReport })) : undefined,
         renderAboveContent: () => (_jsxs(Stack, { gap: "3", className: "px-[var(--appkit-space-3)] pb-[var(--appkit-space-2)]", children: [!eventId ? (_jsx(Alert, { variant: "warning", title: "Missing event id", children: "Event id is required to load entries." })) : null, statsQuery.error ? (_jsx(Alert, { variant: "error", title: "Could not load event stats", children: statsQuery.error instanceof Error ? statsQuery.error.message : "Unknown error" })) : null, _jsxs(Div, { layout: "grid", gap: "3", className: "grid-cols-1 sm:grid-cols-3", children: [_jsx(Alert, { variant: "info", title: "Total entries", children: String(statsQuery.data?.stats?.totalEntries ?? 0) }), _jsx(Alert, { variant: "success", title: "Approved", children: String(statsQuery.data?.stats?.approvedEntries ?? 0) }), _jsx(Alert, { variant: "warning", title: "Flagged", children: String(statsQuery.data?.stats?.flaggedEntries ?? 0) })] })] })),
     };
-    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(RecordDetailModal, { isOpen: detail !== null, onClose: () => setDetail(null), title: detail?.userDisplayName || detail?.userEmail || "Entry", badges: detail ? [{ label: detail.reviewStatus }] : undefined, description: detail?.pollComment, fields: detail
-                    ? [
-                        { label: "Entrant", value: detail.userDisplayName ?? detail.userId ?? "—" },
-                        { label: "Email", value: detail.userEmail ?? "—" },
-                        { label: "Review status", value: detail.reviewStatus },
-                        { label: "Points", value: detail.points != null ? String(detail.points) : "—" },
-                        { label: "Raffle eligible", value: detail.raffleEligible ? "Yes" : "No" },
-                        { label: "Poll votes", value: detail.pollVotes?.join(", ") || "—" },
-                        { label: "Reviewed by", value: detail.reviewedBy ?? "—" },
-                        { label: "Review note", value: detail.reviewNote ?? "—" },
-                        { label: "Entry ID", value: detail.id },
-                    ]
-                    : undefined, 
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(RecordDetailModal, { isOpen: detail !== null, onClose: () => setDetail(null), title: detail?.userDisplayName || detail?.userEmail || "Entry", badges: detail ? [{ label: detail.reviewStatus }] : undefined, description: detail?.pollComment, fields: detail ? buildEventEntryDetailFields(detail) : undefined, footer: detail ? (
+                // The full page — a modal cannot be linked, bookmarked or reloaded
+                // into, which is the whole reason the page exists.
+                _jsx(TextLink, { href: String(ROUTES.ADMIN.EVENT_ENTRY_DETAIL(detail.id)), children: "Open full page \u2192" })) : undefined, 
                 // The survey/feedback answers — the actual submission being judged.
                 metadata: detail?.formResponses })] }));
 }

package/dist/features/events/components/EventRafflesSection.js

@@ -1,7 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
-import { sieveFilter, sieveAnd, SIEVE_OP } from "@mohasinac/appkit/client";
-import { sortBy } from "@mohasinac/appkit/client";
+import { serverLogger } from "../../../monitoring/server-logger";
+// Import from the DEFINING modules, never `@mohasinac/appkit/client` — that
+// entry is `"use client"`, so in this async Server Component these would resolve
+// to client-reference proxies and calling them throws during the server render
+// (Root Cause #18). The `try/catch` below swallowed that throw, which is why
+// this section silently rendered nothing instead of failing loudly.
+import { sieveFilter, sieveAnd, SIEVE_OP } from "../../../utils/sieve-builder";
+import { sortBy } from "../../../constants/sort";
 import { Container, Div, Heading, Section, Stack, Text, } from "../../../ui";
 import { eventRepository } from "../repository/events.repository";
 import { EventCard } from "./EventCard";
@@ -24,6 +30,12 @@ export async function EventRafflesSection({ config, }) {
     }
     catch (_err) {
         void normalizeError(_err);
+        // Loud on purpose: a swallowed failure here is indistinguishable from "no
+        // active raffles", which is how this section stayed invisible in production
+        // without anyone noticing (Root Cause #59).
+        serverLogger.error("EventRafflesSection query failed", {
+            error: _err instanceof Error ? _err.message : String(_err),
+        });
         events = [];
     }
     if (events.length === 0)

package/dist/features/events/components/EventStatusBadge.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Span } from "../../../ui";
 const STATUS_MAP = {
-    draft: { label: "Draft", color: "bg-[var(--appkit-color-surface)] text-gray-700 bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]" },
+    draft: { label: "Draft", color: "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]" },
     active: { label: "Active", color: "bg-success-surface text-success" },
     paused: { label: "Paused", color: "bg-warning-surface text-warning" },
     ended: { label: "Ended", color: "bg-error-surface text-error" },

package/dist/features/events/components/event-entry-detail-fields.d.ts

@@ -0,0 +1,24 @@
+import type { EventEntryItem } from "../types";
+/**
+ * The scalar rows for one event entry.
+ *
+ * Extracted 2026-08-26 (W22) so `AdminEventEntriesView`'s detail modal and
+ * `/admin/event-entries/[id]/view` render the same thing. The list had these
+ * inline; a page that re-listed them would be a second copy, and the first
+ * field added to one and not the other is the drift.
+ *
+ * Same shape as `buildBidDetailFields` in the auctions feature — that one also
+ * takes a viewer, because a bid's bidder identity is portal-dependent. An
+ * event entry has no such split: only admins and moderators reach this at all,
+ * so there is no viewer parameter to add and adding one "for symmetry" would
+ * imply a distinction that does not exist.
+ *
+ * `formResponses` is deliberately NOT a row. It is the survey/feedback
+ * submission being judged — open-ended and often long — and belongs in the
+ * `metadata` slot, not squeezed into a definition list.
+ */
+export interface EntryFieldRow {
+    label: string;
+    value: string;
+}
+export declare function buildEventEntryDetailFields(entry: EventEntryItem): EntryFieldRow[];

package/dist/features/events/components/event-entry-detail-fields.js

@@ -0,0 +1,13 @@
+export function buildEventEntryDetailFields(entry) {
+    return [
+        { label: "Entrant", value: entry.userDisplayName ?? entry.userId ?? "—" },
+        { label: "Email", value: entry.userEmail ?? "—" },
+        { label: "Review status", value: entry.reviewStatus },
+        { label: "Points", value: entry.points != null ? String(entry.points) : "—" },
+        { label: "Raffle eligible", value: entry.raffleEligible ? "Yes" : "No" },
+        { label: "Poll votes", value: entry.pollVotes?.join(", ") || "—" },
+        { label: "Reviewed by", value: entry.reviewedBy ?? "—" },
+        { label: "Review note", value: entry.reviewNote ?? "—" },
+        { label: "Entry ID", value: entry.id },
+    ];
+}

package/dist/features/faq/components/ContactCTA.js

@@ -3,7 +3,7 @@ import { Card, Div, Heading, Row, Span, Text, TextLink } from "../../../ui";
 const __P = {
     p8: "p-[var(--appkit-space-8)]",
 };
-const CLS_CONTACT_CARD = "flex items-center gap-[var(--appkit-space-3)] rounded-lg border border-zinc-100 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-elevated)] px-[var(--appkit-space-4)] py-[var(--appkit-space-3)] hover:border-primary/40 transition-colors";
+const CLS_CONTACT_CARD = "flex items-center gap-[var(--appkit-space-3)] rounded-lg border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-elevated)] px-[var(--appkit-space-4)] py-[var(--appkit-space-3)] hover:border-primary/40 transition-colors";
 const CLS_CONTACT_LABEL = "text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)]";
 export function ContactCTA({ email, phone, contactHref, labels, }) {
     return (_jsxs(Card, { variant: "outlined", padding: "lg", className: "text-center", children: [_jsx(Row, { className: "mb-6", justify: "center", children: _jsx(Div, { className: `bg-primary/10 ${__P.p8}`, rounded: "full", children: _jsx("svg", { className: "h-12 w-12 text-primary", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M3 8l7.89 5.26a2 2 0 002.22 0L21 8M5 19h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z" }) }) }) }), _jsx(Heading, { level: 2, className: "mb-3", size: "2xl", weight: "semibold", children: labels?.title ?? "Need More Help?" }), _jsx(Text, { className: "mx-auto mb-6 max-w-2xl", color: "muted", children: labels?.description ?? "Our support team is here to help you." }), _jsxs(Div, { layout: "grid", gap: "4", className: "mb-8 grid-cols-1 md:grid-cols-3", children: [_jsxs(TextLink, { href: `mailto:${email}`, variant: "none", className: CLS_CONTACT_CARD, children: [_jsx(Text, { className: CLS_CONTACT_LABEL, children: labels?.emailUs ?? "Email Us" }), _jsx(Text, { size: "xs", color: "muted", children: email })] }), _jsxs(TextLink, { href: `tel:${phone}`, variant: "none", className: CLS_CONTACT_CARD, children: [_jsx(Text, { className: CLS_CONTACT_LABEL, children: labels?.callUs ?? "Call Us" }), _jsx(Text, { size: "xs", color: "muted", children: phone })] }), _jsxs(TextLink, { href: contactHref, className: CLS_CONTACT_CARD, children: [_jsx(Text, { className: CLS_CONTACT_LABEL, children: labels?.contactForm ?? "Contact Form" }), _jsx(Text, { size: "xs", color: "muted", children: labels?.submitRequest ?? "Submit a request" })] })] }), _jsxs(TextLink, { rounded: "xl", href: contactHref, layout: "inline-flex", align: "center", gap: "sm", className: "bg-primary p-[1.5rem] text-white transition-colors hover:bg-primary/90", weight: "medium", children: [_jsx(Span, { children: labels?.contactTeam ?? "Contact Team" }), _jsx("svg", { className: "h-5 w-5", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M9 5l7 7-7 7" }) })] })] }));

package/dist/features/faq/components/FAQHelpfulButtons.js

@@ -44,9 +44,9 @@ export function FAQHelpfulButtons({ faqId, initialHelpful, initialNotHelpful, on
                             ? "bg-success-solid text-success-on-solid"
                             : userVote
                                 ? "cursor-not-allowed bg-zinc-200 text-[var(--appkit-color-text-muted)] opacity-50 dark:bg-slate-600 text-[var(--appkit-color-text-muted)]"
-                                : "bg-[var(--appkit-color-surface)] text-zinc-800 hover:bg-green-50 bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)] dark:hover:bg-green-900/20"}`, children: [_jsx(Span, { size: "sm", children: labels?.yes ?? "Yes" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", helpful, ")"] })] }), _jsxs(Button, { variant: "ghost", onClick: () => handleVote(false), disabled: isPending || userVote !== null, className: `flex-1 gap-[var(--appkit-space-2)] rounded-lg p-[var(--appkit-space-4)] transition-all ${userVote === "not-helpful"
+                                : "bg-[var(--appkit-color-surface)] hover:bg-success-surface bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)]"}`, children: [_jsx(Span, { size: "sm", children: labels?.yes ?? "Yes" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", helpful, ")"] })] }), _jsxs(Button, { variant: "ghost", onClick: () => handleVote(false), disabled: isPending || userVote !== null, className: `flex-1 gap-[var(--appkit-space-2)] rounded-lg p-[var(--appkit-space-4)] transition-all ${userVote === "not-helpful"
                             ? "bg-error-solid text-error-on-solid"
                             : userVote
                                 ? "cursor-not-allowed bg-zinc-200 text-[var(--appkit-color-text-muted)] opacity-50 dark:bg-slate-600 text-[var(--appkit-color-text-muted)]"
-                                : "bg-[var(--appkit-color-surface)] text-zinc-800 hover:bg-red-50 bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)] dark:hover:bg-red-900/20"}`, children: [_jsx(Span, { size: "sm", children: labels?.no ?? "No" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", notHelpful, ")"] })] })] })] }));
+                                : "bg-[var(--appkit-color-surface)] hover:bg-error-surface bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)]"}`, children: [_jsx(Span, { size: "sm", children: labels?.no ?? "No" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", notHelpful, ")"] })] })] })] }));
 }

package/dist/features/faq/repository/faqs.repository.d.ts

@@ -15,10 +15,25 @@ export declare class FAQsRepository {
     update(id: string, data: Partial<FAQ>): Promise<FAQ>;
     delete(id: string): Promise<void>;
 }
+/**
+ * FAQ `searchTxt`. Exported so the seed derives byte-identical tokens — the
+ * seed writes documents raw via batch.set() and never goes through this
+ * repository, which is exactly why all 63 seeded FAQs had no tokens at all.
+ *
+ * EVERY field is prefix-expanded, including the answer body. An earlier version
+ * whole-worded the body to protect the token budget, and a seed test caught what
+ * that costs: searching "ship" returned FEWER FAQs than "shipping", because an
+ * answer mentioning shipping had only the whole word indexed. Partial match that
+ * silently excludes the body is not partial match.
+ *
+ * Measured over the real seed corpus: max 449 tokens, average 200, nothing near
+ * the 600 cap — so nothing is truncated. Re-measure before reusing this shape on
+ * a long-form collection (blog posts), where bodies are far larger.
+ */
+export declare function buildFaqSearchTxt(input: Partial<FAQDocument>): string[];
 export declare class FirebaseFAQsRepository extends BaseRepository<FAQDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    private buildSearchTokens;
     create(data: Partial<FAQDocument>): Promise<FAQDocument>;
     update(id: string, data: Partial<FAQDocument>): Promise<FAQDocument>;
     list(model: SieveModel, opts?: {

package/dist/features/faq/repository/faqs.repository.js

@@ -2,6 +2,7 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { DatabaseError } from "../../../errors";
 import { increment } from "../../../contracts/field-ops";
 import { FAQ_FIELDS } from "../../../constants/field-names";
+import { buildSearchTxt, matchesAllSearchTerms, parseSearchTxtQuery, } from "../../../utils/search-txt";
 import { FAQS_COLLECTION, createFAQId, slugifyQuestion, } from "../schemas";
 export class FAQsRepository {
     constructor(repo) {
@@ -51,38 +52,39 @@ export class FAQsRepository {
         return this.repo.delete(id);
     }
 }
+/**
+ * FAQ `searchTxt`. Exported so the seed derives byte-identical tokens — the
+ * seed writes documents raw via batch.set() and never goes through this
+ * repository, which is exactly why all 63 seeded FAQs had no tokens at all.
+ *
+ * EVERY field is prefix-expanded, including the answer body. An earlier version
+ * whole-worded the body to protect the token budget, and a seed test caught what
+ * that costs: searching "ship" returned FEWER FAQs than "shipping", because an
+ * answer mentioning shipping had only the whole word indexed. Partial match that
+ * silently excludes the body is not partial match.
+ *
+ * Measured over the real seed corpus: max 449 tokens, average 200, nothing near
+ * the 600 cap — so nothing is truncated. Re-measure before reusing this shape on
+ * a long-form collection (blog posts), where bodies are far larger.
+ */
+export function buildFaqSearchTxt(input) {
+    const answer = typeof input.answer === "string" ? input.answer : (input.answer?.text ?? "");
+    return buildSearchTxt([
+        input.question,
+        input.category,
+        ...(input.tags ?? []),
+        answer.replace(/<[^>]+>/g, " "),
+    ]);
+}
 export class FirebaseFAQsRepository extends BaseRepository {
     constructor() {
         super(FAQS_COLLECTION);
     }
-    buildSearchTokens(input) {
-        const rawText = [
-            input.question,
-            typeof input.answer === "string" ? input.answer : input.answer?.text,
-            input.category,
-            ...(input.tags ?? []),
-        ]
-            .filter(Boolean)
-            .join(" ")
-            .toLowerCase();
-        return Array.from(new Set(rawText
-            .split(/[^a-z0-9]+/i)
-            .map((token) => token.trim())
-            .filter((token) => token.length >= 2))).slice(0, 50);
-    }
     async create(data) {
-        const searchTokens = this.buildSearchTokens({
-            question: data.question ?? "",
-            answer: data.answer ?? {
-                text: "",
-                format: "plain",
-            },
-            tags: data.tags ?? [],
-            category: (data.category ?? "general"),
-        });
+        const searchTxt = buildFaqSearchTxt(data);
         return super.create({
             ...data,
-            searchTokens,
+            searchTxt,
         });
     }
     async update(id, data) {
@@ -96,39 +98,52 @@ export class FirebaseFAQsRepository extends BaseRepository {
         };
         return super.update(id, {
             ...data,
-            searchTokens: this.buildSearchTokens({
-                question: merged.question,
-                answer: merged.answer,
-                tags: merged.tags ?? [],
-                category: merged.category,
-            }),
+            searchTxt: buildFaqSearchTxt(merged),
         });
     }
     async list(model, opts) {
         let baseQuery = this.getCollection();
         const tags = opts?.tags?.filter(Boolean) ?? [];
-        const searchTokens = (opts?.search ?? "")
-            .toLowerCase()
-            .split(/[^a-z0-9]+/i)
-            .map((token) => token.trim())
-            .filter((token) => token.length >= 2)
-            .slice(0, 10);
-        if (tags.length > 0 && searchTokens.length > 0) {
-            throw new DatabaseError("Combining FAQ tag filters and token search requires a dedicated search index");
+        // Longest term first — only ONE may become the array-contains clause
+        // (Firestore permits a single array operator per query), and the longest is
+        // the cheapest proxy for "narrows the most" without cardinality stats.
+        const terms = parseSearchTxtQuery(opts?.search ?? "");
+        const rawSearch = (opts?.search ?? "").trim();
+        // A query that produced no usable term must return NOTHING, not everything.
+        // The old guard dropped tokens under 2 characters, so a 1-character search
+        // silently fell through to the entire unfiltered list.
+        if (rawSearch && terms.length === 0) {
+            return { items: [], total: 0, page: 1, pageSize: 0, totalPages: 0, hasMore: false };
         }
-        if (tags.length === 1) {
+        // Firestore allows one array operator per query, so tags and search cannot
+        // both be pushed down. Search takes the clause and tags refine in memory —
+        // this used to throw a DatabaseError and fail the request outright.
+        const pushTags = terms.length === 0;
+        if (pushTags && tags.length === 1) {
             baseQuery = baseQuery.where(FAQ_FIELDS.TAGS, "array-contains", tags[0]);
         }
-        else if (tags.length > 1) {
+        else if (pushTags && tags.length > 1) {
             baseQuery = baseQuery.where(FAQ_FIELDS.TAGS, "array-contains-any", tags.slice(0, 10));
         }
-        if (searchTokens.length === 1) {
-            baseQuery = baseQuery.where(FAQ_FIELDS.SEARCH_TOKENS, "array-contains", searchTokens[0]);
+        if (terms.length > 0) {
+            baseQuery = baseQuery.where(FAQ_FIELDS.SEARCH_TXT, "array-contains", terms[0]);
         }
-        else if (searchTokens.length > 1) {
-            baseQuery = baseQuery.where(FAQ_FIELDS.SEARCH_TOKENS, "array-contains-any", searchTokens);
-        }
-        return this.sieveQuery(model, FirebaseFAQsRepository.SIEVE_FIELDS, { baseQuery });
+        const result = await this.sieveQuery(model, FirebaseFAQsRepository.SIEVE_FIELDS, { baseQuery });
+        // Refine the remaining terms (AND) and any tags that could not be pushed
+        // down. `array-contains-any` would have been OR — "shipping cost" returning
+        // everything matching either word is why search felt like it did nothing.
+        const extraTerms = terms.slice(1);
+        if (extraTerms.length === 0 && (pushTags || tags.length === 0))
+            return result;
+        const items = result.items.filter((faq) => matchesAllSearchTerms(faq.searchTxt, extraTerms) &&
+            (pushTags || tags.length === 0 || tags.some((t) => faq.tags?.includes(t))));
+        return {
+            ...result,
+            items,
+            total: items.length,
+            totalPages: items.length === 0 ? 0 : 1,
+            hasMore: false,
+        };
     }
     async getFAQBySlug(slug) {
         const snapshot = await this.db
@@ -248,12 +263,7 @@ export class FirebaseFAQsRepository extends BaseRepository {
                 ...input.seo,
                 slug,
             },
-            searchTokens: this.buildSearchTokens({
-                question: input.question,
-                answer: input.answer,
-                tags: input.tags ?? [],
-                category: input.category,
-            }),
+            searchTxt: buildFaqSearchTxt(input),
             stats: {
                 views: 0,
                 helpful: 0,
@@ -293,7 +303,7 @@ FirebaseFAQsRepository.SIEVE_FIELDS = {
     order: { canFilter: true, canSort: true },
     priority: { canFilter: true, canSort: true },
     tags: { canFilter: true, canSort: false },
-    searchTokens: { canFilter: true, canSort: false },
+    searchTxt: { canFilter: true, canSort: false },
     "stats.helpful": { canFilter: false, canSort: true },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
 };

package/dist/features/faq/schemas/firestore.d.ts

@@ -19,7 +19,8 @@ export interface FAQDocument extends BaseDocument {
     order: number;
     priority: number;
     tags: string[];
-    searchTokens?: string[];
+    /** Normalized edge-n-gram search field. Replaced `searchTokens`. */
+    searchTxt?: string[];
     relatedFAQs: string[];
     useSiteSettings: boolean;
     variables?: Record<string, string>;
@@ -31,7 +32,7 @@ export interface FAQDocument extends BaseDocument {
     createdBy: string;
 }
 export declare const FAQS_COLLECTION: "faqs";
-export declare const FAQS_INDEXED_FIELDS: readonly ["slug", "seo.slug", "category", "order", "showOnHomepage", "showInFooter", "isPinned", "priority", "tags", "searchTokens", "isActive", "stats.helpful", "createdBy", "createdAt"];
+export declare const FAQS_INDEXED_FIELDS: readonly ["slug", "seo.slug", "category", "order", "showOnHomepage", "showInFooter", "isPinned", "priority", "tags", "searchTxt", "isActive", "stats.helpful", "createdBy", "createdAt"];
 export declare const FAQ_CATEGORY_LABELS: Record<FAQCategory, string>;
 export declare const DEFAULT_FAQ_DATA: Partial<FAQDocument>;
 export declare const FAQS_PUBLIC_FIELDS: readonly ["id", "question", "answer", "category", "showOnHomepage", "showInFooter", "isPinned", "order", "priority", "tags", "relatedFAQs", "stats.views", "stats.helpful", "stats.notHelpful", "seo.slug", "seo.metaTitle", "seo.metaDescription", "isActive", "createdAt"];

package/dist/features/faq/schemas/firestore.js

@@ -13,7 +13,7 @@ export const FAQS_INDEXED_FIELDS = [
     "isPinned",
     "priority",
     "tags",
-    "searchTokens",
+    "searchTxt",
     "isActive",
     "stats.helpful",
     "createdBy",
@@ -36,7 +36,7 @@ export const DEFAULT_FAQ_DATA = {
     order: 0,
     priority: 0,
     tags: [],
-    searchTokens: [],
+    searchTxt: [],
     relatedFAQs: [],
     useSiteSettings: true,
     variables: {},

package/dist/features/faq/schemas/index.d.ts

@@ -228,7 +228,7 @@ export declare const faqFirestoreSchema: z.ZodObject<{
     order: z.ZodNumber;
     priority: z.ZodNumber;
     tags: z.ZodArray<z.ZodString, "many">;
-    searchTokens: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    searchTxt: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     relatedFAQs: z.ZodArray<z.ZodString, "many">;
     useSiteSettings: z.ZodBoolean;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -310,7 +310,7 @@ export declare const faqFirestoreSchema: z.ZodObject<{
         metaTitle?: string | undefined;
         metaDescription?: string | undefined;
     };
-    searchTokens?: string[] | undefined;
+    searchTxt?: string[] | undefined;
     variables?: Record<string, string> | undefined;
 }, {
     id: string;
@@ -349,7 +349,7 @@ export declare const faqFirestoreSchema: z.ZodObject<{
         metaTitle?: string | undefined;
         metaDescription?: string | undefined;
     };
-    searchTokens?: string[] | undefined;
+    searchTxt?: string[] | undefined;
     variables?: Record<string, string> | undefined;
 }>;
 export type FAQFromSchema = z.infer<typeof faqFirestoreSchema>;