vintage-frames 0.14.1 → 0.16.0

package/dist/shell/finder.d.ts

@@ -23,6 +23,9 @@
  *   View (Arrange Windows), Special (Clean Up, Empty Trash…), each disabled
  *   while it has nothing to act on. A site switches commands off and adds
  *   its own.
+ * - Alerts are the Finder's own, composed with the site's caution art and
+ *   held by it while they are up. A site answers any of them with its own
+ *   dialog through `alertWith`.
  */
 import type { VfIcon, VfMenuItem, VfViewportBox } from '../index.js';
 import type { Catalog, CatalogStorage, Item, Volumes } from './catalog.js';
@@ -43,7 +46,40 @@ export interface FinderArt {
     disk?: string;
     /** 12×12: the mark before the item count in the Trash's window and trashed folders. */
     trashMark?: string;
+    /** 32×32: beside the message in the Finder's alerts. Without it they have no art. */
+    caution?: string;
 }
+/** What a failed command was, in the `failed` alert. */
+export type FinderFailedAction = 'new-folder' | 'empty-trash' | 'paste' | 'add-file';
+/** The Finder's alerts, by id, with the details each one's handler gets. */
+export interface FinderAlerts {
+    /** Special → Empty Trash…: an answer of `'ok'` empties the Trash. */
+    'empty-trash': {
+        count: number;
+        bytes: number;
+    };
+    /** New Folder, Paste, a dropped file or `storageReady()`, without storage. */
+    'storage-unavailable': Record<string, never>;
+    /** A rename past the limit. */
+    'name-too-long': {
+        limit: number;
+    };
+    /** A rename to nothing. */
+    'name-rejected': Record<string, never>;
+    /** A filing storage refused. */
+    'move-failed': {
+        error: Error;
+    };
+    /** New Folder, Empty Trash, Paste or a dropped file failed. */
+    failed: {
+        action: FinderFailedAction;
+        error: Error;
+    };
+}
+/** One of the Finder's alerts. */
+export type FinderAlert = keyof FinderAlerts;
+/** Answers one of the Finder's alerts: resolves the answer, or null. */
+export type FinderAlertHandler<K extends FinderAlert> = (details: FinderAlerts[K]) => string | null | Promise<string | null>;
 /** The Finder's own commands, each of which a site can switch off. */
 export type FinderCommand = 'open' | 'new-folder' | 'close' | 'copy' | 'paste' | 'select-all' | 'arrange' | 'clean-up' | 'empty-trash';
 /** The Finder's menus, by `data-menu`. */
@@ -85,6 +121,13 @@ export interface FinderApi {
     iconFor(id: string): VfIcon | null;
     /** Add a command to the Finder's menus. Call it from `extend`, before the menus first reach the bar. */
     addCommand(spec: FinderCommandSpec): VfMenuItem;
+    /** Answer one of the Finder's alerts with the site's own dialog. Call it from `extend`. */
+    alertWith<K extends FinderAlert>(id: K, handler: FinderAlertHandler<K>): void;
+    /**
+     * Whether storage answers. When it doesn't, raises Storage Unavailable —
+     * the site's answer to it, where `alertWith` gave one — and returns false.
+     */
+    storageReady(): boolean;
 }
 export interface FinderOptions {
     /** Where the catalog is kept: `memoryStorage()`, `indexedDbStorage(name)`, the site's own, or null for nothing. */
@@ -107,7 +150,9 @@ export interface FinderOptions {
     cleanUpAfterResize?: boolean;
     /** Switch commands off: `{ 'empty-trash': false }`. */
     commands?: Partial<Record<FinderCommand, boolean>>;
-    /** Add the site's own commands. */
+    /** The site's dialogs for the Finder, each with a `data-dialog` name, held by it: `ctx.dialog(name)` in `extend`. */
+    dialogs?: string;
+    /** Add the site's own commands, and answer the Finder's alerts. */
     extend?(finder: FinderApi, ctx: AppContext): void;
     /** A folder window's size, system px. Default 320 × 223: three columns and two rows of icons. */
     window?: Size;