@cosmicdrift/kumiko-renderer 0.386.0 → 0.388.0

package/dist/components/render-field.js

@@ -16,7 +16,7 @@ import { fileIdsOf } from "../file-ids-of.js";
 import { applyFormatSpec, currencyDecimals, EMPTY_VALUE_PLACEHOLDER, } from "../headless/index.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
+import { isCompleteRowPage, referenceOptionSource } from "../hooks/use-reference-lookup.js";
 import { useLocale, useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { AvailabilityOptionsMultiSelect, AvailabilityOptionsSelect, staticSelectOptions, } from "./availability-options-select.js";
@@ -29,11 +29,10 @@ const AllFieldsRequiredContext = createContext(false);
 export const AllFieldsRequiredProvider = AllFieldsRequiredContext.Provider;
 export function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay = "form", row, changed, layout, accent, fillDisabled, hideLabel, }) {
     const { Field, Input, Banner, Text, JsonView } = usePrimitives();
-    // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
-    // navigator.language (Browser-Sprache) zurück statt der gewählten
-    // App-Sprache. BEWUSSTE API-Verschärfung (seit 0.38): RenderField ist
-    // public exportiert und verlangt jetzt einen LocaleProvider —
-    // Standalone-Consumer/Tests müssen wrappen (createKumikoApp tut es).
+    // The app locale is required for money/date inputs; otherwise they fall back
+    // to navigator.language instead of the selected app language. RenderField is
+    // publicly exported and therefore requires a LocaleProvider; standalone
+    // consumers and tests must wrap it (createKumikoApp does this).
     const appLocale = useLocale().locale();
     const t = useTranslation();
     const allFieldsRequired = useContext(AllFieldsRequiredContext);
@@ -45,13 +44,13 @@ export function RenderField({ field, issues, onChange, featureName, labelAppendi
     // the list-column path (render-list.tsx). Only takes effect once the field
     // is actually readOnly — a FormatSpec/PlatformComponent renderer has no
     // editable widget of its own, so applying it to an editable field would
-    // silently make that field un-editable (fw#2245).
+    // silently make that field un-editable.
     const readOnlyText = valueDisplay === "text" && field.readOnly && field.renderer === undefined;
-    // Reference-Field rendert eine eigene Component — sie nutzt
-    // useQuery() für den Live-Lookup, also muss sie als React-
-    // Komponente gemountet werden (nicht als pure render-Call).
-    // The list input prints its own list-level issues (empty state included), so
-    // the Field wrapper must not print them a second time.
+    // The reference field renders its own component because it uses useQuery()
+    // for the live lookup and must therefore be mounted as a React component,
+    // not called as a pure render function.
+    // The list input prints its own list-level issues (including the empty state),
+    // so the Field wrapper must not print them a second time.
     const listPrintsOwnIssues = field.type === "embedded" &&
         field.embeddedListCells !== undefined &&
         !(field.readOnly && field.renderer !== undefined);
@@ -168,38 +167,35 @@ function WriteOnlyTextInput({ field, id, hasError, onChange, changed, }) {
             },
         }) }));
 }
-// Tier 2.7e-3 + 2.1c: Reference-Input rendert eine Searchable Combobox
-// gefüllt aus einer Live-Query auf die referenced Entity. Default-
-// Limit: 200 — bei größeren Datasets fehlt der Tail im Dropdown
-// (Tier 2.7e-Remote: server-side Search-Query mit debounce kommt später).
-//   - Display = row[refLabelField], Default labelField "id".
-//   - Loading-State: leeres Dropdown bis die rows da sind. Field
-//     ist disabled während useQuery läuft.
-//   - Multi-Mode (Tier 2.7e-Multi via field.refMultiple): value ist
-//     ein UUID-Array, Combobox rendert Selected-Tags.
+// ReferenceInput renders a searchable combobox populated by a live query for
+// the referenced entity. With the default limit of 200, larger datasets miss
+// the tail in the dropdown; a server-side debounced search query comes later.
+//   - Display = row[refLabelField], default labelField "id".
+//   - During loading, the dropdown is empty and the field is disabled.
+//   - In multiple mode (field.refMultiple), value is a UUID array and the
+//     combobox renders tags.
 //
