@apollohg/react-native-rich-text-editor 2.0.0

package/common/cpp/react/renderer/components/PreparedProseViewer/PreparedProseViewerShadowNode.cpp

@@ -0,0 +1,192 @@
+#include "PreparedProseViewerShadowNode.h"
+
+#include <react/renderer/core/LayoutContext.h>
+
+#include <cmath>
+#include <atomic>
+#include <limits>
+#include <optional>
+
+namespace facebook::react {
+
+namespace {
+
+bool HasRepresentablePhysicalWidth(Float width, Float scale) {
+  if (!std::isfinite(width) || width <= 0 || !std::isfinite(scale) ||
+      scale <= 0) {
+    return false;
+  }
+  const double physicalWidth = static_cast<double>(width) * static_cast<double>(scale);
+  if (!std::isfinite(physicalWidth) || physicalWidth <= 0) {
+    return false;
+  }
+  const double roundedWidth = std::round(physicalWidth);
+  const double largestConvertible = std::nextafter(
+      static_cast<double>(std::numeric_limits<long long>::max()), 0.0);
+  return std::isfinite(roundedWidth) && roundedWidth > 0 &&
+      roundedWidth <= largestConvertible;
+}
+
+std::optional<int32_t> CheckedPhysicalPixel(
+    Float value,
+    Float scale,
+    bool allowZero) {
+  if (!std::isfinite(value) || !std::isfinite(scale) || scale <= 0) {
+    return std::nullopt;
+  }
+  const auto physical = std::round(
+      static_cast<double>(value) * static_cast<double>(scale));
+  if (!std::isfinite(physical) || (!allowZero && physical <= 0) ||
+      physical < static_cast<double>(std::numeric_limits<int32_t>::min()) ||
+      physical > static_cast<double>(std::numeric_limits<int32_t>::max())) {
+    return std::nullopt;
+  }
+  return static_cast<int32_t>(physical);
+}
+
+uint64_t FontEnvironmentRevision(const PreparedProseViewerProps &props) {
+  const double value = static_cast<double>(props.fontEnvironmentRevision);
+  const double largestConvertible = std::nextafter(
+      static_cast<double>(std::numeric_limits<uint64_t>::max()), 0.0);
+  return std::isfinite(value) && value > 0 && value <= largestConvertible
+      ? static_cast<uint64_t>(value)
+      : 0;
+}
+
+uint64_t NextFabricLeaseHandle() {
+  // The Android JNI contract is a signed jlong.  Stop rather than wrapping:
+  // aliasing a still-live owner would be worse than declining a theoretical
+  // 9e18th viewer incarnation.
+  static std::atomic<int64_t> next{0};
+  for (;;) {
+    auto current = next.load(std::memory_order_relaxed);
+    if (current < 0 || current == std::numeric_limits<int64_t>::max()) {
+      return 0;
+    }
+    // compare_exchange_weak writes the observed value back to `current` on a
+    // collision. Restart from that value: falling through after a failed
+    // zero-to-one race would hand the losing family an invalid zero handle.
+    if (next.compare_exchange_weak(
+            current, current + 1, std::memory_order_relaxed,
+            std::memory_order_relaxed)) {
+      return static_cast<uint64_t>(current + 1);
+    }
+  }
+}
+
+} // namespace
+
+extern const char PreparedProseViewerComponentName[] = "PreparedProseViewer";
+
+ShadowNodeTraits PreparedProseViewerShadowNode::BaseTraits() {
+  auto traits = ConcreteViewShadowNode::BaseTraits();
+  traits.set(ShadowNodeTraits::Trait::LeafYogaNode);
+  traits.set(ShadowNodeTraits::Trait::MeasurableYogaNode);
+  return traits;
+}
+
+PreparedProseViewerShadowNode::ConcreteStateData
+PreparedProseViewerShadowNode::initialStateData(
+    const Props::Shared& /*props*/,
+    const ShadowNodeFamily::Shared& family,
+    const ComponentDescriptor& /*componentDescriptor*/) {
+  PreparedProseViewerState state;
+  state.leaseHandle = NextFabricLeaseHandle();
+  state.surfaceId = family->getSurfaceId();
+  state.componentTag = family->getEventEmitter()->getEventTarget()->getTag();
+  state.leaseLifecycle = std::make_shared<PreparedProseViewerLeaseLifecycle>();
+  return state;
+}
+
+void PreparedProseViewerShadowNode::setMeasurementsManager(
+    const std::shared_ptr<PreparedProseMeasurementsManager>&
+        measurementsManager) {
+  ensureUnsealed();
+  measurementsManager_ = measurementsManager;
+}
+
+Size PreparedProseViewerShadowNode::measureContent(
+    const LayoutContext& layoutContext,
+    const LayoutConstraints& layoutConstraints) const {
+  const auto maximumWidth = layoutConstraints.maximumSize.width;
+  const auto pointScaleFactor = layoutContext.pointScaleFactor;
+  if (!measurementsManager_) {
+    return {};
+  }
+
+  const auto hasUsableMeasurement =
+      HasRepresentablePhysicalWidth(maximumWidth, pointScaleFactor);
+  const auto effectiveWidth = hasUsableMeasurement
+      ? std::round(maximumWidth * pointScaleFactor) / pointScaleFactor
+      : maximumWidth;
+  const auto& props = getConcreteProps();
+  const auto& state = getStateData();
+  // The committed state mints this once, before Yoga's first measurement.
+  // A delayed callback from a released incarnation may still calculate an
+  // unowned size, but it must never recreate a Fabric lease or sidecar.
+  const auto leaseHandle = state.leaseLifecycle && state.leaseLifecycle->isActive()
+      ? state.leaseHandle
+      : 0;
+  if (leaseHandle != 0) {
+    measurementsManager_->bindLeaseLifecycle(
+        getSurfaceId(), getTag(), leaseHandle, state.leaseLifecycle);
+  }
+  return measurementsManager_->measure(
+      getSurfaceId(),
+      getTag(),
+      props,
+      effectiveWidth,
+      pointScaleFactor,
+      state.attachmentRevision,
+      state.nativeFontRevision,
+      state.nativeFontScale,
+      state.userInterfaceStyle,
+      state.accessibilityContrast,
+      FontEnvironmentRevision(props),
+      leaseHandle,
+      state.leaseLifecycle);
+}
+
+void PreparedProseViewerShadowNode::layout(LayoutContext layoutContext) {
+  ConcreteViewShadowNode::layout(layoutContext);
+  if (!measurementsManager_) {
+    return;
+  }
+  const auto metrics = getLayoutMetrics();
+  const auto contentFrame = getLayoutMetrics().getContentFrame();
+  const auto scale = metrics.pointScaleFactor;
+  const auto widthPx = CheckedPhysicalPixel(contentFrame.size.width, scale, false);
+  const auto originXPx = CheckedPhysicalPixel(contentFrame.origin.x, scale, true);
+  const auto originYPx = CheckedPhysicalPixel(contentFrame.origin.y, scale, true);
+  if (!widthPx || !originXPx || !originYPx) {
+    return;
+  }
+  const auto& props = getConcreteProps();
+  const auto& state = getStateData();
+  const auto leaseHandle = state.leaseLifecycle && state.leaseLifecycle->isActive()
+      ? state.leaseHandle
+      : 0;
+  if (leaseHandle == 0) {
+    return;
+  }
+  measurementsManager_->bindLeaseLifecycle(
+      getSurfaceId(), getTag(), leaseHandle, state.leaseLifecycle);
+  measurementsManager_->prepareFinalLayout(
+      getSurfaceId(),
+      getTag(),
+      props,
+      *widthPx,
+      *originXPx,
+      *originYPx,
+      scale,
+      state.attachmentRevision,
+      state.nativeFontRevision,
+      state.nativeFontScale,
+      state.userInterfaceStyle,
+      state.accessibilityContrast,
+      FontEnvironmentRevision(props),
+      leaseHandle,
+      state.leaseLifecycle);
+}
+
+} // namespace facebook::react

