@docyrus/docyrus 0.0.67 → 0.0.68

package/resources/pi-agent/skills/docyrus-data-grid-page-design/references/hook-pages.md

@@ -0,0 +1,183 @@
+# Hook-first Docyrus DataGrid Pages
+
+## Use this path when
+
+- The page is a normal Docyrus records/index page.
+- Rows come from a Docyrus items endpoint or a generated collection hook.
+- Saved views should drive visible columns, sorting, filters, grouping, paging, and toolbar state.
+- You want the fastest path to a production page.
+
+## Minimal page shell
+
+```tsx
+'use client';
+
+import { useMemo } from 'react';
+
+import { useDocyrusAuth } from '@docyrus/signin';
+import {
+  DataGrid,
+  getDataGridActionsColumn,
+  type ColumnDef
+} from '@docyrus/ui/components/data-grid';
+import { useDocyrusDataGrid } from '@docyrus/ui/library/hooks/use-docyrus-data-grid';
+import { Button } from '@docyrus/ui/primitives/ui/button';
+
+type OrganizationRow = { id: string; name?: string };
+
+export function OrganizationsPage() {
+  const { client } = useDocyrusAuth();
+
+  if (!client) return null;
+
+  return <OrganizationsPageInner client={client} />;
+}
+
+function OrganizationsPageInner({ client }: { client: NonNullable<ReturnType<typeof useDocyrusAuth>['client']> }) {
+  const actionsColumn = useMemo<ColumnDef<OrganizationRow>>(
+    () => getDataGridActionsColumn<OrganizationRow>({
+      cell: ({ row }) => (
+        <Button size="sm" variant="ghost" onClick={() => { void row.original.id; }}>
+          Open
+        </Button>
+      )
+    }),
+    []
+  );
+
+  const { users } = useUsers();
+  const { formatDate, formatDateTime, formatNumber } = useGridFormatters();
+
+  const { table, gridProps, toolbar, resolvedListParams } = useDocyrusDataGrid<OrganizationRow>({
+    client,
+    appSlug: 'crm',
+    dataSourceSlug: 'organization',
+    actionsColumn,
+    users,
+    formatDate,
+    formatDateTime,
+    formatNumber,
+    listParams: { limit: 50 },
+    defaultRowGroupingColumn: 'status'
+  });
+
+  return (
+    <div className="flex h-full flex-col gap-4 overflow-hidden px-6 py-5">
+      <div className="shrink-0">{toolbar}</div>
+      <div className="min-h-0 flex-1">
+        <DataGrid table={table} {...gridProps} height="auto" />
+      </div>
+    </div>
+  );
+}
+```
+
+If a generated collection already exists, pass `collection` to `useDocyrusDataGrid` and let the hook call `collection.list(resolvedListParams)` instead of the direct items endpoint.
+
+## Data modes
+
+1. `data`: pass pre-resolved rows when another part of the page owns fetching.
+2. `collection`: pass a generated collection hook; the hook calls `collection.list(resolvedListParams)`.
+3. direct API: pass only `client`, `appSlug`, and `dataSourceSlug`.
+
+Use `onReload` when you use `data` mode, because the hook cannot refetch rows on its own there.
+
+## High-value options
+
+### Columns and toolbar
+
+- `actionsColumn`: add per-row actions right after the select column.
+- `extraColumns`: prepend custom columns before metadata-generated Docyrus fields.
+- `mapColumn`: override or skip generated field columns.
+- `defaultRowGroupingColumn`: seed a default grouping for views that do not define one.
+- `systemViews`: add static developer-defined views before saved backend views.
+- `enableViewSelect`, `enableSearchInput`, `enableFilterMenu`, `enableGroupMenu`, `enableSortMenu`, `enableRowHeightMenu`, `enableDisplayMenu`, `enableReloadButton`: trim the standard toolbar.
+- `showSelectColumn`, `enableRowMarkers`: control the left-most reserved column.
+
+### Query shape
+
+- `listParams`: append query params like `limit`, `fullCount`, `expand`, or custom backend flags. `listParams` overrides win against the hook's defaults, so use this to pin paging or add tenant-specific flags.
+
+### Tenant-aware formatters
+
+- `formatDate?: (value) => string` — wired into `DateCell` display.
+- `formatDateTime?: (value) => string` — wired into `DateTimeCell` display.
+- `formatNumber?: (value, opts?: { variant?: 'number' | 'currency' | 'percent'; currency?: string }) => string` — wired into `NumberCell` / `CurrencyCell` / `PercentCell` display.
+
+Build these from `@docyrus/app-utils` (`createDateUtils` + `createNumberUtils` over `getTenantPreferences`). See `tenant-and-users-providers.md` for the standard provider pattern.
+
+### Shared users list
+
+- `users?: ReadonlyArray<CellUserOption>` — seeds the static option list for `field-userSelect` and `field-userMultiSelect` cells.
+  - When supplied, those cells render avatars + labels from this list immediately.
+  - When not supplied, cells fall back to the row's expanded `{ id, name, photo }` payload (which is why the auto-expand for reference fields matters — see below).
+  - Type with `import { type CellUserOption } from '@docyrus/ui/components/data-grid'`.
+
+## How backend query params are derived
+
+The hook builds `resolvedListParams` from the active view and toolbar state:
+
+- `columns`: visible field slugs, with `id` always first.
+- `orderBy`: mapped from `view.sorting`.
+- `filters`: AND-merge of `view.filterQuery` (saved view) and the toolbar filter menu's transient state. Toolbar filter changes refetch the items query automatically (no extra wiring needed in standard mode).
+- `filterKeyword`: mapped from the debounced toolbar search input.
+- `expand`: every visible reference-type column slug is added automatically. Covered types: `field-userSelect`, `field-userMultiSelect`, `field-relation`, `field-relatedField`, `field-select`, `field-radioGroup`, `field-enum`, `field-systemEnum`, `field-multiSelect`, `field-tagSelect`, `field-status`, `field-approvalStatus`.
+- `limit` / `offset`: default to `100` / `0`, then `listParams` wins.
+- grouping column safety: the active grouping field is appended even if the saved view hides it.
+
+Inspect `resolvedListParams` when you need debugging, analytics, export, or a "copy query" action.
+
+## Filter menu (`DataGridFilterMenu`) behavior
+
+The hook's toolbar wires the filter menu so it pulls live data from the backend instead of only filtering loaded rows.
+
+- Toolbar filter additions/changes trigger a refetch with the merged `filters` payload.
+- Filter changes reset `pageIndex` to 0 so a stale offset can't land out of bounds.
+- Toolbar filters are session-transient and clear when the active view changes.
+- Field type to filter type mappings:
+  - `field-userSelect`, `field-userMultiSelect`, `field-relation`, `field-relatedField`, `field-multiSelect`, `field-tagSelect` → `multiOption` (server `in` operator), with debounced async option search.
+  - `field-status`, `field-approvalStatus`, `field-enum`, `field-systemEnum`, `field-select`, `field-radioGroup` → `option` with the field's static enum options.
+  - `field-checkbox`, `field-switch` → `boolean` (true / false / empty).
+  - `field-date`, `field-dateTime`, `field-dateRange` → `date` with `is between` for ranges.
+  - `field-money`, `field-currency`, `field-percent`, `field-rating`, `field-duration`, `field-number`, `field-autonumber` → `number`.
+  - `field-file`, `field-image`, `field-chart`, etc. are excluded from the filter menu entirely.
+- Async option search calls `/v1/users` for user fields and `/v1/apps/{appSlug}/data-sources/{slug}/items` for relations. The hook caches the data-sources lookup needed to resolve `relationDataSourceId` (UUID) to the URL slugs, valid for 5 minutes.
+
+## Reserved columns
+
+`useDocyrusDataGrid` always:
+
+- Re-prepends `select` and `actions` to the column order after a saved view is applied (saved views only know real field slugs).
+- Pins both reserved columns to the left so they stay visible during horizontal scroll.
+
+You don't need to configure pinning yourself; the hook merges with whatever the saved view declares.
+
+## Cell variants for reference fields
+
+Out of the box (no `mapColumn` needed):
+
+- `field-userSelect` → `UserCell` with avatar + name. If a static `users` list is passed, options come from there; otherwise the cell reads the row's expanded `{ id, name, photo }` payload directly.
+- `field-userMultiSelect` → `UserMultiSelectCell` (avatar stack). Same options/expanded-payload fallback.
+- `field-relation`, `field-relatedField` → `RelationCell` showing the related record's name (from `expand`).
+- `field-status`, `field-approvalStatus` → `StatusCell` with color + icon from the field's enums.
+- `field-select`, `field-radioGroup` → `SelectCell` with color/icon support.
+- `field-multiSelect`, `field-tagSelect` → multi-select cells with chips.
+- `field-identity` → `UuidCell`. Defaults to `showCopyButton: true` (60px fixed-width icon-only column). Override `mapColumn` to set `showCopyButton: false` for a 300px full-text column.
+- `field-url` → `UrlCell` rendering as a link with `target="_blank"`.
+- `field-money`, `field-currency`, `field-percent`, `field-number` → `NumberCell` family. Honor the `formatNumber` option for tenant-aware locale formatting.
+- `field-date`, `field-dateTime` → `DateCell` / `DateTimeCell`. Honor `formatDate` / `formatDateTime`.
+
+Use `mapColumn` only when you need to override these defaults.
+
+## Important behavior
+
+- `gridProps` already carries the active view's paging settings. Usually you should just spread it into `<DataGrid>`.
+- Backend-saved views store field slugs, not reserved columns like `select` or `actions`. The hook re-prepends and re-pins those reserved columns for you.
+- In `data` mode the search box becomes client-side global filtering. In backend modes it becomes `filterKeyword`.
+- The hook controls TanStack `columnFilters` state. If you build a manual page, replicate this so toolbar filter changes can drive your row query.
+
+## Default recommendation
+
+If the page is a CRUD-style Docyrus list page, start here first. Drop to manual composition only when the toolbar, saved-view lifecycle, or row fetching needs to diverge from the standard behavior.
+
+For system views, hidden views, paging ownership, or translating active views into a custom query pipeline, also read `advanced-saved-view-query-patterns.md`.

