@lerx/promise-modal 0.12.1 → 0.12.3

package/README.md

@@ -793,11 +793,13 @@ Opens a prompt modal to receive input from the user.
     - props: `{ value: T; onChange: (value: T) => void }`
   - `defaultValue?`: Default value (T)
   - `disabled?`: Function to determine if confirm button should be disabled
-    - `(value: T) => boolean`
-  - `returnOnCancel?`: Whether to return default value on cancel (boolean)
+    - `(value: T | undefined) => boolean`
+  - `returnOnCancel?`: If true, cancel resolves with the current input value instead of null (boolean)
   - `footer?`: Footer settings (similar to confirm)
 
-**Returns:** `Promise<T>` - Resolves to the input value
+**Returns:** `Promise<T | null>` - Resolves to the input value on confirm, or null on cancel
+
+> **Upgrade note:** `prompt()` now types cancellation explicitly — the return is `Promise<T | null>` and the `disabled` callback receives `T | undefined`. Consumers that previously annotated these as non-null may hit new TypeScript errors on upgrade; the runtime behaviour (cancel resolves `null`) is unchanged.
 
 ```typescript
 // Example

package/dist/app/ModalManager.d.ts

@@ -15,8 +15,17 @@ export declare class ModalManager {
     static get anchored(): boolean;
     private static __prerenderList__;
     static get prerender(): Modal[];
+    private static __defaultOpenHandler__;
     private static __openHandler__;
+    /**
+     * Registers the React-side open handler, then flushes the prerender queue
+     * through it so modals opened before mount keep their promise wiring alive.
+     */
     static set openHandler(handler: Fn<[Modal], ModalNode>);
+    /** Attaches a flush-time dispatcher to a queued modal; no-op if not queued. */
+    static bindPrerender(modal: Modal, dispatch: Fn): void;
+    /** Removes a queued modal (pre-mount abort). Returns whether it was queued. */
+    static cancelPrerender(modal: Modal): boolean;
     private static __refreshHandler__?;
     static set refreshHandler(handler: Fn<[], void>);
     static refresh(): void;
@@ -24,5 +33,5 @@ export declare class ModalManager {
     static applyStyleSheet(): void;
     static getHashedClassNames(styleId: string): string;
     static reset(): void;
-    static open(modal: Modal): ModalNode;
+    static open(modal: Modal): ModalNode | undefined;
 }

package/dist/app/index.d.ts

@@ -0,0 +1,2 @@
+export { ModalManager } from './ModalManager.js';
+export { DEFAULT_ANIMATION_DURATION, DEFAULT_BACKDROP_COLOR, DEFAULT_Z_INDEX, } from './constant.js';

package/dist/bootstrap/BootstrapProvider/useBootstrap.d.ts

@@ -96,33 +96,6 @@ import type { BootstrapProviderProps } from './type.js';
  * ```
  *
  * @example
