@updog/data-editor 0.1.85 → 0.1.87

package/index.d.ts

@@ -67,6 +67,8 @@ declare var export_default = {
       clearField: "Clear field",
       showPassword: "Show password",
       hidePassword: "Hide password",
+      switchToAm: "Switch to AM",
+      switchToPm: "Switch to PM",
     },
     select: {
       noResults: "No results",
@@ -414,10 +416,12 @@ declare var export_default = {
       invalidFormat: "Invalid format",
       invalidNumber: "Invalid number",
       invalidOption: "Invalid option",
+      invalidTime: "Invalid time",
       outOfRange: "Out of range",
       required: "This field is required",
       structuralMismatch: "This might be in the wrong column.",
       tooManyDecimals: "Too many decimal places",
+      tooPreciseTime: "Too precise for this column",
       valueMustBeUnique: "Value must be unique",
     },
     license: {
@@ -575,6 +579,58 @@ declare var export_default = {
 
 type PluralSuffixes = "_zero" | "_one" | "_two" | "_few" | "_many" | "_other";
 
+/**
+ * Strips plural suffixes from a key to get the base form.
+ * e.g. "createRows_one" → "createRows", "createRows_other" → "createRows"
+ */
+type StripPluralSuffix<K extends string> =
+  K extends `${infer Base}${PluralSuffixes}` ? Base : K;
+
+/**
+ * Recursively derives dot-separated keys from a nested object type.
+ * - Plural keys (e.g. `createRows_one`, `createRows_other`) are collapsed to their base (`createRows`).
+ * - `Record<string, string>` leaf nodes (like `calendar.months`) are treated as terminal.
+ */
+type NestedKeyOf<T, Prefix extends string = ""> =
+  T extends Record<string, unknown>
+    ? string extends keyof T
+      ? Prefix extends ""
+        ? never
+        : Prefix
+      : {
+          [K in keyof T & string]: T[K] extends Record<string, unknown>
+            ? string extends keyof T[K]
+              ?
+                  | (Prefix extends ""
+                      ? StripPluralSuffix<K>
+                      : `${Prefix}.${StripPluralSuffix<K>}`)
+                  | NestedKeyOf<
+                      T[K],
+                      Prefix extends ""
+                        ? StripPluralSuffix<K>
+                        : `${Prefix}.${StripPluralSuffix<K>}`
+                    >
+              : NestedKeyOf<
+                  T[K],
+                  Prefix extends ""
+                    ? StripPluralSuffix<K>
+                    : `${Prefix}.${StripPluralSuffix<K>}`
+                >
+            : Prefix extends ""
+              ? StripPluralSuffix<K>
+              : `${Prefix}.${StripPluralSuffix<K>}`;
+        }[keyof T & string]
+    : never;
+
+/** Union of all valid translation keys derived from the English locale. */
+type TranslationKeys = NestedKeyOf<typeof export_default>;
+
+/** Typed translation function. Accepts typed keys with autocomplete, and dynamic strings as fallback. */
+type TFunction = (
+  key: TranslationKeys | (string & {}),
+  options?: Record<string, unknown>,
+) => string;
+
 /** Makes all properties optional recursively. */
 type DeepPartial<T> = {
   [P in keyof T]?: T[P] extends Record<string, unknown>
@@ -656,6 +712,11 @@ type Filters = {
         min?: string;
         max?: string;
     }>;
+    /** Per-column time-of-day range filters. Key = column ID, values are canonical times. */
+    columnTimeRangeFilters: Record<string, {
+        min?: string;
+        max?: string;
+    }>;
 };
 
 /**
@@ -700,6 +761,16 @@ type TextEditorCell = {
 type DateEditorCell = {
     type: "date";
 };
+/** Time-of-day cell. Bounds come from the column's `{ type: "time" }` validator. */
+type TimeEditorCell = {
+    type: "time";
+    /**
+     * The clock the cell draws, `h23` for `18:00` and `h12` for `6:00 PM`.
+     * Defaults to the clock the reader's own browser uses. Whichever is drawn,
+     * both forms stay readable when the person types.
+     */
+    hourCycle?: "h12" | "h23";
+};
 /** Dropdown select cell. The user picks from a fixed list of options. */
 type SelectEditorCell = {
     type: "select";
@@ -734,11 +805,12 @@ type NumberEditorCell = {
  *
  * - `"text"` — plain text input (default).
  * - `"date"` — date picker; the calendar honours the column's date validator bounds.
+ * - `"time"` — plain text input for a time of day; the column is checked against `{ type: "time" }`.
  * - `"select"` — dropdown with a fixed list of options.
  * - `"multiselect"` — dropdown allowing zero or more options; stored as `string[]`.
  * - `"number"` — number input with locale-aware formatting.
  */
-type CellEditor = TextEditorCell | DateEditorCell | SelectEditorCell | MultiSelectEditorCell | NumberEditorCell;
+type CellEditor = TextEditorCell | DateEditorCell | TimeEditorCell | SelectEditorCell | MultiSelectEditorCell | NumberEditorCell;
 /** Dropdown filter shown in the sidebar Filters panel. */
 type SelectColumnFilter = {
     type: "select";
@@ -763,14 +835,21 @@ type DateRangeColumnFilter = {
     /** Label displayed above the filter. */
     label?: string;
 };
+/** Time-of-day min/max range filter shown in the sidebar Filters panel. */
+type TimeRangeColumnFilter = {
+    type: "time-range";
+    /** Label displayed above the filter. */
+    label?: string;
+};
 /**
  * Filter control shown in the sidebar Filters panel for a column.
  *
  * - `"select"` — dropdown to pick one or more values.
  * - `"number-range"` — two inputs for min and max number.
  * - `"date-range"` — two date pickers for start and end date.
+ * - `"time-range"` — two time fields for the earliest and latest time of day.
  */
-type ColumnFilter = SelectColumnFilter | NumberRangeColumnFilter | DateRangeColumnFilter;
+type ColumnFilter = SelectColumnFilter | NumberRangeColumnFilter | DateRangeColumnFilter | TimeRangeColumnFilter;
 /** Lock mode for a column. `"all"` locks for every row; `"default"` locks only default-source rows. */
 type ColumnLockMode = "all" | "default";
 /**
@@ -806,8 +885,21 @@ type DataEditorColumn = {
     /** Format the display value without changing stored data. E.g. add `$` prefix. */
     formatter?: (value: string) => string;
     /**
-     * Transform a value before it enters the store. Runs when rows are uploaded
-     * to the data editor.
+     * Transform a value on its way into the store. Runs on every value arriving
+     * from outside the editor, so `loadData`, a file import, a remote source, a
+     * custom format, and a paste of text from another app all call it. A value
+     * moving inside the grid is left alone, so a manual edit, a fill, a paste of
+     * cells copied from the grid itself, undo, and redo never call it.
+     *
+     * The value arrives in the shape the cell is stored in. Numbers and dates
+     * canonicalize first, and a `select` value resolves through value matching
+     * first, so the transformer sees the option the user confirmed. On a
+     * `multiselect` column it runs once per token, the way `formatter` already
+     * reads that column. A token it empties leaves the list, and two tokens it
+     * makes equal collapse into one.
+     *
+     * It runs before validation, so a transformer that moves a value outside
+     * `editor.options` makes its own column fail a `oneOf` rule.
      */
     transformer?: (value: unknown) => unknown;
     /** How the cell is edited. Defaults to text input. */
@@ -832,6 +924,8 @@ type DataEditorColumn = {
     locked?: boolean | ColumnLockMode;
 };
 
+/** How precisely a time-of-day column is written. */
+type TimePrecision = "minutes" | "seconds" | "milliseconds";
 /**
  * A built-in declarative validator — a declarative object the SDK interprets.
  */
@@ -864,6 +958,15 @@ type BuiltInValidator = {
     min?: string;
     max?: string;
     message?: string;
+} | {
+    type: "time";
+    /** Inclusive lower bound, canonical, any of the three precisions. */
+    min?: string;
+    /** Inclusive upper bound, canonical, any of the three precisions. */
+    max?: string;
+    /** The finest the column is written. A value carrying more is flagged, never trimmed. */
+    precision?: TimePrecision;
+    message?: string;
 } | {
     type: "unique";
     message?: string;
@@ -1140,6 +1243,54 @@ declare class ErrorHandler {
     handleError(error: UpdogError): void;
 }
 
+/**
+ * The parts of a column every cell type reads. Both `DataEditorColumn` and
+ * `NormalizedColumn` satisfy it, so core and the UI pass the column they hold.
+ */
+type TypedColumn = Pick<DataEditorColumn, "id" | "editor" | "formatter">;
+type ColumnFormat = {
+    readonly typeId: string;
+    readonly candidateId: string;
+};
+
+type FormatScope = string;
+type FormatField = {
+    key: string;
+    column: TypedColumn;
+};
+type AmbiguousColumn = {
+    field: string;
+    applied: ColumnFormat;
+    candidates: readonly ColumnFormat[];
+    samples: readonly string[];
+};
+type FormatBatch = {
+    reader(key: string): (value: unknown) => unknown;
+    ambiguous: readonly AmbiguousColumn[];
+};
+/**
+ * The one door every reading of raw text goes through. The verdict lives on
+ * the pair of scope and column, so a column is never read by its neighbour's
+ * verdict and a neighbouring source starts its own vote.
+ *
+ * The locale fallback needs no branch of its own: a tie falls to the first
+ * candidate in declared order, and the lists are ordered so the reader's own
+ * locale sits first among its peers.
+ */
+declare class FormatGate {
+    private deps;
+    private memory;
+    constructor(deps: {
+        columns: () => readonly TypedColumn[];
+        i18n: () => {
+            locale: string;
+            t: TFunction;
+        } | null;
+    });
+    prepare(scope: FormatScope, rows: readonly Record<string, unknown>[], fields?: readonly FormatField[]): FormatBatch;
+    forget(scope?: FormatScope): void;
+}
+
 type FormulaCellContext = {
     value: unknown;
     field: string;
@@ -1239,6 +1390,7 @@ type NormalizedColumn = Omit<DataEditorColumn, "validators"> & {
     asyncConfig?: AsyncFunctionValidator[];
     numberConfig?: NumberConfig;
     dateConfig?: DateConfig;
+    timeConfig?: TimeConfig;
 };
 type NumberConfig = {
     min?: number;
@@ -1249,6 +1401,11 @@ type DateConfig = {
     min?: string;
     max?: string;
 };
+type TimeConfig = {
+    min?: string;
+    max?: string;
+    precision?: TimePrecision;
+};
 
 type PrimaryKeyInput = string | readonly string[];
 
@@ -1848,6 +2005,8 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     readonly formulaRegistry: FormulaRegistry;
     private _isLoading;
     private sourceManager;
+    /** The format verdict of every source and column pair that has one. */
+    readonly formats: FormatGate;
     readonly sourceLifecycle: SourceLifecycle<TRow>;
     private dirtyTracker;
     private filterEngine;
@@ -1887,10 +2046,15 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     private filterRowReader;
     private bulkMutationHost;
     private orchestrator;
+    private i18n;
     constructor(errorHandler?: ErrorHandler);
     getRowId(index: number): TRowId | undefined;
     getLocalRowCount(): number;
     setValidator(validator: IValidator<TRow>): void;
+    setI18n(i18n: {
+        t: TFunction;
+        locale: string;
+    }): void;
     isColumnLocked(field: string): boolean;
     isColumnPreLocked(field: string): boolean;
     lockColumn(field: string, mode?: ColumnLockMode): void;
@@ -2006,9 +2170,50 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
      * has already normalised through buildImportRow — never transforms twice.
      */
     appendClientRows(sourceId: DataSourceId, newRows: TRow[]): TRowId[];
+    private formatContext;
+    /**
+     * A column nothing separated is a signal to whoever integrated the SDK, so
+     * it goes out in English through `onError` rather than to the person at the
+     * screen. The wizard could ask which shape instead; the seam is here and
+     * the dialog is out of scope (spec section 10).
+     */
+    private reportAmbiguity;
+    /**
+     * The column's reader with no verdict behind it. A formula result is one
+     * value, so there is nothing to vote on; the reader is here to give the
+     * column's storage shape, which for a number means digits rather than an
+     * exponent or a JS number.
+     */
+    private fieldReader;
+    /**
+     * The column's own reader over values an assistant produced. There is no
+     * column of file text to vote on here, so the reader runs without a verdict,
+     * the same way a formula result is read: it gives the value the shape its
+     * column stores rather than a JS number or an exponent. A value that reads
+     * back onto what the cell already holds leaves the delta, so an untouched
+     * cell stays untouched.
+     */
+    private readChatDeltas;
     private normalizeClientRows;
     appendRows(sourceId: DataSourceId, newRows: TRow[], rowIdMap?: Map<number, TRowId>): TRowId[];
-    seedInitialChanges(assignedRowIds: TRowId[], currentRows: TRow[], changes: InitialRowChange<TRow>[]): void;
+    /**
+     * The declared transformers, resolved once so a per-row loop never rescans
+     * the column list.
+     */
+    private collectTransformers;
+    /**
+     * Runs the column transformers over a partial row the client states as a
+     * baseline, so it is compared against the stored row in the same shape the
+     * stored row was written in.
+     */
+    private transformClientValues;
+    /**
+     * Reads a stated original the way the row itself was read, then transforms
+     * it. The verdict is already in the gate's memory from the append that put
+     * these rows in, so an empty batch reuses it rather than voting again.
+     */
+    private normalizeClientValues;
+    seedInitialChanges(sourceId: DataSourceId, assignedRowIds: TRowId[], currentRows: TRow[], changes: InitialRowChange<TRow>[]): void;
     upsertRows(sourceId: DataSourceId, newRows: TRow[], options?: UpsertOptions): UpsertResult<TRow>;
     private getAnchorMap;
     private clearAnchorMapCache;
@@ -2194,7 +2399,7 @@ type ColumnDelta = {
 
 /** Numeric row identifier. V8 stores small integers (Smi) inline — no heap allocation. */
 type TRowId = number;
-type SortType = "text" | "number" | "date";
+type SortType = "text" | "number" | "date" | "time";
 
 /** A pointer to a specific cell in the grid. */
 type CellLocation = {