@mohasinac/appkit 2.2.0 → 2.3.1

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

@@ -89,22 +89,22 @@ export declare const faqSchema: z.ZodObject<{
         text: string;
         format: "html" | "plain" | "markdown";
     };
-    createdAt?: string | undefined;
-    updatedAt?: string | undefined;
-    seo?: {
-        slug?: string | undefined;
-    } | undefined;
     order?: number | undefined;
     priority?: number | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
     stats?: {
         views?: number | undefined;
         helpful?: number | undefined;
         notHelpful?: number | undefined;
     } | undefined;
     isActive?: boolean | undefined;
-    showInFooter?: boolean | undefined;
-    showOnHomepage?: boolean | undefined;
     tags?: string[] | undefined;
+    seo?: {
+        slug?: string | undefined;
+    } | undefined;
+    showOnHomepage?: boolean | undefined;
+    showInFooter?: boolean | undefined;
     isPinned?: boolean | undefined;
     relatedFAQs?: string[] | undefined;
 }, {
@@ -115,22 +115,22 @@ export declare const faqSchema: z.ZodObject<{
         text: string;
         format: "html" | "plain" | "markdown";
     };
-    createdAt?: string | undefined;
-    updatedAt?: string | undefined;
-    seo?: {
-        slug?: string | undefined;
-    } | undefined;
     order?: number | undefined;
     priority?: number | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
     stats?: {
         views?: number | undefined;
         helpful?: number | undefined;
         notHelpful?: number | undefined;
     } | undefined;
     isActive?: boolean | undefined;
-    showInFooter?: boolean | undefined;
-    showOnHomepage?: boolean | undefined;
     tags?: string[] | undefined;
+    seo?: {
+        slug?: string | undefined;
+    } | undefined;
+    showOnHomepage?: boolean | undefined;
+    showInFooter?: boolean | undefined;
     isPinned?: boolean | undefined;
     relatedFAQs?: string[] | undefined;
 }>;
