@cosmicdrift/kumiko-renderer 0.385.0 → 0.387.0

package/dist/components/render-list.d.ts

@@ -6,27 +6,26 @@ import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableProps,
 import { type ListEmptyStateContent } from "./list-empty-state.tsx";
 export type RenderListProps = {
     readonly screen: EntityListScreenDefinition;
-    readonly entity: EntityDefinition;
+    readonly entity: Pick<EntityDefinition, "fields" | "derivedFields">;
     readonly rows: readonly Readonly<Record<string, unknown>>[];
     readonly featureName: string;
     readonly translate?: Translate;
     readonly onRowClick?: (row: ListRowViewModel) => void;
-    /** Override der Default-Empty-Box. Wenn gesetzt, wird der Auto-CTA
-     *  via `onCreate` ignoriert — Caller-Inhalt gewinnt. */
+    /** Overrides the default empty box. When set, the automatic CTA via
+     *  `onCreate` is ignored; the caller's content takes precedence. */
     readonly emptyState?: ReactNode;
-    /** Setzt einen "+ Neu" Button in die Toolbar UND dient als CTA in
-     *  der Default-Empty-Box. Caller liefert die Action selber (z. B.
-     *  navigate auf den Edit-Screen). */
+    /** Adds a "+ New" button to the toolbar and uses it as the CTA in the
+     *  default empty box. The caller provides the action (for example,
+     *  navigation to the edit screen). */
     readonly onCreate?: () => void;
-    /** Label für den + Neu Button. Default kommt aus dem i18n-Bundle
-     *  (`kumiko.actions.create`). Caller kann durch eigenen String
-     *  überschreiben. */
+    /** Label for the + New button. Defaults to the i18n bundle key
+     *  (`kumiko.actions.create`). The caller can override it. */
     readonly createLabel?: string;
-    /** Aktiviert ein Search-Input in der Toolbar. Server-side Filter
-     *  via Caller's onSearchChange — RenderList filtert NICHT lokal. */
+    /** Enables a search input in the toolbar. Filtering is server-side via
+     *  the caller's onSearchChange; RenderList does not filter locally. */
     readonly searchable?: boolean;
-    /** Placeholder für das Search-Input. Default kommt aus dem i18n-
-     *  Bundle (`kumiko.list.search-placeholder`). */
+    /** Placeholder for the search input. Defaults to the i18n bundle key
+     *  (`kumiko.list.search-placeholder`). */
     readonly searchPlaceholder?: string;
     /** Hint at the left of the toolbar (already translated). */
     readonly description?: string;
@@ -38,35 +37,35 @@ export type RenderListProps = {
     readonly defaultFilterActive?: boolean;
     /** Plural-forms key for the footer count noun; default is the entity's `:noun` convention key. */
     readonly itemNounKey?: string;
-    /** Aktueller Search-Term (vom URL-State / Parent). RenderList puffert
-     *  Tipps lokal mit 300ms Debounce, bevor onSearchChange gefeuert
-     *  wird — sonst macht jeder Tastendruck einen Server-Roundtrip. */
+    /** Current search term (from URL state / the parent). RenderList buffers
+     *  typing locally with a 300ms debounce before calling onSearchChange;
+     *  otherwise every keystroke would trigger a server round trip. */
     readonly searchValue?: string;
-    /** Wird gerufen wenn der debounced Search-Term sich ändert. Caller
-     *  setzt damit URL-State (?<id>.q=…) und triggert ein refetch. */
+    /** Called when the debounced search term changes. The caller uses it to
+     *  set URL state (?<id>.q=…) and trigger a refetch. */
     readonly onSearchChange?: (next: string) => void;
-    /** Aktuelle Sortierung (oder null = Server-Default-Order). */
+    /** Current sorting, or null for the server's default order. */
     readonly sort?: ListSort | null;
-    /** Wird gerufen mit dem nächsten Sort-State nach einem Header-Klick. */
+    /** Called with the next sort state after a header click. */
     readonly onSortChange?: (next: ListSort | null) => void;
-    /** Pager-Props für pagination="pages". Wenn undefined, kein Pager-
-     *  UI — Default oder infinite-Mode. KumikoScreen liefert das je nach
-     *  screen.pagination. */
+    /** Pager props for pagination="pages". If undefined, no pager UI is
+     *  rendered; the default or infinite mode is used. KumikoScreen supplies
+     *  this according to screen.pagination. */
     readonly pager?: {
         readonly page: number;
         readonly limit: number;
         readonly total: number;
         readonly onPageChange: (next: number) => void;
     };
-    /** Infinite-Scroll-Wiring für pagination="infinite". KumikoScreen
-     *  hält accumulated rows + cursor, RenderList reicht die Callbacks
-     *  einfach durch an DataTable. */
+    /** Infinite-scroll wiring for pagination="infinite". KumikoScreen keeps
+     *  the accumulated rows and cursor; RenderList passes the callbacks
+     *  through to DataTable. */
     readonly onReachEnd?: () => void;
     readonly loadingMore?: boolean;
     readonly hasMore?: boolean;
-    /** Pro-Row-Aktionen — Resolved-Form (KumikoScreen baut das aus
-     *  EntityListScreenDefinition.rowActions: handler-QN → dispatcher-Call,
-     *  i18n-Keys → translated Strings). */
+    /** Per-row actions in resolved form. KumikoScreen builds them from
+     *  EntityListScreenDefinition.rowActions: handler-QN becomes a dispatcher
+     *  call, and i18n keys become translated strings. */
     readonly rowActions?: readonly DataTableRowAction[];
     /** How the row-action column renders (see `DataTableProps.rowActionMode`).
      *  KumikoScreen derives it from the actions themselves; without it the
@@ -75,38 +74,38 @@ export type RenderListProps = {
     /** Forwarded to `DataTableProps.rowGrouping` / `rowTone`. */
     readonly rowGrouping?: DataTableRowGrouping;
     readonly rowTone?: DataTableProps["rowTone"];
-    /** Toolbar-Aktionen im List-Header — Resolved-Form (KumikoScreen baut
-     *  das aus EntityListScreenDefinition.toolbarActions: navigate-target
-     *  → useNav, handler-QN → dispatcher-Call). RenderList rendert die
-     *  Buttons rechts in der Toolbar, vor "+ Neu". */
+    /** Toolbar actions in the list header in resolved form. KumikoScreen
+     *  builds them from EntityListScreenDefinition.toolbarActions:
+     *  navigate targets use useNav and handler-QN uses a dispatcher call.
+     *  RenderList renders the buttons on the right side of the toolbar,
+     *  before "+ New". */
     readonly toolbarActions?: readonly ToolbarActionButton[];
-    /** Faceted-Filter-Dropdowns — KumikoScreen baut sie aus den filterable
-     *  select/boolean-Feldern; RenderList reicht sie an die DataTable durch. */
+    /** Faceted filter dropdowns. KumikoScreen builds them from filterable
+     *  select/boolean fields; RenderList passes them through to DataTable. */
     readonly filterFacets?: readonly DataTableFacet[];
-    /** Aktuell gewählte Facet-Werte je Feld (vom URL-State). */
+    /** Currently selected facet values by field (from URL state). */
     readonly filterValues?: Readonly<Record<string, readonly string[]>>;
-    /** Toggle eines Facet-Werts (URL-State setzen + refetch). */
+    /** Toggles a facet value (sets URL state and refetches). */
     readonly onFilterChange?: (field: string, values: readonly string[]) => void;
     /** Reset aller aktiven Facets. */
     readonly onFilterReset?: () => void;
-    /** Time-range filters (fw#3104) — forwarded to the DataTable. */
+    /** Time-range filters — forwarded to the DataTable. */
     readonly dateRangeFacets?: readonly DataTableDateRangeFacet[];
     /** One bound changed (set URL state + refetch). */
     readonly onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void;
     /** Forwarded to `DataTableProps.chromeless` — drops the table's own card
      *  frame for a host that already provides one (relatedList in a tabs-mode
-     *  section, fw#2722). Default false. */
+     *  section). Default false. */
     readonly chromeless?: boolean;
     /** Forwarded to `DataTableProps.scrollBody` — bounds the table height and
      *  scrolls rows internally instead of growing the page (relatedList in a
-     *  tabs-mode section, fw#2722). Default false. */
+     *  tabs-mode section). Default false. */
     readonly scrollBody?: boolean;
     /** Forwarded to `DataTableProps.screenPadding` — `true`: the table carries
      *  the shared screen padding because it is the screen body (entityList/
-     *  projectionList, fw#2640). Explicit `false`: no padding at all — the
-     *  host already pads its own children (relatedList in a tabs-mode Card,
-     *  fw#3234). Omitted: legacy `p-6` fallback for a standalone table with no
-     *  padded host. */
+     *  projectionList). Explicit `false`: no padding at all — the host already
+     *  pads its own children (relatedList in a tabs-mode Card). Omitted: legacy
+     *  `p-6` fallback for a standalone table with no padded host. */
     readonly screenPadding?: boolean;
     /** Forwarded to `DataTableProps.expandedRowIds` / `onToggleRowExpanded` /
      *  `renderExpandedRow` (entityList `expandableRow`). */