- * Multiple modal systems:
- * ```tsx
- * function MultiModalApp() {
- *   // System modals (errors, confirmations)
- *   const { portal: systemPortal } = useBootstrap({
- *     ForegroundComponent: SystemModal,
- *     options: { backdrop: 'rgba(255, 0, 0, 0.8)' },
- *   });
- *
- *   // Feature modals (forms, wizards)
- *   const { portal: featurePortal } = useBootstrap({
- *     ForegroundComponent: FeatureModal,
- *     options: { backdrop: 'rgba(0, 0, 255, 0.8)' },
- *   });
- *
- *   return (
- *     <>
- *       <SystemSection />
- *       <FeatureSection />
- *       {systemPortal}
- *       {featurePortal}
- *     </>
- *   );
- * }
- * ```
- *
- * @example
  * With custom hooks for specific modal types:
  * ```tsx
  * function useConfirmDialog() {
@@ -178,7 +151,8 @@ import type { BootstrapProviderProps } from './type.js';
  * @remarks
  * - Use `mode: 'manual'` when you need to control the initialization timing
  * - The portal element must be rendered in your component tree
- * - Each hook instance creates an independent modal system
+ * - The modal system is a singleton: mount exactly one bootstrap
+ *   (ModalProvider or useBootstrap) at a time
  * - Context changes will affect all modals created after the change
  */
 export declare const useBootstrap: ({ usePathname: useExternalPathname, ForegroundComponent, BackgroundComponent, TitleComponent, SubtitleComponent, ContentComponent, FooterComponent, options, context, mode, }?: BootstrapProviderProps & {

package/dist/claude-hashes.json

@@ -2,15 +2,15 @@
   "schemaVersion": 1,
   "package": {
     "name": "@lerx/promise-modal",
-    "version": "0.12.1"
+    "version": "0.12.3"
   },
-  "generatedAt": "2026-04-24T14:52:39.411Z",
+  "generatedAt": "2026-07-05T18:39:01.047Z",
   "algorithm": "sha256",
   "assetRoot": "docs/claude",
   "files": {
     "skills/promise-modal-skill/SKILL.md": "b424c979b9e969e11ba8fa0a56afc3cbf1793c822f06509e6b730068f384679e",
     "skills/promise-modal-skill/knowledge/advanced-patterns.md": "2e2c29449a46b1336727f8a1d5f1eede4e99639675dbe819edd2bf4243acfaab",
-    "skills/promise-modal-skill/knowledge/api-reference.md": "1df36fa5b832d2349c05dacaec913876f7c30fad6478fcae64c8a4bd65bc023a",
+    "skills/promise-modal-skill/knowledge/api-reference.md": "b54ae4dcd0791ebfce8110a69af615e712bfdcbb5be5b57f725cd4bfb12ab50f",
     "skills/promise-modal-skill/knowledge/hooks-reference.md": "b0137caf257ad9712cfa7ab44c908041bbbc61bf355fa0180925a35479e47516",
     "skills/promise-modal-skill/knowledge/type-definitions.md": "fde17b7f99d3e65b7e6c16abf4689af0a9e41a8a06dfeb9482b94a7611841d50"
   },

package/dist/core/handle/alert.d.ts

@@ -8,7 +8,8 @@ import type { AlertProps } from './type.js';
  * @returns Object containing modalNode and promiseHandler
  *
  * @remarks
- * - modalNode: The created modal node instance
+ * - modalNode: live getter for the modal node; undefined while the modal is
+ *   queued before the ModalProvider mounts, then set once the queue flushes
  * - promiseHandler: Promise that resolves when the modal is closed
  *
  * @example
@@ -22,6 +23,7 @@ import type { AlertProps } from './type.js';
  * ```
  */
 export declare const alertHandler: <BackgroundValue = any>(args: AlertProps<BackgroundValue>) => {
-    readonly modalNode: AlertNode<BackgroundValue>;
-    readonly promiseHandler: Promise<void>;
+    readonly modalNode: AlertNode<BackgroundValue> | undefined;
+    promiseHandler: Promise<void>;
+    cancel: import("../../@aileron/declare").Fn<[], void>;
 };

package/dist/core/handle/confirm.d.ts

@@ -8,10 +8,11 @@ import type { ConfirmProps } from './type.js';
  * @returns Object containing modalNode and promiseHandler
  *
  * @remarks
- * - modalNode: The created modal node instance
+ * - modalNode: live getter for the modal node; undefined while the modal is
+ *   queued before the ModalProvider mounts, then set once the queue flushes
  * - promiseHandler: Promise that resolves to true if confirmed, false if cancelled
  * - Returns true only when explicitly confirmed via the confirm action
- * - Returns false for cancel action or backdrop click (if enabled)
+ * - Returns false for cancel action, backdrop click (if enabled), or abort
  *
  * @example
  * ```tsx
@@ -27,6 +28,7 @@ import type { ConfirmProps } from './type.js';
  * ```
  */
 export declare const confirmHandler: <BackgroundValue = any>(args: ConfirmProps<BackgroundValue>) => {
-    readonly modalNode: ConfirmNode<BackgroundValue>;
-    readonly promiseHandler: Promise<boolean>;
+    readonly modalNode: ConfirmNode<BackgroundValue> | undefined;
+    promiseHandler: Promise<boolean>;
+    cancel: import("../../@aileron/declare").Fn<[], void>;
 };

