useDocyrusDataGrid

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-grid

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query @tanstack/react-table react-querybuilder

This hook is distributed as source. It requires an authenticated RestApiClient from @docyrus/api-client and a QueryClientProvider from @tanstack/react-query somewhere above your component tree.

Overview

useDocyrusDataGrid is the one-call entry point that wires a Docyrus data source to <DataGrid> and produces a ready-to-render toolbar with the standard arrangement:

• Left: DataGridViewSelect (saved views from the backend, wired through useDocyrusDataViewSelect), inline search input, filter menu.
• Right: column grouping, sort, row height, display (grid/gallery), reload.

It also generates ColumnDefs automatically from the data source's field metadata, mapping every Docyrus field type (field-text, field-status, field-enum, field-multiSelect, field-money, field-rating, etc.) to the matching DataGrid cell variant.

Backend connection

The hook supports three ways to feed rows to the grid (precedence top→bottom):

1. data — a pre-resolved array. Use when records come from somewhere outside of TanStack Query.
2. collection — a TanStack DB collection generated by @docyrus/tanstack-db-generator (e.g., the result of useBaseOrganizationCollection()). The hook calls collection.list(resolvedListParams) inside its own useQuery.
3. Default — GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items via the @docyrus/api-client you already passed as client. No extra setup.

The reload button refetches the items query (in modes 2 and 3), the data source + views queries, and any onReload callback you provided. In mode 1 the hook can't refetch rows on its own — wire onReload to your fetcher.

Tenant-aware formatting

Date / datetime / number cells render through the formatters supplied by <DocyrusTenantProvider> — no per-grid wiring required. Mount the provider once near the root of your app and every useDocyrusDataGrid call below it picks up the tenant's dateFormat, dateTimeFormat, decimalSeparator, thousandSeparator, decimalPrecision, and timeZone settings automatically.

Resolution order for each cell formatter (date / datetime / number):

1. Explicit prop on useDocyrusDataGrid({ formatDate, formatDateTime, formatNumber }) — wins when supplied.
2. Surrounding useDateFormat() / useNumberFormat() context (typically installed by <DocyrusTenantProvider>).
3. The cell's own legacy fallback (Intl.NumberFormat for currency / percent in NumberCell, raw-string display for dates) — used only when neither a prop nor a real provider is present.

Apps that haven't adopted <DocyrusTenantProvider> yet keep their previous behaviour byte-for-byte (step 3). The migration is purely additive.

Relation cell icons / logos

field-relation cells render only the related record's name by default. To prefix each cell with the related record's display icon (or logo image), pass a relationIconFields map that points each relation field slug to the column slug on the related data source that holds the icon value:

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'contact',
  collection,
  relationIconFields: {
    organization: 'company_icon',  // field-icon on the org DSO
    country: 'flag_image'           // field-image on the country DSO
  }
});

The hook expands the items-query projection from organization(id, name, autonumber_id) to organization(id, name, autonumber_id, company_icon) so the server returns the icon value alongside the name in a single request. RelationCell then auto-detects the value shape:

• field-icon (string identifier like 'huge ai-brain-03') → resolved via <DocyrusIcon>.
• field-image (URL string, single { signed_url, file_name } object, or an array thereof) → rendered as a small <img> thumbnail.

The prefix is suppressed right after the user picks a new value (until the next refetch hydrates the row), since the freshly-picked option doesn't carry the icon field yet.

Borrowed relation columns

A grid lists one data source, but the field the user actually wants to see often lives one hop away — "the Matter's Project Lead next to each time entry". Set enableRelationColumns and every relation field on the schema is paired with every non-relation field of the data source it points at, offered as an extra column in the Fields menu:

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'time_entry',
  collection,
  enableRelationColumns: true
});

Off by default: it costs one extra request per data source (GET /v1/dev/data-sources/:id/fields?expand=parent) and widens the Fields menu considerably. The borrowed columns start hidden, so the grid looks and queries exactly as before until the user picks one.

What the user sees

The Fields menu groups borrowed columns under the relation they arrive through — Matter, Billing Contact, Case Handler 1 — with the grid's own fields in the first, unlabelled group.

