@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/dist/components/datagrid/grid-master-detail.d.ts

@@ -0,0 +1,38 @@
+import type { Bind } from '@motifx/core';
+import type { DetailContext } from './detail-context';
+/**
+ * Details under the rows: a row opens to show what `template` makes for it (another grid, a form,
+ * tabs), in a row of its own across the grid. Every field but `template`, `canExpand` and `height`
+ * as a function of the row is a value or a function that is followed. Read and change it later
+ * through `grid.masterDetail`.
+ */
+export interface GridMasterDetail<T> {
+    /** The expand column: the user opens and closes the details. Off, they open from code only (`expandRow`). Default `false`. */
+    enabled?: Bind<boolean>;
+    /** Every row starts open. Changing it, `enabled` or `template` opens or closes them all again. Default `false`. */
+    autoExpandAll?: Bind<boolean>;
+    /** What a row's details hold: a component, an element or a text. Made the first time the details show. */
+    template?: (ctx: DetailContext<T>) => unknown;
+    /** Whether a row has details: a value, or a function of the row. Default `true`. */
+    canExpand?: Bind<boolean> | ((row: T) => boolean);
+    /** A closed row keeps what its details hold, and shows it as it was when it opens again; off, closing disposes it. Default `true`. */
+    keepDetails?: Bind<boolean>;
+    /**
+     * Paged grid: the details of the rows of the page left keep what they hold while the user pages, up to `keepLimit`;
+     * off, another page or page size disposes them, and they are made again when their page shows (a row stays open).
+     * Default `false`.
+     */
+    keepAcrossPages?: Bind<boolean>;
+    /** Height of the details in pixels, the content scrolling inside; a function of the row gives each row its own. Default: as tall as the content. */
+    height?: Bind<number | undefined> | ((row: T) => number);
+    /** Height details count at before they are drawn and measured, while none is; then the average of those measured. Default `200`. */
+    estimatedHeight?: Bind<number>;
+    /** Open details out of view that keep their content; past it, the ones seen longest ago are disposed and made again when they show. Default `100`. */
+    keepLimit?: Bind<number>;
+    /** Width of the expand column, in pixels. Default `36`. */
+    columnWidth?: Bind<number>;
+    /** Keys on the expand cell that open and close the details (`KeyboardEvent.key` values). Default `['Enter', ' ']`. */
+    toggleKeys?: Bind<readonly string[]>;
+    /** Right on the expand cell of a closed row opens it, Left on an open one closes it; otherwise they move. Default `true`. */
+    arrowKeys?: Bind<boolean>;
+}

package/dist/components/datagrid/grid-mode.d.ts

@@ -0,0 +1,2 @@
+/** One long virtual list, pages with a pager, or a list that loads its next part as it nears the end. */
+export type GridMode = 'virtual' | 'paged' | 'infinite';

package/dist/components/datagrid/grid-more-rows-loaded-event-args.d.ts

@@ -0,0 +1,6 @@
+/** Infinite mode: a part of the rows came, `count` rows from `skip`; `ended` once every row shows. */
+export interface GridMoreRowsLoadedEventArgs {
+    readonly skip: number;
+    readonly count: number;
+    readonly ended: boolean;
+}

package/dist/components/datagrid/grid-more-rows-loading-event-args.d.ts

@@ -0,0 +1,6 @@
+import type { EventArgs } from '@motifx/core';
+/** Infinite mode: the next part of the rows is about to load, `take` rows from `skip`; `cancel` keeps the rows as they are. */
+export interface GridMoreRowsLoadingEventArgs extends EventArgs {
+    readonly skip: number;
+    readonly take: number;
+}

package/dist/components/datagrid/grid-option-changed-event-args.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A setting was assigned: one of `grid.settings`, one of a column's (`grid.columnSettings(field)`,
+ * `grid.columnOption(field, …)`, `field` set) or of the toolbar (`name` `'toolbar.visible'`,
+ * `'toolbar.items'`). `name` `'columns'`: a column was added or taken out; `value` and `previous`
+ * are the fields of the data columns.
+ */
+export interface GridOptionChangedEventArgs {
+    readonly name: string;
+    /** The column, for a column's setting. */
+    readonly field?: string;
+    /** The value now (a function's current result). */
+    readonly value: unknown;
+    readonly previous: unknown;
+}

