@bananapus/nana-sdk-react 51.0.0 → 53.0.0

package/dist/hooks/heldWrite/HeldWritesNotice.d.ts

@@ -0,0 +1,11 @@
+import type { HeldWriteItem } from "./useHeldWrites";
+/**
+ * The one app-wide notice of held writes: each with its action's label, its
+ * line, any warning, and the release when its hold offers the exit. Feed it
+ * useHeldWrites, useHeldIntents, or both. Unstyled: `className` is the hook.
+ */
+export declare function HeldWritesNotice({ items, className, }: {
+    items: readonly HeldWriteItem[];
+    className?: string;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=HeldWritesNotice.d.ts.map

package/dist/hooks/heldWrite/HeldWritesNotice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeldWritesNotice.d.ts","sourceRoot":"","sources":["../../../src/hooks/heldWrite/HeldWritesNotice.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,SAAS,GACV,EAAE;IACD,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,sCA4BA"}

package/dist/hooks/heldWrite/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./HeldWritesNotice";
+export * from "./useHeldWrite";
+export * from "./useHeldWrites";
+export * from "./useSavedAttempt";
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/heldWrite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/heldWrite/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/hooks/heldWrite/useHeldWrite.d.ts

@@ -0,0 +1,63 @@
+import { type HeldWriteEvidence, type HeldWriteView, type ReviewedWriteRecoveryInput, type WriteHold, type WriteHoldClient, type WriteHoldGate, type WriteHoldHandle, type WriteHoldSettled, type WriteHoldState } from "@bananapus/nana-sdk-core/review";
+import type { Address, Hex, TransactionReceipt } from "viem";
+export type UseHeldWriteOptions = {
+    /** The app's one write hold controller (createWriteHold()). */
+    hold: WriteHold;
+    chainId: number;
+    /** The account that sends: the wallet, or the Safe. */
+    account: Address;
+    /** Whether `account` is a Safe whose writes are proposals. */
+    safe?: boolean;
+    /** The action's intent key (payIntent and the other builders). */
+    namespace?: string;
+    /** Keys an earlier version held this write under. */
+    legacy?: Parameters<WriteHold["open"]>[1] extends infer O ? O extends {
+        legacy?: infer L;
+    } ? L : never : never;
+    /** The reviewed call, when built; without one, the hold is found by `namespace`. */
+    call?: ReviewedWriteRecoveryInput["call"];
+    /** Reads the account's chain. */
+    client: WriteHoldClient | undefined;
+    /** A previous deploy's saved evidence of this write: adopted before any send. */
+    adopt?: () => Promise<HeldWriteEvidence | null | undefined>;
+    onAdopted?: (state: WriteHoldState) => void;
+    /** The hold settled what this view saw held, on authenticated evidence: once. */
+    onSettled?: (settled: WriteHoldSettled, receipt: TransactionReceipt | null) => void;
+    /** Released: by the user's exit (reopen the review), or by another window. */
+    onReleased?: (by: "user" | "other-tab") => void;
+    /** How often a held write is asked again (15 s to 60 s, 30 s by default). */
+    pollMs?: number;
+};
+export type UseHeldWriteResult = HeldWriteView & {
+    /** The exit the hold offers now, with its label; null when none. */
+    exitAction: {
+        label: string;
+        run: () => Promise<boolean>;
+    } | null;
+    /**
+     * On a success settled while away ("This went through while you were
+     * away."): the user's choice to send it again. Null otherwise.
+     */
+    sendAgainAction: {
+        label: string;
+        run: () => Promise<void>;
+    } | null;
+    /** Send under the hold, once any adoption is done. */
+    send: (run: (gate: WriteHoldGate) => Promise<Hex>) => Promise<Hex>;
+    /** Ask the chain now. */
+    check: () => Promise<HeldWriteView>;
+    /** The hold handle, for anything else. */
+    handle: WriteHoldHandle | undefined;
+};
+/**
+ * One held write, the one way every app runs it: its send under the hold,
+ * the watch, the shared follower of its transaction or Safe proposal, its
+ * one line, its exit and the adoption of a previous deploy's record.
+ *
+ * The exit ("I checked my wallet") only releases the hold: `onReleased("user")`
+ * is where the app reopens its review, so a resend always shows the values it
+ * sends. A release by another window is neutral (`releasedBy: "other-tab"`),
+ * and `onSettled` fires only for a settlement of what this view saw held.
+ */
+export declare function useHeldWrite(options: UseHeldWriteOptions): UseHeldWriteResult;
+//# sourceMappingURL=useHeldWrite.d.ts.map

package/dist/hooks/heldWrite/useHeldWrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHeldWrite.d.ts","sourceRoot":"","sources":["../../../src/hooks/heldWrite/useHeldWrite.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAElB,KAAK,0BAA0B,EAC/B,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,MAAM,CAAC;AAQ7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,+DAA+D;IAC/D,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GACrD,CAAC,SAAS;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;KAAE,GAC5B,CAAC,GACD,KAAK,GACP,KAAK,CAAC;IACV,oFAAoF;IACpF,IAAI,CAAC,EAAE,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAC1C,iCAAiC;IACjC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC5D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC5C,iFAAiF;IACjF,SAAS,CAAC,EAAE,CACV,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB,GAAG,IAAI,KAC/B,IAAI,CAAC;IACV,8EAA8E;IAC9E,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,KAAK,IAAI,CAAC;IAChD,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG;IAC/C,oEAAoE;IACpE,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAClE;;;OAGG;IACH,eAAe,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACpE,sDAAsD;IACtD,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACnE,yBAAyB;IACzB,KAAK,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IACpC,0CAA0C;IAC1C,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;CACrC,CAAC;AAiBF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAgG7E"}

package/dist/hooks/heldWrite/useHeldWrites.d.ts

@@ -0,0 +1,40 @@
+import { type HeldWriteView, type WriteHold, type WriteHoldClient } from "@bananapus/nana-sdk-core/review";
+import type { Address } from "viem";
+/** One held write an app-wide notice shows. */
+export type HeldWriteItem = {
+    key: string;
+    /** What the action is, when the app names it. */
+    label?: string;
+    view: HeldWriteView;
+    /** Release it (the notice's exit): true when released. */
+    release: () => Promise<boolean>;
+};
+/**
+ * The holds of a fixed set of actions, found by their intents alone and
+ * shown with their lines and exits, whatever the actions' buttons allow now.
+ */
+export declare function useHeldIntents({ hold, chainId, account, client, intents, pollMs, }: {
+    hold: WriteHold;
+    chainId: number;
+    account: Address | undefined;
+    client: WriteHoldClient | undefined;
+    intents: readonly {
+        namespace: string;
+        label?: string;
+    }[];
+    pollMs?: number;
+}): HeldWriteItem[];
+/**
+ * Every write held for `account` on `chainId`, whatever action made it
+ * (`hold.list`), read again when another window changes one and every poll.
+ */
+export declare function useHeldWrites({ hold, chainId, account, client, label, pollMs, }: {
+    hold: WriteHold;
+    chainId: number;
+    account: Address | undefined;
+    client: WriteHoldClient | undefined;
+    /** The app's name for a listed write's action, when it knows it. */
+    label?: (record: ReturnType<WriteHold["list"]>[number]["record"]) => string | undefined;
+    pollMs?: number;
+}): HeldWriteItem[];
+//# sourceMappingURL=useHeldWrites.d.ts.map

package/dist/hooks/heldWrite/useHeldWrites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHeldWrites.d.ts","sourceRoot":"","sources":["../../../src/hooks/heldWrite/useHeldWrites.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAElB,KAAK,SAAS,EACd,KAAK,eAAe,EAErB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAO,MAAM,MAAM,CAAC;AAEzC,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,aAAa,CAAC;IACpB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,CAAC;AAqDF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,OAAO,EACP,OAAO,EACP,MAAM,EACN,OAAO,EACP,MAAM,GACP,EAAE;IACD,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,OAAO,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,aAAa,EAAE,CAqBlB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,OAAO,EACP,OAAO,EACP,MAAM,EACN,KAAK,EACL,MAAe,GAChB,EAAE;IACD,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,oEAAoE;IACpE,KAAK,CAAC,EAAE,CACN,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,KACpD,MAAM,GAAG,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,aAAa,EAAE,CA6BlB"}

package/dist/hooks/heldWrite/useSavedAttempt.d.ts

@@ -0,0 +1,54 @@
+import { type SavedAttempt, type SavedAttemptOutcome, type SavedAttemptRecovery, type SavedAttemptRetirement, type WriteHoldClient } from "@bananapus/nana-sdk-core/review";
+export type UseSavedAttemptOptions<T> = {
+    /** The app's one saved-attempt recovery (createSavedAttemptRecovery()). */
+    recovery: SavedAttemptRecovery;
+    /** The saved attempt; none while nothing is saved. */
+    attempt: SavedAttempt<T> | null | undefined;
+    /** Reads the attempt's chain. */
+    client: WriteHoldClient | undefined;
+    /** The check action's next step: "I checked it. <next>." ("Review it again" by default). */
+    checkNext?: string;
+};
+/** What a retirement returned: whether it took, and whether it outlives this tab. */
+type Retired = Awaited<ReturnType<SavedAttemptRecovery["retire"]>>;
+export type UseSavedAttemptResult<T> = {
+    /** How recovery ended; null until it has, or with no attempt. */
+    outcome: SavedAttemptOutcome<T> | null;
+    recovering: boolean;
+    /** Recover again now: also "Check again" on a success whose details are unavailable. */
+    recover: () => Promise<SavedAttemptOutcome<T> | null>;
+    /** On `check`: the one explicit action, which retires the attempt for every tab and reload. */
+    checkAction: {
+        line: string;
+        warning: string;
+        label: string;
+        run: () => Promise<Retired>;
+    } | null;
+    /**
+     * Only after the check action came back `reason: "unreadable"` (the browser
+     * has storage it can't read): the warned exit, "I checked my wallet.
+     * Continue anyway", which retires in this tab alone if storage still can't
+     * be read. Never a first option.
+     */
+    unreadableAction: {
+        line: string;
+        label: string;
+        run: () => Promise<Retired>;
+    } | null;
+    /**
+     * Retire after the user's exit or a followed settlement; recovers again.
+     * Bound to the attempt it was rendered for: called after that attempt (or
+     * its recovery or client) changed, it refuses before anything is saved.
+     */
+    retire: (reason: SavedAttemptRetirement) => Promise<Retired>;
+};
+/**
+ * One saved attempt's recovery, the one way every app runs it: recovered
+ * when it (or the client) appears, before the app prepares any new send, with
+ * the check action ready on `check`. Every answer and callback belongs to the
+ * attempt, recovery and client it started with: an earlier one's, or an older
+ * request's, never reaches the current one.
+ */
+export declare function useSavedAttempt<T>(options: UseSavedAttemptOptions<T>): UseSavedAttemptResult<T>;
+export {};
+//# sourceMappingURL=useSavedAttempt.d.ts.map

package/dist/hooks/heldWrite/useSavedAttempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSavedAttempt.d.ts","sourceRoot":"","sources":["../../../src/hooks/heldWrite/useSavedAttempt.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACrB,MAAM,iCAAiC,CAAC;AAUzC,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI;IACtC,2EAA2E;IAC3E,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,sDAAsD;IACtD,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5C,iCAAiC;IACjC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qFAAqF;AACrF,KAAK,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEnE,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,iEAAiE;IACjE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,wFAAwF;IACxF,OAAO,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACtD,+FAA+F;IAC/F,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;KAC7B,GAAG,IAAI,CAAC;IACT;;;;;OAKG;IACH,gBAAgB,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;KAC7B,GAAG,IAAI,CAAC;IACT;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,CAAC;AASF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACjC,qBAAqB,CAAC,CAAC,CAAC,CAoG1B"}

package/dist/hooks/index.d.ts

@@ -16,4 +16,5 @@ export * from "./useEtherPrice";
 export * from "./ruleset/useJBRuleset";
 export * from "./ruleset/useResolveDataHook";
 export * from "./ruleset/useJBUpcomingRuleset";
+export * from "./heldWrite";
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AACrD,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AACrD,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,aAAa,CAAC"}