@jackuait/blok 0.16.1 → 0.17.0

package/src/tools/video/empty-state.ts

@@ -0,0 +1,45 @@
+import { DEFAULT_MIME_TYPES } from './constants';
+import { tr } from './i18n';
+import {
+  renderMediaEmptyState,
+  type MediaEmptyStateElement,
+} from '../../components/utils/media-empty-state';
+import type { I18nInstance } from '../../components/utils/tools';
+
+export interface EmptyStateOptions {
+  onFile(file: File): void;
+  onUrl(url: string): void;
+  /** MIME types to accept on file picker + show in the formats hint. */
+  acceptTypes?: string[];
+  /** Max file size in bytes — surfaced in the formats hint when set. */
+  maxSize?: number;
+  i18n?: I18nInstance;
+}
+
+export type EmptyStateElement = MediaEmptyStateElement;
+
+export function renderEmptyState(opts: EmptyStateOptions): EmptyStateElement {
+  const i18n = opts.i18n;
+  return renderMediaEmptyState({
+    acceptTypes: opts.acceptTypes ?? [...DEFAULT_MIME_TYPES],
+    maxSize: opts.maxSize,
+    onFile: opts.onFile,
+    onUrl: opts.onUrl,
+    labels: {
+      add: tr(i18n, 'tools.video.emptyAddVideo', 'Add a video'),
+      upload: tr(i18n, 'tools.video.emptyUpload', 'Upload'),
+      embed: tr(i18n, 'tools.video.emptyLink', 'Link'),
+      chooseFile: tr(i18n, 'tools.video.emptyChooseFile', 'Choose file'),
+      orDropHere: tr(i18n, 'tools.video.emptyOrDropHere', 'or drop a video here'),
+      dropToUpload: tr(i18n, 'tools.video.emptyDropToUpload', 'Drop to upload'),
+      urlPlaceholder: tr(i18n, 'tools.video.emptyUrlPlaceholder', 'Paste a video URL…'),
+      urlAria: tr(i18n, 'tools.video.emptyUrlAria', 'Video URL'),
+      submit: tr(i18n, 'tools.video.emptyInsert', 'Insert'),
+      sourceAria: tr(i18n, 'tools.video.emptySourceAria', 'Video source'),
+      maxSize: (size) =>
+        i18n?.has('tools.video.emptyMaxSize')
+          ? i18n.t('tools.video.emptyMaxSize', { size })
+          : `max ${size}`,
+    },
+  });
+}

package/src/tools/video/i18n.ts

@@ -0,0 +1,13 @@
+import type { I18nInstance } from '../../components/utils/tools';
+
+/**
+ * Resolve a translation key, falling back to an inline English string when the
+ * host editor has not registered the key. Keeps the video tool usable before
+ * locale messages are wired and gives the i18n regression scan a single place
+ * to find the source copy.
+ */
+export function tr(i18n: I18nInstance | undefined, key: string, fallback: string): string {
+  if (i18n?.has(key)) return i18n.t(key);
+
+  return fallback;
+}

package/src/tools/video/index.ts

