Custom Features

import type { GridFeature } from '@sv5ui/datagrid';

// A feature is a plain object. Every hook is optional, and the built-in
// features use nothing that is not available here.
const myFeature = <TRow,>(): GridFeature<TRow> => ({
  id: 'my-feature',          // also the key of its state on grid.state

  pipelineStage: { order, transform },   // an ordered, pure row transform
  createState: (grid) => new MyState(grid),
  createApi: (grid) => ({ myMethod: () => {} }),
  keybindings: [{ key: 'Ctrl+k', when, handler }],
  menuItems: (ctx) => [],
  cellDecoration: (ctx) => ({ class: '', selected: false }),
  serialize: (grid) => sliceForSnapshot,
  hydrate: (slice, grid) => {}
});

import type { GridFeature } from '@sv5ui/datagrid';

// The smallest useful feature: a class on the cells that deserve one.
const highlightHighEarners = (): GridFeature<Person> => ({
  id: 'highlight-high-earners',
  cellDecoration: ({ node, column }) =>
    column.id === 'salary' && node.row.salary > 120000
      ? { class: 'bg-success/10 font-semibold text-success' }
      : undefined
});

createDataGrid<Person>({ columns, data, getRowId, features: [highlightHighEarners()] });

// cellDecoration runs for every rendered cell, so keep it cheap. A grid
// whose features do not define it skips the work entirely.

// A class can only name a value someone thought of in advance. The scale
// below is the number itself, so it goes on the cell's own style.
const heat = (max: number): GridFeature<Person> => ({
  id: 'heat',
  cellDecoration: ({ node, column }) =>
    column.id === 'salary'
      ? {
          style: {
            'background-color': `color-mix(in oklab, var(--color-primary) ${Math.round(
              (node.row.salary / max) * 45
            )}%, transparent)`
          }
        }
      : undefined
});

// Keyed by CSS property, custom properties included, which is how a
// feature reaches a pseudo-element:
{ style: { '--dg-bar': '62%' } }

// Several features decorating one cell merge per property, the later one
// winning, the same way their classes stack. A key that is not a CSS
// property is dropped and a value is cut at the first semicolon, so one
// entry stays one declaration and a colour read out of row data cannot
// open a second.

// The grid writes its own layout as style directives, which outrank the
// attribute: a decoration can paint a cell, but it cannot move it out of
// its column or unpin it.

// cellValue stands between a cell and every way the grid lets it out.
const maskedReader = () => '***';

const maskSalary = (masked: () => boolean): GridFeature<Person> => ({
  id: 'mask-salary',
  // Asked per column and per purpose, not per value: the passes that read
  // a whole column at a time ask once and then loop over the rows.
  cellValue: ({ column }) => (column.id === 'salary' && masked() ? maskedReader : undefined)
});

// The purposes are every way out: 'render' | 'export' | 'clipboard' |
// 'search' | 'facet' | 'edit'. Masking render alone would leave the value
// in the clipboard, in the CSV and in the text a quick filter searches.

// Read one yourself when you need to know what a purpose sees:
grid.getValue(node, column);             // what the cell draws
grid.getValue(node, column, 'export');   // what a CSV would carry
grid.readerFor('salary', 'export');      // the reader itself, to hoist out of a loop

// Hand the same reader back each time. The grid compares by identity to
// tell a substituted cell from an untouched one, and the quick filter's
// text and the set filter's value list are cached per column and keyed by
// the reader: a fresh closure per call throws both caches away.

import { PIPELINE_ORDER, type GridFeature } from '@sv5ui/datagrid';

// A stage is a pure transform of RowNode[], inserted at a declared order:
//   filter 100, sort 200, group 300, flatten 400, pin-split 500, window 900
const onlyActive = (enabled: () => boolean): GridFeature<Person> => ({
  id: 'only-active',
  pipelineStage: {
    order: PIPELINE_ORDER.filter + 1,   // just after the filter stage
    transform: (nodes) =>
      enabled() ? nodes.filter((node) => node.row.status === 'active') : nodes
  }
});

