@gridkitjs/dom 0.2.1 → 0.3.0

package/README.md

@@ -57,7 +57,7 @@ Overlays stack in the order they attach: Escape and outside clicks reach the
 topmost first, and detaching one closes every overlay opened above it, so a
 submenu never outlives its menu.
 
-Full documentation: [github.com/blagojablazhevski/gridkit](https://github.com/blagojablazhevski/gridkit#readme)
+Full documentation: [github.com/gridkitjs/gridkitjs](https://github.com/gridkitjs/gridkitjs#readme)
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ColumnResizeSession, ColumnOrderState, GroupByState, GridFocus, NavigationModifiers, VisibleRange, ResolvedToolbarItem } from '@gridkitjs/core';
+import { ColumnResizeSession, ColumnOrderState, GroupByState, GridFocus, NavigationModifiers, VisibleRange, ResolvedToolbarItem, PrintPage } from '@gridkitjs/core';
 
 /** A live region to report changes through. */
 interface LiveAnnouncer {
@@ -65,6 +65,65 @@ declare function groupRowFrom(target: EventTarget | null): GroupRowTarget | null
  */
 declare function bodyRowFrom(target: EventTarget | null): BodyRowTarget | null;
 
+interface ChecklistOptions {
+    /**
+     * The item at `index` — its place in the whole list — asks to be checked
+     * or unchecked: Space on it, or a click. The caller flips it in its own
+     * state and draws the new `aria-checked`.
+     */
+    readonly onToggle: (index: number) => void;
+    /** Focus moved to the item at `index`, by a key, a click or a script. */
+    readonly onFocusChange?: ((index: number) => void) | undefined;
+    /**
+     * Bring the item at `index` into view, mounting it if the list's window
+     * does not hold it. A virtualized renderer forwards this to its
+     * virtualizer's `scrollToIndex`, with `{ block: "nearest" }` so a move of
+     * one item scrolls by one item.
+     */
+    readonly scrollToIndex: (index: number) => void;
+}
+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.
+     */
+    readonly setCount: (count: number) => void;
+    /**
+     * Focuses the item at `index`, clamped to the list, scrolling to it first.
+     * 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`. */
+    readonly detach: () => void;
+}
+/**
+ * Makes `list` — a `role="listbox"` the renderer drew, usually virtualized
+ * so that only a window of a long list is mounted — behave as a
+ * multi-select checklist with one tab stop: the arrow keys, Home, End,
+ * PageUp and PageDown move focus among its items, and Space or a click asks
+ * for the focused item to be toggled. It decides; the caller is told through
+ * the callbacks and draws the outcome, `aria-checked` included.
+ *
+ * Items are the list's descendants with `data-gridkit-checklist-item` and a
+ * `data-gridkit-checklist-index`: their place in the whole list rather than
+ * in the window, since an item's place is all that survives it being
+ * unmounted and mounted again. The list is the element that scrolls: PageUp
+ * and PageDown move by as many items as it shows whole.
+ *
+ * One item at a time has `tabindex="0"` — the focused one, or the first
+ * mounted while the focused one is scrolled away — and the rest `-1`, kept
+ * so as items mount by an observer of the list's children rather than by
+ * the renderer. A move to an item outside the window asks `scrollToIndex`
+ * for it and focuses it once it mounts, unless focus has gone somewhere
+ * else in the meantime.
+ *
+ * Enter is not handled, so a form around the list hears it and applies;
+ * Escape is the overlay stack's.
+ */
+declare function attachChecklist(list: HTMLElement, options: ChecklistOptions): AttachedChecklist;
+
 /**
  * How a context menu was asked for: by a pointer — a right-click, or a touch
  * held still — or by the keyboard.
@@ -168,6 +227,44 @@ declare function startColumnResizeGesture(handle: HTMLElement, press: PointerPre
  */
 declare function measureColumnContent(table: HTMLTableElement, columnId: string): number | null;
 
+/** What `writeClipboard` puts on the clipboard: the same copy as plain text and as HTML. */
+interface ClipboardContent {
+    readonly text: string;
+    readonly html: string;
+}
+/**
+ * Whether a copy key pressed at `target` belongs to the browser: pressed in a
+ * text field, or with text highlighted anywhere on the page. Either way the
+ * user means the text in front of them, and a grid copying its own cell
+ * instead would take that from them.
+ */
+declare function isNativeCopy(target: EventTarget | null): boolean;
+/**
+ * Puts `content` on the clipboard as both `text/plain` and `text/html`, so a
+ * paste into a spreadsheet splits into cells and one into a word processor
+ * keeps its table. Call it from a user's gesture — a key press, a menu
+ * choice — as browsers allow the clipboard only then.
+ *
+ * Tries each way a browser offers, best first: the async Clipboard API with
+ * a `ClipboardItem` holding both types; then its `writeText`, plain text
+ * alone, where `ClipboardItem` is missing or refused; then the legacy `copy`
+ * event, for a page outside a secure context, where the async API is not
+ * there at all. Rejects only when every one fails.
+ */
+declare function writeClipboard(content: ClipboardContent): Promise<void>;
+
+/**
+ * Saves `blob` as a file named `fileName` — the browser's own download, as a
+ * link with a `download` attribute starts one, so nothing is opened or
+ * navigated to.
+ *
+ * The link is put in the document for the click, as Firefox has needed, and
+ * taken out straight after. Its object URL is revoked a task later rather
+ * than at once: Safari starts the download from the URL after the click
+ * returns, and a URL revoked synchronously is gone before it does.
+ */
+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. */
@@ -591,6 +688,15 @@ interface OverlayOptions extends OverlayPlacementOptions {
      * Defaults to `false`, where every scroll outside the panel dismisses it.
      */
     readonly ignoreScrollAfterInput?: boolean | undefined;
+    /**
+     * Whether Tab and Shift+Tab stay inside the panel: from its last tabbable
+     * element Tab moves to its first, and Shift+Tab from its first to its last,
+     * as a dialog keeps them. Defaults to `false`, where tabbing out of the
+     * panel moves focus outside it, which dismisses it with `"blur"`. Only
+     * the keys are kept: a pointer down outside still dismisses it, and so
+     * does focus moved out by any other route.
+     */
+    readonly trapFocus?: boolean | undefined;
 }
 /**
  * Shows `panel` as an overlay beside `anchor` — a menu, a popover, a filter
@@ -752,4 +858,44 @@ interface ToolbarOverflow {
  */
 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 };