package/common/cpp/react/renderer/components/PreparedProseViewer/PreparedProseViewerShadowNode.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include "PreparedProseMeasurementsManager.h"
+#include "PreparedProseViewerState.h"
+
+#include <react/renderer/components/ReactNativeProseEditorSpec/EventEmitters.h>
+#include <react/renderer/components/ReactNativeProseEditorSpec/Props.h>
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+
+namespace facebook::react {
+
+class ComponentDescriptor;
+
+extern const char PreparedProseViewerComponentName[];
+
+class PreparedProseViewerShadowNode final
+    : public ConcreteViewShadowNode<
+          PreparedProseViewerComponentName,
+          PreparedProseViewerProps,
+          PreparedProseViewerEventEmitter,
+          PreparedProseViewerState> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+
+  static ShadowNodeTraits BaseTraits();
+
+  static ConcreteStateData initialStateData(
+      const Props::Shared& props,
+      const ShadowNodeFamily::Shared& family,
+      const ComponentDescriptor& componentDescriptor);
+
+  void setMeasurementsManager(
+      const std::shared_ptr<PreparedProseMeasurementsManager>&
+          measurementsManager);
+
+  Size measureContent(
+      const LayoutContext& layoutContext,
+      const LayoutConstraints& layoutConstraints) const override;
+
+  void layout(LayoutContext layoutContext) override;
+
+ private:
+  std::shared_ptr<PreparedProseMeasurementsManager> measurementsManager_;
+};
+
+} // namespace facebook::react

