@gridkitjs/dom 0.1.0 → 0.2.0

package/README.md

@@ -2,8 +2,8 @@
 
 The browser behaviours a GridKit renderer needs, as framework-free
 TypeScript: pointer gestures, keyboard focus movement, the observers behind
-fit-to-width and infinite scroll, the row virtualizer's measuring, overlays,
-and a live-region announcer. Built on
+fit-to-width and infinite scroll, the row virtualizer's measuring, overlays
+and the menus shown in them, and a live-region announcer. Built on
 [`@gridkitjs/core`](https://www.npmjs.com/package/@gridkitjs/core) and used by
 [`@gridkitjs/react`](https://www.npmjs.com/package/@gridkitjs/react).
 
@@ -47,6 +47,8 @@ announcer.destroy();
 | `createGridFocus`          | Keeps the grid's single tab stop and moves the browser's focus with the keys. |
 | `bodyCellFrom` and others  | Resolve a delegated body event to the cell, row or group header it addresses. |
 | `attachOverlay`            | Positions a panel beside an anchor or point, and reports when to dismiss it.  |
+| `attachMenu`               | Moves a menu's focus by key, typeahead and pointer, and reports choices.      |
+| `attachContextMenuTrigger` | Reports a right-click, Shift+F10 or the ContextMenu key, once per gesture.    |
 
 Full documentation: [github.com/blagojablazhevski/gridkit](https://github.com/blagojablazhevski/gridkit#readme)
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ColumnResizeSession, ColumnOrderState, GroupByState, GridFocus, NavigationModifiers, VisibleRange } from '@gridkitjs/core';
+import { ColumnResizeSession, ColumnOrderState, GroupByState, GridFocus, NavigationModifiers, VisibleRange, ResolvedToolbarItem } from '@gridkitjs/core';
 
 /** A live region to report changes through. */
 interface LiveAnnouncer {
@@ -65,6 +65,54 @@ declare function groupRowFrom(target: EventTarget | null): GroupRowTarget | null
  */
 declare function bodyRowFrom(target: EventTarget | null): BodyRowTarget | null;
 
+/**
+ * How a context menu was asked for: by a pointer — a right-click, or a touch
+ * held still — or by the keyboard.
+ */
+type ContextMenuSource = "pointer" | "keyboard";
+/** A context menu asked for inside the root, as `onRequest` hears of it. */
+interface ContextMenuRequest {
+    /** The element it was asked for on: the one under the pointer, or the one focused for a key. */
+    readonly target: Element;
+    /**
+     * Where the pointer was, in viewport coordinates — where a menu opened by
+     * it goes. `null` from the keyboard, which has no point: a menu it opens
+     * goes beside the focused element instead.
+     */
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+    } | null;
+    readonly source: ContextMenuSource;
+}
+interface ContextMenuTriggerOptions {
+    /**
+     * A context menu was asked for inside the root. Returns whether the caller
+     * opened one of its own: if so the browser's menu is prevented, and if not
+     * it shows as it would have.
+     */
+    readonly onRequest: (request: ContextMenuRequest) => boolean;
+}
+/**
+ * Reports every context menu the user asks for inside `root` — a right-click,
+ * Shift+F10, the ContextMenu key, or a touch held still for half a second —
+ * through `onRequest`, and returns the function that stops it.
+ *
+ * Each gesture asks once. Pressing a key, or holding a touch, also makes some
+ * browsers fire `contextmenu` of their own, and that event is taken, not
+ * reported again, once the gesture opened a menu. The click a touch brings
+ * as it lifts is taken too: the menu opened under the finger, and the click
+ * would land in it.
+ *
+ * An event something already prevented is left alone, so a cell template
+ * that shows a menu of its own keeps it. That is why the listeners are on the
+ * document, in the bubble phase: a framework that handles events at its own
+ * root container — React does — hears them before the document does, where
+ * a listener on `root` itself would hear them first. Only events whose target
+ * is inside `root` count.
+ */
+declare function attachContextMenuTrigger(root: Element, options: ContextMenuTriggerOptions): () => void;
+
 /**
  * The `pointerdown` a gesture starts from. A native `PointerEvent` is one,
  * and so is a framework's wrapper around it, such as React's synthetic
@@ -370,6 +418,80 @@ interface InfiniteScroll {
  */
 declare function attachInfiniteScroll(root: Element, options: InfiniteScrollOptions): InfiniteScroll;
 
+/**
+ * Where focus goes when a submenu opens: its first item, or nowhere — it
+ * stays on the item that opened it, as when the pointer opened it.
+ */
+type MenuSubmenuFocus = "first" | "none";
+/** Why a menu asked for every menu to close. */
+type MenuCloseReason = "tab";
+interface MenuOptions {
+    /**
+     * An enabled item that opens no submenu was chosen — Enter, Space or a
+     * click. The caller runs it, and closes every menu.
+     */
+    readonly onActivate: (id: string) => void;
+    /**
+     * An enabled submenu item asks for its submenu: Enter, Space or ArrowRight
+     * on it want its first item focused (`"first"`), a click or the pointer
+     * resting on it want focus left where it is (`"none"`). It may come for a
+     * submenu already open — ArrowRight on one the pointer opened — when a
+     * `"first"` asks for focus to move into it (`focusItem(0)` on its menu).
+     * Opening it closes any other submenu open from this menu.
+     */
+    readonly onOpenSubmenu?: ((id: string, options: {
+        readonly focus: MenuSubmenuFocus;
+    }) => void) | undefined;
+    /**
+     * The pointer came to rest on an item that opens no submenu, or a disabled
+     * one: close whatever submenu is open from this menu, if any. Moving on to
+     * another item is how a pointer user leaves a submenu they did not want.
+     */
+    readonly onCollapseSubmenu?: (() => void) | undefined;
+    /**
+     * ArrowLeft was pressed in this menu, which is a submenu: close it, and
+     * focus goes back to the item that opened it. Passed only for a submenu —
+     * in a menu without it, ArrowLeft does nothing.
+     */
+    readonly onCloseSubmenu?: (() => void) | undefined;
+    /**
+     * Tab or Shift+Tab was pressed: close every menu, so focus returns to where
+     * the first one was opened from rather than moving on past it.
+     */
+    readonly onClose: (reason: MenuCloseReason) => void;
+}
+interface AttachedMenu {
+    /**
+     * Focuses an item, by its `data-gridkit-menu-item` id or its place among
+     * the items. Does nothing for an item the menu does not have.
+     */
+    readonly focusItem: (item: string | number) => void;
+    /** Removes every listener. The items keep the `tabindex` they had. */
+    readonly detach: () => void;
+}
+/**
+ * Makes `panel` — a `role="menu"` element the renderer drew — behave as a
+ * menu: the arrow keys, Home, End and typeahead move focus among its items,
+ * Enter, Space and a click choose one, ArrowRight and ArrowLeft open and
+ * close submenus, and the pointer moves focus to the item under it. It
+ * decides; the caller is told through the callbacks and draws the outcome —
+ * runs the item, opens or closes a submenu.
+ *
+ * Items are the panel's descendants with a menu item role (`menuitem`,
+ * `menuitemcheckbox`, `menuitemradio`) and a `data-gridkit-menu-item` id,
+ * read afresh on every key so items drawn since attaching count. A submenu
+ * item says so with `aria-haspopup="menu"`; an item with
+ * `aria-disabled="true"` takes focus, so a screen reader finds it, but is
+ * never chosen. One item at a time has `tabindex="0"` — the focused one, or
+ * the first — and the rest `-1`: every item can take focus, and the first is
+ * what an overlay's initial focus finds when the menu is attached before it.
+ *
+ * Escape is not handled: a menu is shown with `attachOverlay`, whose stack
+ * gives Escape to the topmost overlay. A submenu is a menu of its own, in an
+ * overlay of its own anchored to its item, attached when it opens.
+ */
+declare function attachMenu(panel: HTMLElement, options: MenuOptions): AttachedMenu;
+
 /** Which side of its anchor an overlay opens on. */
 type OverlaySide = "top" | "bottom" | "left" | "right";
 /**
@@ -395,6 +517,14 @@ interface OverlayPlacementOptions {
     readonly placement?: OverlayPlacement | undefined;
     /** Space between the anchor and the overlay, in pixels. Defaults to `0`. */
     readonly gap?: number | undefined;
+    /**
+     * Pixels to shift the overlay along the anchor's edge — down beside a
+     * `left`/`right` side, right beside `top`/`bottom`; negative goes the other
+     * way. A submenu opened `right-start` takes its own top padding, negated,
+     * so its first item lines up with the item that opened it. The overlay is
+     * still kept on screen. Defaults to `0`.
+     */
+    readonly offset?: number | undefined;
 }
 /** Where an overlay goes: its top-left corner, and the placement it ended up with. */
 interface OverlayPosition {
@@ -421,21 +551,46 @@ type OverlayAnchor = Element | {
     readonly x: number;
     readonly y: number;
 };
+/**
+ * Where focus goes when an overlay attaches: its first focusable descendant,
+ * the panel itself, nowhere — focus stays where it was — or a given element.
+ */
+type OverlayInitialFocus = "first" | "panel" | "none" | HTMLElement;
 /** Why an overlay asked to close. */
-type OverlayDismissReason = "escape" | "outside" | "scroll" | "resize" | "blur";
+type OverlayDismissReason = "escape" | "outside" | "scroll" | "resize" | "blur" | "parent";
 interface OverlayOptions extends OverlayPlacementOptions {
     /**
-     * The overlay asks to close: Escape was pressed, a pointer went down
-     * outside it, something outside it scrolled, the window resized or lost
-     * focus, or focus moved outside it. The caller closes it — removes the
-     * panel and detaches — or keeps it open by doing nothing.
+     * The overlay asks to close: Escape was pressed while it was the topmost
+     * overlay, a pointer went down outside it, something outside it scrolled,
+     * the window resized or lost focus, focus moved outside it, or the overlay
+     * it was opened above detached. The caller closes it — removes the panel
+     * and detaches — or keeps it open by doing nothing, except after
+     * `"parent"`, which detaches it regardless.
      */
     readonly onDismiss: (reason: OverlayDismissReason) => void;
+    /**
+     * Where focus goes on attaching. Defaults to `"first"`: a menu focuses its
+     * first item. A panel whose first control is not where the user starts — a
+     * filter editor's operator picker before its value box — passes that
+     * element, or `"panel"` to land on the panel itself; `"none"` leaves focus
+     * where it was, as a suggestion list does while typing goes on in the
+     * field that opened it.
+     */
+    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.
      */
     readonly returnFocusTo?: 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 —
+     * leaves it open. A panel whose controls change the page under it opts
+     * in: a column chooser hiding a column narrows the grid it opened from,
+     * and the browser scrolls that grid back within its narrower content.
+     * Defaults to `false`, where every scroll outside the panel dismisses it.
+     */
+    readonly ignoreScrollAfterInput?: boolean | undefined;
 }
 /**
  * Shows `panel` as an overlay beside `anchor` — a menu, a popover, a filter
@@ -447,17 +602,27 @@ interface OverlayOptions extends OverlayPlacementOptions {
  * The panel is positioned `fixed`, at the place `placeOverlay` picks from the
  * anchor's and the panel's measured boxes, and carries that placement in
  * `data-gridkit-placement` (`"top-start"` once flipped above, say) for a
- * stylesheet to point an arrow by. Focus moves to the panel's first focusable
- * descendant, or to the panel itself — given `tabindex="-1"` if it has no
- * `tabindex` — when there is none.
+ * stylesheet to point an arrow by. Whenever the panel's size changes — a list
+ * that shrinks under a search — it is placed again beside the anchor, so a
+ * panel flipped above its anchor keeps its bottom edge there — or beside
+ * where the anchor was, once it has left the page. Focus moves
+ * where `initialFocus` says.
  *
  * Nothing that happens on or in the anchor dismisses the overlay, so a button
  * that toggles it can close it with its own click rather than having the
  * overlay close and the click reopen it.
  *
+ * Overlays stack in the order they attach. Escape belongs to the topmost
+ * alone, which takes it: it closes a submenu without closing the menu under
+ * it, and nothing else on the page — a grid that clears its selection on
+ * Escape — hears it. An overlay counts everything in the overlays above it
+ * as inside itself, so a click in a submenu keeps its menu open while a click
+ * elsewhere in the menu closes only the submenu.
+ *
  * Detaching removes every listener and returns focus, but only when focus is
- * still in the panel or nowhere — a click that dismissed it by landing on
- * another control leaves focus on that control.
+ * 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.
+ * Any overlay still above it is dismissed with `"parent"` and detached first.
  */
 declare function attachOverlay(anchor: OverlayAnchor, panel: HTMLElement, options: OverlayOptions): () => void;
 
@@ -512,4 +677,79 @@ interface RowVirtualizer {
  */
 declare function createRowVirtualizer(scrollElement: HTMLElement, options: RowVirtualizerOptions): RowVirtualizer;
 
-export { type BodyCellTarget, type BodyRowTarget, type ColumnDropContext, type ColumnDropTarget, type ColumnResizeGestureHandlers, type DragReorderHandlers, type DragReorderState, type FocusVirtualRange, type GridFocusController, type GridFocusOptions, type GridFocusRows, type GroupByDropTarget, type GroupRowTarget, type InfiniteScroll, type InfiniteScrollOptions, type LiveAnnouncer, NO_DRAG, type OverlayAlign, type OverlayAnchor, type OverlayDismissReason, type OverlayOptions, type OverlayPlacement, type OverlayPlacementOptions, type OverlayPosition, type OverlayRect, type OverlaySide, type OverlaySize, type PointerPress, type RowVirtualizer, type RowVirtualizerOptions, attachInfiniteScroll, attachOverlay, bodyCellFrom, bodyRowFrom, createGridFocus, createLiveAnnouncer, createRowVirtualizer, findBodyRow, groupRowFrom, measureColumnContent, measurePageSize, observeElementWidth, placeOverlay, resolveColumnDropTarget, resolveGroupByDropTarget, startColumnResizeGesture, startDragReorder };
+/**
+ * Makes `toolbar` — a `role="toolbar"` element the renderer drew — one tab
+ * stop that the arrow keys move within, following the WAI-ARIA toolbar
+ * pattern: ArrowRight and ArrowLeft move focus to the next and previous
+ * control, wrapping round the ends, and Home and End to the first and last.
+ * Returns the function that stops it.
+ *
+ * The toolbar's entries are its descendants with a `data-gridkit-toolbar-item`,
+ * and each entry's control is the entry itself when it can take focus, else
+ * the first element in it that can; an entry with none — a separator, a
+ * spacer — is passed over. They are read afresh on every key. One control at
+ * a time has `tabindex="0"` — the focused one, or the first — and the rest
+ * `-1`, kept so as entries come and go; a control with
+ * `aria-disabled="true"` stays one of them, so a screen reader finds it.
+ *
+ * A text field keeps the keys it needs: Home and End, and an arrow while
+ * the caret has text to move through in that direction. At the start or end
+ * of its text, the arrow moves on to the next control.
+ */
+declare function attachToolbar(toolbar: HTMLElement): () => void;
+
+/**
+ * A toolbar entry as the overflow reads it: its kind, the key its element
+ * carries and, for a button or a dropdown, its label — a change to which,
+ * while the entry is in "More" and not drawn, makes the width remembered for
+ * it stale.
+ */
+type ToolbarOverflowItem = Pick<ResolvedToolbarItem, "type" | "key"> & {
+    readonly label?: string | undefined;
+};
+interface ToolbarOverflowOptions {
+    /**
+     * Every entry of the toolbar, in order — those drawn and those moved into
+     * "More" alike — as `resolveToolbar` gave them.
+     */
+    readonly items: readonly ToolbarOverflowItem[];
+    /**
+     * How many entries fit, as `fitToolbarItems` counts them: called once
+     * straight away, then whenever the count changes.
+     */
+    readonly onChange: (fit: number) => void;
+}
+interface ToolbarOverflow {
+    /**
+     * Call whenever the items change, with the current options: measures
+     * again, and reports a changed count.
+     */
+    readonly update: (options: ToolbarOverflowOptions) => void;
+    /** Stops observing. */
+    readonly detach: () => void;
+}
+/**
+ * Measures how many of a toolbar's entries fit in it, reporting the count
+ * through `onChange` straight away — so a renderer calling this before
+ * paint draws the right entries from the first frame — and again whenever a
+ * resize changes it. The arithmetic is @gridkitjs/core's `fitToolbarItems`:
+ * the search box and custom entries always stay, and room for "More" is kept
+ * only when something does not fit.
+ *
+ * Entries are found by their `data-gridkit-toolbar-item`, holding each
+ * item's `key`, and the "More" button by `data-gridkit-toolbar-more`. An
+ * entry moved into "More" is no longer drawn, so each width is remembered
+ * by key from the last time it was; one never drawn yet counts as nothing,
+ * which lets it be drawn, measured, and moved back out if it does not fit —
+ * as one whose label changed while it was not drawn counts again.
+ * A spacer counts as nothing too: its width is only the room left over. The
+ * toolbar's padding and the `column-gap` between entries are allowed for.
+ *
+ * It measures again whenever the toolbar or an entry resizes and whenever
+ * entries are drawn or taken away — the ones the count it reported let in,
+ * or the "More" button — so a renderer only has to draw what it is told,
+ * and to pass new items to `update`.
+ */
+declare function observeToolbarOverflow(toolbar: HTMLElement, options: ToolbarOverflowOptions): ToolbarOverflow;
+
+export { type AttachedMenu, type BodyCellTarget, type BodyRowTarget, type ColumnDropContext, type ColumnDropTarget, type ColumnResizeGestureHandlers, type ContextMenuRequest, type ContextMenuSource, type ContextMenuTriggerOptions, type DragReorderHandlers, type DragReorderState, type FocusVirtualRange, type GridFocusController, type GridFocusOptions, type GridFocusRows, type GroupByDropTarget, type GroupRowTarget, type InfiniteScroll, type InfiniteScrollOptions, type LiveAnnouncer, type MenuCloseReason, type MenuOptions, type MenuSubmenuFocus, NO_DRAG, type OverlayAlign, type OverlayAnchor, type OverlayDismissReason, type OverlayInitialFocus, type OverlayOptions, type OverlayPlacement, type OverlayPlacementOptions, type OverlayPosition, type OverlayRect, type OverlaySide, type OverlaySize, type PointerPress, type RowVirtualizer, type RowVirtualizerOptions, type ToolbarOverflow, type ToolbarOverflowItem, type ToolbarOverflowOptions, attachContextMenuTrigger, attachInfiniteScroll, attachMenu, attachOverlay, attachToolbar, bodyCellFrom, bodyRowFrom, createGridFocus, createLiveAnnouncer, createRowVirtualizer, findBodyRow, groupRowFrom, measureColumnContent, measurePageSize, observeElementWidth, observeToolbarOverflow, placeOverlay, resolveColumnDropTarget, resolveGroupByDropTarget, startColumnResizeGesture, startDragReorder };