@inkbrick/react 0.0.0-stage → 0.1.0-alpha.0

package/src/context/EditorProvider.tsx

@@ -0,0 +1,172 @@
+import { useLayoutEffect, useMemo, type ReactNode } from 'react';
+
+import type { Editor } from '@inkbrick/engine';
+
+import { EditorView } from '../editing/EditorView';
+import { highlightCode } from '../code/highlight';
+import type { CodeHighlighter } from '../code/types';
+import { createTranslator, resolveMessages } from '../i18n/translate';
+import { temmlRenderer, type FormulaRenderer } from '../math/renderer';
+import type { PartialMessages } from '../i18n/en';
+import { resolveKeymap } from '../keymap/keymap';
+import type { KeyBinding } from '../keymap/types';
+import { resolveSlashItems } from '../slash/defaultSlashItems';
+import type { ImageOptions } from '../images/types';
+import type { SlashMenuItem } from '../slash/types';
+import { EditorUIContext } from '../ui/EditorUIContext';
+import type { EditorPresentation } from '../ui/presentation';
+import type { BlockComponentRegistry, EditorSlots } from '../ui/types';
+import { EditorContext, EditorViewContext } from './EditorContext';
+import { blockComponentsOf, type ReactBlockDefinition } from '../blocks/defineBlock';
+import { controllerKeymap, controllerSlashItems, mergeById } from '../controllers/adapters';
+
+export interface EditorProviderProps {
+  readonly editor: Editor;
+  readonly children: ReactNode;
+  /**
+   * Визуальный слой одним объектом (дизайн-система): представления блоков, оболочка, slash-меню, подсветка кода
+   * и формулы — см. `definePresentation`. Отдельные props ниже уточняют его. Держите объект стабильным.
+   */
+  readonly presentation?: EditorPresentation;
+  /**
+   * Пользовательские блоки из `defineBlock`: их компоненты добавляются к `components` (prop `components`
+   * с тем же flavour важнее). Схемы и контроллеры этих блоков передайте и в `new Editor({ blocks })`:
+   * пункты slash-меню, меню блока и клавиши берутся из контроллеров редактора. Держите массив стабильным.
+   */
+  readonly blocks?: readonly ReactBlockDefinition<any>[];
+  /**
+   * Свои React-представления блоков: `{ 'block:paragraph': MyParagraph }`.
+   * Не указанные flavour используют стандартные компоненты Inkbrick.
+   * Чтобы не перерисовывать документ без необходимости, держите объект стабильным
+   * (вынесите из компонента или оберните в useMemo).
+   */
+  readonly components?: BlockComponentRegistry;
+  readonly slots?: EditorSlots;
+  /**
+   * Пункты slash-меню. Дополняют стандартные (одинаковый `id` заменяет стандартный пункт);
+   * `false` выключает меню. Держите массив стабильным (вынесите из компонента или useMemo).
+   */
+  readonly slashItems?: readonly SlashMenuItem[] | false;
+  /**
+   * Подсветка синтаксиса в блоках кода. По умолчанию — встроенный `highlightCode` (без зависимостей);
+   * свой подсветчик (Shiki, Prism, highlight.js) — функция `(code, language) => токены`; `false` выключает подсветку.
+   * Держите функцию стабильной: смена функции перерисовывает все блоки кода.
+   */
+  readonly highlighter?: CodeHighlighter | false;
+  /**
+   * Отрисовка формул (блоки и встроенные): по умолчанию Temml → MathML, подгружается при первой формуле.
+   * Свой подсчётчик (KaTeX, MathJax) — функция `(latex, target, { display }) => void | Promise<void>`;
+   * `false` — показывать только исходный код. Держите функцию стабильной: её смена перерисовывает все формулы.
+   */
+  readonly formulaRenderer?: FormulaRenderer | false;
+  /**
+   * Язык интерфейса: код подключённого словаря (`'en'`, `'ru'` или свой, см. `registerLocale` и `locales`).
+   * `'pt-BR'` без своего словаря возьмёт `'pt'`; неизвестный код — английский. По умолчанию `'en'`.
+   */
+  readonly locale?: string;
+  /**
+   * Словари, подключаемые только к этому редактору: `{ de: { 'menu.delete': 'Löschen', … } }`.
+   * Словарь может быть неполным — недостающее берётся из английского. Держите объект стабильным.
+   */
+  readonly locales?: Readonly<Record<string, PartialMessages>>;
+  /** Точечные замены строк поверх выбранного языка: `{ 'menu.delete': 'Убрать' }`. Держите объект стабильным. */
+  readonly messages?: PartialMessages;
+  /**
+   * Свои привязки клавиш. Привязка с `id` стандартной (`'undo'`, `'format.bold'`, `'indent'`, …) заменяет её,
+   * новая проверяется раньше стандартных; `unbind('id')` отключает стандартную. Держите массив стабильным.
+   */
+  readonly keymap?: readonly KeyBinding[];
+  /**
+   * Режим только чтения: ввод, команды, undo, toolbar, ручки блоков и slash-меню отключены,
+   * выделение и копирование работают. Применяется к редактору (`editor.setReadOnly`), поэтому
+   * защищает документ и от вызовов из кода.
+   */
+  readonly readOnly?: boolean;
+  /**
+   * Изображения: `upload` — куда сохранять файлы (иначе картинки встраиваются в документ как data:-адреса
+   * до `maxInlineBytes`), `acceptedTypes`, `onError`. Держите объект стабильным.
+   */
+  readonly images?: ImageOptions;
+}
+
+export function EditorProvider({
+  editor,
+  children,
+  presentation,
+  blocks,
+  components,
+  slots,
+  slashItems,
+  keymap,
+  highlighter,
+  formulaRenderer,
+  locale,
+  locales,
+  messages,
+  readOnly,
+  images,
+}: EditorProviderProps) {
+  const view = useMemo(() => new EditorView(), [editor]);
+
+  useLayoutEffect(() => {
+    if (readOnly === undefined) return;
+
+    const previous = editor.readOnly;
+
+    editor.setReadOnly(readOnly);
+
+    return () => editor.setReadOnly(previous);
+  }, [editor, readOnly]);
+
+  const t = useMemo(
+    () => createTranslator(resolveMessages({ locale, locales, messages })),
+    [locale, locales, messages],
+  );
+
+  const ui = useMemo(() => {
+    const visual = presentation ?? {};
+    const code = highlighter ?? visual.highlighter;
+    const math = formulaRenderer ?? visual.formulaRenderer;
+    const customSlash = slashItems ?? visual.slashItems;
+    const customKeys = keymap ?? [];
+
+    return {
+      components: { ...blockComponentsOf(blocks), ...visual.components, ...components },
+      slots: { ...visual.slots, ...slots },
+      // Пункты контроллеров идут после стандартных; пункт приложения с тем же id важнее.
+      slashItems:
+        customSlash === false
+          ? []
+          : resolveSlashItems(mergeById(controllerSlashItems(editor), customSlash ?? []), t),
+      highlighter: code === false ? null : (code ?? highlightCode),
+      formulaRenderer: math === false ? null : (math ?? temmlRenderer),
+      locale: locale ?? 'en',
+      t,
+      keymap: resolveKeymap(mergeById(controllerKeymap(editor), customKeys, 'preferred-first')),
+      images: images ?? {},
+      readOnly,
+    };
+  }, [
+    editor,
+    presentation,
+    blocks,
+    components,
+    slots,
+    slashItems,
+    keymap,
+    highlighter,
+    formulaRenderer,
+    locale,
+    t,
+    readOnly,
+    images,
+  ]);
+
+  return (
+    <EditorContext.Provider value={editor}>
+      <EditorViewContext.Provider value={view}>
+        <EditorUIContext.Provider value={ui}>{children}</EditorUIContext.Provider>
+      </EditorViewContext.Provider>
+    </EditorContext.Provider>
+  );
+}

