@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

package/src/hooks/use-stream-handler.ts

@@ -1,134 +0,0 @@
-import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context";
-
-// React wrapper around dispatcher.stream (#1382). Accumulates yielded
-// chunks into `chunks` (unlike useQuery({live:true}), which only
-// invalidates and re-fetches). Each start() owns an AbortController;
-// a newer start() / unmount aborts the previous run so late chunks
-// cannot clobber fresher state.
-
-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 = {
-  // When true, start() runs once on mount with the initial payload.
-  // Default false — streams are usually user-triggered (unlike queries).
-  readonly autoStart?: boolean;
-};
-
-export function useStreamHandler<TChunk = unknown>(
-  type: string,
-  payload: unknown = {},
-  options: UseStreamHandlerOptions = {},
-): UseStreamHandlerResult<TChunk> {
-  const dispatcher = useDispatcher();
-  const { autoStart = false } = options;
-
-  const [chunks, setChunks] = useState<readonly TChunk[]>([]);
-  const [status, setStatus] = useState<StreamStatus>("idle");
-  const [error, setError] = useState<DispatcherError | null>(null);
-
-  const activeCtrl = useRef<AbortController | null>(null);
-  const payloadRef = useRef(payload);
-  payloadRef.current = payload;
-
-  const abort = useCallback((): void => {
-    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((): void => {
-    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: AbortController): void => {
-    if (activeCtrl.current === null || activeCtrl.current === ctrl) setStatus("idle");
-  }, []);
-
-  const start = useCallback(
-    async (overridePayload?: unknown): Promise<void> => {
-      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<TChunk>(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: unknown): DispatcherError {
-  if (e && typeof e === "object" && "code" in e && "message" in e && "i18nKey" in e) {
-    return e as DispatcherError;
-  }
-  return {
-    code: "stream_error",
-    httpStatus: 0,
-    i18nKey: "errors.unknown",
-    message: e instanceof Error ? e.message : String(e),
-  };
-}

package/src/i18n-defaults.ts

@@ -1,240 +0,0 @@
-// 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).
-
-import type { TranslationsByLocale } from "./i18n";
-
-export const kumikoDefaultTranslations: TranslationsByLocale = {
-  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/src/i18n.tsx

@@ -1,286 +0,0 @@
-// 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 {
-  type Formality,
-  formalLocaleTag,
-  resolveTranslationValue,
-  type TranslationValue,
-} from "@cosmicdrift/kumiko-framework/ui-types";
-import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
-import {
-  createContext,
-  type ReactNode,
-  useCallback,
-  useContext,
-  useMemo,
-  useSyncExternalStore,
-} 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 function translationsByLocaleFromKeys(source: TranslationsByKey): TranslationsByLocale {
-  const out: Record<string, Record<string, TranslationValue>> = {};
-  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: TranslationsByLocale,
-  override: TranslationsByLocale,
-): TranslationsByLocale {
-  const locales = new Set([...Object.keys(base), ...Object.keys(override)]);
-  const merged: Record<string, Record<string, TranslationValue>> = {};
-  for (const locale of locales) {
-    merged[locale] = { ...(base[locale] ?? {}), ...(override[locale] ?? {}) };
-  }
-  return merged;
-}
-
-type LocaleContextValue = {
-  readonly resolver: LocaleResolver;
-  readonly fallbackBundles: readonly TranslationsByLocale[];
-  readonly fallbackLocale: string;
-};
-
-const LocaleContext = createContext<LocaleContextValue | undefined>(undefined);
-const FormalityContext = createContext<Formality>("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: readonly 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 function LocaleProvider({
-  resolver,
-  fallbackBundles = EMPTY_FALLBACK_BUNDLES,
-  fallbackLocale = "en",
-  children,
-}: LocaleProviderProps): ReactNode {
-  // 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 <LocaleContext.Provider value={value}>{children}</LocaleContext.Provider>;
-}
-
-/** 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(): LocaleResolver {
-  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(): (
-  key: string,
-  params?: Readonly<Record<string, unknown>>,
-) => string {
-  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: string, params?: Readonly<Record<string, unknown>>): string =>
-      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,
-}: {
-  readonly formality: Formality;
-  readonly children: ReactNode;
-}): ReactNode {
-  return <FormalityContext.Provider value={formality}>{children}</FormalityContext.Provider>;
-}
-
-export function useFormality(): Formality {
-  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: LocaleContextValue,
-  locale: string,
-  formality: Formality,
-  key: string,
-  params?: Readonly<Record<string, unknown>>,
-): string {
-  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: string,
-  fallbackLocale: string,
-  formality: Formality,
-): readonly (readonly string[])[] {
-  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(): string | undefined {
-  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(): string {
-  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():
-  | ((key: string, params?: Readonly<Record<string, unknown>>) => string)
-  | undefined {
-  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: string, params?: Readonly<Record<string, unknown>>): string =>
-      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: { readonly locale?: string; readonly timeZone?: string } = {},
-): LocaleResolver {
-  const locale = options.locale ?? "en";
-  const timeZone = options.timeZone ?? "UTC";
-  return {
-    translate: (key: string) => key,
-    locale: () => locale,
-    timeZone: () => timeZone,
-    // No-op subscribe: unsere Locale ist statisch, es gibt nie ein
-    // Change-Event. Unsubscribe ist ebenfalls no-op.
-    subscribe: () => () => {},
-  };
-}