package/dist/core/handle/dispatchModal.d.ts

@@ -0,0 +1,29 @@
+import type { Fn } from '../../@aileron/declare/index.js';
+import type { ModalNode } from '../../core/node/index.js';
+import type { Modal } from '../../types/index.js';
+interface DispatchModalOptions<Result> {
+    /** Abort signal that cancels the modal (before or after mount). */
+    signal?: AbortSignal;
+    /** Maps the node's raw resolve payload to the public promise result. */
+    mapResult: Fn<[result: unknown], Result>;
+    /** Raw payload used when the modal is aborted before React ever mounted. */
+    cancelResult: Fn<[], unknown>;
+}
+/**
+ * Opens a modal through ModalManager and wires its promise settlement.
+ *
+ * The resolver travels inside the modal data (`handleResolve`), so the wiring
+ * survives the prerender queue: modals opened before the provider mounts are
+ * flushed later and still settle the very same promise.
+ *
+ * @returns modalNode - live getter: undefined while the modal is queued before
+ *   mount, then the node created by the flush (late reads see the real node)
+ * @returns promiseHandler - settles on user interaction or abort; rejects only
+ *   when the open handler itself throws
+ */
+export declare const dispatchModal: <Node extends ModalNode, Result>(modal: Modal, { signal, mapResult, cancelResult }: DispatchModalOptions<Result>) => {
+    readonly modalNode: Node | undefined;
+    promiseHandler: Promise<Result>;
+    cancel: Fn<[], void>;
+};
+export {};

package/dist/core/handle/index.d.ts

@@ -2,4 +2,4 @@ export { alertHandler } from './alert.js';
 export { confirmHandler } from './confirm.js';
 export { promptHandler } from './prompt.js';
 export { alert, confirm, prompt } from './static.js';
-export type { AlertProps, ConfirmProps, PromptProps } from './type.js';
+export type { AlertProps, ConfirmProps, OverridableHandleProps, PromptProps, } from './type.js';

package/dist/core/handle/prompt.d.ts

@@ -9,12 +9,14 @@ import type { PromptProps } from './type.js';
  * @returns Object containing modalNode and promiseHandler
  *
  * @remarks
- * - modalNode: The created modal node instance
- * - promiseHandler: Promise that resolves with user input value
+ * - modalNode: live getter for the modal node; undefined while the modal is
+ *   queued before the ModalProvider mounts, then set once the queue flushes
+ * - promiseHandler: Promise that resolves with the user input value
  * - Input component receives value, onChange, onConfirm, onCancel, and context props
  * - Use disabled function to control confirm button's enabled state
- * - If returnOnCancel is false (default), promise rejects on cancel
- * - If returnOnCancel is true, returns defaultValue on cancel
+ * - If returnOnCancel is false (default), the promise resolves with null on cancel
+ * - If returnOnCancel is true, resolves with the input value at cancel time
+ *   (initially defaultValue)
  *
  * @example
  * ```tsx
@@ -31,15 +33,12 @@ import type { PromptProps } from './type.js';
  *   defaultValue: '',
  * });
  *
- * try {
- *   const name = await promiseHandler;
- *   console.log('User entered:', name);
- * } catch {
- *   console.log('User cancelled');
- * }
+ * const name = await promiseHandler;
+ * if (name === null) console.log('User cancelled');
  * ```
  */
 export declare const promptHandler: <InputValue, BackgroundValue = any>(args: PromptProps<InputValue, BackgroundValue>) => {
-    readonly modalNode: PromptNode<InputValue, BackgroundValue>;
-    readonly promiseHandler: Promise<InputValue>;
+    readonly modalNode: PromptNode<InputValue, BackgroundValue> | undefined;
+    promiseHandler: Promise<InputValue | null>;
+    cancel: import("../../@aileron/declare").Fn<[], void>;
 };

package/dist/core/handle/static.d.ts

