@saena-io/create 0.1.0 → 0.2.0

package/template/base/src/components/ui/rich-text/toolbar.tsx

@@ -0,0 +1,668 @@
+import {
+  ArrowTurnBackwardIcon,
+  ArrowTurnForwardIcon,
+  CheckListIcon,
+  FileExportIcon,
+  FileImportIcon,
+  GridTableIcon,
+  Heading01Icon,
+  Heading02Icon,
+  Heading03Icon,
+  LeftToRightListBulletIcon,
+  LeftToRightListNumberIcon,
+  Link01Icon,
+  ListChevronsDownUpIcon,
+  MoreHorizontalIcon,
+  PlusSignIcon,
+  QuoteDownIcon,
+  SourceCodeIcon,
+  SourceCodeSquareIcon,
+  TextAlignCenterIcon,
+  TextAlignJustifyCenterIcon,
+  TextAlignLeftIcon,
+  TextAlignRightIcon,
+  TextBoldIcon,
+  TextIcon,
+  TextItalicIcon,
+  TextStrikethroughIcon,
+  TextUnderlineIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import type { Alignment } from '@platejs/basic-styles';
+import { flip, offset, useFloatingToolbar, useFloatingToolbarState } from '@platejs/floating';
+import { unwrapLink, upsertLink } from '@platejs/link';
+import { ListStyleType, someList, someTodoList, toggleList } from '@platejs/list';
+import { insertTable } from '@platejs/table';
+import { someToggle } from '@platejs/toggle';
+import { openNextToggles } from '@platejs/toggle/react';
+import { Button, buttonVariants } from '@saena-io/ui/components/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@saena-io/ui/components/dialog';
+import { DropdownMenuItem } from '@saena-io/ui/components/dropdown-menu';
+import { Input } from '@saena-io/ui/components/input';
+import { Popover, PopoverContent, PopoverTrigger } from '@saena-io/ui/components/popover';
+import {
+  Toolbar,
+  type ToolbarGroup,
+  ToolbarItems,
+  type ToolbarNode,
+} from '@saena-io/ui/components/toolbar';
+import { cn } from '@saena-io/ui/lib/utils';
+import { KEYS } from 'platejs';
+import { useEditorId, useEditorReadOnly, useEditorState, useEventEditorValue } from 'platejs/react';
+import { useRef, useState } from 'react';
+import type { RichTextExtension } from './extension';
+import { exportMenuItems, importMenuItems } from './import-export-toolbar';
+import type { RichTextEditor } from './plugins';
+import { tableMenuNode } from './table-toolbar';
+import { mergeExtensionItems } from './toolbar-slots';
+
+// The rich-text toolbar, expressed as DATA. Each control is a node (button / menu / custom) in a group;
+// the generic @saena-io/ui <Toolbar> renders them and folds whole groups into a single dropdown when the
+// container is narrow (mobile). A feature package contributes the same node shapes — so a media addon's
+// "video / image / file" buttons land in a group and miniaturise for free, no responsive code in the plugin.
+
+/**
+ * The focused editor, falling back to the last focused one. Opening a portal blurs the editor, so a control
+ * that writes on value-change must remember which pane (source / target) it drives. Kept null-safe because
+ * the toolbar lives in a dual-pane PlateController (no single concrete editor under it).
+ */
+export function useActiveEditor(): RichTextEditor | null {
+  const live = useEditorState() as RichTextEditor | null;
+  const ref = useRef<RichTextEditor | null>(null);
+  if (live) ref.current = live;
+  return live ?? ref.current;
+}
+
+/** Block types for the "turn into" menu and the heading entries of the insert menu. */
+const BLOCK_TYPES = [
+  { value: 'p', label: 'Text', icon: TextIcon },
+  { value: 'h1', label: 'Heading 1', icon: Heading01Icon },
+  { value: 'h2', label: 'Heading 2', icon: Heading02Icon },
+  { value: 'h3', label: 'Heading 3', icon: Heading03Icon },
+  { value: 'blockquote', label: 'Quote', icon: QuoteDownIcon },
+] as const;
+
+/** Bullet-list styles, each with a glyph matching the rendered marker. */
+const BULLET_STYLES = [
+  { value: ListStyleType.Disc, label: 'Default', shape: 'disc' },
+  { value: ListStyleType.Circle, label: 'Circle', shape: 'circle' },
+  { value: ListStyleType.Square, label: 'Square', shape: 'square' },
+] as const;
+
+/** Ordered-list styles. */
+const ORDERED_STYLES = [
+  { value: ListStyleType.Decimal, label: 'Decimal (1, 2, 3)' },
+  { value: ListStyleType.LowerAlpha, label: 'Lower Alpha (a, b, c)' },
+  { value: ListStyleType.UpperAlpha, label: 'Upper Alpha (A, B, C)' },
+  { value: ListStyleType.LowerRoman, label: 'Lower Roman (i, ii, iii)' },
+  { value: ListStyleType.UpperRoman, label: 'Upper Roman (I, II, III)' },
+] as const;
+
+/** Block alignment options. */
+const ALIGN_TYPES = [
+  { value: 'left', label: 'Align left', icon: TextAlignLeftIcon },
+  { value: 'center', label: 'Align center', icon: TextAlignCenterIcon },
+  { value: 'right', label: 'Align right', icon: TextAlignRightIcon },
+  { value: 'justify', label: 'Justify', icon: TextAlignJustifyCenterIcon },
+] as const;
+
+/** The little bullet glyph next to each bullet style — matches the rendered marker. */
+function BulletShape({ shape }: { shape: 'disc' | 'circle' | 'square' }) {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'size-2 shrink-0',
+        shape === 'disc' && 'rounded-full bg-current',
+        shape === 'circle' && 'rounded-full border-[1.5px] border-current',
+        shape === 'square' && 'bg-current',
+      )}
+    />
+  );
+}
+
+const newBlock = (type: string) => ({ type, children: [{ text: '' }] });
+
+/** Insert a new sibling block after the current one. */
+function insertSibling(editor: RichTextEditor, node: object) {
+  const path = editor.api.block()?.[1];
+  const at = path ? [...path.slice(0, -1), path[path.length - 1] + 1] : undefined;
+  editor.tf.insertNodes(node as Parameters<RichTextEditor['tf']['insertNodes']>[0], {
+    ...(at ? { at } : {}),
+    select: true,
+  });
+  editor.tf.focus();
+}
+
+function insertNewList(editor: RichTextEditor, style: ListStyleType) {
+  insertSibling(editor, newBlock('p'));
+  toggleList(editor, { listStyleType: style });
+  editor.tf.focus();
+}
+
+function insertTableBlock(editor: RichTextEditor) {
+  if (!editor.selection) {
+    const end = editor.api.end([]);
+    if (end) editor.tf.select(end);
+  }
+  insertTable(editor, { rowCount: 3, colCount: 3 }, { select: true });
+  editor.tf.focus();
+}
+
+// --- Link (custom node — a URL field). Expanded: a popover button. Collapsed: a submenu with the same
+//     form, so a text-input control still lives inside a folded group (your "custom UI in a group" case). ---
+
+function useLinkState(editor: RichTextEditor | null) {
+  const entry = editor?.api.node({ match: { type: 'a' } });
+  const isLink = Boolean(entry);
+  const currentUrl = (entry?.[0] as { url?: string } | undefined)?.url ?? '';
+  return { isLink, currentUrl };
+}
+
+function LinkForm({
+  editor,
+  isLink,
+  currentUrl,
+  onDone,
+}: {
+  editor: RichTextEditor | null;
+  isLink: boolean;
+  currentUrl: string;
+  onDone: () => void;
+}) {
+  const [url, setUrl] = useState(currentUrl);
+  const apply = () => {
+    const value = url.trim();
+    if (editor && value) upsertLink(editor, { url: value });
+    onDone();
+  };
+  const remove = () => {
+    if (editor) unwrapLink(editor);
+    onDone();
+  };
+  return (
+    <div className="flex flex-col gap-2">
+      <Input
+        autoFocus
+        value={url}
+        onChange={(e) => setUrl(e.target.value)}
+        placeholder="https://example.com"
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') apply();
+        }}
+      />
+      <div className="flex justify-end gap-2">
+        {isLink ? (
+          <Button variant="ghost" size="sm" onClick={remove}>
+            Remove
+          </Button>
+        ) : null}
+        <Button size="sm" onClick={apply} disabled={!url.trim()}>
+          {isLink ? 'Update' : 'Add'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function LinkPopover() {
+  const editor = useActiveEditor();
+  const [open, setOpen] = useState(false);
+  const { isLink, currentUrl } = useLinkState(editor);
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger
+        className={cn(buttonVariants({ variant: isLink ? 'secondary' : 'ghost', size: 'icon' }))}
+        aria-pressed={isLink}
+        title="Link"
+      >
+        <HugeiconsIcon icon={Link01Icon} strokeWidth={2} className="size-3.5" />
+      </PopoverTrigger>
+      <PopoverContent className="w-64" align="start">
+        <LinkForm
+          editor={editor}
+          isLink={isLink}
+          currentUrl={currentUrl}
+          onDone={() => setOpen(false)}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/** Collapsed form of the link control: a menu item that opens the link dialog. A menu can't host a text
+ *  field — its typeahead competes with typing — so the form opens as a separate modal surface instead. */
+function LinkMenuItem({ onSelect }: { onSelect?: () => void }) {
+  return (
+    <DropdownMenuItem onMouseDown={(e) => e.preventDefault()} onClick={() => onSelect?.()}>
+      <HugeiconsIcon icon={Link01Icon} strokeWidth={2} className="size-4" />
+      Link…
+    </DropdownMenuItem>
+  );
+}
+
+/** The link editor as a modal dialog — opened from the collapsed Format group's "Link…" entry. */
+function LinkDialog({
+  open,
+  onOpenChange,
+  editor,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  editor: RichTextEditor | null;
+}) {
+  const { isLink, currentUrl } = useLinkState(editor);
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-sm">
+        <DialogHeader>
+          <DialogTitle>{isLink ? 'Edit link' : 'Add link'}</DialogTitle>
+          <DialogDescription className="sr-only">
+            Enter a URL for the selected text.
+          </DialogDescription>
+        </DialogHeader>
+        <LinkForm
+          editor={editor}
+          isLink={isLink}
+          currentUrl={currentUrl}
+          onDone={() => onOpenChange(false)}
+        />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+// --- Group config: built from the active editor each render, so active states stay live. ---
+
+type PickFile = (accept: string, handler: (file: File) => void | Promise<void>) => void;
+
+/**
+ * The Format group (inline marks + link). Shared by the fixed toolbar and the floating selection toolbar,
+ * so the latter reads one group instead of building the whole toolbar config just to discard the rest.
+ */
+function buildFormatGroup(
+  editor: RichTextEditor | null,
+  ctx?: { openLink?: () => void },
+): ToolbarGroup {
+  const marks = (editor?.api?.marks?.() ?? {}) as Record<string, unknown>;
+  const mark = (id: string, label: string, icon: typeof TextBoldIcon): ToolbarNode => ({
+    kind: 'button',
+    id,
+    label,
+    icon,
+    active: Boolean(marks[id]),
+    onSelect: () => editor?.tf.toggleMark(id),
+  });
+  return {
+    // Text styling is also in the floating selection toolbar, so on small screens hide it here entirely
+    // (rather than fold it) — select text to get the marks. Stays expanded on desktop. (No `icon` since it
+    // never folds to a trigger.)
+    id: 'format',
+    label: 'Format',
+    hideBelow: 'md',
+    items: [
+      mark('bold', 'Bold', TextBoldIcon),
+      mark('italic', 'Italic', TextItalicIcon),
+      mark('underline', 'Underline', TextUnderlineIcon),
+      mark('strikethrough', 'Strikethrough', TextStrikethroughIcon),
+      mark('code', 'Inline code', SourceCodeIcon),
+      {
+        kind: 'custom',
+        id: 'link',
+        expanded: <LinkPopover />,
+        collapsed: <LinkMenuItem onSelect={ctx?.openLink} />,
+      },
+    ],
+  };
+}
+
+function buildGroups(
+  editor: RichTextEditor | null,
+  ctx?: { openLink?: () => void; pickFile?: PickFile },
+): ToolbarGroup[] {
+  const blockType = (editor?.api?.block?.()?.[0]?.type as string | undefined) ?? 'p';
+  const rawAlign = (editor?.api?.block?.()?.[0] as { align?: string } | undefined)?.align ?? 'left';
+  const align = rawAlign === 'start' ? 'left' : rawAlign === 'end' ? 'right' : rawAlign;
+
+  const turnInto: ToolbarNode = {
+    kind: 'menu',
+    id: 'turn-into',
+    label: 'Turn into',
+    valueLabel: BLOCK_TYPES.find((b) => b.value === blockType)?.label ?? 'Text',
+    icon: BLOCK_TYPES.find((b) => b.value === blockType)?.icon ?? TextIcon,
+    variant: 'labeled',
+    triggerClassName: 'w-32',
+    radio: true,
+    items: BLOCK_TYPES.map((b) => ({
+      kind: 'button',
+      id: b.value,
+      label: b.label,
+      icon: b.icon,
+      active: blockType === b.value,
+      onSelect: () => {
+        if (!editor) return;
+        if (b.value === 'blockquote') editor.tf.toggleBlock('blockquote', { wrap: true });
+        else editor.tf.toggleBlock(b.value);
+        editor.tf.focus();
+      },
+    })),
+  };
+
+  // Align is its own group of buttons (one per alignment) — expanded shows all four; it only folds into a
+  // dropdown on small screens. The collapsed-trigger icon reflects the current alignment.
+  const alignGroup: ToolbarGroup = {
+    id: 'align',
+    label: 'Align',
+    icon: ALIGN_TYPES.find((a) => a.value === align)?.icon ?? TextAlignLeftIcon,
+    collapse: 'md',
+    items: ALIGN_TYPES.map(
+      (a): ToolbarNode => ({
+        kind: 'button',
+        id: `align-${a.value}`,
+        label: a.label,
+        icon: a.icon,
+        active: align === a.value,
+        onSelect: () => {
+          editor?.tf.textAlign.setNodes(a.value as Alignment);
+          editor?.tf.focus();
+        },
+      }),
+    ),
+  };
+
+  const insertMenu: ToolbarNode = {
+    kind: 'menu',
+    id: 'insert',
+    label: 'Insert',
+    icon: PlusSignIcon,
+    variant: 'plain',
+    items: [
+      ...BLOCK_TYPES.filter((b) => b.value !== 'p').map(
+        (b): ToolbarNode => ({
+          kind: 'button',
+          id: `insert-${b.value}`,
+          label: b.label,
+          icon: b.icon,
+          onSelect: () => editor && insertSibling(editor, newBlock(b.value)),
+        }),
+      ),
+      {
+        kind: 'button',
+        id: 'insert-bulleted',
+        label: 'Bulleted list',
+        icon: LeftToRightListBulletIcon,
+        onSelect: () => editor && insertNewList(editor, ListStyleType.Disc),
+      },
+      {
+        kind: 'button',
+        id: 'insert-numbered',
+        label: 'Numbered list',
+        icon: LeftToRightListNumberIcon,
+        onSelect: () => editor && insertNewList(editor, ListStyleType.Decimal),
+      },
+      {
+        kind: 'button',
+        id: 'insert-code',
+        label: 'Code block',
+        icon: SourceCodeSquareIcon,
+        onSelect: () =>
+          editor &&
+          insertSibling(editor, {
+            type: 'code_block',
+            children: [{ type: 'code_line', children: [{ text: '' }] }],
+          }),
+      },
+      {
+        kind: 'button',
+        id: 'insert-table',
+        label: 'Table',
+        icon: GridTableIcon,
+        onSelect: () => editor && insertTableBlock(editor),
+      },
+    ],
+  };
+
+  const applyList = (
+    listStyleType: NonNullable<Parameters<typeof toggleList>[1]>['listStyleType'],
+  ) => {
+    if (!editor) return;
+    toggleList(editor, { listStyleType });
+    editor.tf.focus();
+  };
+
+  const bulletList: ToolbarNode = {
+    kind: 'menu',
+    id: 'bulleted-list',
+    label: 'Bulleted list',
+    icon: LeftToRightListBulletIcon,
+    variant: 'split',
+    active: editor ? BULLET_STYLES.some((b) => someList(editor, b.value)) : false,
+    onPrimary: () => applyList(ListStyleType.Disc),
+    radio: true,
+    items: BULLET_STYLES.map(
+      (b): ToolbarNode => ({
+        kind: 'button',
+        id: b.value,
+        label: b.label,
+        iconNode: <BulletShape shape={b.shape} />,
+        active: editor ? someList(editor, b.value) : false,
+        onSelect: () => applyList(b.value),
+      }),
+    ),
+  };
+
+  const numberedList: ToolbarNode = {
+    kind: 'menu',
+    id: 'numbered-list',
+    label: 'Numbered list',
+    icon: LeftToRightListNumberIcon,
+    variant: 'split',
+    active: editor ? ORDERED_STYLES.some((o) => someList(editor, o.value)) : false,
+    onPrimary: () => applyList(ListStyleType.Decimal),
+    radio: true,
+    items: ORDERED_STYLES.map(
+      (o): ToolbarNode => ({
+        kind: 'button',
+        id: o.value,
+        label: o.label,
+        active: editor ? someList(editor, o.value) : false,
+        onSelect: () => applyList(o.value),
+      }),
+    ),
+  };
+
+  const todo: ToolbarNode = {
+    kind: 'button',
+    id: 'todo-list',
+    label: 'To-do list',
+    icon: CheckListIcon,
+    active: editor ? someTodoList(editor) : false,
+    onSelect: () => applyList(KEYS.listTodo),
+  };
+
+  const toggleListNode: ToolbarNode = {
+    kind: 'button',
+    id: 'toggle-list',
+    label: 'Toggle list',
+    icon: ListChevronsDownUpIcon,
+    active: editor ? Boolean(someToggle(editor)) : false,
+    onSelect: () => {
+      if (!editor) return;
+      openNextToggles(editor);
+      editor.tf.toggleBlock(KEYS.toggle);
+      editor.tf.collapse();
+      editor.tf.focus();
+    },
+  };
+
+  const importMenu: ToolbarNode = {
+    kind: 'menu',
+    id: 'import',
+    label: 'Import',
+    icon: FileImportIcon,
+    variant: 'plain',
+    items: importMenuItems(editor, ctx?.pickFile ?? (() => undefined)).map(
+      (it): ToolbarNode => ({ kind: 'button', id: it.id, label: it.label, onSelect: it.run }),
+    ),
+  };
+  const exportMenu: ToolbarNode = {
+    kind: 'menu',
+    id: 'export',
+    label: 'Export',
+    icon: FileExportIcon,
+    variant: 'plain',
+    items: exportMenuItems(editor).map(
+      (it): ToolbarNode => ({ kind: 'button', id: it.id, label: it.label, onSelect: it.run }),
+    ),
+  };
+
+  // Undo / redo + Import / export — document-level actions, all the way at the left. Folds to a single
+  // "more" (3-dots) dropdown on smaller screens.
+  const documentGroup: ToolbarGroup = {
+    id: 'document',
+    label: 'Edit',
+    icon: MoreHorizontalIcon,
+    collapse: 'lg',
+    items: [
+      {
+        kind: 'button',
+        id: 'undo',
+        label: 'Undo',
+        icon: ArrowTurnBackwardIcon,
+        onSelect: () => editor?.undo(),
+      },
+      {
+        kind: 'button',
+        id: 'redo',
+        label: 'Redo',
+        icon: ArrowTurnForwardIcon,
+        onSelect: () => editor?.redo(),
+      },
+      importMenu,
+      exportMenu,
+    ],
+  };
+
+  return [
+    documentGroup,
+    {
+      // Insert + Turn-into never fold — kept as-is on every screen size (we have the room).
+      id: 'block',
+      label: 'Block',
+      icon: TextIcon,
+      collapse: 'never',
+      items: [insertMenu, turnInto],
+    },
+    buildFormatGroup(editor, ctx),
+    alignGroup,
+    {
+      id: 'lists',
+      label: 'Lists',
+      icon: LeftToRightListBulletIcon,
+      collapse: 'md',
+      items: [bulletList, numberedList, todo, toggleListNode],
+    },
+    {
+      id: 'objects',
+      label: 'Table',
+      icon: GridTableIcon,
+      collapse: 'never',
+      items: [tableMenuNode(editor)],
+    },
+  ];
+}
+
+/**
+ * The shared rich-text toolbar. Render once inside a <PlateController> above the editor pane(s). Built as a
+ * config and rendered by the generic <Toolbar>, which folds groups into dropdowns as the width shrinks.
+ * Extension-contributed controls (RichTextExtension.toolbar) merge into the group named by each item's
+ * `slot`, sorted by `order` — see mergeExtensionItems / extension.ts.
+ */
+export function RichTextToolbar({
+  className,
+  extensions = [],
+}: {
+  className?: string;
+  extensions?: RichTextExtension[];
+}) {
+  const editor = useActiveEditor();
+  const [linkOpen, setLinkOpen] = useState(false);
+  // One hidden file input drives every Import action, re-targeted (accept + handler) before each open.
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const onPick = useRef<(file: File) => void | Promise<void>>(() => undefined);
+  const pickFile: PickFile = (accept, handler) => {
+    onPick.current = handler;
+    const input = fileInputRef.current;
+    if (!input) return;
+    input.value = '';
+    input.accept = accept;
+    input.click();
+  };
+  const groups = buildGroups(editor, { openLink: () => setLinkOpen(true), pickFile });
+  mergeExtensionItems(groups, extensions);
+  return (
+    <>
+      <Toolbar groups={groups} className={className} />
+      <input
+        ref={fileInputRef}
+        type="file"
+        className="hidden"
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          if (file) void onPick.current(file);
+        }}
+      />
+      <LinkDialog open={linkOpen} onOpenChange={setLinkOpen} editor={editor} />
+    </>
+  );
+}
+
+/**
+ * A floating toolbar over a non-collapsed selection. Registered as a plugin's render.afterEditable (see
+ * rich-text-editor.tsx), so it mounts INSIDE each concrete editor — safe under the dual-pane controller. It
+ * reuses the Format group (marks + link), rendered without collapse and without the fixed-toolbar chrome.
+ */
+export function FloatingRichTextToolbar() {
+  const editorId = useEditorId();
+  const focusedEditorId = useEventEditorValue('focus');
+  const readOnly = useEditorReadOnly();
+  const editor = useActiveEditor();
+  const state = useFloatingToolbarState({
+    editorId,
+    focusedEditorId,
+    floatingOptions: {
+      placement: 'top',
+      middleware: [
+        offset(8),
+        flip({
+          fallbackPlacements: ['top-start', 'top-end', 'bottom-start', 'bottom-end'],
+          padding: 12,
+        }),
+      ],
+    },
+  });
+  const { clickOutsideRef, hidden, props, ref } = useFloatingToolbar(state);
+  if (readOnly || hidden) return null;
+  const formatGroup = buildFormatGroup(editor);
+  return (
+    <div ref={clickOutsideRef}>
+      <div
+        ref={ref}
+        {...props}
+        className={cn(
+          'absolute z-50 flex w-auto items-center rounded-md border bg-popover p-1 text-popover-foreground shadow-md print:hidden',
+        )}
+      >
+        {/* ToolbarItems (not <Toolbar>) — the latter sets an @container, which stops the bar sizing to its
+            content in this shrink-to-fit popover and broke the background. */}
+        <ToolbarItems items={formatGroup.items} />
+      </div>
+    </div>
+  );
+}

package/template/base/src/components/ui/rich-text/use-ai-chat.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { type UseChatHelpers, useChat as useBaseChat } from '@ai-sdk/react';
+import { AIChatPlugin } from '@platejs/ai/react';
+import { DefaultChatTransport, type UIMessage } from 'ai';
+import type { PlateEditor } from 'platejs/react';
+import * as React from 'react';
+
+// The editor's chat instance (ADR-0010). @platejs/ai's AIChatPlugin does NOT own an HTTP client — it borrows
+// an @ai-sdk/react `useChat` instance that we create and inject via editor.setOption(AIChatPlugin, 'chat').
+// The transport points at the SAENA streaming route (/api/ai/command by default), which returns an AI-SDK UI
+// Message Stream. Adapted from @platejs/ai's example, stripped of its faker mock + comment/table data-part
+// handling (SAENA's server emits plain text/reasoning parts only).
+
+export type ChatMessage = UIMessage;
+
+/** Create + own the editor's chat, inject it into AIChatPlugin, and keep it in sync. Call inside the
+ *  plugin's `useHooks` (which runs within the editor's React context). */
+export function useAiChat(editor: PlateEditor, api: string): UseChatHelpers<ChatMessage> {
+  const transport = React.useMemo(() => new DefaultChatTransport<ChatMessage>({ api }), [api]);
+  const chat = useBaseChat<ChatMessage>({ id: 'editor', transport });
+
+  // Depend on the chat's STABLE fields, NOT the `chat` object — useChat returns a fresh object every render,
+  // so `[chat]` would re-run this effect → setOption → re-render → loop ("Maximum update depth exceeded").
+  // status/messages/error only change on real chat events, which is exactly when the plugin needs the update.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally keyed on chat's stable fields.
+  React.useEffect(() => {
+    // The plugin's `chat` option is typed for its own ChatMessage (UIMessage + comment/table data parts);
+    // ours carries only text/reasoning parts, so the structural types don't line up. The runtime contract
+    // (sendMessage/regenerate/stop/setMessages/status/messages) matches — cast past the cosmetic mismatch.
+    editor.setOption(AIChatPlugin, 'chat', chat as never);
+  }, [editor, chat.status, chat.messages, chat.error]);
+
+  return chat;
+}