feat(spa): custom-widget plugin protocol (#625) + 1.8.0 (#650)

Closes #625. The cross-repo chain is now complete:

| Repo | Released | Notes |
|---|---|---|
| django-admin-rest-api 1.3.0 | PyPI | emits `widget: "custom"` + `widget_class` |
| django-admin-react 1.8.0   | this PR | dispatches to consumer-registered widgets |

## Plugin protocol

A consumer registers a vanilla mount fn for any `formfield_overrides`
widget the SPA doesn't natively render:

```html
<!-- before the SPA bundle runs (custom change_form_template, a
     shared base template, or any <script> ahead of the SPA's bundle): -->
<script>
  window.darFieldWidgets = window.darFieldWidgets ?? {};
  window.darFieldWidgets['mypkg.widgets.MarkdownEditor'] = {
    mount(container, props) {
      // Render whatever — vanilla JS, jQuery, mini-React, etc.
      // `props.value`     — current draft (live via getter)
      // `props.onChange`  — emit a new value
      // `props.error`     — per-field validation errors
      // `props.widgetClass` — the dotted class path
      // return optional cleanup fn called on SPA unmount.
    },
  };
</script>
```

Why vanilla JS rather than React: the SPA's React is bundled +
tree-shaken; exposing it on a global so consumer React modules
could use it is fragile across bundle rebuilds. A vanilla
mount-fn contract keeps the consumer's widget framework-agnostic
(jQuery, Stimulus, mini-React, vanilla DOM all work). The SPA
wraps the mount fn in a thin React effect with the latestProps
ref pattern so value / onChange / error reach the widget without
re-mounting on every render.

## Two registration paths

- **No-build path:** assign to ``window.darFieldWidgets[<class>]``
  in a regular ``<script>``. Works with no npm publish, no
  consumer-side bundler.
- **Module path:** import ``registerFieldWidget`` from ``@dar/ui``
  in a consumer's own SPA build (when they ship their own React
  module sideloaded into the page). Module-level registrations
  win over the window global on conflict.

## Fallback when no registration matches

The SPA renders a default text input + an amber note
(``Custom widget <class> is not registered; using the default text
input.``). The operator can still complete the form; the gap is
explicit and recoverable, not a silent break. Consumers can keep
affected models on the legacy admin via ``LEGACY_ADMIN_URL_PREFIX``
deeplink until they wire the widget.

## What's new

- ``frontend/packages/ui/src/custom-widget.ts`` — the registry
  module + ``registerFieldWidget`` / ``lookupFieldWidget`` exports.
- ``frontend/packages/form/src/CustomWidgetMount.tsx`` — React
  adapter wrapping the consumer's mount fn (latestProps ref so
  re-renders forward value/onChange/error without re-mounting).
- ``FieldInput.tsx`` — new render branch for ``widget === 'custom'``
  with the registered-widget path and the missing-registration
  fallback.
- ``contract.ts`` — ``WidgetHint`` extends ``'custom'``;
  ``FieldDescriptor`` gains ``widget_class?: string``.
- README — new "Custom widgets (formfield_overrides +
  registerFieldWidget)" section with worked example, props table,
  and fallback semantics.
- i18n catalogs (es / pt / fr) — translated the two new fallback
  strings.

## Dep bump

``django-admin-rest-api ^1.2.0`` → ``^1.3.0``. The new
``widget_class`` field + ``"custom"`` widget value land in 1.3.0;
older API versions will never trigger the new SPA branch (they
just emit no hint).

## Verification

- ``pnpm test`` — **222 / 222 ✓** (up from 216; +6 new in
  ``custom-widget.test.ts``)
- ``poetry run pytest -q`` — **64 / 64 ✓** on Django 4.2.30
- ``pnpm -r typecheck`` ✓
- ``pnpm lint`` ✓
- ``pnpm -w build`` ✓

## Minor bump rationale

``1.7.0`` → ``1.8.0``. New user-visible capability (consumer-
supplied custom widgets render in the SPA) per SemVer's "additive
features" guideline. Matches the symmetric ``1.3.0`` minor on
``django-admin-rest-api``.

Closes #625.

Co-authored-by: Martin Castro Laminrs <mcastro@laminr.ai>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

README.md

@@ -790,11 +790,65 @@ HTML admin. The wire shape is identical regardless of locale —
 only the human-readable strings change.
 
 **The SPA's own chrome strings** ("Add", "Search", "Save and