package/common/cpp/react/renderer/components/PreparedProseViewer/PreparedProseViewerState.h

@@ -0,0 +1,145 @@
+#pragma once
+
+#include <cmath>
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <functional>
+#include <mutex>
+
+#include <react/renderer/core/ReactPrimitives.h>
+
+#ifdef ANDROID
+#include <folly/dynamic.h>
+#endif
+
+namespace facebook::react {
+
+/// Shared by every Fabric state clone for one viewer incarnation. The shadow
+/// node checks this before handing work to a platform registry, while a
+/// recycled component view deactivates it before releasing its exact lease.
+/// Its lifetime is bounded by the state snapshots that reference it.
+class PreparedProseViewerLeaseLifecycle final {
+ public:
+  ~PreparedProseViewerLeaseLifecycle() {
+    deactivate();
+    std::function<void()> cleanup;
+    {
+      std::lock_guard<std::mutex> lock(cleanupMutex_);
+      cleanup = std::move(cleanup_);
+    }
+    if (cleanup) cleanup();
+  }
+
+  bool isActive() const {
+    return active_.load(std::memory_order_acquire);
+  }
+
+  void deactivate() {
+    active_.store(false, std::memory_order_release);
+  }
+
+  // The platform bridge binds this once the first measurement knows the
+  // concrete Fabric surface/tag. It is held by shared state data, so ordinary
+  // state clones cannot fire it; it runs only when the family incarnation's
+  // final snapshot dies.
+  void bindTerminalCleanup(std::function<void()> cleanup) {
+    std::lock_guard<std::mutex> lock(cleanupMutex_);
+    if (!cleanup_) cleanup_ = std::move(cleanup);
+  }
+
+ private:
+  std::atomic<bool> active_{true};
+  std::mutex cleanupMutex_;
+  std::function<void()> cleanup_;
+};
+
+struct PreparedProseViewerState final {
+  uint64_t attachmentRevision{0};
+  uint64_t nativeFontRevision{0};
+  // A native Dynamic Type invalidation carries the scale that caused it.
+  // The JS revision can remain unchanged, so it cannot select this snapshot.
+  double nativeFontScale{1.0};
+  int32_t userInterfaceStyle{0};
+  int32_t accessibilityContrast{0};
+  // Opaque, native-owned Fabric handoff incarnation. The shadow node mints it
+  // once and component views must pass this exact value back to the registry.
+  uint64_t leaseHandle{0};
+  SurfaceId surfaceId{0};
+  Tag componentTag{0};
+  // This is deliberately C++-only state. Dynamic platform updates retain the
+  // previous lifecycle when they omit the native-owned handle.
+  std::shared_ptr<PreparedProseViewerLeaseLifecycle> leaseLifecycle{};
+
+#ifdef ANDROID
+  PreparedProseViewerState() = default;
+
+  PreparedProseViewerState(
+      const PreparedProseViewerState& previousState,
+      const folly::dynamic& data)
+      : attachmentRevision(revisionValue(data, "attachmentRevision")),
+        nativeFontRevision(revisionValue(data, "nativeFontRevision")),
+        nativeFontScale(scaleValue(data, "nativeFontScale")),
+        userInterfaceStyle(previousState.userInterfaceStyle),
+        accessibilityContrast(previousState.accessibilityContrast),
+        leaseHandle(handleValue(data, "leaseHandle", previousState.leaseHandle)),
+        surfaceId(previousState.surfaceId),
+        componentTag(previousState.componentTag),
+        leaseLifecycle(lifecycleValue(previousState, leaseHandle)) {}
+
+  folly::dynamic getDynamic() const {
+    return folly::dynamic::object("attachmentRevision", attachmentRevision)(
+        "nativeFontRevision", nativeFontRevision)(
+        "nativeFontScale", nativeFontScale)(
+        // ReadableMap exposes numeric values as doubles on Android. Preserve
+        // this opaque Int64 identity as decimal text at the state boundary;
+        // the synchronous JNI measurement path still carries a real jlong.
+        "leaseHandle", std::to_string(static_cast<int64_t>(leaseHandle)));
+  }
+
+ private:
+  static uint64_t revisionValue(const folly::dynamic& data, const char* key) {
+    const auto value = data.getDefault(key, 0).asInt();
+    return value > 0 ? static_cast<uint64_t>(value) : 0;
+  }
+
+  static double scaleValue(const folly::dynamic& data, const char* key) {
+    const auto value = data.getDefault(key, 1.0).asDouble();
+    return std::isfinite(value) && value > 0.0 ? value : 1.0;
+  }
+
+  static uint64_t handleValue(
+      const folly::dynamic& data,
+      const char* key,
+      uint64_t fallback) {
+    if (data.count(key) == 0) {
+      return fallback;
+    }
+    if (data[key].isString()) {
+      try {
+        const auto value = std::stoll(data[key].asString());
+        return value > 0 ? static_cast<uint64_t>(value) : 0;
+      } catch (...) {
+        return 0;
+      }
+    }
+    const auto value = data.getDefault(key, 0).asInt();
+    return value > 0 ? static_cast<uint64_t>(value) : 0;
+  }
+
+  static std::shared_ptr<PreparedProseViewerLeaseLifecycle> lifecycleValue(
+      const PreparedProseViewerState& previousState,
+      uint64_t handle) {
+    if (handle == 0) {
+      return nullptr;
+    }
+    if (handle == previousState.leaseHandle && previousState.leaseLifecycle) {
+      return previousState.leaseLifecycle;
+    }
+    return std::make_shared<PreparedProseViewerLeaseLifecycle>();
+  }
+#endif
+};
+
+} // namespace facebook::react

