@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/features/blog/columns/index.js

@@ -25,6 +25,11 @@ export const blogAdminColumns = [
         header: "Featured",
         render: (p) => (p.isFeatured ? "Yes" : "No"),
     },
+    {
+        key: "isPinned",
+        header: "Pinned",
+        render: (p) => (p.isPinned ? "Yes" : "No"),
+    },
     {
         key: "readTimeMinutes",
         header: "Read Time",

package/dist/features/blog/components/BlogIndexPageView.js

@@ -3,6 +3,7 @@ import { blogRepository } from "../../../repositories/index.js";
 import { Container, Heading, Main, Section } from "../../../ui/index.js";
 import { AdSlot } from "../../homepage/components/AdSlot.js";
 import { BlogIndexListing } from "./BlogIndexListing.js";
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
 function sp(params, key) {
@@ -10,7 +11,7 @@ function sp(params, key) {
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
 }
 export async function BlogIndexPageView({ searchParams = {} }) {
-    const sort = sp(searchParams, "sort") || "-publishedAt";
+    const sort = sp(searchParams, "sort") || BLOG_DEFAULT_PUBLIC_SORT;
     const page = Number(sp(searchParams, "page")) || 1;
     const pageSize = Number(sp(searchParams, "pageSize")) || 24;
     const category = sp(searchParams, "category");

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

@@ -55,6 +55,10 @@ declare class BlogRepository extends BaseRepository<BlogPostDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        isPinned: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         readTimeMinutes: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/blog/repository/blog.repository.js

@@ -223,6 +223,11 @@ BlogRepository.SIEVE_FIELDS = {
     authorName: { canFilter: true, canSort: true },
     authorId: { canFilter: true, canSort: false },
     isFeatured: { canFilter: true, canSort: false },
+    // canSort because it is the FIRST key of the default sort
+    // `-isPinned,-publishedAt`. A `canSort: false` field is silently dropped by
+    // sievejs (Root Cause #63), which would leave the index ordered by date
+    // alone and the pin doing nothing, with no error anywhere.
+    isPinned: { canFilter: true, canSort: true },
     readTimeMinutes: { canFilter: true, canSort: true },
     views: { canFilter: true, canSort: true },
     publishedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },

package/dist/features/blog/schemas/blog-form.d.ts

@@ -47,6 +47,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     publishedAt: z.ZodString;
     authorName: z.ZodString;
     isFeatured: z.ZodBoolean;
+    isPinned: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
     status: "published" | "draft" | "archived";
     title: string;
@@ -60,6 +61,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     excerpt: string;
     coverImage: string;
     authorName: string;
+    isPinned: boolean;
     metaTitle: string;
     metaDescription: string;
 }, {
@@ -75,6 +77,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     excerpt: string;
     coverImage: string;
     authorName: string;
+    isPinned: boolean;
     metaTitle: string;
     metaDescription: string;
 }>;

package/dist/features/blog/schemas/blog-form.js

@@ -97,4 +97,5 @@ export const blogDraftSchema = z.object({
     }),
     authorName: annotate(z.string(), { section: "publish", order: 3, row: "pair" }),
     isFeatured: annotate(z.boolean(), { section: "publish", order: 4, row: "quarter" }),
+    isPinned: annotate(z.boolean(), { section: "publish", order: 5, row: "quarter" }),
 });

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