@@ -66,8 +66,9 @@ export declare const confirm: <BackgroundValue = any>(args: ConfirmProps<Backgro
  * @typeParam InputValue - Type of the value collected from user input
  * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
  * @param args - Prompt modal configuration options
- * @returns Promise that resolves with user input value
- * @throws Rejects when cancelled (unless returnOnCancel is true)
+ * @returns Promise that resolves with the user input value on confirm, or null
+ *   on cancel. With returnOnCancel: true, cancel resolves with the input value
+ *   at cancel time (initially defaultValue) instead of null.
  *
  * @example
  * ```tsx
@@ -84,6 +85,9 @@ export declare const confirm: <BackgroundValue = any>(args: ConfirmProps<Backgro
  *   ),
  *   defaultValue: 'John Doe',
  * });
+ * if (name === null) {
+ *   console.log('User cancelled');
+ * }
  * ```
  *
  * @example
@@ -102,4 +106,4 @@ export declare const confirm: <BackgroundValue = any>(args: ConfirmProps<Backgro
  * });
  * ```
  */
-export declare const prompt: <InputValue, BackgroundValue = any>(args: PromptProps<InputValue, BackgroundValue>) => Promise<InputValue>;
+export declare const prompt: <InputValue, BackgroundValue = any>(args: PromptProps<InputValue, BackgroundValue>) => Promise<InputValue | null>;

package/dist/core/handle/type.d.ts

@@ -44,9 +44,13 @@ export interface PromptProps<InputValue, BackgroundValue = any> extends BaseHand
     defaultValue?: InputValue;
     /** Input component that receives value, onChange, and other props */
     Input: Fn<[props: PromptInputProps<InputValue>], ReactNode>;
-    /** Validation function. Returns true to disable the confirm button */
-    disabled?: Fn<[value: InputValue], boolean>;
-    /** If true, returns defaultValue instead of rejecting on cancel */
+    /**
+     * Validation function. Returns true to disable the confirm button.
+     * Called with the current value, which stays undefined until the first
+     * input when no defaultValue is provided.
+     */
+    disabled?: Fn<[value: InputValue | undefined], boolean>;
+    /** If true, cancel resolves with the current input value instead of null */
     returnOnCancel?: boolean;
     /** Footer configuration. Can be a render function, options object, or false */
     footer?: PromptFooterRender<InputValue> | FooterOptions | false;

package/dist/core/node/ModalNode/PromptNode.d.ts

@@ -8,7 +8,7 @@ export declare class PromptNode<T = any, B = any> extends AbstractNode<T, B> {
     readonly content?: ReactNode | ComponentType<PromptContentProps>;
     readonly defaultValue: T | undefined;
     readonly Input: Fn<[props: PromptInputProps<T>], ReactNode>;
-    readonly disabled?: Fn<[value: T], boolean>;
+    readonly disabled?: Fn<[value: T | undefined], boolean>;
     readonly returnOnCancel?: boolean;
     readonly footer?: PromptFooterRender<T> | FooterOptions | false;
     private __value__;

package/dist/helpers/hideModal.d.ts

@@ -0,0 +1,2 @@
+import type { ModalNode } from '../core/index.js';
+export declare const hideModal: (modalNode: ModalNode, refresh?: boolean) => NodeJS.Timeout | undefined;

package/dist/hooks/useModal.d.ts

@@ -1,7 +1,6 @@
-import { type AlertProps, type ConfirmProps, type PromptProps } from '../core/index.js';
-import type { OverridableHandleProps } from '../core/handle/type.js';
+import { type AlertProps, type ConfirmProps, type OverridableHandleProps, type PromptProps } from '../core/index.js';
 export declare const useModal: (configuration?: OverridableHandleProps) => {
     readonly alert: <Background = any>(args: AlertProps<Background>) => Promise<void>;
     readonly confirm: <Background = any>(args: ConfirmProps<Background>) => Promise<boolean>;
-    readonly prompt: <Value, Background = any>(args: PromptProps<Value, Background>) => Promise<Value>;
+    readonly prompt: <Value, Background = any>(args: PromptProps<Value, Background>) => Promise<Value | null>;
 };