@gjermundgaraba/pixel-paper 0.0.0-stage → 0.1.0

package/dist/command-palette/command-palette.d.ts

@@ -0,0 +1,579 @@
+import { Command } from "./match.js";
+import { Message } from "./message.js";
+import { Effect, Option, Schema } from "effect";
+import * as FoldkitCommand from "foldkit/command";
+import { Html } from "foldkit/html";
+import * as Subscription from "foldkit/subscription";
+import * as Update from "foldkit/update";
+/** Schema for a command palette: its Dialog, the commands' query and cursor (kept while a
+ *  page is open, so Back restores them), the open page, and the choice being picked. A cursor
+ *  is a row's id, so it holds to its row while the list changes. The rows are the view's
+ *  (built from its `commands`), so ↑, ↓ and Enter carry what their render showed: its rows,
+ *  the row it showed the cursor on, and the query and waiting arrows it was rendered with.
+ *  When that query is the Model's and the render had applied the waiting arrows, those rows
+ *  are the list, and update steps among them from the Model's cursor. A key pressed before the
+ *  view caught up (as the palette opens, or just after typing, while the list still shows the
+ *  last query's rows) cannot name a row yet: `cursorShift` counts the arrows, which the next
+ *  render applies from the cursor's row, and `isEnterPending` an Enter. Such a key returns
+ *  `ReportPendingKeys`, which reads the row the next render shows the cursor on: it becomes
+ *  the cursor, and a waiting Enter acts on it. `renderGeneration` counts the changes to the
+ *  page, the query and the waiting arrows, so a report from an older render is refused. */
+export declare const Model: Schema.Struct<{
+  readonly dialog: Schema.Struct<{
+    readonly dialog: Schema.Struct<{
+      readonly id: Schema.String;
+      readonly isOpen: Schema.Boolean;
+      readonly isAnimated: Schema.Boolean;
+      readonly animation: Schema.Struct<{
+        readonly id: Schema.String;
+        readonly isShowing: Schema.Boolean;
+        readonly transitionState: Schema.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
+        readonly transitionGeneration: Schema.Number;
+      }>;
+      readonly maybeFocusSelector: Schema.Option<Schema.String>;
+    }>;
+  }>;
+  readonly query: Schema.String;
+  readonly maybeCursor: Schema.Option<Schema.String>;
+  readonly cursorShift: Schema.Finite;
+  readonly isEnterPending: Schema.Boolean;
+  readonly renderGeneration: Schema.Int;
+  readonly maybePage: Schema.Option<Schema.Struct<{
+    readonly commandId: Schema.String;
+    readonly query: Schema.String;
+    readonly maybeCursor: Schema.Option<Schema.String>;
+  }>>;
+  readonly maybePicking: Schema.Option<Schema.String>;
+}>;
+export type Model = typeof Model.Type;
+/** Union of OutMessages a command palette reports. `SelectedCommand`: run this command; the
+ *  palette has closed first, so what it opens takes focus. `SelectedChoice`: apply this choice
+ *  of that command's page; the page holds, the row printing the working cursor, until the
+ *  caller reports back with `pickSucceeded` or `pickFailed`. `Closed`: the reader dismissed
+ *  the palette (Escape, a press on the veil), even while a pick was out; a write already
+ *  running keeps running, and its answer no longer changes the palette. */
+export declare const OutMessage: import("foldkit/message").MessageUnion<{
+  readonly SelectedCommand: {
+    id: Schema.String;
+  };
+  readonly SelectedChoice: {
+    commandId: Schema.String;
+    choiceId: Schema.String;
+  };
+  readonly Closed: {};
+}>;
+export type OutMessage = typeof OutMessage.Type;
+/** Configuration for creating a command palette with `init`. The `id` must be unique in the
+ *  document. */
+export type InitConfig = Readonly<{
+  id: string;
+}>;
+/** Creates a closed command palette. */
+export declare const init: (config: InitConfig) => Model;
+/** The palette's id, unique in the document. */
+export declare const id: (model: Model) => string;
+/** Whether the palette is open. */
+export declare const isOpen: (model: Model) => boolean;
+/** The words in the field: the open page's, or the commands'. A page whose choices are a
+ *  function of what is typed reads it here. */
+export declare const query: (model: Model) => string;
+/** The command whose page is open. */
+export declare const maybePageId: (model: Model) => Option.Option<string>;
+/** Whether a picked choice is waiting for the caller's answer. */
+export declare const isPicking: (model: Model) => boolean;
+/**
+ * Scrolls the cursor's row of the palette `paletteId` (its `id`) into view by the least
+ * distance, once the view has rendered. The palette returns it itself as the cursor moves, the
+ * query changes or a page opens; an application returns it too when the rows change under an
+ * open palette (see `maybeCursorId`), or as it opens one on a page whose cursor may be far
+ * down, and resolves it with `Message.CompletedScrollToCursor` in a Scene.
+ */
+export declare const ScrollToCursor: FoldkitCommand.CommandDefinitionWithArgs<"ScrollToCursor", {
+  paletteId: Schema.String;
+}, Effect.Effect<{
+  readonly _tag: "CompletedScrollToCursor";
+}, never, never>>;
+/** Processes a command palette Message and returns the next Model, Commands and OutMessage. */
+export declare const update: (model: Model, message: Message) => Readonly<{
+  model: {
+    readonly dialog: {
+      readonly dialog: {
+        readonly id: string;
+        readonly isOpen: boolean;
+        readonly isAnimated: boolean;
+        readonly animation: {
+          readonly id: string;
+          readonly isShowing: boolean;
+          readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
+          readonly transitionGeneration: number;
+        };
+        readonly maybeFocusSelector: Option.Option<string>;
+      };
+    };
+    readonly query: string;
+    readonly maybeCursor: Option.Option<string>;
+    readonly cursorShift: number;
+    readonly isEnterPending: boolean;
+    readonly renderGeneration: number;
+    readonly maybePage: Option.Option<{
+      readonly commandId: string;
+      readonly query: string;
+      readonly maybeCursor: Option.Option<string>;
+    }>;
+    readonly maybePicking: Option.Option<string>;
+  };
+  commands?: Update.Commands<{
+    readonly _tag: "CompletedFocus";
+  } | {
+    readonly _tag: "CompletedScrollToCursor";
+  } | {
+    readonly _tag: "CompletedReportPendingKeys";
+    readonly renderGeneration: number;
+    readonly maybeRow: Option.Option<{
+      readonly id: string;
+      readonly isHeld: boolean;
+      readonly hasPage: boolean;
+    }>;
+  } | {
+    readonly _tag: "ClickedBack";
+  } | {
+    readonly _tag: "ClickedRow";
+    readonly row: {
+      readonly id: string;
+      readonly isHeld: boolean;
+      readonly hasPage: boolean;
+    };
+    readonly maybeShownPage: Option.Option<string>;
+  } | {
+    readonly _tag: "GotDialogMessage";
+    readonly message: {
+      readonly _tag: "GotDialogMessage";
+      readonly message: {
+        readonly _tag: "CompletedCloseDialog";
+      } | {
+        readonly _tag: "CompletedReleaseDialogResources";
+      } | {
+        readonly _tag: "FailedAcquireResources";
+      } | {
+        readonly _tag: "FailedShowDialog";
+      } | {
+        readonly _tag: "GotAnimationMessage";
+        readonly message: {
+          readonly _tag: "CompletedWaitForPaint";
+          readonly generation: number;
+        } | {
+          readonly _tag: "EndedAnimation";
+          readonly generation: number;
+        } | {
+          readonly _tag: "Hid";
+        } | {
+          readonly _tag: "Showed";
+        };
+      } | {
+        readonly _tag: "RequestedClose";
+      } | {
+        readonly _tag: "RequestedOpen";
+      } | {
+        readonly _tag: "SucceededAcquireResources";
+      } | {
+        readonly _tag: "SucceededShowDialog";
+      } | {
+        readonly _tag: "Unmounted";
+      };
+    } | {
+      readonly _tag: "PressedActionKey";
+      readonly direction: "Next" | "Previous";
+    };
+  } | {
+    readonly _tag: "PressedArrowKey";
+    readonly key: "ArrowDown" | "ArrowUp";
+    readonly snapshot: {
+      readonly maybeShownPage: Option.Option<string>;
+      readonly shownQuery: string;
+      readonly shownShift: number;
+      readonly rows: readonly {
+        readonly id: string;
+        readonly isHeld: boolean;
+        readonly hasPage: boolean;
+      }[];
+      readonly maybeShownCursor: Option.Option<string>;
+    };
+  } | {
+    readonly _tag: "PressedBackspace";
+    readonly maybeShownPage: Option.Option<string>;
+  } | {
+    readonly _tag: "PressedEarlyArrowKey";
+    readonly key: "ArrowDown" | "ArrowUp";
+  } | {
+    readonly _tag: "PressedEarlyEnter";
+  } | {
+    readonly _tag: "PressedEnter";
+    readonly snapshot: {
+      readonly maybeShownPage: Option.Option<string>;
+      readonly shownQuery: string;
+      readonly shownShift: number;
+      readonly rows: readonly {
+        readonly id: string;
+        readonly isHeld: boolean;
+        readonly hasPage: boolean;
+      }[];
+      readonly maybeShownCursor: Option.Option<string>;
+    };
+  } | {
+    readonly _tag: "UpdatedQuery";
+    readonly value: string;
+    readonly maybeShownPage: Option.Option<string>;
+  }, never>;
+  outMessage?: {
+    readonly _tag: "Closed";
+  } | {
+    readonly _tag: "SelectedChoice";
+    readonly commandId: string;
+    readonly choiceId: string;
+  } | {
+    readonly _tag: "SelectedCommand";
+    readonly id: string;
+  };
+}>;
+/** Opens the palette on the commands, with an empty field and the cursor on the first row.
+ *  Snapshot what the commands act on (the selected item, its title for `scope`) in the
+ *  caller's Model as it opens, and build `commands` from that snapshot until it closes. */
+export declare const open: (model: Model) => Update.Return<Model, Message>;
+/** Configuration for `openAt`. */
+export type OpenAtConfig = Readonly<{
+  /** The command whose page opens, one that has a page. The cursor starts on its `start`,
+   *  else its `current`. */
+  commandId: string;
+}>;
+/** Opens the palette straight on a command's page. Back still leads to the commands. */
+export declare const openAt: (model: Model, config: OpenAtConfig) => Update.Return<Model, Message>;
+/** The caller applied the choice: the palette closes. An answer for a pick that is no longer
+ *  out (the palette was dismissed, its page left, or a newer pick replaced it) changes
+ *  nothing; the caller keeps the write it made. */
+export declare const pickSucceeded: (model: Model, choiceId: string) => Update.Return<Model, Message>;
+/** The caller refused the choice: the page stays with its query, focus and the cursor on that
+ *  choice; say why in the view's `toDetailView`. An answer for a pick that is no longer out
+ *  changes nothing. */
+export declare const pickFailed: (model: Model, choiceId: string) => Update.Return<Model, Message>;
+/** While the palette is open, takes ↑ ↓ and Enter pressed before its field has focus (the
+ *  field's own are the view's), on the window, before the page's own key bindings see them,
+ *  so the keys pressed straight after the one that opened it are not lost. Lift it into the
+ *  application's Subscriptions, once per palette, with a key prefix of the parent's that no
+ *  other record on the page uses: `subscriptions("palette")` is keyed `paletteEarlyKeys`. */
+export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) => {
+  readonly earlyKeys: Subscription.EntryWithoutKeepAlive<{
+    readonly dialog: {
+      readonly dialog: {
+        readonly id: string;
+        readonly isOpen: boolean;
+        readonly isAnimated: boolean;
+        readonly animation: {
+          readonly id: string;
+          readonly isShowing: boolean;
+          readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
+          readonly transitionGeneration: number;
+        };
+        readonly maybeFocusSelector: Option.Option<string>;
+      };
+    };
+    readonly query: string;
+    readonly maybeCursor: Option.Option<string>;
+    readonly cursorShift: number;
+    readonly isEnterPending: boolean;
+    readonly renderGeneration: number;
+    readonly maybePage: Option.Option<{
+      readonly commandId: string;
+      readonly query: string;
+      readonly maybeCursor: Option.Option<string>;
+    }>;
+    readonly maybePicking: Option.Option<string>;
+  }, {
+    readonly _tag: "CompletedFocus";
+  } | {
+    readonly _tag: "CompletedScrollToCursor";
+  } | {
+    readonly _tag: "CompletedReportPendingKeys";
+    readonly renderGeneration: number;
+    readonly maybeRow: Option.Option<{
+      readonly id: string;
+      readonly isHeld: boolean;
+      readonly hasPage: boolean;
+    }>;
+  } | {
+    readonly _tag: "ClickedBack";
+  } | {
+    readonly _tag: "ClickedRow";
+    readonly row: {
+      readonly id: string;
+      readonly isHeld: boolean;
+      readonly hasPage: boolean;
+    };
+    readonly maybeShownPage: Option.Option<string>;
+  } | {
+    readonly _tag: "GotDialogMessage";
+    readonly message: {
+      readonly _tag: "GotDialogMessage";
+      readonly message: {
+        readonly _tag: "CompletedCloseDialog";
+      } | {
+        readonly _tag: "CompletedReleaseDialogResources";
+      } | {
+        readonly _tag: "FailedAcquireResources";
+      } | {
+        readonly _tag: "FailedShowDialog";
+      } | {
+        readonly _tag: "GotAnimationMessage";
+        readonly message: {
+          readonly _tag: "CompletedWaitForPaint";
+          readonly generation: number;
+        } | {
+          readonly _tag: "EndedAnimation";
+          readonly generation: number;
+        } | {
+          readonly _tag: "Hid";
+        } | {
+          readonly _tag: "Showed";
+        };
+      } | {
+        readonly _tag: "RequestedClose";
+      } | {
+        readonly _tag: "RequestedOpen";
+      } | {
+        readonly _tag: "SucceededAcquireResources";
+      } | {
+        readonly _tag: "SucceededShowDialog";
+      } | {
+        readonly _tag: "Unmounted";
+      };
+    } | {
+      readonly _tag: "PressedActionKey";
+      readonly direction: "Next" | "Previous";
+    };
+  } | {
+    readonly _tag: "PressedArrowKey";
+    readonly key: "ArrowDown" | "ArrowUp";
+    readonly snapshot: {
+      readonly maybeShownPage: Option.Option<string>;
+      readonly shownQuery: string;
+      readonly shownShift: number;
+      readonly rows: readonly {
+        readonly id: string;
+        readonly isHeld: boolean;
+        readonly hasPage: boolean;
+      }[];
+      readonly maybeShownCursor: Option.Option<string>;
+    };
+  } | {
+    readonly _tag: "PressedBackspace";
+    readonly maybeShownPage: Option.Option<string>;
+  } | {
+    readonly _tag: "PressedEarlyArrowKey";
+    readonly key: "ArrowDown" | "ArrowUp";
+  } | {
+    readonly _tag: "PressedEarlyEnter";
+  } | {
+    readonly _tag: "PressedEnter";
+    readonly snapshot: {
+      readonly maybeShownPage: Option.Option<string>;
+      readonly shownQuery: string;
+      readonly shownShift: number;
+      readonly rows: readonly {
+        readonly id: string;
+        readonly isHeld: boolean;
+        readonly hasPage: boolean;
+      }[];
+      readonly maybeShownCursor: Option.Option<string>;
+    };
+  } | {
+    readonly _tag: "UpdatedQuery";
+    readonly value: string;
+    readonly maybeShownPage: Option.Option<string>;
+  }, {
+    readonly maybeOpenId: Option.Option<string>;
+  }, never> & {
+    readonly __subscription: never;
+  };
+} extends (infer T) ? { readonly [Key in keyof T as `${Prefix}${Capitalize<Key>}`]: T[Key]; } : never;
+/** Per-render inputs passed to `view` through `h.submodel`'s `viewInputs`. */
+export type ViewInputs = Readonly<{
+  /** Built from what the caller snapshotted as the palette opened (see `open`). A command
+   *  that leaves while its page is open sends the reader back to the commands. */
+  commands: readonly Command[];
+  /** What the commands act on, kept on every page (the selected item's name). Defaults to
+   *  `"commands"`. */
+  scope?: string;
+  /** What else can be typed, for the placeholder (`"type a command or a title"`). */
+  noun?: string;
+  /** Above the list, on the commands and on every page: the application's own content (a
+   *  sync notice and its retry, why a pick was refused). A function, so its controls send the
+   *  application's Messages. */
+  toDetailView?: () => ReadonlyArray<Html | string>;
+  /** The page's live region and toasts while this is the topmost open dialog, `undefined`
+   *  while it is not (see `Dialog`). */
+  toLiveRegionView?: (() => Html) | undefined;
+}>;
+/** The row the cursor is on as the view shows it with `commands`: the row the reader moved it
+ *  to while that row is listed, else the page's `start` or `current` while the query finds it,
+ *  else the first row the query finds; none when nothing is listed. Compare it before and after
+ *  the caller's commands change to know when the cursor fell to another row (its row left) and
+ *  should be scrolled into view with `ScrollToCursor`; a cursor whose row is still listed keeps
+ *  it, and the list its scroll. */
+export declare const maybeCursorId: (model: Model, commands: readonly Command[]) => Option.Option<string>;
+/**
+ * Type to find a command or a title; one inverted cursor row, moved by ↑ and ↓ only
+ * (stopping at the ends; the pointer shades a row but never moves the cursor); Enter or a
+ * click selects it, and the palette closes first so what the command opens takes focus. A
+ * command with a page opens that page in place: Back, or Backspace in an empty field, returns
+ * to the commands with their query and cursor as they were. The choice in force is tagged
+ * current and cannot be picked; a picked choice holds the page until the caller answers. Once
+ * a query is typed, a polite status says how many rows it finds. Escape closes the whole
+ * palette.
+ *
+ * A pixel-paper Dialog (named "Commands", hung near the top) holding a field built on
+ * `@foldkit/ui`'s Input as an ARIA combobox (`aria-activedescendant` on the cursor's row) over
+ * an always open `role="listbox"` of `role="option"` rows, grouped under their headings.
+ */
+export declare const view: import("foldkit/submodel").View<{
+  readonly dialog: {
+    readonly dialog: {
+      readonly id: string;
+      readonly isOpen: boolean;
+      readonly isAnimated: boolean;
+      readonly animation: {
+        readonly id: string;
+        readonly isShowing: boolean;
+        readonly transitionState: "EnterAnimating" | "EnterStart" | "Idle" | "LeaveAnimating" | "LeaveStart";
+        readonly transitionGeneration: number;
+      };
+      readonly maybeFocusSelector: Option.Option<string>;
+    };
+  };
+  readonly query: string;
+  readonly maybeCursor: Option.Option<string>;
+  readonly cursorShift: number;
+  readonly isEnterPending: boolean;
+  readonly renderGeneration: number;
+  readonly maybePage: Option.Option<{
+    readonly commandId: string;
+    readonly query: string;
+    readonly maybeCursor: Option.Option<string>;
+  }>;
+  readonly maybePicking: Option.Option<string>;
+}, {
+  readonly _tag: "CompletedFocus";
+} | {
+  readonly _tag: "CompletedScrollToCursor";
+} | {
+  readonly _tag: "CompletedReportPendingKeys";
+  readonly renderGeneration: number;
+  readonly maybeRow: Option.Option<{
+    readonly id: string;
+    readonly isHeld: boolean;
+    readonly hasPage: boolean;
+  }>;
+} | {
+  readonly _tag: "ClickedBack";
+} | {
+  readonly _tag: "ClickedRow";
+  readonly row: {
+    readonly id: string;
+    readonly isHeld: boolean;
+    readonly hasPage: boolean;
+  };
+  readonly maybeShownPage: Option.Option<string>;
+} | {
+  readonly _tag: "GotDialogMessage";
+  readonly message: {
+    readonly _tag: "GotDialogMessage";
+    readonly message: {
+      readonly _tag: "CompletedCloseDialog";
+    } | {
+      readonly _tag: "CompletedReleaseDialogResources";
+    } | {
+      readonly _tag: "FailedAcquireResources";
+    } | {
+      readonly _tag: "FailedShowDialog";
+    } | {
+      readonly _tag: "GotAnimationMessage";
+      readonly message: {
+        readonly _tag: "CompletedWaitForPaint";
+        readonly generation: number;
+      } | {
+        readonly _tag: "EndedAnimation";
+        readonly generation: number;
+      } | {
+        readonly _tag: "Hid";
+      } | {
+        readonly _tag: "Showed";
+      };
+    } | {
+      readonly _tag: "RequestedClose";
+    } | {
+      readonly _tag: "RequestedOpen";
+    } | {
+      readonly _tag: "SucceededAcquireResources";
+    } | {
+      readonly _tag: "SucceededShowDialog";
+    } | {
+      readonly _tag: "Unmounted";
+    };
+  } | {
+    readonly _tag: "PressedActionKey";
+    readonly direction: "Next" | "Previous";
+  };
+} | {
+  readonly _tag: "PressedArrowKey";
+  readonly key: "ArrowDown" | "ArrowUp";
+  readonly snapshot: {
+    readonly maybeShownPage: Option.Option<string>;
+    readonly shownQuery: string;
+    readonly shownShift: number;
+    readonly rows: readonly {
+      readonly id: string;
+      readonly isHeld: boolean;
+      readonly hasPage: boolean;
+    }[];
+    readonly maybeShownCursor: Option.Option<string>;
+  };
+} | {
+  readonly _tag: "PressedBackspace";
+  readonly maybeShownPage: Option.Option<string>;
+} | {
+  readonly _tag: "PressedEarlyArrowKey";
+  readonly key: "ArrowDown" | "ArrowUp";
+} | {
+  readonly _tag: "PressedEarlyEnter";
+} | {
+  readonly _tag: "PressedEnter";
+  readonly snapshot: {
+    readonly maybeShownPage: Option.Option<string>;
+    readonly shownQuery: string;
+    readonly shownShift: number;
+    readonly rows: readonly {
+      readonly id: string;
+      readonly isHeld: boolean;
+      readonly hasPage: boolean;
+    }[];
+    readonly maybeShownCursor: Option.Option<string>;
+  };
+} | {
+  readonly _tag: "UpdatedQuery";
+  readonly value: string;
+  readonly maybeShownPage: Option.Option<string>;
+}, Readonly<{
+  /** Built from what the caller snapshotted as the palette opened (see `open`). A command
+   *  that leaves while its page is open sends the reader back to the commands. */
+  commands: readonly Command[];
+  /** What the commands act on, kept on every page (the selected item's name). Defaults to
+   *  `"commands"`. */
+  scope?: string;
+  /** What else can be typed, for the placeholder (`"type a command or a title"`). */
+  noun?: string;
+  /** Above the list, on the commands and on every page: the application's own content (a
+   *  sync notice and its retry, why a pick was refused). A function, so its controls send the
+   *  application's Messages. */
+  toDetailView?: () => ReadonlyArray<Html | string>;
+  /** The page's live region and toasts while this is the topmost open dialog, `undefined`
+   *  while it is not (see `Dialog`). */
+  toLiveRegionView?: (() => Html) | undefined;
+}>>;