package/src/controllers/adapters.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+
+import type { Editor } from '@inkbrick/engine';
+
+import { Icon } from '../icons/Icon';
+import { ICON_SHAPES, type IconName } from '../icons/lucide';
+import type { KeyBinding, KeymapContext } from '../keymap/types';
+import type { SlashMenuItem } from '../slash/types';
+
+export function iconByName(name: string | undefined): ReactNode {
+  return name && Object.hasOwn(ICON_SHAPES, name) ? <Icon name={name as IconName} /> : undefined;
+}
+
+export function controllerSlashItems(editor: Editor): SlashMenuItem[] {
+  return editor.controllers.entries().flatMap(([flavour, controller]) =>
+    (controller.slashItems ?? []).map<SlashMenuItem>((item) => ({
+      id: item.id,
+      title: item.title,
+      description: item.description,
+      keywords: item.keywords,
+      icon: iconByName(item.icon),
+      flavour,
+      props: item.props,
+    })),
+  );
+}
+
+function controlledBlockAt(context: KeymapContext, flavour: string) {
+  const selection = context.selection();
+  const block = selection && context.editor.store.getBlock(selection.from.blockId);
+
+  return block?.flavour === flavour ? block : undefined;
+}
+
+export function controllerKeymap(editor: Editor): KeyBinding[] {
+  return editor.controllers.entries().flatMap(([flavour, controller]) =>
+    (controller.keymap ?? []).map<KeyBinding>((binding) => ({
+      id: binding.id,
+      keys: binding.keys,
+      when: (context) => controlledBlockAt(context, flavour) !== undefined,
+      run: (context) => {
+        const block = controlledBlockAt(context, flavour);
+
+        return block ? binding.run(context.editor.controllers.contextOf(block)) : false;
+      },
+    })),
+  );
+}
+
+/**
+ * Объединяет пункты по id: пункт из `preferred` заменяет одноимённый из `base`.
+ * Порядок: сначала `base`, затем `preferred` (или наоборот — `'preferred-first'`, для клавиш: проверяются раньше).
+ */
+export function mergeById<T extends { readonly id: string }>(
+  base: readonly T[],
+  preferred: readonly T[],
+  order: 'base-first' | 'preferred-first' = 'base-first',
+): T[] {
+  const ids = new Set(preferred.map((item) => item.id));
+  const rest = base.filter((item) => !ids.has(item.id));
+
+  return order === 'base-first' ? [...rest, ...preferred] : [...preferred, ...rest];
+}

