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

package/src/renderer/virtual/VirtualChildList.tsx

@@ -0,0 +1,355 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
+
+import type { BlockId } from '@inkbrick/document';
+import type { Editor } from '@inkbrick/engine';
+
+import { useEditor } from '../../hooks/useEditor';
+import { useEditorView } from '../../hooks/useEditorView';
+import { BlockRenderer } from '../BlockRenderer';
+import type { ChildListProps } from '../DocumentRenderer';
+import { estimateSubtree, type BlockHeightEstimate } from './estimate';
+
+export interface ResolvedVirtualOptions {
+  readonly threshold: number;
+  readonly overscan: number;
+  readonly maxRendered: number;
+  readonly estimateHeight: BlockHeightEstimate;
+}
+
+interface Range {
+  readonly top: number;
+  readonly bottom: number;
+}
+
+const SPACER = 'data-inkbrick-spacer';
+
+function upperBound(offsets: Float64Array, value: number): number {
+  let lo = 0;
+  let hi = offsets.length;
+
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+
+    if (offsets[mid] <= value) lo = mid + 1;
+    else hi = mid;
+  }
+
+  return lo;
+}
+
+function scrollParents(element: HTMLElement): HTMLElement[] {
+  const result: HTMLElement[] = [];
+
+  for (
+    let node = element.parentElement;
+    node && node !== document.body && node !== document.documentElement;
+    node = node.parentElement
+  ) {
+    if (/(auto|scroll|hidden|clip)/.test(getComputedStyle(node).overflowY)) result.push(node);
+  }
+
+  return result;
+}
+
+function visibleRange(marker: HTMLElement, parents: readonly HTMLElement[]): Range {
+  let top = 0;
+  let bottom = window.innerHeight;
+
+  for (const parent of parents) {
+    const rect = parent.getBoundingClientRect();
+
+    top = Math.max(top, rect.top);
+    bottom = Math.min(bottom, rect.bottom);
+  }
+
+  const origin = marker.getBoundingClientRect().top;
+
+  return { top: top - origin, bottom: Math.max(top, bottom) - origin };
+}
+
+function indexOfItem(
+  editor: Editor,
+  parentId: BlockId,
+  ids: readonly BlockId[],
+  id: BlockId,
+): number {
+  let block = editor.store.getBlock(id);
+
+  while (block && block.parentId !== parentId) {
+    block = block.parentId ? editor.store.getBlock(block.parentId) : undefined;
+  }
+
+  return block ? ids.indexOf(block.id) : -1;
+}
+
+function Spacer({ height }: { readonly height: number }) {
+  return (
+    <div
+      className="inkbrick-spacer"
+      data-inkbrick-spacer=""
+      aria-hidden="true"
+      contentEditable={false}
+      style={{ height }}
+    />
+  );
+}
+
+/**
+ * Дети контейнера с окном отрисовки: в DOM — блоки около видимой области, первый и последний блок (для Ctrl+A),
+ * края выделения, перетаскиваемый блок и запрошенные редактором (`view.viewport`); остальные заменены
+ * распорками. Высота отрисованного блока измеряется (вместе с отступом до следующего), неотрисованного — оценивается.
+ * Короткие списки (меньше `threshold`) рисуются целиком теми же элементами, поэтому переход порога ничего не
+ * пересоздаёт.
+ */
+export function VirtualChildList({
+  parentId,
+  ids,
+  options,
+}: ChildListProps & { readonly options: ResolvedVirtualOptions }) {
+  const editor = useEditor();
+  const view = useEditorView();
+  const windowed = ids.length >= options.threshold;
+  const marker = useRef<HTMLDivElement>(null);
+  const parents = useRef<HTMLElement[]>([]);
+  // Измеренные высоты блоков и оценки неотрисованных (оценка не обновляется, пока блок не отрисуют и не измерят).
+  const [heights] = useState(() => new Map<BlockId, number>());
+  const [estimates] = useState(() => new Map<BlockId, number>());
+  const [measured, remeasure] = useReducer((n: number) => n + 1, 0);
+  const [range, setRange] = useState<Range>(() => ({
+    top: 0,
+    bottom: typeof window === 'undefined' ? 1000 : window.innerHeight,
+  }));
+
+  const pins = useSyncExternalStore(
+    view.viewport.subscribe,
+    view.viewport.getVersion,
+    view.viewport.getVersion,
+  );
+  const dragId = useSyncExternalStore(
+    view.blocks.subscribe,
+    () => view.blocks.getState().drag?.blockId ?? null,
+    () => null,
+  );
+  const dropId = useSyncExternalStore(
+    view.blocks.subscribe,
+    () => view.blocks.getState().drag?.targetId ?? null,
+    () => null,
+  );
+
+  useEffect(() => (windowed ? view.viewport.attach() : undefined), [view, windowed]);
+
+  const offsets = useMemo(() => {
+    if (!windowed) return null;
+
+    const result = new Float64Array(ids.length + 1);
+    const getBlock = (id: BlockId) => editor.store.getBlock(id);
+
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      let height = heights.get(id) ?? estimates.get(id);
+
+      if (height === undefined) {
+        height = estimateSubtree(getBlock, id, options.estimateHeight);
+        estimates.set(id, height);
+      }
+
+      result[i + 1] = result[i] + height;
+    }
+
+    return result;
+    // measured — версия изменяемой карты heights
+  }, [ids, windowed, measured, heights, estimates, editor, options.estimateHeight]);
+
+  const rendered = useMemo(() => {
+    if (!offsets) return null;
+
+    const last = ids.length - 1;
+    const from = Math.max(0, upperBound(offsets, range.top - options.overscan) - 1);
+    const to = Math.min(
+      last,
+      upperBound(offsets, range.bottom + options.overscan) - 1,
+      from + options.maxRendered - 1,
+    );
+    const pinned = new Set<number>([0, last]);
+
+    for (const id of [...view.viewport.getPinned(), dragId, dropId]) {
+      if (id) pinned.add(indexOfItem(editor, parentId, ids, id));
+    }
+
+    pinned.delete(-1);
+
+    const result: number[] = [];
+
+    for (const i of [...pinned].sort((a, b) => a - b)) if (i < from) result.push(i);
+    for (let i = from; i <= to; i++) result.push(i);
+    for (const i of [...pinned].sort((a, b) => a - b)) if (i > to) result.push(i);
+
+    return result;
+    // pins — версия view.viewport: getPinned() меняется вместе с ней
+  }, [offsets, ids, range, options, view, editor, parentId, dragId, dropId, pins]);
+
+  const observer = useRef<ResizeObserver | null>(null);
+  const observed = useRef(new Map<Element, number>());
+
+  useLayoutEffect(() => {
+    if (!windowed || !rendered || !marker.current) return;
+
+    const seen = new Set<Element>();
+    const expected = new Set(rendered.map((i) => ids[i]));
+    let changed = false;
+    let previous: { id: BlockId; top: number; height: number } | null = null;
+    let remaining = rendered.length;
+
+    const settle = (height: number) => {
+      if (!previous) return;
+      // Элемент без раскладки (скрыт, jsdom) не измеряем: остаётся оценка.
+      if (height > 0 && Math.abs((heights.get(previous.id) ?? -1) - height) > 0.5) {
+        heights.set(previous.id, height);
+        changed = true;
+      }
+      previous = null;
+    };
+
+    for (
+      let element = marker.current.nextElementSibling;
+      element && remaining > 0;
+      element = element.nextElementSibling
+    ) {
+      const rect = element.getBoundingClientRect();
+
+      if (previous) settle(rect.top - previous.top);
+      if (element.hasAttribute(SPACER)) continue;
+
+      remaining -= 1;
+
+      const id = element.getAttribute('data-block-id');
+
+      if (id && expected.has(id)) {
+        previous = { id, top: rect.top, height: rect.height };
+        seen.add(element);
+      }
+    }
+
+    if (previous) settle((previous as { height: number }).height);
+
+    if (typeof ResizeObserver !== 'undefined') {
+      const sizes = observed.current;
+
+      observer.current ??= new ResizeObserver((entries) => {
+        let resized = false;
+
+        for (const entry of entries) {
+          const size = entry.contentRect.height;
+          const known = sizes.get(entry.target);
+
+          // Первое уведомление приходит сразу после observe — это не изменение.
+          if (known !== undefined && Math.abs(known - size) > 0.5) resized = true;
+          sizes.set(entry.target, size);
+        }
+
+        if (resized) remeasure();
+      });
+
+      for (const element of [...sizes.keys()]) {
+        if (!seen.has(element)) {
+          observer.current.unobserve(element);
+          sizes.delete(element);
+        }
+      }
+
+      for (const element of seen) {
+        if (!sizes.has(element)) observer.current.observe(element);
+      }
+    }
+
+    const next = visibleRange(marker.current, parents.current);
+    const step = options.overscan / 4;
+
+    setRange((current) =>
+      Math.abs(current.top - next.top) < step && Math.abs(current.bottom - next.bottom) < step
+        ? current
+        : next,
+    );
+
+    if (changed) remeasure();
+  });
+
+  useEffect(() => () => observer.current?.disconnect(), []);
+
+  useEffect(() => {
+    if (!windowed || !marker.current) return;
+
+    parents.current = scrollParents(marker.current);
+
+    let frame = 0;
+    const step = options.overscan / 4;
+
+    const onScroll = () => {
+      if (frame) return;
+
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        if (!marker.current) return;
+
+        const next = visibleRange(marker.current, parents.current);
+
+        setRange((current) =>
+          Math.abs(current.top - next.top) < step && Math.abs(current.bottom - next.bottom) < step
+            ? current
+            : next,
+        );
+      });
+    };
+
+    window.addEventListener('scroll', onScroll, { capture: true, passive: true });
+    window.addEventListener('resize', onScroll);
+
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', onScroll, { capture: true });
+      window.removeEventListener('resize', onScroll);
+    };
+  }, [windowed, options.overscan]);
+
+  if (!rendered || !offsets) {
+    return (
+      <>
+        {null}
+        {ids.map((id) => (
+          <BlockRenderer key={id} id={id} />
+        ))}
+      </>
+    );
+  }
+
+  const items: ReactNode[] = [];
+  let next = 0;
+
+  for (const i of rendered) {
+    if (i > next) items.push(<Spacer key={`gap:${next}`} height={offsets[i] - offsets[next]} />);
+    items.push(<BlockRenderer key={ids[i]} id={ids[i]} />);
+    next = i + 1;
+  }
+
+  return (
+    <>
+      <div
+        ref={marker}
+        className="inkbrick-spacer"
+        data-inkbrick-spacer="start"
+        aria-hidden="true"
+        contentEditable={false}
+      />
+      {items}
+    </>
+  );
+}

