drf-react-by-schema 0.28.26 → 0.28.28

package/README.md

@@ -34,6 +34,16 @@ On the React side, `drf-react-by-schema-react` offers a range of powerful compon
 
 The _DRF and React By Schema_ Suite is available for React at https://www.npmjs.com/package/drf-react-by-schema and for Django at https://pypi.org/project/drf-react-by-schema/.
 
+## API reference
+
+Every exported component (purpose and props), the full `useAPIWrapper()` API (data,
+auth, form state, dialogs, feedback), the shared prop building blocks
+(`fieldsLayout`, `fieldsProps`, `sumRows`, actions, …) and the utility functions are
+documented in **[`docs/API_REFERENCE.md`](docs/API_REFERENCE.md)**.
+
+Consuming apps must use `useAPIWrapper()`. The lower-level `useDRFReactBySchema()` is
+internal, is not exported from the package entry and must not be used by app code.
+
 ## Field types & widgets
 
 Every schema field `type` maps to a specific widget. This includes the standard

package/dist/components/DataGridBySchemaEditable/DataGridDesktop.d.ts

@@ -5,6 +5,9 @@ import { AnySchema } from 'yup';
 import { CustomToolbarProps } from './CustomToolbar';
 declare module '@mui/x-data-grid' {
     interface ToolbarPropsOverrides extends CustomToolbarProps {
+        isEditableToolbar?: boolean;
+        hideToolbarComponent?: boolean;
+        watchEditingRowValues?: WatchEditingRowValues;
     }
 }
 import { SxProps, Theme } from '@mui/material/styles';

package/dist/components/DataGridBySchemaEditable/DataGridDesktop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataGridDesktop.d.ts","sourceRoot":"","sources":["../../../src/components/DataGridBySchemaEditable/DataGridDesktop.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"DataGridDesktop.d.ts","sourceRoot":"","sources":["../../../src/components/DataGridBySchemaEditable/DataGridDesktop.tsx"],"names":[],"mappings":"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"}

package/dist/components/DataGridBySchemaEditable/DataGridDesktop.js

@@ -32,6 +32,17 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -59,6 +70,13 @@ const usePreparedColumns_1 = require("./hooks/usePreparedColumns");
 const useDataGridActions_1 = require("./hooks/useDataGridActions");
 const useProcessRowUpdate_1 = require("./hooks/useProcessRowUpdate");
 const RowEditingWatcher_1 = __importDefault(require("./RowEditingWatcher"));
