@cosmicdrift/kumiko-renderer 1.0.0 → 2.0.0

package/src/i18n.tsx

@@ -16,7 +16,14 @@
 //      Session die Sprache umschalten ohne Reload.
 
 import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
-import { createContext, type ReactNode, useContext, useSyncExternalStore } from "react";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useSyncExternalStore,
+} from "react";
 
 /** Map von i18n-Key → Template-String. Templates dürfen `{name}`-
  *  Platzhalter enthalten — identische Semantik zu i18next-t. */
@@ -25,6 +32,21 @@ export type TranslationBundle = Readonly<Record<string, string>>;
 /** 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 → string. */
+export type TranslationsByKey = Readonly<Record<string, Readonly<Record<string, string>>>>;
+
+/** Pivot key-first server translations to locale-first client bundles. */
+export function translationsByLocaleFromKeys(source: TranslationsByKey): TranslationsByLocale {
+  const out: Record<string, Record<string, string>> = {};
+  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. */
@@ -48,6 +70,12 @@ type LocaleContextValue = {
 
 const LocaleContext = createContext<LocaleContextValue | undefined>(undefined);
 
+// 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;
   /** Von Feature-Plugins gelieferte Default-Bundles. Lookup-Reihenfolge
@@ -64,15 +92,21 @@ export type LocaleProviderProps = {
 
 export function LocaleProvider({
   resolver,
-  fallbackBundles = [],
+  fallbackBundles = EMPTY_FALLBACK_BUNDLES,
   fallbackLocale = "en",
   children,
 }: LocaleProviderProps): ReactNode {
-  return (
-    <LocaleContext.Provider value={{ resolver, fallbackBundles, fallbackLocale }}>
-      {children}
-    </LocaleContext.Provider>
+  // Ohne Memoization baut jeder Re-Render des Providers (z.B. weil ein
+  // Ahnen-Component neu rendert) ein neues Context-Value-Objekt — jeder
+  // Consumer von useTranslation()/useLocale() sieht dann eine neue `ctx`-
+  // Referenz und damit selbst mit useCallback-Memoization einen neuen `t`.
+  // Konsequenz: `t` in einem useEffect-Dependency-Array triggert einen
+  // Endlos-Loop (siehe 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
@@ -112,38 +146,45 @@ export function useTranslation(): (
   // 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.
-  useSyncExternalStore(
+  const locale = useSyncExternalStore(
     ctx.resolver.subscribe,
     () => ctx.resolver.locale(),
     () => "en",
   );
 
-  return (key, params) => {
-    // 1. App-provided resolver zuerst. Convention: wenn der App-Resolver
-    //    den Key nicht kennt, gibt er den Key zurück — das ist die
-    //    Fallback-Einladung an Plugin-Bundles. i18next verhält sich
-    //    exakt so per default.
-    const resolved = ctx.resolver.translate(key, params);
-    if (resolved !== key) return resolved;
-
-    // 2. + 3. Plugin-Bundles durchlaufen für current + fallback-locale.
-    const currentLocale = ctx.resolver.locale();
-    const primaryLookup = currentLocale;
-    // `primaryLookup` könnte z.B. "de-AT" sein — in den Bundles stehen
-    // oft nur die Language-Roots ("de"). Wir versuchen beide.
-    const languageRoot = primaryLookup.split("-")[0] ?? primaryLookup;
-    const localesToTry = [primaryLookup, languageRoot, ctx.fallbackLocale];
-
-    for (const bundle of ctx.fallbackBundles) {
-      for (const locale of localesToTry) {
-        const value = bundle[locale]?.[key];
-        if (value !== undefined) return interpolate(value, params);
+  // `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).
+  return useCallback(
+    (key: string, params?: Readonly<Record<string, unknown>>): string => {
+      // 1. App-provided resolver zuerst. Convention: wenn der App-Resolver
+      //    den Key nicht kennt, gibt er den Key zurück — das ist die
+      //    Fallback-Einladung an Plugin-Bundles. i18next verhält sich
+      //    exakt so per default.
+      const resolved = ctx.resolver.translate(key, params);
+      if (resolved !== key) return resolved;
+
+      // 2. + 3. Plugin-Bundles durchlaufen für current + fallback-locale.
+      const primaryLookup = locale;
+      // `primaryLookup` könnte z.B. "de-AT" sein — in den Bundles stehen
+      // oft nur die Language-Roots ("de"). Wir versuchen beide.
+      const languageRoot = primaryLookup.split("-")[0] ?? primaryLookup;
+      const localesToTry = [primaryLookup, languageRoot, ctx.fallbackLocale];
+
+      for (const bundle of ctx.fallbackBundles) {
+        for (const localeToTry of localesToTry) {
+          const value = bundle[localeToTry]?.[key];
+          if (value !== undefined) return interpolate(value, params);
+        }
       }
-    }
 
-    // 4. Nichts gefunden — key zurück, wie der Default-Resolver auch.
-    return key;
-  };
+      // 4. Nichts gefunden — key zurück, wie der Default-Resolver auch.
+      return key;
+    },
+    [ctx, locale],
+  );
 }
 
 function interpolate(template: string, params?: Readonly<Record<string, unknown>>): string {

package/src/index.ts

@@ -18,6 +18,8 @@ export type {
 export { ColumnRenderersProvider, useColumnRenderer } from "./app/column-renderers";
 export type { CustomScreensMap, CustomScreensProviderProps } from "./app/custom-screens";
 export { CustomScreensProvider, useCustomScreenComponent } from "./app/custom-screens";
+export type { DashboardBodyProps, DashboardBodyProviderProps } from "./app/dashboard-body";
+export { DashboardBodyProvider, useDashboardBody } from "./app/dashboard-body";
 export type {
   ExtensionFormRegistry,
   ExtensionFormSubmitHandler,
@@ -57,11 +59,27 @@ export {
   useDispatcherStatus,
   useOptionalDispatcher,
 } from "./context/dispatcher-context";
+export type { UserRolesProviderProps } from "./context/user-roles-context";
+export { UserRolesProvider, useUserRoles } from "./context/user-roles-context";
+export { formatWhen } from "./format-when";
 export {
   REFERENCE_COMBOBOX_LIMIT,
   REFERENCE_LIST_LOOKUP_LIMIT,
   REFERENCE_SEARCH_DEBOUNCE_MS,
 } from "./hooks/reference-limits";
+export type {
+  AiTextActionState,
+  AiTextMode,
+  AiTextRewriteStyle,
+  AiTextRunPayload,
+  AiTextRunResult,
+  AiTextUsage,
+  UseAiTextActionResult,
+  UseCompletionResult,
+} from "./hooks/use-ai-text";
+export { AI_TEXT_RUN_QN, useAiTextAction, useCompletion } from "./hooks/use-ai-text";
+export type { UseDisclosureResult } from "./hooks/use-disclosure";
+export { useDisclosure } from "./hooks/use-disclosure";
 export type { UseFormOptions, UseFormResult } from "./hooks/use-form";
 export { useForm } from "./hooks/use-form";
 export type {
@@ -71,18 +89,28 @@ export type {
   ListUrlStateApi,
 } from "./hooks/use-list-url-state";
 export { useListUrlState } from "./hooks/use-list-url-state";
+export type { UseMutationResult } from "./hooks/use-mutation";
+export { useMutation } from "./hooks/use-mutation";
 export type { UseQueryOptions, UseQueryResult } from "./hooks/use-query";
 export { useQuery } from "./hooks/use-query";
 export { useStore, useStoreSelector } from "./hooks/use-store";
+export type {
+  StreamStatus,
+  UseStreamHandlerOptions,
+  UseStreamHandlerResult,
+} from "./hooks/use-stream-handler";
+export { useStreamHandler } from "./hooks/use-stream-handler";
 export type {
   LocaleProviderProps,
   TranslationBundle,
+  TranslationsByKey,
   TranslationsByLocale,
 } from "./i18n";
 export {
   createStaticLocaleResolver,
   LocaleProvider,
   mergeTranslations,
+  translationsByLocaleFromKeys,
   useLocale,
   useTranslation,
 } from "./i18n";
@@ -108,6 +136,8 @@ export type {
   GridProps,
   HeadingProps,
   InputProps,
+  LightboxProps,
+  LinkProps,
   PrimitivesProviderProps,
   PrimitivesRegistry,
   RuntimeRenderer,
@@ -115,6 +145,7 @@ export type {
   TextProps,
 } from "./primitives";
 export { PrimitivesProvider, usePrimitives } from "./primitives";
+export { sortByAccessor } from "./sort-by-accessor";
 export type { LiveEvent, LiveEventSubscriber, LiveEventsProviderProps } from "./sse/live-events";
 export { LiveEventsProvider, useLiveEvents } from "./sse/live-events";
 export type {

package/src/primitives.tsx

@@ -66,8 +66,35 @@ export type ButtonProps = {
   readonly loading?: boolean;
   /** Semantische Klasse — default="primary". Custom-Impls entscheiden
    *  was daraus visuell wird; die Renderer verwenden "primary" für
-   *  Save, "danger" für Delete, "secondary" für Confirm-State. */
-  readonly variant?: "primary" | "secondary" | "danger";
+   *  Save, "danger" für Delete, "secondary" für Confirm-State,
+   *  "link" für Inline-Aktionen im Fließtext (kein BG, underline). */
+  readonly variant?: "primary" | "secondary" | "danger" | "link";
+  /** Größe — default="md". "sm" für kompakte Inline-Aktionen (Toolbar,
+   *  Listen-Zeilen), "icon" für quadratische Icon-only-Buttons. */
+  readonly size?: "sm" | "md" | "icon";
+  /** Barrierefreies Label — Pflicht bei icon-only-Buttons (children ist nur
+   *  ein Icon/Zeichen), sonst hat der Button keinen zugänglichen Namen. */
+  readonly ariaLabel?: string;
+  /** Breite — default="auto" (inhaltsbreit). "full" streckt CTA-Buttons auf
+   *  die Container-Breite (Karten/Panels). Andere Breiten sind Layout-Sache
+   *  des Containers, kein Button-Prop (Kit hält arbiträres Sizing draußen). */
+  readonly width?: "full" | "auto";
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
+/** Navigations-Link. `variant="button"` rendert die Button-Optik auf einem
+ *  semantischen Anchor (z.B. „Zum Login" nach Reset-Success), `muted` den
+ *  dezenten Sekundär-Link. Interne SPA-Navigation läuft über den Browser-
+ *  Default (History-Integration liegt beim Nav-Layer, nicht am Primitive). */
+export type LinkProps = {
+  readonly href: string;
+  readonly variant?: "default" | "button" | "muted";
+  /** `_blank` setzt in der Web-Impl automatisch rel="noreferrer". */
+  readonly target?: "_blank";
+  /** Layout-Zusätze (self-center, text-xs) — Web merged via cn(),
+   *  Native-Impls ignorieren es (Präzedenz: CardProps.className). */
+  readonly className?: string;
   readonly children: ReactNode;
   readonly testId?: string;
 };
@@ -125,6 +152,12 @@ export type InputProps =
       /** Browser-Autofill / Native-Keyboard-Hint. Web setzt das auf
        *  `<input autocomplete=...>`, Native auf `textContentType`. */
       readonly autoComplete?: string;
+      /** `data-testid` aufs echte `<input>` — App-Tests adressieren das
+       *  Element direkt (getByTestId + readOnly/disabled-Assertions). */
+      readonly testId?: string;
+      /** Read-only Input (z.B. gewürfelter Free-Tier-Slug). Nicht `disabled`
+       *  — bleibt fokussier-/kopierbar. */
+      readonly readOnly?: boolean;
     }
   | {
       readonly kind: "email";
@@ -139,6 +172,7 @@ export type InputProps =
       /** Default "email". Apps die "username" wollen (Login-Form mit
        *  Username-or-Email) reichen das durch. */
       readonly autoComplete?: string;
+      readonly testId?: string;
     }
   | {
       readonly kind: "password";
@@ -153,6 +187,7 @@ export type InputProps =
        *  Browser-Password-Manager nutzen das für die Speicherentscheidung.
        *  Native: textContentType="password" / "newPassword". */
       readonly autoComplete?: "current-password" | "new-password";
+      readonly testId?: string;
     }
   | {
       readonly kind: "number";
@@ -163,6 +198,20 @@ export type InputProps =
       readonly disabled?: boolean;
       readonly required?: boolean;
       readonly hasError?: boolean;
+      readonly testId?: string;
+    }
+  | {
+      readonly kind: "range";
+      readonly id: string;
+      readonly name: string;
+      readonly value: number;
+      readonly onChange: (v: number) => void;
+      readonly min: number;
+      readonly max: number;
+      readonly step?: number;
+      readonly disabled?: boolean;
+      readonly required?: boolean;
+      readonly hasError?: boolean;
     }
   | {
       readonly kind: "boolean";
@@ -511,6 +560,10 @@ export type SectionProps = {
    *  übernehmen"). Web rendert standalone eine abgehobene Footer-Row
    *  (border-t), innerhalb eines Forms eine rechtsbündige Button-Reihe. */
   readonly actions?: ReactNode;
+  /** "destructive" marks the Section as a warning/danger area (e.g. account
+   *  deletion, restrict processing) — border color only, no content change.
+   *  Default "default" (normal card border). */
+  readonly variant?: "default" | "destructive";
   readonly testId?: string;
 };
 
@@ -533,9 +586,10 @@ export type GridCellProps = {
 /** Semantischer Text. Variants bilden Standard-Typografie-Rollen ab —
  *  `body` ist Default, `small` für sekundäre Labels, `code` für inline
  *  monospace (entityId, screen-id), `required-mark` für das Sternchen
- *  hinter Labels. Custom-Impls mappen auf ihren TypeScale. */
+ *  hinter Labels, `muted` für gedimmten Fließtext (text-sm muted-
+ *  foreground). Custom-Impls mappen auf ihren TypeScale. */
 export type TextProps = {
-  readonly variant?: "body" | "small" | "code" | "required-mark";
+  readonly variant?: "body" | "small" | "code" | "required-mark" | "muted";
   readonly children: ReactNode;
   readonly testId?: string;
 };
@@ -581,6 +635,16 @@ export type DialogProps = {
   readonly testId?: string;
 };
 
+/** Image lightbox — full-size preview on click. Web renders Radix overlay;
+ *  trigger (thumbnail) and open state live in the app. */
+export type LightboxProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly src: string;
+  readonly alt: string;
+  readonly testId?: string;
+};
+
 /** Source-badge for one cascade step (User / Tenant / System / …).
  *  Used inline next to a config value to indicate where it came from.
  *  Requires a LocaleProvider above it (labels run through useTranslation)
@@ -661,8 +725,10 @@ export type CorePrimitives = {
   readonly Text: ComponentType<TextProps>;
   readonly Heading: ComponentType<HeadingProps>;
   readonly Dialog: ComponentType<DialogProps>;
+  readonly Lightbox: ComponentType<LightboxProps>;
   readonly ConfigSourceBadge: ComponentType<ConfigSourceBadgeProps>;
   readonly ConfigCascadeView: ComponentType<ConfigCascadeViewProps>;
+  readonly Link: ComponentType<LinkProps>;
 };
 
 /** Offene Extension-Zone für App-eigene Primitives. Devs erweitern

package/src/sort-by-accessor.ts

@@ -0,0 +1,20 @@
+import type { DataTableSort } from "./primitives";
+
+/** Sorts `rows` by a `DataTableSort` against a field->accessor map. Unknown
+ *  field or `sort === null` returns `rows` unchanged (no-op, not an error —
+ *  callers pass whatever the DataTable reports). */
+export function sortByAccessor<TRow>(
+  rows: readonly TRow[],
+  sort: DataTableSort | null,
+  accessors: Readonly<Record<string, (row: TRow) => string | number>>,
+): readonly TRow[] {
+  if (sort === null) return rows;
+  const accessor = accessors[sort.field];
+  if (accessor === undefined) return rows;
+  const factor = sort.dir === "asc" ? 1 : -1;
+  return [...rows].sort((a, b) => {
+    const av = accessor(a);
+    const bv = accessor(b);
+    return av < bv ? -factor : av > bv ? factor : 0;
+  });
+}