package/src/editing/BlockSelectionController.ts

@@ -0,0 +1,27 @@
+/**
+ * Какие блоки сейчас затронуты непустым выделением. Подписка идёт на уровне отдельного блока:
+ * при смене выделения перерисовываются только те блоки, у которых флаг `selected` изменился.
+ */
+export class BlockSelectionController {
+  private selected: ReadonlySet<string> = new Set();
+
+  private readonly listeners = new Set<() => void>();
+
+  isSelected = (blockId: string): boolean => this.selected.has(blockId);
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  set(ids: readonly string[]): void {
+    if (ids.length === this.selected.size && ids.every((id) => this.selected.has(id))) return;
+
+    this.selected = new Set(ids);
+
+    for (const listener of [...this.listeners]) listener();
+  }
+}

package/src/editing/CaretController.ts

@@ -0,0 +1,27 @@
+/**
+ * В каком блоке сейчас стоит каретка (выделение свёрнуто). Подписка идёт на уровне блока: при переносе каретки
+ * перерисовываются только два блока — тот, который она покинула, и тот, куда попала.
+ */
+export class CaretController {
+  private blockId: string | null = null;
+
+  private readonly listeners = new Set<() => void>();
+
+  has = (blockId: string): boolean => this.blockId === blockId;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  set(blockId: string | null): void {
+    if (this.blockId === blockId) return;
+
+    this.blockId = blockId;
+
+    for (const listener of [...this.listeners]) listener();
+  }
+}

package/src/editing/EditorView.ts

