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

package/src/math/renderer.ts

@@ -0,0 +1,198 @@
+export interface FormulaRenderOptions {
+  readonly display: boolean;
+}
+
+/**
+ * Рисует формулу в `target`: по коду LaTeX строит DOM (MathML, HTML, SVG…). Может быть асинхронной — например, для
+ * подгрузки библиотеки. Если код ошибочен, функция должна бросить исключение: редактор покажет исходный текст и
+ * сообщение об ошибке. Встроенный `temmlRenderer` строит MathML; KaTeX подключается так:
+ * `(latex, target, { display }) => katex.render(latex, target, { displayMode: display, throwOnError: true })`.
+ *
+ * Результат вставляется в страницу как есть, поэтому используйте только безопасные режимы библиотек
+ * (например, `trust: false`): LaTeX приходит из документа и может быть недоверенным.
+ */
+export type FormulaRenderer = (
+  latex: string,
+  target: HTMLElement,
+  options: FormulaRenderOptions,
+) => void | Promise<void>;
+
+type TemmlApi = typeof import('temml').default;
+
+let temml: Promise<TemmlApi> | undefined;
+
+/** Temml (≈ 480 КБ) подгружается при первой формуле: документы без формул её не платят. */
+const loadTemml = () => (temml ??= import('temml').then((module) => module.default));
+
+export const temmlRenderer: FormulaRenderer = async (latex, target, { display }) => {
+  const api = await loadTemml();
+
+  api.render(latex, target, {
+    displayMode: display,
+    throwOnError: true,
+    trust: false,
+    strict: false,
+    maxExpand: 1000,
+  });
+};
+
+let mathCss: Promise<string> | undefined;
+
+const loadMathCss = () => (mathCss ??= import('./mathCss').then((module) => module.MATH_CSS));
+
+let shadowSheet: CSSStyleSheet | null | undefined;
+
+function constructableSheet(css: string): CSSStyleSheet | null {
+  if (shadowSheet !== undefined) return shadowSheet;
+
+  try {
+    if (typeof CSSStyleSheet !== 'undefined' && 'replaceSync' in CSSStyleSheet.prototype) {
+      shadowSheet = new CSSStyleSheet();
+      shadowSheet.replaceSync(css);
+
+      return shadowSheet;
+    }
+  } catch {
+    // нет поддержки конструируемых таблиц стилей — ниже используется <style>
+  }
+
+  return (shadowSheet = null);
+}
+
+const styled = new WeakSet<Document | ShadowRoot>();
+
+function applyMathStyles(scope: Document | ShadowRoot, css: string): void {
+  if (typeof ShadowRoot !== 'undefined' && scope instanceof ShadowRoot) {
+    const sheet = constructableSheet(css);
+
+    if (sheet && Array.isArray(scope.adoptedStyleSheets)) {
+      scope.adoptedStyleSheets = [...scope.adoptedStyleSheets, sheet];
+    } else {
+      const style = globalThis.document.createElement('style');
+
+      style.textContent = css;
+      scope.appendChild(style);
+    }
+
+    return;
+  }
+
+  const doc = scope as Document;
+
+  if (doc.head.querySelector('style[data-inkbrick-math]')) return;
+
+  const style = doc.createElement('style');
+
+  style.setAttribute('data-inkbrick-math', '');
+  style.textContent = `@layer inkbrick.math {\n${css}\n}`;
+  doc.head.appendChild(style);
+}
+
+/**
+ * Подключает стили MathML (Temml) к документу или теневому корню встроенной формулы. В документе стили кладутся
+ * в слой `inkbrick.math`, поэтому любое ваше правило без слоя сильнее. Стили подгружаются при первом вызове
+ * и применяются, как только загрузятся (одновременно с самой формулой).
+ */
+export function ensureMathStyles(scope: Document | ShadowRoot): void {
+  if (styled.has(scope)) return;
+
+  styled.add(scope);
+  void loadMathCss().then((css) => applyMathStyles(scope, css));
+}
+
+type Rendered = readonly Node[];
+
+const MAX_CACHE = 500;
+const caches = new WeakMap<FormulaRenderer, Map<string, Rendered>>();
+
+function cacheOf(renderer: FormulaRenderer): Map<string, Rendered> {
+  let cache = caches.get(renderer);
+
+  if (!cache) caches.set(renderer, (cache = new Map()));
+
+  return cache;
+}
+
+export type FormulaState = 'empty' | 'source' | 'loading' | 'ready' | 'error';
+
+export interface MountFormulaOptions {
+  readonly display: boolean;
+  readonly renderer: FormulaRenderer | null;
+  readonly onSettled?: (state: 'ready' | 'error', message?: string) => void;
+}
+
+/**
+ * Рисует формулу в `target`. Пока идёт расчёт, виден исходный код (`data-state="loading"`); готовый результат кладётся
+ * в кэш, поэтому одинаковые формулы (и перерисовка блока на каждое нажатие клавиши) появляются сразу, без мигания.
+ * Возвращает функцию отмены: после неё устаревший результат в `target` не попадёт.
+ */
+export function mountFormula(
+  target: HTMLElement,
+  latex: string,
+  { display, renderer, onSettled }: MountFormulaOptions,
+): () => void {
+  const source = latex.trim();
+
+  if (source === '') {
+    target.replaceChildren();
+    target.setAttribute('data-state', 'empty');
+
+    return () => undefined;
+  }
+
+  if (!renderer) {
+    target.textContent = latex;
+    target.setAttribute('data-state', 'source');
+
+    return () => undefined;
+  }
+
+  const key = `${display ? 'd' : 'i'}:${latex}`;
+  const cache = cacheOf(renderer);
+  const cached = cache.get(key);
+
+  if (cached) {
+    target.replaceChildren(...cached.map((node) => node.cloneNode(true)));
+    target.setAttribute('data-state', 'ready');
+    onSettled?.('ready');
+
+    return () => undefined;
+  }
+
+  let cancelled = false;
+
+  target.textContent = latex;
+  target.setAttribute('data-state', 'loading');
+
+  const scratch = globalThis.document.createElement('span');
+
+  void (async () => {
+    try {
+      await renderer(latex, scratch, { display });
+
+      if (cancelled) return;
+
+      const nodes = [...scratch.childNodes];
+
+      if (cache.size >= MAX_CACHE) cache.delete(cache.keys().next().value as string);
+
+      cache.set(
+        key,
+        nodes.map((node) => node.cloneNode(true)),
+      );
+      target.replaceChildren(...nodes);
+      target.setAttribute('data-state', 'ready');
+      onSettled?.('ready');
+    } catch (error) {
+      if (cancelled) return;
+
+      target.textContent = latex;
+      target.setAttribute('data-state', 'error');
+      onSettled?.('error', error instanceof Error ? error.message : String(error));
+    }
+  })();
+
+  return () => {
+    cancelled = true;
+  };
+}

