@mohasinac/appkit 2.3.1 → 2.4.0

package/dist/features/seller/repository/offer.repository.js

@@ -63,14 +63,14 @@ class OfferRepository extends BaseRepository {
             hasMore: false,
         };
     }
-    async findBySeller(sellerId, model) {
+    async findByStore(storeId, model) {
         if (model) {
             return this.sieveQuery(model, OfferRepository.SIEVE_FIELDS, {
-                baseQuery: this.getCollection().where(OFFER_FIELDS.SELLER_ID, "==", sellerId),
+                baseQuery: this.getCollection().where(OFFER_FIELDS.STORE_ID, "==", storeId),
             });
         }
         const snap = await this.getCollection()
-            .where(OFFER_FIELDS.SELLER_ID, "==", sellerId)
+            .where(OFFER_FIELDS.STORE_ID, "==", storeId)
             .orderBy(OFFER_FIELDS.CREATED_AT, "desc")
             .get();
         const items = snap.docs.map((d) => this.mapDoc(d));
@@ -83,9 +83,9 @@ class OfferRepository extends BaseRepository {
             hasMore: false,
         };
     }
-    async findPendingBySeller(sellerId) {
+    async findPendingByStore(storeId) {
         const snap = await this.getCollection()
-            .where(OFFER_FIELDS.SELLER_ID, "==", sellerId)
+            .where(OFFER_FIELDS.STORE_ID, "==", storeId)
             .where(OFFER_FIELDS.STATUS, "==", "pending")
             .orderBy(OFFER_FIELDS.CREATED_AT, "asc")
             .get();
@@ -203,7 +203,7 @@ OfferRepository.SIEVE_FIELDS = {
     status: { canFilter: true, canSort: false },
     productId: { canFilter: true, canSort: false },
     buyerUid: { canFilter: true, canSort: false },
-    sellerId: { canFilter: true, canSort: false },
+    storeId: { canFilter: true, canSort: false },
     createdAt: { canFilter: false, canSort: true },
 };
 export const offerRepository = new OfferRepository();

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

@@ -22,8 +22,8 @@ export interface OfferDocument {
     buyerUid: string;
     buyerName: string;
     buyerEmail: string;
-    sellerId: string;
-    sellerName: string;
+    storeId: string;
+    storeName: string;
     offerAmount: number;
     listedPrice: number;
     counterAmount?: number;
@@ -39,7 +39,7 @@ export interface OfferDocument {
     updatedAt: Date;
 }
 export declare const OFFER_COLLECTION: "offers";
-export declare const OFFER_INDEXED_FIELDS: readonly ["buyerUid", "sellerId", "productId", "status", "createdAt", "expiresAt"];
+export declare const OFFER_INDEXED_FIELDS: readonly ["buyerUid", "storeId", "productId", "status", "createdAt", "expiresAt"];
 export declare const OFFER_FIELDS: {
     readonly ID: "id";
     readonly PRODUCT_ID: "productId";
@@ -47,8 +47,8 @@ export declare const OFFER_FIELDS: {
     readonly BUYER_UID: "buyerUid";
     readonly BUYER_NAME: "buyerName";
     readonly BUYER_EMAIL: "buyerEmail";
-    readonly SELLER_ID: "sellerId";
-    readonly SELLER_NAME: "sellerName";
+    readonly STORE_ID: "storeId";
+    readonly STORE_NAME: "storeName";
     readonly OFFER_AMOUNT: "offerAmount";
     readonly LISTED_PRICE: "listedPrice";
     readonly COUNTER_AMOUNT: "counterAmount";
@@ -63,11 +63,11 @@ export declare const OFFER_FIELDS: {
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
 };
-export type OfferCreateInput = Pick<OfferDocument, "productId" | "productTitle" | "productSlug" | "productImageUrl" | "buyerUid" | "buyerName" | "buyerEmail" | "sellerId" | "sellerName" | "offerAmount" | "listedPrice" | "currency" | "buyerNote">;
+export type OfferCreateInput = Pick<OfferDocument, "productId" | "productTitle" | "productSlug" | "productImageUrl" | "buyerUid" | "buyerName" | "buyerEmail" | "storeId" | "storeName" | "offerAmount" | "listedPrice" | "currency" | "buyerNote">;
 export type OfferUpdateInput = Partial<Pick<OfferDocument, "status" | "counterAmount" | "lockedPrice" | "sellerNote" | "acceptedAt" | "respondedAt" | "updatedAt">>;
 export declare const offerQueryHelpers: {
     readonly byBuyer: (buyerUid: string) => readonly ["buyerUid", "==", string];
-    readonly bySeller: (sellerId: string) => readonly ["sellerId", "==", string];
+    readonly byStore: (storeId: string) => readonly ["storeId", "==", string];
     readonly byProduct: (productId: string) => readonly ["productId", "==", string];
     readonly byStatus: (status: OfferStatus) => readonly ["status", "==", OfferStatus];
     readonly pending: () => readonly ["status", "==", "pending"];

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

@@ -15,7 +15,7 @@ export const OfferStatusValues = {
 export const OFFER_COLLECTION = "offers";
 export const OFFER_INDEXED_FIELDS = [
     "buyerUid",
-    "sellerId",
+    "storeId",
     "productId",
     "status",
     "createdAt",
@@ -28,8 +28,8 @@ export const OFFER_FIELDS = {
     BUYER_UID: "buyerUid",
     BUYER_NAME: "buyerName",
     BUYER_EMAIL: "buyerEmail",
-    SELLER_ID: "sellerId",
-    SELLER_NAME: "sellerName",
+    STORE_ID: "storeId",
+    STORE_NAME: "storeName",
     OFFER_AMOUNT: "offerAmount",
     LISTED_PRICE: "listedPrice",
     COUNTER_AMOUNT: "counterAmount",
@@ -46,7 +46,7 @@ export const OFFER_FIELDS = {
 };
 export const offerQueryHelpers = {
     byBuyer: (buyerUid) => ["buyerUid", "==", buyerUid],
-    bySeller: (sellerId) => ["sellerId", "==", sellerId],
+    byStore: (storeId) => ["storeId", "==", storeId],
     byProduct: (productId) => ["productId", "==", productId],
     byStatus: (status) => ["status", "==", status],
     pending: () => ["status", "==", "pending"],

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

@@ -9,14 +9,14 @@ export declare const socialLinksSchema: z.ZodObject<{
     facebook: z.ZodOptional<z.ZodString>;
     linkedin: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    twitter?: string | undefined;
     instagram?: string | undefined;
     facebook?: string | undefined;
+    twitter?: string | undefined;
     linkedin?: string | undefined;
 }, {
-    twitter?: string | undefined;
     instagram?: string | undefined;
     facebook?: string | undefined;
+    twitter?: string | undefined;
     linkedin?: string | undefined;
 }>;
 /**
@@ -51,14 +51,14 @@ export declare const sellerStoreSchema: z.ZodObject<{
         facebook: z.ZodOptional<z.ZodString>;
         linkedin: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        twitter?: string | undefined;
         instagram?: string | undefined;
         facebook?: string | undefined;
+        twitter?: string | undefined;
         linkedin?: string | undefined;
     }, {
-        twitter?: string | undefined;
         instagram?: string | undefined;
         facebook?: string | undefined;
+        twitter?: string | undefined;
         linkedin?: string | undefined;
     }>>;
     returnPolicy: z.ZodOptional<z.ZodString>;
@@ -90,8 +90,8 @@ export declare const sellerStoreSchema: z.ZodObject<{
     createdAt: string;
     updatedAt: string;
     storeName: string;
-    storeSlug: string;
     ownerId: string;
+    storeSlug: string;
     isPublic: boolean;
     stats?: {
         itemsSold: number;
@@ -101,18 +101,18 @@ export declare const sellerStoreSchema: z.ZodObject<{
     } | undefined;
     location?: string | undefined;
     socialLinks?: {
-        twitter?: string | undefined;
         instagram?: string | undefined;
         facebook?: string | undefined;
+        twitter?: string | undefined;
         linkedin?: string | undefined;
     } | undefined;
-    bio?: string | undefined;
     returnPolicy?: string | undefined;
-    storeLogoURL?: string | undefined;
+    website?: string | undefined;
+    bio?: string | undefined;
     storeDescription?: string | undefined;
     storeCategory?: string | undefined;
+    storeLogoURL?: string | undefined;
     storeBannerURL?: string | undefined;
-    website?: string | undefined;
     shippingPolicy?: string | undefined;
     isVacationMode?: boolean | undefined;
     vacationMessage?: string | undefined;
@@ -122,8 +122,8 @@ export declare const sellerStoreSchema: z.ZodObject<{
     createdAt: string;
     updatedAt: string;
     storeName: string;
-    storeSlug: string;
     ownerId: string;
+    storeSlug: string;
     isPublic: boolean;
     stats?: {
         itemsSold: number;
@@ -133,18 +133,18 @@ export declare const sellerStoreSchema: z.ZodObject<{
     } | undefined;
     location?: string | undefined;
     socialLinks?: {
-        twitter?: string | undefined;
         instagram?: string | undefined;
         facebook?: string | undefined;
+        twitter?: string | undefined;
         linkedin?: string | undefined;
     } | undefined;
-    bio?: string | undefined;
     returnPolicy?: string | undefined;
-    storeLogoURL?: string | undefined;
+    website?: string | undefined;
+    bio?: string | undefined;
     storeDescription?: string | undefined;
     storeCategory?: string | undefined;
+    storeLogoURL?: string | undefined;
     storeBannerURL?: string | undefined;
-    website?: string | undefined;
     shippingPolicy?: string | undefined;
     isVacationMode?: boolean | undefined;
     vacationMessage?: string | undefined;
@@ -171,7 +171,6 @@ export declare const payoutRecordSchema: z.ZodObject<{
     status: "pending" | "failed" | "processing" | "completed";
     createdAt: string;
     updatedAt: string;
-    sellerId: string;
     requestedAt: string;
     sellerName: string;
     sellerEmail: string;
@@ -182,13 +181,13 @@ export declare const payoutRecordSchema: z.ZodObject<{
     currency: string;
     paymentMethod: "bank_transfer" | "upi";
     orderIds: string[];
+    sellerId: string;
     processedAt?: string | undefined;
 }, {
     id: string;
     status: "pending" | "failed" | "processing" | "completed";
     createdAt: string;
     updatedAt: string;
-    sellerId: string;
     requestedAt: string;
     sellerName: string;
     sellerEmail: string;
@@ -199,6 +198,7 @@ export declare const payoutRecordSchema: z.ZodObject<{
     currency: string;
     paymentMethod: "bank_transfer" | "upi";
     orderIds: string[];
+    sellerId: string;
     processedAt?: string | undefined;
 }>;
 export declare const sellerListParamsSchema: z.ZodObject<{
@@ -212,15 +212,15 @@ export declare const sellerListParamsSchema: z.ZodObject<{
     sort?: string | undefined;
     q?: string | undefined;
     status?: "pending" | "active" | "rejected" | "suspended" | undefined;
-    page?: number | undefined;
     category?: string | undefined;
+    page?: number | undefined;
     perPage?: number | undefined;
 }, {
     sort?: string | undefined;
     q?: string | undefined;
     status?: "pending" | "active" | "rejected" | "suspended" | undefined;
-    page?: number | undefined;
     category?: string | undefined;
+    page?: number | undefined;
     perPage?: number | undefined;
 }>;
 export declare const payoutListParamsSchema: z.ZodObject<{

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

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+export interface FormShellSection {
+    id: string;
+    label: string;
+}
+export interface FormShellProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    breadcrumb?: string;
+    isDirty?: boolean;
+    isLoading?: boolean;
+    /** Left-nav anchor sections (section mode). Omit when using StepForm inside. */
+    sections?: FormShellSection[];
+    onSaveDraft?: () => void | Promise<void>;
+    onPublish?: () => void | Promise<void>;
+    saveLabel?: string;
+    publishLabel?: string;
+    /** Override the entire bottom action bar. */
+    renderBottomBar?: () => ReactNode;
+    children: ReactNode;
+}
+export interface UseFormShellResult {
+    isDirty: boolean;
+    markDirty: () => void;
+    markClean: () => void;
+}
+export declare function useFormShell(): UseFormShellResult;
+export declare function FormShell({ isOpen, onClose, title, breadcrumb, isDirty, isLoading, sections, onSaveDraft, onPublish, saveLabel, publishLabel, renderBottomBar, children, }: FormShellProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/features/shell/FormShell.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { X, AlertTriangle } from "lucide-react";
+import { Button } from "../../ui/components/Button";
+import { classNames } from "../../ui/style.helper";
+export function useFormShell() {
+    const [isDirty, setIsDirty] = useState(false);
+    return {
+        isDirty,
+        markDirty: useCallback(() => setIsDirty(true), []),
+        markClean: useCallback(() => setIsDirty(false), []),
+    };
+}
+const FOCUSABLE = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+export function FormShell({ isOpen, onClose, title, breadcrumb, isDirty = false, isLoading = false, sections, onSaveDraft, onPublish, saveLabel = "Save Draft", publishLabel = "Publish", renderBottomBar, children, }) {
+    const panelRef = useRef(null);
+    const bodyRef = useRef(null);
+    const [showUnsaved, setShowUnsaved] = useState(false);
+    const [savingDraft, setSavingDraft] = useState(false);
+    const [publishing, setPublishing] = useState(false);
+    const attemptClose = useCallback(() => {
+        if (isDirty) {
+            setShowUnsaved(true);
+        }
+        else {
+            onClose();
+        }
+    }, [isDirty, onClose]);
+    // Keyboard: Esc → attempt close; Tab → trap focus inside panel
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const handle = (e) => {
+            if (e.key === "Escape") {
+                e.preventDefault();
+                attemptClose();
+                return;
+            }
+            if (e.key === "Tab" && panelRef.current) {
+                const els = Array.from(panelRef.current.querySelectorAll(FOCUSABLE));
+                if (!els.length) {
+                    e.preventDefault();
+                    return;
+                }
+                if (e.shiftKey) {
+                    if (document.activeElement === els[0]) {
+                        e.preventDefault();
+                        els[els.length - 1].focus();
+                    }
+                }
+                else {
+                    if (document.activeElement === els[els.length - 1]) {
+                        e.preventDefault();
+                        els[0].focus();
+                    }
+                }
+            }
+        };
+        document.addEventListener("keydown", handle);
+        return () => document.removeEventListener("keydown", handle);
+    }, [isOpen, attemptClose]);
+    // Lock body scroll while open
+    useEffect(() => {
+        if (isOpen) {
+            document.body.style.overflow = "hidden";
+        }
+        else {
+            document.body.style.overflow = "";
+        }
+        return () => { document.body.style.overflow = ""; };
+    }, [isOpen]);
+    const scrollToSection = (id) => {
+        const el = bodyRef.current?.querySelector(`#${id}`);
+        if (el)
+            el.scrollIntoView({ behavior: "smooth", block: "start" });
+    };
+    const handleSaveDraft = async () => {
+        if (!onSaveDraft)
+            return;
+        setSavingDraft(true);
+        try {
+            await onSaveDraft();
+        }
+        finally {
+            setSavingDraft(false);
+        }
+    };
+    const handlePublish = async () => {
+        if (!onPublish)
+            return;
+        setPublishing(true);
+        try {
+            await onPublish();
+        }
+        finally {
+            setPublishing(false);
+        }
+    };
+    if (!isOpen)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "fixed inset-0 bg-black/50 backdrop-blur-[2px]", style: { zIndex: "calc(var(--appkit-z-modal) - 1)" }, "aria-hidden": "true", onClick: attemptClose }), _jsxs("div", { ref: panelRef, role: "dialog", "aria-modal": "true", "aria-label": title, className: "fixed inset-0 flex flex-col bg-[var(--appkit-color-surface)] shadow-2xl", style: { zIndex: "var(--appkit-z-modal)" }, children: [_jsxs("div", { className: "flex-shrink-0 sticky top-0 z-10 border-b border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-4 py-3 flex items-center gap-3", children: [_jsx("button", { type: "button", onClick: attemptClose, "aria-label": "Close", className: "rounded-lg p-1.5 text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-border-subtle)] transition-colors flex-shrink-0", children: _jsx(X, { className: "w-5 h-5" }) }), _jsxs("div", { className: "flex-1 min-w-0", children: [breadcrumb && (_jsx("p", { className: "text-xs text-[var(--appkit-color-text-muted)] truncate mb-0.5", children: breadcrumb })), _jsx("p", { className: "text-sm font-semibold text-[var(--appkit-color-text)] truncate", children: title })] }), _jsxs("div", { className: "flex items-center gap-2 flex-shrink-0", children: [onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsx(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: publishLabel }))] })] }), _jsxs("div", { className: "flex flex-1 overflow-hidden", children: [sections && sections.length > 0 && (_jsx("nav", { "aria-label": "Form sections", className: "hidden lg:flex flex-col flex-shrink-0 w-48 border-r border-[var(--appkit-color-border)] py-4 px-3 gap-1 overflow-y-auto", children: sections.map((sec) => (_jsx("button", { type: "button", onClick: () => scrollToSection(sec.id), className: "text-left text-sm px-3 py-2 rounded-lg text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)] hover:bg-[var(--appkit-color-border-subtle)] transition-colors", children: sec.label }, sec.id))) })), sections && sections.length > 0 && (_jsx("div", { className: "lg:hidden fixed top-[var(--form-shell-topbar-h,57px)] left-0 right-0 z-10 flex overflow-x-auto gap-1 px-4 py-2 bg-[var(--appkit-color-surface)] border-b border-[var(--appkit-color-border)]", children: sections.map((sec) => (_jsx("button", { type: "button", onClick: () => scrollToSection(sec.id), className: "flex-shrink-0 text-xs px-3 py-1.5 rounded-full border border-[var(--appkit-color-border)] text-[var(--appkit-color-text-muted)] hover:border-[var(--appkit-color-primary)] hover:text-[var(--appkit-color-primary)] transition-colors whitespace-nowrap", children: sec.label }, sec.id))) })), _jsx("div", { ref: bodyRef, className: classNames("flex-1 overflow-y-auto", sections && sections.length > 0 ? "pt-0 lg:pt-0" : ""), children: _jsx("div", { className: "max-w-3xl mx-auto px-4 py-6 sm:px-6", children: children }) })] }), renderBottomBar ? (renderBottomBar()) : (onSaveDraft || onPublish) ? (_jsxs("div", { className: "flex-shrink-0 sticky bottom-0 z-10 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-4 py-3 flex items-center justify-between", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: attemptClose, disabled: isLoading, children: "Discard" }), _jsxs("div", { className: "flex items-center gap-2", children: [onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsxs(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: [publishLabel, " \u2192"] }))] })] })) : null] }), showUnsaved && (_jsxs(_Fragment, { children: [_jsx("div", { className: "fixed inset-0 bg-black/60", style: { zIndex: "calc(var(--appkit-z-modal) + 5)" }, onClick: () => setShowUnsaved(false) }), _jsxs("div", { className: "fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[90vw] max-w-sm bg-[var(--appkit-color-surface)] rounded-xl shadow-2xl p-6", style: { zIndex: "calc(var(--appkit-z-modal) + 5)" }, children: [_jsxs("div", { className: "flex gap-3 mb-4", children: [_jsx("span", { className: "flex-shrink-0 w-10 h-10 rounded-full bg-[var(--appkit-color-warning-surface)] flex items-center justify-center", children: _jsx(AlertTriangle, { className: "w-5 h-5 text-[var(--appkit-color-warning)]" }) }), _jsxs("div", { children: [_jsx("p", { className: "font-semibold text-[var(--appkit-color-text)]", children: "Unsaved changes" }), _jsx("p", { className: "text-sm text-[var(--appkit-color-text-muted)] mt-1", children: "You have unsaved changes. Leave without saving?" })] })] }), _jsxs("div", { className: "flex gap-2 justify-end", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setShowUnsaved(false), children: "Stay" }), _jsx(Button, { variant: "danger", size: "sm", onClick: () => { setShowUnsaved(false); onClose(); }, children: "Leave" })] })] })] }))] }));
+}

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

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+export type QuickFieldType = "text" | "number" | "select" | "toggle" | "date" | "textarea" | "email" | "url";
+export interface QuickFieldDef {
+    name: string;
+    label: string;
+    type: QuickFieldType;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    required?: boolean;
+    placeholder?: string;
+    helperText?: string;
+    defaultValue?: unknown;
+}
+export interface QuickFormDrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    fields: QuickFieldDef[];
+    defaultValues?: Record<string, unknown>;
+    onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+    submitLabel?: string;
+    cancelLabel?: string;
+    isLoading?: boolean;
+    /** Extra content rendered below auto-generated fields. */
+    renderExtra?: (values: Record<string, unknown>, onChange: (name: string, value: unknown) => void) => ReactNode;
+}
+export declare function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues, onSubmit, submitLabel, cancelLabel, isLoading, renderExtra, }: QuickFormDrawerProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/features/shell/QuickFormDrawer.js