-// Storage: UI-Wert ist UUID (row.id) oder UUID-Array bei multiple.
-// Server-Schema: z.uuid() bzw. z.array(z.uuid()).
-// REFERENCE_COMBOBOX_LIMIT lebt zentral in hooks/reference-limits.ts
-// (siehe dort für Begründung der Default-Werte).
+// Storage: the UI value is a UUID (row.id), or a UUID array in multiple mode.
+// Server schema: z.uuid() or z.array(z.uuid()).
+// REFERENCE_COMBOBOX_LIMIT is centralized in hooks/reference-limits.ts
+// (see there for the rationale behind the default values).
 function ReferenceInput({ field, id, hasError, onChange, Input, featureName, }) {
     const { Banner } = usePrimitives();
     const refEntity = field.refEntity ?? "";
     const refFeature = field.refFeature ?? featureName;
     const isMultiple = field.refMultiple === true;
-    // Tier 2.7e Cross-Feature: refFeature kann ≠ featureName sein
-    // (z.B. items.assignee → users:query:user:list). Default ist
-    // same-feature, kommt aus dem ViewModel (parseRefTarget).
-    // fw#2780: refOptionsQuery replaces that source with an author-supplied
-    // handler whose rows already carry a composed `label`.
+    // refFeature may differ from featureName (for example,
+    // items.assignee → users:query:user:list). The default is the same feature,
+    // as provided by the ViewModel (parseRefTarget).
+    // refOptionsQuery replaces that source with an author-supplied handler whose
+    // rows already carry a composed `label`.
     const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
-    // Issue #1681: "+ Neu" in der Combobox öffnet den Create-Screen der
-    // referenced entity als Dialog, statt die aktuelle Form zu verlassen.
-    // refFeature kann ein anderes Feature als das aktuell gerenderte sein
-    // — appFeatures (createKumikoApp) kennt alle Feature-Schemas, nicht
-    // nur das der aktiven Screen. Kein Match (Feature/Screen/Entity nicht
-    // registriert, oder allowCreate:false) → onCreate bleibt undefined,
-    // Combobox rendert dann ohne den Footer.
+    // "+ Neu" in the combobox opens the referenced entity's create screen in a
+    // dialog instead of leaving the current form.
+    // refFeature may differ from the currently rendered feature; appFeatures
+    // (createKumikoApp) knows all feature schemas, not only the active screen.
+    // If the feature, screen, or entity is not registered, or allowCreate:false,
+    // onCreate remains undefined and the combobox renders without the footer.
     const appFeatures = useAppFeatures();
     const userRoles = useUserRoles();
     const t = useTranslation();
@@ -210,10 +206,10 @@ function ReferenceInput({ field, id, hasError, onChange, Input, featureName, })
         s.allowCreate !== false &&
         screenAccessAllows(s.access, userRoles));
     const refEntityDef = refTargetSchema?.entities[refEntity];
-    // Tier 2.7e Remote-Search: User tippt im Combobox → Server filtert
-    // via existing list-payload `search`-Param (Tier 2.6c). Combobox
-    // debounced den keystroke selbst (300ms) und ruft onSearchChange.
-    // Initial-State leer → erste 50 Items vom Server (default-sortiert).
+    // When the user types in the combobox, the server filters through the
+    // existing list-payload `search` parameter. The combobox debounces the
+    // keystroke itself (300ms) and calls onSearchChange.
+    // An empty initial state requests the first 50 items in default order.
     const [searchTerm, setSearchTerm] = useState("");
     const queryPayload = useMemo(() => searchTerm === ""
         ? { limit: REFERENCE_COMBOBOX_LIMIT }
@@ -254,13 +250,14 @@ function ReferenceInput({ field, id, hasError, onChange, Input, featureName, })
             return { value: idVal, label };
         });
     }, [queryResult.data, labelKey]);
