@saena-io/create 0.1.0 → 0.2.0

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

@@ -0,0 +1,187 @@
+import { GripVerticalIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { DndPlugin, useDraggable, useDropLine } from '@platejs/dnd';
+import { cn } from '@saena-io/ui/lib/utils';
+import { KEYS, isType } from 'platejs';
+import {
+  MemoizedChildren,
+  type PlateElementProps,
+  type RenderNodeWrapper,
+  useEditorRef,
+  useElement,
+} from 'platejs/react';
+import { type Ref, type RefObject, useEffect, useState } from 'react';
+
+// A per-block drag handle. Registered as DndPlugin's render.aboveNodes (see rich-text-editor.tsx), so it
+// wraps every top-level block (paragraphs, headings, quote, code, lists, table). Hovering a block reveals a
+// grip in the left gutter; dragging reorders the block and a drop line previews where it lands. The single
+// react-dnd backend is provided once at the root (RichTextDndProvider) so the two translation panes don't
+// double-mount it — hence we wire only render.aboveNodes here, not the example's per-editor aboveSlate.
+// Table rows keep their own in-table drag handle (table-node.tsx); this only adds the whole-block handle.
+
+const UNDRAGGABLE_TYPES = [KEYS.tr, KEYS.td, KEYS.column];
+
+export const BlockDraggable: RenderNodeWrapper = ({ editor, element, path }) => {
+  // Only top-level blocks get a handle; never table rows/cells/columns (they drag from inside the table).
+  if (editor.dom.readOnly) return;
+  if (path.length !== 1) return;
+  if (isType(editor, element, UNDRAGGABLE_TYPES)) return;
+  return (props) => <DraggableBlock {...props} />;
+};
+
+function DraggableBlock(props: PlateElementProps) {
+  const { children, element } = props;
+  const editor = useEditorRef();
+  const { isAboutToDrag, isDragging, nodeRef, previewRef, handleRef } = useDraggable({ element });
+  // Align the grip with the FIRST LINE of text: the wrapper's top sits above the text by the block's
+  // top margin (large for headings), so offset by margin-top and center the 24px grip on the line height.
+  const [handleTop, setHandleTop] = useState(0);
+
+  // The drag image is a CLONE placed in the dedicated `previewRef` element below (not the live content) —
+  // an in-flow content node snapshots the whole editor inside the fixed sheet. Reveal it just before the
+  // drag starts (so the browser captures a painted image) and clear it when the drag ends.
+  useEffect(() => {
+    if (isAboutToDrag) previewRef.current?.classList.remove('opacity-0');
+  }, [isAboutToDrag, previewRef]);
+  useEffect(() => {
+    if (!isDragging && previewRef.current) {
+      previewRef.current.replaceChildren();
+      previewRef.current.classList.add('hidden');
+    }
+  }, [isDragging, previewRef]);
+
+  return (
+    <div
+      // Named group (`/drag`) so the surrounding card's own `group` can't trigger the hover reveal — an
+      // unnamed `group-hover` would match any ancestor `.group`, showing every handle at once.
+      className={cn('group/drag relative', isDragging && 'opacity-50')}
+      onMouseEnter={() => {
+        if (isDragging) return;
+        const dom = editor.api.toDOMNode(element);
+        if (!dom) return;
+        const cs = getComputedStyle(dom);
+        const marginTop = Number.parseFloat(cs.marginTop) || 0;
+        const lineHeight = Number.parseFloat(cs.lineHeight);
+        const center = Number.isFinite(lineHeight) ? (lineHeight - 24) / 2 : 0;
+        setHandleTop(marginTop + center);
+      }}
+    >
+      {/* Left gutter — hidden until THIS block is hovered. */}
+      <div
+        className="-translate-x-full absolute left-0 flex select-none pr-1 opacity-0 transition-opacity group-hover/drag:opacity-100"
+        style={{ top: `${handleTop}px` }}
+        contentEditable={false}
+      >
+        <DragHandle dragRef={handleRef} previewRef={previewRef} />
+      </div>
+      {/* Dedicated drag-preview container — overlays the block (top:0) and stays hidden until a drag starts,
+          when DragHandle fills it with a clean clone of the block. Using an isolated, absolutely-positioned
+          element keeps the HTML5 drag image to just the block. */}
+      <div
+        ref={previewRef}
+        className="absolute top-0 left-0 hidden w-full"
+        contentEditable={false}
+      />
+      <div ref={nodeRef} className="flow-root">
+        <MemoizedChildren>{children}</MemoizedChildren>
+        <DropLine />
+      </div>
+    </div>
+  );
+}
+
+/** Strip Slate/DnD data attributes from a cloned subtree so the drag preview is plain, inert markup. */
+function stripSlateAttributes(el: HTMLElement) {
+  for (const attr of Array.from(el.attributes)) {
+    if (attr.name.startsWith('data-slate') || attr.name.startsWith('data-block-id')) {
+      el.removeAttribute(attr.name);
+    }
+  }
+  el.removeAttribute('contenteditable');
+  for (const child of Array.from(el.children)) {
+    stripSlateAttributes(child as HTMLElement);
+  }
+}
+
+// Make a cloned subtree safe to use as an HTML5 drag image. Chrome expands the drag-image snapshot to the
+// WHOLE VIEWPORT when the dragged element contains a `position: fixed` descendant (it's positioned against
+// the viewport, not the element) — this is why only the code block broke: its language picker (a Base-UI
+// Combobox) renders a hidden `position: fixed` input. We drop fixed descendants here; we also clip nested
+// scroll containers and strip transform/filter, which can corrupt drag images too. Runs after the clone is
+// in the DOM so getComputedStyle resolves.
+function neutralizeDragImageClipping(root: HTMLElement) {
+  const all = [root, ...Array.from(root.querySelectorAll<HTMLElement>('*'))];
+  for (const el of all) {
+    const cs = getComputedStyle(el);
+    if (cs.position === 'fixed') {
+      el.style.display = 'none';
+      continue;
+    }
+    if (/(auto|scroll)/.test(cs.overflowX) || /(auto|scroll)/.test(cs.overflowY)) {
+      el.style.overflow = 'hidden';
+    }
+    if (cs.transform !== 'none') el.style.transform = 'none';
+    if (cs.filter !== 'none') el.style.filter = 'none';
+  }
+}
+
+function DragHandle({
+  dragRef,
+  previewRef,
+}: {
+  dragRef: Ref<HTMLButtonElement>;
+  previewRef: RefObject<HTMLDivElement | null>;
+}) {
+  const editor = useEditorRef();
+  const element = useElement();
+  return (
+    <button
+      ref={dragRef}
+      type="button"
+      title="Drag to move"
+      aria-label="Drag to move"
+      className={cn(
+        'flex h-6 w-4 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground',
+        'cursor-grab active:cursor-grabbing',
+      )}
+      onClick={() => editor.tf.select(element)}
+      onMouseDown={() => {
+        // Build the drag image: a clean clone of this block in the dedicated preview element. Kept at
+        // opacity-0 (rendered, so the browser can paint it for setDragImage) until the drag actually begins.
+        const preview = previewRef.current;
+        if (!preview) return;
+        preview.replaceChildren();
+        const dom = editor.api.toDOMNode(element);
+        if (!dom) return;
+        const clone = dom.cloneNode(true) as HTMLElement;
+        stripSlateAttributes(clone);
+        const wrapper = document.createElement('div');
+        wrapper.style.display = 'flow-root';
+        wrapper.append(clone);
+        preview.append(wrapper);
+        // Clip scroll containers etc. now that the clone is in the DOM (see fn) so the drag image is the block.
+        neutralizeDragImageClipping(clone);
+        preview.classList.remove('hidden');
+        preview.classList.add('opacity-0');
+        editor.setOption(DndPlugin, 'multiplePreviewRef', previewRef);
+      }}
+      data-plate-prevent-deselect
+    >
+      <HugeiconsIcon icon={GripVerticalIcon} strokeWidth={2} className="size-4" />
+    </button>
+  );
+}
+
+function DropLine() {
+  const { dropLine } = useDropLine();
+  if (!dropLine) return null;
+  return (
+    <div
+      className={cn(
+        'absolute inset-x-0 z-50 h-0.5 bg-primary/60',
+        dropLine === 'top' ? '-top-px' : '-bottom-px',
+      )}
+      contentEditable={false}
+    />
+  );
+}

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

@@ -0,0 +1,17 @@
+import { cva } from 'class-variance-authority';
+
+// The block-selection overlay variant used by table cells/rows to show a selection tint. Ported from the
+// PlateJS example (bg-brand → bg-primary for the SAENA palette). The full BlockSelection render component
+// isn't needed here — the table renderers use this class directly via the selection hooks.
+export const blockSelectionVariants = cva(
+  'pointer-events-none absolute inset-0 z-1 bg-primary/10 transition-opacity',
+  {
+    defaultVariants: { active: true },
+    variants: {
+      active: {
+        false: 'opacity-0',
+        true: 'opacity-100',
+      },
+    },
+  },
+);

package/template/base/src/components/ui/rich-text/code-block-node.tsx

@@ -0,0 +1,204 @@
+import { Combobox as ComboboxPrimitive } from '@base-ui/react';
+import { Copy01Icon, Tick02Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { CodeBlockPlugin } from '@platejs/code-block/react';
+import { Button } from '@saena-io/ui/components/button';
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxTrigger,
+  ComboboxValue,
+} from '@saena-io/ui/components/combobox';
+import { cn } from '@saena-io/ui/lib/utils';
+import type { TElement } from 'platejs';
+import {
+  PlateElement,
+  type PlateElementProps,
+  PlateLeaf,
+  type PlateLeafProps,
+  useEditorRef,
+  useElement,
+  useReadOnly,
+} from 'platejs/react';
+import * as React from 'react';
+
+// Code block with an in-block language picker + syntax highlighting (mirrors the Plate example's flow).
+// The block stores its language on `element.lang`; the CodeBlockPlugin's `lowlight` instance decorates each
+// code_line with `code_syntax` leaves carrying highlight.js class names (see rich-text-editor.tsx). The
+// CodeSyntaxLeaf below applies those classes and globals.css (`.saena-hljs`) colors them per theme.
+
+type CodeBlockNode = TElement & { lang?: string };
+
+type LangItem = { value: string; label: string };
+
+// Friendly labels for the languages lowlight `common` registers; anything else falls back to a title-cased id.
+const LANG_LABELS: Record<string, string> = {
+  bash: 'Bash',
+  c: 'C',
+  cpp: 'C++',
+  csharp: 'C#',
+  css: 'CSS',
+  diff: 'Diff',
+  go: 'Go',
+  graphql: 'GraphQL',
+  ini: 'INI / TOML',
+  java: 'Java',
+  javascript: 'JavaScript',
+  json: 'JSON',
+  kotlin: 'Kotlin',
+  less: 'Less',
+  lua: 'Lua',
+  makefile: 'Makefile',
+  markdown: 'Markdown',
+  objectivec: 'Objective-C',
+  perl: 'Perl',
+  php: 'PHP',
+  'php-template': 'PHP Template',
+  python: 'Python',
+  'python-repl': 'Python REPL',
+  r: 'R',
+  ruby: 'Ruby',
+  rust: 'Rust',
+  scss: 'SCSS',
+  shell: 'Shell',
+  sql: 'SQL',
+  swift: 'Swift',
+  typescript: 'TypeScript',
+  vbnet: 'VB.NET',
+  wasm: 'WebAssembly',
+  xml: 'HTML / XML',
+  yaml: 'YAML',
+};
+
+function titleCase(id: string) {
+  return id.replace(/(^|[-_])(\w)/g, (_, sep, ch) => (sep ? ' ' : '') + ch.toUpperCase());
+}
+
+// `plaintext` / `auto` are pseudo-languages handled specially by the plugin's decorate (no highlight /
+// highlightAuto). highlight.js registers `plaintext` itself, so exclude the reserved ids from the grammar
+// list to avoid a duplicate option (and duplicate React key).
+const RESERVED_LANGS = new Set(['plaintext', 'auto']);
+
+function useLanguageItems(): LangItem[] {
+  const editor = useEditorRef();
+  return React.useMemo(() => {
+    const lowlight = editor.getOptions(CodeBlockPlugin).lowlight;
+    const langs = (lowlight ? [...lowlight.listLanguages()] : [])
+      .filter((id) => !RESERVED_LANGS.has(id))
+      .map((id) => ({ value: id, label: LANG_LABELS[id] ?? titleCase(id) }))
+      .sort((a, b) => a.label.localeCompare(b.label));
+    return [
+      { value: 'plaintext', label: 'Plain text' },
+      { value: 'auto', label: 'Auto' },
+      ...langs,
+    ];
+  }, [editor]);
+}
+
+function LanguageCombobox({ element }: { element: CodeBlockNode }) {
+  const editor = useEditorRef();
+  const items = useLanguageItems();
+  const current = element.lang || 'plaintext';
+  const selected = items.find((item) => item.value === current) ?? items[0];
+
+  const setLanguage = (lang: string) => {
+    const path = editor.api.findPath(element);
+    if (!path) return;
+    editor.tf.setNodes<CodeBlockNode>({ lang }, { at: path });
+  };
+
+  return (
+    <Combobox
+      items={items}
+      value={selected}
+      onValueChange={(item) => item && setLanguage((item as LangItem).value)}
+    >
+      <ComboboxTrigger
+        render={<Button variant="ghost" size="sm" />}
+        className="h-6 gap-1 px-2 font-mono text-muted-foreground text-xs hover:text-foreground"
+      >
+        <ComboboxValue>{(val: LangItem | null) => val?.label ?? 'Plain text'}</ComboboxValue>
+      </ComboboxTrigger>
+      <ComboboxContent align="end" className="w-56">
+        <div className="border-b p-1">
+          <ComboboxPrimitive.Input
+            placeholder="Search language…"
+            className="w-full rounded-sm bg-transparent px-2 py-1 text-xs outline-none placeholder:text-muted-foreground"
+          />
+        </div>
+        <ComboboxEmpty>No language found.</ComboboxEmpty>
+        <ComboboxList>
+          {(item: LangItem) => (
+            <ComboboxItem key={item.value} value={item}>
+              {item.label}
+            </ComboboxItem>
+          )}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+
+/** Copy the code block's text to the clipboard, with a brief check-mark confirmation. */
+function CopyButton({ element }: { element: CodeBlockNode }) {
+  const [copied, setCopied] = React.useState(false);
+  const copy = () => {
+    const lines = (element.children as Array<{ children?: Array<{ text?: string }> }>) ?? [];
+    const text = lines.map((l) => (l.children ?? []).map((c) => c.text ?? '').join('')).join('\n');
+    navigator.clipboard
+      ?.writeText(text)
+      .then(() => {
+        setCopied(true);
+        window.setTimeout(() => setCopied(false), 1500);
+      })
+      .catch(() => {});
+  };
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon-sm"
+      title={copied ? 'Copied' : 'Copy code'}
+      aria-label="Copy code"
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={copy}
+    >
+      <HugeiconsIcon icon={copied ? Tick02Icon : Copy01Icon} strokeWidth={2} className="size-3.5" />
+    </Button>
+  );
+}
+
+export function CodeBlockElement(props: PlateElementProps) {
+  const { children } = props;
+  const element = useElement<CodeBlockNode>();
+  const readOnly = useReadOnly();
+  return (
+    <PlateElement
+      {...props}
+      className="group/code relative my-4 overflow-hidden rounded-lg border bg-muted/40"
+    >
+      {!readOnly && (
+        <div
+          className="absolute top-1 right-1 z-10 flex items-center gap-0.5 opacity-70 transition-opacity focus-within:opacity-100 group-hover/code:opacity-100"
+          contentEditable={false}
+        >
+          <LanguageCombobox element={element} />
+          <CopyButton element={element} />
+        </div>
+      )}
+      <pre className="overflow-x-auto px-4 py-3 font-mono text-[13px] leading-relaxed [tab-size:2]">
+        <code className="saena-hljs">{children}</code>
+      </pre>
+    </PlateElement>
+  );
+}
+
+// Each highlighted token arrives as a `code_syntax` decoration carrying a `className` (highlight.js scopes
+// like `hljs-keyword`); applying it here is what makes the colors in globals.css `.saena-hljs` take effect.
+export function CodeSyntaxLeaf(props: PlateLeafProps) {
+  const className = (props.leaf as { className?: string }).className;
+  return <PlateLeaf {...props} className={cn(className)} />;
+}

package/template/base/src/components/ui/rich-text/codec.ts

@@ -0,0 +1,63 @@
+import type { Value } from 'platejs';
+
+// The on-the-wire storage codec for a `rich` field (ADR-0005 §5: one serialized Slate-JSON document per
+// value). A leaf module — only the `Value` type from platejs, no editor — so BOTH the editor and the
+// editor-free static renderer (public site) can parse/serialize a stored value without pulling the editor
+// into the bundle. Every consumer (translations page, CMS, future plugins) agrees on this single shape.
+// Keep parse + serialize symmetric: serializeRichText(parseRichText(s)) round-trips a well-formed value.
+
+/** An empty document (one paragraph) — the value a fresh rich field starts from. */
+export const emptyRichValue: Value = [{ type: 'p', children: [{ text: '' }] }];
+
+/**
+ * Parse a stored rich value (serialized Slate JSON) back into a `Value`. Empty/whitespace input and a
+ * non-array / empty parse both normalise to {@link emptyRichValue}.
+ *
+ * `plainTextFallback` (default false) controls the catch path for input that isn't valid JSON: when true,
+ * the raw string is wrapped in a single paragraph (i18n's history of storing translations as raw strings);
+ * a brand-new `rich` field with no plain-text rows should leave it off so malformed JSON surfaces.
+ */
+export function parseRichText(
+  text: string | undefined,
+  opts?: { plainTextFallback?: boolean },
+): Value {
+  if (!text) return emptyRichValue;
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) && parsed.length > 0 ? (parsed as Value) : emptyRichValue;
+  } catch {
+    return opts?.plainTextFallback ? [{ type: 'p', children: [{ text }] }] : emptyRichValue;
+  }
+}
+
+/** Serialize a rich `Value` to its stored string form. */
+export function serializeRichText(value: Value): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * Structural deep-equality of two Slate node trees, ignoring object-key order. The save dirty-check, instead
+ * of comparing JSON.stringify output (key-order-sensitive → spurious dirties → needless re-staling). Compares
+ * values not text, so it can only report fewer (never spurious) differences.
+ */
+function richValueEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => richValueEqual(v, b[i]));
+  }
+  const ak = Object.keys(a as object);
+  const bk = Object.keys(b as object);
+  if (ak.length !== bk.length) return false;
+  return ak.every(
+    (k) =>
+      Object.hasOwn(b as object, k) &&
+      richValueEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),
+  );
+}
+
+/** Whether `current` differs from `initial` — the save dirty-check for a rich field. */
+export function richValueIsDirty(current: Value, initial: Value): boolean {
+  return !richValueEqual(current, initial);
+}

