@cosmicdrift/kumiko-renderer-web 0.182.0 → 0.183.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.182.0",
+  "version": "0.183.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.182.0",
-    "@cosmicdrift/kumiko-headless": "0.182.0",
-    "@cosmicdrift/kumiko-renderer": "0.182.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.183.0",
+    "@cosmicdrift/kumiko-headless": "0.183.0",
+    "@cosmicdrift/kumiko-renderer": "0.183.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -38,7 +38,11 @@
     "react-dom": "^19.2.6",
     "react-resizable-panels": "^4.12.2",
     "tailwind-merge": "^3.6.0",
-    "temporal-polyfill": "^0.3.2"
+    "temporal-polyfill": "^0.3.2",
+    "@tiptap/core": "^3.29.2",
+    "@tiptap/pm": "^3.29.2",
+    "@tiptap/react": "^3.29.2",
+    "@tiptap/starter-kit": "^3.29.2"
   },
   "peerDependencies": {
     "@tailwindcss/cli": "^4.3.0",

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

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { CONTENT_EDITOR_ELEMENT_ID } from "@cosmicdrift/kumiko-renderer";
+import { render, screen } from "../../__tests__/test-utils";
+import { RichContentEditor } from "../rich-content-editor";
+
+describe("RichContentEditor", () => {
+  test("falls back to the plain textarea while the tiptap chunk loads, then swaps in the editor", async () => {
+    render(
+      <RichContentEditor
+        value="<p>hello</p>"
+        onChange={() => {}}
+        variables={[]}
+        readOnly={false}
+      />,
+    );
+    // The textarea id proves #1794's "never an empty panel" fallback is the
+    // Suspense boundary — a null fallback would leave nothing to find here.
+    expect(document.getElementById(CONTENT_EDITOR_ELEMENT_ID)).not.toBeNull();
+    expect(await screen.findByText("hello")).toBeTruthy();
+  });
+});

package/src/app/__tests__/tiptap-editor.test.tsx

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { CONTENT_EDITOR_ELEMENT_ID } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { fireEvent, render, screen } from "../../__tests__/test-utils";
+import TiptapEditor from "../tiptap-editor";
+
+function Controlled({ initial }: { readonly initial: string }): ReactNode {
+  const [value, setValue] = useState(initial);
+  return <TiptapEditor value={value} onChange={setValue} variables={["name"]} readOnly={false} />;
+}
+
+// Mirrors the real caller: TextBlockEditor mounts with value="" and only
+// gets the loaded content after its by-slug query resolves — value arrives
+// as a prop update, not at mount. A test that renders the final HTML
+// straight away would stay green even if the sync effect were missing.
+function LateValue({ loaded }: { readonly loaded: string }): ReactNode {
+  const [value, setValue] = useState("");
+  return (
+    <div>
+      <button type="button" onClick={() => setValue(loaded)}>
+        load
+      </button>
+      <TiptapEditor value={value} onChange={setValue} variables={[]} readOnly={false} />
+    </div>
+  );
+}
+
+describe("TiptapEditor — jsdom smoke", () => {
+  test("mounts a contenteditable surface for the given HTML", async () => {
+    render(
+      <TiptapEditor value="<p>hello</p>" onChange={() => {}} variables={[]} readOnly={false} />,
+    );
+    const editable = await screen.findByText("hello");
+    expect(editable.closest('[contenteditable="true"]')).not.toBeNull();
+  });
+
+  test("the contenteditable surface carries CONTENT_EDITOR_ELEMENT_ID so the wrapping Field's label stays associated", async () => {
+    render(
+      <TiptapEditor value="<p>hello</p>" onChange={() => {}} variables={[]} readOnly={false} />,
+    );
+    expect(document.getElementById(CONTENT_EDITOR_ELEMENT_ID)).not.toBeNull();
+  });
+
+  test("no variables → no chip bar", async () => {
+    render(
+      <TiptapEditor value="<p>hello</p>" onChange={() => {}} variables={[]} readOnly={false} />,
+    );
+    await screen.findByText("hello");
+    expect(screen.queryAllByRole("button", { name: "Bold" })).toHaveLength(1);
+    expect(screen.queryByText(/^\{\{.*\}\}$/)).toBeNull();
+  });
+
+  test("every toolbar action resolves by its accessible name", async () => {
+    render(
+      <TiptapEditor value="<p>hello</p>" onChange={() => {}} variables={[]} readOnly={false} />,
+    );
+    await screen.findByText("hello");
+    for (const name of [
+      "Bold",
+      "Italic",
+      "Heading 1",
+      "Heading 2",
+      "Bullet list",
+      "Numbered list",
+    ]) {
+      expect(screen.getByRole("button", { name })).toBeTruthy();
+    }
+  });
+
+  test("a value arriving after mount (async load) still reaches the editor", async () => {
+    render(<LateValue loaded="<p>loaded content</p>" />);
+    expect(screen.queryByText("loaded content")).toBeNull();
+    fireEvent.click(screen.getByText("load"));
+    expect(await screen.findByText("loaded content")).toBeTruthy();
+  });
+
+  test("toolbar H1 toggles the block type and reports it via onChange", async () => {
+    // Block-type commands (headings) apply at the cursor's block, unlike
+    // inline marks (bold/italic) which need an explicit text selection —
+    // simulating a real range selection in happy-dom is unreliable, so this
+    // is the toolbar-wiring smoke test; the extension itself is tiptap's.
+    render(<Controlled initial="<p>hello</p>" />);
+    await screen.findByText("hello");
+    fireEvent.click(screen.getByRole("button", { name: "Heading 1" }));
+    const editable = (await screen.findByText("hello")).closest('[contenteditable="true"]');
+    expect(editable?.innerHTML).toContain("<h1");
+  });
+
+  test("variable chip inserts {{name}} as plain text at the cursor", async () => {
+    render(<Controlled initial="<p></p>" />);
+    fireEvent.click(screen.getByText("{{name}}"));
+    expect(await screen.findByText("{{name}}", { selector: "p" })).toBeTruthy();
+  });
+});

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

@@ -0,0 +1,21 @@
+// @runtime client
+//
+// "rich" contentFormat editor: WYSIWYG on tiptap. Public contract is the
+// same four props every ContentEditorComponent gets — no tiptap type
+// crosses this boundary. tiptap itself is dynamic-imported (TiptapEditor
+// lives in ./tiptap-editor) so an app that never mounts a "rich" collection
+// never pays for it; the fallback while the chunk loads is the same plain
+// textarea #1794 uses for a missing editor, never a blank panel.
+
+import { type ContentEditorProps, TextareaContentEditor } from "@cosmicdrift/kumiko-renderer";
+import { lazy, type ReactNode, Suspense } from "react";
+
+const TiptapEditor = lazy(() => import("./tiptap-editor"));
+
+export function RichContentEditor(props: ContentEditorProps): ReactNode {
+  return (
+    <Suspense fallback={<TextareaContentEditor {...props} />}>
+      <TiptapEditor {...props} />
+    </Suspense>
+  );
+}

package/src/app/tiptap-editor.tsx

@@ -0,0 +1,178 @@
+// @runtime client
+//
+// tiptap-backed implementation behind RichContentEditor's lazy() boundary —
+// never import this file directly, tiptap must only load when a "rich"
+// collection is actually rendered. StarterKit covers bold/italic/lists/
+// headings, and its bundled Link extension autolinks on type/paste — no
+// link button, so no URL-prompt UI to build or test.
+
+import {
+  CONTENT_EDITOR_ELEMENT_ID,
+  type ContentEditorProps,
+  TextareaContentEditor,
+  usePrimitives,
+  useTranslation,
+  VariableChips,
+} from "@cosmicdrift/kumiko-renderer";
+import { EditorContent, useEditor } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import {
+  Bold as BoldIcon,
+  Heading1,
+  Heading2,
+  Italic as ItalicIcon,
+  List,
+  ListOrdered,
+} from "lucide-react";
+import { type ReactNode, useEffect } from "react";
+import { cn } from "../lib/cn";
+
+type ToolbarAction = {
+  readonly label: string;
+  readonly icon: typeof BoldIcon;
+  readonly isActive: boolean;
+  readonly onClick: () => void;
+};
+
+function Toolbar({
+  actions,
+  disabled,
+}: {
+  readonly actions: readonly ToolbarAction[];
+  readonly disabled: boolean;
+}): ReactNode {
+  const { Button } = usePrimitives();
+  return (
+    <div className="flex flex-wrap gap-1 border-b border-input p-1">
+      {actions.map((action) => (
+        <Button
+          key={action.label}
+          type="button"
+          variant={action.isActive ? "primary" : "secondary"}
+          size="icon"
+          disabled={disabled}
+          onClick={action.onClick}
+          ariaLabel={action.label}
+        >
+          <action.icon size={16} />
+        </Button>
+      ))}
+    </div>
+  );
+}
+
+export default function TiptapEditor({
+  value,
+  onChange,
+  variables,
+  readOnly,
+}: ContentEditorProps): ReactNode {
+  const t = useTranslation();
+  const editor = useEditor({
+    extensions: [StarterKit],
+    content: value,
+    editable: !readOnly,
+    // Suspense (RichContentEditor's lazy boundary) speculatively mounts
+    // this component before committing it; immediate render would create
+    // an editor instance during that throwaway pass.
+    immediatelyRender: false,
+    // Same id the textarea fallback uses — the Field wrapping the editor
+    // (TextBlockEditor) associates its label via this id; the editor
+    // contract has no `id` prop of its own, see content-editors.tsx.
+    editorProps: { attributes: { id: CONTENT_EDITOR_ELEMENT_ID } },
+    onUpdate: ({ editor: e }) => onChange(e.getHTML()),
+  });
+
+  // TextBlockEditor loads the entry's content asynchronously (by-slug query
+  // resolves after mount), so `value` arrives after useEditor already read
+  // its initial (empty) content once. Sync it in — guarded against
+  // clobbering in-flight typing by comparing against the editor's own HTML.
+  useEffect(() => {
+    if (editor && value !== editor.getHTML()) {
+      editor.commands.setContent(value, { emitUpdate: false });
+    }
+  }, [value, editor]);
+
+  useEffect(() => {
+    editor?.setEditable(!readOnly);
+  }, [readOnly, editor]);
+
+  if (!editor)
+    return (
+      <TextareaContentEditor
+        value={value}
+        onChange={onChange}
+        variables={variables}
+        readOnly={readOnly}
+      />
+    );
+
+  const actions: readonly ToolbarAction[] = [
+    {
+      label: t("kumiko.contentEditor.bold"),
+      icon: BoldIcon,
+      isActive: editor.isActive("bold"),
+      onClick: () => editor.chain().focus().toggleBold().run(),
+    },
+    {
+      label: t("kumiko.contentEditor.italic"),
+      icon: ItalicIcon,
+      isActive: editor.isActive("italic"),
+      onClick: () => editor.chain().focus().toggleItalic().run(),
+    },
+    {
+      label: t("kumiko.contentEditor.heading1"),
+      icon: Heading1,
+      isActive: editor.isActive("heading", { level: 1 }),
+      onClick: () => editor.chain().focus().toggleHeading({ level: 1 }).run(),
+    },
+    {
+      label: t("kumiko.contentEditor.heading2"),
+      icon: Heading2,
+      isActive: editor.isActive("heading", { level: 2 }),
+      onClick: () => editor.chain().focus().toggleHeading({ level: 2 }).run(),
+    },
+    {
+      label: t("kumiko.contentEditor.bulletList"),
+      icon: List,
+      isActive: editor.isActive("bulletList"),
+      onClick: () => editor.chain().focus().toggleBulletList().run(),
+    },
+    {
+      label: t("kumiko.contentEditor.orderedList"),
+      icon: ListOrdered,
+      isActive: editor.isActive("orderedList"),
+      onClick: () => editor.chain().focus().toggleOrderedList().run(),
+    },
+  ];
+
+  const insertVariable = (name: string): void => {
+    editor
+      .chain()
+      .focus()
+      .insertContent({ type: "text", text: `{{${name}}}` })
+      .run();
+  };
+
+  return (
+    <div className="rounded-md border border-input bg-transparent">
+      <Toolbar actions={actions} disabled={readOnly} />
+      <EditorContent
+        editor={editor}
+        className={cn(
+          "min-h-40 px-3 py-2 text-base outline-none md:text-sm",
+          "[&_.ProseMirror]:min-h-40 [&_.ProseMirror]:outline-none",
+          "[&_ul]:list-disc [&_ol]:list-decimal [&_ul]:pl-6 [&_ol]:pl-6",
+          "[&_h1]:text-xl [&_h1]:font-bold [&_h2]:text-lg [&_h2]:font-bold",
+          "[&_a]:underline [&_a]:text-primary",
+          "[&_strong]:font-bold [&_em]:italic",
+        )}
+      />
+      {variables.length > 0 && (
+        <div className="border-t border-input p-1">
+          <VariableChips variables={variables} onInsert={insertVariable} disabled={readOnly} />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -97,6 +97,7 @@ 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 { RichContentEditor } from "./app/rich-content-editor";
 export type { AppLayoutProps } from "./layout/app-layout";
 export { AppLayout } from "./layout/app-layout";
 export type { AvatarProps, AvatarSize } from "./layout/avatar";