Two relation fields pointing at the same data source stay separate groups. That is deliberate: on a schema where six different relation fields all target contact, "Billing Contact's email" and "Case Handler 1's email" are distinct columns and never collapse into one.

What goes on the wire

Picking a borrowed column does not issue a second request — its field joins that relation's existing projection group, and the backend resolves it in the same /items call:

columns=id,date,matter(id,name,project_lead)

row.matter.project_lead comes back already resolved to { id, name }. The three grammars are not interchangeable, and the hook maps between them for you:

One hop only

Target fields that are themselves relations are not offered. The backend's projection parser does not understand nested paths (rel_a(rel_b(x))), so a two-hop column would be pickable and then fail at query time — it is dropped from the catalogue instead.

Filtering a borrowed column is positive-only

Borrowed columns are filterable, but with a restricted operator set and always ANDed — never inside an OR group. This is a chosen contract, not a stopgap, and it follows from how the backend compiles a rel_ condition:

• A rel_ condition is a query-level join, drained once into the FROM clause. It narrows the row set before the boolean structure of the WHERE tree is evaluated — so an OR branch containing a relation condition annihilates the whole OR: the other branch can match perfectly and the row still vanishes.
• Negation lies under three-valued logic. "Matter type is not Litigation" compiles to a predicate that is false for a time entry with no matter at all, so those rows silently disappear and the user is shown a smaller number than the sentence they built promises. not contains is worse — its is null or … arm can make an exclusion filter grow the result set.

So the surface offers positive operators only (equals, contains, in, comparisons, safe relative dates). A relation rule the user drags into an OR group, or an operator outside the whitelist, is dropped before the request rather than sent and answered incorrectly.

Query parameters sent to the backend

Both backend modes (collection + direct fetch) call the items endpoint with a ZodSelectQueryPayload shaped object — see the full reference in docs/guides/docyrus-api-query-guide.md. The hook builds this payload (resolvedListParams) automatically from the active view + the toolbar search input + your listParams overrides:

The @docyrus/api-client jsonToQueryString helper auto-serializes object/array values via JSON.stringify, so complex filters and orderBy go on the wire as JSON strings without extra wiring.

The fully-resolved payload is exposed back to the consumer as resolvedListParams so you can inspect or persist it (e.g., for a "copy as cURL" button).

Usage

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { DataGrid } from '@docyrus/ui/components/data-grid';
import { useDocyrusDataGrid } from '@docyrus/ui/library/hooks/use-docyrus-data-grid';

type OrganizationRow = { id: string; name: string };

export function OrganizationsGrid() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  // Direct API mode (no codegen needed):
  const { table, gridProps, toolbar } = useDocyrusDataGrid<OrganizationRow>({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'organization'
  });

  // Collection mode (with @docyrus/tanstack-db-generator):
  // const collection = useCrmOrganizationCollection();
  // const { table, gridProps, toolbar } = useDocyrusDataGrid<OrganizationRow>({
  //   client,
  //   appSlug: 'crm',
  //   dataSourceSlug: 'organization',
  //   collection
  // });

  return (
    <div className="flex h-full flex-col gap-3">
      {toolbar}
      <DataGrid table={table} {...gridProps} height="auto" />
    </div>
  );
}

API Reference

Parameters

The hook accepts every option from useDocyrusDataViewSelect (for view CRUD + filter fields), plus:

Return Value

Pivot filter integration

Pass pivotFilters: [{ fieldSlug: 'status' }, { fieldSlug: 'priority' }, …] and the hook stacks one or more pivot filter strips above the data-view toolbar automatically — no extra rendering or state-lifting required on the consumer side.

const grid = useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  pivotFilters: [
    { fieldSlug: 'status', totalLabel: 'All statuses' },
    { fieldSlug: 'priority', totalLabel: 'All priorities' }
  ]
});

return (
  <div className="flex h-full flex-col gap-4">
    {grid.toolbar}        {/* pivot strips appear here, above the data-view toolbar */}
    <DataGrid table={grid.table} {...grid.gridProps} />
  </div>
);

What the hook does internally:

