drf-react-by-schema 0.28.25 → 0.28.27

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.25",
+  "version": "0.28.27",
   "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"
   ]
 }