@gridkitjs/dom 0.3.3 → 0.4.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;
     /**
@@ -196,14 +197,24 @@ interface ColumnResizeGestureHandlers {
      * 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
@@ -289,18 +300,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
@@ -428,8 +446,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 +504,9 @@ 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, or
+     * the sentinel has left `rootMargin` and come back.
      */
     readonly onLoadMore?: (() => void) | undefined;
     /** Whether a load `onLoadMore` started is still in flight. */
@@ -494,24 +518,24 @@ 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.
      */
     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 +700,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 +762,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;
@@ -759,10 +795,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, and so does a row count that no
+     * longer holds that row.
      */
     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;
 }
 /**
@@ -877,7 +918,8 @@ interface PrintDocumentOptions {
  * 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>;