@gjermundgaraba/pixel-paper 0.0.0-stage → 0.1.1

package/dist/rail/rail.d.ts

@@ -0,0 +1,403 @@
+import { KeyHintConfig } from "../button/button.js";
+import { Effect, Option, Schema } from "effect";
+import * as Command from "foldkit/command";
+import { Html } from "foldkit/html";
+import * as Mount from "foldkit/mount";
+import * as Subscription from "foldkit/subscription";
+import * as Update from "foldkit/update";
+/** Schema for a rail: whether it is open as a drawer (at 900px and under; wider, it is always
+ *  in the page and this stays false), and its splitter while a pointer drags it. Its width,
+ *  and whether the reader hid it, are the parent's. */
+export declare const Model: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly isOpen: Schema.Boolean;
+  readonly maybeResizing: Schema.Option<Schema.Struct<{
+    readonly pointerId: Schema.Finite;
+    readonly pressX: Schema.Finite;
+    readonly fromWidth: Schema.Finite;
+    readonly width: Schema.Finite;
+  }>>;
+}>;
+export type Model = typeof Model.Type;
+/** Union of all Messages a rail can produce. `ClosedDrawer` is the browser closing it on
+ *  Escape or a press on the veil; `BlurredDrawer` is focus leaving it; `WidenedPastDrawer` is
+ *  the window growing past 900px while it is open, where the rail is back in the page. */
+export declare const Message: import("foldkit/message").MessageUnion<{
+  readonly ClickedOpen: {};
+  readonly ClickedToggle: {};
+  readonly PressedSplitter: {
+    pointerId: Schema.Finite;
+    clientX: Schema.Finite;
+    width: Schema.Finite;
+  };
+  readonly MovedSplitter: {
+    clientX: Schema.Finite;
+  };
+  readonly ReleasedSplitter: {
+    clientX: Schema.Finite;
+  };
+  readonly CancelledSplitter: {};
+  readonly PressedEscape: {};
+  readonly PressedSplitterKey: {
+    width: Schema.Finite;
+  };
+  readonly ClickedClose: {};
+  readonly ClosedDrawer: {};
+  readonly BlurredDrawer: {};
+  readonly WidenedPastDrawer: {};
+  readonly CompletedShowRailDrawer: {};
+  readonly CompletedHideRailDrawer: {};
+  readonly CompletedFocusRailToggle: {};
+}>;
+export type Message = typeof Message.Type;
+/** What a rail asks of its parent. `ResizedRail`: its splitter was let go, or stepped by a
+ *  key, at `width` pixels, within the rail's bounds; the parent keeps it (per client) and
+ *  passes it back as the view's `maybeWidth`. `ToggledRail`: its toggle was pressed; the
+ *  parent flips whether it keeps the rail hidden (per client) and passes it back as the view's
+ *  `isHidden`. */
+export declare const OutMessage: import("foldkit/message").MessageUnion<{
+  readonly ResizedRail: {
+    width: Schema.Finite;
+  };
+  readonly ToggledRail: {};
+}>;
+export type OutMessage = typeof OutMessage.Type;
+/** Configuration for creating a rail with `init`. The `id` is the rail's, unique in the
+ *  document. */
+export type InitConfig = Readonly<{
+  id: string;
+}>;
+/** Creates a rail, closed, its splitter at rest. */
+export declare const init: (config: InitConfig) => Model;
+/** The rail's id, unique in the document. */
+export declare const id: (model: Model) => string;
+/** Whether the rail is open as a drawer: a parent pauses its own page keys while it is. */
+export declare const isOpen: (model: Model) => boolean;
+/** Opens the rail as a drawer over the page and puts focus on its first control past its
+ *  head. */
+export declare const ShowRailDrawer: Command.CommandDefinitionWithArgs<"ShowRailDrawer", {
+  railId: Schema.String;
+}, Effect.Effect<{
+  readonly _tag: "CompletedShowRailDrawer";
+}, never, never>>;
+/** Closes the drawer, and puts focus back on the button that opened it when asked. */
+export declare const HideRailDrawer: Command.CommandDefinitionWithArgs<"HideRailDrawer", {
+  railId: Schema.String;
+  buttonId: Schema.String;
+  isReturningFocus: Schema.Boolean;
+}, Effect.Effect<{
+  readonly _tag: "CompletedHideRailDrawer";
+}, never, never>>;
+/** Puts focus on the rail's toggle once the rail has folded or unfolded, if focus was in the
+ *  rail or on its splitter: folding takes away every control in it but the toggle, which
+ *  brings it back, and the splitter with them. Focus anywhere else stays where it is. */
+export declare const FocusRailToggle: Command.CommandDefinitionWithArgs<"FocusRailToggle", {
+  railId: Schema.String;
+  toggleId: Schema.String;
+}, Effect.Effect<{
+  readonly _tag: "CompletedFocusRailToggle";
+}, never, never>>;
+type UpdateReturn = Update.Return<Model, Message>;
+/** Closes the rail's drawer, focus back on its button. */
+export declare const close: (model: Model) => UpdateReturn;
+/** Folds or unfolds the rail from a key of the parent's: the parent flips whether it keeps the
+ *  rail hidden, as it does for `ToggledRail`, and folds this in, which moves focus in the rail
+ *  onto the toggle. */
+export declare const toggle: (model: Model) => UpdateReturn;
+/** Processes a rail Message and returns the next Model, Commands and OutMessage: a splitter let
+ *  go where it changes the width, or stepped by a key, asks for the width, and the toggle asks
+ *  to fold or unfold the rail. */
+export declare const update: (model: Model, message: Message) => Readonly<{
+  model: {
+    readonly id: string;
+    readonly isOpen: boolean;
+    readonly maybeResizing: Option.Option<{
+      readonly pointerId: number;
+      readonly pressX: number;
+      readonly fromWidth: number;
+      readonly width: number;
+    }>;
+  };
+  commands?: Update.Commands<{
+    readonly _tag: "CompletedShowRailDrawer";
+  } | {
+    readonly _tag: "CompletedHideRailDrawer";
+  } | {
+    readonly _tag: "CompletedFocusRailToggle";
+  } | {
+    readonly _tag: "BlurredDrawer";
+  } | {
+    readonly _tag: "CancelledSplitter";
+  } | {
+    readonly _tag: "ClickedClose";
+  } | {
+    readonly _tag: "ClickedOpen";
+  } | {
+    readonly _tag: "ClickedToggle";
+  } | {
+    readonly _tag: "ClosedDrawer";
+  } | {
+    readonly _tag: "MovedSplitter";
+    readonly clientX: number;
+  } | {
+    readonly _tag: "PressedEscape";
+  } | {
+    readonly _tag: "PressedSplitter";
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly width: number;
+  } | {
+    readonly _tag: "PressedSplitterKey";
+    readonly width: number;
+  } | {
+    readonly _tag: "ReleasedSplitter";
+    readonly clientX: number;
+  } | {
+    readonly _tag: "WidenedPastDrawer";
+  }, never>;
+  outMessage?: {
+    readonly _tag: "ResizedRail";
+    readonly width: number;
+  } | {
+    readonly _tag: "ToggledRail";
+  };
+}>;
+/** Follows the drawer the browser shows: the browser closing it (Escape, a press on the
+ *  veil), focus leaving it while it is open, and the window growing past its width while it
+ *  is open, each of which closes the rail. */
+export declare const FollowRailDrawer: Mount.MountDefinitionNoArgs<"FollowRailDrawer", {
+  readonly _tag: "BlurredDrawer";
+} | {
+  readonly _tag: "ClosedDrawer";
+} | {
+  readonly _tag: "WidenedPastDrawer";
+}>;
+/** A dragged splitter follows the pointer, and Escape puts it back before a dialog or the
+ *  page sees it, from listeners that run only while it is dragged. Lift them into the
+ *  application's Subscriptions behind a key prefix of the parent's: `subscriptions("rail")` is
+ *  keyed `railResize` and `railEscape`. */
+export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) => {
+  readonly resize: Subscription.EntryWithoutKeepAlive<{
+    readonly id: string;
+    readonly isOpen: boolean;
+    readonly maybeResizing: Option.Option<{
+      readonly pointerId: number;
+      readonly pressX: number;
+      readonly fromWidth: number;
+      readonly width: number;
+    }>;
+  }, {
+    readonly _tag: "CompletedShowRailDrawer";
+  } | {
+    readonly _tag: "CompletedHideRailDrawer";
+  } | {
+    readonly _tag: "CompletedFocusRailToggle";
+  } | {
+    readonly _tag: "BlurredDrawer";
+  } | {
+    readonly _tag: "CancelledSplitter";
+  } | {
+    readonly _tag: "ClickedClose";
+  } | {
+    readonly _tag: "ClickedOpen";
+  } | {
+    readonly _tag: "ClickedToggle";
+  } | {
+    readonly _tag: "ClosedDrawer";
+  } | {
+    readonly _tag: "MovedSplitter";
+    readonly clientX: number;
+  } | {
+    readonly _tag: "PressedEscape";
+  } | {
+    readonly _tag: "PressedSplitter";
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly width: number;
+  } | {
+    readonly _tag: "PressedSplitterKey";
+    readonly width: number;
+  } | {
+    readonly _tag: "ReleasedSplitter";
+    readonly clientX: number;
+  } | {
+    readonly _tag: "WidenedPastDrawer";
+  }, {
+    readonly maybePointerId: Option.Option<number>;
+  }, never> & {
+    readonly __subscription: never;
+  };
+  readonly escape: Subscription.EntryWithoutKeepAlive<{
+    readonly id: string;
+    readonly isOpen: boolean;
+    readonly maybeResizing: Option.Option<{
+      readonly pointerId: number;
+      readonly pressX: number;
+      readonly fromWidth: number;
+      readonly width: number;
+    }>;
+  }, {
+    readonly _tag: "CompletedShowRailDrawer";
+  } | {
+    readonly _tag: "CompletedHideRailDrawer";
+  } | {
+    readonly _tag: "CompletedFocusRailToggle";
+  } | {
+    readonly _tag: "BlurredDrawer";
+  } | {
+    readonly _tag: "CancelledSplitter";
+  } | {
+    readonly _tag: "ClickedClose";
+  } | {
+    readonly _tag: "ClickedOpen";
+  } | {
+    readonly _tag: "ClickedToggle";
+  } | {
+    readonly _tag: "ClosedDrawer";
+  } | {
+    readonly _tag: "MovedSplitter";
+    readonly clientX: number;
+  } | {
+    readonly _tag: "PressedEscape";
+  } | {
+    readonly _tag: "PressedSplitter";
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly width: number;
+  } | {
+    readonly _tag: "PressedSplitterKey";
+    readonly width: number;
+  } | {
+    readonly _tag: "ReleasedSplitter";
+    readonly clientX: number;
+  } | {
+    readonly _tag: "WidenedPastDrawer";
+  }, {
+    readonly isResizing: boolean;
+  }, 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<{
+  /** Names the rail for screen readers, and its button, drawer head and splitter
+   *  (`"collections"`). */
+  label: string;
+  /** The width the reader gave the rail, in pixels, as the parent keeps it from `ResizedRail`
+   *  (for this client: another reader's window is not this one's); none for the stylesheet's.
+   *  A width out of the rail's bounds prints at the nearer bound. */
+  maybeWidth: Option.Option<number>;
+  /** Whether the reader folded the rail to its first panel's title bar, as the parent keeps it
+   *  from `ToggledRail` (for this client, as it keeps the width). The drawer ignores it. */
+  isHidden: boolean;
+  /** The parent's key for the toggle, which its tip prints after its label; the parent binds
+   *  it to `toggle`. */
+  maybeToggleKeyHint: Option.Option<KeyHintConfig>;
+  /** The rail's panels: a tree, places, filters, given the toggle that folds the rail to put in
+   *  its first panel's `lead`. A function because a Submodel's viewInputs may hold functions
+   *  only at the top level, and Foldkit runs this one in the parent's boundary, so the
+   *  handlers in what it returns dispatch the parent's Messages. */
+  toAsideView: (toggle: Html) => readonly Html[];
+  /** The page beside the rail, `main.deck#main` or `main.bench#main`, given the button that
+   *  opens the drawer to print first in it. A function because it receives that button, and
+   *  runs in the parent's boundary like `toAsideView`. */
+  toDeckView: (openButton: Html) => Html;
+}>;
+/**
+ * A column of panels beside the deck, fixed under the top bar: `div.railed >` the deck, then
+ * `aside.rail[popover="auto"][aria-label]`, then its splitter, `div.rail-resize[role="separator"]`,
+ * on its right edge. What comes before its last panel keeps its height, and the last panel
+ * shrinks to the room left, its bar and foot staying while its body scrolls. One element
+ * serves both layouts, so nothing in it renders twice or loses its state. At 900px and under it leaves the page, and
+ * `span.rail-open > button.btn.small` at the top of the deck opens the same element as a drawer
+ * over a veil, its head (the name and a close glyph) showing. Opening focuses its first
+ * control; Escape, a press on the veil, the close glyph, focus leaving or the window growing
+ * past 900px closes it, and the first three put focus back on the button.
+ *
+ * Its splitter sizes it, by a pointer (previewed as it moves) or the side arrows, within its
+ * bounds, and reports the width as `ResizedRail` for the parent to keep and pass back as
+ * `maybeWidth`, which the view sets as `--railed-width` on `div.railed`, so the page's padding
+ * and the rail's width follow it (without one, `--rail`). The drawer keeps its own width. Lift
+ * `subscriptions(keyPrefix)` into the application's, or a dragged splitter follows nothing.
+ *
+ * Its toggle, `span.rail-toggle > button.iconbtn.quiet[aria-expanded]` ("Hide <label>"), comes
+ * to `toAsideView` to print as the first panel's `lead`. Pressed, it reports `ToggledRail` for
+ * the parent to keep and pass back as `isHidden`: `div.railed.folded` then stands the first
+ * panel's title bar on end on the ground (the toggle at its top, "Show <label>"), the rest of
+ * the rail and its splitter gone, and the deck takes the width. Focus in the rail lands on the
+ * toggle. The drawer, at 900px and under, prints neither the toggle nor the fold.
+ *
+ * Its state is its own, not `@foldkit/ui`'s Popover: that panel is placed by Floating UI and
+ * rendered only while open, and this one is always in the page, placed by the stylesheet, and
+ * opened as a native popover so the browser keeps it in the top layer.
+ */
+export declare const view: import("foldkit/submodel").View<{
+  readonly id: string;
+  readonly isOpen: boolean;
+  readonly maybeResizing: Option.Option<{
+    readonly pointerId: number;
+    readonly pressX: number;
+    readonly fromWidth: number;
+    readonly width: number;
+  }>;
+}, {
+  readonly _tag: "CompletedShowRailDrawer";
+} | {
+  readonly _tag: "CompletedHideRailDrawer";
+} | {
+  readonly _tag: "CompletedFocusRailToggle";
+} | {
+  readonly _tag: "BlurredDrawer";
+} | {
+  readonly _tag: "CancelledSplitter";
+} | {
+  readonly _tag: "ClickedClose";
+} | {
+  readonly _tag: "ClickedOpen";
+} | {
+  readonly _tag: "ClickedToggle";
+} | {
+  readonly _tag: "ClosedDrawer";
+} | {
+  readonly _tag: "MovedSplitter";
+  readonly clientX: number;
+} | {
+  readonly _tag: "PressedEscape";
+} | {
+  readonly _tag: "PressedSplitter";
+  readonly pointerId: number;
+  readonly clientX: number;
+  readonly width: number;
+} | {
+  readonly _tag: "PressedSplitterKey";
+  readonly width: number;
+} | {
+  readonly _tag: "ReleasedSplitter";
+  readonly clientX: number;
+} | {
+  readonly _tag: "WidenedPastDrawer";
+}, Readonly<{
+  /** Names the rail for screen readers, and its button, drawer head and splitter
+   *  (`"collections"`). */
+  label: string;
+  /** The width the reader gave the rail, in pixels, as the parent keeps it from `ResizedRail`
+   *  (for this client: another reader's window is not this one's); none for the stylesheet's.
+   *  A width out of the rail's bounds prints at the nearer bound. */
+  maybeWidth: Option.Option<number>;
+  /** Whether the reader folded the rail to its first panel's title bar, as the parent keeps it
+   *  from `ToggledRail` (for this client, as it keeps the width). The drawer ignores it. */
+  isHidden: boolean;
+  /** The parent's key for the toggle, which its tip prints after its label; the parent binds
+   *  it to `toggle`. */
+  maybeToggleKeyHint: Option.Option<KeyHintConfig>;
+  /** The rail's panels: a tree, places, filters, given the toggle that folds the rail to put in
+   *  its first panel's `lead`. A function because a Submodel's viewInputs may hold functions
+   *  only at the top level, and Foldkit runs this one in the parent's boundary, so the
+   *  handlers in what it returns dispatch the parent's Messages. */
+  toAsideView: (toggle: Html) => readonly Html[];
+  /** The page beside the rail, `main.deck#main` or `main.bench#main`, given the button that
+   *  opens the drawer to print first in it. A function because it receives that button, and
+   *  runs in the parent's boundary like `toAsideView`. */
+  toDeckView: (openButton: Html) => Html;
+}>>;
+export {};