makersclaw 0.1.0 → 0.3.0

package/registry/blocks/doc-editor/demo.jsx

@@ -0,0 +1,225 @@
+"use client";
+
+// DocEditor three ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Document   the full editor: / menu, drag handles, @mentions; beside
+//              it what the helpers read out of the doc (markdown, the
+//              checklist). Read-only behind a switch.
+//   Comment    minimal mode: no side menu, no / menu; @mentions,
+//              Cmd/Ctrl+Enter posts, the box clears through its handle.
+//   Merge      an email body with merge fields ({ or /), previewed for
+//              each recipient, with a warning for a value the recipient lacks.
+import { useMemo, useState } from "react";
+import { Avatar, Badge, Button, Card, Field, IconButton, KbdGroup, Notice, Select, Switch, TabPanel, Tabs } from "../components/ui";
+import {
+  DocEditor,
+  docChecklist,
+  docFields,
+  docToMarkdown,
+  docToText,
+  isDocEmpty,
+  setChecklistItem,
+  useDocEditor,
+} from "../components/blocks/doc-editor";
+
+const PEOPLE = [
+  { id: "u-priya", label: "Priya Raman", description: "Design" },
+  { id: "u-tomas", label: "Tomás Ortega", description: "Engineering" },
+  { id: "u-june", label: "June Okafor", description: "Growth" },
+  { id: "u-lena", label: "Lena Fischer", description: "Sales" },
+];
+const findPeople = async (query) => {
+  const q = query.toLowerCase();
+  return PEOPLE.filter((p) => p.label.toLowerCase().includes(q));
+};
+
+const t = (text, styles = {}) => ({ type: "text", text, styles });
+const who = (id) => ({ type: "mention", props: { id, label: PEOPLE.find((p) => p.id === id).label } });
+
+// Written by hand, so each block gets its id here: the checklist beside
+// the editor ticks items by id before the first edit has come back.
+const LAUNCH_DOC = [
+  { type: "heading", props: { level: 1 }, content: [t("Harbor 2.0 launch")] },
+  {
+    type: "paragraph",
+    content: [t("We ship on "), t("14 November", { bold: true }), t(". This page is the one place for the plan; "), who("u-june"), t(" owns it.")],
+  },
+  { type: "heading", props: { level: 2 }, content: [t("Before launch")] },
+  { type: "checkListItem", props: { checked: true }, content: [t("Freeze the pricing page copy")] },
+  { type: "checkListItem", content: [who("u-priya"), t(" final hero screenshots")] },
+  { type: "checkListItem", content: [who("u-tomas"), t(" migrate the waitlist to the new plan table")] },
+  { type: "heading", props: { level: 2 }, content: [t("Launch day")] },
+  { type: "numberedListItem", content: [t("Changelog post at 9:00")] },
+  { type: "numberedListItem", content: [t("Email to the waitlist at 10:00")] },
+  { type: "numberedListItem", content: [t("Founders post on LinkedIn")] },
+  { type: "quote", content: [t("Say what changed for the customer, not what we built.")] },
+].map((b, i) => ({ id: `launch-${i + 1}`, ...b }));
+
+function DocumentDemo() {
+  const [doc, setDoc] = useState(LAUNCH_DOC);
+  const [readOnly, setReadOnly] = useState(false);
+  const [view, setView] = useState("checklist");
+  const items = useMemo(() => docChecklist(doc), [doc]);
+  return (
+    <div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_20rem]">
+      <Card padding="lg" actions={<Switch id="doc-ro" label="Read-only" checked={readOnly} onChange={(e) => setReadOnly(e.target.checked)} />}>
+        <DocEditor value={doc} onChange={setDoc} editable={!readOnly} mentions={findPeople} placeholder="Start writing, or press / for blocks" label="Launch plan" />
+      </Card>
+      <Card padding="none" className="min-w-0">
+        <Tabs
+          aria-label="What the helpers read"
+          className="px-3"
+          value={view}
+          onChange={setView}
+          tabs={[
+            { key: "checklist", label: `Checklist (${items.length})` },
+            { key: "markdown", label: "Markdown" },
+          ]}
+        />
+        <TabPanel tab="checklist" value={view} className="p-3">
+          {items.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No checklist items. Type [] in the doc to start one.</p>
+          ) : (
+            <ul className="grid gap-2">
+              {items.map((it) => (
+                <li key={it.id} className="flex items-start gap-2 text-sm">
+                  <IconButton
+                    size="sm"
+                    icon={it.checked ? "check-circle" : "circle"}
+                    label={it.checked ? "Mark not done" : "Mark done"}
+                    onClick={() => setDoc((d) => setChecklistItem(d, it.id, !it.checked))}
+                  />
+                  <span className={it.checked ? "pt-1.5 text-muted-foreground line-through" : "pt-1.5"}>{it.text || "Untitled item"}</span>
+                  {it.mentions[0] ? <Avatar name={it.mentions[0].label} size="xs" className="ml-auto mt-1 shrink-0" /> : null}
+                </li>
+              ))}
+            </ul>
+          )}
+        </TabPanel>
+        <TabPanel tab="markdown" value={view} className="p-3">
+          <pre className="max-h-96 overflow-auto whitespace-pre-wrap break-words font-mono text-xs text-muted-foreground">{docToMarkdown(doc)}</pre>
+        </TabPanel>
+      </Card>
+    </div>
+  );
+}
+
+const THREAD = [
+  { id: "c1", author: "Lena Fischer", text: "Can we move the email to 11:00? The EU list opens later." },
+  { id: "c2", author: "June Okafor", text: "@Lena Fischer fine by me — @Tomás Ortega does the send job care?" },
+];
+
+function CommentDemo() {
+  const [comments, setComments] = useState(THREAD);
+  const [draft, setDraft] = useState(null);
+  const box = useDocEditor();
+  const post = (doc) => {
+    if (isDocEmpty(doc)) return;
+    setComments((c) => [...c, { id: `c${c.length + 1}`, author: "You", text: docToText(doc) }]);
+    box.current?.clear();
+    setDraft(null);
+  };
+  return (
+    <Card title="Comments" description="Minimal mode: no side menu, no / menu. @ mentions someone." className="max-w-xl">
+      <ul className="mb-4 grid gap-3">
+        {comments.map((c) => (
+          <li key={c.id} className="flex gap-3">
+            <Avatar name={c.author} size="sm" />
+            <div className="min-w-0">
+              <p className="text-sm font-medium">{c.author}</p>
+              <p className="whitespace-pre-wrap break-words text-sm text-muted-foreground">{c.text}</p>
+            </div>
+          </li>
+        ))}
+      </ul>
+      <div className="rounded-md border border-input bg-background px-3 py-2 focus-within:ring-2 focus-within:ring-ring">
+        <DocEditor minimal editorRef={box} onChange={setDraft} onSubmit={post} mentions={findPeople} placeholder="Write a comment…" label="Comment" />
+      </div>
+      <div className="mt-2 flex items-center justify-between gap-3">
+        <KbdGroup keys={["⌘", "Enter"]} className="text-xs text-muted-foreground" />
+        <Button size="sm" variant="primary" disabled={!draft || isDocEmpty(draft)} onClick={() => post(box.current?.getDoc())}>
+          Post
+        </Button>
+      </div>
+    </Card>
+  );
+}
+
+const FIELDS = [
+  { key: "first_name", label: "First name" },
+  { key: "company", label: "Company" },
+  { key: "last_order", label: "Last order" },
+];
+const RECIPIENTS = [
+  { id: "r1", name: "Ana Souza", values: { first_name: "Ana", company: "Fernhill Bakery", last_order: "Sourdough starter kit" } },
+  { id: "r2", name: "Marcus Webb", values: { first_name: "Marcus", company: "Webb & Daughters", last_order: "" } },
+  { id: "r3", name: "Keiko Tan", values: { first_name: "Keiko", company: "", last_order: "Rye flour, 10 kg" } },
+];
+const field = (key) => ({ type: "field", props: { key, label: FIELDS.find((f) => f.key === key).label } });
+const EMAIL_BODY = [
+  { type: "paragraph", content: [t("Hi "), field("first_name"), t(",")] },
+  { type: "paragraph", content: [] },
+  { type: "paragraph", content: [t("Thanks for your last order ("), field("last_order"), t("). We've opened wholesale accounts for teams like "), field("company"), t(" — 12% off from the second bag.")] },
+  { type: "paragraph", content: [] },
+  { type: "paragraph", content: [t("Reply to this email and I'll set it up.")] },
+];
+
+function MergeDemo() {
+  const [body, setBody] = useState(EMAIL_BODY);
+  const [to, setTo] = useState(RECIPIENTS[0].id);
+  const recipient = RECIPIENTS.find((r) => r.id === to);
+  const used = docFields(body);
+  const missing = used.filter((f) => !recipient.values[f.key]);
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <Card title="Body" description="Type { or / to insert a field.">
+        <DocEditor value={body} onChange={setBody} fields={FIELDS} placeholder="Write the email…" label="Email body" />
+        <div className="mt-3 flex flex-wrap gap-1.5">
+          {used.map((f) => (
+            <Badge key={f.key}>
+              {f.label} ×{f.count}
+            </Badge>
+          ))}
+        </div>
+      </Card>
+      <Card title="Preview">
+        <Field id="merge-to" label="Recipient" className="mb-3">
+          <Select id="merge-to" value={to} onChange={(e) => setTo(e.target.value)} options={RECIPIENTS.map((r) => ({ value: r.id, label: r.name }))} />
+        </Field>
+        {missing.length ? (
+          <Notice tone="warning" className="mb-3">
+            {recipient.name} has no {missing.map((f) => f.label.toLowerCase()).join(" or ")}: the email would say {missing.map((f) => `{${f.key}}`).join(", ")}.
+          </Notice>
+        ) : null}
+        <p className="whitespace-pre-wrap break-words rounded-md border border-border bg-background p-3 text-sm">{docToText(body, { fields: recipient.values })}</p>
+      </Card>
+    </div>
+  );
+}
+
+export default function DocEditorDemo() {
+  const [tab, setTab] = useState("document");
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="DocEditor variants"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "document", label: "Document" },
+          { key: "comment", label: "Comment" },
+          { key: "merge", label: "Merge fields" },
+        ]}
+      />
+      <TabPanel tab="document" value={tab}>
+        <DocumentDemo />
+      </TabPanel>
+      <TabPanel tab="comment" value={tab}>
+        <CommentDemo />
+      </TabPanel>
+      <TabPanel tab="merge" value={tab}>
+        <MergeDemo />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/doc-editor/doc-editor.jsx

