@cosmicdrift/kumiko-renderer 0.291.0 → 0.293.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.291.0",
+  "version": "0.293.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.291.0",
-    "@cosmicdrift/kumiko-headless": "0.291.0",
-    "@cosmicdrift/kumiko-types": "0.291.0",
+    "@cosmicdrift/kumiko-framework": "0.293.0",
+    "@cosmicdrift/kumiko-headless": "0.293.0",
+    "@cosmicdrift/kumiko-types": "0.293.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.291.0"
+    "@cosmicdrift/kumiko-locale-de": "0.293.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/use-list-url-state.test.tsx

@@ -183,6 +183,55 @@ describe("useListUrlState", () => {
     });
   });
 
+  // fw#3104: the date-range facet lives in the same .f. namespace so
+  // clearFilters covers it — but both bounds have to land in ONE params
+  // update, or the second call overwrites the first.
+  test("setDateRange schreibt beide Grenzen atomar + resettet page", () => {
+    const nav = makeNav({ "orders.page": "4" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setDateRange("createdAt", { from: "2020-06-10", to: "2020-06-14" });
+    });
+    expect(nav.captures).toHaveLength(1);
+    expect(nav.captures[0]).toEqual({
+      "orders.f.createdAt.from": "2020-06-10",
+      "orders.f.createdAt.to": "2020-06-14",
+      "orders.page": null,
+    });
+  });
+
+  test("setDateRange mit leerer Grenze löscht nur diesen Key", () => {
+    const nav = makeNav({
+      "orders.f.createdAt.from": "2020-06-10",
+      "orders.f.createdAt.to": "2020-06-14",
+    });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setDateRange("createdAt", { from: "", to: "2020-06-14" });
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.f.createdAt.from": null,
+      "orders.f.createdAt.to": "2020-06-14",
+      "orders.page": null,
+    });
+  });
+
+  test("clearFilters löscht auch die Zeitraum-Grenzen", () => {
+    const nav = makeNav({
+      "orders.f.createdAt.from": "2020-06-10",
+      "orders.f.createdAt.to": "2020-06-14",
+    });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.clearFilters();
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.page": null,
+      "orders.f.createdAt.from": null,
+      "orders.f.createdAt.to": null,
+    });
+  });
+
   test("clearFilters löscht alle aktiven .f.<field>-Keys", () => {
     const nav = makeNav({
       "orders.f.status": "draft",

package/src/app/__tests__/list-daterange-facet.test.ts

@@ -0,0 +1,165 @@
+// fw#3104: a dateRange facet turns two calendar dates into the two query
+// params it declares. The conversion is the whole risk surface — a calendar
+// date has no time, `createdAt` is an instant, and "to the 14th" has to mean
+// "through the end of the 14th" in the viewer's zone, not "at 00:00".
+
+import { describe, expect, test } from "bun:test";
+import type { ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+import { Temporal } from "temporal-polyfill";
+import {
+  buildDateRangePayload,
+  clampDateRange,
+  readDateRange,
+  resolveDateRangeFacets,
+  resolveProjectionFacetSpecs,
+} from "../list-facets";
+
+const VIENNA = "Europe/Vienna";
+
+const auditFacets: readonly ListFacetSpec[] = [
+  {
+    type: "dateRange",
+    field: "createdAt",
+    label: "audit.log.col.when",
+    params: { from: "from", to: "to" },
+  },
+];
+
+const specs = resolveDateRangeFacets(auditFacets, (key) => key);
+
+function payload(
+  filters: Record<string, readonly string[]>,
+  timeZone = VIENNA,
+): Record<string, string> {
+  return buildDateRangePayload(specs, filters, timeZone);
+}
+
+describe("dateRange facet resolution", () => {
+  test("resolves the declared param names, not a from/to convention", () => {
+    const resolved = resolveDateRangeFacets(
+      [
+        {
+          type: "dateRange",
+          field: "occurredAt",
+          label: "when",
+          params: { from: "since", to: "until" },
+        },
+      ],
+      (key) => key,
+    );
+    expect(resolved).toEqual([
+      { field: "occurredAt", label: "when", fromParam: "since", toParam: "until" },
+    ]);
+  });
+
+  test("stays out of the option-dropdown facets (no `filters` entry)", () => {
+    expect(resolveProjectionFacetSpecs(auditFacets, (key) => key, "audit")).toEqual([]);
+  });
+
+  test("reads both bounds out of the shared f.<field> URL namespace", () => {
+    expect(
+      readDateRange(
+        { "createdAt.from": ["2020-06-10"], "createdAt.to": ["2020-06-14"] },
+        "createdAt",
+      ),
+    ).toEqual({ from: "2020-06-10", to: "2020-06-14" });
+    expect(readDateRange({}, "createdAt")).toEqual({ from: "", to: "" });
+  });
+});
+
+describe("dateRange facet → query params", () => {
+  test("both bounds travel under the declared param names", () => {
+    expect(payload({ "createdAt.from": ["2020-06-10"], "createdAt.to": ["2020-06-14"] })).toEqual({
+      from: "2020-06-09T22:00:00Z",
+      to: "2020-06-14T21:59:59.999999999Z",
+    });
+  });
+
+  test("open interval: only `from` set sends only that param", () => {
+    expect(payload({ "createdAt.from": ["2020-06-10"] })).toEqual({ from: "2020-06-09T22:00:00Z" });
+  });
+
+  test("open interval: only `to` set sends only that param", () => {
+    expect(payload({ "createdAt.to": ["2020-06-14"] })).toEqual({
+      to: "2020-06-14T21:59:59.999999999Z",
+    });
+  });
+
+  test("no bounds set sends nothing", () => {
+    expect(payload({})).toEqual({});
+  });
+
+  test("a half-typed or hand-crafted URL value is dropped, not sent", () => {
+    expect(payload({ "createdAt.from": ["2020-06"], "createdAt.to": ["nonsense"] })).toEqual({});
+  });
+
+  test("bounds follow the viewer's zone", () => {
+    expect(payload({ "createdAt.from": ["2020-06-10"] }, "UTC")).toEqual({
+      from: "2020-06-10T00:00:00Z",
+    });
+  });
+
+  test("DST: the day the clock jumps forward is still bounded by its own edges", () => {
+    // 2020-03-29 is 23h long in Vienna — a naive +24h end-of-day would spill
+    // an hour into the 30th.
+    expect(payload({ "createdAt.from": ["2020-03-29"], "createdAt.to": ["2020-03-29"] })).toEqual({
+      from: "2020-03-28T23:00:00Z",
+      to: "2020-03-29T21:59:59.999999999Z",
+    });
+  });
+});
+
+describe("dateRange facet timezone edge (issue #3104)", () => {
+  test("an event at 23:59 of the `to` day falls inside the range", () => {
+    const { from, to } = payload({
+      "createdAt.from": ["2020-06-14"],
+      "createdAt.to": ["2020-06-14"],
+    });
+    if (from === undefined || to === undefined) throw new Error("expected both bounds");
+    const lateEvent = Temporal.ZonedDateTime.from(`2020-06-14T23:59:00[${VIENNA}]`).toInstant();
+    expect(Temporal.Instant.compare(lateEvent, Temporal.Instant.from(from))).toBeGreaterThan(0);
+    // The handler filters with `lte`, so the last instant of the day counts.
+    expect(Temporal.Instant.compare(lateEvent, Temporal.Instant.from(to))).toBeLessThanOrEqual(0);
+  });
+
+  test("the next day's first moment falls outside", () => {
+    const { to } = payload({ "createdAt.to": ["2020-06-14"] });
+    if (to === undefined) throw new Error("expected a `to` bound");
+    const nextDay = Temporal.ZonedDateTime.from(`2020-06-15T00:00:00[${VIENNA}]`).toInstant();
+    expect(Temporal.Instant.compare(nextDay, Temporal.Instant.from(to))).toBeGreaterThan(0);
+  });
+});
+
+describe("clampDateRange keeps from <= to", () => {
+  test("a `from` past the current `to` pushes `to` along", () => {
+    expect(clampDateRange({ from: "2020-06-01", to: "2020-06-10" }, "from", "2020-06-20")).toEqual({
+      from: "2020-06-20",
+      to: "2020-06-20",
+    });
+  });
+
+  test("a `to` before the current `from` pulls `from` along", () => {
+    expect(clampDateRange({ from: "2020-06-10", to: "2020-06-20" }, "to", "2020-06-01")).toEqual({
+      from: "2020-06-01",
+      to: "2020-06-01",
+    });
+  });
+
+  test("a valid bound leaves the other alone", () => {
+    expect(clampDateRange({ from: "2020-06-01", to: "2020-06-20" }, "from", "2020-06-05")).toEqual({
+      from: "2020-06-05",
+      to: "2020-06-20",
+    });
+  });
+
+  test("clearing a bound never drags the other one with it", () => {
+    expect(clampDateRange({ from: "2020-06-10", to: "2020-06-20" }, "from", "")).toEqual({
+      from: "",
+      to: "2020-06-20",
+    });
+    expect(clampDateRange({ from: "2020-06-10", to: "2020-06-20" }, "to", "")).toEqual({
+      from: "2020-06-10",
+      to: "",
+    });
+  });
+});

package/src/app/__tests__/list-filter-facets.test.tsx

@@ -106,10 +106,11 @@ function renderScreen(
   schema: FeatureSchema,
   qn: string,
   dispatcher: Dispatcher = stubDispatcher(),
+  timeZone = "UTC",
 ): void {
   render(
     <LocaleProvider
-      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      resolver={createStaticLocaleResolver({ locale: "de-DE", timeZone })}
       fallbackBundles={[kumikoDefaultTranslations]}
     >
       <DispatcherProvider dispatcher={dispatcher}>
@@ -426,3 +427,92 @@ describe("projectionList filter + facets (fw#2224)", () => {
     });
   });
 });
+
+// fw#3104: a dateRange facet is the first facet that does NOT travel in
+// payload.filters — its two bounds go out as the top-level params the screen
+// declares. A screen may declare it as its only facet, so the wiring must not
+// hang off the option-facet path.
+describe("projectionList dateRange facet (fw#3104)", () => {
+  const dateRangeScreen: ProjectionListScreenDefinition = {
+    id: "event-list",
+    type: "projectionList",
+    query: "ledger:query:event:list",
+    columns: ["createdAt"],
+    facets: [
+      {
+        field: "createdAt",
+        type: "dateRange",
+        label: "When",
+        params: { from: "from", to: "to" },
+      },
+    ],
+  };
+  const schema: FeatureSchema = {
+    featureName: "ledger",
+    entities: {},
+    screens: [dateRangeScreen],
+  } as FeatureSchema;
+
+  test("reaches the DataTable as a dateRange facet, not as a filter dropdown", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    renderScreen(schema, "ledger:screen:event-list");
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    const props = getCapturedProps();
+    if (props === undefined) throw new Error("DataTable was not rendered");
+    expect(props.dateRangeFacets).toEqual([
+      { field: "createdAt", label: "When", from: "", to: "" },
+    ]);
+    expect(props.filterFacets).toBeUndefined();
+    // Reset still has to be reachable on a dateRange-only screen.
+    expect(props.onFilterReset).toBeDefined();
+    expect(queryCalls[0]?.payload).not.toHaveProperty("from");
+  });
+
+  test("picking a bound sends it as the declared query param, in the viewer's zone", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    renderScreen(schema, "ledger:screen:event-list", stubDispatcher(), "Europe/Vienna");
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    const before = queryCalls.length;
+    await act(async () => {
+      getCapturedProps()?.onDateRangeChange?.("createdAt", "to", "2020-06-14");
+    });
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(before));
+    const payload = queryCalls[queryCalls.length - 1]?.payload;
+    // Open interval: only the bound the user picked travels.
+    expect(payload).toMatchObject({ to: "2020-06-14T21:59:59.999999999Z" });
+    expect(payload).not.toHaveProperty("from");
+    expect(payload).not.toHaveProperty("filters");
+    expect(getCapturedProps()?.dateRangeFacets).toEqual([
+      { field: "createdAt", label: "When", from: "", to: "2020-06-14" },
+    ]);
+  });
+
+  test("a `from` past the current `to` is clamped before it can reach the handler's refine", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    renderScreen(schema, "ledger:screen:event-list", stubDispatcher(), "Europe/Vienna");
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    await act(async () => {
+      getCapturedProps()?.onDateRangeChange?.("createdAt", "to", "2020-06-14");
+    });
+    await act(async () => {
+      getCapturedProps()?.onDateRangeChange?.("createdAt", "from", "2020-06-20");
+    });
+    await waitFor(() =>
+      expect(getCapturedProps()?.dateRangeFacets).toEqual([
+        { field: "createdAt", label: "When", from: "2020-06-20", to: "2020-06-20" },
+      ]),
+    );
+    const payload = queryCalls[queryCalls.length - 1]?.payload as Record<string, string>;
+    const from = payload["from"];
+    const to = payload["to"];
+    expect(from).toBeString();
+    expect(to).toBeString();
+    expect((from ?? "") <= (to ?? "")).toBe(true);
+  });
+});

