@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

package/dist/hooks/use-reference-lookup.js

@@ -0,0 +1,63 @@
+// Tier 2.7e-4: Renderer-Side Eagerload für Reference-Felder.
+//
+// Pro Reference-Spalte einer Liste wird einmal `<feature>:query:
+// <refEntity>:list` (limit:200) gerufen, eine Map<uuid, displayValue>
+// gebaut, und der Renderer nutzt sie als Cell-Display-Renderer.
+//
+// Strategy-Trade-offs:
+//   - Server-side Drizzle-Joins wären effizienter (eine Query statt
+//     N+1), würden aber die executor-API um lookupTables erweitern
+//     müssen. Für das MVP geht der Renderer-Side-Pfad vor.
+//   - Limit:200 ist eine harte UX-Grenze: bei mehr Entries in der
+//     referenced Entity zeigen die letzten Rows nur noch UUIDs.
+//     Searchable-Combobox (Tier 2.1c) + Server-Eagerload mit
+//     ID-Whitelist heben das später auf.
+//
+// Dieser Hook ist call-stable: Lookup-Map wird durch useQuery's
+// internen Cache shared zwischen List + Edit-Form für die gleiche
+// Entity, Live-Updates kommen via SSE (use-query-live).
+import { REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useMemo } from "react";
+import { toKebab } from "../app/qn.js";
+import { useTranslation } from "../i18n.js";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "./reference-limits.js";
+import { useQuery } from "./use-query.js";
+/** Where a reference target's label rows come from: the central override for
+ *  that `feature:entity` if one exists, else the entity-convention list
+ *  handler plus the caller's own label field. */
+export function referenceLookupSource(refFeature, refEntity, labelField) {
+    const override = REFERENCE_LOOKUP_SOURCES[`${refFeature}:${refEntity}`];
+    if (override !== undefined)
+        return override;
+    return {
+        queryQn: `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`,
+        labelKey: labelField,
+    };
+}
+/** Empty while the query loads (or fails), so callers fall back to the raw id.
+ *  `featureName` is the reference's target feature, not the screen's. */
+export function useReferenceLookup(featureName, refEntity, labelField) {
+    const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
+    const result = useQuery(queryQn, {
+        limit: REFERENCE_LIST_LOOKUP_LIMIT,
+    });
+    const translate = useTranslation();
+    const systemLabel = SYSTEM_REFERENCE_LABELS[`${featureName}:${refEntity}`];
+    const map = useMemo(() => {
+        const out = new Map();
+        for (const row of result.data?.rows ?? []) {
+            const id = row["id"];
+            if (id === undefined || id === null)
+                continue;
+            const idStr = String(id);
+            const label = row[labelKey] ?? id;
+            out.set(idStr, String(label));
+        }
+        // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row, so
+        // the bulk lookup above never covers them — inject the label directly.
+        if (systemLabel !== undefined)
+            out.set(systemLabel.id, translate(systemLabel.labelKey));
+        return out;
+    }, [result.data, labelKey, systemLabel, translate]);
+    return { map, loading: result.loading };
+}

package/dist/hooks/use-store.d.ts

@@ -0,0 +1,3 @@
+import type { Store } from "@cosmicdrift/kumiko-headless";
+export declare function useStore<T>(store: Store<T>): T;
+export declare function useStoreSelector<T, S>(store: Store<T>, select: (snapshot: T) => S, equals?: (a: S, b: S) => boolean): S;

package/dist/hooks/use-store.js

