Server Row Model

import {
  createDataGrid, filtering, pagination, sorting,
  getSorting, toFilterRequest, toSortRequest, SELECTION_COLUMN_ID
} from '@sv5ui/datagrid';

// rowModel: 'server' tells the pipeline that data already holds exactly
// what should be shown. Filtering, sorting and windowing pass their rows
// through untouched, while the features stay registered, because their
// state, their UI and their events are what a server model listens to.
const grid = createDataGrid<Person>({
  columns,
  data: [],
  getRowId,
  rowModel: 'server',
  features: [sorting(), filtering(), pagination({ pageSize: 10 })]
});

// The events are the trigger, and the mount is the first load.
for (const event of ['sortChanged', 'filterChanged', 'pageChanged'] as const) {
  grid.events.on(event, () => void load());
}
onMount(() => void load(true));

// Latest wins: typing into the quick filter sends a request per keystroke
// and they do not come back in the order they left. lastSent is a separate
// guard - setRowCount can clamp the page and emit pageChanged, which would
// otherwise fetch a page nothing asked for.
let ticket = 0;
let lastSent = '';

async function load(force = false) {
  const paging = getPagination(grid);
  const sorting = getSorting(grid);

  // The columns a bare query applies to: whatever is visible when it is
  // typed, which is what the client would have matched. The checkbox
  // column is visible too and holds nothing, so it is not a field.
  const quickFields = grid.columns.visible
    .filter((column) => column.id !== SELECTION_COLUMN_ID)
    .map((column) => column.id);

  const body = JSON.stringify({
    filter: toFilterRequest(getFiltering(grid)?.model ?? { quick: '', columns: {} }, quickFields),
    sort: toSortRequest(sorting?.sort ?? [], grid.columns.defs, sorting?.nulls),
    page: paging?.page ?? 1,
    pageSize: paging?.pageSize ?? 10
  });
  if (!force && body === lastSent) return;

  const mine = ++ticket;
  lastSent = body;
  const response = await fetch('/api/rows', { method: 'POST', body });
  const { rows, total } = await response.json();
  if (mine !== ticket) return;     // an older answer, already out of date

  grid.data = rows;                // one page
  grid.api.setRowCount?.(total);   // what the footer counts against
}

// Do NOT reload from an $effect that reads the grid. This looks
// innocent and never settles:
$effect(() => {
  void load();   // reads page, pageSize, the filter model and the sort
});

// load() writes the answer back:
grid.data = rows;
grid.api.setRowCount?.(total);

// setRowCount writes the row count that page and pageCount are derived
// from, which the effect read on its way in, so the effect re-runs and
// fetches again. The 300ms server delay is the only thing pacing it.

// The grid already tells you when to reload. Listen, and load once on
// mount:
for (const event of ['sortChanged', 'filterChanged', 'pageChanged'] as const) {
  grid.events.on(event, () => void load());
}
onMount(() => void load(true));

// The two request builders produce normalized wire shapes, kept
// deliberately separate from the internal models so they can stay frozen
// while those grow. They grow only by carrying something a backend could
// not otherwise know, which is what quickFields and nulls are.

toFilterRequest(grid.api.getFilterModel(), quickFields);
// {
//   quick: 'ada',
//   quickFields: ['name', 'team', 'salary'],
//   columns: {
//     salary: { join: 'and', conditions: [{ kind: 'number', op: 'gte', value: 90000 }] }
//   }
// }
// Always a list and a join, even where the model kept one condition flat.
// quickFields names the columns the query applies to: the visible ones, in
// the order they are shown. Leave it out and a backend is guessing.

toSortRequest(getSorting(grid).sort, grid.columns.defs, getSorting(grid).nulls);
// [{ field: 'lastName', direction: 'asc', nulls: 'first' }]
// A column's sortField is what travels, so an id that is a UI concern need
// not be one your database recognises.
//
// nulls is written as the side the blanks actually land on, which is not
// always the side the option names: on the client a blank sorts as the
// smallest value, so nulls: 'first' arrives as 'last' once the direction
// is descending. SQL's NULLS FIRST means first either way, so passing it
// straight through is what keeps the two orderings identical.
//
// Header groups are handled inside: the builder flattens what it is given,
// so the same call works with or without them.

-- Everything the grid decided, translated. Where the two disagree,
-- what the reader sees is whatever your backend does.

-- nulls rides on every sort entry, so ORDER BY reproduces the client
-- ordering without further thought:
ORDER BY last_name ASC NULLS FIRST, salary DESC NULLS LAST

-- Text is case-insensitive unless the condition sets caseSensitive, which
-- LIKE is not in Postgres:
WHERE name ILIKE '%' || $1 || '%'

-- Blank means null or the empty string, and IS NULL misses one of them:
WHERE country IS NULL OR country = ''

-- between includes both ends:
WHERE salary BETWEEN $1 AND $2

-- A date condition means a calendar day in the reader's own zone, not an
-- instant in the database's:
WHERE joined_at >= $1::date AND joined_at < $1::date + 1

-- A percent column holds the ratio, so 5% arrives as 0.05.

<script lang="ts">
  let loading = $state(true);
  let error = $state<string | null>(null);

  async function load() {
    loading = true;
    error = null;
    try {
      const { rows, total } = await fetchPage();
      grid.data = rows;
      grid.api.setRowCount?.(total);
    } catch (cause) {
      error = 'Could not reach the server';
    } finally {
      loading = false;
    }
  }
</script>

<!-- The grid renders the surfaces; the fetch owns the flags -->
<DataGrid {grid} toolbar {loading} {error} onRetry={load} />

// What the server model does and does not cover.

// Covered: filter, sort and paging travel to the server, and setRowCount
// keeps the footer honest about a total the client never sees.

// Not covered:
//  - selection still addresses the rows in hand, so select-all reaches the
//    page rather than the result set. The ids it holds survive the page
//    turning, so a count spanning pages is real, but the rows behind the
//    ids are not, and "select every match" is yours to model.
//  - virtualization windows the page it was given: rowModel 'server' with
//    virtualization is a fixed-size page in a scroller, not infinite scroll.
//  - the quick filter travels as one string plus the fields it applies to;
//    what it means against them is the server's decision. The client also
//    matches the text a cell draws, which a backend has no renderers for.

// Debounce at the edge rather than in the grid: the quick filter already
// debounces its input, but a slider or a date range wants its own.

<!-- exportCsv writes the rows the grid is holding. Under a server row
     model that is one page, so the item is named "Loaded rows" rather
     than promising the rest. Point it at an endpoint that streams a
     file and it goes back to being "All rows". -->
<DataGrid {grid} toolbar onExportAll={exportEverything} />

<script lang="ts">
  function exportEverything() {
    // The same request the grid sends, so the file matches the screen.
    const query = new URLSearchParams({
      filter: JSON.stringify(toFilterRequest(getFiltering(grid)!.model, quickFields)),
      sort: JSON.stringify(toSortRequest(getSorting(grid)!.sort, grid.columns.defs))
    });
    location.href = `/api/people.csv?${query}`;
  }
</script>

<!-- Selection is unaffected either way: the ids are held across pages, so
     "Selected rows" writes the ones the grid still has in hand. -->