Sorting

// sortable turns on click-to-sort for one column
const columns: ColumnDef<Person>[] = [
  { id: 'name', header: 'Name', sortable: true, flex: 1 },
  { id: 'team', header: 'Team', sortable: true, width: 130 },
  { id: 'salary', header: 'Salary', sortable: true, align: 'right', width: 140,
    type: 'currency' },
  { id: 'email', header: 'Email', flex: 1.4 }   // not sortable
];

// The shorthand form registers sorting for you
<DataGrid data={people} {columns} {getRowId} />

import { createDataGrid, sorting } from '@sv5ui/datagrid';

const grid = createDataGrid<Person>({
  data: people,
  columns,
  getRowId,
  features: [
    sorting({
      // Where the grid starts
      initial: [
        { columnId: 'team', direction: 'asc' },
        { columnId: 'salary', direction: 'desc' }
      ]
    })
  ]
});

// Shift-click a header, or press Shift+Enter on a focused header cell, to
// add a column to the sort instead of replacing it. A numbered badge shows
// the priority once more than one column is sorted.

// What a header click walks through. null clears the column.
sorting({ cycle: ['asc', 'desc', null] })   // the default

// Never leave the column unsorted
sorting({ cycle: ['asc', 'desc'] })

// Start with the largest first, which suits amounts and dates
sorting({ cycle: ['desc', 'asc', null] })

// A cycle with no direction at all falls back to the default.

// Where blank values land, regardless of direction
sorting({ nulls: 'first' })   // the default
sorting({ nulls: 'last' })

// Blank is null, undefined or the empty string: the same set the blank
// filter operator matches and the renderers show as empty. A column that
// means something by '' and wants it ordered as a value needs a sortFn.

// Under rowModel: 'server' the choice travels, so the same grid does not
// reorder itself when the rows start coming from a database:
toSortRequest(getSorting(grid)!.sort, grid.columns.defs, getSorting(grid)!.nulls);
// [{ field: 'country', direction: 'desc', nulls: 'last' }]
//
// Written as the side the blanks actually land on rather than 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, while
// SQL's NULLS FIRST means first either way. Passing it straight into
// ORDER BY ... NULLS LAST is what keeps the two orderings identical.

// A date or datetime column orders by the date behind the cell, so the
// form a row happens to hold does not decide the order.
const columns: ColumnDef<Shipment>[] = [
  { id: 'ref', header: 'Reference', width: 130 },
  { id: 'shippedAt', header: 'Shipped', sortable: true, width: 150,
    type: 'date', typeOptions: { locale: 'en-US' } }
];

const shipments = [
  { id: 1, ref: 'A-1001', shippedAt: '2024-03-14' },                    // date-only string
  { id: 2, ref: 'A-1002', shippedAt: new Date(2024, 0, 5) },            // Date object
  { id: 3, ref: 'A-1003', shippedAt: new Date(2024, 6, 22).getTime() }, // epoch number
  { id: 4, ref: 'A-1004', shippedAt: '2024-05-02' },
  { id: 5, ref: 'A-1005', shippedAt: new Date(2023, 11, 31) }
];

// Without type: 'date' these are compared as text, which puts a Date
// object's "Fri Jul 22 2024" before an ISO string's "2024-01-05".
//
// A date-only string names a calendar day rather than UTC midnight, so it
// keeps its day west of Greenwich as well as east of it.

// A custom comparator. The direction factor is applied on top of the
// result, so always compare ascending here.
const rank = { suspended: 0, invited: 1, active: 2 };

const columns: ColumnDef<Person>[] = [
  {
    id: 'status',
    header: 'Status',
    sortable: true,
    width: 140,
    type: 'badge',
    sortFn: (a, b) => rank[a.status] - rank[b.status]
  }
];

// A column that shows one thing and orders by another: the cell reads
// "Ada Lovelace" while the sort follows the surname.
{
  id: 'name',
  header: 'Name',
  sortable: true,
  sortField: 'lastName'
}

// On the client sortField names a row property. Under rowModel: 'server'
// it is what toSortRequest puts on the wire, so a column id that is a UI
// concern never has to be one your database recognises.
// sortFn wins over sortField when both are set.

import { getSorting } from '@sv5ui/datagrid';

const sorting = getSorting(grid);

sorting?.sort;                       // SortState[], reactive
sorting?.directionOf('salary');      // 'asc' | 'desc' | undefined
sorting?.priorityOf('salary');       // 1-based, or null below two columns

// Replace the sort outright
sorting?.setSort([{ columnId: 'name', direction: 'asc' }]);

// Walk one column through the cycle; append keeps the rest of the sort
sorting?.toggleSort('team');
sorting?.toggleSort('salary', { append: true });

// The same two, merged into the grid api
grid.api.setSort?.([{ columnId: 'name', direction: 'asc' }]);
grid.api.toggleSort?.('team');

// Every change emits
grid.events.on('sortChanged', ({ sort }) => console.log(sort));