@vuu-ui/vuu-utils 4.0.0-alpha.9 → 4.0.0-beta.1

package/types/filters/filterAsQuery.d.ts

@@ -1,8 +1,49 @@
+import type { TableSchema } from "@vuu-ui/vuu-data-types";
+import type { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
 import type { ColumnDescriptorsByName, Filter, SingleValueFilterClause } from "@vuu-ui/vuu-filter-types";
+import { type TemporalInfo } from "../date/temporal";
+import { type RelativeDate } from "../date/time-zone";
 export declare const filterAsQuery: (f: Filter, opts?: {
     columnsByName?: ColumnDescriptorsByName;
 }) => string;
 export declare const ONE_DAY_IN_MILLIS: number;
+export interface TemporalFilterAsQueryOptions {
+    /**
+     * The date against which time of day (TimeString) values are resolved.
+     * Default is 'today', resolved at the time the query is created.
+     */
+    date?: RelativeDate;
+}
+/**
+ * Serialize a filter clause on a temporal column. Values are interpreted at
+ * the granularity implied by the value and the column 'kind':
+ * - day: column kind is 'date', or a 'datetime' value at the exact start of a
+ *   day (in the column time zone), e.g as selected from a DatePicker. The clause
+ *   applies to the whole day: '=' becomes a [startOfDay, startOfNextDay) range,
+ *   '>' becomes '>= startOfNextDay' etc. Day boundaries are DST safe.
+ * - period: time of day values (TimeString or whole second 'time' values). A
+ *   TimeString represents the period implied by its precision, e.g hh:mm:ss is
+ *   the whole second, hh:mm:ss.fff the whole millisecond (on a nanosecond
+ *   column), and is treated like the day granularity above.
+ * - exact: all other values
+ * Values are encoded according to the column encoding (millis or nanos).
+ */
+export declare function temporalFilterAsQuery(f: SingleValueFilterClause, temporalInfo: TemporalInfo, options?: TemporalFilterAsQueryOptions): string;
+/**
+ * @deprecated use temporalFilterAsQuery
+ */
 export declare function dateFilterAsQuery(f: SingleValueFilterClause<number>, opts?: {
     columnsByName?: ColumnDescriptorsByName;
 }): string;
+export declare const getColumnsByName: (columns: readonly ColumnDescriptor[]) => ColumnDescriptorsByName;
+/**
+ * Build the columnsByName used to serialize a filter. Column descriptors
+ * provided by client take precedence over (are merged with) the schema columns.
+ */
+export declare const getColumnsByNameForFilter: (tableSchema?: Pick<TableSchema, "columns">, columnsByName?: ColumnDescriptorsByName) => ColumnDescriptorsByName | undefined;
+/**
+ * Returns true if the filter includes clauses whose meaning depends on the
+ * column type (temporal columns) or which serialize themselves. Such filters
+ * must be resolved (see resolveFilterQuery) before they can be evaluated locally.
+ */
+export declare const filterRequiresResolution: (filter: Filter, columnsByName?: ColumnDescriptorsByName) => boolean;

package/types/filters/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./filter-utils";
 export * from "./filterAsQuery";
+export * from "./temporal-cell-filter";

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

@@ -13,6 +13,22 @@ export declare const isInputElement: (el: HTMLElement | EventTarget | null) => e
 export declare const isDateInput: (el: HTMLElement | EventTarget | null) => el is HTMLInputElement;
 export declare const hasOpenOptionList: (el: HTMLElement | EventTarget | null) => boolean | undefined;
 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/index.d.ts

@@ -21,7 +21,6 @@ export * from "./debug-utils";
 export { isInlineEditingSession } from "./edit-utils";
 export { StaleUpdateError } from "./errors";
 export * from "./event-emitter";
-export * from "./errors";
 export * from "./feature-utils";
 export * from "./filters";
 export * from "./form-utils";

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/react-utils.d.ts

@@ -1,4 +1,4 @@
-import { type ReactElement, type ReactNode, type SetStateAction } from "react";
+import { ReactElement, ReactNode, SetStateAction } from "react";
 export declare const asReactElements: (children: ReactNode) => ReactElement[];
 export declare const useIsMounted: (id?: string) => import("react").RefObject<boolean>;
 export declare const isSimpleStateValue: <T>(arg: SetStateAction<T>) => arg is T;

package/types/sort-utils.d.ts

@@ -1,5 +1,5 @@
-import type { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
-import type { VuuSort, VuuSortType } from "@vuu-ui/vuu-protocol-types";
+import { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
+import { VuuSort, VuuSortType } from "@vuu-ui/vuu-protocol-types";
 export declare const toggleOrApplySort: ({ sortDefs }: VuuSort, { name: column }: ColumnDescriptor, extendSort?: boolean, sortType?: VuuSortType) => VuuSort;
 export declare const setSortColumn: ({ sortDefs }: VuuSort, column: ColumnDescriptor, sortType?: "A" | "D") => VuuSort;
 export declare const addSortColumn: ({ sortDefs }: VuuSort, column: ColumnDescriptor, sortType?: "A" | "D") => VuuSort;

package/types/table-schema-utils.d.ts

@@ -1,5 +1,5 @@
+import type { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
 import type { SchemaColumn, TableSchemaTable } from "@vuu-ui/vuu-data-types";
 import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
-import type { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
+export declare const toSchemaColumn: ({ editable, name, required, serverDataType, }: ColumnDescriptor) => SchemaColumn;
 export declare const getVuuTable: (schemaTable: TableSchemaTable) => VuuTable;
-export declare const toSchemaColumn: ({ editable, name, serverDataType }: ColumnDescriptor) => SchemaColumn;

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[];
 }

package/types/src/Clock.d.ts

@@ -1,20 +0,0 @@
-export interface ClockProps {
-    year?: number;
-    month?: number;
-    day?: number;
-    hours?: number;
-    minutes?: number;
-    seconds?: number;
-    milliseconds?: number;
-}
-export type ClockTimeUnit = "minutes" | "seconds" | "ms";
-export declare class Clock {
-    #private;
-    constructor(props?: ClockProps);
-    goBack(value: number, units?: ClockTimeUnit): this;
-    advance(value: number, units?: ClockTimeUnit): this;
-    set showCurrentTime(value: boolean);
-    toString(): string;
-    get now(): number;
-    get date(): Date;
-}

package/types/src/PageVisibilityObserver.d.ts

@@ -1,36 +0,0 @@
-import { EventEmitter } from "./event-emitter";
-export type PageVisibilityEvents = {
-    /**
-     * emits when page has been hidden for this period of time
-     */
-    "inactive-timeout": () => void;
-    /**
-     * emits when page is hidden
-     */
-    hidden: () => void;
-    /**
-     * emits when page is made visible
-     */
-    visible: () => void;
-    /**
-     * emits when page visibility status changes
-     */
-    visibilityChange: (hidden: boolean) => void;
-};
-export interface PageVisibilityObserverConstructorProps {
-    /**
-     * timeout period in seconds. Defaults to zero which will never timeout
-     */
-    inactiveTimeout?: number;
-    onHidden?: () => void;
-    onInactiveTimeout?: () => void;
-    onVisible?: () => void;
-    onVisibilityChange?: () => void;
-}
-export declare class PageVisibilityObserver extends EventEmitter<PageVisibilityEvents> {
-    #private;
-    visibilityChangeHandler: () => void;
-    constructor({ inactiveTimeout, onHidden, onInactiveTimeout, onVisibilityChange, onVisible, }?: PageVisibilityObserverConstructorProps);
-    clear(): void;
-    private set hidden(value);
-}

package/types/src/ScaledDecimal.d.ts

@@ -1,12 +0,0 @@
-export declare class ScaledDecimal {
-    protected readonly value: string;
-    private readonly decimals;
-    constructor(value: string, decimals?: number);
-    get asLong(): string;
-    toJSON(): string;
-    toString(): string;
-}
-export declare const ScaledDecimal2: (value: string) => ScaledDecimal;
-export declare const ScaledDecimal4: (value: string) => ScaledDecimal;
-export declare const ScaledDecimal6: (value: string) => ScaledDecimal;
-export declare const ScaledDecimal8: (value: string) => ScaledDecimal;

package/types/src/ShellContext.d.ts

@@ -1,11 +0,0 @@
-import type { RpcResponseHandler } from "@vuu-ui/vuu-data-types";
-import type { DefaultColumnConfiguration, DefaultTableConfiguration } from "@vuu-ui/vuu-table-types";
-import { LookupTableProvider } from "./feature-utils";
-export interface ShellContextProps {
-    getDefaultColumnConfig?: DefaultColumnConfiguration;
-    getDefaultTableConfig?: DefaultTableConfiguration;
-    getLookupValues?: LookupTableProvider;
-    handleRpcResponse?: RpcResponseHandler;
-}
-export declare const ShellContext: import("react").Context<ShellContextProps>;
-export declare const useShellContext: () => ShellContextProps;

package/types/src/ThemeProvider.d.ts

@@ -1,32 +0,0 @@
-import { type ReactNode } from "react";
-export declare const DEFAULT_DENSITY: Density;
-export declare const DEFAULT_THEME = "salt-theme";
-export declare const DEFAULT_THEME_MODE: ThemeMode;
-export type Density = "high" | "medium" | "low" | "touch";
-export type ThemeMode = "light" | "dark";
-export type TargetElement = "root" | "scope" | "child";
-export interface ThemeContextProps {
-    density: Density;
-    theme: string;
-    themeMode: ThemeMode;
-}
-export declare const ThemeContext: import("react").Context<ThemeContextProps>;
-export type ThemeClasses = [string, string, ThemeMode];
-export type ThemeAttributes = {
-    themeClass: string;
-    densityClass: string;
-    dataMode: ThemeMode;
-};
-export declare const useThemeAttributes: (themeAttributes?: ThemeAttributes) => [string, string, ThemeMode];
-interface ThemeProviderProps {
-    applyThemeClasses?: boolean;
-    children: ReactNode;
-    density?: Density;
-    theme?: string;
-    themeMode?: ThemeMode;
-}
-export declare function ThemeProvider({ applyThemeClasses, children, theme: themeProp, themeMode: themeModeProp, density: densityProp, }: ThemeProviderProps): import("react").JSX.Element;
-export declare namespace ThemeProvider {
-    var displayName: string;
-}
-export {};

package/types/src/array-utils.d.ts

@@ -1,16 +0,0 @@
-export type PartitionTest<T> = (value: T, index: number) => boolean;
-export declare function partition<T>(array: T[], test: PartitionTest<T>, pass?: T[], fail?: T[]): [T[], T[]];
-export declare function itemsChanged<T = unknown>(currentItems: T[], newItems: T[], identityProperty?: string): boolean;
-export declare function itemsOrOrderChanged<T = unknown>(currentItems: T[], newItems: T[], identityProperty?: string): boolean;
-export declare const moveItemDeprecated: <T = unknown>(items: T[], item: T, moveTo: number) => T[];
-export declare const moveItem: <T = unknown>(items: T[], fromIndex: number, toIndex: number) => T[];
-export declare const getAddedItems: <T>(values: undefined | T[], newValues: T[]) => T[];
-export declare const getMissingItems: <T, I>(sourceItems: T[], items: I[], identity: (s: T) => I) => I[];
-/**
- * Given an ordered list of item names, return items in same order
- */
-export declare const reorderItems: <T extends {
-    name: string;
-} = {
-    name: string;
-}>(originalItems: readonly T[], orderedNames: string[]) => T[];

package/types/src/box-utils.d.ts

@@ -1,24 +0,0 @@
-export interface rect {
-    bottom: number;
-    left: number;
-    right: number;
-    top: number;
-}
-export type rectTuple = [number, number, number, number];
-export type dimension = "width" | "height";
-export declare function boxContainsPoint(rect: rect, x: number, y: number): boolean | undefined;
-export type GridLayoutSplitDirection = "north" | "south" | "east" | "west";
-export type GridLayoutDropPosition = GridLayoutSplitDirection | "header" | "centre";
-export declare function getCenteredBox({ right, left, top, bottom }: rect, pctSize: number): {
-    left: number;
-    top: number;
-    right: number;
-    bottom: number;
-};
-export declare function pointPositionWithinRect(x: number, y: number, rect: rect, borderZone?: number): {
-    pctX: number;
-    pctY: number;
-    closeToTheEdge: number;
-};
-export declare const isGridLayoutSplitDirection: (position: GridLayoutDropPosition) => position is GridLayoutSplitDirection;
-export declare function getPositionWithinBox(x: number, y: number, rect: rect, pctX: number, pctY: number): GridLayoutDropPosition;

package/types/src/broadcast-channel.d.ts

@@ -1,16 +0,0 @@
-interface VuuBroadcastChannelEventMap<T> {
-    message: MessageEvent<T>;
-    messageerror: MessageEvent<T>;
-}
-export interface VuuBroadcastChannel<T> extends EventTarget {
-    readonly name: string;
-    onmessage: ((this: BroadcastChannel, evt: MessageEvent<T>) => void) | null;
-    onmessageerror: ((this: BroadcastChannel, evt: MessageEvent<T>) => void) | null;
-    close(): void;
-    postMessage<M extends T = T>(message: M): void;
-    addEventListener<K extends keyof VuuBroadcastChannelEventMap<T>>(type: K, listener: (this: BroadcastChannel, evt: VuuBroadcastChannelEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions): void;
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<K extends keyof VuuBroadcastChannelEventMap<T>>(type: K, listener: (this: BroadcastChannel, evt: VuuBroadcastChannelEventMap<T>[K]) => void, options?: boolean | EventListenerOptions): void;
-    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
-}
-export {};