@@ -29,6 +29,23 @@ export interface BlogPostDocument extends BaseDocument {
     category: BlogPostCategory;
     tags: string[];
     isFeatured: boolean;
+    /**
+     * Keeps the post at the top of the blog index and the homepage
+     * `blog-articles` section, above newer posts.
+     *
+     * 🛑 REQUIRED, not optional, and that is load-bearing. The default sort is
+     * `-isPinned,-publishedAt`, and Firestore EXCLUDES a document that lacks an
+     * `orderBy` field (Root Cause #100) — so an optional `isPinned` would drop
+     * every pre-existing post out of its own index, silently, with a 200.
+     * A `mapDoc` default cannot rescue it either: that is a read-side fixup and
+     * a query never sees it (Root Cause #101). Every row needs a real `false`
+     * written, which is why the seed carries it explicitly.
+     *
+     * Distinct from `isFeatured` on purpose: featured drives the badge and the
+     * featured-card treatment, and there are several featured posts. Overloading
+     * it would make "featured" and "first" the same decision.
+     */
+    isPinned: boolean;
     status: BlogPostStatus;
     publishedAt?: Date;
     authorId: string;
@@ -40,7 +57,25 @@ export interface BlogPostDocument extends BaseDocument {
     metaDescription?: string;
 }
 export declare const BLOG_POSTS_COLLECTION: "blogPosts";
-export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "category", "slug"];
+export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "isPinned", "category", "slug"];
+/**
+ * The default ordering for every PUBLIC blog surface — the `/blog` index, the
+ * `/api/blog` route that refetches it, and the homepage `blog-articles` feed.
+ *
+ * 🛑 ONE constant, three consumers, deliberately. The SSR view hands its result
+ * to the listing hook as `initialData`, and that hook sets `staleTime: Infinity`
+ * when given SSR data — so if the route's default sort differed from the view's
+ * by even a character, the first paint would be frozen in one order while the
+ * query key described another (Root Cause #30). Three literals is how that
+ * drift happens; one import is how it cannot.
+ *
+ * `isPinned` leads so pinned posts sit above newer ones. Needs the composite
+ * indexes on (status, isPinned DESC, publishedAt DESC) and its category /
+ * isFeatured / searchTxt variants — a multi-field sieve sort becomes two
+ * `orderBy` calls, and a missing index is a silent FAILED_PRECONDITION that
+ * every caller swallows into an empty page (Root Cause #2 / #59).
+ */
+export declare const BLOG_DEFAULT_PUBLIC_SORT: "-isPinned,-publishedAt";
 export declare const BLOG_POST_FIELDS: {
     /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
     readonly SEARCH_TXT: "searchTxt";
@@ -56,6 +91,7 @@ export declare const BLOG_POST_FIELDS: {
     readonly CATEGORY: "category";
     readonly TAGS: "tags";
     readonly IS_FEATURED: "isFeatured";
+    readonly IS_PINNED: "isPinned";
     readonly STATUS: "status";
     readonly PUBLISHED_AT: "publishedAt";
     readonly AUTHOR_ID: "authorId";
@@ -89,6 +125,7 @@ export type BlogPostUpdateInput = Partial<Omit<BlogPostDocument, "id" | "created
 export declare const blogPostQueryHelpers: {
     readonly published: () => readonly ["status", "==", BlogPostStatus];
     readonly featured: () => readonly ["isFeatured", "==", true];
+    readonly pinned: () => readonly ["isPinned", "==", true];
     readonly byCategory: (category: BlogPostCategory) => readonly ["category", "==", BlogPostCategory];
     readonly bySlug: (slug: string) => readonly ["slug", "==", string];
     readonly byAuthor: (authorId: string) => readonly ["authorId", "==", string];

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

@@ -14,9 +14,28 @@ export const BLOG_POSTS_INDEXED_FIELDS = [
     "status",
     "publishedAt",
     "isFeatured",
+    "isPinned",
     "category",
     "slug",
 ];
+/**
+ * The default ordering for every PUBLIC blog surface — the `/blog` index, the
+ * `/api/blog` route that refetches it, and the homepage `blog-articles` feed.
+ *
+ * 🛑 ONE constant, three consumers, deliberately. The SSR view hands its result
+ * to the listing hook as `initialData`, and that hook sets `staleTime: Infinity`
+ * when given SSR data — so if the route's default sort differed from the view's
+ * by even a character, the first paint would be frozen in one order while the
+ * query key described another (Root Cause #30). Three literals is how that
+ * drift happens; one import is how it cannot.
+ *
+ * `isPinned` leads so pinned posts sit above newer ones. Needs the composite
+ * indexes on (status, isPinned DESC, publishedAt DESC) and its category /
+ * isFeatured / searchTxt variants — a multi-field sieve sort becomes two
+ * `orderBy` calls, and a missing index is a silent FAILED_PRECONDITION that
+ * every caller swallows into an empty page (Root Cause #2 / #59).
+ */
+export const BLOG_DEFAULT_PUBLIC_SORT = "-isPinned,-publishedAt";
 export const BLOG_POST_FIELDS = {
     /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
     SEARCH_TXT: "searchTxt",
@@ -32,6 +51,7 @@ export const BLOG_POST_FIELDS = {
     CATEGORY: "category",
     TAGS: "tags",
     IS_FEATURED: "isFeatured",
+    IS_PINNED: "isPinned",
     STATUS: "status",
     PUBLISHED_AT: "publishedAt",
     AUTHOR_ID: "authorId",
@@ -64,6 +84,7 @@ export const DEFAULT_BLOG_POST_DATA = {
     category: "news",
     tags: [],
     isFeatured: false,
+    isPinned: false,
     status: "draft",
     authorId: "",
     authorName: "",
@@ -80,6 +101,7 @@ export const BLOG_POST_PUBLIC_FIELDS = [
     "category",
     "tags",
     "isFeatured",
+    "isPinned",
     "status",
     "publishedAt",
     "authorName",
@@ -94,6 +116,7 @@ export const BLOG_POST_PUBLIC_FIELDS = [
 export const blogPostQueryHelpers = {
     published: () => ["status", "==", "published"],
     featured: () => ["isFeatured", "==", true],
+    pinned: () => ["isPinned", "==", true],
     byCategory: (category) => ["category", "==", category],
     bySlug: (slug) => ["slug", "==", slug],
     byAuthor: (authorId) => ["authorId", "==", authorId],

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

@@ -99,6 +99,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     category: z.ZodString;
     tags: z.ZodArray<z.ZodString, "many">;
     isFeatured: z.ZodBoolean;
+    isPinned: z.ZodBoolean;
     status: z.ZodEnum<["draft", "published", "archived"]>;
     publishedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -134,6 +135,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     authorId: string;
     authorName: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     publishedAt?: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -187,6 +189,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     authorId: string;
     authorName: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     publishedAt?: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -343,6 +346,7 @@ export declare const blogPostSchema: z.ZodObject<{
     category: z.ZodEnum<["news", "tips", "guides", "updates", "community"]>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     isFeatured: z.ZodOptional<z.ZodBoolean>;
+    isPinned: z.ZodOptional<z.ZodBoolean>;
     status: z.ZodEnum<["draft", "published", "archived"]>;
     publishedAt: z.ZodOptional<z.ZodString>;
     authorId: z.ZodOptional<z.ZodString>;
@@ -401,6 +405,7 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     authorAvatar?: string | undefined;
     metaTitle?: string | undefined;
     metaDescription?: string | undefined;
@@ -430,6 +435,7 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;

package/dist/features/blog/schemas/index.js

@@ -18,6 +18,7 @@ export const blogPostFirestoreSchema = z.object({
     category: z.string(),
     tags: z.array(z.string()),
     isFeatured: z.boolean(),
+    isPinned: z.boolean(),
     status: blogPostStatusEnumSchema,
     publishedAt: firestoreDateSchema.optional(),
     authorId: z.string(),
@@ -72,6 +73,7 @@ export const blogPostSchema = z.object({
     category: blogPostCategorySchema,
     tags: z.array(z.string()).optional(),
     isFeatured: z.boolean().optional(),
+    isPinned: z.boolean().optional(),
     status: blogPostStatusSchema,
     publishedAt: z.string().optional(),
     authorId: z.string().optional(),

package/dist/features/blog/types/index.d.ts

@@ -15,6 +15,8 @@ export interface BlogPost {
     category: BlogPostCategory;
     tags?: string[];
     isFeatured?: boolean;
+    /** Keeps the post above newer ones on the blog index and homepage. */
+    isPinned?: boolean;
     status: BlogPostStatus;
     publishedAt?: string;
     authorId?: string;

package/dist/features/cart/components/CartPriceBreakdown.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { FeeDerivations } from "../../../_internal/shared/fees/explain";
 /**
  * The aggregate price breakdown shown in the cart's expandable preview and in
  * the checkout Order Summary.
@@ -86,5 +87,15 @@ export interface CartPriceBreakdownProps {
     errorNote?: React.ReactNode;
     isLoading?: boolean;
     className?: string;
+    /**
+     * Per-line "why am I paying this" disclosures, built by the
+     * `explain*` helpers in `_internal/shared/fees/explain`.
+     *
+     * 🛑 Optional, and an absent entry renders no disclosure rather than a
+     * placeholder. The cart renders this breakdown for a signed-out guest with
+     * no server preview at all — a line that cannot be explained must say
+     * nothing, never "we could not work this out", which reads as a fault.
+     */
+    derivations?: FeeDerivations;
 }
-export declare function CartPriceBreakdown({ preview, itemCount, currency, unavailableNote, fallbackSubtotal, errorNote, isLoading, className, }: CartPriceBreakdownProps): React.JSX.Element;
+export declare function CartPriceBreakdown({ preview, itemCount, currency, unavailableNote, fallbackSubtotal, errorNote, isLoading, className, derivations, }: CartPriceBreakdownProps): React.JSX.Element;

package/dist/features/cart/components/CartPriceBreakdown.js

@@ -1,15 +1,34 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { Details, Div, Row, Stack, Summary, Text } from "../../../ui/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
-function Line({ label, amount, tone = "muted", strong = false, }) {
-    return (_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "min-w-0", truncate: 1, children: label }), _jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "flex-shrink-0 tabular-nums", children: amount })] }));
+/**
+ * The "how is this calculated?" disclosure under a fee line.
+ *
+ * 🛑 Collapsed by default, and that is the whole design. An unexplained charge
+ * is untrustworthy, but five expanded derivations turn the Order Summary into
+ * a wall of arithmetic at the moment a buyer is deciding to pay. The
+ * obligation is that the answer is *available at the point of the charge* —
+ * not that it is shouted.
+ *
+ * A native `<details>` rather than a tooltip or a modal: it works before
+ * hydration, it is keyboard-reachable for free, and it does not cover the
+ * number it is explaining.
+ */
+function Derivation({ derivation }) {
+    return (_jsxs(Details, { tone: "muted", padding: "sm", rounded: "md", children: [_jsx(Summary, { size: "xs", color: "muted", children: "How is this calculated?" }), _jsxs(Stack, { gap: "xs", className: "pt-[var(--appkit-space-2)]", children: [_jsx(Text, { size: "xs", color: "muted", children: derivation.summary }), derivation.steps.map((step, i) => (_jsx(Text, { size: "xs", color: "faint", className: "tabular-nums", children: step }, i)))] })] }));
+}
+function Line({ label, amount, tone = "muted", strong = false, derivation, }) {
+    const row = (_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "min-w-0", truncate: 1, children: label }), _jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "flex-shrink-0 tabular-nums", children: amount })] }));
+    if (!derivation)
+        return row;
+    return (_jsxs(Stack, { gap: "xs", children: [row, _jsx(Derivation, { derivation: derivation })] }));
 }
 /** "Shipping (2 stores)" — only qualifies when more than one store contributes. */
 function withStoreCount(label, count) {
     return count > 1 ? `${label} (${count} stores)` : label;
 }
-export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unavailableNote, fallbackSubtotal = 0, errorNote, isLoading = false, className = "", }) {
+export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unavailableNote, fallbackSubtotal = 0, errorNote, isLoading = false, className = "", derivations, }) {
     const money = (value) => formatCurrency(value, currency);
     if (!preview) {
         return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: itemCount !== undefined ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""})` : "Subtotal", amount: money(fallbackSubtotal) }), (errorNote ?? unavailableNote) && (_jsx(Text, { size: "xs", color: errorNote ? "error" : "muted", children: errorNote ?? unavailableNote }))] }));
@@ -21,7 +40,7 @@ export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unava
     const subtotalLabel = itemCount !== undefined
         ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""}${storeCount > 1 ? `, ${storeCount} stores` : ""})`
         : "Subtotal";