package/dist/components/datagrid/grid-page-changed-event-args.d.ts

@@ -0,0 +1,5 @@
+/** Another page shows. */
+export interface GridPageChangedEventArgs {
+    readonly page: number;
+    readonly previous: number;
+}

package/dist/components/datagrid/grid-page-changing-event-args.d.ts

@@ -0,0 +1,6 @@
+import type { EventArgs } from '@motifx/core';
+/** Another page is about to show (paged mode, 0-based); `cancel` stays on this one. */
+export interface GridPageChangingEventArgs extends EventArgs {
+    readonly page: number;
+    readonly previous: number;
+}

package/dist/components/datagrid/grid-page-size-changed-event-args.d.ts

@@ -0,0 +1,5 @@
+/** The rows per page changed (0: every row on one page); the grid is back on the first page. */
+export interface GridPageSizeChangedEventArgs {
+    readonly pageSize: number;
+    readonly previous: number;
+}

package/dist/components/datagrid/grid-page-size-changing-event-args.d.ts

@@ -0,0 +1,6 @@
+import type { EventArgs } from '@motifx/core';
+/** The rows per page are about to change (0: every row on one page); `cancel` keeps them. */
+export interface GridPageSizeChangingEventArgs extends EventArgs {
+    readonly pageSize: number;
+    readonly previous: number;
+}

package/dist/components/datagrid/grid-pasting-event-args.d.ts

@@ -0,0 +1,7 @@
+import type { EventArgs } from '@motifx/core';
+/** Text is about to be pasted into the cells (Ctrl+V, `paste()`); change `text`, or `cancel`. */
+export interface GridPastingEventArgs extends EventArgs {
+    text: string;
+    readonly rowIndex: number;
+    readonly field: string;
+}

package/dist/components/datagrid/grid-row-click-event-args.d.ts

@@ -0,0 +1,13 @@
+import type { EventArgs } from '@motifx/core';
+import type { GridRowType } from './grid-row-type';
+/** A row was clicked (or double-clicked), after its cell's event; `cancel` stops what the grid does with it. */
+export interface GridRowClickEventArgs<T> extends EventArgs {
+    /** The row; `undefined` on a group row or while the row loads. */
+    readonly row: T | undefined;
+    readonly rowIndex: number;
+    readonly rowType: GridRowType;
+    readonly groupKey?: readonly unknown[];
+    /** The row element. */
+    readonly element: HTMLElement;
+    readonly event: MouseEvent;
+}

package/dist/components/datagrid/grid-row-drag-event-args.d.ts

@@ -0,0 +1,36 @@
+import type { DataGrid } from './DataGrid';
+/**
+ * A row is dragged (`rowDragging`'s `onDragStart`, `onDragMove`, `onDragChange`, `onDragEnd`), with
+ * the mouse, a pen, a finger on the drag icon or the keys that move a row; `cancel` stops it: at the
+ * start the row is not dragged, while it moves the place under the pointer takes no drop, at the end
+ * nothing is dropped. Indexes are the grid's row indexes (as `focusedRowIndex` and
+ * `getVisibleRows()` count them); `toIndex` is where the row would be after the drop, -1 while it is
+ * over no grid that takes it.
+ */
+export interface GridRowDragEventArgs<T = any> {
+    /** The grid that raised the event. */
+    readonly component: DataGrid<T>;
+    /** The grid the row comes from. */
+    readonly fromComponent: DataGrid<T>;
+    /** The grid under the pointer that takes the row, or `null`; the same grid while reordering. */
+    readonly toComponent: DataGrid<T> | null;
+    /** The row dragged. */
+    readonly itemData: T;
+    /** Its key, when it has one. */
+    readonly itemKey: unknown;
+    /** Its element in the grid it comes from. */
+    readonly itemElement: HTMLElement;
+    readonly fromIndex: number;
+    readonly toIndex: number;
+    /** The row at `toIndex` before the drop (the dragged row lands just before it, or after it when it comes from above); `undefined` at the end or on a group row. */
+    readonly toItemData: T | undefined;
+    /** Dropped onto the row at `toIndex` (`allowDropInsideItem`), not between rows. */
+    readonly dropInsideItem: boolean;
+    /** `rowDragging.data` of the grid it comes from. */
+    readonly fromData: unknown;
+    /** `rowDragging.data` of the grid under the pointer. */
+    readonly toData: unknown;
+    /** The pointer or key event behind it. */
+    readonly event: Event | undefined;
+    cancel: boolean;
+}

