@multiplatform.one/frappe-ui 7.28.0 → 7.29.0

package/types/useFrappeForm.d.ts

@@ -0,0 +1,142 @@
+import { type DocTypeMeta, type FormSection } from "@multiplatform.one/frappe";
+import type { DocRights, DocShareGrant } from "./formEngine/docPermissions";
+import { type FrappeConnection } from "./formEngine/formActions";
+import { type FormTab } from "./formEngine/formLayout";
+/** Where a form's DocType meta comes from when the host already loaded it. */
+export interface FrappeFormMetaSource {
+    meta?: DocTypeMeta;
+    isLoading: boolean;
+    error?: Error | null;
+}
+export interface UseFrappeFormOptions<TDoc extends {
+    name: string;
+    doctype: string;
+}> {
+    doctype: string;
+    /** The record; omitted, the form creates one. */
+    name?: string;
+    baseURL?: string;
+    auth?: FrappeConnection["auth"];
+    syncOptions?: Record<string, unknown>;
+    /** Columns the live read asks for; every field when omitted. */
+    fields?: readonly (keyof TDoc & string)[];
+    /** Replaces the meta layout; laid out by the same engine. */
+    sections?: FormSection[];
+    hideFields?: readonly string[];
+    /** Section or Tab Breaks to drop, by fieldname or label. */
+    hideSections?: readonly string[];
+    /** Roles to resolve rights and permlevels against instead of the session's. */
+    roles?: string[];
+    /** Rights the host already resolved (a desk page's docinfo); they win over the session's. */
+    rights?: DocRights;
+    /** DocShare rows the host already holds; otherwise read live when `readShares`. */
+    shares?: readonly DocShareGrant[];
+    /** Read the record's DocShare rows live (the sidebar's Shared With, share rights). */
+    readShares?: boolean;
+    /** Locks every field and action. */
+    disabled?: boolean;
+    /** A server-rendered copy of the record, shown until the live read lands. */
+    initialDoc?: Partial<TDoc>;
+    /** The host's own meta load; the form then loads none. */
+    meta?: FrappeFormMetaSource;
+}
+/** Where the record stands: still reading, missing, unreadable, or on screen. */
+export type FrappeFormStatus = "loading" | "ready" | "notFound" | "error";
+/** A laid-out field, for a jump-to-field list. */
+export interface FrappeFormFieldTarget {
+    name: string;
+    label: string;
+    tabKey: string;
+    tabLabel: string;
+}
+/**
+ * A FrappeForm's state and actions, owned by whoever called `useFrappeForm`.
+ * FrappeForm renders the fields from it; a host page builds its own chrome
+ * (toolbar, confirms, banners) on the same object.
+ */
+export interface FrappeFormController<TDoc extends {
+    name: string;
+    doctype: string;
+}> {
+    doctype: string;
+    name?: string;
+    isCreate: boolean;
+    /** The connection the form reads and writes through; undefined when no bench is configured. */
+    connection?: FrappeFormConnectionConfig;
+    meta?: DocTypeMeta;
+    metaLoading: boolean;
+    metaError?: Error | null;
+    doc: Partial<TDoc>;
+    /** The last server copy the edits are measured against. */
+    baseline?: Partial<TDoc>;
+    setValue: (field: keyof TDoc | string, value: unknown) => void;
+    errors: Record<string, string>;
+    setErrors: (errors: Record<string, string>) => void;
+    dirtyFields: string[];
+    isDirty: boolean;
+    isSubmitting: boolean;
+    docstatus: number;
+    isSubmittable: boolean;
+    rights: DocRights;
+    /** The session's roles are still loading, so `rights` withholds what they may grant. */
+    rightsPending: boolean;
+    roles?: string[];
+    /** The session user, once known. */
+    user?: string;
+    /** The record's DocShare rows: the host's, the live read, or undefined when neither. */
+    shareRows?: readonly DocShareGrant[];
+    /** Create on a new record, write on a saved one. */
+    canWrite: boolean;
+    /** Nothing on the record can change: disabled, deleted, a read-only doctype, or no write. */
+    readOnly: boolean;
+    wasDeleted: boolean;
+    /** Fields the user edited that also changed on the server. */
+    conflictFields: string[];
+    /** A save lost to a newer server copy, or fields changed on both sides. */
+    conflict: boolean;
+    status: FrappeFormStatus;
+    docError: Error | null;
+    /** A server-rendered copy stands in while the live read is out. */
+    showsSeed: boolean;
+    /** The laid-out tabs; undefined until meta is known. */
+    tabs?: FormTab[];
+    /** The doctype names records by prompt, so a new one asks for a name. */
+    promptNamed: boolean;
+    fieldTargets: FrappeFormFieldTarget[];
+    activeTab?: string;
+    setActiveTab: (tab: string | undefined) => void;
+    /** Opens the tab a field sits on; false when no tab shows it. */
+    revealField: (name: string) => boolean;
+    /** The live amendment of a cancelled record, if one exists. */
+    amendedAs?: string;
+    /** Required fields that are empty, keyed by field. */
+    validate: () => Record<string, string>;
+    /** Saves; resolves with the record's name, undefined when nothing was written. */
+    save: () => Promise<string | undefined>;
+    /** Draft to submitted, through the record's live collection. No confirm. */
+    submitDocument: () => Promise<boolean>;
+    /** Submitted to cancelled, through the record's live collection. No confirm. */
+    cancelDocument: () => Promise<boolean>;
+    /** Deletes the record. No confirm. */
+    remove: () => Promise<boolean>;
+    /** Drops the edits, conflicts and errors: back to the server copy. */
+    reset: () => void;
+    /** Stashes and returns the amended draft of a cancelled record (desk copy_doc from_amend). */
+    amend: () => Partial<TDoc> | undefined;
+    /** Stashes and returns the copyable values for a duplicate (desk copy_doc). */
+    duplicate: () => Record<string, unknown> | undefined;
+}
+/** The connection a form reads and writes through. */
+export type FrappeFormConnectionConfig = FrappeConnection;
+/**
+ * The state behind a FrappeForm: meta, the live record, edits measured
+ * against the server copy, rights, the desk layout (`buildFormTabs`), and
+ * save, submit, cancel, amend and delete. `<FrappeForm form={controller} />`
+ * renders the fields from it, so a page that wants its own chrome keeps one
+ * engine with FrappeForm.
+ */
+export declare function useFrappeForm<TDoc extends {
+    name: string;
+    doctype: string;
+}>(options: UseFrappeFormOptions<TDoc>): FrappeFormController<TDoc>;
+//# sourceMappingURL=useFrappeForm.d.ts.map

package/types/useFrappeForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFrappeForm.d.ts","sourceRoot":"","sources":["../src/useFrappeForm.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAQnC,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5E,OAAO,EAAkC,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjG,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAKjC,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,gEAAgE;IAChE,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1C,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,mFAAmF;IACnF,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,sFAAsF;IACtF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC7B;AAED,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;AAE1E,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IACpD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,wFAAwF;IACxF,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACrC,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,yEAAyE;IACzE,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,qBAAqB,EAAE,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAChD,iEAAiE;IACjE,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,kFAAkF;IAClF,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,4EAA4E;IAC5E,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,gFAAgF;IAChF,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,sCAAsC;IACtC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,sEAAsE;IACtE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,8FAA8F;IAC9F,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IACvC,+EAA+E;IAC/E,SAAS,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACtD;AAED,sDAAsD;AACtD,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;AAiC1D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC1E,OAAO,EAAE,oBAAoB,CAAC,IAAI,CAAC,GAClC,oBAAoB,CAAC,IAAI,CAAC,CAmkB5B"}