@vuu-ui/vuu-utils 4.0.0-alpha.3 → 4.0.0-alpha.30

package/types/filters/scaled-decimal-filter.d.ts

@@ -0,0 +1,58 @@
+import type { ExtendedFilterOptions, ScaledDecimalFilterOptions, SingleValueFilterClause } from "@vuu-ui/vuu-filter-types";
+import type { DataValueDescriptor } from "@vuu-ui/vuu-data-types";
+export type ScaledDecimalScale = ScaledDecimalFilterOptions["scale"];
+export declare const getScaledDecimalScale: (serverDataType?: string) => ScaledDecimalScale | undefined;
+export declare const isValidDecimalString: (value: string) => boolean;
+export declare const isScaledDecimalFilterOptions: (options?: ExtendedFilterOptions) => options is ScaledDecimalFilterOptions;
+/**
+ * A decimal (not exponential) string representation of a filter value.
+ */
+export declare const toDecimalString: (value: unknown, scale: ScaledDecimalScale) => string;
+/**
+ * Convert a decimal string to its scaled integer representation. Digits beyond
+ * the scale are truncated, as the Vuu server does.
+ */
+export declare const toScaledInteger: (value: string, scale: ScaledDecimalScale) => bigint;
+/**
+ * Convert a scaled integer to a decimal string with 'scale' decimal places,
+ * the literal form in which scaled decimals are expressed in a filter query.
+ */
+export declare const fromScaledInteger: (value: bigint, scale: ScaledDecimalScale) => string;
+/**
+ * The filter options for a clause on a scaled decimal column, describing the
+ * precision with which the column displays values. These mirror the formatting
+ * rules of numericFormatter: a column with no type descriptor displays the full
+ * value, a type descriptor with no decimals displays 4 decimal places.
+ */
+export declare const getScaledDecimalFilterOptions: (column: Pick<DataValueDescriptor, "serverDataType" | "type">) => ScaledDecimalFilterOptions | undefined;
+/**
+ * The range of scaled integer values, inclusive at both ends, matched by a
+ * filter value. A value with no more decimal places than are displayed matches
+ * every value that displays as that value, e.g 1.23, displayed with 2 decimals,
+ * rounded, matches [1.225, 1.235). Display rounding applies to the magnitude,
+ * so -1.23 matches (-1.235, -1.225]. A value with more decimal places than are
+ * displayed is matched at its own precision, by the same rounding rule, e.g
+ * 1.234 matches [1.2335, 1.2345). A value with as many decimal places as the
+ * column holds, or any value where every decimal is displayed, is matched exactly.
+ */
+export declare const getScaledDecimalMatchRange: (value: string, { scale, decimals, roundingRule }: ScaledDecimalFilterOptions) => [bigint, bigint];
+/**
+ * Serialize a filter clause on a scaled decimal column. Where the value matches
+ * a range of values (see getScaledDecimalMatchRange), each operator applies to
+ * that range, e.g '>' matches values greater than every value in the range.
+ * Note: '!=' on a range is expressed as '< from or > to', which, unlike an
+ * exact '!=', does not match a null value.
+ */
+export declare const scaledDecimalFilterAsQuery: ({ column, op, value, }: Pick<SingleValueFilterClause, "column" | "op" | "value">, options: ScaledDecimalFilterOptions) => string;
+export interface ScaledDecimalCellFilter {
+    /** The value as displayed */
+    label: string;
+    op: "=";
+    value: string;
+}
+/**
+ * The filter for a cell value on a scaled decimal column, matching the value as
+ * displayed, e.g a cell displaying 1.23 (underlying value 1.234567) creates a
+ * filter matching every value that displays as 1.23.
+ */
+export declare const getScaledDecimalCellFilter: (column: Pick<DataValueDescriptor, "serverDataType" | "type">, value: unknown) => ScaledDecimalCellFilter | undefined;

package/types/filters/temporal-cell-filter.d.ts