-    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
+    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee), derivation: derivations?.codHandlingFee })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge), derivation: derivations?.emiSurcharge })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && (_jsx(Line, { label: "Platform fee", amount: money(preview.platformFee), derivation: derivations?.platformFee })), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee), derivation: derivations?.gstOnFee })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
                     ? "Your points could not be applied to this order."
                     : storeCount > 1
                         ? "None of these sellers accepts points."

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

@@ -147,6 +147,20 @@ export declare class CartRepository extends BaseRepository<CartDocument> {
      * and keeping both shapes invites a reader that handles only one. Same
      * reasoning as `setStoreAddons` directly above.
      */
+    /**
+     * Set or clear the instalment plan.
+     *
+     * 🛑 `null` DELETES the field rather than storing `{ optIn: false }`. The
+     * schema's rule is that absent means "no instalments", so a second
+     * representation of the same state is one more thing every reader has to
+     * get right (Root Cause #42's shape). `tenureMonths` is stored verbatim and
+     * validated against the live `emi.tenureOptions` at order time — the admin
+     * can change those options after a cart was saved, so validating here would
+     * freeze a tenure that is no longer offered.
+     */
+    setEmiPlan(userId: string, plan: {
+        tenureMonths: number;
+    } | null): Promise<void>;
     setUseAllPoints(userId: string, useAllPoints: boolean): Promise<void>;
     /**
      * Cloud Functions: return refs of stale carts not updated within TTL.

package/dist/features/cart/repository/cart.repository.js

@@ -608,6 +608,26 @@ export class CartRepository extends BaseRepository {
      * and keeping both shapes invites a reader that handles only one. Same
      * reasoning as `setStoreAddons` directly above.
      */
+    /**
+     * Set or clear the instalment plan.
+     *
+     * 🛑 `null` DELETES the field rather than storing `{ optIn: false }`. The
+     * schema's rule is that absent means "no instalments", so a second
+     * representation of the same state is one more thing every reader has to
+     * get right (Root Cause #42's shape). `tenureMonths` is stored verbatim and
+     * validated against the live `emi.tenureOptions` at order time — the admin
+     * can change those options after a cart was saved, so validating here would
+     * freeze a tenure that is no longer offered.
+     */
+    async setEmiPlan(userId, plan) {
+        await this.db
+            .collection(this.collection)
+            .doc(userId)
+            .set({
+            emiPlan: plan ? { tenureMonths: plan.tenureMonths } : FieldValue.delete(),
+            updatedAt: new Date(),
+        }, { merge: true });
+    }
     async setUseAllPoints(userId, useAllPoints) {
         await this.db
             .collection(this.collection)

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

@@ -331,6 +331,30 @@ export interface CartDocument extends BaseDocument {
      * (D46). A number was the wrong shape as well as the wrong place.
      */
     useAllPoints?: boolean;
+    /**
+     * "Pay in instalments", with the chosen tenure — an opt-in ON THE ORDER,
+     * orthogonal to how the token is tendered.
+     *
+     * 🛑 It lives HERE, on the cart, for exactly the reason `storeAddons` does:
+     * the online path creates the gateway order in one request
+     * (`/api/payment/create-order`, which decides the CAPTURE amount) and the
+     * order document in a later one (`/api/payment/verify`). A choice carried in
+     * a request body cannot be read by both, so the two would be free to
+     * disagree about how much of the total is deferred — and the difference is
+     * money captured that the order does not record (the D37/D38/D40 class).
+     *
+     * `useAllPoints` is the precedent and the shape is deliberately the same: a
+     * durable selection the server re-reads, never a client-supplied amount.
+     *
+     * Absent means a plain full-price order, which is why it is written with
+     * `FieldValue.delete()` rather than `{ optIn: false }` — a stored false and
+     * an absent field must not be two ways of saying the same thing.
+     */
+    emiPlan?: CartEmiPlan;
+}
+/** The buyer's instalment selection. `tenureMonths` is validated against the live `emi.tenureOptions` at order time, never here. */
+export interface CartEmiPlan {
+    tenureMonths: number;
 }
 export declare const CART_COLLECTION: "carts";
 export declare const CART_INDEXED_FIELDS: string[];

package/dist/features/dashboard/components/DashboardHubView.d.ts

@@ -0,0 +1,83 @@
+import React from "react";
+import type { AttentionCounts } from "../../../_internal/server/features/dashboard/attention";
+import type { DashboardHubSection } from "../../../_internal/shared/features/dashboard/hub-sections";
+/**
+ * The dashboard hub — one component, two modes, zero copy of its own.
+ *
+ * ## Why one component and not two
+ *
+ * A landing page lists SECTIONS; a section hub lists SCREENS. Those read as
+ * two features and are one: a grid of link cards, each with a title, a
+ * sentence about what it is for, and an optional count of things waiting. Same
+ * prop surface, same renderer — which the Duplication Framework calls a
+ * consolidate-on-sight ("copies accept the same parameters and return the same
+ * shape"), not a Rule-of-Three wait.
+ *
+ * The thing it must not become is `AdminGuideHubView`, which is the visual
+ * pattern here and hand-writes its own 13-card list — so a guide added to the
+ * nav never appears on it. Every card below comes from a nav item's existing
+ * `label` and `description`.
+ *
+ * ## Not a client component
+ *
+ * It takes plain data and renders. No hook, no fetch, no `"use client"` — the
+ * page that mounts it is already per-request (its layout reads the session), so
+ * the counts arrive with the render rather than costing a second invocation
+ * after it. See `_internal/server/features/dashboard/data.ts`.
+ *
+ * ## No icons, on purpose
+ *
+ * A nav item carries no `iconKey`, so icons would mean a hand-written map of
+ * 22 sections or ~130 screens — a second list to drift from the first, which is
+ * the whole defect this feature exists to avoid (Root Cause #61). The section
+ * heading plus the card's own sentence is the distinction; `<Badge>` carries
+ * the only signal that needs to catch the eye.
+ */
+export interface DashboardHubViewProps {
+    /**
+     * Page heading. Omit when the grid is embedded in a page that already has
+     * one — `/store` renders it inside a `CollapsibleSection`, and a second
+     * `<h1>` mid-page breaks the heading outline for a screen reader.
+     */
+    title?: string;
+    /** One sentence under the heading. Only rendered alongside a `title`. */
+    description?: string;
+    /**
+     * What to render.
+     *
+     * - `"sections"` — one card per section, linking to its hub. The landing page.
+     * - `"screens"` — one card per screen in `sections[0]`. A section hub.
+     *
+     * 🛑 A hub is passed a ONE-section array rather than a section plus a mode
+     * flag, so the two modes cannot disagree about what they are rendering.
+     */
+    mode: "sections" | "screens";
+    sections: DashboardHubSection[];
+    /** Built by the caller from `ROUTES.{PORTAL}.SECTION(slug)`. */
+    sectionHrefs: Record<string, string>;
+    counts: AttentionCounts;
+    /**
+     * Rendered above the cards — the live stat tiles on `/store` and `/user`.
+     *
+     * Those are real data and stay: the plan's "bland tile walls" are the
+     * undifferentiated grids of ~19 nav shortcuts, not the figures beside them.
+     * Deleting a working panel while replacing its neighbour is Root Cause #60's
+     * shape, so the slot exists and the caller keeps passing them.
+     */
+    above?: React.ReactNode;
+    /** Shown when the viewer can see nothing at all. */
+    emptyMessage?: string;
+    /**
+     * Render "7 screens" on a section card. Default `true`.
+     *
+     * 🛑 Pass `false` whenever `sections` has NOT been through every filter that
+     * applies to the portal. `/store` is the live case: its entitlement filter
+     * (`filterStoreNavGroups`) runs in the layout and on the hub pages, but the
+     * client landing does not hold the store document, so its "Listings" card
+     * would claim nine screens where the seller can reach six. The section itself
+     * is still correct — it is the COUNT that would over-promise, so the count is
+     * withheld rather than guessed.
+     */
+    showScreenCount?: boolean;
+}
+export declare function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount, }: DashboardHubViewProps): React.JSX.Element;

