@cosmicdrift/kumiko-renderer 0.373.0 → 0.374.0

package/dist/app/action-form-support.d.ts

@@ -0,0 +1,51 @@
+import type { ActionFormLoad } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { DispatcherError, Translate } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+/** Record id of a `load` form: the route path id, else the drawer prefill `id`
+ *  (the clicked row), else the URL `id` param. Only the id is read from these
+ *  sources, never another value. */
+export declare function resolveActionFormRecordId(sources: {
+    readonly routeEntityId: string | undefined;
+    readonly drawerOverrides: Readonly<Record<string, unknown>> | undefined;
+    readonly searchParams: Readonly<Record<string, string>>;
+}): string | undefined;
+export type ActionFormLoadState = {
+    readonly status: "missing-id";
+} | {
+    readonly status: "loading";
+} | {
+    readonly status: "error";
+    readonly error: DispatcherError;
+} | {
+    readonly status: "missing-record";
+} | {
+    readonly status: "ready";
+    readonly values: Readonly<Record<string, unknown>>;
+};
+/** A sensitive, writeOnly or password field never takes a value from a loaded
+ *  record: the form must not echo a secret back into an input. */
+export declare function isSecretFormField(field: unknown): boolean;
+/** Loads the initial values of an actionForm declaring `load`; undefined for a
+ *  form without `load`. */
+export declare function useActionFormLoad(load: ActionFormLoad | undefined, recordId: string | undefined, fieldNames: readonly string[]): ActionFormLoadState | undefined;
+/** Banner for every `load` state that is not "ready". */
+export declare function ActionFormLoadStatus({ state, screenId, translate, }: {
+    readonly state: Exclude<ActionFormLoadState, {
+        readonly status: "ready";
+    }>;
+    readonly screenId: string;
+    readonly translate: Translate;
+}): ReactNode;
+export type ResolvedSuccessLink = {
+    readonly key: string;
+    readonly label: string;
+    readonly href: string;
+    readonly onPress: () => void;
+};
+export type ActionFormSuccessState = {
+    readonly text: string;
+    readonly links: readonly ResolvedSuccessLink[];
+};
+export declare function ActionFormSuccessBanner({ success, }: {
+    readonly success: ActionFormSuccessState;
+}): ReactNode;

package/dist/app/action-form-support.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { useMemo } from "react";
+import { useQuery } from "../hooks/use-query.js";
+import { usePrimitives } from "../primitives.js";
+import { QueryLoadingBanner } from "./query-state-banners.js";
+import { dispatcherErrorText } from "./write-failed-error.js";
+const DEFAULT_LOAD_ID_PARAM = "id";
+function nonEmptyId(value) {
+    if (typeof value === "string" && value !== "")
+        return value;
+    return typeof value === "number" ? String(value) : undefined;
+}
+/** Record id of a `load` form: the route path id, else the drawer prefill `id`
+ *  (the clicked row), else the URL `id` param. Only the id is read from these
+ *  sources, never another value. */
+export function resolveActionFormRecordId(sources) {
+    return (nonEmptyId(sources.routeEntityId) ??
+        nonEmptyId(sources.drawerOverrides?.[DEFAULT_LOAD_ID_PARAM]) ??
+        nonEmptyId(sources.searchParams[DEFAULT_LOAD_ID_PARAM]));
+}
+/** A sensitive, writeOnly or password field never takes a value from a loaded
+ *  record: the form must not echo a secret back into an input. */
+export function isSecretFormField(field) {
+    return (propertyOf(field, "sensitive") === true ||
+        propertyOf(field, "writeOnly") === true ||
+        propertyOf(field, "format") === "password");
+}
+function pickDeclaredFields(record, fieldNames) {
+    if (typeof record !== "object" || record === null)
+        return {};
+    const picked = {};
+    for (const name of fieldNames) {
+        const value = Object.hasOwn(record, name) ? Reflect.get(record, name) : undefined;
+        if (value !== undefined && value !== null)
+            picked[name] = value;
+    }
+    return picked;
+}
+/** Loads the initial values of an actionForm declaring `load`; undefined for a
+ *  form without `load`. */
+export function useActionFormLoad(load, recordId, fieldNames) {
+    const query = useQuery(load?.query ?? "", { [load?.idParam ?? DEFAULT_LOAD_ID_PARAM]: recordId }, { enabled: load !== undefined && recordId !== undefined });
+    const values = useMemo(() => pickDeclaredFields(query.data, fieldNames), [query.data, fieldNames]);
+    if (load === undefined)
+        return undefined;
+    if (recordId === undefined)
+        return { status: "missing-id" };
+    if (query.error !== null)
+        return { status: "error", error: query.error };
+    if (query.loading)
+        return { status: "loading" };
+    if (query.data === null)
+        return { status: "missing-record" };
+    return { status: "ready", values };
+}
+/** Banner for every `load` state that is not "ready". */
+export function ActionFormLoadStatus({ state, screenId, translate, }) {
+    const { Banner, Text } = usePrimitives();
+    switch (state.status) {
+        case "loading":
+            return _jsx(QueryLoadingBanner, {});
+        case "error":
+            return (_jsx(Banner, { padded: true, variant: "error", testId: "kumiko-screen-error", children: dispatcherErrorText(state.error, translate) }));
+        case "missing-record":
+            return (_jsx(Banner, { padded: true, variant: "error", testId: "kumiko-screen-record-missing", children: translate("kumiko.record.not-found.title") }));
+        case "missing-id":
+            return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-action-form-missing-id", children: ["Screen ", _jsx(Text, { variant: "code", children: screenId }), " (actionForm with load) needs a record id in the path or the clicked row."] }));
+    }
+}
+export function ActionFormSuccessBanner({ success, }) {
+    const { Banner, Link } = usePrimitives();
+    return (_jsxs(Banner, { variant: "info", testId: "action-form-success", children: [success.text, success.links.map((link) => (_jsx(Link, { href: link.href, onPress: link.onPress, className: "ml-2 underline", testId: `action-form-success-link-${link.key}`, children: link.label }, link.key)))] }));
+}

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