• Renders <DocyrusPivotFilterGroup> at the top of the returned toolbar, so pivots show up above the existing controls without the consumer having to place them.
• Owns the per-strip selection state via the child-component pattern (each pivot runs its own useDocyrusPivotFilter).
• AND-merges the combined filterRule into resolvedListParams.filters alongside the saved view filter, toolbar filter, and side-panel filter — so pivot selections are applied to the items query.
• Feeds the external filter chain (saved view + toolbar + side, without the pivot's own rule) back into each pivot as activeFilters so pill counts cross-react when the user changes those filters too.
• Exposes the combined rule via pivotFilterRule on the return — useful for badges, persistence, or downstream pages that mirror the same scope.

Each pivotFilters[i] entry accepts the same shape as DocyrusPivotFilterGroupField:

For pages that need pivot strips outside the grid's toolbar (e.g. above a calendar or map), reach for the lower-level useDocyrusPivotFilter or <DocyrusPivotFilterGroup> directly.

Side panel filters

When enableSideFilters is true, the hook renders a <DataTableSideFilters> rail alongside the grid. The panel emits a RuleGroupType whenever the user adjusts a filter; the hook ANDs it onto the saved view's filterQuery and any toolbar filter menu rules before sending the items request — so side filters, toolbar filters, and the saved view all stack.

The toolbar filter menu (enableFilterMenu) is not auto-hidden; both can be active at the same time.

Collapse / expand

• sideFiltersDefaultExpanded controls the initial state. Default true.
• When expanded, a panel-close icon (top right of the panel header) collapses it to a vertical rail.
• When collapsed, the rail shows a 90°-rotated "Filters" label (with the active-filter count appended) that re-expands the panel on click.
• For controlled collapse state, pass sideFiltersExpanded + onSideFiltersExpandedChange.

DocyrusDataGridSideFiltersConfig<TData>

Usage

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { DataGrid } from '@docyrus/ui/components/data-grid';
import { useDocyrusDataGrid } from '@docyrus/ui/library/hooks/use-docyrus-data-grid';
import { createColumnConfigHelper } from '@docyrus/ui/components/data-table-filter';

type OrganizationRow = { id: string; name: string; status: 'active' | 'archived' };

const dtf = createColumnConfigHelper<OrganizationRow>();

const sideFilterColumns = [
  dtf
    .text()
    .id('name')
    .accessor(row => row.name)
    .displayName('Name')
    .build(),
  dtf
    .option()
    .id('status')
    .accessor(row => row.status)
    .displayName('Status')
    .options([
      { value: 'active', label: 'Active' },
      { value: 'archived', label: 'Archived' }
    ])
    .build()
] as const;

export function OrganizationsGrid() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const {
    table, gridProps, toolbar, sideFilters
  } = useDocyrusDataGrid<OrganizationRow>({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'organization',
    enableSideFilters: true,
    sideFiltersDefaultExpanded: true,
    sideFiltersWidth: 280,
    sideFiltersConfig: {
      columnsConfig: sideFilterColumns,
      strategy: 'server',
      defaults: {
        status: { mode: 'inline-checkbox' }
      }
    }
  });

  return (
    <div className="flex h-full flex-col gap-3">
      {toolbar}
      <div className="flex flex-1 min-h-0">
        {sideFilters}
        <DataGrid table={table} {...gridProps} height="auto" className="flex-1" />
      </div>
    </div>
  );
}

Advanced AND/OR filtering

The toolbar chip bar can express exactly one rule per column, all ANDed, with no combinator control — so status = Active OR owner = me has nowhere to live in it. The advanced filter panel is the surface for that query: a full QueryBuilderDocyrus with OR, nesting and the complete operator vocabulary, without having to save a view.

It rides in the toolbar next to the filter chips (part of enableFilterMenu) and needs no extra option to turn on.

How it composes with the chips

The advanced group is ANDed with the chip bar, and the chips stay live and editable beside it. Nothing is converted between the two surfaces in either direction — chips → group would be redundant (the chips already reach the wire) and group → chips is provably lossy (one rule per column, no combinator, no nesting).

The cost of two live surfaces is that a chip can contradict an advanced rule and return zero rows. That is stated in words inside the panel rather than hidden, and the group also shows as a chip in the same row so it is never invisible.