package/src/registry/defaultBlockComponents.ts

@@ -0,0 +1,26 @@
+import type { BlockComponentRegistry } from '../ui/types';
+import { PageBlock } from '../blocks/PageBlock';
+import { NoteBlock } from '../blocks/NoteBlock';
+import { ParagraphBlock } from '../blocks/ParagraphBlock';
+import { HeadingBlock } from '../blocks/HeadingBlock';
+import { ListBlock } from '../blocks/ListBlock';
+import { QuoteBlock } from '../blocks/QuoteBlock';
+import { CodeBlock } from '../blocks/CodeBlock';
+import { DividerBlock } from '../blocks/DividerBlock';
+import { CalloutBlock } from '../blocks/CalloutBlock';
+import { ImageBlock } from '../blocks/ImageBlock';
+import { FormulaBlock } from '../blocks/FormulaBlock';
+
+export const defaultBlockComponents: BlockComponentRegistry = Object.freeze({
+  'block:page': PageBlock,
+  'block:note': NoteBlock,
+  'block:paragraph': ParagraphBlock,
+  'block:heading': HeadingBlock,
+  'block:list': ListBlock,
+  'block:quote': QuoteBlock,
+  'block:code': CodeBlock,
+  'block:divider': DividerBlock,
+  'block:callout': CalloutBlock,
+  'block:image': ImageBlock,
+  'block:formula': FormulaBlock,
+});