@@ -0,0 +1,27 @@
+import type { DataValueDescriptor } from "@vuu-ui/vuu-data-types";
+export interface TemporalCellFilter {
+    /** The value, formatted as displayed */
+    label: string;
+    op: "=" | "between-inclusive";
+    value: string | [string, string];
+}
+/**
+ * Describes a filter that matches a temporal value at the precision with which
+ * it is displayed by the given column descriptor, e.g. where the descriptor
+ * displays milliseconds, the filter matches the whole millisecond.
+ * - date => the whole day, as a start of day value
+ * - time => a time of day (TimeString), truncated to the displayed precision
+ * - datetime => a range, unless the displayed precision is that of the encoding
+ * The filter is suitable for FilterAggregator.add (with the same descriptor) and
+ * matches the value a ColumnFilter with this descriptor would commit.
+ *
+ * @param column the descriptor of the filter (or table cell) displaying the value
+ * @param value a value as received from the server
+ * @param columnFilter the value is displayed by a ColumnFilter, rather than a
+ * table cell. A ColumnFilter displays a 'datetime' value as a date (DatePicker,
+ * so the filter is the whole day) and a 'time' value to the second, or to the
+ * millisecond with the 'hh:mm:ss.ms' pattern (TimeInput supports no finer
+ * precision, whereas a table cell displays nanos by default).
+ * @returns undefined if value is empty or column is not temporal
+ */
+export declare const getTemporalCellFilter: (column: DataValueDescriptor, value: unknown, columnFilter?: boolean) => TemporalCellFilter | undefined;

package/types/form-utils.d.ts