package/dist/components/render-list.js

@@ -18,8 +18,8 @@ function isHeaderPromotableToolbarAction(action) {
 }
 export function RenderList(props) {
     const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, emptyContent, narrowed = false, defaultFilterActive: defaultFilterActiveProp = false, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, rowGrouping, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
-    // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
-    // wären Column-Header raw i18n-Keys.
+    // As in RenderEdit, fall back to the i18next context for translation;
+    // otherwise column headers would display raw i18n keys.
     const t = useTranslation();
     const translate = translateProp ?? t;
     const { DataTable, Button, Dialog, Input, Banner, PageHeader } = usePrimitives();
@@ -62,30 +62,28 @@ export function RenderList(props) {
         return () => clearTimeout(timer);
     }, [localQ, searchValue, onSearchChange]);
     const vm = useMemo(() => computeListViewModel({ screen, entity, rows, translate, featureName }), [screen, entity, rows, translate, featureName]);
-    // Tier 2.7e-4: Reference-Field-Eagerload via Bridge-Component-Pattern.
-    // Hooks-Rule-Konflikt: pro reference-Spalte muss useReferenceLookup
-    // gerufen werden, aber die Anzahl varriiert per Schema. Lösung —
-    // ReferenceLookupBridge-Komponenten pro Spalte gemountet, die ihre
-    // Map über onMap-Callback in einen lokalen State veröffentlichen.
-    // Anzahl der Hook-Calls pro Bridge-Component ist konstant (1), und
-    // React verwaltet die mounted/unmounted Lifecycles beim Schema-
-    // Wechsel über die key-Property automatisch.
+    // Reference-field eager loading through bridge components.
+    // The Hooks rule requires useReferenceLookup for each reference column,
+    // but the number of columns varies with the schema. Each column therefore
+    // mounts a ReferenceLookupBridge that publishes its map to local state
+    // through onMap. Each bridge makes a constant number of hook calls (one),
+    // and React manages its lifecycle when the schema changes via key.
     const referenceColumns = useMemo(() => vm.columns
         .filter((c) => c.type === "reference" && c.refEntity !== undefined)
         .map((c) => ({
         field: c.field,
         refEntity: c.refEntity ?? "",
-        // Tier 2.7e Cross-Feature: refFeature kommt aus parseRefTarget
-        // im ViewModel (default = current featureName).
+        // refFeature comes from parseRefTarget in the ViewModel
+        // (default = the current featureName).
         refFeature: c.refFeature ?? featureName,
         labelField: c.refLabelField ?? "id",
     })), [vm.columns, featureName]);
     const [referenceLookups, setReferenceLookups] = useState({});
     const handleLookupMap = useCallback((field, map) => {
         setReferenceLookups((prev) => {
-            // skip-update wenn die Map identisch ist (Render-Loop-Schutz —
-            // Bridge-Component re-rendert sonst und schickt die gleiche Map
-            // wieder rein bis React in eine Endlosschleife geht).
+            // Skip the update when the map is identical. Otherwise the bridge
+            // would re-render and send the same map back until React entered
+            // an infinite loop.
             if (prev[field] === map)
                 return prev;
             return { ...prev, [field]: map };
@@ -98,8 +96,8 @@ export function RenderList(props) {
         return vm.columns.map((col) => {
             if (col.type !== "reference")
                 return col;
-            // Author-deklarierter Renderer übersteuert immer — Default greift
-            // nur wenn keiner gesetzt ist.
+            // An author-declared renderer always takes precedence;
+            // the default is used only when none is set.
             if (col.renderer !== undefined)
                 return col;
             const map = referenceLookups[col.field];
@@ -145,11 +143,11 @@ export function RenderList(props) {
                 });
             };
             const renderer = (value, row) => {
-                // Tier 2.7e Server-Eagerload: wenn der Server _refs mit-
-                // schickt, lesen wir den Display-Wert direkt aus der
-                // resolved Row — kein Roundtrip durch die Bridge-Map nötig
-                // und keine limit:200-Constraint. EagerloadedRow-Type aus
-                // @cosmicdrift/kumiko-framework/db pinnt die Form von _refs.
+                // Server eager loading: when the server includes _refs, read the display
+                // value directly from the resolved row. This avoids a round trip
+                // through the bridge map and the limit:200 constraint. The
+                // EagerloadedRow type from @cosmicdrift/kumiko-framework/db defines
+                // the shape of _refs.
                 const resolved = eagerloadedRef(row, col.field);
                 if (Array.isArray(resolved) && resolved.length > 0) {
                     return resolved.map((r) => String(r[labelField] ?? r["id"] ?? "")).join(", ");
@@ -157,7 +155,7 @@ export function RenderList(props) {
                 if (isPlainRecord(resolved)) {
                     return String(resolved[labelField] ?? resolved["id"] ?? "");
                 }
-                // Renderer-Side-Fallback (kein Server-Eagerload aktiv).
+                // Renderer-side fallback when server eager loading is not active.
                 if (Array.isArray(value)) {
                     if (value.length === 0)
                         return EMPTY_VALUE_PLACEHOLDER;
@@ -182,9 +180,9 @@ export function RenderList(props) {
         ...vm,
         columns: enrichedColumns,
     }), [vm, enrichedColumns]);
-    // i18n-Defaults für Toolbar/Empty-State Strings — Caller kann jeden
-    // einzeln per Prop überschreiben, sonst kommen die Framework-Bundles
-    // (kumiko.actions.create, kumiko.list.search-placeholder, …).
+    // i18n defaults for toolbar and empty-state strings. The caller can
+    // override each one through a prop; otherwise the framework bundles provide
+    // them (kumiko.actions.create, kumiko.list.search-placeholder, …).
     const effectiveCreateLabel = translate(createLabel ?? screen.createLabel ?? "kumiko.actions.create");
     const effectiveSearchPlaceholder = translate(searchPlaceholder ?? screen.searchPlaceholder ?? "kumiko.list.search-placeholder");
     const nounKey = itemNounKey ?? `${featureName}:entity:${screen.entity}:noun`;
@@ -193,12 +191,12 @@ export function RenderList(props) {
         ? (count) => translate(nounKey, { count })
         : undefined;
     const toolbarStart = searchable ? (_jsx(Input, { kind: "text", id: "render-list-search", name: "search", value: localQ, onChange: setLocalQ, placeholder: effectiveSearchPlaceholder })) : undefined;
-    // Toolbar-End-Slot: optionaler Header-Slot (z.B. Cap-Counter, links im
-    // rechten Cluster) + Toolbar-Actions (List-Header-Buttons aus dem Schema)
-    // + optional "+ Neu" am rechten Edge. Der Header-Slot lebt IN der Toolbar-
-    // Zeile (gleicher Card-Rahmen), nicht als loser Text über dem Screen-Titel
-    // (Bug-Bash 3 #12). Reihenfolge = Array-Reihenfolge (Schema-deklariert),
-    // "+ Neu" zuletzt weil das die häufigste/auffälligste CTA ist.
+    // Toolbar-end slot: an optional header slot (for example, a cap counter,
+    // at the left of the right-hand cluster), toolbar actions from the schema,
+    // and an optional "+ New" button at the right edge. The header slot lives
+    // inside the toolbar row, with the same card frame, rather than as loose
+    // text above the screen title. Items retain array order, and "+ New" comes
+    // last because it is the most common and prominent CTA.
     const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
     const hasHeaderSlot = screen.slots?.header !== undefined;
     const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
@@ -218,30 +216,29 @@ export function RenderList(props) {
         hasToolbarActionsInToolbar ||
         (onCreate !== undefined && !createInPageHeader) ? (_jsxs(_Fragment, { children: [hasHeaderSlot && _jsx(ListHeaderSlotMount, { screen: screen }), hasToolbarActionsInToolbar &&
                 toolbarActionsInToolbar.map((a) => (_jsx(ToolbarActionView, { action: a, iconOnly: toolbarIconOnly, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), !createInPageHeader && createButton] })) : undefined;
-    // Empty-State: Default zeigt Heading + Description + optional CTA-
-    // Button. Caller kann via emptyState-Prop komplett überschreiben.
-    // Wenn weder onCreate noch ein Override gegeben ist, fällt die
-    // DataTable auf den DataTable-Default zurück (`kumiko.list.no-entries`).
+    // Empty state: by default, show a heading, description, and optional CTA
+    // button. The caller can replace it completely through emptyState.
+    // Without onCreate or an override, DataTable uses its default
+    // (`kumiko.list.no-entries`).
     const defaultFilterActive = defaultFilterActiveProp && onFilterReset !== undefined;
     const composedEmptyState = emptyState ??
         (onCreate !== undefined || emptyContent !== undefined || narrowed || defaultFilterActive ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, defaultFilterActive: defaultFilterActive, ...(onFilterReset !== undefined && { onShowAll: onFilterReset }), translate: translate, createButton: onCreate !== undefined && !narrowed && !defaultFilterActive && !createInPageHeader ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined);
-    // Title-Resolution: ein konventioneller i18n-Key `screen:<id>.title`.
-    // Wenn das Bundle den Key kennt, schöner Titel; sonst kommt der
-    // screenId selber raus (kein "Untitled"-Fallback — der App-Dev sieht
-    // dann dass die Übersetzung fehlt).
+    // Title resolution uses the conventional i18n key `screen:<id>.title`.
+    // If the bundle knows the key, use its translated title; otherwise use
+    // screenId so the app developer can see that the translation is missing.
     const titleKey = `screen:${screen.id}.title`;
     const resolvedTitle = translate(titleKey);
     const toolbarTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
-    // ListSort = DataTableSort (use-list-url-state aliased) — kein Cast nötig.
+    // ListSort = DataTableSort (aliased in use-list-url-state), so no cast is needed.
     return (_jsxs(_Fragment, { children: [createInPageHeader && PageHeader !== undefined && _jsx(PageHeader, { actions: createButton }), promotedActionButton !== undefined && PageHeader !== undefined && (_jsx(PageHeader, { actions: promotedActionButton })), referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: handleLookupMap }, rc.field))), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...(onRowClick !== undefined && { onRowClick }), ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }), ...(toolbarStart !== undefined && { toolbarStart }), ...(description !== undefined && { toolbarDescription: description }), ...(toolbarEnd !== undefined && { toolbarEnd }), ...(sort !== undefined && { sort }), ...(onSortChange !== undefined && { onSortChange }), ...(pager !== undefined && { pager }), ...(onReachEnd !== undefined && { onReachEnd }), ...(loadingMore !== undefined && { loadingMore }), ...(hasMore !== undefined && { hasMore }), ...(itemNoun !== undefined && { itemNoun }), ...(rowActions !== undefined && { rowActions }), ...(rowActionMode !== undefined && { rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(filterFacets !== undefined && { filterFacets }), ...(filterValues !== undefined && { filterValues }), ...(onFilterChange !== undefined && { onFilterChange }), ...(onFilterReset !== undefined && { onFilterReset }), ...(dateRangeFacets !== undefined && { dateRangeFacets }), ...(onDateRangeChange !== undefined && { onDateRangeChange }), ...(chromeless !== undefined && { chromeless }), ...(scrollBody !== undefined && { scrollBody }), ...(screenPadding !== undefined && { screenPadding }), ...(expandedRowIds !== undefined && { expandedRowIds }), ...(onToggleRowExpanded !== undefined && { onToggleRowExpanded }), ...(renderExpandedRow !== undefined && { renderExpandedRow }), testId: "render-list-table" })] }));
 }
-// Header-Slot in der Listen-Toolbar (toolbarEnd): `screen.slots.header` ist
-// eine PlatformComponent (`{ react: { __component: "X" } }`), aufgelöst über
-// dieselbe ExtensionSectionsProvider-Registry wie entityEdit-Sections.
-// entityId ist null (Listen-Kontext, keine Row); die Component lädt ihre
-// Daten selbst (z.B. ein Cap-Counter aus einer usage-Query). Eigene
-// Component wegen Rules-of-Hooks — useExtensionSectionComponent darf nicht
-// konditional im RenderList-Body laufen.
+// Header slot in the list toolbar (toolbarEnd): `screen.slots.header` is
+// a PlatformComponent (`{ react: { __component: "X" } }`) resolved through
+// the same ExtensionSectionsProvider registry as entityEdit sections.
+// entityId is null in the list context because there is no row; the component
+// loads its own data (for example, a cap counter from a usage query). A
+// separate component is required by the Rules of Hooks because
+// useExtensionSectionComponent must not run conditionally in RenderList.
 function ListHeaderSlotMount({ screen, }) {
     const header = screen.slots?.header;
     const name = header !== undefined ? extensionSectionName(header) : undefined;
@@ -261,18 +258,18 @@ function ListHeaderSlotMount({ screen, }) {
     // (useListUrlState) — e.g. a tag filter narrowing the list to an id-set.
     return _jsx(Component, { entityName: screen.entity, entityId: null, screenId: screen.id });
 }
-// Tier 2.7e-4: Bridge-Component pro reference-Spalte. Mounted für jede
-// Spalte einmal, ruft useReferenceLookup unconditional (Hook-Rules
-// happy), und published die Map über onMap an den Parent. React
-// verwaltet das Mounting/Unmounting beim Schema-Wechsel über die
-// key-Prop im map-Loop des Parents.
+// Bridge component for each reference column. It is mounted once per
+// column, calls useReferenceLookup unconditionally, and publishes the map
+// to the parent through onMap. React manages mounting and unmounting when
+// the schema changes through the key prop in the parent's map loop.
 function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
     const lookup = useReferenceLookup(featureName, refEntity, labelField);
-    // useEffect statt direktem call damit setState außerhalb des Render-
-    // Pfads passiert (sonst React-Warning "Cannot update a component
-    // while rendering a different component").
-    // Unpublished while loading or after a failed lookup: the renderer treats a missing map as
-    // "not resolved", an empty published map as "nothing found". Only the latter may say "Unknown".
+    // Use an effect rather than calling directly so setState runs outside the
+    // render path; otherwise React warns about updating one component while
+    // rendering another.
+    // Do not publish while loading or after a failed lookup: a missing map means
+    // "not resolved", whereas an empty published map means "nothing found".
+    // Only the latter may display "Unknown".
     const resolved = !lookup.loading && !lookup.failed;
     useEffect(() => {
         if (resolved)
@@ -280,18 +277,17 @@ function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMa
     }, [field, lookup.map, resolved, onMap]);
     return null;
 }
-// ToolbarActionView — pro Toolbar-Action ein Button (+ Confirm-Dialog
-// wenn confirm gesetzt). Same Pattern wie RowAction (Inline-Variante)
-// aber ohne row-Context. busy-State während async onTrigger; Dialog
-// öffnet sich vor dem Trigger wenn confirm/danger gesetzt.
+// ToolbarActionView renders one button per toolbar action, with a confirm
+// dialog when required. It follows the inline RowAction pattern but has no
+// row context. The busy state covers async onTrigger; the dialog opens before
+// the trigger when confirmation is required for confirm/danger actions.
 function ToolbarActionView({ action, iconOnly = false, Button, Dialog, Banner, }) {
     const [busy, setBusy] = useState(false);
     const [confirmOpen, setConfirmOpen] = useState(false);
-    // Toolbar-Actions haben (anders als rowActions, die über die DataTable-
-    // Primitive laufen) keine Toast-Primitive zur Verfügung — ein inline
-    // Error-Banner ist der surfacing-Pfad hier. Gleicher Grund wie bei
-    // rowActions (Prod-Bug 2026-06-07): ein verschlucktes Failure-Result
-    // sieht für den User wie "nichts passiert" aus.
+    // Toolbar actions do not have access to the toast primitive, unlike
+    // rowActions routed through the DataTable primitive, so an inline error
+    // banner is used to surface failures. Without it, a swallowed failure result
+    // would look to the user as though nothing happened.
     const [errorText, setErrorText] = useState(null);
     const trigger = async () => {
         setBusy(true);

package/dist/components/use-wizard-form-draft.js

@@ -12,10 +12,10 @@ const FORM_DRAFT_LIST = "form-draft:query:list";
 // Mirrors bundled-features/src/form-draft/web/constants.ts's FORM_DRAFT_KEY_MAX_LENGTH
 // — same hardcoding rationale as the QNs above (no dependency on that package).
 const FORM_DRAFT_KEY_MAX_LENGTH = 256;
-// Trailing-edge debounce for patch()-triggered draft saves (#1914). A single
+// Trailing-edge debounce for patch()-triggered draft saves. A single
 // patch() call (VIN-decode, an extension section) should not save immediately
 // per call, but patch() can also fire from inside onChange on every keystroke
-// (the #1888 derived-field shape) — 500ms collapses a typing burst into one
+// (the derived-field shape) — 500ms collapses a typing burst into one
 // save instead of one per keystroke, while still saving well before a user
 // abandons the tab.
 export const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
@@ -40,7 +40,7 @@ function mintDraftId() {
     return `draft-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
 }
 export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draftStorage, }) {
-    // Create-mode draftId (issue #1913) — resumed from `sessionStorage` (web)
+    // Create-mode draftId — resumed from `sessionStorage` (web)
     // on mount so a same-tab reload finds the right one of several parallel
     // create-sessions on this screen; `null` until the first step change
     // mints one (saveDraft), or the mount-time `form-draft:query:list`
@@ -55,7 +55,7 @@ export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draf
     // once for this mount. Without this, a create-mode discard resets `draftId`
     // to `null` (see discardDraft below) and would re-arm the list effect —
     // silently adopting an unrelated parallel draft on the same screen right
-    // after the user just submitted (#1908).
+    // after the user just submitted.
     const didListRef = useRef(false);
     const [draftCandidates, setDraftCandidates] = useState(null);
     // Derived from the screen id + the host entity id only — never from
@@ -64,7 +64,7 @@ export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draf
     // unchanged. Create-mode: `${screenId}:new:${draftId}` once a draftId
     // exists (resumed, adopted, or minted), `undefined` before that — two
     // parallel create sessions on the same screen must never collapse onto
-    // the same key (kumiko-framework#1908).
+    // the same key.
     const draftKey = useMemo(() => isCreateMode
         ? draftId !== null
             ? `${screenId}:new:${draftId}`
@@ -133,7 +133,7 @@ export function useWizardFormDraftRestore({ screenId, isCreateMode, draftEnabled
         hasNavigatedRef,
         setRawStep,
     ]);
-    // Mount-time fallback (issue #1913) for create-mode when no draftId
+    // Mount-time fallback for create-mode when no draftId
     // survived in storage (new tab, cleared storage): ask the server for this
     // screen's open drafts and let the user choose via a picker (below) —
     // even for exactly one candidate. Auto-adopting a lone candidate would
@@ -186,7 +186,7 @@ export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled,
     // (see draftCandidates below) — adopt it the same way a single
     // auto-adopted candidate would be.
     function adoptDraft(candidate) {
-        // Locked state (#1896/fw#1909): `disabled` means "no write possible" —
+        // Locked state: `disabled` means "no write possible" —
         // repointing draftKey and patching in the candidate's values is exactly
         // that, so a locked form must not adopt a draft.
         // skip: a locked form keeps its current draft (reason above).
@@ -202,8 +202,8 @@ export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled,
     //
     // Create-mode, first draft save (step change OR a debounced patch() from
     // controlled mode / extension sections, see patchAndScheduleDraftSave
-    // above — both call this on step 0 too): mints the draftId here (issue
-    // #1913) rather than at mount, so a form nobody ever interacted with
+    // above — both call this on step 0 too): mints the draftId here
+    // rather than at mount, so a form nobody ever interacted with
     // never claims a draftId or writes a row. `draftKey`/`draftId` state
     // won't reflect the mint until the next render, so the just-minted key is
     // computed inline instead of read from the memoized `draftKey`.
@@ -220,7 +220,7 @@ export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled,
             key = `${screenId}:new:${mintedId}`;
             // A stale picker from the mount-time list fallback must not survive a
             // mint — picking a candidate afterwards would repoint draftKey at an
-            // unrelated draft mid-edit and overwrite it (#1908).
+            // unrelated draft mid-edit and overwrite it.
             setDraftCandidates(null);
         }
         // skip: create-mode with a draftId that failed to mint — unreachable

package/dist/context/dispatcher-context.js

@@ -32,11 +32,11 @@ export function useDispatcher() {
     }
     return dispatcher;
 }
-// Soft-Variante: null wenn kein Provider mounted statt throw. Für
-// Components die einen Dispatcher OPTIONAL brauchen (z.B. KumikoScreen
-// rendert mit/ohne rowActions; die Test-Suite mountet kein Dispatcher
-// wenn der Screen keine Mutation triggert). Caller ist zuständig dass
-// er bei null einen sinnvollen Fallback hat (typisch: kein Action-Wiring).
+// Soft variant: returns null when no provider is mounted instead of throwing. For
+// components that optionally need a Dispatcher (for example, KumikoScreen renders
+// with or without rowActions; the test suite does not mount a Dispatcher when the
+// screen triggers no mutation). Callers must provide a sensible fallback for null
+// (typically, no action wiring).
 export function useOptionalDispatcher() {
     return useContext(DispatcherContext) ?? undefined;
 }

package/dist/context/user-roles-context.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from "react";
 // Threads the current user's roles through the tree so KumikoScreen can
-// gate role-restricted screens at render time (see #1203 — nav filtering
-// alone doesn't stop a direct-URL/screenQn hit on a role-gated screen).
+// gate role-restricted screens at render time — nav filtering alone
+// doesn't stop a direct-URL/screenQn hit on a role-gated screen).
 // Apps wire this from their `shell` render-prop, the same place they
 // already pass `user` to WorkspaceShell for nav filtering.
 //

package/dist/headless/apex/index.d.ts

@@ -231,6 +231,5 @@ export declare function injectPageHead(html: string, tagsHtml: string): string;
  *  the shared timeout. Never throws and never changes `html` on a resolver
  *  error, a `null` resolve, or a timeout — the caller's shell always ships
  *  unchanged. runProdApp and runDevApp both call this single function, so a
- *  future change to timeout or fallback semantics has one place to land
- *  (kumiko-framework#3026). */
+ *  future change to timeout or fallback semantics has one place to land. */
 export declare function resolveAndInjectPageHead(html: string, resolvePageHead: PageHeadResolver, input: PageHeadResolveInput): Promise<string>;

package/dist/headless/apex/index.js

@@ -8,8 +8,8 @@ import { APEX_STRUCTURAL_CSS } from "./css.js";
 import { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT } from "./lightbox.js";
 export { APEX_NAV_MENU_CSS, APEX_NAV_TOGGLE_RESPONSIVE_CSS, APEX_STRUCTURAL_CSS } from "./css.js";
 export { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT, APEX_LIGHTBOX_SCRIPT_CSP_HASH, } from "./lightbox.js";
-// JSON in <script>-Kontext: `<` als < serialisieren, damit weder
-// `</script>` noch `<!--` aus dem Block ausbrechen kann (JSON bleibt valide).
+// JSON in <script> context: serialize `<` as < so neither
+// `</script>` nor `<!--` can escape the block (JSON remains valid).
 function scriptSafeJsonHtml(value) {
     return JSON.stringify(value).replace(/</g, "\\u003c");
 }
@@ -265,7 +265,7 @@ export function renderApexHeadTags(head) {
 export function renderApexPage(page) {
     const { head, brand } = page;
     const theme = page.theme ?? "light";
-    // Brand-CSS ist app-authored (Trust-Boundary siehe Datei-Header), kein Tenant-Input.
+    // Brand CSS is app-authored (see the file header for the trust boundary), not tenant input.
     const cssHtml = (brand.fontFaceCss ?? "") + brand.tokensCss + APEX_STRUCTURAL_CSS;
     const sectionsHtml = page.sections.map(renderSection).join("\n\n    ");
     // interactive-widget is ignored by iOS Safari; apex pages have no fixed bottom bars, so
@@ -308,7 +308,7 @@ export function injectPageHead(html, tagsHtml) {
 // Resolver runs alongside the request, never gates it: a slow, throwing, or
 // null-returning resolver must never turn a 200 shell into a 500 or a
 // stall. One constant shared by runProdApp and runDevApp so both time out
-// on the same value (kumiko-framework#3026).
+// on the same value.
 const PAGE_HEAD_TIMEOUT_MS = 300;
 async function resolvePageHeadWithTimeout(resolvePageHead, input) {
     let timer;
@@ -367,8 +367,7 @@ function toApexHead(meta) {
  *  the shared timeout. Never throws and never changes `html` on a resolver
  *  error, a `null` resolve, or a timeout — the caller's shell always ships
  *  unchanged. runProdApp and runDevApp both call this single function, so a
- *  future change to timeout or fallback semantics has one place to land
- *  (kumiko-framework#3026). */
+ *  future change to timeout or fallback semantics has one place to land. */
 export async function resolveAndInjectPageHead(html, resolvePageHead, input) {
     const meta = await resolvePageHeadWithTimeout(resolvePageHead, input);
     if (!meta)

package/dist/headless/form/form-controller.js

@@ -68,7 +68,7 @@ function stripUntouchedEmptyStrings(values, initial, forceIncludeEmpty) {
     let out;
     for (const key of Object.keys(v)) {
         // Value-based seed strip, except keys previously submitted as "" after a
-        // real clear — those must survive post-rebase submits (#1858).
+        // real clear — those must survive post-rebase submits.
         if (!forceIncludeEmpty.has(key) && v[key] === "" && ini[key] === "") {
             out ??= { ...v };
             delete out[key];
@@ -105,7 +105,7 @@ export function createFormController(options) {
     let initial = { ...options.initial };
     let errors = Object.freeze({});
     // Keys last submitted as "" (intentional clear). Survives rebase so a later
-    // submit of other fields does not drop them (#1858).
+    // submit of other fields does not drop them.
     const forceIncludeEmpty = new Set();
     // ctx is cast-held as TCtx; `undefined` is valid when callers don't
     // declare conditional predicates that depend on it.
@@ -166,7 +166,7 @@ export function createFormController(options) {
     function runValidate(scope, opts) {
         // See the validate() doc comment in types.ts for the scope contract.
         // A scope entry matches its exact path and everything below it, but not
-        // siblings: `address.city` must not pull in `address.zip` (#1898).
+        // siblings: `address.city` must not pull in `address.zip`.
         const isInScope = scope === undefined
             ? undefined
             : (path) => scope.some((entry) => path === entry || path.startsWith(`${entry}.`));
@@ -193,8 +193,8 @@ export function createFormController(options) {
                 hiddenFields.add(fieldKey);
         }
         // Root-level .refine() issues use path "(root)". Wizard step validate()
-        // still drops them (#1885); submit() passes includeRoot so RenderEdit
-        // fields={…} cannot silently skip cross-field rules (#1907).
+        // still drops them; submit() passes includeRoot so RenderEdit
+        // fields={…} cannot silently skip cross-field rules.
         const relevantIssues = relevantFieldIssues(zodErrorToFieldIssues(parsed.error), {
             hiddenFields,
             ...(scope !== undefined && { scope }),
@@ -382,7 +382,7 @@ export function createFormController(options) {
                 const result = await dispatcher.write(submitCfg.type, payload, { requestId });
                 unansweredAttempt = isTransportFailure(result) ? { requestId, fingerprint } : null;
                 if (result.isSuccess) {
-                    // Remember intentional empty clears so post-rebase submits keep them (#1858).
+                    // Remember intentional empty clears so post-rebase submits keep them.
                     if (payload && typeof payload === "object" && !Array.isArray(payload)) {
                         for (const [k, v] of Object.entries(payload)) {
                             if (v === "")

package/dist/headless/form/zod-bridge.js

@@ -46,8 +46,8 @@ export function zodErrorToFieldIssues(error) {
 }
 // The issues that count for validity: hidden fields never block, and a
 // scope narrows to the listed paths (an entry matches itself and everything
-// below it, not siblings — #1898). `includeRoot` keeps "(root)" refine issues
-// inside a scope (submit passes it, #1907). Shared by the controller's
+// below it, not siblings). `includeRoot` keeps "(root)" refine issues
+// inside a scope (submit passes it). Shared by the controller's
 // validate() and RenderEdit's `valid` dry-run so the two cannot drift.
 export function relevantFieldIssues(issues, opts) {
     const { hiddenFields, scope, includeRoot } = opts;