@clevertask/scribe 0.0.15 → 0.1.1

package/README.md

@@ -9,12 +9,14 @@ A versatile, block-based rich text editor for diverse applications, built with T
 - **Markdown Paste:** Paste plain-text markdown into the editor and have it converted into rich content automatically.
 - **Versatile Integration:** Easily integrate `@clevertask/scribe` into any project requiring rich text editing.
 - **View and Edit:** Seamlessly switch between viewing and editing modes.
+- **Experimental Table of Contents:** Subscribe to heading changes and render an app-owned table of contents outside the editor.
 
 ## Table of Contents
 
 - [@clevertask/scribe](#clevertaskscribe)
   - [Installation](#installation)
   - [Usage](#usage)
+  - [Experimental Table of Contents](#experimental-table-of-contents)
   - [Math Expressions](#math-expressions)
   - [Props](#props)
   - [Helper Functions](#helper-functions)
@@ -37,8 +39,10 @@ npm install @clevertask/scribe
 ### Basic usage
 
 ```tsx
+import "@radix-ui/themes/styles.css";
 import "@clevertask/scribe/dist/main.css";
-import { Scribe, ScribeOnChangeContents } from "@clevertask/scribe";
+import { Theme } from "@radix-ui/themes";
+import { Scribe, ScribeRef } from "@clevertask/scribe";
 
 function App() {
   const onContentChange = useCallback(
@@ -48,14 +52,20 @@ function App() {
     [],
   );
 
-  return <Scribe onContentChange={onContentChange} />;
+  return (
+    <Theme>
+      <Scribe onContentChange={onContentChange} />
+    </Theme>
+  );
 }
 ```
 
 ### With ref
 
 ```tsx
+import "@radix-ui/themes/styles.css";
 import "@clevertask/scribe/dist/main.css";
+import { Theme } from "@radix-ui/themes";
 import { Scribe, ScribeOnChangeContents } from "@clevertask/scribe";
 
 function App() {
@@ -67,37 +77,76 @@ function App() {
 
   return (
     <>
-      <Scribe ref={editor} />
+      <Theme>
+        <Scribe ref={editor} />
+      </Theme>
       <button onClick={resetContent}>Reset content</button>
     </>
   );
 }
 ```
 
-### With Dark Mode
+### Using Your App Theme
 
 ```tsx
+import "@radix-ui/themes/styles.css";
 import "@clevertask/scribe/dist/main.css";
-import { Scribe, ScribeOnChangeContents } from "@clevertask/scribe";
+import { Theme } from "@radix-ui/themes";
+import { Scribe } from "@clevertask/scribe";
 
 function App() {
-  const editor = useRef<ScribeRef>(null);
+  return (
+    <Theme appearance="dark">
+      <Scribe />
+    </Theme>
+  );
+}
+```
 
-  const resetContent = useCallback(() => {
-    editor.current.resetContent();
-  }, []);
+## Experimental Table of Contents
+
+Scribe can expose table-of-contents data without rendering a table-of-contents block inside the editable document. Enable the experimental API with `enableTableOfContents`, keep the latest items in your app state, and call `scrollToTableOfContentsItem` when a user selects an entry.
+
+```tsx
+import { Scribe, ScribeRef, ScribeTableOfContentsItem } from "@clevertask/scribe";
+import { useRef, useState } from "react";
+
+function DocumentEditor() {
+  const scribe = useRef<ScribeRef>(null);
+  const [tableOfContentsItems, setTableOfContentsItems] = useState<ScribeTableOfContentsItem[]>([]);
 
   return (
     <>
-      <Scribe darkMode />
-      <button onClick={resetContent}>Reset content</button>
+      <Scribe
+        ref={scribe}
+        enableTableOfContents
+        onTableOfContentsChange={setTableOfContentsItems}
+      />
+
+      {tableOfContentsItems.length > 0 ? (
+        <nav aria-label="Table of contents">
+          {tableOfContentsItems.map((item) => (
+            <button
+              key={item.id}
+              type="button"
+              onClick={() => scribe.current?.scrollToTableOfContentsItem(item)}
+            >
+              {item.textContent}
+            </button>
+          ))}
+        </nav>
+      ) : null}
     </>
   );
 }
 ```
 
+The table of contents currently tracks default TipTap heading nodes only. Each item includes the heading text, depth, document position, DOM node, and active/scrolled state. This API is marked experimental while we validate the contract in real document surfaces.
+
 ## Math Expressions
 
+Scribe's default UI is styled with Radix Themes components. Load `@radix-ui/themes/styles.css` once in your app alongside `@clevertask/scribe/dist/main.css`, and render Scribe somewhere inside a Radix `<Theme>`.
+
 Scribe ships with `@tiptap/extension-mathematics`. The extension renders math when it receives math nodes in the HTML:
 
 ```html
@@ -127,22 +176,23 @@ If your content arrives as HTML (for example from a server), use the helper belo
 
 ## Props
 
-| Prop                     | Type                                         | Default                    | Description                                                                                                                                                                                                                                        |
-| ------------------------ | -------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `content`                | `string`                                     | `undefined`                | The initial content of the editor. This prop can also be used to control the editor's content. When `content` is updated, the editor's content will be updated accordingly.                                                                        |
-| `onContentChange`        | `(content: ScribeOnChangeContents) => void;` | `undefined`                | A callback function triggered whenever the editor's content changes. It receives an object containing the current content in various formats (`jsonContent`, `htmlContent`, `markdownContent`).                                                    |
-| `editable`               | `boolean`                                    | `true`                     | Controls whether the editor is editable.                                                                                                                                                                                                           |
-| `autoFocus`              | `boolean`                                    | `false`                    | Controls whether the editor should automatically focus when mounted.                                                                                                                                                                               |
-| `extensions`             | `Extension[]`                                | `undefined`                | You can set your own extensions for the text editor. For more information, [check the tip tap extensions docs](https://tiptap.dev/docs/editor/core-concepts/extensions)                                                                            |
-| `editorProps`            | `EditorProps`                                | `undefined`                | A tiptap-based prop to handle advanced use cases, you can read about it on their [documentation](https://tiptap.dev/docs/editor/api/editor#editorprops)                                                                                            |
-| `showBarMenu`            | `boolean`                                    | `true`                     | Determines whether to show the text editor top menu bar or not. This menu bar shows options to format the text                                                                                                                                     |
-| `placeholderText`        | `string`                                     | `Type "/" for commands...` | Change the initial placeholder for your text editor                                                                                                                                                                                                |
-| `editorContentStyle`     | `React.CSSProperties`                        | `undefined`                | You can send a CSS object to add styles to the editor content container. Useful if you want to limit the editor's height.                                                                                                                          |
-| `editorContentClassName` | `string`                                     | `undefined`                | The same idea of `editorContentStyle` but with classes.                                                                                                                                                                                            |
-| `mainContainerStyle`     | `React.CSSProperties`                        | `undefined`                | You can send a CSS object to style the main editor container                                                                                                                                                                                       |
-| `mainContainerClassName` | `string`                                     | `undefined`                | The same idea of `mainContainerStyle` but with classes.                                                                                                                                                                                            |
-| `onKeyDown`              | `KeyboardEventHandler`                       | `undefined`                | A callback function that is triggered when a key is pressed within the editor. This allows you to handle custom keyboard shortcuts. For example, you can use this prop to implement a "send message" functionality when `Ctrl + Enter` is pressed. |
-| `darkMode`               | `boolean`                                    | `false`                    | You can switch the darkMode value to change the text editor's theme                                                                                                                                                                                |
+| Prop                      | Type                                                               | Default                    | Description                                                                                                                                                                                                                                              |
+| ------------------------- | ------------------------------------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `content`                 | `string`                                                           | `undefined`                | The initial content of the editor. Controlled updates through this prop are deprecated; prefer `ScribeRef.setContent` for programmatic updates after mount.                                                                                              |
+| `onContentChange`         | `(content: ScribeOnChangeContents) => void;`                       | `undefined`                | A callback function triggered whenever the editor's content changes. It receives an object containing the current content in various formats (`jsonContent`, `htmlContent`, `markdownContent`). Internal table-of-contents metadata updates are ignored. |
+| `editable`                | `boolean`                                                          | `true`                     | Controls whether the editor is editable.                                                                                                                                                                                                                 |
+| `autoFocus`               | `boolean`                                                          | `false`                    | Controls whether the editor should automatically focus when mounted.                                                                                                                                                                                     |
+| `extensions`              | `Extension[]`                                                      | `undefined`                | You can set your own extensions for the text editor. For more information, [check the tip tap extensions docs](https://tiptap.dev/docs/editor/core-concepts/extensions)                                                                                  |
+| `editorProps`             | `EditorProps`                                                      | `undefined`                | A tiptap-based prop to handle advanced use cases, you can read about it on their [documentation](https://tiptap.dev/docs/editor/api/editor#editorprops)                                                                                                  |
+| `showBarMenu`             | `boolean`                                                          | `true`                     | Determines whether to show the text editor top menu bar or not. This menu bar shows options to format the text                                                                                                                                           |
+| `placeholderText`         | `string`                                                           | `Type "/" for commands...` | Change the initial placeholder for your text editor                                                                                                                                                                                                      |
+| `editorContentStyle`      | `React.CSSProperties`                                              | `undefined`                | You can send a CSS object to add styles to the editor content container. Useful if you want to limit the editor's height.                                                                                                                                |
+| `editorContentClassName`  | `string`                                                           | `undefined`                | The same idea of `editorContentStyle` but with classes.                                                                                                                                                                                                  |
+| `mainContainerStyle`      | `React.CSSProperties`                                              | `undefined`                | You can send a CSS object to style the main editor container                                                                                                                                                                                             |
+| `mainContainerClassName`  | `string`                                                           | `undefined`                | The same idea of `mainContainerStyle` but with classes.                                                                                                                                                                                                  |
+| `onKeyDown`               | `KeyboardEventHandler`                                             | `undefined`                | A callback function that is triggered when a key is pressed within the editor. This allows you to handle custom keyboard shortcuts. For example, you can use this prop to implement a "send message" functionality when `Ctrl + Enter` is pressed.       |
+| `enableTableOfContents`   | `boolean`                                                          | `false`                    | Experimental. Enables the app-owned table-of-contents API for heading nodes.                                                                                                                                                                             |
+| `onTableOfContentsChange` | `(items: ScribeTableOfContentsItem[], isCreate?: boolean) => void` | `undefined`                | Experimental. Receives table-of-contents items whenever heading text, structure, or active/scrolled state changes.                                                                                                                                       |
 
 ## Helper Functions
 

package/dist/BarMenu-DaKIz3zZ.js

@@ -0,0 +1,327 @@
+import { jsx as i, jsxs as l } from "react/jsx-runtime";
+import { Box as A, Flex as r, Popover as g, IconButton as B, Text as m, TextField as R, Button as f, Separator as F } from "@radix-ui/themes";
+import { u as H } from "./index-DxF-1P4n.js";
+import { useState as v, useCallback as u, Fragment as U } from "react";
+import { getPopupMountTarget as V } from "./components/Scribe/extension/getPopupMountTarget.js";
+import { BoldIcon as q, ItalicIcon as E, StrikeIcon as W, InlineCodeIcon as Q, HighlightIcon as G, UnorderedListIcon as J, OrderedListIcon as K, LinkIcon as X, ImageIcon as Y, CodeBlockIcon as Z, BlockQuoteIcon as _, HorizontalLineIcon as ee } from "./icons/ToolbarIcons.js";
+function O(e) {
+  var s, a, t = "";
+  if (typeof e == "string" || typeof e == "number") t += e;
+  else if (typeof e == "object") if (Array.isArray(e)) {
+    var h = e.length;
+    for (s = 0; s < h; s++) e[s] && (a = O(e[s])) && (t && (t += " "), t += a);
+  } else for (a in e) e[a] && (t && (t += " "), t += a);
+  return t;
+}
+function I() {
+  for (var e, s, a = 0, t = "", h = arguments.length; a < h; a++) (e = arguments[a]) && (s = O(e)) && (t && (t += " "), t += s);
+  return t;
+}
+const ce = ({ editor: e }) => {
+  const [s, a] = v(!1), [t, h] = v(!1), [p, y] = v(""), [b, L] = v(""), C = V(e), c = H({
+    editor: e,
+    selector: ({ editor: n }) => n ? {
+      isBold: n.isActive("bold"),
+      isItalic: n.isActive("italic"),
+      isStrike: n.isActive("strike"),
+      isCode: n.isActive("code"),
+      isHighlight: n.isActive("highlight"),
+      isBulletList: n.isActive("bulletList"),
+      isOrderedList: n.isActive("orderedList"),
+      isLink: n.isActive("link"),
+      isImage: n.isActive("image"),
+      isCodeBlock: n.isActive("codeBlock"),
+      isBlockquote: n.isActive("blockquote")
+    } : null
+  }), z = u(
+    (n) => {
+      if (n) {
+        const d = e.getAttributes("link").href ?? "";
+        y(d), h(!1);
+      }
+      a(n);
+    },
+    [e]
+  ), M = u(
+    (n) => {
+      if (n) {
+        const d = e.getAttributes("image").src ?? "";
+        L(d), a(!1);
+      }
+      h(n);
+    },
+    [e]
+  ), S = u(() => {
+    const n = p.trim();
+    if (n.length === 0) {
+      e.chain().focus().extendMarkRange("link").unsetLink().run(), a(!1);
+      return;
+    }
+    e.chain().focus().extendMarkRange("link").setLink({ href: n }).selectTextblockEnd().run(), a(!1);
+  }, [e, p]), P = u(() => {
+    e.chain().focus().extendMarkRange("link").unsetLink().run(), a(!1);
+  }, [e]), T = u(() => {
+    const n = b.trim();
+    n && (e.chain().focus().setImage({ src: n }).run(), h(!1));
+  }, [e, b]), D = u(
+    (n, d) => {
+      n.preventDefault(), d();
+    },
+    []
+  ), w = u((n) => {
+    n.preventDefault();
+  }, []), N = u(
+    ({ target: { value: n } }) => {
+      y(n);
+    },
+    []
+  ), $ = u(
+    ({ target: { value: n } }) => {
+      L(n);
+    },
+    []
+  ), x = [
+    [
+      {
+        name: "bold",
+        icon: q,
+        command: () => e.chain().focus().toggleBold().run(),
+        isActive: () => !!c?.isBold
+      },
+      {
+        name: "italic",
+        icon: E,
+        command: () => e.chain().focus().toggleItalic().run(),
+        isActive: () => !!c?.isItalic
+      },
+      {
+        name: "strike",
+        icon: W,
+        command: () => e.chain().focus().toggleStrike().run(),
+        isActive: () => !!c?.isStrike
+      }
+    ],
+    [
+      {
+        name: "inline-code",
+        icon: Q,
+        command: () => e.chain().focus().toggleCode().run(),
+        isActive: () => !!c?.isCode
+      },
+      {
+        name: "highlight",
+        icon: G,
+        command: () => e.chain().focus().toggleHighlight().run(),
+        isActive: () => !!c?.isHighlight
+      }
+    ],
+    [
+      {
+        name: "unordered-list",
+        icon: J,
+        command: () => e.chain().focus().toggleBulletList().run(),
+        isActive: () => !!c?.isBulletList
+      },
+      {
+        name: "ordered-list",
+        icon: K,
+        command: () => e.chain().focus().toggleOrderedList().run(),
+        isActive: () => !!c?.isOrderedList
+      }
+    ],
+    [
+      {
+        name: "link",
+        icon: X,
+        isActive: () => !!c?.isLink,
+        popover: "link"
+      },
+      {
+        name: "image",
+        icon: Y,
+        isActive: () => !!c?.isImage,
+        disabled: !1,
+        popover: "image"
+      },
+      {
+        name: "code-block",
+        icon: Z,
+        command: () => e.chain().focus().toggleCodeBlock().run(),
+        isActive: () => !!c?.isCodeBlock
+      },
+      {
+        name: "block-quote",
+        icon: _,
+        command: () => e.chain().focus().toggleBlockquote().run(),
+        isActive: () => !!c?.isBlockquote
+      },
+      {
+        name: "horizontal-line",
+        icon: ee,
+        command: () => e.chain().focus().setHorizontalRule().run(),
+        isActive: () => !1
+      }
+    ]
+  ];
+  return /* @__PURE__ */ i(A, { className: "scribe-toolbar", children: /* @__PURE__ */ i(r, { align: "center", gap: "3", wrap: "wrap", children: x.map((n, d) => /* @__PURE__ */ l(U, { children: [
+    /* @__PURE__ */ i(r, { align: "center", gap: "2", wrap: "wrap", children: n.map((o, k) => o.popover === "link" ? /* @__PURE__ */ l(
+      g.Root,
+      {
+        open: s,
+        onOpenChange: z,
+        children: [
+          /* @__PURE__ */ i(g.Trigger, { children: /* @__PURE__ */ i(
+            B,
+            {
+              type: "button",
+              radius: "medium",
+              color: "gray",
+              variant: o.isActive() ? "soft" : "ghost",
+              disabled: o.disabled || !e.isEditable,
+              title: o.name,
+              onMouseDown: w,
+              className: I(o.disabled && "scribe-toolbar-button--disabled"),
+              children: /* @__PURE__ */ i(o.icon, { className: "scribe-toolbar-icon" })
+            }
+          ) }),
+          /* @__PURE__ */ i(
+            g.Content,
+            {
+              container: C,
+              size: "2",
+              side: "bottom",
+              align: "start",
+              style: { maxWidth: "calc(100vw - 32px)", width: 320 },
+              children: /* @__PURE__ */ l(r, { direction: "column", gap: "4", children: [
+                /* @__PURE__ */ l(A, { children: [
+                  /* @__PURE__ */ i(m, { as: "p", size: "3", weight: "medium", children: "Link" }),
+                  /* @__PURE__ */ i(m, { as: "p", size: "2", color: "gray", children: "Add or update a link for the current selection." })
+                ] }),
+                /* @__PURE__ */ i("label", { children: /* @__PURE__ */ l(r, { direction: "column", gap: "2", children: [
+                  /* @__PURE__ */ i(m, { as: "span", size: "2", weight: "medium", children: "URL" }),
+                  /* @__PURE__ */ i(
+                    R.Root,
+                    {
+                      autoFocus: !0,
+                      placeholder: "https://example.com",
+                      value: p,
+                      onChange: N
+                    }
+                  )
+                ] }) }),
+                /* @__PURE__ */ l(r, { justify: "between", gap: "3", wrap: "wrap", children: [
+                  /* @__PURE__ */ i(
+                    f,
+                    {
+                      type: "button",
+                      color: "red",
+                      variant: "soft",
+                      disabled: !((e.getAttributes("link").href ?? "").trim() || p.trim()),
+                      onClick: P,
+                      children: "Remove link"
+                    }
+                  ),
+                  /* @__PURE__ */ l(r, { gap: "2", justify: "end", style: { marginLeft: "auto" }, children: [
+                    /* @__PURE__ */ i(g.Close, { children: /* @__PURE__ */ i(f, { type: "button", variant: "soft", color: "gray", children: "Cancel" }) }),
+                    /* @__PURE__ */ i(
+                      f,
+                      {
+                        type: "button",
+                        disabled: p.trim().length === 0,
+                        onClick: S,
+                        children: "Save"
+                      }
+                    )
+                  ] })
+                ] })
+              ] })
+            }
+          )
+        ]
+      },
+      `${o.name}-${k}`
+    ) : o.popover === "image" ? /* @__PURE__ */ l(
+      g.Root,
+      {
+        open: t,
+        onOpenChange: M,
+        children: [
+          /* @__PURE__ */ i(g.Trigger, { children: /* @__PURE__ */ i(
+            B,
+            {
+              type: "button",
+              radius: "medium",
+              color: "gray",
+              variant: o.isActive() ? "soft" : "ghost",
+              disabled: o.disabled || !e.isEditable,
+              title: o.name,
+              onMouseDown: w,
+              className: I(o.disabled && "scribe-toolbar-button--disabled"),
+              children: /* @__PURE__ */ i(o.icon, { className: "scribe-toolbar-icon" })
+            }
+          ) }),
+          /* @__PURE__ */ i(
+            g.Content,
+            {
+              container: C,
+              size: "2",
+              side: "bottom",
+              align: "start",
+              style: { maxWidth: "calc(100vw - 32px)", width: 320 },
+              children: /* @__PURE__ */ l(r, { direction: "column", gap: "4", children: [
+                /* @__PURE__ */ l(A, { children: [
+                  /* @__PURE__ */ i(m, { as: "p", size: "3", weight: "medium", children: "Image" }),
+                  /* @__PURE__ */ i(m, { as: "p", size: "2", color: "gray", children: "Insert an image from a URL." })
+                ] }),
+                /* @__PURE__ */ i("label", { children: /* @__PURE__ */ l(r, { direction: "column", gap: "2", children: [
+                  /* @__PURE__ */ i(m, { as: "span", size: "2", weight: "medium", children: "Image URL" }),
+                  /* @__PURE__ */ i(
+                    R.Root,
+                    {
+                      autoFocus: !0,
+                      placeholder: "https://example.com/image.png",
+                      value: b,
+                      onChange: $
+                    }
+                  )
+                ] }) }),
+                /* @__PURE__ */ l(r, { justify: "end", gap: "2", children: [
+                  /* @__PURE__ */ i(g.Close, { children: /* @__PURE__ */ i(f, { type: "button", variant: "soft", color: "gray", children: "Cancel" }) }),
+                  /* @__PURE__ */ i(
+                    f,
+                    {
+                      type: "button",
+                      disabled: b.trim().length === 0,
+                      onClick: T,
+                      children: "Save"
+                    }
+                  )
+                ] })
+              ] })
+            }
+          )
+        ]
+      },
+      `${o.name}-${k}`
+    ) : /* @__PURE__ */ i(
+      B,
+      {
+        type: "button",
+        radius: "medium",
+        color: "gray",
+        variant: o.isActive() ? "soft" : "ghost",
+        disabled: o.disabled || !e.isEditable,
+        title: o.name,
+        onMouseDown: (j) => D(j, o.command),
+        className: I(o.disabled && "scribe-toolbar-button--disabled"),
+        children: /* @__PURE__ */ i(o.icon, { className: "scribe-toolbar-icon" })
+      },
+      `${o.name}-${k}`
+    )) }),
+    d !== x.length - 1 ? /* @__PURE__ */ i(F, { orientation: "vertical", decorative: !0, style: { height: 20 } }) : null
+  ] }, `format-group-${d}`)) }) });
+};
+export {
+  ce as B,
+  I as c
+};