@voplus/morpho-csp 11.2.9 → 11.3.0-dev.0

package/es/modules/corporate/company/identity/components/SelectLegalContactDialog/state.d.ts

@@ -1,52 +1,303 @@
 import { IAddress } from "@voplus/morpho-ui/es/data";
 import { IIdentity } from "../../../../../../data/identity";
+import type { StoreApi } from "zustand/vanilla";
+import type { IIdentityShape } from "@voplus/morpho-compliance/es/data/identityShape";
+import type { IdentityShapeCatalogStatus } from "@voplus/morpho-compliance/es/components/IdentityShapeSelect";
+import type { CapturedShapeFieldValues } from "@voplus/morpho-compliance/es/components/CapturedShapeFields";
+/** Host visibility and the completion channel for the legal-contact wizard. */
 export type LegalProps = {
+    /** Whether this wizard owns an active visible dialog. */
     visible: boolean;
+    /** Reports a completed owner selection or an explicit dialog close. */
     updateVisible?: (unitId?: string) => Promise<void> | void;
 };
+/** The three writes the create path performs, in order — also what a failure names. */
+export type CreateStep = "contact" | "details" | "identity";
+/** The identity-step fields a picked shape's policies can block: the selection itself plus its captured fields. */
+export type IdentityStepErrors = Partial<Record<"shape" | keyof CapturedShapeFieldValues, string>>;
+/**
+ * The writes the create sequence performs, as the dialog state needs them. The review step binds
+ * them to the identity and unit stores it has, so the order, the named step in flight and what a
+ * failure says can stay owned by the state instead of by the step that happens to call them.
+ */
+export interface CreateWrites {
+    /** Create the owning contact; rejects when nothing was created. */
+    createOwner: () => Promise<{
+        id: string;
+        name: string;
+    }>;
+    /** Save contact details; optional name is supplied only for a changed nonblank draft rename. Rejects on write failure. */
+    saveDetails: (ownerId: string, name?: string) => Promise<void>;
+    /** Create the identity from the created owner and the picked shape's `source` number. */
+    createIdentity: (ownerId: string, shape: IIdentityShape) => Promise<void>;
+}
+/** A sequence can complete, fail at a named write, lack a shape, already be running, or lose its review's ownership. */
+export type CreateOutcome = {
+    status: "completed";
+    ownerId: string;
+} | {
+    status: "failed";
+    step: CreateStep;
+} | {
+    status: "blocked";
+} | {
+    status: "busy";
+} | {
+    status: "abandoned";
+};
+/** The wizard's dialog state — everything its steps read and write. */
+export interface LegalState {
+    /** step of Add Legal Contact */
+    step: number;
+    /** Search an existing contact or Create a new contact */
+    operate: "Search" | "Create";
+    /** type of unit of the new officer */
+    unitType: string;
+    /** id of identity */
+    identityId: string;
+    /** id of unit of the new officer */
+    unitId: string;
+    /** */
+    fistName: string;
+    /** last name */
+    lastName: string;
+    /** */
+    middleName: string;
+    /** number of identity of the new officer */
+    number: string | number;
+    /** country of identity of the new officer */
+    country: string;
+    /** issuing country captured under the picked shape's policy */
+    issuingCountry: string;
+    /** alias captured under the picked shape's policy */
+    alias: string;
+    /** expiryDate of identity of the new officer, when the picked shape captures it */
+    expiryDate?: string;
+    /** email of unit of the new officer */
+    email: string;
+    /** phone of unit of the new officer */
+    phone: string;
+    /** address of unit of the new officer */
+    address: IAddress;
+    /** list of unit */
+    contactList: IIdentity[];
+    /** order name by Western or Eastern */
+    orderName: string;
+    /** key of tabPane of Page4 */
+    tabKey: "Contact" | "Identify";
+    /** loading of load identity list */
+    loading: boolean;
+    /** loading of save identity item, and of the create sequence while it runs */
+    saving: boolean;
+    /** the shape picked for the new identity — its `source` is the number the identity is created with */
+    shape?: IIdentityShape;
+    /** spec:3717 — the picker's catalog status; the identity step is blocked until it is "ready". */
+    catalogStatus: IdentityShapeCatalogStatus;
+    /** spec:3713 — the identity-step messages a blocked step shows for the picked shape's policies. */
+    shapeErrors: IdentityStepErrors;
+    /** spec:3851 — the pre-create disclosure the user accepts before the contact is written. */
+    disclosureOpen: boolean;
+    /** spec:3851 — the owner the create sequence already created; a retry reuses it. */
+    createdOwner: {
+        id: string;
+        name: string;
+    } | null;
+    /** spec:3851 — whether the entered contact details were saved onto the created owner. */
+    detailsSaved: boolean;
+    /** spec:3851 — the step of the create sequence in flight, named while it runs. */
+    savingStep: CreateStep | null;
+    /** spec:3851 — the step that failed after the owner was created; the wizard stays open. */
+    failedOperation: CreateStep | null;
+    /** spec:3851 — the confirmation shown when the user tries to leave an unfinished contact. */
+    leaveConfirmOpen: boolean;
+}
+/** The transitions the dialog state's store exposes on top of the state itself. */
+export interface LegalTransitions {
+    /** Start a fresh wizard run, dropping everything a previous one left behind. */
+    reset: () => void;
+    /** Revoke pending submission ownership while keeping directory writes already completed. */
+    invalidateSubmission: () => void;
+    /** Open the pre-create disclosure. */
+    openDisclosure: () => void;
+    /** Dismiss the pre-create disclosure without writing anything. */
+    closeDisclosure: () => void;
+    /** Ask to leave an unfinished contact: the user has to confirm it first. */
+    requestLeave: () => void;
+    /** Keep editing, dropping the leave confirmation with the state left intact. */
+    cancelLeave: () => void;
+    /** Gate the identity step on the picked shape's carried-field policies. */
+    advanceFromIdentityStep: () => string[];
+    /** spec:3851 — Run the ordered writes and deliver completion only while this submission still owns the review. */
+    submitCreate: (writes: CreateWrites, onComplete?: (ownerId: string) => void) => Promise<CreateOutcome>;
+}
+/** The dialog state plus its transitions: what the Zustand store below holds. */
+export type LegalStoreState = LegalState & LegalTransitions;
+/** The contact's display name in the picked Western or Eastern order. */
+export declare const fullNameOf: (state: LegalState) => string;
+/** The captured values projected onto the keys the shape policies are keyed by. */
+export declare const capturedValuesOf: (state: LegalState) => CapturedShapeFieldValues;
+/** Whether a captured definition applies to the wizard's current owner kind. */
+export declare const isShapeApplicableTo: (shape: IIdentityShape, unitType: string) => boolean;
+/**
+ * spec:3851 — what the identity step still needs: a picked shape (its `source` is the number the
+ * identity is created with), and a value for every captured field that shape's policies mark
+ * mandatory. A field the shape omits or leaves optional is never required.
+ */
+export declare const identityStepErrorsOf: (state: LegalState) => IdentityStepErrors;
+/** spec:3851 — what leaving now keeps in the contact directory, so the confirmation can say it exactly. */
+export declare const leaveDescriptionOf: (state: LegalState) => string;
+/**
+ * The dialog state's store. A pure UI store, so it is a Zustand store and not a MobX one: every
+ * wizard step goes through it — the facade below for the property-shaped reads and writes the
+ * steps have always used, and `useLegalContext` for a re-render on each write.
+ */
+export declare const createLegalStore: () => StoreApi<LegalStoreState>;
+/** The store the wizard's `State` facade drives, and the handle the dialog renders inside. */
+export type LegalStore = ReturnType<typeof createLegalStore>;
+/**
+ * The wizard's dialog state. The state itself lives in a Zustand store (`createLegalStore`); this
+ * facade keeps the property-shaped reads and writes the steps have always used — `legal.email =
+ * value`, `legal.step += 1` — writing straight through to the store, and owns the two things that
+ * belong to the dialog's host rather than to the state: its props, and the callback a finished
+ * contact is reported to.
+ */
 export declare class State {
+    /** The store every read and write of this dialog state goes through. */
+    readonly store: LegalStore;
+    /** The dialog's host props: whether it is open, and the channel it reports back through. */
     props: LegalProps;
+    /** @param store - the store to drive. The default is a whole fresh wizard, so `new State()` is one. */
+    constructor(store?: LegalStore);
+    /** The current state, read for every property below. */
+    private get snapshot();
     /** step of Add Legal Contact */
-    accessor step: number;
+    get step(): LegalState["step"];
+    set step(value: number);
     /** Search an existing contact or Create a new contact */
-    accessor operate: "Search" | "Create";
+    get operate(): LegalState["operate"];
+    set operate(value: "Search" | "Create");
     /** type of unit of the new officer */
-    accessor unitType: string;
+    get unitType(): LegalState["unitType"];
+    set unitType(value: string);
     /** id of identity */
-    accessor identityId: string;
+    get identityId(): LegalState["identityId"];
+    set identityId(value: string);
     /** id of unit of the new officer */
-    accessor unitId: string;
+    get unitId(): LegalState["unitId"];
+    set unitId(value: string);
     /** */
-    accessor fistName: string;
+    get fistName(): LegalState["fistName"];
+    set fistName(value: string);
     /** last name */
-    accessor lastName: string;
+    get lastName(): LegalState["lastName"];
+    set lastName(value: string);
     /** */
-    accessor middleName: string;
+    get middleName(): LegalState["middleName"];
+    set middleName(value: string);
     /** number of identity of the new officer */
-    accessor number: string | number;
+    get number(): LegalState["number"];
+    set number(value: string | number);
     /** country of identity of the new officer */
-    accessor country: string;
-    /** type of identity of the new officer */
-    accessor type: string;
-    /** expiryDate of identity(Passport required) */
-    accessor expiryDate: string;
+    get country(): LegalState["country"];
+    set country(value: string);
+    /** issuing country captured under the picked shape's policy */
+    get issuingCountry(): LegalState["issuingCountry"];
+    set issuingCountry(value: string);
+    /** alias captured under the picked shape's policy */
+    get alias(): LegalState["alias"];
+    set alias(value: string);
+    /** expiryDate of identity of the new officer, when the picked shape captures it */
+    get expiryDate(): LegalState["expiryDate"];
+    set expiryDate(value: string | undefined);
     /** email of unit of the new officer */
-    accessor email: string;
+    get email(): LegalState["email"];
+    set email(value: string);
     /** phone of unit of the new officer */
-    accessor phone: string;
+    get phone(): LegalState["phone"];
+    set phone(value: string);
     /** address of unit of the new officer */
-    accessor address: IAddress;
+    get address(): LegalState["address"];
+    set address(value: IAddress);
     /** list of unit */
-    accessor contactList: IIdentity[];
+    get contactList(): LegalState["contactList"];
+    set contactList(value: IIdentity[]);
     /** order name by Western or Eastern */
-    accessor orderName: string;
+    get orderName(): LegalState["orderName"];
+    set orderName(value: string);
     /** key of tabPane of Page4 */
-    accessor tabKey: "Contact" | "Identify";
+    get tabKey(): LegalState["tabKey"];
+    set tabKey(value: "Contact" | "Identify");
     /** loading of load identity list */
-    accessor loading: boolean;
-    /** loading of save identity item */
-    accessor saving: boolean;
+    get loading(): LegalState["loading"];
+    set loading(value: boolean);
+    /** loading of save identity item, and of the create sequence while it runs */
+    get saving(): LegalState["saving"];
+    set saving(value: boolean);
+    /** the shape picked for the new identity — its `source` is the number the identity is created with */
+    get shape(): LegalState["shape"];
+    set shape(value: IIdentityShape | undefined);
+    /** spec:3717 — the picker's catalog status; the identity step is blocked until it is "ready". */
+    get catalogStatus(): LegalState["catalogStatus"];
+    set catalogStatus(value: IdentityShapeCatalogStatus);
+    /** spec:3713 — the identity-step messages a blocked step shows for the picked shape's policies. */
+    get shapeErrors(): LegalState["shapeErrors"];
+    set shapeErrors(value: IdentityStepErrors);
+    /** spec:3851 — the pre-create disclosure the user accepts before the contact is written. */
+    get disclosureOpen(): LegalState["disclosureOpen"];
+    set disclosureOpen(value: boolean);
+    /** spec:3851 — the owner the create sequence already created; a retry reuses it. */
+    get createdOwner(): LegalState["createdOwner"];
+    set createdOwner(value: {
+        id: string;
+        name: string;
+    } | null);
+    /** spec:3851 — whether the entered contact details were saved onto the created owner. */
+    get detailsSaved(): LegalState["detailsSaved"];
+    set detailsSaved(value: boolean);
+    /** spec:3851 — the step of the create sequence in flight, named while it runs. */
+    get savingStep(): LegalState["savingStep"];
+    set savingStep(value: CreateStep | null);
+    /** spec:3851 — the step that failed after the owner was created; the wizard stays open. */
+    get failedOperation(): LegalState["failedOperation"];
+    set failedOperation(value: CreateStep | null);
+    /** spec:3851 — the confirmation shown when the user tries to leave an unfinished contact. */
+    get leaveConfirmOpen(): LegalState["leaveConfirmOpen"];
+    set leaveConfirmOpen(value: boolean);
+    /** The contact's display name in the picked Western or Eastern order. */
     get fullName(): string;
+    /** The captured values projected onto the keys the shape policies are keyed by. */
+    get capturedValues(): CapturedShapeFieldValues;
+    /** What leaving now keeps in the contact directory, so the confirmation can say it exactly. */
+    get leaveDescription(): string;
+    /** Start a fresh wizard run. */
+    reset: () => void;
+    /** spec:3851 — Revoke an abandoned review's pending result without discarding saved directory data. */
+    invalidateSubmission: () => void;
+    /** Open the pre-create disclosure. */
+    openDisclosure: () => void;
+    /** Dismiss the pre-create disclosure without writing anything. */
+    closeDisclosure: () => void;
+    /** spec:3851 — ask to leave: with nothing created the dialog just closes, with a contact
+     *  already created the user confirms first, because that contact stays in the directory. */
+    requestLeave: () => void;
+    /** spec:3851 — keep editing: drop the leave confirmation so the wizard stays open for a retry. */
+    cancelLeave: () => void;
+    /** spec:3851 — leave the unfinished contact behind: it stays in the directory with whatever was
+     *  saved for it, and no identity is selected for the calling workflow. */
+    leave: () => void;
+    /** spec:3851 — gate the identity step on the picked shape's captured-field policies. */
+    advanceFromIdentityStep: () => string[];
+    /**
+     * spec:3851 — run the ordered create sequence, then report a finished contact back through the
+     * dialog's own result channel. Only a created identity advances the calling workflow; a contact
+     * left behind by a failure or by leaving is never reported as a selection.
+     */
+    submitCreate: (writes: CreateWrites) => Promise<CreateOutcome>;
 }
 export declare const LegalContext: import("react").Context<State>;
+/**
+ * The dialog state for the calling step. The same hook subscribes the step to every write of that
+ * state, so a step re-renders when the wizard advances, when the shape catalog answers, or when a
+ * create sequence reports the step it is on — no observable wrapper required.
+ */
 export declare const useLegalContext: () => State;