package/dist/components/datagrid/grid-row-dragging.d.ts

@@ -0,0 +1,71 @@
+import type { Bind } from '@motifx/core';
+import type { GridRowDragEventArgs } from './grid-row-drag-event-args';
+import type { GridRowDropEventArgs } from './grid-row-drop-event-args';
+/**
+ * Rows moved by dragging them (DevExtreme's `rowDragging`): within the grid (`allowReordering`),
+ * onto a row (`allowDropInsideItem`), or to another grid of the same `group`. The grid shows where
+ * the row would land and tells it in the events; your handlers move the data. Rows also move with
+ * the keyboard (`moveUpKeys`, `moveDownKeys`) and with `moveRow()`. Every field but the handlers and
+ * `dragTemplate` is a value or a function that is followed; read and change them later through
+ * `grid.rowDragging`.
+ */
+export interface GridRowDragging<T = any> {
+    /** Rows move within the grid. Default `false`. */
+    allowReordering?: Bind<boolean>;
+    /** A row can be dropped onto another (the middle of a row), for trees and details. Default `false`. */
+    allowDropInsideItem?: Bind<boolean>;
+    /** Where a drop would land: a line between rows (`'indicate'`), or the rows making room for it (`'push'`, not with `allowDropInsideItem`). Default `'indicate'`. */
+    dropFeedbackMode?: Bind<'indicate' | 'push'>;
+    /** A column of drag icons to drag rows by; off, the whole row is dragged. Default `true`. */
+    showDragIcons?: Bind<boolean>;
+    /** A CSS selector of what a row is dragged by, instead of the drag icon or the whole row. Default `''`. */
+    handle?: Bind<string>;
+    /** Grids of the same group take each other's rows (`onAdd` on the one dropped on, `onRemove` on the one it came from). */
+    group?: Bind<string | undefined>;
+    /** Anything of yours, handed to the events as `fromData` / `toData`. */
+    data?: Bind<unknown>;
+    /** Where the copy of the row may go: `'vertical'`, `'horizontal'` or `'both'`. Default `'both'`. */
+    dragDirection?: Bind<'both' | 'vertical' | 'horizontal'>;
+    /** An element (or a CSS selector) the dragged row stays inside. Default: none. */
+    boundary?: Bind<string | HTMLElement | undefined>;
+    /** An element (or a CSS selector) the copy of the row is shown in. Default: the grid. */
+    container?: Bind<string | HTMLElement | undefined>;
+    /** Where the copy sits from the pointer, `{ x, y }` (or `'x y'`). Default: where the row was taken, kept level with the rows. */
+    cursorOffset?: Bind<{
+        x?: number;
+        y?: number;
+    } | string | undefined>;
+    /** Content of your own instead of the copy of the row: a component, an element or a text. */
+    dragTemplate?: (e: {
+        itemData: T;
+        itemElement: HTMLElement;
+    }) => unknown;
+    /** The rows scroll while the pointer is near their top or bottom edge. Default `true`. */
+    autoScroll?: Bind<boolean>;
+    /** Pixels scrolled per frame at the edge. Default `30`. */
+    scrollSpeed?: Bind<number>;
+    /** How near the edge, in pixels, scrolling starts. Default `60`. */
+    scrollSensitivity?: Bind<number>;
+    /** The keys move the active row too. Default `true`. */
+    keyboard?: Bind<boolean>;
+    /** Keys that move the active row up one place. Default `['Ctrl+Shift+ArrowUp']`. */
+    moveUpKeys?: Bind<readonly string[]>;
+    /** Keys that move the active row down one place. Default `['Ctrl+Shift+ArrowDown']`. */
+    moveDownKeys?: Bind<readonly string[]>;
+    /** Width of the drag icon column, in pixels. Default `36`. */
+    columnWidth?: Bind<number>;
+    /** A row is about to be dragged; `cancel` keeps it in place. */
+    onDragStart?: (e: GridRowDragEventArgs<T>) => void;
+    /** The row moved under the pointer; `cancel` takes no drop there. */
+    onDragMove?: (e: GridRowDragEventArgs<T>) => void;
+    /** The place the row would land changed; `cancel` takes no drop there. */
+    onDragChange?: (e: GridRowDragEventArgs<T>) => void;
+    /** The row is about to be dropped; `cancel` drops nothing. */
+    onDragEnd?: (e: GridRowDragEventArgs<T>) => void;
+    /** The row was dropped elsewhere in this grid: move it in the data. */
+    onReorder?: (e: GridRowDropEventArgs<T>) => void;
+    /** A row of another grid was dropped on this one: add it to the data. */
+    onAdd?: (e: GridRowDropEventArgs<T>) => void;
+    /** This grid's row was dropped on another one: take it out of the data. */
+    onRemove?: (e: GridRowDropEventArgs<T>) => void;
+}

