@cosmicdrift/kumiko-renderer 0.181.0 → 0.182.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.181.0",
+  "version": "0.182.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,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.181.0",
-    "@cosmicdrift/kumiko-headless": "0.181.0",
+    "@cosmicdrift/kumiko-framework": "0.182.0",
+    "@cosmicdrift/kumiko-headless": "0.182.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2"
   },

package/src/app/__tests__/content-editors.test.tsx

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { type CorePrimitives, type InputProps, PrimitivesProvider } from "../../primitives";
+import {
+  CONTENT_EDITOR_ELEMENT_ID,
+  type ContentEditorProps,
+  ContentEditorsProvider,
+  TextareaContentEditor,
+  useContentEditor,
+} from "../content-editors";
+
+const captureInput: ComponentType<InputProps> = (props) => {
+  if (props.kind !== "textarea") return null;
+  return (
+    <textarea
+      data-testid="ca-textarea"
+      id={props.id}
+      value={props.value}
+      disabled={props.disabled}
+      readOnly
+    />
+  );
+};
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: captureInput,
+  DataTable: noop,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function RichEditor({ value }: ContentEditorProps): ReactNode {
+  return <div data-testid="ca-rich">{value}</div>;
+}
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return <PrimitivesProvider value={testPrimitives}>{children}</PrimitivesProvider>;
+}
+
+function Probe({ contentFormat }: { readonly contentFormat?: string }): ReactNode {
+  const Editor = useContentEditor(contentFormat);
+  return <Editor value="hello" onChange={() => {}} variables={[]} readOnly={false} />;
+}
+
+describe("useContentEditor", () => {
+  test("no editor registered for the format → falls back to the textarea", () => {
+    render(<Probe contentFormat="plain" />, { wrapper: Wrapper });
+    expect(screen.getByTestId("ca-textarea")).toBeTruthy();
+    expect(screen.getByTestId("ca-textarea").id).toBe(CONTENT_EDITOR_ELEMENT_ID);
+  });
+
+  test("undefined contentFormat behaves like plain", () => {
+    render(<Probe />, { wrapper: Wrapper });
+    expect(screen.getByTestId("ca-textarea")).toBeTruthy();
+  });
+
+  test("an app-registered editor for the format wins over the textarea fallback", () => {
+    render(
+      <ContentEditorsProvider value={{ rich: RichEditor }}>
+        <Probe contentFormat="rich" />
+      </ContentEditorsProvider>,
+      { wrapper: Wrapper },
+    );
+    expect(screen.getByTestId("ca-rich").textContent).toBe("hello");
+    expect(screen.queryByTestId("ca-textarea")).toBeNull();
+  });
+
+  test("a registered editor only applies to its own format — other formats stay on the fallback", () => {
+    render(
+      <ContentEditorsProvider value={{ rich: RichEditor }}>
+        <Probe contentFormat="plain" />
+      </ContentEditorsProvider>,
+      { wrapper: Wrapper },
+    );
+    expect(screen.getByTestId("ca-textarea")).toBeTruthy();
+    expect(screen.queryByTestId("ca-rich")).toBeNull();
+  });
+});
+
+describe("TextareaContentEditor", () => {
+  test("passes value + disabled=readOnly through to the primitives Input", () => {
+    render(
+      <TextareaContentEditor value="draft" onChange={() => {}} variables={[]} readOnly={true} />,
+      { wrapper: Wrapper },
+    );
+    const el = screen.getByTestId("ca-textarea") as HTMLTextAreaElement;
+    expect(el.value).toBe("draft");
+    expect(el.disabled).toBe(true);
+  });
+});

