@box-kite/react 2.2.6 → 2.2.8

package/utils/interactions/interactionChannel.d.ts

@@ -0,0 +1,35 @@
+import { InteractionEvent, InteractionListener, InteractionOptions, InteractionReport } from './interactionTypes';
+export type { ComponentInteraction, ComponentInteractions, CustomInteraction, DomInteraction, InteractionComponent, InteractionEvent, InteractionJson, InteractionListener, InteractionOptions, InteractionReport, InteractionSource, InteractionType, } from './interactionTypes';
+/** What happened, as it stood when it happened; everything else is worked out on delivery. */
+export interface Entry {
+    kind: InteractionEvent['kind'];
+    input: InteractionReport;
+    event?: Event;
+    /** The element a React handler ran on, read now: `currentTarget` is gone once dispatch ends. */
+    handler?: unknown;
+    timeStamp: number;
+    time: number;
+    url: string;
+}
+export interface Channel {
+    listeners: Map<InteractionListener, InteractionOptions>;
+    queue: Entry[];
+    /** The event the browser is dispatching, so a change made inside a handler names it without being told. */
+    dispatching?: Event;
+    /** Both set by the delivery half when it loads; until then, what happens waits in the queue. */
+    schedule?: () => void;
+    flush?: () => void;
+    loading?: boolean;
+    warned?: boolean;
+}
+/**
+ * Hear every interaction from here on, until the returned function is called. Delivery is fire and forget: events arrive in order,
+ * batched, in a background task after the handler that caused them, and a listener that throws is reported rather than rethrown.
+ */
+export declare function subscribeInteractions(listener: InteractionListener, options?: InteractionOptions): () => void;
+/** Deliver whatever is queued, now: what an analytics sender calls on `pagehide` before it sends its batch. */
+export declare const flushInteractions: () => void;
+/** What a component reports, beside the callback it fires for the same change. */
+export declare const emitInteraction: (input: InteractionReport) => void;
+/** A moment of the app's own (a page view, a hover, a wizard step) to the same listeners, fire and forget. */
+export declare const reportInteraction: (input: InteractionReport) => void;

package/utils/interactions/interactionJson.d.ts

@@ -0,0 +1,6 @@
+import { InteractionJson } from './interactionTypes';
+/**
+ * A value as plain JSON, or `undefined` for what has none: a function, a React element, a DOM node, a class instance.
+ * A `Date` is its ISO string, a `Set` an array and a `Map` a record; an object met a second time is left out, which cuts a cycle.
+ */
+export declare function toInteractionJson(value: unknown): InteractionJson | undefined;

package/utils/interactions/interactionListening.d.ts

@@ -0,0 +1,6 @@
+import { Channel } from './interactionChannel';
+/**
+ * The half of the channel fetched with the first subscription: delivery, which event is being dispatched (so a change made
+ * inside a handler names it unasked), and a press on anything a component styled.
+ */
+export default function deliver(channel: Channel): void;

package/utils/interactions/interactionTypes.d.ts