package/src/registry/resolveBlockComponent.ts

@@ -0,0 +1,14 @@
+import type { BlockComponent, BlockComponentRegistry } from '../ui/types';
+import { defaultBlockComponents } from './defaultBlockComponents';
+
+function lookup(registry: BlockComponentRegistry, flavour: string): BlockComponent | undefined {
+  // hasOwn: ключи вроде "constructor" или "__proto__" не должны находить прототипные свойства.
+  return Object.hasOwn(registry, flavour) ? registry[flavour] : undefined;
+}
+
+export function resolveBlockComponent(
+  flavour: string,
+  custom: BlockComponentRegistry,
+): BlockComponent | undefined {
+  return lookup(custom, flavour) ?? lookup(defaultBlockComponents, flavour);
+}

package/src/renderer/BlockRenderer.tsx

@@ -0,0 +1,63 @@
+import { memo, useSyncExternalStore } from 'react';
+
+import type { BlockId } from '@inkbrick/document';
+
+import { BlockChildren } from '../blocks/BlockChildren';
+import { UnknownBlockView } from '../blocks/UnknownBlockView';
+import { useBlock } from '../hooks/useBlock';
+import { useEditor } from '../hooks/useEditor';
+import { useEditorView } from '../hooks/useEditorView';
+import { useReadOnly } from '../hooks/useReadOnly';
+import { resolveBlockComponent } from '../registry/resolveBlockComponent';
+import { useEditorUI } from '../ui/EditorUIContext';
+
+export interface BlockRendererProps {
+  readonly id: BlockId;
+}
+
+const warned = new Set<string>();
+
+export const BlockRenderer = memo(function BlockRenderer({ id }: BlockRendererProps) {
+  const editor = useEditor();
+  const view = useEditorView();
+  const readOnly = useReadOnly();
+  const { components, slots } = useEditorUI();
+  const selected = useSyncExternalStore(
+    view.selection.subscribe,
+    () => view.selection.isSelected(id),
+    () => false,
+  );
+  const block = useBlock(id);
+
+  if (!block) {
+    return null;
+  }
+
+  const Component = resolveBlockComponent(block.flavour, components);
+
+  if (Component) {
+    return (
+      <Component
+        block={block}
+        editor={editor}
+        selected={selected}
+        readOnly={readOnly}
+        controller={editor.controllers.get(block.flavour)}
+      />
+    );
+  }
+
+  // Неизвестный тип блока не должен ронять редактор и не должен подменяться другим типом.
+  if (!warned.has(block.flavour)) {
+    warned.add(block.flavour);
+    console.warn(`[@inkbrick/react] No component registered for block "${block.flavour}"`);
+  }
+
+  const Fallback = slots.UnknownBlock ?? UnknownBlockView;
+
+  return (
+    <Fallback block={block} editor={editor} selected={selected} readOnly={readOnly}>
+      <BlockChildren id={block.id} />
+    </Fallback>
+  );
+});

package/src/renderer/DocumentRenderer.tsx

@@ -0,0 +1,33 @@
+import { createContext, type ComponentType } from 'react';
+
+import type { BlockId } from '@inkbrick/document';
+
+import { BlockRenderer } from './BlockRenderer';
+
+export interface ChildListProps {
+  readonly parentId: BlockId;
+  readonly ids: readonly BlockId[];
+}
+
+/**
+ * Способ отрисовки документа: как выводить детей каждого контейнера (страницы, заметки, вложенного списка).
+ * Модель и команды от него не зависят. Встроенные варианты — `fullRenderer` (всё дерево, по умолчанию)
+ * и `virtualRenderer()` (только блоки около видимой области).
+ */
+export interface DocumentRenderer {
+  readonly ChildList: ComponentType<ChildListProps>;
+}
+
+function FullChildList({ ids }: ChildListProps) {
+  return (
+    <>
+      {ids.map((id) => (
+        <BlockRenderer key={id} id={id} />
+      ))}
+    </>
+  );
+}
+
+export const fullRenderer: DocumentRenderer = { ChildList: FullChildList };
+
+export const DocumentRendererContext = createContext<DocumentRenderer>(fullRenderer);

