@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/ui/widgets/types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Widget model — the declarative half.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE HAS NO `render` AND NO REACT IMPORT
+ * ---------------------------------------------------------------------------
+ *
+ * A widget DEFINITION has to be readable by four callers that have nothing
+ * else in common: the renderer (client), the admin editor (client), the
+ * config validator (server), and the required-field resolver (isomorphic,
+ * and it is a pure Zod refinement with no React in scope at all). Putting
+ * `render` on the definition forces every one of them to pull React.
+ *
+ * That is not a hypothetical. `src/constants/navigation.tsx` carries a 🛑
+ * comment for Root Cause #76: it called `navItemId` at module scope, the
+ * import resolved through a `"use client"` entry, and the Vercel build died
+ * with *"Attempted to call navItemId() from the server but navItemId is on
+ * the client"* — while every local check passed. The same shape applies here
+ * with more call sites.
+ *
+ * So the split is: capabilities + placement live here (plain data, no JSX),
+ * and renderers are a separate `Record<type, (ctx) => ReactNode>` map in a
+ * `.tsx` module that only the rendering surface imports. This mirrors
+ * `_internal/shared/features/dashboard/recent-entry.ts`, which deliberately
+ * stays "schema-free … matching every other type in it", and
+ * `SECTION_REGISTRY`, which is the one place that holds `render`.
+ *
+ * ---------------------------------------------------------------------------
+ * THE TIERS (see docs/overhaul/widget-architecture.md §2 for the argument)
+ * ---------------------------------------------------------------------------
+ *
+ *   T0 surface  — a route family / host page.          NOT a widget.
+ *   T1 region   — a declared hole in a template.       Code-only; its CHILDREN are config.
+ *   T2 section  — a container widget, typed config.    CONFIG.
+ *   T3 element  — a leaf widget, down to a single link. CONFIG.
+ *   T4 field    — a form input or display row.         CONFIG (existing `fieldVisibility`).
+ *   T5 atom     — Button / Badge / Icon / Text.        NEVER widgetised; token-themed.
+ *
+ * The discriminator between T3 and T5, which is the whole granularity
+ * decision in one question: **does this thing carry its own content/target,
+ * or does it render its parent's data?** Own `href`/`label`/`body` → T3.
+ * Renders the parent's field → a T4 field key on the parent. Pure
+ * presentation of either → T5.
+ */
+/** Which tier a definition sits in. T1 regions are declared separately — see `WidgetRegionDef`. */
+export type WidgetTier = "section" | "element";
+/**
+ * A content-tag dependency. Structurally identical to
+ * `_internal/shared/features/content-tags/registry.ts`'s `ContentTag`, and
+ * declared structurally here rather than imported so this module stays free
+ * of runtime imports (see the header). The real `isContentVisible` is
+ * injected through `WidgetResolveContext.isContentVisible`, so there is ONE
+ * implementation of that predicate, not two.
+ */
+export interface WidgetContentTag {
+    governs: "listingType" | "categoryType" | "browsePage";
+    value: string;
+}
+/**
+ * A T1 region — a named hole in a surface's template.
+ *
+ * 🛑 Regions are declared in CODE and can never be created by config. A hole
+ * has to exist in JSX before config can fill it. `NavSlotId`'s own doc
+ * comment is the cautionary example: four slot ids exist in the type and
+ * only `sidebar-admin` has a real chrome bridge, so composing into the other
+ * three is a silent no-op. Config-created regions would multiply that class
+ * of no-op by the 379 `pageId`s already in the tree.
+ */
+export interface WidgetRegionDef {
+    /** `"<surfaceId>:<slotName>"`. Hand-chosen and stable — never route-derived. */
+    id: string;
+    /** Which surface this region belongs to. Matched against `WidgetResolveContext.surface`. */
+    surface: string;
+    label: string;
+    /** Widget types permitted as direct children. A type absent from here is a config error, not a silent drop. */
+    allowedTypes: readonly string[];
+    /** `false` takes the whole region and everything in it off. Default `true`. */
+    enabled?: boolean;
+}
+/**
+ * A widget DEFINITION — one row per type, in code.
+ *
+ * Every capability field here already exists somewhere in this codebase and
+ * is being read from one place instead of several:
+ *   `surfaces`           ← `SectionDef.surfaces` (homepage/lib/section-renderer.tsx)
+ *   `requiredPermission` ← `SidebarNavItem.requiredPermission`
+ *   `governedBy`         ← `DashboardCard.contentTags`
+ * `childTypes` and `ownsFields` are the two genuinely new ones: they are what
+ * make nesting and the blocked-⇒-not-required rule expressible at all.
+ */
+export interface WidgetDef {
+    /** Registry key. T2 reuses `SectionType` spellings; T3 reuses `CardElement["kind"]` spellings. */
+    type: string;
+    tier: WidgetTier;
+    label: string;
+    /**
+     * CAPABILITY — which surfaces this type is fit for.
+     *
+     * 🛑 This is the capability half of the governing principle and it must be
+     * READ, not merely declared. `SectionDef.surfaces` is declared today and
+     * its own comment admits it is "Declared, not yet CONSUMED", so a
+     * `category`-tagged section mounted on a category page renders an empty
+     * state. `resolveWidgetTree` consumes it.
+     */
+    surfaces: readonly string[];
+    /** CAPABILITY — permitted child types. `[]` means leaf, which is what caps nesting depth. */
+    childTypes: readonly string[];
+    /** CAPABILITY — a PERMISSION string. Never a role literal, never a listing-type comparison. */
+    requiredPermission?: string;
+    /** CAPABILITY — content-tag dependencies evaluated through the injected `isContentVisible`. */
+    governedBy?: readonly WidgetContentTag[];
+    /**
+     * Dotted field paths this widget OWNS — i.e. the fields that become
+     * unreachable when this widget is off. The input to the
+     * blocked-⇒-not-required rule. Absent/empty means the widget owns no
+     * fields, which is the common case for display widgets.
+     */
+    ownsFields?: readonly string[];
+    /** Default state when an instance says nothing. `false` = present in the template but off until enabled. */
+    defaultOn?: boolean;
+    /**
+     * `false` = this widget CANNOT be switched off by configuration.
+     *
+     * 🛑 Added because of the owner's granularity ruling (2026-11-08): `price`
+     * on a product card is a WIDGET, not a field. The moment that is true,
+     * "price can never be removed from a card" stops being expressible as a
+     * required-FIELD rule and has to become a widget capability — otherwise the
+     * guardrail A16 states plainly has no mechanism behind it:
+     *
+     *   *"Required elements cannot be removed: price, condition, authenticity
+     *   claim, the risk banner, consent affordances, and anything legally
+     *   mandated (GST-inclusive labelling, country of origin, seller identity).
+     *   A vendor may restyle them, never hide them."*
+     *
+     * This is the STRUCTURAL MIRROR of Lane G's `system` tier, and it behaves
+     * the same way: an explicit `state: "off"` on a non-removable widget is
+     * REFUSED and REPORTED at save time, not silently honoured and not silently
+     * ignored. The widget stays visible.
+     *
+     * Absent = `true` (removable), so every pre-existing definition keeps its
+     * current behaviour.
+     */
+    removable?: boolean;
+}
+/**
+ * A stored widget INSTANCE — one row per placed widget, in config.
+ *
+ * 🛑 `id` IS MINTED AND STORED, NEVER DERIVED. The live nav system derives
+ * `id` from the href at module scope (`navItemId(portal, href)`,
+ * `publicNavId(href)`) and that derived id is the `siteSettings.navConfig`
+ * key and the attention-count key. Change an href and the re-derived key
+ * matches nothing: every badge silently vanishes behind a 200. The same file
+ * already records the near-miss of two surfaces deriving two spellings
+ * (`nav-brands` vs `nav-public-brands`) and each believing it had saved.
+ *
+ * A minted id survives all three changes a derived one cannot:
+ *   MOVE      → `regionId` changes, `id` does not.
+ *   RENAME    → `config.label` / `config.href` change, `id` does not.
+ *   RE-PARENT → `parentId` changes, `id` does not.
+ */
+export interface WidgetInstance {
+    id: string;
+    /** Registry key. Changing the type is a delete + create, never an edit — the config shape differs. */
+    type: string;
+    /** Owning T1 region id. */
+    regionId: string;
+    /** Containing instance id, or `null` for a region root. */
+    parentId: string | null;
+    order: number;
+    /**
+     * Discrete span, reusing the SAME closed vocabulary `utils/pack-by-span.ts`'s
+     * `RowSpan`, `field-ui-meta.ts`'s `FieldRow` and `CardElementSpan` already
+     * share. Owner's rule: *"the resize should be in breakpoints not on
+     * stretching"* — so four options, never a drag handle.
+     */
+    span?: "full" | "pair" | "third" | "quarter";
+    /**
+     * Three-valued by omission: `"on"` / `"off"` / absent = inherit the
+     * definition's `defaultOn`. Absent is the overwhelmingly common case, which
+     * is what keeps the config table sparse — see the key count in
+     * docs/overhaul/widget-architecture.md §8.
+     */
+    state?: "on" | "off";
+    /** Per-type config bag. Labels, hrefs, titles, data sources live HERE, never in the identity. */
+    config?: Record<string, unknown>;
+    /** Instance-level content tags, AND-ed with the definition's `governedBy`. */
+    contentTags?: readonly WidgetContentTag[];
+    /** Clone tracking (A16). `templateSlot` is the merge key when a required template element is pushed into clones. */
+    templateId?: string;
+    templateVersion?: number;
+    templateSlot?: string;
+    /**
+     * Legacy derived keys this instance also answers to. WRITTEN ONCE at
+     * migration time from the href as it then was, and NEVER re-derived — that
+     * is the entire point. The resolver is the only code that knows derived ids
+     * ever existed.
+     */
+    aliases?: readonly string[];
+}
+/** Everything the resolver needs about the viewer and the surface. No globals, no I/O. */
+export interface WidgetResolveContext {
+    /** The surface being rendered, matched against `WidgetDef.surfaces` and `WidgetRegionDef.surface`. */
+    surface: string;
+    /**
+     * The viewer's PERMISSION set. A set of permissions, never a role — a role
+     * is a named bundle of permissions and the bundle is data.
+     */
+    permissions?: ReadonlySet<string>;
+    /**
+     * The ONE content-visibility predicate, injected. Defaults to "always
+     * visible" when omitted, matching `isContentVisible`'s own
+     * absent-means-enabled rule so an install predating tagging does not have
+     * everything vanish.
+     */
+    isContentVisible?: (tags: readonly WidgetContentTag[] | undefined) => boolean;
+    /** Fields already hidden by the surface's own `fieldVisibility/{surfaceId}` map or a `when` predicate. */
+    hiddenFields?: readonly string[];
+    /** True for an admin with edit mode on: blocked widgets resolve to `visible: false` but are RETAINED for the dimmed editor affordance. */
+    editMode?: boolean;
+}
+/** Why a widget is not visible. Exactly one reason is reported — the first that applies, in this order. */
+export type WidgetBlockReason = "unknown-type" | "unknown-region" | "region-disabled" | "wrong-surface" | "content-tag-off" | "missing-permission" | "state-off" | "parent-off" | "orphan-parent" | "cycle" | "disallowed-child";
+export interface ResolvedWidget {
+    instance: WidgetInstance;
+    def: WidgetDef | undefined;
+    /** The effective verdict. `false` means this widget does not render for this viewer on this surface. */
+    visible: boolean;
+    /** Set when `visible` is false. */
+    reason?: WidgetBlockReason;
+    /** Resolved children, already ordered. */
+    children: ResolvedWidget[];
+    depth: number;
+}
+/** A config problem worth telling an operator about, in the SAME shape Lane G's `validateRequiredFieldConfig` already returns. */
+export interface WidgetConfigProblem {
+    scope: string;
+    field: string;
+    problem: string;
+}
+export interface WidgetTreeResult {
+    /** Region roots, ordered. */
+    roots: ResolvedWidget[];
+    byId: Map<string, ResolvedWidget>;
+    /**
+     * Union of `ownsFields` over every widget that is NOT visible, plus
+     * `ctx.hiddenFields`. This is the value that must be handed to the
+     * required-field resolver — see `partitionRequiredRules`.
+     */
+    unreachableFields: string[];
+    /** Operator-facing problems: an explicit `on` under an off parent, a disallowed child, a cycle, an orphan. */
+    problems: WidgetConfigProblem[];
+}