// Reading a rune inside transform is what makes the stage re-run: the
// pipeline memoizes each link with $derived, so an unchanged input is an
// unchanged output.

import type { GridFeature, GridState } from '@sv5ui/datagrid';

const SUMMARY = 'summary';

class Summary {
  on = $state(false);
}

const getSummary = (grid: GridState<Person>) => grid.feature<Summary>(SUMMARY);

const KEPT = new Set(['name', 'salary']);

const summary = (): GridFeature<Person> => ({
  id: SUMMARY,
  createState: () => new Summary(),

  // Handed the definitions, answers the list the grid should draw.
  columns: (defs, grid) => {
    // Reading the rune here is what makes the grid ask again when it moves.
    if (!getSummary(grid)?.on) return defs;

    return [
      // Hidden rather than dropped, so they still filter.
      ...defs.map((def) => (KEPT.has(def.id) ? def : { ...def, hidden: true })),
      // And one of its own, which is a column like any other.
      {
        id: 'summary-where',
        header: 'Where',
        accessor: (person: Person) => `${person.role}, ${person.team}, ${person.country}`
      }
    ];
  }
});

import { type GridFeature, type GridState } from '@sv5ui/datagrid';

const FLAGS = 'flags';

class Flags<TRow> {
  flagged = $state.raw<ReadonlySet<string>>(new Set());

  constructor(private grid: GridState<TRow>) {}

  toggle = (id: string) => {
    const next = new Set(this.flagged);
    next.has(id) ? next.delete(id) : next.add(id);
    this.flagged = next;
  };
}

// Declare what the feature adds to grid.api, from the feature's own module.
declare module '@sv5ui/datagrid' {
  interface GridApi {
    toggleFlag?: (id: string) => void;
  }
}

export const flags = <TRow,>(): GridFeature<TRow> => ({
  id: FLAGS,
  createState: (grid) => new Flags(grid),
  createApi: (grid) => ({ toggleFlag: getFlags(grid)!.toggle }),
  cellDecoration: ({ grid, node }) =>
    getFlags(grid)?.flagged.has(node.id) ? { class: 'bg-warning/12' } : undefined
});

// The accessor is the typed path, the same shape the built-ins ship.
export const getFlags = <TRow,>(grid: GridState<TRow>) =>
  grid.feature<Flags<TRow>>(FLAGS);

const flags = <TRow,>(): GridFeature<TRow> => ({
  id: 'flags',

  // Context menu entries. ctx carries the grid, and the row or column the
  // menu was opened on.
  menuItems: ({ grid, node }) =>
    node
      ? [
          {
            id: 'toggle-flag',
            label: 'Toggle flag',
            icon: 'lucide:flag',
            onSelect: () => getFlags(grid)?.toggle(node.id)
          }
        ]
      : [],

  // Keybindings, with a guard. Returning false from when lets a later
  // binding claim the same key.
  keybindings: [
    {
      key: 'Ctrl+f',
      when: (grid) => grid.focus.active.row >= 0,
      handler: (grid) => {
        const node = grid.preWindowNodes[grid.focus.active.row];
        if (node) getFlags(grid)?.toggle(node.id);
      }
    }
  ]
});

const flags = <TRow,>(): GridFeature<TRow> => ({
  id: 'flags',

  // The feature's slice of a state snapshot. Return undefined and it stays
  // out of the snapshot entirely.
  serialize: (grid) => {
    const ids = [...(getFlags(grid)?.flagged ?? [])];
    return ids.length > 0 ? ids : undefined;
  },

  // Restores what serialize produced. A feature added after the snapshot
  // was written simply starts fresh.
  hydrate: (slice, grid) => {
    const state = getFlags(grid);
    if (state && Array.isArray(slice)) state.flagged = new Set(slice as string[]);
  }
});

// Both run through grid.api.getState() and setState(), and therefore
// through persistState too.