@@ -142,16 +142,16 @@ export declare const faqListParamsSchema: z.ZodObject<{
     page: z.ZodOptional<z.ZodNumber>;
     perPage: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    perPage?: number | undefined;
-    page?: number | undefined;
     q?: string | undefined;
+    page?: number | undefined;
     category?: "general" | "orders_payment" | "shipping_delivery" | "returns_refunds" | "product_information" | "account_security" | "technical_support" | undefined;
+    perPage?: number | undefined;
     homepage?: boolean | undefined;
 }, {
-    perPage?: number | undefined;
-    page?: number | undefined;
     q?: string | undefined;
+    page?: number | undefined;
     category?: "general" | "orders_payment" | "shipping_delivery" | "returns_refunds" | "product_information" | "account_security" | "technical_support" | undefined;
+    perPage?: number | undefined;
     homepage?: boolean | undefined;
 }>;
 export * from "./firestore";

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-// ─── Sub-schemas ──────────────────────────────────────────────────────────────
+// --- Sub-schemas --------------------------------------------------------------
 export const faqCategorySchema = z.enum([
     "orders_payment",
     "shipping_delivery",
@@ -19,7 +19,7 @@ export const faqStatsSchema = z.object({
     helpful: z.number().optional(),
     notHelpful: z.number().optional(),
 });
-// ─── Base item schema ─────────────────────────────────────────────────────────
+// --- Base item schema ---------------------------------------------------------
 /**
  * Base Zod schema for a FAQ item.
  * Apps can extend this to add their own fields:

package/dist/features/faq/server.d.ts

@@ -3,7 +3,6 @@
  *
  * Server-only entry point for FAQ API route handlers.
  */
-import "server-only";
 export * from "./actions";
 export { FAQsRepository, FirebaseFAQsRepository, faqsRepository, } from "./repository/faqs.repository";
 export { GET as faqGET, GET } from "./api/route";

package/dist/features/faq/server.js

@@ -3,7 +3,6 @@
  *
  * Server-only entry point for FAQ API route handlers.
  */
-import "server-only";
 export * from "./actions";
 export { FAQsRepository, FirebaseFAQsRepository, faqsRepository, } from "./repository/faqs.repository";
 export { GET as faqGET, GET } from "./api/route";

package/dist/features/filters/FilterFacetSection.js

@@ -34,6 +34,6 @@ export function FilterFacetSection({ title, options, selected, onChange, selecti
     const hasValue = selected.length > 0;
     return (_jsxs(Div, { className: cn("p-4 border-b border-zinc-200 dark:border-slate-700 last:border-b-0", className), children: [_jsxs(Row, { gap: "xs", children: [_jsxs(Button, { type: "button", onClick: handleToggle, variant: "ghost", size: "sm", className: "flex flex-1 items-center justify-between text-sm font-semibold text-zinc-900 dark:text-zinc-50 py-1 hover:opacity-80 transition-opacity", "aria-expanded": !isCollapsed, children: [_jsxs(Row, { as: Span, gap: "xs", children: [title, hasValue && (_jsx(Span, { className: "inline-flex items-center justify-center w-5 h-5 text-xs rounded-full bg-emerald-50 dark:bg-emerald-900/30 text-emerald-700 dark:text-emerald-300 ring-1 ring-emerald-600/20 dark:ring-emerald-400/20", children: selected.length }))] }), _jsx("svg", { className: cn("w-4 h-4 text-zinc-500 dark:text-zinc-400 transition-transform duration-200", isCollapsed ? "" : "rotate-180"), fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) })] }), onClear && hasValue && (_jsx(Button, { type: "button", onClick: onClear, variant: "ghost", size: "sm", className: "inline-flex items-center justify-center w-5 h-5 p-0 text-zinc-500 dark:text-zinc-400 hover:text-red-600 dark:hover:text-red-400 hover:bg-zinc-100 dark:hover:bg-slate-700 transition-colors rounded-full", "aria-label": "Clear filter", children: _jsx("svg", { className: "w-3 h-3", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M6 18L18 6M6 6l12 12" }) }) }))] }), !isCollapsed && (_jsxs(Div, { className: "mt-3 space-y-1", children: [searchable && options.length > 8 && (_jsx(Input, { type: "search", placeholder: "Search\u2026", value: search, onChange: (e) => setSearch(e.target.value), className: "w-full rounded-md border border-zinc-200 dark:border-slate-700 bg-white dark:bg-slate-800/60 px-2.5 py-1.5 text-xs text-zinc-900 dark:text-zinc-100 focus:outline-none focus:ring-2 focus:ring-primary-500/20 dark:focus:ring-secondary-400/20 mb-2" })), filtered.map((option) => {
                         const isSelected = selected.includes(option.value);
-                        return (_jsxs(Row, { gap: "2.5", className: "py-1 cursor-pointer group", children: [selectionMode === "single" ? (_jsx("input", { type: "radio", checked: isSelected, onChange: () => toggle(option.value), className: cn("flex-shrink-0 border-zinc-300 dark:border-slate-600 cursor-pointer", "w-4 h-4 rounded-full text-primary-600 dark:text-secondary-500", "focus:ring-primary-500/30 dark:focus:ring-secondary-400/30") })) : (_jsx("input", { type: "checkbox", checked: isSelected, onChange: () => toggle(option.value), className: cn("flex-shrink-0 border-zinc-300 dark:border-slate-600 cursor-pointer", "w-4 h-4 rounded text-primary-600 dark:text-secondary-500 checked:bg-primary-600 dark:checked:bg-secondary-500", "focus:ring-primary-500/30 dark:focus:ring-secondary-400/30") })), _jsx(Span, { className: "flex-1 text-sm text-zinc-700 dark:text-zinc-300 group-hover:text-zinc-900 dark:group-hover:text-zinc-100 transition-colors truncate", children: option.label }), option.count !== undefined && (_jsx(Span, { className: "text-xs text-zinc-400 dark:text-zinc-500 tabular-nums flex-shrink-0", children: option.count }))] }, option.value));
+                        return (_jsxs(Row, { gap: "2.5", className: "py-1 cursor-pointer group", children: [selectionMode === "single" ? (_jsx("input", { type: "radio", checked: isSelected, onChange: () => toggle(option.value), "aria-label": option.label, className: cn("flex-shrink-0 border-zinc-300 dark:border-slate-600 cursor-pointer", "w-4 h-4 rounded-full text-primary-600 dark:text-secondary-500", "focus:ring-primary-500/30 dark:focus:ring-secondary-400/30") })) : (_jsx("input", { type: "checkbox", checked: isSelected, onChange: () => toggle(option.value), "aria-label": option.label, className: cn("flex-shrink-0 border-zinc-300 dark:border-slate-600 cursor-pointer", "w-4 h-4 rounded text-primary-600 dark:text-secondary-500 checked:bg-primary-600 dark:checked:bg-secondary-500", "focus:ring-primary-500/30 dark:focus:ring-secondary-400/30") })), _jsx(Span, { className: "flex-1 text-sm text-zinc-700 dark:text-zinc-300 group-hover:text-zinc-900 dark:group-hover:text-zinc-100 transition-colors truncate", children: option.label }), option.count !== undefined && (_jsx(Span, { className: "text-xs text-zinc-400 dark:text-zinc-500 tabular-nums flex-shrink-0", children: option.count }))] }, option.value));
                     }), filtered.length === 0 && (_jsx(Text, { className: "text-xs text-zinc-400 dark:text-zinc-500 py-1", children: "No results" }))] }))] }));
 }

package/dist/features/filters/index.d.ts

@@ -8,3 +8,7 @@ export { FilterPanel } from "./FilterPanel";
 export type { FilterPanelProps, FilterConfig, UrlTable, FacetSingleConfig, FacetMultiConfig, SwitchConfig, RangeNumberConfig, RangeDateConfig, } from "./FilterPanel";
 export { getFilterLabel, getFilterValue, cn } from "./filterUtils";
 export type { FilterOption } from "./filterUtils";
+export { usePendingFilters } from "./usePendingFilters";
+export type { UsePendingFiltersOptions, UsePendingFiltersResult, } from "./usePendingFilters";
+export { parseRouteFilterSegments, serializeRouteFilterSegments, buildFilterUrl, extractFilterStateFromParams, mergeFilterUpdate, } from "./routeFilterState";
+export type { RouteFilterState } from "./routeFilterState";

package/dist/features/filters/index.js

@@ -4,3 +4,5 @@ export { RangeFilter } from "./RangeFilter";
 export { SwitchFilter } from "./SwitchFilter";
 export { FilterPanel } from "./FilterPanel";
 export { getFilterLabel, getFilterValue, cn } from "./filterUtils";
+export { usePendingFilters } from "./usePendingFilters";
+export { parseRouteFilterSegments, serializeRouteFilterSegments, buildFilterUrl, extractFilterStateFromParams, mergeFilterUpdate, } from "./routeFilterState";

package/dist/features/filters/routeFilterState.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Route-param filter state — parser and serializer
+ *
+ * Canonical URL pattern:
+ *   /listing/[segment-key]/[segment-value]/[segment-key]/[segment-value]/...
+ *
+ * Example:
+ *   /products/category/collectibles/sort/price-asc/page/2
+ *   → { category: "collectibles", sort: "price-asc", page: "2" }
+ *
+ * Special handling:
+ *   - Unknown trailing segments are ignored during parse.
+ *   - `page` defaults to "1" when absent.
+ *   - `sort` defaults to "relevance" when absent.
+ *   - Segments are always lowercase-URL-safe values.
+ */
+export type RouteFilterState = Record<string, string>;
+/**
+ * Parse flat path segments (key/value pairs) into a filter state map.
+ *
+ * @example
+ *   parseRouteFilterSegments(["category", "collectibles", "sort", "price-asc", "page", "2"])
+ *   // → { category: "collectibles", sort: "price-asc", page: "2" }
+ */
+export declare function parseRouteFilterSegments(segments: string[]): RouteFilterState;
+/**
+ * Serialize a filter state map back into flat path segments for use in a URL.
+ *
+ * Keys are emitted in the provided `keyOrder` first, then any remaining keys
+ * alphabetically. Keys with empty / undefined values are omitted.
+ *
+ * @example
+ *   serializeRouteFilterSegments({ category: "collectibles", sort: "price-asc", page: "2" })
+ *   // → "category/collectibles/sort/price-asc/page/2"
+ */
+export declare function serializeRouteFilterSegments(state: RouteFilterState, keyOrder?: string[]): string;
+/**
+ * Build a full listing URL by combining the base path with serialized filter
+ * state segments.
+ *
+ * @example
+ *   buildFilterUrl("/products", { category: "collectibles", sort: "price-asc", page: "2" })
+ *   // → "/products/category/collectibles/sort/price-asc/page/2"
+ */
+export declare function buildFilterUrl(basePath: string, state: RouteFilterState, keyOrder?: string[]): string;
+/**
+ * Extract filter state from a Next.js catch-all `params.segments` array or
+ * an already-split string path after the base route.
+ *
+ * Handles both string[] (Next.js catch-all) and string (split by "/").
+ */
+export declare function extractFilterStateFromParams(segments: string | string[] | undefined): RouteFilterState;
+/**
+ * Merge a partial filter update into the current state, resetting `page` to
+ * "1" when any filter key other than `page` changes (prevents stale
+ * pagination).
+ */
+export declare function mergeFilterUpdate(current: RouteFilterState, update: RouteFilterState): RouteFilterState;

package/dist/features/filters/routeFilterState.js

@@ -0,0 +1,97 @@
+/**
+ * Route-param filter state — parser and serializer
+ *
+ * Canonical URL pattern:
+ *   /listing/[segment-key]/[segment-value]/[segment-key]/[segment-value]/...
+ *
+ * Example:
+ *   /products/category/collectibles/sort/price-asc/page/2
+ *   → { category: "collectibles", sort: "price-asc", page: "2" }
+ *
+ * Special handling:
+ *   - Unknown trailing segments are ignored during parse.
+ *   - `page` defaults to "1" when absent.
+ *   - `sort` defaults to "relevance" when absent.
+ *   - Segments are always lowercase-URL-safe values.
+ */
+/**
+ * Parse flat path segments (key/value pairs) into a filter state map.
+ *
+ * @example
+ *   parseRouteFilterSegments(["category", "collectibles", "sort", "price-asc", "page", "2"])
+ *   // → { category: "collectibles", sort: "price-asc", page: "2" }
+ */
+export function parseRouteFilterSegments(segments) {
+    const state = {};
+    for (let i = 0; i < segments.length - 1; i += 2) {
+        const key = segments[i];
+        const value = segments[i + 1];
+        if (key && value !== undefined) {
+            state[key] = value;
+        }
+    }
+    return state;
+}
+/**
+ * Serialize a filter state map back into flat path segments for use in a URL.
+ *
+ * Keys are emitted in the provided `keyOrder` first, then any remaining keys
+ * alphabetically. Keys with empty / undefined values are omitted.
+ *
+ * @example
+ *   serializeRouteFilterSegments({ category: "collectibles", sort: "price-asc", page: "2" })
+ *   // → "category/collectibles/sort/price-asc/page/2"
+ */
+export function serializeRouteFilterSegments(state, keyOrder = ["category", "sort", "page"]) {
+    const orderedKeys = [
+        ...keyOrder.filter((k) => k in state),
+        ...Object.keys(state)
+            .filter((k) => !keyOrder.includes(k))
+            .sort(),
+    ];
+    return orderedKeys
+        .filter((k) => state[k] !== undefined && state[k] !== "")
+        .map((k) => `${encodeURIComponent(k)}/${encodeURIComponent(state[k])}`)
+        .join("/");
+}
+/**
+ * Build a full listing URL by combining the base path with serialized filter
+ * state segments.
+ *
+ * @example
+ *   buildFilterUrl("/products", { category: "collectibles", sort: "price-asc", page: "2" })
+ *   // → "/products/category/collectibles/sort/price-asc/page/2"
+ */
+export function buildFilterUrl(basePath, state, keyOrder) {
+    const segments = serializeRouteFilterSegments(state, keyOrder);
+    if (!segments)
+        return basePath;
+    return `${basePath.replace(/\/$/, "")}/${segments}`;
+}
+/**
+ * Extract filter state from a Next.js catch-all `params.segments` array or
+ * an already-split string path after the base route.
+ *
+ * Handles both string[] (Next.js catch-all) and string (split by "/").
+ */
+export function extractFilterStateFromParams(segments) {
+    if (!segments)
+        return {};
+    const parts = Array.isArray(segments)
+        ? segments
+        : segments.split("/").filter(Boolean);
+    return parseRouteFilterSegments(parts);
+}
+/**
+ * Merge a partial filter update into the current state, resetting `page` to
+ * "1" when any filter key other than `page` changes (prevents stale
+ * pagination).
+ */
+export function mergeFilterUpdate(current, update) {
+    const next = { ...current, ...update };
+    const changed = Object.keys(update).some((k) => k !== "page" && update[k] !== current[k]);
+    if (changed && !("page" in update)) {
+        next.page = "1";
+    }
+    return next;
+}

package/dist/features/filters/usePendingFilters.d.ts

@@ -0,0 +1,37 @@
+import type { UrlTable } from "./FilterPanel";
+/**
+ * usePendingFilters — deferred apply pattern for filter panels.
+ *
+ * Maintains a local "staging" copy of filter values. Changes write only to
+ * the staging table; nothing is committed to the URL/state until `commit()`
+ * is called (e.g. when the user clicks "Apply Filters").
+ *
+ * Usage:
+ *   const { stagingTable, pendingCount, commit, reset } = usePendingFilters({
+ *     initial: currentUrlParams,
+ *     onCommit: (values) => router.push(buildUrl(values)),
+ *   });
+ *   // Pass stagingTable to <FilterPanel table={stagingTable} />
+ *   // Pass pendingCount to filterPendingCount prop of ListingLayout
+ *   // Call commit() from onFilterApply
+ *   // Call reset() from onFilterClear
+ */
+export interface UsePendingFiltersOptions {
+    /** Current committed filter values (URL params / server state snapshot). */
+    initial: Record<string, string>;
+    /** Called with the full staged values when the user commits. */
+    onCommit: (values: Record<string, string>) => void;
+}
+export interface UsePendingFiltersResult {
+    /** UrlTable backed by staging state — pass to FilterPanel / FilterFacetSection. */
+    stagingTable: UrlTable;
+    /** Number of keys that differ between staged and committed values. */
+    pendingCount: number;
+    /** Flush staged values to committed via onCommit. */
+    commit: () => void;
+    /** Revert staged values back to the last committed snapshot. */
+    reset: () => void;
+    /** Current staged values (read-only snapshot). */
+    staged: Record<string, string>;
+}
+export declare function usePendingFilters({ initial, onCommit, }: UsePendingFiltersOptions): UsePendingFiltersResult;

package/dist/features/filters/usePendingFilters.js

@@ -0,0 +1,22 @@
+"use client";
+import { useState, useCallback, useMemo } from "react";
+export function usePendingFilters({ initial, onCommit, }) {
+    const [staged, setStaged] = useState({ ...initial });
+    const stagingTable = useMemo(() => ({
+        get: (key) => staged[key] ?? "",
+        set: (key, value) => setStaged((prev) => ({ ...prev, [key]: value })),
+        setMany: (updates) => setStaged((prev) => ({ ...prev, ...updates })),
+    }), [staged]);
+    const pendingCount = useMemo(() => {
+        const allKeys = new Set([...Object.keys(staged), ...Object.keys(initial)]);
+        let count = 0;
+        for (const key of allKeys) {
+            if ((staged[key] ?? "") !== (initial[key] ?? ""))
+                count++;
+        }
+        return count;
+    }, [staged, initial]);
+    const commit = useCallback(() => onCommit(staged), [onCommit, staged]);
+    const reset = useCallback(() => setStaged({ ...initial }), [initial]);
+    return { stagingTable, pendingCount, commit, reset, staged };
+}

package/dist/features/forms/Checkbox.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { Div, Span } from "../../ui";

package/dist/features/forms/Form.js

@@ -1,4 +1,3 @@
-"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Div } from "../../ui";
 import { cn } from "./utils";
@@ -22,7 +21,7 @@ export function FormGroup({ children, columns = 1, gap = "md", className = "", }
     };
     return (_jsx(Div, { className: cn("grid", gridClasses[columns], GAP_MAP[gap], className), children: children }));
 }
-// ─── FormFieldSpan ────────────────────────────────────────────────────────────
+// --- FormFieldSpan ------------------------------------------------------------
 /** Wraps a child so it spans full width inside a multi-column FormGroup. */
 export function FormFieldSpan({ children, className = "", }) {
     return _jsx(Div, { className: cn("col-span-full", className), children: children });

package/dist/features/forms/Radio.js

@@ -1,4 +1,3 @@
-"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Div, Span } from "../../ui";
 import { cn, LABEL_BASE, ERROR_BASE } from "./utils";

package/dist/features/forms/utils.js

@@ -2,7 +2,7 @@
 export function cn(...classes) {
     return classes.filter(Boolean).join(" ");
 }
-// ─── Shared style constants ───────────────────────────────────────────────────
+// --- Shared style constants ---------------------------------------------------
 export const INPUT_BASE = "rounded-lg border border-zinc-200 dark:border-slate-700 bg-white dark:bg-slate-800/60 px-3.5 py-2.5 text-sm text-zinc-900 dark:text-zinc-100 focus:ring-2 focus:ring-primary-500/20 dark:focus:ring-secondary-400/20 focus:border-primary-500 dark:focus:border-secondary-400 focus:outline-none transition-colors duration-150 placeholder:text-zinc-400 dark:placeholder:text-zinc-500";
 export const INPUT_ERROR = "border-red-400 dark:border-red-500 focus:ring-red-500/20 focus:border-red-500 bg-red-50/30 dark:bg-red-950/10";
 export const INPUT_SUCCESS = "border-emerald-400 dark:border-emerald-500 focus:ring-emerald-500/20 focus:border-emerald-500";

package/dist/features/homepage/actions/homepage-section-actions.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { serverLogger } from "../../../monitoring";
 import { homepageSectionsRepository } from "../repository/homepage-sections.repository";
-// ─── Schemas ──────────────────────────────────────────────────────────────
+// --- Schemas --------------------------------------------------------------
 export const createSectionSchema = z.object({
     type: z.string().min(1),
     enabled: z.boolean().default(true),
@@ -13,7 +13,7 @@ export const updateSectionSchema = z.object({
     enabled: z.boolean().optional(),
     config: z.record(z.string(), z.unknown()).optional(),
 });
-// ─── Actions ──────────────────────────────────────────────────────────────
+// --- Actions --------------------------------------------------------------
 export async function createHomepageSection(input, createdBy) {
     const section = await homepageSectionsRepository.create(input);
     serverLogger.info("createHomepageSection", {

package/dist/features/homepage/ad-registry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Ad Placement Registry
+ *
+ * Provides a typed, centralized registry of ad slot configurations.
+ * Consumers call `registerAdSlot` at app boot to configure each slot,
+ * then render `<AdSlot id="..." />` in page layouts.
+ *
+ * Consent gate: slots with `requiresConsent: true` will not render until
+ * `setAdConsentGranted(true)` is called (e.g. after cookie banner accept).
+ *
+ * @example
+ * // In your layout root:
+ * registerAdSlots([
+ *   { id: "homepage-hero-banner", provider: "adsense", adsenseClient: "ca-pub-...", adsenseSlot: "..." },
+ *   { id: "listing-between-rows", provider: "manual", reservedHeight: 90 },
+ * ]);
+ */
+export type AdSlotId = "homepage-hero-banner" | "homepage-mid-banner" | "homepage-bottom-banner" | "listing-sidebar-top" | "listing-sidebar-bottom" | "listing-between-rows" | "detail-below-gallery" | "detail-below-price" | "cart-upsell" | "checkout-upsell" | "search-inline";
+/**
+ * `manual`     — static HTML/React content supplied via `manualContent` on `<AdSlot>`
+ * `adsense`    — Google AdSense `<ins>` tag; requires `adsenseClient` + `adsenseSlot`
+ * `thirdParty` — third-party iframe; requires `thirdPartyUrl` or `thirdPartyScript`
+ */
+export type AdProvider = "manual" | "adsense" | "thirdParty";
+export interface AdSlotConfig {
+    /** Unique slot identifier. */
+    id: AdSlotId;
+    /** Primary ad provider for this slot. */
+    provider: AdProvider;
+    /**
+     * Reserved pixel height for the slot container.
+     * Prevents layout shift (CLS) while the ad loads.
+     * @default undefined (no reserved height)
+     */
+    reservedHeight?: number;
+    /**
+     * Fallback provider order if the primary provider fails or is disabled.
+     * Tried left-to-right until one succeeds.
+     */
+    fallbackOrder?: AdProvider[];
+    /**
+     * When `true` the slot will not render until `setAdConsentGranted(true)` has
+     * been called. Use for GDPR/consent-gated slots.
+     * @default false
+     */
+    requiresConsent?: boolean;
+    /**
+     * Master on/off switch. `false` → slot renders nothing (no reserved space).
+     * @default true
+     */
+    enabled?: boolean;
+    /** AdSense publisher ID, e.g. "ca-pub-1234567890" */
+    adsenseClient?: string;
+    /** AdSense ad-slot string, e.g. "9876543210" */
+    adsenseSlot?: string;
+    /** AdSense data-ad-format (default: "auto") */
+    adsenseFormat?: string;
+    /** Full URL for an iframe `src`. */
+    thirdPartyUrl?: string;
+    /** Raw `<script>` tag inner text to inject (server-safe strings only). */
+    thirdPartyScript?: string;
+    /** iframe width, e.g. "728px". */
+    thirdPartyWidth?: string;
+    /** iframe height, e.g. "90px". */
+    thirdPartyHeight?: string;
+}
+/**
+ * Register (or replace) an ad slot configuration.
+ * Call once at app boot — e.g. in a layout component or `providers.tsx`.
+ */
+export declare function registerAdSlot(config: AdSlotConfig): void;
+/** Register multiple ad slots at once. */
+export declare function registerAdSlots(configs: AdSlotConfig[]): void;
+/** Retrieve the config for a given slot id. Returns `undefined` if unregistered. */
+export declare function getAdSlot(id: AdSlotId): AdSlotConfig | undefined;
+/** Return all registered slot configs. */
+export declare function getAllAdSlots(): AdSlotConfig[];
+/** Remove a slot config from the registry. */
+export declare function unregisterAdSlot(id: AdSlotId): void;
+/** Clear all registered slot configs (useful in tests / HMR). */
+export declare function clearAdRegistry(): void;
+/**
+ * Signal that the user has granted consent for personalised / tracking ads.
+ * Consent-gated slots (`requiresConsent: true`) will start rendering.
+ *
+ * @example
+ * onAcceptAll={() => setAdConsentGranted(true)}
+ */
+export declare function setAdConsentGranted(granted: boolean): void;
+/** Returns the current consent state. */
+export declare function isAdConsentGranted(): boolean;
+/**
+ * Returns `true` if the slot should render given the current registry +
+ * consent state.
+ */
+export declare function isAdSlotRenderable(id: AdSlotId): boolean;

package/dist/features/homepage/ad-registry.js

@@ -0,0 +1,84 @@
+/**
+ * Ad Placement Registry
+ *
+ * Provides a typed, centralized registry of ad slot configurations.
+ * Consumers call `registerAdSlot` at app boot to configure each slot,
+ * then render `<AdSlot id="..." />` in page layouts.
+ *
+ * Consent gate: slots with `requiresConsent: true` will not render until
+ * `setAdConsentGranted(true)` is called (e.g. after cookie banner accept).
+ *
+ * @example
+ * // In your layout root:
+ * registerAdSlots([
+ *   { id: "homepage-hero-banner", provider: "adsense", adsenseClient: "ca-pub-...", adsenseSlot: "..." },
+ *   { id: "listing-between-rows", provider: "manual", reservedHeight: 90 },
+ * ]);
+ */
+// ---------------------------------------------------------------------------
+// Registry store
+// ---------------------------------------------------------------------------
+const _registry = new Map();
+let _consentGranted = false;
+/**
+ * Register (or replace) an ad slot configuration.
+ * Call once at app boot — e.g. in a layout component or `providers.tsx`.
+ */
+export function registerAdSlot(config) {
+    _registry.set(config.id, {
+        enabled: true,
+        requiresConsent: false,
+        ...config,
+    });
+}
+/** Register multiple ad slots at once. */
+export function registerAdSlots(configs) {
+    configs.forEach(registerAdSlot);
+}
+/** Retrieve the config for a given slot id. Returns `undefined` if unregistered. */
+export function getAdSlot(id) {
+    return _registry.get(id);
+}
+/** Return all registered slot configs. */
+export function getAllAdSlots() {
+    return Array.from(_registry.values());
+}
+/** Remove a slot config from the registry. */
+export function unregisterAdSlot(id) {
+    _registry.delete(id);
+}
+/** Clear all registered slot configs (useful in tests / HMR). */
+export function clearAdRegistry() {
+    _registry.clear();
+}
+// ---------------------------------------------------------------------------
+// Consent gate
+// ---------------------------------------------------------------------------
+/**
+ * Signal that the user has granted consent for personalised / tracking ads.
+ * Consent-gated slots (`requiresConsent: true`) will start rendering.
+ *
+ * @example
+ * onAcceptAll={() => setAdConsentGranted(true)}
+ */
+export function setAdConsentGranted(granted) {
+    _consentGranted = granted;
+}
+/** Returns the current consent state. */
+export function isAdConsentGranted() {
+    return _consentGranted;
+}
+/**
+ * Returns `true` if the slot should render given the current registry +
+ * consent state.
+ */
+export function isAdSlotRenderable(id) {
+    const config = _registry.get(id);
+    if (!config)
+        return false;
+    if (config.enabled === false)
+        return false;
+    if (config.requiresConsent && !_consentGranted)
+        return false;
+    return true;
+}

package/dist/features/homepage/api/[id]/route.js

@@ -12,7 +12,7 @@ import { NextResponse } from "next/server.js";
 import { z } from "zod";
 import { getProviders } from "../../../../contracts";
 import { createRouteHandler } from "../../../../next";
-// ──── GET /api/homepage-sections/[id] ────────────────────────────────────────
+// ---- GET /api/homepage-sections/[id] ----------------------------------------
 export async function GET(_request, context) {
     try {
         const { id } = await context.params;
@@ -33,7 +33,7 @@ export async function GET(_request, context) {
     }
 }
 export { GET as homepageSectionItemGET };
-// ──── PATCH /api/homepage-sections/[id] ───────────────────────────────────
+// ---- PATCH /api/homepage-sections/[id] -----------------------------------
 const homepageSectionUpdateSchema = z
     .object({
     type: z
@@ -79,7 +79,7 @@ export const homepageSectionItemPATCH = createRouteHandler({
         return NextResponse.json({ success: true, data: updated });
     },
 });
-// ──── DELETE /api/homepage-sections/[id] ─────────────────────────────────
+// ---- DELETE /api/homepage-sections/[id] ---------------------------------
 export const homepageSectionItemDELETE = createRouteHandler({
     auth: true,
     roles: ["admin"],