package/template/base/src/components/ui/rich-text/extension.ts

@@ -0,0 +1,53 @@
+import type { AnyPlatePlugin } from 'platejs/react';
+import type { ReactNode } from 'react';
+
+// The rich-text ADDON seam (§9, ADR-0005). The editor ships a core capability set; feature packages
+// extend it with their own Plate plugins + toolbar controls (media, text styles, AI copilot, …). An
+// addon is authored against @saena-io/ui ONLY — the Plate surface it needs (`AnyPlatePlugin`) is
+// re-exported from the rich-text barrel — so it never imports `platejs` directly and the plugin
+// dependency boundary holds (plugins may import @saena-io/plugin-sdk + @saena-io/ui only; ARCHITECTURE §13).
+
+/**
+ * Where an extension's toolbar control is placed. A slot names a toolbar group: contributed items are
+ * appended to that group (after its built-in controls, so those keep their positions) and sorted by
+ * `order`. `document | block | format | lists | objects` are the editor's existing groups; `ai` and `end`
+ * have no core group, so items there form their own trailing group ("AI" / "More"). Placement is by id, so
+ * an addon's button lands predictably regardless of load order, and adding a slot later never reshuffles
+ * existing controls.
+ */
+export type ToolbarSlot = 'document' | 'block' | 'format' | 'lists' | 'objects' | 'ai' | 'end';
+
+/** One toolbar control, contributed by an extension. */
+export interface ToolbarItem {
+  /** Stable id — React key + de-dupe. */
+  id: string;
+  /** Which group it renders into (see {@link ToolbarSlot}). */
+  slot: ToolbarSlot;
+  /** Sort order within the slot; lower renders first. Leave gaps (10, 20, …) so addons can interleave. */
+  order: number;
+  /** Renders the control (its expanded form). Reads the focused editor via Plate hooks, like the core
+   *  controls. When its group folds on a narrow screen the same node is shown inside the dropdown, so keep
+   *  it click-only (a button / popover trigger), not an inline text field. */
+  render: () => ReactNode;
+}
+
+/**
+ * A rich-text addon — the EDITOR half of a feature package. It contributes Plate plugins and toolbar
+ * controls; the host composes a list of extensions into an editor instance (see `useRichTextEditor` /
+ * `RichTextToolbar`).
+ *
+ * Server-backed capabilities (an AI completion fn, an asset uploader) are closed over when the host
+ * CONSTRUCTS the extension — e.g. `createAiCopilotExtension({ complete })` returns a `RichTextExtension`
+ * with its Plate plugin already wired to the injected fn — so those dependencies never flow through
+ * @saena-io/ui. The matching SERVER half (the completion/upload endpoint) is a separate
+ * `@saena-io/plugin-sdk` Plugin. (Static renderers for the public-site bundle attach here when that path
+ * lands — ADR-0005.)
+ */
+export interface RichTextExtension {
+  /** Namespaced id, e.g. 'media' | 'text-style' | 'ai'. */
+  id: string;
+  /** Plate plugins appended to the core editor set. */
+  platePlugins?: AnyPlatePlugin[];
+  /** Toolbar controls placed into slots. */
+  toolbar?: ToolbarItem[];
+}

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

