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

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

@@ -1,7 +1,7 @@
 import type { RemoteModuleConnection, TableSchema } from "@vuu-ui/vuu-data-types";
 import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
 import type { ListOption } from "@vuu-ui/vuu-table-types";
-import { type ReactElement } from "react";
+import React, { type ReactElement } from "react";
 export type PathMap = {
     [key: string]: string;
 };
@@ -28,6 +28,20 @@ export interface DynamicFeatureProps<P extends object | undefined = object> {
     title?: string;
     width?: number;
 }
+export type FeatureModule = {
+    default: React.ComponentType<object>;
+};
+export type FeatureImporter = (url: string) => Promise<FeatureModule>;
+declare const importFeatureByUrl: FeatureImporter;
+/**
+ * By default, a dynamic feature is loaded from its url with a native
+ * dynamic import. An application that bundles its features can install
+ * an importer that resolves feature urls to bundled modules. Use
+ * `importFeatureByUrl` as a fallback for unknown urls.
+ */
+export declare const setFeatureImporter: (importer: FeatureImporter) => void;
+export declare const importFeature: (url: string) => Promise<FeatureModule>;
+export { importFeatureByUrl };
 declare global {
     const vuuConfig: Promise<VuuConfig>;
 }

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;

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