@@ -0,0 +1,521 @@
+import type {
+  API,
+  BlockAPI,
+  BlockTool,
+  BlockToolConstructorOptions,
+  FilePasteEvent,
+  PasteConfig,
+  PasteEvent,
+  PatternPasteEvent,
+  ToolboxConfig,
+} from '../../../types';
+import type { MenuConfig } from '../../../types/tools/menu-config';
+import type { VideoAlignment, VideoConfig, VideoData } from '../../../types/tools/video';
+import {
+  IconAlignCenter,
+  IconAlignLeft,
+  IconAlignRight,
+  IconCaption,
+  IconCopy,
+  IconDownload,
+  IconPlayerLoop,
+  IconPlayerPlay,
+  IconPlayerSettings,
+  IconReplace,
+  IconVideo,
+} from '../../components/icons';
+import { attachResizeHandle, type ResizeEdge } from '../image/resizer';
+import { renderUploadingState, type UploadingStateElement } from '../image/uploading-state';
+import { DEFAULT_CAPTION_PLACEHOLDER, MIN_WIDTH_PX, URL_PATTERN } from './constants';
+import { renderEmptyState, type EmptyStateElement } from './empty-state';
+import { tr } from './i18n';
+import { renderCaptionRow, renderVideo } from './ui';
+import { attachControls, type ControlsHandle } from './controls';
+import { Uploader, VideoUploadError, type UploadResult } from './uploader';
+import { uploadErrorMessage } from '../../components/utils/upload-error-message';
+import { pickDisplayMaxSize } from '../../components/utils/max-size';
+
+type ToolState = 'EMPTY' | 'LOADING' | 'RENDERED' | 'ERROR';
+
+export class VideoTool implements BlockTool {
+  private readonly api: API;
+  private readonly block: BlockAPI;
+  private readonly config: VideoConfig;
+  private readonly uploader: Uploader;
+  private data: VideoData;
+  private readOnly: boolean;
+  private root: HTMLElement | null = null;
+  private state: ToolState;
+  private uploadingEl: UploadingStateElement | null = null;
+  private lastFileName: string | null = null;
+  private errorMessage: string | null = null;
+  private lastSource: { kind: 'file'; file: File } | { kind: 'url'; url: string } | null = null;
+  private resizeDetach: (() => void)[] = [];
+  private controlsHandle: ControlsHandle | null = null;
+  // Ephemeral theater (cinema-width) state — presentation only, never saved.
+  private theater = false;
+
+  constructor(options: BlockToolConstructorOptions<VideoData, VideoConfig>) {
+    this.api = options.api;
+    this.block = options.block;
+    this.config = options.config ?? {};
+    this.readOnly = options.readOnly;
+    this.data = { ...options.data, url: options.data?.url ?? '' };
+    this.state = this.data.url ? 'RENDERED' : 'EMPTY';
+    this.uploader = new Uploader(this.config);
+  }
+
+  public render(): HTMLElement {
+    const root = document.createElement('div');
+    root.setAttribute('data-blok-tool', 'video');
+    this.root = root;
+    this.renderState();
+    return root;
+  }
+
+  public save(_block?: HTMLElement): VideoData {
+    const out: VideoData = { url: this.data.url };
+    if (this.data.caption !== undefined) out.caption = this.data.caption;
+    if (this.data.captionVisible !== undefined) out.captionVisible = this.data.captionVisible;
+    if (this.data.width !== undefined) out.width = this.data.width;
+    if (this.data.alignment !== undefined) out.alignment = this.data.alignment;
+    if (this.data.autoplay) out.autoplay = true;
+    if (this.data.loop) out.loop = true;
+    if (this.data.hideControls) out.hideControls = true;
+    if (this.data.fileName !== undefined) out.fileName = this.data.fileName;
+    if (this.data.mimeType !== undefined) out.mimeType = this.data.mimeType;
+    if (this.data.aspectRatio !== undefined) out.aspectRatio = this.data.aspectRatio;
+    return out;
+  }
+
+  public validate(data: VideoData): boolean {
+    return typeof data.url === 'string' && data.url.length > 0;
+  }
+
+  public static get toolbox(): ToolboxConfig {
+    return {
+      icon: IconVideo,
+      titleKey: 'video',
+      searchTerms: ['video', 'movie', 'clip', 'player', 'mp4', 'media'],
+    };
+  }
+
+  public static get isReadOnlySupported(): boolean {
+    return true;
+  }
+
+  public static get pasteConfig(): PasteConfig {
+    return {
+      patterns: { video: URL_PATTERN },
+      files: { mimeTypes: ['video/*'] },
+    };
+  }
+
+  public onPaste(event: PasteEvent): void {
+    if (event.type === 'pattern') {
+      this.applyResult({ url: (event as PatternPasteEvent).detail.data });
+      return;
+    }
+    if (event.type === 'file') {
+      this.startUpload((event as FilePasteEvent).detail.file);
+    }
+  }
+
+  public getToolbarAnchorElement(): HTMLElement | undefined {
+    return this.root?.querySelector<HTMLElement>('[data-role="video-figure"]') ?? undefined;
+  }
+
+  public getContentOffset(_hoveredElement: Element): { left: number } | undefined {
+    const root = this.root;
+    const figure = root?.querySelector<HTMLElement>('[data-role="video-figure"]');
+    if (!root || !figure) return undefined;
+    const delta = figure.getBoundingClientRect().left - root.getBoundingClientRect().left;
+    return delta > 0 ? { left: delta } : undefined;
+  }
+
+  public setReadOnly(state: boolean): void {
+    this.readOnly = state;
+    this.renderState();
+  }
+
+  public renderSettings(): MenuConfig {
+    const i18n = this.api.i18n;
+    const current: VideoAlignment = this.data.alignment ?? 'center';
+    const captionVisible = this.data.captionVisible !== false;
+    const alignments: { value: VideoAlignment; title: string; icon: string }[] = [
+      { value: 'left', title: tr(i18n, 'tools.video.alignmentLeft', 'Align left'), icon: IconAlignLeft },
+      { value: 'center', title: tr(i18n, 'tools.video.alignmentCenter', 'Align center'), icon: IconAlignCenter },
+      { value: 'right', title: tr(i18n, 'tools.video.alignmentRight', 'Align right'), icon: IconAlignRight },
+    ];
+    const alignIcon = alignments.find((a) => a.value === current)?.icon ?? alignments[1].icon;
+
+    return [
+      {
+        icon: alignIcon,
+        title: tr(i18n, 'tools.video.alignment', 'Alignment'),
+        name: 'video-alignment',
+        children: {
+          items: alignments.map((a) => ({
+            icon: a.icon,
+            title: a.title,
+            name: `video-alignment-${a.value}`,
+            isActive: current === a.value,
+            closeOnActivate: true,
+            onActivate: (): void => this.setAlignment(a.value),
+          })),
+        },
+      },
+      {
+        icon: IconCaption,
+        title: tr(i18n, 'tools.video.caption', 'Caption'),
+        name: 'video-caption',
+        isActive: captionVisible,
+        closeOnActivate: true,
+        onActivate: (): void => this.toggleCaption(),
+      },
+      {
+        icon: IconPlayerPlay,
+        title: tr(i18n, 'tools.video.autoplay', 'Autoplay'),
+        name: 'video-autoplay',
+        isActive: this.data.autoplay === true,
+        closeOnActivate: true,
+        onActivate: (): void => this.toggleAutoplay(),
+      },
+      {
+        icon: IconPlayerLoop,
+        title: tr(i18n, 'tools.video.loop', 'Loop'),
+        name: 'video-loop',
+        isActive: this.data.loop === true,
+        closeOnActivate: true,
+        onActivate: (): void => this.toggleLoop(),
+      },
+      {
+        icon: IconPlayerSettings,
+        title: tr(i18n, 'tools.video.hideControls', 'Hide controls'),
+        name: 'video-hide-controls',
+        isActive: this.data.hideControls === true,
+        closeOnActivate: true,
+        onActivate: (): void => this.toggleHideControls(),
+      },
+      {
+        icon: IconReplace,
+        title: tr(i18n, 'tools.video.replace', 'Replace video'),
+        name: 'video-replace',
+        closeOnActivate: true,
+        onActivate: (): void => this.transitionToEmpty(),
+      },
+      {
+        icon: IconDownload,
+        title: tr(i18n, 'tools.video.download', 'Download'),
+        name: 'video-download',
+        closeOnActivate: true,
+        onActivate: (): void => this.download(),
+      },
+      {
+        icon: IconCopy,
+        title: tr(i18n, 'tools.video.copyUrl', 'Copy URL'),
+        name: 'video-copy-url',
+        closeOnActivate: true,
+        onActivate: (): void => this.copyUrl(),
+      },
+    ];
+  }
+
+  public removed(): void {
+    this.detachResize();
+    this.controlsHandle?.destroy();
+    this.controlsHandle = null;
+    if (this.data.url.startsWith('blob:')) {
+      URL.revokeObjectURL(this.data.url);
+    }
+  }
+
+  private startUpload(file: File): void {
+    this.lastFileName = file.name;
+    this.lastSource = { kind: 'file', file };
+    this.state = 'LOADING';
+    this.renderState();
+    void this.uploader
+      .handleFile(file, { onProgress: (p) => this.uploadingEl?.setProgress(p) })
+      .then((result) => this.applyResult(result, file.type))
+      .catch((err) => this.applyError(err));
+  }
+
+  private startUrl(url: string): void {
+    this.lastFileName = null;
+    this.lastSource = { kind: 'url', url };
+    this.state = 'LOADING';
+    this.renderState();
+    void this.uploader
+      .handleUrl(url, { onProgress: (p) => this.uploadingEl?.setProgress(p) })
+      .then((result) => this.applyResult(result))
+      .catch((err) => this.applyError(err));
+  }
+
+  private applyResult(result: UploadResult, mimeType?: string): void {
+    this.data = {
+      ...this.data,
+      url: result.url,
+      fileName: result.fileName ?? this.lastFileName ?? this.data.fileName,
+      mimeType: mimeType || this.data.mimeType,
+    };
+    this.errorMessage = null;
+    this.state = 'RENDERED';
+    this.renderState();
+    this.block.dispatchChange();
+  }
+
+  private applyError(err?: unknown): void {
+    this.errorMessage = err instanceof VideoUploadError
+      ? uploadErrorMessage(err, (key) => this.api.i18n.t(key), {
+        tooLarge: 'tools.video.errorFileTooLarge',
+        generic: 'tools.video.errorUploadFailed',
+      })
+      : null;
+    this.state = 'ERROR';
+    this.renderState();
+  }
+
+  private detachResize(): void {
+    while (this.resizeDetach.length > 0) {
+      this.resizeDetach.pop()?.();
+    }
+  }
+
+  private syncRootAttributes(): void {
+    if (!this.root) return;
+    const r = this.root;
+    r.setAttribute('data-state', this.state.toLowerCase());
+    r.setAttribute('data-align', this.data.alignment ?? 'center');
+    r.setAttribute('data-caption', this.data.captionVisible === false ? 'off' : 'on');
+    r.setAttribute('data-controls', this.data.hideControls === true ? 'off' : 'on');
+  }
+
+  private renderState(): void {
+    if (!this.root) return;
+    this.detachResize();
+    this.controlsHandle?.destroy();
+    this.controlsHandle = null;
+    this.root.replaceChildren();
+    this.uploadingEl = null;
+    this.syncRootAttributes();
+
+    if (this.state === 'EMPTY') {
+      this.renderEmpty();
+      return;
+    }
+    if (this.state === 'LOADING') {
+      this.renderLoading();
+      return;
+    }
+    if (this.state === 'ERROR') {
+      this.renderError();
+      return;
+    }
+    this.renderRendered();
+  }
+
+  private renderEmpty(): void {
+    if (!this.root) return;
+    const el: EmptyStateElement = renderEmptyState({
+      onFile: (file) => this.startUpload(file),
+      onUrl: (url) => this.startUrl(url),
+      acceptTypes: this.config.types,
+      maxSize: pickDisplayMaxSize(this.config.maxSize),
+      i18n: this.api.i18n,
+    });
+    this.root.appendChild(el);
+  }
+
+  private renderLoading(): void {
+    if (!this.root) return;
+    this.uploadingEl = renderUploadingState({
+      fileName: this.lastFileName ?? tr(this.api.i18n, 'tools.video.uploading', 'Uploading…'),
+      onCancel: () => this.transitionToEmpty(),
+      i18n: this.api.i18n,
+    });
+    this.root.appendChild(this.uploadingEl);
+  }
+
+  private renderError(): void {
+    if (!this.root) return;
+    const wrap = document.createElement('div');
+    wrap.className = 'blok-video-error-state';
+    wrap.setAttribute('data-role', 'video-error');
+
+    const message = document.createElement('span');
+    message.textContent = this.errorMessage ?? tr(this.api.i18n, 'tools.video.errorUploadFailed', 'Upload failed');
+
+    const retry = document.createElement('button');
+    retry.type = 'button';
+    retry.className = 'blok-video-retry';
+    retry.setAttribute('data-action', 'replace');
+    retry.textContent = tr(this.api.i18n, 'tools.video.errorReplace', 'Replace');
+    retry.addEventListener('click', () => this.transitionToEmpty());
+
+    wrap.append(message, retry);
+    this.root.appendChild(wrap);
+  }
+
+  private renderRendered(): void {
+    if (!this.root) return;
+    const figure = renderVideo(this.data);
+    const media = figure.querySelector<HTMLElement>('[data-role="video-media"]') ?? figure;
+
+    // Custom playback controls replace the native chrome — available to
+    // viewers too, so they attach regardless of read-only.
+    const video = media.querySelector('video');
+    if (video) {
+      // Loop is content — honour it in both modes. Autoplay is a read-only viewer
+      // affordance: muted + autoplay + loop turns the block into a gif. Browsers
+      // only honour autoplay when muted, so we mute here; editing never autoplays.
+      video.loop = this.data.loop === true;
+      if (this.readOnly && this.data.autoplay === true) {
+        video.muted = true;
+        video.setAttribute('muted', '');
+        video.setAttribute('autoplay', '');
+      }
+      // "Hide controls" tune renders a clean, control-free frame — the custom
+      // chrome is skipped entirely (native controls were never attached). Loop
+      // and autoplay above still apply: they are content/viewer affordances.
+      if (this.data.hideControls !== true) {
+        this.controlsHandle = attachControls({
+          video,
+          figure,
+          glow: this.config.glow ?? 'minimal',
+          loop: this.data.loop === true,
+        });
+        media.appendChild(this.controlsHandle.element);
+      }
+
+      // When metadata arrives, update the media wrapper's aspect ratio so it
+      // matches the video's intrinsic dimensions.  If the ratio differs from
+      // the default 16 : 9 (or a previously stored value) we persist it so
+      // subsequent renders skip the layout pop.
+      video.addEventListener('loadedmetadata', () => {
+        if (video.videoWidth > 0 && video.videoHeight > 0) {
+          const ratio = `${video.videoWidth} / ${video.videoHeight}`;
+          if (ratio !== this.data.aspectRatio) {
+            this.data.aspectRatio = ratio;
+            media.style.aspectRatio = ratio;
+            this.block.dispatchChange();
+          }
+        }
+      }, { once: true });
+    }
+
+    // Theater is an ephemeral view mode: observe the player's toggle to keep our
+    // copy, and re-apply it after a re-render so alignment/caption changes don't
+    // eject the viewer. Never written to save() — presentation, not content.
+    figure.addEventListener('blok-video-theater', (event) => {
+      this.theater = (event as CustomEvent<{ on: boolean }>).detail.on;
+    });
+    if (this.theater) this.controlsHandle?.setTheater(true);
+
+    const placeholder = this.config.captionPlaceholder ?? DEFAULT_CAPTION_PLACEHOLDER;
+    const captionVisible = this.data.captionVisible !== false;
+    if (captionVisible || !this.readOnly) {
+      figure.appendChild(renderCaptionRow({
+        value: this.data.caption ?? '',
+        placeholder,
+        readOnly: this.readOnly,
+        onChange: (next) => {
+          if (next !== this.data.caption) {
+            this.data.caption = next;
+            this.block.dispatchChange();
+          }
+        },
+      }));
+    }
+
+    this.root.appendChild(figure);
+
+    if (!this.readOnly) {
+      this.attachResizeHandles(figure);
+    }
+  }
+
+  private attachResizeHandles(figure: HTMLElement): void {
+    const edges: ResizeEdge[] = ['left', 'right'];
+    for (const edge of edges) {
+      const handle = document.createElement('div');
+      handle.setAttribute('data-role', 'resize-handle');
+      handle.setAttribute('data-edge', edge);
+      figure.appendChild(handle);
+      const detach = attachResizeHandle({
+        handle,
+        figure,
+        container: figure.parentElement ?? figure,
+        edge,
+        alignment: this.data.alignment ?? 'center',
+        minWidthPx: MIN_WIDTH_PX,
+        onPreview: (percent) => {
+          figure.style.setProperty('width', `${percent}%`);
+        },
+        onCommit: (percent) => {
+          this.data.width = percent;
+          this.block.dispatchChange();
+        },
+      });
+      this.resizeDetach.push(detach);
+    }
+  }
+
+  private setAlignment(next: VideoAlignment): void {
+    if (this.data.alignment === next) return;
+    this.data.alignment = next;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private toggleCaption(): void {
+    this.data.captionVisible = this.data.captionVisible === false;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private toggleAutoplay(): void {
+    this.data.autoplay = this.data.autoplay !== true ? true : undefined;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private toggleLoop(): void {
+    this.data.loop = this.data.loop !== true ? true : undefined;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private toggleHideControls(): void {
+    this.data.hideControls = this.data.hideControls !== true ? true : undefined;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private transitionToEmpty(): void {
+    this.data = { ...this.data, url: '' };
+    this.state = 'EMPTY';
+    this.lastSource = null;
+    this.lastFileName = null;
+    this.renderState();
+    this.block.dispatchChange();
+  }
+
+  private download(): void {
+    const a = document.createElement('a');
+    a.href = this.data.url;
+    a.download = this.data.fileName ?? '';
+    a.target = '_blank';
+    a.rel = 'noopener';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+  }
+
+  private copyUrl(): void {
+    const clip = navigator.clipboard;
+    if (clip && typeof clip.writeText === 'function') {
+      void clip.writeText(this.data.url);
+    }
+  }
+}

package/src/tools/video/ui.ts

@@ -0,0 +1,83 @@
+import type { VideoAlignment, VideoData } from '../../../types/tools/video';
+
+const ALIGN_TO_TEXT_ALIGN: Record<VideoAlignment, string> = {
+  left: 'left',
+  center: 'center',
+  right: 'right',
+};
+
+export function renderVideo(data: Partial<VideoData> & { url: string }): HTMLElement {
+  const alignment = data.alignment ?? 'center';
+  const figure = document.createElement('figure');
+  figure.className = 'blok-video-inner';
+  figure.setAttribute('data-role', 'video-figure');
+  figure.style.margin = '0';
+  figure.style.textAlign = ALIGN_TO_TEXT_ALIGN[alignment];
+  figure.style.position = 'relative';
+  if (data.width !== undefined) {
+    figure.style.width = `${data.width}%`;
+  }
+
+  // The media wrapper hugs the player pixels and anchors the overlaid chrome
+  // (custom controls, edit toolbar, resize handles) so they sit over the video
+  // only — never over the caption row below.
+  const media = document.createElement('div');
+  media.className = 'blok-video-media';
+  media.setAttribute('data-role', 'video-media');
+  media.style.position = 'relative';
+  // Reserve space before loadedmetadata fires — without this the <video>
+  // collapses to zero height then "pops" when the browser learns the
+  // intrinsic ratio (the "squeeze" visual glitch on load).
+  media.style.aspectRatio = data.aspectRatio ?? '16 / 9';
+
+  // No native `controls` — a custom Airbnb-style control surface is attached
+  // separately (see controls.ts) and fully replaces the browser chrome.
+  const video = document.createElement('video');
+  video.setAttribute('data-blok-testid', 'video-player');
+  video.setAttribute('playsinline', '');
+  video.setAttribute('preload', 'metadata');
+  // Focusable so the player can field keyboard control (seek, volume, speed,
+  // play/pause, mute, fullscreen) à la a native player.
+  video.setAttribute('tabindex', '0');
+  video.setAttribute(
+    'aria-keyshortcuts',
+    'Space k j l ArrowLeft ArrowRight ArrowUp ArrowDown m f Home End',
+  );
+  video.setAttribute('src', data.url);
+  video.style.width = '100%';
+  video.style.display = 'block';
+  media.appendChild(video);
+  figure.appendChild(media);
+
+  return figure;
+}
+
+export interface CaptionRowOptions {
+  value: string;
+  placeholder: string;
+  readOnly: boolean;
+  onChange(next: string): void;
+}
+
+export function renderCaptionRow(opts: CaptionRowOptions): HTMLElement {
+  const row = document.createElement('div');
+  row.className = 'blok-video-caption-row';
+  row.setAttribute('data-role', 'video-caption-row');
+
+  const caption = document.createElement('div');
+  caption.className = 'blok-video-caption';
+  caption.setAttribute('data-role', 'video-caption');
+  caption.setAttribute('role', 'textbox');
+  caption.setAttribute('contenteditable', opts.readOnly ? 'false' : 'true');
+  caption.setAttribute('data-placeholder', opts.placeholder);
+  caption.textContent = opts.value;
+  caption.style.outline = 'none';
+  caption.style.textAlign = 'left';
+
+  if (!opts.readOnly) {
+    caption.addEventListener('blur', () => opts.onChange(caption.textContent ?? ''));
+  }
+
+  row.appendChild(caption);
+  return row;
+}