useDocyrusKanban

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-kanban

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query @dnd-kit/core @dnd-kit/sortable react-querybuilder

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

Overview

useDocyrusKanban is the kanban-first companion to useDocyrusDataGrid. It wires a Docyrus data source to a fully configured <Kanban> board with:

• saved-view filters, sorting, and search wiring (via useDocyrusDataViewSelect)
• automatic column derivation from the field type you point it at
• drag-to-update persistence (PATCH /items/:id)
• final-zone integration when the group-by field is a field-status
• a ready-to-render standard card layout (avatar, title, description, footer with user + audit info)

Supported group-by field types

The groupByFieldSlug you pass must point to one of these field types:

For enum-backed fields, the hook automatically appends the field slug to the request expand array so each row's value carries the option's color and icon. The same is done for field-userSelect so the user payload (photo, name, team) is available for column headers and card avatars.

Card contract

Every card is rendered with the same standard layout — only the field bindings change:

┌─────────────────────────────────────────────┐
│ ◯  Title                              ⋮     │ ← avatarColumn + titleColumn + menu
│    Description                              │ ← descriptionColumn
│                                             │
│    {cardContent}                            │ ← free-form children
│                                             │
│ ◎                                       ℹ︎  │ ← userColumn + audit tooltip
└─────────────────────────────────────────────┘

Override the menu either by listing items directly or by passing a function that receives the defaults — the function form lets you keep Open/Edit/Delete and append additional entries.

Usage

Status-driven board (enum + final zone)

'use client';

import { useDocyrusAuth } from '@docyrus/signin';
import { useDocyrusKanban } from '@docyrus/ui/library/hooks/use-docyrus-kanban';

type LeadRow = {
  id: string;
  name: string;
  description?: string;
  status: { id: string; name: string };
  assigned_to?: { id: string; firstname: string; lastname: string; photo?: string };
  icon?: string;
  color?: string;
};

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

  if (!client) return null;

  const { toolbar, board } = useDocyrusKanban<LeadRow>({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'lead',
    groupByFieldSlug: 'status',
    avatarColumn: 'icon', // any field whose value is an icon/color/image bag
    titleColumn: 'name',
    descriptionColumn: 'description',
    userColumn: 'assigned_to',
    onCardOpen: row => router.push(`/crm/leads/${row.id}`),
    onCardEdit: row => openEditDialog(row.id)
  });

  return (
    <div className="flex h-full flex-col">
      {toolbar}
      <div className="flex-1 overflow-hidden">{board}</div>
    </div>
  );
}

Date board with the Group By picker

const { toolbar, board } = useDocyrusKanban<TaskRow>({
  client,
  appSlug: 'project',
  dataSourceSlug: 'task',
  groupByFieldSlug: 'due_date',     // field-date or field-dateTime
  dateGroupBy: 'week',              // Day | Week | Month — switchable via toolbar
  titleColumn: 'subject',
  descriptionColumn: 'summary',
  userColumn: 'assigned_to'
});

When the group-by field is a date or datetime field the toolbar automatically renders a "Group by" Select with Day, Week, and Month. The time portion is always ignored — buckets are computed from the UTC date components only.

User board with User/Team toggle

const { toolbar, board } = useDocyrusKanban<TaskRow>({
  client,
  appSlug: 'project',
  dataSourceSlug: 'task',
  groupByFieldSlug: 'assigned_to',  // field-userSelect
  userGroupBy: 'team',              // User | Team — switchable via toolbar
  avatarColumn: 'icon',
  titleColumn: 'subject',
  descriptionColumn: 'description',
  userColumn: 'assigned_to'
});

userGroupBy: 'team' reads team_id (or a nested team.id) off the user payload returned by expand=assigned_to. Cards remain draggable in 'user' mode and become read-only in 'team' mode (since teams aren't a writable field on the user reference).

Show all columns (enum) toggle

For enum-backed fields the toolbar renders a Show all switch (default true) that mirrors the showAllColumns option:

• true (default): every enum option is rendered as a column even when no record currently maps to it. Useful when you want users to be able to drop a card into a fresh stage.
• false: only columns with at least one record are rendered.

const { toolbar, board, showAllColumns, setShowAllColumns } = useDocyrusKanban({
  /* … */
  showAllColumns: false    // initial value — the toolbar switch still controls it
});

Final zone (status fields)

When the group-by field is field-status, every enum option flagged is_final_option is rendered inside a <KanbanFinalZone> below the main board instead of as a board column:

const { board } = useDocyrusKanban({
  /* … */
  groupByFieldSlug: 'status'
});

Dragging a card into a final-zone column issues the same PATCH /items/:id as dragging between board columns — the only difference is that final columns aren't rendered side-by-side with the active stages.

API Reference

Parameters

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

Return Value

Drag-and-drop persistence

When a card is dropped into a different column the hook computes a payload based on the field type and either:

• calls collection.update(id, payload) if the consumer passed a TanStack DB collection with an update method, or
• issues a PATCH /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:id with the RestApiClient from @docyrus/signin.

Pass onItemMoveCommit to skip the built-in PATCH entirely (e.g. for optimistic updates with rollback) and onItemMove to mirror the change in local state without replacing the mutation.

Field type → column derivation matrix

Out of scope

• field-relation, field-multiSelect, and field-tagSelect are intentionally not surfaced as group-by candidates — relation fields would require additional metadata to render meaningful column headers and multi-value fields don't map cleanly onto a single column. If you need to group by one of these, render your own board with the same useDocyrusDataViewSelect wiring.