@docyrus/docyrus 0.0.66 → 0.0.68

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.

package/resources/pi-agent/skills/docyrus-record-detail-form-design/references/advanced-inline-edit-and-renderers.md

@@ -0,0 +1,140 @@
+# Advanced Inline Editing and Renderer Patterns
+
+## Read this when
+
+- The page should edit fields inline instead of switching to a dedicated form.
+- You need change tracking or save/discard actions.
+- You need to decide between `EditableRecordDetail`, `EditableValue`, `DynamicValue`, and raw form fields.
+- A field type has companion values that must survive save flows.
+
+## `EditableRecordDetail` for record-level inline editing
+
+Use `EditableRecordDetail` when the whole record should be displayed as a detail surface, but each row can become editable.
+
+```tsx
+import {
+  EditableRecordDetail,
+  EditableRecordDetailField
+} from '@docyrus/ui/components/editable-record-detail';
+
+<EditableRecordDetail
+  fields={fields}
+  record={record}
+  onSave={async (changes, values) => {
+    void changes;
+    void values;
+  }}
+  trackChanges>
+  <EditableRecordDetailField slug="full_name" />
+  <EditableRecordDetailField slug="email" />
+  <EditableRecordDetailField slug="status" />
+</EditableRecordDetail>
+```
+
+Use it when:
+
+- the page is a detail panel or sheet
+- users should edit a few fields in place
+- you want a floating save/discard bar with changed-field summaries
+
+## `EditableValue` for single-field inline editing
+
+Use `EditableValue` when only one field should toggle between display and edit modes.
+
+```tsx
+<EditableValue
+  field={field}
+  value={record[field.slug]}
+  record={record}
+  enumOptions={enumOptions}
+  onValueChange={(next) => saveOneField(field.slug, next)}
+  onCompanionChange={(companion) => saveCompanionFields(companion)}
+  changed={isChanged}
+  trackChanges
+/>
+```
+
+This is the right primitive for compact inline edits inside cards, summaries, or custom detail rows.
+
+## Field behavior categories inside `EditableValue`
+
+`EditableValue` is not a simple text editor. It dispatches behavior by field type:
+
+- inline types save on blur or Enter
+- instant-save types commit immediately on change
+- explicit-save types show confirm/cancel actions
+- popover types keep edit mode stable while focus moves into portaled content
+- read-only types stay display-only
+
+That is why `useDocyrusFieldComponent(..., 'editable-value')` always returns `EditableValue` instead of a field-type-specific component.
+
+## Companion fields matter
+
+Manual inline save flows must preserve companion keys for composite field types.
+
+Common examples:
+
+- money → value + `__slug_currency`
+- phone → value + `__slug_country`
+- status → value + `__slug_secondary`, `__slug_description`, `__slug_followup_date`
+- avatar → main value plus mapped companion fields
+
+If you save only the visible main field, you can silently corrupt or flatten the record state.
+
+## Renderer selection rules
+
+Use these defaults:
+
+- full editable form → form-field component
+- full read-only detail → value renderer
+- one-off inline field → `EditableValue`
+- view-first detail screen with record-level inline save → `EditableRecordDetail`
+
+If a field has no editable form component, prefer a value-render fallback instead of inventing a broken partial editor.
+
+## Value-renderer guidance
+
+Value renderers are not just pretty labels. They understand field semantics:
+
+- `StatusValue` reads status companion data like description and follow-up date
+- `MoneyValue` formats amounts with currency context
+- `UserValue` and `UserMultiValue` present users properly
+- `RelationValue` renders relationship display values
+- `RichTextValue` and `DocEditorValue` display stored rich content safely
+
+Prefer the value renderer over custom text formatting whenever you are showing a Docyrus field type in read-only mode.
+
+For the pure field-type dispatch matrix and unsupported-field defaults, also read `field-type-mapping-and-fallbacks.md`.
+
+## Shared maps are the source of truth
+
+The safest advanced pattern is to stay on the shared registries exposed by `useDocyrusFieldComponent`:
+
+- `FORM_FIELD_MAP`
+- `VALUE_RENDERER_MAP`
+- `CELL_COMPONENT_MAP`
+
+That keeps forms, detail views, data-grid cells, and inline editing behavior aligned.
+
+## Good combinations
+
+### Detail page with manual sections + inline fields
+
+- layout shell: your own markup
+- read-only rows: `DynamicValue`
+- editable rows: `EditableValue`
+- bulk record save experience: `EditableRecordDetail`
+
+### Hook-first detail page with selective inline editing
+
+- outer data workflow: `useDocyrusFormView`
+- default layout: `renderLayout()` in `view` mode
+- inline edit UX: `clickToEdit: true`
+
+## Debug checklist
+
+- **Field never becomes editable?** It may be a read-only field type or lack a registered form-field component.
+- **Inline save loses currency/country/status metadata?** You forgot companion-field handling.
+- **Renderer shows weak output?** Check whether `record` or `enumOptions` is incomplete.
+- **Detail page edits but does not show change state?** Enable `trackChanges` and wire changed-state inputs correctly.
+- **Custom manual switch statement is drifting from Docyrus UI behavior?** Replace it with `useDocyrusFieldComponent`, `DynamicFormField`, or `DynamicValue`.