@efa-one/sdk 1.25.0 → 1.27.0

package/README.md

@@ -14,7 +14,7 @@ sub-paths — this keeps `express` out of the frontend and `react` out of the ba
 |---|---|---|
 | `@efa-one/sdk/backend` | Node/Express | Auth + token exchange (`requireAuth`, `createExchangeRouter`, `requireInternalOrAuth` …), health router, service discovery + gateway client (`serviceClient`, `resolveService`), clients for audit/reporting/mail/notifications, permission resolution/registration (`getUserPermissions`, `registerPermissions`, `checkPermission`), platform-admin check (`isPlatformAdmin` — top permission `efa-all`, legacy `converge-admin` accepted until Q1-2027; `requireAdmin`/`requireAdminOrPermission` use it), capability registry (`registerApiMetadata`), backend i18n |
 | `@efa-one/sdk/frontend` | Browser/React | postMessage IPC (`registerAppInfo`, `sendAtStart`, `navigateToApp`, `notifyRouteChange` …), react-i18next factory (`initI18n`), platform-admin check (`isPlatformAdmin`, `PLATFORM_ADMIN_PERMISSIONS`), `DevHeader` |
-| `@efa-one/sdk/frontend/ui` | Browser/React | The efa-one design-system kit: `Button`, `Input`, `Badge`, `Alert`, `Dialog`, `DropdownMenu`, `Tooltip`, `EmptyState`, `Skeleton`, `RecordDialog`, and the **`DataTable`** (sortable/filterable/groupable list with draggable, resizable columns, a per-user persisted view and CSV/Excel export of the current view; reflows to stacked cards below 640px). Also exports `useIsMobile` — the platform-wide 640px breakpoint hook. Ship its companion CSS once: `import '@efa-one/sdk/frontend/ui/styles.css'` |
+| `@efa-one/sdk/frontend/ui` | Browser/React | The efa-one design-system kit: `Button`, `Input`, `Switch` (on/off settings — checkboxes only for row selection and confirmations), `Badge`, `Alert`, `Dialog`, `DropdownMenu`, `Tooltip`, `EmptyState`, `Skeleton`, `RecordDialog` with `useRecords` (ready-made list/create/edit/delete flow) and `ConfirmDeleteDialog`, and the **`DataTable`** (sortable/filterable/groupable list with draggable, resizable columns, a per-user persisted view and CSV/Excel export of the current view; reflows to stacked cards below 640px). Also exports `useIsMobile` — the platform-wide 640px breakpoint hook. Ship its companion CSS once: `import '@efa-one/sdk/frontend/ui/styles.css'` |
 | `@efa-one/sdk/frontend/format` | Browser | Platform-wide date/time display — `formatDate` (`01.09.2026`), `formatDateTime` (`01.09.2026, 11:05`), `formatTime`, `formatFileStamp`, `localeForLanguage`. Always use these instead of `toLocaleDateString`/`toLocaleString`: without an options object those render `1.9.2026`, and without a locale argument they follow the browser language (`9/1/2026`) |
 | `@efa-one/sdk/frontend/viewPreferences` | Browser/React | Persistence seam for `DataTable` — `createViewPreferencesClient()` (standard `/api/view-preferences/:listId` adapter) + `useViewPreferences()` |
 
@@ -281,6 +281,29 @@ Excel export for such data. No backend or kernel change.
   scrollbar sits above the table and scrolls in sync with the bottom one. Not on
   mobile. The border moved to an outer wrapper.
 