@@ -1,7 +1,11 @@
 import { DataValueTypeSimple } from "@vuu-ui/vuu-data-types";
 import { VuuColumnDataType, VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
 import { KeyboardEvent, SyntheticEvent } from "react";
+import { EpochTimestamp } from "./date/EpochTimestamp";
+import { type TemporalInfo } from "./date/temporal";
+import type { DataValueDescriptor } from "@vuu-ui/vuu-data-types";
 import { ExtendedFilterOptions } from "@vuu-ui/vuu-filter-types";
+import { type ScaledDecimal } from "./ScaledDecimal";
 export declare class DataValidationError extends Error {
     actualType: string;
     expectedType: string;
@@ -35,3 +39,18 @@ export declare function getTypedRange([value1, value2]: [string, string], dataTy
  */
 export declare function getTypedValue(value: string, type: VuuColumnDataType | DataValueTypeSimple, throwIfInvalid?: false, options?: ExtendedFilterOptions): VuuRowDataItemType | undefined;
 export declare function getTypedValue(value: string, type: VuuColumnDataType | DataValueTypeSimple, throwIfInvalid: true, options?: ExtendedFilterOptions): VuuRowDataItemType;
+/**
+ * Convert a string value (from user input or a filter control) to the wire
+ * representation of a temporal value, using the column's TemporalInfo.
+ * - time kind: a TimeString is applied to today's date (in the column time zone)
+ * - any kind: canonical input (see parseTemporalInput) or raw epoch digits
+ * Values are returned in the column encoding (number for epochMillis, string
+ * for epochNanos).
+ */
+export declare function getTypedTemporalValue(value: string, temporalInfo: TemporalInfo, throwIfInvalid?: boolean, baseValue?: EpochTimestamp): number | string | undefined;
+/**
+ * Like getTypedValue, but takes a column (or form field) descriptor. Temporal
+ * values are handled according to getTemporalInfo, other values according to
+ * the type name, if there is one, otherwise the serverDataType.
+ */
+export declare function getTypedValueForDescriptor(value: string, descriptor: DataValueDescriptor, throwIfInvalid?: boolean): VuuRowDataItemType | ScaledDecimal | bigint | undefined;

package/types/formatting-utils.d.ts

@@ -1,8 +1,30 @@
-import { ColumnDescriptor, ValueFormatter } from "@vuu-ui/vuu-table-types";
+import { DataValueDescriptor } from "@vuu-ui/vuu-data-types";
+import { ColumnDescriptor, FractionalSecondDigits, ValueFormatter } from "@vuu-ui/vuu-table-types";
 export type ValueFormatters = {
     [key: string]: ValueFormatter;
 };
 export declare const defaultValueFormatter: (value: unknown) => string;
+/**
+ * The number of fractional second digits displayed for a temporal value:
+ * type.formatting.fractionalSecondDigits if set, otherwise 3 for an
+ * 'hh:mm:ss.ms' time pattern, 9 for a nanosecond column with any other time
+ * pattern, else 0.
+ */
+export declare const getFractionalSecondDigits: (column: DataValueDescriptor, temporalInfo?: import("./date").TemporalInfo | undefined) => FractionalSecondDigits;
+/**
+ * Creates a formatter for a temporal value (see getTemporalInfo). Handles
+ * millisecond and nanosecond encodings, the configured (or default) pattern,
+ * time zone, locale and fractional second digits.
+ * Empty values (null, undefined, '', 0) are rendered as empty string.
+ */
+export declare const temporalFormatter: (column: DataValueDescriptor, temporalInfo?: import("./date").TemporalInfo | undefined) => ValueFormatter;
+/**
+ * Format a filter value on a temporal column for display (e.g. in a FilterPill
+ * tooltip or a list of filter clauses). Time of day (TimeString) values are
+ * displayed as is. A 'datetime' value at the start of a day (which the filter
+ * applies to the whole day, see temporalFilterAsQuery) is displayed as a date.
+ */
+export declare const formatTemporalFilterValue: (value: unknown, column: DataValueDescriptor) => string;
 export declare const numericFormatter: ({ align, serverDataType, type, }: Partial<ColumnDescriptor>) => typeof defaultValueFormatter;
 export declare const getValueFormatter: (column: ColumnDescriptor) => ValueFormatter;
 /**

package/types/html-utils.d.ts

@@ -12,7 +12,28 @@ export declare const isSelectableElement: (el?: HTMLElement | null) => boolean;
 export declare const isInputElement: (el: HTMLElement | EventTarget | null) => el is HTMLInputElement;
 export declare const isDateInput: (el: HTMLElement | EventTarget | null) => el is HTMLInputElement;
 export declare const hasOpenOptionList: (el: HTMLElement | EventTarget | null) => boolean | undefined;
+/**
+ * Test whether viewport coordinates (e.g. clientX, clientY from a pointer
+ * event) fall within the bounding rect of an element.
+ */
+export declare const containsPoint: (el: HTMLElement | null, x: number, y: number) => boolean;
 export declare function getScrollbarSize(): number;
+/**
+ * Used when the max scroll height cannot be measured, e.g. outside a browser.
+ */
+export declare const DEFAULT_MAX_SCROLL_HEIGHT = 33000000;
+/**
+ * Measure the largest scrollHeight (in CSS pixels) the browser supports for a
+ * scrollable element. Engines have an internal layout limit, which shrinks in
+ * CSS pixels as browser zoom increases, e.g.
+ *   Chromium/WebKit: ~33.5M at 100%, ~11.18M at 300%
+ *   Firefox:         ~17.9M at 100%, ~5.97M at 300%
+ * Chromium/WebKit clamp heights above the limit, Firefox ignores them entirely,
+ * so a single oversized probe cannot be used. Instead we binary search for the
+ * largest height that is honoured. Browser zoom changes devicePixelRatio, so
+ * results are cached per ratio.
+ */
+export declare function getMaxScrollHeight(doc?: Document | undefined): number;
 export type MouseEventTypes = "dblclick" | "click";
 export type KeyboardEventTypes = "keydown" | "keypress" | "keyup";
 export declare const dispatchMouseEvent: (el: HTMLElement, type: MouseEventTypes) => void;

package/types/keyset.d.ts

@@ -5,12 +5,22 @@ export interface IKeySet {
 }
 export declare class KeySet implements IKeySet {
     private keys;
+    private freeKeys;
     private nextKeyValue;
     private range;
     constructor(range: VuuRange);
     next(free?: number[]): number;
     private init;
-    reset(range: VuuRange): boolean;
+    /**
+     * Keys assigned to rows that remain within range are never changed, keys
+     * released by rows leaving the range are recycled for rows entering the
+     * range. Keys are never re-sequenced, clients may retain rows (and their
+     * keys) that remain within range, so re-assigning keys to those rows would
+     * risk duplicate keys on the client.
+     * Note: range is copied, callers may mutate the range object they pass.
+     * Returns false, keys are never resequenced.
+     */
+    reset({ from, to }: VuuRange): boolean;
     keyFor(rowIndex: number): number;
     toDebugString(): string;
 }

package/types/tree-types.d.ts

@@ -5,5 +5,7 @@ export interface TreeSourceNode<T = unknown> {
     header?: boolean;
     label: string;
     childNodes?: TreeSourceNode<T>[];
+    /** node is rendered expanded initially */
+    expanded?: boolean;
     tags?: string[];
 }