package/dist/ui/widgets/types.js

@@ -0,0 +1,45 @@
+/**
+ * Widget model — the declarative half.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE HAS NO `render` AND NO REACT IMPORT
+ * ---------------------------------------------------------------------------
+ *
+ * A widget DEFINITION has to be readable by four callers that have nothing
+ * else in common: the renderer (client), the admin editor (client), the
+ * config validator (server), and the required-field resolver (isomorphic,
+ * and it is a pure Zod refinement with no React in scope at all). Putting
+ * `render` on the definition forces every one of them to pull React.
+ *
+ * That is not a hypothetical. `src/constants/navigation.tsx` carries a 🛑
+ * comment for Root Cause #76: it called `navItemId` at module scope, the
+ * import resolved through a `"use client"` entry, and the Vercel build died
+ * with *"Attempted to call navItemId() from the server but navItemId is on
+ * the client"* — while every local check passed. The same shape applies here
+ * with more call sites.
+ *
+ * So the split is: capabilities + placement live here (plain data, no JSX),
+ * and renderers are a separate `Record<type, (ctx) => ReactNode>` map in a
+ * `.tsx` module that only the rendering surface imports. This mirrors
+ * `_internal/shared/features/dashboard/recent-entry.ts`, which deliberately
+ * stays "schema-free … matching every other type in it", and
+ * `SECTION_REGISTRY`, which is the one place that holds `render`.
+ *
+ * ---------------------------------------------------------------------------
+ * THE TIERS (see docs/overhaul/widget-architecture.md §2 for the argument)
+ * ---------------------------------------------------------------------------
+ *
+ *   T0 surface  — a route family / host page.          NOT a widget.
+ *   T1 region   — a declared hole in a template.       Code-only; its CHILDREN are config.
+ *   T2 section  — a container widget, typed config.    CONFIG.
+ *   T3 element  — a leaf widget, down to a single link. CONFIG.
+ *   T4 field    — a form input or display row.         CONFIG (existing `fieldVisibility`).
+ *   T5 atom     — Button / Badge / Icon / Text.        NEVER widgetised; token-themed.
+ *
+ * The discriminator between T3 and T5, which is the whole granularity
+ * decision in one question: **does this thing carry its own content/target,
+ * or does it render its parent's data?** Own `href`/`label`/`body` → T3.
+ * Renders the parent's field → a T4 field key on the parent. Pure
+ * presentation of either → T5.
+ */
+export {};

