@gridkitjs/dom 0.3.3 → 0.5.0

package/dist/index.d.ts

@@ -87,7 +87,8 @@ interface AttachedChecklist {
      * How many items the whole list holds, mounted or not. Starts at 0, so a
      * renderer calls this straight after attaching, and again whenever the
      * list changes — a search narrowing it, say. A focused place past the new
-     * end moves back to the last item.
+     * end moves back to the last item, and so does a move still waiting for
+     * an item past it.
      */
     readonly setCount: (count: number) => void;
     /**
@@ -95,7 +96,11 @@ interface AttachedChecklist {
      * An item outside the mounted window is focused once it mounts.
      */
     readonly focusItem: (index: number) => void;
-    /** Removes every listener and observer. The items keep their `tabindex`. */
+    /**
+     * Removes every listener and observer. The items keep their `tabindex`.
+     * After it, `setCount` and `focusItem` do nothing: they neither scroll
+     * nor focus, and a move still waiting for its item is dropped.
+     */
     readonly detach: () => void;
 }
 /**
@@ -190,20 +195,31 @@ interface ColumnResizeGestureHandlers {
     /** Every pointer move, with the width the column takes there. */
     readonly onMove: (width: number) => void;
     /**
-     * The pointer was released. `width` is the width to commit, or `null` when
-     * it ended where it started: a click on the handle — as each half of a
-     * double-click is — is not a resize, and reporting one would fire a
-     * spurious resize on every click.
+     * The pointer was released. `width` is the width to commit, even when a
+     * drag brought it back to where it started, or `null` when the width never
+     * changed: a click on the handle — as each half of a double-click is — is
+     * not a resize, and reporting one would fire a spurious resize on every
+     * click.
      */
     readonly onEnd: (width: number | null) => void;
-    /** Escape, or a cancelled pointer: the column goes back to `session.startWidth`. */
+    /**
+     * Escape, a cancelled pointer or an aborted `signal`: the column goes back
+     * to `session.startWidth`.
+     */
     readonly onCancel: () => void;
+    /**
+     * Cancels the resize when aborted, as Escape does. For a renderer whose
+     * handle goes away mid-drag, so what it draws for the resize ends with it.
+     * Already aborted, no resize starts.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * Drags a column's edge from `press` on its resize `handle`, turning pointer
  * positions into widths through `@gridkitjs/core`'s `session` — begun with
  * `beginColumnResize` — and reporting them. Returns whether a resize began:
- * only the primary button of the primary pointer starts one.
+ * only the primary button of the primary pointer starts one, and not once
+ * `handlers.signal` has aborted.
  *
  * Captures the pointer on `handle`, so the drag keeps reporting wherever the
  * pointer goes, and prevents the press's default, so it does not select the
@@ -265,15 +281,22 @@ declare function writeClipboard(content: ClipboardContent): Promise<void>;
  */
 declare function downloadBlob(blob: Blob, fileName: string): void;
 