@@ -0,0 +1,46 @@
+import type { RowActionClientAction } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+export type ClientActionOutcome = {
+    readonly ok: true;
+}
+/** `message` is an i18n key; a literal is shown as is. */
+ | {
+    readonly ok: false;
+    readonly message: string;
+};
+export type ClientActionHandler = (payload: Readonly<Record<string, unknown>>) => Promise<ClientActionOutcome>;
+export type ClientActionsMap = Readonly<Record<string, ClientActionHandler>>;
+export type ActionNotice = {
+    readonly tone: "success" | "error";
+    readonly text: string;
+};
+/** Shows the outcome of a client action. The platform layer provides it
+ *  (renderer-web: a toast); without one a failure is thrown to the action
+ *  host's own error surface and a success stays silent. */
+export type ActionNotifier = (notice: ActionNotice) => void;
+export type ClientActionRuntime = {
+    readonly handlers: ClientActionsMap | undefined;
+    readonly notify: ActionNotifier | undefined;
+};
+export declare function ClientActionsProvider({ children, value, }: {
+    readonly children: ReactNode;
+    readonly value: ClientActionsMap;
+}): ReactNode;
+export declare function ActionNoticeProvider({ children, notify, }: {
+    readonly children: ReactNode;
+    readonly notify: ActionNotifier;
+}): ReactNode;
+export declare function useClientActionHandler(name: string): ClientActionHandler | undefined;
+/** Handlers plus notifier, as the action builders take them. */
+export declare function useClientActionRuntime(): ClientActionRuntime;
+/** Runs the handler registered for `action.action` and reports the outcome.
+ *  Resolves true when the handler returned `{ ok: true }` (the caller then
+ *  refetches). A failure goes to the notifier; without one it is thrown so the
+ *  host's own error surface (row toast, header banner) shows it. */
+export declare function runClientAction(options: {
+    readonly action: RowActionClientAction;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly runtime: ClientActionRuntime | undefined;
+    readonly translate: Translate;
+}): Promise<boolean>;

