@mohasinac/appkit 4.14.0 → 4.16.0

package/dist/features/shell/field-ui-meta.js

@@ -0,0 +1,324 @@
+/*
+ * WHY: Which section a field belongs to, and whether it shares a row with its
+ *      neighbour, were conventions written in a table in a plan document. A
+ *      convention drifts; 70 bare `grid-cols-2` in the tree — each one two
+ *      columns wide at 320px — are what that drift looks like. Zod 4 lets the
+ *      rule live on the field it describes, so the schema becomes the single
+ *      source of validation, section membership AND layout.
+ * WHAT: `FieldUiMeta`, the typed `ui` registry, and `inferFieldUiMeta` — the
+ *       heuristic that means only `section` has to be stated per field.
+ *
+ * ## 🛑 There are TWO zods in this repo, and that decided the design
+ *
+ * Measured 2026-08-24: the app depends on **zod 4.4.3**, but `appkit`'s own
+ * `package.json` declares `zod: ^3.24.0` and a v3 copy is nested at
+ * `node_modules/@mohasinac/appkit/node_modules/zod` (3.25.76). Verified with
+ * `createRequire`: appkit's shipped `dist` resolves `"zod"` to that nested v3,
+ * while consumer code resolves to root v4. Two instances, one bundle — the
+ * Root Cause #19 shape, on a package the dedupe script does not cover.
+ *
+ * So `z.registry<FieldUiMeta>()` is **not usable here**: it is a zod-4 API and
+ * appkit compiles against v3. Aligning the two is a dependency major across
+ * the 76 appkit files that import zod — its own wave, not a drive-by inside a
+ * spine wave.
+ *
+ * This registry is therefore a plain `WeakMap` keyed by schema instance, which
+ * is what `z.registry()` is internally. It behaves identically, works on both
+ * majors, and is strictly MORE robust to the split: object identity does not
+ * care which zod class produced the object. `annotate()` is typed, so a typo
+ * (`rows:` for `row:`) is a compile error — the property `.meta()` never had.
+ *
+ * Everything that introspects a schema below reads BOTH shapes for the same
+ * reason: zod 3 says `_def.typeName === "ZodOptional"`, zod 4 says
+ * `_def.type === "optional"`, and this file sees both at runtime.
+ *
+ * ## 🛑 The ordering trap — metadata MUST be the last call in the chain
+ *
+ * Verified at runtime:
+ *
+ *     annotate(z.string(), {...}).optional()   // ✗ meta LOST → lookup undefined
+ *     annotate(z.string().optional(), {...})   // ✓ survives
+ *
+ * Every wrapper (`.optional()`, `.nullable()`, `.default()`, `.catch()`)
+ * returns a NEW schema instance, and the registry is keyed by instance. Most
+ * fields are optional, so getting this backwards silently drops layout for the
+ * majority of them. `audit-field-ui-meta` enforces the ordering.
+ *
+ * EXPORTS:
+ *   FieldUiMeta, FieldRow, FieldKind, CalculatedTier, ui, annotate,
+ *   inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, ROW_COLUMNS
+ *
+ * @tag domain:forms
+ * @tag layer:shared
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:buildSectionsFromSchema,audit-field-ui-meta
+ * @tag sideEffects:none
+ */
+/**
+ * The registry. A module-level singleton, because the whole point is that
+ * every form schema in the app annotates into the same place and can be
+ * queried as one ("every media field", "every quick field", "every field with
+ * no section").
+ *
+ * `WeakMap` so annotating a schema never keeps it alive.
+ */
+const REGISTRY = new WeakMap();
+export const ui = {
+    /** Attach metadata to a schema instance. Returns the SAME instance. */
+    add(schema, meta) {
+        REGISTRY.set(schema, meta);
+        return schema;
+    },
+    get(schema) {
+        return REGISTRY.get(schema);
+    },
+    has(schema) {
+        return REGISTRY.has(schema);
+    },
+};
+/**
+ * Annotate a field. **Must be the outermost call in the chain** — see the
+ * ordering trap in the header.
+ *
+ *     name:  annotate(z.string().min(1),   { section: "basics", quick: true }),
+ *     photo: annotate(z.string().optional(), { section: "media" }),
+ *
+ * Wrapping the call rather than chaining off it (`.register()`-style) is
+ * deliberate: it puts the schema visually INSIDE the annotation, so appending
+ * `.optional()` afterwards looks as wrong as it is.
+ */
+export function annotate(schema, meta) {
+    return ui.add(schema, meta);
+}
+/** `row` → the `<FormGroup columns>` value it packs into. */
+export const ROW_COLUMNS = {
+    full: 1,
+    pair: 2,
+    third: 3,
+    quarter: 4,
+};
+// ---------------------------------------------------------------------------
+// Inference
+// ---------------------------------------------------------------------------
+/**
+ * Normalise a zod type discriminator across majors.
+ * zod 3: `_def.typeName === "ZodOptional"` · zod 4: `_def.type === "optional"`.
+ */
+function typeOf(schema) {
+    const def = schema._def;
+    if (def?.type)
+        return def.type; // v4, already lowercase
+    const name = def?.typeName; // v3, "ZodOptional"
+    return name ? name.replace(/^Zod/, "").toLowerCase() : "";
+}
+/** Wrappers that produce a new instance around an inner type. */
+const WRAPPERS = new Set(["optional", "nullable", "default", "catch", "readonly", "nonoptional"]);
+/**
+ * Strip `.optional()` / `.nullable()` / `.default()` / `.catch()` to reach the
+ * type that actually decides the control. Returns the innermost schema and its
+ * normalised type discriminator.
+ *
+ * Reads `_def` because zod exposes no public accessor for this, on either
+ * major. Depth-bounded rather than trusting the shape: `_def` is internal, and
+ * this must degrade to "text" rather than loop if a future zod reshapes it.
+ */
+export function unwrapSchema(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 10; depth++) {
+        const def = current._def;
+        const type = typeOf(current);
+        if (!WRAPPERS.has(type) || !def?.innerType)
+            return { schema: current, type };
+        current = def.innerType;
+    }
+    return { schema: current, type: "" };
+}
+/**
+ * The `max()` bound on a string schema, when it declares one — the signal that
+ * separates a text input from a textarea.
+ *
+ * The two majors store checks completely differently:
+ *   v3: `_def.checks = [{ kind: "max", value: 300 }]`
+ *   v4: `_def.checks = [{ _zod: { def: { check: "max_length", maximum: 300 } } }]`
+ */
+function stringMaxLength(schema) {
+    const checks = schema._def?.checks;
+    if (!Array.isArray(checks))
+        return undefined;
+    for (const check of checks) {
+        const v4 = check?._zod?.def;
+        if (v4?.check === "max_length" && typeof v4.maximum === "number")
+            return v4.maximum;
+        const v3 = check;
+        if (v3?.kind === "max" && typeof v3.value === "number")
+            return v3.value;
+    }
+    return undefined;
+}
+/**
+ * Enum members. v4 exposes `.options`; v3 keeps them on `_def.values`, and for
+ * a native enum on `_def.values` as an object.
+ */
+function enumOptions(schema) {
+    const direct = schema.options;
+    if (Array.isArray(direct))
+        return direct.filter((o) => typeof o === "string");
+    const values = schema._def?.values;
+    if (Array.isArray(values))
+        return values.filter((o) => typeof o === "string");
+    if (values && typeof values === "object") {
+        return Object.values(values).filter((o) => typeof o === "string");
+    }
+    return undefined;
+}
+/** Public: the option list for a select-shaped field, or null. */
+export function schemaEnumOptions(schema) {
+    const { schema: inner } = unwrapSchema(schema);
+    return enumOptions(inner) ?? null;
+}
+/** Public: whether a field's type is optional-wrapped (i.e. not required). */
+export function schemaIsOptional(schema) {
+    const type = typeOf(schema);
+    return type === "optional" || type === "default" || type === "nullish";
+}
+/**
+ * The `.shape` of an object schema, seeing through effects wrappers.
+ *
+ * `.superRefine()` / `.refine()` / `.transform()` return a wrapper that does
+ * NOT expose `.shape` — verified: `z.object({...}).superRefine(fn)` has
+ * `_def.typeName === "ZodEffects"`, `.shape === undefined`, and the real object
+ * on `_def.schema`. Reading `.shape` directly therefore returns nothing for any
+ * schema with a cross-field rule, which is most of the interesting ones (the
+ * payout form's UPI-vs-bank branch is exactly this shape).
+ *
+ * Failing to unwrap would not error — it would silently derive a form with
+ * ZERO sections, which is the quiet-wrong-answer failure mode this whole wave
+ * exists to eliminate.
+ */
+export function objectShape(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 10; depth++) {
+        const direct = current.shape;
+        if (direct)
+            return direct;
+        const def = current._def;
+        const next = def?.schema ?? def?.innerType ?? def?.in;
+        if (!next)
+            return null;
+        current = next;
+    }
+    return null;
+}
+/**
+ * Name patterns override the Zod type, because a name carries intent a type
+ * cannot. `images` is `ZodArray` but it is a media field, not a list editor;
+ * `description` is `ZodString` but it is a textarea.
+ *
+ * Ordered — the first match wins, so the media test runs before the long-text
+ * one (`coverImage` must not become a textarea).
+ */
+const NAME_RULES = [
+    {
+        // Media claims a full row ALWAYS, and forces its section to keepMounted:
+        // a MediaUploadField stacks a source-tab strip, a drop target, a progress
+        // bar and a preview, and collapsing it mid-upload discards the transfer.
+        test: /(^|[a-z])(image|images|photo|video|media|avatar|banner|logo|cover|thumbnail)([A-Z]|s?$)/i,
+        meta: { kind: "media", row: "full", sectionKeepMounted: true },
+    },
+    {
+        test: /^(description|body|content|notes?|bio|message|excerpt|answer|returnPolicy)$/i,
+        meta: { kind: "textarea", row: "full" },
+    },
+    {
+        // Long single inputs: truncating a URL or an address into half a row makes
+        // it unreadable, so they take the whole row even though they are short types.
+        test: /^(url|slug|email|title|name|displayName|headline|address|addressLine1|addressLine2|line1|line2)$/i,
+        meta: { row: "full" },
+    },
+    {
+        test: /^(firstName|lastName|city|state|postcode|pincode|postalCode|ifsc|gstin|pan|hsn|price|rate|percent|quantity|phone)$/i,
+        meta: { row: "pair" },
+    },
+];
+/**
+ * Fields nothing should ever render as an input — ids, audit stamps and
+ * counters. Marked `derived` so `audit-form-field-roundtrip` reads them as
+ * server-owned rather than as unreachable schema fields.
+ */
+const SERVER_OWNED = /^(id|createdAt|updatedAt|createdBy|updatedBy|ownerId|authorId|userId|views|viewCount|productCount|usageCount|helpfulCount|replyCount|reportCount)$/;
+/** Zod type → its default control and row span. */
+function fromZodType(type, inner) {
+    switch (type) {
+        case "boolean":
+            // Several per wrapping row — a switch plus label is short, and stacking
+            // them one-per-row makes a settings section endless.
+            return { kind: "toggle", row: "quarter" };
+        case "enum":
+        case "nativeEnum":
+        case "literal":
+        case "union":
+            return { kind: "select", row: "pair" };
+        case "date":
+            return { kind: "date", row: "pair" };
+        case "number":
+        case "bigint":
+            return { kind: "number", row: "pair" };
+        case "array":
+            return { kind: "list", row: "full" };
+        case "object":
+        case "record":
+            return { kind: "list", row: "full" };
+        case "string": {
+            const max = stringMaxLength(inner);
+            return max != null && max > 200
+                ? { kind: "textarea", row: "full" }
+                : { kind: "text", row: "pair" };
+        }
+        default:
+            return { kind: "text", row: "pair" };
+    }
+}
+/**
+ * Everything about a field's layout that can be derived from its name and its
+ * Zod type. `section` is never inferred, so the return type is a Partial —
+ * `resolveFieldUiMeta` is what merges it with the explicit registration.
+ *
+ * This is what makes annotation cheap: a 13-field form is 13 short
+ * `.register(ui, { section: "…" })` calls, not 13 full metadata objects.
+ */
+export function inferFieldUiMeta(name, schema) {
+    const { schema: inner, type } = unwrapSchema(schema);
+    const meta = { ...fromZodType(type, inner) };
+    for (const rule of NAME_RULES) {
+        if (rule.test.test(name)) {
+            Object.assign(meta, rule.meta);
+            break;
+        }
+    }
+    if (SERVER_OWNED.test(name)) {
+        meta.derived = true;
+        meta.tier = meta.tier ?? "t2-server";
+    }
+    // >5 options is the standing PaginatedSelect threshold. Recorded as `help`
+    // rather than a separate flag so the renderer can decide without a second
+    // source of truth about what "many options" means.
+    const options = enumOptions(inner);
+    if (meta.kind === "select" && options != null && options.length > 5) {
+        meta.help = meta.help ?? "paginated";
+    }
+    return meta;
+}
+/**
+ * The field's final metadata: inference first, explicit registration on top.
+ *
+ * Returns `null` when the field has no registration at all — the caller
+ * decides whether that is a hard error (a registered form schema, where
+ * `section` is mandatory) or a fallback (an ad-hoc schema being previewed).
+ */
+export function resolveFieldUiMeta(name, schema) {
+    const explicit = ui.get(schema);
+    if (!explicit)
+        return null;
+    return { ...inferFieldUiMeta(name, schema), ...explicit };
+}

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

