@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/docs/datagrid-filtering.md

@@ -0,0 +1,455 @@
+# DataGrid: Filtering and search
+
+> DataGrid · @motifx-community/ui 0.1.0-beta.0
+
+## Filters
+
+The filter row has a cell per column: a condition chosen in the cell, by the column type (contains, starts with, =, <, between, empty…), and the kit's field for the value; typing applies after a short pause. The header filter lists the column's values with their counts, honoring the other filters: rows in memory are counted by the grid, an adapter that groups is asked with `group`, any other server answers `loadValues`. Both feed the data source's filter (`data.where`, `data.and`, `data.or`), together with AND.
+
+```tsx
+/** An order, as the examples' made-up server keeps it. */
+export interface Order {
+  id: number;
+  customer: string;
+  city: string;
+  date: string;
+  status: string;
+  paid: boolean;
+  amount: number;
+  note: string;
+}
+```
+
+## Filter panel and builder
+
+`settings.filterPanel` puts a panel under the rows that reads the filter value as text — `[City] Equals 'Ankara' And [Amount] Is greater than '900.00'`, in the columns' titles, formats and lookup texts. Pressing it opens the kit's [FilterBuilder](filterbuilder.md) in a modal window on every column (`filterBuilder` per column turns one off), with “is any of” and “is none of” for each; OK makes its value the filter value, Cancel and Escape leave it. The check box turns the filter value off and on, Clear takes it away.
+
+With `filterSyncEnabled` (on while the panel shows) the filter row and the header filters are part of the filter value: a condition the builder sets shows in the column's cell or its value list when they can show it (one each), and what they set reads in the panel and opens in the builder. Conditions they cannot show — an OR group, a second condition on a column — stay in the filter value only. The filter goes to the data source as any other: here 100,000 orders on a server, or 200 in memory. The layout kept with `layoutKey`, and `state()`, keep the filter value and the check box.
+
+```tsx
+import { data } from '@motifx-community/data';
+
+/** Rows in memory that answer a little later, the way a server does; for the examples. */
+export class SlowAdapter<T extends object, K> extends data.ArrayAdapter<T, K> {
+  constructor(
+    options: data.ArrayAdapterOptions<T>,
+    private readonly delayMs = 300,
+  ) {
+    super(options);
+  }
+
+  override async load(options: data.LoadOptions = {}): Promise<data.LoadResult<T>> {
+    await new Promise((done) => setTimeout(done, this.delayMs));
+    return super.load(options);
+  }
+}
+```
+
+| Option | What it does |
+| --- | --- |
+| `settings.filterPanel` | The panel under the rows: the check box, the filter as text (pressing it opens the builder), “Create Filter” while there is none, and “Clear”. `boolean`, default `false`. |
+| `settings.filterSyncEnabled` | The filter row and the header filters are part of the filter value, both ways. `'auto'`: while the panel shows. `boolean \| 'auto'`, default `'auto'`. |
+| `settings.filterBuilder, column `filterBuilder`` | The column is a field of the builder. `boolean`, default `true`. |
+| `filterValue` | The filter value; a function is followed, the user's changes come in `onFilterChanged` (`e.filterValue`). Also a property. `Bind<data.FilterExpression \| null>`, default `null`. |
+| `filterEnabled` | Whether the filter value applies: the panel's check box. Also a property. `Bind<boolean>`, default `true`. |
+| `filterPanelText` | The panel's text, from the one it would show. `({ text, filterValue }) => string`. |
+| `filterBuilder` | Any prop of `FilterBuilder` but `value` and `fields` (`customOperations`, `maxGroupLevel`, `groupOperations`, its events…); live as `grid.filterBuilder`. `GridFilterBuilderOptions`, default `{}`. |
+| `filterBuilderPopup` | The window: `title`, `showTitle`, `width` (`'40rem'`), `height`, `resizable`, `movable`, `showCloseButton`, `showMaximize`, `fullScreen`; live as `grid.filterBuilderPopup`. `GridFilterBuilderPopup`, default `{}`. |
+| `openFilterBuilder(), closeFilterBuilder(apply?), clearFilterValue()` | What the panel does, from code. `filterText` is the panel's text, `filterBuilderInstance` the open builder. |
+| `onFilterBuilderOpening / Opened, onFilterBuilderClosing / Closed` | `e.cancel` keeps the builder closed, or open; `e.apply` / `e.applied` say whether OK was pressed. `onFilterChanging` (cancelable) and `onFilterChanged` carry `filterValue` and `filterEnabled` too. |
+
+## Ranges, dates and entries
+
+A column's `headerFilterInterval` groups its header filter: a number column in ranges of that size (“0 – 250”, “250 – 500”; several sizes, `[1000, 100]`, make a tree), a date column in a tree of years, months and days — down to the part it names (`'year'`, `'quarter'`, `'month'`, `'day'`, `'hour'`, `'minute'`, `'second'`; `null` lists the dates one by one). Dates are a tree by default, down to the day (`headerFilterDateInterval`). The tree is the kit's `TreeView` with check boxes and “Select all”; a month checked keeps the month (`'2026/3'`), a year `2026`, and filters with `>=` its first moment and `<` the next one's, so a server runs it too. The counts are worked out in the browser from the column's distinct values: counted in memory, grouped by an adapter that groups, or from `loadValues`.
+
+`headerFilterItems` gives the header filter entries of its own, `{ text, value }`, where a value is a value or a filter expression (`data.where('city', 'in', […])`); a function gets the other filters and `values()`, the entries it would list, to add to. `filterValues` and `filterType` (both may be functions that are followed) set what the header filter holds: `'exclude'` leaves those values out, so values that come later show. In the list, choosing every value and then taking some away leaves those out the same way.
+
+```tsx
+/** An order, as the examples' made-up server keeps it. */
+export interface Order {
+  id: number;
+  customer: string;
+  city: string;
+  date: string;
+  status: string;
+  paid: boolean;
+  amount: number;
+  note: string;
+}
+```
+
+## Search panel
+
+`searchPanel` puts a search box in the toolbar: its text is looked for in every searchable column at once, after a short typing pause. Each column reads it by its type — text columns contain it (without case, in the locale), number, date and yes/no columns match it when it reads as one of their values, list columns by their option texts — and the columns are joined with OR, then with the filter row and the header filter with AND. A text no column can read leaves no row. The filter goes to the data source like any other (`data.where`, `data.or`), so a server runs it; what was found is marked in the cells. `searchText` binds the text both ways with `onSearchTextChanged`; `searchByText()` searches from code.
+
+A lookup column is searched by its texts: the lookup source — here a customers service apart from the sales' server — is asked for the items whose text holds the search (at most `searchLimit`), and their keys go to the rows' server as `customerId in [...]`. A column with a `textFrom` field searches that field of the row instead.
+
+```tsx
+import { data } from '@motifx-community/data';
+
+/** Rows in memory that answer a little later, the way a server does; for the examples. */
+export class SlowAdapter<T extends object, K> extends data.ArrayAdapter<T, K> {
+  constructor(
+    options: data.ArrayAdapterOptions<T>,
+    private readonly delayMs = 300,
+  ) {
+    super(options);
+  }
+
+  override async load(options: data.LoadOptions = {}): Promise<data.LoadResult<T>> {
+    await new Promise((done) => setTimeout(done, this.delayMs));
+    return super.load(options);
+  }
+}
+```
+
+## Example files
+
+`Filters.tsx`
+
+```tsx
+import { Button, DataGrid, Stack } from '@motifx-community/ui';
+import type { Order } from './order';
+import { filterColumns, makeOrders } from './orders';
+
+/** The filter row and the header filter, on rows in memory. */
+export default function Filters() {
+  let grid: DataGrid<Order> | null = null;
+
+  const setFilters = () => {
+    if (grid) grid.filters = { city: { values: ['Ankara', 'İzmir'] }, amount: { op: 'between', value: 100, value2: 500 } };
+  };
+
+  return (
+    <>
+      <DataGrid
+        class="dg-filters"
+        style="block-size: 30rem"
+        rows={makeOrders(200)}
+        rowKey="id"
+        columns={filterColumns}
+        label="Orders to filter"
+        locale="en"
+        settings={{ striped: true }}
+        ref={(g: DataGrid<Order>) => (grid = g)}
+      />
+      <Stack orientation="horizontal" wrap align="center">
+        <Button text="Ankara and İzmir, 100 to 500" variant="outline" onclick={setFilters} />
+        <Button text="Clear the filters" variant="ghost" onclick={() => grid?.clearFilters()} />
+        <output class="dg-filter-count">{() => `${grid?.total ?? 0} of 200 orders`}</output>
+      </Stack>
+    </>
+  );
+}
+```
+
+`orders.ts`
+
+```tsx
+import type { GridColumn } from '@motifx-community/ui';
+import type { Order } from './order';
+
+const CUSTOMERS = ['Ada Lovelace', 'Grace Hopper', 'Alan Turing', 'Cahit Arf', 'Katherine Johnson', 'Edsger Dijkstra', 'Barbara Liskov', 'Donald Knuth', 'İlhan Koman', 'Margaret Hamilton'];
+const CITIES = ['Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya', 'Trabzon'];
+const STATUSES = ['Draft', 'Approved', 'Shipped', 'Delivered', 'Cancelled'];
+const NOTES = ['', 'Leave at the door', 'Call before delivery', 'Gift wrap, please, with a card that says happy birthday', '', 'Fragile'];
+
+/** `n` made-up orders, the same ones every time. */
+export function makeOrders(n: number): Order[] {
+  const day = Date.UTC(2026, 0, 1);
+  return Array.from({ length: n }, (_, i) => ({
+    id: i + 1,
+    customer: CUSTOMERS[(i * 7) % CUSTOMERS.length],
+    city: CITIES[(i * 3) % CITIES.length],
+    date: new Date(day + ((i * 37) % 300) * 86_400_000).toISOString().slice(0, 10),
+    status: STATUSES[i % STATUSES.length],
+    paid: i % 3 === 0,
+    amount: ((i * 7919) % 100_000) / 100,
+    note: NOTES[i % NOTES.length],
+  }));
+}
+
+const money = new Intl.NumberFormat('en', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+
+/** The order columns: the number pinned to the start, the amount to the end. */
+export const columns: GridColumn<Order>[] = [
+  { field: 'id', title: 'No', type: 'number', width: 80, sticky: 'start', editable: false },
+  { field: 'customer', title: 'Customer', width: 180, flex: 1, required: true },
+  { field: 'city', title: 'City', type: 'list', width: 120, options: CITIES },
+  { field: 'date', title: 'Date', type: 'date', width: 130, editable: false, creatable: true },
+  { field: 'status', title: 'Status', type: 'list', width: 120, options: STATUSES, required: true },
+  { field: 'paid', title: 'Paid', type: 'boolean', width: 80 },
+  { field: 'note', title: 'Note', width: 200 },
+  {
+    field: 'amount',
+    title: 'Amount',
+    type: 'number',
+    width: 120,
+    sticky: 'end',
+    required: true,
+    validate: (v) => (typeof v === 'number' && v < 0 ? 'The amount cannot be negative.' : null),
+    format: (v) => (typeof v === 'number' ? money.format(v) : ''),
+  },
+];
+
+/** The same columns with a filter cell and a header filter on most of them. */
+export const filterColumns: GridColumn<Order>[] = columns.map((c) => ({ ...c, filterRow: c.field !== 'note', headerFilter: c.field !== 'note' && c.field !== 'id' }));
+
+const today = () => new Date().toISOString().slice(0, 10);
+
+/** What a new order starts with. */
+export const newOrder = () => ({ date: today(), status: 'Draft', paid: false });
+```
+
+`order.ts`
+
+```tsx
+/** An order, as the examples' made-up server keeps it. */
+export interface Order {
+  id: number;
+  customer: string;
+  city: string;
+  date: string;
+  status: string;
+  paid: boolean;
+  amount: number;
+  note: string;
+}
+```
+
+`FilterPanel.tsx`
+
+```tsx
+import { reactive } from '@motifx/core';
+import { data } from '@motifx-community/data';
+import { Button, DataGrid, RadioGroup, Stack, Switch } from '@motifx-community/ui';
+import { SlowAdapter } from '../../../shared/slow-adapter';
+import type { Order } from './order';
+import { filterColumns, makeOrders } from './orders';
+
+/** The filter panel and its builder, on 100,000 orders of a server or 200 in memory, the filter row and header filters kept in step. */
+export default function FilterPanel() {
+  const orders = new data.DataSource<Order, number>({ adapter: new SlowAdapter<Order, number>({ data: makeOrders(100_000), key: 'id' }, 200), loadMode: 'blocks', pageSize: 100 });
+  const rows = makeOrders(200);
+  const s = reactive({ where: 'server', sync: true, filter: null as data.FilterExpression | null });
+  let grid: DataGrid<Order> | null = null;
+
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center">
+        <RadioGroup
+          label="Rows"
+          orientation="horizontal"
+          items={[
+            { value: 'server', text: '100,000 on a server' },
+            { value: 'memory', text: '200 in memory' },
+          ]}
+          x-model={() => s.where}
+        />
+        <Switch label="filterSyncEnabled" x-model={() => s.sync} />
+        <Button text="Open the builder" variant="outline" onclick={() => grid?.openFilterBuilder()} />
+        <Button
+          text="Paid, over 900"
+          variant="ghost"
+          onclick={() => (s.filter = data.and(data.where('paid', '=', true), data.where('amount', '>', 900)))}
+        />
+      </Stack>
+      <DataGrid
+        class="dg-server-filters"
+        style="block-size: 30rem"
+        dataSource={() => (s.where === 'server' ? orders : null)}
+        rows={rows}
+        rowKey="id"
+        columns={filterColumns}
+        label="Orders with a filter panel"
+        locale="en"
+        settings={{ filterPanel: true, filterSyncEnabled: () => s.sync }}
+        filterValue={() => s.filter}
+        filterBuilder={{ maxGroupLevel: 2 }}
+        filterBuilderPopup={{ title: 'Filter the orders' }}
+        onFilterChanged={(e) => (s.filter = e.filterValue)}
+        ref={(g: DataGrid<Order>) => (grid = g)}
+      />
+      <output class="dg-server-filter">{() => `${(grid?.total ?? 0).toLocaleString('en')} orders · ${JSON.stringify(grid?.filter ?? null)}`}</output>
+      <output class="dg-filter-value">{() => `filterValue: ${JSON.stringify(s.filter)}`}</output>
+    </>
+  );
+}
+```
+
+`slow-adapter.ts`
+
+```tsx
+import { data } from '@motifx-community/data';
+
+/** Rows in memory that answer a little later, the way a server does; for the examples. */
+export class SlowAdapter<T extends object, K> extends data.ArrayAdapter<T, K> {
+  constructor(
+    options: data.ArrayAdapterOptions<T>,
+    private readonly delayMs = 300,
+  ) {
+    super(options);
+  }
+
+  override async load(options: data.LoadOptions = {}): Promise<data.LoadResult<T>> {
+    await new Promise((done) => setTimeout(done, this.delayMs));
+    return super.load(options);
+  }
+}
+```
+
+`HeaderFilterIntervals.tsx`
+
+```tsx
+import { reactive } from '@motifx/core';
+import { data } from '@motifx-community/data';
+import { Button, DataGrid, Stack, type GridColumn } from '@motifx-community/ui';
+import type { Order } from './order';
+import { columns, makeOrders } from './orders';
+
+const COAST = ['Antalya', 'İstanbul', 'İzmir', 'Trabzon'];
+
+/** The order columns with header filters: amounts in ranges, dates in a tree, cities by entries of their own, statuses left out. */
+const intervalColumns: GridColumn<Order>[] = columns.map((c) => {
+  switch (c.field) {
+    case 'amount':
+      // "0 – 250", "250 – 500" …
+      return { ...c, headerFilter: true, headerFilterInterval: 250 };
+    case 'date':
+      // Year → month → day, by the grid's headerFilterDateInterval.
+      return { ...c, headerFilter: true };
+    case 'city':
+      return {
+        ...c,
+        headerFilter: true,
+        headerFilterItems: [
+          { text: 'On the coast', value: data.where('city', 'in', COAST) },
+          { text: 'Inland', value: data.not(data.where('city', 'in', COAST)) },
+          { text: 'Ankara only', value: 'Ankara' },
+        ],
+      };
+    case 'status':
+      // Every status but Cancelled: statuses that come later show too.
+      return { ...c, headerFilter: true, filterValues: ['Cancelled'], filterType: 'exclude' };
+    default:
+      return c;
+  }
+});
+
+/** The header filter in ranges of amounts, a tree of dates, entries of its own, and values left out. */
+export default function HeaderFilterIntervals() {
+  const s = reactive({ months: false });
+  let grid: DataGrid<Order> | null = null;
+
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center">
+        <Button text={() => (s.months ? 'Dates down to the day' : 'Dates down to the month')} variant="outline" onclick={() => (s.months = !s.months)} />
+        <Button text="Amounts in ranges of 1,000" variant="outline" onclick={() => grid?.columnOption('amount', 'headerFilterInterval', 1000)} />
+        <Button text="Clear the filters" variant="ghost" onclick={() => grid?.clearFilters()} />
+      </Stack>
+      <DataGrid
+        class="dg-intervals"
+        style="block-size: 30rem"
+        rows={makeOrders(300)}
+        rowKey="id"
+        columns={intervalColumns}
+        label="Orders filtered by ranges and dates"
+        locale="en"
+        settings={{ headerFilterDateInterval: () => (s.months ? 'month' : 'day') }}
+        ref={(g: DataGrid<Order>) => (grid = g)}
+      />
+      <output class="dg-intervals-filter">{() => `${grid?.total ?? 0} orders · ${JSON.stringify(grid?.filters ?? {})}`}</output>
+    </>
+  );
+}
+```
+
+`Search.tsx`
+
+```tsx
+import { reactive } from '@motifx/core';
+import { data } from '@motifx-community/data';
+import { Button, CheckBox, DataGrid, Stack, type GridColumn } from '@motifx-community/ui';
+import { SlowAdapter } from '../../../shared/slow-adapter';
+import { makeCustomers, type Customer } from './customers';
+import { columns, makeOrders } from './orders';
+
+type Sale = { id: number; customerId: number; amount: number };
+
+const money = new Intl.NumberFormat('en', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+
+/** The search panel over rows in memory, and over a server whose customer names live on another service. */
+export default function Search() {
+  const s = reactive({ text: 'ankara', caseSensitive: false });
+
+  // The sales and the customers are two services: the search asks the customers' service for the
+  // names, then the sales' server only for keys.
+  const customers = new data.DataSource<Customer, number>({ adapter: new SlowAdapter<Customer, number>({ data: makeCustomers(600), key: 'id' }, 300) });
+  const salesServer = new SlowAdapter<Sale, number>({ data: Array.from({ length: 50_000 }, (_, i) => ({ id: i + 1, customerId: ((i * 37) % 600) + 1, amount: ((i * 7919) % 100_000) / 100 })), key: 'id' }, 250);
+  const sales = new data.DataSource<Sale, number>({ adapter: salesServer, loadMode: 'blocks', pageSize: 100 });
+  const saleColumns: GridColumn<Sale>[] = [
+    { field: 'id', title: 'No', type: 'number', width: 90 },
+    { field: 'customerId', title: 'Customer', flex: 1, width: 220, lookup: { dataSource: customers, valueField: 'id', textField: 'name' } },
+    { field: 'amount', title: 'Amount', type: 'number', width: 120, format: (v) => (typeof v === 'number' ? money.format(v) : '') },
+  ];
+  let server: DataGrid<Sale> | null = null;
+
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center">
+        <Button text="Search for “approved”" variant="outline" onclick={() => (s.text = 'approved')} />
+        <CheckBox label="Mark only the same case" x-model={() => s.caseSensitive} />
+      </Stack>
+      <DataGrid
+        class="dg-search"
+        style="block-size: 30rem"
+        rows={makeOrders(200)}
+        rowKey="id"
+        columns={columns}
+        label="Orders to search"
+        locale="en"
+        searchText={() => s.text}
+        onSearchTextChanged={(e) => (s.text = e.text)}
+        settings={{ searchPanel: true, searchPanelWidth: 220, highlightCaseSensitive: () => s.caseSensitive }}
+      />
+      <output class="dg-search-text">{() => `Searching for “${s.text}”`}</output>
+      <DataGrid
+        class="dg-server-search"
+        style="block-size: 30rem"
+        dataSource={sales}
+        columns={saleColumns}
+        label="50,000 sales to search"
+        locale="en"
+        settings={{ searchPanel: true, searchPlaceholder: 'A customer, an amount…' }}
+        ref={(g: DataGrid<Sale>) => (server = g)}
+      />
+      <output class="dg-server-search-filter">{() => `${(server?.total ?? 0).toLocaleString('en')} sales · ${JSON.stringify(server?.filter ?? null)}`}</output>
+    </>
+  );
+}
+```
+
+`customers.ts`
+
+```tsx
+/** A customer, as another made-up service keeps it. */
+export interface Customer {
+  id: number;
+  name: string;
+  city: string;
+}
+
+const FIRST = ['Ada', 'Grace', 'Alan', 'Cahit', 'Katherine', 'Edsger', 'Barbara', 'Donald', 'İlhan', 'Margaret', 'Feza', 'Ali Nesin'];
+const LAST = ['Lovelace', 'Hopper', 'Turing', 'Arf', 'Johnson', 'Dijkstra', 'Liskov', 'Knuth', 'Koman', 'Hamilton', 'Gürsey', 'Yılmaz'];
+const CITIES = ['Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya', 'Trabzon'];
+
+/** `n` made-up customers, the same ones every time. */
+export function makeCustomers(n: number): Customer[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: i + 1,
+    name: `${FIRST[i % FIRST.length]} ${LAST[Math.floor(i / FIRST.length) % LAST.length]} ${Math.floor(i / (FIRST.length * LAST.length)) + 1}`,
+    city: CITIES[(i * 5) % CITIES.length],
+  }));
+}
+```