package/resources/pi-agent/skills/docyrus-data-grid-page-design/references/manual-pages.md

@@ -0,0 +1,145 @@
+# Manual DataGrid Page Patterns
+
+## Use this path when
+
+- The page uses local/demo data.
+- You need a custom toolbar layout.
+- You want backend-saved views but your own row-query lifecycle.
+- You only need local views and not Docyrus view persistence.
+
+## Local views with full manual composition
+
+```tsx
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+
+import {
+  DataGrid,
+  DataGridFilterMenu,
+  DataGridGroupMenu,
+  DataGridRowHeightMenu,
+  DataGridSortMenu,
+  applyViewToTable,
+  getDataGridActionsColumn,
+  getDataGridSelectColumn,
+  useDataGrid,
+  type ColumnDef,
+  type SavedDataGridView
+} from '@docyrus/ui/components/data-grid';
+import { DataGridViewSelect } from '@docyrus/ui/components/data-grid-view-select';
+
+const columns: ColumnDef<Row>[] = [
+  getDataGridSelectColumn<Row>(),
+  getDataGridActionsColumn<Row>({ cell: ({ row }) => <OpenButton row={row.original} /> }),
+  ...dataColumns
+];
+
+export function TasksPage() {
+  const [views, setViews] = useState<SavedDataGridView[]>(INITIAL_VIEWS);
+  const [activeViewId, setActiveViewId] = useState('all');
+  const activeView = useMemo(() => views.find(view => view.id === activeViewId), [views, activeViewId]);
+
+  const { table, ...gridProps } = useDataGrid<Row>({
+    data: rows,
+    columns,
+    enableSearch: true,
+    enableGrouping: true
+  });
+
+  useEffect(() => {
+    if (!activeView) return;
+    applyViewToTable(table, activeView);
+  }, [table, activeView]);
+
+  return (
+    <div className="flex h-full flex-col gap-4 overflow-hidden">
+      <div className="shrink-0 flex items-center gap-2">
+        <DataGridViewSelect
+          table={table}
+          variant="horizontal-tabs"
+          editable
+          views={views}
+          activeViewId={activeViewId}
+          onViewChange={(view) => setActiveViewId(view.id)}
+          onViewSave={(view) => setViews(prev => prev.map(item => item.id === view.id ? view : item))}
+          onViewCreate={(view) => setViews(prev => [...prev, view])}
+          onViewDelete={(viewId) => setViews(prev => prev.filter(item => item.id !== viewId))} />
+        <DataGridFilterMenu table={table} />
+        <DataGridGroupMenu table={table} />
+        <DataGridSortMenu table={table} />
+        <DataGridRowHeightMenu table={table} />
+      </div>
+      <div className="min-h-0 flex-1">
+        <DataGrid table={table} {...gridProps} height="auto" />
+      </div>
+    </div>
+  );
+}
+```
+
+`DataGridViewSelect` applies views automatically when the user clicks a different tab. The `useEffect` above is still needed for the initial/default view.
+
+## Backend saved views with custom row fetching
+
+```tsx
+const viewSelect = useDocyrusDataViewSelect({
+  client,
+  appSlug: 'crm',
+  dataSourceSlug: 'contacts',
+  defaultRowGroupingColumn: 'status',
+  systemViews: [ALL_CONTACTS_VIEW]
+});
+
+const activeView = useMemo(
+  () => viewSelect.views.find(view => view.id === viewSelect.activeViewId),
+  [viewSelect.views, viewSelect.activeViewId]
+);
+
+const { table, ...gridProps } = useDataGrid<Row>({ data: rows, columns, enableGrouping: true });
+
+useEffect(() => {
+  if (!activeView) return;
+  applyViewToTable(table, activeView);
+}, [table, activeView]);
+
+<DataGridViewSelect table={table} editable {...viewSelect.gridViewSelectProps} />
+```
+
+Important: `useDocyrusDataViewSelect` gives you `views`, `fields`, `activeViewId`, CRUD callbacks, hidden-view state, and persistence. It does **not** fetch rows. If the active view should also shape the backend query, translate `activeView.columnVisibility`, `columnOrder`, `sorting`, and `filterQuery` into your request yourself or switch to `useDocyrusDataGrid`.
+
+## Manual toolbar building blocks
+
+Use these when you do not want the prebuilt hook toolbar:
+
+- `DataGridViewSelect`
+- `DataGridFilterMenu`
+- `DataGridSortMenu`
+- `DataGridGroupMenu`
+- `DataGridRowHeightMenu`
+- `DataGridDisplayMenu`
+- `DataGridViewMenu`
+- your own search input wired to `table.setGlobalFilter(...)` or to backend query state
+
+For persistence, system views, paging ownership, or manual translation of the active view into Docyrus query params, also read `advanced-saved-view-query-patterns.md`.
+
+## What you lose by going manual
+
+`useDocyrusDataGrid` does several things automatically that manual mode does **not**:
+
+- **Auto-`expand`** for reference fields. In manual mode you must add reference field slugs to your request's `expand` array yourself, or rich cells (user / relation / select / status) will only see bare IDs.
+- **Reserved-column pinning.** `select` and `actions` are not auto-pinned to the left in manual mode — call `table.setColumnPinning({ left: ['select', 'actions'], right: [] })` after applying the active view.
+- **Filter menu refetch wiring.** `DataGridFilterMenu` writes through to `table.setColumnFilters`, but a manual page's row query doesn't watch that state. You need to read `table.getState().columnFilters` (or lift the state into the host) and translate the filter values into your request's `filters` payload. Reset `pageIndex` to 0 on changes.
+- **Async option search for relation/user filter columns.** The filter menu will show empty option lists unless you pass a `getAsyncOptions` resolver (signature: `(column) => AsyncOptionsConfig | undefined`) that calls `/v1/users` for user fields and `/v1/apps/{appSlug}/data-sources/{slug}/items` for relations.
+- **Tenant-aware formatters.** Pass `formatDate`, `formatDateTime`, `formatNumber` through `useDataGrid({ meta: { ... } })`. Cells read them from `tableMeta`.
+- **Shared users list.** Pass `users: ReadonlyArray<CellUserOption>` to `buildTanstackColumnDef({ users })` (or set the `cell.options` directly via `mapColumn`) so user cells get avatar + label from the global list.
+
+If any of these matter to the page, prefer `useDocyrusDataGrid` and use `mapColumn` / `extraColumns` / toolbar enable flags to customize.
+
+## Gotchas
+
+- Local/manual `SavedDataGridView` objects can include reserved columns like `select` and `actions` in `columnOrder`.
+- Backend Docyrus-saved views store real field slugs only. If you want the standard reserved-column behavior, `useDocyrusDataGrid` is the safest path.
+- Pass `fields` into `DataGridViewSelect` when you want the filter builder inside the editor.
+- Pass `isSaving` and `isLoading` when the host owns async view CRUD.
+- For manual Docyrus item requests, always send `columns`. Add reference-type field slugs (`field-userSelect`, `field-userMultiSelect`, `field-relation`, `field-relatedField`, `field-select`, `field-radioGroup`, `field-enum`, `field-systemEnum`, `field-multiSelect`, `field-tagSelect`, `field-status`, `field-approvalStatus`) to `expand` so the API returns `{ id, name, ... }` payloads.

