Hooks

useDocyrusPivotCalendar

PivotCalendar backed by a Docyrus data source. Aggregates per day or month in the database through a pivot matrix, optionally grouped by a relation, and turns a tapped value into a ready-to-run drilldown query.

iOSAndroidExpo Go

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-pivot-calendar
Required Packages(3 packages)
pnpm add @docyrus/api-client @tanstack/react-query date-fns

A straight port of the web hook, with the same signature. It sends a pivot.matrix + calculations request to GET /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/items through TanStack Query:

  • The date axis is bucket:to_char[YYYY-MM-DD]@<dateField> (YYYY-MM for the year view) over a dateRange covering the active period.
  • With groupBy, a second matrix entry adds groupLabel:<labelField> (plus groupId:<idField> when idField is set).

The response is mapped into cells + groups, and pivotCalendarProps is ready to spread onto the native PivotCalendar. It needs an authenticated RestApiClient and a QueryClientProvider above it. Only the first 2 measures are requested, same as web.

Usage

import { useState } from 'react';

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

import { PivotCalendar } from '@/components/docyrus-native/pivot-calendar';
import {
  useDocyrusPivotCalendar,
  type DocyrusPivotDrilldownQuery
} from '@/hooks/docyrus-native/use-docyrus-pivot-calendar';

const toHours = (seconds: number) => seconds / 3600;

export function TimeEntriesCalendar() {
  const client = useDocyrusClient();
  const [drilldown, setDrilldown] = useState<DocyrusPivotDrilldownQuery | null>(null);

  const { pivotCalendarProps, buildDrilldownQuery } = useDocyrusPivotCalendar({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'time_entry',
    dateField: 'date',
    measures: [
      { id: 'logged', label: 'Logged', field: 'duration', func: 'sum', transform: toHours, formatValue: v => `${v.toFixed(1)}h`, color: '#10b981' },
      { id: 'billable', label: 'Billable', field: 'duration_billable', func: 'sum', transform: toHours, formatValue: v => `${v.toFixed(1)}h`, color: '#6366f1' }
    ],
    groupBy: { field: 'record_owner', label: 'User', labelField: 'name', idField: 'user_id' },
    persistState: true,
    // `drilldown.filters` / `columns` / `orderBy` → fetch the underlying records.
    onCellClick: info => setDrilldown(buildDrilldownQuery(info))
  });

  return <PivotCalendar {...pivotCalendarProps} />;
}

API Reference

Options

OptionTypeDefaultDescription
clientRestApiClient—Required. Authenticated Docyrus API client.
appSlugstring—Required. App slug of the data source.
dataSourceSlugstring—Required. Data source slug.
dateFieldstring—Required. Date field that is bucketed per day or month (e.g. created_on, due_date).
measuresDocyrusPivotMeasure[]—Required. Measures to aggregate. Only the first 2 are requested and rendered.
groupByDocyrusPivotGroupBy—Optional grouping dimension (relation, user or select field).
columnsstring—Extra columns segment for the request. Defaults to a relation spread (...<groupBy.field>(<labelField>)) or id.
filtersunknown—Filters applied to the aggregated records. They are also merged into the drilldown query.
defaultViewTPivotCalendarView'month-calendar'Initial view.
viewTPivotCalendarView—Controlled view.
onViewChange(view: TPivotCalendarView) => void—Called when the view changes.
defaultDateDatenew Date()Initial reference date.
dateDate—Controlled reference date.
onDateChange(date: Date) => void—Called when the reference date changes.
hideViewSwitcherboolean—Pass-through to PivotCalendar.
hideSidebarboolean—Pass-through to PivotCalendar (hides the group filter sheet).
visibleViewsTPivotCalendarView[]—Pass-through to PivotCalendar.
enabledbooleantrueEnables or disables the query.
staleTimenumber30000TanStack Query staleTime (ms).
showEmptyCellsbooleantrueWhen false, sends pivot.hideEmptyRows: true.
onCellClick(info: IPivotCalendarCellClick<PivotRow>) => void—Fires when a value is tapped. Pair it with buildDrilldownQuery.
persistStateboolean | { storage?: 'session' | 'local'; key?: string }—Persists the uncontrolled view and focused date under docyrus:view-params:<appSlug>:<dataSourceSlug>:pivot-calendar. true / 'session' is in-memory for the JS runtime. 'local' uses the store registered with <DocyStorageProvider> / setDocyLocalStore() and survives restarts. Controlled view / date always win.

DocyrusPivotMeasure

FieldTypeDescription
idstringStable id; also the calculation name in the response.
labelstringVisible label.
shortLabelstringCompact label for headers.
fieldstringField slug to aggregate ('id' for count).
func'sum' | 'count' | 'avg' | 'min' | 'max'Aggregation function.
transform(value: number) => numberApplied to the API value (e.g. seconds → hours).
formatValue(value: number) => stringCell formatter.
colorstringAccent colour.
descriptionstringShown in the day sheet.

DocyrusPivotGroupBy

FieldTypeDescription
fieldstringGrouping relation / select field slug.
labelstringLabel for the filter sheet and the grid's group column.
labelFieldstringSub-field used as the group label. Default 'name'.
idFieldstringNon-join sub-field used as a stable group id (e.g. 'user_id' for users). With it, drilldown filters use <field> = <id>; without it, they use rel_<field>/<labelField> = <label>.
filtersunknownFilters on the group dimension's CTE.
toGroup(row: PivotRow) => Partial<IPivotCalendarGroup>Avatar / colour override per group.

Result

FieldTypeDescription
pivotCalendarPropsPivotCalendarProps<TData>Spread onto <PivotCalendar /> (remote mode).
cellsIPivotCalendarRemoteCell[]Mapped cells.
groupsIPivotCalendarGroup[]Groups found in the response, sorted by label.
measuresIPivotCalendarMeasure<TData>[]Component measures.
view / setViewTPivotCalendarView / (view) => voidActive view.
selectedDate / setSelectedDateDate / (date) => voidReference date.
isLoadingbooleanFirst load in flight.
errorError | nullQuery error.
refetch() => voidRefetch the pivot.
buildDrilldownQuery(info: IPivotCalendarCellClick<TData>) => DocyrusPivotDrilldownQueryConverts a tap into filters (date between + group + caller filters), columns and orderBy, ready for /items.

DocyrusPivotDrilldownQuery

FieldTypeDescription
appSlug / dataSourceSlug / dateFieldstringSource identity.
groupField / groupLabelstring / string | nullGroup dimension and the tapped group's label.
bucketStart / bucketEndDateBucket range.
bucketStartIso / bucketEndIsostringSame range as ISO strings.
measureField / measureFuncstring / TPivotCalendarAggregateTapped measure source.
measure / measureValue / measureFormattedIPivotCalendarMeasure<PivotRow> / number / stringTapped measure and value.
filtersDocyrusPivotFilterGroup{ combinator: 'and', rules }.
columnsstringSuggested columns.
orderBystring<dateField> DESC.

Type Exports

TypeDescription
UseDocyrusPivotCalendarOptionsHook options.
UseDocyrusPivotCalendarResult<TData>Hook result.
DocyrusPivotMeasureMeasure descriptor.
DocyrusPivotGroupByGrouping descriptor.
DocyrusPivotFilterRule / DocyrusPivotFilterGroupDrilldown filter shapes.
DocyrusPivotDrilldownQuerybuildDrilldownQuery result.
PivotRowRecord<string, unknown>.

On this page