It is a draft editor

Nothing is written to the grid until Apply, and Apply prunes the group first. This is not politeness about request volume: the shapes react-querybuilder produces mid-edit are hard errors on /items (a rule with no field yet, a between holding an empty string) or silent zero-row answers (a freshly added empty group). Writing on every keystroke would blank the grid while the user is still typing, with no error surfaced anywhere.

Limits: 10 rules and 2 levels of nesting (ADVANCED_FILTER_MAX_RULES / ADVANCED_FILTER_MAX_DEPTH).

Where the group is stored

Under a reserved columnFilters entry (__advanced_filter__), not a parallel state slice. columnFilters is already lifted into this hook, fed to TanStack as controlled state, reset on view switch, rehydrated from the saved view / per-user overlay / session cache, snapshotted by persistState and passed to the filter builder — a reserved entry inherits all six wirings for free.

It is safe to park there because ColumnFiltersState carries no schema constraint, TanStack's filtered row model skips an unknown column id silently, and the chip bar skips any id with no column type — so a client-side grid is unaffected and no phantom chip is ever rendered.

Field Type → Cell Variant Mapping

The hook maps every Docyrus field type to the matching DataGrid cell variant when generating columns from dataSource.fields:

Enum option resolution

For enum-backed fields (field-status, field-enum, field-systemEnum, field-select, field-radioGroup, field-multiSelect, field-tagSelect), options are read from the field's enums array (returned by the expand=enums data source fetch) and fall back to options if enums is absent. Each option's slug becomes the cell value and name becomes the label; color is forwarded when present.

Status cells

field-status renders with StatusCell, not the plain select. Options may carry parent (two-level status → sub-status lists, shown as "Main › Sub"), isFinalOption (closing statuses get a check mark) and forceDescription / forceFollowupDate. When a real data source is bound, the hook wires tableMeta.onStatusUpdate to POST /v1/apps/{app}/data-sources/{ds}/status-update/{fieldSlug}; the cell then asks for the required note / follow-up date before saving and logs the activity in addition to writing the value through the normal cell update — the endpoint only records the activity, it does not change the row. Without onStatusUpdate (local data), the cell behaves like a select and never asks for details it could not persist.

Out of scope

field-userSelect, field-userMultiSelect, field-relation, and field-relatedField need extra metadata that is not part of the data source field response (user list, related data source id). They fall back to short-text — pass mapColumn to render a richer cell when your app has the extra info on hand.

Translating column headers

Column headers default to each field's schema label (field.name). Pass dynamicLabelTranslator to remap them from your own i18n dictionary — the hook calls it once per column and renders whatever string you return. Omit the prop and headers stay exactly as the schema defines them.

The function receives the raw label and returns the display text. Return the label unchanged for anything you don't want to translate:

// Simple dictionary
const labels: Record<string, string> = {
  Name: 'İsim',
  Status: 'Durum',
  Description: 'Açıklama'
};

const { table, gridProps, toolbar } = useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicLabelTranslator: (label) => labels[label] ?? label
});

// With an i18n library (i18next, next-intl, …)
const { t } = useTranslation();

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicLabelTranslator: (label) => t(`fields.${label}`, label)
});

Translating enum options

dynamicLabelTranslator only touches field-level labels (headers). To translate the option labels inside enum-backed cells and filter dropdowns (field-select, field-status, field-radioGroup, field-enum, field-multiSelect, field-tagSelect), pass dynamicEnumOptionTranslator.

Enum options carry a stable, language-independent slug (the stored value) plus a display name. Key your translation by enums.<field.slug>.<option.slug> and translate only name — slug, color, and icon are preserved automatically:

const { t } = useTranslation();

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicEnumOptionTranslator: (option, field) =>
    t(`enums.${field.slug}.${option.slug}`, option.name)
});

// Simple dictionary keyed by option slug
const statusLabels: Record<string, string> = { open: 'Açık', done: 'Tamamlandı' };

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicEnumOptionTranslator: (option) =>
    option.slug ? statusLabels[option.slug] ?? option.name : option.name
});