package/resources/pi-agent/skills/docyrus-data-grid-page-design/references/tenant-and-users-providers.md

@@ -0,0 +1,290 @@
+# Tenant Preferences and Shared Users Providers
+
+`useDocyrusDataGrid` accepts two tenant-scoped inputs that should be sourced from app-level providers, not refetched per page:
+
+- **Tenant preferences** → drives `formatDate`, `formatDateTime`, `formatNumber` so date and money cells respect regional settings.
+- **Shared users list** → seeds `field-userSelect` / `field-userMultiSelect` cell options so avatar + name render instantly without per-row fetches.
+
+Both should be fetched **once** at app boot and re-used everywhere.
+
+## Tenant preferences provider
+
+Source the utilities from `@docyrus/app-utils`:
+
+```ts
+import {
+  getTenantPreferences,
+  createDateUtils,
+  createNumberUtils,
+  type DateUtils,
+  type NumberUtils,
+  type TenantPreferences
+} from '@docyrus/app-utils';
+```
+
+### Provider shape
+
+```tsx
+'use client';
+
+import {
+  createContext, useContext, useMemo, type ReactNode
+} from 'react';
+
+import { useDocyrusAuth } from '@docyrus/signin';
+import { useQuery } from '@tanstack/react-query';
+
+interface TenantContextValue {
+  preferences: TenantPreferences | null;
+  dateUtils: DateUtils | null;
+  numberUtils: NumberUtils | null;
+  isLoading: boolean;
+}
+
+const TenantContext = createContext<TenantContextValue>({
+  preferences: null,
+  dateUtils: null,
+  numberUtils: null,
+  isLoading: false
+});
+
+export function TenantProvider({ children }: { children: ReactNode }) {
+  const { client, status, user } = useDocyrusAuth();
+  const userTimezone = (user as { timeZone?: { id?: string } } | null)?.timeZone?.id;
+
+  const query = useQuery<TenantPreferences>({
+    queryKey: ['tenant', 'preferences'],
+    queryFn: () => getTenantPreferences(client!),
+    enabled: status === 'authenticated' && Boolean(client),
+    staleTime: 30 * 60_000
+  });
+
+  const value = useMemo<TenantContextValue>(() => {
+    const preferences = query.data ?? null;
+
+    if (!preferences) {
+      return {
+        preferences: null, dateUtils: null, numberUtils: null, isLoading: query.isLoading
+      };
+    }
+
+    return {
+      preferences,
+      dateUtils: createDateUtils({ preferences, userTimezone }),
+      numberUtils: createNumberUtils({ preferences }),
+      isLoading: query.isLoading
+    };
+  }, [query.data, query.isLoading, userTimezone]);
+
+  return <TenantContext.Provider value={value}>{children}</TenantContext.Provider>;
+}
+
+export function useTenant() {
+  return useContext(TenantContext);
+}
+```
+
+### Wrapping for the data-grid hook
+
+The grid hook expects three callable formatters. Wrap the utils once and expose them via a small hook:
+
+```tsx
+export function useGridFormatters() {
+  const { dateUtils, numberUtils } = useTenant();
+
+  return useMemo(() => {
+    const formatDate = (value: unknown): string => {
+      if (value == null) return '';
+      if (!dateUtils) return String(value);
+      try { return dateUtils.formatDate(value as string | Date) ?? ''; } catch { return String(value); }
+    };
+
+    const formatDateTime = (value: unknown): string => {
+      if (value == null) return '';
+      if (!dateUtils) return String(value);
+      try { return dateUtils.formatDateTime(value as string | Date) ?? ''; } catch { return String(value); }
+    };
+
+    const formatNumber = (
+      value: unknown,
+      opts?: { variant?: 'number' | 'currency' | 'percent'; currency?: string }
+    ): string => {
+      if (value == null || value === '') return '';
+
+      const numeric = typeof value === 'number' ? value : Number(value);
+
+      if (Number.isNaN(numeric)) return String(value);
+      if (!numberUtils) return String(value);
+
+      const variant = opts?.variant ?? 'number';
+      const base = numberUtils.formatNumber(variant === 'percent' ? numeric * 100 : numeric) ?? String(numeric);
+
+      if (variant === 'currency' && opts?.currency) return `${base} ${opts.currency}`;
+      if (variant === 'percent') return `${base}%`;
+
+      return base;
+    };
+
+    return { formatDate, formatDateTime, formatNumber };
+  }, [dateUtils, numberUtils]);
+}
+```
+
+Note the `formatNumber` wrapper handles the variant semantics:
+
+- `'percent'` multiplies by 100 and appends `%`.
+- `'currency'` appends the currency code provided in the cell meta.
+- Plain `'number'` goes straight through `numberUtils.formatNumber`.
+
+If the consuming app uses different conventions (e.g. always show a currency symbol), customize the wrapper accordingly.
+
+## Shared users provider
+
+`useDocyrusDataGrid` accepts `users: ReadonlyArray<CellUserOption>` (`{ value, label, avatarUrl?, initials? }`). Populate it from `/v1/users`:
+
+```tsx
+'use client';
+
+import {
+  createContext, useContext, useMemo, type ReactNode
+} from 'react';
+
+import { useDocyrusAuth } from '@docyrus/signin';
+import { useQuery } from '@tanstack/react-query';
+
+import { type CellUserOption } from '@docyrus/ui/components/data-grid';
+
+interface UserRecord {
+  id: string;
+  firstname?: string | null;
+  lastname?: string | null;
+  email?: string | null;
+  photo?: string | null;
+  [key: string]: unknown;
+}
+
+const UsersContext = createContext<{ users: ReadonlyArray<CellUserOption>; records: ReadonlyArray<UserRecord>; isLoading: boolean }>({
+  users: [], records: [], isLoading: false
+});
+
+function pickString(record: Record<string, unknown>, ...keys: Array<string>): string | null {
+  for (const key of keys) {
+    const value = record[key];
+
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+
+  return null;
+}
+
+function toUserOption(record: UserRecord): CellUserOption | null {
+  if (!record.id) return null;
+
+  const firstName = pickString(record, 'firstname', 'firstName', 'first_name');
+  const lastName = pickString(record, 'lastname', 'lastName', 'last_name');
+  const fullName = firstName ? lastName ? `${firstName} ${lastName}` : firstName : lastName;
+  const email = pickString(record, 'email');
+  const label = fullName ?? email ?? record.id;
+  const avatarUrl = pickString(record, 'photo', 'avatar_url', 'avatarUrl', 'profile_image_url', 'profileImageUrl') ?? undefined;
+
+  return { value: record.id, label, ...(avatarUrl ? { avatarUrl } : {}) };
+}
+
+export function UsersProvider({ children }: { children: ReactNode }) {
+  const { client, status } = useDocyrusAuth();
+
+  const query = useQuery<Array<UserRecord>>({
+    queryKey: ['users', 'all'],
+    queryFn: async () => {
+      const response = await client!.get<Array<UserRecord> | { data?: Array<UserRecord> }>(
+        '/v1/users',
+        { limit: 1000 }
+      );
+
+      return Array.isArray(response) ? response : (response.data ?? []);
+    },
+    enabled: status === 'authenticated' && Boolean(client),
+    staleTime: 5 * 60_000
+  });
+
+  const value = useMemo(() => {
+    const records = query.data ?? [];
+    const users = records
+      .map(toUserOption)
+      .filter((option): option is CellUserOption => option !== null);
+
+    return { users, records, isLoading: query.isLoading };
+  }, [query.data, query.isLoading]);
+
+  return <UsersContext.Provider value={value}>{children}</UsersContext.Provider>;
+}
+
+export function useUsers() {
+  return useContext(UsersContext);
+}
+```
+
+### User record field name fallbacks
+
+The Docyrus `/v1/users` API returns `firstname` / `lastname` (lowercase, no separator) plus `email` and `photo`. The provider also accepts the common camelCase / snake_case aliases as fallbacks so the same code works against tenants that have customized the user schema.
+
+## Wiring providers into the app shell
+
+Place the providers inside the auth + query providers and outside the routes:
+
+```tsx
+<AuthProvider>
+  <QueryProvider>
+    <DevtoolsProvider>
+      <TenantProvider>
+        <UsersProvider>
+          <Routes>{/* ... */}</Routes>
+        </UsersProvider>
+      </TenantProvider>
+    </DevtoolsProvider>
+  </QueryProvider>
+</AuthProvider>
+```
+
+Order matters:
+
+- `AuthProvider` must wrap both because the providers need an authenticated `client` to fetch.
+- `QueryProvider` must wrap both because they use `useQuery`.
+- `TenantProvider` and `UsersProvider` are siblings; either order is fine.
+
+## Wiring providers into a grid page
+
+```tsx
+const { users } = useUsers();
+const { formatDate, formatDateTime, formatNumber } = useGridFormatters();
+
+const { table, gridProps, toolbar } = useDocyrusDataGrid<Row>({
+  client,
+  appSlug,
+  dataSourceSlug,
+  users,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  // ... other options
+});
+```
+
+The grid hook routes:
+
+- `formatDate` / `formatDateTime` / `formatNumber` into TanStack `tableMeta`. `DateCell`, `DateTimeCell`, `NumberCell` (and its currency / percent variants) read these via `tableMeta?.formatDate` etc. and prefer them over their built-in fallbacks.
+- `users` into the cell-options builder for `field-userSelect` and `field-userMultiSelect` columns. The cells render avatar + label from this list immediately. Rows pointing at users not in the list still render correctly via the expanded-payload fallback.
+
+## Why centralize these
+
+- Single network round-trip per session for tenant prefs and the user roster.
+- Consistent formatting and avatar display across every grid, form, and dialog in the app.
+- Pages don't need to know about formatters or user fetching — they just consume context.
+- Tenant settings change rarely (long staleTime); user roster also changes slowly (5 min staleTime is a safe default).
+
+## Debug checklist
+
+- **Dates / numbers showing as raw values?** Tenant query likely failed or hasn't resolved yet. Check `useTenant().isLoading` and the network tab for `getTenantPreferences`.
+- **User cells show "Unassigned" instead of names?** Either `users` wasn't passed in, or the row's user payload didn't expand. Verify `useDocyrusDataGrid` sees both the global `users` list (via context) and that the user column slug appears in `expand` (auto-added; check `resolvedListParams.expand`).
+- **Currency shows "1.234,50 USD" but you wanted "$1,234.50"?** Customize the `formatNumber` wrapper for that variant. The default is locale-formatted number + currency code suffix.
+- **Avatars missing?** The provider reads `photo` first, then `avatar_url` / `avatarUrl` / `profile_image_url` / `profileImageUrl`. Confirm the API returns one of those fields.

