@bmsuisse/datagrid 0.37.1 → 0.39.0

package/README.md

@@ -27,6 +27,30 @@ const columns: ColumnDef<Row>[] = [
 <DataGrid columns={columns} dataSource={{ mode: "client", data: rows }} />;
 ```
 
+### Translating the filter UI
+
+Filter widgets ship with English strings. Pass `filterLabels` (a
+`Partial<FilterLabels>`; anything omitted keeps its default from
+`defaultFilterLabels`) to translate them:
+
+```tsx
+import { de } from "date-fns/locale";
+
+<DataGrid
+  columns={columns}
+  dataSource={{ mode: "client", data: rows }}
+  filterLabels={{
+    selectAll: "Alle auswählen",
+    searchPlaceholder: (header) => `${header} suchen…`,
+    filterAriaLabel: (header) => `${header} filtern`,
+    dateLocale: de,
+  }}
+/>;
+```
+
+Widgets rendered outside a `<DataGrid>` read the same labels from a
+`<FilterLabelsProvider labels={…}>`, or take a per-widget `labels` prop.
+
 See [AGENTS.md](../../AGENTS.md) for the full design rationale, and
 `packages/datagrid/demo` for a runnable example against both a SQL and a
 Meilisearch backend.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Locale } from 'date-fns';
 import { ReactNode, ReactElement, MouseEvent, ComponentType, RefObject } from 'react';
 import { ColumnSizingState, RowData } from '@tanstack/react-table';
 export { ColumnSizingState } from '@tanstack/react-table';
@@ -62,6 +63,96 @@ declare function fieldKey(field: string | string[]): string;
  */
 declare function evaluateFilter<TRow>(row: TRow, filter: CompositeFilterDescriptor | FilterDescriptor | null | undefined): boolean;
 
+/**
+ * Every user-facing string the built-in filter widgets (and `<DataGrid>`'s
+ * own header filter trigger) render. This package has no translation/i18n
+ * layer — same convention as `EditingOptions.saveLabel`/`discardLabel`:
+ * you supply already-translated strings (or, for templated ones, a
+ * function) and the English defaults in `defaultFilterLabels` apply to
+ * anything you leave out. See #72.
+ *
+ * Supply them via `<DataGrid filterLabels>`, a `<FilterLabelsProvider>`
+ * around any widgets you render yourself (custom `renderFilter`,
+ * `renderHeader`, standalone use), or a single widget's own `labels` prop —
+ * innermost wins, each merged over the one outside it.
+ */
+interface FilterLabels {
+    /** Accessible name of every filter trigger button (the header funnel icon and each widget's own `bare={false}` trigger). */
+    filterAriaLabel: (header: string) => string;
+    /** EnumFilter search input placeholder. */
+    searchPlaceholder: (header: string) => string;
+    /** EnumFilter "Select all" checkbox label (acts on the currently visible options). */
+    selectAll: string;
+    /** Accessible name of an EnumFilter group header's tri-state checkbox. */
+    selectAllOfGroup: (group: string) => string;
+    /** EnumFilter empty-search message. */
+    noMatches: string;
+    /** EnumFilter `bare={false}` trigger summary once something is selected. */
+    selectedCount: (count: number) => string;
+    stringPlaceholder: (header: string) => string;
+    stringContains: string;
+    stringIs: string;
+    stringStartsWith: string;
+    stringEndsWith: string;
+    /** Accessible name of the StringFilter/NumberComparisonFilter operator dropdown. */
+    operatorAriaLabel: (header: string) => string;
+    booleanAll: string;
+    booleanYes: string;
+    booleanNo: string;
+    /** Accessible name of the BooleanFilter select. */
+    booleanAriaLabel: (header: string) => string;
+    minPlaceholder: string;
+    maxPlaceholder: string;
+    valuePlaceholder: string;
+    /** The small word between the min and max inputs. */
+    rangeSeparator: string;
+    minimumAriaLabel: (header: string) => string;
+    maximumAriaLabel: (header: string) => string;
+    minimumSliderAriaLabel: (header: string) => string;
+    maximumSliderAriaLabel: (header: string) => string;
+    numberGreaterThan: string;
+    numberGreaterThanOrEqual: string;
+    numberLessThan: string;
+    numberLessThanOrEqual: string;
+    numberEquals: string;
+    numberNotEquals: string;
+    numberBetween: string;
+    /** NumberHistogramFilter's clear button. */
+    clear: string;
+    /** NumberHistogramFilter's `loadValues` in-flight message. */
+    loading: string;
+    /** NumberHistogramFilter: `loadValues` rejected. */
+    loadFailed: string;
+    /** NumberHistogramFilter: retry action next to `loadFailed`. */
+    retry: string;
+    dateToday: string;
+    dateLast7Days: string;
+    dateThisMonth: string;
+    dateCustom: string;
+    /**
+     * date-fns locale for DateRangeFilter's calendar (month/weekday names,
+     * first day of week) and its trigger summary. Unset keeps date-fns'/
+     * react-day-picker's own default (en-US), exactly as before.
+     */
+    dateLocale?: Locale;
+}
+/** English defaults — byte-for-byte the strings every widget rendered before `FilterLabels` existed. */
+declare const defaultFilterLabels: FilterLabels;
+/** Merges `overrides` over `base`, ignoring keys explicitly set to `undefined` (so `{ selectAll: maybeT }` never blanks a default). */
+declare function mergeFilterLabels(base: FilterLabels, overrides: Partial<FilterLabels> | undefined): FilterLabels;
+/**
+ * Supplies `labels` to every filter widget below it, merged over any
+ * enclosing provider's (or the English defaults). `<DataGrid filterLabels>`
+ * renders one of these itself; use it directly around widgets you render
+ * outside a `<DataGrid>`.
+ */
+declare function FilterLabelsProvider({ labels, children, }: {
+    labels: Partial<FilterLabels> | undefined;
+    children: ReactNode;
+}): ReactElement;
+/** The effective labels here: context (or defaults), with an optional per-widget `overrides` merged on top. */
+declare function useFilterLabels(overrides?: Partial<FilterLabels>): FilterLabels;
+
 /**
  * Contract every built-in filter widget implements. `TColumn` is narrowed to
  * the specific column shape the widget knows how to render (e.g. `EnumColumn`
@@ -70,11 +161,16 @@ declare function evaluateFilter<TRow>(row: TRow, filter: CompositeFilterDescript
  *
  * `value` is the current FilterDescriptor for this column, or undefined when
  * no filter is applied. `onChange(undefined)` clears the filter entirely.
+ *
+ * `labels` overrides this one widget's user-facing strings, merged over
+ * whatever an enclosing `<FilterLabelsProvider>`/`<DataGrid filterLabels>`
+ * supplies (see `FilterLabels`).
  */
 interface FilterWidgetProps<TColumn> {
     column: TColumn;
     value: FilterDescriptor | undefined;
     onChange: (next: FilterDescriptor | undefined) => void;
+    labels?: Partial<FilterLabels>;
 }
 
 /** Horizontal alignment used for a column's cell content and header. */
@@ -293,7 +389,7 @@ declare function isEditable<TRow>(column: ColumnDef<TRow>, row: TRow): boolean;
  * `bare` doc for why (`renderDefaultFilterWidget` passes this automatically
  * outside `filterDisplay: "row"`).
  */
-declare function BooleanFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<BooleanColumn<TRow>> & {
+declare function BooleanFilter<TRow>({ column, value, onChange, bare, labels: labelOverrides, }: FilterWidgetProps<BooleanColumn<TRow>> & {
     bare?: boolean;
 }): ReactElement;
 
@@ -312,7 +408,7 @@ declare function BooleanFilter<TRow>({ column, value, onChange, bare, }: FilterW
  * `EnumFilter`'s identical `bare` doc for why (`renderDefaultFilterWidget`
  * passes this automatically outside `filterDisplay: "row"`).
  */
-declare function DateRangeFilter<TRow>({ column, value, onChange, today, bare, }: FilterWidgetProps<DateColumn<TRow>> & {
+declare function DateRangeFilter<TRow>({ column, value, onChange, today, bare, labels: labelOverrides, }: FilterWidgetProps<DateColumn<TRow>> & {
     today?: Date;
     bare?: boolean;
 }): ReactElement;
@@ -354,7 +450,7 @@ declare function DateRangeFilter<TRow>({ column, value, onChange, today, bare, }
  * "row"`, so `<DataGrid>`'s own header-icon popover isn't nested inside a
  * second one of this component's own).
  */
-declare function EnumFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<EnumColumn<TRow>> & {
+declare function EnumFilter<TRow>({ column, value, onChange, bare, labels: labelOverrides, }: FilterWidgetProps<EnumColumn<TRow>> & {
     bare?: boolean;
 }): ReactElement;
 
@@ -387,7 +483,7 @@ declare function EnumFilter<TRow>({ column, value, onChange, bare, }: FilterWidg
  * column also sets `filterDisplay: "row"`, where nothing else provides a
  * trigger — see `NumberHistogramFilter`'s identical `bare` doc for why.
  */
-declare function NumberComparisonFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<NumberColumn<TRow>> & {
+declare function NumberComparisonFilter<TRow>({ column, value, onChange, bare, labels: labelOverrides, }: FilterWidgetProps<NumberColumn<TRow>> & {
     bare?: boolean;
 }): ReactElement;
 
@@ -418,7 +514,7 @@ declare function NumberComparisonFilter<TRow>({ column, value, onChange, bare, }
  * (bare: false) is what keeps a plain numeric column from forcing its whole
  * column wider than its data ever needs.
  */
-declare function NumberRangeFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<NumberColumn<TRow>> & {
+declare function NumberRangeFilter<TRow>({ column, value, onChange, bare, labels: labelOverrides, }: FilterWidgetProps<NumberColumn<TRow>> & {
     bare?: boolean;
 }): ReactElement;
 
@@ -498,7 +594,7 @@ type NumberHistogramFilterProps<TRow> = FilterWidgetProps<NumberColumn<TRow>> &
  * `facetedNumberValues(data, column, filter)` in client mode, or supply
  * `loadValues` to fetch the facet from the server in server mode.
  */
-declare function NumberHistogramFilter<TRow>({ column, value, onChange, allValues, loadValues, format, buckets, bare, }: NumberHistogramFilterProps<TRow>): ReactElement;
+declare function NumberHistogramFilter<TRow>({ column, value, onChange, allValues, loadValues, format, buckets, bare, labels: labelOverrides, }: NumberHistogramFilterProps<TRow>): ReactElement;
 
 type FilterNode = FilterDescriptor | CompositeFilterDescriptor;
 /**
@@ -531,7 +627,7 @@ declare function facetedNumberValues<TRow>(data: readonly TRow[], column: Column
  * identical `bare` doc for why (`renderDefaultFilterWidget` passes this
  * automatically outside `filterDisplay: "row"`).
  */
-declare function StringFilter<TRow>({ column, value, onChange, bare, }: FilterWidgetProps<StringColumn<TRow>> & {
+declare function StringFilter<TRow>({ column, value, onChange, bare, labels: labelOverrides, }: FilterWidgetProps<StringColumn<TRow>> & {
     bare?: boolean;
 }): ReactElement;
 
@@ -1391,6 +1487,28 @@ interface ActionsMenuProps<TRow> {
  */
 declare function ActionsMenu<TRow>({ items, ctx, triggerLabel }: ActionsMenuProps<TRow>): ReactElement | null;
 
+/** Structured error shown by the grid's error states. Same shape as `@bmsuisse/ui`'s `ErrorInfo`. */
+interface ErrorInfo {
+    title?: string;
+    message?: string;
+    /** Technical details (stack, response body) — shown behind a "Show details" toggle. */
+    details?: string;
+}
+/** What the grids accept for `error` — pass a TanStack Query / SWR / `catch` error straight through. */
+type ErrorInput = ErrorInfo | Error | string | null | undefined | false;
+declare function toErrorInfo(error: unknown): ErrorInfo | undefined;
+/** User-facing strings of the grid's loading/error/empty states. Anything omitted keeps its English default. */
+interface GridStatusLabels {
+    loading: string;
+    noResults: string;
+    errorTitle: string;
+    retry: string;
+    showDetails: string;
+    /** TreeDataGrid: shown on a node whose lazy children failed to load. */
+    nodeLoadFailed: string;
+}
+declare const defaultGridStatusLabels: GridStatusLabels;
+
 /**
  * `"client"`: the grid owns filtering/sorting/pagination and evaluates them
  * in-memory against the full `data` array (via `evaluateFilter`).
@@ -1445,6 +1563,17 @@ interface DataGridProps<TRow> {
      * The two are OR'd together if both happen to be set. Defaults to `false`.
      */
     loading?: boolean;
+    /**
+     * The data fetch failed. With no rows to show, the body is replaced by an error
+     * state (title, message, collapsible details, Retry); with stale rows still shown,
+     * they stay and a slim error banner appears above them. Accepts a string, an
+     * `Error` (message + stack as details) or `{ title, message, details }`.
+     */
+    error?: ErrorInput;
+    /** Shows a Retry action in the error state/banner. */
+    onRetry?: () => void;
+    /** Overrides the grid's "Loading...", "No results." and error-state strings. */
+    statusLabels?: Partial<GridStatusLabels>;
     /** Per-row kebab menu. Evaluated with `ctx.row` set to that row. */
     rowActions?: MenuItem<TRow>[];
     /** Toolbar menu above the table. Evaluated with `ctx.selectedRows` set. */
@@ -1690,6 +1819,15 @@ interface DataGridProps<TRow> {
      * See `CellEditingOptions` for the full contract.
      */
     cellEditing?: CellEditingOptions<TRow>;
+    /**
+     * Overrides the user-facing strings of every column-filter UI this grid
+     * renders — the header filter trigger's accessible name and every
+     * built-in filter widget (including ones a column's own `renderFilter`
+     * renders, via context). Anything omitted keeps its English default from
+     * `defaultFilterLabels`, so leaving this unset changes nothing. See
+     * `FilterLabels` for every key (#72).
+     */
+    filterLabels?: Partial<FilterLabels>;
 }
 
 /**
@@ -1700,7 +1838,7 @@ interface DataGridProps<TRow> {
  * (`"server"`). Column filter UI defaults to the type-appropriate widget
  * from `src/filter` unless a column supplies its own `cell` renderer.
  */
-declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, onGridStateChange, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, cellEditing, }: DataGridProps<TRow>): ReactElement;
+declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, onGridStateChange, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, error, onRetry, statusLabels, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, cellEditing, filterLabels, }: DataGridProps<TRow>): ReactElement;
 
 interface GridStateController {
     state: GridState;
@@ -1884,6 +2022,16 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
      * Defaults to `false`.
      */
     loading?: boolean;
+    /**
+     * The root data fetch failed. With no rows, the body shows an error state (title,
+     * message, collapsible details, Retry); with rows, they stay and a slim banner
+     * appears above. Per-node lazy-load failures are handled separately (inline, per row).
+     */
+    error?: ErrorInput;
+    /** Shows a Retry action in the error state/banner. */
+    onRetry?: () => void;
+    /** Overrides the grid's "Loading...", "No results." and error-state strings. */
+    statusLabels?: Partial<GridStatusLabels>;
     /**
      * The column whose cell gets the depth indentation + expand/collapse
      * chevron prepended. Defaults to the first column in `columns`.
@@ -2115,7 +2263,7 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
  * column's cell matches `treeColumnId` (defaults to `columns[0]`); every
  * other column renders exactly like it would in `<DataGrid>`.
  */
-declare function TreeDataGrid<TRow>({ columns, data, loading, treeColumnId, columnVisibility, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, testId, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, }: TreeDataGridProps<TRow>): ReactElement;
+declare function TreeDataGrid<TRow>({ columns, data, loading, error, onRetry, statusLabels, treeColumnId, columnVisibility, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, testId, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, }: TreeDataGridProps<TRow>): ReactElement;
 
 interface FlatTreeRow<TRow> {
     row: TRow;
@@ -2171,4 +2319,4 @@ interface UseTreeStateOptions<TRow> extends TreeAccessors<TRow> {
  */
 declare function useTreeState<TRow>({ data, getRowId, getChildren, hasChildren, onLoadChildren, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, }: UseTreeStateOptions<TRow>): TreeStateController<TRow>;
 
-export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanEditor, BooleanFilter, type CellAddress, type CellChange, type CellEditingCellContext, type CellEditingOptions, type CellEditingState, type CellRange, type CellSelectionController, type CellSelectionOptions, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, EditingBar, type EditingBarProps, type EditingCellContext, type EditingOptions, type EditingState, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type GroupExpansionController, type MenuItem, type MenuItemContext, MultilineStringEditor, type NavigationDirection, type NormalizedRange, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, SelectionOverlay, type SortDescriptor, type StickyGroupHeaderTop, type StringColumn, StringEditor, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, applyColumnOrder, buildIndexMap, canHideColumn, canHideGroup, cellsInRange, coerceValueForColumn, computeFillChanges, countVisible, defaultAlign, defaultFormat, editErrorId, evaluateFilter, extendRangeForFill, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isCellInRange, isColumnVisible, isCompositeFilterDescriptor, isEditable, isFilterDescriptor, isFilterable, isSortable, moveColumnBefore, normalizeRange, orderStorageKeyFor, parseTsv, processClientData, rangeToTsv, renderCellModeCell, renderDefaultEditWidget, renderDefaultFilterWidget, renderEditableCell, resolveMenuItems, storageKeyFor, toDate, useCellEditingState, useCellSelection, useDebouncedCallback, useEditingState, useGridState, useGroupExpansion, useStickyGroupHeaderTop, useTreeState, useVisibleColumns };
+export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanEditor, BooleanFilter, type CellAddress, type CellChange, type CellEditingCellContext, type CellEditingOptions, type CellEditingState, type CellRange, type CellSelectionController, type CellSelectionOptions, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, EditingBar, type EditingBarProps, type EditingCellContext, type EditingOptions, type EditingState, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type ErrorInfo, type ErrorInput, type FilterDescriptor, type FilterLabels, FilterLabelsProvider, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type GridStatusLabels, type GroupExpansionController, type MenuItem, type MenuItemContext, MultilineStringEditor, type NavigationDirection, type NormalizedRange, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, SelectionOverlay, type SortDescriptor, type StickyGroupHeaderTop, type StringColumn, StringEditor, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, applyColumnOrder, buildIndexMap, canHideColumn, canHideGroup, cellsInRange, coerceValueForColumn, computeFillChanges, countVisible, defaultAlign, defaultFilterLabels, defaultFormat, defaultGridStatusLabels, editErrorId, evaluateFilter, extendRangeForFill, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isCellInRange, isColumnVisible, isCompositeFilterDescriptor, isEditable, isFilterDescriptor, isFilterable, isSortable, mergeFilterLabels, moveColumnBefore, normalizeRange, orderStorageKeyFor, parseTsv, processClientData, rangeToTsv, renderCellModeCell, renderDefaultEditWidget, renderDefaultFilterWidget, renderEditableCell, resolveMenuItems, storageKeyFor, toDate, toErrorInfo, useCellEditingState, useCellSelection, useDebouncedCallback, useEditingState, useFilterLabels, useGridState, useGroupExpansion, useStickyGroupHeaderTop, useTreeState, useVisibleColumns };