@jielga/tmdatagrid 2.3.0 → 2.5.0

package/src/core/valueText.ts

@@ -0,0 +1,46 @@
+import type { TMDataGridOption } from "./columnOptions";
+import type { TMDataGridColumnType } from "./filterOperators";
+import type { TMDataGridLabels } from "./labels";
+
+/** The English boolean labels - the defaults `TMDATAGRID_LABELS_EN` takes. */
+export const BOOLEAN_LABELS_EN = {
+  booleanTrue: "Yes",
+  booleanFalse: "No",
+} as const satisfies Pick<TMDataGridLabels, "booleanTrue" | "booleanFalse">;
+
+export type TMDataGridValueTextOptions = {
+  /** The column's `meta.type`. A `boolean` column's `"true"` / `"false"` filter strings read as booleans. */
+  type?: TMDataGridColumnType;
+  /** The column's resolved options: a value with an option reads as its label. */
+  options?: ReadonlyArray<TMDataGridOption>;
+  /** What `true` and `false` read as. Defaults to English. */
+  labels?: Pick<TMDataGridLabels, "booleanTrue" | "booleanFalse">;
+};
+
+/**
+ * A value as the grid's chrome writes it in words - on a filter pill, in a
+ * group row - rather than `String(value)`, which writes `true`, an option's
+ * key instead of its label, and a `Date` as an English timestamp.
+ */
+export function formatValueText(
+  value: unknown,
+  { type, options, labels = BOOLEAN_LABELS_EN }: TMDataGridValueTextOptions = {},
+): string {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => formatValueText(entry, { type, options, labels }))
+      .join(", ");
+  }
+  if (value === true || (type === "boolean" && value === "true")) {
+    return labels.booleanTrue;
+  }
+  if (value === false || (type === "boolean" && value === "false")) {
+    return labels.booleanFalse;
+  }
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "" : value.toLocaleDateString();
+  }
+  const text = String(value);
+  const option = options?.find((candidate) => candidate.value === text);
+  return option?.label ?? text;
+}

package/src/index.ts

