fastapi-rtk 2.18.3__tar.gz → 2.19.1__tar.gz

{fastapi_rtk-2.18.3 → fastapi_rtk-2.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.18.3
+Version: 2.19.1
 Summary: A package that provides a set of tools to build a FastAPI application with a Class-Based CRUD API.
 Project-URL: Homepage, https://codeberg.org/datatactics/fastapi-rtk
 Project-URL: Issues, https://codeberg.org/datatactics/fastapi-rtk/issues

fastapi_rtk-2.19.1/fastapi_rtk/_version.py

@@ -0,0 +1 @@
+__version__ = "2.19.1"

{fastapi_rtk-2.18.3 → fastapi_rtk-2.19.1}/fastapi_rtk/agent_docs/adapters/agents-md/AGENTS.md

@@ -11,7 +11,10 @@ Detailed guidance ships with the package and was installed into this project:
 - `docs/agents/fastapi-rtk/backend.md`: models, `ModelRestApi`, hooks, filters, permissions,
   migrations, file uploads, bulk handlers, OAuth.
 - `docs/agents/fastapi-rtk/frontend.md`: `Provider`, `ApiProvider`, `useApi`, `NextGenDataGrid`,
-  `useForms`, dialogs, JsonForms, i18n.
+  `useForms`, dialogs, i18n.
+- `docs/agents/fastapi-rtk/jsonforms.md`: `JsonFormsWithCustomizer`, schema conditionals, per-control
+  props, custom inputs through the `customizer` slot. Open it only for nested or conditional
+  schemas; ordinary CRUD forms are covered by `frontend.md`.
 - `docs/agents/fastapi-rtk/legacy.md`: workarounds for older releases, keyed by symptom. Open it only
   when this project pins an older fastapi-rtk than the guide was verified against.
 

fastapi_rtk-2.19.1/fastapi_rtk/agent_docs/adapters/claude/skill.frontmatter

@@ -0,0 +1,2 @@
+name: rtk-developer
+description: Use when building, modifying or debugging anything in a fastapi-rtk project: Python models, ModelRestApi or BaseApi endpoints, pre/post hooks, permissions, migrations, file uploads, bulk operations, or the React side (Provider setup, ApiProvider, useApi, NextGenDataGrid, useForms, dialogs, JsonForms). Also on any mention of fastapi-rtk or "rtk backend" / "rtk frontend", and in any project importing from `fastapi_rtk` or the `fastapi-rtk` JS package, where it is preferred over plain FastAPI or React guidance.

{fastapi_rtk-2.18.3 → fastapi_rtk-2.19.1}/fastapi_rtk/agent_docs/guide/backend.md

@@ -2,31 +2,6 @@
 
 Deep reference for the Python side of fastapi-rtk: project setup, models, APIs, hooks, permissions, migrations, file uploads, bulk operations, async tasks. Load this when the user is working on Python code inside an `app/` folder or writing anything that touches `fastapi_rtk` imports.
 
-## Table of contents
-
-1. Install and project layout
-2. Configuration
-3. App initialization
-4. Models
-5. REST APIs: `ModelRestApi`
-6. REST APIs: `BaseApi` for custom endpoints
-7. Pre/post hooks
-8. Column configuration (list / show / add / edit / extra)
-9. Filters and custom filters
-10. Relationship filtering
-11. File and image uploads
-12. Bulk operations
-13. Background and deferred tasks
-14. Permissions, roles, and auth
-15. OAuth providers
-16. Migrations and user management CLI
-17. The `g` global context
-18. Multi-database / binds
-19. Extensions and other backends
-20. Production checklist
-
----
-
 ## 1. Install and project layout
 
 ```bash
@@ -608,7 +583,7 @@ Top-level shape: `dict[role_name, list[[api_glob, permission_glob]]]`. Both fiel
 
 ### The admin role sits outside `ROLES`
 
-`Setting.AUTH_ROLE_ADMIN` (`setting.py:342`, default `DEFAULT_ADMIN_ROLE = "Admin"` from `const.py:71`) names a role that is deliberately absent from `ROLES`, reachable as `g.admin_role` (`globals.py:141-147`). It holds **every permission of every registered Api**, and a `ROLES` edit cannot narrow that: `_associate_permission_with_api` (`fastapi_react_toolkit.py:506`) writes one `PermissionApi` row per `(permission, api)` taken from each Api's exposed routes plus one per `ROLES` entry, then `_associate_role_with_permission_api` (`:545`) grants the admin role every one of those rows except the ones whose permission name contains `|` (`:566-576`). The per-route row for the same permission is a different row and is never excluded, so piping a `ROLES` entry to hide something from the admin role is a no-op. The cleanup pass also exempts that role from disassociation by name, so an existing grant row survives every restart.
+`Setting.AUTH_ROLE_ADMIN` (`setting.py:368`, default `DEFAULT_ADMIN_ROLE = "Admin"` from `const.py:71`) names a role that is deliberately absent from `ROLES`, reachable as `g.admin_role` (`globals.py:141-147`). It holds **every permission of every registered Api**, and a `ROLES` edit cannot narrow that: `_associate_permission_with_api` (`fastapi_react_toolkit.py:506`) writes one `PermissionApi` row per `(permission, api)` taken from each Api's exposed routes plus one per `ROLES` entry, then `_associate_role_with_permission_api` (`:545`) grants the admin role every one of those rows except the ones whose permission name contains `|` (`:566-576`). The per-route row for the same permission is a different row and is never excluded, so piping a `ROLES` entry to hide something from the admin role is a no-op. The cleanup pass also exempts that role from disassociation by name, so an existing grant row survives every restart.
 
 Revoking a permission from it means setting `AUTH_ROLE_ADMIN` to `None` or to an existing `ROLES` role name (which strips the blanket grant entirely, since `if g.admin_role:` guards it), or checking inside the route.
 
@@ -696,10 +671,12 @@ OAUTH_PROVIDERS = [
 OAUTH_REDIRECT_URI = "http://localhost:6006"
 ```
 
-Top-level shape: `list[dict]`. Each dict's `"oauth_client"` is the `httpx_oauth` client; optional keys: `associate_by_email`, `redirect_url`, `redirect_url_factory`, `redirect_url_after_callback` (defaults to `OAUTH_REDIRECT_URI`), `on_before_register`, `on_after_register` (receives the freshly-created user), `on_before_login`. The setting key `OAUTH_CLIENTS` is the canonical name; `OAUTH_PROVIDERS` is accepted as an alternate (`setting.py:311`).
+Top-level shape: `list[dict]`. Each dict's `"oauth_client"` is the `httpx_oauth` client; optional keys: `backend` (`"cookie"` default, or `"jwt"`), `associate_by_email`, `redirect_url`, `redirect_url_factory`, `redirect_url_after_callback` (defaults to `OAUTH_REDIRECT_URI` on a cookie client), `on_before_register`, `on_after_register` (receives the freshly-created user), `on_before_login`. The setting key `OAUTH_CLIENTS` is the canonical name; `OAUTH_PROVIDERS` is accepted as an alternate (`setting.py:390-391`).
 
 The toolkit wires the login/callback routes; the frontend's OAuth sign-in hook kicks off the flow.
 
+A `"backend": "jwt"` client (for clients without a browser cookie store, such as React Native; web apps default to `cookie` and can opt in) answers the callback with `{"access_token", "token_type": "bearer"}` JSON instead of a cookie, so the client has to make the callback request itself: point `redirect_url` (or `redirect_url_factory`) at the URL the app receives the redirect on (on React Native the same URL goes to `createReactNativeAdapters({ oauthRedirectUrl })`, and `oauthSignin` then completes the sign-in itself), or call `oauthCallback("<name>", redirectQuery)` from `useAuth()` with that URL's query string, which forwards `code` and `state` to `GET /api/v1/auth/oauth-authorized/<name>` and stores the returned token. A JWT client rejects `redirect_url_after_callback` with a `ValueError` at startup and a popup login (`?popup=true`) with 400 `OAUTH_POPUP_NOT_SUPPORTED`, since both would drop the token.
+
 ## 16. Migrations and user management CLI
 
 ```bash

{fastapi_rtk-2.18.3 → fastapi_rtk-2.19.1}/fastapi_rtk/agent_docs/guide/frontend.md

@@ -2,36 +2,15 @@
 
 Deep reference for the React side of fastapi-rtk: Provider setup, ApiProvider, hooks (`useApi`, `useAuth`, `useForms`, …), `NextGenDataGrid`, dialogs, JsonForms, bulk actions, i18n. Load this when the user is working on React code inside an `src/` folder or anything that imports from `fastapi-rtk` (the JS package) or `@mantine/*`.
 
-## Table of contents
-
-1. Install and provider setup
-2. The `ApiProvider` context
-3. `useApi`: the CRUD hook
-4. `useCustomFetch`: non-CRUD endpoints
-5. `useInfo`: metadata-driven UIs
-6. Auth: `useAuth` and OAuth
-7. `NextGenDataGrid`: grids
-8. Forms: `useForms` and dialogs
-9. JsonForms for complex schemas
-10. Bulk actions
-11. Infinite scroll and lazy loading
-12. Language / i18n (`useLang`, `LanguageSelector`)
-13. Standard routes: `UserMenu`, `/users`, `/roles`, `/permissions`
-14. Platform adapters (React Native / Expo)
-15. Other notable exports
-16. Rules of thumb
-
----
-
 ## 1. Install and provider setup
 
-The toolkit expects Mantine as the UI kit.
+The toolkit expects Mantine as the UI kit. Use `Stack`, `Group`, `Grid`, `SimpleGrid` for layout and Mantine inputs for one-off forms; mixing in a second UI kit drifts the theme.
 
 ```bash
-pnpm add fastapi-rtk @mantine/core @mantine/dates @mantine/form @mantine/hooks
+pnpm add fastapi-rtk @mantine/core @mantine/dates @mantine/form @mantine/hooks dayjs react-router
 ```
 
-Peer deps: the four `@mantine/*` packages (`^9.0.0`) plus `react` / `react-dom` `^19`. Everything else (mantine-react-table, TanStack Query, zustand, i18next, JsonForms) is bundled inside `fastapi-rtk`. Mantine >= 9.4.1 requires fastapi-rtk >= 2.8.0; older releases loop forever in the grid's `useColumns` ("Maximum update depth exceeded").
+Peer deps: the four `@mantine/*` packages (`^9.0.0`), `react` / `react-dom` (`^19.2.3`), `dayjs` (`^1.11.0`) and `react-router` (`^7.5.3 || ^8.0.0`). Everything else (mantine-react-table, TanStack Query, zustand, i18next, JsonForms) is bundled inside `fastapi-rtk`. Mantine >= 9.4.1 requires fastapi-rtk >= 2.8.0; older releases loop forever in the grid's `useColumns` ("Maximum update depth exceeded").
 
 **Provider order is load-bearing.** Mantine must wrap the fastapi-rtk `Provider`, and the stylesheet order matters: Mantine CSS first, fastapi-rtk CSS last (RTK overrides).
 
@@ -79,7 +58,7 @@ Other `Provider` props: `langProps` (i18n extension, §12), `adapters` (§14), `
 
 Key props:
 
-- `resource_name`: **must match** the backend's `ModelRestApi.resource_name`. This is the contract; no magic fixes a mismatch.
+- `resource_name`: **must match** the backend's `ModelRestApi.resource_name`. If the backend says `items`, this says `items`: not `item`, not `/items`, not `Items`. This is the contract; no magic fixes a mismatch.
 - `initialQueryParams`: seeds pagination, sort, and filters. Use a small, stable object; don't reconstruct inline each render. Full `QueryParams` keys: `page`, `page_size`, `order_column`, `order_direction`, `filters` (list of `{col, opr, value}`), `opr_filters`, `global_filter`, `columns`, `with_count`.
 - `streaming`: switch the provider to infinite-scroll mode (§11).
 - Behavior knobs: `relation`, `fetchInfo`, `clearInfoOnRefetch`, `clearDataOnRefetch`, `refetchInfoBasedOnLang`, `refetchDataBasedOnLang`, `resetQueryParamsOnPathChange`, plus raw TanStack overrides `infoQueryProps` / `dataQueryProps` / `streamingQueryProps`. `withApiProvider` is the HOC variant.
@@ -165,7 +144,7 @@ await addEntry({ name: "x" }); // POST /{resource}
 await updateEntry(id, { name: "y" }); // PUT  /{resource}/{id}
 ```
 
-**Option B, use the TanStack Query namespace `rq`.** `fastapi-rtk` re-exports `@tanstack/react-query` as `rq` (`export * as rq from '@tanstack/react-query'` in `core/src/index.ts:83`; the sibling `mrt` namespace re-exports `mantine-react-table`, with long-form aliases `reactQuery` / `mantineReactTable`). Wrap a `useApi` action (or any toolkit-provided async function) in `rq.useQuery` / `rq.useMutation` so the result participates in the shared query cache (invalidation, refetch-on-focus, devtools). Never call raw `fetch` from the `queryFn` / `mutationFn`, since that re-introduces the exact problems `useCustomFetch` has.
+**Option B, use the TanStack Query namespace `rq`.** `fastapi-rtk` re-exports `@tanstack/react-query` as `rq` (`export * as rq from '@tanstack/react-query'` in `api/src/index.ts:38`, surfaced by `core/src/index.ts:94`; the sibling `mrt` namespace re-exports `mantine-react-table` from `core/src/index.ts:95`, with long-form aliases `reactQuery` / `mantineReactTable`). Wrap a `useApi` action (or any toolkit-provided async function) in `rq.useQuery` / `rq.useMutation` so the result participates in the shared query cache (invalidation, refetch-on-focus, devtools). Never call raw `fetch` from the `queryFn` / `mutationFn`, since that re-introduces the exact problems `useCustomFetch` has.
 
 ```jsx
 import { useApi, rq } from "fastapi-rtk";
@@ -234,6 +213,8 @@ user?.permissions; // string[] of API NAMES the user holds any grant on
 
 Gate routes/components on `user` and `user.roles`. The Provider keeps the session via cookie, so `user` is populated on every page load automatically.
 
+An OAuth provider configured with `"backend": "jwt"` is for clients without a browser cookie store (React Native on `createReactNativeAdapters`, whose bearer transport stores the token); web apps default to `cookie` providers, since a bearer transport on web keeps the token in `localStorage`, readable by any script on the origin. A web app can still opt into JWT: `adapters={{ authTransport: createBearerTransport(webAdapters.storage) }}`, the provider's `redirect_url` at an app route, and `oauthCallback("google", window.location.search)` on that route. On React Native: point the provider's `redirect_url` at the app's deep link (`myapp://oauth/google`), pass the same URL as `createReactNativeAdapters({ ..., oauthRedirectUrl })` (a string for every provider, or `{ google: "myapp://oauth/google", github: "..." }` keyed by provider name), and call `oauthSignin("google", false)` (no popup). A provider missing from that map fails before any browser opens (`error` is `Could not sign in`, `originalError` names the provider). iOS ends the session on any URL with the redirect URL's scheme (so `myapp://oauth/google` and `myapp://oauth/github` are not told apart there), Android on the first deep link starting with it; for an `https` redirect on iOS 17.4+ pass `oauthPreferUniversalLinks: true` (needs the Associated Domains entitlement) to match host and path instead. The RN opener runs `webBrowser.openAuthSessionAsync(loginUrl, oauthRedirectUrl, { preferUniversalLinks })` and hands the redirected URL back, and `oauthSignin` forwards its `code` / `state` to `auth/oauth-authorized/<provider>`, stores the returned token through `authTransport.persistLogin`, and refetches the user; a failure sets `error` to `Could not sign in`. An app that receives the redirect another way calls `oauthCallback("google", redirectQuery)` from `useAuth()` with that URL's query string.
+
 **`user.permissions` holds Api names, not permission names.** `auth/user` builds it as `select(Api.name)` joined through the user's roles (backend reference §14, "What the browser gets"), so `user.permissions.includes("ItemApi")` answers "has any grant on that Api" and nothing finer: `can_get` and `can_post` are indistinguishable there. It is the right gate for "may this user reach this resource at all", and it beats shipping a role list through the frontend config, since it follows the grants themselves and leaves no second list to keep in step. For per-verb detail read `useApi().info.permissions` (§5), which is that Api's `/_info` intersected with the user's grants.
 
 ## 7. `NextGenDataGrid`: grids
@@ -274,11 +255,11 @@ import { NextGenDataGrid } from "fastapi-rtk";
 Key props:
 
 - Columns are auto-generated from `/_info` + `list_columns`; there is NO `columns` prop. Per-column overrides go in `columnProps`: a dict keyed by column name whose values are partial MRT `ColumnDef` objects (or factories).
-- Row identity comes from the list response's top-level `ids` array, never from a column. `useProvideApi` maps the payload to `{...item, id: data.ids[index]}` (`api/esm/ApiProvider/hooks/useProvideApi.mjs:148-151`, plus the streaming twin at `:187-190`), and `getRowId` reads `getItemId` = `item.id_ ?? item.id`. The zipped `id` is spread last, so it also overrides a same-named column. So adding `"id"` to the backend `list_columns` gives the grid nothing it does not already have, and only surfaces a raw `id` column to the user; `list_obj_schema` is generated `with_id=False`, which is why the raw JSON lacks one and a backend test reading `row["id"]` fails. Such a test should read the response's `ids` array instead of widening the projection.
+- Row identity comes from the list response's top-level `ids` array, never from a column. `useProvideApi` maps the payload to `{...item, id: data.ids[index]}` (`api/src/ApiProvider/hooks/useProvideApi.ts:183-186`, plus the streaming twin at `:236-239`), and `getRowId` reads `getItemId` = `item.id_ ?? item.id`. The zipped `id` is spread last, so it also overrides a same-named column. So adding `"id"` to the backend `list_columns` gives the grid nothing it does not already have, and only surfaces a raw `id` column to the user; `list_obj_schema` is generated `with_id=False`, which is why the raw JSON lacks one and a backend test reading `row["id"]` fails. Such a test should read the response's `ids` array instead of widening the projection.
 - `quickFilters`: one-click filter presets rendered above the grid (`quickFiltersComponent` swaps the renderer).
 - `enableAdvancedFilters`: shows the structured filter builder.
 - `queryOnlyVisibleColumns`: perf, only requests visible columns from the backend.
-- `header` / `body` / `form`: per-column customization objects. `header` (keyed by column name): `filterComponent`, `filterProps`, `enableFilterModes` (per-operator component maps), `filterState` (external control), `filterSync`, `withLocalStorage` + `localStorageKey` (persist filter state), `defaultOpr`. `body` (keyed by column name): `truncate`, `component`, `separator` (multi-row cells), `highlight` / `highlightProps`, `tooltipProps`. `form` is keyed by `add` / `edit` / `view` / `delete`, each a JsonForms customizer applied to that auto-generated dialog plus dialog-level keys `initialView` / `dialogProps` (custom inputs: see §9.2).
+- `header` / `body` / `form`: per-column customization objects. `header` (keyed by column name): `filterComponent`, `filterProps`, `enableFilterModes` (per-operator component maps), `filterState` (external control), `filterSync`, `withLocalStorage` + `localStorageKey` (persist filter state), `defaultOpr`. `body` (keyed by column name): `truncate`, `component`, `separator` (multi-row cells), `highlight` / `highlightProps`, `tooltipProps`. `form` is keyed by `add` / `edit` / `view` / `delete`, each a JsonForms customizer applied to that auto-generated dialog plus dialog-level keys `initialView` / `dialogProps` (custom inputs: jsonforms.md §3).
 - `toolbar`: `customizer` hides (`null`) or replaces the built-in buttons (`toggleGlobalFilter`, `filter`, `refresh`, `add`, `download`, `showHideColumns`, `toggleDensePadding`, `toggleFullScreen`); `leftToolbar` / `centerToolbar` / `custom` add slots; the alert banner is customizable the same way.
 - Misc: `table` (raw MRT options, merged as overrides on top of the generated ones), `optimizations`, `memo` (`'filters' | 'cells'`), `withBorder`, `wrapperProps`, `fetchOnMount`, `hideToolbar` / `hideActions` / `hidePagination` / `hideError`, `textFilterSeparator`, and a `children` render prop.
 
@@ -339,165 +320,9 @@ Mounting these dialogs **outside** a `NextGenDataGrid` (e.g. wiring CRUD onto a
 
 ## 9. JsonForms for complex schemas
 
-When a form needs nested objects, arrays of subforms, or conditional sections, the built-in dialog form isn't enough; use `JsonFormsWithCustomizer`, which wraps `@jsonforms/react` with Mantine renderers. Input cells cover DateTime, Date, Time, File, Image, Boolean, Enum, Text, Number and full layout/control renderers.
-
-```jsx
-import { JsonFormsWithCustomizer } from "fastapi-rtk";
-
-<JsonFormsWithCustomizer
-  schema={jsonSchema}
-  uischema={uiSchema}
-  data={formData}
-  onChange={({ data, errors }) => setState({ data, errors })}
-/>;
-```
-
-For most CRUD forms you don't need this, since the default dialog plus `/_info` schema covers it. Reach for JsonForms when you're rendering user-defined schemas or deeply nested data. Full prop set: `schema`, `uischema`, `data`, `onChange`, `customizer`, `debounce`, `translations`, `hideWarnings`, `createTranslator`, `middleware`.
-
-**Schema-level `allOf` / `if`/`then`/`else` resolve live against the form data.** `JsonFormsWithCustomizer` installs a JsonForms middleware that resolves schema conditionals on every data change and renders the branch-applied schema: the matching branch's `properties` merge recursively over the base (narrowing one nested field keeps its siblings), scalar keywords win per key (a narrowed `enum` replaces the base list), `required` unions at each level, and the combinator is stripped. Conditionals resolve at the root and inside nested object properties: a nested `if` evaluates against that object's own data slice, while a root-level `if` sees the whole form data and may reference nested paths (and its `then`/`else` may narrow nested fields). Not resolved: `anyOf` / `oneOf` and conditionals inside array `items`. A supplied `uischema` is preserved; with none, the UI schema is regenerated from the resolved schema. Exported for programmatic use: `resolveConditionalSchema(schema, data, ajv)`, `createConditionalMiddleware(schema, { regenerateUischema })`, and `composeMiddleware(outer, inner)`; a caller-supplied `middleware` prop is composed to run underneath the conditional middleware.
-
-### 9.1 Per-control props via `options.props` and `options.ifProps`
-
-Every Mantine-themed control built on `useCommonProps` (the hook backing the toolkit's JsonForms renderers) spreads two extra props blocks from the uischema, in this order:
-
-1. `uischema.options.props`: static props passed straight to the underlying component.
-2. `uischema.options.ifProps`: dynamic props chosen by an `if/then/else` schema evaluated against the **whole form data** (not the control's own value).
-
-`ifProps` only works on control components. Both `then` and `else` are optional; the matching branch's `props` object is spread onto the control, the other is dropped.
-
-```js
-{
-  "type": "Control",
-  "scope": "#/properties/details",
-  "options": {
-    "ifProps": {
-      "if": {
-        "properties": { "category": { "const": "C" } },
-        "required": ["category"]
-      },
-      "then": { "props": { "required": true } },
-      "else": { "props": { "disabled": true } }
-    }
-  }
-}
-```
-
-**Conditional `required` indicator.** A schema-level `if` / `then.required` produces the conditional asterisk and validation on its own: the resolver merges `then.required` into the live `required` array (at the root or inside a nested object) and JsonForms derives the asterisk from it, updating as the trigger field changes. No `options.ifProps` layer is needed for `required`; keep `ifProps` for non-schema props (`disabled`, `placeholder`, a custom `component`). Rule effects cover only `SHOW` / `HIDE` / `ENABLE` / `DISABLE` (there is no `REQUIRE`), and a static `options.props.required: true` is read unconditionally.
-
-```js
-// schema (the uischema needs nothing on the dependent field)
-{
-  "type": "object",
-  "required": ["category"],
-  "properties": {
-    "category": { "type": "string", "enum": ["A", "B", "C"] },
-    "details":  { "type": "string" }
-  },
-  "if":   { "properties": { "category": { "const": "C" } }, "required": ["category"] },
-  "then": { "required": ["details"] }
-}
-```
-
-When a field is **unconditionally** required, lift it onto top-level `required: [...]`; JsonForms derives the asterisk from the schema, no `options.props.required` needed.
-
-**Pitfall: always pair `properties` with `required` inside `if`.** A JSON Schema `if` with only `{ "properties": { "x": { "const": "Y" } } }` matches when `x` is absent (an undefined value satisfies the property schema trivially), so `then.props.required: true` fires on first render before the user has touched the selector. Adding `"required": ["x"]` gates the match on "x is set AND equals Y".
-
-**`ifProps` conditions always evaluate against the form root, not the control's container.** `useIfProps` reads `core.data` from `useJsonForms()`, which is the whole form data, not the sub-slice the control sits in. A conditional control deep inside `#/properties/details/properties/subcategory` must reference siblings by their root path (`properties.details.properties.category`, not `properties.category`). Schema-level conditionals differ by placement: a root-level `allOf[].if` is also root-scoped, while a conditional inside a nested object property evaluates against that object's own data slice.
-
-Since js 2.0.1, `useIfProps` short-circuits on `null` root data (no values to inspect, no useful `then`), so an `if` never fires against effectively-empty data; matching a _property_ whose value is `null` still works (`if: { properties: { x: { const: null } }, required: ["x"] }`) because the root is still an object.
-
-### 9.2 Custom Input components via the `customizer` slot
+When a form needs nested objects, arrays of subforms, or conditional sections, the built-in dialog form isn't enough; use `JsonFormsWithCustomizer`, which wraps `@jsonforms/react` with Mantine renderers. For most CRUD forms you don't need it, since the default dialog plus the `/_info` schema covers them (§8).
 
-To add a custom input, you do **not** register a `withJsonFormsControlProps` renderer + a `rankWith` tester into a renderers array. `JsonFormsWithCustomizer` hardcodes `renderers={mantineRenderers}` and ships all the classic renderers, cells, and testers inside `fastapi-rtk`; you consume that machinery, you don't re-declare it. A custom input is a plain Mantine component bound to a schema field **by key**, through a `{ component, props }` customizer slot.
-
-**The slot, and the two props every slot factory receives:**
-
-```jsx
-const customizer = {
-  [key]: {
-    component, // ReactNode | ((args) => ReactNode)  : REPLACE the input
-    props, // object    | ((args) => object)      : MERGE props onto the built-in
-  },
-  __: { debounce: true }, // reserved: { debounce, debounceOptions: { delay, flushOnUnmount }, setNull }, not a slot
-};
-```
-
-`args` is always `{ componentProps, jsonFormsProps }`:
-
-- `componentProps` : the fully computed Mantine props the built-in would have used: `value`, `onChange` (already wired to JsonForms `handleChange(path, value)`), `onBlur`, `label`, `description`, `required`, `disabled`, `error`, plus `uischema.options.props` and `ifProps` (§9.1). Spread it onto a value-based Mantine input and the field is controlled and validated for free.
-- `jsonFormsProps` : the raw control props (`data`, `handleChange`, `path`, `schema`, `uischema`, `enabled`, `errors`, `visible`, `id`). Reach here when `componentProps` is not enough, or call `useCommonProps(jsonFormsProps)` (from `fastapi-rtk`) to have the library rebuild the `handleChange(path, value)` wrapper for you.
-
-`key` is a **renderer name** (`Text`, `Number`, `Integer`, `Boolean`, `Date`, `DateTime`, `Time`, `Enum`, `EnumArray`, `OneOfEnum`, `File`, `Image`, `Json`, `Object`, `Label`, `Table`, `Array`, `Array.Accordion`), a **JsonForms path / field name** (`status`, `details.category`), or `all`. Precedence when several match: `all` < renderer-name < path (slots deep-merge in that order, most specific wins). Since 2.8.0 every structural wrapper is addressable too: `Table.Thead` / `Table.Tbody` / `Table.Empty`, `Table.Header.*` (`Tr`, `Actions`, `Validation`, `Toolbar`, `Wrapper`, `Flex`), `Table.Row.*` (`Tr`, `Td`, `Actions`, `Grid`, `Up`, `Down`, `Remove`), per-row / per-cell addressing (`Table.Row.{index}`, `Table.Row.{index}.{subPath}`, `Table.Row.{subPath}`), `Array.Stack` / `Array.Items` / `Array.Empty` / `Array.Header.*` / `Array.Item.*` / `Array.DeleteDialog`, `File.Box` / `Image.Box`, and `Label.{text}`. (Collision escape: when a real field is named `all`, the wildcard moves to the exported `specialKey.all`.)
-
-**Write the component** as a plain Mantine component. For a blob field, `JSON.parse` on read and `JSON.stringify` on write; keep spreading `{...componentProps}` so the label / description / error wrapper still renders:
-
-```jsx
-import { TagsInput } from "@mantine/core";
-
-function TagsField({ componentProps }) {
-  const value = componentProps.value ? JSON.parse(componentProps.value) : [];
-  return (
-    <TagsInput
-      {...componentProps}
-      value={value}
-      onChange={(next) => componentProps.onChange(JSON.stringify(next))}
-    />
-  );
-}
-```
-
-**Register it by key** (no tester, no `{ tester, renderer }`, no `renderers` array). Three equivalent entry points:
-
-1. **On a grid's add/edit dialogs** (the common CRUD path) via `NextGenDataGrid`'s `form` prop. `form.add` / `form.edit` are customizer trees keyed by field name; the grid forwards them to its internal `<AddDialog jsonForms>` / `<EditDialog jsonForms>`. Dialog-level keys (`initialView`, `dialogProps`) sit next to the field keys.
-
-   ```jsx
-   <NextGenDataGrid
-     form={{
-       add: {
-         tags: {
-           component: ({ componentProps }) => (
-             <TagsField componentProps={componentProps} />
-           ),
-         },
-       },
-       edit: {
-         tags: {
-           component: ({ componentProps }) => (
-             <TagsField componentProps={componentProps} />
-           ),
-         },
-       },
-     }}
-   />
-   ```
-
-2. **On the standalone dialogs**: `<AddDialog jsonForms={customizer} />` / `<EditDialog jsonForms={customizer} />`.
-
-3. **On a raw element** for a bespoke (non-CRUD) form: `<JsonFormsWithCustomizer schema={schema} uischema={uischema} data={data} onChange={onChange} customizer={customizer} />`.
-
-**`component` swaps the whole input; `props` only tweaks the built-in.** Use `props` to nudge every control of a type, or to derive a prop from the field's own state:
-
-```jsx
-const customizer = {
-  Enum: { props: { searchable: true } }, // every Enum control
-  all: {
-    props: ({ componentProps }) => ({ withAsterisk: componentProps.required }),
-  },
-};
-```
-
-A `props` value of `null` explicitly unsets that prop on the built-in; `undefined` is a no-op that leaves the prior value. Function-valued slots receive the fully-merged default props as `componentProps` (since 2.8.0), including a structural slot's computed attributes and children, so an override can wrap or reuse exactly what the built-in would have rendered.
-
-**Pitfall - a hook-using custom input must be returned as an element, not passed as a component type.** The slot value runs through `parseFromValuesOrFunc`, which _calls_ a function slot inline (`slot({ componentProps, jsonFormsProps })`). Passing the component type directly (`component: MyInput`) therefore executes `MyInput`'s hooks inside the built-in renderer's render pass, a rule-of-hooks violation. Always wrap it in an arrow that returns an element so React mounts it normally:
-
-```jsx
-const customizer = {
-  color: { component: (args) => <ColorField {...args} /> }, // arrow returns an element -> hooks safe
-  // NOT: { color: { component: ColorField } }                // called inline -> hooks run in the wrong pass
-};
-```
-
-**Escape hatch - a genuinely new control type** not covered by any built-in renderer: pass a standard `@jsonforms` `renderers` array (your `withJsonFormsControlProps` component + a `rankWith` tester) through the dialog's `jsonFormsProps`, which spreads onto the inner `<JsonForms>` (`<AddDialog jsonFormsProps={{ renderers: [...myRenderers] }} />`). Include the built-in `mantineRenderers` in that array or you lose every default input. TypeScript nit: `jsonFormsProps` is typed `Partial<JsonFormsWithCustomizerProps>`, which omits `renderers`; the runtime spread honors it anyway, so cast to pass it. The renderer-building kit is exported for this path: `mantineRenderers`, `mantineCells`, and the per-type prop hooks (`useContextProps`, `useTextProps`, `useDateProps`, `useFileProps`, `useNumberProps`, ...). Prefer the `customizer` for anything that maps onto an existing input: it keeps the Mantine theme, i18n, debounce, and error wiring.
+**Read `jsonforms.md` for the whole subsystem**: schema-level `allOf` / `if`/`then`/`else` resolution, per-control props via `options.props` and `options.ifProps`, and custom inputs through the `customizer` slot.
 
 ## 10. Bulk actions
 
@@ -648,15 +473,5 @@ Cookie login is on by default on the backend; the JWT endpoint exists only when
 - Headless fetcher layer for code outside any provider: `buildRequest`, `getItems` / `getItem` / `createItem` / `updateItem` / `deleteItem` / `getInfo`, `formCreateItem` / `formUpdateItem`, `uploadItems` / `downloadItems`, `postBulk`, plus `useAdapters` / `webAdapters`.
 - Legacy `DataGrid` is still exported alongside `NextGenDataGrid`; standalone `ActionIcons` (`Actions`, `Add`, `Delete`, `Download`, `Edit`, `Refresh`, `Upload`, `View`) and `Filter` compose custom layouts.
 - Utilities: `deepMerge`, `parseFromValuesOrFunc`, `createSafeContext`, `getItemId`, `urlJoin`, `Memoizer`, `FastAPIRTKLogger`; hooks `useActionIcon`, `useSyncValues`, `useTrueOnce`.
-- Router integration targets `react-router` v7.
+- Router integration targets `react-router` v7 or v8 (peer range `^7.5.3 || ^8.0.0`).
 - Streaming loads render a progress bar instead of a blocking overlay (2.8.0+); toolbar buttons auto-hide when the backend disables the matching feature.
-
-## 16. Rules of thumb
-
-1. **Never `fetch` a standard resource.** Use `useApi`. Direct fetch calls miss session refresh, error handling, and `/_info`-driven UI hydration.
-2. **Respect the provider hierarchy.** If `useApi` throws "not inside an ApiProvider", wrap the component; don't switch to `useCustomFetch` as a workaround.
-3. **`resource_name` is the contract.** If the backend says `items`, the frontend says `items`. Not `item`, not `/items`, not `Items`.
-4. **Configure the grid; don't wrap it.** The `header` / `body` / `form` props cover almost all customization. Wrapping breaks selection/filter sync.
-5. **Let `/_info` drive UI.** When the backend adds a column or changes permissions, a well-built frontend picks it up for free. Hardcoding column lists is a per-release maintenance tax.
-6. **Mantine layout primitives only.** Use `Stack`, `Group`, `Grid`, `SimpleGrid` for layout, Mantine inputs for one-off forms. Mixing Mantine with another UI kit leads to theme drift.
-7. **CSS import order: Mantine → fastapi-rtk.** Otherwise grid/form styles render oddly because fastapi-rtk CSS depends on Mantine tokens.

fastapi_rtk-2.19.1/fastapi_rtk/agent_docs/guide/jsonforms.md

@@ -0,0 +1,165 @@
+# JsonForms reference (fastapi-rtk React)
+
+Deep reference for `JsonFormsWithCustomizer`: schema-level conditionals, per-control props, and custom inputs through the `customizer` slot. Load this only when a form needs nested objects, arrays of subforms, conditional sections, or a custom input; the default dialog form plus the `/_info` schema covers ordinary CRUD, which is frontend.md §8.
+
+## 1. When to reach for it
+
+When a form needs nested objects, arrays of subforms, or conditional sections, the built-in dialog form isn't enough; use `JsonFormsWithCustomizer`, which wraps `@jsonforms/react` with Mantine renderers. Input cells cover DateTime, Date, Time, File, Image, Boolean, Enum, Text, Number and full layout/control renderers.
+
+```jsx
+import { JsonFormsWithCustomizer } from "fastapi-rtk";
+
+<JsonFormsWithCustomizer
+  schema={jsonSchema}
+  uischema={uiSchema}
+  data={formData}
+  onChange={({ data, errors }) => setState({ data, errors })}
+/>;
+```
+
+For most CRUD forms you don't need this, since the default dialog plus `/_info` schema covers it. Reach for JsonForms when you're rendering user-defined schemas or deeply nested data. Full prop set: `schema`, `uischema`, `data`, `onChange`, `customizer`, `debounce`, `translations`, `hideWarnings`, `createTranslator`, `middleware`.
+
+**Schema-level `allOf` / `if`/`then`/`else` resolve live against the form data.** `JsonFormsWithCustomizer` installs a JsonForms middleware that resolves schema conditionals on every data change and renders the branch-applied schema: the matching branch's `properties` merge recursively over the base (narrowing one nested field keeps its siblings), scalar keywords win per key (a narrowed `enum` replaces the base list), `required` unions at each level, and the combinator is stripped. Conditionals resolve at the root and inside nested object properties: a nested `if` evaluates against that object's own data slice, while a root-level `if` sees the whole form data and may reference nested paths (and its `then`/`else` may narrow nested fields). Not resolved: `anyOf` / `oneOf` and conditionals inside array `items`. A supplied `uischema` is preserved; with none, the UI schema is regenerated from the resolved schema. Exported for programmatic use: `resolveConditionalSchema(schema, data, ajv)`, `createConditionalMiddleware(schema, { regenerateUischema })`, and `composeMiddleware(outer, inner)`; a caller-supplied `middleware` prop is composed to run underneath the conditional middleware.
+
+## 2. Per-control props via `options.props` and `options.ifProps`
+
+Every Mantine-themed control built on `useCommonProps` (the hook backing the toolkit's JsonForms renderers) spreads two extra props blocks from the uischema, in this order:
+
+1. `uischema.options.props`: static props passed straight to the underlying component.
+2. `uischema.options.ifProps`: dynamic props chosen by an `if/then/else` schema evaluated against the **whole form data** (not the control's own value).
+
+`ifProps` only works on control components. Both `then` and `else` are optional; the matching branch's `props` object is spread onto the control, the other is dropped.
+
+```js
+{
+  "type": "Control",
+  "scope": "#/properties/details",
+  "options": {
+    "ifProps": {
+      "if": {
+        "properties": { "category": { "const": "C" } },
+        "required": ["category"]
+      },
+      "then": { "props": { "required": true } },
+      "else": { "props": { "disabled": true } }
+    }
+  }
+}
+```
+
+**Conditional `required` indicator.** A schema-level `if` / `then.required` produces the conditional asterisk and validation on its own: the resolver merges `then.required` into the live `required` array (at the root or inside a nested object) and JsonForms derives the asterisk from it, updating as the trigger field changes. No `options.ifProps` layer is needed for `required`; keep `ifProps` for non-schema props (`disabled`, `placeholder`, a custom `component`). Rule effects cover only `SHOW` / `HIDE` / `ENABLE` / `DISABLE` (there is no `REQUIRE`), and a static `options.props.required: true` is read unconditionally.
+
+```js
+// schema (the uischema needs nothing on the dependent field)
+{
+  "type": "object",
+  "required": ["category"],
+  "properties": {
+    "category": { "type": "string", "enum": ["A", "B", "C"] },
+    "details":  { "type": "string" }
+  },
+  "if":   { "properties": { "category": { "const": "C" } }, "required": ["category"] },
+  "then": { "required": ["details"] }
+}
+```
+
+When a field is **unconditionally** required, lift it onto top-level `required: [...]`; JsonForms derives the asterisk from the schema, no `options.props.required` needed.
+
+**Pitfall: always pair `properties` with `required` inside `if`.** A JSON Schema `if` with only `{ "properties": { "x": { "const": "Y" } } }` matches when `x` is absent (an undefined value satisfies the property schema trivially), so `then.props.required: true` fires on first render before the user has touched the selector. Adding `"required": ["x"]` gates the match on "x is set AND equals Y".
+
+**`ifProps` conditions always evaluate against the form root, not the control's container.** `useIfProps` reads `core.data` from `useJsonForms()`, which is the whole form data, not the sub-slice the control sits in. A conditional control deep inside `#/properties/details/properties/subcategory` must reference siblings by their root path (`properties.details.properties.category`, not `properties.category`). Schema-level conditionals differ by placement: a root-level `allOf[].if` is also root-scoped, while a conditional inside a nested object property evaluates against that object's own data slice.
+
+Since js 2.0.1, `useIfProps` short-circuits on `null` root data (no values to inspect, no useful `then`), so an `if` never fires against effectively-empty data; matching a _property_ whose value is `null` still works (`if: { properties: { x: { const: null } }, required: ["x"] }`) because the root is still an object.
+
+## 3. Custom Input components via the `customizer` slot
+
+To add a custom input, you do **not** register a `withJsonFormsControlProps` renderer + a `rankWith` tester into a renderers array. `JsonFormsWithCustomizer` hardcodes `renderers={mantineRenderers}` and ships all the classic renderers, cells, and testers inside `fastapi-rtk`; you consume that machinery, you don't re-declare it. A custom input is a plain Mantine component bound to a schema field **by key**, through a `{ component, props }` customizer slot.
+
+**The slot, and the two props every slot factory receives:**
+
+```jsx
+const customizer = {
+  [key]: {
+    component, // ReactNode | ((args) => ReactNode)  : REPLACE the input
+    props, // object    | ((args) => object)      : MERGE props onto the built-in
+  },
+  __: { debounce: true }, // reserved: { debounce, debounceOptions: { delay, flushOnUnmount }, setNull }, not a slot
+};
+```
+
+`args` is always `{ componentProps, jsonFormsProps }`:
+
+- `componentProps` : the fully computed Mantine props the built-in would have used: `value`, `onChange` (already wired to JsonForms `handleChange(path, value)`), `onBlur`, `label`, `description`, `required`, `disabled`, `error`, plus `uischema.options.props` and `ifProps` (§2). Spread it onto a value-based Mantine input and the field is controlled and validated for free.
+- `jsonFormsProps` : the raw control props (`data`, `handleChange`, `path`, `schema`, `uischema`, `enabled`, `errors`, `visible`, `id`). Reach here when `componentProps` is not enough, or call `useCommonProps(jsonFormsProps)` (from `fastapi-rtk`) to have the library rebuild the `handleChange(path, value)` wrapper for you.
+
+`key` is a **renderer name** (`Text`, `Number`, `Integer`, `Boolean`, `Date`, `DateTime`, `Time`, `Enum`, `EnumArray`, `OneOfEnum`, `File`, `Image`, `Json`, `Object`, `Label`, `Table`, `Array`, `Array.Accordion`), a **JsonForms path / field name** (`status`, `details.category`), or `all`. Precedence when several match: `all` < renderer-name < path (slots deep-merge in that order, most specific wins). Since 2.8.0 every structural wrapper is addressable too: `Table.Thead` / `Table.Tbody` / `Table.Empty`, `Table.Header.*` (`Tr`, `Actions`, `Validation`, `Toolbar`, `Wrapper`, `Flex`), `Table.Row.*` (`Tr`, `Td`, `Actions`, `Grid`, `Up`, `Down`, `Remove`), per-row / per-cell addressing (`Table.Row.{index}`, `Table.Row.{index}.{subPath}`, `Table.Row.{subPath}`), `Array.Stack` / `Array.Items` / `Array.Empty` / `Array.Header.*` / `Array.Item.*` / `Array.DeleteDialog`, `File.Box` / `Image.Box`, and `Label.{text}`. (Collision escape: when a real field is named `all`, the wildcard moves to the exported `specialKey.all`.)
+
+**Write the component** as a plain Mantine component. For a blob field, `JSON.parse` on read and `JSON.stringify` on write; keep spreading `{...componentProps}` so the label / description / error wrapper still renders:
+
+```jsx
+import { TagsInput } from "@mantine/core";
+
+function TagsField({ componentProps }) {
+  const value = componentProps.value ? JSON.parse(componentProps.value) : [];
+  return (
+    <TagsInput
+      {...componentProps}
+      value={value}
+      onChange={(next) => componentProps.onChange(JSON.stringify(next))}
+    />
+  );
+}
+```
+
+**Register it by key** (no tester, no `{ tester, renderer }`, no `renderers` array). Three equivalent entry points:
+
+1. **On a grid's add/edit dialogs** (the common CRUD path) via `NextGenDataGrid`'s `form` prop. `form.add` / `form.edit` are customizer trees keyed by field name; the grid forwards them to its internal `<AddDialog jsonForms>` / `<EditDialog jsonForms>`. Dialog-level keys (`initialView`, `dialogProps`) sit next to the field keys.
+
+   ```jsx
+   <NextGenDataGrid
+     form={{
+       add: {
+         tags: {
+           component: ({ componentProps }) => (
+             <TagsField componentProps={componentProps} />
+           ),
+         },
+       },
+       edit: {
+         tags: {
+           component: ({ componentProps }) => (
+             <TagsField componentProps={componentProps} />
+           ),
+         },
+       },
+     }}
+   />
+   ```
+
+2. **On the standalone dialogs**: `<AddDialog jsonForms={customizer} />` / `<EditDialog jsonForms={customizer} />`.
+
+3. **On a raw element** for a bespoke (non-CRUD) form: `<JsonFormsWithCustomizer schema={schema} uischema={uischema} data={data} onChange={onChange} customizer={customizer} />`.
+
+**`component` swaps the whole input; `props` only tweaks the built-in.** Use `props` to nudge every control of a type, or to derive a prop from the field's own state:
+
+```jsx
+const customizer = {
+  Enum: { props: { searchable: true } }, // every Enum control
+  all: {
+    props: ({ componentProps }) => ({ withAsterisk: componentProps.required }),
+  },
+};
+```
+
+A `props` value of `null` explicitly unsets that prop on the built-in; `undefined` is a no-op that leaves the prior value. Function-valued slots receive the fully-merged default props as `componentProps` (since 2.8.0), including a structural slot's computed attributes and children, so an override can wrap or reuse exactly what the built-in would have rendered.
+
+**Pitfall - a hook-using custom input must be returned as an element, not passed as a component type.** The slot value runs through `parseFromValuesOrFunc`, which _calls_ a function slot inline (`slot({ componentProps, jsonFormsProps })`). Passing the component type directly (`component: MyInput`) therefore executes `MyInput`'s hooks inside the built-in renderer's render pass, a rule-of-hooks violation. Always wrap it in an arrow that returns an element so React mounts it normally:
+
+```jsx
+const customizer = {
+  color: { component: (args) => <ColorField {...args} /> }, // arrow returns an element -> hooks safe
+  // NOT: { color: { component: ColorField } }                // called inline -> hooks run in the wrong pass
+};
+```
+
+**Escape hatch - a genuinely new control type** not covered by any built-in renderer: pass a standard `@jsonforms` `renderers` array (your `withJsonFormsControlProps` component + a `rankWith` tester) through the dialog's `jsonFormsProps`, which spreads onto the inner `<JsonForms>` (`<AddDialog jsonFormsProps={{ renderers: [...myRenderers] }} />`). Include the built-in `mantineRenderers` in that array or you lose every default input. TypeScript nit: `jsonFormsProps` is typed `Partial<JsonFormsWithCustomizerProps>`, which omits `renderers`; the runtime spread honors it anyway, so cast to pass it. The renderer-building kit is exported for this path: `mantineRenderers`, `mantineCells`, and the per-type prop hooks (`useContextProps`, `useTextProps`, `useDateProps`, `useFileProps`, `useNumberProps`, ...). Prefer the `customizer` for anything that maps onto an existing input: it keeps the Mantine theme, i18n, debounce, and error wiring.

{fastapi_rtk-2.18.3 → fastapi_rtk-2.19.1}/fastapi_rtk/agent_docs/guide/legacy.md

@@ -18,11 +18,11 @@ Before 2.0.1, `useIfProps` early-returned only on `data === undefined`. If the r
 }
 ```
 
-Fixed in 2.0.1 (`useIfProps` short-circuits on `null` root data); the explicit `type: "object"` gate is unnecessary on current versions (frontend.md §9.1).
+Fixed in 2.0.1 (`useIfProps` short-circuits on `null` root data); the explicit `type: "object"` gate is unnecessary on current versions (jsonforms.md §2).
 
 ## Schema-level `allOf` / `if`/`then`/`else` hangs the form (js, fastapi-rtk <= 2.9.4)
 
-Through 2.9.4, `JsonFormsWithCustomizer` passed schema combinators straight to JsonForms. With no `uischema`, `Generate.uiSchema` treats an object schema carrying a combinator as a leaf and emits a `Control` scoped to the object itself; the object control then regenerates the same UI schema for its detail view and recurses until the render loop hangs. Applies to a combinator at the root or on any nested object property. Workaround on those versions: pass an explicit `uischema` whose controls target the leaf properties (never a bare control scoped to the combinator-carrying object), or resolve the conditionals out of the schema before passing it in. Later releases resolve schema conditionals automatically via middleware (frontend.md §9).
+Through 2.9.4, `JsonFormsWithCustomizer` passed schema combinators straight to JsonForms. With no `uischema`, `Generate.uiSchema` treats an object schema carrying a combinator as a leaf and emits a `Control` scoped to the object itself; the object control then regenerates the same UI schema for its detail view and recurses until the render loop hangs. Applies to a combinator at the root or on any nested object property. Workaround on those versions: pass an explicit `uischema` whose controls target the leaf properties (never a bare control scoped to the combinator-carrying object), or resolve the conditionals out of the schema before passing it in. Later releases resolve schema conditionals automatically via middleware (jsonforms.md §1).
 
 ## Conditional `required` asterisk needs a two-layer `ifProps` recipe (js, fastapi-rtk <= 2.9.4)
 
@@ -42,4 +42,4 @@ Without the schema resolver, a schema-level `if` / `then.required` only gates AJ
 }
 ```
 
-Later releases derive the conditional asterisk from the schema alone, including inside nested objects (frontend.md §9.1).
+Later releases derive the conditional asterisk from the schema alone, including inside nested objects (jsonforms.md §2).

fastapi_rtk-2.19.1/fastapi_rtk/agent_docs/guide/overview.md

@@ -0,0 +1,50 @@
+# rtk-developer
+
+The FastAPI React Toolkit is ONE framework with two halves designed to fit together. Treat it as a single system, not two independent stacks.
+
+## The core concept
+
+The value of fastapi-rtk is convention. Define a SQLAlchemy model, register a `ModelRestApi` with `resource_name="items"`, and the backend exposes full CRUD at `/api/v1/items`. Wrap a component in `<ApiProvider resource_name="items">`, call `useApi()`, and you get `data`, `loading`, `addEntry`, `updateEntry`, `deleteEntry` with no fetch code and no manual types.
+
+**The `resource_name` string is the contract, and a typo breaks it silently.**
+
+So most features have a backend half and a frontend half that must line up. Work out which side(s) a request touches before writing code:
+
+| Feature             | Backend piece                                                    | Frontend piece                                                                           |
+| ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| CRUD on a model     | `ModelRestApi`                                                   | `ApiProvider` + `useApi`                                                                 |
+| List/detail views   | `list_columns`, `show_columns`                                   | `NextGenDataGrid` auto-columns + `columnProps`                                           |
+| Add/edit forms      | `add_columns`, `edit_columns`, hooks                             | `useForms(kind)` → `setItem` + `setOpened`, `AddDialog`/`EditDialog`                     |
+| Filtering           | `base_filters`, `FilterXxx`                                      | `initialQueryParams`, `quickFilters` (`{name, value:[{col,opr,value}]}`)                 |
+| File / image upload | `FileColumn`, `ImageColumn`, file manager                        | form auto-detects and renders file input                                                 |
+| Bulk actions        | method `bulk_<handler>(body, query, session)` on the Api class   | `useBulkActions` → `dispatchBulkActions(handler, ids)`                                   |
+| Permissions         | `ROLES` config + `@protect`                                      | `useAuth`, route guards                                                                  |
+| Custom endpoint     | `BaseApi` + `@expose`                                            | `rq` wrapper / `useCustomFetch` (last resort)                                            |
+| Platform adapters   | auth endpoints (cookie `auth/login`; JWT needs `AUTH_LOGIN_JWT`) | `adapters` prop on `Provider` (web defaults; RN via `fastapi-rtk/react-native-adapters`) |
+
+## Cross-cutting rules
+
+1. **Never bypass the toolkit.** Backend: prefer `ModelRestApi` over hand-rolled routes and add behavior through `pre_*` / `post_*` hooks. `@expose` is for an endpoint whose logic is NOT CRUD on a model (an RPC-style call, an external-API proxy, a job with no model row); "do something extra when a row is added, edited or fetched" is a hook, not a new route. Frontend: never `fetch` or `axios` a standard resource, and render resource rows with `NextGenDataGrid` configured through its props, not a hand-built `<Table>` or a `.map`. Dropping to raw APIs suits genuinely custom behavior; doing it out of habit fights the framework. An ad-hoc route registered directly on the FastAPI app needs `tags=["<RegisteredApiClass>"]` to appear in `export api-docs` output.
+2. **Align `resource_name` exactly** on both sides.
+3. **Expose a different column projection per operation** rather than one model-wide set, and let the grid render from `/_info`. Do not overfetch on the model when the view already filters.
+4. **Async-first.** Async drivers throughout, hooks are `async def`, and a sync portion mixed into async gets wrapped in `smart_run()`.
+5. **Relationship filtering happens on the backend**, never by filtering dropdown options in JS. The form picks the backend's answer up automatically.
+6. **Permissions are declarative**, configured rather than checked inline. Keep ad-hoc role checks out of business logic.
+
+## Which reference to read
+
+Keep this file in context and load a reference only for the detail.
+
+| Work                                                                        | Read                                   |
+| --------------------------------------------------------------------------- | -------------------------------------- |
+| Models, APIs, hooks, migrations, users, filters, file managers, bulk, OAuth | `docs/agents/fastapi-rtk/backend.md`   |
+| Provider setup, ApiProvider, hooks, DataGrid, forms, dialogs, i18n          | `docs/agents/fastapi-rtk/frontend.md`  |
+| Nested or conditional schemas, a custom form input, the `customizer` slot   | `docs/agents/fastapi-rtk/jsonforms.md` |
+| Full-stack                                                                  | the table above, then both             |
+| Docs look wrong AND the project pins an OLDER release than the stamp below  | `docs/agents/fastapi-rtk/legacy.md`    |
+
+`legacy.md` is keyed by symptom and never loads on a current release.
+
+Bootstrapping a new project starts with `fastapi-rtk create-app`, which scaffolds the backend from the fastapi-rtk-skeleton template; the backend reference covers the pieces it produces. In a pre-existing project, read a few of its real files (`app/apis.py`, `src/main.jsx`) rather than assuming a fresh layout, since the toolkit is flexible.
+
+**Staleness rule.** The three references were verified claim by claim against fastapi-rtk source at v2.9.0 (2026-07-09). At v2.18.3 (2026-09-16) a narrower re-check re-resolved every `file:line` citation, every config key, every backend symbol named here, the published JS export list and the declared peer dependencies, and fixed the seven that had drifted; prose claims outside those classes still date from v2.9.0. On a NEWER release, treat any claim contradicting observed behavior as possibly stale: read the installed package's source before fighting the code, and fix the reference and its version stamp in the same session when it drifted.