@@ -0,0 +1,117 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { X } from "lucide-react";
+import { Button } from "../../ui/components/Button";
+import { FormField } from "../../ui/components/FormField";
+import { Toggle } from "../../ui/components/Toggle";
+function initValues(fields, defaults = {}) {
+    const out = {};
+    for (const f of fields) {
+        out[f.name] =
+            f.name in defaults
+                ? defaults[f.name]
+                : (f.defaultValue ?? (f.type === "toggle" ? false : ""));
+    }
+    return out;
+}
+const FOCUSABLE = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues, onSubmit, submitLabel = "Save", cancelLabel = "Cancel", isLoading = false, renderExtra, }) {
+    const drawerRef = useRef(null);
+    const [values, setValues] = useState(() => initValues(fields, defaultValues));
+    const [errors, setErrors] = useState({});
+    const [submitting, setSubmitting] = useState(false);
+    // Re-initialise when defaultValues change (e.g. edit mode)
+    useEffect(() => {
+        if (isOpen)
+            setValues(initValues(fields, defaultValues));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isOpen]);
+    const set = (name, value) => {
+        setValues((prev) => ({ ...prev, [name]: value }));
+        if (errors[name])
+            setErrors((prev) => { const n = { ...prev }; delete n[name]; return n; });
+    };
+    const validate = () => {
+        const errs = {};
+        for (const f of fields) {
+            if (f.required) {
+                const v = values[f.name];
+                if (v === undefined || v === null || v === "") {
+                    errs[f.name] = `${f.label} is required`;
+                }
+            }
+        }
+        setErrors(errs);
+        return Object.keys(errs).length === 0;
+    };
+    const handleSubmit = useCallback(async (e) => {
+        e?.preventDefault();
+        if (!validate())
+            return;
+        setSubmitting(true);
+        try {
+            await onSubmit(values);
+            setValues(initValues(fields, defaultValues));
+            setErrors({});
+        }
+        finally {
+            setSubmitting(false);
+        }
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [values, fields, defaultValues, onSubmit]);
+    const handleClose = useCallback(() => {
+        setValues(initValues(fields, defaultValues));
+        setErrors({});
+        onClose();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fields, defaultValues, onClose]);
+    // Keyboard: Esc → close; Tab → trap focus
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const handle = (e) => {
+            if (e.key === "Escape") {
+                e.preventDefault();
+                handleClose();
+                return;
+            }
+            if (e.key === "Tab" && drawerRef.current) {
+                const els = Array.from(drawerRef.current.querySelectorAll(FOCUSABLE));
+                if (!els.length) {
+                    e.preventDefault();
+                    return;
+                }
+                if (e.shiftKey) {
+                    if (document.activeElement === els[0]) {
+                        e.preventDefault();
+                        els[els.length - 1].focus();
+                    }
+                }
+                else {
+                    if (document.activeElement === els[els.length - 1]) {
+                        e.preventDefault();
+                        els[0].focus();
+                    }
+                }
+            }
+        };
+        document.addEventListener("keydown", handle);
+        return () => document.removeEventListener("keydown", handle);
+    }, [isOpen, handleClose]);
+    if (!isOpen)
+        return null;
+    const busy = submitting || isLoading;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "fixed inset-0 bg-black/40 backdrop-blur-[2px]", style: { zIndex: "calc(var(--appkit-z-modal) + 1)" }, "aria-hidden": "true", onClick: handleClose }), _jsxs("div", { ref: drawerRef, role: "dialog", "aria-modal": "true", "aria-label": title, className: "fixed inset-y-0 right-0 flex flex-col bg-[var(--appkit-color-surface)] shadow-2xl w-full lg:w-[40%]", style: { zIndex: "calc(var(--appkit-z-modal) + 2)" }, children: [_jsxs("div", { className: "flex-shrink-0 flex items-center gap-3 px-4 py-4 border-b border-[var(--appkit-color-border)]", children: [_jsx("p", { className: "flex-1 text-base font-semibold text-[var(--appkit-color-text)]", children: title }), _jsx("button", { type: "button", onClick: handleClose, "aria-label": "Close", className: "rounded-lg p-1.5 text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-border-subtle)] transition-colors", children: _jsx(X, { className: "w-5 h-5" }) })] }), _jsxs("form", { className: "flex-1 overflow-y-auto px-4 py-5 space-y-4", onSubmit: handleSubmit, noValidate: true, children: [fields.map((field) => {
+                                const value = values[field.name];
+                                if (field.type === "toggle") {
+                                    return (_jsxs("div", { className: "space-y-1", children: [_jsx(Toggle, { checked: !!value, onChange: (checked) => set(field.name, checked), label: field.label }), field.helperText && (_jsx("p", { className: "text-xs text-[var(--appkit-color-text-muted)]", children: field.helperText }))] }, field.name));
+                                }
+                                return (_jsxs("div", { children: [_jsx(FormField, { name: field.name, label: field.label, type: field.type === "textarea"
+                                                ? "textarea"
+                                                : field.type === "select"
+                                                    ? "select"
+                                                    : "text", value: String(value ?? ""), onChange: (v) => set(field.name, field.type === "number" ? Number(v) : v), options: field.options, placeholder: field.placeholder, disabled: busy, error: errors[field.name] }), field.helperText && !errors[field.name] && (_jsx("p", { className: "mt-1 text-xs text-[var(--appkit-color-text-muted)]", children: field.helperText }))] }, field.name));
+                            }), renderExtra?.(values, set)] }), _jsxs("div", { className: "flex-shrink-0 flex items-center justify-between gap-2 px-4 py-4 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-bg)]", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: handleClose, disabled: busy, children: cancelLabel }), _jsxs(Button, { variant: "primary", size: "sm", onClick: () => void handleSubmit(), disabled: busy, isLoading: busy, children: [submitLabel, " \u2192"] })] })] })] }));
+}

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

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+export interface StepDef<T extends object = Record<string, unknown>> {
+    label: string;
+    render: (props: {
+        values: T;
+        onChange: (partial: Partial<T>) => void;
+        errors: Record<string, string>;
+    }) => ReactNode;
+    /** Returns an error message string if invalid, or null/undefined if valid. */
+    validate?: (values: T) => string | null | undefined;
+}
+export interface StepFormProps<T extends object = Record<string, unknown>> {
+    steps: StepDef<T>[];
+    values: T;
+    onChange: (partial: Partial<T>) => void;
+    onComplete: () => void | Promise<void>;
+    completeLabel?: string;
+    isLoading?: boolean;
+    /** localStorage key to persist current step (optional). */
+    formId?: string;
+    /** Current step index (0-based). Controlled from outside. */
+    currentStep: number;
+    onStepChange: (step: number) => void;
+}
+export interface StepFormActionsProps {
+    currentStep: number;
+    totalSteps: number;
+    onNext: () => void;
+    onPrev?: () => void;
+    completeLabel?: string;
+    isLoading?: boolean;
+    disabled?: boolean;
+}
+/** Standalone step nav bar — use as `renderBottomBar` in FormShell. */
+export declare function StepFormActions({ currentStep, totalSteps, onNext, onPrev, completeLabel, isLoading, disabled, }: StepFormActionsProps): import("react/jsx-runtime").JSX.Element;
+/** Step indicator bar shown above step content. */
+export declare function StepIndicator({ steps, currentStep, onStepClick, }: {
+    steps: {
+        label: string;
+    }[];
+    currentStep: number;
+    onStepClick?: (index: number) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function StepForm<T extends object = Record<string, unknown>>({ steps, values, onChange, onComplete, completeLabel, isLoading, formId, currentStep, onStepChange, }: StepFormProps<T>): import("react/jsx-runtime").JSX.Element;