@@ -10,5 +10,9 @@ export type { SectionDef, SectionFormProps, UseSectionFormNavResult, } from "./S
 export { SectionForm, useSectionFormNav, orderSections, buildFieldToSectionIndex, sectionAnchorId, } from "./SectionForm";
 export type { EntityFormDefinition } from "./entity-form";
 export { deriveQuickFields, deriveQuickFieldNames, allDefinitionFields, applyDerive, assertNoDeriveCollision, humaniseFieldName, } from "./entity-form";
+export type { FieldUiMeta, FieldRow, FieldKind, CalculatedTier, } from "./field-ui-meta";
+export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
+export type { ResolvedField, FieldRenderer, BuildSectionsOptions, } from "./build-sections";
+export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, } from "./build-sections";
 export type { TitleDescriptionGroupProps, ImageFieldGroupProps, SeoFieldGroupProps, StatusFieldGroupProps, StatusFieldGroupOption, } from "./field-groups";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";

package/dist/features/shell/index.js

@@ -4,4 +4,6 @@ export { QuickFormDrawer } from "./QuickFormDrawer";
 export { StepForm, StepFormActions, StepIndicator } from "./StepForm";
 export { SectionForm, useSectionFormNav, orderSections, buildFieldToSectionIndex, sectionAnchorId, } from "./SectionForm";
 export { deriveQuickFields, deriveQuickFieldNames, allDefinitionFields, applyDerive, assertNoDeriveCollision, humaniseFieldName, } from "./entity-form";
