@cloud-ru/ds-markdown 1.0.0

package/src/components/MarkdownEditor/styles.module.scss

@@ -0,0 +1,201 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/markdown.module' as md;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/field.module' as field;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/scroll.module' as scroll;
+@use '../../mixins' as mx;
+
+// Внутренние отступы контента поверх паддинга fieldContainer (его задаёт FieldShell):
+// повторяют contentWrapper.verticalPadding + inputLine.horizontalPadding из field-токенов.
+$content-padding-vertical: field.$sn-field-anatomy-size-m-fieldContainer-contentWrapper-verticalPadding;
+$content-padding-horizontal: field.$sn-field-anatomy-size-m-fieldContainer-paddingRight;
+$min-height: field.$sn-field-anatomy-size-m-fieldContainer-multiLine-minHeight;
+$scrollbar-width: base.simple-var(scroll.$scroll, 'anatomy', 'container', 'size', 's', 'width');
+$button-slot: field.$sn-field-anatomy-size-m-fieldContainer-centeredWrapper-maxHeight;
+$input-line-padding: field.$sn-field-anatomy-size-m-fieldContainer-contentWrapper-inputLine-horizontalPadding;
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: md.$sn-markdown-anatomy-size-container-gap;
+  box-sizing: border-box;
+}
+
+// Шапка (headlineWrapper) — вне поля: тогл Preview слева, подпись справа.
+.header {
+  display: flex;
+  gap: base.$sn-primitive-dimension-8;
+  align-items: center;
+  justify-content: space-between;
+
+  font-family: md.$sn-brand-font-fontFamily-regular-body;
+  font-size: md.$sn-density-typography-roleBody-fontSizeS;
+  line-height: md.$sn-density-typography-roleBody-lineHeightS;
+  color: md.$sn-theme-color-available-version-textSecondary;
+}
+
+.previewToggle {
+  cursor: pointer;
+  user-select: none;
+
+  display: inline-flex;
+  gap: md.$sn-markdown-anatomy-size-container-headlineWrapper-headline-gap;
+  align-items: center;
+}
+
+// Подпись тогла крупнее подписи справа: в мастере это body/m, а не body/s шапки.
+.previewToggleLabel {
+  @include base.composite-var(base.$sn-regular, 'body', 'm');
+
+  color: base.$sn-theme-color-neutral-text;
+}
+
+.label {
+  color: md.$sn-theme-color-available-version-textTertiary;
+}
+
+// Слот тулбара в header-слоте оболочки: растягивается на всю ширину и даёт тулбару
+// сжиматься (Toolbar-root имеет flex-shrink: 0), иначе overflow в More не срабатывает.
+.toolbarSlot {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+// Контентная область поля: общий контейнер для textarea (raw) и EditorContent (preview).
+// position: relative — якорь для overlay-кнопки очистки.
+.contentArea {
+  position: relative;
+
+  display: flex;
+
+  box-sizing: border-box;
+  width: 100%;
+  padding: $content-padding-vertical $content-padding-horizontal;
+}
+
+// Общий resize-бокс: один и тот же DOM-узел в обоих режимах, поэтому заданная ресайзом
+// высота сохраняется при переключении preview. Потомок (textarea/EditorContent) скроллится
+// внутри (native overflow), бокс лишь задаёт высоту.
+.resizeBox {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+
+  min-width: 0;
+  min-height: $min-height;
+}
+
+// При resizable — вертикальный CSS-resize со стартовой высотой min-height (иначе resize
+// не от чего отсчитывать); overflow != visible нужен, чтобы появился resize-handle.
+.resizeBoxResizable {
+  resize: vertical;
+  overflow: hidden;
+  height: $min-height;
+}
+
+.postfix {
+  $square: field.$sn-field-anatomy-size-m-fieldContainer-centeredWrapper-maxHeight;
+  $input-line-padding: field.$sn-field-anatomy-size-m-fieldContainer-contentWrapper-inputLine-horizontalPadding;
+  $line-height: base.$sn-regular-body-m-lineHeight;
+  $vertical-padding: field.$sn-field-anatomy-size-m-fieldContainer-contentWrapper-verticalPadding;
+
+  position: absolute;
+
+  // Кнопка центрируется по первой строке текста: verticalPadding (отступ контента сверху)
+  // + центровка слота в line-height. Так 32px-кнопка верхним краем садится ровно на
+  // внутреннюю границу поля (Figma), а не выступает над ней.
+  top: calc(#{$vertical-padding} + (#{$line-height} - #{$square}) / 2);
+  right: calc(#{$scrollbar-width} + #{$input-line-padding});
+
+  display: grid;
+  grid-auto-rows: $square;
+
+  // Единственный явный column-track шириной с контейнер: без него implicit-колонка
+  // растягивается (auto) под кнопку, и кнопка перестаёт центрироваться по слоту.
+  grid-template-columns: 100%;
+  row-gap: base.$sn-primitive-dimension-2;
+  place-items: center center;
+
+  width: $square;
+}
+
+.rawInputWrapper {
+  display: flex;
+  width: 100%;
+  height: 100%;
+}
+
+// raw-режим: «сырой» markdown в textarea. Native-скролл при переполнении resize-бокса.
+.rawInput {
+  resize: none;
+
+  overflow-y: auto;
+  flex: 1 1 auto;
+
+  min-height: 0;
+  padding: 0;
+  padding-right: calc(#{$button-slot} + #{$scrollbar-width} + #{$input-line-padding});
+  border: none;
+
+  font-family: md.$sn-brand-font-fontFamily-regular-body;
+  font-size: md.$sn-density-typography-roleBody-fontSizeM;
+  line-height: md.$sn-density-typography-roleBody-lineHeightM;
+  color: md.$sn-theme-color-available-version-textMain;
+
+  background: transparent;
+  outline: none;
+
+  &::placeholder {
+    color: base.$sn-theme-color-available-version-textDisabled;
+  }
+}
+
+// preview-режим: WYSIWYG (EditorContent). Заполняет resize-бокс, скроллится при переполнении.
+.content {
+  overflow-y: auto;
+  flex: 1 1 auto;
+
+  min-height: 0;
+
+  font-family: md.$sn-brand-font-fontFamily-regular-body;
+  font-size: md.$sn-density-typography-roleBody-fontSizeM;
+  line-height: md.$sn-density-typography-roleBody-lineHeightM;
+  color: md.$sn-theme-color-available-version-textMain;
+
+  :global(.ProseMirror) {
+    min-height: 100%;
+    padding-right: calc(#{$button-slot} + #{$scrollbar-width} + #{$input-line-padding});
+    outline: none;
+
+    @include mx.markdown-content;
+    @include mx.markdown-block-spacings;
+
+    pre {
+      overflow-x: auto;
+      padding: base.$sn-primitive-dimension-12;
+      border-radius: md.$sn-density-radius-2xs;
+      background: md.$sn-theme-color-neutral-background2Level;
+
+      code {
+        min-height: 0;
+        padding: 0;
+        background: transparent;
+      }
+    }
+
+    :global(p.is-editor-empty:first-child)::before {
+      pointer-events: none;
+      content: attr(data-placeholder);
+
+      float: left;
+
+      height: 0;
+
+      color: base.$sn-theme-color-available-version-textDisabled;
+    }
+
+    img {
+      max-width: 100%;
+      height: auto;
+    }
+  }
+}

package/src/components/Toolbar/Toolbar.tsx

@@ -0,0 +1,292 @@
+import { ChevronRightSVG, MoreSVG } from '@cloud-ru/ds-icons/interface/system';
+import { Droplist, DroplistProps, ItemProps } from '@cloud-ru/ds-list';
+import { usePortalContext } from '@cloud-ru/ds-portal-context';
+import { Tooltip } from '@cloud-ru/ds-tooltip';
+import { Fragment, useCallback, useEffect, useMemo, useState } from 'react';
+
+import { TEST_IDS, TOOLBAR_ITEM, toolbarButtonTestId } from '../../constants';
+import {
+  ButtonHeading,
+  Buttons,
+  ButtonsDivider,
+  ButtonsGroup,
+  CustomizeTableModal,
+  ImageModal,
+  LinkModal,
+  LinkProps,
+  PrivateButton,
+  PrivateButtonProps,
+  TableSelectSettingsGrid,
+} from '../../helperComponents';
+import { markdownLocale } from '../../locale';
+import { ToolbarApi } from '../../toolbarApi';
+import { ToolbarItemId } from '../../types';
+import { BUTTONS, GROUPS } from './constants';
+import { useToolbarHotkeys, useToolbarOverflow } from './hooks';
+import styles from './styles.module.scss';
+
+type ToolbarProps = {
+  /** Бэкенд команд: WYSIWYG (TipTap) в preview-режиме либо markdown-исходник (textarea) в raw-режиме. */
+  api: ToolbarApi;
+  items: ToolbarItemId[];
+};
+
+export function Toolbar({ api, items }: ToolbarProps) {
+  const portalContext = usePortalContext();
+  const { t } = markdownLocale.useTranslations();
+
+  // Overflow тулбара (сколько кнопок видно, остальные — в «Ещё») вынесен в хук.
+  const { rootRef, moreButtonRef, visibleCount } = useToolbarOverflow(items);
+  const [moreOpen, setMoreOpen] = useState(false);
+  const [tableOpen, setTableOpen] = useState(false);
+  const [linkInitial, setLinkInitial] = useState<LinkProps | undefined>(undefined);
+
+  const [toolbarItemModal, setToolbarItemModal] = useState<'image' | 'link' | 'table'>();
+
+  // Закрывает оба table-picker'а и открывает модалку настройки размеров.
+  const openCustomize = useCallback(() => {
+    setTableOpen(false);
+    setMoreOpen(false);
+    setToolbarItemModal('table');
+  }, []);
+
+  const openLink = useCallback(() => {
+    setMoreOpen(false);
+
+    // raw-режим: ссылка добавляется как сырой markdown-шаблон прямо в textarea, без модалки.
+    if (api.mode === 'raw') {
+      api.setLink({});
+      return;
+    }
+
+    setLinkInitial({
+      href: api.getLinkHref(),
+      title: api.getLinkTitle(),
+    });
+    setToolbarItemModal('link');
+  }, [api]);
+
+  const openImage = useCallback(() => {
+    setMoreOpen(false);
+    setToolbarItemModal('image');
+  }, []);
+
+  const closeToolbarItemModal = () => {
+    setToolbarItemModal(undefined);
+    api.focus();
+  };
+
+  // Принудительный re-render тулбара на selection/transaction → переключаются checked-стейты кнопок.
+  const [, setTick] = useState(0);
+  useEffect(() => api.subscribe(() => setTick(n => n + 1)), [api]);
+
+  useToolbarHotkeys({ rootRef, items, api, onLink: openLink, onImage: openImage });
+
+  const toolbarTableItems = useMemo<DroplistProps['items']>(
+    () => [
+      {
+        content: (
+          <TableSelectSettingsGrid
+            onPick={(rows, cols) => {
+              api.insertTable(rows, cols);
+              setTableOpen(false);
+              setMoreOpen(false);
+            }}
+          />
+        ),
+        inactive: true,
+      },
+      { type: 'group', content: '', divider: true },
+      {
+        content: {
+          label: t('table.customize'),
+          className: styles.tableCustomizeOption,
+        },
+        onClick: openCustomize,
+        afterContent: <ChevronRightSVG />,
+        'data-test-id': TEST_IDS.tableCustomize,
+      },
+    ],
+    [api, t, openCustomize],
+  );
+
+  const renderItem = (id: ToolbarItemId) => {
+    const spec = BUTTONS[id];
+
+    if (!spec) {
+      return null;
+    }
+
+    const name = t(spec.nameKey);
+
+    const commonButtonProps: PrivateButtonProps = {
+      id,
+      icon: spec.icon,
+      'data-test-id': toolbarButtonTestId(id),
+      'aria-label': name,
+      tip: { title: name, caption: spec.hotkey },
+      checked: api.isActive(id),
+      onClick: () => api.toggle(id),
+    };
+
+    if (id === TOOLBAR_ITEM.Heading) {
+      return <ButtonHeading key={id} api={api} />;
+    }
+
+    if (id === TOOLBAR_ITEM.Link && spec) {
+      commonButtonProps.onClick = openLink;
+    }
+
+    if (id === TOOLBAR_ITEM.Image) {
+      commonButtonProps.onClick = openImage;
+    }
+
+    if (id === TOOLBAR_ITEM.Table && spec) {
+      return (
+        <Droplist
+          size='m'
+          container={portalContext}
+          key={id}
+          open={tableOpen}
+          onOpenChange={setTableOpen}
+          placement='bottom-start'
+          triggerClassName={styles.tooltipTrigger}
+          items={toolbarTableItems}
+        >
+          <PrivateButton key={id} {...commonButtonProps} />
+        </Droplist>
+      );
+    }
+
+    return <PrivateButton key={id} {...commonButtonProps} />;
+  };
+
+  // Решаем, какие items видимы, группируем под GROUPS, рисуем дивайдеры между группами.
+  const visibleItems = new Set(items.slice(0, visibleCount));
+  const overflowItems = items.slice(visibleCount);
+  const presentGroups = GROUPS.map(group => group.filter(id => visibleItems.has(id))).filter(g => g.length > 0);
+
+  const handleMoreSelect = (id: ToolbarItemId) => {
+    if (id === TOOLBAR_ITEM.Table) {
+      // Table-picker открывается вторым уровнем, якорь — More-кнопка (childless Dropdown + triggerRef).
+      setTableOpen(true);
+      return;
+    }
+
+    if (id === TOOLBAR_ITEM.Link) {
+      openLink();
+    } else if (id === TOOLBAR_ITEM.Image) {
+      openImage();
+    } else {
+      setMoreOpen(false);
+      api.toggle(id);
+    }
+  };
+
+  const handleSubmitCustomizeTable: ToolbarApi['insertTable'] = (rows, cols) => {
+    api.insertTable(rows, cols);
+    closeToolbarItemModal();
+    setMoreOpen(false);
+  };
+
+  const handleLinkSubmit: ToolbarApi['setLink'] = linkProps => {
+    api.setLink(linkProps);
+    closeToolbarItemModal();
+  };
+
+  const handleImageSubmit: ToolbarApi['insertImage'] = (url, alt) => {
+    api.insertImage(url, alt);
+    closeToolbarItemModal();
+  };
+
+  // Строки More-списка: иконка + подпись + хоткей справа (caption).
+  const moreItems = overflowItems.flatMap((id): ItemProps[] => {
+    const spec = BUTTONS[id];
+
+    if (!spec) return [];
+
+    const base = {
+      id,
+      beforeContent: spec?.icon,
+      content: { label: t(spec.nameKey), caption: spec.hotkey },
+      onClick: () => handleMoreSelect(id),
+      'data-test-id': toolbarButtonTestId(id),
+    };
+
+    if (id === TOOLBAR_ITEM.Table) {
+      return [
+        {
+          ...base,
+          type: 'next-list',
+          items: toolbarTableItems,
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        beforeContent: spec.icon,
+        content: { label: t(spec.nameKey), caption: spec.hotkey },
+        checked: api.isActive(id),
+      },
+    ];
+  });
+
+  return (
+    <div ref={rootRef} className={styles.root}>
+      <Buttons>
+        {presentGroups.map((group, gi) => (
+          <Fragment key={`g-${gi}`}>
+            {gi > 0 && <ButtonsDivider />}
+            <ButtonsGroup>{group.map(renderItem)}</ButtonsGroup>
+          </Fragment>
+        ))}
+
+        {overflowItems.length > 0 && (
+          <>
+            <ButtonsDivider />
+
+            <Droplist
+              size='m'
+              container={portalContext}
+              open={moreOpen}
+              onOpenChange={setMoreOpen}
+              placement='bottom-end'
+              marker={false}
+              items={moreItems}
+              triggerElemRef={moreButtonRef}
+              triggerClassName={styles.tooltipTrigger}
+              data-test-id={TEST_IDS.toolbarMoreList}
+            >
+              <Tooltip tip={t('toolbar.more')} triggerClassName={styles.tooltipTrigger}>
+                <PrivateButton
+                  icon={<MoreSVG />}
+                  data-test-id={TEST_IDS.toolbarMore}
+                  aria-label={t('toolbar.more')}
+                  aria-haspopup='menu'
+                  aria-expanded={moreOpen}
+                />
+              </Tooltip>
+            </Droplist>
+          </>
+        )}
+      </Buttons>
+
+      <CustomizeTableModal
+        open={toolbarItemModal === 'table'}
+        onClose={closeToolbarItemModal}
+        onSubmit={handleSubmitCustomizeTable}
+      />
+
+      <LinkModal
+        open={toolbarItemModal === 'link'}
+        initial={linkInitial}
+        onClose={closeToolbarItemModal}
+        onSubmit={handleLinkSubmit}
+      />
+
+      <ImageModal open={toolbarItemModal === 'image'} onClose={closeToolbarItemModal} onSubmit={handleImageSubmit} />
+    </div>
+  );
+}

package/src/components/Toolbar/constants.tsx

@@ -0,0 +1,63 @@
+import {
+  BlockCodeSVG,
+  BlockQuoteSVG,
+  BoldSVG,
+  BulletListSVG,
+  HeadingSVG,
+  ImageSVG,
+  InlineCodeSVG,
+  ItalicSVG,
+  LinkSVG,
+  OrderedListSVG,
+  StrikeSVG,
+  TableSVG,
+} from '@cloud-ru/ds-icons/interface/system';
+import { ReactNode } from 'react';
+
+import { TOOLBAR_ITEM } from '../../constants';
+import { MarkdownMessages } from '../../locale';
+import { ToolbarItemId } from '../../types';
+
+// Группировка: text-style | inline | lists | blocks | media.
+export const GROUPS: ToolbarItemId[][] = [
+  [TOOLBAR_ITEM.Heading, TOOLBAR_ITEM.Bold, TOOLBAR_ITEM.Italic, TOOLBAR_ITEM.Strikethrough],
+  [TOOLBAR_ITEM.Link, TOOLBAR_ITEM.InlineCode, TOOLBAR_ITEM.BulletList, TOOLBAR_ITEM.OrderedList],
+  [TOOLBAR_ITEM.BlockQuote, TOOLBAR_ITEM.BlockCode, TOOLBAR_ITEM.Table, TOOLBAR_ITEM.Image],
+];
+
+type ButtonSpec = {
+  icon: ReactNode;
+  nameKey: `toolbar.${Extract<keyof MarkdownMessages['toolbar'], string>}`;
+  /** Хоткей для строки в More-списке. Только реально работающие биндинги TipTap. */
+  hotkey?: string;
+};
+
+export const BUTTONS: Record<ToolbarItemId, ButtonSpec> = {
+  [TOOLBAR_ITEM.Heading]: { icon: <HeadingSVG />, nameKey: 'toolbar.heading' },
+  [TOOLBAR_ITEM.Bold]: { icon: <BoldSVG />, nameKey: 'toolbar.bold', hotkey: 'Ctrl+B' },
+  [TOOLBAR_ITEM.Italic]: { icon: <ItalicSVG />, nameKey: 'toolbar.italic', hotkey: 'Ctrl+I' },
+  [TOOLBAR_ITEM.Strikethrough]: { icon: <StrikeSVG />, nameKey: 'toolbar.strikethrough', hotkey: 'Ctrl+Shift+X' },
+  [TOOLBAR_ITEM.Link]: { icon: <LinkSVG />, nameKey: 'toolbar.link', hotkey: 'Ctrl+K' },
+  [TOOLBAR_ITEM.Image]: { icon: <ImageSVG />, nameKey: 'toolbar.image', hotkey: 'Ctrl+Shift+I' },
+  [TOOLBAR_ITEM.Table]: { icon: <TableSVG />, nameKey: 'toolbar.table' },
+  [TOOLBAR_ITEM.InlineCode]: { icon: <InlineCodeSVG />, nameKey: 'toolbar.inlineCode', hotkey: 'Ctrl+E' },
+  [TOOLBAR_ITEM.BulletList]: { icon: <BulletListSVG />, nameKey: 'toolbar.bulletList', hotkey: 'Ctrl+Shift+8' },
+  [TOOLBAR_ITEM.OrderedList]: { icon: <OrderedListSVG />, nameKey: 'toolbar.orderedList', hotkey: 'Ctrl+Shift+7' },
+  [TOOLBAR_ITEM.BlockQuote]: { icon: <BlockQuoteSVG />, nameKey: 'toolbar.blockQuote', hotkey: 'Ctrl+Shift+B' },
+  [TOOLBAR_ITEM.BlockCode]: { icon: <BlockCodeSVG />, nameKey: 'toolbar.blockCode', hotkey: 'Ctrl+Alt+C' },
+};
+
+export const DEFAULT_TOOLBAR: ToolbarItemId[] = [
+  TOOLBAR_ITEM.Heading,
+  TOOLBAR_ITEM.Bold,
+  TOOLBAR_ITEM.Italic,
+  TOOLBAR_ITEM.Strikethrough,
+  TOOLBAR_ITEM.Link,
+  TOOLBAR_ITEM.InlineCode,
+  TOOLBAR_ITEM.BulletList,
+  TOOLBAR_ITEM.OrderedList,
+  TOOLBAR_ITEM.BlockQuote,
+  TOOLBAR_ITEM.BlockCode,
+  TOOLBAR_ITEM.Table,
+  TOOLBAR_ITEM.Image,
+];

package/src/components/Toolbar/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useToolbarHotkeys';
+export * from './useToolbarOverflow';

package/src/components/Toolbar/hooks/useToolbarHotkeys.ts

@@ -0,0 +1,74 @@
+import { RefObject, useEffect } from 'react';
+
+import { TOOLBAR_ITEM } from '../../../constants';
+import { ToolbarApi } from '../../../toolbarApi';
+import { ToolbarItemId } from '../../../types';
+import { BUTTONS } from '../constants';
+
+// Сопоставляет KeyboardEvent с хоткеем вида 'Ctrl+Shift+I' (Cmd подменяет Ctrl на macOS).
+const matchesHotkey = (event: KeyboardEvent, hotkey: string) => {
+  const parts = hotkey.toLowerCase().split('+');
+  const last = parts[parts.length - 1];
+  // С Shift цифры дают символ (Shift+8 → '*'), поэтому помимо event.key матчим и по event.code
+  // (Digit8 / KeyB) — иначе Ctrl+Shift+8/7 не распознались бы.
+  const code = event.code.toLowerCase();
+  const keyMatches = event.key.toLowerCase() === last || code === `key${last}` || code === `digit${last}`;
+  return (
+    (event.ctrlKey || event.metaKey) === parts.includes('ctrl') &&
+    event.shiftKey === parts.includes('shift') &&
+    event.altKey === parts.includes('alt') &&
+    keyMatches
+  );
+};
+
+type ToolbarHotkeysParams = {
+  /** Корень тулбара (из useToolbarOverflow) — от его родителя ищем scope-предка для listener'а. */
+  rootRef: RefObject<HTMLDivElement | null>;
+  items: ToolbarItemId[];
+  api: ToolbarApi;
+  /** Действие кнопки Link (открыть модалку или вставить сырой markdown). */
+  onLink(): void;
+  /** Действие кнопки Image (открыть модалку). */
+  onImage(): void;
+};
+
+/**
+ * Вешает хоткеи тулбара на корень редактора (scope), а не на конкретный input:
+ * - Link/Image открывают UI (модалку/пикер), а не команды TipTap → биндим всегда;
+ * - остальные кнопки (bold/italic/…) в WYSIWYG обрабатывает сам keymap TipTap, а в raw-режиме
+ *   textarea их не знает, поэтому в raw биндим все hotkey'и на api-команды вручную.
+ */
+export function useToolbarHotkeys({ rootRef, items, api, onLink, onImage }: ToolbarHotkeysParams) {
+  useEffect(() => {
+    // Ищем scope от РОДИТЕЛЯ тулбара: у самого toolbar-root есть data-test-id, и closest вернул бы
+    // его же — а input (textarea/ProseMirror) лежит рядом, не внутри тулбара. Нужен общий предок
+    // (оболочка поля), который содержит и тулбар, и input, чтобы keydown из input всплывал к нему.
+    const scope = rootRef.current?.parentElement?.closest<HTMLElement>('[data-test-id]');
+    if (!scope) return;
+
+    const bindings: { hotkey: string; action: () => void }[] = [];
+    for (const id of items) {
+      const hotkey = BUTTONS[id]?.hotkey;
+      if (!hotkey) continue;
+
+      if (id === TOOLBAR_ITEM.Link) {
+        bindings.push({ hotkey, action: onLink });
+      } else if (id === TOOLBAR_ITEM.Image) {
+        bindings.push({ hotkey, action: onImage });
+      } else if (api.mode === 'raw') {
+        bindings.push({ hotkey, action: () => api.toggle(id) });
+      }
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const hit = bindings.find(binding => matchesHotkey(event, binding.hotkey));
+      if (hit) {
+        event.preventDefault();
+        hit.action();
+      }
+    };
+
+    scope.addEventListener('keydown', handleKeyDown);
+    return () => scope.removeEventListener('keydown', handleKeyDown);
+  }, [items, api, onLink, onImage, rootRef]);
+}