@cosmicdrift/kumiko-renderer-web 0.181.0 → 0.182.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.181.0",
+  "version": "0.182.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.181.0",
-    "@cosmicdrift/kumiko-headless": "0.181.0",
-    "@cosmicdrift/kumiko-renderer": "0.181.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.182.0",
+    "@cosmicdrift/kumiko-headless": "0.182.0",
+    "@cosmicdrift/kumiko-renderer": "0.182.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/__tests__/create-app.test.tsx

@@ -9,10 +9,11 @@ import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
 import type {
   AppSchema,
   ColumnRendererProps,
+  ContentEditorProps,
   FeatureSchema,
   NavApi,
 } from "@cosmicdrift/kumiko-renderer";
-import { createStaticLocaleResolver } from "@cosmicdrift/kumiko-renderer";
+import { createStaticLocaleResolver, useContentEditor } from "@cosmicdrift/kumiko-renderer";
 import { act, screen, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import type { ClientFeatureDefinition } from "../app/client-plugin";
@@ -315,6 +316,48 @@ describe("createKumikoApp", () => {
     expect(screen.getByTestId("ca-swatch-field").textContent).toBe("color");
   });
 
+  test("clientFeatures.contentEditors → createKumikoApp verdrahtet Merge → Provider → useContentEditor end-to-end", async () => {
+    // Proves the whole chain: ClientFeatureDefinition.contentEditors →
+    // mergeContentEditors → ContentEditorsProvider in the tree →
+    // useContentEditor in the consumer. Without the provider mount,
+    // useContentEditor would always fall back to the textarea — this test
+    // would fail then.
+    function RichEditor({ value }: ContentEditorProps): ReactNode {
+      return <div data-testid="ca-rich-editor">{value}</div>;
+    }
+    function EditorProbe(): ReactNode {
+      const Editor = useContentEditor("rich");
+      return <Editor value="hello" onChange={() => {}} variables={[]} readOnly={false} />;
+    }
+    const probeSchema: FeatureSchema = {
+      featureName: "tasks",
+      entities: {},
+      screens: [{ id: "editor-probe", type: "custom", renderer: {} }],
+      navs: [
+        {
+          id: "editor-probe",
+          label: "tasks:nav.editor-probe",
+          screen: "tasks:screen:editor-probe",
+        },
+      ],
+    };
+    const clientFeature: ClientFeatureDefinition = {
+      name: "tasks",
+      components: { "editor-probe": EditorProbe },
+      contentEditors: { rich: RichEditor },
+    };
+
+    mountRoot();
+    await mountApp({
+      schema: probeSchema,
+      dispatcher: makeDispatcher(),
+      clientFeatures: [clientFeature],
+    });
+
+    expect(await screen.findByTestId("ca-rich-editor")).toBeTruthy();
+    expect(screen.getByTestId("ca-rich-editor").textContent).toBe("hello");
+  });
+
   test("schema.translations (r.translations, #1059) resolves nav/dashboard labels without any clientFeatures duplication", async () => {
     // Mirrors cap-counter's real shape: a feature that declares r.translations
     // for its own nav label but ships NO web/i18n.ts / clientFeatures entry at

package/src/app/__tests__/merge-content-editors.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import type { ContentEditorComponent } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "../client-plugin";
+import { mergeContentEditors } from "../create-app";
+
+const editor = (): ContentEditorComponent => (() => null) as ContentEditorComponent;
+
+describe("mergeContentEditors", () => {
+  test("merges contentEditors from multiple clientFeatures", () => {
+    const plainEditor = editor();
+    const richEditor = editor();
+    const features: ClientFeatureDefinition[] = [
+      { name: "a", contentEditors: { plain: plainEditor } },
+      { name: "b", contentEditors: { rich: richEditor } },
+    ];
+
+    const merged = mergeContentEditors(features);
+    expect(merged["plain"]).toBe(plainEditor);
+    expect(merged["rich"]).toBe(richEditor);
+  });
+
+  test("Key-Kollision → warnt + last-wins gewinnt", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const first = editor();
+    const second = editor();
+    const features: ClientFeatureDefinition[] = [
+      { name: "first", contentEditors: { plain: first } },
+      { name: "second", contentEditors: { plain: second } },
+    ];
+
+    const merged = mergeContentEditors(features);
+    expect(merged["plain"]).toBe(second);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('contentEditor "plain" defined by multiple clientFeatures'),
+    );
+
+    warnSpy.mockRestore();
+  });
+
+  test("clientFeatures ohne contentEditors werden übersprungen", () => {
+    const features: ClientFeatureDefinition[] = [{ name: "a" }];
+    expect(mergeContentEditors(features)).toEqual({});
+  });
+});

package/src/app/__tests__/plain-content-editor.test.tsx

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { type ReactNode, useState } from "react";
+import { fireEvent, render, screen } from "../../__tests__/test-utils";
+import { PlainContentEditor } from "../plain-content-editor";
+
+function Controlled({ initial }: { readonly initial: string }): ReactNode {
+  const [value, setValue] = useState(initial);
+  return (
+    <PlainContentEditor value={value} onChange={setValue} variables={["name"]} readOnly={false} />
+  );
+}
+
+describe("PlainContentEditor", () => {
+  test("renders the textarea plus one chip per variable", () => {
+    render(
+      <PlainContentEditor value="" onChange={() => {}} variables={["name"]} readOnly={false} />,
+    );
+    expect(screen.getByRole("textbox")).toBeTruthy();
+    expect(screen.getByText("{{name}}")).toBeTruthy();
+  });
+
+  test("no variables → no chips", () => {
+    render(<PlainContentEditor value="" onChange={() => {}} variables={[]} readOnly={false} />);
+    expect(screen.queryAllByRole("button")).toHaveLength(0);
+  });
+
+  test("chip click inserts the placeholder at the caret, not appended", () => {
+    render(<Controlled initial="Hello  world" />);
+    const textarea = screen.getByRole("textbox") as HTMLTextAreaElement;
+    // Caret between the two spaces (index 6), so the insert must land there —
+    // an append-only implementation would put it at the string's end instead.
+    textarea.setSelectionRange(6, 6);
+    fireEvent.click(screen.getByText("{{name}}"));
+    expect(textarea.value).toBe("Hello {{name}} world");
+  });
+
+  test("chip click replaces a selection instead of inserting alongside it", () => {
+    render(<Controlled initial="Hello world" />);
+    const textarea = screen.getByRole("textbox") as HTMLTextAreaElement;
+    textarea.setSelectionRange(6, 11); // selects "world"
+    fireEvent.click(screen.getByText("{{name}}"));
+    expect(textarea.value).toBe("Hello {{name}}");
+  });
+});

package/src/app/client-plugin.tsx

@@ -12,6 +12,7 @@
 import type { TargetRef, TreeChildrenSubscribe } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   ColumnRendererComponent,
+  ContentEditorComponent,
   ExtensionSectionComponent,
   QualifiedContentCollection,
   TranslationsByLocale,
@@ -89,6 +90,15 @@ export type ClientFeatureDefinition = {
     collections: readonly QualifiedContentCollection[],
   ) => CollectionNavProviders;
 
+  /** Content-Editor-Components — Map `contentFormat` ("plain" | "rich" | "markdown") →
+   *  React-Component. `r.contentCollection()` declares which format an
+   *  editor edits; the collection's editor UI (template-resolver's
+   *  TextBlockEditor et al.) looks the component up here and falls back to
+   *  a plain textarea when no clientFeature registered one for that
+   *  format. Same Last-Wins-Semantik wie columnRenderers. Public component
+   *  contract: `{ value, onChange, variables, readOnly }`. */
+  readonly contentEditors?: Readonly<Record<string, ContentEditorComponent>>;
+
   /** Editor-Resolver-Komponenten pro featureId:action-Key. Wenn ein
    *  TreeNode mit target angeklickt wird, schlägt der EditorPanel das
    *  Component hier nach und rendert es. Komponenten erhalten target

package/src/app/create-app.tsx

@@ -11,6 +11,8 @@ import {
   type AppSchema,
   type ColumnRendererComponent,
   ColumnRenderersProvider,
+  type ContentEditorComponent,
+  ContentEditorsProvider,
   CustomScreensProvider,
   DashboardBodyProvider,
   DispatcherProvider,
@@ -216,6 +218,28 @@ export function firstOpenScreenQn(features: readonly FeatureSchema[]): string |
   return undefined;
 }
 
+// Merges the content-editor map — same last-wins semantics as
+// columnRenderers. No entry for a contentFormat → useContentEditor falls
+// back to the textarea on its own, no warning needed.
+export function mergeContentEditors(
+  clientFeatures: readonly ClientFeatureDefinition[],
+): Record<string, ContentEditorComponent> {
+  const contentEditors: Record<string, ContentEditorComponent> = {};
+  for (const f of clientFeatures) {
+    if (f.contentEditors === undefined) continue;
+    for (const [key, value] of Object.entries(f.contentEditors)) {
+      if (contentEditors[key] !== undefined) {
+        // biome-ignore lint/suspicious/noConsole: dev-warning für Schema-Konflikte
+        console.warn(
+          `[kumiko] contentEditor "${key}" defined by multiple clientFeatures — last definition (from "${f.name}") wins.`,
+        );
+      }
+      contentEditors[key] = value;
+    }
+  }
+  return contentEditors;
+}
+
 export function createKumikoApp(options: CreateKumikoAppOptions = {}): { readonly root: Root } {
   const rootId = options.rootId ?? "root";
   const container = document.getElementById(rootId);
@@ -320,6 +344,8 @@ export function createKumikoApp(options: CreateKumikoAppOptions = {}): { readonl
     }
   }
 
+  const contentEditors = mergeContentEditors(clientFeatures);
+
   const { navProviders, navEntities } = buildNavProviderMaps(
     clientFeatures,
     app.features.flatMap((f) => f.contentCollections ?? []),
@@ -367,16 +393,18 @@ export function createKumikoApp(options: CreateKumikoAppOptions = {}): { readonl
                 <DashboardBodyProvider value={WebDashboardBody}>
                   <CustomScreensProvider value={customScreens}>
                     <ColumnRenderersProvider value={columnRenderers}>
-                      <ExtensionSectionsProvider value={extensionSectionComponents}>
-                        <NavProvidersProvider value={navProviders} entities={navEntities}>
-                          <ResolversProvider resolvers={resolvers}>
-                            <ToastProvider>
-                              <UpdateChecker />
-                              {stackWrappers(providers, stackWrappers(gates, screenNode))}
-                            </ToastProvider>
-                          </ResolversProvider>
-                        </NavProvidersProvider>
-                      </ExtensionSectionsProvider>
+                      <ContentEditorsProvider value={contentEditors}>
+                        <ExtensionSectionsProvider value={extensionSectionComponents}>
+                          <NavProvidersProvider value={navProviders} entities={navEntities}>
+                            <ResolversProvider resolvers={resolvers}>
+                              <ToastProvider>
+                                <UpdateChecker />
+                                {stackWrappers(providers, stackWrappers(gates, screenNode))}
+                              </ToastProvider>
+                            </ResolversProvider>
+                          </NavProvidersProvider>
+                        </ExtensionSectionsProvider>
+                      </ContentEditorsProvider>
                     </ColumnRenderersProvider>
                   </CustomScreensProvider>
                 </DashboardBodyProvider>

package/src/app/plain-content-editor.tsx

@@ -0,0 +1,66 @@
+// @runtime client
+//
+// "plain" contentFormat editor: the primitives textarea (TextareaContentEditor,
+// unchanged — keeps its styling and its Field/label association) plus a
+// variable-chip bar underneath. A chip click inserts `{{name}}` at the caret
+// instead of appending to the end.
+//
+// ponytail: looks the textarea up by CONTENT_EDITOR_ELEMENT_ID rather than a
+// ref threaded through the primitives Input contract — that contract is
+// cross-platform (RN has no DOM node), this file is `@runtime client`-only
+// and CONTENT_EDITOR_ELEMENT_ID exists exactly as this DOM hook. Upgrade to a
+// forwarded ref if a screen ever needs two plain editors mounted at once.
+
+import {
+  CONTENT_EDITOR_ELEMENT_ID,
+  type ContentEditorProps,
+  TextareaContentEditor,
+  VariableChips,
+} from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { useEffect, useState } from "react";
+
+export function PlainContentEditor({
+  value,
+  onChange,
+  variables,
+  readOnly,
+}: ContentEditorProps): ReactNode {
+  const [caret, setCaret] = useState<number | null>(null);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on value only — must fire once per committed insert, not on every caret write
+  useEffect(() => {
+    if (caret === null) return;
+    const el = document.getElementById(CONTENT_EDITOR_ELEMENT_ID);
+    if (el instanceof HTMLTextAreaElement) {
+      el.focus();
+      el.setSelectionRange(caret, caret);
+    }
+    setCaret(null);
+  }, [value]);
+
+  const insertAtCaret = (name: string): void => {
+    const el = document.getElementById(CONTENT_EDITOR_ELEMENT_ID);
+    const placeholder = `{{${name}}}`;
+    if (!(el instanceof HTMLTextAreaElement)) {
+      onChange(value + placeholder);
+      return;
+    }
+    const start = el.selectionStart ?? value.length;
+    const end = el.selectionEnd ?? value.length;
+    setCaret(start + placeholder.length);
+    onChange(value.slice(0, start) + placeholder + value.slice(end));
+  };
+
+  return (
+    <div>
+      <TextareaContentEditor
+        value={value}
+        onChange={onChange}
+        variables={variables}
+        readOnly={readOnly}
+      />
+      <VariableChips variables={variables} onInsert={insertAtCaret} disabled={readOnly} />
+    </div>
+  );
+}

package/src/index.ts

@@ -95,6 +95,7 @@ export type { CreatePublicSurfaceOptions, PublicRoute } from "./app/create-publi
 export { createPublicSurface } from "./app/create-public-surface";
 export type { KumikoLinkProps } from "./app/nav";
 export { KumikoLink, useBrowserNavApi } from "./app/nav";
+export { PlainContentEditor } from "./app/plain-content-editor";
 export { useResolvers } from "./app/resolvers-context";
 export type { AppLayoutProps } from "./layout/app-layout";
 export { AppLayout } from "./layout/app-layout";