package/dist/AtomHost.d.ts

@@ -0,0 +1,17 @@
+import type { AtomComponent, AtomComponentProps } from './atoms';
+export interface AtomViewport {
+    /** Visible vertical range in the atom layout's coordinate space, in points. */
+    y: number;
+    height: number;
+    overscan?: number;
+}
+export declare function atomIsVisible(y: number, height: number, viewport?: AtomViewport): boolean;
+export declare function AtomHost({ component: Component, atomProps, width, estimatedHeight, visible, onMeasure, nativeID, }: {
+    component: AtomComponent;
+    atomProps: Omit<AtomComponentProps, 'updatePending' | 'updateError' | 'setActive'>;
+    width: number;
+    estimatedHeight: number;
+    visible?: boolean;
+    onMeasure?: (event: import('react-native').LayoutChangeEvent) => void;
+    nativeID?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/AtomHost.js

@@ -0,0 +1,135 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomIsVisible = atomIsVisible;
+exports.AtomHost = AtomHost;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const atomInstances_1 = require("./atomInstances");
+function atomIsVisible(y, height, viewport) {
+    if (!viewport)
+        return true;
+    if (![viewport.y, viewport.height, viewport.overscan ?? 200].every(Number.isFinite) ||
+        viewport.height < 0 ||
+        (viewport.overscan ?? 200) < 0) {
+        throw new Error('Atom viewport must have finite coordinates and non-negative height and overscan.');
+    }
+    const overscan = viewport.overscan ?? 200;
+    return y + height >= viewport.y - overscan && y <= viewport.y + viewport.height + overscan;
+}
+class AtomErrorBoundary extends react_1.default.Component {
+    constructor() {
+        super(...arguments);
+        this.state = { error: false, component: this.props.component };
+    }
+    static getDerivedStateFromError() {
+        return { error: true };
+    }
+    static getDerivedStateFromProps(props, state) {
+        return props.component === state.component
+            ? null
+            : { component: props.component, error: false };
+    }
+    render() {
+        if (!this.state.error)
+            return this.props.children;
+        return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { accessibilityRole: 'alert', style: { minHeight: 32, padding: 8 }, children: [(0, jsx_runtime_1.jsxs)(react_native_1.Text, { children: ["Unable to display ", this.props.nodeType] }), (0, jsx_runtime_1.jsx)(react_native_1.Pressable, { accessibilityRole: 'button', onPress: () => this.setState({ error: false }), children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { children: "Retry" }) })] }));
+    }
+}
+function AtomHost({ component: Component, atomProps, width, estimatedHeight, visible = true, onMeasure, nativeID, }) {
+    const [measurement, setMeasurement] = (0, react_1.useState)({ width, height: estimatedHeight });
+    const [focused, setFocused] = (0, react_1.useState)(false);
+    const [active, setActive] = (0, react_1.useState)(false);
+    const [pending, setPending] = (0, react_1.useState)(0);
+    const [updateError, setUpdateError] = (0, react_1.useState)(null);
+    const latestRequest = (0, react_1.useRef)(0);
+    const applyUpdate = atomProps.updateAttrs;
+    const mounted = (0, react_1.useRef)(true);
+    (0, react_1.useEffect)(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const updateAttrs = (0, react_1.useCallback)(async (update) => {
+        if (!mounted.current)
+            throw new atomInstances_1.AtomUpdateAttrsError('not-ready', 'The atom is unmounted.');
+        const request = ++latestRequest.current;
+        setPending((count) => count + 1);
+        setUpdateError(null);
+        try {
+            await applyUpdate(update);
+        }
+        catch (error) {
+            if (mounted.current && latestRequest.current === request)
+                setUpdateError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            if (mounted.current)
+                setPending((count) => count - 1);
+        }
+    }, [applyUpdate]);
+    const editor = (0, react_1.useMemo)(() => {
+        if (!atomProps.editor)
+            return undefined;
+        const guard = (action) => async () => {
+            if (!mounted.current)
+                throw new atomInstances_1.AtomUpdateAttrsError('not-ready', 'The atom is unmounted.');
+            return action();
+        };
+        return {
+            select: guard(atomProps.editor.select),
+            delete: guard(atomProps.editor.delete),
+            focusBefore: guard(atomProps.editor.focusBefore),
+            focusAfter: guard(atomProps.editor.focusAfter),
+        };
+    }, [atomProps.editor]);
+    const retainedHeight = measurement.width === width ? measurement.height : estimatedHeight;
+    const show = visible || focused || active || pending > 0 || atomProps.selected;
+    return ((0, jsx_runtime_1.jsx)(react_native_1.View, { testID: 'atom-host', nativeID: nativeID, collapsable: false, pointerEvents: atomProps.interactive === false ? 'none' : 'box-none', accessibilityElementsHidden: !show, importantForAccessibility: !show ? 'no-hide-descendants' : 'auto', onFocus: () => setFocused(true), onBlur: () => setFocused(false), onLayout: (event) => {
+            onMeasure?.(event);
+            const size = event.nativeEvent.layout;
+            if (show &&
+                Number.isFinite(size.height) &&
+                size.height >= 0 &&
+                Math.abs(size.width - width) <= 1) {
+                setMeasurement((previous) => previous.width === width && previous.height === size.height
+                    ? previous
+                    : { width, height: size.height });
+            }
+        }, style: show ? undefined : { height: retainedHeight }, children: show && ((0, jsx_runtime_1.jsx)(AtomErrorBoundary, { component: Component, nodeType: atomProps.nodeType, children: (0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: (0, jsx_runtime_1.jsx)(react_native_1.View, { style: { height: retainedHeight }, children: (0, jsx_runtime_1.jsxs)(react_native_1.Text, { children: ["Loading ", atomProps.nodeType, "\u2026"] }) }), children: (0, jsx_runtime_1.jsx)(Component, { ...atomProps, editor: editor, updateAttrs: updateAttrs, updatePending: pending > 0, updateError: updateError, setActive: setActive }) }) })) }));
+}