package/dist/utils/id-generators.d.ts

@@ -21,7 +21,7 @@ export interface GenerateProductIdInput {
     customId?: string;
 }
 export declare function generateProductId(input: GenerateProductIdInput): string;
-export interface GenerateAuctionIdInput {
+export interface GenerateCollectorDropIdInput {
     name: string;
     category: string;
     condition: "new" | "used" | "refurbished";
@@ -29,7 +29,7 @@ export interface GenerateAuctionIdInput {
     count?: number;
     customId?: string;
 }
-export declare function generateAuctionId(input: GenerateAuctionIdInput): string;
+export declare function generateCollectorDropId(input: GenerateCollectorDropIdInput): string;
 export interface GeneratePreOrderIdInput {
     name: string;
     category: string;
@@ -171,7 +171,7 @@ export interface GenerateProductVideoFilenameInput {
     index?: number;
     ext?: string;
 }
-export interface GenerateAuctionImageFilenameInput {
+export interface GenerateCollectorDropImageFilenameInput {
     name: string;
     category: string;
     store: string;
@@ -222,8 +222,8 @@ export type MediaFilenameContext = ({
 } & GenerateReviewImageFilenameInput) | ({
     type: "review-video";
 } & GenerateReviewVideoFilenameInput) | ({
-    type: "auction-image";
-} & GenerateAuctionImageFilenameInput) | ({
+    type: "collectordrop-image";
+} & GenerateCollectorDropImageFilenameInput) | ({
     type: "preorder-image";
 } & GeneratePreOrderImageFilenameInput) | {
     type: "store-logo";

package/dist/utils/id-generators.js

@@ -32,11 +32,11 @@ export function generateProductId(input) {
     const count = input.count || 1;
     return `product-${slugify(input.name)}-${slugify(input.category)}-${input.condition}-${slugify(input.sellerName)}-${count}`;
 }
-export function generateAuctionId(input) {
+export function generateCollectorDropId(input) {
     if (input.customId?.trim())
         return input.customId.trim();
     const count = input.count || 1;
-    return `auction-${slugify(input.name)}-${slugify(input.category)}-${input.condition}-${slugify(input.sellerName)}-${count}`;
+    return `collectordrop-${slugify(input.name)}-${slugify(input.category)}-${input.condition}-${slugify(input.sellerName)}-${count}`;
 }
 export function generatePreOrderId(input) {
     if (input.customId?.trim())
@@ -229,8 +229,12 @@ export function generateBarcodeFromId(id) {
 export function generateQRCodeData(id, baseUrl) {
     if (id.startsWith("product-"))
         return `${baseUrl}/products/${id}`;
+    if (id.startsWith("collectordrop-"))
+        return `${baseUrl}/collector-drops/${id}`;
+    // Pre-rename slug prefix — an id written before the collector-drop rename
+    // still routes to the right page rather than the catch-all below.
     if (id.startsWith("auction-"))
-        return `${baseUrl}/auctions/${id}`;
+        return `${baseUrl}/collector-drops/${id}`;
     if (id.startsWith("category-"))
         return `${baseUrl}/categories/${id}`;
     if (id.startsWith("store-"))
@@ -244,7 +248,7 @@ export function generateQRCodeData(id, baseUrl) {
 // Naming patterns (all lowercase, hyphen-separated):
 //   product image  → product-{name}-{category}-{store}-image-{n}.{ext}
 //   product video  → product-{name}-{category}-{store}-video-{n}.{ext}
-//   auction image  → auction-{name}-{category}-{store}-image-{n}.{ext}
+//   collector drop image  → collectordrop-{name}-{category}-{store}-image-{n}.{ext}
 //   preorder image → preorder-{name}-{category}-{store}-image-{n}.{ext}
 //   store logo     → store-{name}-logo.{ext}
 //   store banner   → store-{name}-banner.{ext}
@@ -278,13 +282,13 @@ function generateProductVideoFilename(input) {
     const ext = (input.ext ?? "mp4").replace(/^\./, "");
     return `product-${name}-${category}-${store}-video-${n}.${ext}`;
 }
-function generateAuctionImageFilename(input) {
+function generateCollectorDropImageFilename(input) {
     const name = slugify(input.name).substring(0, 40).replace(/-+$/, "");
     const category = slugify(input.category).substring(0, 20).replace(/-+$/, "");
     const store = slugify(input.store).substring(0, 20).replace(/-+$/, "");
     const n = input.index ?? 1;
     const ext = (input.ext ?? "webp").replace(/^\./, "");
-    return `auction-${name}-${category}-${store}-image-${n}.${ext}`;
+    return `collectordrop-${name}-${category}-${store}-image-${n}.${ext}`;
 }
 function generatePreOrderImageFilename(input) {
     const name = slugify(input.name).substring(0, 40).replace(/-+$/, "");
@@ -391,8 +395,8 @@ export function generateMediaFilename(ctx) {
             return generateReviewImageFilename(ctx);
         case "review-video":
             return generateReviewVideoFilename(ctx);
-        case "auction-image":
-            return generateAuctionImageFilename(ctx);
+        case "collectordrop-image":
+            return generateCollectorDropImageFilename(ctx);
         case "preorder-image":
             return generatePreOrderImageFilename(ctx);
         case "store-logo":
@@ -487,7 +491,7 @@ export function generateMediaFilename(ctx) {
  * validator anchored on the compound-prefix shape and rejected real output
  * from every generator except invoice/payout-doc/shipping-proof/
  * refund-proof/catalogue-image — causing /api/media/sign to 500 for
- * product/review/auction/preorder/store/brand/blog/event/category/user/
+ * product/review/collector drop/preorder/store/brand/blog/event/category/user/
  * carousel/rich-text uploads. Each pattern below mirrors one generator
  * function's actual output shape. blog-cover/blog-content-image/
  * blog-additional-image all dispatch to the same generator as blog-image
@@ -504,7 +508,7 @@ const MEDIA_FILENAME_PATTERNS = [
     { context: "product-video", pattern: new RegExp(`^product-${SLUG_PART}-video-\\d+\\.${EXT_PART}$`) },
     { context: "review-image", pattern: new RegExp(`^review-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
     { context: "review-video", pattern: new RegExp(`^review-${SLUG_PART}-video-1\\.${EXT_PART}$`) },
-    { context: "auction-image", pattern: new RegExp(`^auction-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "collectordrop-image", pattern: new RegExp(`^collectordrop-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
     { context: "preorder-image", pattern: new RegExp(`^preorder-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
     { context: "store-logo", pattern: new RegExp(`^store-${SLUG_PART}-logo\\.${EXT_PART}$`) },
     { context: "store-banner", pattern: new RegExp(`^store-${SLUG_PART}-banner\\.${EXT_PART}$`) },

package/dist/utils/listing-params.d.ts

@@ -2,7 +2,7 @@
  * Standardised listing-API param reader (Q2 — S12).
  *
  * All public listing routes (/api/products, /api/pre-orders, /api/stores,
- * /api/auctions, and the per-store nested variants) accept short canonical
+ * /api/collector-drops, and the per-store nested variants) accept short canonical
  * names:
  *
  *   f      — filters (Sieve filter string)

package/dist/utils/listing-params.js

@@ -2,7 +2,7 @@
  * Standardised listing-API param reader (Q2 — S12).
  *
  * All public listing routes (/api/products, /api/pre-orders, /api/stores,
- * /api/auctions, and the per-store nested variants) accept short canonical
+ * /api/collector-drops, and the per-store nested variants) accept short canonical
  * names:
  *
  *   f      — filters (Sieve filter string)

package/dist/utils/pack-by-span.d.ts

@@ -0,0 +1,21 @@
+/** How much of a row an item claims on desktop. Everything is 1-up on mobile. */
+export type RowSpan = "full" | "pair" | "third" | "quarter";
+/** Span → the `<FormGroup columns>` value it packs into. */
+export declare const ROW_COLUMNS: Record<RowSpan, 1 | 2 | 3 | 4>;
+/**
+ * Groups items into rows by span: a `"full"` item always breaks the current
+ * row (so a wide element is never squeezed alongside a narrow one); mixed
+ * spans start a new row too (two `"pair"` items make a clean 2-up; a
+ * `"pair"` next to a `"third"` makes neither); a row fills up to
+ * `ROW_COLUMNS[span]` items before starting the next one.
+ *
+ * `getSpan` defaults missing/undefined spans to `"full"` — the correct
+ * default for a widget card (every stored card before this mechanism
+ * existed has no span data at all, and must keep rendering as one-per-row,
+ * identical to today's single vertical stack). This differs from
+ * `build-sections.tsx`'s `packRows`, which defaults to `"pair"` — a
+ * reasonable default for a FORM field (most inputs are comfortably half-
+ * width), but wrong for a widget element that might be a full-bleed image or
+ * a long paragraph of rich text.
+ */
+export declare function packBySpan<T>(items: T[], getSpan: (item: T) => RowSpan | undefined): T[][];

package/dist/utils/pack-by-span.js

@@ -0,0 +1,84 @@
+/*
+ * WHY: `appkit/src/features/shell/build-sections.tsx`'s `packRows()` already
+ *      solves "group same-span items into equal-width rows, full width on
+ *      mobile" for form fields (`FieldRow`). Phase 3B's widget system
+ *      (`CardElement`/`DashboardCard`, `_internal/shared/features/dashboard/
+ *      recent-entry.ts`) needs the IDENTICAL algorithm for a different item
+ *      type, at the same moment the form-field version is under active,
+ *      heavy churn on a parallel branch (`feat/form-validation`) — see
+ *      `build-sections.tsx`'s own packRows doc comment and the plan's "tree
+ *      moved substantially underneath this plan" note.
+ *
+ *      Flagged rather than silently duplicated: this file is a DELIBERATE,
+ *      temporary second copy of the packing algorithm (not of the forms
+ *      feature's types), kept deliberately out of `features/shell/` so
+ *      touching it never collides with that branch's edits. Once the branch
+ *      settles, `packRows` in `build-sections.tsx` should be rewritten as a
+ *      one-line delegate to `packBySpan` here — see the Duplication Decision
+ *      Framework's criterion 3 ("lifetime is short") for why this is the
+ *      correct call now rather than either leaving two independent
+ *      algorithms forever or risking a merge conflict today.
+ *
+ * WHAT: `RowSpan` (how much of a row an item claims on desktop — full width
+ *       on mobile regardless), `ROW_COLUMNS` (span → column count), and
+ *       `packBySpan` (group same-span items into rows up to that count,
+ *       breaking on `"full"` or a span change).
+ *
+ * EXPORTS: RowSpan, ROW_COLUMNS, packBySpan
+ *
+ * @tag domain:layout
+ * @tag layer:utils
+ * @tag pattern:none
+ * @tag access:universal
+ * @tag consumers:DashboardCardRenderer,AdminComposableRegion
+ * @tag sideEffects:none
+ */
+/** Span → the `<FormGroup columns>` value it packs into. */
+export const ROW_COLUMNS = {
+    full: 1,
+    pair: 2,
+    third: 3,
+    quarter: 4,
+};
+/**
+ * Groups items into rows by span: a `"full"` item always breaks the current
+ * row (so a wide element is never squeezed alongside a narrow one); mixed
+ * spans start a new row too (two `"pair"` items make a clean 2-up; a
+ * `"pair"` next to a `"third"` makes neither); a row fills up to
+ * `ROW_COLUMNS[span]` items before starting the next one.
+ *
+ * `getSpan` defaults missing/undefined spans to `"full"` — the correct
+ * default for a widget card (every stored card before this mechanism
+ * existed has no span data at all, and must keep rendering as one-per-row,
+ * identical to today's single vertical stack). This differs from
+ * `build-sections.tsx`'s `packRows`, which defaults to `"pair"` — a
+ * reasonable default for a FORM field (most inputs are comfortably half-
+ * width), but wrong for a widget element that might be a full-bleed image or
+ * a long paragraph of rich text.
+ */
+export function packBySpan(items, getSpan) {
+    const rows = [];
+    let current = [];
+    let currentSpan = null;
+    const flush = () => {
+        if (current.length > 0)
+            rows.push(current);
+        current = [];
+        currentSpan = null;
+    };
+    for (const item of items) {
+        const span = getSpan(item) ?? "full";
+        if (span === "full") {
+            flush();
+            rows.push([item]);
+            continue;
+        }
+        if (currentSpan !== null && (span !== currentSpan || current.length >= ROW_COLUMNS[span])) {
+            flush();
+        }
+        current.push(item);
+        currentSpan = span;
+    }
+    flush();
+    return rows;
+}

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

@@ -6,7 +6,7 @@ import type { EventDocument } from "../features/events/schemas/firestore";
 import type { BlogPostDocument } from "../features/blog/schemas/firestore";
 import type { ReviewDocument } from "../features/reviews/schemas/firestore";
 import type { OrderDocument } from "../features/orders/schemas/firestore";
-import type { BidDocument } from "../features/auctions/schemas/firestore";
+import type { BidDocument } from "../features/collector-drops/schemas/firestore";
 import type { CouponDocument } from "../features/promotions/schemas/firestore";
 import type { OfferDocument } from "../features/seller/schemas/firestore";
 /** products — title, description, brand, taxonomy, condition, card/grading, specs. */
@@ -103,7 +103,7 @@ export declare function buildScammerSearchTxt(s: Partial<ScammerDocument>): stri
  * bids — what a buyer or a seller actually looks a bid up BY.
  *
  * `productTitle` is what a buyer searching their own bids means ("which
- * auction was that?"); `userName` is what a seller scanning bids on their
+ * collector drop was that?"); `userName` is what a seller scanning bids on their
  * listing means ("has Ravi bid?").
  *
  * 🛑 `userEmail` is ABSENT. It is the single entry in `BID_PII_FIELDS`, and a

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

@@ -298,7 +298,7 @@ export function buildScammerSearchTxt(s) {
  * bids — what a buyer or a seller actually looks a bid up BY.
  *
  * `productTitle` is what a buyer searching their own bids means ("which
- * auction was that?"); `userName` is what a seller scanning bids on their
+ * collector drop was that?"); `userName` is what a seller scanning bids on their
  * listing means ("has Ravi bid?").
  *
  * 🛑 `userEmail` is ABSENT. It is the single entry in `BID_PII_FIELDS`, and a