package/dist/app/client-actions.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+const ClientActionsContext = createContext(undefined);
+const ActionNoticeContext = createContext(undefined);
+export function ClientActionsProvider({ children, value, }) {
+    return _jsx(ClientActionsContext.Provider, { value: value, children: children });
+}
+export function ActionNoticeProvider({ children, notify, }) {
+    return _jsx(ActionNoticeContext.Provider, { value: notify, children: children });
+}
+export function useClientActionHandler(name) {
+    return findClientActionHandler(useContext(ClientActionsContext), name);
+}
+/** Handlers plus notifier, as the action builders take them. */
+export function useClientActionRuntime() {
+    const handlers = useContext(ClientActionsContext);
+    const notify = useContext(ActionNoticeContext);
+    return useMemo(() => ({ handlers, notify }), [handlers, notify]);
+}
+function findClientActionHandler(handlers, name) {
+    return handlers !== undefined && Object.hasOwn(handlers, name) ? handlers[name] : undefined;
+}
+function logClientActionProblem(name, problem, cause) {
+    // biome-ignore lint/suspicious/noConsole: the client has no logger; the toast text is generic, so the action name and cause must reach the DevTools console
+    console.error(`[kumiko] clientAction "${name}" ${problem}`, ...(cause === undefined ? [] : [cause]));
+}
+/** Runs the handler registered for `action.action` and reports the outcome.
+ *  Resolves true when the handler returned `{ ok: true }` (the caller then
+ *  refetches). A failure goes to the notifier; without one it is thrown so the
+ *  host's own error surface (row toast, header banner) shows it. */
+export async function runClientAction(options) {
+    const { action, payload, runtime, translate } = options;
+    const notify = runtime?.notify;
+    const fail = (text) => {
+        if (notify === undefined)
+            throw new Error(text);
+        notify({ tone: "error", text });
+        return false;
+    };
+    const handler = findClientActionHandler(runtime?.handlers, action.action);
+    if (handler === undefined) {
+        logClientActionProblem(action.action, "is not registered by any client feature");
+        return fail(translate("kumiko.clientAction.unregistered"));
+    }
+    let outcome;
+    try {
+        outcome = await handler(payload);
+    }
+    catch (error) {
+        logClientActionProblem(action.action, "threw", error);
+        return fail(translate("kumiko.clientAction.failed"));
+    }
+    if (!outcome.ok)
+        return fail(translate(outcome.message));
+    notify?.({
+        tone: "success",
+        text: translate(action.successMessage ?? "kumiko.clientAction.success"),
+    });
+    return true;
+}

package/dist/app/entity-list-expanded-row.js

@@ -5,6 +5,7 @@ import { RenderEditActionButton } from "../components/render-edit-action-button.
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
+import { useClientActionRuntime } from "./client-actions.js";
 import { useNav } from "./nav.js";
 import { useReturnHost } from "./return-to.js";
 import { buildRecordActions } from "./row-actions.js";
