useDocyrusDataGrid

Installation

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

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

A port of the web hook with the same option and result names. It composes useDocyrusDataViewSelect (schema, views, forms) with the native useDataGrid controller, and returns table + gridProps for <DataGrid> and a ready-made toolbar. It needs an authenticated RestApiClient and a QueryClientProvider above it; mount DocyrusTenantProvider to get tenant date / number formats in every cell.

Overview

• Columns — one TanStack column per schema field (getCellOpts → cell variant), the data source's label field synthesized when the API omits it, duplicate slugs deduped, identity / autonumber / metadata-readOnly fields locked.
• Items query — GET /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/items (or collection.list) with columns (relations projected as slug(id, name, autonumber_id[, iconField][, borrowed…])), expand, orderBy (live sort beats the view preset), filters (saved view + toolbar chips + advanced group + pivot rules + listParams.filters, ANDed), debounced filterKeyword, and limit / offset / fullCount in standard paging. A phantom column reported by the backend is stripped and the request retried.
• Saved views — gridViewSelectProps drives the native DataGridViewSelect; the active view is applied to the table (visibility, order, pinning with select / actions kept first, sort, grouping, row height, paging, inline editing, color rules).
• Advanced filter — DataGridAdvancedFilter stores its AND/OR group under the reserved __advanced_filter__ column-filter entry, ANDed with the chips.
• Borrowed relation columns (enableRelationColumns) — GET /v1/dev/data-sources/:id/fields?expand=parent; hidden until picked in the Fields sheet, one hop, positive-only filters (rel_<relation>/<field>).
• Inline editing — change tracking (save / discard bar) → PATCH …/items/bulk (or collection.updateMany); status cells post to …/status-update/{field} through tableMeta.onStatusUpdate.
• Bulk actions — update / delete / export / email / message on the selection bar (see Native deltas).
• Gallery mode — per-view galleryCardConfig / galleryDisplayConfig (saved view → cardConfig option → detectCardConfigFromFields), editable from the toolbar gallery menus and the view editor.
• Form binding — activeViewFormId / activeViewForm / formViewProps for a companion useDocyrusFormView.
• Persistence — persistState snapshots search, filters, sort, grouping, row height, display mode, column layout, page size and pivot selection per active view.

Usage

import { View } from 'react-native';

import { useDocyrusClient } from '@docyrus/signin/react-native';

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

export function OrganizationsScreen() {
  const client = useDocyrusClient();
  const { table, gridProps, toolbar, pagingMode } = useDocyrusDataGrid({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'organization',
    persistState: true,
    pivotFilters: [{ fieldSlug: 'status' }],
    enableRelationColumns: true
  });

  return (
    <View className="flex-1">
      {toolbar}
      <DataGrid table={table} {...gridProps} pagingMode={pagingMode} />
    </View>
  );
}

Bulk update / compose dialogs

Like web, the update / email / message bulk actions open the native BulkUpdateDialog / EmailComposeDialog / InstantMessageComposeDialog out of the box, and email / phone cells open the compose dialogs through tableMeta.emailClient / messageClient. Override any of them:

const { toolbar, table, gridProps } = useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'contact',
  // optional overrides — omit to use the built-in native dialogs
  renderBulkUpdateDialog: props => <MyBulkUpdateSheet {...props} />,
  onBulkMessage: phones => openWhatsApp(phones)
});

The dialogs are rendered inside toolbar, so render toolbar even when you hide its controls.

Side filters and the vertical-tabs side panel

const { toolbar, table, gridProps, sideFilters, sidePanel } = useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'contact',
  viewSelectVariant: 'vertical-tabs',
  enableSideFilters: true,
  sideFiltersConfig: {
    columnsConfig: [
      { id: 'status', accessor: row => row.status, displayName: 'Status', type: 'option', options: statusOptions },
      { id: 'created_on', accessor: row => row.created_on, displayName: 'Created', type: 'date' }
    ]
  }
});

return (
  <View className="flex-1">
    {sidePanel}
    {toolbar}
    <View className="flex-row px-3">{sideFilters}</View>
    <DataGrid table={table} {...gridProps} />
  </View>
);

sideFilters defaults to presentation: 'sheet': the node is a "Filters (n)" trigger that opens the panel as a bottom sheet. sideFiltersConfig.presentation: 'inline' renders web's collapsible column in place (tablets), bound to sideFiltersExpanded. The emitted rule group is ANDed into the items query.

API Reference

Options (UseDocyrusDataGridOptions<TData>)

Every useDocyrusDataViewSelect option (client, appSlug, dataSourceSlug, appId, dataSource, overrideFields, mapField, staleTime, enabled, enableDataViews, dataSourceExpand, enableForms, persistActiveView, persistKey, activeViewStorage, defaultRowGroupingColumn, systemViews) is accepted and forwarded, plus:

Data & query

Columns

Grid behaviour (forwarded to useDataGrid)

Toolbar

Bulk actions & compose

Side filters

DocyrusDataGridSideFiltersConfig<TData>:

Gallery, forms, accepted-for-parity

Result (UseDocyrusDataGridResult<TData>)

Everything useDocyrusDataViewSelect returns (gridViewSelectProps wraps the gallery config into view save / create; fields honour excludeFieldSlugs), plus:

Native deltas

• Toolbar layout — stacked (pivot strips, view picker, search, one horizontally scrollable row of compact triggers + toolbarEndContent) instead of web's single wrapping row.
• Email / phone cells — tapping opens an action sheet (web: on-hover icons). Like web, tableMeta.emailClient / messageClient = client, so "Compose email" / "Send message" open the grid's own compose dialogs. When renderEmailComposeDialog / onBulkEmail (resp. message) is supplied, the cells route to that override through tableMeta.onComposeEmail / onSendMessage.
• Bulk update / email / message — open the native BulkUpdateDialog / EmailComposeDialog / InstantMessageComposeDialog (bottom sheets). Precedence for email / message: onBulkEmail / onBulkMessage → render*ComposeDialog → default dialog → Linking (mailto: / sms:, only without a client).
• Bulk export — ActionSheet (CSV / Excel / JSON / Markdown); the file is written to the cache directory and shared (optional expo-file-system + expo-sharing).
• Side filters — sideFilters is the native DataTableSideFilters, presentation: 'sheet' by default (web: a collapsible column; available as 'inline').
• Vertical tabs — sidePanel is a DataGridSidePanel: a strip whose view list opens as a bottom sheet on phones, a side column on tablets (≥ 768 dp).
• UUID copy — uses the optional expo-clipboard peer, falling back to the share sheet.
• Storage — persistState uses lib/storage ('session' = in-memory for the process, 'local' = the registered persistent store).
• gridProps.onRefresh — pull-to-refresh runs the records-only reload.
• enableColumnReorder, showDropdownChevron, enablePaste are ignored; column order / pinning live in the Fields sheet.
• New i18n keys: ui.dataGrid.bulkUpdate, ui.dataGrid.bulkDelete, ui.dataGrid.bulkEmail, ui.dataGrid.bulkMessage, ui.dataGrid.reload, ui.dataGrid.exportFormatCsv|Xlsx|Json|Markdown (web hard-codes these labels).

Exports

Type Exports