package/src/renderer/virtual/estimate.ts

@@ -0,0 +1,62 @@
+import type { BaseBlock, BlockId } from '@inkbrick/document';
+
+export type BlockHeightEstimate = (block: BaseBlock) => number;
+
+const CHARS_PER_LINE = 80;
+
+function textLength(block: BaseBlock): number {
+  let length = 0;
+
+  for (const node of block.content) length += node.insert.length;
+  return length;
+}
+
+/**
+ * Оценка по умолчанию под стандартные стили: строки текста × высота строки + отступы блока.
+ * Ошибка оценки сказывается только на длине полосы прокрутки: отрисованный блок измеряется точно.
+ */
+export const estimateBlockHeight: BlockHeightEstimate = (block) => {
+  const lines = Math.max(1, Math.ceil(textLength(block) / CHARS_PER_LINE));
+
+  switch (block.flavour) {
+    case 'block:heading':
+      return 20 + 34 * lines;
+    case 'block:code': {
+      let breaks = 0;
+
+      for (const node of block.content)
+        for (const char of node.insert) if (char === '\n') breaks += 1;
+
+      return 40 + 21 * (breaks + 1);
+    }
+    case 'block:image':
+      return 260;
+    case 'block:divider':
+      return 25;
+    case 'block:formula':
+      return 64;
+    case 'block:callout':
+      return 24 + 26 * lines;
+    default:
+      return 8 + 26 * lines;
+  }
+};
+
+export function estimateSubtree(
+  getBlock: (id: BlockId) => BaseBlock | undefined,
+  id: BlockId,
+  estimate: BlockHeightEstimate,
+): number {
+  let total = 0;
+  const queue: BlockId[] = [id];
+
+  for (let i = 0; i < queue.length; i++) {
+    const block = getBlock(queue[i]);
+
+    if (!block) continue;
+    total += estimate(block);
+    for (const child of block.children) queue.push(child);
+  }
+
+  return total;
+}