@@ -0,0 +1,108 @@
+import type { BlockId } from '@inkbrick/document';
+
+import { BlockHandleController } from '../block-handle/BlockHandleController';
+import { UploadTracker } from '../images/UploadTracker';
+import { BlockSelectionController } from './BlockSelectionController';
+import { FormulaController } from '../formula/FormulaController';
+import { CaretController } from './CaretController';
+import { SlashMenuController } from '../slash/SlashMenuController';
+import { ToolbarController } from '../toolbar/ToolbarController';
+import { ViewportController } from './ViewportController';
+import { setDomSelection, type DocPoint } from './selection';
+
+/**
+ * Связь модели с DOM: корневой редактируемый элемент и элементы текстовых блоков.
+ * Нужна, чтобы после изменения модели вернуть курсор/выделение на место.
+ */
+export class EditorView {
+  private readonly elements = new Map<BlockId, HTMLElement>();
+
+  private root: HTMLElement | null = null;
+
+  readonly slash = new SlashMenuController();
+
+  readonly uploads = new UploadTracker();
+
+  readonly selection = new BlockSelectionController();
+
+  readonly caret = new CaretController();
+
+  readonly blocks = new BlockHandleController();
+
+  readonly formula = new FormulaController();
+
+  readonly toolbar = new ToolbarController();
+
+  readonly viewport = new ViewportController();
+
+  pointerDown = false;
+
+  private pending: { from: DocPoint; to: DocPoint } | null = null;
+
+  setRoot(element: HTMLElement | null): () => void {
+    this.root = element;
+
+    return () => {
+      if (this.root === element) this.root = null;
+    };
+  }
+
+  getRoot(): HTMLElement | null {
+    return this.root;
+  }
+
+  register(id: BlockId, element: HTMLElement): () => void {
+    this.elements.set(id, element);
+
+    const pending = this.pending;
+
+    if (
+      pending &&
+      this.elements.has(pending.from.blockId) &&
+      this.elements.has(pending.to.blockId)
+    ) {
+      // Регистрация идёт раньше, чем блок заполнит текст (тоже в layout-эффекте): ставим после фиксации.
+      queueMicrotask(() => {
+        if (this.pending === pending) this.placeSelection(pending.from, pending.to);
+      });
+    }
+
+    return () => {
+      // Не удаляем, если за это время зарегистрировали другой элемент для того же id.
+      if (this.elements.get(id) === element) {
+        this.elements.delete(id);
+      }
+    };
+  }
+
+  getElement(id: BlockId): HTMLElement | undefined {
+    return this.elements.get(id);
+  }
+
+  placeCaret(id: BlockId, offset: number): void {
+    this.placeSelection({ blockId: id, offset }, { blockId: id, offset });
+  }
+
+  placeSelection(from: DocPoint, to: DocPoint): void {
+    const start = this.elements.get(from.blockId);
+    const end = this.elements.get(to.blockId);
+
+    if (!start || !end) {
+      // Блок за пределами окна виртуального рендерера: просим отрисовать его и ставим выделение,
+      // когда он зарегистрируется (прокрутка к нему — ниже, через scrollIntoView).
+      this.pending = this.viewport.reveal([from.blockId, to.blockId]) ? { from, to } : null;
+      return;
+    }
+
+    this.pending = null;
+
+    // Фокус принадлежит корню: отдельные блоки не являются редактируемыми элементами.
+    if (this.root && globalThis.document.activeElement !== this.root) {
+      this.root.focus({ preventScroll: true });
+    }
+
+    setDomSelection(start, from.offset, end, to.offset);
+
+    end.scrollIntoView?.({ block: 'nearest' });
+  }
+}

package/src/editing/ViewportController.ts

@@ -0,0 +1,63 @@
+/**
+ * Какие блоки обязаны оставаться в DOM при виртуальной отрисовке: края выделения (там стоит каретка или
+ * начинается/кончается выделение) и блоки, которые редактор попросил показать (`reveal`), например перед
+ * установкой каретки в блок за пределами окна. Обычный рендерер это состояние не читает.
+ */
+export class ViewportController {
+  private edges: readonly string[] = [];
+
+  private revealed: readonly string[] = [];
+
+  private lists = 0;
+
+  private version = 0;
+
+  private readonly listeners = new Set<() => void>();
+
+  getVersion = (): number => this.version;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  getPinned(): readonly string[] {
+    return this.revealed.length === 0 ? this.edges : [...this.edges, ...this.revealed];
+  }
+
+  get virtual(): boolean {
+    return this.lists > 0;
+  }
+
+  attach(): () => void {
+    this.lists += 1;
+
+    return () => {
+      this.lists -= 1;
+    };
+  }
+
+  setEdges(ids: readonly string[]): void {
+    if (ids.length === this.edges.length && ids.every((id, i) => this.edges[i] === id)) return;
+
+    this.edges = ids;
+    this.notify();
+  }
+
+  reveal(ids: readonly string[]): boolean {
+    if (!this.virtual) return false;
+
+    this.revealed = ids;
+    this.notify();
+    return true;
+  }
+
+  private notify(): void {
+    this.version += 1;
+
+    for (const listener of [...this.listeners]) listener();
+  }
+}