+/** What `printDocument` prints: a document's title, its body's markup and its stylesheet. */
+interface PrintDocumentOptions {
+    /** The document's title, as text — what the browser puts in a page's header and names a saved PDF. */
+    readonly title: string;
+    /** The `<body>`'s markup, as `buildPrintDocument` writes it. */
+    readonly bodyHtml: string;
+    /** The document's whole stylesheet — `printStyles(page)`, and anything added after it. */
+    readonly styles: string;
+}
+/**
+ * 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
+ * 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.
+ */
+declare function printDocument(options: PrintDocumentOptions): Promise<void>;
+
+/**
+ * The stylesheet a print of `buildPrintDocument`'s markup needs, for `page`.
+ * A print frame sees none of the page's CSS, so this carries what makes the
+ * table read on paper and nothing of a theme: the paper's size and
+ * orientation; a header row repeated at the top of every page; rows kept
+ * whole across a page break; neutral one-pixel borders; group headers
+ * stepped in by depth; backgrounds printed as they are rather than dropped
+ * to save ink; page numbers in the bottom-right margin, where the browser
+ * draws `@page` margin boxes; and for `fitToWidth`, a smaller font in fixed
+ * columns that wrap their text.
+ *
+ * The grand total prints once, after the last row — not repeated at the
+ * foot of every page, where browsers repeat a `<tfoot>`, as a total of
+ * rows the page does not hold would mislead. Add CSS after it to restyle.
+ */
+declare function printStyles(page: PrintPage): string;
+
+export { type AttachedChecklist, type AttachedMenu, type BodyCellTarget, type BodyRowTarget, type ChecklistOptions, type ClipboardContent, 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 PrintDocumentOptions, type RowVirtualizer, type RowVirtualizerOptions, type ToolbarOverflow, type ToolbarOverflowItem, type ToolbarOverflowOptions, attachChecklist, attachContextMenuTrigger, attachInfiniteScroll, attachMenu, attachOverlay, attachToolbar, bodyCellFrom, bodyRowFrom, createGridFocus, createLiveAnnouncer, createRowVirtualizer, downloadBlob, findBodyRow, groupRowFrom, isNativeCopy, measureColumnContent, measurePageSize, observeElementWidth, observeToolbarOverflow, placeOverlay, printDocument, printStyles, resolveColumnDropTarget, resolveGroupByDropTarget, startColumnResizeGesture, startDragReorder, writeClipboard };