package/dist/components/datagrid/grid-row-drop-event-args.d.ts

@@ -0,0 +1,9 @@
+import type { GridRowDragEventArgs } from './grid-row-drag-event-args';
+/**
+ * A row was dropped (`rowDragging`'s `onReorder`, `onAdd`, `onRemove`). The grid does not move the
+ * data itself: move the row in your array (`splice`) or tell the server (a field that holds the
+ * order). Give `promise` for work that takes time: the grid waits for it, the drop marks shown.
+ */
+export interface GridRowDropEventArgs<T = any> extends Omit<GridRowDragEventArgs<T>, 'cancel'> {
+    promise?: PromiseLike<unknown>;
+}

package/dist/components/datagrid/grid-row-expanded-event-args.d.ts

@@ -0,0 +1,10 @@
+/** A group, or a row's details (`masterDetail`), opened or closed, by the user or from code. See `GridRowExpandingEventArgs`. */
+export type GridRowExpandedEventArgs = {
+    readonly kind: 'group';
+    readonly key: readonly unknown[];
+    readonly row?: undefined;
+} | {
+    readonly kind: 'detail';
+    readonly key: unknown;
+    readonly row: unknown;
+};

package/dist/components/datagrid/grid-row-expanding-event-args.d.ts

@@ -0,0 +1,15 @@
+import type { EventArgs } from '@motifx/core';
+/**
+ * A group, or a row's details (`masterDetail`), is about to open or close, by the user or from code;
+ * `cancel` keeps it as it is. `kind` tells which: a group's `key` is the values of the groups from the
+ * top level down to it, a row's is the row's key.
+ */
+export type GridRowExpandingEventArgs = EventArgs & ({
+    readonly kind: 'group';
+    readonly key: readonly unknown[];
+    readonly row?: undefined;
+} | {
+    readonly kind: 'detail';
+    readonly key: unknown;
+    readonly row: unknown;
+});

package/dist/components/datagrid/grid-row-extend-keys.d.ts

@@ -0,0 +1,7 @@
+/** The keys that extend a multiple row selection from the anchor as the active row moves: a row up or down, a screen of rows up or down. Each is a list of chords. */
+export interface GridRowExtendKeys {
+    up: readonly string[];
+    down: readonly string[];
+    pageUp: readonly string[];
+    pageDown: readonly string[];
+}

package/dist/components/datagrid/grid-row-inserted-event-args.d.ts

@@ -0,0 +1,6 @@
+/** A new row was saved. */
+export interface GridRowInsertedEventArgs<T, K = unknown> {
+    /** The row, with what the backend gave back. */
+    readonly row: T;
+    readonly key: K;
+}