@@ -0,0 +1,38 @@
+import { useRef, useSyncExternalStore } from "react";
+// React-Bindings für Kumikos Store-Primitive (`createStore` aus
+// @cosmicdrift/kumiko-headless). Beide Hooks sind dünne Wrapper um React's
+// useSyncExternalStore — die ganze Subscribe/Notify-Mechanik lebt im
+// Store selbst, hier wird nur React verdrahtet.
+//
+// useStore: gibt den ganzen Snapshot zurück. Re-rendert wenn der
+// Store seine Identität wechselt. Object.is-Gate im Store selbst
+// verhindert no-op-Updates.
+//
+// useStoreSelector: gibt eine abgeleitete Sicht zurück. Selectors die
+// Object-/Array-Literale zurückgeben (z.B. `s => ({ a, b })`) erzeugen
+// pro Render eine neue Identität — useSyncExternalStore würde das als
+// "Change" lesen und in eine Re-Render-Schleife laufen. Der dritte
+// Arg `equals` dient genau dafür: gleiche Auswahl → cached
+// Identität zurück, kein Re-Render.
+// @wrapper-known semantic-alias
+export function useStore(store) {
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+export function useStoreSelector(store, select, equals = Object.is) {
+    // Cache der letzten Auswahl. Beim nächsten getSnapshot-Call vergleicht
+    // der Wrapper die neu berechnete Auswahl mit dem Cache und gibt — falls
+    // gleich — die cached Identität zurück. Das ist der Trick, der
+    // Selector-Returns wie `s => ({ a, b })` stabil hält.
+    const lastSelected = useRef(undefined);
+    const initialized = useRef(false);
+    const getSelectedSnapshot = () => {
+        const next = select(store.getSnapshot());
+        if (initialized.current && equals(lastSelected.current, next)) {
+            return lastSelected.current;
+        }
+        lastSelected.current = next;
+        initialized.current = true;
+        return next;
+    };
+    return useSyncExternalStore(store.subscribe, getSelectedSnapshot, getSelectedSnapshot);
+}

package/dist/hooks/use-stream-handler.d.ts

@@ -0,0 +1,14 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+export type StreamStatus = "idle" | "streaming" | "done" | "error";
+export type UseStreamHandlerResult<TChunk> = {
+    readonly chunks: readonly TChunk[];
+    readonly status: StreamStatus;
+    readonly error: DispatcherError | null;
+    readonly start: (payload?: unknown) => Promise<void>;
+    readonly abort: () => void;
+    readonly reset: () => void;
+};
+export type UseStreamHandlerOptions = {
+    readonly autoStart?: boolean;
+};
+export declare function useStreamHandler<TChunk = unknown>(type: string, payload?: unknown, options?: UseStreamHandlerOptions): UseStreamHandlerResult<TChunk>;

package/dist/hooks/use-stream-handler.js

@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context.js";
+export function useStreamHandler(type, payload = {}, options = {}) {
+    const dispatcher = useDispatcher();
+    const { autoStart = false } = options;
+    const [chunks, setChunks] = useState([]);
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    const activeCtrl = useRef(null);
+    const payloadRef = useRef(payload);
+    payloadRef.current = payload;
+    const abort = useCallback(() => {
+        activeCtrl.current?.abort();
+        activeCtrl.current = null;
+        // User cancel — exit streaming so UI can re-enable the start button.
+        setStatus((s) => (s === "streaming" ? "idle" : s));
+    }, []);
+    const reset = useCallback(() => {
+        abort();
+        setChunks([]);
+        setStatus("idle");
+        setError(null);
+    }, [abort]);
+    // Shared by every abort-detection branch below: only touch status if this
+    // run is still the active one (or activeCtrl was already cleared by abort()).
+    const settleAborted = useCallback((ctrl) => {
+        if (activeCtrl.current === null || activeCtrl.current === ctrl)
+            setStatus("idle");
+    }, []);
+    const start = useCallback(async (overridePayload) => {
+        activeCtrl.current?.abort();
+        const ctrl = new AbortController();
+        activeCtrl.current = ctrl;
+        setChunks([]);
+        setError(null);
+        setStatus("streaming");
+        const body = overridePayload !== undefined ? overridePayload : payloadRef.current;
+        try {
+            for await (const chunk of dispatcher.stream(type, body, { signal: ctrl.signal })) {
+                // skip: a newer start() already superseded this run
+                if (ctrl.signal.aborted) {
+                    settleAborted(ctrl);
+                    return;
+                }
+                setChunks((prev) => [...prev, chunk]);
+            }
+            // skip: aborted after last chunk, don't mark done
+            if (ctrl.signal.aborted) {
+                settleAborted(ctrl);
+                return;
+            }
+            setStatus("done");
+        }
+        catch (e) {
+            // skip: abort is not an error toast
+            if (ctrl.signal.aborted) {
+                settleAborted(ctrl);
+                return;
+            }
+            const mapped = asDispatcherError(e);
+            // skip: dispatcher-mapped abort (fetch cancelled)
+            if (mapped.code === "aborted") {
+                settleAborted(ctrl);
+                return;
+            }
+            setError(mapped);
+            setStatus("error");
+        }
+    }, [dispatcher, type, settleAborted]);
+    useEffect(() => {
+        // skip: autoStart off — streams are usually user-triggered
+        if (!autoStart)
+            return;
+        void start();
+    }, [autoStart, start]);
+    useEffect(() => {
+        return () => {
+            activeCtrl.current?.abort();
+        };
+    }, []);
+    return { chunks, status, error, start, abort, reset };
+}
+function asDispatcherError(e) {
+    if (e && typeof e === "object" && "code" in e && "message" in e && "i18nKey" in e) {
+        return e;
+    }
+    return {
+        code: "stream_error",
+        httpStatus: 0,
+        i18nKey: "errors.unknown",
+        message: e instanceof Error ? e.message : String(e),
+    };
+}

package/dist/i18n-defaults.d.ts

@@ -0,0 +1,2 @@
+import type { TranslationsByLocale } from "./i18n.js";
+export declare const kumikoDefaultTranslations: TranslationsByLocale;

package/dist/i18n-defaults.js

@@ -0,0 +1,201 @@
+// Framework-Default-Bundle. Strings die die Renderer-Components hart
+// brauchen (Save/Cancel/Delete-Buttons, Empty-States, Search-Placeholder,
+// Nav-Toggle-aria-Labels, Validation-Reasons). createKumikoApp hängt das
+// als ALLERLETZTEN Fallback in den LocaleProvider — Apps können
+// einzelne Keys via clientFeatures.translations überschreiben.
+//
+// Convention: alle Keys mit `kumiko.`-Prefix damit sie nicht mit
+// App-Keys kollidieren. Sub-Pfade gruppieren nach Bereich (actions /
+// list / nav / form / validation).
+export const kumikoDefaultTranslations = {
+    en: {
+        "kumiko.actions.save": "Save",
+        "kumiko.actions.cancel": "Cancel",
+        "kumiko.actions.delete": "Delete",
+        "kumiko.actions.delete-confirm": "Confirm delete?",
+        "kumiko.actions.reload": "Reload",
+        "kumiko.actions.create": "New",
+        "kumiko.actions.edit": "Edit",
+        "kumiko.actions.view": "View",
+        "kumiko.actions.copyLink": "Copy link",
+        "kumiko.actions.copyLinkCopied": "Copied!",
+        "kumiko.actions.next": "Next",
+        "kumiko.actions.back": "Back",
+        "kumiko.actions.finish": "Finish",
+        "kumiko.wizard.step": "Step {current} of {total}",
+        "kumiko.wizard.step-with-title": "Step {current} of {total} · {title}",
+        "kumiko.version.update-available": "A new version is available.",
+        "kumiko.toast.learn-more": "Learn more",
+        "kumiko.field.open-calendar": "Open calendar",
+        "kumiko.field.dateField.placeholderYear": "Y",
+        "kumiko.field.dateField.placeholderMonth": "M",
+        "kumiko.field.dateField.placeholderDay": "D",
+        "kumiko.field.time": "Time",
+        "kumiko.field.timezone": "Time zone",
+        "kumiko.field.locatedTzHint": "Time local to the given location",
+        "kumiko.field.reference-created-no-id": "Record was created but could not be selected automatically. Please select it manually.",
+        "kumiko.field.unsupported": "This field type can't be edited here yet.",
+        "kumiko.field.embedded-list.add-row": "Add row",
+        "kumiko.field.embedded-list.remove-row": "Remove row",
+        "kumiko.field.embedded-list.duplicate-row": "Duplicate row",
+        "kumiko.field.embedded-list.move-up": "Move up",
+        "kumiko.field.embedded-list.move-down": "Move down",
+        "kumiko.field.embedded-list.empty": "No rows yet.",
+        "kumiko.field.embedded-list.empty-cta": "Add first row",
+        "kumiko.field.embedded-list.paste-rows-truncated": "{count} pasted row(s) were dropped (max row count reached).",
+        "kumiko.field.embedded-list.paste-cells-unmatched": "{count} cell(s) had no matching option and were left unchanged.",
+        "kumiko.field.multiSelect.select-all": "Select all",
+        "kumiko.field.multiSelect.deselect-all": "Deselect all",
+        "kumiko.list.search-placeholder": "Search…",
+        "kumiko.list.empty.title": "No entries yet.",
+        "kumiko.list.empty.hint": "Create the first one to get started.",
+        "kumiko.list.no-entries": "No entries.",
+        "kumiko.list.end-of-list": "— End of list —",
+        "kumiko.list.sort.label": "Sort",
+        "kumiko.list.sort.unsorted": "Unsorted",
+        "kumiko.list.filter.reset": "Reset",
+        "kumiko.list.filter.toggle": "Filters",
+        "kumiko.list.related-list-truncated": "Showing the first {count} entries. More are available but not loaded — this list does not paginate.",
+        "kumiko.reference.system-tenant": "System",
+        "kumiko.reference.system-user": "System",
+        "kumiko.pager.status": "{from}–{to} of {total}",
+        "kumiko.pager.pageOf": "Page {page} of {pages}",
+        "kumiko.form.all-required": "All fields are required.",
+        "kumiko.pager.status.noun": "{from}–{to} of {total} {noun}",
+        "kumiko.pager.pageSize": "{size} per page",
+        "kumiko.pager.pageSizeLabel": "Entries per page",
+        "kumiko.list.count.noun": "{count} {noun}",
+        "kumiko.list.count.one": "1 entry",
+        "kumiko.list.count.other": "{count} entries",
+        "kumiko.list.row-actions.more": "More actions",
+        "kumiko.list.sort.by": "Sorted by {column}",
+        "kumiko.form.changed": "changed",
+        "kumiko.form.on-this-page": "On this page",
+        "kumiko.form.unsaved.one": "1 unsaved change",
+        "kumiko.form.unsaved.other": "{count} unsaved changes",
+        "kumiko.wizard.next-with-title": "Next: {title}",
+        "kumiko.wizard.save-and-close": "Save and close",
+        "kumiko.pager.previousPage": "Previous page",
+        "kumiko.pager.nextPage": "Next page",
+        "kumiko.combobox.search-placeholder": "Search…",
+        "kumiko.combobox.empty": "No matches.",
+        "kumiko.combobox.loading": "Loading…",
+        "kumiko.combobox.placeholder": "—",
+        "kumiko.dashboard.filter.all": "All",
+        "kumiko.app-boot.loading": "Loading…",
+        "kumiko.app-boot.unauthorized": "You need to sign in to see this.",
+        "kumiko.app-boot.failed": "Couldn't load the app. Check your connection and try again.",
+        "kumiko.app-boot.no-open-screen": "This app has no screen that's accessible without a role restriction.",
+        "kumiko.widget.loading": "Loading…",
+        "kumiko.widget.error.title": "Couldn't load.",
+        "kumiko.widget.upload.uploading": "Uploading…",
+        "kumiko.widget.upload.done": "Uploaded",
+        "kumiko.widget.upload.error": "Failed",
+        "kumiko.widget.upload.rejected-type": "File type not allowed",
+        "kumiko.widget.step-bar.done": "Done",
+        "kumiko.widget.drawer.restore": "Restore drawer width",
+        "kumiko.widget.drawer.maximize": "Maximize drawer width",
+        "kumiko.widget.drawer.resize": "Resize drawer",
+        "kumiko.widget.floatingPanel.move": "Move panel",
+        "kumiko.widget.floatingPanel.resizeTop": "Resize panel from the top edge",
+        "kumiko.widget.floatingPanel.resizeRight": "Resize panel from the right edge",
+        "kumiko.widget.floatingPanel.resizeBottom": "Resize panel from the bottom edge",
+        "kumiko.widget.floatingPanel.resizeLeft": "Resize panel from the left edge",
+        "kumiko.planCard.current": "Current plan",
+        "kumiko.planCard.priceUnavailable": "Price not available",
+        "kumiko.nav.expand": "Expand",
+        "kumiko.nav.collapse": "Collapse",
+        "kumiko.nav.search": "Search navigation…",
+        "kumiko.nav.language": "Language",
+        "kumiko.workspace.switch": "Switch workspace",
+        // Workspace-Switcher fallback label when activeId points at no visible workspace.
+        "kumiko.workspace.select": "Select workspace",
+        "kumiko.dialog.confirm": "Confirm",
+        "kumiko.dialog.cancel": "Cancel",
+        "kumiko.dialog.close": "Close",
+        "kumiko.drawer.discard.title": "Discard changes?",
+        "kumiko.drawer.discard.body": "Your input in this form will be lost.",
+        "kumiko.drawer.discard.confirm": "Discard",
+        "kumiko.drawer.discard.cancel": "Keep editing",
+        "kumiko.aiText.acceptHint": "Tab = accept, Esc = discard",
+        "kumiko.aiText.correct": "Correct",
+        "kumiko.aiText.translate": "Translate",
+        "kumiko.aiText.rewrite": "Rewrite",
+        "kumiko.aiText.diff.before": "Before",
+        "kumiko.aiText.diff.after": "After",
+        "kumiko.aiText.diff.generating": "Generating…",
+        "kumiko.aiText.style.formal": "Formal",
+        "kumiko.aiText.style.casual": "Casual",
+        "kumiko.aiText.style.concise": "Concise",
+        "kumiko.aiText.style.expand": "Expand",
+        "kumiko.aiText.capExceeded": "Monthly AI limit reached.",
+        "kumiko.rowAction.failed": "Action failed",
+        "kumiko.contentEditor.insertVariable": "Insert {name}",
+        "kumiko.contentEditor.preview": "Preview",
+        "kumiko.contentEditor.editMode": "Edit",
+        "kumiko.contentEditor.bold": "Bold",
+        "kumiko.contentEditor.italic": "Italic",
+        "kumiko.contentEditor.heading1": "Heading 1",
+        "kumiko.contentEditor.heading2": "Heading 2",
+        "kumiko.contentEditor.bulletList": "Bullet list",
+        "kumiko.contentEditor.orderedList": "Numbered list",
+        "kumiko.config.source.user": "My value",
+        "kumiko.config.source.tenant": "Tenant",
+        "kumiko.config.source.system": "System",
+        "kumiko.config.source.appOverride": "App override",
+        "kumiko.config.source.computed": "Computed",
+        "kumiko.config.source.default": "Default",
+        "kumiko.config.source.missing": "Missing",
+        "kumiko.config.cascade.noValue": "No value set",
+        "kumiko.config.cascade.activeMarker": "active",
+        "kumiko.config.cascade.resetTo": "Reset override ({scope})",
+        "kumiko.form.error.generic": "Something went wrong.",
+        "kumiko.form.error.version-conflict": "Record was modified in the meantime. Reload and try again.",
+        "kumiko.form.extension.save-failed": "A custom field could not be saved.",
+        "kumiko.form.draft.resume-multiple": "Found multiple open drafts for this form. Which one do you want to resume?",
+        "kumiko.form.draft.resume-single": "Found an open draft for this form. Do you want to resume it?",
+        "kumiko.form.draft.start-new": "Start new",
+        "kumiko.secretMint.title": "Your new secret",
+        "kumiko.secretMint.warning": "Copy this now — it is shown only this once and cannot be retrieved later.",
+        "kumiko.secretMint.confirm": "I have copied it",
+        "kumiko.secretMint.copy": "Copy",
+        "kumiko.secretMint.copied": "Copied",
+        "kumiko.secretMint.done": "Done.",
+        "kumiko.validation.required": "Required.",
+        "kumiko.validation.invalid": "Invalid value.",
+        "kumiko.validation.too-short": "Too short (at least {min} characters).",
+        "kumiko.validation.too-long": "Too long (at most {max} characters).",
+        "kumiko.validation.out-of-range": "Value out of allowed range.",
+        "errors.validation.invalid_type": "Invalid value.",
+        "errors.validation.too_small": "Too small or too short (minimum: {minimum}).",
+        "errors.validation.too_big": "Too big or too long (maximum: {maximum}).",
+        "errors.validation.invalid_format": "Invalid format.",
+        "errors.validation.not_multiple_of": "Must be a multiple of {divisor}.",
+        "errors.validation.unrecognized_keys": "Unknown fields.",
+        "errors.validation.invalid_union": "Invalid value.",
+        "errors.validation.invalid_key": "Invalid key.",
+        "errors.validation.invalid_element": "Invalid entry.",
+        "errors.validation.invalid_value": "Invalid choice.",
+        "errors.validation.custom": "Invalid value.",
+        "errors.validation.unexpected_field": "Unknown field.",
+        "errors.validation.out_of_bounds": "Value out of allowed range.",
+        "errors.validation.invalid_option": "Invalid choice.",
+        "errors.validation.failed": "Validation failed.",
+        "errors.feature.disabled": "This feature is currently unavailable.",
+        "errors.access.denied": "You don't have permission to do this.",
+        "errors.notFound": "Not found.",
+        "errors.conflict": "Conflict — the operation could not be completed.",
+        "errors.versionConflict": "The record was modified in the meantime. Reload and try again.",
+        "errors.preconditionFailed": "The record changed in the meantime. Reload and try again.",
+        "errors.uniqueViolation": "This entry already exists.",
+        "errors.unprocessable": "The request could not be processed.",
+        "errors.unconfigured": "This feature isn't configured yet.",
+        "errors.internal": "Something went wrong. Please try again later.",
+        "errors.rate_limited": "Too many requests. Please try again shortly.",
+        "errors.cap.exceeded": "Limit reached. Upgrade your plan or wait for the next period.",
+        "errors.download.urlMissing": "Download unavailable — please try again.",
+        "auth.errors.originNotAllowed": "Requests from this origin are not allowed.",
+        "dispatcher.errors.network": "Network error. Please check your connection and try again.",
+        "dispatcher.errors.aborted": "Request was cancelled.",
+    },
+};

package/dist/i18n.d.ts

@@ -0,0 +1,64 @@
+import { type Formality, type TranslationValue } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+/** Map of i18n key → TranslationValue. Strings may contain `{name}`
+ *  placeholders (same semantics as i18next t); plural entries resolve via
+ *  `resolveTranslationValue`. */
+export type TranslationBundle = Readonly<Record<string, TranslationValue>>;
+/** Map von Locale-Code (BCP-47, z.B. `"de"`, `"en-US"`) → Bundle. */
+export type TranslationsByLocale = Readonly<Record<string, TranslationBundle>>;
+/** Key-first shape for `r.translations({ keys })` — each key maps locale → TranslationValue. */
+export type TranslationsByKey = Readonly<Record<string, Readonly<Record<string, TranslationValue>>>>;
+/** Pivot key-first server translations to locale-first client bundles. */
+export declare function translationsByLocaleFromKeys(source: TranslationsByKey): TranslationsByLocale;
+/** Merged zwei TranslationsByLocale-Maps — der override gewinnt pro Key,
+ *  die Locales werden zusammengeführt. Standard-Baustein für Client-
+ *  Plugins, die App-Overrides über ihre Default-Bundles legen. */
+export declare function mergeTranslations(base: TranslationsByLocale, override: TranslationsByLocale): TranslationsByLocale;
+export type LocaleProviderProps = {
+    readonly resolver: LocaleResolver;
+    /** Default bundles supplied by feature plugins. Lookup order per key:
+     *  (1) app resolver, (2) these bundles in array order, (3) key as-is.
+     *  Apps can thus override individual keys without swapping out whole
+     *  feature bundles. */
+    readonly fallbackBundles?: readonly TranslationsByLocale[];
+    /** Falls back to fallbackLocale when neither the current-locale nor the
+     *  key lookup hits in a plugin bundle. Default: `"en"`. */
+    readonly fallbackLocale?: string;
+    readonly children: ReactNode;
+};
+export declare function LocaleProvider({ resolver, fallbackBundles, fallbackLocale, children, }: LocaleProviderProps): ReactNode;
+/** Liefert den aktuellen LocaleResolver und abonniert automatisch
+ *  Locale-Änderungen — der aufrufende Component re-rendert sobald die
+ *  Sprache gewechselt wird. Wirft wenn kein Provider im Baum ist. */
+export declare function useLocale(): LocaleResolver;
+/** `t("key", params)` resolves in this order:
+ *    1. App resolver (e.g. i18next)
+ *    2. Plugin fallback bundles for the current locale (under a "formal"
+ *       FormalityProvider, `<locale>-x-formal` across all bundles first)
+ *    3. Plugin fallback bundles for fallbackLocale
+ *    4. The key as-is
+ *  `{name}` interpolation applies to every source, fallback strings included. */
+export declare function useTranslation(): (key: string, params?: Readonly<Record<string, unknown>>) => string;
+/** Wording for the subtree: `formal` makes `t` prefer the `<locale>-x-formal`
+ *  bundle entries (e.g. "Sie" on public pages) over plain `<locale>`. */
+export declare function FormalityProvider({ formality, children, }: {
+    readonly formality: Formality;
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function useFormality(): Formality;
+/** Non-throwing LocaleContext read — undefined outside LocaleProvider.
+ *  Used by DataTable FormatCell so plain tables without a provider do not crash. */
+export declare function useOptionalLocale(): string | undefined;
+/** Non-throwing time-zone read — "UTC" outside LocaleProvider, matching
+ *  createStaticLocaleResolver's own default. */
+export declare function useOptionalTimeZone(): string;
+/** Non-throwing translate — undefined outside LocaleProvider. */
+export declare function useOptionalTranslation(): ((key: string, params?: Readonly<Record<string, unknown>>) => string) | undefined;
+/** Default-Resolver für Apps ohne eigene i18n-Schicht. Gibt jeden Key
+ *  unverändert zurück — die Plugin-Fallback-Bundles erledigen dann die
+ *  echte Übersetzung. Nützlich auch als Basis für Tests. */
+export declare function createStaticLocaleResolver(options?: {
+    readonly locale?: string;
+    readonly timeZone?: string;
+}): LocaleResolver;

package/dist/i18n.js

@@ -0,0 +1,166 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Locale handling for React consumers of the Kumiko renderer. A thin layer
+// around the platform-agnostic `LocaleResolver` contract from
+// @cosmicdrift/kumiko-headless: provider, hooks, a default no-op resolver,
+// and a fallback-bundle merge for feature-supplied translations.
+//
+// Architecture:
+//   1. The app supplies exactly one `LocaleResolver` via `<LocaleProvider>`
+//      (or none at all → the default resolver returns keys as-is).
+//   2. Feature plugins may bring fallback bundles: when the app resolver
+//      can't resolve a key, `useTranslation` tries the plugin bundles.
+//      This keeps feature UI independent of the app's own i18next instance
+//      and works out of the box, while staying fully overridable.
+//   3. Re-render on locale change via `useSyncExternalStore` on the
+//      resolver's `subscribe()` — app code can switch language mid-session
+//      without a reload.
+import { formalLocaleTag, resolveTranslationValue, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { createContext, useCallback, useContext, useMemo, useSyncExternalStore, } from "react";
+/** Pivot key-first server translations to locale-first client bundles. */
+export function translationsByLocaleFromKeys(source) {
+    const out = {};
+    for (const [key, byLocale] of Object.entries(source)) {
+        for (const [locale, value] of Object.entries(byLocale)) {
+            out[locale] ??= {};
+            out[locale][key] = value;
+        }
+    }
+    return out;
+}
+/** Merged zwei TranslationsByLocale-Maps — der override gewinnt pro Key,
+ *  die Locales werden zusammengeführt. Standard-Baustein für Client-
+ *  Plugins, die App-Overrides über ihre Default-Bundles legen. */
+export function mergeTranslations(base, override) {
+    const locales = new Set([...Object.keys(base), ...Object.keys(override)]);
+    const merged = {};
+    for (const locale of locales) {
+        merged[locale] = { ...(base[locale] ?? {}), ...(override[locale] ?? {}) };
+    }
+    return merged;
+}
+const LocaleContext = createContext(undefined);
+const FormalityContext = createContext("informal");
+// Stabile Referenz statt `fallbackBundles = []` als Default-Parameter:
+// ein Literal-Default wird bei JEDEM Aufruf neu allokiert und würde die
+// useMemo-Referenzprüfung im Provider unten aushebeln, sobald der
+// Aufrufer fallbackBundles weglässt.
+const EMPTY_FALLBACK_BUNDLES = [];
+export function LocaleProvider({ resolver, fallbackBundles = EMPTY_FALLBACK_BUNDLES, fallbackLocale = "en", children, }) {
+    // Without memoization every re-render of the provider (e.g. because an
+    // ancestor component re-renders) builds a new context-value object —
+    // every consumer of useTranslation()/useLocale() then sees a new `ctx`
+    // reference and, even with useCallback memoization, a new `t`.
+    // Consequence: `t` in a useEffect dependency array triggers an infinite
+    // loop (see admin-shell Overview screens, prod incident).
+    const value = useMemo(() => ({ resolver, fallbackBundles, fallbackLocale }), [resolver, fallbackBundles, fallbackLocale]);
+    return _jsx(LocaleContext.Provider, { value: value, children: children });
+}
+/** Liefert den aktuellen LocaleResolver und abonniert automatisch
+ *  Locale-Änderungen — der aufrufende Component re-rendert sobald die
+ *  Sprache gewechselt wird. Wirft wenn kein Provider im Baum ist. */
+export function useLocale() {
+    const ctx = useContext(LocaleContext);
+    if (ctx === undefined) {
+        throw new Error("useLocale must be used inside <LocaleProvider>");
+    }
+    // Subscribe + current locale-snapshot. Wir brauchen den Rückgabewert
+    // selbst nicht — wichtig ist nur der re-render-trigger.
+    useSyncExternalStore(ctx.resolver.subscribe, () => ctx.resolver.locale(), () => ctx.resolver.locale());
+    return ctx.resolver;
+}
+/** `t("key", params)` resolves in this order:
+ *    1. App resolver (e.g. i18next)
+ *    2. Plugin fallback bundles for the current locale (under a "formal"
+ *       FormalityProvider, `<locale>-x-formal` across all bundles first)
+ *    3. Plugin fallback bundles for fallbackLocale
+ *    4. The key as-is
+ *  `{name}` interpolation applies to every source, fallback strings included. */
+export function useTranslation() {
+    const ctx = useContext(LocaleContext);
+    if (ctx === undefined) {
+        throw new Error("useTranslation must be used inside <LocaleProvider>");
+    }
+    // Re-Render bei Sprach-Wechsel. `ctx.resolver.subscribe` ist bereits
+    // eine stable-reference aus dem Resolver, daher hier keine eigene
+    // Memoization der Subscribe-Callback nötig.
+    const locale = useSyncExternalStore(ctx.resolver.subscribe, () => ctx.resolver.locale(), () => ctx.resolver.locale());
+    // `t` MUSS referenz-stabil sein solange sich Resolver/Bundles/Locale
+    // nicht ändern — Consumer nutzen `t` regelmäßig in useEffect-Deps
+    // (z.B. um Queries neu zu laden wenn sich die Sprache ändert). Ein neu
+    // erzeugtes `t` pro Render führt sonst zu einem Render/Effect-Endlos-
+    // Loop (siehe admin-shell Overview-Screens, Prod-Incident 2026-07-07).
+    const formality = useContext(FormalityContext);
+    return useCallback((key, params) => translateWithFallbacks(ctx, locale, formality, key, params), [ctx, locale, formality]);
+}
+/** Wording for the subtree: `formal` makes `t` prefer the `<locale>-x-formal`
+ *  bundle entries (e.g. "Sie" on public pages) over plain `<locale>`. */
+export function FormalityProvider({ formality, children, }) {
+    return _jsx(FormalityContext.Provider, { value: formality, children: children });
+}
+export function useFormality() {
+    return useContext(FormalityContext);
+}
+// Lookup order: (1) app resolver — it returns the key itself when it has no
+// entry, which is the invitation to try the plugin bundles; (2) the bundles in
+// array order per locale tier; (3) the key as-is. Under "formal" the formal
+// tier is searched across ALL bundles before any plain tier, so a plain "de"
+// app override never puts "du" on a formal page when locale-de has a formal
+// variant; an app rewording such a key must also ship its "de-x-formal" text.
+function translateWithFallbacks(ctx, locale, formality, key, params) {
+    const resolved = ctx.resolver.translate(key, params);
+    if (resolved !== key)
+        return resolved;
+    for (const localesToTry of bundleLocaleTiers(locale, ctx.fallbackLocale, formality)) {
+        for (const bundle of ctx.fallbackBundles) {
+            for (const localeToTry of localesToTry) {
+                const value = bundle[localeToTry]?.[key];
+                if (value !== undefined)
+                    return resolveTranslationValue(value, localeToTry, params);
+            }
+        }
+    }
+    return key;
+}
+function bundleLocaleTiers(locale, fallbackLocale, formality) {
+    const languageRoot = locale.split("-")[0] ?? locale;
+    const plainTier = [locale, languageRoot, fallbackLocale];
+    if (formality === "informal")
+        return [plainTier];
+    return [[formalLocaleTag(locale), formalLocaleTag(languageRoot)], plainTier];
+}
+/** Non-throwing LocaleContext read — undefined outside LocaleProvider.
+ *  Used by DataTable FormatCell so plain tables without a provider do not crash. */
+export function useOptionalLocale() {
+    const ctx = useContext(LocaleContext);
+    useSyncExternalStore((onStoreChange) => (ctx ? ctx.resolver.subscribe(onStoreChange) : () => { }), () => (ctx ? ctx.resolver.locale() : "en"), () => (ctx ? ctx.resolver.locale() : "en"));
+    return ctx === undefined ? undefined : ctx.resolver.locale();
+}
+/** Non-throwing time-zone read — "UTC" outside LocaleProvider, matching
+ *  createStaticLocaleResolver's own default. */
+export function useOptionalTimeZone() {
+    const ctx = useContext(LocaleContext);
+    return useSyncExternalStore((onStoreChange) => (ctx ? ctx.resolver.subscribe(onStoreChange) : () => { }), () => (ctx ? ctx.resolver.timeZone() : "UTC"), () => (ctx ? ctx.resolver.timeZone() : "UTC"));
+}
+/** Non-throwing translate — undefined outside LocaleProvider. */
+export function useOptionalTranslation() {
+    const ctx = useContext(LocaleContext);
+    const locale = useSyncExternalStore((onStoreChange) => (ctx ? ctx.resolver.subscribe(onStoreChange) : () => { }), () => (ctx ? ctx.resolver.locale() : "en"), () => (ctx ? ctx.resolver.locale() : "en"));
+    const formality = useContext(FormalityContext);
+    const t = useCallback((key, params) => ctx === undefined ? key : translateWithFallbacks(ctx, locale, formality, key, params), [ctx, locale, formality]);
+    return ctx === undefined ? undefined : t;
+}
+/** Default-Resolver für Apps ohne eigene i18n-Schicht. Gibt jeden Key
+ *  unverändert zurück — die Plugin-Fallback-Bundles erledigen dann die
+ *  echte Übersetzung. Nützlich auch als Basis für Tests. */
+export function createStaticLocaleResolver(options = {}) {
+    const locale = options.locale ?? "en";
+    const timeZone = options.timeZone ?? "UTC";
+    return {
+        translate: (key) => key,
+        locale: () => locale,
+        timeZone: () => timeZone,
+        // No-op subscribe: unsere Locale ist statisch, es gibt nie ein
+        // Change-Event. Unsubscribe ist ebenfalls no-op.
+        subscribe: () => () => { },
+    };
+}