@cosmicdrift/kumiko-renderer-web 0.176.2 → 0.178.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.176.2",
+  "version": "0.178.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.176.2",
-    "@cosmicdrift/kumiko-headless": "0.176.2",
-    "@cosmicdrift/kumiko-renderer": "0.176.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.178.0",
+    "@cosmicdrift/kumiko-headless": "0.178.0",
+    "@cosmicdrift/kumiko-renderer": "0.178.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/app/__tests__/build-nav-provider-maps.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { TreeChildrenSubscribe } from "@cosmicdrift/kumiko-framework/engine";
+import type { QualifiedContentCollection } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "../client-plugin";
+import { buildNavProviderMaps } from "../create-app";
+
+// Two ways a nav node gets its children: the app wires a navProvider by hand,
+// or a feature derives one per r.contentCollection() from the schema. This
+// pins how they compose — the derived one is the weaker claim.
+
+const provider = (): TreeChildrenSubscribe => () => () => () => {};
+
+function collection(id: string, kind: string): QualifiedContentCollection {
+  return { id, kind, nav: { label: `mail:nav.${id}` }, navQn: `mail:nav:${id}` };
+}
+
+describe("buildNavProviderMaps", () => {
+  test("qualifiziert lokale nav-ids, lässt fertige QNs durch", () => {
+    const feature: ClientFeatureDefinition = {
+      name: "cms",
+      navProviders: { content: provider(), "app:nav:legal": provider() },
+      navEntities: { content: ["text-block"] },
+    };
+
+    const { navProviders, navEntities } = buildNavProviderMaps([feature], []);
+    expect([...navProviders.keys()].sort()).toEqual(["app:nav:legal", "cms:nav:content"]);
+    expect(navEntities.get("cms:nav:content")).toEqual(["text-block"]);
+  });
+
+  test("Collections werden unter ihrer Schema-QN registriert, mit SSE-Entities", () => {
+    const feature: ClientFeatureDefinition = {
+      name: "template-resolver",
+      navProvidersFromCollections: (collections) => ({
+        providers: Object.fromEntries(collections.map((c) => [c.navQn, provider()])),
+        entities: Object.fromEntries(collections.map((c) => [c.navQn, ["template-resource"]])),
+      }),
+    };
+
+    const { navProviders, navEntities } = buildNavProviderMaps(
+      [feature],
+      [collection("templates", "mail-html"), collection("prompts", "ai-prompt")],
+    );
+    expect([...navProviders.keys()].sort()).toEqual(["mail:nav:prompts", "mail:nav:templates"]);
+    expect(navEntities.get("mail:nav:prompts")).toEqual(["template-resource"]);
+  });
+
+  test("ein expliziter navProvider gewinnt gegen den abgeleiteten — ohne Konflikt-Warnung", () => {
+    const explicitProvider = provider();
+    const derivedFeature: ClientFeatureDefinition = {
+      name: "template-resolver",
+      navProvidersFromCollections: () => ({
+        providers: { "mail:nav:templates": provider() },
+      }),
+    };
+    const appFeature: ClientFeatureDefinition = {
+      name: "app",
+      navProviders: { "mail:nav:templates": explicitProvider },
+    };
+
+    const warn = console.warn;
+    const warnings: unknown[] = [];
+    console.warn = mock((...args: unknown[]) => warnings.push(args));
+    try {
+      const { navProviders } = buildNavProviderMaps(
+        [derivedFeature, appFeature],
+        [collection("templates", "mail-html")],
+      );
+      expect(navProviders.get("mail:nav:templates")).toBe(explicitProvider);
+      // Overriding a derived provider is the documented escape hatch, not a
+      // conflict — warning here would train people to ignore the warning.
+      expect(warnings).toHaveLength(0);
+    } finally {
+      console.warn = warn;
+    }
+  });
+
+  test("zwei explizite Provider auf derselben QN warnen weiterhin", () => {
+    const features: ClientFeatureDefinition[] = [
+      { name: "a", navProviders: { "x:nav:content": provider() } },
+      { name: "b", navProviders: { "x:nav:content": provider() } },
+    ];
+
+    const warn = console.warn;
+    const warnings: unknown[] = [];
+    console.warn = mock((...args: unknown[]) => warnings.push(args));
+    try {
+      buildNavProviderMaps(features, []);
+      expect(warnings).toHaveLength(1);
+    } finally {
+      console.warn = warn;
+    }
+  });
+
+  test("Feature ohne Collections-Factory bleibt unberührt von deklarierten Collections", () => {
+    const feature: ClientFeatureDefinition = { name: "cms", navProviders: { content: provider() } };
+    const { navProviders } = buildNavProviderMaps(
+      [feature],
+      [collection("templates", "mail-html")],
+    );
+    expect([...navProviders.keys()]).toEqual(["cms:nav:content"]);
+  });
+});