+**1.27.0 — `useRecords`: edit first, read-only without permission.** No kernel or backend change.
+- `editable` (default `true`): `false` opens records read-only, no pencil, no PUT
+  (`editable: can(user, 'write')`).
+- `openIn: 'edit'`: a click on a record opens the form directly (with `editable`); default
+  `'read'` keeps read → pencil → edit.
+- `dialogProps` now carries `mode`, `onModeChange` and `readOnly`; do not pass them yourself.
+
+**1.26.0 — `useRecords`, `ConfirmDeleteDialog`, `Switch`.** No kernel or backend change.
+- `useRecords({ endpoint, apiBase, emptyForm, toForm, toPayload?, required?, validate? })`
+  runs the whole records flow: load the list, open for create (`openCreate`) or read
+  (`openRecord`), save (`POST <endpoint>` or `PUT <endpoint>/:id`, `updateMethod: 'PATCH'`
+  optional), delete after confirmation (`DELETE <endpoint>/:id`), reload after each write,
+  server messages `{ "error" }` as banner. Spread `dialogProps` into `RecordDialog` and
+  `deleteDialogProps` into `ConfirmDeleteDialog`. The logic itself is
+  `createRecordsController` (no React, for tests or other frameworks).
+- Use it instead of hand-written `save()` functions: one found in a generated app returned
+  early for `{ id: 'new' }`, so „Erstellen" never sent anything and no type check noticed.
+- `ConfirmDeleteDialog`: delete confirmation, `size="sm"`, error banner.
+- `RecordDialog` takes `readOnly` (no pencil, no „Bearbeiten“, e.g. without write
+  permission); `RecordDialogProps` is exported.
+- `Switch`/`SwitchControl` for on/off values (checkboxes only for row selection and
+  confirmations).
+
 **Next minor (planned 1.23.0, not yet released) — exchange, cookie and S2S hardening.**
 Needs a kernel with efaware/efa_kernel#106 and #107 first (gateway exchange token
 `gw: 'app'`, provenance `jti`, cookie filter). Then:

package/frontend/ui/ConfirmDeleteDialog.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export interface ConfirmDeleteDialogProps {
+    open: boolean;
+    itemName?: string;
+    title?: string;
+    description?: string;
+    deleting?: boolean;
+    error?: string;
+    onErrorDismiss?: () => void;
+    onConfirm(): void | Promise<void>;
+    onCancel(): void;
+    labels?: {
+        cancel?: string;
+        confirm?: string;
+    };
+}
+export declare function ConfirmDeleteDialog({ open, itemName, title, description, deleting, error, onErrorDismiss, onConfirm, onCancel, labels, }: ConfirmDeleteDialogProps): React.JSX.Element;

package/frontend/ui/ConfirmDeleteDialog.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Dialog } from './Dialog.js';
+import { Button } from './Button.js';
+import { Alert } from './Alert.js';
+export function ConfirmDeleteDialog({ open, itemName, title, description, deleting, error, onErrorDismiss, onConfirm, onCancel, labels, }) {
+    const text = description ?? (itemName ? `„${itemName}“ wird endgültig gelöscht.` : 'Der Eintrag wird endgültig gelöscht.');
+    return (_jsx(Dialog, { open: open, onOpenChange: (o) => {
+            if (!o)
+                onCancel();
+        }, title: title ?? 'Eintrag löschen?', size: "sm", banner: error ? _jsx(Alert, { variant: "error", onDismiss: onErrorDismiss, children: error }) : undefined, footer: _jsxs(_Fragment, { children: [_jsx(Button, { variant: "secondary", onClick: onCancel, disabled: !!deleting, children: labels?.cancel ?? 'Abbrechen' }), _jsx(Button, { variant: "danger", onClick: () => void onConfirm(), loading: !!deleting, children: labels?.confirm ?? 'Löschen' })] }), children: _jsx("p", { className: "text-sm text-[var(--color-text-secondary)]", children: text }) }));
+}

package/frontend/ui/RecordDialog.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { type DialogSize } from './Dialog.js';
 export type RecordDialogMode = 'read' | 'edit' | 'create';