-/** What a renderer draws while a reorder drag is open. */
-interface DragReorderState<Target> {
-    /** The item being dragged, once the press has become a drag. */
-    readonly draggedId: string | null;
+/**
+ * What a renderer draws for a reorder gesture: nothing while `idle`, which
+ * covers a press still short of the drag threshold, then while `dragging` the
+ * dragged item, where it would land and the ghost trailing the pointer.
+ */
+type DragReorderState<Target> = {
+    readonly kind: "idle";
+} | {
+    readonly kind: "dragging";
+    /** The item being dragged. */
+    readonly draggedId: string;
     /** Where it would land if released now, `null` for nowhere valid. */
     readonly dropTarget: Target | null;
     /** Where the element trailing the pointer sits, as a CSS `transform`. */
-    readonly ghostTransform: string | null;
-}
+    readonly ghostTransform: string;
+};
 /** The state while nothing is dragged — the one a drag reports when it ends. */
 declare const NO_DRAG: DragReorderState<never>;
 interface DragReorderHandlers<Target> {
@@ -289,18 +312,25 @@ interface DragReorderHandlers<Target> {
     readonly onState: (state: DragReorderState<Target>) => void;
     /** The pointer was released over a valid target. */
     readonly onDrop: (target: Target, id: string) => void;
+    /**
+     * Cancels the drag when aborted, as Escape does: `onState(NO_DRAG)`, no
+     * drop. For a renderer whose dragged element goes away mid-drag, so what
+     * it draws for the drag ends with it. Already aborted, no drag starts.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * The pointer mechanics behind every drag-to-reorder gesture in the grid — a
  * column header dragged among the others or into the group-by bar, a
  * group-by chip dragged within it: capture, the drag threshold, and the ghost
  * trailing the pointer, holding the spot it was picked up by. Returns whether
- * a gesture began; only the main button of the primary pointer starts one.
+ * a gesture began; only the main button of the primary pointer starts one,
+ * and not once `handlers.signal` has aborted.
  *
  * The press is left to its default, so the pressed element still takes focus;
  * until the pointer has travelled `DRAG_THRESHOLD` pixels nothing is
- * reported, so a press that never moves stays a click. Escape, or a cancelled
- * pointer, leaves the order as it was.
+ * reported, so a press that never moves stays a click. Escape, a cancelled
+ * pointer or an aborted signal leaves the order as it was.
  *
  * Pointer events rather than HTML5 drag-and-drop: `dragenter`/`dragleave`
  * fire per descendant, so a dragged item's own inner markup would each report
@@ -416,7 +446,7 @@ interface GridFocusController {
      * focused does nothing, which is what lets a cell's own `focus` event
      * report a click through here without a loop.
      */
-    readonly focusCell: (rowIndex: number, columnIndex: number) => void;
+    readonly focusCell: (focus: GridFocus) => void;
     /**
      * Moves the tab stop as `key` does — the arrows, Home, End, the page keys,
      * with Ctrl for the grid's corners. Returns whether the key was one of
@@ -428,8 +458,13 @@ interface GridFocusController {
     /**
      * Connects the tab stop to the rendered rows, which the browser's focus
      * then follows it among. Returns the function that disconnects them.
+     *
+     * `root`, the element holding every row, lets the user take over from a
+     * move still waiting for its row to be drawn: focus leaving `root`, or a
+     * wheel or a press inside it, drops the move, so a row mounting later
+     * neither scrolls back to itself nor pulls focus back into the grid.
      */
-    readonly attach: (rows: GridFocusRows) => () => void;
+    readonly attach: (rows: GridFocusRows, root?: HTMLElement | null) => () => void;
     /**
      * Called by the renderer once it has drawn `drawn` — a value `getFocus`
      * returned — so the browser's focus follows a move to the cell now in the
@@ -481,8 +516,10 @@ interface InfiniteScrollOptions {
     readonly hasMore: boolean;
     /**
      * Called at most once per approach: when the sentinel comes within
-     * `rootMargin` of the root's visible area, and not again until
-     * `isLoadingMore` has gone from `true` back to `false`.
+     * `rootMargin` of the root's visible area. Not again until that load has
+     * finished (`isLoadingMore` back to `false`), `hasMore` has changed, rows
+     * have been added or removed in front of the sentinel, or the sentinel has
+     * left `rootMargin` and come back.
      */
     readonly onLoadMore?: (() => void) | undefined;
     /** Whether a load `onLoadMore` started is still in flight. */
@@ -494,24 +531,26 @@ interface InfiniteScroll {
     /**
      * Takes the current options. Cheap when nothing changed, so a renderer may
      * call it after every render; a new sentinel or `rootMargin` restarts the
-     * observer, and `isLoadingMore` going back to `false` re-checks at once.
+     * observer, and a load finishing or `hasMore` changing re-checks at once.
+     * While a load it asked for has not reported `isLoadingMore`, it measures
+     * where the sentinel sits, to tell whether rows answered it.
      */
     readonly update: (options: InfiniteScrollOptions) => void;
-    /** Stops watching for good. */
+    /** Stops watching for good: a later `update` does nothing. */
     readonly detach: () => void;
 }
 /**
  * Turns a sentinel's approach to the bottom of the scrolling `root` into
- * `onLoadMore` calls, no more than one per "the sentinel is near and no load
- * is in flight since the last one finished".
+ * `onLoadMore` calls, no more than one per approach while no load is in
+ * flight.
  *
- * Three facts drive it: whether the sentinel is intersecting (as of the
- * observer's last report), whether `onLoadMore` has fired since the last
- * load finished, and whether a load was in flight at the last update. They
- * outlive the sentinel itself, which a renderer mounts and unmounts as
- * `hasMore` changes, so they live here rather than on any one observer.
+ * Two facts drive it: whether the sentinel is intersecting (as of the
+ * observer's last report), and the `LoadState`. Both outlive the sentinel
+ * itself, which a renderer mounts and unmounts as `hasMore` changes, so they
+ * live here rather than on any one observer.
  *
- * Off means off: with `hasMore` false, or no sentinel, no observer exists.
+ * Off means off: with `hasMore` false, no sentinel, or once detached, no
+ * observer exists.
  */
 declare function attachInfiniteScroll(root: Element, options: InfiniteScrollOptions): InfiniteScroll;
 
@@ -676,9 +715,19 @@ interface OverlayOptions extends OverlayPlacementOptions {
     readonly initialFocus?: OverlayInitialFocus | undefined;
     /**
      * Where focus goes when the overlay detaches. Defaults to the element that
-     * had focus when it attached; `null` leaves focus alone.
+     * had focus when it attached; `null` leaves focus alone, unless
+     * `returnFocusFallback` names somewhere.
      */
     readonly returnFocusTo?: HTMLElement | null | undefined;
+    /**
+     * Where focus goes when there is nothing to return it to as the overlay
+     * detaches: `returnFocusTo` is `null`, or has left the page — the button a
+     * menu opened from, taken away by what the menu ran. Called then, so it
+     * can name what is on the page by that time; returning `null` leaves focus
+     * alone. Like the return itself, it applies only while focus is still in
+     * the panel, in an overlay above it, or nowhere.
+     */
+    readonly returnFocusFallback?: (() => HTMLElement | null) | undefined;
     /**
      * Whether a scroll outside the panel just after input inside it — an
      * `input` or `change` event, in the two animation frames that follow it —
@@ -728,6 +777,8 @@ interface OverlayOptions extends OverlayPlacementOptions {
  * Detaching removes every listener and returns focus, but only when focus is
  * still in the panel, in an overlay above it, or nowhere — a click that
  * dismissed it by landing on another control leaves focus on that control.
+ * Focus goes to `returnFocusFallback` instead when the element it would
+ * return to has left the page.
  * Any overlay still above it is dismissed with `"parent"` and detached first.
  */
 declare function attachOverlay(anchor: OverlayAnchor, panel: HTMLElement, options: OverlayOptions): () => void;
@@ -747,7 +798,11 @@ interface RowVirtualizerOptions {
 interface RowVirtualizer {
     /** How many rows there are. Measured heights of the rows that remain are kept. */
     readonly setRowCount: (count: number) => void;
-    /** Forgets every measured height, for rows that are no longer the ones measured. */
+    /**
+     * Forgets every measured height, for rows that are no longer the ones
+     * measured. A `scrollToIndex` still waiting for its row is dropped too:
+     * the row it asked for is no longer at that index.
+     */
     readonly resetHeights: () => void;
     /**
      * A ref callback for the element of row `index` (its place among all the
@@ -759,10 +814,15 @@ interface RowVirtualizer {
     /**
      * Scrolls so row `index` is in view. A mounted row is scrolled to directly;
      * one outside the window is jumped to at its estimated offset, then
-     * scrolled to properly once it mounts and can be measured.
+     * scrolled to properly once it mounts and can be measured. A later call
+     * replaces one still waiting for its row; a row count that no longer holds
+     * that row, or `resetHeights`, drops it.
      */
     readonly scrollToIndex: (index: number, options?: ScrollIntoViewOptions) => void;
-    /** Stops listening and measuring, for good. */
+    /**
+     * Stops listening, measuring and scrolling, for good: every method does
+     * nothing after it.
+     */
     readonly destroy: () => void;
 }
 /**
@@ -871,13 +931,14 @@ interface PrintDocumentOptions {
  * Prints a document through a hidden frame: its own page, holding only
  * `bodyHtml` under `styles`, so what is printed is what was built — every
  * row, not the slice of them a virtualised grid has drawn — and nothing of
- * the page around it. The frame loads, waits for its fonts, opens the
- * print dialog, and is removed once the dialog closes, when the promise
+ * the page around it. The frame loads, waits for its fonts (a few seconds
+ * at most), opens the print dialog, and is removed once the dialog closes, when the promise
  * resolves; focus goes back where it was. A frame rather than a new window,
  * which a popup blocker would stop.
  *
  * One print at a time: a call while a print is open resolves at once
- * without printing.
+ * without printing. Rejects, with the frame removed, if the frame is taken
+ * out of the page before it loads or the dialog fails to open.
  */
 declare function printDocument(options: PrintDocumentOptions): Promise<void>;