@bimetal/react
Die generische React-Bindung für die BIMETAL-Komponenten-Familie. Dieses Paket bindet einen
kanonischen Controller (aus einem der @bimetal/*-headless-Pakete) via dem React-eigenen Primitiv
useSyncExternalStore in React ein — es enthält keine eigene Interaktionslogik und keine
Kalender-Spezifika. Jedes if lebt im Controller; React rendert nur den identitätsstabilen Snapshot
und übersetzt DOM-Events in Intent-Aufrufe.
Die fertigen Komponenten (<Calendar>, <Kanban>, <Table>, <Gantt>, <Whiteboard>,
<Tree>, <List>, <Picker>, <FormBuilder>/<FormRenderer>) liegen in den
@bimetal/<familie>-react-components-Paketen. Dieses Paket liefert die Bausteine darunter (den
generischen Hook, per-Komponenten-Hooks, die Fokus-Trap, Test-Utilities) für eigene React-UIs.
Installation
npm install @bimetal/react @bimetal/<familie>-headless @bimetal/<familie>-data
# z. B. @bimetal/react @bimetal/kanban-headless @bimetal/kanban-data
Was das Paket liefert
| Export | Zweck |
|---|---|
useController(factory, options) | Das generische Primitiv: erzeugt einen Controller (stabil über die store-Identität) und abonniert seinen Snapshot via useSyncExternalStore. Gibt [snapshot, controller] zurück. |
useKanbanController, useTableController, useGanttController, useWhiteboardController, useTreeController, useListController, usePickerController, useToastController, useOverlayController, useFormBuilderController, useFormRendererController | Vorkonfigurierte Wrapper um useController je Familie — elf Hooks in zehn Dateien (useFormController.ts liefert Builder und Renderer). |
useLiveOptions(options) | Hält die Callbacks eines einmal erzeugten Controllers lebendig. Steckt bereits in allen Controller-Hooks und in useFocusTrap; direkt gebraucht wird er nur für ein eigenes Binding. Siehe Options an einen Controller durchreichen. |
useConfigPush(ctrl, config) / useReactivePush(push, value, identity) | Reaktive Durchreichung einer Options-Leitung (setConfig, setRules, …) in einen laufenden Controller. |
useFocusTrap(ref, options) | Fokus-Trap-Hook (Dialog-Lifecycle: enter → trap → escape → restore), gewrappt um @bimetal/a11y-dom. onEscape ist lebendig (bimetal-179). |
renderProbe / probeRender | Test-Utilities für Re-Render-Zählung. |
Die Controller-Factories selbst (createKanbanController, createTableController,
createGanttController, createWhiteboardController, createTreeController, createListController,
createPickerController, createFormBuilderController/createFormRendererController) + ihre Typen
werden aus den jeweiligen @bimetal/<familie>-headless-Paketen re-exportiert.
Der Calendar-Hook (
useCalendarController) liegt aus historischen Gründen direkt in@bimetal/calendar-react-components, nicht hier — Calendar war die Referenz-Komponente vor dieser generischen Bindung. Alle anderen Familien laufen über dieses Paket. Zusammen sind das zwölf Controller-Hooks: elf hier, einer im Kalender-Paket.
Architektur-Hintergrund: Controller-Konzept (Headless und Bindings).
Re-exports
Zur Bequemlichkeit re-exportiert @bimetal/react alles aus @bimetal/temporal, sodass die Zeit-/
Layout-/Recurrence-Typen aus einem einzigen Paket importiert werden können.
Options an einen Controller durchreichen
setConfig (und setRules/setCustomViews) mit strukturell identischer
Config ist ein No-op — das ist seit bimetal-157 ein Vertrag des Controllers,
nicht des React-Bindings. Ein inline erzeugtes Objekt ist deshalb in jedem
Render-Layer unbedenklich:
// Genau so gedacht: das Inline-Objekt ist bei jedem Render neu; der Controller
// erkennt die strukturelle Gleichheit und löst keinen Zustandswechsel aus.
const [snapshot, ctrl] = useTableController({
store,
config: { columns: COLUMNS, rowHeight: 36 },
});
Für eigene Bindings (ein Controller, den BIMETAL nicht selbst anbietet) gibt es die reaktive Durchreichung einzeln:
import { useConfigPush, useReactivePush } from '@bimetal/react';
useConfigPush(ctrl, config); // ctrl.setConfig, reaktiv
useReactivePush(v => ctrl.setRules(v), rules, ctrl); // beliebiger Setter
Eine Grenze, die man kennen muss: Werte, die sich nur per Identität
vergleichen lassen — eine inline definierte Funktion (nodeMeta), ein frisches
Date, ein per Factory gebautes Regel-Objekt — sind bei jedem Render neu und
gelten damit als Änderung. Memoisiere sie (useMemo, Modul-Konstante). Der
Controller meldet sich in der Entwicklung von selbst, wenn er eine solche
Instabilitäts-Signatur sieht — mit dem Namen der betroffenen Leitung.
Callbacks: die Anwesenheit ist am Mount festgelegt, die Identität lebt
Ein Controller wird einmal erzeugt (useController memoisiert auf
[store, id]) und destrukturiert seine Callbacks im Konstruktor. Ohne
Gegenmaßnahme wäre damit die Closure des ersten Renders für immer
festgenagelt — jeder Host, dessen onSubmit frischen State liest (der Normalfall
in React), schickte gegen den Stand vom Mount ab. Still, plausibel und falsch.
useLiveOptions löst das, und alle Controller-Hooks dieses Pakets (sowie
useFocusTrap und useCalendarController) fahren bereits darüber. Der Vertrag:
// Jeder Render darf einen frischen Handler übergeben — die Geste erreicht IMMER
// den zuletzt übergebenen. Kein useCallback nötig, kein Controller-Neubau.
const [snapshot, ctrl] = useFormRendererController({
store, formId,
onSubmit: values => save(values, draftFromState), // liest frischen State
});
| Verhalten | |
|---|---|
| Callback beim Mount vorhanden, später getauscht | Der Aufruf erreicht die neueste Funktion. |
Callback beim Mount vorhanden, später weggenommen (undefined) | Der Aufruf erreicht die zuletzt bekannte Funktion. Der Controller hat die Anwesenheit beim Mount destrukturiert: er kann einen Loader nicht nachträglich lernen, also darf er auch keinen verlieren — sonst stünde undefined dort, wo der Kern eine Funktion erwartet (ein weggenommenes loadChildren hinterließ einen Baum mit ewigem Lade-Chevron, ohne Fehlermeldung). |
| Callback beim Mount nicht vorhanden, später gesetzt | Wirkungslos — der Controller hat bereits undefined destrukturiert. Im Entwicklungsmodus wird das gemeldet, einmal je Feld je Hook-Instanz. Übergib den Callback ab dem ersten Render; ein stabiles No-op genügt. |
Nicht-Funktions-Felder (options, initialValues, debounceMs, …) | Weiterhin auf den Mount-Wert festgelegt. Ihr Wert wird intern aufgefrischt, damit ein nach einem <Activity>/Suspense-Reveal neu erzeugter Controller nicht auf dem Mount-Stand einfriert — ein Reaktivitäts-Versprechen ist das ausdrücklich nicht. Wer sie zur Laufzeit ändern will, nimmt die imperative Setter des Controllers (setOptions(), setConfig()). |
Grenzen der Weiterleitung (heute nutzt kein Options-Typ eines davon; ein
künftiger darf daran nicht still brechen): die Weiterleitung ist eine gewöhnliche
Pfeilfunktion, es überlebt nur das Aufruf-Verhalten. Eigenschaften an der
Funktion, length/name, new-Barkeit, die this-Bindung, Symbol-Schlüssel
und die Prototyp-Kette gehen verloren. Ein Options-Feld, das als Methode auf
this zugreift, muss gebunden übergeben werden.
Für ein eigenes Binding (ein Controller, den BIMETAL nicht selbst anbietet) gilt dieselbe Reihenfolge wie in den Hausbindings — erst lebendig machen, dann erzeugen:
import { useController, useLiveOptions, useConfigPush } from '@bimetal/react';
const live = useLiveOptions(options); // Callbacks lebendig
const [snapshot, ctrl] = useController(() => createMyController(live), [options.store]);
useConfigPush(ctrl, options.config);