@@ -110,6 +110,8 @@ export {
   type TMDataGridEditRowProjection,
   type TMDataGridEditRowSnapshot,
   type TMDataGridEditState,
+  type TMDataGridEditCommitMap,
+  type TMDataGridEditCommitMapArgs,
   type TMDataGridEditValueMap,
   type TMDataGridEditValueMapArgs,
   type TMDataGridFieldValidate,
@@ -264,6 +266,19 @@ export {
   type TMDataGridStorageMode,
   type TMDataGridUrlStorage,
 } from "./core/persistence";
+export {
+  createTMDataGridUrlState,
+  type TMDataGridColumnInfo,
+  type TMDataGridColumnInfoOf,
+  type TMDataGridDateInput,
+  type TMDataGridTypedColumn,
+  type TMDataGridUrlFiltersInput,
+  type TMDataGridUrlInput,
+  type TMDataGridUrlPayload,
+  type TMDataGridUrlSearchStorage,
+  type TMDataGridUrlSortableId,
+  type TMDataGridUrlState,
+} from "./core/urlState";
 export type {
   TMDataGridCellEventArgs,
   TMDataGridRowContextMenuArgs,

package/src/useTMDataGrid.tsx

@@ -77,6 +77,7 @@ import {
 import {
   emptyValueForOperator,
   type TMDataGridColumnType,
+  type TMDataGridFilterOperator,
   tmDataGridFilterFn,
 } from "./core/filterOperators";
 import {
@@ -137,6 +138,12 @@ import {
   type TMDataGridQueryTable,
 } from "./core/pageReset";
 import type { TMDataGridCellRange } from "./core/cellRange";
+import type {
+  TMDataGridAccessorColumnId,
+  TMDataGridColumnInfoHints,
+  TMDataGridColumnInfoOf,
+  TMDataGridTypedColumn,
+} from "./core/urlState";
 import {
   resolveExportOptions,
   type TMDataGridExportOptions,
@@ -361,6 +368,13 @@ type WithRowTypedMeta<TDef, TData extends RowData> = TDef extends unknown
  * TanStack's column helper with `meta` typed against `TData`, so the
  * `meta.options` and `meta.edit.enabled` callbacks receive
  * `Row<TMDataGridFeatures, TData>`.
+ *
+ * Every column it returns also carries `TMDataGridColumnInfo` in its type,
+ * read from the literal values of `id`, `meta.type`,
+ * `meta.filter.operators`, `meta.filter.url`, `enableColumnFilter` and
+ * `enableSorting`. `createTMDataGridUrlState` reads it to type the links into
+ * the grid. TanStack's own return type keeps none of this: it types
+ * `accessorKey` as a plain string.
  */
 export type TMDataGridColumnHelper<TData extends RowData> = {
   accessor: <
@@ -370,6 +384,12 @@ export type TMDataGridColumnHelper<TData extends RowData> = {
       : TAccessor extends DeepKeys<TData>
         ? DeepValue<TData, TAccessor>
         : never,
+    const TId extends string = never,
+    TType extends TMDataGridColumnType = "string",
+    TOperator extends TMDataGridFilterOperator = TMDataGridFilterOperator,
+    TFilterable extends boolean = true,
+    TSortable extends boolean = true,
+    TUrl extends boolean = true,
   >(
     accessor: TAccessor,
     column: WithRowTypedMeta<
@@ -377,20 +397,43 @@ export type TMDataGridColumnHelper<TData extends RowData> = {
         ? DisplayColumnDef<TMDataGridFeatures, TData, TValue>
         : IdentifiedColumnDef<TMDataGridFeatures, TData, TValue>,
       TData
-    >,
-  ) => TAccessor extends AccessorFn<TData>
+    > &
+      TMDataGridColumnInfoHints<
+        TId,
+        TType,
+        TOperator,
+        TFilterable,
+        TSortable,
+        TUrl
+      >,
+  ) => (TAccessor extends AccessorFn<TData>
     ? AccessorFnColumnDef<TMDataGridFeatures, TData, TValue>
-    : AccessorKeyColumnDef<TMDataGridFeatures, TData, TValue>;
+    : AccessorKeyColumnDef<TMDataGridFeatures, TData, TValue>) &
+    TMDataGridTypedColumn<{
+      id: TMDataGridAccessorColumnId<TAccessor, TId>;
+      type: TType;
+      value: TValue;
+      operators: TOperator;
+      filterable: TFilterable;
+      sortable: TSortable;
+      url: TUrl;
+    }>;
   columns: ColumnHelper<TMDataGridFeatures, TData>["columns"];
   display: (
     column: WithRowTypedMeta<DisplayColumnDef<TMDataGridFeatures, TData>, TData>,
   ) => DisplayColumnDef<TMDataGridFeatures, TData, unknown>;
-  group: (
+  /** A header group. Carries the column info of every column under it. */
+  group: <
+    const TChildren extends ReadonlyArray<
+      ColumnDef<TMDataGridFeatures, TData, any>
+    >,
+  >(
     column: WithRowTypedMeta<
-      GroupColumnDef<TMDataGridFeatures, TData, unknown>,
+      Omit<GroupColumnDef<TMDataGridFeatures, TData, unknown>, "columns">,
       TData
-    >,
-  ) => GroupColumnDef<TMDataGridFeatures, TData, unknown>;
+    > & { columns: TChildren },
+  ) => GroupColumnDef<TMDataGridFeatures, TData, unknown> &
+    TMDataGridTypedColumn<TMDataGridColumnInfoOf<TChildren[number]>>;
 };
 
 export function createTMDataGridColumnHelper<
@@ -734,7 +777,7 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * One TanStack Form per editing row; drafts survive scrolling because the
  * forms live outside the DOM, keyed by row id. Which columns edit, and with
  * what, is declared per column under `meta.edit`: `meta.type` picks the
- * built-in editor, and `enabled`, `field`, `editor`, `validate` and `mapValue`
+ * built-in editor, and `enabled`, `field`, `editor`, `validate`, `mapValue` and `mapCommitValue`
  * override the rest.
  */
 export type TMDataGridEditingOptions<TData extends RowData> =