@cosmicdrift/kumiko-renderer 0.327.0 → 0.328.1

package/{src/app/qn.ts → dist/app/qn.js}

@@ -16,21 +16,19 @@
 // nimmt den letzten ":"-getrennten Teil. Robust gegen Strings ohne
 // ":" (returnt sie unverändert, damit App-Author-Code mit Short-Form-
 // ids in eigenen Stellen weiter passt).
-
-export function lastSegment(qn: string): string {
-  const idx = qn.lastIndexOf(":");
-  return idx < 0 ? qn : qn.slice(idx + 1);
+export function lastSegment(qn) {
+    const idx = qn.lastIndexOf(":");
+    return idx < 0 ? qn : qn.slice(idx + 1);
 }
-
 /**
  * Client-safe copy of framework `toKebab` (engine/qualified-name.ts).
  * Must stay in sync — do NOT import from `@cosmicdrift/kumiko-framework/engine`
  * here: that barrel pulls server deps into the browser bundle.
  */
-export function toKebab(input: string): string {
-  return input
-    .replace(/\./g, "-")
-    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
-    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-    .toLowerCase();
+export function toKebab(input) {
+    return input
+        .replace(/\./g, "-")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase();
 }

package/dist/app/qualify-screen-id.d.ts

@@ -0,0 +1,2 @@
+export declare function qualifyScreenId(featureName: string, screenId: string): string;
+export declare function featureNameFromQualifiedScreenId(id: string): string | undefined;

package/{src/app/qualify-screen-id.ts → dist/app/qualify-screen-id.js}

@@ -1,15 +1,14 @@
 // Dependency-free: kumiko-screen.tsx already imports useNav from nav.tsx, so
 // this can't live in either without a cycle. Form must match the registry's
 // qualification rule (packages/framework/src/engine/qualified-name.ts).
-export function qualifyScreenId(featureName: string, screenId: string): string {
-  return `${featureName}:screen:${screenId}`;
+export function qualifyScreenId(featureName, screenId) {
+    return `${featureName}:screen:${screenId}`;
 }
-
 // Inverse of qualifyScreenId. A short id ("task-list") has no feature
 // segment and returns undefined — callers need that to tell "this redirect
 // names a feature" apart from "this redirect is feature-less, resolve by
 // short id alone" (fw#2485).
-export function featureNameFromQualifiedScreenId(id: string): string | undefined {
-  const parts = id.split(":");
-  return parts.length === 3 && parts[1] === "screen" ? parts[0] : undefined;
+export function featureNameFromQualifiedScreenId(id) {
+    const parts = id.split(":");
+    return parts.length === 3 && parts[1] === "screen" ? parts[0] : undefined;
 }

package/dist/app/reference-facet-bridge.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+import type { ResolvedFacetSpec } from "./list-facets.js";
+export type ReferenceFacetOption = {
+    readonly value: string;
+    readonly label: string;
+};
+export declare function ReferenceFacetBridges({ specs, onOptions, }: {
+    readonly specs: readonly ResolvedFacetSpec[];
+    readonly onOptions: (field: string, options: readonly ReferenceFacetOption[]) => void;
+}): ReactNode;

package/dist/app/reference-facet-bridge.js

@@ -0,0 +1,22 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// One bridge component per reference facet, mirroring ReferenceLookupBridge —
+// facet count varies per screen, so the hook can't be called in a loop.
+import { useEffect } from "react";
+import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
+function ReferenceFacetOptionsBridge({ field, refEntity, refFeature, labelField, onOptions, }) {
+    const lookup = useReferenceLookup(refFeature, refEntity, labelField);
+    useEffect(() => {
+        if (lookup.loading)
+            return;
+        onOptions(field, [...lookup.map.entries()].map(([value, label]) => ({ value, label })));
+    }, [lookup.loading, lookup.map, field, onOptions]);
+    return null;
+}
+// One invisible bridge per "reference" facet spec, each publishing its
+// resolved options back via `onOptions` once loaded.
+export function ReferenceFacetBridges({ specs, onOptions, }) {
+    const referenceSpecs = specs.filter((spec) => spec.reference !== undefined);
+    if (referenceSpecs.length === 0)
+        return null;
+    return (_jsx(_Fragment, { children: referenceSpecs.map((spec) => (_jsx(ReferenceFacetOptionsBridge, { field: spec.field, refEntity: spec.reference?.refEntity ?? "", refFeature: spec.reference?.refFeature ?? "", labelField: spec.reference?.labelField ?? "id", onOptions: onOptions }, spec.field))) }));
+}

package/dist/app/return-to.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import type { FeatureSchema } from "./feature-schema.js";
+import { type NavApi, type NavTarget, type ScreenTarget } from "./nav.js";
+export declare const RETURN_TO_PARAM = "returnTo";
+export type ReturnHost = {
+    readonly screenId: string;
+    readonly entityId?: string;
+};
+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 declare function splitReturnTo(raw: string): ReturnTo;
+export declare function formatReturnTo(host: ReturnHost, hostParams?: Readonly<Record<string, string>>): string;
+export declare function returnToParams(host: ReturnHost | undefined, target: ScreenTarget, hostParams?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+export declare function navigateWithReturnTo(nav: NavApi, target: NavTarget, host: ReturnHost | undefined, params?: Readonly<Record<string, string | null>>): void;
+/** 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 declare function navigateToReturn(nav: NavApi, target: ScreenTarget): void;
+export declare function navigateToReturnOr(nav: NavApi, target: ScreenTarget | undefined, fallback: () => void): void;
+export declare function resolveReturnTarget(raw: string | undefined, ownScreenId: string, features: readonly FeatureSchema[], userRoles: readonly string[] | undefined): ScreenTarget | undefined;
+export declare function ReturnHostProvider({ value, children, }: {
+    readonly value: ReturnHost;
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function useReturnHost(): ReturnHost | undefined;
+export declare function useReturnTarget(ownScreenId: string): ScreenTarget | undefined;

package/dist/app/return-to.js

@@ -0,0 +1,188 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { useUserRoles } from "../context/user-roles-context.js";
+import { useAppFeatures } from "./app-features-context.js";
+import { useNav, } from "./nav.js";
+import { lastSegment } from "./qn.js";
+import { screenAccessAllows } from "./screen-access.js";
+// A search param, not nav/route state, so it survives a full page reload
+// 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 = Object.freeze({});
+/** 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) {
+    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) {
+    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) {
+    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, hostParams) {
+    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
+// would land on the current page instead of the one being left.
+export function returnToParams(host, target, hostParams) {
+    if (host === undefined)
+        return {};
+    if (lastSegment(target.screenId) === host.screenId && target.entityId === host.entityId) {
+        return {};
+    }
+    return { [RETURN_TO_PARAM]: formatReturnTo(host, hostParams) };
+}
+// ObjectTarget only resolves to a path inside the NavApi impl (detailFor
+// lookup across all features), so compare hrefs instead of the raw target.
+function objectTargetIsHost(nav, target, host) {
+    const hostTarget = {
+        screenId: host.screenId,
+        ...(host.entityId !== undefined && { entityId: host.entityId }),
+    };
+    return nav.hrefFor(target) === nav.hrefFor(hostTarget);
+}
+function returnParamsFor(nav, target, host) {
+    if ("screenId" in target)
+        return returnToParams(host, target, nav.searchParams);
+    if (host === undefined || objectTargetIsHost(nav, target, host))
+        return {};
+    return { [RETURN_TO_PARAM]: formatReturnTo(host, nav.searchParams) };
+}
+export function navigateWithReturnTo(nav, target, host, params) {
+    // Snapshot before navigating — nav.searchParams still describes the host.
+    const returnParams = returnParamsFor(nav, target, host);
+    nav.navigate(target);
+    const merged = {
+        ...(params ?? {}),
+        ...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, target) {
+    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, target, fallback) {
+    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]/;
+// Every failure branch returns undefined so a malformed or stale value falls
+// back to the caller's own default instead of throwing.
+export function resolveReturnTarget(raw, ownScreenId, features, userRoles) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    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;
+    if (screenId === undefined || screenId.includes(":"))
+        return undefined;
+    if (screenId === lastSegment(ownScreenId))
+        return undefined;
+    let matched;
+    for (const feature of features) {
+        matched = feature.screens.find((s) => lastSegment(s.id) === screenId);
+        if (matched !== undefined)
+            break;
+    }
+    if (matched === undefined)
+        return undefined;
+    if (!screenAccessAllows(matched.access, userRoles))
+        return undefined;
+    if (entityId !== undefined) {
+        if (entityId === "." || entityId === "..")
+            return undefined;
+        if (UNSAFE_ENTITY_ID_PATTERN.test(entityId))
+            return undefined;
+        let decodedEntityId;
+        try {
+            decodedEntityId = decodeURIComponent(entityId);
+        }
+        catch {
+            return undefined;
+        }
+        if (decodedEntityId === "." || decodedEntityId === "..")
+            return undefined;
+        if (UNSAFE_ENTITY_ID_PATTERN.test(decodedEntityId) || decodedEntityId.includes("/")) {
+            return undefined;
+        }
+        if (matched.type !== "entityEdit" && matched.type !== "projectionDetail")
+            return undefined;
+    }
+    if (matched.type === "projectionDetail" && matched.singleton !== true && entityId === undefined) {
+        return undefined;
+    }
+    return { screenId, ...(entityId !== undefined && { entityId }) };
+}
+const ReturnHostContext = createContext(undefined);
+export function ReturnHostProvider({ value, children, }) {
+    return _jsx(ReturnHostContext.Provider, { value: value, children: children });
+}
+export function useReturnHost() {
+    return useContext(ReturnHostContext);
+}
+// Reads through useNav().searchParams (reactive), not a useState snapshot —
+// a later setSearchParams call must not leave this stale.
+export function useReturnTarget(ownScreenId) {
+    const nav = useNav();
+    const features = useAppFeatures();
+    const userRoles = useUserRoles();
+    const raw = nav.searchParams[RETURN_TO_PARAM];
+    return useMemo(() => resolveReturnTarget(raw, ownScreenId, features, userRoles), [raw, ownScreenId, features, userRoles]);
+}

package/dist/app/row-actions.d.ts

@@ -0,0 +1,77 @@
+import type { EntityEditScreenDefinition, RelatedListToolbarAction, RowAction, RowActionDrawer, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ToolbarAction } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher, ListRowViewModel, Translate } from "@cosmicdrift/kumiko-headless";
+import type { RenderEditAction } from "../components/render-edit-types.js";
+import type { ToolbarActionButton } from "../components/render-list.js";
+import type { DataTableRowAction } from "../primitives.js";
+import type { NavApi } from "./nav.js";
+import { type ReturnHost } from "./return-to.js";
+export declare function buildDefaultEditRowAction(editScreen: EntityEditScreenDefinition | undefined, idColumn?: string): RowActionNavigate | undefined;
+export declare function evalRowExtractor(extractor: RowFieldExtractor, row: Record<string, unknown>): Record<string, unknown>;
+export declare function isWriteHandlerRowAction(action: RowAction): action is RowActionWriteHandler;
+export declare function stringifyNavParams(params: Record<string, unknown>): Record<string, string | null>;
+export declare function navigateActionSearchParams(action: RowActionNavigate, values: Readonly<Record<string, unknown>>): Record<string, string | null> | undefined;
+export declare function refetchAfterWrite(refetch: () => Promise<unknown>): Promise<void>;
+export declare function runProjectionRowNavigate(nav: NavApi, action: RowActionNavigate, row: ListRowViewModel, host: ReturnHost | undefined): void;
+type OpenDrawer = (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void;
+/** @internal test-only */
+export declare function resetDrawerActionWarningsForTests(): void;
+export declare function buildProjectionRowActions(options: {
+    readonly rowActions: readonly RowAction[] | undefined;
+    readonly translate: Translate;
+    readonly dispatcher: Dispatcher | undefined;
+    readonly nav: NavApi;
+    readonly refetch: () => Promise<unknown>;
+    /** Opens the drawer-kind action's target actionForm, prefilled from the
+     *  clicked row. Omitted callers (e.g. RelatedListSection embedded directly
+     *  without onOpenDrawer) drop drawer actions and get a dev warning —
+     *  mirrors the `dispatcher === undefined` skip below for writeHandler. */
+    readonly openDrawer?: OpenDrawer;
+    /** Prepended unless a declared action already has id "edit" — declared wins. */
+    readonly defaultEditRowAction?: RowActionNavigate;
+    readonly host: ReturnHost | undefined;
+}): readonly DataTableRowAction[] | undefined;
+type OpenToolbarDrawer = (action: ToolbarAction & {
+    readonly kind: "drawer";
+}) => void;
+export declare function buildProjectionToolbarActions(options: {
+    readonly toolbarActions: readonly RelatedListToolbarAction[] | undefined;
+    readonly translate: Translate;
+    readonly dispatcher: Dispatcher | undefined;
+    readonly nav: NavApi;
+    readonly refetch: () => Promise<unknown>;
+    /** Omitted callers drop drawer-kind toolbar actions and get a dev warning,
+     *  mirroring the rowActions behavior above. */
+    readonly openDrawer?: OpenToolbarDrawer;
+    /** Search params set on the target after a navigate-kind action, e.g. a
+     *  relatedList's parent id for create-form prefill. */
+    readonly navigatePrefill?: Readonly<Record<string, unknown>>;
+    /** The relatedList's parent record — only a relatedList caller has one.
+     *  Enables `visible`/`params` (RelatedListToolbarAction), evaluated
+     *  against it exactly like header actions/RowAction.visible. Plain
+     *  entityList/projectionList toolbars have no record and omit this. */
+    readonly record?: Readonly<Record<string, unknown>>;
+    readonly host: ReturnHost | undefined;
+}): readonly ToolbarActionButton[] | undefined;
+export declare function buildRecordActions(options: {
+    readonly actions: readonly RowAction[];
+    readonly record: Readonly<Record<string, unknown>>;
+    readonly translate: Translate;
+    readonly nav: NavApi;
+    readonly host: ReturnHost | undefined;
+    readonly dispatcher: Dispatcher | undefined;
+    readonly openDrawer: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void;
+    /** Called after a writeHandler action succeeds (refetch/reload). */
+    readonly onWriteSuccess: () => void | Promise<void>;
+    /** Screen-target navigate default entityId when the action declares no
+     *  explicit `entityId` field-source. A caller editing a fixed entity can
+     *  pass its own `entityId` here directly (the record it already is). A
+     *  caller whose shown record may differ from the navigate target's entity
+     *  resolves this per-target via `sameEntityScreenId` instead. */
+    readonly defaultScreenTargetEntityId?: string;
+    /** Given a navigate action's target screen id, returns the record id to
+     *  default to IF that screen edits the same entity the current record
+     *  belongs to (cross-feature lookup) — undefined otherwise. Omitted by
+     *  callers with no such cross-screen lookup. */
+    readonly sameEntityScreenId?: (targetScreen: string) => string | undefined;
+}): readonly RenderEditAction[] | undefined;
+export {};