-interface RecordDialogProps {
+export interface RecordDialogProps {
     open: {
         id: string;
         item?: any;
@@ -20,6 +20,7 @@ interface RecordDialogProps {
     saveDisabled?: boolean;
     error?: string;
     onErrorDismiss?: () => void;
+    readOnly?: boolean;
     size?: DialogSize;
     labels?: {
         close?: string;
@@ -29,5 +30,4 @@ interface RecordDialogProps {
         edit?: string;
     };
 }
-export declare function RecordDialog({ open, onOpenChange, mode: controlledMode, onModeChange, title, readContent, editContent, onSave, saving, saveDisabled, error, onErrorDismiss, size, labels, }: RecordDialogProps): React.JSX.Element;
-export {};
+export declare function RecordDialog({ open, onOpenChange, mode: controlledMode, onModeChange, title, readContent, editContent, onSave, saving, saveDisabled, error, onErrorDismiss, readOnly, size, labels, }: RecordDialogProps): React.JSX.Element;

package/frontend/ui/RecordDialog.js

@@ -4,8 +4,8 @@ import { Pencil } from 'lucide-react';
 import { Dialog, DialogClose } from './Dialog.js';
 import { Button } from './Button.js';
 import { Alert } from './Alert.js';
-export function RecordDialog({ open, onOpenChange, mode: controlledMode, onModeChange, title, readContent, editContent, onSave, saving, saveDisabled, error, onErrorDismiss, size, labels, }) {
-    const [internalMode, setInternalMode] = useState('read');
+export function RecordDialog({ open, onOpenChange, mode: controlledMode, onModeChange, title, readContent, editContent, onSave, saving, saveDisabled, error, onErrorDismiss, readOnly, size, labels, }) {
+    const [internalMode, setInternalMode] = useState(() => (open?.id === 'new' ? 'create' : 'read'));
     const mode = controlledMode ?? internalMode;
     useEffect(() => {
         if (!open)
@@ -24,7 +24,7 @@ export function RecordDialog({ open, onOpenChange, mode: controlledMode, onModeC
         onOpenChange(null);
     }
     async function handleSave() {
-        if (mode === 'read')
+        if (mode === 'read' || (readOnly && mode === 'edit'))
             return;
         await onSave(mode);
     }
@@ -36,5 +36,5 @@ export function RecordDialog({ open, onOpenChange, mode: controlledMode, onModeC
     return (_jsx(Dialog, { open: open !== null, onOpenChange: (o) => { if (!o)
             handleClose(); }, title: title, size: size, banner: mode !== 'read' && error
             ? _jsx(Alert, { variant: "error", onDismiss: onErrorDismiss, children: error })
-            : undefined, footer: mode === 'read' ? (_jsxs(_Fragment, { children: [_jsx(DialogClose, { asChild: true, children: _jsx(Button, { variant: "secondary", children: closeLabel }) }), _jsxs(Button, { onClick: () => setMode('edit'), children: [_jsx(Pencil, { className: "w-4 h-4" }), editLabel] })] })) : (_jsxs(_Fragment, { children: [_jsx(DialogClose, { asChild: true, children: _jsx(Button, { variant: "secondary", children: cancelLabel }) }), _jsx(Button, { onClick: handleSave, loading: !!saving, disabled: !!saveDisabled, children: mode === 'create' ? createLabel : saveLabel })] })), children: mode === 'read' ? (_jsxs("div", { children: [_jsx("div", { className: "flex justify-end mb-2 -mt-1", children: _jsx("button", { onClick: () => setMode('edit'), className: "p-1.5 rounded-md text-[var(--color-text-muted)] hover:text-[var(--color-primary-text)] hover:bg-[var(--color-surface-raised)] transition-colors", title: editLabel, "aria-label": editLabel, children: _jsx(Pencil, { className: "w-4 h-4" }) }) }), readContent] })) : (_jsx("div", { className: "flex flex-col gap-4", children: editContent })) }));
+            : undefined, footer: mode === 'read' ? (_jsxs(_Fragment, { children: [_jsx(DialogClose, { asChild: true, children: _jsx(Button, { variant: "secondary", children: closeLabel }) }), !readOnly && (_jsxs(Button, { onClick: () => setMode('edit'), children: [_jsx(Pencil, { className: "w-4 h-4" }), editLabel] }))] })) : (_jsxs(_Fragment, { children: [_jsx(DialogClose, { asChild: true, children: _jsx(Button, { variant: "secondary", children: cancelLabel }) }), _jsx(Button, { onClick: handleSave, loading: !!saving, disabled: !!saveDisabled, children: mode === 'create' ? createLabel : saveLabel })] })), children: mode === 'read' ? (_jsxs("div", { children: [!readOnly && (_jsx("div", { className: "flex justify-end mb-2 -mt-1", children: _jsx("button", { onClick: () => setMode('edit'), className: "p-1.5 rounded-md text-[var(--color-text-muted)] hover:text-[var(--color-primary-text)] hover:bg-[var(--color-surface-raised)] transition-colors", title: editLabel, "aria-label": editLabel, children: _jsx(Pencil, { className: "w-4 h-4" }) }) })), readContent] })) : (_jsx("div", { className: "flex flex-col gap-4", children: editContent })) }));
 }

package/frontend/ui/Switch.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+export type SwitchTone = 'primary' | 'danger';
+export interface SwitchControlProps {
+    id?: string;
+    checked: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    tone?: SwitchTone;
+    className?: string;
+    name?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+}
+export declare function SwitchControl({ id, checked, onCheckedChange, disabled, tone, className, name, ...aria }: SwitchControlProps): React.JSX.Element;
+export interface SwitchProps extends Omit<SwitchControlProps, 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'className'> {
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    title?: string;
+    className?: string;
+}
+export declare function Switch({ label, description, title, className, id, ...control }: SwitchProps): React.JSX.Element;

package/frontend/ui/Switch.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+export function SwitchControl({ id, checked, onCheckedChange, disabled = false, tone = 'primary', className = '', name, ...aria }) {
+    const button = (_jsx("button", { type: "button", role: "switch", id: id, "aria-checked": checked, "data-state": checked ? 'checked' : 'unchecked', disabled: disabled, onClick: () => onCheckedChange?.(!checked), className: `switch switch-${tone} ${className}`, ...aria, children: _jsx("span", { className: "switch-thumb", "aria-hidden": "true" }) }));
+    if (!name)
+        return button;
+    return (_jsxs(_Fragment, { children: [button, _jsx("input", { type: "hidden", name: name, value: checked ? 'true' : 'false', disabled: disabled })] }));
+}
+export function Switch({ label, description, title, className = '', id, ...control }) {
+    const autoId = useId();
+    const switchId = id ?? `switch-${autoId}`;
+    const descId = description ? `${switchId}-desc` : undefined;
+    return (_jsxs("div", { className: `flex items-start gap-3 ${className}`, title: title, children: [_jsx("span", { className: "pt-0.5 flex", children: _jsx(SwitchControl, { id: switchId, "aria-describedby": descId, ...control }) }), _jsxs("span", { className: "min-w-0", children: [_jsx("label", { htmlFor: switchId, className: `block text-sm text-[var(--color-text-primary)] ${control.disabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'}`, children: label }), description && (_jsx("span", { id: descId, className: "block text-xs text-[var(--color-text-muted)] mt-0.5", children: description }))] })] }));
+}

package/frontend/ui/index.d.ts

@@ -1,5 +1,6 @@
 export { Button } from './Button.js';
 export { Input } from './Input.js';
+export { Switch, SwitchControl, type SwitchProps, type SwitchControlProps, type SwitchTone } from './Switch.js';
 export { Badge } from './Badge.js';
 export { Alert, type AlertVariant } from './Alert.js';
 export { Dialog, DialogClose, DEFAULT_DIALOG_SIZE, type DialogSize } from './Dialog.js';
@@ -7,7 +8,10 @@ export * as DropdownMenu from './DropdownMenu.js';
 export { Tooltip, TooltipProvider } from './Tooltip.js';
 export { EmptyState } from './EmptyState.js';
 export { Skeleton, SkeletonRow } from './Skeleton.js';
-export { RecordDialog, type RecordDialogMode } from './RecordDialog.js';
+export { RecordDialog, type RecordDialogMode, type RecordDialogProps } from './RecordDialog.js';
+export { ConfirmDeleteDialog, type ConfirmDeleteDialogProps } from './ConfirmDeleteDialog.js';
+export { useRecords, type UseRecordsResult } from './useRecords.js';
+export { createRecordsController, type RecordsController, type RecordsOptions, type RecordsState, type RecordsSaveMode, type RecordsDialogMode, } from './records.js';
 export { useIsMobile, MOBILE_QUERY } from '../useIsMobile.js';
 export { DataTable, DEFAULT_VIEW_VERSION, type ColumnDef, type FilterDef, type DataTableSelectionProps, } from './DataTable.js';
 export { toCsv, toXlsx, downloadFile, type ExportCell, type ExportTable } from './tableExport.js';

package/frontend/ui/index.js

@@ -1,5 +1,6 @@
 export { Button } from './Button.js';
 export { Input } from './Input.js';
+export { Switch, SwitchControl } from './Switch.js';
 export { Badge } from './Badge.js';
 export { Alert } from './Alert.js';
 export { Dialog, DialogClose, DEFAULT_DIALOG_SIZE } from './Dialog.js';
@@ -8,6 +9,9 @@ export { Tooltip, TooltipProvider } from './Tooltip.js';
 export { EmptyState } from './EmptyState.js';
 export { Skeleton, SkeletonRow } from './Skeleton.js';
 export { RecordDialog } from './RecordDialog.js';
+export { ConfirmDeleteDialog } from './ConfirmDeleteDialog.js';
+export { useRecords } from './useRecords.js';
+export { createRecordsController, } from './records.js';
 export { useIsMobile, MOBILE_QUERY } from '../useIsMobile.js';
 export { DataTable, DEFAULT_VIEW_VERSION, } from './DataTable.js';
 export { toCsv, toXlsx, downloadFile } from './tableExport.js';

package/frontend/ui/records.d.ts

@@ -0,0 +1,54 @@
+export type RecordsSaveMode = 'create' | 'edit';
+export type RecordsDialogMode = 'read' | 'edit' | 'create';
+export interface RecordsOptions<T, F> {
+    endpoint: string;
+    apiBase: string | (() => string);
+    emptyForm: () => F;
+    toForm: (row: T) => F;
+    toPayload?: (form: F) => unknown;
+    required?: ReadonlyArray<keyof F>;
+    validate?: (form: F, mode: RecordsSaveMode) => string | null | undefined;
+    getId?: (row: T) => string;
+    editable?: boolean;
+    openIn?: 'read' | 'edit';
+    updateMethod?: 'PUT' | 'PATCH';
+    fetchImpl?: typeof fetch;
+}
+export interface RecordsState<T, F> {
+    rows: T[];
+    loading: boolean;
+    loadError: string;
+    open: {
+        id: string;
+        item?: T;
+    } | null;
+    mode: RecordsDialogMode;
+    form: F;
+    saving: boolean;
+    saveError: string;
+    deleteTarget: T | null;
+    deleting: boolean;
+    deleteError: string;
+}
+export interface RecordsController<T, F> {
+    getState(): RecordsState<T, F>;
+    subscribe(listener: () => void): () => void;
+    setOptions(options: RecordsOptions<T, F>): void;
+    load(): Promise<void>;
+    dismissLoadError(): void;
+    openCreate(): void;
+    openRecord(row: T): void;
+    close(): void;
+    setMode(mode: RecordsDialogMode): void;
+    setForm(next: F | ((prev: F) => F)): void;
+    setField<K extends keyof F>(key: K, value: F[K]): void;
+    isComplete(): boolean;
+    save(mode: RecordsSaveMode): Promise<void>;
+    dismissSaveError(): void;
+    requestDelete(row: T): void;
+    cancelDelete(): void;
+    confirmDelete(): Promise<void>;
+    dismissDeleteError(): void;
+}
+export declare function requiredFilled<F>(form: F, required: ReadonlyArray<keyof F> | undefined): boolean;
+export declare function createRecordsController<T, F>(initial: RecordsOptions<T, F>): RecordsController<T, F>;

package/frontend/ui/records.js

@@ -0,0 +1,248 @@
+const NEW_ID = 'new';
+export function requiredFilled(form, required) {
+    return (required ?? []).every((k) => !isEmpty(form[k]));
+}
+function isEmpty(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+async function errorMessage(res, fallback) {
+    try {
+        const body = (await res.json());
+        if (typeof body?.error === 'string' && body.error.trim())
+            return body.error;
+        if (typeof body?.message === 'string' && body.message.trim())
+            return body.message;
+    }
+    catch {
+    }
+    return `${fallback} (HTTP ${res.status})`;
+}
+export function createRecordsController(initial) {
+    let options = initial;
+    let state = {
+        rows: [],
+        loading: true,
+        loadError: '',
+        open: null,
+        mode: 'read',
+        form: initial.emptyForm(),
+        saving: false,
+        saveError: '',
+        deleteTarget: null,
+        deleting: false,
+        deleteError: '',
+    };
+    const listeners = new Set();
+    let loadSeq = 0;
+    let loadedOnce = false;
+    function set(patch) {
+        state = { ...state, ...patch };
+        for (const l of listeners)
+            l();
+    }
+    function base() {
+        const b = options.apiBase;
+        return typeof b === 'function' ? b() : (b ?? '');
+    }
+    function tryId(row) {
+        const id = options.getId ? options.getId(row) : row.id;
+        return id === undefined || id === null || String(id) === '' ? null : String(id);
+    }
+    const NO_ID = 'Eintrag ohne ID: Die Liste liefert kein Feld „id“ (in useRecords getId angeben).';
+    function url(id) {
+        const root = `${base()}${options.endpoint}`;
+        return id === undefined ? root : `${root.replace(/\/$/, '')}/${encodeURIComponent(id)}`;
+    }
+    function request(target, method, body) {
+        const f = options.fetchImpl ?? fetch;
+        return f(target, {
+            method,
+            credentials: 'include',
+            headers: body === undefined ? { Accept: 'application/json' } : { 'Content-Type': 'application/json', Accept: 'application/json' },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+    }
+    function isComplete() {
+        return requiredFilled(state.form, options.required);
+    }
+    async function load() {
+        const seq = ++loadSeq;
+        set({ loading: !loadedOnce, loadError: '' });
+        try {
+            const res = await request(url(), 'GET');
+            if (!res.ok) {
+                const msg = await errorMessage(res, 'Liste konnte nicht geladen werden');
+                if (seq === loadSeq)
+                    set({ loading: false, loadError: msg });
+                return;
+            }
+            let data;
+            try {
+                data = await res.json();
+            }
+            catch {
+                if (seq === loadSeq)
+                    set({ loading: false, loadError: 'Liste konnte nicht geladen werden (Antwort ist kein JSON, stimmen apiBase und endpoint?)' });
+                return;
+            }
+            if (seq !== loadSeq)
+                return;
+            if (!Array.isArray(data)) {
+                set({ loading: false, loadError: 'Liste konnte nicht geladen werden (Antwort ist keine Liste)' });
+                return;
+            }
+            loadedOnce = true;
+            set({ rows: data, loading: false });
+        }
+        catch {
+            if (seq === loadSeq)
+                set({ loading: false, loadError: 'Server nicht erreichbar' });
+        }
+    }
+    async function save(mode) {
+        if (state.saving)
+            return;
+        const open = state.open;
+        if (!open)
+            return;
+        if (mode === 'edit' && options.editable === false) {
+            set({ saveError: 'Keine Berechtigung zum Ändern.' });
+            return;
+        }
+        if (!isComplete()) {
+            set({ saveError: 'Bitte alle Pflichtfelder ausfüllen.' });
+            return;
+        }
+        const invalid = options.validate?.(state.form, mode);
+        if (invalid) {
+            set({ saveError: invalid });
+            return;
+        }
+        let target;
+        let method;
+        if (mode === 'create') {
+            target = url();
+            method = 'POST';
+        }
+        else {
+            const id = open.item ? tryId(open.item) : null;
+            if (id === null) {
+                set({ saveError: open.item ? NO_ID : 'Kein Eintrag zum Speichern geöffnet.' });
+                return;
+            }
+            target = url(id);
+            method = options.updateMethod ?? 'PUT';
+        }
+        const payload = options.toPayload ? options.toPayload(state.form) : state.form;
+        set({ saving: true, saveError: '' });
+        try {
+            const res = await request(target, method, payload);
+            if (!res.ok) {
+                set({ saving: false, saveError: await errorMessage(res, 'Speichern fehlgeschlagen') });
+                return;
+            }
+        }
+        catch {
+            set({ saving: false, saveError: 'Server nicht erreichbar' });
+            return;
+        }
+        if (state.open === open)
+            set({ saving: false, open: null, form: options.emptyForm() });
+        else
+            set({ saving: false });
+        await load();
+    }
+    async function confirmDelete() {
+        const row = state.deleteTarget;
+        if (!row || state.deleting)
+            return;
+        const id = tryId(row);
+        if (id === null) {
+            set({ deleteError: NO_ID });
+            return;
+        }
+        set({ deleting: true, deleteError: '' });
+        try {
+            const res = await request(url(id), 'DELETE');
+            if (!res.ok) {
+                set({ deleting: false, deleteError: await errorMessage(res, 'Löschen fehlgeschlagen') });
+                return;
+            }
+        }
+        catch {
+            set({ deleting: false, deleteError: 'Server nicht erreichbar' });
+            return;
+        }
+        const openItem = state.open?.item;
+        const closeDialog = openItem !== undefined && tryId(openItem) === id;
+        set({ deleting: false, deleteTarget: null, ...(closeDialog ? { open: null } : {}) });
+        await load();
+    }
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setOptions(next) {
+            options = next;
+        },
+        load,
+        dismissLoadError() {
+            set({ loadError: '' });
+        },
+        openCreate() {
+            set({ open: { id: NEW_ID }, mode: 'create', form: options.emptyForm(), saveError: '' });
+        },
+        openRecord(row) {
+            const id = tryId(row);
+            if (id === null) {
+                console.error('useRecords: Eintrag ohne ID (getId angeben)', row);
+                set({ loadError: NO_ID });
+                return;
+            }
+            const mode = options.openIn === 'edit' && options.editable !== false ? 'edit' : 'read';
+            set({ open: { id, item: row }, mode, form: options.toForm(row), saveError: '' });
+        },
+        close() {
+            set({ open: null, saveError: '' });
+        },
+        setMode(mode) {
+            if (mode !== 'edit' || options.editable === false || !state.open?.item || state.mode === 'edit')
+                return;
+            set({ mode: 'edit' });
+        },
+        setForm(next) {
+            const form = typeof next === 'function' ? next(state.form) : next;
+            set({ form });
+        },
+        setField(key, value) {
+            set({ form: { ...state.form, [key]: value } });
+        },
+        isComplete,
+        save,
+        dismissSaveError() {
+            set({ saveError: '' });
+        },
+        requestDelete(row) {
+            set({ deleteTarget: row, deleteError: '' });
+        },
+        cancelDelete() {
+            if (state.deleting)
+                return;
+            set({ deleteTarget: null, deleteError: '' });
+        },
+        confirmDelete,
+        dismissDeleteError() {
+            set({ deleteError: '' });
+        },
+    };
+}

package/frontend/ui/styles.css

@@ -1,7 +1,7 @@
 /**
  * @efa-one/sdk/frontend/ui/styles.css
  *
- * Globale Hilfsklassen, die `Badge` und `Skeleton` aus dem SDK-ui-Kit benötigen
+ * Globale Hilfsklassen, die `Badge`, `Skeleton`, `Alert` und `Switch` aus dem SDK-ui-Kit benötigen
  * (sie sind CSS-Klassen-basiert, nicht Tailwind-Arbitrary). Einmal pro App
  * importieren:  import '@efa-one/sdk/frontend/ui/styles.css';
  *
@@ -110,3 +110,62 @@
   from { background-position: 200% 0; }
   to   { background-position: -200% 0; }
 }
+
+/* ── Switch (Schalter für Ein/Aus-Werte) ─────────────────────────
+ * Spur 36 × 20 px, Knopf 16 px. Aus-Zustand bewusst dunkler als
+ * `--color-border`: auf weißer Fläche wäre eine reine Rahmenfarbe kaum zu
+ * erkennen (WCAG 1.4.11 verlangt 3 : 1 für Bedienelemente). Die Mischung
+ * Richtung `--color-text-primary` wird im dunklen Theme automatisch heller.
+ * Gegen alle Built-in-Themes nachgerechnet (Spur auf surface/surface-raised,
+ * Knopf auf Spur): test/switch.test.ts. An-Zustand: Signalfarbe des Tons
+ * (`primary` bzw. `danger`) mit weißem Knopf — dieselbe Paarung wie der
+ * Primär-Button; der Zustand ist zusätzlich an der Knopf-Position erkennbar. */
+.switch {
+  position: relative;
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  width: 36px;
+  height: 20px;
+  padding: 0;
+  border: 2px solid transparent;
+  border-radius: 9999px;
+  background: color-mix(in srgb, var(--color-text-primary) 45%, var(--color-border));
+  cursor: pointer;
+  transition: background-color 150ms ease;
+}
+.switch-primary[data-state='checked'] { background: var(--color-primary); }
+.switch-danger[data-state='checked']  { background: var(--color-danger); }
+.switch:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.switch:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--color-surface), 0 0 0 4px var(--color-primary);
+}
+.switch-thumb {
+  display: block;
+  width: 16px;
+  height: 16px;
+  border-radius: 9999px;
+  background: #fff;
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.25);
+  transform: translateX(0);
+  transition: transform 150ms ease;
+  pointer-events: none;
+}
+.switch[data-state='checked'] .switch-thumb { transform: translateX(16px); }
+@media (prefers-reduced-motion: reduce) {
+  .switch, .switch-thumb { transition: none; }
+}
+/* Windows-Kontrastmodus ersetzt Hintergrundfarben durch Systemfarben — ohne
+ * diesen Block wären Spur und Knopf gleich und der Zustand unsichtbar. */
+@media (forced-colors: active) {
+  .switch { border-color: ButtonText; background: Canvas; }
+  .switch-thumb { background: ButtonText; box-shadow: none; }
+  .switch[data-state='checked'] { background: Highlight; }
+  .switch[data-state='checked'] .switch-thumb { background: HighlightText; }
+  .switch:disabled { border-color: GrayText; }
+  .switch:disabled .switch-thumb { background: GrayText; }
+}

package/frontend/ui/useRecords.d.ts

@@ -0,0 +1,22 @@
+import type { RecordDialogProps } from './RecordDialog.js';
+import type { ConfirmDeleteDialogProps } from './ConfirmDeleteDialog.js';
+import { type RecordsOptions } from './records.js';
+export interface UseRecordsResult<T, F> {
+    rows: T[];
+    loading: boolean;
+    loadError: string;
+    dismissLoadError(): void;
+    reload(): Promise<void>;
+    form: F;
+    setForm(next: F | ((prev: F) => F)): void;
+    setField<K extends keyof F>(key: K, value: F[K]): void;
+    current: T | null;
+    openCreate(): void;
+    openRecord(row: T): void;
+    close(): void;
+    dialogProps: Pick<RecordDialogProps, 'open' | 'onOpenChange' | 'mode' | 'onModeChange' | 'readOnly' | 'onSave' | 'saving' | 'saveDisabled' | 'error' | 'onErrorDismiss'>;
+    requestDelete(row: T): void;
+    deleteTarget: T | null;
+    deleteDialogProps: Pick<ConfirmDeleteDialogProps, 'open' | 'deleting' | 'error' | 'onConfirm' | 'onCancel' | 'onErrorDismiss'>;
+}
+export declare function useRecords<T, F>(options: RecordsOptions<T, F>): UseRecordsResult<T, F>;

package/frontend/ui/useRecords.js

@@ -0,0 +1,53 @@
+import { useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { createRecordsController, requiredFilled, } from './records.js';
+export function useRecords(options) {
+    const [controller] = useState(() => createRecordsController(options));
+    useEffect(() => {
+        controller.setOptions(options);
+    });
+    useEffect(() => {
+        void controller.load();
+    }, [controller, options.endpoint]);
+    const state = useSyncExternalStore(controller.subscribe, controller.getState, controller.getState);
+    const complete = requiredFilled(state.form, options.required);
+    const readOnly = options.editable === false;
+    return useMemo(() => ({
+        rows: state.rows,
+        loading: state.loading,
+        loadError: state.loadError,
+        dismissLoadError: controller.dismissLoadError,
+        reload: controller.load,
+        form: state.form,
+        setForm: controller.setForm,
+        setField: controller.setField,
+        current: state.open?.item ?? null,
+        openCreate: controller.openCreate,
+        openRecord: controller.openRecord,
+        close: controller.close,
+        dialogProps: {
+            open: state.open,
+            onOpenChange: (next) => {
+                if (!next)
+                    controller.close();
+            },
+            mode: readOnly && state.mode === 'edit' ? 'read' : state.mode,
+            onModeChange: controller.setMode,
+            readOnly,
+            onSave: controller.save,
+            saving: state.saving,
+            saveDisabled: !complete,
+            error: state.saveError,
+            onErrorDismiss: controller.dismissSaveError,
+        },
+        requestDelete: controller.requestDelete,
+        deleteTarget: state.deleteTarget,
+        deleteDialogProps: {
+            open: state.deleteTarget !== null,
+            deleting: state.deleting,
+            error: state.deleteError,
+            onConfirm: controller.confirmDelete,
+            onCancel: controller.cancelDelete,
+            onErrorDismiss: controller.dismissDeleteError,
+        },
+    }), [controller, state, complete, readOnly]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@efa-one/sdk",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Offizielles SDK für efa-one-Apps: Auth/Session, Service-Discovery, Gateway-Client, Audit/Reporting/Mail/Notifications, Permission- und Capability-Registrierung sowie das Frontend-IPC-/i18n-Toolkit.",
   "license": "Apache-2.0",
   "type": "commonjs",