package/dist/features/dashboard/components/DashboardHubView.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Badge, Div, Grid, Heading, Row, Section, Stack, Text, TextLink } from "../../../ui/index.js";
+/**
+ * Sum of the counts inside a section, or `null` when it has none.
+ *
+ * 🛑 `null` and `0` are different answers and a card renders only the first as
+ * "no badge". A section whose every count FAILED must not read as "nothing
+ * waiting" (Root Cause #72), so a failed read inside an otherwise-countless
+ * section stays `null` rather than collapsing to a sum of zero.
+ */
+function sectionTotal(section, counts) {
+    let total = null;
+    for (const item of section.items) {
+        const value = item.id ? counts[item.id] : undefined;
+        if (typeof value !== "number")
+            continue;
+        total = (total ?? 0) + value;
+    }
+    return total;
+}
+/** A count worth showing. Zero is not — a `0` badge is noise on every card. */
+function badgeFor(value) {
+    if (typeof value !== "number" || value <= 0)
+        return null;
+    return (_jsx(Badge, { variant: "warning", "aria-label": `${value} waiting`, children: value }));
+}
+function CardGrid({ cards }) {
+    return (_jsx(Grid, { cols: "cards", gap: "md", children: cards.map((card) => (_jsxs(TextLink, { variant: "bare", href: card.href, rounded: "xl", layout: "flex-col", gap: "sm", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: "group border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0 w-full", children: [_jsx(Text, { weight: "semibold", className: "min-w-0 text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", children: card.label }), badgeFor(card.count)] }), card.description && (_jsx(Text, { size: "sm", className: "text-[var(--appkit-color-text-muted)] leading-relaxed", children: card.description })), card.meta && (_jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-faint)] mt-auto", children: card.meta }))] }, card.key))) }));
+}
+export function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount = true, }) {
+    const hasAny = sections.some((section) => section.items.length > 0);
+    return (_jsxs(Stack, { gap: "lg", children: [title && (_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, size: "xl", weight: "semibold", color: "primary", children: title }), description && (_jsx(Text, { size: "sm", color: "muted", children: description }))] })), above, !hasAny && (_jsx(Alert, { variant: "info", title: "Nothing here yet", children: emptyMessage ??
+                    "Your permission set doesn't include access to any of these screens yet. Ask an admin for the permissions you need." })), hasAny && mode === "sections" && (_jsx(CardGrid, { cards: sections.map((section) => ({
+                    key: section.slug,
+                    href: sectionHrefs[section.slug] ?? "",
+                    label: section.title,
+                    /*
+                     * A section has no description of its own and must not invent one —
+                     * so it names what is inside it instead. `items.length` is the
+                     * post-filter count, which is what this viewer will actually find
+                     * PROVIDED every filter has run; see `showScreenCount`.
+                     */
+                    meta: showScreenCount
+                        ? `${section.items.length} ${section.items.length === 1 ? "screen" : "screens"}`
+                        : undefined,
+                    count: sectionTotal(section, counts),
+                })) })), hasAny &&
+                mode === "screens" &&
+                sections.map((section) => (_jsxs(Section, { children: [_jsx(Heading, { level: 2, size: "lg", weight: "semibold", className: "mb-4 text-[var(--appkit-color-text)]", children: section.title }), _jsx(CardGrid, { cards: section.items.map((item) => ({
+                                key: item.id ?? item.href,
+                                href: item.href,
+                                label: item.label,
+                                description: item.description,
+                                count: item.id ? (counts[item.id] ?? null) : null,
+                            })) })] }, section.slug))), hasAny && mode === "sections" && (_jsx(Div, { children: _jsx(Text, { size: "xs", color: "faint", children: "Every card above is a section of the sidebar. The screens inside one are the same screens, with a sentence each on what they are for." }) }))] }));
+}

package/dist/features/dashboard/components/DashboardSectionsClient.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+import type { NavPortal, SidebarNavGroup } from "../../../_internal/shared/features/layout/types";
+export interface DashboardSectionsClientProps {
+    portal: NavPortal;
+    /**
+     * The portal's nav groups.
+     *
+     * 🛑 Pass the groups the SIDEBAR was given, already put through any
+     * portal-specific filter (`filterStoreNavGroups` for `/store`). This applies
+     * only the navConfig/permission filter; a section the store is not entitled
+     * to would otherwise appear here and nowhere else.
+     */
+    groups: readonly SidebarNavGroup[];
+    /** `null` means admin; `undefined` means "no permission gating applies". */
+    permissions?: string[] | null;
+    /** Omit when embedding in a page that already has a heading. */
+    title?: string;
+    description?: string;
+    /** Live stat tiles and anything else that belongs above the cards. */
+    above?: React.ReactNode;
+    emptyMessage?: string;
+}
+export declare function DashboardSectionsClient({ portal, groups, permissions, title, description, above, emptyMessage, }: DashboardSectionsClientProps): React.JSX.Element;