@@ -0,0 +1,224 @@
+/**
+ * What `Box.onInteraction` hears, as types. Every value and every detail arrives as plain JSON — the channel copies
+ * it on the way out — so an event can go to a log, a beacon or `JSON.stringify` as it stands.
+ */
+/** A value as it arrives: what `JSON.parse` could have produced. */
+export type InteractionJson = string | number | boolean | null | InteractionJson[] | {
+    [key: string]: InteractionJson;
+};
+type Key = string | number;
+type Open = {
+    openChange: boolean;
+};
+type CellRange = {
+    startRow: number;
+    endRow: number;
+    columns: Key[];
+};
+/** Every change a component reports, by its namespace and then its type: the value each one carries. */
+export interface ComponentInteractions {
+    accordion: {
+        valueChange: string[];
+    };
+    alertDialog: Open;
+    approval: {
+        decisionChange: 'approved' | 'rejected';
+    };
+    calendar: {
+        valueChange: InteractionJson;
+        pageChange: string;
+        viewChange: 'day' | 'month' | 'year';
+    };
+    collapsible: Open;
+    combobox: Open & {
+        valueChange: InteractionJson;
+    };
+    dashboard: {
+        layoutCommit: InteractionJson;
+        grab: string;
+        grabCancel: string;
+    };
+    datagrid: {
+        sortingChange: {
+            columnKey: Key;
+            direction: 'ASC' | 'DESC';
+        };
+        globalFilterChange: string;
+        columnFiltersChange: {
+            [columnKey: string]: InteractionJson;
+        };
+        paginationChange: {
+            page: number;
+            pageSize: number;
+        };
+        selectedRowKeysChange: Key[];
+        expandedRowKeysChange: Key[];
+        expandedTreeKeysChange: Key[];
+        rangeChange: CellRange;
+        copy: CellRange;
+        cellEditStart: InteractionJson;
+        cellEdit: InteractionJson;
+        cellEditCancel: InteractionJson;
+        cellEditReject: InteractionJson;
+        /** How many cells took the pasted value: `details.cells`, the values themselves, are content. */
+        paste: number;
+        columnPinChange: 'START' | 'END';
+        columnVisibilityChange: boolean;
+        columnResize: number;
+        groupingChange: Key[];
+        groupExpandedChange: boolean;
+        selectionViewChange: boolean;
+        export: 'csv' | 'xlsx';
+        retry: undefined;
+        recordChange: Key | null;
+        sheetChange: string | null;
+        selectModeChange: boolean;
+        showMore: number;
+    };
+    dateField: {
+        valueChange: string | null;
+    };
+    datePicker: Open & {
+        valueChange: string | null;
+    };
+    dateRangePicker: {
+        valueChange: {
+            start: string;
+            end: string;
+        } | null;
+    };
+    dialog: Open;
+    dropdown: Open & {
+        valueChange: InteractionJson[];
+    };
+    form: {
+        submit: string[];
+    };
+    menu: Open;
+    'menu.checkboxItem': {
+        checkedChange: boolean;
+    };
+    'menu.item': {
+        select: string;
+    };
+    'menu.radioGroup': {
+        valueChange: string;
+    };
+    'menu.sub': Open;
+    popover: Open;
+    radioGroup: {
+        valueChange: string;
+    };
+    reasoning: Open;
+    slider: {
+        valueCommit: number | number[];
+    };
+    sortableList: {
+        orderChange: string[];
+        orderCommit: string[];
+        grab: string;
+        grabCancel: string;
+    };
+    swipeItem: {
+        openChange: 'start' | 'end' | null;
+        fullSwipe: 'start' | 'end';
+    };
+    tabs: {
+        valueChange: string;
+    };
+    timeZoneSelect: Open & {
+        valueChange: string;
+    };
+    toaster: {
+        show: string;
+        update: string;
+        dismiss: string;
+        action: string;
+    };
+    toolCall: Open;
+    widget: {
+        refresh: string;
+    };
+}
+export type InteractionComponent = keyof ComponentInteractions;
+export type InteractionType<C extends InteractionComponent> = keyof ComponentInteractions[C] & string;
+/** Which component and which of its changes: what a component names about itself. */
+export type InteractionSource = {
+    [C in InteractionComponent]: {
+        component: C;
+        type: InteractionType<C>;
+    };
+}[InteractionComponent];
+interface InteractionBase {
+    /** Why, in the component's own words: the `reason` its callback is given. */
+    reason?: string;
+    /** Whatever else the callback is told (`rowKey`, `columnKey`, `oldValue`…), as plain JSON. */
+    details?: {
+        [key: string]: InteractionJson;
+    };
+    /** `'app'` when the code did it — a ref call, a timer, a `toast()` — rather than the person on the page. */
+    source: 'user' | 'app';
+    /** The DOM event behind it, when there was one: passed by the component, or the one being dispatched. */
+    event?: Event;
+    /** The element it happened on: the control that handled the event, else the component's own. */
+    target?: Element;
+    /** `performance.now()`, so it lines up with `event.timeStamp`. */
+    timeStamp: number;
+    /** `Date.now()`: when it happened, for a log on another machine. */
+    time: number;
+    /** The page it happened on, so an event delivered after a navigation still names its own; no query or hash without `content`. */
+    url: string;
+}
+/** A change a component reports — `kind: 'change'`, so `component` and `type` narrow `value`. */
+export type ComponentInteraction = {
+    [C in InteractionComponent]: {
+        [T in InteractionType<C>]: InteractionBase & {
+            kind: 'change';
+            component: C;
+            type: T;
+            value?: ComponentInteractions[C][T];
+        };
+    }[InteractionType<C>];
+}[InteractionComponent];
+/**
+ * A click or a change on anything a component styled, named by its `data-bk` (`Box.configure({ componentAttribute: true })`).
+ * `value` is a checkbox's or a radio's `checked`, never what was typed; `details.interactive` says whether a control was hit.
+ */
+export interface DomInteraction extends InteractionBase {
+    kind: 'dom';
+    component: string;
+    type: 'click' | 'change';
+    value?: boolean;
+}
+/** A moment the app reported itself with `Box.reportInteraction`. */
+export interface CustomInteraction extends InteractionBase {
+    kind: 'custom';
+    component: string;
+    type: string;
+    value?: InteractionJson;
+}
+export type InteractionEvent = ComponentInteraction | DomInteraction | CustomInteraction;
+export type InteractionListener = (event: InteractionEvent) => void;
+/** How much a listener is handed. */
+export interface InteractionOptions {
+    /**
+     * What people typed, pasted or picked as data (a search, a cell, a date), the text a toast showed them, and the URL's query
+     * and hash. Left out unless asked for, because a listener is usually a log on somebody else's machine.
+     */
+    content?: boolean;
+}
+/** What `Box.reportInteraction` takes: `event` may be React's synthetic one, and anything not JSON is dropped on the way out. */
+export interface InteractionReport {
+    component: string;
+    type: string;
+    reason?: string;
+    value?: unknown;
+    details?: Record<string, unknown>;
+    event?: unknown;
+    target?: Element;
+    /** Default: `'app'` for the reasons `imperative`, `programmatic` and `timeout`, `'user'` otherwise. */
+    source?: 'user' | 'app';
+    /** Which of `'value'` and the `details` keys are content: a listener that did not ask for content is not handed them. */
+    content?: readonly string[];
+}
+export {};