package/dist/components/datagrid/grid-row-inserting-event-args.d.ts

@@ -0,0 +1,7 @@
+import type { EventArgs } from '@motifx/core';
+/** A new row is about to be sent; change `data` to change what goes out, `cancel` keeps it unsent. */
+export interface GridRowInsertingEventArgs<T> extends EventArgs {
+    readonly row: T;
+    /** The values sent. */
+    readonly data: Partial<T>;
+}

package/dist/components/datagrid/grid-row-prepared-event-args.d.ts

@@ -0,0 +1,14 @@
+import type { GridRowType } from './grid-row-type';
+/**
+ * A row was drawn: style it or add to it. The element is reused for other rows while the user scrolls,
+ * so set and clear what you change, every time.
+ */
+export interface GridRowPreparedEventArgs<T> {
+    /** The row; `undefined` on a group row. */
+    readonly row: T | undefined;
+    readonly rowIndex: number;
+    readonly rowType: GridRowType;
+    readonly groupKey?: readonly unknown[];
+    readonly isSelected: boolean;
+    readonly element: HTMLElement;
+}

package/dist/components/datagrid/grid-row-removed-event-args.d.ts

@@ -0,0 +1,5 @@
+/** A row was deleted on the backend. */
+export interface GridRowRemovedEventArgs<T, K = unknown> {
+    readonly key: K;
+    readonly row: T;
+}

package/dist/components/datagrid/grid-row-removing-event-args.d.ts

@@ -0,0 +1,6 @@
+import type { EventArgs } from '@motifx/core';
+/** A row's deletion is about to be sent; `cancel` keeps it (marked in batch mode). */
+export interface GridRowRemovingEventArgs<T, K = unknown> extends EventArgs {
+    readonly key: K;
+    readonly row: T;
+}

package/dist/components/datagrid/grid-row-type.d.ts

@@ -0,0 +1,2 @@
+/** What a row of the grid is: a data row, a new row not saved yet, a group row, a group's footer, the row of totals, a row's details (`masterDetail`), or a row's adaptive detail (the columns the width hides). */
+export type GridRowType = 'data' | 'new' | 'group' | 'groupFooter' | 'totalFooter' | 'detail' | 'detailAdaptive';

package/dist/components/datagrid/grid-row-updated-event-args.d.ts

@@ -0,0 +1,7 @@
+/** A row's changes were saved. */
+export interface GridRowUpdatedEventArgs<T, K = unknown> {
+    readonly key: K;
+    /** The row, with the saved values. */
+    readonly row: T;
+    readonly changes: Partial<T>;
+}

package/dist/components/datagrid/grid-row-updating-event-args.d.ts

@@ -0,0 +1,9 @@
+import type { EventArgs } from '@motifx/core';
+/** A row's changes are about to be sent; change `changes` to change what goes out, `cancel` keeps them unsent. */
+export interface GridRowUpdatingEventArgs<T, K = unknown> extends EventArgs {
+    readonly key: K;
+    /** The row as it was read. */
+    readonly row: T;
+    /** The changed fields and their new values. */
+    readonly changes: Partial<T>;
+}

package/dist/components/datagrid/grid-row-validating-event-args.d.ts

@@ -0,0 +1,22 @@
+import type { EventArgs } from '@motifx/core';
+/**
+ * A row is checked before it is saved, after its cells. `errors` holds the messages found, by field
+ * (`''` the whole row): add or remove some. `isValid = false` (or `cancel`) keeps the row from being
+ * saved, with `errorText` as its message.
+ */
+export interface GridRowValidatingEventArgs<T> extends EventArgs {
+    /** The row's key; `undefined` for a new row. */
+    readonly key: unknown;
+    /** The row itself. */
+    readonly row: T;
+    /** The values entered and not saved yet, by field (`{}` while there are none); the row itself does not hold them. */
+    readonly values: Readonly<Partial<T>>;
+    /** The value a field is saved with: the entered one when there is one, else the row's. */
+    getValue(field: string): unknown;
+    readonly isNew: boolean;
+    /** The fields with unsaved edits. */
+    readonly changed: readonly string[];
+    errors: Record<string, string>;
+    isValid: boolean;
+    errorText: string;
+}