package/resources/pi-agent/skills/docyrus-record-detail-form-design/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: docyrus-record-detail-form-design
+description: Build Docyrus React record forms, detail sheets, inspector panels, and inline-edit record UIs with `useDocyrusFormView`, `DynamicFormField`, `DynamicValue`, `EditableRecordDetail`, `EditableValue`, and value renderers. Use when asked to create or refactor create/edit/view pages, modal or sheet record forms, click-to-edit detail panels, metadata-driven field layouts, manual read-only record summaries, or field-type mapping logic that must choose correctly between form inputs, inline editors, and value-renderer fallbacks.
+---
+
+# Docyrus Record Detail Form Design
+
+Build full Docyrus record create, edit, and detail experiences around shared field metadata.
+
+## Choose the build mode
+
+1. **Standard create/edit/view record screen** → use `useDocyrusFormView`.
+   - Best when the page is a normal Docyrus form or detail surface.
+   - Handles metadata loading, item loading, option hydration, field rendering, and submit behavior.
+   - Read `references/hook-form-view.md`.
+
+2. **Custom manual form or detail layout** → use `DynamicFormField`, `DynamicValue`, or `useDocyrusFieldComponent`.
+   - Best when the page already owns form state, layout, or data fetching.
+   - Read `references/manual-form-detail-patterns.md`.
+
+3. **Inline editing, click-to-edit detail rows, or field-by-field editing** → use `EditableRecordDetail` and `EditableValue`.
+   - Best when users should edit a record in place without switching to a full form.
+   - Read `references/advanced-inline-edit-and-renderers.md`.
+
+4. **Complex query/schema/API work** → also load `docyrus-api-dev` or `docyrus-app-dev-react`.
+5. **Field-type mapping or unsupported-field decisions** → read `references/field-type-mapping-and-fallbacks.md`.
+
+## Default workflow
+
+1. Confirm `appSlug`, `dataSourceSlug`, `mode`, and `itemId` if the record already exists.
+2. Decide whether the page should be hook-first or fully manual.
+3. Keep editable fields and read-only renderers on the same field-type registry.
+4. Hydrate enum, user, and relation options before declaring the page done.
+5. Verify create, edit, view, reset, and save behavior.
+6. If the page supports inline editing, verify companion-field saves for composite types such as money, phone, and status.
+
+## Non-negotiables
+
+- Prefer `useDocyrusFormView` for standard create/edit/view pages.
+- Manual editable layouts should use `DynamicFormField`, specific form-field components, or `useDocyrusFieldComponent(..., 'form-field')`.
+- Manual read-only layouts should use `DynamicValue`, specific value renderers, or `useDocyrusFieldComponent(..., 'value-renderer')`.
+- Do not invent parallel per-field switch statements when the shared registry already solves the dispatch.
+- `useDocyrusFormView` already keeps form fields, value renderers, and inline detail mode aligned through `useDocyrusFieldComponent`.
+- `clickToEdit` on `useDocyrusFormView` view layouts routes through `EditableRecordDetail`; use it when you want view-first UX with inline saves.
+- Manual Docyrus item fetching must always send `columns`. `useDocyrusFormView` derives them automatically, including companion columns.
+- Composite fields can require companion keys on read and write: money, phone, status, avatar, and similar types must stay intact in manual save flows.
+- If a field has no editable component, create-mode UX should usually skip it; edit/view UX should usually fall back to a value renderer unless you have a better explicit design.
+
+## References
+
+- `references/hook-form-view.md` — hook-first create, edit, view, layout, submit, and click-to-edit patterns.
+- `references/manual-form-detail-patterns.md` — manual form and detail composition with field components, renderers, and shared field maps.
+- `references/advanced-inline-edit-and-renderers.md` — `EditableRecordDetail`, `EditableValue`, renderer selection rules, and companion-field save patterns.
+- `references/field-type-mapping-and-fallbacks.md` — shared field maps, fallback rules, and unsupported-field strategy by render mode.