package/dist/DefaultAtomChip.d.ts

@@ -0,0 +1,2 @@
+import type { AtomComponentProps } from './atoms';
+export declare function DefaultAtomChip({ nodeType }: AtomComponentProps): import("react/jsx-runtime").JSX.Element;

package/dist/DefaultAtomChip.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultAtomChip = DefaultAtomChip;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_native_1 = require("react-native");
+const atomConstants_1 = require("./atomConstants");
+function DefaultAtomChip({ nodeType }) {
+    return ((0, jsx_runtime_1.jsx)(react_native_1.View, { style: styles.container, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.label, children: nodeType }) }));
+}
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        minHeight: atomConstants_1.DEFAULT_ATOM_CHIP_HEIGHT,
+        justifyContent: 'center',
+        paddingHorizontal: 10,
+        borderRadius: 6,
+        backgroundColor: '#E5E7EB',
+    },
+    label: {
+        color: '#374151',
+        fontSize: 13,
+    },
+});

package/dist/EditorAddon.d.ts

@@ -0,0 +1,32 @@
+import type { MentionsAddonConfig } from './addons';
+export interface MentionPressEvent {
+    docPos: number;
+    label: string;
+    attrs: Record<string, unknown>;
+}
+export interface MentionsAddonOptions extends MentionsAddonConfig {
+    /** Prepended to viewer mention labels unless already present. */
+    prefix?: string;
+    /** Enables mention presses in the viewer. */
+    onPress?: (event: MentionPressEvent) => void;
+}
+export interface CodeHighlightingAddonOptions {
+    readonly provider: string;
+    readonly theme: string;
+}
+export interface MentionsAddon {
+    readonly id: 'mentions';
+    readonly version: 1;
+    readonly capability: 'mentions';
+    readonly options: Readonly<MentionsAddonOptions>;
+}
+export interface CodeHighlightingAddon {
+    readonly id: 'code-highlighting';
+    readonly version: 1;
+    readonly capability: 'code-highlighting';
+    readonly options: CodeHighlightingAddonOptions;
+}
+export type EditorAddon = MentionsAddon | CodeHighlightingAddon;
+export type EditorAddonEntry = EditorAddon | false | null | undefined;
+export type EditorAddons = readonly EditorAddonEntry[];
+export declare function createMentionsAddon(options?: MentionsAddonOptions): MentionsAddon;

