@bmsuisse/datagrid 0.37.0 → 0.38.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,92 @@ 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;
+    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 +157,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 +385,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 +404,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 +446,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 +479,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 +510,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 +590,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 +623,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;
 
@@ -1690,6 +1782,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 +1801,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, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, cellEditing, filterLabels, }: DataGridProps<TRow>): ReactElement;
 
 interface GridStateController {
     state: GridState;
@@ -2171,4 +2272,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 FilterDescriptor, type FilterLabels, FilterLabelsProvider, 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, defaultFilterLabels, defaultFormat, 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, useCellEditingState, useCellSelection, useDebouncedCallback, useEditingState, useFilterLabels, useGridState, useGroupExpansion, useStickyGroupHeaderTop, useTreeState, useVisibleColumns };