-    // Single: value ist String/null; Multi: Array. Coerce auf das was
-    // der Combobox-Mode erwartet, damit Storage-Drift (Server liefert
-    // alten String wo jetzt Array erwartet wird) keine Crash auslöst.
+    // Single mode uses a String/null value; multiple mode uses an array. Coerce
+    // to the shape expected by the combobox so storage drift (for example, an
+    // old String from the server where an array is now expected) cannot crash it.
     const baseInputProps = {
         id,
         name: field.field,
-        // Initial-Load disabled — danach loading-Indicator im Popover.
+        // Disable the input during the initial load; subsequent loads show a
+        // loading indicator in the popover.
         disabled: field.readOnly || (queryResult.loading && options.length === 0),
         required: field.required,
         hasError,
@@ -295,7 +292,7 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
     if (isFormatSpec(renderer)) {
         // format:"json" wants the raw value (JsonView stringifies + highlights
         // itself) — applyFormatSpec's already-indented string is only the
-        // fallback for primitives-providers without JsonView (fw#2312).
+        // fallback for primitives-providers without JsonView.
         if (renderer.format === "json" && JsonView !== undefined) {
             return (_jsx(JsonView, { value: field.value, indent: renderer.indent, testId: `field-value-${field.field}` }));
         }
@@ -308,8 +305,8 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         // App locale as default when the FormatSpec declares none of its own —
         // otherwise locale-sensitive formats (timestamp/date/number/decimal/
         // bigInt/unit) fell back to Intl's runtime default instead of the app
-        // language chosen via LocaleProvider (fw#2187). Prefer renderer.locale
-        // when set; coalesce undefined (spread override) back to appLocale (#2332).
+        // language chosen via LocaleProvider. Prefer renderer.locale
+        // when set; coalesce undefined (spread override) back to appLocale.
         return (_jsx(Text, { testId: `field-value-${field.field}`, children: applyFormatSpec({
                 ...renderer,
                 locale: stringPropertyOf(renderer, "locale") ?? appLocale,
@@ -357,7 +354,10 @@ function ReadOnlyReferenceValue({ field, featureName, }) {
         const row = rows.find((r) => String(r["id"] ?? "") === id);
         if (row === undefined) {
             const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${refFeature}:${refEntity}`];
-            const label = unknownKey !== undefined && !queryResult.loading && queryResult.error === null
+            const label = unknownKey !== undefined &&
+                !queryResult.loading &&
+                queryResult.error === null &&
+                isCompleteRowPage(queryResult.data)
                 ? t(unknownKey)
                 : id;
             return { id, label, link: undefined };
@@ -417,7 +417,7 @@ function resolveFieldIcon(field) {
 // from the EditFieldViewModel (computeEditViewModel pulls them from
 // SelectFieldDef.options). Structural types without a widget (embedded,
 // jsonb, multiSelect) render read-only instead of a data-destroying text
-// fallback (#1834); truly unknown scalar types still fall back to text.
+// fallback; truly unknown scalar types still fall back to text.
 function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, Text, JsonView, t, row, fill, }) {
     const common = {
         id,
@@ -438,7 +438,7 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         // decimal/bigInt are both plain numbers on the wire (fieldToZod:
         // z.number() / z.number().int().safe()) — the number input's onChange
         // already emits `number | undefined`, so no extra coercion is needed
-        // beyond what "number" already does (#1925).
+        // beyond what "number" already does.
         case "number":
         case "bigInt": {
             const icon = resolveFieldIcon(field);
@@ -472,11 +472,11 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         case "locatedTimestamp":
             return (_jsx(Input, { kind: "locatedTimestamp", ...common, value: locatedValue(field.value), onChange: (v) => onChange(v), locale: field.dateLocale ?? appLocale, ...(field.min !== undefined && { min: field.min }), ...(field.max !== undefined && { max: field.max }) }));
         case "select": {
-            // Translated Option-Labels kommen aus dem ViewModel-Builder
-            // (computeEditViewModel, Convention-Key
+            // Translated option labels come from the ViewModel builder
+            // (computeEditViewModel, convention key
             // `<feature>:entity:<entity>:field:<field>:option:<value>`).
-            // Wenn keine Translations registriert sind, fallback auf raw
-            // value als Label — der ComboboxInput zeigt dann unverändert.
+            // If no translations are registered, fall back to the raw value as the
+            // label, which ComboboxInput then shows unchanged.
             const selectOptions = field.optionLabels !== undefined ? staticSelectOptions(field) : (field.options ?? []);
             // `display` is shared with multiSelect's "checkboxes", which is not a
             // select presentation — narrow to the two a select field can request.
@@ -495,11 +495,11 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         case "images":
             return (_jsx(FileListField, { field: field, id: id, kind: field.type === "images" ? "image" : "file", hasError: hasError, onChange: (ids) => onChange(ids) }));
         // embedded (without embeddedListCells — that's embeddedList, which has
-        // had its own EmbeddedListField widget since #1838) and jsonb carry
+        // had its own EmbeddedListField widget) and jsonb carry
         // arbitrary objects. Without a dedicated widget these must NOT fall
         // through to a text input: stringValue() turns them into
         // "[object Object]" and saving that overwrites the real data with the
-        // mangled string (#1834). A `required: true` on either is caught loudly
+        // mangled string. A `required: true` on either is caught loudly
         // at boot (validateNoWidgetRequiredField in the framework package)
         // instead of silently failing here.
         case "embedded":
@@ -519,7 +519,7 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
             // is set (the view-model carries it), the renderer switches to
             // textarea. longText always renders a textarea — that's the point of
             // the type — regardless of whether `multiline` is set; `multiline`
-            // only supplies an optional `{ rows }` override for it (#1925).
+            // only supplies an optional `{ rows }` override for it.
             if (field.type === "longText" || (field.type === "text" && field.multiline)) {
                 const rows = typeof field.multiline === "object" ? field.multiline.rows : undefined;
                 return (_jsx(Input, { kind: "textarea", ...common, value: stringValue(field.value), onChange: (v) => onChange(v), ...(rows !== undefined && { rows }), ...placeholderProp }));
@@ -628,8 +628,9 @@ function moneyPayload(minorUnits, currency) {
         return undefined;
     return { amount: minorUnits / 10 ** currencyDecimals(currency), currency };
 }
-// locatedTimestamp-Feldwert: das Read-Wrapper liefert `{ at, tz, utc }`; leer
-// (noch nicht gesetzt) → "" als Empty-Sentinel, analog money/timestamp.
+// A locatedTimestamp field value is supplied by the read wrapper as
+// `{ at, tz, utc }`; an unset value becomes "" as the empty sentinel,
+// consistent with money and timestamp fields.
 function locatedValue(v) {
     if (v !== null && typeof v === "object" && "at" in v && "tz" in v) {
         const utc = propertyOf(v, "utc");
@@ -644,7 +645,7 @@ function locatedValue(v) {
 // Read-only text for a `field.readOnly` field without its own `renderer` —
 // per-type formatting that reuses the same value-shaping helpers as the
 // editable widgets above, so a text value and its would-be Input widget stay
-// derived from the identical parse (fw#2245). `type: "reference"` isn't
+// derived from the identical parse. `type: "reference"` isn't
 // covered here — it needs a live label lookup, see ReadOnlyReferenceValue.
 // `isComplexFieldType` types aren't covered either — callers keep those on
 // `renderInput`'s existing Banner fallback.

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

@@ -11,22 +11,21 @@ export type RenderListProps = {
     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`). */