@@ -0,0 +1,23 @@
+import { CopilotPlugin } from '@platejs/ai/react';
+import { useEditorPlugin, usePluginOption } from 'platejs/react';
+
+// Ghost-text renderer for the AI copilot (ADR-0010). Shows the current block's pending AI suggestion inline
+// (muted, non-editable); Tab accepts, Esc rejects (wired by CopilotPlugin's shortcuts). Vendored here — Plate
+// ships this as a registry component the consumer owns, so it lives in @saena-io/ui beside the editor.
+export function GhostText() {
+  const { editor } = useEditorPlugin(CopilotPlugin);
+  const blockId = (editor.api.block({ highest: true })?.[0] as { id?: string } | undefined)?.id;
+  const isSuggested = usePluginOption(CopilotPlugin, 'isSuggested', blockId as string);
+  if (!isSuggested) return null;
+  return <GhostTextContent />;
+}
+
+function GhostTextContent() {
+  const suggestionText = usePluginOption(CopilotPlugin, 'suggestionText');
+  if (!suggestionText) return null;
+  return (
+    <span className="text-muted-foreground/70 max-sm:hidden" contentEditable={false}>
+      {suggestionText}
+    </span>
+  );
+}

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

@@ -0,0 +1,103 @@
+import { MarkdownPlugin } from '@platejs/markdown';
+import { getEditorDOMFromHtmlString, stripSlateDataAttributes } from 'platejs/static';
+import type { RichTextEditor } from './plugins';
+
+// Document import / export ACTIONS (Markdown, HTML, Word). Exposed as item builders so the toolbar can
+// drop them into a group that miniaturises — import reads a file via a host-provided picker (one hidden
+// input lives in the toolbar), export serializes the focused pane and downloads. Markdown round-trips
+// through MarkdownPlugin (GFM); HTML via editor.api.html + a clean-up of the rendered DOM; Word via docx-io.
+//
+// `@platejs/docx-io` is imported DYNAMICALLY inside the two Word handlers, never at module scope: it pulls
+// the CJS `virtual-dom` package, which Vite's ESM SSR can't resolve (throws "Cannot find module
+// virtual-dom/vnode/vnode"). A top-level import would drag that into the SSR module graph and crash any
+// server-rendered route that mounts the editor — even when Word import/export is never used. Deferring it
+// to the click keeps the editor's load graph SSR-safe (and trims it from the initial client bundle).
+
+function download(href: string, filename: string) {
+  const link = document.createElement('a');
+  link.href = href;
+  link.download = filename;
+  document.body.append(link);
+  link.click();
+  link.remove();
+}
+
+function textHref(mime: string, text: string) {
+  return `data:${mime};charset=utf-8,${encodeURIComponent(text)}`;
+}
+
+type AnyNodes = Parameters<RichTextEditor['tf']['insertNodes']>[0];
+
+/** One import/export menu entry. */
+export interface DocItem {
+  id: string;
+  label: string;
+  run: () => void;
+}
+
+/** Import entries — each opens the host's file picker with the right `accept` + parse handler. */
+export function importMenuItems(
+  editor: RichTextEditor | null,
+  pick: (accept: string, handler: (file: File) => void | Promise<void>) => void,
+): DocItem[] {
+  const importHtml = async (file: File) => {
+    if (!editor) return;
+    const element = getEditorDOMFromHtmlString(await file.text());
+    editor.tf.insertNodes(editor.api.html.deserialize({ element }) as AnyNodes);
+  };
+  const importMarkdown = async (file: File) => {
+    if (!editor) return;
+    editor.tf.insertNodes(
+      editor.getApi(MarkdownPlugin).markdown.deserialize(await file.text()) as AnyNodes,
+    );
+  };
+  const importWord = async (file: File) => {
+    if (!editor) return;
+    const { importDocx } = await import('@platejs/docx-io');
+    const result = await importDocx(editor, await file.arrayBuffer());
+    editor.tf.insertNodes(result.nodes as AnyNodes);
+  };
+  return [
+    {
+      id: 'import-html',
+      label: 'Import from HTML',
+      run: () => pick('text/html,.html', importHtml),
+    },
+    {
+      id: 'import-markdown',
+      label: 'Import from Markdown',
+      run: () => pick('.md,.mdx,text/markdown', importMarkdown),
+    },
+    { id: 'import-word', label: 'Import from Word', run: () => pick('.docx', importWord) },
+  ];
+}
+
+/** Export entries — serialize the focused pane and download. */
+export function exportMenuItems(editor: RichTextEditor | null): DocItem[] {
+  const exportMarkdown = () => {
+    if (!editor) return;
+    const md = editor.getApi(MarkdownPlugin).markdown.serialize();
+    download(textHref('text/markdown', md), 'translation.md');
+  };
+  const exportHtml = () => {
+    if (!editor) return;
+    // Serialize the rendered editor DOM and strip Slate's internal attributes, for clean semantic HTML.
+    const dom = editor.api.toDOMNode(editor);
+    const body = stripSlateDataAttributes(dom?.innerHTML ?? '');
+    const html = `<!DOCTYPE html>\n<html>\n<head><meta charset="utf-8" /></head>\n<body>\n${body}\n</body>\n</html>`;
+    download(textHref('text/html', html), 'translation.html');
+  };
+  const exportWord = async () => {
+    if (!editor) return;
+    const { exportToDocx } = await import('@platejs/docx-io');
+    const blob = await exportToDocx(editor.children);
+    const url = URL.createObjectURL(blob);
+    download(url, 'translation.docx');
+    URL.revokeObjectURL(url);
+  };
+  return [
+    { id: 'export-markdown', label: 'Export as Markdown', run: exportMarkdown },
+    { id: 'export-html', label: 'Export as HTML', run: exportHtml },
+    { id: 'export-word', label: 'Export as Word', run: () => void exportWord() },
+  ];
+}

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

@@ -0,0 +1,18 @@
+import { getLinkAttributes } from '@platejs/link';
+import type { TLinkElement } from 'platejs';
+import { PlateElement, type PlateElementProps } from 'platejs/react';
+
+// Inline link node renderer. The URL lives on the node (element.url) and round-trips through the stored
+// Slate JSON. We spread getLinkAttributes(editor, element) so the editor <a> carries a real, sanitized
+// href/target (cmd/middle-click, copy-link, hover-preview all work). Add/edit/remove is driven from the
+// toolbar's Link popover (upsertLink / unwrapLink).
+export function LinkElement(props: PlateElementProps<TLinkElement>) {
+  return (
+    <PlateElement
+      {...props}
+      as="a"
+      className="cursor-pointer font-medium text-primary underline underline-offset-2"
+      attributes={{ ...props.attributes, ...getLinkAttributes(props.editor, props.element) }}
+    />
+  );
+}