package/src/renderer/virtual/virtualRenderer.tsx

@@ -0,0 +1,35 @@
+import type { ChildListProps, DocumentRenderer } from '../DocumentRenderer';
+import { estimateBlockHeight, type BlockHeightEstimate } from './estimate';
+import { VirtualChildList, type ResolvedVirtualOptions } from './VirtualChildList';
+
+export interface VirtualRendererOptions {
+  /** Контейнер с меньшим числом детей рисуется целиком. По умолчанию 100. */
+  readonly threshold?: number;
+  /** Запас над и под видимой областью, в котором блоки уже отрисованы, px. По умолчанию 1200. */
+  readonly overscan?: number;
+  /** Не больше стольких блоков подряд в окне (защита от нулевых высот). По умолчанию 400. */
+  readonly maxRendered?: number;
+  readonly estimateHeight?: BlockHeightEstimate;
+}
+
+/**
+ * Виртуальный рендерер: в DOM только блоки около видимой области, остальные заменены распорками известной
+ * (измеренной) или оценённой высоты. Подключение: `<DocumentView renderer={virtualRenderer()} />` (или
+ * `renderer="virtual"` с настройками по умолчанию). Создавайте рендерер один раз, вне компонента.
+ */
+export function virtualRenderer(options: VirtualRendererOptions = {}): DocumentRenderer {
+  const resolved: ResolvedVirtualOptions = {
+    threshold: Math.max(1, options.threshold ?? 100),
+    overscan: Math.max(0, options.overscan ?? 1200),
+    maxRendered: Math.max(1, options.maxRendered ?? 400),
+    estimateHeight: options.estimateHeight ?? estimateBlockHeight,
+  };
+
+  function VirtualChildren(props: ChildListProps) {
+    return <VirtualChildList {...props} options={resolved} />;
+  }
+
+  return { ChildList: VirtualChildren };
+}
+
+export const defaultVirtualRenderer = virtualRenderer();

