pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/rich-text-editor/MODULE.md

@@ -0,0 +1,225 @@
+# rich-text-editor/ — a themed native rich-text editor (bold/lists/quote/code/link/image/@mention)
+
+`RichTextEditor` wraps Software Mansion's `react-native-enriched-html` (`EnrichedTextInput`, a native
+Fabric editor) with this library's own toolbar, a link-insert dialog, and an `@`-mention dropdown —
+one shared module instead of each consumer app hand-rolling its own editor.
+
+## Why this exists
+
+tickets-mobile shipped two separate, independently hand-rolled editors, both far below web's TipTap
+editor: `RichDescriptionEditor` (a markdown-ish plain `TextInput`, no real rich text) and
+`RichTextComposer` (an even thinner raw-HTML-ish `TextInput`, no headings/quote/code-block/
+strikethrough/mentions). Both exist only because no native rich-text editor was available; this
+module is what a future migration replaces them with — that migration is **not** part of this change.
+
+## Uncontrolled, by the native library's own design
+
+`EnrichedTextInput`'s content is only readable via an async `getHTML()` ref call — the library's own
+docs warn that its `onChangeHtml` event is too expensive to drive on every keystroke. So this module
+follows the same contract: `defaultValue` (initial HTML, never re-applied on prop change) + a `ref`
+exposing `getHTML()` (`Promise<string>`), `focus()`, `blur()`, `setValue(html)`. Callers read the
+final HTML by awaiting `ref.getHTML()` at their own save/submit point — never from continuous state.
+`onChangeText` is a **cheap, plain-text** signal on every keystroke (dirty-tracking, enabling a Save
+button) — it is not the HTML and must not be used for persistence.
+
+## Files
+
+| File | Role |
+|------|------|
+| `RichTextEditor.tsx` | The component: toolbar (`Button`), the native editor, the link dialog (`Modal` + `Input`), the mention dropdown. |
+| `RichTextEditor.variants.ts` | Pure resolvers — toolbar item catalogue, `onChangeState` → active-action mapping, mention filtering, colour + `HtmlStyle` token mapping — plus the themed structural resolvers. No React, no native import (types-only from `react-native-enriched-html`). |
+| `index.ts` | Public surface: `RichTextEditor`, `RichTextEditorHandle`, `RichTextEditorProps`, `MentionUser`, `RichTextEditorImage`, `RichTextEditorToolbarAction`, `RICH_TEXT_EDITOR_TOOLBAR_ITEMS`. |
+| `__tests__/RichTextEditor.test.ts` | Pure: WCAG contrast for the field/mention pill/code/code-block/blockquote/link/list-marker colours (all brands × modes), the toolbar item catalogue, `onChangeState` mapping, mention filtering. |
+| `__tests__/RichTextEditor.render.test.tsx` | Render, with `react-native-enriched-html` mocked at the module level (jest cannot render a native Fabric component): toolbar presence, ref forwarding, a toolbar press invoking the matching native command, toggle highlighting, the link dialog, the image flow (`focus` then `setImage`, cancel/zero-size/rejection paths), and the mention dropdown's open/filter/select/close plus its `keyboardShouldPersistTaps="always"`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultValue` | `string` | — | Initial HTML/text. Uncontrolled — never re-applied after mount. |
+| `placeholder` | `string` | — | |
+| `label` | `string` | — | Rendered above the toolbar. Also becomes the editor field's accessible name (see "Accessibility" below). |
+| `accessibilityLabel` | `string` | — | Overrides the `label`→accessible-name fallback. |
+| `minHeight` | `number` | `140` | Editor field minimum height, dp. |
+| `mentionUsers` | `MentionUser[]` | `[]` | `{ id: string \| number; label: string; profileUrl? }`. Empty/omitted disables `@` mentions entirely — no indicator wired, no mention toolbar button rendered. |
+| `onRequestImage` | `() => Promise<RichTextEditorImage \| null>` | — | Supplies `{ uri, width, height }` to insert at the caret. Omitted/undefined hides the image toolbar button entirely, same contract as `mentionUsers`. Resolve `null` for a cancel or a failure the consumer already reported. |
+| `onChangeText` | `(text: string) => void` | — | Cheap plain-text signal, every keystroke. NOT the HTML. |
+| `onFocus` / `onBlur` | `() => void` | — | |
+| `editable` | `boolean` | `true` | |
+| `scrollEnabled` | `boolean` | `false` | Native-editor internal scrolling. **Deliberately inverts the native default (`true`)** — see "Gestures" below. Turn on only alongside a bounded height. |
+| `containerStyle` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `useHtmlNormalizer` | `boolean` | `false` | Passthrough to the native `useHtmlNormalizer` — normalizes foreign HTML (Word/Docs/legacy markup) into the canonical subset before applying it. Matches the native default (off); a consumer whose HTML source may be non-canonical (e.g. tickets-mobile's ticket descriptions) opts in. |
+| `testID` | `string` | — | Toolbar buttons get `${testID}-<action>`. |
+
+Ref (`RichTextEditorHandle`): `getHTML(): Promise<string>`, `focus()`, `blur()`, `setValue(html)`.
+
+## The card owns the boundary (not the native view)
+
+Toolbar + field sit inside one bordered card `View` — `border.interactive` (≥ 3:1) at rest, shifting
+to `border.focus` when focused. That shift is near-imperceptible (~1.25:1 between the two); the focus
+signal is carried by the same 2px/2px focus ring `Input`/`Textarea` draw
+(`testID="rich-text-editor-focus-ring"`; the card itself is `${testID}-card`). The toolbar keeps only
+a `borderBottomWidth` divider (`border.default`) and its `bg.raised` strip; the native
+`EnrichedTextInput` is handed no border, radius or fill at all and stays transparent over the card.
+
+This is not a stylistic choice: on **Android** `EnrichedTextInput` is driven by a `SimpleViewManager`,
+and `BaseViewManager` declares **no `border*` `@ReactProp`** — a border in the native view's own
+`style` is silently dropped (the package's own types annotate every `border*Color`/`border*Radius`
+key `@platform ios web`). Before this, the field painted no boundary at all on Android. No
+`overflow: "hidden"` on the card: it would clip both the 200dp mention dropdown and the focus ring.
+
+## Gestures — `scrollEnabled` defaults to `false`
+
+Android's `EnrichedTextInputView.canScrollVertically/Horizontally` return the `scrollEnabled` prop
+**verbatim**, without asking whether there is anything to scroll. While it is `true`, the
+`ACTION_MOVE` guard that would call `requestDisallowInterceptTouchEvent(false)` can never pass, so
+the editor keeps the gesture it grabbed on `ACTION_DOWN`: a drag that starts inside the field —
+most visibly on an inline image, a one-character `ImageSpan` with a full-size hit box — focuses the
+editor, opens the keyboard and drags out a selection (the Cut/Copy/Paste action bar) instead of
+scrolling the page. The field sets `minHeight` and no `maxHeight`, so it already grows to fit its
+content and internal scrolling buys nothing; turning it off costs nothing and releases the drag.
+
+## Toolbar (16 actions, `RICH_TEXT_EDITOR_TOOLBAR_ITEMS`)
+
+Bold, italic, underline, strikethrough, inline code, H1–H3, quote, code block, bullet list, numbered
+list, checklist, link, image, mention — each an icon-only `Button` (`variant="outline"`,
+`tone="neutral"`). Toggle highlighting (`variant="solid"` when active) is driven by the native
+`onChangeState` event, the one signal that tracks "is the cursor inside bold/a heading/…" — there is no
+other way to know. Checklist always inserts unchecked (`toggleCheckboxList(false)`); the mention button
+calls the ref's `startMention("@")` rather than toggling a style. The mention button is omitted when
+`mentionUsers` is empty and the image button when `onRequestImage` is absent, per the "disables
+gracefully" contract above.
+
+## Image insert
+
+The consumer owns picking, uploading and any failure message; this module owns the button, its busy
+state, and the native call. `onRequestImage` resolves `{ uri, width, height }`, or `null` for a cancel
+or an already-reported failure; a rejection is caught (dev `console.warn`, same gate `FileUpload` uses)
+so the toolbar recovers with nothing inserted. While the promise is pending the button renders
+`loading`, which `Button` already turns into a spinner + `accessibilityState.busy` + a blocked press,
+so a double-tap mid-upload needs no extra state here.
+
+`width`/`height` are **required and must be > 0**: the native editor reads an `<img>`'s dimensions once
+at parse time and never re-measures, so a missing/zero dimension renders an invisible 0×0 image. The
+editor is focused before `setImage` — native `addImage` silently no-ops on a null selection. Those
+dimensions are persisted (`getHTML()` emits `<img src width height>`), so a mobile-inserted image
+carries an explicit width web's CSS-sized `.ProseMirror img` rule will not override until the content is
+re-saved from web. Nothing is themable here — the native `HtmlStyle` has no `img` key, so this action
+adds no colour and needs no contrast proof.
+
+## Link insert dialog
+
+Copies `RichDescriptionEditor`'s `Modal` + `Input` pattern. The last `onChangeSelection` event (native,
+fires on every selection change) is captured in a ref — not state, to avoid a re-render per caret move
+— and read when the dialog confirms, calling `ref.setLink(start, end, selectedText || url, url)`.
+
+## Mention dropdown
+
+`mentionIndicators=["@"]`. `onStartMention` opens the dropdown (query `""`, so it starts populated —
+matches web's `onStart` behaviour); `onChangeMention` re-filters by `.text` (case-insensitive
+substring, capped at 8 — same cap web's `mentionSuggestion.ts` uses); `onEndMention` closes it. It is a
+plain absolutely-positioned `View`, anchored to "below the toolbar" (the wrapper around the editor
+field is the `relative` anchor) — not a measured popover; this is React Native, not the DOM, so there
+is no anchor-element geometry to reproduce.
+
+Inside it the candidates go through `VirtualList` (`core/list`), not a `ScrollView` + `.map()`, with
+`itemHeight={MENTION_ROW_HEIGHT}` — the rows are a fixed 40dp (`richTextEditorMentionRowStructure`'s
+`minHeight`), so `getItemLayout` is exact and the list never measures. Rows are a memo'd `MentionRow`
+taking **primitives** (`id`, `label`), and `onSelect(id, label)` is one shared `useCallback` with `[]`
+deps rather than a closure minted per row.
+
+**`keyboardShouldPersistTaps="always"` — `"handled"` is not enough here.** The dropdown only exists
+while the mention session is live, and the session dies with the keyboard. Under RN's default
+(`"never"`) the first tap on a row is spent dismissing the keyboard instead of selecting (WCAG
+2.1.1). `"handled"` fixes the row tap but still dismisses on a tap the rows don't claim — between
+rows, or on the dropdown's own padding — which ends the mention session mid-selection and the
+dropdown disappears under the user's finger. `combobox/` uses `"handled"` for the opposite reason:
+its list fills a bottom sheet the user may legitimately want to dismiss by tapping past a row. The
+toolbar `ScrollView` in this same component already uses `"always"` for the same reason the
+dropdown now does.
+
+## Accessibility
+
+- **Editor field accessible name.** The native `EnrichedTextInput` gets `accessibilityLabel` from
+  `accessibilityLabel ?? label` (`resolveRichTextEditorAccessibility`) — before this fix it had no
+  path to a name at all. On native the now-redundant visible `label` `Text` is hidden from
+  assistive tech (`aria-hidden`) so the name isn't announced twice. **On web it stays exposed**:
+  `react-native-enriched-html`'s web build renders a TipTap `EditorContent` and forwards no
+  accessibility prop to the underlying `contenteditable` (only `enterkeyhint`), so the field itself
+  never carries the name there — hiding the label too would leave a web screen-reader user with
+  nothing. Follow-up: an upstream `aria-label` passthrough on `EnrichedTextInput`'s web build would
+  close this gap.
+- **Toolbar toggle (pressed) state.** The 14 style-toggle buttons (all but the `image`/`mention`
+  triggers, see `RichTextEditorToolbarItem.toggle`) pass `Button`'s `selected` prop, driven by the
+  same `activeActions` state that already drove the `variant="solid"` highlight — before this fix
+  the toggle was colour-only (WCAG 1.4.1) and announced nothing (4.1.2). `Button` itself resolves
+  `selected` into `aria-pressed` (web) / `accessibilityState.selected` (native), per
+  `docs/PLATFORM-A11Y-PROPS.md`'s "genuinely diverge" case — RN has no `pressed` accessibility
+  state at all. `image`/`mention` never receive `selected`: they open a picker, not toggle a style.
+- **Flat-only `aria-*`**, per `docs/PLATFORM-A11Y-PROPS.md` — no `accessibilityState={{…}}` /
+  `accessibilityValue={{…}}` object literal anywhere in this module; `react-native-web` discards
+  the object form silently.
+
+## Colour (measured in `__tests__/RichTextEditor.test.ts`, every brand × mode)
+
+Every colour handed to the native `htmlStyle`/native props is a role lookup, never a hex:
+
+| Element | Fill | Ink |
+|---|---|---|
+| Inline code / mention pill | `accent.subtle` | `accent.text` (the pair already proven ≥ 4.5:1 for every brand × mode — see `org-switcher/MODULE.md`) |
+| Code block | `bg.sunken` | `fg.default` (the same pair `Avatar`'s neutral fill uses) |
+| Blockquote bar / text | `border.interactive` (≥ 3:1) | `fg.muted` (≥ 4.5:1) |
+| Link | — | `accent.text` |
+| Card (toolbar + field) | `bg.surface` | `fg.default`, placeholder `fg.muted` |
+| Card border | `border.interactive` at rest, `border.focus` focused — both ≥ 3:1 on the fill **and** the canvas, but only ~1.25:1 apart, so the ring carries focus | — |
+| Toolbar strip / divider | `bg.raised` / `border.default` (decorative — the card border is the 1.4.11 boundary) | — |
+
+`style` passed to the native editor respects `EnrichedInputStyle` — a RESTRICTED subset of `TextStyle`
+(no `flexDirection`/`alignItems`/etc.) — so `richTextEditorFieldStructure` only emits padding/
+`fontSize` (plus `minHeight`/`color` from the component), never a flex-layout key.
+
+## Known gaps
+
+- **EAS Android dev-client build confirmed successful (build `22b8321f`, APK built) but NOT yet
+  verified on a physical device by the user.** Everything reported here is typecheck/build/unit-test
+  level — jest cannot render a native Fabric component, so nothing here claims the editor "works" on
+  device.
+- `onChangeState.image.isBlocking` (the caret is somewhere an `<img>` can't go, e.g. inside a code
+  block) is not honoured — the pick/upload still runs and native `addImage` then silently no-ops.
+  Disabling the button on that flag is the follow-up.
+- No paste/drop image handling: the native `onPasteImages` event is unwired, so a pasted image is
+  dropped. Web has full paste support — the natural second half of image parity.
+- `scrollEnabled: false` fixes the *drag* case, not the *tap* case: a touch on an inline image that
+  never leaves touch slop still registers as a tap on the `ImageSpan`, and Android selects an image
+  span on tap → action bar. `setTextIsSelectable(true)` is hardcoded in the package's
+  `onAttachedToWindow` and `startActionMode` only appends to the platform menu, so there is no prop
+  to suppress it — an upstream `selectionEnabled`-style prop is the real fix.
+- No anchor-measured mention dropdown position (see "Mention dropdown" above) — same deferral
+  `Menu`/`Tooltip` already document for their own unmeasured overlays.
+- tickets-mobile's `RichDescriptionEditor.tsx` (ticket descriptions) and `CommentThread.tsx`'s
+  comment composer/inline-edit (replacing the deleted `RichTextComposer.tsx`) both now wrap this
+  module — see `tickets/mobile/src/modules/ticket-detail/MODULE.md` for the consumer-side detail.
+
+## Performance
+
+Wrapped in `React.memo`. This component re-renders on every keystroke (`onChangeState` refreshes
+`activeActions`), so everything handed to a child is stabilized:
+
+- `colors`, `htmlStyle` and the native `fieldStyle` object are `useMemo`'d. `fieldStyle` in
+  particular is passed straight to the native `EnrichedTextInput`; a fresh object per keystroke
+  crossed the bridge as a prop change.
+- Every style array/object the JSX used to build inline (root, label, card, toolbar, mention
+  dropdown, focus ring, link-dialog body and actions) is `useMemo`'d.
+- `renderItem`/`keyExtractor` for the mention list are `useCallback`'d — the module ESLint config
+  rejects inline arrows on those two props.
+- `actionHandlers` maps each toolbar action to one stable `() => void`, so each toolbar `Button`
+  keeps its `onPress` identity; `closeLinkDialog`/`openLinkDialog` replaced the inline
+  `() => setLinkOpen(…)` arrows for the same reason.
+
+No motion of its own — the editor's own visual state changes (toggle highlighting, focus ring) are
+instant, and the mention dropdown is a list, where per-row animation is forbidden.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.

package/lib/module/modules/rich-text-editor/RichTextEditor.js

@@ -0,0 +1,413 @@
+"use strict";
+
+/**
+ * RichTextEditor — a themed wrapper around `react-native-enriched-html`'s native Fabric editor
+ * (`EnrichedTextInput`), with its own toolbar (`Button`), a link-insert dialog (`Modal` + `Input`,
+ * copied from the app's `RichDescriptionEditor` pattern), and an `@`-mention dropdown.
+ *
+ * UNCONTROLLED, by the native library's own design: the editor's HTML is only readable via the
+ * async `getHTML()` ref call (the library's own docs warn `onChangeHtml` is too expensive to drive
+ * live sync). So this component takes `defaultValue` (initial HTML, never re-applied on change) and
+ * exposes a `ref` with `getHTML()`/`focus()`/`blur()`/`setValue()` — the caller reads the final HTML
+ * at its own save/submit point, not from continuous state. `onChangeText` is a cheap plain-text
+ * signal (every keystroke) for dirty-tracking / enabling a Save button — it is NOT the HTML.
+ *
+ * Toolbar toggle highlighting is driven by the native `onChangeState` event (bold/italic/… active
+ * state as the cursor moves) — see `RichTextEditor.variants.ts` → `resolveRichTextEditorActiveActions`.
+ */
+
+import { forwardRef, memo, useCallback, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
+import { EnrichedTextInput } from "react-native-enriched-html";
+import { VirtualList } from "../../core/list/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Button } from "../button/index.js";
+import { Input } from "../input/index.js";
+import { Modal } from "../modal/index.js";
+import { filterMentionCandidates, resolveRichTextEditorAccessibility, resolveRichTextEditorActiveActions, resolveRichTextEditorColors, resolveRichTextEditorHtmlStyle, RICH_TEXT_EDITOR_TOOLBAR_ITEMS, richTextEditorCardStructure, richTextEditorFieldStructure, richTextEditorLayout, richTextEditorMentionDropdownStructure, richTextEditorMentionRowStructure, richTextEditorToolbarStructure } from "./RichTextEditor.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const MENTION_ROW_HEIGHT = 40;
+const IS_WEB = Platform.OS === "web";
+const MENTION_INDICATOR = "@";
+const MENTION_INDICATORS = [MENTION_INDICATOR];
+const EMPTY_MENTION_INDICATORS = [];
+const MentionRow = /*#__PURE__*/memo(function MentionRow({
+  id,
+  label,
+  theme,
+  colors,
+  onSelect
+}) {
+  const handlePress = useCallback(() => onSelect(id, label), [onSelect, id, label]);
+  const restingStyle = useMemo(() => [richTextEditorMentionRowStructure(theme), {
+    backgroundColor: colors.mentionRowBackground
+  }], [theme, colors.mentionRowBackground]);
+  const pressedStyle = useMemo(() => [richTextEditorMentionRowStructure(theme), {
+    backgroundColor: colors.mentionRowPressed
+  }], [theme, colors.mentionRowPressed]);
+  const rowStyle = useCallback(({
+    pressed
+  }) => pressed ? pressedStyle : restingStyle, [pressedStyle, restingStyle]);
+  const labelStyle = useMemo(() => ({
+    fontSize: theme.fontSizes.sm,
+    color: colors.mentionRowText
+  }), [theme.fontSizes.sm, colors.mentionRowText]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    accessibilityRole: "menuitem",
+    onPress: handlePress,
+    style: rowStyle,
+    children: /*#__PURE__*/_jsx(Text, {
+      style: labelStyle,
+      children: label
+    })
+  });
+});
+
+// Identical to `Input`/`Textarea`: the ring sits OUTSIDE the field, on the canvas, where
+// `border.focus` is the token proven ≥ 3:1.
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_GAP = 2;
+function RichTextEditorImpl({
+  defaultValue,
+  placeholder,
+  label,
+  accessibilityLabel,
+  minHeight = 140,
+  mentionUsers = [],
+  onRequestImage,
+  onChangeText,
+  onFocus,
+  onBlur,
+  editable = true,
+  scrollEnabled = false,
+  containerStyle,
+  useHtmlNormalizer = false,
+  testID
+}, ref) {
+  const theme = useTheme();
+  const nativeRef = useRef(null);
+  const selectionRef = useRef({
+    start: 0,
+    end: 0,
+    text: ""
+  });
+  const [activeActions, setActiveActions] = useState({});
+  const [linkOpen, setLinkOpen] = useState(false);
+  const [linkUrl, setLinkUrl] = useState("");
+  const [imageBusy, setImageBusy] = useState(false);
+  const [focused, setFocused] = useState(false);
+  // `null` = closed; "" = just opened (no filter typed yet) — matches web's onStart/onUpdate split.
+  const [mentionQuery, setMentionQuery] = useState(null);
+  const a11y = useMemo(() => resolveRichTextEditorAccessibility({
+    label,
+    accessibilityLabel,
+    web: IS_WEB
+  }), [label, accessibilityLabel]);
+  const colors = useMemo(() => resolveRichTextEditorColors(theme.colors), [theme.colors]);
+  const htmlStyle = useMemo(() => resolveRichTextEditorHtmlStyle(theme), [theme]);
+  const mentionEnabled = mentionUsers.length > 0;
+
+  // `EnrichedInputStyle` (unlike a normal View's `style`) takes ONE plain object, not an array — so
+  // the structural + colour pieces are flattened into a single object here rather than passed as the
+  // `[structure, { ... }]` array every other module in this library uses for its root style.
+  const fieldStyle = useMemo(() => ({
+    ...StyleSheet.flatten(richTextEditorFieldStructure(theme)),
+    minHeight,
+    color: colors.text
+  }), [theme, minHeight, colors.text]);
+  useImperativeHandle(ref, () => ({
+    getHTML: () => nativeRef.current?.getHTML() ?? Promise.resolve(""),
+    focus: () => nativeRef.current?.focus(),
+    blur: () => nativeRef.current?.blur(),
+    setValue: html => nativeRef.current?.setValue(html)
+  }), []);
+  const handleChangeText = useCallback(e => onChangeText?.(e.nativeEvent.value), [onChangeText]);
+  const handleChangeSelection = useCallback(e => {
+    selectionRef.current = e.nativeEvent;
+  }, []);
+  const handleChangeState = useCallback(e => {
+    setActiveActions(resolveRichTextEditorActiveActions(e.nativeEvent));
+  }, []);
+  const handleFocus = useCallback(() => {
+    setFocused(true);
+    onFocus?.();
+  }, [onFocus]);
+  const handleBlur = useCallback(() => {
+    setFocused(false);
+    onBlur?.();
+  }, [onBlur]);
+  const handleStartMention = useCallback(() => setMentionQuery(""), []);
+  const handleChangeMention = useCallback(e => setMentionQuery(e.text), []);
+  const handleEndMention = useCallback(() => setMentionQuery(null), []);
+  const mentionCandidates = useMemo(() => mentionQuery === null ? [] : filterMentionCandidates(mentionUsers, mentionQuery), [mentionQuery, mentionUsers]);
+  const selectMention = useCallback((id, label) => {
+    nativeRef.current?.setMention(MENTION_INDICATOR, label, {
+      id: String(id)
+    });
+    setMentionQuery(null);
+  }, []);
+  const openLinkDialog = useCallback(() => {
+    setLinkUrl("");
+    setLinkOpen(true);
+  }, []);
+  const closeLinkDialog = useCallback(() => setLinkOpen(false), []);
+  const confirmLink = useCallback(() => {
+    const {
+      start,
+      end,
+      text
+    } = selectionRef.current;
+    const url = linkUrl.trim();
+    nativeRef.current?.setLink(start, end, text || url, url);
+    setLinkOpen(false);
+  }, [linkUrl]);
+  const insertImage = useCallback(async () => {
+    if (!onRequestImage) return;
+    setImageBusy(true);
+    try {
+      const picked = await onRequestImage();
+      if (!picked || picked.width <= 0 || picked.height <= 0) return;
+      // Native `addImage` silently no-ops on a null selection, which is what an unfocused editor has.
+      nativeRef.current?.focus();
+      nativeRef.current?.setImage(picked.uri, picked.width, picked.height);
+    } catch (error) {
+      // Gated exactly as `FileUpload`/`PixelizeProvider` gate theirs — skipped only when `__DEV__`
+      // is DEFINITELY false, and never swallowed silently.
+      const isDefinitelyProd = typeof __DEV__ !== "undefined" && !__DEV__;
+      if (!isDefinitelyProd) {
+        console.warn("[pixelize-native-library] <RichTextEditor> onRequestImage rejected — nothing was inserted.", error);
+      }
+    } finally {
+      setImageBusy(false);
+    }
+  }, [onRequestImage]);
+
+  // Stable per (action → () => void), independent of theme/render — a fresh inline closure per
+  // toolbar Button would defeat its `React.memo` (CLAUDE.md "Performance", same discipline
+  // Menu/Select/MultiSelect follow for their option lists).
+  const runAction = useCallback(action => {
+    if (action === "link") {
+      openLinkDialog();
+      return;
+    }
+    if (action === "image") {
+      void insertImage();
+      return;
+    }
+    const editor = nativeRef.current;
+    if (!editor) return;
+    switch (action) {
+      case "bold":
+        editor.toggleBold();
+        break;
+      case "italic":
+        editor.toggleItalic();
+        break;
+      case "underline":
+        editor.toggleUnderline();
+        break;
+      case "strikethrough":
+        editor.toggleStrikeThrough();
+        break;
+      case "inlineCode":
+        editor.toggleInlineCode();
+        break;
+      case "h1":
+        editor.toggleH1();
+        break;
+      case "h2":
+        editor.toggleH2();
+        break;
+      case "h3":
+        editor.toggleH3();
+        break;
+      case "blockQuote":
+        editor.toggleBlockQuote();
+        break;
+      case "codeBlock":
+        editor.toggleCodeBlock();
+        break;
+      case "unorderedList":
+        editor.toggleUnorderedList();
+        break;
+      case "orderedList":
+        editor.toggleOrderedList();
+        break;
+      case "checkboxList":
+        editor.toggleCheckboxList(false);
+        break;
+      case "mention":
+        editor.startMention(MENTION_INDICATOR);
+        break;
+    }
+  }, [insertImage, openLinkDialog]);
+  const actionHandlers = useMemo(() => {
+    const handlers = {};
+    for (const item of RICH_TEXT_EDITOR_TOOLBAR_ITEMS) {
+      handlers[item.action] = () => runAction(item.action);
+    }
+    return handlers;
+  }, [runAction]);
+  const mentionKeyExtractor = useCallback(user => String(user.id), []);
+  const renderMentionItem = useCallback(({
+    item: user
+  }) => /*#__PURE__*/_jsx(MentionRow, {
+    id: user.id,
+    label: user.label,
+    theme: theme,
+    colors: colors,
+    onSelect: selectMention
+  }), [theme, colors, selectMention]);
+  const toolbarItems = useMemo(() => RICH_TEXT_EDITOR_TOOLBAR_ITEMS.filter(item => (item.action !== "mention" || mentionEnabled) && (item.action !== "image" || onRequestImage !== undefined)), [mentionEnabled, onRequestImage]);
+  const rootStyle = useMemo(() => [richTextEditorLayout(theme), containerStyle], [theme, containerStyle]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.default
+  }], [theme]);
+  const cardStyle = useMemo(() => [richTextEditorCardStructure(theme), {
+    backgroundColor: colors.cardBackground,
+    borderColor: focused ? colors.cardBorderFocus : colors.cardBorder
+  }], [theme, colors, focused]);
+  const toolbarStyle = useMemo(() => [richTextEditorToolbarStructure(theme), {
+    borderColor: colors.toolbarDivider,
+    backgroundColor: colors.toolbarBackground
+  }], [theme, colors.toolbarDivider, colors.toolbarBackground]);
+  const dropdownStyle = useMemo(() => [richTextEditorMentionDropdownStructure(theme), {
+    backgroundColor: colors.mentionDropdownBackground,
+    borderColor: colors.mentionDropdownBorder
+  }], [theme, colors.mentionDropdownBackground, colors.mentionDropdownBorder]);
+  const focusRingStyle = useMemo(() => ({
+    position: "absolute",
+    top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    borderWidth: FOCUS_RING_WIDTH,
+    borderColor: theme.colors.border.focus,
+    borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+  }), [theme]);
+  const linkBodyStyle = useMemo(() => ({
+    rowGap: theme.space[4]
+  }), [theme.space]);
+  const linkActionsStyle = useMemo(() => ({
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    columnGap: theme.space[2]
+  }), [theme.space]);
+  return /*#__PURE__*/_jsxs(View, {
+    style: rootStyle,
+    children: [label !== undefined && /*#__PURE__*/_jsx(Text, {
+      "aria-hidden": a11y["aria-hidden"],
+      style: labelStyle,
+      children: label
+    }), /*#__PURE__*/_jsxs(View, {
+      testID: testID ? `${testID}-card` : undefined,
+      style: cardStyle,
+      children: [/*#__PURE__*/_jsx(View, {
+        style: toolbarStyle,
+        children: /*#__PURE__*/_jsx(ScrollView, {
+          horizontal: true,
+          showsHorizontalScrollIndicator: false,
+          keyboardShouldPersistTaps: "always",
+          children: toolbarItems.map(item => {
+            const active = activeActions[item.action] === true;
+            return /*#__PURE__*/_jsx(Button, {
+              icon: item.icon,
+              accessibilityLabel: item.label,
+              variant: active ? "solid" : "outline"
+              // Without this the toggle state is carried by `variant`'s colour alone (WCAG 1.4.1).
+              ,
+              selected: item.toggle ? active : undefined,
+              tone: "neutral",
+              size: "sm",
+              loading: item.action === "image" && imageBusy,
+              onPress: actionHandlers[item.action],
+              testID: testID ? `${testID}-${item.action}` : undefined
+            }, item.action);
+          })
+        })
+      }), /*#__PURE__*/_jsxs(View, {
+        style: styles.fieldWrap,
+        children: [/*#__PURE__*/_jsx(EnrichedTextInput, {
+          ref: nativeRef,
+          testID: testID,
+          accessibilityLabel: a11y.accessibilityLabel,
+          editable: editable,
+          defaultValue: defaultValue,
+          placeholder: placeholder,
+          placeholderTextColor: colors.placeholder,
+          cursorColor: colors.cursor,
+          selectionColor: colors.selection,
+          mentionIndicators: mentionEnabled ? MENTION_INDICATORS : EMPTY_MENTION_INDICATORS,
+          htmlStyle: htmlStyle,
+          style: fieldStyle,
+          scrollEnabled: scrollEnabled,
+          useHtmlNormalizer: useHtmlNormalizer,
+          onFocus: handleFocus,
+          onBlur: handleBlur,
+          onChangeText: handleChangeText,
+          onChangeSelection: handleChangeSelection,
+          onChangeState: handleChangeState,
+          onStartMention: handleStartMention,
+          onChangeMention: handleChangeMention,
+          onEndMention: handleEndMention
+        }), mentionQuery !== null && mentionCandidates.length > 0 && /*#__PURE__*/_jsx(View, {
+          style: dropdownStyle,
+          children: /*#__PURE__*/_jsx(VirtualList, {
+            data: mentionCandidates,
+            keyExtractor: mentionKeyExtractor,
+            renderItem: renderMentionItem,
+            itemHeight: MENTION_ROW_HEIGHT
+            // The dropdown only exists while the mention session (and so the keyboard) is up,
+            // so no tap anywhere on it may dismiss the keyboard — `"handled"` still would, for
+            // taps landing between rows, which ends the session mid-selection.
+            ,
+            keyboardShouldPersistTaps: "always"
+          })
+        })]
+      }), focused && /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        testID: "rich-text-editor-focus-ring",
+        style: focusRingStyle
+      })]
+    }), /*#__PURE__*/_jsx(Modal, {
+      visible: linkOpen,
+      onRequestClose: closeLinkDialog,
+      title: "Insert link",
+      size: "sm",
+      children: /*#__PURE__*/_jsxs(View, {
+        style: linkBodyStyle,
+        children: [/*#__PURE__*/_jsx(Input, {
+          value: linkUrl,
+          onChangeText: setLinkUrl,
+          label: "URL",
+          placeholder: "https://example.com",
+          leadingIcon: "link"
+        }), /*#__PURE__*/_jsxs(View, {
+          style: linkActionsStyle,
+          children: [/*#__PURE__*/_jsx(Button, {
+            label: "Cancel",
+            variant: "ghost",
+            tone: "neutral",
+            onPress: closeLinkDialog
+          }), /*#__PURE__*/_jsx(Button, {
+            label: "Insert",
+            variant: "solid",
+            tone: "accent",
+            onPress: confirmLink
+          })]
+        })]
+      })
+    })]
+  });
+}
+const styles = StyleSheet.create({
+  fieldWrap: {
+    position: "relative"
+  }
+});
+
+// A consumer's screen re-renders far more often than this component's own props change — memo is
+// near-free insurance for a design-system primitive (CLAUDE.md "Performance").
+export const RichTextEditor = /*#__PURE__*/memo(/*#__PURE__*/forwardRef(RichTextEditorImpl));
+//# sourceMappingURL=RichTextEditor.js.map