@cosmicdrift/kumiko-renderer 0.341.0 → 0.343.0

package/dist/app/kumiko-screen.js

@@ -42,6 +42,8 @@ import { buildDefaultEditRowAction, buildDrawerRowAction, buildProjectionRowActi
 import { findEditScreenFor, navigateTargetAllows, screenAccessAllows } from "./screen-access.js";
 import { SecretMintBody } from "./secret-mint-body.js";
 import { SecretsEditBody } from "./secrets-edit-body.js";
+import { useEmbeddedScreen } from "./use-embedded-screen.js";
+import { evalVisibleWhen } from "./visible-when.js";
 import { dispatcherErrorText, WriteFailedError } from "./write-failed-error.js";
 export { qualifyScreenId };
 /** Mirrors qualifyScreenId for nav QNs (registry form `<feature>:nav:<short-id>`).
@@ -66,7 +68,16 @@ export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCo
     if (!screenAccessAllows(screen.access, userRoles)) {
         return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-access-denied", children: ["Access denied: ", _jsx(Text, { variant: "code", children: qn })] }));
     }
-    const body = renderScreenBody({ schema, screen, translate, entityId, onRowClick, onCopyLink });
+    const screenBody = renderScreenBody({
+        schema,
+        screen,
+        translate,
+        entityId,
+        onRowClick,
+        onCopyLink,
+    });
+    // Gate every entry (incl. direct URL): the body element is only mounted once the condition holds.
+    const body = screen.visibleWhen !== undefined ? (_jsx(ScreenVisibilityGate, { featureName: schema.featureName, visibleWhen: screen.visibleWhen, fallback: screen.fallback, translate: translate, children: screenBody })) : (screenBody);
     // An embedded screen (e.g. a dashboard panel) keeps its parent's host and
     // must not portal its page header into the shell that hosts the outer screen.
     if (outerHost !== undefined) {
@@ -74,6 +85,29 @@ export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCo
     }
     return _jsx(ReturnHostProvider, { value: ownHost, children: body });
 }
+function ScreenVisibilityGate({ featureName, visibleWhen, fallback, translate, children, }) {
+    const { Banner } = usePrimitives();
+    const t = useTranslation();
+    const result = useQuery(visibleWhen.query, {}, { live: true });
+    const verdict = evalVisibleWhen(visibleWhen, result);
+    if (verdict === "visible")
+        return children;
+    if (verdict === "loading") {
+        return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
+    }
+    if (fallback !== undefined) {
+        return _jsx(FallbackScreen, { featureName: featureName, fallback: fallback, translate: translate });
+    }
+    return (_jsx(Banner, { padded: true, variant: "info", testId: "kumiko-screen-unavailable", children: t("kumiko.screen.unavailable") }));
+}
+function FallbackScreen({ featureName, fallback, translate, }) {
+    const target = useEmbeddedScreen(featureName, fallback);
+    const { Banner, Text } = usePrimitives();
+    if (target === undefined) {
+        return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-not-found", children: ["Screen not found: ", _jsx(Text, { variant: "code", children: fallback })] }));
+    }
+    return _jsx(KumikoScreen, { schema: target.schema, qn: target.qn, translate: translate });
+}
 function renderScreenBody({ schema, screen, translate, entityId, onRowClick, onCopyLink, }) {
     switch (screen.type) {
         case "entityEdit":

package/dist/app/visible-when.d.ts

@@ -0,0 +1,4 @@
+import type { DashboardPanelVisibility } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { UseQueryResult } from "../hooks/use-query.js";
+export type VisibleWhenVerdict = "loading" | "visible" | "hidden" | "error";
+export declare function evalVisibleWhen(visibleWhen: DashboardPanelVisibility, result: UseQueryResult<Readonly<Record<string, unknown>>> | undefined): VisibleWhenVerdict;

package/dist/app/visible-when.js

@@ -0,0 +1,11 @@
+// Shared by dashboard screen panels and screen-level visibleWhen. Anything but a
+// positive match is non-visible (fail-closed); `error` is split out so panels can offer a retry.
+export function evalVisibleWhen(visibleWhen, result) {
+    if (result?.error)
+        return "error";
+    if (result === undefined)
+        return "hidden";
+    if (result.data === null)
+        return result.loading ? "loading" : "hidden";
+    return result.data[visibleWhen.field] === visibleWhen.eq ? "visible" : "hidden";
+}

package/dist/i18n-defaults.js

@@ -106,6 +106,7 @@ export const kumikoDefaultTranslations = {
         "kumiko.dashboard.panel.error.retry": "Try again",
         "kumiko.dashboard.panel.error.title": "{label} could not be loaded",
         "kumiko.dashboard.time-range": "Time range",
+        "kumiko.screen.unavailable": "This page is not available right now.",
         "kumiko.dashboard.today": "Today",
         "kumiko.dashboard.updated-at": "As of {time}",
         "kumiko.app-boot.loading": "Loading…",

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export type { EmbeddedScreenTarget } from "./app/use-embedded-screen.js";
 export { useEmbeddedScreen } from "./app/use-embedded-screen.js";
 export type { VariableChipsProps } from "./app/variable-chips.js";
 export { VariableChips } from "./app/variable-chips.js";
+export { evalVisibleWhen, type VisibleWhenVerdict } from "./app/visible-when.js";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error.js";
 export { RelatedListSection } from "./components/related-list-section.js";
 export type { RenderEditAction, RenderEditChangeState, RenderEditControls, RenderEditProps, } from "./components/render-edit.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export { lastSegment } from "./app/qn.js";
 export { navigateToReturn, navigateToReturnOr, navigateWithReturnTo, RETURN_TO_PARAM, ReturnHostProvider, resolveReturnTarget, splitReturnTo, useReturnHost, useReturnTarget, } from "./app/return-to.js";
 export { useEmbeddedScreen } from "./app/use-embedded-screen.js";
 export { VariableChips } from "./app/variable-chips.js";
+export { evalVisibleWhen } from "./app/visible-when.js";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error.js";
 export { RelatedListSection } from "./components/related-list-section.js";
 export { RenderEdit } from "./components/render-edit.js";

package/dist/primitives.d.ts

@@ -107,8 +107,12 @@ export type BannerProps = {
     /** "error" for alerts (conflict, network error), "info" for neutral
      *  placeholders (not-found, loading), "loading" for load states, "warning"
      *  for a non-blocking but attention-grabbing notice (e.g. secretMint's
-     *  "this is shown only once"). */
-    readonly variant?: "error" | "info" | "loading" | "warning";
+     *  "this is shown only once"), "primary" for a call-to-action notice (neutral
+     *  background, accent in the primary color; pair it with `title` and `actions`). */
+    readonly variant?: "error" | "info" | "loading" | "warning" | "primary";
+    /** Bold heading above `children`, inside the text column. */
+    readonly title?: ReactNode;
+    readonly titleTestId?: string;
     readonly children: ReactNode;
     /** Optional — weitere Knöpfe/Elemente rechts vom Text (z.B. "Neu
      *  laden"). Inline, nicht als eigener Block. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.341.0",
+  "version": "0.343.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.341.0",
-    "@cosmicdrift/kumiko-headless": "0.341.0",
-    "@cosmicdrift/kumiko-types": "0.341.0",
+    "@cosmicdrift/kumiko-framework": "0.343.0",
+    "@cosmicdrift/kumiko-headless": "0.343.0",
+    "@cosmicdrift/kumiko-types": "0.343.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.341.0"
+    "@cosmicdrift/kumiko-locale-de": "0.343.0"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "Screens take visibleWhen and fallback",
+    "detail": "Any screen can gate itself on a query field with `visibleWhen`, including on direct URL access. Unmet or failed conditions render the `fallback` screen or a standard notice instead of the content. New i18n key: `kumiko.screen.unavailable`."
+  },
+  {
+    "version": "0.342.0",
+    "type": "improvement",
+    "title": "Banner gets title, titleTestId and variant \"primary\"",
+    "detail": "Banner takes title, titleTestId and variant \"primary\"\n`BannerProps` gets `title` (bold heading above the text), `titleTestId` and the variant `\"primary\"` for call-to-action notices: left accent in the primary color, neutral background, `actions` right of the text on wide screens and below it on narrow ones. Existing variants render unchanged."
+  },
   {
     "version": "0.341.0",
     "type": "fix",