@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/features/account/hooks/useCollapsedSections.js

@@ -1,63 +1,236 @@
 "use client";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError } from "../../../errors/normalize";
 import { useCurrentProfile, useUpdateCurrentProfile } from "./useProfile";
 const PERSIST_DEBOUNCE_MS = 600;
-/** Persisted, per-user, accordion-scoped collapse state for a page's
- * dashboard sections. Debounces writes to PATCH /api/user/profile so rapid
- * toggling doesn't fire a request per click. */
-export function useCollapsedSections({ sectionIds, }) {
+const LOCAL_KEY = "letitrip:section-state";
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Persisted, per-user, per-surface open/closed state for collapsible sections.
+ *
+ * `useSectionState` is the implementation; `useCollapsedSections` below is a
+ * thin adapter preserving the older hook's exact semantics for its existing
+ * call sites.
+ *
+ * 🛑 THE STORED VALUE IS WHAT IS **OPEN**, NOT WHAT IS COLLAPSED.
+ *
+ * The predecessor stored `uiPreferences.collapsedSections`: one flat, global,
+ * un-namespaced array of collapsed ids, shared by every page and kept apart
+ * only by a naming convention. Two consequences, both of which the polarity
+ * flip removes rather than patches:
+ *
+ *   - a never-seen surface had to DEFAULT to collapsed, because "absent" and
+ *     "deliberately collapsed" were the same value. Storing what is open makes
+ *     a never-seen scope resolve to `defaultOpen` by absence, so "section 1
+ *     open, the rest collapsed" needs no sentinel;
+ *   - one page's ids could collide with another's.
+ *
+ * The scope key is `"{portal}:{surface}"` and is supplied by the caller. It is
+ * deliberately NOT derived from the section ids — a hash would change the
+ * moment a section is added, silently resetting every user's layout.
+ *
+ * ── localStorage mirror ─────────────────────────────────────────────────────
+ * The profile arrives over the network, so a server-only read paints every
+ * section in its default state and then snaps to the user's real layout a
+ * moment later. Writes go to localStorage synchronously (instant, and it
+ * survives for signed-out users) and to the user document debounced (durable,
+ * and it follows the user to another device). localStorage seeds first paint;
+ * the profile is authoritative once it lands.
+ *
+ * ── Migration ───────────────────────────────────────────────────────────────
+ * One-way and lossless: the first time a scope is read with no `sectionState`
+ * entry, its open set is derived from the legacy `collapsedSections`
+ * (`sectionIds − collapsed`) and persisted under the new key. `collapsedSections`
+ * keeps being written for one release so a rollback loses nothing.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// localStorage mirror
+// ─────────────────────────────────────────────────────────────────────────────
+function readLocalScopes() {
+    if (typeof window === "undefined")
+        return {};
+    try {
+        const raw = window.localStorage.getItem(LOCAL_KEY);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        // Validate rather than trust: this value survives across releases and a
+        // shape written by an older version must degrade to "no preference", not
+        // to a render crash. Every entry is checked, so the cast above is a claim
+        // this loop then makes true.
+        const out = {};
+        for (const [scope, ids] of Object.entries(parsed)) {
+            if (Array.isArray(ids))
+                out[scope] = ids.filter((id) => typeof id === "string");
+        }
+        return out;
+        // localStorage throws on access in private mode, and JSON.parse throws on a
+        // value some other version wrote. Neither is reportable — the user document
+        // is the durable copy and this is only a first-paint cache — but the throw
+        // is still normalized rather than swallowed raw.
+    }
+    catch (err) {
+        void normalizeError(err);
+        return {};
+    }
+}
+function writeLocalScope(scope, openIds) {
+    if (typeof window === "undefined")
+        return;
+    try {
+        const all = readLocalScopes();
+        all[scope] = openIds;
+        window.localStorage.setItem(LOCAL_KEY, JSON.stringify(all));
+        // setItem throws on quota exhaustion and in private mode. Same reasoning as
+        // readLocalScopes — the debounced profile PATCH is the durable write, so
+        // losing the mirror costs one frame of default layout and nothing else.
+    }
+    catch (err) {
+        void normalizeError(err);
+    }
+}
+export function useSectionState({ scope, sectionIds, defaultOpen, mode = "multi", }) {
     const { data: profile } = useCurrentProfile();
     const updateProfile = useUpdateCurrentProfile();
-    // Full server-side list, including other pages' entries this hook must
-    // never clobber when it persists its own page's next state.
-    const savedFullListRef = useRef([]);
-    const [localCollapsed, setLocalCollapsed] = useState(null);
-    const debounceRef = useRef(null);
     const sectionIdsRef = useRef(sectionIds);
     sectionIdsRef.current = sectionIds;
+    const fallbackOpen = useMemo(() => defaultOpen ?? (sectionIds.length > 0 ? [sectionIds[0]] : []), 
+    // Only the first id matters for the default, so this does not need to
+    // re-run every time the array identity changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [defaultOpen, sectionIds[0], sectionIds.length]);
+    const fallbackOpenRef = useRef(fallbackOpen);
+    fallbackOpenRef.current = fallbackOpen;
+    // Server copy of EVERY scope, so persisting this surface never clobbers
+    // another's entry.
+    const savedScopesRef = useRef({});
+    const legacyCollapsedRef = useRef(undefined);
+    const debounceRef = useRef(null);
+    /** `scope: ""` opts out of every durable store — see the option's docstring. */
+    const persistent = scope !== "";
+    // Seeded synchronously from localStorage so first paint is already correct.
+    const [localOpen, setLocalOpen] = useState(() => {
+        if (!persistent)
+            return null;
+        const cached = readLocalScopes()[scope];
+        return cached ? new Set(cached) : null;
+    });
     useEffect(() => {
-        if (!profile)
+        if (!persistent || !profile)
             return;
-        const serverList = profile.uiPreferences?.collapsedSections;
-        savedFullListRef.current = serverList ?? [];
-        setLocalCollapsed((prev) => {
-            if (prev !== null)
-                return prev; // local interaction already in progress — don't clobber it
-            const known = new Set(serverList ?? []);
-            const initial = new Set();
-            for (const id of sectionIdsRef.current) {
-                // Never-set user (serverList undefined) → default every section collapsed.
-                if (serverList === undefined || known.has(id))
-                    initial.add(id);
-            }
-            return initial;
-        });
-    }, [profile]);
+        const prefs = profile.uiPreferences;
+        savedScopesRef.current = prefs?.sectionState ?? {};
+        legacyCollapsedRef.current = prefs?.collapsedSections;
+        const stored = savedScopesRef.current[scope];
+        if (stored) {
+            setLocalOpen(new Set(stored));
+            return;
+        }
+        // No entry for this scope yet — derive one from the legacy flat list if the
+        // user has one, otherwise fall back to the default. Persisting is left to
+        // the first real toggle: writing on mere page view would fire a profile
+        // PATCH for every visitor on every dashboard.
+        const legacy = legacyCollapsedRef.current;
+        if (legacy !== undefined) {
+            const collapsed = new Set(legacy);
+            setLocalOpen(new Set(sectionIdsRef.current.filter((id) => !collapsed.has(id))));
+        }
+        else {
+            setLocalOpen(new Set(fallbackOpenRef.current));
+        }
+    }, [profile, scope, persistent]);
     useEffect(() => () => {
         if (debounceRef.current)
             clearTimeout(debounceRef.current);
     }, []);
-    const persist = useCallback((nextForThisPage) => {
+    const persist = useCallback((next) => {
+        if (!persistent)
+            return;
+        const openIds = sectionIdsRef.current.filter((id) => next.has(id));
+        writeLocalScope(scope, openIds);
+        savedScopesRef.current = { ...savedScopesRef.current, [scope]: openIds };
         if (debounceRef.current)
             clearTimeout(debounceRef.current);
         debounceRef.current = setTimeout(() => {
+            // Keep writing the legacy list for one release: derived from this
+            // surface's ids only, merged over whatever other pages recorded, so a
+            // rollback finds the same state it would have written itself.
             const ids = sectionIdsRef.current;
-            const others = savedFullListRef.current.filter((id) => !ids.includes(id));
-            const merged = [...others, ...nextForThisPage];
-            savedFullListRef.current = merged;
-            updateProfile.mutate({ uiPreferences: { collapsedSections: merged } });
+            const others = (legacyCollapsedRef.current ?? []).filter((id) => !ids.includes(id));
+            const collapsedHere = ids.filter((id) => !next.has(id));
+            const mergedLegacy = [...others, ...collapsedHere];
+            legacyCollapsedRef.current = mergedLegacy;
+            updateProfile.mutate({
+                uiPreferences: {
+                    sectionState: { [scope]: openIds },
+                    collapsedSections: mergedLegacy,
+                },
+            });
         }, PERSIST_DEBOUNCE_MS);
-    }, [updateProfile]);
-    const isCollapsed = useCallback((id) => localCollapsed?.has(id) ?? true, [localCollapsed]);
+    }, [scope, persistent, updateProfile]);
+    const effectiveOpen = localOpen ?? new Set(fallbackOpen);
+    const isOpen = useCallback((id) => (localOpen ?? new Set(fallbackOpenRef.current)).has(id), [localOpen]);
     const toggle = useCallback((id) => {
-        setLocalCollapsed((prev) => {
-            const wasCollapsed = prev?.has(id) ?? true;
-            const next = wasCollapsed
-                ? new Set(sectionIdsRef.current.filter((s) => s !== id)) // opening id collapses every sibling
-                : new Set(sectionIdsRef.current); // closing the open one — back to all-collapsed
+        setLocalOpen((prev) => {
+            const current = prev ?? new Set(fallbackOpenRef.current);
+            const next = new Set(current);
+            if (next.has(id))
+                next.delete(id);
+            else if (mode === "single") {
+                next.clear();
+                next.add(id);
+            }
+            else
+                next.add(id);
+            persist(next);
+            return next;
+        });
+    }, [mode, persist]);
+    const open = useCallback((id) => {
+        setLocalOpen((prev) => {
+            const current = prev ?? new Set(fallbackOpenRef.current);
+            if (current.has(id))
+                return current;
+            // Deliberately additive even under `mode: "single"`: this exists for
+            // error recovery, and collapsing the section the user was just editing
+            // in order to reveal the one that failed loses their place.
+            const next = new Set(current);
+            next.add(id);
+            persist(next);
+            return next;
+        });
+    }, [persist]);
+    const setOpenIds = useCallback((ids) => {
+        setLocalOpen(() => {
+            const next = new Set(ids);
             persist(next);
             return next;
         });
     }, [persist]);
+    const openIds = useMemo(() => sectionIds.filter((id) => effectiveOpen.has(id)), 
+    // effectiveOpen is derived from localOpen; depending on the Set identity
+    // directly would recompute on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sectionIds, localOpen, fallbackOpen]);
+    return { isOpen, toggle, open, setOpenIds, openIds };
+}
+/**
+ * @deprecated Prefer `useSectionState`, which is namespaced per surface,
+ * supports several sections open at once, and defaults to section 1 open.
+ *
+ * Kept so the existing dashboard call sites need no edit. Semantics are
+ * byte-identical to the original: default all-collapsed (`defaultOpen: []`)
+ * and accordion (`mode: "single"`).
+ */
+export function useCollapsedSections({ sectionIds, scope = "legacy:collapsed-sections", }) {
+    const { isOpen, toggle } = useSectionState({
+        scope,
+        sectionIds,
+        defaultOpen: [],
+        mode: "single",
+    });
+    const isCollapsed = useCallback((id) => !isOpen(id), [isOpen]);
     return { isCollapsed, toggle };
 }

package/dist/features/account/hooks/useProfile.d.ts

@@ -12,7 +12,11 @@ export interface UserProfile {
     googleLinked?: boolean;
     googleLinkedEmail?: string | null;
     uiPreferences?: {
+        /** @deprecated Superseded by `sectionState`. Still written during the
+         * migration window so an existing user's layout carries over. */
         collapsedSections?: string[];
+        /** scope -> ids that are OPEN. See useSectionState. */
+        sectionState?: Record<string, string[]>;
         dataViewMode?: "table" | "grid" | "list";
         handMode?: "left" | "right";
     };
@@ -32,7 +36,11 @@ export interface UpdateCurrentProfileInput {
     bio?: string;
     profileIsPublic?: boolean;
     uiPreferences?: {
+        /** @deprecated Superseded by `sectionState`. Still written during the
+         * migration window so an existing user's layout carries over. */
         collapsedSections?: string[];
+        /** scope -> ids that are OPEN. See useSectionState. */
+        sectionState?: Record<string, string[]>;
         dataViewMode?: "table" | "grid" | "list";
         handMode?: "left" | "right";
     };

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

@@ -3,14 +3,11 @@ export * from "./schemas";
 export * from "./columns";
 export * from "./hooks/useAccount";
 export * from "./hooks/useAddresses";
-export * from "./hooks/useAddressForm";
 export * from "./hooks/useAddressSelector";
 export * from "./hooks/useNotifications";
 export * from "./hooks/useProfileStats";
 export * from "./hooks/useCollapsedSections";
 export { useCurrentProfile as useProfile, useUpdateCurrentProfile as useUpdateProfile, } from "./hooks/useProfile";
 export * from "./hooks/usePublicProfile";
-export * from "./constants/addresses";
-export * from "./address-validation";
 export * from "./components";
 export { manifest } from "./manifest";

package/dist/features/account/index.js

@@ -3,14 +3,11 @@ export * from "./schemas";
 export * from "./columns";
 export * from "./hooks/useAccount";
 export * from "./hooks/useAddresses";
-export * from "./hooks/useAddressForm";
 export * from "./hooks/useAddressSelector";
 export * from "./hooks/useNotifications";
 export * from "./hooks/useProfileStats";
 export * from "./hooks/useCollapsedSections";
 export { useCurrentProfile as useProfile, useUpdateCurrentProfile as useUpdateProfile, } from "./hooks/useProfile";
 export * from "./hooks/usePublicProfile";
-export * from "./constants/addresses";
-export * from "./address-validation";
 export * from "./components";
 export { manifest } from "./manifest";

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

@@ -1,39 +1,5 @@
 export * from "./firestore";
 import { z } from "zod";
-export declare const userAddressSchema: z.ZodObject<{
-    id: z.ZodString;
-    label: z.ZodOptional<z.ZodString>;
-    line1: z.ZodString;
-    line2: z.ZodOptional<z.ZodString>;
-    city: z.ZodString;
-    state: z.ZodString;
-    postalCode: z.ZodString;
-    country: z.ZodString;
-    isDefault: z.ZodOptional<z.ZodBoolean>;
-    phone: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    country: string;
-    id: string;
-    city: string;
-    state: string;
-    postalCode: string;
-    line1: string;
-    label?: string | undefined;
-    isDefault?: boolean | undefined;
-    phone?: string | undefined;
-    line2?: string | undefined;
-}, {
-    country: string;
-    id: string;
-    city: string;
-    state: string;
-    postalCode: string;
-    line1: string;
-    label?: string | undefined;
-    isDefault?: boolean | undefined;
-    phone?: string | undefined;
-    line2?: string | undefined;
-}>;
 export declare const notificationPreferencesSchema: z.ZodObject<{
     orderUpdates: z.ZodOptional<z.ZodBoolean>;
     promotions: z.ZodOptional<z.ZodBoolean>;
@@ -71,40 +37,6 @@ export declare const userProfileSchema: z.ZodObject<{
     phone: z.ZodOptional<z.ZodString>;
     photoURL: z.ZodOptional<z.ZodString>;
     bio: z.ZodOptional<z.ZodString>;
-    addresses: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-        line1: z.ZodString;
-        line2: z.ZodOptional<z.ZodString>;
-        city: z.ZodString;
-        state: z.ZodString;
-        postalCode: z.ZodString;
-        country: z.ZodString;
-        isDefault: z.ZodOptional<z.ZodBoolean>;
-        phone: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        country: string;
-        id: string;
-        city: string;
-        state: string;
-        postalCode: string;
-        line1: string;
-        label?: string | undefined;
-        isDefault?: boolean | undefined;
-        phone?: string | undefined;
-        line2?: string | undefined;
-    }, {
-        country: string;
-        id: string;
-        city: string;
-        state: string;
-        postalCode: string;
-        line1: string;
-        label?: string | undefined;
-        isDefault?: boolean | undefined;
-        phone?: string | undefined;
-        line2?: string | undefined;
-    }>, "many">>;
     notificationPreferences: z.ZodOptional<z.ZodObject<{
         orderUpdates: z.ZodOptional<z.ZodBoolean>;
         promotions: z.ZodOptional<z.ZodBoolean>;
@@ -132,18 +64,6 @@ export declare const userProfileSchema: z.ZodObject<{
     displayName?: string | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
-    addresses?: {
-        country: string;
-        id: string;
-        city: string;
-        state: string;
-        postalCode: string;
-        line1: string;
-        label?: string | undefined;
-        isDefault?: boolean | undefined;
-        phone?: string | undefined;
-        line2?: string | undefined;
-    }[] | undefined;
     photoURL?: string | undefined;
     bio?: string | undefined;
     phone?: string | undefined;
@@ -160,18 +80,6 @@ export declare const userProfileSchema: z.ZodObject<{
     displayName?: string | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
-    addresses?: {
-        country: string;
-        id: string;
-        city: string;
-        state: string;
-        postalCode: string;
-        line1: string;
-        label?: string | undefined;
-        isDefault?: boolean | undefined;
-        phone?: string | undefined;
-        line2?: string | undefined;
-    }[] | undefined;
     photoURL?: string | undefined;
     bio?: string | undefined;
     phone?: string | undefined;

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

@@ -1,18 +1,16 @@
 export * from "./firestore";
 import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
 // --- Sub-schemas --------------------------------------------------------------
-export const userAddressSchema = z.object({
-    id: z.string(),
-    label: z.string().optional(),
-    line1: z.string(),
-    line2: z.string().optional(),
-    city: z.string(),
-    state: z.string(),
-    postalCode: z.string(),
-    country: z.string(),
-    isDefault: z.boolean().optional(),
-    phone: z.string().optional(),
-});
+/*
+ * `userAddressSchema` is DELETED (W5 / D19).
+ *
+ * It carried the `line1`/`line2` naming — one of the eleven address shapes,
+ * and the only one that disagreed with `AddressDocument` on field NAMES rather
+ * than just on rules. Zero consumers outside the barrel that re-exported it.
+ * The one shape is `addressFormSchema` in
+ * `features/addresses/schemas/address-form.ts`.
+ */
 export const notificationPreferencesSchema = z.object({
     orderUpdates: z.boolean().optional(),
     promotions: z.boolean().optional(),
@@ -39,7 +37,6 @@ export const userProfileSchema = z.object({
     phone: z.string().optional(),
     photoURL: z.string().optional(),
     bio: z.string().optional(),
-    addresses: z.array(userAddressSchema).optional(),
     notificationPreferences: notificationPreferencesSchema.optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
@@ -51,10 +48,23 @@ export const userProfileSchema = z.object({
  * validation too.
  */
 export const updateProfileSchema = z.object({
-    displayName: z.string().min(1, "Enter your name").optional(),
-    phoneNumber: z.string().optional(),
-    bio: z.string().max(500, "Bio must be 500 characters or fewer").optional(),
-    profileIsPublic: z.boolean().optional(),
+    displayName: annotate(z.string().min(1, "Enter your name").optional(), {
+        section: "profile", sectionLabel: "Your details", sectionRequired: true,
+        quick: true, order: 1, row: "pair", label: "Display name",
+    }),
+    phoneNumber: annotate(z.string().optional(), {
+        section: "profile", quick: true, order: 2, row: "pair",
+        label: "Phone number", inputType: "tel",
+    }),
+    bio: annotate(z.string().max(500, "Bio must be 500 characters or fewer").optional(), {
+        section: "profile", order: 3, row: "full", kind: "textarea",
+        label: "Bio", help: "Up to 500 characters. Buyers see this on your public profile.",
+    }),
+    profileIsPublic: annotate(z.boolean().optional(), {
+        section: "visibility", sectionLabel: "Visibility", order: 1, row: "full",
+        label: "Public profile",
+        help: "When on, your profile is visible to other LetItRip users.",
+    }),
 });
 /**
  * Changing the account email.
@@ -69,11 +79,23 @@ export const updateProfileSchema = z.object({
  * credential, not chosen here.
  */
 export const changeEmailSchema = z.object({
-    newEmail: z
+    newEmail: annotate(z
         .string()
         .trim()
         .toLowerCase()
         .min(1, "Enter the new email address.")
-        .email("That doesn't look like an email address."),
-    emailPassword: z.string().min(1, "Enter your current password to confirm."),
+        .email("That doesn't look like an email address."), {
+        section: "basics", sectionLabel: "Change email", sectionRequired: true,
+        order: 1, row: "full", label: "New email address", inputType: "email",
+    }),
+    /*
+     * 🛑 `inputType: "password"` is not cosmetic. Without it the generated
+     * control is a bare `<FieldInput>` with no `type`, which renders a password
+     * IN PLAINTEXT — the defect found the first time this generator met a
+     * credential field.
+     */
+    emailPassword: annotate(z.string().min(1, "Enter your current password to confirm."), {
+        section: "basics", order: 2, row: "full", label: "Current password",
+        inputType: "password",
+    }),
 });

package/dist/features/addresses/components/AddressLocationFields.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+import type { JsonValue } from "@mohasinac/appkit/client";
+export interface AddressLocationFieldsProps {
+    country: string;
+    state: string;
+    postalCode: string;
+    errors: Record<string, string>;
+    isLooking?: boolean;
+    onChange: (partial: Record<string, JsonValue>) => void;
+    /** Called with (postalCode, country) whenever either settles. */
+    onPostalSettled: (postalCode: string, country: string) => void;
+}
+export declare function AddressLocationFields({ country, state, postalCode, errors, isLooking, onChange, onPostalSettled, }: AddressLocationFieldsProps): React.JSX.Element;

package/dist/features/addresses/components/AddressLocationFields.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PaginatedSelect, Stack, Text } from "../../../ui";
+import { FieldInput } from "../../../ui/forms/FieldInput";
+import { FormGroup } from "../../../ui/components/Form";
+import { countryFor, postalLabelFor, COUNTRIES } from "../../../constants/geo/countries";
+import { subdivisionsFor } from "../../../constants/geo/subdivisions";
+const COUNTRY_OPTIONS = Object.values(COUNTRIES).map((c) => ({
+    value: c.code,
+    label: c.name,
+}));
+export function AddressLocationFields({ country, state, postalCode, errors, isLooking = false, onChange, onPostalSettled, }) {
+    const def = countryFor(country);
+    const states = subdivisionsFor(def?.code);
+    const postalLabel = postalLabelFor(country);
+    return (_jsxs(Stack, { gap: "sm", children: [_jsxs(FormGroup, { columns: 2, children: [_jsx(PaginatedSelectField, { label: "Country", value: def?.code ?? "", error: errors.country, onChange: (next) => {
+                            /*
+                             * Changing country invalidates the state: "Karnataka" is not a
+                             * Canadian province. Cleared rather than carried, because a state
+                             * that no longer belongs to its country is a row nothing can
+                             * group or ship.
+                             */
+                            onChange({ country: next, state: "" });
+                            onPostalSettled(postalCode, next);
+                        } }), states.length > 0 ? (_jsx(PaginatedSelectField, { label: "State / region", value: state, error: errors.state, options: states.map((s) => ({ value: s, label: s })), onChange: (next) => onChange({ state: next }) })) : (_jsx(FieldInput, { name: "state", label: "State / region", required: true, value: state, error: errors.state, onChange: (v) => onChange({ state: v }) }))] }), _jsx(FieldInput, { name: "postalCode", label: postalLabel, required: true, value: postalCode, error: errors.postalCode, hint: isLooking
+                    ? "Looking up your city…"
+                    : "We fill in the city and state when we recognise it.", onChange: (v) => {
+                    onChange({ postalCode: v });
+                    onPostalSettled(v, country);
+                }, onBlur: () => onPostalSettled(postalCode, country) }), !def && country.trim() && (_jsx(Text, { size: "xs", color: "muted", children: "We do not know the postal format for that country, so anything plausible is accepted." }))] }));
+}
+/**
+ * A labelled `PaginatedSelect`.
+ *
+ * The primitive takes no `label` or `error` of its own — the generator wraps
+ * it the same way at `build-sections.tsx:392`. This is that wrapper, named,
+ * so the two country pickers in this file do not each rebuild it.
+ */
+function PaginatedSelectField({ label, value, error, options = COUNTRY_OPTIONS, onChange, }) {
+    return (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", weight: "medium", color: "muted", children: [label, " *"] }), _jsx(PaginatedSelect, { value: value, options: options, onChange: (next) => onChange(next ?? ""), ariaLabel: label, placeholder: `Select ${label.toLowerCase()}…` }), error && (_jsx(Text, { size: "xs", color: "error", role: "alert", children: error }))] }));
+}

package/dist/features/addresses/hooks/usePostalLookup.d.ts

@@ -0,0 +1,17 @@
+export interface PostalLookupResult {
+    city: string;
+    state: string;
+}
+export interface UsePostalLookupOptions {
+    /** Called with the resolved place. Only ever fires on a hit. */
+    onResolved: (result: PostalLookupResult) => void;
+    /** Skip the lookup entirely — e.g. while the form is submitting. */
+    enabled?: boolean;
+}
+export interface UsePostalLookupResult {
+    /** Feed it the current postal code and country on every change or blur. */
+    lookup: (postalCode: string, country: string) => void;
+    /** True while a request is in flight. Purely for a spinner; never gates. */
+    isLooking: boolean;
+}
+export declare function usePostalLookup({ onResolved, enabled, }: UsePostalLookupOptions): UsePostalLookupResult;