Sachbearbeiter-Cockpit (@gentics/cockpit)

React-Library zum Bauen von Sachbearbeiter-Cockpits auf ActaNova. Sie bündelt alles, was jedes Sachbearbeiter-Cockpit sonst neu bauen müsste — Anmeldung, Mandanten, API-Zugriff, Caching und die wiederverwendbaren UI-Widgets — sodass ein konkretes Sachbearbeiter-Cockpit nur noch seine Apps zusammensteckt.

Ein Sachbearbeiter-Cockpit besteht damit aus zwei Teilen: dem Rahmen aus der Library (BaseCockpit) und den Apps, die du selbst schreibst. Der Rahmen kümmert sich um Login, App-Übersicht, Routing und Mandantenwahl; deine App bekommt einen fertigen Query- und Tenant-Kontext und kann direkt Daten laden und anzeigen.

Die zwei Einstiegspunkte

Import	Inhalt
@gentics/cockpit/core	Nicht-UI: BaseCockpit, Auth, Services, Store-Hooks, Tenant-Context, Typen
@gentics/cockpit/widgets	UI-Widgets: List, Field, Badge, Assignment, Submitter, FileManager, ToastHost + Helfer
@gentics/cockpit/style.css	Das gebaute Tailwind-CSS für beide Entrypoints

Mehr gibt es nicht: ein Import vom Paket-Root (@gentics/cockpit) existiert nicht, die exports in der package.json geben genau diese drei Pfade frei.

Wie die Teile zusammenhängen

                        ┌───────────────────────────────┐
  authConfig.json ────► │  BaseCockpit                  │
  (OIDC-Settings)       │  Config-Gate → Login (OIDC)   │
                        │  AuthProvider                 │
                        │  QueryClientProvider          │
                        │  Router (hash/browser/none)   │
                        │  Header + App-Übersicht       │
                        └───────────────┬───────────────┘
                                        │  eine App gewählt (/:appId/*)
                                        ▼
                        ┌───────────────────────────────┐
                        │  TenantProvider (pro App)     │
                        │  ──► deine App-Komponente     │
                        │      mit eigenen <Routes>     │
                        └───────────────┬───────────────┘
                                        │
                 Widgets ◄──────────────┴──────────────► Store-Hooks
       (List, Field, Badge, …)                    (useFiles, useFile, …)
                                                          │
                                                    Services (BaseService)
                                                          │
                                              /api/cockpit/an/Tenants/Items/…

Von unten nach oben:

1. Services (FilesService, DocumentsService, …) sprechen die ActaNova-API. Sie erben von BaseService, das Base-URL, Bearer-Token und Token-Erneuerung erledigt — reine Klassen, keine Hooks.
2. Stores (useFiles, useFile, useSaveFile, …) wickeln die Services in React-Query-Hooks: Cache, Deduplizierung, Lade-/Fehlerzustände und Invalidierung nach dem Speichern.
3. Widgets bekommen ihre Daten nicht selbst, sondern als Datenquelle hereingereicht — eine Funktion, die ein Query-Ergebnis liefert. Dadurch funktioniert dasselbe Widget mit echten Hooks, mit Mock-Daten oder mit einem statischen Objekt.
4. BaseCockpit ist der Rahmen darüber und stellt alles bereit, was die Schichten 1–3 zur Laufzeit brauchen.

Was die Library mitbringt — und was dein Projekt liefert

Die Library bringt mit	Dein Projekt liefert
OIDC-Anmeldung inkl. Silent-Renew, Login-Screen, Profil-Menü	authConfig.json mit den OIDC-Settings
App-Übersicht, Rechtefilter über Keycloak-Rollen	Die Apps selbst (CockpitApp[]) und deren UI
Router, Mandantenwahl, React-Query-Client	Peer-Dependencies (React 19, React Query 5, React Router 7)
Services + Hooks für Files, Dokumente, Gruppen, User, Personen, Annotations, Aktivitäten	Ein Proxy, der /api/cockpit/an auf /api/main/v1 umschreibt
Widgets samt kompiliertem Stylesheet für deren Klassen	Ein eigenes Tailwind-Setup für deine Klassen — plus CSS-Reset, den die Lib bewusst nicht mitliefert

Versionierung und Bezug

Die Version der Library matcht die ActaNova-Version, für die sie gebaut ist: der Major kommt von ActaNova, Minor/Patch zählen die Releases der Library innerhalb dieser ActaNova-Version. Ein neues ActaNova-Major bedeutet eine neue Major-Linie der Library.

Das Paket liegt nicht auf npmjs.com, sondern in der Gentics-Registry (https://repo.gentics.com/repository/npm-products/, Zugriff restricted) — siehe Installation.

Wo weiterlesen

Du willst …	Seite
das Paket installieren und einbinden	Installation
ein Sachbearbeiter-Cockpit von Null aufsetzen	Sachbearbeiter-Cockpit aufsetzen
die erste App mit Liste + Detailansicht bauen	Erste App
ein bestimmtes Feature nutzen (Routing, Datenquellen, Mandanten, Rechte, Stores, Mock)	Anleitungen
das Sachbearbeiter-Cockpit als Container ausliefern	Deployment
die Props eines Widgets nachsehen	Widgets
wissen, was getByPath & Co. tun	Helfer

Widget-Übersicht

Widget	Zweck	Live-Vorschau
Badge	Farbiger Status-Badge (Literal- oder Pfad-Modus)	✅
Field	Anzeige-/Eingabefeld, liest Werte per JSON-Pfad	✅
List	Sortier- und filterbare Tabelle/Karten-Liste	✅
Assignment	Zuweisung von Gruppen/Benutzern	✅ mit Demo-Store
Submitter	Anzeige-Karte für die Daten eines Einbringers	✅ 🚧 experimentell
FileManager	Dokumente anzeigen und hochladen	✅ mit Demo-Store
ToastHost	Toast-Kanal der Widgets (widgetToast)	✅