+export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
+export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, } from "./build-sections";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";

package/dist/features/shipments/schemas/validation.d.ts

@@ -230,36 +230,36 @@ export declare const createShipmentItemSchema: z.ZodEffects<z.ZodObject<{
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }, {
     title: string;
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }>, {
     title: string;
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }, {
     title: string;
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }>;
 export declare const updateShipmentItemSchema: z.ZodObject<{
@@ -278,11 +278,11 @@ export declare const updateShipmentItemSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     title?: string | undefined;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
-    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
+    brandSlug?: string | undefined;
     quantity?: number | undefined;
+    categorySlugs?: string[] | undefined;
+    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     isForSelfUse?: boolean | undefined;
     linkedProductId?: string | null | undefined;
     linkedProductSlug?: string | null | undefined;
@@ -290,11 +290,11 @@ export declare const updateShipmentItemSchema: z.ZodObject<{
 }, {
     title?: string | undefined;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
-    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
+    brandSlug?: string | undefined;
     quantity?: number | undefined;
+    categorySlugs?: string[] | undefined;
+    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     isForSelfUse?: boolean | undefined;
     linkedProductId?: string | null | undefined;
     linkedProductSlug?: string | null | undefined;
@@ -319,36 +319,36 @@ export declare const bulkShipmentItemsSchema: z.ZodEffects<z.ZodArray<z.ZodObjec
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }, {
     title: string;
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }>, "many">, {
     title: string;
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }[], {
     title: string;
     quantity: number;
     isForSelfUse: boolean;
     notes?: string | undefined;
-    categorySlugs?: string[] | undefined;
-    brandSlug?: string | undefined;
     price?: number | undefined;
+    brandSlug?: string | undefined;
+    categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }[]>;
 export type CreateShipmentInput = z.infer<typeof createShipmentSchema>;

package/dist/features/status-history/components/StatusTimeline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * StatusTimeline — the one rail that renders any entity's status history.
+ *
+ * Both the order timeline and the offer timeline were about to be written
+ * separately, against the same `StatusChangeEntry[]` shape, with the same
+ * dot-and-connector rail and the same two load-bearing rules. That is the
+ * duplication the Rule of Three exists to prevent, so this is the single
+ * implementation and each feature supplies only its own phase vocabulary.
+ *
+ * ## Two rules this component must never break
+ *
+ * **1. Never fabricate a timestamp.** A step with no recorded date renders an
+ * em-dash. Not `new Date()`, and not a proxy field: `updatedAt` means "last
+ * write of any kind" and `expiresAt` is a deadline, not an event. An offer
+ * that expired has no timestamp at all because `expireMany` never wrote one
+ * before this wave, and inventing one would make the record lie.
+ *
+ * **2. It never fetches.** A client component that loaded its own chain would
+ * fire one request per opened modal per portal. The API returns the chain;
+ * this renders it.
+ */
+import type { ReactNode } from "react";
+import type { FieldChange } from "../../../_internal/shared/history/index";
+/** The client-facing entry shape — dates already serialised to ISO. */
+export interface TimelineEntry {
+    at: string;
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    trigger: string;
+}
+export interface TimelineStep {
+    key: string;
+    label: string;
+    /** ISO string, or absent — absent renders an em-dash, never a guess. */
+    date?: string;
+    /** Terminal-negative: cancelled, declined, rejected. Renders in error tone. */
+    negative?: boolean;
+    /**
+     * Neutral-but-ended, e.g. a superseded offer round. Deliberately distinct
+     * from `negative`: the buyer did not walk away, they countered, and the
+     * negotiation continued.
+     */
+    muted?: boolean;
+    actorRole?: TimelineEntry["actorRole"];
+    reason?: string;
+    note?: string;
+    /** Round divider text for multi-round chains ("Round 2"). */
+    roundLabel?: string;
+}
+export interface StatusTimelineProps {
+    title?: string;
+    steps: TimelineStep[];
+    /** Entries trimmed off the front of the capped history, if any. */
+    truncatedCount?: number;
+    /** Rendered below the rail — tracking details, chain summary, etc. */
+    footer?: ReactNode;
+    /** Suppress `footer` when the last step is terminal-negative. */
+    hideFooterWhenNegative?: boolean;
+    emptyLabel?: string;
+    className?: string;
+}
+export declare function StatusTimeline({ title, steps, truncatedCount, footer, hideFooterWhenNegative, emptyLabel, className, }: StatusTimelineProps): import("react").JSX.Element;
+/**
+ * Turn recorded history entries into steps.
+ *
+ * Only entries that actually changed `status` become steps — an entry
+ * recording a tracking number or a payment-review outcome is real history but
+ * is not a phase, and putting every entry on the rail would bury the five
+ * transitions anyone reads.
+ */
+export declare function stepsFromEntries(entries: TimelineEntry[] | undefined, labelFor: (status: string) => string, isNegative: (status: string) => boolean): TimelineStep[];

package/dist/features/status-history/components/StatusTimeline.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge, Div, Heading, Row, Stack, Text } from "../../../ui";
+const ACTOR_LABEL = {
+    buyer: "Buyer",
+    seller: "Store",
+    admin: "Admin",
+    system: "System",
+};
+export function StatusTimeline({ title = "Timeline", steps, truncatedCount, footer, hideFooterWhenNegative = true, emptyLabel = "No history yet", className = "", }) {
+    const isTerminalNegative = steps[steps.length - 1]?.negative === true;
+    const showFooter = footer && !(hideFooterWhenNegative && isTerminalNegative);
+    return (_jsxs(Div, { className: className, rounded: "xl", padding: "md", surface: "muted", border: "default", children: [_jsx(Heading, { level: 3, size: "sm", weight: "semibold", color: "muted", className: "mb-3", children: title }), truncatedCount && truncatedCount > 0 ? (
+            // Say what is not being shown. Silent truncation reads as "this is all
+            // of it", which is the same lie as a silently dropped field.
+            _jsxs(Text, { size: "xs", color: "muted", className: "mb-2", children: [truncatedCount, " earlier ", truncatedCount === 1 ? "entry" : "entries", " trimmed"] })) : null, steps.length === 0 ? (_jsx(Badge, { variant: "default", children: emptyLabel })) : (_jsx(Stack, { gap: "none", children: steps.map((step, i) => {
+                    const isLast = i === steps.length - 1;
+                    return (_jsxs(Stack, { gap: "none", children: [step.roundLabel && (_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "mb-1 mt-2", children: step.roundLabel })), _jsxs(Row, { gap: "sm", padding: isLast ? "none" : "b-md", children: [_jsxs(Stack, { gap: "none", align: "center", className: "shrink-0", children: [_jsx(Div, { className: `h-2.5 w-2.5 ${step.negative || step.muted ? "" : "bg-[var(--appkit-color-primary)]"}`, rounded: "full", surface: step.negative ? "danger-surface" : step.muted ? "subtle" : "none" }), !isLast && _jsx(Div, { className: "w-px flex-1 min-h-[24px]", surface: "subtle" })] }), _jsxs(Stack, { gap: "none", className: "min-w-0 flex-1", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Text, { size: "sm", weight: "medium", className: step.negative ? "text-error" : undefined, color: step.muted ? "muted" : undefined, children: step.label }), step.actorRole && step.actorRole !== "system" && (_jsx(Badge, { variant: "default", size: "xs", children: ACTOR_LABEL[step.actorRole] }))] }), _jsx(Text, { size: "xs", color: "muted", children: step.date ? new Date(step.date).toLocaleString() : "—" }), step.reason && (_jsx(Text, { size: "xs", color: "muted", className: "mt-0.5", children: step.reason })), step.note && (_jsxs(Text, { size: "xs", color: "muted", italic: true, className: "mt-0.5", children: ["\u201C", step.note, "\u201D"] }))] })] })] }, `${step.key}-${i}`));
+                }) })), showFooter ? (_jsx(Div, { className: "mt-3 border-t border-[var(--appkit-color-border)]", padding: "t-sm", children: footer })) : null] }));
+}
+/**
+ * Turn recorded history entries into steps.
+ *
+ * Only entries that actually changed `status` become steps — an entry
+ * recording a tracking number or a payment-review outcome is real history but
+ * is not a phase, and putting every entry on the rail would bury the five
+ * transitions anyone reads.
+ */
+export function stepsFromEntries(entries, labelFor, isNegative) {
+    if (!entries?.length)
+        return [];
+    return entries
+        .filter((e) => "status" in e.changes)
+        .map((e) => {
+        const to = String(e.changes.status?.to ?? "");
+        return {
+            key: to,
+            label: labelFor(to),
+            date: e.at,
+            negative: isNegative(to),
+            actorRole: e.actorRole,
+            reason: e.reason,
+            note: e.note,
+        };
+    });
+}