package/src/renderer/DocumentView.tsx

@@ -0,0 +1,94 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+import { BlockHandleHost } from '../block-handle/BlockHandleHost';
+import { DropIndicatorHost } from '../block-handle/DropIndicatorHost';
+import { useClipboard } from '../clipboard/useClipboard';
+import { useBlockHandles } from '../block-handle/useBlockHandles';
+import { useEditorInput } from '../editing/useEditorInput';
+import { useSelectionState } from '../editing/useSelectionState';
+import { useEditor } from '../hooks/useEditor';
+import { useEditorView } from '../hooks/useEditorView';
+import { useReadOnly } from '../hooks/useReadOnly';
+import { useT } from '../hooks/useT';
+import { useEditorUI } from '../ui/EditorUIContext';
+import { FormulaPopover } from '../formula/FormulaPopover';
+import { preloadFormulaPalette } from '../formula/LazyFormulaPalette';
+import { SlashMenuHost } from '../slash/SlashMenuHost';
+import { ToolbarHost } from '../toolbar/ToolbarHost';
+import { BlockRenderer } from './BlockRenderer';
+import { DocumentRendererContext, fullRenderer, type DocumentRenderer } from './DocumentRenderer';
+import { defaultVirtualRenderer } from './virtual/virtualRenderer';
+
+export interface DocumentViewProps {
+  readonly label?: string;
+  /**
+   * Как рисовать блоки: `'full'` (по умолчанию) — всё дерево; `'virtual'` или `virtualRenderer({...})` — только
+   * блоки около видимой области (для документов на тысячи блоков); либо свой `DocumentRenderer`.
+   */
+  readonly renderer?: 'full' | 'virtual' | DocumentRenderer;
+}
+
+function resolveRenderer(renderer: DocumentViewProps['renderer']): DocumentRenderer {
+  if (renderer === 'virtual') return defaultVirtualRenderer;
+  if (!renderer || renderer === 'full') return fullRenderer;
+  return renderer;
+}
+
+/**
+ * Единственный редактируемый элемент документа. Все блоки лежат внутри него, поэтому
+ * выделение работает через границы блоков; ввод перехватывается и превращается в команды движка.
+ */
+export function DocumentView({ label, renderer }: DocumentViewProps = {}) {
+  const editor = useEditor();
+  const view = useEditorView();
+  const ref = useRef<HTMLDivElement>(null);
+
+  const { slots } = useEditorUI();
+
+  const readOnly = useReadOnly();
+  const t = useT();
+
+  useEditorInput(ref, !readOnly);
+  useSelectionState(ref);
+  useClipboard(ref, readOnly);
+  useBlockHandles(ref, slots.BlockHandle !== null && !readOnly);
+
+  useLayoutEffect(() => view.setRoot(ref.current), [view]);
+
+  /*
+   * Палитру формул (отдельный чанк ~5 КБ) начинаем грузить сразу после первой отрисовки: она не задерживает
+   * открытие документа, но готова к первому редактору формулы (Tab из поля кода ведёт в палитру).
+   */
+  useEffect(() => {
+    if (!readOnly) void preloadFormulaPalette();
+  }, [readOnly]);
+
+  return (
+    <>
+      <div
+        ref={ref}
+        className="inkbrick-editor"
+        data-inkbrick-root=""
+        contentEditable={!readOnly}
+        suppressContentEditableWarning
+        spellCheck={false}
+        role="textbox"
+        aria-multiline="true"
+        aria-label={label ?? t('editor.label')}
+        // Документ только для чтения должен получать фокус: так работают Ctrl+A и Ctrl+C с клавиатуры.
+        tabIndex={readOnly ? 0 : undefined}
+        aria-readonly={readOnly || undefined}
+        data-readonly={readOnly || undefined}
+      >
+        <DocumentRendererContext.Provider value={resolveRenderer(renderer)}>
+          <BlockRenderer id={editor.document.rootId} />
+        </DocumentRendererContext.Provider>
+      </div>
+      <SlashMenuHost />
+      <ToolbarHost />
+      <FormulaPopover />
+      <BlockHandleHost />
+      <DropIndicatorHost />
+    </>
+  );
+}