quoin-editor 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -109,17 +109,17 @@ declare function paletteBlocks(definitions: AnyBlockDefinition[]): AnyBlockDefin
 type BlockCanvasProps = {
     /**
      * The document. Update it synchronously from `onChange`, as with a controlled `<input value onChange>`.
-     * Applying the edit late is tolerated as long as what comes back is one of the arrays the canvas emitted:
-     * it recognises its own output even several keystrokes behind, so a transition or a debounced setter is safe.
-     * A store that rebuilds the document on the way through hands back a structural copy instead, which arrives
-     * behind the canvas's own state and reads as a foreign document. That does not revert the edit cleanly: the
-     * characters the copy predates are dropped and the ones typed after them are kept.
+     * Applying the edit late is tolerated: the canvas recognises an array it emitted however late it comes back, and
+     * a structural copy of one within 64 edits, so a transition, a debounced setter or a store that clones the
+     * document on the way through is safe.
      * A new array that differs from the last one you supplied replaces what the canvas shows, which is how a host
      * loads, undoes or merges. An array structurally equal to the last one you supplied is ignored, so a "discard
-     * changes" button that hands back the original document does nothing; remount the canvas with a React `key` to
-     * force a reset. The comparison is shallow over each block's `data`: a host whose block `data` holds nested
-     * objects rebuilt on every render, and which does not echo `onChange` back, can still lose an edit. The core
-     * block types all have flat data, so this only affects custom blocks.
+     * changes" button that hands back the original document does nothing. A host that does not echo `onChange` back
+     * meets the same when it restores a copy of a state from the last 64 edits, which reads as a late echo. Remount
+     * the canvas with a React `key` to force a reset in either case. The comparison is shallow over each block's
+     * `data`: a host whose block `data` holds nested objects rebuilt on every render, and which does not echo
+     * `onChange` back, can still lose an edit. The core block types all have flat data, so this only affects custom
+     * blocks.
      */
     blocks: QuoinBlock[];
     onChange: (blocks: QuoinBlock[]) => void;
@@ -209,8 +209,8 @@ type UploadFieldProps = {
     label: string;
     /** An `accept` attribute for the file input, such as `'image/*'` or `'.pdf'`. */
     accept?: string;
-    /** Called once the upload resolves. Throwing from it is reported through the canvas `onError`. */
-    onUploaded: (result: UploadResult) => void;
+    /** Called once the upload resolves. The field stays busy until a returned promise settles, and throwing or rejecting is reported through the canvas `onError`. */
+    onUploaded: (result: UploadResult) => void | Promise<void>;
 };
 /** A file picker wired to the canvas `upload` function, with its own busy state and inline error. */
 declare function UploadField({ category, label, accept, onUploaded }: UploadFieldProps): React.JSX.Element;
@@ -267,7 +267,7 @@ type BlockList = {
 declare function useBlockList(initial: QuoinBlock[]): BlockList;
 
 /** Where a debounced save stands, for a "Saving..." or "Saved" indicator. */
-type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying';
+type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying' | 'failed';
 /** What `useAutosave` tracks, how to build the payload, and how to persist it. */
 type UseAutosaveInput<T> = {
     /** The tracked fields. An edit to any of them marks dirty and restarts the debounce. */
@@ -280,24 +280,41 @@ type UseAutosaveInput<T> = {
     save: (payload: T) => unknown;
     debounceMs?: number;
     maxBackoffMs?: number;
+    /** Retries after a failed save before giving up with status `failed`. Defaults to 8. */
+    maxRetries?: number;
+    /**
+     * Whether a failed save is worth retrying. Receives the rejection, or the resolved
+     * `{ ok: false }` value. Return false for a permanent failure. Defaults to always.
+     */
+    isRetryable?: (error: unknown) => boolean;
+    /** Save a pending edit when the page is hidden or closed. Defaults to true. */
+    flushOnHide?: boolean;
 };
-/** The current save status and a way to retry a failed save immediately. */
+/** The current save status, the last failure, and ways to save immediately. */
 type UseAutosaveResult = {
     status: AutosaveStatus;
+    /** The last failure, kept while a retry is pending and cleared by the next success. */
+    error: unknown;
+    /** Saves now, even when nothing is pending, and starts the retries over. */
     retry: () => void;
+    /** Saves a pending edit now and starts the retries over. A no-op when nothing is pending. */
+    flush: () => void;
 };
 /**
- * Debounced last-write-wins autosave. Nothing fires on mount, only after the first
- * real edit, and a rejected save backs off exponentially until it lands. `save` and
- * `build` are read at fire time, so passing fresh closures each render is safe.
+ * Debounced last-write-wins autosave. Nothing fires on mount, only after the first real
+ * edit. One save runs at a time: edits made while it runs are saved once it settles, as one
+ * save of the newest payload. A failed save backs off exponentially until it lands, stops
+ * being retryable or runs out of retries. An edit still waiting for its debounce is saved
+ * on unmount and when the page is hidden. `save` and `build` are read at fire time, so
+ * passing fresh closures each render is safe.
  */
-declare function useAutosave<T>({ deps, build, save, debounceMs, maxBackoffMs, }: UseAutosaveInput<T>): UseAutosaveResult;
+declare function useAutosave<T>({ deps, build, save, debounceMs, maxBackoffMs, maxRetries, isRetryable, flushOnHide, }: UseAutosaveInput<T>): UseAutosaveResult;
 
 /** Height follows the content, and is recomputed when the box gets narrower or
  *  wider, because a re-wrap changes the line count without changing the value.
  *  Only a width change refits: reacting to the height this hook just set would
  *  feed the observer its own output. */
-declare function useAutoGrow<T extends HTMLTextAreaElement>(value: string): React.RefObject<T | null>;
+declare function useAutoGrow<T extends HTMLTextAreaElement>(value: string): React.RefObject<T>;
 
 /** A slash-palette entry: how it is shown and searched, and the markdown it inserts. */
 type TextCommand = {

package/dist/index.d.ts

@@ -109,17 +109,17 @@ declare function paletteBlocks(definitions: AnyBlockDefinition[]): AnyBlockDefin
 type BlockCanvasProps = {
     /**
      * The document. Update it synchronously from `onChange`, as with a controlled `<input value onChange>`.
-     * Applying the edit late is tolerated as long as what comes back is one of the arrays the canvas emitted:
-     * it recognises its own output even several keystrokes behind, so a transition or a debounced setter is safe.
-     * A store that rebuilds the document on the way through hands back a structural copy instead, which arrives
-     * behind the canvas's own state and reads as a foreign document. That does not revert the edit cleanly: the
-     * characters the copy predates are dropped and the ones typed after them are kept.
+     * Applying the edit late is tolerated: the canvas recognises an array it emitted however late it comes back, and
+     * a structural copy of one within 64 edits, so a transition, a debounced setter or a store that clones the
+     * document on the way through is safe.
      * A new array that differs from the last one you supplied replaces what the canvas shows, which is how a host
      * loads, undoes or merges. An array structurally equal to the last one you supplied is ignored, so a "discard
-     * changes" button that hands back the original document does nothing; remount the canvas with a React `key` to
-     * force a reset. The comparison is shallow over each block's `data`: a host whose block `data` holds nested
-     * objects rebuilt on every render, and which does not echo `onChange` back, can still lose an edit. The core
-     * block types all have flat data, so this only affects custom blocks.
+     * changes" button that hands back the original document does nothing. A host that does not echo `onChange` back
+     * meets the same when it restores a copy of a state from the last 64 edits, which reads as a late echo. Remount
+     * the canvas with a React `key` to force a reset in either case. The comparison is shallow over each block's
+     * `data`: a host whose block `data` holds nested objects rebuilt on every render, and which does not echo
+     * `onChange` back, can still lose an edit. The core block types all have flat data, so this only affects custom
+     * blocks.
      */
     blocks: QuoinBlock[];
     onChange: (blocks: QuoinBlock[]) => void;
@@ -209,8 +209,8 @@ type UploadFieldProps = {
     label: string;
     /** An `accept` attribute for the file input, such as `'image/*'` or `'.pdf'`. */
     accept?: string;
-    /** Called once the upload resolves. Throwing from it is reported through the canvas `onError`. */
-    onUploaded: (result: UploadResult) => void;
+    /** Called once the upload resolves. The field stays busy until a returned promise settles, and throwing or rejecting is reported through the canvas `onError`. */
+    onUploaded: (result: UploadResult) => void | Promise<void>;
 };
 /** A file picker wired to the canvas `upload` function, with its own busy state and inline error. */
 declare function UploadField({ category, label, accept, onUploaded }: UploadFieldProps): React.JSX.Element;
@@ -267,7 +267,7 @@ type BlockList = {
 declare function useBlockList(initial: QuoinBlock[]): BlockList;
 
 /** Where a debounced save stands, for a "Saving..." or "Saved" indicator. */
-type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying';
+type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'retrying' | 'failed';
 /** What `useAutosave` tracks, how to build the payload, and how to persist it. */
 type UseAutosaveInput<T> = {
     /** The tracked fields. An edit to any of them marks dirty and restarts the debounce. */
@@ -280,24 +280,41 @@ type UseAutosaveInput<T> = {
     save: (payload: T) => unknown;
     debounceMs?: number;
     maxBackoffMs?: number;
+    /** Retries after a failed save before giving up with status `failed`. Defaults to 8. */
+    maxRetries?: number;
+    /**
+     * Whether a failed save is worth retrying. Receives the rejection, or the resolved
+     * `{ ok: false }` value. Return false for a permanent failure. Defaults to always.
+     */
+    isRetryable?: (error: unknown) => boolean;
+    /** Save a pending edit when the page is hidden or closed. Defaults to true. */
+    flushOnHide?: boolean;
 };
-/** The current save status and a way to retry a failed save immediately. */
+/** The current save status, the last failure, and ways to save immediately. */
 type UseAutosaveResult = {
     status: AutosaveStatus;
+    /** The last failure, kept while a retry is pending and cleared by the next success. */
+    error: unknown;
+    /** Saves now, even when nothing is pending, and starts the retries over. */
     retry: () => void;
+    /** Saves a pending edit now and starts the retries over. A no-op when nothing is pending. */
+    flush: () => void;
 };
 /**
- * Debounced last-write-wins autosave. Nothing fires on mount, only after the first
- * real edit, and a rejected save backs off exponentially until it lands. `save` and
- * `build` are read at fire time, so passing fresh closures each render is safe.
+ * Debounced last-write-wins autosave. Nothing fires on mount, only after the first real
+ * edit. One save runs at a time: edits made while it runs are saved once it settles, as one
+ * save of the newest payload. A failed save backs off exponentially until it lands, stops
+ * being retryable or runs out of retries. An edit still waiting for its debounce is saved
+ * on unmount and when the page is hidden. `save` and `build` are read at fire time, so
+ * passing fresh closures each render is safe.
  */
-declare function useAutosave<T>({ deps, build, save, debounceMs, maxBackoffMs, }: UseAutosaveInput<T>): UseAutosaveResult;
+declare function useAutosave<T>({ deps, build, save, debounceMs, maxBackoffMs, maxRetries, isRetryable, flushOnHide, }: UseAutosaveInput<T>): UseAutosaveResult;
 
 /** Height follows the content, and is recomputed when the box gets narrower or
  *  wider, because a re-wrap changes the line count without changing the value.
  *  Only a width change refits: reacting to the height this hook just set would
  *  feed the observer its own output. */
-declare function useAutoGrow<T extends HTMLTextAreaElement>(value: string): React.RefObject<T | null>;
+declare function useAutoGrow<T extends HTMLTextAreaElement>(value: string): React.RefObject<T>;
 
 /** A slash-palette entry: how it is shown and searched, and the markdown it inserts. */
 type TextCommand = {