package/src/app/__tests__/projection-detail-reference-field.test.tsx

@@ -18,6 +18,8 @@ import { KumikoScreen } from "../kumiko-screen";
 import type { NavApi } from "../nav";
 import { NavProvider } from "../nav";
 
+const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+
 const noop = (): ReactNode => null;
 const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
 // passChildren would drop testId — ReadOnlyReferenceValue/readOnlyDisplayText
@@ -55,7 +57,7 @@ function stubDispatcher(): Dispatcher {
       if (type === "sessions:query:session:detail") {
         return {
           isSuccess: true,
-          data: { id: "sess-1", userId: "u-1", ip: "10.0.0.1" },
+          data: { id: "sess-1", userId: "u-1", actedBy: SYSTEM_USER_ID, ip: "10.0.0.1" },
         };
       }
       if (type === "user:query:user:list") {
@@ -84,7 +86,13 @@ const detailScreen: ProjectionDetailScreenDefinition = {
   layout: {
     sections: [
       {
-        fields: [{ field: "userId", refEntity: "user:user", refLabelField: "displayName" }, "ip"],
+        fields: [
+          { field: "userId", refEntity: "user:user", refLabelField: "displayName" },
+          // Mirrors the audit-log detail actor field (fw#3103) — a system
+          // write has no read_users row for the bulk lookup to find.
+          { field: "actedBy", refEntity: "user:user", refLabelField: "displayName" },
+          "ip",
+        ],
       },
     ],
   },
@@ -137,6 +145,14 @@ describe("projectionDetail reference field resolves labels (fw#2662)", () => {
     });
   });
 
+  test("SYSTEM_USER_ID resolves to the system label instead of the raw id (fw#3103)", async () => {
+    const { getByTestId } = renderDetailScreen();
+
+    await waitFor(() => {
+      expect(getByTestId("field-value-actedBy").textContent).toBe("System");
+    });
+  });
+
   test("non-regression: a field without refEntity metadata renders its raw value unchanged", async () => {
     const { getByTestId } = renderDetailScreen();
 

package/src/app/__tests__/projection-list-reference-column.test.tsx

@@ -6,7 +6,10 @@
 // text back off the reference column's injected runtime renderer.
 
 import { describe, expect, test } from "bun:test";
-import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type {
+  ListColumnSpec,
+  ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher, RuntimeRenderer } from "@cosmicdrift/kumiko-headless";
 import { render, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
@@ -21,6 +24,9 @@ import { NavProvider } from "../nav";
 
 const SYSTEM_TENANT_ID = "00000000-0000-4000-8000-000000000000";
 const REAL_TENANT_ID = "11111111-1111-4111-8111-111111111111";
+const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+const REAL_USER_ID = "22222222-2222-4222-8222-222222222222";
+const DELETED_USER_ID = "33333333-3333-4333-8333-333333333333";
 
 let capturedProps: DataTableProps | undefined;
 const captureDataTable: ComponentType<DataTableProps> = (props) => {
@@ -61,8 +67,9 @@ function stubDispatcher(): Dispatcher {
           isSuccess: true,
           data: {
             rows: [
-              { id: "row-1", tenantId: REAL_TENANT_ID },
-              { id: "row-2", tenantId: SYSTEM_TENANT_ID },
+              { id: "row-1", tenantId: REAL_TENANT_ID, createdBy: REAL_USER_ID },
+              { id: "row-2", tenantId: SYSTEM_TENANT_ID, createdBy: SYSTEM_USER_ID },
+              { id: "row-3", tenantId: REAL_TENANT_ID, createdBy: DELETED_USER_ID },
             ],
             nextCursor: null,
           },
@@ -74,6 +81,12 @@ function stubDispatcher(): Dispatcher {
           data: { rows: [{ id: REAL_TENANT_ID, name: "Acme Inc" }], nextCursor: null },
         };
       }
+      if (type === "user:query:user:list") {
+        return {
+          isSuccess: true,
+          data: { rows: [{ id: REAL_USER_ID, displayName: "Ada Lovelace" }], nextCursor: null },
+        };
+      }
       return { isSuccess: true, data: { rows: [], nextCursor: null } };
     }) as unknown as Dispatcher["query"],
     batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
@@ -95,6 +108,21 @@ function buildSchema(screen: ProjectionListScreenDefinition): FeatureSchema {
   } as FeatureSchema;
 }
 
+const TENANT_COLUMN: ListColumnSpec = {
+  field: "tenantId",
+  label: "delivery.log.col.tenantId",
+  refEntity: "tenant:tenant",
+  refLabelField: "name",
+};
+
+// Mirrors the audit-log actor column (fw#3103).
+const ACTOR_COLUMN: ListColumnSpec = {
+  field: "createdBy",
+  label: "audit.log.col.actor",
+  refEntity: "user:user",
+  refLabelField: "displayName",
+};
+
 const staticNav: NavApi = {
   route: { screenId: "delivery:screen:log" },
   navigate: () => {},
@@ -104,19 +132,12 @@ const staticNav: NavApi = {
   setSearchParams: () => {},
 };
 
-function renderLogScreen(): void {
+function renderLogScreen(column: ListColumnSpec = TENANT_COLUMN): void {
   const screen: ProjectionListScreenDefinition = {
     id: "log",
     type: "projectionList",
     query: "delivery:query:log:list",
-    columns: [
-      {
-        field: "tenantId",
-        label: "delivery.log.col.tenantId",
-        refEntity: "tenant:tenant",
-        refLabelField: "name",
-      },
-    ],
+    columns: [column],
   };
   render(
     <LocaleProvider
@@ -134,8 +155,8 @@ function renderLogScreen(): void {
   );
 }
 
-function referenceRenderer(): RuntimeRenderer {
-  const col = getCapturedProps()?.columns.find((c) => c.field === "tenantId");
+function referenceRenderer(field = "tenantId"): RuntimeRenderer {
+  const col = getCapturedProps()?.columns.find((c) => c.field === field);
   if (typeof col?.renderer !== "function") throw new Error("reference column has no renderer yet");
   return col.renderer as RuntimeRenderer;
 }
@@ -159,3 +180,35 @@ describe("projectionList reference column resolves labels (fw#2662)", () => {
     });
   });
 });
+
+describe("actor column resolves display names (fw#3103)", () => {
+  const actorCell = (id: string): unknown => referenceRenderer("createdBy")(id, { createdBy: id });
+
+  test("a real user id resolves to the display name", async () => {
+    capturedProps = undefined;
+    renderLogScreen(ACTOR_COLUMN);
+
+    await waitFor(() => {
+      expect(actorCell(REAL_USER_ID)).toBe("Ada Lovelace");
+    });
+  });
+
+  test("SYSTEM_USER_ID resolves to the system label", async () => {
+    capturedProps = undefined;
+    renderLogScreen(ACTOR_COLUMN);
+
+    await waitFor(() => {
+      expect(actorCell(SYSTEM_USER_ID)).toBe("System");
+    });
+  });
+
+  test("an unresolvable actor (deleted user) falls back to the raw id without throwing", async () => {
+    capturedProps = undefined;
+    renderLogScreen(ACTOR_COLUMN);
+
+    await waitFor(() => {
+      expect(actorCell(REAL_USER_ID)).toBe("Ada Lovelace");
+    });
+    expect(actorCell(DELETED_USER_ID)).toBe(DELETED_USER_ID);
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -50,8 +50,9 @@ import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-cont
 import { useUserRoles } from "../context/user-roles-context";
 import { type ListSort, useListUrlState } from "../hooks/use-list-url-state";
 import { type UseQueryResult, useQuery } from "../hooks/use-query";
-import { useTranslation } from "../i18n";
+import { useOptionalTimeZone, useTranslation } from "../i18n";
 import {
+  type DataTableDateRangeFacet,
   type DataTableFacet,
   type DataTableRowAction,
   statusToneForValue,
@@ -66,10 +67,14 @@ import type { FeatureSchema } from "./feature-schema";
 import { buildFormSchema } from "./form-schema";
 import { layoutFieldNames } from "./layout-fields";
 import {
+  buildDateRangePayload,
   buildFilterFacets,
   buildFilterPayload,
+  clampDateRange,
   mergeReferenceFacetOptions,
   type ResolvedFacetSpec,
+  readDateRange,
+  resolveDateRangeFacets,
   resolveProjectionFacetSpecs,
 } from "./list-facets";
 import { type NavApi, type ScreenTarget, useInitialValuesHandoff, useNav } from "./nav";
@@ -101,7 +106,7 @@ import {
   runProjectionRowNavigate,
   stringifyNavParams,
 } from "./row-actions";
-import { findEditScreenFor, screenAccessAllows } from "./screen-access";
+import { findEditScreenFor, navigateTargetAllows, screenAccessAllows } from "./screen-access";
 import { SecretMintBody } from "./secret-mint-body";
 import { SecretsEditBody } from "./secrets-edit-body";
 import { dispatcherErrorText, WriteFailedError } from "./write-failed-error";
@@ -2410,6 +2415,19 @@ function ProjectionListBody({
     [urlState.filters, facetSpecs],
   );
 
+  // dateRange facets (fw#3104) bypass `filters` entirely — their two bounds
+  // become the top-level query params the facet declares, resolved from a
+  // calendar date to an instant in the viewer's zone.
+  const timeZone = useOptionalTimeZone();
+  const dateRangeSpecs = useMemo(
+    () => resolveDateRangeFacets(screen.facets, effectiveTranslate),
+    [screen.facets, effectiveTranslate],
+  );
+  const dateRangePayload = useMemo(
+    () => buildDateRangePayload(dateRangeSpecs, urlState.filters, timeZone),
+    [dateRangeSpecs, urlState.filters, timeZone],
+  );
+
   const queryPayload = useMemo(() => {
     const payload = buildListQueryPayload({
       limit,
@@ -2430,6 +2448,7 @@ function ProjectionListBody({
     if (screen.facets !== undefined && filterPayload.length > 0) {
       payload["filters"] = filterPayload;
     }
+    Object.assign(payload, dateRangePayload);
     return payload;
   }, [
     limit,
@@ -2440,6 +2459,7 @@ function ProjectionListBody({
     screen.filter,
     screen.facets,
     filterPayload,
+    dateRangePayload,
   ]);
 
   const rowsQuery = useQuery<PagedRows>(screen.query, queryPayload, { live: true });
@@ -2448,6 +2468,24 @@ function ProjectionListBody({
     () => buildFilterFacets(resolvedFacetSpecs),
     [resolvedFacetSpecs],
   );
+  const dateRangeFacets = useMemo<DataTableDateRangeFacet[]>(
+    () =>
+      dateRangeSpecs.map((spec) => ({
+        field: spec.field,
+        label: spec.label,
+        ...readDateRange(urlState.filters, spec.field),
+      })),
+    [dateRangeSpecs, urlState.filters],
+  );
+  const handleDateRangeChange = useCallback(
+    (field: string, bound: "from" | "to", value: string) => {
+      urlState.setDateRange(
+        field,
+        clampDateRange(readDateRange(urlState.filters, field), bound, value),
+      );
+    },
+    [urlState.setDateRange, urlState.filters],
+  );
 
   // Entity-Targets (fw#2228) — see EntityListBody.runNavigate for why the
   // resolution happens in the NavApi impl. Unlike there: NO row["id"]
@@ -2583,8 +2621,14 @@ function ProjectionListBody({
         {...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick })}
         {...(filterFacets.length > 0 && {
           filterFacets,
-          filterValues: urlState.filters,
           onFilterChange: urlState.setFilter,
+        })}
+        {...(dateRangeFacets.length > 0 && {
+          dateRangeFacets,
+          onDateRangeChange: handleDateRangeChange,
+        })}
+        {...((filterFacets.length > 0 || dateRangeFacets.length > 0) && {
+          filterValues: urlState.filters,
           onFilterReset: urlState.clearFilters,
         })}
       />
@@ -3184,7 +3228,7 @@ function ProjectionDetailBody({
                 const testId = `kumiko-screen-projection-detail-metric-${field}`;
                 const navigate = metricNavigateSpec(metric);
                 const onPress =
-                  navigate !== undefined
+                  navigate !== undefined && navigateTargetAllows(navigate, appFeatures, userRoles)
                     ? () => runMetricNavigate(nav, navigate, record, host)
                     : undefined;
                 return Metric !== undefined ? (

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/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/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "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",

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 })}

package/src/hooks/use-list-url-state.ts

@@ -48,6 +48,14 @@ export type ListUrlStateApi = ListUrlState & {
   readonly setFilter: (field: string, values: readonly string[]) => void;
   /** Löscht alle aktiven Faceted-Filter (Reset-Button). */
   readonly clearFilters: () => void;
+  /** Sets both bounds of a dateRange facet in ONE params update — two
+   *  setFilter calls would overwrite each other, since the second still sees
+   *  the old searchParams. An empty string clears that bound. Resets the page
+   *  like setFilter. */
+  readonly setDateRange: (
+    field: string,
+    next: { readonly from: string; readonly to: string },
+  ) => void;
 };
 
 // `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
@@ -142,11 +150,22 @@ export function useListUrlState(screenId: string): ListUrlStateApi {
     [nav, screenId],
   );
 
+  const setDateRange = useCallback(
+    (field: string, next: { readonly from: string; readonly to: string }) => {
+      nav.setSearchParams({
+        [key(screenId, `f.${field}.from`)]: next.from === "" ? null : next.from,
+        [key(screenId, `f.${field}.to`)]: next.to === "" ? null : next.to,
+        [key(screenId, "page")]: null,
+      });
+    },
+    [nav, screenId],
+  );
+
   const clearFilters = useCallback(() => {
     const updates: Record<string, string | null> = { [key(screenId, "page")]: null };
     for (const field of Object.keys(filters)) updates[key(screenId, `f.${field}`)] = null;
     nav.setSearchParams(updates);
   }, [nav, screenId, filters]);
 
-  return { sort, q, page, filters, setSort, setQ, setPage, setFilter, clearFilters };
+  return { sort, q, page, filters, setSort, setQ, setPage, setFilter, clearFilters, setDateRange };
 }

package/src/i18n-defaults.ts

@@ -67,6 +67,7 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.related-list-truncated":
       "Showing the first {count} entries. More are available but not loaded — this list does not paginate.",
     "kumiko.reference.system-tenant": "System",
+    "kumiko.reference.system-user": "System",
 
     "kumiko.pager.status": "{from}–{to} of {total}",
     "kumiko.pager.previousPage": "Previous page",

package/src/i18n.tsx

@@ -205,6 +205,17 @@ export function useOptionalLocale(): string | undefined {
   return ctx === undefined ? undefined : ctx.resolver.locale();
 }
 
+/** Non-throwing time-zone read — "UTC" outside LocaleProvider, matching
+ *  createStaticLocaleResolver's own default. */
+export function useOptionalTimeZone(): string {
+  const ctx = useContext(LocaleContext);
+  return useSyncExternalStore(
+    (onStoreChange) => (ctx ? ctx.resolver.subscribe(onStoreChange) : () => {}),
+    () => (ctx ? ctx.resolver.timeZone() : "UTC"),
+    () => (ctx ? ctx.resolver.timeZone() : "UTC"),
+  );
+}
+
 /** Non-throwing translate — undefined outside LocaleProvider. */
 export function useOptionalTranslation():
   | ((key: string, params?: Readonly<Record<string, unknown>>) => string)

package/src/index.ts

@@ -64,6 +64,13 @@ export type {
 export { isAppSchema, toAppSchema } from "./app/feature-schema";
 export type { KumikoScreenProps } from "./app/kumiko-screen";
 export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen";
+export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets";
+export {
+  buildDateRangePayload,
+  clampDateRange,
+  readDateRange,
+  resolveDateRangeFacets,
+} from "./app/list-facets";
 export type {
   NavApi,
   NavProviderProps,
@@ -188,6 +195,7 @@ export type {
   CardProps,
   CardSlots,
   CorePrimitives,
+  DataTableDateRangeFacet,
   DataTableFacet,
   DataTableProps,
   DataTableRowAction,

package/src/primitives.tsx

@@ -572,6 +572,18 @@ export type DataTableFacet = {
   readonly options: readonly { readonly value: string; readonly label: string }[];
 };
 
+// Time-range filter slot in the toolbar (fw#3104): two date inputs
+// (from/to) instead of an options dropdown. Values are `YYYY-MM-DD` or ""
+// (bound open) — the caller converts them into query params.
+export type DataTableDateRangeFacet = {
+  /** The facet's namespace (its date field) — a key, not a filter value. */
+  readonly field: string;
+  /** Translated label ("When"). */
+  readonly label: string;
+  readonly from: string;
+  readonly to: string;
+};
+
 export type DataTableProps = {
   readonly columns: readonly ListColumnViewModel[];
   readonly rows: readonly ListRowViewModel[];
@@ -622,6 +634,10 @@ export type DataTableProps = {
   /** Reset-Button: löscht alle aktiven Facets. Renderer zeigt ihn nur
    *  wenn mindestens ein Facet aktiv ist. */
   readonly onFilterReset?: () => void;
+  /** Time-range filters beside the facet dropdowns (fw#3104). */
+  readonly dateRangeFacets?: readonly DataTableDateRangeFacet[];
+  /** One bound changed ("" clears it) → caller writes URL state + refetch. */
+  readonly onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void;
   /** Pagination-State + Callback. Wenn gesetzt, rendert der Renderer
    *  einen Pager unter der Tabelle (Web: Footer-Bar mit ← 1 ... N →).
    *  total/limit/page sind 1-basiert für die UI; Server-Translation