@@ -0,0 +1,291 @@
+"use client";
+
+// DocEditor — BlockNote, in the workspace theme, behind one set of props.
+//
+// Client only, one static bundle. BlockNote needs the DOM, and the app's
+// check refuses import() (so no next/dynamic): the modules load with the
+// page, and the editor itself is created only after the first effect
+// (the mount guard). Until then — on the server and in the first client
+// paint — a placeholder shows the doc's words in the same box, so the
+// server HTML already reads right and nothing jumps.
+import "@blocknote/shadcn/style.css";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { filterSuggestionItems } from "@blocknote/core/extensions";
+import { en } from "@blocknote/core/locales";
+import {
+  DragHandleMenu,
+  FormattingToolbar,
+  FormattingToolbarController,
+  RemoveBlockItem,
+  SideMenu,
+  SideMenuController,
+  SuggestionMenuController,
+  TableColumnHeaderItem,
+  TableRowHeaderItem,
+  getDefaultReactSlashMenuItems,
+  getFormattingToolbarItems,
+  useCreateBlockNote,
+} from "@blocknote/react";
+import { BlockNoteView } from "@blocknote/shadcn";
+import { Icon, cx } from "../../ui";
+import { SCHEMA } from "./schema";
+import { THEME } from "./theme";
+import { docToText, emptyDoc, isDocEmpty } from "./doc";
+
+/** A ref for the editor's handle: `const ed = useDocEditor()`, then
+ *  `<DocEditor editorRef={ed} />` and `ed.current?.insertField("first_name")`. */
+export function useDocEditor() {
+  return useRef(null);
+}
+
+const nonEmpty = (doc) => (Array.isArray(doc) && doc.length ? doc : null);
+
+// The box, the same in the placeholder and the live editor.
+const BOX = {
+  full: "min-h-40",
+  minimal: "min-h-10",
+};
+// `compact`: the full editor (menus, handles) in a short box, for a doc cut
+// into many small sections (brief-doc). A className cannot lower min-h-40:
+// cx joins classes without merging, and min-h-40 won (2026-09-24).
+const boxOf = (minimal, compact) => (minimal ? BOX.minimal : compact ? "min-h-16" : BOX.full);
+// BlockNote's editor element: its own padding off (54px each side, for the
+// drag handles), ours on. Full mode keeps room for the handles from 640px;
+// on a phone there is no hover, so no handles and no gutter.
+const EDITOR = {
+  full: "[&_.bn-editor]:px-0! [&_.bn-editor]:py-1! sm:[&_.bn-editor]:ps-12! text-base",
+  minimal: "[&_.bn-editor]:px-0! [&_.bn-editor]:py-0! text-sm",
+};
+
+export function DocEditor(props) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return <DocPlaceholder {...props} />;
+  return <LiveEditor {...props} />;
+}
+
+/** What the server renders (and the first client paint): the doc's words,
+ *  or the placeholder, in the editor's box. Not editable, not focusable. */
+function DocPlaceholder({ value, defaultValue, placeholder, minimal = false, compact = false, className }) {
+  const doc = nonEmpty(value) ?? nonEmpty(defaultValue);
+  const text = doc && !isDocEmpty(doc) ? docToText(doc) : "";
+  const mode = minimal ? "minimal" : "full";
+  return (
+    <div className={cx(boxOf(minimal, compact), className)} aria-busy="true">
+      <div className={cx(EDITOR[mode], !minimal && "sm:ps-12", "whitespace-pre-wrap", text ? "text-foreground" : "text-muted-foreground")}>
+        {text || placeholder || " "}
+      </div>
+    </div>
+  );
+}
+
+/** Keep the members of a group together, in first-seen order: BlockNote's
+ *  menu draws a group heading each time the group changes. */
+function grouped(items) {
+  const order = [];
+  const by = new Map();
+  for (const it of items) {
+    const g = it.group ?? "";
+    if (!by.has(g)) {
+      by.set(g, []);
+      order.push(g);
+    }
+    by.get(g).push(it);
+  }
+  return order.flatMap((g) => by.get(g));
+}
+
+const iconOf = (icon) => (typeof icon === "string" ? <Icon name={icon} size={18} /> : icon);
+
+/** The workspace's light or dark, read off <html> (the desk sets data-theme). */
+function schemeOf() {
+  const root = document.documentElement;
+  if (root.dataset.theme === "light" || root.dataset.theme === "dark") return root.dataset.theme;
+  const cs = getComputedStyle(root).colorScheme || "";
+  return /\blight\b/.test(cs) && !/\bdark\b/.test(cs) ? "light" : "dark";
+}
+
+function LiveEditor({
+  value,
+  defaultValue,
+  onChange,
+  editable = true,
+  placeholder,
+  slashItems,
+  mentions,
+  fields,
+  minimal = false,
+  compact = false,
+  autoFocus = false,
+  onSubmit,
+  onKeyDown,
+  uploadFile,
+  editorRef,
+  className,
+  label,
+}) {
+  const mode = minimal ? "minimal" : "full";
+  const initial = useRef(nonEmpty(value) ?? nonEmpty(defaultValue) ?? emptyDoc());
+  const dictionary = useMemo(
+    () => ({
+      ...en,
+      placeholders: {
+        ...en.placeholders,
+        emptyDocument: placeholder || undefined,
+        // "type '/' for commands" is a lie with no slash menu.
+        default: minimal ? undefined : en.placeholders.default,
+      },
+    }),
+    // The editor is created once; a new placeholder needs a new key.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+  const editor = useCreateBlockNote({ schema: SCHEMA, initialContent: initial.current, dictionary, uploadFile, trailingBlock: !minimal }, []);
+  const [scheme, setScheme] = useState("dark");
+  useEffect(() => {
+    setScheme(schemeOf());
+    const obs = new MutationObserver(() => setScheme(schemeOf()));
+    obs.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme", "class", "style"] });
+    return () => obs.disconnect();
+  }, []);
+
+  // Controlled: a `value` that is not what we last sent replaces the doc.
+  const last = useRef(JSON.stringify(initial.current));
+  const applying = useRef(false);
+  useEffect(() => {
+    if (value === undefined) return;
+    const next = nonEmpty(value) ?? emptyDoc();
+    const s = JSON.stringify(next);
+    if (s === last.current) return;
+    last.current = s;
+    applying.current = true;
+    try {
+      editor.replaceBlocks(editor.document, next);
+    } finally {
+      applying.current = false;
+    }
+  }, [value, editor]);
+
+  const emit = () => {
+    if (applying.current) return;
+    const doc = editor.document;
+    last.current = JSON.stringify(doc);
+    onChange?.(doc);
+  };
+
+  // The handle a block reaches through editorRef / useDocEditor().
+  const handle = useMemo(
+    () => ({
+      editor,
+      focus: () => editor.focus(),
+      getDoc: () => editor.document,
+      setDoc: (doc) => editor.replaceBlocks(editor.document, nonEmpty(doc) ?? emptyDoc()),
+      clear: () => editor.replaceBlocks(editor.document, emptyDoc()),
+      isEmpty: () => isDocEmpty(editor.document),
+      insertText: (text) => editor.insertInlineContent([String(text ?? "")]),
+      insertMention: ({ id, label: l }) => editor.insertInlineContent([{ type: "mention", props: { id: String(id), label: String(l ?? id) } }, " "]),
+      insertField: (key, l) => {
+        const f = (fields ?? []).find((x) => x.key === key);
+        editor.insertInlineContent([{ type: "field", props: { key, label: l ?? f?.label ?? key } }, " "]);
+      },
+    }),
+    [editor, fields],
+  );
+  useEffect(() => {
+    if (!editorRef) return;
+    editorRef.current = handle;
+    return () => {
+      if (editorRef.current === handle) editorRef.current = null;
+    };
+  }, [editorRef, handle]);
+
+  const fieldItems = (query, group) =>
+    filterSuggestionItems(
+      (fields ?? []).map((f) => ({
+        title: f.label ?? f.key,
+        subtext: `{${f.key}}`,
+        aliases: [f.key, "field", "merge"],
+        group,
+        icon: iconOf("tag"),
+        onItemClick: () => handle.insertField(f.key, f.label),
+      })),
+      query,
+    );
+
+  const getSlashItems = async (query) => {
+    const own = (slashItems ?? []).map((it) => ({
+      title: it.title,
+      subtext: it.subtext,
+      aliases: it.aliases,
+      group: it.group ?? "Other",
+      icon: iconOf(it.icon),
+      onItemClick: () => it.onSelect?.(handle),
+    }));
+    const all = grouped([...getDefaultReactSlashMenuItems(editor), ...own]);
+    return [...filterSuggestionItems(all, query), ...(fields?.length ? fieldItems(query, "Fields") : [])];
+  };
+
+  const getMentionItems = async (query) => {
+    let people = [];
+    try {
+      people = (await mentions(query)) ?? [];
+    } catch {
+      people = [];
+    }
+    return people.slice(0, 20).map((p) => ({
+      title: p.label ?? String(p.id),
+      subtext: p.description,
+      icon: iconOf("user"),
+      onItemClick: () => handle.insertMention({ id: p.id, label: p.label }),
+    }));
+  };
+
+  // Cmd/Ctrl+Enter submits, before BlockNote sees the Enter.
+  const keyDown = (e) => {
+    if (onSubmit && e.key === "Enter" && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+      e.preventDefault();
+      e.stopPropagation();
+      onSubmit(editor.document);
+      return;
+    }
+    onKeyDown?.(e);
+  };
+
+  return (
+    // raw: a plain box that hears keys on their way into BlockNote's
+    // contenteditable (capture), for Cmd/Ctrl+Enter; no control of its own.
+    <div className={cx(boxOf(minimal, compact), className)} onKeyDownCapture={keyDown}>
+      <BlockNoteView
+        editor={editor}
+        editable={editable}
+        autoFocus={autoFocus}
+        theme={scheme}
+        className={cx(THEME, EDITOR[mode])}
+        onChange={emit}
+        aria-label={label}
+        slashMenu={false}
+        sideMenu={false}
+        formattingToolbar={false}
+        emojiPicker={!minimal}
+      >
+        <FormattingToolbarController formattingToolbar={Toolbar} />
+        {!minimal && <SideMenuController sideMenu={Handles} />}
+        {!minimal && <SuggestionMenuController triggerCharacter="/" getItems={getSlashItems} />}
+        {mentions && <SuggestionMenuController triggerCharacter="@" getItems={getMentionItems} />}
+        {fields?.length ? <SuggestionMenuController triggerCharacter="{" getItems={async (q) => fieldItems(q)} /> : null}
+      </BlockNoteView>
+    </div>
+  );
+}
+
+// BlockNote's toolbar and block menu without their colour pickers: the
+// theme has no red or purple to offer (theme.js maps what is stored).
+const Toolbar = () => <FormattingToolbar>{getFormattingToolbarItems().filter((el) => el.key !== "colorStyleButton")}</FormattingToolbar>;
+const BlockMenu = () => (
+  <DragHandleMenu>
+    <RemoveBlockItem>{en.drag_handle.delete_menuitem}</RemoveBlockItem>
+    <TableRowHeaderItem>{en.drag_handle.header_row_menuitem}</TableRowHeaderItem>
+    <TableColumnHeaderItem>{en.drag_handle.header_column_menuitem}</TableColumnHeaderItem>
+  </DragHandleMenu>
+);
+const Handles = (props) => <SideMenu {...props} dragHandleMenu={BlockMenu} />;