@riducms/plugin-richtext 0.1.0

package/src/menu/rich-text-block-toolbar.svelte

@@ -0,0 +1,323 @@
+<script lang="ts">
+	import { getAdminI18n, type FieldAuthoringHost } from "@riducms/plugin";
+	import {
+		CommandInput,
+		CommandRoot,
+		PopoverContent,
+		PopoverRoot,
+		ToolbarButton,
+		ToolbarRoot,
+		TooltipContent,
+		TooltipRoot,
+		TooltipTrigger,
+	} from "@riducms/ui";
+	import { DraggableBlockPlugin, useLexicalComposerContext } from "@hvniel/lexical-svelte";
+	import { mergeRegister } from "@lexical/utils";
+	import {
+		$createParagraphNode,
+		$createTextNode,
+		$getNearestNodeFromDOMNode,
+		$getNodeByKey,
+		$getRoot,
+		$getSelection,
+		$isParagraphNode,
+		$isRangeSelection,
+		COMMAND_PRIORITY_LOW,
+		KEY_ARROW_DOWN_COMMAND,
+		KEY_ARROW_UP_COMMAND,
+		type LexicalNode,
+		type NodeKey,
+	} from "lexical";
+	import type { Attachment } from "svelte/attachments";
+
+	import type { RichTextConfig } from "@plugin-richtext/field/rich-text-config";
+	import RichTextMenu from "@plugin-richtext/menu/rich-text-menu.svelte";
+	import {
+		buildRichTextOptions,
+		filterRichTextOptions,
+		type RichTextMenuOption,
+	} from "@plugin-richtext/menu/rich-text-options";
+
+	type PickerState = {
+		insertBefore: boolean;
+		targetNodeKey: NodeKey;
+	};
+
+	let {
+		anchorElement,
+		authoring,
+		config,
+	}: {
+		anchorElement: HTMLElement;
+		authoring: FieldAuthoringHost | undefined;
+		config: RichTextConfig;
+	} = $props();
+	const i18n = getAdminI18n();
+	const editor = useLexicalComposerContext()[0];
+	let draggableElement = $state.raw<HTMLElement | null>(null);
+	let pickerState = $state.raw<PickerState | null>(null);
+	let pickerOpen = $state(false);
+	let query = $state("");
+	let menuElement = $state.raw<HTMLElement | null>(null);
+	let movementAnnouncement = $state("");
+	let restorePickerFocus = true;
+	// The mounted field's authoring surface and feature set are stable.
+	// svelte-ignore state_referenced_locally
+	const baseOptions = buildRichTextOptions(editor, config, i18n, authoring);
+	const options = $derived(filterRichTextOptions(baseOptions, query, i18n.language));
+
+	function isOnToolbar(element: HTMLElement) {
+		return element.closest(".ridu-richtext-block-toolbar") !== null;
+	}
+
+	function closePicker() {
+		pickerOpen = false;
+		pickerState = null;
+	}
+
+	function handlePickerOpenChange(open: boolean) {
+		if (!open) closePicker();
+	}
+
+	function restoreEditorFocus(event: Event) {
+		event.preventDefault();
+		if (restorePickerFocus) queueMicrotask(() => editor.focus());
+		restorePickerFocus = true;
+	}
+
+	function preserveOutsideFocus(event: Event) {
+		restorePickerFocus = false;
+		const target =
+			event.target instanceof Element
+				? event.target.closest<HTMLElement>(
+						"button, a[href], input, select, textarea, [tabindex]:not([tabindex='-1'])"
+					)
+				: null;
+		if (target !== null) window.setTimeout(() => target.focus());
+	}
+
+	function closePickerFromEscape() {
+		restorePickerFocus = true;
+		closePicker();
+	}
+
+	function handlePickerKeydown(event: KeyboardEvent) {
+		if (event.key !== "Escape") return;
+		event.preventDefault();
+		event.stopPropagation();
+		closePickerFromEscape();
+	}
+
+	function openPicker(event: MouseEvent) {
+		event.preventDefault();
+		event.stopPropagation();
+		if (draggableElement === null || menuElement === null) return;
+
+		let targetNodeKey: NodeKey | null = null;
+		editor.read(() => {
+			targetNodeKey = $getNearestNodeFromDOMNode(draggableElement!)?.getKey() ?? null;
+		});
+		if (targetNodeKey === null) return;
+
+		pickerState = {
+			insertBefore: event.altKey || event.ctrlKey,
+			targetNodeKey,
+		};
+		query = "";
+		restorePickerFocus = true;
+		pickerOpen = true;
+	}
+
+	// @lexical-scope
+	function $moveBlock(block: LexicalNode, direction: -1 | 1) {
+		const siblings = $getRoot().getChildren();
+		const index = siblings.findIndex((candidate) => candidate.is(block));
+		if (index < 0) return undefined;
+		const targetIndex = index + direction;
+		if (targetIndex < 0 || targetIndex >= siblings.length) {
+			return i18n.t(
+				direction < 0
+					? "plugin.richtext:editor.blockAlreadyFirst"
+					: "plugin.richtext:editor.blockAlreadyLast"
+			);
+		}
+		const target = siblings[targetIndex];
+		if (direction < 0) target.insertBefore(block);
+		else target.insertAfter(block);
+		return i18n.t("plugin.richtext:editor.blockMovedPosition", {
+			position: i18n.formatNumber(targetIndex + 1),
+			total: i18n.formatNumber(siblings.length),
+		});
+	}
+
+	function announceMovement(message: string | undefined) {
+		if (message === undefined) return;
+		movementAnnouncement = "";
+		queueMicrotask(() => {
+			movementAnnouncement = message;
+			editor.focus();
+		});
+	}
+
+	function selectOption(option: RichTextMenuOption) {
+		const state = pickerState;
+		restorePickerFocus = option.restoreEditorFocus;
+		closePicker();
+		if (state === null) return;
+
+		editor.update(() => {
+			const target = $getNodeByKey(state.targetNodeKey);
+			if (target === null) return;
+			const placeholder = $createParagraphNode();
+			const text = $createTextNode("");
+			placeholder.append(text);
+			if (state.insertBefore) target.insertBefore(placeholder);
+			else target.insertAfter(placeholder);
+			text.select();
+			option.select();
+
+			if (option.preservePlaceholder) return;
+			const latestPlaceholder = placeholder.getLatest();
+			if (!$isParagraphNode(latestPlaceholder)) return;
+			if (latestPlaceholder.getTextContentSize() === 0) {
+				latestPlaceholder.remove();
+			}
+		});
+	}
+
+	const attachMenuElement: Attachment<HTMLElement> = (element) => {
+		menuElement = element;
+		return () => {
+			if (menuElement === element) menuElement = null;
+		};
+	};
+
+	const focusSearchInput: Attachment<HTMLInputElement> = (element) => {
+		element.focus();
+	};
+
+	$effect(() =>
+		mergeRegister(
+			editor.registerCommand(
+				KEY_ARROW_UP_COMMAND,
+				(event) => {
+					if (event === null || !event.altKey || !event.shiftKey) return false;
+					const selection = $getSelection();
+					if (!$isRangeSelection(selection)) return false;
+					event.preventDefault();
+					announceMovement($moveBlock(selection.anchor.getNode().getTopLevelElementOrThrow(), -1));
+					return true;
+				},
+				COMMAND_PRIORITY_LOW
+			),
+			editor.registerCommand(
+				KEY_ARROW_DOWN_COMMAND,
+				(event) => {
+					if (event === null || !event.altKey || !event.shiftKey) return false;
+					const selection = $getSelection();
+					if (!$isRangeSelection(selection)) return false;
+					event.preventDefault();
+					announceMovement($moveBlock(selection.anchor.getNode().getTopLevelElementOrThrow(), 1));
+					return true;
+				},
+				COMMAND_PRIORITY_LOW
+			)
+		)
+	);
+</script>
+
+<PopoverRoot open={pickerOpen} onOpenChange={handlePickerOpenChange}>
+	<DraggableBlockPlugin
+		{anchorElement}
+		isOnMenu={isOnToolbar}
+		onElementChanged={(element) => (draggableElement = element)}
+	>
+		{#snippet menu(attach)}
+			<ToolbarRoot
+				class="ridu-richtext-block-toolbar absolute top-0 start-0 z-2 flex! h-6 cursor-grab items-center gap-[0.2rem] text-foreground-faint opacity-0 transition-[opacity,color] duration-120 will-change-[transform,opacity] hover:text-foreground-muted focus-within:text-foreground-muted active:cursor-grabbing"
+				aria-label={i18n.t("plugin.richtext:editor.blockActions")}
+				{@attach attach}
+				{@attach attachMenuElement}
+			>
+				<span
+					class="ridu-richtext-block-grip grid h-5 w-[0.8rem] grid-cols-[repeat(2,2px)] grid-rows-[repeat(3,2px)] place-content-center gap-[2px]"
+					title={i18n.t("plugin.richtext:editor.dragToMoveBlock")}
+					aria-hidden="true"
+				>
+					<span></span>
+					<span></span>
+					<span></span>
+					<span></span>
+					<span></span>
+					<span></span>
+				</span>
+				<TooltipRoot>
+					<TooltipTrigger>
+						{#snippet child({ props })}
+							<ToolbarButton
+								{...props}
+								class="grid size-5 cursor-pointer place-items-center rounded-[3px] border border-transparent bg-transparent p-0 text-sm leading-none text-foreground-muted hover:border-control-border hover:bg-control-hover hover:text-foreground focus-visible:border-control-border focus-visible:bg-control-hover focus-visible:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/45"
+								type="button"
+								aria-label={i18n.t("plugin.richtext:editor.addBlock")}
+								aria-haspopup="dialog"
+								aria-expanded={pickerOpen}
+								aria-controls={pickerOpen ? "ridu-richtext-block-picker" : undefined}
+								onclick={openPicker}
+							>
+								<span aria-hidden="true">+</span>
+							</ToolbarButton>
+						{/snippet}
+					</TooltipTrigger>
+					<TooltipContent>{i18n.t("plugin.richtext:editor.addBlock")}</TooltipContent>
+				</TooltipRoot>
+			</ToolbarRoot>
+		{/snippet}
+
+		{#snippet targetLine(attach)}
+			<div
+				class="pointer-events-none absolute top-0 left-0 z-2 h-0.5 rounded-full bg-primary opacity-0 will-change-transform"
+				{@attach attach}
+			></div>
+		{/snippet}
+	</DraggableBlockPlugin>
+
+	{#if pickerOpen && menuElement !== null}
+		<PopoverContent
+			id="ridu-richtext-block-picker"
+			class="w-[min(19rem,calc(100vw-2rem))] animate-[ridu-richtext-menu-in_150ms_ease] motion-reduce:animate-none"
+			role="dialog"
+			aria-label={i18n.t("plugin.richtext:editor.insertBlock")}
+			customAnchor={menuElement}
+			side={i18n.direction === "rtl" ? "left" : "right"}
+			align="start"
+			sideOffset={8}
+			strategy="fixed"
+			trapFocus
+			onCloseAutoFocus={restoreEditorFocus}
+			onInteractOutside={preserveOutsideFocus}
+		>
+			<CommandRoot label={i18n.t("plugin.richtext:editor.filterBlocks")} shouldFilter={false} loop>
+				<CommandInput
+					type="search"
+					class="box-border h-[2.6rem] border-0 border-b border-control-border bg-control px-[0.8rem] text-[13px] text-foreground outline-none placeholder:text-foreground-faint focus:border-b-primary/48"
+					aria-label={i18n.t("plugin.richtext:editor.filterBlocks")}
+					placeholder={i18n.t("plugin.richtext:editor.filterBlocksPlaceholder")}
+					bind:value={query}
+					onkeydown={handlePickerKeydown}
+					{@attach focusSearchInput}
+				/>
+				{#if options.length > 0}
+					<RichTextMenu {options} onSelect={selectOption} embedded command />
+				{:else}
+					<p class="p-4 text-xs text-foreground-faint">
+						{i18n.t("plugin.richtext:editor.noMatchingBlocks")}
+					</p>
+				{/if}
+			</CommandRoot>
+		</PopoverContent>
+	{/if}
+</PopoverRoot>
+
+<p class="sr-only" aria-live="polite" aria-atomic="true" data-richtext-movement-status>
+	{movementAnnouncement}
+</p>

package/src/menu/rich-text-commands.ts

@@ -0,0 +1,32 @@
+import { createCommand, type LexicalCommand, type NodeKey } from "lexical";
+
+export interface OpenUploadBrowserPayload {
+	collectionSlug: string;
+	documentID?: string;
+	mode?: "edit" | "insert" | "replace";
+	nodeKey?: NodeKey;
+}
+
+export type OpenRelationshipBrowserPayload = OpenUploadBrowserPayload;
+
+export interface UpdateUploadCaptionPayload {
+	caption: string;
+	nodeKey: NodeKey;
+}
+
+export const OPEN_UPLOAD_BROWSER_COMMAND: LexicalCommand<OpenUploadBrowserPayload> = createCommand(
+	"OPEN_UPLOAD_BROWSER_COMMAND"
+);
+
+export const OPEN_RELATIONSHIP_BROWSER_COMMAND: LexicalCommand<OpenRelationshipBrowserPayload> =
+	createCommand("OPEN_RELATIONSHIP_BROWSER_COMMAND");
+
+export const REMOVE_UPLOAD_COMMAND: LexicalCommand<NodeKey> =
+	createCommand("REMOVE_UPLOAD_COMMAND");
+
+export const REMOVE_RELATIONSHIP_COMMAND: LexicalCommand<NodeKey> = createCommand(
+	"REMOVE_RELATIONSHIP_COMMAND"
+);
+
+export const UPDATE_UPLOAD_CAPTION_COMMAND: LexicalCommand<UpdateUploadCaptionPayload> =
+	createCommand("UPDATE_UPLOAD_CAPTION_COMMAND");

package/src/menu/rich-text-menu.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+	import { getAdminI18n } from "@riducms/plugin";
+	import {
+		CommandGroup,
+		CommandGroupHeading,
+		CommandGroupItems,
+		CommandItem,
+		CommandList,
+	} from "@riducms/ui";
+
+	import type { RichTextMenuOption } from "@plugin-richtext/menu/rich-text-options";
+
+	let {
+		options,
+		selectedIndex = null,
+		onHighlight = () => undefined,
+		onSelect,
+		embedded = false,
+		command = false,
+		idPrefix = "richtext-menu-item",
+	}: {
+		options: readonly RichTextMenuOption[];
+		selectedIndex?: number | null;
+		onHighlight?: (index: number) => void;
+		onSelect: (option: RichTextMenuOption) => void;
+		embedded?: boolean;
+		command?: boolean;
+		idPrefix?: string;
+	} = $props();
+	const i18n = getAdminI18n();
+	const menuClasses = $derived([
+		"ridu-richtext-menu max-h-80 w-[min(19rem,calc(100vw-2rem))] overflow-y-auto rounded-[4px] border border-control-border bg-popover p-[0.35rem] shadow-[var(--shadow-popover)] animate-[ridu-richtext-menu-in_150ms_ease] motion-reduce:animate-none",
+		embedded && "max-h-68 w-full rounded-0 border-0 shadow-none animate-none",
+	]);
+	const optionClasses =
+		"grid min-h-10 cursor-pointer grid-cols-[1.85rem_minmax(0,1fr)_auto] items-center gap-[0.6rem] rounded-[3px] px-[0.55rem] py-[0.35rem] text-foreground-muted outline-none hover:bg-control-hover hover:text-foreground data-[selected]:bg-control-hover data-[selected]:text-foreground";
+</script>
+
+{#snippet optionContent(option: RichTextMenuOption)}
+	<span
+		class="grid size-7 place-items-center rounded-[3px] border border-control-border bg-control font-mono text-[10px] text-foreground-muted"
+		aria-hidden="true"
+	>
+		{option.glyph}
+	</span>
+	<span class="grid min-w-0 gap-[0.1rem]">
+		<strong class="text-[13px] font-medium">{option.label}</strong>
+		<small class="text-[11px] text-foreground-faint">{option.description}</small>
+	</span>
+	<span class="font-mono text-[11px] text-foreground-faint">{option.keyHint}</span>
+{/snippet}
+
+{#if command}
+	<CommandList class={menuClasses}>
+		<CommandGroup>
+			<CommandGroupHeading
+				class="px-[0.6rem] pt-[0.45rem] pb-[0.35rem] font-mono text-[10px] tracking-[0.13em] text-foreground-faint uppercase"
+			>
+				{i18n.t("plugin.richtext:editor.insertBlock")}
+			</CommandGroupHeading>
+			<CommandGroupItems>
+				{#each options as option, index (option.key)}
+					<CommandItem
+						class={optionClasses}
+						id={`${idPrefix}-${index}`}
+						value={option.label}
+						keywords={[...option.keywords]}
+						onSelect={() => onSelect(option)}
+					>
+						{@render optionContent(option)}
+					</CommandItem>
+				{/each}
+			</CommandGroupItems>
+		</CommandGroup>
+	</CommandList>
+{:else}
+	<div class={menuClasses} data-richtext-menu-surface>
+		<p
+			class="px-[0.6rem] pt-[0.45rem] pb-[0.35rem] font-mono text-[10px] tracking-[0.13em] text-foreground-faint uppercase"
+		>
+			{i18n.t("plugin.richtext:editor.insertBlock")}
+		</p>
+		<ul class="grid list-none gap-[0.1rem] p-0" role="presentation">
+			{#each options as option, index (option.key)}
+				<li
+					id={`${idPrefix}-${index}`}
+					class={[optionClasses, selectedIndex === index && "bg-control-hover text-foreground"]}
+					role="option"
+					aria-selected={selectedIndex === index}
+					tabindex="-1"
+					{@attach option.attach}
+					onmouseenter={() => onHighlight(index)}
+					onmousedown={(event) => event.preventDefault()}
+					onclick={() => onSelect(option)}
+					onkeydown={(event) => {
+						if (event.key === "Enter" || event.key === " ") {
+							event.preventDefault();
+							onSelect(option);
+						}
+					}}
+				>
+					{@render optionContent(option)}
+				</li>
+			{/each}
+		</ul>
+	</div>
+{/if}

package/src/menu/rich-text-options.ts

@@ -0,0 +1,244 @@
+import { $createCodeNode } from "@lexical/code";
+import {
+	INSERT_CHECK_LIST_COMMAND,
+	INSERT_ORDERED_LIST_COMMAND,
+	INSERT_UNORDERED_LIST_COMMAND,
+} from "@lexical/list";
+import { $createHeadingNode, $createQuoteNode } from "@lexical/rich-text";
+import { $setBlocksType } from "@lexical/selection";
+import type { AdminI18n, FieldAuthoringHost } from "@riducms/plugin";
+import { INSERT_HORIZONTAL_RULE_COMMAND, MenuOption } from "@hvniel/lexical-svelte";
+import {
+	$createParagraphNode,
+	$getSelection,
+	$isRangeSelection,
+	type ElementNode,
+	type LexicalEditor,
+} from "lexical";
+
+import {
+	OPEN_RELATIONSHIP_BROWSER_COMMAND,
+	OPEN_UPLOAD_BROWSER_COMMAND,
+} from "@plugin-richtext/menu/rich-text-commands";
+import { hasRichTextFeature, type RichTextConfig } from "@plugin-richtext/field/rich-text-config";
+
+export class RichTextMenuOption extends MenuOption {
+	readonly label: string;
+	readonly description: string;
+	readonly glyph: string;
+	readonly keywords: readonly string[];
+	readonly select: () => void;
+	readonly keyHint: string;
+	readonly preservePlaceholder: boolean;
+	readonly restoreEditorFocus: boolean;
+
+	constructor(
+		key: string,
+		label: string,
+		description: string,
+		glyph: string,
+		keywords: readonly string[],
+		select: () => void,
+		options: {
+			keyHint?: string;
+			preservePlaceholder?: boolean;
+			restoreEditorFocus?: boolean;
+		} = {}
+	) {
+		super(key);
+		this.label = label;
+		this.description = description;
+		this.glyph = glyph;
+		this.keywords = keywords;
+		this.select = select;
+		this.keyHint = options.keyHint ?? "↵";
+		this.preservePlaceholder = options.preservePlaceholder ?? true;
+		this.restoreEditorFocus = options.restoreEditorFocus ?? true;
+	}
+}
+
+export function buildRichTextOptions(
+	editor: LexicalEditor,
+	config: RichTextConfig,
+	i18n: AdminI18n,
+	authoring?: FieldAuthoringHost
+): RichTextMenuOption[] {
+	const options = [
+		new RichTextMenuOption(
+			"paragraph",
+			i18n.t("plugin.richtext:option.paragraph.label"),
+			i18n.t("plugin.richtext:option.paragraph.description"),
+			"¶",
+			keywords(i18n.t("plugin.richtext:option.paragraph.keywords")),
+			() => $setBlock($createParagraphNode)
+		),
+		new RichTextMenuOption(
+			"heading-2",
+			i18n.t("plugin.richtext:option.heading2.label"),
+			i18n.t("plugin.richtext:option.heading2.description"),
+			"h2",
+			keywords(i18n.t("plugin.richtext:option.heading2.keywords")),
+			() => $setBlock(() => $createHeadingNode("h2"))
+		),
+		new RichTextMenuOption(
+			"heading-3",
+			i18n.t("plugin.richtext:option.heading3.label"),
+			i18n.t("plugin.richtext:option.heading3.description"),
+			"h3",
+			keywords(i18n.t("plugin.richtext:option.heading3.keywords")),
+			() => $setBlock(() => $createHeadingNode("h3"))
+		),
+		new RichTextMenuOption(
+			"quote",
+			i18n.t("plugin.richtext:option.quote.label"),
+			i18n.t("plugin.richtext:option.quote.description"),
+			'"',
+			keywords(i18n.t("plugin.richtext:option.quote.keywords")),
+			() => $setBlock($createQuoteNode)
+		),
+	];
+
+	if (hasRichTextFeature(config, "lists")) {
+		options.push(
+			new RichTextMenuOption(
+				"bulleted-list",
+				i18n.t("plugin.richtext:option.bulletedList.label"),
+				i18n.t("plugin.richtext:option.bulletedList.description"),
+				"•",
+				keywords(i18n.t("plugin.richtext:option.bulletedList.keywords")),
+				() => editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND, undefined)
+			),
+			new RichTextMenuOption(
+				"numbered-list",
+				i18n.t("plugin.richtext:option.numberedList.label"),
+				i18n.t("plugin.richtext:option.numberedList.description"),
+				"1.",
+				keywords(i18n.t("plugin.richtext:option.numberedList.keywords")),
+				() => editor.dispatchCommand(INSERT_ORDERED_LIST_COMMAND, undefined)
+			),
+			new RichTextMenuOption(
+				"checklist",
+				i18n.t("plugin.richtext:option.checklist.label"),
+				i18n.t("plugin.richtext:option.checklist.description"),
+				"☑",
+				keywords(i18n.t("plugin.richtext:option.checklist.keywords")),
+				() => editor.dispatchCommand(INSERT_CHECK_LIST_COMMAND, undefined)
+			)
+		);
+	}
+
+	if (hasRichTextFeature(config, "code")) {
+		options.push(
+			new RichTextMenuOption(
+				"code-block",
+				i18n.t("plugin.richtext:option.codeBlock.label"),
+				i18n.t("plugin.richtext:option.codeBlock.description"),
+				"</>",
+				keywords(i18n.t("plugin.richtext:option.codeBlock.keywords")),
+				() => $setBlock($createCodeNode)
+			)
+		);
+	}
+
+	if (hasRichTextFeature(config, "horizontal-rule")) {
+		options.push(
+			new RichTextMenuOption(
+				"divider",
+				i18n.t("plugin.richtext:option.divider.label"),
+				i18n.t("plugin.richtext:option.divider.description"),
+				"—",
+				keywords(i18n.t("plugin.richtext:option.divider.keywords")),
+				() => editor.dispatchCommand(INSERT_HORIZONTAL_RULE_COMMAND, undefined),
+				{ preservePlaceholder: false }
+			)
+		);
+	}
+
+	if (hasRichTextFeature(config, "uploads")) {
+		const allowed = new Set(config.uploadCollections);
+		const uploadOptions: RichTextMenuOption[] = [];
+		for (const collection of authoring?.collections ?? []) {
+			if (!collection.capabilities.upload || (allowed.size > 0 && !allowed.has(collection.slug))) {
+				continue;
+			}
+			uploadOptions.push(
+				new RichTextMenuOption(
+					`upload-${collection.slug}`,
+					collection.labels.singular,
+					i18n.t("plugin.richtext:option.upload.description", {
+						label: collection.labels.singular.toLocaleLowerCase(i18n.language),
+					}),
+					"ref",
+					[...keywords(i18n.t("plugin.richtext:option.upload.keywords")), collection.slug],
+					() =>
+						queueMicrotask(() =>
+							editor.dispatchCommand(OPEN_UPLOAD_BROWSER_COMMAND, {
+								collectionSlug: collection.slug,
+							})
+						),
+					{ restoreEditorFocus: false }
+				)
+			);
+		}
+		options.splice(4, 0, ...uploadOptions);
+	}
+
+	if (hasRichTextFeature(config, "relationships")) {
+		const allowed = new Set(config.relationshipCollections);
+		const relationshipOptions: RichTextMenuOption[] = [];
+		for (const collection of authoring?.collections ?? []) {
+			if (allowed.size > 0 && !allowed.has(collection.slug)) continue;
+			relationshipOptions.push(
+				new RichTextMenuOption(
+					`relationship-${collection.slug}`,
+					i18n.t("plugin.richtext:option.relationship.label", {
+						label: collection.labels.singular,
+					}),
+					i18n.t("plugin.richtext:option.relationship.description", {
+						label: collection.labels.singular.toLocaleLowerCase(i18n.language),
+					}),
+					"rel",
+					[...keywords(i18n.t("plugin.richtext:option.relationship.keywords")), collection.slug],
+					() =>
+						queueMicrotask(() =>
+							editor.dispatchCommand(OPEN_RELATIONSHIP_BROWSER_COMMAND, {
+								collectionSlug: collection.slug,
+							})
+						),
+					{ restoreEditorFocus: false }
+				)
+			);
+		}
+		// Upload and relationship labels can intentionally overlap (for example,
+		// Asset and Related Asset). Preserve the established upload result first
+		// for keyboard selection and append the explicit relationship commands.
+		options.push(...relationshipOptions);
+	}
+
+	return options;
+}
+
+export function filterRichTextOptions(
+	options: readonly RichTextMenuOption[],
+	query: string,
+	language?: string
+): RichTextMenuOption[] {
+	const normalized = query.trim().toLocaleLowerCase(language);
+	if (normalized === "") return [...options];
+	return options.filter(
+		(option) =>
+			option.label.toLocaleLowerCase(language).includes(normalized) ||
+			option.description.toLocaleLowerCase(language).includes(normalized) ||
+			option.keywords.some((keyword) => keyword.toLocaleLowerCase(language).includes(normalized))
+	);
+}
+
+function keywords(value: string) {
+	return value.split(/\s+/).filter(Boolean);
+}
+
+// @lexical-scope
+function $setBlock(createBlock: () => ElementNode) {
+	const selection = $getSelection();
+	if ($isRangeSelection(selection)) $setBlocksType(selection, createBlock);
+}