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

package/src/hooks/useBlock.ts

@@ -0,0 +1,21 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+import type { BlockId } from '@inkbrick/document';
+
+import { useEditor } from './useEditor';
+
+/**
+ * Подписывается на один блок. Блоки в документе иммутабельны (каждое изменение
+ * создаёт новый объект), поэтому ссылка — корректный snapshot для React.
+ */
+export function useBlock(id: BlockId) {
+  const { store } = useEditor();
+
+  const subscribe = useCallback(
+    (listener: () => void) => store.subscribeBlock(id, listener),
+    [store, id],
+  );
+  const getSnapshot = useCallback(() => store.getBlock(id), [store, id]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/hooks/useBlockController.ts

@@ -0,0 +1,30 @@
+import { useMemo } from 'react';
+
+import type { BaseBlock, BlockProps } from '@inkbrick/document';
+import type { BlockContext, BlockController } from '@inkbrick/engine';
+
+import { useEditor } from './useEditor';
+
+export interface BlockControllerHandle<
+  TProps extends BlockProps = BlockProps,
+> extends BlockContext<TProps> {
+  readonly controller: BlockController<TProps> | undefined;
+}
+
+/**
+ * Контроллер блока для его React-компонента: `execute('counter.increment')` и `can(...)` уже знают `blockId`.
+ * Команды уважают режим только чтения (возвращают undefined); для разметки используйте prop `readOnly`.
+ */
+export function useBlockController<TProps extends BlockProps = BlockProps>(
+  block: BaseBlock,
+): BlockControllerHandle<TProps> {
+  const editor = useEditor();
+
+  return useMemo(() => {
+    const context = editor.controllers.contextOf<TProps>(block);
+
+    return Object.assign(Object.create(context) as BlockContext<TProps>, {
+      controller: editor.controllers.get(block.flavour) as BlockController<TProps> | undefined,
+    });
+  }, [editor, block]);
+}

package/src/hooks/useChildren.ts

@@ -0,0 +1,16 @@
+import type { BlockId } from '@inkbrick/document';
+
+import { useBlock } from './useBlock';
+
+const NO_CHILDREN: readonly BlockId[] = [];
+
+/**
+ * Идентификаторы дочерних блоков. Возвращает стабильную ссылку, пока children
+ * не изменились (создавать новый массив в getSnapshot нельзя — это приводит
+ * к бесконечному циклу рендера в useSyncExternalStore).
+ */
+export function useChildren(parentId: BlockId): readonly BlockId[] {
+  const parent = useBlock(parentId);
+
+  return parent?.children ?? NO_CHILDREN;
+}

package/src/hooks/useDocument.ts

@@ -0,0 +1,16 @@
+import { useSyncExternalStore } from 'react';
+
+import { useEditor } from './useEditor';
+
+export function useDocument() {
+  const editor = useEditor();
+  const { store } = editor;
+
+  useSyncExternalStore(
+    (listener) => store.subscribe(listener),
+    () => store.getVersion(),
+    () => store.getVersion(),
+  );
+
+  return editor.document;
+}

package/src/hooks/useEditor.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+
+import { EditorContext } from '../context/EditorContext';
+
+export function useEditor() {
+  const editor = useContext(EditorContext);
+
+  if (!editor) {
+    throw new Error('useEditor must be used inside <EditorProvider>');
+  }
+
+  return editor;
+}

package/src/hooks/useEditorView.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+
+import { EditorViewContext } from '../context/EditorContext';
+
+export function useEditorView() {
+  const view = useContext(EditorViewContext);
+
+  if (!view) {
+    throw new Error('useEditorView must be used inside <EditorProvider>');
+  }
+
+  return view;
+}

package/src/hooks/useHistory.ts

@@ -0,0 +1,46 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { flushSync } from 'react-dom';
+
+import type { HistoryResult } from '@inkbrick/engine';
+
+import { useEditor } from './useEditor';
+import { useEditorView } from './useEditorView';
+
+export interface HistoryControls {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  undo(): boolean;
+  redo(): boolean;
+}
+
+export function useHistory(): HistoryControls {
+  const editor = useEditor();
+  const view = useEditorView();
+  const { store } = editor;
+
+  useSyncExternalStore(
+    (listener) => store.subscribe(listener),
+    () => store.getHistoryVersion(),
+    () => store.getHistoryVersion(),
+  );
+
+  const apply = useCallback(
+    (action: () => HistoryResult | undefined) => {
+      let result: HistoryResult | undefined;
+
+      flushSync(() => {
+        result = action();
+      });
+
+      if (result?.caret) view.placeCaret(result.caret.blockId, result.caret.offset);
+
+      return result !== undefined;
+    },
+    [view],
+  );
+
+  const undo = useCallback(() => apply(() => editor.undo()), [apply, editor]);
+  const redo = useCallback(() => apply(() => editor.redo()), [apply, editor]);
+
+  return { canUndo: editor.canUndo, canRedo: editor.canRedo, undo, redo };
+}

package/src/hooks/useReadOnly.ts

@@ -0,0 +1,21 @@
+import { useSyncExternalStore } from 'react';
+
+import { useEditorUI } from '../ui/EditorUIContext';
+import { useEditor } from './useEditor';
+
+export function useReadOnly(): boolean {
+  const editor = useEditor();
+  const { readOnly } = useEditorUI();
+
+  const state = useSyncExternalStore(
+    (listener) => editor.subscribeReadOnly(listener),
+    () => editor.readOnly,
+    () => editor.readOnly,
+  );
+
+  /*
+   * Prop провайдера действует сразу (в том числе при серверном рендере, где эффекты не выполняются),
+   * а движок синхронизируется эффектом.
+   */
+  return readOnly ?? state;
+}

package/src/hooks/useT.ts

@@ -0,0 +1,10 @@
+import type { TFunction } from '../i18n/translate';
+import { useEditorUI } from '../ui/EditorUIContext';
+
+export function useT(): TFunction {
+  return useEditorUI().t;
+}
+
+export function useLocale(): string {
+  return useEditorUI().locale;
+}

package/src/i18n/en.ts

@@ -0,0 +1,182 @@
+/**
+ * Английский словарь — эталон: набор его ключей определяет `MessageKey`, а недостающие ключи любого другого
+ * словаря берутся отсюда. В строках можно использовать подстановки `{name}`.
+ */
+export const en = {
+  'editor.hint': 'Press / to open the menu',
+  'editor.label': 'Document',
+
+  'block.list.done': 'Done',
+  'block.code.language': 'Code language',
+  'block.code.copy': 'Copy code',
+  'block.code.copied': 'Copied',
+  'block.callout.label': 'Callout style: {tone}. Click to change',
+  'block.callout.change': 'Change style',
+  'block.callout.tone.info': 'info',
+  'block.callout.tone.warning': 'warning',
+  'block.callout.tone.success': 'success',
+  'block.callout.tone.danger': 'danger',
+  'block.unknown.title': 'Unknown block type:',
+  'block.unknown.hint': 'Register a component for it via',
+
+  'image.options': 'Image options',
+  'image.align.left': 'Align left',
+  'image.align.center': 'Align center',
+  'image.align.right': 'Align right',
+  'image.width': 'Image width',
+  'image.alt': 'Alt text',
+  'image.caption.label': 'Caption',
+  'image.caption.placeholder': 'Write a caption…',
+  'image.replace': 'Replace image',
+  'image.url.label': 'Image URL',
+  'image.url.placeholder': 'Paste an image link…',
+  'image.embed': 'Embed',
+  'image.upload': 'Upload',
+  'image.status.uploading': 'Uploading…',
+  'image.status.none': 'No image',
+  'image.status.unsupported': 'This image address is not supported',
+  'image.status.failed': 'The image could not be loaded',
+  'image.status.retry': 'Replace',
+  'image.error.invalidLink': 'Enter a valid http(s) image link',
+  'image.error.unsupportedAddress': 'This image address is not supported',
+  'image.error.type': 'Unsupported image type "{type}"',
+  'image.error.size':
+    'The image is larger than {size} KB. Provide "images.upload" to store larger images.',
+  'image.error.uploadAddress': 'The upload returned an unsupported image address',
+  'image.error.read': 'Could not read the file',
+  'image.error.generic': 'Could not add the image',
+
+  'formula.source': 'LaTeX formula',
+  'formula.placeholder': 'Type LaTeX, e.g. \\frac{a}{b}',
+  'formula.hint': 'Ctrl+Enter to apply, Esc to cancel',
+  'formula.empty': 'Add a formula',
+  'formula.edit': 'Edit formula',
+  'formula.inline.title': 'Inline formula',
+  'formula.apply': 'Apply',
+  'formula.remove': 'Remove formula',
+  'formula.cancel': 'Cancel',
+  'formula.palette.label': 'Math symbols',
+  'formula.palette.functions': 'Functions',
+  'formula.palette.structures': 'Structures',
+  'formula.palette.greek': 'Greek letters',
+  'formula.palette.operators': 'Operators',
+  'formula.palette.relations': 'Relations',
+  'formula.palette.arrows': 'Arrows',
+  'formula.palette.sets': 'Sets and logic',
+
+  'color.black': 'Black',
+  'color.white': 'White',
+  'color.gray': 'Gray',
+  'color.brown': 'Brown',
+  'color.orange': 'Orange',
+  'color.yellow': 'Yellow',
+  'color.green': 'Green',
+  'color.blue': 'Blue',
+  'color.purple': 'Purple',
+  'color.pink': 'Pink',
+  'color.red': 'Red',
+
+  'toolbar.label': 'Text formatting',
+  'toolbar.bold.label': 'Bold',
+  'toolbar.bold.title': 'Bold (Ctrl+B)',
+  'toolbar.italic.label': 'Italic',
+  'toolbar.italic.title': 'Italic (Ctrl+I)',
+  'toolbar.underline.label': 'Underline',
+  'toolbar.underline.title': 'Underline (Ctrl+U)',
+  'toolbar.strike.label': 'Strikethrough',
+  'toolbar.strike.title': 'Strikethrough (Ctrl+Shift+X)',
+  'toolbar.code.label': 'Code',
+  'toolbar.code.title': 'Code (Ctrl+E)',
+  'toolbar.formula.label': 'Formula',
+  'toolbar.formula.title': 'Formula (Ctrl+Shift+M)',
+  'toolbar.color.label': 'Text color',
+  'toolbar.color.title': 'Text color',
+  'toolbar.color.default': 'Default color',
+  'toolbar.highlight.label': 'Highlight color',
+  'toolbar.highlight.title': 'Highlight',
+  'toolbar.highlight.none': 'No highlight',
+  'toolbar.align.left.label': 'Align left',
+  'toolbar.align.left.title': 'Align left (Ctrl+Shift+L)',
+  'toolbar.align.center.label': 'Align center',
+  'toolbar.align.center.title': 'Align center (Ctrl+Shift+E)',
+  'toolbar.align.right.label': 'Align right',
+  'toolbar.align.right.title': 'Align right (Ctrl+Shift+R)',
+  'toolbar.align.justify.label': 'Justify',
+  'toolbar.align.justify.title': 'Justify (Ctrl+Shift+J)',
+  'toolbar.link.label': 'Link',
+  'toolbar.link.title': 'Link (Ctrl+K)',
+  'toolbar.link.url': 'Link URL',
+  'toolbar.link.placeholder': 'Paste a link…',
+  'toolbar.link.apply': 'Apply link',
+  'toolbar.link.remove': 'Remove link',
+
+  'handle.add': 'Add block below',
+  'handle.grip': 'Drag to move, click for options',
+  'menu.label': 'Block options',
+  'menu.duplicate': 'Duplicate',
+  'menu.moveUp': 'Move up',
+  'menu.moveDown': 'Move down',
+  'menu.delete': 'Delete',
+  'menu.turnInto': 'Turn into',
+  'menu.empty': 'No actions',
+
+  'history.undo': 'Undo',
+  'history.redo': 'Redo',
+
+  'slash.label': 'Insert block',
+  'slash.empty': 'No results',
+  'slash.item.text.title': 'Text',
+  'slash.item.text.description': 'Plain paragraph',
+  'slash.item.text.keywords': 'paragraph, p',
+  'slash.item.heading-1.title': 'Heading 1',
+  'slash.item.heading-1.description': 'Large section heading',
+  'slash.item.heading-1.keywords': 'h1, title',
+  'slash.item.heading-2.title': 'Heading 2',
+  'slash.item.heading-2.description': 'Medium section heading',
+  'slash.item.heading-2.keywords': 'h2, subtitle',
+  'slash.item.heading-3.title': 'Heading 3',
+  'slash.item.heading-3.description': 'Small section heading',
+  'slash.item.heading-3.keywords': 'h3',
+  'slash.item.heading-4.title': 'Heading 4',
+  'slash.item.heading-4.description': 'Subsection heading',
+  'slash.item.heading-4.keywords': 'h4',
+  'slash.item.heading-5.title': 'Heading 5',
+  'slash.item.heading-5.description': 'Minor subsection heading',
+  'slash.item.heading-5.keywords': 'h5',
+  'slash.item.heading-6.title': 'Heading 6',
+  'slash.item.heading-6.description': 'Smallest heading',
+  'slash.item.heading-6.keywords': 'h6',
+  'slash.item.bullet-list.title': 'Bulleted list',
+  'slash.item.bullet-list.description': 'Simple bulleted list',
+  'slash.item.bullet-list.keywords': 'ul, unordered, list',
+  'slash.item.numbered-list.title': 'Numbered list',
+  'slash.item.numbered-list.description': 'List with numbering',
+  'slash.item.numbered-list.keywords': 'ol, ordered, list',
+  'slash.item.todo-list.title': 'To-do list',
+  'slash.item.todo-list.description': 'Track tasks with checkboxes',
+  'slash.item.todo-list.keywords': 'todo, task, checkbox, check',
+  'slash.item.quote.title': 'Quote',
+  'slash.item.quote.description': 'Capture a quote',
+  'slash.item.quote.keywords': 'blockquote, citation',
+  'slash.item.code.title': 'Code',
+  'slash.item.code.description': 'Code snippet with monospace font',
+  'slash.item.code.keywords': 'snippet, pre, program',
+  'slash.item.callout.title': 'Callout',
+  'slash.item.callout.description': 'Highlight important information',
+  'slash.item.callout.keywords': 'info, note, warning, tip, alert',
+  'slash.item.image.title': 'Image',
+  'slash.item.image.description': 'Upload or embed an image',
+  'slash.item.image.keywords': 'picture, photo, img, upload',
+  'slash.item.formula.title': 'Formula',
+  'slash.item.formula.description': 'Display a LaTeX formula',
+  'slash.item.formula.keywords': 'math, equation, latex, tex',
+  'slash.item.divider.title': 'Divider',
+  'slash.item.divider.description': 'Visually separate sections',
+  'slash.item.divider.keywords': 'hr, line, separator, rule',
+} as const;
+
+export type MessageKey = keyof typeof en;
+
+export type Messages = Readonly<Record<MessageKey, string>>;
+
+export type PartialMessages = Readonly<Partial<Record<MessageKey, string>>>;

package/src/i18n/ru.ts

@@ -0,0 +1,174 @@
+import type { Messages } from './en';
+
+export const ru: Messages = {
+  'editor.hint': 'Нажмите «/», чтобы открыть меню',
+  'editor.label': 'Документ',
+
+  'block.list.done': 'Выполнено',
+  'block.code.language': 'Язык кода',
+  'block.code.copy': 'Копировать код',
+  'block.code.copied': 'Скопировано',
+  'block.callout.label': 'Стиль заметки: {tone}. Нажмите, чтобы изменить',
+  'block.callout.change': 'Изменить стиль',
+  'block.callout.tone.info': 'информация',
+  'block.callout.tone.warning': 'предупреждение',
+  'block.callout.tone.success': 'успех',
+  'block.callout.tone.danger': 'опасность',
+  'block.unknown.title': 'Неизвестный тип блока:',
+  'block.unknown.hint': 'Зарегистрируйте для него компонент через',
+
+  'image.options': 'Параметры изображения',
+  'image.align.left': 'По левому краю',
+  'image.align.center': 'По центру',
+  'image.align.right': 'По правому краю',
+  'image.width': 'Ширина изображения',
+  'image.alt': 'Альтернативный текст',
+  'image.caption.label': 'Подпись',
+  'image.caption.placeholder': 'Добавьте подпись…',
+  'image.replace': 'Заменить изображение',
+  'image.url.label': 'Адрес изображения',
+  'image.url.placeholder': 'Вставьте ссылку на изображение…',
+  'image.embed': 'Вставить',
+  'image.upload': 'Загрузить',
+  'image.status.uploading': 'Загрузка…',
+  'image.status.none': 'Нет изображения',
+  'image.status.unsupported': 'Этот адрес изображения не поддерживается',
+  'image.status.failed': 'Не удалось загрузить изображение',
+  'image.status.retry': 'Заменить',
+  'image.error.invalidLink': 'Введите корректную ссылку на изображение (http или https)',
+  'image.error.unsupportedAddress': 'Этот адрес изображения не поддерживается',
+  'image.error.type': 'Неподдерживаемый тип изображения «{type}»',
+  'image.error.size':
+    'Изображение больше {size} КБ. Чтобы хранить большие изображения, задайте «images.upload».',
+  'image.error.uploadAddress': 'Загрузчик вернул неподдерживаемый адрес изображения',
+  'image.error.read': 'Не удалось прочитать файл',
+  'image.error.generic': 'Не удалось добавить изображение',
+
+  'formula.source': 'Формула LaTeX',
+  'formula.placeholder': 'Введите LaTeX, например \\frac{a}{b}',
+  'formula.hint': 'Ctrl+Enter — применить, Esc — отмена',
+  'formula.empty': 'Добавить формулу',
+  'formula.edit': 'Изменить формулу',
+  'formula.inline.title': 'Встроенная формула',
+  'formula.apply': 'Применить',
+  'formula.remove': 'Удалить формулу',
+  'formula.cancel': 'Отмена',
+  'formula.palette.label': 'Математические символы',
+  'formula.palette.functions': 'Функции',
+  'formula.palette.structures': 'Конструкции',
+  'formula.palette.greek': 'Греческие буквы',
+  'formula.palette.operators': 'Операторы',
+  'formula.palette.relations': 'Отношения',
+  'formula.palette.arrows': 'Стрелки',
+  'formula.palette.sets': 'Множества и логика',
+
+  'color.black': 'Чёрный',
+  'color.white': 'Белый',
+  'color.gray': 'Серый',
+  'color.brown': 'Коричневый',
+  'color.orange': 'Оранжевый',
+  'color.yellow': 'Жёлтый',
+  'color.green': 'Зелёный',
+  'color.blue': 'Синий',
+  'color.purple': 'Фиолетовый',
+  'color.pink': 'Розовый',
+  'color.red': 'Красный',
+
+  'toolbar.label': 'Форматирование текста',
+  'toolbar.bold.label': 'Жирный',
+  'toolbar.bold.title': 'Жирный (Ctrl+B)',
+  'toolbar.italic.label': 'Курсив',
+  'toolbar.italic.title': 'Курсив (Ctrl+I)',
+  'toolbar.underline.label': 'Подчёркнутый',
+  'toolbar.underline.title': 'Подчёркнутый (Ctrl+U)',
+  'toolbar.strike.label': 'Зачёркнутый',
+  'toolbar.strike.title': 'Зачёркнутый (Ctrl+Shift+X)',
+  'toolbar.code.label': 'Код',
+  'toolbar.code.title': 'Код (Ctrl+E)',
+  'toolbar.formula.label': 'Формула',
+  'toolbar.formula.title': 'Формула (Ctrl+Shift+M)',
+  'toolbar.color.label': 'Цвет текста',
+  'toolbar.color.title': 'Цвет текста',
+  'toolbar.color.default': 'Цвет по умолчанию',
+  'toolbar.highlight.label': 'Цвет фона',
+  'toolbar.highlight.title': 'Выделение цветом',
+  'toolbar.highlight.none': 'Без выделения',
+  'toolbar.align.left.label': 'По левому краю',
+  'toolbar.align.left.title': 'По левому краю (Ctrl+Shift+L)',
+  'toolbar.align.center.label': 'По центру',
+  'toolbar.align.center.title': 'По центру (Ctrl+Shift+E)',
+  'toolbar.align.right.label': 'По правому краю',
+  'toolbar.align.right.title': 'По правому краю (Ctrl+Shift+R)',
+  'toolbar.align.justify.label': 'По ширине',
+  'toolbar.align.justify.title': 'По ширине (Ctrl+Shift+J)',
+  'toolbar.link.label': 'Ссылка',
+  'toolbar.link.title': 'Ссылка (Ctrl+K)',
+  'toolbar.link.url': 'Адрес ссылки',
+  'toolbar.link.placeholder': 'Вставьте ссылку…',
+  'toolbar.link.apply': 'Применить ссылку',
+  'toolbar.link.remove': 'Удалить ссылку',
+
+  'handle.add': 'Добавить блок ниже',
+  'handle.grip': 'Перетащите, чтобы переместить, или нажмите для параметров',
+  'menu.label': 'Параметры блока',
+  'menu.duplicate': 'Дублировать',
+  'menu.moveUp': 'Переместить вверх',
+  'menu.moveDown': 'Переместить вниз',
+  'menu.delete': 'Удалить',
+  'menu.turnInto': 'Превратить в',
+  'menu.empty': 'Нет действий',
+
+  'history.undo': 'Отменить',
+  'history.redo': 'Повторить',
+
+  'slash.label': 'Вставить блок',
+  'slash.empty': 'Ничего не найдено',
+  'slash.item.text.title': 'Текст',
+  'slash.item.text.description': 'Обычный абзац',
+  'slash.item.text.keywords': 'абзац, параграф, текст, paragraph',
+  'slash.item.heading-1.title': 'Заголовок 1',
+  'slash.item.heading-1.description': 'Крупный заголовок раздела',
+  'slash.item.heading-1.keywords': 'заголовок, h1, title',
+  'slash.item.heading-2.title': 'Заголовок 2',
+  'slash.item.heading-2.description': 'Средний заголовок раздела',
+  'slash.item.heading-2.keywords': 'заголовок, подзаголовок, h2',
+  'slash.item.heading-3.title': 'Заголовок 3',
+  'slash.item.heading-3.description': 'Небольшой заголовок раздела',
+  'slash.item.heading-3.keywords': 'заголовок, h3',
+  'slash.item.heading-4.title': 'Заголовок 4',
+  'slash.item.heading-4.description': 'Заголовок подраздела',
+  'slash.item.heading-4.keywords': 'заголовок, h4',
+  'slash.item.heading-5.title': 'Заголовок 5',
+  'slash.item.heading-5.description': 'Мелкий заголовок подраздела',
+  'slash.item.heading-5.keywords': 'заголовок, h5',
+  'slash.item.heading-6.title': 'Заголовок 6',
+  'slash.item.heading-6.description': 'Самый мелкий заголовок',
+  'slash.item.heading-6.keywords': 'заголовок, h6',
+  'slash.item.bullet-list.title': 'Маркированный список',
+  'slash.item.bullet-list.description': 'Простой список с маркерами',
+  'slash.item.bullet-list.keywords': 'список, маркер, ul, list',
+  'slash.item.numbered-list.title': 'Нумерованный список',
+  'slash.item.numbered-list.description': 'Список с нумерацией',
+  'slash.item.numbered-list.keywords': 'список, нумерация, ol, list',
+  'slash.item.todo-list.title': 'Список задач',
+  'slash.item.todo-list.description': 'Задачи с флажками',
+  'slash.item.todo-list.keywords': 'задачи, чекбокс, флажок, todo, task',
+  'slash.item.quote.title': 'Цитата',
+  'slash.item.quote.description': 'Выделить цитату',
+  'slash.item.quote.keywords': 'цитата, blockquote',
+  'slash.item.code.title': 'Код',
+  'slash.item.code.description': 'Фрагмент кода моноширинным шрифтом',
+  'slash.item.code.keywords': 'код, сниппет, программа, snippet',
+  'slash.item.callout.title': 'Заметка',
+  'slash.item.callout.description': 'Выделить важную информацию',
+  'slash.item.callout.keywords': 'заметка, важно, предупреждение, подсказка, callout, info',
+  'slash.item.image.title': 'Изображение',
+  'slash.item.image.description': 'Загрузить или вставить изображение',
+  'slash.item.image.keywords': 'картинка, фото, изображение, image, img',
+  'slash.item.formula.title': 'Формула',
+  'slash.item.formula.description': 'Формула LaTeX отдельной строкой',
+  'slash.item.formula.keywords': 'формула, математика, уравнение, latex',
+  'slash.item.divider.title': 'Разделитель',
+  'slash.item.divider.description': 'Визуально разделить разделы',
+  'slash.item.divider.keywords': 'линия, разделитель, черта, hr',
+};

package/src/i18n/translate.ts

@@ -0,0 +1,77 @@
+import { en, type MessageKey, type Messages, type PartialMessages } from './en';
+import { ru } from './ru';
+
+export type MessageParams = Readonly<Record<string, string | number>>;
+
+export type TFunction = (key: MessageKey, params?: MessageParams) => string;
+
+const registry = new Map<string, PartialMessages>([
+  ['en', en],
+  ['ru', ru],
+]);
+
+/**
+ * Подключает словарь под кодом языка (`'de'`, `'uk'`, `'pt-BR'`). Словарь может быть неполным: недостающие
+ * ключи берутся из английского. Повторная регистрация того же кода заменяет словарь (в том числе встроенный).
+ */
+export function registerLocale(code: string, messages: PartialMessages): void {
+  registry.set(normalize(code), messages);
+}
+
+export function getLocales(): string[] {
+  return [...registry.keys()];
+}
+
+const normalize = (code: string) => code.trim().toLowerCase();
+
+function lookup(
+  code: string,
+  locales: Readonly<Record<string, PartialMessages>> | undefined,
+): PartialMessages | undefined {
+  const wanted = normalize(code);
+  const own = locales
+    ? Object.fromEntries(Object.entries(locales).map(([key, value]) => [normalize(key), value]))
+    : undefined;
+
+  for (const candidate of [wanted, wanted.split('-')[0]]) {
+    const found = own?.[candidate] ?? registry.get(candidate);
+
+    if (found) return found;
+  }
+
+  return undefined;
+}
+
+export interface ResolveMessagesOptions {
+  readonly locale?: string;
+  readonly locales?: Readonly<Record<string, PartialMessages>>;
+  readonly messages?: PartialMessages;
+}
+
+export function resolveMessages(options: ResolveMessagesOptions = {}): Messages {
+  const base = options.locale ? lookup(options.locale, options.locales) : undefined;
+
+  return { ...en, ...stripEmpty(base), ...stripEmpty(options.messages) };
+}
+
+function stripEmpty(messages: PartialMessages | undefined): PartialMessages {
+  if (!messages) return {};
+
+  return Object.fromEntries(
+    Object.entries(messages).filter(([, value]) => typeof value === 'string'),
+  ) as PartialMessages;
+}
+
+export function interpolate(template: string, params?: MessageParams): string {
+  if (!params) return template;
+
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in params ? String(params[name]) : match,
+  );
+}
+
+export function createTranslator(messages: Messages): TFunction {
+  return (key, params) => interpolate(messages[key] ?? en[key], params);
+}
+
+export const defaultT: TFunction = createTranslator(en);