package/dist/components/datagrid/grid-saved-event-args.d.ts

@@ -0,0 +1,7 @@
+import type { data } from '@motifx-community/data';
+/** The answer to a save came. */
+export interface GridSavedEventArgs<T> {
+    readonly changes: readonly data.Change<T, unknown>[];
+    readonly saved: number;
+    readonly failed: number;
+}

package/dist/components/datagrid/grid-saving-event-args.d.ts

@@ -0,0 +1,10 @@
+import type { EventArgs } from '@motifx/core';
+import type { data } from '@motifx-community/data';
+/**
+ * Changes are about to be sent (leaving a row, the queue of `background`, "Save changes"); `cancel`
+ * keeps them all unsent. Each row then gets its own `onRowInserting`, `onRowUpdating` or `onRowRemoving`.
+ */
+export interface GridSavingEventArgs<T> extends EventArgs {
+    /** What is sent, in order. */
+    readonly changes: readonly data.Change<T, unknown>[];
+}

package/dist/components/datagrid/grid-search-text-changed-event-args.d.ts

@@ -0,0 +1,4 @@
+/** The search text changed: typed in the search box, or set from code. */
+export interface GridSearchTextChangedEventArgs {
+    text: string;
+}

package/dist/components/datagrid/grid-search-text-changing-event-args.d.ts

@@ -0,0 +1,6 @@
+import type { EventArgs } from '@motifx/core';
+/** The search text is about to change (typed, or set from code); `cancel` keeps the one before. */
+export interface GridSearchTextChangingEventArgs extends EventArgs {
+    readonly text: string;
+    readonly previous: string;
+}

package/dist/components/datagrid/grid-selection-changed-event-args.d.ts

@@ -0,0 +1,7 @@
+import type { GridSelection } from './grid-selection';
+/** The selection changed, by the user or by code. */
+export interface GridSelectionChangedEventArgs {
+    selection: GridSelection;
+    /** The change comes from rows selected by dragging over them. */
+    byDrag: boolean;
+}

package/dist/components/datagrid/grid-selection-changing-event-args.d.ts

@@ -0,0 +1,9 @@
+import type { EventArgs } from '@motifx/core';
+import type { GridSelection } from './grid-selection';
+/** The selection is about to change (by the user or by code); `cancel` keeps it as it is. */
+export interface GridSelectionChangingEventArgs extends EventArgs {
+    readonly selection: GridSelection;
+    readonly previous: GridSelection;
+    /** The change comes from rows selected by dragging over them. */
+    readonly byDrag: boolean;
+}

package/dist/components/datagrid/grid-selection.d.ts

@@ -0,0 +1,16 @@
+import type { data } from '@motifx-community/data';
+/**
+ * The selected rows as a state, not a list: one by one (`keys`), or every row of `filter` but
+ * `except`, which is what "select all" gives over data of any size. Send it to the server for work on
+ * the selected rows; `grid.selectionFilter` turns it into a filter when the key is one field.
+ */
+export interface GridSelection {
+    /** Every row of `filter` is selected but the ones in `except`. */
+    all: boolean;
+    /** Keys of the selected rows, while `all` is `false`. */
+    keys: unknown[];
+    /** Keys of the rows left out, while `all` is `true`. */
+    except: unknown[];
+    /** The rows' filter when everything was selected (the source's filter, the grid's filters in it). */
+    filter: data.FilterExpression | null;
+}

package/dist/components/datagrid/grid-settings-props.d.ts

@@ -0,0 +1,6 @@
+import type { Bind } from '@motifx/core';
+import type { GridSettings } from './grid-settings';
+/** The `settings` prop: any of the switches, each a value or a function that is followed. */
+export type GridSettingsProps = {
+    [K in keyof GridSettings]?: Bind<GridSettings[K]>;
+};