+// Module-level so the slot type stays stable across renders; an inline slot component remounts the toolbar and its quick filter input.
+const InternalToolbar = (_a) => {
+    var { isEditableToolbar, hideToolbarComponent, watchEditingRowValues } = _a, props = __rest(_a, ["isEditableToolbar", "hideToolbarComponent", "watchEditingRowValues"]);
+    return (react_1.default.createElement(react_1.default.Fragment, null,
+        isEditableToolbar && watchEditingRowValues && (react_1.default.createElement(RowEditingWatcher_1.default, { watchEditingRowValues: watchEditingRowValues })),
+        !hideToolbarComponent && react_1.default.createElement(CustomToolbar_1.CustomToolbar, Object.assign({}, props))));
+};
 function DataGridDesktop({ schema, apiRef, dataGridRows, setDataGridRows, rowCount = 0, columns, columnVisibilityModel, model, name = Math.floor(Math.random() * 1000000).toString(), indexField = 'nome', addExistingModel, indexFieldMinWidth = 350, indexFieldBasePath = '', indexFieldViewBasePath, stateToLink = {}, minWidth = 80, loading, modelParent, modelParentId, customColumnOperations, customFieldFormLayouts, customLinkDestination, LinkComponent, onProcessRow, watchEditingRowValues, onEditModel, isEditable = false, nonEditableActions, hasBulkSelect, onSelectActions, sx: sxProp, isAutoHeight, defaultValues, hideFooterPagination, setVisibleRows, paginationModel, setPaginationModel, hideFooterComponent, hideToolbarComponent, tableAutoHeight, actions = ['editInline', 'remove'], customActions, hideColumnsButton, hideFilterButton, hideDensityButton, hideExportButton, hideQuickFilterBar, optionsAC: optionsACExternal, extraValidators, emptyItem, handleDeleteClick, setSnackBar, yupValidationSchema, }) {
     var _a;
     const [dataGridLoading, setDataGridLoading] = (0, react_1.useState)(false);
@@ -365,10 +383,7 @@ function DataGridDesktop({ schema, apiRef, dataGridRows, setDataGridRows, rowCou
             });
             console.log(e);
         }, slots: {
-            // toolbar: hideToolbarComponent ? () => <React.Fragment /> : CustomToolbar,
-            toolbar: (props) => (react_1.default.createElement(react_1.default.Fragment, null,
-                isEditable && watchEditingRowValues && (react_1.default.createElement(RowEditingWatcher_1.default, { watchEditingRowValues: watchEditingRowValues })),
-                !hideToolbarComponent && react_1.default.createElement(CustomToolbar_1.CustomToolbar, Object.assign({}, props)))),
+            toolbar: InternalToolbar,
             footer: hideFooterComponent ? () => react_1.default.createElement(react_1.default.Fragment, null) : InternalFooter,
         }, slotProps: {
             toolbar: {
@@ -384,6 +399,9 @@ function DataGridDesktop({ schema, apiRef, dataGridRows, setDataGridRows, rowCou
                 hideDensityButton,
                 hideExportButton,
                 hideQuickFilterBar,
+                hideToolbarComponent,
+                isEditableToolbar: isEditable,
+                watchEditingRowValues,
                 showQuickFilter: true,
                 quickFilterProps: { debounceMs: 500 },
                 handleExportExcel: paginationModel

package/dist/components/forms/Form.d.ts

@@ -52,7 +52,9 @@ interface FormProps<T extends TField = void> extends Omit<CommonFieldProps<T>, '
     elevation?: number;
     CustomFormActions?: (props: FormActionsProps) => React.JSX.Element;
     extraValidators?: ExtraValidators<T>;
+    /** Field names monitored on change; requires `onWatchChange`. */
     watchValues?: FieldList<T>;
+    /** Called with `{ [field]: value }` when a watched value changes. */
     onWatchChange?: (values: FormWatchObject<T>) => void;
     reloadStateStamp?: number | string;
 }

package/dist/components/forms/Form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Form.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Form.tsx"],"names":[],"mappings":"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"}

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.

package/docs/FIELD_TYPES.md

@@ -0,0 +1,145 @@
+# Field types & widgets
+
+`drf-react-by-schema` derives every form widget, validation rule and DataGrid column
+directly from the schema generated by `drf-react-by-schema-django` (via the model
+serializers + `OPTIONS`/`sync_react`). This page documents each schema field `type`
+and the matching widget it renders.
+
+## Quick reference
+
+The `type` value comes from the schema that Django exposes for each model field.
+The table below maps every type to its **form widget** and its **DataGrid** behavior.
+
+| Schema type | Form widget | DataGrid read (cell) | DataGrid edit | Notes |
+| --- | --- | --- | --- | --- |
+| `string` | `TextField` (single line) | text | text input (mask if `pattern_format`) | |
+| `string` + `model_html` | **Tiptap WYSIWYG** (`HtmlFieldBySchema`) | sanitized **HTML** | text input | optional peers; falls back to multiline `TextField` |
+| `email` | `TextField` (email) | text | text input | |
+| `password` | `TextField` (`type="password"`) | text (hidden) | text input | |
+| `number`, `integer` | `TextField` (numeric) | number (pt-BR formatted) | numeric input | `min`/`max` from validators |
+| `decimal`, `float` | `FloatFieldBySchema` (decimal input) | number (pt-BR, `decimal_places`) | `GridDecimalInput` | honors `decimal_places`, `is_currency` |
+| `date` | `DesktopDatePickerBySchema` (MUI date picker) | date (`date_views` format) | `GridDateInput` | |
+| `datetime` | `DesktopDateTimePickerBySchema` (MUI date-time picker) | date-time (`DD/MM/YYYY HH:mm`) | `GridDateTimeInput` | |
+| `boolean` | `BooleanFieldBySchema` (switch) | `Sim` / `Não` | `BooleanInputCell` | |
+| `choice` | `AutocompleteFieldBySchema` (single select) | label (join) | `SelectEditInputCell` | `choices` provide options |
+| `list` / `multiple choice` | `AutocompleteFieldBySchema` (multi-select) | label (comma-joined) | `SelectEditInputCell` (`multiple`) | `many: true`; child `choices` |
+| `field` / `nested object` | `EditableAutocompleteFieldBySchema` (related) | related label | `SelectEditInputCell` | `related_editable` enables editing via dialog |
+| `file` / `file upload` | `FileFieldBySchema` (upload) | file name | `FileInputCell` | `allowed_mime_types` |
+| `image` / `image upload` | `FileFieldBySchema` (image upload) | thumbnail preview | `FileInputCell` | `allowed_mime_types` |
+| `array` | `TextField` (default fallback) | text | text input | |
+| `slug` | `TextField` | text | text input | forced `read_only` |
+| `point` | Leaflet **point picker** (see Geometry below) | **thumb map** | **modal** point picker | requires PostGIS + leaflet |
+| `polygon` | Leaflet **polygon draw** (see Geometry below) | **thumb map** | **modal** polygon draw | requires PostGIS + leaflet |
+| `multipoint` | Leaflet **multi-point picker** (see Geometry below) | **thumb map** | **modal** multi-point picker | requires PostGIS + leaflet |
+| `multipolygon` | Leaflet **multi-polygon draw** (see Geometry below) | **thumb map** | **modal** multi-polygon draw | requires PostGIS + leaflet |
+| `geometrycollection` | Leaflet **points + polygons draw** (see Geometry below) | **thumb map** | **modal** geometry draw | requires PostGIS + leaflet |
+
+## Rich text fields (`model_html`)
+
+A Django `TextField(rich_text=True)` (from `drf_react_by_schema.fields`) keeps its plain
+`string` type but adds `model_html: true` to the schema. The value **is HTML** — the same
+format the Django admin's Summernote widgets store — so no conversion or migration is
+needed for existing admin-authored content.
+
+### Requirements
+
+The editor is optional, like the map widgets. Install Tiptap in the **consuming app**:
+
+```bash
+npm install @tiptap/react @tiptap/starter-kit
+# optional: sanitizes rich text in detail views
+npm install dompurify
+```
+
+Without Tiptap the field falls back to the multiline text field (raw HTML editable as
+text), and the form keeps working. Without `dompurify` the detail view renders the value
+as plain text (tags stripped) instead of injecting HTML.
+
+### Widgets and behaviour
+
+- **Form** (`HtmlFieldBySchema` → `RichTextEditorInput`): a Tiptap editor with an MUI
+  toolbar — paragraph/H1–H3, bold, italic, underline, strikethrough, bullet and ordered
+  lists, quote, code block, horizontal rule, link (dialog), clear formatting, undo/redo.
+  The form value is the editor's HTML (`getHTML()`), empty content is saved as `''`.
+- **Detail** (`DetailFieldBySchema` → `HtmlContent`): the HTML is sanitized with
+  DOMPurify against an allow-list of tags/attributes, then rendered read-only with the
+  package's typography scale.
+- **Grid**: the cell shows the stored HTML as text (no rendering); the toolbar strings are
+  localized through `theme.texts.richText` (see `docs/localization.md`).
+
+Sanitization happens on **render**, not on save: the API keeps the HTML verbatim, so any
+other client of the same column must sanitize it too.
+
+## Geometry fields (PostGIS)
+
+Geometry field types map to Django's GeoDjango model fields (`PointField`,
+`PolygonField`, `MultiPointField`, `MultiPolygonField`, `GeometryCollectionField`)
+serialized as **GeoJSON**. They are only emitted when the database engine is PostGIS.
+
+### Requirements
+
+The map widgets are optional. They require the following packages to be installed in
+the **consuming app** (they are declared as *optional* peer dependencies of
+`drf-react-by-schema`):
+
+```bash
+npm install leaflet react-leaflet leaflet-draw
+```
+
+If any of them is missing, the field falls back to a plain widget so the app keeps
+working:
+
+- **`point`** → a single-line text input.
+- **`polygon`, `multipoint`, `multipolygon`, `geometrycollection`** → a multiline text area.
+
+In both cases the value stays a GeoJSON string.
+
+### Widgets and behaviour
+
+All geometry widgets share the same map + text editing UI:
+
+- The **map** shows and edits the geometry over an OpenStreetMap base layer.
+- A **text field** below the map is **always synchronized in both directions**:
+  - paste/edit a GeoJSON string → it renders immediately on the map;
+  - draw/move on the map → the text field updates to the generated GeoJSON.
+- **Malformed (or wrong-type) GeoJSON** text is flagged as an **input error** — the
+  message shows `Dados malformados, corrija o GeoJSON para refletir no mapa.` and the
+  previously drawn features are kept on the map (they are not wiped).
+- The read-only **grid cell** renders a **thumb map**: a static mini-map fitted to the
+  geometry with padding + a zoom cap, so the shape is shown with some surrounding
+  context.
+- The **grid edit cell** is a button that opens a **modal** with the picker/drawer + the
+  synced GeoJSON text field.
+
+Behaviour per type:
+
+| `type` | Can add | Move existing | Remove existing | Single instance? |
+| --- | --- | --- | --- | --- |
+| `point` | add **one** marker | drag marker | via grid edit delete | **yes** |
+| `polygon` | draw **one** polygon | draw-edit (drag/reshape) | via edit delete | **yes** |
+| `multipoint` | add **many** markers | drag each marker | via edit delete | no |
+| `multipolygon` | add **many** polygons | draw-edit each | via edit delete | no |
+| `geometrycollection` | **many** points **and** polygons | both | both | no |
+
+- For the **single-instance** types (`point`, `polygon`), once one shape exists the
+  corresponding "add" tool is hidden from the toolbar — the shape can be **moved** and
+  **removed**, and removing it re-enables adding.
+- Points (`point`, `multipoint`, and the points in `geometrycollection`) are **draggable**
+  markers: drag to move, and the new coordinates are written back immediately.
+- Polygons (and the polygon parts of `multipolygon` / `geometrycollection`) use
+  Leaflet-Draw's edit control to **move/resize** and its delete tool to remove.
+
+### Server side
+
+| Model field (drf-react-by-schema) | Schema `type` | GeoJSON |
+| --- | --- | --- |
+| `fields.PointField` | `point` | `Point` |
+| `fields.PolygonField` | `polygon` | `Polygon` |
+| `fields.MultiPointField` | `multipoint` | `MultiPoint` |
+| `fields.MultiPolygonField` | `multipolygon` | `MultiPolygon` |
+| `fields.GeometryCollectionField` | `geometrycollection` | `GeometryCollection` |
+
+> Tip: after adding/editing these model fields, run Django's `manage.py sync_react` to
+> regenerate the TypeScript types — geometry fields map to the corresponding GeoJSON
+> types (`Point`, `Polygon`, `MultiPoint`, `MultiPolygon`, `GeometryCollection`) rather
+> than `any`.

package/docs/localization.md

@@ -0,0 +1,173 @@
+# Localization & theming
+
+## Overview
+
+`drf-react-by-schema` exposes its user-facing strings through the **MUI theme**, so a
+consuming app can localize (translate) every widget in **one place** — its own theme.
+This follows MUI's own approach (MUI components take `localeText`/`locale` props and the
+DataGrid locale lives on the theme), keeps the strings out of `DRFReactBySchemaProvider`,
+and works out of the box with sensible defaults.
+
+## How it works
+
+- The package **augments the MUI theme** (`@mui/material/styles`) with a typed `texts`
+  field (`Theme.texts` / `ThemeOptions.texts`).
+- Package **defaults** (English) are baked into the package's **default theme**; apps
+  override any namespace they want in their own theme.
+- `DRFReactBySchemaProvider` **deepmerges** the app's `theme` onto that default theme
+  (`deepmerge(defaultTheme, theme)`), so an app only sets the keys it wants.
+- Widgets read the texts through `useTheme()` plus the exported `getThemeTexts(theme)`
+  helper, falling back to the built-in defaults when `theme.texts` is absent.
+
+Because everything lives in the theme, it works under `DRFReactBySchemaProvider` **and**
+under any plain `ThemeProvider` (texts simply fall back to the package defaults).
+
+## Available texts (namespaces)
+
+The `texts` shape is extensible — add new namespaces over time. Currently:
+
+| Namespace | Used by | Keys |
+| --------- | ------- | ---- |
+| `texts.geometry` | geometry picker (`MapGeometryPicker`) and grid edit/thumb cells (`GeoEditCell`) | `labelPoint`, `labelOther`, `malformed`, `synced`, `edit`, `define`, `drawSelectTitle`, `close` |
+| `texts.forms` | form action buttons (`FormActions`, `DialogFormBySchema`) and dialogs (`DialogActions`) | `save`, `saveAndContinue`, `saveAndCreateNew`, `cancel`, `remove`, `dialogCancel`, `dialogSave` |
+| `texts.richText` | rich-text toolbar (`RichTextEditorInput`) and link dialog | `paragraph`, `heading1`–`heading3`, `bold`, `italic`, `underline`, `strike`, `bulletList`, `orderedList`, `blockquote`, `codeBlock`, `horizontalRule`, `link`, `linkTitle`, `linkUrl`, `linkApply`, `linkRemove`, `linkCancel`, `clearFormatting`, `undo`, `redo` |
+
+## Setting texts in your app
+
+Add a `texts` key to the `theme` you pass to `DRFReactBySchemaProvider` (or to your own
+`ThemeProvider`). The provider deepmerges it, so you can provide only the keys you want
+to change.
+
+```tsx
+// theme.ts
+import { createTheme } from '@mui/material/styles'
+
+export const theme = createTheme({
+  // ...palette, typography, etc.
+  texts: {
+    geometry: {
+      labelPoint: 'Coordenadas (GeoJSON)',
+      labelOther: 'GeoJSON (cole aqui)',
+      malformed: 'Dados malformados, corrija o GeoJSON para refletir no mapa.',
+      synced: 'O GeoJSON abaixo é sincronizado com o mapa.',
+      edit: 'Editar geometria',
+      define: 'Definir geometria',
+      drawSelectTitle: 'Desenhar / selecionar geometria',
+      close: 'Fechar',
+    },
+    forms: {
+      save: 'Salvar',
+      saveAndContinue: 'Salvar e continuar',
+      saveAndCreateNew: 'Salvar e criar novo',
+      cancel: 'Cancelar',
+      remove: 'Apagar',
+      dialogCancel: 'Cancelar',
+      dialogSave: 'Salvar',
+    },
+    richText: {
+      paragraph: 'Parágrafo',
+      heading1: 'Título 1',
+      heading2: 'Título 2',
+      heading3: 'Título 3',
+      bold: 'Negrito',
+      italic: 'Itálico',
+      underline: 'Sublinhado',
+      strike: 'Riscado',
+      bulletList: 'Lista com marcadores',
+      orderedList: 'Lista numerada',
+      blockquote: 'Citação',
+      codeBlock: 'Bloco de código',
+      horizontalRule: 'Linha horizontal',
+      link: 'Link',
+      linkTitle: 'Inserir link',
+      linkUrl: 'URL',
+      linkApply: 'Aplicar',
+      linkRemove: 'Remover link',
+      linkCancel: 'Cancelar',
+      clearFormatting: 'Limpar formatação',
+      undo: 'Desfazer',
+      redo: 'Refazer',
+    },
+  },
+})
+
+// App.js
+import { DRFReactBySchemaProvider } from 'drf-react-by-schema'
+import { theme } from './theme'
+
+<DRFReactBySchemaProvider serverEndPoint={...} schema={...} theme={theme}>
+  <YourWonderfulApp />
+</DRFReactBySchemaProvider>
+```
+
+TypeScript picks up the `texts` keys automatically from the theme augmentation; you can
+also import and reuse the text types (`DRFReactBySchemaTexts`, `GeometryTexts`,
+`FormTexts`) from `drf-react-by-schema` for reference.
+
+## Precedence
+
+Strings resolve in this order, so the most specific wins:
+
+1. **Explicit component prop** — e.g. `FormActions` has `labelSave`/`labelCancel`/
+   `labelRemove`/`labelSaveAndContinue`/`labelSaveAndCreateNew`; `DialogActions` has
+   `btnCancel`/`btnConfirm`; `MapGeometryPicker` has `label`/`helperText`.
+2. **`theme.texts.<namespace>`** — set app-wide in your theme.
+3. **Package `DEFAULT_TEXTS`** — the built-in fallback.
+
+Since the explicit props still exist, both strategies can coexist: pass per-component
+strings for a one-off button, or set theme texts for whole-app localization.
+
+## MUI component localization
+
+The package's default theme already localizes the MUI components it renders to
+**pt-BR** by composing MUI's official locale packages:
+
+- `@mui/material/locale` (core components)
+- `@mui/x-data-grid/locales` (DataGrid), plus DataGrid `localeText` overrides for the
+  package's custom toolbar strings (`Buscar...`, `Limpar busca`, …)
+- `@mui/x-date-pickers/locales` (date pickers)
+
+Date/time inputs additionally wrap each field in
+`<LocalizationProvider adapterLocale="pt-br">`. To switch to another language, set the
+corresponding MUI locale + DataGrid `localeText` in your theme and the desired
+`adapterLocale` on the picker inputs.
+
+## Markers (geometry)
+
+By default the geometry widgets render points with a **built-in inline-SVG marker
+icon** (a data-URI), so markers appear out of the box under any bundler — Leaflet's
+stock page-relative PNGs 404 inside an SPA. To use a custom marker, call the imperative
+helper once at app startup (it always applies/overrides):
+
+```ts
+import { applyDefaultLeafletIcon } from 'drf-react-by-schema'
+
+applyDefaultLeafletIcon({
+  iconUrl: '/assets/my-marker.png',
+  iconSize: [30, 42],
+  iconAnchor: [15, 42],
+})
+```
+
+If you don't call it, the package's widgets apply the built-in default the first time it
+is needed (and never override an icon you already placed on `L.Icon.Default`). Because
+the application is one-shot, call it before rendering your maps; subsequent calls without
+arguments are no-ops.
+
+## Reading texts in custom components
+
+If you build custom widgets that should share the same themed strings, use the exported
+`getThemeTexts(theme)` helper (returns theme texts merged over the package defaults):
+
+```tsx
+import { useTheme } from '@mui/material/styles'
+import { getThemeTexts } from 'drf-react-by-schema'
+
+function MyActions() {
+  const formTexts = getThemeTexts(useTheme()).forms
+  return <button>{formTexts.save}</button>
+}
+```
+
+The text types (`DRFReactBySchemaTexts`, `GeometryTexts`, `FormTexts`) are exported from
+`drf-react-by-schema` too, so you can type helper objects separately.

package/docs/password-reset-and-email.md

@@ -0,0 +1,145 @@
+# Password reset, change password & e-mail setup
+
+End-to-end guide for the **forgot-password / change-password** flow on a
+Django + DRF + simplejwt backend with this React package.
+
+The **React** side ships:
+
+- `ForgotPasswordForm` — works in two modes:
+  - *request*: asks for the e-mail and calls `requestPasswordReset`.
+  - *confirm*: given `uid` + `token` (from the e-mail link), sets a new password
+    via `confirmPasswordReset`.
+- `ChangePasswordForm` — for an already signed-in user (current password + new
+  password), backed by `changePassword`.
+- `useAPIWrapper()` exposes: `requestPasswordReset(email)`,
+  `validatePasswordReset({ uid, token })`,
+  `confirmPasswordReset({ uid, token, new_password })`, `changePassword({ old_password, new_password })`.
+  `validatePasswordReset` resolves the account behind a reset link (name +
+  `has_usable_password`) without changing anything, so the page can greet the user
+  by name and tell a first-time invite (no usable password yet) from a reset.
+
+Everything is mobile-friendly (the forms use `fullWidth` fields) and lives under
+`DRFReactBySchemaProvider`, so the helpers are typed through `useAPIWrapper()`.
+
+## 1. Server contract (provided by drf-react-by-schema-django)
+
+The Django package exposes these endpoints (auto-registered):
+
+| Method | Endpoint | Auth | Body |
+|---|---|---|---|
+| POST | `password_reset/request/` | none | `{ email }` |
+| POST | `password_reset/validate/` | none | `{ uid, token }` |
+| POST | `password_reset/confirm/` | none | `{ uid, token, new_password }` |
+| POST | `my_account/change_password/` | JWT | `{ old_password, new_password }` |
+
+It reuses `django.contrib.auth` for token generation and password hashing, so no
+extra package (allauth / dj-rest-auth) is required. See the Django package README
+for the full details of the pluggable delivery callback.
+
+## 2. Frontend wiring (no extra config needed)
+
+`DRFReactBySchemaProvider` derives `requestPasswordReset`, `validatePasswordReset`,
+`confirmPasswordReset` and `changePassword` from your `serverEndPoint` automatically
+(`{api}/password_reset/…`, `{api}/my_account/change_password/`). You only need the
+usual `url`/`apiTokenUrl`, e.g.:
+
+```ts
+const serverEndPoint = {
+  url: 'http://localhost:8000',
+  apiTokenUrl: 'http://localhost:8000/api/token/',
+}
+```
+
+Example — a public reset page reached both from the login screen and from the
+e-mail link (`/esqueci-senha?uid=..&token=..`):
+
+```tsx
+import { ForgotPasswordForm } from 'drf-react-by-schema'
+
+function ForgotPasswordPage() {
+  const [params] = useSearchParams()
+  const navigate = useNavigate()
+  const uid = params.get('uid') ?? undefined
+  const token = params.get('token') ?? undefined
+  return (
+    <ForgotPasswordForm
+      uid={uid}                    // present -> confirm mode
+      token={token}
+      onBack={() => navigate('/')}
+      onSuccess={() => navigate('/')}
+    />
+  )
+}
+```
+
+An authenticated "change my password" screen:
+
+```tsx
+import { ChangePasswordForm } from 'drf-react-by-schema'
+// <ChangePasswordForm onSuccess={() => signOut()} />
+```
+
+## 3. Delivering the e-mail (the "e-mail infrastructure")
+
+Sending is handled by the **backend** — the React app only composes the reset
+link `{scheme}://{host}\{path}?uid=..&token=..`. Two levels of configuration:
+
+**Simple (no code):** configure Django e-mail settings and the reset link path;
+
+```python
+# settings.py / settings_local.py
+EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"  # or console in dev
+EMAIL_HOST = "smtp.your-provider.com"
+EMAIL_PORT = 587
+EMAIL_USE_TLS = True
+EMAIL_HOST_USER = "no-reply@your-domain"
+EMAIL_HOST_PASSWORD = "…"
+DEFAULT_FROM_EMAIL = "Your App <no-reply@your-domain>"
+
+PASSWORD_RESET_SCHEME = "https"
+PASSWORD_RESET_DOMAIN = "app.your-domain"   # avoids trusting request scheme behind a proxy
+PASSWORD_RESET_CONFIRM_PATH = "/esqueci-senha"  # your page
+```
+
+With that, `drf-react-by-schema-django` sends a plain-text message via Django's
+mail backend.
+
+**Customised (still small):** point `DRF_REACT_BY_SCHEMA['PASSWORD_RESET_CALLBACK']`
+at a callable `(request, user, uid, token)`. The library already mints
+`uid`/`token` before invoking it, so the change is a single function (branding,
+HTML, another channel, queueing…):
+
+```python
+# myapp/auth.py
+def send_reset_email(request, user, uid, token):
+    send_mail("Redefina sua senha", f"Link: https://app.suaorg.org/esqueci-senha?uid={uid}&token={token}", None, [user.email])
+```
+
+```python
+DRF_REACT_BY_SCHEMA = { ...
+    "PASSWORD_RESET_CALLBACK": "myapp.auth.send_reset_email",
+    "PASSWORD_RESET_CONFIRM_PATH": "/esqueci-senha",
+}
+```
+
+### Dev vs prod
+
+- **Dev**: `EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"` prints
+  the message to the terminal — great to test the flow without real SMTP.
+- **Prod (Ubuntu/VPS)**: point `EMAIL_BACKEND` to a real SMTP host (transactional
+  provider recommended), set `EMAIL_*`, fix `PASSWORD_RESET_DOMAIN`/`SCHEME` and
+  list the domain in `ALLOWED_HOSTS`. Keep real credentials out of the repo
+  (e.g. in a gitignored `settings_local.py` + a gitignored server guide).
+
+## 4. Real-world flow
+
+1. User taps "Esqueci minha senha" on the login → goes to the public page.
+2. Page calls `requestPasswordReset(email)` → backend mints `uid`/`token` and
+   fires the callback → e-mail with the link.
+3. User opens the link (`…?uid=..&token=..`) → the same page is in *confirm* mode
+   → `confirmPasswordReset({ uid, token, new_password })` sets the password.
+4. (Optional) sign-in and use `ChangePasswordForm` → `changePassword(...)`.
+
+Inviting a new user works the same way: create the account with an **unusable
+password** on the backend and fire `requestPasswordReset(email)` so the invited
+person receives a link to set their own password.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drf-react-by-schema",
-  "version": "0.28.26",
+  "version": "0.28.28",
   "description": "Components and Tools for building a React App having Django Rest Framework (DRF) as server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -132,6 +132,7 @@
     "not dead"
   ],
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ]
 }