package/dist/features/status-history/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Status history — the shared timeline rail for any entity that records how
+ * it reached its current state (orders, offers, and the 8 more adopting the
+ * primitive in W15).
+ *
+ * Deliberately NOT `features/history/` — that name was already taken by the
+ * buyer's browsing-history feature (`useHistory`, guest-history utils), which
+ * is an entirely unrelated concept.
+ */
+export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";
+export type { StatusTimelineProps, TimelineEntry, TimelineStep } from "./components/StatusTimeline";

package/dist/features/status-history/index.js

@@ -0,0 +1,10 @@
+/**
+ * Status history — the shared timeline rail for any entity that records how
+ * it reached its current state (orders, offers, and the 8 more adopting the
+ * primitive in W15).
+ *
+ * Deliberately NOT `features/history/` — that name was already taken by the
+ * buyer's browsing-history feature (`useHistory`, guest-history utils), which
+ * is an entirely unrelated concept.
+ */
+export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";

package/dist/features/store-extensions/components/ReviewDecisionModal.d.ts

@@ -0,0 +1,27 @@
+import type { ZodType } from "zod";
+/**
+ * Generic over the schema's OUTPUT type, so a caller's `onConfirm` receives
+ * `ModerationReviewFormValues` / `ReportReviewFormValues` rather than an
+ * untyped bag. A `Record<string, unknown>` here would put the very seam this
+ * component exists to close straight back into the callback signature.
+ */
+export interface ReviewDecisionModalProps<TValues> {
+    isOpen: boolean;
+    onClose: () => void;
+    /** Modal heading, e.g. "Reject media". */
+    title: string;
+    /** The schema BOTH this modal and its route validate against. */
+    schema: ZodType<TValues>;
+    /** The status this decision sets — parsed as part of the payload. */
+    status: string;
+    /** Which key carries the note: `reason` for moderation, `resolution` for reports. */
+    noteField: string;
+    noteLabel: string;
+    noteHelp?: string;
+    notePlaceholder?: string;
+    confirmLabel: string;
+    confirmVariant?: "primary" | "danger";
+    /** Called only once the payload has parsed cleanly, with the PARSED value. */
+    onConfirm: (values: TValues) => Promise<void>;
+}
+export declare function ReviewDecisionModal<TValues>({ isOpen, onClose, title, schema, status, noteField, noteLabel, noteHelp, notePlaceholder, confirmLabel, confirmVariant, onConfirm, }: ReviewDecisionModalProps<TValues>): import("react").JSX.Element;