@@ -18,6 +19,7 @@ export function EntityListExpandedRow({ section, row, featureName, translate, ex
     const nav = useNav();
     const host = useReturnHost();
     const dispatcher = useOptionalDispatcher();
+    const clientActions = useClientActionRuntime();
     const [actionError, setActionError] = useState(null);
     const onTitleActionWritten = useCallback(async () => {
         onSubListInvalidated();
@@ -33,6 +35,7 @@ export function EntityListExpandedRow({ section, row, featureName, translate, ex
             dispatcher,
             openDrawer,
             onWriteSuccess: onTitleActionWritten,
+            clientActions,
         })
         : undefined, [
         section.actions,
@@ -43,6 +46,7 @@ export function EntityListExpandedRow({ section, row, featureName, translate, ex
         dispatcher,
         openDrawer,
         onTitleActionWritten,
+        clientActions,
     ]);
     const titleActionButtons = titleActions?.map((action) => (_jsx(RenderEditActionButton, { action: action, Button: Button, Dialog: Dialog, onError: setActionError }, action.id)));
     return (_jsxs(_Fragment, { children: [actionError !== null && (_jsx(Banner, { variant: "error", testId: `row-${row.id}-expansion-action-error`, children: actionError })), _jsx(RelatedListSection, { embedded: true, section: section, parentId: String(row.values["id"] ?? row.id), record: row.values, featureName: featureName, translate: effectiveTranslate, onOpenDrawer: openDrawer, onAfterWrite: onAfterWrite, ...(titleActionButtons !== undefined && { actions: titleActionButtons }) }, expansionNonce)] }));

package/dist/app/header-actions-bar.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import type { RenderEditAction } from "../components/render-edit-types.ts";
+import type { usePrimitives } from "../primitives.tsx";
+export declare function HeaderActionsBar({ actions, Button, Dialog, ActionOverflowMenu, onError, collapseAfterPrimary, compact, preferredPrimaryId, PageHeader, overflowTestId, }: {
+    /** `primaryAction` of the screen: wins over the edit/primary-style precedence. */
+    readonly preferredPrimaryId?: string;
+    /** Header slot layout: only the primary action stays a button, the rest goes into the menu. */
+    readonly collapseAfterPrimary?: boolean;
+    /** Phone-width shell header: an icon-only primary button, the rest in the shell's overflow menu. */
+    readonly compact?: boolean;
+    readonly PageHeader?: ReturnType<typeof usePrimitives>["PageHeader"];
+    readonly actions: readonly RenderEditAction[];
+    readonly Button: ReturnType<typeof usePrimitives>["Button"];
+    readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+    readonly ActionOverflowMenu: ReturnType<typeof usePrimitives>["ActionOverflowMenu"];
+    readonly onError: (text: string | null) => void;
+    /** Test id of the overflow menu; projectionDetail's by default. */
+    readonly overflowTestId?: string;
+}): ReactNode;

package/dist/app/header-actions-bar.js

@@ -0,0 +1,30 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RenderEditActionButton } from "../components/render-edit-action-button.js";
+import { useActionMenuItems } from "../components/use-action-menu-items.js";
+import { useTranslation } from "../i18n.js";
+import { compactHeaderPrimary, orderPlainHeaderActions, primaryHeaderAction, } from "./header-actions.js";
+// Header actions bar (A7): <=2 actions render as plain buttons; >2 with an
+// `ActionOverflowMenu` primitive collapse to the primary button plus a menu
+// for the rest — same rule as RowActionsCell for table rows. Owns confirm
+// state for menu items: RenderEditActionButton already owns a per-button
+// confirm dialog for the always-visible primary action, but a menu item has
+// no button of its own to carry one.
+export function HeaderActionsBar({ actions, Button, Dialog, ActionOverflowMenu, onError, collapseAfterPrimary = false, compact = false, preferredPrimaryId, PageHeader, overflowTestId = "kumiko-screen-projection-detail-actions-overflow", }) {
+    const t = useTranslation();
+    const { toMenuItem, confirmDialog: pendingActionDialog } = useActionMenuItems({
+        Dialog,
+        onError,
+    });
+    if (compact && PageHeader !== undefined) {
+        const compactPrimary = compactHeaderPrimary(actions, preferredPrimaryId);
+        const overflowActions = actions.filter((a) => a !== compactPrimary?.action);
+        return (_jsxs(_Fragment, { children: [compactPrimary !== undefined && (_jsx(RenderEditActionButton, { action: compactPrimary.action, Button: Button, Dialog: Dialog, iconOnly: compactPrimary.iconOnly, compactLabel: true, onError: onError }, compactPrimary.action.id)), overflowActions.length > 0 && (_jsx(PageHeader, { overflowItems: overflowActions.map(toMenuItem) })), pendingActionDialog] }));
+    }
+    const maxPlainButtons = collapseAfterPrimary ? 1 : 2;
+    if (actions.length <= maxPlainButtons || ActionOverflowMenu === undefined) {
+        return (_jsx(_Fragment, { children: orderPlainHeaderActions(actions, preferredPrimaryId).map((action) => (_jsx(RenderEditActionButton, { action: action, Button: Button, Dialog: Dialog, hideIcon: true, onError: onError }, action.id))) }));
+    }
+    const primary = primaryHeaderAction(actions, preferredPrimaryId);
+    const rest = actions.filter((a) => a.id !== primary?.id);
+    return (_jsxs(_Fragment, { children: [primary !== undefined && (_jsx(RenderEditActionButton, { action: primary, Button: Button, Dialog: Dialog, hideIcon: true, onError: onError }, primary.id)), _jsx(ActionOverflowMenu, { label: t("kumiko.list.row-actions.more"), testId: overflowTestId, items: rest.map(toMenuItem) }), pendingActionDialog] }));
+}