package/src/slash/DefaultSlashMenu.tsx

@@ -0,0 +1,119 @@
+import { useId, useLayoutEffect, useRef, useState } from 'react';
+
+import { useEditorView } from '../hooks/useEditorView';
+import { useT } from '../hooks/useT';
+import type { SlashMenuProps } from './types';
+
+const ESTIMATED_LINE = 28;
+
+export function DefaultSlashMenu({
+  items,
+  activeIndex,
+  position,
+  onSelect,
+  onHover,
+}: SlashMenuProps) {
+  const t = useT();
+  const view = useEditorView();
+  const ref = useRef<HTMLDivElement>(null);
+  const [flip, setFlip] = useState(false);
+  const menuId = useId();
+  const optionId = (index: number) => `${menuId}-option-${index}`;
+
+  useLayoutEffect(() => {
+    const menu = ref.current;
+
+    if (!menu) return;
+
+    setFlip(
+      position.y + menu.offsetHeight > window.innerHeight &&
+        position.y - menu.offsetHeight - ESTIMATED_LINE > 0,
+    );
+  }, [position.x, position.y, items.length]);
+
+  useLayoutEffect(() => {
+    ref.current?.querySelector('[aria-selected="true"]')?.scrollIntoView?.({ block: 'nearest' });
+  }, [activeIndex, items]);
+
+  /*
+   * Фокус остаётся в тексте документа, а меню управляется с клавиатуры редактором (паттерн combobox ARIA):
+   * корень документа ссылается на меню и на выбранный пункт — так экранный чтец озвучивает выбор.
+   */
+  useLayoutEffect(() => {
+    const root = view.getRoot();
+
+    if (!root) return;
+
+    root.setAttribute('aria-controls', menuId);
+
+    if (items.length > 0) root.setAttribute('aria-activedescendant', optionId(activeIndex));
+    else root.removeAttribute('aria-activedescendant');
+
+    return () => {
+      root.removeAttribute('aria-controls');
+      root.removeAttribute('aria-activedescendant');
+    };
+  }, [view, menuId, activeIndex, items.length]);
+
+  return (
+    <div
+      ref={ref}
+      id={menuId}
+      className="inkbrick-slash-menu"
+      data-inkbrick-ui="slash-menu"
+      /*
+       * Прокручиваемая область должна быть доступна с клавиатуры. До меню фокус Tab-ом не доходит: в открытом
+       * меню Tab выбирает пункт (его перехватывает редактор), а клик по меню не уводит фокус из текста.
+       */
+      tabIndex={0}
+      role="listbox"
+      aria-label={t('slash.label')}
+      data-testid="slash-menu"
+      style={{
+        left: Math.max(
+          8,
+          Math.min(position.x, window.innerWidth - (ref.current?.offsetWidth ?? 320) - 8),
+        ),
+        top: flip ? position.y - (ref.current?.offsetHeight ?? 0) - ESTIMATED_LINE : position.y + 4,
+      }}
+      onMouseDown={(event) => event.preventDefault()}
+    >
+      {items.length === 0 && (
+        <div className="inkbrick-slash-menu__description" data-inkbrick-part="empty">
+          {t('slash.empty')}
+        </div>
+      )}
+
+      {items.map((item, index) => (
+        <div
+          key={item.id}
+          id={optionId(index)}
+          role="option"
+          aria-selected={index === activeIndex}
+          data-slash-item={item.id}
+          data-inkbrick-part="item"
+          data-active={index === activeIndex || undefined}
+          className={`inkbrick-slash-menu__item${index === activeIndex ? ' inkbrick-slash-menu__item--selected' : ''}`}
+          onMouseEnter={() => onHover(index)}
+          onClick={() => onSelect(item)}
+        >
+          {item.icon !== undefined && (
+            <span className="inkbrick-slash-menu__icon" data-inkbrick-part="icon">
+              {item.icon}
+            </span>
+          )}
+          <div className="inkbrick-slash-menu__body" data-inkbrick-part="body">
+            <div className="inkbrick-slash-menu__header" data-inkbrick-part="title">
+              {item.title}
+            </div>
+            {item.description && (
+              <div className="inkbrick-slash-menu__description" data-inkbrick-part="description">
+                {item.description}
+              </div>
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/slash/SlashMenuController.ts

@@ -0,0 +1,66 @@
+export interface SlashMenuState {
+  readonly open: boolean;
+  readonly blockId: string | null;
+  readonly slashOffset: number;
+  readonly query: string;
+  readonly activeIndex: number;
+  readonly position: { readonly x: number; readonly y: number } | null;
+}
+
+const CLOSED: SlashMenuState = Object.freeze({
+  open: false,
+  blockId: null,
+  slashOffset: 0,
+  query: '',
+  activeIndex: 0,
+  position: null,
+});
+
+export class SlashMenuController {
+  private state: SlashMenuState = CLOSED;
+
+  private readonly listeners = new Set<() => void>();
+
+  getState = (): SlashMenuState => this.state;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  open(blockId: string, slashOffset: number): void {
+    this.set({ ...CLOSED, open: true, blockId, slashOffset });
+  }
+
+  close(): void {
+    if (this.state.open) this.set(CLOSED);
+  }
+
+  update(patch: Partial<Pick<SlashMenuState, 'query' | 'activeIndex' | 'position'>>): void {
+    if (!this.state.open) return;
+
+    const next = { ...this.state, ...patch };
+    const same =
+      next.query === this.state.query &&
+      next.activeIndex === this.state.activeIndex &&
+      next.position?.x === this.state.position?.x &&
+      next.position?.y === this.state.position?.y;
+
+    if (!same) this.set(next);
+  }
+
+  move(delta: number, count: number): void {
+    if (!this.state.open || count === 0) return;
+
+    this.update({ activeIndex: (this.state.activeIndex + delta + count) % count });
+  }
+
+  private set(state: SlashMenuState): void {
+    this.state = state;
+
+    for (const listener of [...this.listeners]) listener();
+  }
+}

package/src/slash/SlashMenuHost.tsx

@@ -0,0 +1,48 @@
+import { createPortal } from 'react-dom';
+import { useSyncExternalStore } from 'react';
+
+import { useEditor } from '../hooks/useEditor';
+import { useEditorView } from '../hooks/useEditorView';
+import { useReadOnly } from '../hooks/useReadOnly';
+import { useEditorUI } from '../ui/EditorUIContext';
+import { applySlashItem } from './applySlashItem';
+import { DefaultSlashMenu } from './DefaultSlashMenu';
+import { visibleSlashItems } from './items';
+
+export function SlashMenuHost() {
+  const editor = useEditor();
+  const view = useEditorView();
+  const { slots, slashItems } = useEditorUI();
+  const readOnly = useReadOnly();
+  const state = useSyncExternalStore(
+    view.slash.subscribe,
+    view.slash.getState,
+    view.slash.getState,
+  );
+
+  if (
+    readOnly ||
+    !state.open ||
+    !state.blockId ||
+    !state.position ||
+    typeof document === 'undefined'
+  ) {
+    return null;
+  }
+
+  const items = visibleSlashItems(editor, slashItems, state.blockId, state.query);
+  const Menu = slots.SlashMenu ?? DefaultSlashMenu;
+
+  return createPortal(
+    <Menu
+      items={items}
+      query={state.query}
+      activeIndex={Math.min(state.activeIndex, Math.max(items.length - 1, 0))}
+      position={state.position}
+      onSelect={(item) => applySlashItem(editor, view, item)}
+      onHover={(index) => view.slash.update({ activeIndex: index })}
+      onClose={() => view.slash.close()}
+    />,
+    document.body,
+  );
+}