-continue editing", "Loading…") are still hard-coded English. A
-message-catalog refresh + `config.language` wire field is tracked
-in [#630](https://github.com/MartinCastroAlvarez/django-admin-react/issues/630). Until that lands, non-English-primary shops
-get translated `verbose_name` / `help_text` (via `LocaleMiddleware`)
-but English chrome around them.
+continue editing", "Loading…") flow through the same locale (#630,
+since 1.7.0). Shipped catalogs: English (source-as-key), Spanish,
+Portuguese / pt-BR, French. Adding a new language: drop a JSON file
+under `frontend/packages/ui/src/i18n/`, import it in
+`frontend/packages/ui/src/i18n.ts`, ship.
+
+### Custom widgets (`formfield_overrides` + `registerFieldWidget`)
+
+When your `ModelAdmin` routes a field through a custom widget —
+`formfield_overrides = {MyJSONField: {"widget": MyCustomWidget}}`,
+or a custom `Form` class declaring widgets directly, or a
+third-party widget library — the API surfaces it as
+`widget: "custom"` + `widget_class: "<dotted.Python.Path>"`
+(`django-admin-rest-api` 1.3.0+). The SPA dispatches the render to
+a consumer-registered widget via a small plugin protocol (#625).
+
+Register your widget BEFORE the SPA bundle runs — in your custom
+`change_form_template`, a shared base template, or any `<script>`
+tag that loads ahead of the SPA's bundle:
+
+```html
+<!-- in your Django template -->
+<script>
+  window.darFieldWidgets = window.darFieldWidgets ?? {};
+  window.darFieldWidgets['mypkg.widgets.MarkdownEditor'] = {
+    mount(container, props) {
+      // Read `props.value` for the current value.
+      // Call `props.onChange(next)` when the operator edits.
+      // Render whatever — vanilla JS, jQuery, mini-React, …
+      const textarea = document.createElement('textarea');
+      textarea.value = props.value ?? '';
+      textarea.addEventListener('input', (e) => props.onChange(e.target.value));
+      container.appendChild(textarea);
+      // (Optional) return a cleanup fn called on SPA unmount.
+      return () => textarea.remove();
+    },
+  };
+</script>
+```
+
+The `props` object passed to `mount` has:
+
+| Prop | Type | Description |
+|---|---|---|
+| `value` | `WriteValue` | Current draft value (live — read each access via getter). |
+| `onChange` | `(next) => void` | Call to emit a new value; the SPA re-renders. |
+| `error` | `string[] \| undefined` | Per-field validation errors from the last save attempt. |
+| `widgetClass` | `string` | The dotted class path (handy if a single mount fn handles related widgets). |
+
+When no registration matches the `widget_class` on the wire, the
+SPA falls back to a default text input + a small amber note
+(`Custom widget <class> is not registered; using the default text
+input.`). The operator can still complete the form; the gap is
+explicit and recoverable, not a silent break.
+
+If you'd rather skip the consumer-side widget for a model and keep
+it on the legacy `/admin/`, the
+[experience-toggle strip](#experience-toggle-strip-optional) +
+`LEGACY_ADMIN_URL_PREFIX` give consumers a one-click hop back.
 
 ---
 

frontend/packages/api/src/contract.ts

@@ -42,8 +42,20 @@ export type FieldType =
  * `shuttle_v` come from `filter_horizontal` / `filter_vertical` (#627) —
  * the SPA renders Django's two-pane "available / chosen" widget for the
  * M2M field, with horizontal or vertical orientation respectively.
+ * `custom` (api 1.3.0+) marks a field whose bound form widget class lives
+ * outside `django.*` — `formfield_overrides` / `formfield_for_dbfield` /
+ * a third-party widget. The SPA dispatches to a consumer-registered
+ * widget via `registerFieldWidget(widget_class, …)` (#625); falls back
+ * to the default control + an "open in legacy admin" note when no
+ * registration matches.
  */
-export type WidgetHint = 'radio' | 'raw_id' | 'password' | 'shuttle_h' | 'shuttle_v';
+export type WidgetHint =
+  | 'radio'
+  | 'raw_id'
+  | 'password'
+  | 'shuttle_h'
+  | 'shuttle_v'
+  | 'custom';
 
 export interface Permissions {
   view: boolean;
@@ -446,6 +458,14 @@ export interface FieldDescriptor {
    * has redacted `value` (it ships `null`).
    */
   widget?: WidgetHint;
+  /**
+   * Dotted Python path of the bound form widget's class (api 1.3.0+),
+   * present only when `widget` is `"custom"`. The SPA dispatches to a
+   * consumer-registered widget via `registerFieldWidget(widget_class,
+   * …)`; falls back to the default control + an "open in legacy admin"
+   * note when no registration matches (#625).
+   */
+  widget_class?: string;
 }
 
 export interface FieldsetDescriptor {

frontend/packages/form/src/CustomWidgetMount.tsx

@@ -0,0 +1,85 @@
+// CustomWidgetMount — React adapter for the consumer-supplied
+// vanilla mount-fn plugin protocol (#625). Bridges the SPA's
+// controlled-form world (value + onChange every render) to the
+// imperative DOM world of a `function mount(container, props)`
+// contract.
+//
+// Why this layer:
+// - The SPA's React is bundled into the wheel; exposing it on a
+//   global so consumer React components can use it is fragile
+//   across rebuilds.
+// - A vanilla mount-fn contract keeps the consumer free to use
+//   any framework (jQuery, Stimulus, mini-React, vanilla DOM).
+// - The mount fn is called once on mount with the initial props;
+//   value changes invoked from inside the widget (via
+//   `props.onChange`) flow through React's normal re-render path.
+//   Successive mounts after a re-render don't fire — React's
+//   useEffect with `[]` deps mounts exactly once.
+
+import { useEffect, useRef } from 'react';
+
+import type { WriteValue } from '@dar/data';
+import type { CustomWidgetSpec } from '@dar/ui';
+
+interface CustomWidgetMountProps {
+  spec: CustomWidgetSpec;
+  widgetClass: string;
+  value: WriteValue;
+  onChange: (next: WriteValue) => void;
+  error: string[] | undefined;
+}
+
+export function CustomWidgetMount({
+  spec,
+  widgetClass,
+  value,
+  onChange,
+  error,
+}: CustomWidgetMountProps): JSX.Element {
+  const ref = useRef<HTMLDivElement>(null);
+  // Latest props the widget needs to see at re-render time. The
+  // mount fn captured the FIRST onChange; subsequent React renders
+  // would close over a stale onChange unless we forward via a
+  // ref. The widget reads through this ref each time it emits.
+  const latestProps = useRef({ value, onChange, error, widgetClass });
+  latestProps.current = { value, onChange, error, widgetClass };
+
+  useEffect(() => {
+    if (!ref.current) return undefined;
+    const container = ref.current;
+    // Mount with stable proxies — the widget's mount fn captures
+    // these once; the wrappers read through latestProps.current so
+    // every emit and every value-read sees the freshest binding.
+    const cleanup = spec.mount(container, {
+      get value() {
+        return latestProps.current.value;
+      },
+      onChange: (next) => latestProps.current.onChange(next),
+      get error() {
+        return latestProps.current.error;
+      },
+      get widgetClass() {
+        return latestProps.current.widgetClass;
+      },
+    });
+    return () => {
+      if (typeof cleanup === 'function') cleanup();
+      // Defensive: if the widget didn't fully tear down its DOM,
+      // wipe the container so a re-mount starts clean. The mount
+      // fn is the source of truth; this is a last-resort backstop.
+      container.innerHTML = '';
+    };
+    // Intentional: mount-once contract. Re-mounting on every value
+    // change would defeat the imperative widget's own state
+    // management. The latestProps ref pattern (above) forwards
+    // value / onChange / error to the widget without re-mounting.
+  }, [spec]);
+
+  return (
+    <div
+      ref={ref}
+      data-custom-widget-class={widgetClass}
+      className="rounded border border-gray-300 p-2"
+    />
+  );
+}

frontend/packages/form/src/FieldInput.tsx

@@ -13,9 +13,10 @@ import { Plus } from 'lucide-react';
 
 import type { FieldDescriptor, FieldValue, WriteValue } from '@dar/data';
 import { FieldValueView } from '@dar/details';
-import { Checkbox } from '@dar/ui';
+import { Checkbox, lookupFieldWidget, t } from '@dar/ui';
 
 import { AutocompleteInput } from './AutocompleteInput';
+import { CustomWidgetMount } from './CustomWidgetMount';
 import { RelatedAddModal } from './RelatedAddModal';
 import { ShuttleSelect } from './ShuttleSelect';
 
@@ -70,6 +71,49 @@ export function FieldInput({ name, field, value, error, onChange }: FieldInputPr
         className={base}
       />
     );
+  } else if (field.widget === 'custom' && field.widget_class) {
+    // Custom widget plugin protocol (#625). The API (1.3.0+) marks
+    // any field whose bound form widget class lives outside
+    // ``django.*`` with ``widget: "custom"`` + the widget's dotted
+    // Python path. Consumers register a vanilla mount fn for that
+    // class via ``registerFieldWidget(class, {mount})``; the SPA's
+    // ``CustomWidgetMount`` adapter bridges React → the mount fn's
+    // imperative DOM world.
+    //
+    // If no registration matches, render the default control for the
+    // field's type with a small inline note so the operator isn't
+    // stuck — they can still type something into the field; the
+    // consumer's missing widget is a deployment gap, not a hard
+    // block. The note links to the legacy admin which has the real
+    // widget rendered server-side.
+    const widgetSpec = lookupFieldWidget(field.widget_class);
+    if (widgetSpec) {
+      control = (
+        <CustomWidgetMount
+          spec={widgetSpec}
+          widgetClass={field.widget_class}
+          value={value}
+          onChange={onChange}
+          error={error}
+        />
+      );
+    } else {
+      control = (
+        <div className="space-y-1">
+          <input
+            id={id}
+            type="text"
+            value={value == null ? '' : String(value)}
+            onChange={(e) => onChange(e.target.value)}
+            className={base}
+          />
+          <p className="text-xs text-amber-700">
+            {t('Custom widget')} <code className="font-mono">{field.widget_class}</code>{' '}
+            {t('is not registered; using the default text input.')}
+          </p>
+        </div>
+      );
+    }
   } else if (field.widget === 'raw_id' && field.type === 'foreignkey') {
     // raw_id_fields (#626 / #251). The consumer explicitly OPTED OUT
     // of an autocomplete picker — typically because the FK target has

frontend/packages/ui/src/custom-widget.test.ts

@@ -0,0 +1,67 @@
+// Lock the custom widget plugin protocol (#625):
+//
+//   1. `registerFieldWidget(class, spec)` puts a spec in the
+//      module-level registry.
+//   2. `lookupFieldWidget(class)` returns the registered spec or
+//      undefined when nothing matches.
+//   3. The window.darFieldWidgets global is a fallback path for
+//      consumers shipping a vanilla <script> registration (no
+//      build).
+//   4. Module-level registry wins over the window global on
+//      conflict (explicit `registerFieldWidget` is more intentional
+//      than a global assignment).
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  _resetFieldWidgetRegistryForTests,
+  lookupFieldWidget,
+  registerFieldWidget,
+} from './custom-widget';
+
+afterEach(() => {
+  _resetFieldWidgetRegistryForTests();
+  delete window.darFieldWidgets;
+});
+
+describe('registerFieldWidget / lookupFieldWidget', () => {
+  it('round-trips a registered widget by class name', () => {
+    const spec = { mount: vi.fn() };
+    registerFieldWidget('mypkg.MarkdownEditor', spec);
+    expect(lookupFieldWidget('mypkg.MarkdownEditor')).toBe(spec);
+  });
+
+  it('returns undefined when no registration matches', () => {
+    expect(lookupFieldWidget('not.registered')).toBeUndefined();
+  });
+
+  it('latest registration wins (re-register overwrites)', () => {
+    const first = { mount: vi.fn() };
+    const second = { mount: vi.fn() };
+    registerFieldWidget('x', first);
+    registerFieldWidget('x', second);
+    expect(lookupFieldWidget('x')).toBe(second);
+  });
+});
+
+describe('window.darFieldWidgets fallback (no-build path)', () => {
+  it('reads from window.darFieldWidgets when the module registry is empty', () => {
+    const spec = { mount: vi.fn() };
+    window.darFieldWidgets = { 'global.Widget': spec };
+    expect(lookupFieldWidget('global.Widget')).toBe(spec);
+  });
+
+  it('module registry wins over the window global on conflict', () => {
+    const moduleSpec = { mount: vi.fn() };
+    const globalSpec = { mount: vi.fn() };
+    window.darFieldWidgets = { 'shared.Widget': globalSpec };
+    registerFieldWidget('shared.Widget', moduleSpec);
+    expect(lookupFieldWidget('shared.Widget')).toBe(moduleSpec);
+  });
+
+  it('is robust when window.darFieldWidgets is undefined', () => {
+    // Simulate a fresh page where no consumer has registered
+    // anything via either path.
+    delete window.darFieldWidgets;
+    expect(lookupFieldWidget('anything')).toBeUndefined();
+  });
+});