package/src/app/client-plugin.tsx

@@ -13,10 +13,20 @@ import type { TargetRef, TreeChildrenSubscribe } from "@cosmicdrift/kumiko-frame
 import type {
   ColumnRendererComponent,
   ExtensionSectionComponent,
+  QualifiedContentCollection,
   TranslationsByLocale,
 } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 
+/** What a `navProvidersFromCollections` factory returns: the providers plus
+ *  the entities whose live events should re-fire them. Without `entities` a
+ *  derived tree would sit stale until re-mount — the hand-wired path has the
+ *  SSE refresh and the derived one must not lose it. */
+export type CollectionNavProviders = {
+  readonly providers: Readonly<Record<string, TreeChildrenSubscribe>>;
+  readonly entities?: Readonly<Record<string, readonly string[]>>;
+};
+
 export type ClientFeatureDefinition = {
   readonly name: string;
   /** Context-Provider die um den kompletten Renderer-Tree gewrapped
@@ -68,6 +78,16 @@ export type ClientFeatureDefinition = {
    *  (analog `treeEntities`). Live-Event für eine Entity → Provider des
    *  Knotens wird neu aufgerufen → neue Kinder erscheinen live. */
   readonly navEntities?: Readonly<Record<string, readonly string[]>>;
+  /** Nav providers derived from the app schema — called with every
+   *  `r.contentCollection()` the app declares. A feature that serves any
+   *  number of collections (template-resolver) builds one provider per
+   *  collection this way, without the app writing navId + kind a second time
+   *  and without the renderer having to know bundled-features. Merged with
+   *  `navProviders`; the static map wins on key collision (explicit beats
+   *  derived). */
+  readonly navProvidersFromCollections?: (
+    collections: readonly QualifiedContentCollection[],
+  ) => CollectionNavProviders;
 
   /** Editor-Resolver-Komponenten pro featureId:action-Key. Wenn ein
    *  TreeNode mit target angeklickt wird, schlägt der EditorPanel das

package/src/app/create-app.tsx

@@ -26,6 +26,7 @@ import {
   NavProvider,
   PrimitivesProvider,
   type PrimitivesRegistry,
+  type QualifiedContentCollection,
   qualifyScreenId,
   TokensProvider,
   type TranslationsByLocale,
@@ -58,6 +59,55 @@ export function qualifyNavProviderKey(feature: string, id: string): string {
   return id.includes(":nav:") ? id : `${feature}:nav:${id}`;
 }
 
+// Nav-Provider-Map: ein navProvider hängt dynamische Children an einen
+// konkreten r.nav({provider:true})-Knoten (per QN). Lokale nav-ids werden wie
+// in r.nav mit dem Feature-Namen qualifiziert; bereits qualifizierte QNs
+// (cross-feature, z.B. App registriert Nav für ein bundled-feature) gehen
+// unverändert durch.
+//
+// Schema-derived providers (r.contentCollection) run first and hold the weaker
+// claim on a QN — an explicitly registered navProvider overrides them without
+// comment. Only two EXPLICIT registrations on the same QN are the conflict
+// that deserves the warning.
+export function buildNavProviderMaps(
+  clientFeatures: readonly ClientFeatureDefinition[],
+  collections: readonly QualifiedContentCollection[],
+): {
+  readonly navProviders: ReadonlyMap<string, TreeChildrenSubscribe>;
+  readonly navEntities: ReadonlyMap<string, readonly string[]>;
+} {
+  const navProviders = new Map<string, TreeChildrenSubscribe>();
+  const navEntities = new Map<string, readonly string[]>();
+  const derivedQns = new Set<string>();
+  for (const f of clientFeatures) {
+    if (f.navProvidersFromCollections === undefined) continue;
+    const derived = f.navProvidersFromCollections(collections);
+    for (const [qn, provider] of Object.entries(derived.providers)) {
+      navProviders.set(qn, provider);
+      derivedQns.add(qn);
+    }
+    for (const [qn, entities] of Object.entries(derived.entities ?? {})) {
+      if (entities.length > 0) navEntities.set(qn, entities);
+    }
+  }
+  for (const f of clientFeatures) {
+    for (const [navId, provider] of Object.entries(f.navProviders ?? {})) {
+      const qn = qualifyNavProviderKey(f.name, navId);
+      if (navProviders.has(qn) && !derivedQns.delete(qn)) {
+        // biome-ignore lint/suspicious/noConsole: dev-warning für Schema-Konflikte
+        console.warn(
+          `[kumiko] navProvider for "${qn}" defined by multiple clientFeatures — last wins.`,
+        );
+      }
+      navProviders.set(qn, provider);
+    }
+    for (const [navId, entities] of Object.entries(f.navEntities ?? {})) {
+      if (entities.length > 0) navEntities.set(qualifyNavProviderKey(f.name, navId), entities);
+    }
+  }
+  return { navProviders, navEntities };
+}
+
 // Web-Bootstrap. Mounted den ganzen Kumiko-Render-Stack im Browser:
 // Tokens (class-based light/dark via <html>), Primitives (HTML),
 // Navigation (window.history), LiveEvents (EventSource), Dispatcher
@@ -270,28 +320,10 @@ export function createKumikoApp(options: CreateKumikoAppOptions = {}): { readonl
     }
   }
 
-  // Nav-Provider-Map: ein navProvider hängt dynamische Children an einen
-  // konkreten r.nav({provider:true})-Knoten (per QN). Lokale nav-ids werden
-  // wie in r.nav mit dem Feature-Namen qualifiziert; bereits qualifizierte
-  // QNs (cross-feature, z.B. App registriert Nav für ein bundled-feature)
-  // gehen unverändert durch.
-  const navProviders = new Map<string, TreeChildrenSubscribe>();
-  const navEntities = new Map<string, readonly string[]>();
-  for (const f of clientFeatures) {
-    for (const [navId, provider] of Object.entries(f.navProviders ?? {})) {
-      const qn = qualifyNavProviderKey(f.name, navId);
-      if (navProviders.has(qn)) {
-        // biome-ignore lint/suspicious/noConsole: dev-warning für Schema-Konflikte
-        console.warn(
-          `[kumiko] navProvider for "${qn}" defined by multiple clientFeatures — last wins.`,
-        );
-      }
-      navProviders.set(qn, provider);
-    }
-    for (const [navId, entities] of Object.entries(f.navEntities ?? {})) {
-      if (entities.length > 0) navEntities.set(qualifyNavProviderKey(f.name, navId), entities);
-    }
-  }
+  const { navProviders, navEntities } = buildNavProviderMaps(
+    clientFeatures,
+    app.features.flatMap((f) => f.contentCollections ?? []),
+  );
 
   // Editor-Resolver aggregieren — keyed by "featureId:action". Gleiche
   // Last-Wins-Semantik wie columnRenderers. Warnung bei Kollision.