drf-react-by-schema 0.28.25 → 0.28.27

package/docs/API_REFERENCE.md

@@ -0,0 +1,665 @@
+# API reference — `drf-react-by-schema` (React)
+
+Canonical reference for everything the package exposes to **consuming apps**: the
+provider, `useAPIWrapper()`, the components, their props and the utility functions.
+
+The public surface is exactly what `src/index.ts` exports. If a symbol is not
+re-exported there, it is internal — do not import it from a deep path
+(`drf-react-by-schema/dist/...`), because its signature may change without notice.
+
+Related docs:
+
+- [`FIELD_TYPES.md`](FIELD_TYPES.md) — schema `type` → widget table.
+- [`localization.md`](localization.md) — `theme.texts`, MUI locale setup.
+- [`password-reset-and-email.md`](password-reset-and-email.md) — forgot/change password flow.
+
+---
+
+## 0. Golden rules for consuming apps
+
+1. **Wrap the app with `DRFReactBySchemaProvider`.** It installs the MUI theme,
+   `CssBaseline`, the context and the built-in overlays (dialog, snackbar, loading
+   backdrop).
+2. **Use `useAPIWrapper()` for every data/auth action.** It is the only public data
+   hook.
+3. **Never call `useDRFReactBySchema()`.** It exists as an internal building block of
+   this package, is **not exported** from the package entry, and only returns raw
+   context (`serverEndPoint`, `theme`, `isInBatches`, `firstBatchLength`, `schemas`,
+   `pagination`). It has no data, auth or form helpers and is not a supported app API.
+4. **Fetch helpers return `Item | AxiosError`.** Always check
+   `axios.isAxiosError(result)` before using the value.
+5. **Schemas come from the Django pair** (`drf-react-by-schema-django`) through
+   `OPTIONS` or the `sync_react` snapshots passed to the provider. Never hand-write
+   field metadata for a model that the backend already describes.
+
+---
+
+## 1. `DRFReactBySchemaProvider`
+
+`src/context/DRFReactBySchemaProvider.tsx`
+
+Wraps the app. Props (`DRFReactBySchemaProviderProps`):
+
+| Prop | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `serverEndPoint` | `ServerEndPoint \| null` | `null` | Django URLs. See below. |
+| `theme` | `Theme` | package default | Deep-merged over the default theme. Localize through `theme.texts`. |
+| `isInBatches` | `boolean` | `true` | Lists fetch in two batches (schema+first page, then the rest) to render faster. |
+| `firstBatchLength` | `number` | `100` | Batch size used when `isInBatches` is on. |
+| `schemas` | `SchemasType` | `undefined` | `sync_react` output. Avoids `OPTIONS` round-trips. Values may be inline `SchemaOptionsType` objects or `() => import(...)` loaders. |
+| `pagination` | `PaginationConfig` | `{ perPage: 50, pageSizeOptions: [5,10,25,50,100,200], maxPageSize: 500 }` | Defaults for server-side lists. |
+| `children` | `ReactNode` | — | App tree. |
+
+`ServerEndPoint`:
+
+| Key | Default derived by the provider |
+| --- | --- |
+| `url` | required |
+| `apiTokenUrl` | required (JWT token endpoint) |
+| `api` | `${url}/api` |
+| `autocomplete` | `${url}/autocomplete` |
+| `getToken` | `apiTokenUrl` |
+| `refreshToken` | `${apiTokenUrl}refresh/` |
+| `verifyToken` | `${apiTokenUrl}verify/` |
+| `media` | `${url}/media` |
+| `signUp` | **no default** — set it explicitly to enable sign-up |
+| `requestPasswordReset` | `${api}/password_reset/request/` |
+| `validatePasswordReset` | `${api}/password_reset/validate/` |
+| `confirmPasswordReset` | `${api}/password_reset/confirm/` |
+| `changePassword` | `${api}/my_account/change_password/` |
+
+The provider also renders the package overlays, so `setDialog`,
+`onTriggerSnackBar` and the loading backdrop work anywhere below it.
+
+---
+
+## 2. `useAPIWrapper()`
+
+`src/context/APIWrapperContext.tsx`
+
+The single hook for data, auth, form state and feedback. It returns
+`APIWrapperContextType<T>` (generic `T` is your generated model type; omit it for
+`Record<string, any>`).
+
+```ts
+const {
+  usuaria, isLoggedIn, signOut,
+  getGenericModelList, getGenericModel, onDeleteModel,
+  onTriggerSnackBar, setDialog, isMobile,
+} = useAPIWrapper();
+```
+
+### 2.1 Session and current user
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `usuaria` | `Item \| null` | Current user from `GET /api/my_account/`. `null` before load/sign-out. |
+| `updateUsuaria` | `() => void` | Re-fetches `my_account`. On failure stores `{ erro: 'token inválido' }`. |
+| `isLoggedIn` | `() => Promise<false \| Item>` | Validates the stored JWT and returns the user (or `false`). Does not write `usuaria`. |
+| `loginByPayload` | `(payload: Item) => Promise<boolean \| AxiosError>` | `POST` to `getToken`; stores access/refresh tokens. Returns `false` on bad credentials. |
+| `signOut` | `() => void` | Clears tokens, `usuaria`, `optionsAC`, `pageForm` and `editModel`. |
+| `getSignUpOptions` | `() => Promise<SchemaType \| AxiosError>` | Schema of the sign-up form. |
+| `signUp` | `<U>(data: Item<U>) => Promise<Item<U> \| AxiosError>` | `POST` to `serverEndPoint.signUp`. |
+| `isMobile` | `boolean` | `theme.breakpoints.down('md')`. |
+
+Password management (see [`password-reset-and-email.md`](password-reset-and-email.md)):
+
+| Member | Signature |
+| --- | --- |
+| `requestPasswordReset` | `(email: string) => Promise<Item \| AxiosError>` |
+| `validatePasswordReset` | `(data: Item) => Promise<Item \| AxiosError>` |
+| `confirmPasswordReset` | `(data: Item) => Promise<Item \| AxiosError>` |
+| `changePassword` | `(data: Item) => Promise<Item \| AxiosError>` |
+
+### 2.2 Reading data
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `getGenericModel` | `({ model, id?, relatedModel?, relatedModelId? }) => Promise<{ data, schema, columns, modelOptions } \| AxiosError>` | One record + its schema/columns. With no `id` it returns the schema and an empty record; create forms should use `loadSinglePageData`/`<Form>`, which map tmp ids to no id. |
+| `getGenericModelList` | `GetGenericModelListPropsLocal<T> => Promise<DataSchemaColumnsType<T> \| AxiosError>` | List with server filter/sort/paginate/totals. Params: `model`, `id`, `relatedModel`, `relatedModelId`, `columnFields`, `creatableFields`, `disabledFields`, `isInBatches`, `loadedSchema`, `loadedModelOptions`, `page`, `pageSize`, `filter`, `queryParams`, `sort`, `sumRows`. Returns `{ data, schema, columns, modelOptions, rowCount, sumRowsTotals, facets }`. |
+| `getAutoComplete` | `(model: string, queryParams?: string[]) => Promise<AutocompleteItem[] \| AxiosError>` | Options for relation fields. Duplicate labels get a `(n)` suffix. |
+| `getRawData` | `<U = void>(route: string) => Promise<U \| AxiosError>` | Authenticated `GET` against `${api}/${route}`. Handles 401 by refreshing the token. |
+| `getAllModels` | `() => Promise<Item[]>` | Model list used by admin-like screens. Returns `[]` on error. |
+| `getModelMeta` | `(model: string) => Promise<{ verboseName, verboseNamePlural }>` | From the loaded schemas; falls back to the model slug. Does not hit the network when `schemas` is provided. |
+
+Server query grammar produced by `getGenericModelList` (Django side):
+
+- quick filter → `search=<value>`
+- filter item → `field=<field>&operator=<op>&value=<value>`
+- sort → `ordering=field,-other`
+- pagination → `page=<1-based>&page_size=<n>`
+- totals → `sum_rows=<field>[|<facet>...][|<limit>],...`
+- batching → `is_first_batch=1` / `is_last_batch=1`
+
+### 2.3 Writing data
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `onSubmit` | `(model, id, data, event?) => Promise<Id \| AxiosError>` | Validates/normalizes `data` with the current `pageForm.schema`, then `POST` when `id` is tmp/empty or `PUT` otherwise. Shows snackbars and refreshes `optionsAC`. Requires a loaded `pageForm` (normally provided by `<Form>`/`loadSinglePageData`). Returns the new id. |
+| `postData` | `({ path, data, contentType? }) => Promise<Item \| AxiosError>` | Raw `POST` (no schema normalization). |
+| `updateModel` | `({ path, id, data, contentType? }) => Promise<Item \| AxiosError>` | Raw `PUT`. |
+| `rawUpdateDataBySchema` | `(props: UpdateDataBySchema) => Promise<Item \| AxiosError>` | `POST` (tmp/missing id) or `PUT` after `prepareDataBySchema` normalization. `props`: `{ model, modelObjectId, data, schema, path? }`. |
+| `rawDeleteData` | `(model: string, id: Id) => Promise<true \| AxiosError>` | Raw `DELETE`, no dialog/snackbar. |
+| `onEditModelDataGridSave` | `({ model, newRow, schema }) => Promise<Item \| AxiosError>` | Inline grid save; uses the row id and `path = model`. |
+| `onEditRelatedModelSave` | `({ model, id, relatedModel, newRow, schema, onlyAddExisting? }) => Promise<Item \| ItemSchemaColumnsType \| AxiosError>` | Nested create/update (`onlyAddExisting` links an existing record via `id_to_add`). |
+| `onDeleteRelatedModel` | `({ model, id, relatedModel, relatedModelId }) => Promise<true \| AxiosError>` | Nested `DELETE`, no confirmation dialog. |
+| `exportExcelData` | `({ model, modelParent?, modelParentId?, paginationModel }) => Promise<true \| AxiosError>` | Downloads the current list as an Excel file. |
+
+### 2.4 Dialog-driven CRUD
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `onEditModel` | `(p: OnEditModelType) => void` | Opens the built-in dialog and loads the record. `p`: `{ model, id, labelKey, fieldKey?, index?, setValue?, getValues?, fieldsLayout?, initialValuesPartial? }`. It updates the parent form value and `optionsAC` after save when `setValue`/`getValues` are given. |
+| `onEditModelSave` | `(data: Item) => Promise<boolean \| AxiosError>` | Closes the dialog and saves the model currently held in `editModel.current` (set by `onEditModel`). |
+| `onDeleteModel` | `(model, id, onSuccess?) => void` | Opens a confirmation dialog and deletes on confirm. Returns immediately — no promise. For nested rows use `onDeleteRelatedModel`. |
+| `editModel` | `RefObject<Item>` | The record being edited in the dialog. Read-only for app code. |
+
+### 2.5 Page form state
+
+`<Form>` stores its state here; custom screens can reuse the same machinery.
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `loadSinglePageData` | `(p: LoadSinglePageDataProps) => Promise<Item \| AxiosError>` | Loads record + schema, builds initial values and the yup validation schema, and populates `pageForm`. `p`: `{ model, objId?, objTitleField?, optionsACModels?, defaults?, extraValidators?, fieldsLayout? }`. |
+| `pageForm` | `PageFormType \| null` | `{ id, model, modelVerboseName, modelVerboseNamePlural, schema, columns, initialValues, validationSchema, objTitleField }`. |
+| `resetPageForm` | `() => void` | Clears `pageForm`. |
+| `formTools` | `FormTools \| undefined` | React-hook-form handles of the mounted `<Form>`: `{ errors, reset, getValues, setValue, isDirty }`. |
+| `optionsAC` | `OptionsAC \| null` | Cache of autocomplete options, keyed by model. |
+| `setOptionsAC` | `(x: Partial<OptionsAC>) => void` | Merges into the cache. |
+| `populateOptionsAC` | `(models: string[]) => void` | Fetches and caches options for the given models. |
+| `handleLoading` | `(p: boolean) => void` | Shows/hides the global loading backdrop. |
+
+### 2.6 Feedback
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `onTriggerSnackBar` | `({ msg, severity? }) => void` | `severity` is a MUI `AlertColor` (`'info'` default). |
+| `setDialog` | `(state: Partial<DialogType> \| null) => void` | Opens/updates/closes the global dialog. `{ open, loading?, title?, Body?, Actions?, isCancelDisabled?, size? }`. Pass `null` to reset. |
+
+---
+
+## 3. Components
+
+All components below are exported from the package root. Generic components accept an
+optional `T` (`TField`) generated by `sync_react`.
+
+### 3.1 Forms
+
+#### `<Form />` — full create/edit page
+
+`src/components/forms/Form.tsx`
+
+Loads schema + record, builds fields and validation, renders top/bottom action bars, and
+navigates after save.
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `model` | `string` | Model slug (e.g. `"comunidade"`). |
+| `objId` | `Id` | Record id. Omit/`'novo'`/`tmp*` for create. |
+| `defaults` | `PartialItem<T>` | Initial values for a create form. |
+| `objTitleField` | `FieldKey<T>` | Field used as the record title. |
+| `onSave` | `(currentId, newIdOrError, buttonType: FormSaveActions) => void` | After a save attempt. `buttonType` tells which button was used. |
+| `onDelete` | `(removedId: Id) => void` | After a delete. |
+| `onCancel` | `MouseEventHandler` | Runs before navigating away from cancel. |
+| `navigate` | `(to: string) => void; (delta: number) => void` | Router adapter. Without it, `window.location.href` / `history.back()` are used. |
+| `exit` | `(newId?: Id) => void` | Custom exit. Takes precedence over `exitPath`. |
+| `exitPath` | `string` | Path to go after save/cancel; `{ID}` is replaced by the record id. |
+| `editPath` | `string` | Path of the edit page; `{ID}` marks where the id goes. Defaults to the current directory + id. |
+| `saveAndContinue` | `boolean` | Shows the "save and continue" button. |
+| `title` | `string` | Header title. |
+| `labelSave` / `labelSaveAndContinue` / `labelSaveAndCreateNew` / `labelCancel` / `labelRemove` | `string` | Override button labels (defaults come from `theme.texts.forms`). |
+| `fieldsLayout` | `FormFieldLayout<T>[]` | Sections/rows/custom elements. See §4.1. |
+| `customFieldFormLayouts` | `CustomFormFieldLayouts<T>` | Per-relation-field layouts for nested/editable relations. |
+| `hiddenFields` | `FieldList<T>` | Fields not rendered; their values are preserved as hidden inputs on save. |
+| `fieldsProps` | `FieldsProps<T>` | Per-field widget overrides (see §4.3). |
+| `optionsAC` / `setOptionsAC` | `OptionsAC<T>` / setter | External autocomplete cache. Usually unnecessary inside a page. |
+| `isolatedGetAutoComplete` | `(model) => Promise<AutocompleteItem[] \| AxiosError>` | Replace the autocomplete loader for this form only. |
+| `relatedEditable` | `boolean` | `false` disables the inline edit dialogs for relation fields. |
+| `autoFocusField` | `FieldKey<T>` | Focus this field on mount. |
+| `elevation` | `number` | Card elevation. |
+| `extraValidators` | `ExtraValidators<T>` | Replace the yup validator for individual fields. |
+| `watchValues` | `FieldList<T>` | Fields monitored by `FormWatcher`. Requires `onWatchChange`. |
+| `onWatchChange` | `(values: FormWatchObject<T>) => void` | Called with `{ [field]: value }` whenever a watched value changes (deep-equality guarded). |
+| `reloadStateStamp` | `number \| string` | Change it to force a reload of the record/schema. |
+| `CustomFormActions` | `(props: FormActionsProps) => JSX.Element` | Replace the default action bar. |
+| `multiline`, `fieldKey`, `labelKey`, `optionsModel`, `getOptionLabel`, `renderOption`, `onEditModel`, `options`, `isSemaphoric`, `label`, `decimalScale` | — | Shared field props forwarded to the schema renderer (only these are forwarded). |
+| `sxSection`, `sxSectionTitle`, `sxRow`, `sxRowMultiple` | `SxProps<Theme>` | Layout styling. |
+
+Behavior worth knowing:
+
+- It renders an empty fragment until the schema for `model` is in `pageForm`.
+- Navigation precedence on exit: `exit` → `exitPath` → `history.back()`.
+- A dirty form installs a `beforeunload` guard.
+- DRF field errors returned by a serializer `validate()` are mapped onto the form fields.
+- On unmount it resets `pageForm`.
+
+#### `<FormBySchema />` — form body (no page chrome)
+
+`src/components/forms/FormBySchema.tsx`
+
+Renders a schema-driven form body. It does **not** create the react-hook-form context, so
+you pass `schema`, `control`, `errors` and (usually) `getValues`/`setValue`.
+
+Additional props beyond the shared field props (§4.2):
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `schema` | `SchemaType<T>` | Required. |
+| `control` | `Control<Item<T>>` | Required. |
+| `errors` | `FieldErrors<Item<T>>` | Required. |
+| `fieldsLayout` | `FormFieldLayout<T>[]` | Sections/rows/custom elements. |
+| `customFieldFormLayouts` | `CustomFormFieldLayouts<T>` | Per-relation layouts. |
+| `hiddenFields` | `FieldList<T>` | Fields not rendered. |
+| `fieldsProps` | `FieldsProps<T>` | Per-field overrides. |
+| `setOptionsAC` | `(x: OptionsAC<T>) => void` | Cache setter when you own the options. |
+| `isolatedGetAutoComplete` | loader | Replace the autocomplete loader. |
+| `relatedEditable` | `boolean` | Disable inline relation dialogs. |
+| `autoFocusField` | `FieldKey<T>` | Initial focus. |
+| `elevation` | `number` | Card elevation. |
+| `conditionalVisible` / `watchedValues` | internal | Usually supplied by `<Form>`/`DialogFormBySchema`; do not set by hand. |
+| `sxSection`, `sxSectionTitle`, `sxRow`, `sxRowMultiple` | `SxProps<Theme>` | Layout styling. |
+
+#### `<DialogFormBySchema />` — schema-driven dialog form
+
+`src/components/forms/DialogFormBySchema.tsx`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `schema` | `SchemaType<T>` | Required. |
+| `validationSchema` | `AnyObjectSchema` | Required yup schema. |
+| `initialValues` | `Item<T>` | Required. |
+| `onEditModelSave` | `(data: Item<T>) => Promise<boolean \| AxiosError>` | Save callback. |
+| `setDialog` | `(x: Partial<DialogType>) => void` | Close/update the dialog. |
+| `getAutoComplete` | loader | Autocomplete loader. |
+| `optionsAC` / `hiddenFields` / `fieldsLayout` | — | Options cache, hidden fields, layout. |
+| `setOptionsAC` | `(x: Partial<OptionsAC<T>>) => void` | Required by the prop type, but currently unused (pass the cache through `optionsAC`). |
+| `isCancelDisabled` | `boolean` | Disable cancel (e.g. while saving). |
+| `forceSaveEnabled` | `boolean` | Keep the save button enabled even when the form is not dirty. |
+
+#### `<FormWatcher />` — invisible watcher
+
+`src/components/forms/FormWatcher.tsx`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `control` | `Control<GenericValue>` | Required form control. |
+| `watch` | `FieldList<T>` | Required list of field names. |
+| `onChange` | `(values: FormWatchObject<T>) => void` | Called on change (deep-equality guarded). |
+
+`<Form>` wraps it for you through `watchValues` + `onWatchChange`; use it directly only
+inside a custom `FormProvider`.
+
+#### `<FieldBySchema />` — one field
+
+`src/components/forms/FieldBySchema.tsx` — routes the schema `type` to the right widget.
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `name` | `FieldKey<T>` | Required field name. |
+| `schema` | `SchemaType<T>` | Required full schema. |
+| `control` | `Control<Item<T>>` | Required. |
+| `errors` | `FieldErrors<Item<T>>` | Required. |
+| `autoFocus` | `boolean` | Initial focus. |
+| plus | `CommonFieldProps<T>` | `fieldKey`, `labelKey`, `index`, `optionsAC`, `optionsModel`, `getOptionLabel`, `renderOption`, `onEditModel`, `fieldsLayout`, `options`, `multiline`, `isSemaphoric`, `label`, `onValueChange`, `decimalScale`, `type`, `autoComplete`, `minRows`, `optionIdKey`, `optionLabelKey`, `disabled`, `sx`. |
+
+#### Password forms
+
+| Component | Props | Purpose |
+| --- | --- | --- |
+| `ChangePasswordForm` | `onSuccess?: () => void`, `submitLabel?: string` | Current/new/confirm password; calls `changePassword`. |
+| `ForgotPasswordForm` | `token?: string`, `uid?: string`, `onSuccess?: () => void`, `onBack?: () => void` | With `token`+`uid` it shows the "set new password" step; without them it requests the reset e-mail. |
+
+### 3.2 Lists and grids
+
+#### `<GenericModelList />` — main list page
+
+`src/components/GenericModelList.tsx`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `model` | `string` | Required. |
+| `paginationMode` | `'server' \| 'client'` | Required. `client`: fetch all (batched); `server`: filter/sort/paginate/totals on the server. |
+| `columnFields` | `FieldList<T>` | Columns to show, in order. Defaults to every schema field. |
+| `hiddenFields` | `FieldList<T>` | Columns hidden by default. |
+| `creatableFields` | `FieldList<T>` | Fields editable when adding a row. |
+| `disabledFields` | `FieldList<T>` | Fields never editable. |
+| `minWidthFields` | `MinWidthFields<T>` | Per-column min width. |
+| `indexField` | `FieldKey<T>` | Main/link column. |
+| `indexFieldBasePath` / `indexFieldViewBasePath` | `string` | Paths used by the index link. |
+| `addExistingModel` | `string` | Enables "add existing" for a relation list. |
+| `isEditable` | `boolean` | Inline editing. |
+| `hasBulkSelect`, `onSelectActions` | `boolean`, `OnSelectActions[]` | Selection + bulk actions (`'bulkDelete'`, `'bulkCreate'`, or a custom function). |
+| `actions` | `RowAction<T>[]` | Row actions; default `['editInline', 'remove']`. |
+| `nonEditableActions` | `NonEditableRowAction<T>[]` | Read-only row actions (`'edit'`, `'view'`, custom). |
+| `customActions` | `CustomAction[]` | Extra toolbar/grid actions (`{ key, icon, label, handleClick }`). |
+| `customColumnOperations` | `(column) => column \| Promise<column>` | Last-chance column mutation. |
+| `customLinkDestination` | `(params: GridRenderCellParams) => string` | Custom href for cells. |
+| `customFieldFormLayouts` | `CustomFormFieldLayouts<T>` | Nested relation layouts. |
+| `sumRows` | `SumRowsType<T>` | Totals; in `server` mode also sends `sum_rows` and renders facets. |
+| `defaultFilter` | `GridFilterModel` | Initial filter, merged with the toolbar filter in server mode. |
+| `queryParams` | `string[]` | Extra raw query params appended to every request. |
+| `defaultValues` | `PartialItem<T>` | Defaults for new inline rows. |
+| `optionsAC` | `OptionsAC<T>` | External options cache. |
+| `extraValidators` | `ExtraValidators<T>` | Per-field yup overrides for inline editing. |
+| `onProcessRow` | `(row?: Item<T>) => void` | After an inline save (row) or delete. |
+| `onDataChange` | `(rows: Item<T>[]) => void` | After any grid data change. |
+| `watchEditingRowValues` | `WatchEditingRowValues<T>` | Observe the row being edited; receives `{ rowEditingValues, setRowEditingValues }`. |
+| `reloadStateStamp` | `number \| string` | Change to reload the list. |
+| `isAutoHeight` | `boolean` | Default `true`. |
+| `tableAutoHeight` | `boolean` | Fill the parent instead of fixed grid height. |
+| `cardsViewOnly` | `boolean` | Force the mobile card layout. |
+| `hasHeader` | `boolean` | Show the model plural name + add link. |
+| `LinkComponent` | `LinkComponentType \| null` | Router link adapter (`{ to, href?, state?, ... }`). |
+| `MobileListRenderItem` | `(info) => ReactElement \| null` | Custom mobile card renderer. `info`: `{ item, index, id }` where `item` is formatted. |
+| `MobileRenderNoResults` | `() => ReactElement \| null` | Empty state for mobile. |
+| `disableScreenLoading` | `boolean` | Skip the global loading backdrop. |
+| `hideFooterComponent`, `hideToolbarComponent`, `hideColumnsButton`, `hideFilterButton`, `hideDensityButton`, `hideExportButton`, `hideQuickFilterBar` | `boolean` | UI toggles. |
+
+#### `<GenericRelatedModelList />` — nested collection
+
+`src/components/GenericRelatedModelList.tsx`
+
+Most of the same grid props (minus `disableScreenLoading`, `hasHeader` and
+`customLinkDestination`), plus:
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `model` | `string` | Parent model. |
+| `id` | `Id` | Parent id. |
+| `relatedModel` | `string` | Related model slug (the nested route segment). |
+| `label` | `string` | Card/table title. |
+| `paginationMode` | `'server' \| 'client'` | Required. |
+| `usuaria` | `Item \| null` | Kept for compatibility; not used by the component. |
+| `isInBatches` | `boolean` | Default `true`. |
+| `noCardWrapper` | `boolean` | Render without the surrounding `Card`. |
+| `hiddenFields` | `FieldList<T>` | Default `['id']`. |
+| `isEditable` | `boolean` | Default `true`. |
+
+It requests `/<model>/<id>/<relatedModel>/` and offers add/edit/remove for those rows.
+
+#### `<DataGridBySchemaEditable />` — lower-level grid
+
+`src/components/DataGridBySchemaEditable.tsx`
+
+Desktop DataGrid + mobile cards. Use it for fully custom grids; the list components above
+wrap it. Required: `schema`, `data`, `columns`, `model`, `onEditModel`.
+
+Other props: `rowCount`, `columnVisibilityModel`, `fieldKey`, `labelKey`, `index`,
+`name`, `indexField` (default `'nome'`), `addExistingModel`, `indexFieldMinWidth`,
+`indexFieldBasePath`, `indexFieldViewBasePath`, `stateToLink`, `minWidth`, `loading`,
+`modelParent`, `modelParentId`, `customColumnOperations`, `customFieldFormLayouts`,
+`customLinkDestination`, `LinkComponent`, `onProcessRow`, `onDataChange`,
+`watchEditingRowValues`, `isEditable` (default `false`), `nonEditableActions`,
+`hasBulkSelect`, `cardsViewOnly`, `onSelectActions`, `sx`, `isAutoHeight`,
+`defaultValues`, `hideFooterPagination`, `setVisibleRows`, `paginationModel`,
+`setPaginationModel`, `hideFooterComponent`, `hideToolbarComponent`, `tableAutoHeight`,
+`actions` (default `['editInline', 'remove']`), `customActions`, `hideColumnsButton`,
+`hideFilterButton`, `hideDensityButton`, `hideExportButton`, `hideQuickFilterBar`,
+`optionsAC`, `extraValidators`, `MobileListRenderItem`, `MobileRenderNoResults`.
+
+#### `<DataTotals />` — client-side totals
+
+`src/components/DataTotals.tsx`
+
+| Prop | Type |
+| --- | --- |
+| `schema` | `SchemaType` |
+| `data` | `Item[]` |
+| `sumRows` | `SumRowsType` (required to render) |
+| `visibleRows` | `GridRowId[]` (optional; sum only visible rows) |
+
+There is no public `DataTotalsServer`: server totals/facets are rendered internally by
+`GenericModelList`. (This is a correction to older docs that listed it as exported.)
+
+### 3.3 Detail views
+
+#### `<DetailBySchema />` — read-only detail body
+
+`src/components/details/DetailBySchema.tsx`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `values` | `Item<T>` | Required record. |
+| `schema` | `SchemaType<T>` | Required. |
+| `columns` | `GridEnrichedBySchemaColDef<T>[]` | Required; drives field order/labels. |
+| `loading` | `boolean` | Loading state. |
+| `editLink` / `editLabel` | `string` | Optional edit button. |
+| `fieldsLayout` | `DetailFieldLayout<T>[]` | Sections/accordions. See §4.6. |
+| `hiddenFields` | `FieldList<T>` | Default `['id']`. |
+| `fieldsProps` | `DetailFieldsProps<T>` | Per-field overrides/formatters. |
+| `elevation` | `number` | Card elevation. |
+| `sxSection`, `sxSectionTitle`, `sxRow`, `sxRowMultiple`, `sxField`, `sxLabel`, `sxValue`, `sxValueList`, `sxValueListItem`, `sxValueListItemText` | `SxProps<Theme>` | Styling. |
+
+#### `<DetailFieldBySchema />` — one read-only field
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `fieldKey` | `FieldKey` | Required label/fallback. |
+| `fieldSchema` | `Field` | Metadata; without it the component logs an error and renders nothing. |
+| `value` | `FormattedItemValue` (`{ title, valueStr, value }`) | The formatted value. |
+| `item` | `Item<T>` | Raw record, passed to formatters. |
+| `valueFormatter` | `(value, item, fieldSchema?) => any` | Format before display. |
+| `renderValue` | `({ value, item, fieldSchema, label }) => ReactNode` | Replace the value node. |
+| `emptyValue` | `ReactNode` | Default `-`. |
+| `hideIfEmpty` | `boolean` | Render nothing when empty. |
+| `optionIdKey` / `optionLabelKey` | `string` | Choice/relation keys. |
+| `sxField`, `sxLabel`, `sxValue`, `sxValueList`, `sxValueListItem`, `sxValueListItemText` | `SxProps<Theme>` | Styling. |
+
+#### `<DetailPage />` — full detail page
+
+`src/components/details/DetailPage.tsx` — header (back/title/edit), optional hero and
+tabs; no router dependency.
+
+Props: `model`, `objId`, `titleField`, `title`, `backLink`, `backLabel` (default
+`'Back'`), `onBack` (takes precedence over `backLink`), `editLink`, `editLabel`,
+`hero`, `tabs` (`DetailTabConfig[]`: `{ key, label, sections?, render?, count?,
+hidden?, icon? }`), `sections`, `fieldsLayout` (alias of `sections`), `hiddenFields`,
+`fieldsProps`, `elevation` (default `0`), `renderHeader`, `renderShell`, `emptyLabel`,
+`errorLabel`, `retryLabel`, plus the shared `sx*` props.
+
+#### `useDetailData()` — detail data loader
+
+`src/hooks/useDetailData.ts`
+
+```ts
+const { values, schema, columns, loading, error, reload } = useDetailData({ model, objId });
+```
+
+`UseDetailDataResult`: `{ values, schema, columns, loading, error, reload }`.
+`UseDetailDataProps` also declares `titleField`, but the hook currently only uses
+`model` and `objId`.
+
+### 3.4 Small shared components
+
+| Component | Props | Purpose |
+| --- | --- | --- |
+| `HtmlContent` | `{ html?: string \| null; sx?: SxProps<Theme> }` | Sanitized read-only HTML. Uses `dompurify` when installed, otherwise strips tags. |
+| `FileTypeIcon` | `{ name?: string }` | Icon for a file name/URL extension. Exports `FILE_TYPE_ICONS` and `DEFAULT_FILE_ICON` from the same module (not from the package root). |
+| `DialogActions` | `{ setDialog, handleSave?, btnCancel?, btnConfirm? }` | Cancel/confirm buttons for a `setDialog` body. |
+
+### 3.5 Field widgets and grid cells
+
+These are exported for composition inside custom layouts. All form widgets accept
+`FieldBySchemaProps<T>` (`name`, `schema`, `control`, `errors`, plus `CommonFieldProps`):
+
+`TextFieldBySchema`, `HtmlFieldBySchema`, `BooleanFieldBySchema`,
+`DesktopDatePickerBySchema`, `DesktopDateTimePickerBySchema`,
+`AutocompleteFieldBySchema`, `EditableAutocompleteFieldBySchema`, `FloatFieldBySchema`.
+
+Grid editing primitives (they rely on the DataGrid edit context, not on
+react-hook-form): `SelectEditInputCell`, `GridDateInput`, `GridDecimalInput`,
+`GridPatternInput`, `BooleanInputCell`.
+
+Leaflet helpers: `applyDefaultLeafletIcon`, `applyThemeMarkerIcon`,
+`DRF_REACT_BY_SCHEMA_MARKER_ICON`, `DEFAULT_LAYERS`; text lookup: `getThemeTexts`.
+
+---
+
+## 4. Shared prop building blocks
+
+These types are exported from `@types` and reused by the components above.
+
+### 4.1 `fieldsLayout` (forms)
+
+`FormFieldLayout<T>` = `{ title?, rows?, customLabels?, CustomElement? }` per section.
+
+- `rows` is an array of: a field name, an array of fields (same row), or a
+  `CustomFormField` (`{ key, CustomElement }`).
+- `customLabels` overrides specific labels in that section.
+- `CustomElement` replaces the whole section body.
+
+### 4.2 `CommonFieldProps` (shared by field widgets/forms)
+
+`value`, `multiline`, `setValue`, `getValues`, `fieldKey`, `labelKey`, `index`,
+`optionsAC`, `optionsModel`, `getOptionLabel`, `renderOption`, `onEditModel`,
+`fieldsLayout`, `multiple`, `sx`, `options`, `isSemaphoric`, `label`, `onValueChange`,
+`decimalScale`, `type`, `autoComplete`, `minRows`, `optionIdKey`, `optionLabelKey`,
+`disabled`.
+
+### 4.3 `fieldsProps`
+
+`Record<fieldName, CommonFieldProps>` — per-field widget overrides, e.g.
+`fieldsProps={{ observacao: { minRows: 5 }, comunidade: { disabled: true } }}`.
+
+### 4.4 `hiddenFields`, `columnFields`, `creatableFields`, `disabledFields`
+
+`FieldList<T>` (array of field names). They filter columns/fields; in forms,
+`hiddenFields` values are preserved as hidden inputs on save.
+
+### 4.5 `sumRows`
+
+`SumRowsType<T>` = `{ rows: SumRowsItem<T>[]; severity?: AlertColor }`, where a row is
+`{ field, prefix?, suffix?, isCount?, facetBy?, facetLimit? }`.
+
+- In `client` mode `DataTotals` sums the loaded rows (optionally only `visibleRows`).
+- In `server` mode the same rows become the `sum_rows` query and `DataTotalsServer`
+  (internal) renders `sumRowsTotals` + `facets`.
+- `facetBy` accepts field keys or nested forward relations (`'comunidade__municipio'`).
+
+### 4.6 `fieldsLayout` (details)
+
+`DetailFieldLayout<T>` = `{ title?, rows?, CustomElement?, isAccordion?, isAccordionOpen?,
+hidden?, hideIfEmpty? }`.
+
+- `rows` accepts field paths, arrays (same row), or `CustomDetailField`
+  (`{ key, CustomElement }`).
+- Dotted paths (`'contratacao.valor'`) resolve nested values/metadata.
+- `hidden(values)` omits the section; `hideIfEmpty` omits it when every field is empty.
+
+### 4.7 `fieldsProps` (details)
+
+`DetailFieldsProps<T>` — per-field `DetailCommonFieldProps`: `valueFormatter`,
+`renderValue`, `emptyValue`, `hideIfEmpty`, `item`, `fieldSchema`, plus `sx*` overrides
+and the shared `CommonFieldProps`.
+
+### 4.8 Actions
+
+- `ActionType`: `'editInline' | 'remove' | 'edit' | 'view'`.
+- `RowAction<T>`: an `ActionType` or `CustomRowAction` (`{ icon, label?, handleClick(item) }`).
+- `NonEditableRowAction<T>`: `'edit' | 'view' | CustomRowAction`.
+- `CustomAction<T>`: `{ key, icon, label, handleClick(item) }` — extra toolbar action.
+- `OnSelectActions`: `{ title, action: 'bulkDelete' | 'bulkCreate' | custom(selectedData, bulkUpdateData) }`.
+
+### 4.9 `optionsAC` and relation loading
+
+`OptionsAC<T>` is `Record<model, OptionsACItem[]>` (usually
+`AutocompleteItem = { id, label }`, choice items are also accepted). It is populated
+automatically for relation fields; pass it only when you need to preload/override
+options.
+
+### 4.10 `extraValidators`
+
+`Record<fieldName, YupSchema>` replacing the generated validator for those fields.
+Useful for cross-field rules, e.g.
+`{ fim: yup.date().min(yup.ref('inicio'), '...') }` (resolve the ref against the form
+values).
+
+### 4.11 `LinkComponent`
+
+`React.ComponentType<{ to: string | object; href?; state?; className?; style?; children? }>`
+— lets the package navigate with react-router (or any router) instead of plain anchors.
+
+### 4.12 `FormSaveActions`
+
+Enum passed to `Form.onSave` as `buttonType`:
+`EXIT_ON_SAVE = 'exitOnSave'`, `SAVE_AND_CONTINUE = 'saveAndContinue'`,
+`SAVE_AND_CREATE_NEW = 'saveAndCreateNew'`.
+
+### 4.13 `reloadStateStamp`
+
+Any `number | string`. When it changes, `<Form>`, `<GenericModelList>` and
+`<GenericRelatedModelList>` reload their data. Useful after an external mutation.
+
+### 4.14 `conditional_visible`
+
+Schema key (produced by Django) that hides fields until a condition holds. Hidden
+fields are cleared on save. Shapes accepted: a `[field, value]` pair, an array of
+conditions (OR, legacy), or `{ operator: 'AND' | 'OR', conditions: [...] }` (nestable).
+`ui_required` fields are required only while visible. See the README section for a
+worked example.
+
+---
+
+## 5. Utility functions
+
+Exported from the package root.
+
+| Function | Signature | Purpose |
+| --- | --- | --- |
+| `setAuthToken` | `(token: string \| null) => void` | Stores the access token in `localStorage` and sets/clears the axios `Authorization` header. `null` also removes the refresh token. |
+| `hasJWT` | `() => boolean` | Whether an access token is stored. |
+| `clearJWT` | `() => false` | Removes the access token (and returns `false`). |
+| `AUTH_EXPIRED_EVENT` | `string` constant | Dispatched on `window` when the token refresh fails. Listen to it to sign the user out. |
+| `emptyByType` | `(field: Field, forDatabase = false) => any` | Empty value for a field type (`''`, `[]`, `false`, `0`, `null`, …). `forDatabase` fixes nested-object/`field` edge cases. |
+| `populateValues` | `({ data, schema }) => Item` | Fills missing values with `emptyByType` and normalizes choices/relations for the forms. |
+| `enrichChoices` | `(rawData, schema) => Item<T>` | Shapes raw choice values into `{ value, display_name }` (and lists into arrays of them). |
+| `getChoiceByValue` | `(value, choices?) => string \| null \| undefined` | Choice `display_name` for a raw value. |
+| `buildGenericYupValidationSchema` | `({ data, schema, many?, skipFields?, extraValidators?, uiFields? }) => ObjectSchema` | Builds the yup schema used by forms/grids from field metadata. |
+| `getDataGridColumns` | `(schema, columnFields?, creatableFields?, disabledFields?) => GridEnrichedBySchemaColDef[] \| false` | Derives grid columns from a schema. |
+| `errorProps` | `({ errors, fieldKey, fieldKeyProp, index? }) => { error, helperText }` | Maps react-hook-form errors to MUI `TextField`/grid props. |
+| `getFieldErrorsFromResponse` | `(response, schema?) => Record<field, { type, message }>` | Normalizes DRF validation errors for `setError` (skips unknown keys and `non_field_errors`). |
+| `getTmpId` | `() => string` | Generates a `tmp<n>` id for unsaved rows. |
+| `isTmpId` | `(id) => boolean` | `true` for empty/`'novo'`/`tmp*` ids. |
+| `isReadOnlyField` | `(field?) => boolean` | Read-only derived field (relations are not considered read-only here). |
+| `isRelationField` | `(field?) => boolean` | `type` is `'field'` or `'nested object'`. |
+| `getPatternFormat` | `(type: string) => string` | Input mask for known field types (`telefone`, `cpf`, `cnpj`, …). |
+| `slugToCamelCase` | `(str, includeFirst = false) => string` | Converts slugs to camelCase (`my_model` → `myModel`); `includeFirst` capitalizes the first letter (`MyModel`). |
+
+---
+
+## 6. Error handling contract
+
+- Every fetch/write helper resolves to the value **or** an `AxiosError`-shaped object
+  (`axios.isAxiosError(result) === true`). Check before use.
+- A `401` triggers a single token refresh; if that fails the package dispatches
+  `AUTH_EXPIRED_EVENT` and returns an error.
+- The high-level write helpers (`onSubmit`, `onEditModelSave`, `onDeleteModel`, …) also
+  show a snackbar and close dialogs as documented above; the raw helpers (`postData`,
+  `updateModel`, `rawDeleteData`) do not.
+- `<Form>` maps per-field DRF errors onto the corresponding form fields; unknown keys
+  and `non_field_errors` stay in the generic snackbar message.
+
+---
+
+## 7. Agent notes and gotchas
+
+- `watchValues`/`onWatchChange` only run when **both** are provided. `onWatchChange`
+  receives an object keyed by the listed field names, and is only called when the
+  watched values actually change (deep equality).
+- `GenericModelList` has no `paginationModel` or `title` prop; the pagination model is
+  internal and the header title is the model's `verbose_name_plural`. `fieldsLayout`
+  belongs to `<Form>`; lists use `customFieldFormLayouts` for nested forms.
+- `onDeleteModel` is fire-and-forget (confirmation dialog), while
+  `onDeleteRelatedModel` returns a promise.
+- `getRawData` prefixes `${serverEndPoint.api}/`; do not pass a leading `/api`.
+- `FormBySchema` needs the react-hook-form `control`/`errors`; it does not create a form.
+- `Form` accepts a `register` prop in its type but ignores it — the component owns the
+  react-hook-form instance and passes its own `register` down.
+- `FieldBySchema`/`DetailFieldBySchema` silently skip fields with no schema entry
+  (`DetailFieldBySchema` logs an error); always pass the matching schema.
+- `conditional_visible` values are cleared on save; do not rely on stale hidden values.
+- `ui_required` is enforced only for fields present in the rendered layout.
+- Mobile: forms/grids switch to cards below the `md` breakpoint; `cardsViewOnly` forces
+  cards on desktop. Always check layouts on mobile.
+- The two `*.md` files next to `DataGridBySchemaEditable` and
+  `DRFReactBySchemaProvider` are legacy snippets, not references — use this document.