@docyrus/docyrus 0.0.67 → 0.0.68

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`.

package/resources/pi-agent/skills/docyrus-record-detail-form-design/references/field-type-mapping-and-fallbacks.md

@@ -0,0 +1,150 @@
+# Field-Type Mapping and Unsupported-Field Strategy
+
+## Read this when
+
+- You need to decide which component stack should render a Docyrus field.
+- A field type has no editable component yet.
+- You are building manual metadata-driven UIs and want safe fallback behavior.
+- You need to extend Docyrus UI for a new field type without breaking forms, details, and inline editing.
+
+## Single source of truth
+
+Docyrus field rendering should flow through the shared field maps exposed by `useDocyrusFieldComponent`:
+
+- `FORM_FIELD_MAP`
+- `VALUE_RENDERER_MAP`
+- `CELL_COMPONENT_MAP`
+
+Use these indirectly through:
+
+- `DynamicFormField`
+- `DynamicValue`
+- `useDocyrusFormView`
+- `useDocyrusFieldComponent`
+
+Do **not** create a parallel local switch statement unless there is a very strong reason.
+
+## Render-context lookup matrix
+
+`useDocyrusFieldComponent(field.type, kind)` supports five render kinds:
+
+| kind | Typical use | Unknown / unsupported fallback |
+|------|-------------|--------------------------------|
+| `form-field` | editable forms | `null` |
+| `value-renderer` | read-only detail | `TextValue` |
+| `data-grid-cell-variant` | grid cells | `ShortTextCell` |
+| `editable-value` | single-field inline edit | `EditableValue` |
+| `tanstack-column-def` | dynamic table columns | builder with short-text cell fallback |
+
+This fallback behavior is the baseline for every manual page and hook-first page.
+
+## What each dispatcher does
+
+### `DynamicFormField`
+
+- resolves `form-field`
+- returns `null` when the field type has no registered editable component
+- best for metadata-driven editable forms
+
+### `DynamicValue`
+
+- resolves `value-renderer`
+- always returns a renderable component because the fallback is `TextValue`
+- best for metadata-driven read-only layouts
+
+### `EditableValue`
+
+- is the inline-edit dispatcher
+- returned for the `editable-value` kind regardless of field type
+- internally decides whether the field behaves like inline edit, instant save, explicit save, popover edit, or read-only display
+
+### `useDocyrusFormView`
+
+- uses `form-field` in editable mode
+- uses `value-renderer` in read-only mode
+- handles unsupported editable fields differently by mode:
+  - create mode default: `unsupportedFieldBehavior = 'skip'`
+  - edit/view mode default: `unsupportedFieldBehavior = 'value'`
+
+That default is usually correct because create screens should not tease unusable inputs, while edit/view screens can still show existing values safely.
+
+## Recommended unsupported-field strategy
+
+### Create mode
+
+Prefer skipping unsupported editable fields unless the page explicitly designs a read-only preview row.
+
+Why:
+
+- users expect every visible field in a create form to be fillable
+- showing a read-only renderer inside create mode can be confusing
+- the hook default already follows this rule
+
+### Edit mode
+
+Prefer value-render fallback when the field cannot be edited.
+
+Why:
+
+- users can still review the field
+- the record detail stays complete
+- you avoid broken partial editors
+
+### View mode
+
+Always prefer value renderers.
+
+That is the natural mode for detail pages, approval reviews, summaries, and read-only sheets.
+
+## Safe manual pattern
+
+When building a manual dynamic page, use this decision order:
+
+```tsx
+const FormField = useDocyrusFieldComponent(field.type, 'form-field');
+const Value = useDocyrusFieldComponent(field.type, 'value-renderer');
+
+if (mode === 'view') {
+  return <Value field={field} value={value} record={record} enumOptions={options} />;
+}
+
+if (FormField) {
+  return <FormField field={field} form={form} enumOptions={options} />;
+}
+
+return mode === 'create'
+  ? null
+  : <Value field={field} value={value} record={record} enumOptions={options} />;
+```
+
+This keeps manual pages aligned with hook-first Docyrus behavior.
+
+## When a field type needs more than mapping
+
+Some field types require more than just selecting a component:
+
+- enum/select-like fields need `enumOptions`
+- user and relation editors need hydrated option lists
+- status fields may need companion values like description and follow-up date
+- money and phone fields need companion currency/country keys
+- avatar-like fields can require companion image or color keys
+
+A field can be “supported” in the map but still render weakly if its supporting data is missing.
+
+## Adding support for a new field type
+
+When extending Docyrus UI, check all relevant layers:
+
+1. add the editable component to `FORM_FIELD_MAP` if the type is editable
+2. add the read-only renderer to `VALUE_RENDERER_MAP`
+3. add the grid cell component or fallback strategy if the type should appear richly in grids
+4. update any companion read/write logic if the field stores secondary keys
+5. verify `useDocyrusFormView`, `DynamicFormField`, `DynamicValue`, and `EditableValue` behavior
+
+## Debug checklist
+
+- **Field disappears in manual edit mode?** `form-field` likely resolved to `null`.
+- **Field shows raw text instead of richer UI?** You are hitting the `value-renderer` fallback or missing supporting props.
+- **Create form unexpectedly shows read-only rows?** Your unsupported strategy is too permissive for create mode.
+- **Inline field never edits?** The field may be effectively read-only in `EditableValue` or missing required option data.
+- **New field type works in forms but not in details or grids?** You updated one map but not the others.

package/resources/pi-agent/skills/docyrus-record-detail-form-design/references/hook-form-view.md

@@ -0,0 +1,127 @@
+# Hook-first Record Forms and Detail Views
+
+## Use this path when
+
+- The page is a standard Docyrus create, edit, or read-only record screen.
+- You want field metadata, item loading, option hydration, and submit behavior handled in one place.
+- You want the same field list to render as editable inputs in one mode and value renderers in another.
+
+## Minimal create form
+
+```tsx
+'use client';
+
+import { useDocyrusAuth } from '@docyrus/signin';
+import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';
+import { Button } from '@docyrus/ui/primitives/ui/button';
+
+export function CreateContactForm() {
+  const { client } = useDocyrusAuth();
+
+  if (!client) return null;
+
+  const formView = useDocyrusFormView({
+    client,
+    appSlug: 'crm',
+    dataSourceSlug: 'contacts',
+    mode: 'create',
+    gridColumns: 2,
+    defaultValues: { status: 'lead' },
+    fieldOrder: ['full_name', 'email', 'phone', 'status', 'notes'],
+    fieldLayout: {
+      notes: { colSpan: 'full' }
+    }
+  });
+
+  return (
+    <form
+      className="space-y-4"
+      onSubmit={async (event) => {
+        event.preventDefault();
+        await formView.submit();
+      }}>
+      {formView.renderLayout()}
+      <div className="flex items-center gap-2">
+        <Button type="submit" disabled={formView.isSubmitting || formView.isLoading}>Create</Button>
+        <Button type="button" variant="outline" onClick={formView.reset}>Reset</Button>
+      </div>
+    </form>
+  );
+}
+```
+
+## Minimal edit and view patterns
+
+- **edit**: pass `mode: 'edit'` and `itemId`.
+- **view**: pass `mode: 'view'` and `itemId`.
+- **prefetched record**: pass `item` to skip the item query.
+- **generated collection**: pass `collection` so the hook uses `collection.get`, `collection.create`, and `collection.update`.
+
+## Click-to-edit detail mode
+
+In `view` mode, `clickToEdit: true` swaps the plain value layout for `EditableRecordDetail` while still using the normal Docyrus submit pipeline.
+
+```tsx
+const detailView = useDocyrusFormView({
+  client,
+  appSlug: 'crm',
+  dataSourceSlug: 'contacts',
+  itemId: contactId,
+  mode: 'view',
+  clickToEdit: true,
+  fieldOrder: ['full_name', 'email', 'phone', 'status', 'notes']
+});
+
+return detailView.renderLayout();
+```
+
+Use this when the page should feel like a detail sheet first, but still allow inline field edits.
+
+## High-value options
+
+- `fieldOrder`: impose explicit field ordering.
+- `fieldSlugs`: whitelist fields.
+- `hiddenFieldSlugs`: hard-hide fields.
+- `fieldLayout`: override hidden, required, readOnly, disabled, colSpan, label, description, and per-field props.
+- `layout`: build nested `fieldset`, `tabpanel`, and `tab` sections.
+- `mapField`: transform normalized field metadata or drop a field entirely.
+- `includeReadOnlyFields`: keep read-only rows in the rendered layout.
+- `unsupportedFieldBehavior`: choose whether unsupported editable fields are skipped or rendered as values.
+- `resolveUserOptions`, `resolveRelationOptions`, `enumOptions`: control option hydration.
+- `transformSubmit`: final payload transform before create/update.
+- `onSubmit`: replace default submit behavior entirely.
+- `onSubmitSuccess`, `onSubmitError`: react to mutation outcomes.
+
+## How render mode is decided
+
+The hook resolves components from the shared field-component registry:
+
+- editable mode → `form-field`
+- read-only mode → `value-renderer`
+
+It does not keep a separate form/detail mapping system. That means `useDocyrusFormView`, `DynamicFormField`, `DynamicValue`, and data-grid field behavior stay aligned when the registry changes.
+
+## Why this hook is usually the default
+
+It handles three difficult layers together:
+
+1. data-source metadata
+2. current item loading
+3. dynamic option hydration for enum, user, and relation fields
+
+It also derives the required backend `columns`, including companion columns for composite fields.
+
+## Important behavior
+
+- `renderField(slug)` renders a single resolved field.
+- `renderLayout()` renders the full layout grid and is usually the fastest path.
+- `reset()` restores the latest committed baseline.
+- successful `submit()` updates the clean baseline, so the page stops being dirty.
+- in `view` mode, `submit()` returns current values and skips normal validation.
+
+## Default recommendation
+
+Start with `useDocyrusFormView` unless the page already has its own form state, its own item query lifecycle, or a heavily custom layout system that would fight the hook.
+
+For deeper inline editing and renderer behavior, also read `advanced-inline-edit-and-renderers.md`.
+For shared field-map behavior and unsupported-field defaults, also read `field-type-mapping-and-fallbacks.md`.

package/resources/pi-agent/skills/docyrus-record-detail-form-design/references/manual-form-detail-patterns.md

@@ -0,0 +1,125 @@
+# Manual Form and Detail Patterns
+
+## Use this path when
+
+- The page already owns its form state.
+- You want a completely custom layout.
+- The record is already loaded elsewhere.
+- You need precise control over when editable inputs versus read-only renderers appear.
+
+## Manual editable form with `DynamicFormField`
+
+```tsx
+'use client';
+
+import { useForm } from '@tanstack/react-form';
+import { DynamicFormField, type IField, type EnumOption } from '@docyrus/ui/components/form-fields';
+
+const fields: IField[] = [
+  { id: '1', name: 'Full Name', slug: 'full_name', type: 'field-text' },
+  { id: '2', name: 'Status', slug: 'status', type: 'field-select' }
+];
+
+const statusOptions: EnumOption[] = [
+  { id: 'lead', slug: 'lead', name: 'Lead', color: '#64748b' },
+  { id: 'customer', slug: 'customer', name: 'Customer', color: '#22c55e' }
+];
+
+export function ContactForm() {
+  const form = useForm({
+    defaultValues: {
+      full_name: '',
+      status: 'lead'
+    },
+    onSubmit: async ({ value }) => {
+      void value;
+    }
+  });
+
+  return (
+    <form onSubmit={(event) => { event.preventDefault(); void form.handleSubmit(); }}>
+      {fields.map((field) => (
+        <DynamicFormField
+          key={field.id}
+          field={field}
+          form={form}
+          enumOptions={field.slug === 'status' ? statusOptions : undefined} />
+      ))}
+    </form>
+  );
+}
+```
+
+Use the specific form-field components directly when you want more explicit imports or field-specific props. Use `DynamicFormField` when the field list is metadata-driven.
+
+## Manual read-only detail with `DynamicValue`
+
+```tsx
+import { DynamicValue } from '@docyrus/ui/components/value-renderers';
+
+function ContactDetail({ fields, record, statusOptions }: {
+  fields: IField[];
+  record: Record<string, unknown>;
+  statusOptions: EnumOption[];
+}) {
+  return (
+    <div className="grid gap-4 md:grid-cols-2">
+      {fields.map((field) => (
+        <div key={field.id} className="space-y-1">
+          <div className="text-sm font-medium">{field.name}</div>
+          <DynamicValue
+            field={field}
+            value={record[field.slug]}
+            record={record}
+            enumOptions={field.slug === 'status' ? statusOptions : undefined} />
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Use this when the page is read-only or when some fields are intentionally not editable.
+
+## Shared registry pattern with `useDocyrusFieldComponent`
+
+When you need total control, use the registry hook directly instead of writing a per-type switch.
+
+```tsx
+const FormField = useDocyrusFieldComponent(field.type, 'form-field');
+const Value = useDocyrusFieldComponent(field.type, 'value-renderer');
+
+if (isEditing && FormField) {
+  return <FormField field={field} form={form} enumOptions={options} />;
+}
+
+return <Value field={field} value={value} record={record} enumOptions={options} />;
+```
+
+This is the safest manual pattern because it stays aligned with the Docyrus UI field maps.
+
+## When to choose which primitive
+
+- `DynamicFormField`: metadata-driven editable inputs.
+- specific form-field component: explicit field type, custom props, or smaller import surface.
+- `DynamicValue`: metadata-driven read-only display.
+- specific value renderer: explicit display control for a known field type.
+- `useDocyrusFieldComponent`: custom render orchestration that still stays on the shared registry.
+
+## Manual option requirements
+
+Manual pages must supply the option data that the renderer or field needs:
+
+- select-like fields need `enumOptions`
+- relation renderers usually need `record` context
+- user and relation field editors often need hydrated options upstream
+- composite renderers such as status, money, phone, and avatar depend on companion values in the record object
+
+If those values are absent, the component may render a weaker fallback.
+
+## Common manual pattern
+
+Use editable inputs in edit mode and read-only renderers in view mode, but keep the same field list and the same metadata source. That keeps create, edit, and detail pages consistent even when the layout differs.
+
+For inline editing and change tracking, also read `advanced-inline-edit-and-renderers.md`.
+For field-type dispatch rules and unsupported-field fallback strategy, also read `field-type-mapping-and-fallbacks.md`.