package/dist/EditorAddon.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMentionsAddon = createMentionsAddon;
+function copyConfiguration(value, ancestors = new Set()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (ancestors.has(value))
+        throw new Error('Addon configuration must not contain cycles.');
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('Addon configuration must contain only plain objects and arrays.');
+    }
+    ancestors.add(value);
+    const copy = Array.isArray(value)
+        ? value.map((entry) => copyConfiguration(entry, ancestors))
+        : Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            copyConfiguration(entry, ancestors),
+        ]));
+    ancestors.delete(value);
+    return Object.freeze(copy);
+}
+function createMentionsAddon(options = {}) {
+    return Object.freeze({
+        id: 'mentions',
+        version: 1,
+        capability: 'mentions',
+        options: copyConfiguration(options),
+    });
+}

package/dist/EditorAddonNormalization.d.ts

@@ -0,0 +1,6 @@
+import type { CodeHighlightingAddonOptions, EditorAddons, MentionsAddonOptions } from './EditorAddon';
+export interface NormalizedEditorAddons {
+    mentions?: Readonly<MentionsAddonOptions>;
+    codeHighlighting?: CodeHighlightingAddonOptions;
+}
+export declare function normalizeEditorAddons(addons?: EditorAddons): NormalizedEditorAddons;

package/dist/EditorAddonNormalization.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEditorAddons = normalizeEditorAddons;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeEditorAddons(addons) {
+    if (addons === undefined)
+        return {};
+    if (!Array.isArray(addons))
+        throw new Error('addons must be a flat readonly array.');
+    const normalized = {};
+    const ids = new Set();
+    for (const [index, addon] of addons.entries()) {
+        if (addon === false || addon === null || addon === undefined)
+            continue;
+        const path = `addons[${index}]`;
+        if (!isRecord(addon))
+            throw new Error(`${path} must be an addon descriptor.`);
+        if (addon.version !== 1)
+            throw new Error(`${path}.version must be 1.`);
+        if (addon.capability !== 'mentions' && addon.capability !== 'code-highlighting') {
+            throw new Error(`${path}.capability is unsupported.`);
+        }
+        if (addon.id !== addon.capability)
+            throw new Error(`${path}.id must match its capability.`);
+        if (ids.has(addon.capability))
+            throw new Error(`${path}: duplicate addon id '${addon.id}'.`);
+        ids.add(addon.capability);
+        if (!isRecord(addon.options))
+            throw new Error(`${path}.options must be an object.`);
+        if (addon.capability === 'mentions') {
+            normalized.mentions = addon.options;
+        }
+        else {
+            for (const key of ['provider', 'theme']) {
+                if (typeof addon.options[key] !== 'string' || !addon.options[key].trim()) {
+                    throw new Error(`${path}.options.${key} must be a nonempty string.`);
+                }
+            }
+            normalized.codeHighlighting = {
+                provider: addon.options.provider,
+                theme: addon.options.theme,
+            };
+        }
+    }
+    return normalized;
+}