@cosmicdrift/kumiko-renderer 0.290.0 → 0.292.0

package/src/app/list-facets.ts

@@ -4,6 +4,7 @@
 import type { ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
 import { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Translate } from "@cosmicdrift/kumiko-headless";
+import { Temporal } from "temporal-polyfill";
 import type { DataTableFacet } from "../primitives";
 
 // One resolved facet, independent of where the type info came from — an
@@ -94,40 +95,165 @@ export function resolveProjectionFacetSpecs(
 ): ResolvedFacetSpec[] {
   if (facets === undefined) return [];
   const tr = (label: string): string => (isFacetI18nKey(label) ? translate(label) : label);
-  return facets.map((facet): ResolvedFacetSpec => {
+  // dateRange carries no option list and no `filters` entry — it resolves
+  // through resolveDateRangeFacets into its own toolbar control instead.
+  return facets.flatMap((facet): ResolvedFacetSpec[] => {
+    if (facet.type === "dateRange") return [];
     if (facet.type === "select") {
-      return {
-        field: facet.field,
-        type: "select",
-        label: tr(facet.label),
-        options: facet.options.map((opt) => ({
-          value: opt.value,
-          label: tr(opt.label),
-        })),
-      };
+      return [
+        {
+          field: facet.field,
+          type: "select",
+          label: tr(facet.label),
+          options: facet.options.map((opt) => ({
+            value: opt.value,
+            label: tr(opt.label),
+          })),
+        },
+      ];
     }
     if (facet.type === "boolean") {
-      return {
-        field: facet.field,
-        type: "boolean",
-        label: tr(facet.label),
-        options: [
-          { value: "true", label: tr(facet.trueLabel) },
-          { value: "false", label: tr(facet.falseLabel) },
-        ],
-      };
+      return [
+        {
+          field: facet.field,
+          type: "boolean",
+          label: tr(facet.label),
+          options: [
+            { value: "true", label: tr(facet.trueLabel) },
+            { value: "false", label: tr(facet.falseLabel) },
+          ],
+        },
+      ];
     }
     const target = parseRefTarget(facet.entity, featureName);
-    return {
-      field: facet.field,
-      type: "reference",
-      label: tr(facet.label),
-      options: [],
-      reference: {
-        refEntity: target.entityName,
-        refFeature: target.featureName,
-        labelField: facet.labelField ?? "id",
+    return [
+      {
+        field: facet.field,
+        type: "reference",
+        label: tr(facet.label),
+        options: [],
+        reference: {
+          refEntity: target.entityName,
+          refFeature: target.featureName,
+          labelField: facet.labelField ?? "id",
+        },
       },
-    };
+    ];
   });
 }
+
+// --- dateRange facet (fw#3104) ---
+
+// A resolved dateRange facet. Kept out of ResolvedFacetSpec because it shares
+// nothing with the option-dropdown facets: no options, no `filters` entry —
+// the two bounds travel as named top-level query params.
+export type ResolvedDateRangeFacet = {
+  readonly field: string;
+  readonly label: string;
+  readonly fromParam: string;
+  readonly toParam: string;
+};
+
+export type DateRangeBound = "from" | "to";
+
+export type DateRangeValue = { readonly from: string; readonly to: string };
+
+export function resolveDateRangeFacets(
+  facets: readonly ListFacetSpec[] | undefined,
+  translate: Translate,
+): ResolvedDateRangeFacet[] {
+  if (facets === undefined) return [];
+  return facets.flatMap((facet): ResolvedDateRangeFacet[] =>
+    facet.type === "dateRange"
+      ? [
+          {
+            field: facet.field,
+            label: isFacetI18nKey(facet.label) ? translate(facet.label) : facet.label,
+            fromParam: facet.params.from,
+            toParam: facet.params.to,
+          },
+        ]
+      : [],
+  );
+}
+
+// The bounds live in the same `<screenId>.f.<key>` URL namespace the option
+// facets use, so setFilter's page-reset and clearFilters cover them for free.
+// buildFilterPayload drops them again: a dotted key resolves to no facet
+// type, which is its "unknown field" case.
+export function dateRangeUrlField(field: string, bound: DateRangeBound): string {
+  return `${field}.${bound}`;
+}
+
+export function readDateRange(
+  urlFilters: Readonly<Record<string, readonly string[]>>,
+  field: string,
+): DateRangeValue {
+  return {
+    from: urlFilters[dateRangeUrlField(field, "from")]?.[0] ?? "",
+    to: urlFilters[dateRangeUrlField(field, "to")]?.[0] ?? "",
+  };
+}
+
+// Keeps from <= to by pushing the opposite bound along, so an inverted range
+// can't reach the server and trip a handler's `from <= to` refine (a 422 the
+// user would see as a broken list, not as a correction).
+export function clampDateRange(
+  current: DateRangeValue,
+  bound: DateRangeBound,
+  value: string,
+): DateRangeValue {
+  if (bound === "from") {
+    const to = current.to !== "" && value !== "" && value > current.to ? value : current.to;
+    return { from: value, to };
+  }
+  const from = current.from !== "" && value !== "" && value < current.from ? value : current.from;
+  return { from, to: value };
+}
+
+// A calendar date covers a whole day in the viewer's zone: "from the 14th"
+// starts at that day's first instant, "to the 14th" includes everything up to
+// its last. Going through the next day's start keeps both ends right across a
+// DST boundary, where the day is not 24h long.
+function dayBoundInstant(date: string, bound: DateRangeBound, timeZone: string): string | null {
+  let plainDate: Temporal.PlainDate;
+  try {
+    plainDate = Temporal.PlainDate.from(date);
+  } catch {
+    // Half-typed or hand-crafted URL value — drop the bound rather than send
+    // something the handler's ISO-datetime schema would reject.
+    return null;
+  }
+  const start = plainDate.toZonedDateTime(timeZone).toInstant();
+  return bound === "from"
+    ? start.toString()
+    : plainDate
+        .add({ days: 1 })
+        .toZonedDateTime(timeZone)
+        .toInstant()
+        .subtract({
+          nanoseconds: 1,
+        })
+        .toString();
+}
+
+export function buildDateRangePayload(
+  specs: readonly ResolvedDateRangeFacet[],
+  urlFilters: Readonly<Record<string, readonly string[]>>,
+  timeZone: string,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const spec of specs) {
+    const range = readDateRange(urlFilters, spec.field);
+    for (const [bound, param] of [
+      ["from", spec.fromParam],
+      ["to", spec.toParam],
+    ] as const) {
+      const value = range[bound];
+      if (value === "") continue;
+      const instant = dayBoundInstant(value, bound, timeZone);
+      if (instant !== null) out[param] = instant;
+    }
+  }
+  return out;
+}

package/src/app/projection-detail-shim.ts

@@ -60,6 +60,7 @@ export function synthesizeProjectionDetailScreen(
     if (!isFieldsEditSection(section)) return section;
     return {
       ...section,
+      // kumiko-lint-ignore section-fields-raw rewrites both sources in place — the groups branch below does the same for groups[].fields
       fields: section.fields.map(forceReadOnly),
       ...(section.groups !== undefined && {
         groups: section.groups.map((group) => ({

package/src/app/return-to.tsx

@@ -11,13 +11,72 @@ import { screenAccessAllows } from "./screen-access";
 // and a copied/shared URL.
 export const RETURN_TO_PARAM = "returnTo";
 
+// Screen levels one returnTo value may carry: the host itself plus its own
+// nested chain. Beyond that the host's returnTo is left out of the snapshot.
+const MAX_RETURN_DEPTH = 3;
+// Serialized host snapshot longer than this is dropped whole — the bare
+// target still resolves, only the restored state is lost.
+const MAX_RETURN_STATE_LENGTH = 512;
+
+const NO_RETURN_STATE: Readonly<Record<string, string>> = Object.freeze({});
+
 export type ReturnHost = {
   readonly screenId: string;
   readonly entityId?: string;
 };
 
-export function formatReturnTo(host: ReturnHost): string {
-  return host.entityId !== undefined ? `${host.screenId}/${host.entityId}` : host.screenId;
+export type ReturnTo = {
+  readonly path: string;
+  readonly state: Readonly<Record<string, string>>;
+};
+
+/** Splits `<screenId>[/<entityId>][?<host-params>]`. One `URLSearchParams`
+ *  pass per nesting level — a deeper level stays encoded inside a value and
+ *  is only decoded when that level is reached. */
+export function splitReturnTo(raw: string): ReturnTo {
+  const queryStart = raw.indexOf("?");
+  if (queryStart === -1) return { path: raw, state: NO_RETURN_STATE };
+  return {
+    path: raw.slice(0, queryStart),
+    state: Object.fromEntries(new URLSearchParams(raw.slice(queryStart + 1))),
+  };
+}
+
+// Saturates at MAX_RETURN_DEPTH — callers only ask whether the cap is
+// reached, and an unbounded walk would follow attacker-sized nesting.
+function returnToDepth(raw: string): number {
+  let depth = 1;
+  let current = raw;
+  while (depth < MAX_RETURN_DEPTH) {
+    const nested = splitReturnTo(current).state[RETURN_TO_PARAM];
+    if (nested === undefined) return depth;
+    depth += 1;
+    current = nested;
+  }
+  return depth;
+}
+
+// Both caps degrade to the pre-snapshot value instead of failing, so a value
+// that hits one still navigates.
+function returnStateSnapshot(hostParams: Readonly<Record<string, string>> | undefined): string {
+  if (hostParams === undefined) return "";
+  const snapshot = new URLSearchParams();
+  for (const [key, value] of Object.entries(hostParams)) {
+    if (value === "") continue;
+    if (key === RETURN_TO_PARAM && returnToDepth(value) >= MAX_RETURN_DEPTH) continue;
+    snapshot.set(key, value);
+  }
+  const serialized = snapshot.toString();
+  return serialized.length > MAX_RETURN_STATE_LENGTH ? "" : serialized;
+}
+
+export function formatReturnTo(
+  host: ReturnHost,
+  hostParams?: Readonly<Record<string, string>>,
+): string {
+  const path = host.entityId !== undefined ? `${host.screenId}/${host.entityId}` : host.screenId;
+  const state = returnStateSnapshot(hostParams);
+  return state === "" ? path : `${path}?${state}`;
 }
 
 // {} when target IS host — pushPath no-ops on the same path, so the param
@@ -25,12 +84,13 @@ export function formatReturnTo(host: ReturnHost): string {
 export function returnToParams(
   host: ReturnHost | undefined,
   target: ScreenTarget,
+  hostParams?: Readonly<Record<string, string>>,
 ): Readonly<Record<string, string>> {
   if (host === undefined) return {};
   if (lastSegment(target.screenId) === host.screenId && target.entityId === host.entityId) {
     return {};
   }
-  return { [RETURN_TO_PARAM]: formatReturnTo(host) };
+  return { [RETURN_TO_PARAM]: formatReturnTo(host, hostParams) };
 }
 
 export function navigateWithReturnTo(
@@ -39,16 +99,42 @@ export function navigateWithReturnTo(
   host: ReturnHost | undefined,
   params?: Readonly<Record<string, string | null>>,
 ): void {
+  // Snapshot before navigating — nav.searchParams still describes the host.
+  const returnParams = returnToParams(host, target, nav.searchParams);
   nav.navigate(target);
   const merged: Record<string, string | null> = {
     ...(params ?? {}),
-    ...returnToParams(host, target),
+    ...returnParams,
   };
   if (Object.keys(merged).length > 0) {
     nav.setSearchParams(merged);
   }
 }
 
+/** Jumps back to an already-validated returnTo target and restores the host
+ *  search params carried in the same value. The host's own returnTo travels
+ *  with them, so a chain unwinds one level per jump. */
+export function navigateToReturn(nav: NavApi, target: ScreenTarget): void {
+  const raw = nav.searchParams[RETURN_TO_PARAM];
+  const state = raw === undefined ? NO_RETURN_STATE : splitReturnTo(raw).state;
+  nav.navigate(target);
+  // The explicit null drops this screen's own returnTo on nav impls whose
+  // navigate keeps the query.
+  nav.setSearchParams({ ...state, [RETURN_TO_PARAM]: state[RETURN_TO_PARAM] ?? null });
+}
+
+export function navigateToReturnOr(
+  nav: NavApi,
+  target: ScreenTarget | undefined,
+  fallback: () => void,
+): void {
+  if (target === undefined) {
+    fallback();
+    return;
+  }
+  navigateToReturn(nav, target);
+}
+
 // "%" is left alone — route entityIds come raw from the path and can carry it.
 const UNSAFE_ENTITY_ID_PATTERN = /[\\?#\s]/;
 
@@ -61,7 +147,7 @@ export function resolveReturnTarget(
   userRoles: readonly string[] | undefined,
 ): ScreenTarget | undefined {
   if (raw === undefined || raw === "") return undefined;
-  const segments = raw.split("/");
+  const segments = splitReturnTo(raw).path.split("/");
   if (segments.length !== 1 && segments.length !== 2) return undefined;
   if (segments.some((segment) => segment === "")) return undefined;
   const [screenId, entityId] = segments;

package/src/app/screen-access.ts

@@ -4,6 +4,7 @@ import type {
   FeatureSchema,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import { isOpenToAllGranted } from "@cosmicdrift/kumiko-framework/ui-types";
+import { lastSegment } from "./qn";
 
 // Minimal role-gate for the screen-render path (#1203 — nav filtering via
 // filterByAccess in workspace-shell.tsx hid role-gated screens from the
@@ -23,6 +24,39 @@ export function screenAccessAllows(
   return access.roles.some((role) => userRoles.includes(role));
 }
 
+// A navigate target (metric click) declares no access rule of its own — the
+// destination screen already does, so the jump is offered exactly when the
+// user may open where it lands (solon#424). No second copy of the rule to
+// drift from the screen's own.
+export function navigateTargetAllows(
+  navigate: { readonly screen?: string; readonly entity?: string },
+  appFeatures: readonly FeatureSchema[],
+  userRoles: readonly string[] | undefined,
+): boolean {
+  const { screen, entity } = navigate;
+  // Neither set — stays on the current screen (tab switch), already allowed.
+  if (screen === undefined && entity === undefined) return true;
+  // KumikoScreen rendered outside createKumikoApp has no screen registry to
+  // resolve against; gating on an empty one would hide every jump, not the
+  // forbidden ones.
+  if (appFeatures.length === 0) return true;
+  for (const feature of appFeatures) {
+    for (const candidate of feature.screens) {
+      const isTarget =
+        entity !== undefined
+          ? candidate.detailFor === entity
+          : lastSegment(candidate.id) === screen;
+      // First match IS the destination: short ids are globally unique
+      // (validateScreenShortIdCollisions) and both the router and
+      // resolveTarget take the first hit.
+      if (isTarget) return screenAccessAllows(candidate.access, userRoles);
+    }
+  }
+  // Unresolvable target — the boot-validator doesn't check metric navigate
+  // targets, so this is a typo'd dead jump. Don't offer it.
+  return false;
+}
+
 // Searches all mounted features, and access is part of the predicate so a
 // role-gated first match can't hide an accessible second one.
 export function findEditScreenFor(

package/src/app/secret-mint-body.tsx

@@ -10,11 +10,15 @@ import {
   synthesizeSecretMintConfirmScreen,
 } from "./action-form-shim";
 import type { FeatureSchema } from "./feature-schema";
-import { buildInitialValues, mergeSearchParamsIntoInitial } from "./kumiko-screen";
+import {
+  buildInitialValues,
+  literalCurrencyOverrides,
+  mergeSearchParamsIntoInitial,
+} from "./kumiko-screen";
 import { layoutFieldNames } from "./layout-fields";
 import { useInitialValuesHandoff, useNav } from "./nav";
 import { lastSegment } from "./qn";
-import { useReturnTarget } from "./return-to";
+import { navigateToReturnOr, useReturnTarget } from "./return-to";
 
 export type SecretMintBodyProps = {
   readonly schema: FeatureSchema;
@@ -71,6 +75,11 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
         searchParams: nav.searchParams,
         urlPrefillFields: screen.urlPrefillFields,
         renderableFields: layoutFieldNames(synthScreen),
+        // A mint form has no entity either, so its money fields name their own
+        // currency source (fw#2839). Only the literal form is resolved here:
+        // `{ kind: "tenant" }` would need the config query this screen never
+        // runs, and a one-time secret mint has no money use case to justify it.
+        moneyCurrencyOverrides: literalCurrencyOverrides(screen.fields),
         ...(handoffValues !== undefined && { handoffValues }),
       }) as FormValues,
     [screen.fields, screen.urlPrefillFields, nav.searchParams, synthScreen, handoffValues],
@@ -91,7 +100,14 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
     [screen, confirm],
   );
   const confirmInitial = useMemo(
-    () => (confirm !== undefined ? (buildInitialValues(confirm.fields) as FormValues) : undefined),
+    () =>
+      confirm !== undefined
+        ? (buildInitialValues(
+            confirm.fields,
+            undefined,
+            literalCurrencyOverrides(confirm.fields),
+          ) as FormValues)
+        : undefined,
     [confirm],
   );
 
@@ -114,7 +130,8 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
   const handleCancel = useMemo<(() => void) | undefined>(() => {
     const target = screen.cancelTarget ?? screen.redirect;
     if (target === undefined || target === false) return undefined;
-    return () => nav.navigate(returnTarget ?? { screenId: lastSegment(target) });
+    return () =>
+      navigateToReturnOr(nav, returnTarget, () => nav.navigate({ screenId: lastSegment(target) }));
   }, [nav, screen.redirect, screen.cancelTarget, returnTarget]);
 
   // Ends the reveal phase for both paths (the bare acknowledge button, and a
@@ -125,8 +142,11 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
   const finishMint = useCallback(() => {
     setRevealed(null);
     carriedRef.current = {};
-    if (screen.redirect !== undefined) {
-      nav.navigate(returnTarget ?? { screenId: lastSegment(screen.redirect) });
+    const redirect = screen.redirect;
+    if (redirect !== undefined) {
+      navigateToReturnOr(nav, returnTarget, () =>
+        nav.navigate({ screenId: lastSegment(redirect) }),
+      );
     } else {
       setDone(true);
     }

package/src/app/secrets-edit-body.tsx

@@ -118,6 +118,7 @@ export function SecretsEditBody({ screen, translate }: SecretsEditBodyProps): Re
           key={section.title ?? `section-${index}`}
           {...(section.title !== undefined && { title: effectiveTranslate(section.title) })}
         >
+          {/* kumiko-lint-ignore section-fields-raw secretsEdit section fields are field-id strings, not EditFieldSpec */}
           {section.fields.map((fieldId) => {
             const qualified = screen.secretKeys[fieldId];
             if (qualified === undefined) return null;

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.292.0",
+    "type": "fix",
+    "title": "A projectionDetail metric is only clickable when its navigate target is reachable",
+    "detail": "`MetricNavigate` declares no access rule of its own, so a metric could jump to a screen the current user is not allowed to open — the destination rendered its access-denied banner, or the target's query rejected the request server-side, after the user had already clicked. The metric now derives its gate from the destination: `navigate.screen` is resolved by short id, `navigate.entity` through the screen declaring `detailFor`, and the screen's own `access` decides whether the metric renders clickable at all. No second copy of the rule on the metric, so it cannot drift from the screen's. A `navigate` with only `tab` set stays on the record and is unaffected.\nTwo consequences worth knowing. A navigate target that resolves to no registered screen is treated as denied — the boot-validator does not check metric navigate targets, so a typo'd target used to render a clickable metric that went nowhere and now renders a plain one. And the gate needs the app-wide screen registry `createKumikoApp` provides; a `KumikoScreen` rendered outside it sees no registry and every metric stays clickable, exactly as before."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "returnTo restores the host screen's search params and nests return chains",
+    "detail": "A `returnTo` value may now carry the host's search params as a nested query (`token-detail/abc?tab=keys&orders.sort=name`), so jumping back lands on the tab, filter and sort the user left — `use-list-url-state` keys and `layout.mode: \"tabs\"` included, with no per-key allowlist to keep in sync. The host's own `returnTo` travels inside that snapshot, so a chain (list → edit → action form → back → save) unwinds one level per jump instead of losing its tail. Two syntactic caps bound the URL: at most three screen levels per value, and a snapshot over 512 characters is dropped whole. Both degrade to the previous bare value rather than failing, and a value without a snapshot is byte-identical to before, so existing links keep working. Target validation is unchanged: `resolveReturnTarget` sees only the path part and still rejects anything that is not an accessible in-app screen."
+  },
   {
     "version": "0.290.0",
     "type": "fix",

package/src/components/embedded-list-field.tsx

@@ -151,7 +151,7 @@ export function EmbeddedListField({
   const referenceQueries = referenceCells.map((cell) => {
     const refFeature = cell.refFeature ?? featureName;
     const refEntity = cell.refEntity ?? "";
-    const qn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+    const qn = cell.refOptionsQuery ?? `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
     // biome-ignore lint/correctness/useHookAtTopLevel: referenceCells comes from the entity-schema definition — fixed for the screen's lifetime, not a real conditional-hook risk.
     return useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(qn, {
       limit: REFERENCE_COMBOBOX_LIMIT,
@@ -165,10 +165,10 @@ export function EmbeddedListField({
     if (cell.type === "reference") {
       const idx = referenceCells.indexOf(cell);
       const query = referenceQueries[idx];
-      const labelField = cell.refLabelField ?? "id";
+      const labelKey = cell.refOptionsQuery !== undefined ? "label" : (cell.refLabelField ?? "id");
       const referenceOptions = (query?.data?.rows ?? []).map((row) => ({
         value: String(row["id"] ?? ""),
-        label: String(row[labelField] ?? row["id"] ?? ""),
+        label: String(row[labelKey] ?? row["id"] ?? ""),
       }));
       return {
         field: cell.field,

package/src/components/render-field.tsx

@@ -167,6 +167,24 @@ export function RenderField({
   );
 }
 
+// Where a reference field's option rows come from, and which of their keys
+// holds the display text — the entity's own list handler plus `refLabelField`
+// by default, or an author-supplied handler whose rows carry `label`
+// (fw#2780), for targets with no readable column of their own.
+function referenceOptionSource(
+  field: Pick<EditFieldViewModel, "refLabelField" | "refOptionsQuery">,
+  refFeature: string,
+  refEntity: string,
+): { readonly queryQn: string; readonly labelKey: string } {
+  if (field.refOptionsQuery !== undefined) {
+    return { queryQn: field.refOptionsQuery, labelKey: "label" };
+  }
+  return {
+    queryQn: `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`,
+    labelKey: field.refLabelField ?? "id",
+  };
+}
+
 // 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
@@ -200,12 +218,13 @@ function ReferenceInput({
   const { Banner } = usePrimitives();
   const refEntity = field.refEntity ?? "";
   const refFeature = field.refFeature ?? featureName;
-  const labelField = field.refLabelField ?? "id";
   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).
-  const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  // fw#2780: 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
@@ -276,10 +295,10 @@ function ReferenceInput({
     const rows = queryResult.data?.rows ?? [];
     return rows.map((row) => {
       const idVal = String(row["id"] ?? "");
-      const label = String(row[labelField] ?? idVal);
+      const label = String(row[labelKey] ?? idVal);
       return { value: idVal, label };
     });
-  }, [queryResult.data, labelField]);
+  }, [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.
@@ -431,9 +450,8 @@ function ReadOnlyReferenceValue({
   const t = useTranslation();
   const refEntity = field.refEntity ?? "";
   const refFeature = field.refFeature ?? featureName;
-  const labelField = field.refLabelField ?? "id";
   const isMultiple = field.refMultiple === true;
-  const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
   const queryResult = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
     limit: REFERENCE_COMBOBOX_LIMIT,
   });
@@ -454,7 +472,7 @@ function ReadOnlyReferenceValue({
   const labels = ids.map((id) => {
     if (systemLabel !== undefined && id === systemLabel.id) return t(systemLabel.labelKey);
     const row = rows.find((r) => String(r["id"] ?? "") === id);
-    return row !== undefined ? String(row[labelField] ?? id) : id;
+    return row !== undefined ? String(row[labelKey] ?? id) : id;
   });
   return <Text testId={`field-value-${field.field}`}>{labels.join(", ")}</Text>;
 }

package/src/components/render-list.tsx

@@ -18,6 +18,7 @@ import type { ListSort } from "../hooks/use-list-url-state";
 import { type ReferenceLookupMap, useReferenceLookup } from "../hooks/use-reference-lookup";
 import { useTranslation } from "../i18n";
 import {
+  type DataTableDateRangeFacet,
   type DataTableFacet,
   type DataTableRowAction,
   type DataTableRowActionMode,
@@ -110,6 +111,10 @@ export type RenderListProps = {
   readonly onFilterChange?: (field: string, values: readonly string[]) => void;
   /** Reset aller aktiven Facets. */
   readonly onFilterReset?: () => void;
+  /** Time-range filters (fw#3104) — 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. */
@@ -175,6 +180,8 @@ export function RenderList(props: RenderListProps): ReactNode {
     filterValues,
     onFilterChange,
     onFilterReset,
+    dateRangeFacets,
+    onDateRangeChange,
     chromeless,
     scrollBody,
     screenPadding,
@@ -392,6 +399,8 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(filterValues !== undefined && { filterValues })}
         {...(onFilterChange !== undefined && { onFilterChange })}
         {...(onFilterReset !== undefined && { onFilterReset })}
+        {...(dateRangeFacets !== undefined && { dateRangeFacets })}
+        {...(onDateRangeChange !== undefined && { onDateRangeChange })}
         {...(chromeless !== undefined && { chromeless })}
         {...(scrollBody !== undefined && { scrollBody })}
         {...(screenPadding !== undefined && { screenPadding })}