package/src/app/__tests__/variable-chips.test.tsx

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { fireEvent, render, screen } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { type ButtonProps, type CorePrimitives, PrimitivesProvider } from "../../primitives";
+import { VariableChips } from "../variable-chips";
+
+const captureButton: ComponentType<ButtonProps> = ({ children, onClick, ariaLabel, disabled }) => (
+  <button type="button" aria-label={ariaLabel} onClick={() => void onClick?.()} disabled={disabled}>
+    {children}
+  </button>
+);
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: captureButton,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale: "en" })}>
+      <PrimitivesProvider value={testPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("VariableChips", () => {
+  test("renders no chips when there are no variables", () => {
+    render(<VariableChips variables={[]} onInsert={() => {}} />, { wrapper: Wrapper });
+    expect(screen.queryAllByRole("button")).toHaveLength(0);
+  });
+
+  test("renders one chip per variable and reports a click by name", () => {
+    const inserted: string[] = [];
+    render(
+      <VariableChips
+        variables={["customerName", "orderId"]}
+        onInsert={(name) => inserted.push(name)}
+      />,
+      { wrapper: Wrapper },
+    );
+    expect(screen.getAllByRole("button")).toHaveLength(2);
+    fireEvent.click(screen.getByText("{{orderId}}"));
+    expect(inserted).toEqual(["orderId"]);
+  });
+
+  test("disabled propagates to every chip", () => {
+    render(<VariableChips variables={["a"]} onInsert={() => {}} disabled />, { wrapper: Wrapper });
+    expect((screen.getByRole("button") as HTMLButtonElement).disabled).toBe(true);
+  });
+});

package/src/app/content-editors.tsx

@@ -0,0 +1,77 @@
+// Content-Editor-Components-Map: client-side lookup by `contentFormat`
+// ("plain" | "rich" | "markdown") for r.contentCollection() entries. A collection
+// declares its contentFormat in the schema; the client resolves it to a
+// React component here. Same registry shape as columnRenderers/
+// extensionSectionComponents — String-key in the schema, Component in the
+// client bundle, last-wins merge in createKumikoApp.
+//
+// No entry registered for a format → TextareaContentEditor, so a missing
+// editor is never an empty panel.
+
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+import { usePrimitives } from "../primitives";
+
+export type ContentEditorProps = {
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  /** Variable names insertable as chips (from the collection's
+   *  variableSchema). Empty until the variable-chip step wires it up —
+   *  editors must accept it now, that's the point of fixing the signature
+   *  here. */
+  readonly variables: readonly string[];
+  readonly readOnly: boolean;
+};
+
+export type ContentEditorComponent = ComponentType<ContentEditorProps>;
+
+/** Fixed DOM id the fallback textarea renders under. Callers that wrap an
+ *  editor in a `Field` (label + htmlFor) use this as the Field's `id` so the
+ *  label stays associated — the editor contract has no `id` prop of its own,
+ *  every registered editor owns its own focusable element's id. */
+export const CONTENT_EDITOR_ELEMENT_ID = "content-editor-textarea";
+
+export type ContentEditorsMap = Readonly<Record<string, ContentEditorComponent>>;
+
+const ContentEditorsContext = createContext<ContentEditorsMap>({});
+
+export type ContentEditorsProviderProps = {
+  readonly children: ReactNode;
+  readonly value: ContentEditorsMap;
+};
+
+export function ContentEditorsProvider({
+  children,
+  value,
+}: ContentEditorsProviderProps): ReactNode {
+  return <ContentEditorsContext.Provider value={value}>{children}</ContentEditorsContext.Provider>;
+}
+
+/** Plain-textarea fallback for a contentFormat with no registered editor.
+ *  Uses the primitives Input like every other form field, so it renders on
+ *  every platform without requiring the platform's DOM/native equivalent. */
+export function TextareaContentEditor({
+  value,
+  onChange,
+  readOnly,
+}: ContentEditorProps): ReactNode {
+  const { Input } = usePrimitives();
+  return (
+    <Input
+      kind="textarea"
+      id={CONTENT_EDITOR_ELEMENT_ID}
+      name={CONTENT_EDITOR_ELEMENT_ID}
+      value={value}
+      onChange={onChange}
+      disabled={readOnly}
+      rows={14}
+    />
+  );
+}
+
+/** Resolves the editor for a contentFormat, falling back to the plain
+ *  textarea when no clientFeature registered one. `contentFormat`
+ *  undefined (collection didn't declare one) behaves like "plain". */
+export function useContentEditor(contentFormat?: string): ContentEditorComponent {
+  const map = useContext(ContentEditorsContext);
+  return map[contentFormat ?? "plain"] ?? TextareaContentEditor;
+}

package/src/app/variable-chips.tsx

@@ -0,0 +1,39 @@
+// Editor-agnostic chip bar for a content editor's declared variables
+// (ContentCollectionDefinition.variableSchema). Renders next to the text
+// surface, never inside it — step 3 (rich/tiptap) reuses this same bar over
+// a different editor, so it must not assume a textarea underneath.
+
+import { Fragment, type ReactNode } from "react";
+import { useTranslation } from "../i18n";
+import { usePrimitives } from "../primitives";
+
+export type VariableChipsProps = {
+  readonly variables: readonly string[];
+  readonly onInsert: (name: string) => void;
+  readonly disabled?: boolean;
+};
+
+// No wrapping element: @cosmicdrift/kumiko-renderer is DOM-free (native impls
+// have no <div>), and layout is a platform concern anyway — the caller
+// (PlainContentEditor et al.) places these buttons in its own container.
+export function VariableChips({ variables, onInsert, disabled }: VariableChipsProps): ReactNode {
+  const { Button } = usePrimitives();
+  const t = useTranslation();
+  return (
+    <Fragment>
+      {variables.map((name) => (
+        <Button
+          key={name}
+          type="button"
+          variant="secondary"
+          size="sm"
+          disabled={disabled}
+          onClick={() => onInsert(name)}
+          ariaLabel={t("kumiko.contentEditor.insertVariable", { name })}
+        >
+          {`{{${name}}}`}
+        </Button>
+      ))}
+    </Fragment>
+  );
+}

package/src/i18n-defaults.ts

@@ -85,6 +85,9 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     // Row-Actions — Fehler-Toast wenn ein Action-Write fehlschlägt.
     "kumiko.rowAction.failed": "Aktion fehlgeschlagen",
 
+    // ContentEditor — Variablen-Chip-Leiste (VariableChips).
+    "kumiko.contentEditor.insertVariable": "{name} einfügen",
+
     // Config-Cascade — Source-Badges + Cascade-Panel (ConfigCascadeView).
     "kumiko.config.source.user": "Mein Wert",
     "kumiko.config.source.tenant": "Tenant",
@@ -216,6 +219,8 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
 
     "kumiko.rowAction.failed": "Action failed",
 
+    "kumiko.contentEditor.insertVariable": "Insert {name}",
+
     "kumiko.config.source.user": "My value",
     "kumiko.config.source.tenant": "Tenant",
     "kumiko.config.source.system": "System",

package/src/index.ts

@@ -18,6 +18,18 @@ export type {
   ColumnRenderersProviderProps,
 } from "./app/column-renderers";
 export { ColumnRenderersProvider, useColumnRenderer } from "./app/column-renderers";
+export type {
+  ContentEditorComponent,
+  ContentEditorProps,
+  ContentEditorsMap,
+  ContentEditorsProviderProps,
+} from "./app/content-editors";
+export {
+  CONTENT_EDITOR_ELEMENT_ID,
+  ContentEditorsProvider,
+  TextareaContentEditor,
+  useContentEditor,
+} from "./app/content-editors";
 export type { CustomScreensMap, CustomScreensProviderProps } from "./app/custom-screens";
 export { CustomScreensProvider, useCustomScreenComponent } from "./app/custom-screens";
 export type { DashboardBodyProps, DashboardBodyProviderProps } from "./app/dashboard-body";
@@ -52,6 +64,8 @@ export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen
 export type { NavApi, NavProviderProps, NavRoute, NavTarget } from "./app/nav";
 export { formatPath, NavProvider, parsePath, useNav } from "./app/nav";
 export { lastSegment } from "./app/qn";
+export type { VariableChipsProps } from "./app/variable-chips";
+export { VariableChips } from "./app/variable-chips";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error";
 export type { RenderEditProps } from "./components/render-edit";
 export { RenderEdit } from "./components/render-edit";