@vuu-ui/vuu-utils 4.0.0-alpha.2 → 4.0.0-alpha.20

package/src/html-utils.js

@@ -81,6 +81,40 @@ function getScrollbarSize() {
     }
     return size;
 }
+const DEFAULT_MAX_SCROLL_HEIGHT = 33000000;
+const MAX_PROBE_HEIGHT = 2 ** 26;
+const maxScrollHeightByDevicePixelRatio = new Map();
+function getMaxScrollHeight(doc = globalThis.document) {
+    if (doc?.body === void 0 || null === doc.body) return DEFAULT_MAX_SCROLL_HEIGHT;
+    const devicePixelRatio = doc.defaultView?.devicePixelRatio ?? 1;
+    const cachedValue = maxScrollHeightByDevicePixelRatio.get(devicePixelRatio);
+    if (void 0 !== cachedValue) return cachedValue;
+    const outer = doc.createElement("div");
+    outer.style.cssText = "position:absolute;top:-200px;left:-200px;width:50px;height:50px;overflow:scroll;visibility:hidden;";
+    const inner = doc.createElement("div");
+    inner.style.width = "1px";
+    outer.appendChild(inner);
+    doc.body.appendChild(outer);
+    const isHonoured = (height)=>{
+        inner.style.height = `${height}px`;
+        return outer.scrollHeight >= height - 1;
+    };
+    let lo = 0;
+    let hi = MAX_PROBE_HEIGHT;
+    while(hi - lo > 1){
+        const mid = Math.floor((lo + hi) / 2);
+        if (isHonoured(mid)) lo = mid;
+        else hi = mid;
+    }
+    inner.style.height = `${lo}px`;
+    const maxScrollHeight = Math.min(lo, outer.scrollHeight);
+    outer.remove();
+    if (maxScrollHeight > 0) {
+        maxScrollHeightByDevicePixelRatio.set(devicePixelRatio, maxScrollHeight);
+        return maxScrollHeight;
+    }
+    return DEFAULT_MAX_SCROLL_HEIGHT;
+}
 const dispatchMouseEvent = (el, type)=>{
     const evt = new MouseEvent(type, {
         view: window,
@@ -105,4 +139,4 @@ const dispatchCustomEvent = (el, type)=>{
     });
     el.dispatchEvent(evt);
 };
-export { createEl, dispatchCustomEvent, dispatchKeyboardEvent, dispatchMouseEvent, focusFirstFocusableElement, getClosest, getClosestIndexItem, getElementByDataIndex, getElementDataIndex, getFocusableElement, getScrollbarSize, hasOpenOptionList, isDateInput, isInputElement, isSelectableElement, queryClosest };
+export { DEFAULT_MAX_SCROLL_HEIGHT, createEl, dispatchCustomEvent, dispatchKeyboardEvent, dispatchMouseEvent, focusFirstFocusableElement, getClosest, getClosestIndexItem, getElementByDataIndex, getElementDataIndex, getFocusableElement, getMaxScrollHeight, getScrollbarSize, hasOpenOptionList, isDateInput, isInputElement, isSelectableElement, queryClosest };

package/src/keyset.js

@@ -1,10 +1,14 @@
 const EMPTY = [];
 class KeySet {
     keys = new Map();
+    freeKeys = [];
     nextKeyValue = 0;
     range;
     constructor(range){
-        this.range = range;
+        this.range = {
+            from: range.from,
+            to: range.to
+        };
         this.init(range);
     }
     next(free = EMPTY) {
@@ -13,6 +17,7 @@ class KeySet {
     }
     init({ from, to }) {
         this.keys.clear();
+        this.freeKeys.length = 0;
         this.nextKeyValue = 0;
         for(let rowIndex = from; rowIndex < to; rowIndex++){
             const nextKeyValue = this.next();
@@ -20,23 +25,24 @@ class KeySet {
         }
         return true;
     }
-    reset(range) {
-        const { from, to } = range;
-        const newSize = to - from;
-        const currentSize = this.range.to - this.range.from;
-        this.range = range;
-        if (currentSize > newSize) return this.init(range);
-        const freeKeys = [];
+    reset({ from, to }) {
+        this.range = {
+            from,
+            to
+        };
+        const { freeKeys } = this;
         this.keys.forEach((keyValue, rowIndex)=>{
             if (rowIndex < from || rowIndex >= to) {
                 freeKeys.push(keyValue);
                 this.keys.delete(rowIndex);
             }
         });
+        let freeKeyIndex = 0;
         for(let rowIndex = from; rowIndex < to; rowIndex++)if (!this.keys.has(rowIndex)) {
-            const nextKeyValue = this.next(freeKeys);
+            const nextKeyValue = freeKeyIndex < freeKeys.length ? freeKeys[freeKeyIndex++] : this.nextKeyValue++;
             this.keys.set(rowIndex, nextKeyValue);
         }
+        if (freeKeyIndex > 0) freeKeys.splice(0, freeKeyIndex);
         return false;
     }
     keyFor(rowIndex) {

package/src/useResizeObserver.js

@@ -29,7 +29,7 @@ const getTargetSize = (element, size, dimension)=>{
             return 0;
     }
 };
-const resizeObserver = new ResizeObserver((entries)=>{
+const resizeObserver = "u" < typeof ResizeObserver ? void 0 : new ResizeObserver((entries)=>{
     for (const entry of entries){
         const { target, borderBoxSize, contentBoxSize } = entry;
         const observedTarget = observedMap.get(target);
@@ -81,7 +81,7 @@ function useResizeObserver(ref, dimensions, onResize, reportInitialSize = false)
             if (observedTarget) {
                 const measurements = measure(target);
                 observedTarget.measurements = measurements;
-                resizeObserver.observe(target);
+                resizeObserver?.observe(target);
                 if (reportInitialSize) onResize(measurements);
             } else console.log("%cuseResizeObserver an target expected to be under observation wa snot found. This warrants investigation", "font-weight:bold; color:red;");
         }
@@ -93,7 +93,7 @@ function useResizeObserver(ref, dimensions, onResize, reportInitialSize = false)
         }
         return ()=>{
             if (target && observedMap.has(target)) {
-                resizeObserver.unobserve(target);
+                resizeObserver?.unobserve(target);
                 observedMap.delete(target);
             }
         };

package/types/array-utils.d.ts

@@ -1,11 +1,14 @@
 export type PartitionTest<T> = (value: T, index: number) => boolean;
+export type ItemComparator<T> = (firstItem: T, secondItem: T) => 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 function itemsChanged<T = unknown>(currentItems: readonly T[], newItems: readonly T[], identityProperty?: string): boolean;
+export declare function itemsOrOrderChanged<T = unknown>(currentItems: readonly T[], newItems: readonly 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[];
+export declare const getAddedItems: <T>(currentItems: undefined | readonly T[], newItems: readonly T[], compareItems?: ItemComparator<T>) => readonly T[];
+export declare const getRemovedItems: <T>(currentItems: readonly T[], newItems: undefined | readonly T[], compareItems?: ItemComparator<T>) => readonly T[];
+export declare const containsSubsetOfItems: <T>(allItems: readonly T[], comparedItems: readonly T[]) => boolean;
+export declare const getMissingItems: <T, I>(sourceItems: readonly T[], items: readonly I[], identity: (s: T) => I) => I[];
 /**
  * Given an ordered list of item names, return items in same order
  */

package/types/column-utils.d.ts

@@ -1,8 +1,8 @@
 import type { DataSourceRow, DataValueDescriptor, DataValueType, DataValueTypeSimple, DateTimeDataValueDescriptor, SchemaColumn, TableSchema, TimeDataValueDescriptor } from "@vuu-ui/vuu-data-types";
 import type { VuuAggType, VuuAggregation, VuuColumnDataType, VuuDataRowDto, VuuGroupBy, VuuSort } from "@vuu-ui/vuu-protocol-types";
 import type { ColumnAlignment, ColumnDescriptor, ColumnLayout, ColumnTypeFormatting, ColumnTypeRendering, ColumnTypeWithValidationRules, DataRow, DataValueTypeDescriptor, DefaultColumnConfiguration, GroupColumnDescriptor, LookupRenderer, MappedValueTypeRenderer, PinLocation, RuntimeColumnDescriptor, TableCellRendererProps, TableConfig, TableHeadings, ValueListRenderer } from "@vuu-ui/vuu-table-types";
-import type { CSSProperties } from "react";
 import type { TableModel } from "@vuu-ui/vuu-table";
+import type { CSSProperties } from "react";
 /**
  * ColumnMap provides a lookup of the index position of a data item within a row
  * by column name.
@@ -33,13 +33,48 @@ export type CalculatedColumn = {
 };
 export declare const isVuuColumnDataType: (value: string | undefined | null) => value is VuuColumnDataType;
 export declare const fromServerDataType: (serverDataType: VuuColumnDataType) => DataValueTypeSimple;
+/**
+ * Returns true if serverDataType is epochtimestampnano. Note: prefer
+ * getTemporalInfo, which describes encoding, kind and time zone.
+ */
 export declare const isNanoTimestampColumn: ({ serverDataType, }: DataValueDescriptor) => boolean;
-export declare const isTimestampColumn: (column: ColumnDescriptor) => boolean;
-export declare const isNumericColumn: ({ serverDataType, type }: ColumnDescriptor) => boolean;
-export declare const isDateTimeDataType: (column: ColumnDescriptor) => column is DateTimeDataValueDescriptor;
-export declare const isTimeDataType: (column: ColumnDescriptor) => column is TimeDataValueDescriptor;
-export declare const isDateTimeDataValue: (column: ColumnDescriptor) => boolean;
-export declare const isTimeDataValue: (column?: ColumnDescriptor) => column is TimeDataValueDescriptor;
+/**
+ * Returns true if serverDataType is epochtimestamp or epochtimestampnano.
+ * Note: this does not recognise legacy columns (long with a date/time type),
+ * use isTemporalColumn for that.
+ */
+export declare const isTimestampColumn: (column: DataValueDescriptor) => boolean;
+/**
+ * Returns true for any column holding a temporal value, see getTemporalInfo.
+ */
+export declare const isTemporalColumn: (column?: DataValueDescriptor) => boolean;
+/**
+ * Numeric columns, excluding those that hold temporal values.
+ */
+export declare const isNumericColumn: (column: ColumnDescriptor) => boolean;
+/**
+ * Checks the 'type' only, returns true for 'date/time' (or 'date').
+ * @deprecated use getTemporalInfo or isDateTimeDataValue
+ */
+export declare const isDateTimeDataType: (column: DataValueDescriptor) => column is DateTimeDataValueDescriptor;
+/**
+ * Checks the 'type' only, returns true for 'time'.
+ * @deprecated use getTemporalInfo or isTimeDataValue
+ */
+export declare const isTimeDataType: (column: DataValueDescriptor) => column is TimeDataValueDescriptor;
+/**
+ * Temporal value of kind 'datetime' or 'date' (i.e has a meaningful date component)
+ */
+export declare const isDateTimeDataValue: (column?: DataValueDescriptor) => boolean;
+/**
+ * Temporal value of kind 'time' (time of day)
+ */
+export declare const isTimeDataValue: (column?: DataValueDescriptor) => column is TimeDataValueDescriptor;
+/**
+ * A time column is edited/filtered with millisecond precision if its
+ * formatting pattern includes milliseconds.
+ */
+export declare const isTimeDataValueWithMilliseconds: (column?: ColumnDescriptor) => column is TimeDataValueDescriptor;
 export declare const isPinned: (column: ColumnDescriptor) => boolean;
 export declare const hasHeadings: (column: ColumnDescriptor) => boolean;
 export declare const isResizing: (column: RuntimeColumnDescriptor) => boolean | undefined;
@@ -171,39 +206,7 @@ export declare const setCalculatedColumnType: (column: ColumnDescriptor, serverD
 export declare const setCalculatedColumnExpression: (column: ColumnDescriptor, expression: string) => ColumnDescriptor;
 export declare const moveColumnTo: (columns: ColumnDescriptor[], column: ColumnDescriptor, newIndex: number) => ColumnDescriptor[];
 export declare function replaceColumn<C extends ColumnDescriptor = RuntimeColumnDescriptor>(columns: readonly C[], column: C): C[];
-export declare const applyDefaultColumnConfig: ({ columns: columnsProp, table }: TableSchema, getDefaultColumnConfig?: DefaultColumnConfiguration, includeVuuDefaultColumns?: boolean) => (SchemaColumn | {
-    aggregate?: VuuAggType;
-    align?: ColumnAlignment;
-    allowColumnHeaderMenu?: false;
-    className?: string;
-    colHeaderContentRenderer?: string;
-    colHeaderLabelRenderer?: string;
-    exportFormatter?: (value: unknown) => string;
-    flex?: number;
-    getIcon?: (row: DataRow) => string | undefined;
-    groupable?: boolean;
-    heading?: string[];
-    hidden?: boolean;
-    isSystemColumn?: boolean;
-    locked?: Exclude<PinLocation, "left"> | false;
-    maxWidth?: number;
-    minWidth?: number;
-    pin?: PinLocation | false;
-    removeable?: boolean;
-    resizeable?: boolean;
-    selected?: boolean;
-    sortable?: boolean;
-    source?: "client" | "server";
-    status?: import("@salt-ds/core").ValidationStatus;
-    width?: number;
-    editableBulk?: import("@vuu-ui/vuu-data-types").BulkEdit;
-    label?: string;
-    required?: boolean;
-    type?: DataValueType;
-    editable?: import("@vuu-ui/vuu-data-types").DataEditable | undefined;
-    name: string;
-    serverDataType: VuuColumnDataType;
-})[] | readonly SchemaColumn[];
+export declare const applyDefaultColumnConfig: ({ columns: columnsProp, table }: TableSchema, getDefaultColumnConfig?: DefaultColumnConfiguration, includeVuuDefaultColumns?: boolean) => readonly SchemaColumn[];
 export type columnOptions = {
     availableWidth?: number;
     columnLayout?: ColumnLayout;

package/types/component-registry.d.ts

@@ -1,7 +1,7 @@
-import { EditRuleValidator } from "@vuu-ui/vuu-data-types";
-import { VuuColumnDataType } from "@vuu-ui/vuu-protocol-types";
-import { ColumnDescriptor, ColumnDescriptorCustomRenderer, ColumnTypeRendering, DataRow, HeaderCellProps, TableCellRendererProps } from "@vuu-ui/vuu-table-types";
-import { FunctionComponent as FC, HTMLAttributes } from "react";
+import type { EditRuleValidator } from "@vuu-ui/vuu-data-types";
+import type { VuuColumnDataType } from "@vuu-ui/vuu-protocol-types";
+import type { ColumnDescriptor, ColumnDescriptorCustomRenderer, ColumnTypeRendering, DataRow, HeaderCellProps, TableCellRendererProps } from "@vuu-ui/vuu-table-types";
+import type { FunctionComponent as FC, HTMLAttributes } from "react";
 export interface CellConfigPanelProps extends HTMLAttributes<HTMLDivElement> {
     onConfigChange: () => void;
 }

package/types/datasource/BaseDataSource.d.ts

@@ -1,4 +1,4 @@
-import type { DataSource, DataSourceConstructorProps, DataSourceEvents, DataSourceFilter, DataSourceSubscribeCallback, DataSourceSubscribeProps, DataSourceSuspenseProps, WithBaseFilter, WithFullConfig } from "@vuu-ui/vuu-data-types";
+import type { DataSource, DataSourceConstructorProps, DataSourceEvents, DataSourceFilter, DataSourceSubscribeCallback, DataSourceSubscribeProps, DataSourceSuspenseProps, SetFilterOptions, WithBaseFilter, WithFullConfig } from "@vuu-ui/vuu-data-types";
 import { LinkDescriptorWithLabel, VuuAggregation, VuuRange, VuuSort } from "@vuu-ui/vuu-protocol-types";
 import { EventEmitter } from "../event-emitter";
 import { Range } from "../range-utils";
@@ -28,7 +28,7 @@ export declare abstract class BaseDataSource extends EventEmitter<DataSourceEven
     set columns(columns: string[]);
     get filter(): DataSourceFilter;
     set filter(filter: DataSourceFilter);
-    setFilter(filter: Filter): void;
+    setFilter(filter: Filter, options?: SetFilterOptions): void;
     clearFilter(): void;
     get isAwaitingConfirmationOfConfigChange(): boolean;
     protected confirmConfigChange(): void;

package/types/date/EpochTimestamp.d.ts

@@ -0,0 +1,66 @@
+import { type DateTimeFields, type TimeZoneSpec } from "./time-zone";
+/**
+ * How a temporal value is encoded on the wire (i.e in rows received from,
+ * and values sent to, the server).
+ * - epochMillis, a number (epochtimestamp, or legacy long with a date/time type)
+ * - epochNanos, a string of digits (epochtimestampnano). Nanosecond values
+ *   cannot be represented safely as JavaScript numbers. A bigint is also
+ *   accepted where values are generated locally.
+ */
+export type TemporalEncoding = "epochMillis" | "epochNanos";
+/**
+ * A timestamp with nanosecond precision. Internally represented as epoch
+ * millis (floored) plus nanos within the milli, so the common millisecond
+ * case requires no bigint arithmetic.
+ *
+ * Note: an empty value (null, undefined, '', 0, '0') is treated as 'no value'
+ * by fromWire. The Vuu server uses 0 to represent an unset timestamp, so
+ * the epoch itself (1970-01-01T00:00:00.000Z) cannot be represented.
+ */
+export declare class EpochTimestamp {
+    readonly epochMillis: number;
+    /** nanoseconds within the millisecond, 0 - 999,999 */
+    readonly subMilliNanos: number;
+    private constructor();
+    static fromMillis(epochMillis: number, subMilliNanos?: number): EpochTimestamp;
+    static fromNanos(epochNanos: bigint | string | number): EpochTimestamp;
+    static fromDate(date: Date): EpochTimestamp;
+    static fromFields(fields: Partial<DateTimeFields> & Pick<DateTimeFields, "year" | "month" | "day">, timeZone?: TimeZoneSpec, subMilliNanos?: number): EpochTimestamp;
+    /**
+     * Returns true if value represents 'no value'.
+     */
+    static isEmpty(value: unknown): value is "" | "0" | 0 | 0n | null | undefined;
+    /**
+     * Decode a value as received from the server, or held in a filter,
+     * in the given encoding. Returns undefined for an empty or invalid value,
+     * including a value outside the range of a JavaScript Date (e.g. a nanos
+     * value decoded as millis).
+     */
+    static fromWire(value: unknown, encoding: TemporalEncoding): EpochTimestamp | undefined;
+    private static decode;
+    get epochNanos(): bigint;
+    toDate(): Date;
+    /**
+     * Fraction of second, truncated to the requested number of digits
+     */
+    fractionalSecond(digits: number): string;
+    getFields(timeZone?: TimeZoneSpec): DateTimeFields;
+    /**
+     * Encode for the wire. epochMillis => number, epochNanos => string
+     */
+    toWire(encoding: "epochMillis"): number;
+    toWire(encoding: "epochNanos"): string;
+    toWire(encoding: TemporalEncoding): number | string;
+    /**
+     * Encode as a literal in a filter query (never quoted)
+     */
+    toLiteral(encoding: TemporalEncoding): string;
+    /**
+     * Add a number of the smallest unit for the encoding, i.e 1 milli or 1 nano.
+     * Useful to convert inclusive to exclusive bounds.
+     */
+    addUnits(units: number, encoding: TemporalEncoding): EpochTimestamp;
+    compare(other: EpochTimestamp): number;
+    equals(other?: EpochTimestamp): boolean;
+    toString(): string;
+}

package/types/date/date-utils.d.ts

@@ -5,35 +5,60 @@ export type zeroToFive = 0 | oneToFive;
 export type sixToNine = 6 | 7 | 8 | 9;
 export type zeroToNine = zeroToFive | sixToNine;
 export type oneToNine = oneToFive | sixToNine;
-export type TimeUnit = "hours" | "minutes" | "seconds";
+export type TimeUnit = "hours" | "minutes" | "seconds" | "milliseconds";
 export type Hours = `${0 | 1}${zeroToNine}` | `2${0 | 1 | 2 | 3}`;
 export type Minutes = `${zeroToFive}${zeroToNine}`;
 export type Seconds = `${zeroToFive}${zeroToNine}`;
-export type TimeUnitValue<T extends TimeUnit> = T extends "hours" ? Hours : T extends "minutes" ? Minutes : Seconds;
+export type Milliseconds = `${zeroToNine}${zeroToNine}${zeroToNine}`;
+export type TimeUnitValue<T extends TimeUnit> = T extends "hours" ? Hours : T extends "minutes" ? Minutes : T extends "seconds" ? Seconds : Milliseconds;
 export type TimeString = `${number}${number}:${number}${number}:${number}${number}`;
+/**
+ * A TimeString with millisecond precision, hh:mm:ss.SSS
+ */
+export type TimeStringMillis = `${TimeString}.${number}${number}${number}`;
 type YYYY = `19${zeroToNine}${zeroToNine}` | `20${zeroToNine}${zeroToNine}`;
 type MM = `0${oneToNine}` | `1${0 | 1 | 2}`;
 type DD = `${0}${oneToNine}` | `${1 | 2}${zeroToNine}` | `3${0 | 1}`;
 export type DateStringISO = `${YYYY}-${MM}-${DD}`;
 export declare const zeroTime: TimeString;
+export declare const zeroTimeMillis: TimeStringMillis;
 export declare const zeroTimeUnit: TimeUnitValue<TimeUnit>;
-export declare function incrementTimeUnitValue<T extends TimeUnit>(unit: T, value: TimeUnitValue<T>): TimeUnitValue<T> | Hours;
-export declare function decrementTimeUnitValue<T extends TimeUnit>(unit: T, value: TimeUnitValue<T>): TimeUnitValue<T> | Hours;
-export declare function updateTimeString<T extends TimeUnit>(timeString: TimeString, unit: T, value: TimeUnitValue<T>): TimeString;
+export declare function incrementTimeUnitValue<T extends TimeUnit>(unit: T, value: TimeUnitValue<T>): TimeUnitValue<T>;
+export declare function decrementTimeUnitValue<T extends TimeUnit>(unit: T, value: TimeUnitValue<T>): TimeUnitValue<T>;
+export declare function updateTimeString<S extends TimeString | TimeStringMillis, T extends TimeUnit>(timeString: S, unit: T, value: TimeUnitValue<T>): S;
 export declare const isValidTimeString: (value: unknown) => value is TimeString;
+export declare const isValidTimeStringMillis: (value: unknown) => value is TimeStringMillis;
+/**
+ * Convert a valid TimeString or TimeStringMillis to the required precision.
+ * Milliseconds are added (as 000) or removed as necessary. Returns undefined
+ * if value is not a valid time.
+ */
+export declare function normaliseTimeString(value: unknown, milliseconds: true): TimeStringMillis | undefined;
+export declare function normaliseTimeString(value: unknown, milliseconds?: false): TimeString | undefined;
+export declare function normaliseTimeString(value: unknown, milliseconds?: boolean): TimeString | TimeStringMillis | undefined;
 export declare function asTimeString(value: unknown, allowUndefined: false): TimeString;
 export declare function asTimeString(value: unknown, allowUndefined?: true): TimeString | undefined;
+/**
+ * Millisecond precision equivalent of asTimeString. Accepts a TimeString,
+ * TimeStringMillis or a timestamp (millis since epoch, number or string).
+ */
+export declare function asTimeStringMillis(value: unknown, allowUndefined: false): TimeStringMillis;
+export declare function asTimeStringMillis(value: unknown, allowUndefined?: true): TimeStringMillis | undefined;
 export interface Time {
     hours: number;
     minutes: number;
     seconds: number;
+    milliseconds: number;
     asDate: (date?: Date | DateStringISO) => Date;
 }
-export declare function Time(timeString: TimeString): Time;
+export declare function Time(timeString: TimeString | TimeStringMillis): Time;
 export declare namespace Time {
-    export var millisToTimeString: (timestamp: number) => TimeString;
-    var _a: (hours: number, minutes: number, seconds: number) => TimeString;
-    export { _a as toString };
+    var millisToTimeString: (timestamp: number) => TimeString;
+    var millisToTimeStringMillis: (timestamp: number) => TimeStringMillis;
+    export { timeToString as toString };
     export var isDateInMillis: (dtInMillis: string | number) => boolean;
 }
+declare function timeToString(hours: number, minutes: number, seconds: number): TimeString;
+declare function timeToString(hours: number, minutes: number, seconds: number, milliseconds: number): TimeStringMillis;
+declare function timeToString(hours: number, minutes: number, seconds: number, milliseconds?: number): TimeString | TimeStringMillis;
 export {};

package/types/date/dateTimePattern.d.ts

@@ -1,8 +1,26 @@
-import { DateTimeDataValueDescriptor } from "@vuu-ui/vuu-data-types";
+import type { DataValueDescriptor, DataValueType, DateTimeDataValueDescriptor } from "@vuu-ui/vuu-data-types";
+import { type TemporalKind } from "./temporal";
 import { DateTimePattern } from "./types";
 export declare const defaultPatternsByType: {
     readonly time: "hh:mm:ss";
     readonly date: "dd.mm.yyyy";
 };
 export declare const fallbackDateTimePattern: DateTimePattern;
-export declare function dateTimePattern(type: DateTimeDataValueDescriptor["type"]): DateTimePattern;
+export declare const defaultDateTimePatternByKind: Record<TemporalKind, DateTimePattern>;
+/**
+ * Returns the DateTimePattern configured on the type (formatting.pattern), if
+ * there is one. Otherwise, the default pattern for the temporal kind. If kind
+ * is not provided, it is inferred from type name.
+ */
+export declare function dateTimePattern(type?: DataValueType | DateTimeDataValueDescriptor["type"], kind?: TemporalKind | undefined): DateTimePattern;
+/**
+ * Returns a copy of a temporal descriptor, with its type replaced so that the
+ * value is displayed (or edited) using the given pattern. The type name follows
+ * the pattern: 'date/time' if both date and time are specified, else 'date' or
+ * 'time'. Other formatting (e.g. timeZone, locale) is preserved. The descriptor
+ * is returned unchanged if no pattern is provided or the descriptor is not
+ * temporal.
+ * Use this to present a column differently in different contexts, e.g. a
+ * ColumnFilter using a different pattern to the Table.
+ */
+export declare const withDateTimePattern: <T extends DataValueDescriptor>(descriptor: T, pattern?: DateTimePattern) => T;

package/types/date/formatter.d.ts

@@ -1,9 +1,34 @@
 import { DateFormatter } from "@internationalized/date";
+import type { FractionalSecondDigits } from "@vuu-ui/vuu-table-types";
+import { EpochTimestamp } from "./EpochTimestamp";
+import { type TimeZoneSpec } from "./time-zone";
 import { DateTimePattern } from "./types";
 type DateTimeFormatConfig = {
     locale: string;
     options: Intl.DateTimeFormatOptions;
 };
+export interface DateTimeFormatOptions {
+    /**
+     * Number of sub-second digits to display, when pattern includes time. If
+     * not specified, 3 is used for the 'hh:mm:ss.ms' pattern, otherwise 0.
+     */
+    fractionalSecondDigits?: FractionalSecondDigits;
+    /**
+     * Override the locale implied by the pattern. Pattern then determines the
+     * style of each field, locale determines order and language.
+     */
+    locale?: string;
+    timeZone?: TimeZoneSpec;
+}
+type TimestampFormatter = (ts: EpochTimestamp) => string;
+/**
+ * Create a formatter for EpochTimestamp values. This is the most general
+ * formatter, it supports nanosecond precision.
+ */
+export declare function formatTimestamp({ date, time }: DateTimePattern, { fractionalSecondDigits, locale, timeZone, }?: DateTimeFormatOptions): TimestampFormatter;
+/**
+ * Create a formatter for Date values.
+ */
+export declare function formatDate(pattern: DateTimePattern, options?: DateTimeFormatOptions): (d: Date) => string;
 export declare function getDateFormatter({ locale, options }: DateTimeFormatConfig): DateFormatter;
-export declare function formatDate(pattern: DateTimePattern): (d: Date) => string;
 export {};

package/types/date/index.d.ts

@@ -1,4 +1,8 @@
-export { asTimeString, decrementTimeUnitValue, incrementTimeUnitValue, isValidTimeString, Time, toCalendarDate, type DateStringISO, type Hours, type Minutes, type Seconds, type TimeString, type TimeUnit, type TimeUnitValue, updateTimeString, zeroTime, zeroTimeUnit, } from "./date-utils";
-export { dateTimePattern, defaultPatternsByType, fallbackDateTimePattern, } from "./dateTimePattern";
+export { asTimeString, asTimeStringMillis, decrementTimeUnitValue, incrementTimeUnitValue, isValidTimeString, isValidTimeStringMillis, normaliseTimeString, Time, toCalendarDate, type DateStringISO, type Hours, type Milliseconds, type Minutes, type Seconds, type TimeString, type TimeStringMillis, type TimeUnit, type TimeUnitValue, updateTimeString, zeroTime, zeroTimeMillis, zeroTimeUnit, } from "./date-utils";
+export { dateTimePattern, defaultPatternsByType, fallbackDateTimePattern, withDateTimePattern, } from "./dateTimePattern";
 export * from "./formatter";
 export { dateTimeLabelByType, isDatePattern, isTimePattern, supportedDateTimePatterns, type DatePattern, type DateTimePattern, type TimePattern, } from "./types";
+export { defaultDateTimePatternByKind } from "./dateTimePattern";
+export { EpochTimestamp, type TemporalEncoding } from "./EpochTimestamp";
+export * from "./temporal";
+export * from "./time-zone";

package/types/date/temporal.d.ts

@@ -0,0 +1,68 @@
+import type { DataValueDescriptor, TemporalDataValueTypeSimple } from "@vuu-ui/vuu-data-types";
+import type { FractionalSecondDigits } from "@vuu-ui/vuu-table-types";
+import { EpochTimestamp, type TemporalEncoding } from "./EpochTimestamp";
+import { type TimeZoneSpec } from "./time-zone";
+/**
+ * What a temporal value represents, from the user's perspective
+ * - datetime: a point in time, date and time of day are both meaningful
+ * - date: a calendar date, time of day is not meaningful
+ * - time: a time of day, the date is not meaningful (typically 'today')
+ */
+export type TemporalKind = "datetime" | "date" | "time";
+/**
+ * The finest resolution that the encoding can represent.
+ */
+export type TemporalPrecision = "ms" | "ns";
+export interface TemporalInfo {
+    kind: TemporalKind;
+    encoding: TemporalEncoding;
+    precision: TemporalPrecision;
+    timeZone: TimeZoneSpec;
+}
+export declare const isTemporalTypeName: (typeName?: string) => typeName is TemporalDataValueTypeSimple;
+type TemporalDescriptor = Pick<DataValueDescriptor, "serverDataType" | "type">;
+/**
+ * The single source of truth for whether (and how) a column or form field
+ * holds a temporal value. Rules:
+ *
+ * - encoding is determined by serverDataType
+ *   - epochtimestamp => epochMillis
+ *   - epochtimestampnano => epochNanos
+ *   - long, int, double (or unspecified) => epochMillis, but only when the
+ *     'type' is a temporal type. This legacy usage (pre epochtimestamp) is
+ *     DEPRECATED and supported only for backward compatibility. Timestamps
+ *     should be described by the server as epochtimestamp or epochtimestampnano.
+ * - kind is determined by 'type' ('date/time', 'date', 'time'), default 'datetime'.
+ *   An explicit type of 'number' opts an epochtimestamp column out of temporal
+ *   treatment altogether.
+ * - timeZone from type.formatting.timeZone, falling back to the default time zone
+ *
+ * @returns TemporalInfo or undefined if value is not temporal
+ */
+export declare const getTemporalInfo: (descriptor?: TemporalDescriptor) => TemporalInfo | undefined;
+export declare const isTemporal: (descriptor?: TemporalDescriptor) => boolean;
+export declare const defaultFractionalSecondDigits: (info: Pick<TemporalInfo, "precision">) => FractionalSecondDigits;
+/**
+ * Format a timestamp as a canonical, locale independent, editable string:
+ * - date: yyyy-mm-dd
+ * - datetime: yyyy-mm-dd hh:mm:ss[.fffffffff]
+ * - time: hh:mm:ss[.fffffffff]
+ * Sub-second digits are included only when non zero, up to the precision of
+ * the encoding, so they round-trip unchanged through an edit.
+ */
+export declare const formatTemporalInput: (value: EpochTimestamp | undefined, { kind, precision, timeZone }: Omit<TemporalInfo, "encoding">) => string;
+/**
+ * Parse user input. Accepts the canonical formats produced by
+ * formatTemporalInput as well as raw epoch values (in the encoding of the
+ * column). Where the input does not include a component (e.g the date for a
+ * 'time' value), it is taken from baseValue if provided, otherwise today
+ * (date) or midnight (time).
+ *
+ * @returns EpochTimestamp, or undefined if input is not valid
+ */
+export declare const parseTemporalInput: (input: string, { kind, encoding, precision, timeZone }: TemporalInfo, baseValue?: EpochTimestamp) => EpochTimestamp | undefined;
+/**
+ * Placeholder text describing the canonical input format for a kind.
+ */
+export declare const temporalInputPlaceholder: (kind: TemporalKind) => "hh:mm:ss" | "yyyy-mm-dd" | "yyyy-mm-dd hh:mm:ss";
+export {};

package/types/date/time-zone.d.ts

@@ -0,0 +1,52 @@
+import { CalendarDate } from "@internationalized/date";
+import type { DateStringISO, TimeString } from "./date-utils";
+/**
+ * 'local' (browser time zone), 'UTC' or any IANA time zone identifier.
+ */
+export type TimeZoneSpec = "local" | "UTC" | (string & {});
+/**
+ * Set the time zone used for temporal values where a column does not
+ * specify one explicitly (formatting.timeZone). Default is 'local'.
+ */
+export declare const setDefaultTimeZone: (timeZone: TimeZoneSpec) => void;
+export declare const getDefaultTimeZone: () => TimeZoneSpec;
+/**
+ * Resolve a TimeZoneSpec to an IANA time zone identifier.
+ */
+export declare const resolveTimeZone: (timeZone?: TimeZoneSpec) => string;
+export interface DateTimeFields {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+}
+export declare const getDateTimeFields: (epochMillis: number, timeZone?: TimeZoneSpec) => DateTimeFields;
+/**
+ * Convert wall clock fields in the given time zone to epoch millis. Where the
+ * wall clock time is ambiguous or does not exist (DST transitions), the
+ * 'compatible' disambiguation strategy is used (same as Temporal / JS Date).
+ */
+export declare const fromDateTimeFields: ({ year, month, day, hour, minute, second, millisecond, }: Partial<DateTimeFields> & Pick<DateTimeFields, "year" | "month" | "day">, timeZone?: TimeZoneSpec) => number;
+/**
+ * Epoch millis of the start of the calendar day (in timeZone) that contains epochMillis.
+ */
+export declare const startOfDay: (epochMillis: number, timeZone?: TimeZoneSpec) => number;
+/**
+ * Epoch millis of the start of the calendar day (in timeZone) following the day that
+ * contains epochMillis. This is DST safe, the day may be 23, 24 or 25 hours long.
+ */
+export declare const startOfNextDay: (epochMillis: number, timeZone?: TimeZoneSpec) => number;
+export declare const isStartOfDay: (epochMillis: number, timeZone?: TimeZoneSpec) => boolean;
+/**
+ * A date to which a time of day can be applied. 'today' and 'yesterday' are
+ * resolved at the point of use, so filters that use them remain relative.
+ */
+export type RelativeDate = "today" | "yesterday" | DateStringISO;
+export declare const resolveRelativeDate: (date?: RelativeDate | Date, timeZone?: TimeZoneSpec) => CalendarDate;
+/**
+ * Epoch millis of the given time of day on the given date, in timeZone.
+ */
+export declare const timeOfDayToEpochMillis: (timeString: TimeString | `${TimeString}.${string}`, date?: RelativeDate | Date, timeZone?: TimeZoneSpec) => number;

package/types/filters/filter-utils.d.ts

@@ -26,7 +26,8 @@ export declare const stripFilterFromColumns: (columns: RuntimeColumnDescriptor[]
     allowColumnHeaderMenu?: false;
     colHeaderContentRenderer?: string;
     colHeaderLabelRenderer?: string;
-    exportFormatter?: (value: unknown) => string;
+    exportable?: boolean;
+    exportFormatter?: (value: unknown, row: import("@vuu-ui/vuu-table-types").RowAccessor) => string;
     getIcon?: (row: import("@vuu-ui/vuu-table-types").DataRow) => string | undefined;
     groupable?: boolean;
     hidden?: boolean;
@@ -71,5 +72,9 @@ export declare const stripFilterFromColumns: (columns: RuntimeColumnDescriptor[]
     type?: import("@vuu-ui/vuu-data-types").DataValueType;
 }[];
 export declare const extractFilterForColumn: (filter: Filter | undefined, columnName: string) => Filter | undefined;
+/**
+ * The full-day range used as default value of a time range filter.
+ */
+export declare const getDefaultTimeRange: (column: ColumnDescriptor) => [string, string];
 export declare const getColumnValueFromFilter: (column: ColumnDescriptor, operator: ColumnFilterOp, filter?: FilterContainerFilter) => ColumnFilterValue;
 export declare const filtersAreEqual: (f1: FilterContainerFilter | null | undefined, f2: FilterContainerFilter | null | undefined) => boolean;