@lexical/a11y 0.0.0-bootstrap.0 → 0.46.1-nightly.20260706.0

package/README.md

@@ -1,3 +1,5 @@
-# @lexical/a11y
+# `@lexical/a11y`
 
-This 0.0.0-bootstrap.0 placeholder was published only to claim the npm package name so trusted publishing can be configured on npmjs.com. It contains no code; a future release will replace it.
+[![See API Documentation](https://lexical.dev/img/see-api-documentation.svg)](https://lexical.dev/docs/api/modules/lexical_a11y)
+
+Framework-agnostic accessibility helpers for Lexical: ARIA live regions, focus management, roving tab index, and focus trap. Usable from React, Svelte, Vue, Solid, or vanilla DOM. React-specific wrappers around the same primitives ship from `@lexical/react`.

package/dist/LexicalA11y.dev.js

@@ -0,0 +1,533 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+
+var extension = require('@lexical/extension');
+var lexical = require('lexical');
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+function applyVisuallyHidden(el) {
+  const style = el.style;
+  style.border = '0';
+  style.clip = 'rect(0 0 0 0)';
+  style.height = '1px';
+  style.margin = '-1px';
+  style.overflow = 'hidden';
+  style.padding = '0';
+  style.position = 'absolute';
+  style.whiteSpace = 'nowrap';
+  style.width = '1px';
+}
+
+/**
+ * Creates a visually hidden live-region element as a child of `owner` and
+ * returns it. WAI-ARIA status message pattern (WCAG 4.1.3). The caller owns
+ * the element's lifetime (removal) and applies the `aria-live` politeness and
+ * `textContent` reactively.
+ */
+function createLiveRegion(owner) {
+  const region = owner.ownerDocument.createElement('div');
+  region.setAttribute('aria-atomic', 'true');
+  region.setAttribute('role', 'status');
+  applyVisuallyHidden(region);
+  owner.appendChild(region);
+  return region;
+}
+const FOCUSABLE_SELECTOR = ['a[href]', 'button:not([disabled])', 'input:not([disabled]):not([type="hidden"])', 'select:not([disabled])', 'textarea:not([disabled])', '[tabindex]:not([tabindex="-1"])', '[contenteditable="true"]'].join(',');
+function getFocusableElements(container) {
+  return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+}
+function containsComposed(container, target) {
+  let current = target;
+  while (current !== null) {
+    if (current === container) {
+      return true;
+    }
+    if (lexical.isDOMShadowRoot(current)) {
+      current = current.host;
+    } else {
+      current = current.parentNode;
+    }
+  }
+  return false;
+}
+/**
+ * Traps Tab / Shift+Tab focus inside `container` and restores focus to
+ * the previously-focused element when the returned dispose runs.
+ * Intended for modal dialogs and other transient overlays.
+ *
+ * While active, *any* focus that lands outside the container is pulled
+ * back inside via a document-level `focusin` listener. This recovers
+ * from Safari's default Tab routing through the browser chrome, but it
+ * also means descendants that mount into a portal outside `container`
+ * (autocomplete panels, tooltips, toasts that auto-focus themselves)
+ * will be yanked back as soon as they take focus. Portal them inside
+ * `container`, or skip this helper for those dialogs. The pull-back
+ * always lands on the first focusable descendant (or the container as a
+ * fallback) — `initialFocus` only applies to the activation-time
+ * landing, not to subsequent escape recoveries. Only one trap should be
+ * mounted at a time — two active traps install competing document-level
+ * `focusin` listeners and will fight over focus.
+ *
+ * Escape is not intercepted — the owner handles close-key behavior.
+ */
+function registerFocusTrap(container, options = {}) {
+  const initialFocus = options.initialFocus ?? 'firstFocusable';
+  const doc = container.ownerDocument;
+  const deepActive = lexical.getActiveElementDeep(doc);
+  const previouslyFocused = lexical.isHTMLElement(deepActive) ? deepActive : null;
+  const focusable = getFocusableElements(container);
+  if (initialFocus === 'container' && container.hasAttribute('tabindex')) {
+    container.focus();
+  } else if (focusable.length > 0) {
+    focusable[0].focus();
+  } else if (container.hasAttribute('tabindex')) {
+    container.focus();
+  }
+
+  // Full Tab management — every Tab / Shift+Tab is handled here.
+  // Boundary-only cycling let Safari's default Tab route out to the
+  // browser chrome (URL bar) between presses, producing a visible
+  // focus flash. This trades contentEditable Tab indent for a reliable
+  // trap; the helper is Modal-only today.
+  const keydownHandler = event => {
+    if (event.key !== 'Tab') {
+      return;
+    }
+    const currentFocusable = getFocusableElements(container);
+    if (currentFocusable.length === 0) {
+      event.preventDefault();
+      return;
+    }
+    event.preventDefault();
+    const first = currentFocusable[0];
+    const last = currentFocusable[currentFocusable.length - 1];
+    const active = lexical.getActiveElementDeep(doc);
+    const activeIndex = lexical.isHTMLElement(active) && containsComposed(container, active) ? currentFocusable.indexOf(active) : -1;
+    if (event.shiftKey) {
+      (activeIndex <= 0 ? last : currentFocusable[activeIndex - 1]).focus();
+    } else {
+      (activeIndex === -1 || activeIndex === currentFocusable.length - 1 ? first : currentFocusable[activeIndex + 1]).focus();
+    }
+  };
+
+  // Safety net — if focus ever escapes the container (e.g. portal
+  // ordering routes the browser's default Tab past the modal in
+  // Safari), pull it back to the first focusable inside.
+  const focusinHandler = event => {
+    const target = lexical.getComposedEventTarget(event);
+    if (!lexical.isHTMLElement(target) || containsComposed(container, target)) {
+      return;
+    }
+    if (options.allowOutside != null && options.allowOutside(target)) {
+      return;
+    }
+    const currentFocusable = getFocusableElements(container);
+    if (currentFocusable.length > 0) {
+      currentFocusable[0].focus();
+    } else if (container.hasAttribute('tabindex')) {
+      container.focus();
+    }
+  };
+  return lexical.mergeRegister(
+  // Placed first so mergeRegister's reverse (LIFO) teardown runs it last,
+  // after the focusin listener is removed — otherwise restoring focus to an
+  // element outside the container would re-trigger the trap.
+  () => {
+    if (previouslyFocused !== null && typeof previouslyFocused.focus === 'function' && containsComposed(doc, previouslyFocused)) {
+      previouslyFocused.focus();
+    }
+  }, lexical.registerEventListener(container, 'keydown', keydownHandler), lexical.registerEventListener(doc, 'focusin', focusinHandler));
+}
+const DEFAULT_ROVING_SELECTOR = ':scope > button:not([disabled])';
+
+/**
+ * Implements the WAI-ARIA roving-tabindex pattern on `container`. One
+ * item carries `tabindex="0"` at a time; the rest are `-1`. Arrow keys
+ * move focus inside the group; Home / End jump to the ends. Tab leaves
+ * the group as a unit, matching the toolbar / menubar pattern.
+ *
+ * Items are queried lazily on every interaction so additions or
+ * removals during the lifetime of the group are picked up without
+ * extra wiring.
+ */
+function registerRovingTabIndex(container, options = {}) {
+  const orientation = options.orientation ?? 'horizontal';
+  const selector = options.itemSelector ?? DEFAULT_ROVING_SELECTOR;
+  const getItems = () => Array.from(container.querySelectorAll(selector));
+  const applyTabIndex = (items, activeIndex) => {
+    items.forEach((item, i) => {
+      item.tabIndex = i === activeIndex ? 0 : -1;
+    });
+  };
+  const init = () => {
+    const items = getItems();
+    if (items.length === 0) {
+      return;
+    }
+    const active = lexical.getActiveElementDeep(container.ownerDocument);
+    const activeIdx = items.findIndex(el => el === active);
+    applyTabIndex(items, activeIdx >= 0 ? activeIdx : 0);
+  };
+  init();
+  const handler = event => {
+    const items = getItems();
+    if (items.length === 0) {
+      return;
+    }
+    const active = lexical.getActiveElementDeep(container.ownerDocument);
+    const currentIdx = items.findIndex(el => el === active);
+    if (currentIdx < 0) {
+      // Firefox can focus the container itself (e.g. role="toolbar") rather
+      // than a child item. Treat any arrow/Home/End as "enter the group at
+      // the first item" so the user isn't stuck.
+      if (event.key === 'ArrowRight' || event.key === 'ArrowDown' || event.key === 'ArrowLeft' || event.key === 'ArrowUp' || event.key === 'Home' || event.key === 'End') {
+        event.preventDefault();
+        applyTabIndex(items, 0);
+        items[0].focus();
+      }
+      return;
+    }
+    const horizontal = orientation === 'horizontal' || orientation === 'both';
+    const vertical = orientation === 'vertical' || orientation === 'both';
+    let nextIdx = currentIdx;
+    switch (event.key) {
+      case 'ArrowRight':
+        if (!horizontal) {
+          return;
+        }
+        nextIdx = currentIdx + 1;
+        break;
+      case 'ArrowLeft':
+        if (!horizontal) {
+          return;
+        }
+        nextIdx = currentIdx - 1;
+        break;
+      case 'ArrowDown':
+        if (!vertical) {
+          return;
+        }
+        nextIdx = currentIdx + 1;
+        break;
+      case 'ArrowUp':
+        if (!vertical) {
+          return;
+        }
+        nextIdx = currentIdx - 1;
+        break;
+      case 'Home':
+        nextIdx = 0;
+        break;
+      case 'End':
+        nextIdx = items.length - 1;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    // Single wrap for every case: the only out-of-range value is -1 (left/up
+    // from the first item), and `currentIdx >= 0` keeps `nextIdx >= -1`, so one
+    // `+ length` is enough to normalize.
+    nextIdx = (nextIdx + items.length) % items.length;
+    applyTabIndex(items, nextIdx);
+    items[nextIdx].focus();
+  };
+  return lexical.mergeRegister(lexical.registerEventListener(container, 'keydown', handler), () => {
+    const items = getItems();
+    items.forEach(item => {
+      item.tabIndex = 0;
+    });
+  });
+}
+const DEFAULT_TOOLBAR_FOCUSABLE_SELECTOR = ':scope > button:not([disabled]), :scope > [tabindex="0"]';
+/**
+ * Implements the editor-to-toolbar focus jump recommended by the
+ * WAI-ARIA APG editor menubar pattern: Alt+F10 inside the editor moves
+ * focus to the first focusable in `toolbar`, and Escape inside the
+ * toolbar returns focus to the editor.
+ *
+ * Wires the navigation only. Selection restoration relies on the
+ * editor's own focus handling; the editor's last selection is preserved
+ * across the jump so toolbar commands act on the same range.
+ */
+function registerFocusManager(editor, toolbar, options = {}) {
+  const selector = options.toolbarItemSelector ?? DEFAULT_TOOLBAR_FOCUSABLE_SELECTOR;
+  const handler = event => {
+    if (event.key !== 'Escape') {
+      return;
+    }
+    const target = lexical.getComposedEventTarget(event);
+    if (lexical.isHTMLElement(target)) {
+      const items = toolbar.querySelectorAll(selector);
+      let isRovingItem = false;
+      for (const item of items) {
+        if (item === target || containsComposed(item, target)) {
+          isRovingItem = true;
+          break;
+        }
+      }
+      if (!isRovingItem) {
+        return;
+      }
+    }
+    const rootElement = editor.getRootElement();
+    if (rootElement === null) {
+      return;
+    }
+    event.preventDefault();
+    // Keep Escape inside the toolbar — don't let it bubble to any
+    // window-level Modal close handler.
+    event.stopPropagation();
+    // `editor.focus()` restores the prior selection so commands resume
+    // where the cursor was before the jump; the `rootElement.focus()`
+    // fallback covers test environments where `editor.focus()` does not
+    // also move DOM focus.
+    editor.focus();
+    rootElement.focus();
+  };
+  return lexical.mergeRegister(editor.registerCommand(lexical.KEY_DOWN_COMMAND, event => {
+    if (!event.altKey || event.key !== 'F10') {
+      return false;
+    }
+    const firstItem = toolbar.querySelector('[tabindex="0"]') ?? toolbar.querySelector(selector);
+    if (firstItem === null) {
+      return false;
+    }
+    event.preventDefault();
+    firstItem.focus();
+    return true;
+  }, lexical.COMMAND_PRIORITY_LOW), lexical.registerEventListener(toolbar, 'keydown', handler));
+}
+
+/**
+ * Public output of {@link AriaLiveRegionExtension}. The `politeness` and
+ * `owner` config values are exposed as runtime-tunable signals — setting
+ * `politeness` updates the mounted region's `aria-live`, setting `owner`
+ * re-mounts the region — alongside a stable `announce` sink that is valid for
+ * the editor's lifetime (callers never see the region element or its disposal).
+ */
+
+/**
+ * Platform-independent extension that owns a single `aria-live` region for
+ * the editor and exposes a stable {@link AriaLiveRegion} sink as its output.
+ * Other a11y extensions (`HistoryAnnounceExtension`,
+ * `EditorModeAnnounceExtension`) depend on it and announce through
+ * `output.announce`.
+ *
+ * The sink writes to a private `message` signal created in `init`. The
+ * `politeness` / `owner` config are exposed as signals (via `namedSignals`).
+ * `register` tracks the editor's root element reactively and runs three
+ * effects: one creates / disposes the region element as the root document (or
+ * `owner`) changes, one applies the current `politeness` to the mounted region,
+ * and one mirrors the current message into it. Buffering through signals
+ * decouples the stable `announce` (from `build`) from the region element —
+ * which comes and goes with the root — and creates the region in the editor's
+ * own document (e.g. an iframe-portaled editor) rather than the top-level
+ * `document`.
+ */
+const AriaLiveRegionExtension = /* @__PURE__ */lexical.defineExtension({
+  build(_editor, config, state) {
+    const message = state.getInitResult();
+    return {
+      ...extension.namedSignals(config),
+      announce(text) {
+        // Toggle a trailing zero-width space on repeats so re-announcing the
+        // same text still registers as a textContent change downstream.
+        message.value = text === message.peek() ? text + '\u200B' : text;
+      }
+    };
+  },
+  config: /* @__PURE__ */lexical.safeCast({
+    owner: null,
+    politeness: 'polite'
+  }),
+  dependencies: [extension.RootElementExtension],
+  // Private reactive message buffer shared by `build` (writer) and `register`
+  // (renderer); see the extension doc comment.
+  init: () => extension.signal(''),
+  name: '@lexical/a11y/AriaLiveRegion',
+  register(_editor, _config, state) {
+    const message = state.getInitResult();
+    const {
+      owner,
+      politeness
+    } = state.getOutput();
+    const rootElement = state.getDependency(extension.RootElementExtension).output;
+    const region = extension.signal(null);
+    return lexical.mergeRegister(
+    // Create / dispose the region as the root document (or `owner`) changes.
+    // Subscribe to the root only when no explicit `owner` is configured, so a
+    // fixed-owner region isn't torn down and rebuilt on unrelated root churn.
+    extension.effect(() => {
+      const ownerEl = owner.value;
+      const root = ownerEl ? null : rootElement.value;
+      const host = ownerEl ?? (root ? root.ownerDocument.body : null);
+      if (!host) {
+        return undefined;
+      }
+      const el = createLiveRegion(host);
+      region.value = el;
+      return () => {
+        el.remove();
+        region.value = null;
+      };
+    }),
+    // Apply the (runtime-tunable) politeness to whatever region is mounted.
+    // This tracks `region` so it re-applies the attribute to a re-created
+    // region (an attribute, not an announcement).
+    extension.effect(() => {
+      const el = region.value;
+      if (el) {
+        el.setAttribute('aria-live', politeness.value);
+      }
+    }),
+    // Mirror the current message into whatever region is mounted. Always read
+    // `message.value` (to stay subscribed) but read the region with peek() so
+    // this re-runs only when the message changes, not when the region is
+    // (re)created: replaying the buffered message into a freshly mounted
+    // region would make the screen reader re-announce it on every editor
+    // remount with no user action.
+    extension.effect(() => {
+      const text = message.value;
+      const el = region.peek();
+      if (el) {
+        el.textContent = text;
+      }
+    }));
+  }
+});
+/**
+ * Platform-independent extension that announces undo / redo through the
+ * `AriaLiveRegionExtension`'s shared sink.
+ */
+const HistoryAnnounceExtension = /* @__PURE__ */lexical.defineExtension({
+  build: (_editor, config) => extension.namedSignals(config),
+  config: /* @__PURE__ */lexical.safeCast({
+    disabled: false,
+    redone: 'Redone',
+    undone: 'Undone'
+  }),
+  dependencies: [AriaLiveRegionExtension],
+  name: '@lexical/a11y/HistoryAnnounce',
+  register(editor, _config, state) {
+    const {
+      disabled,
+      redone,
+      undone
+    } = state.getOutput();
+    const {
+      announce
+    } = state.getDependency(AriaLiveRegionExtension).output;
+    // Gate registration on `disabled` from an effect so a disabled announcer
+    // adds no command overhead at all. Peek the message signals at dispatch
+    // time so changing them doesn't re-register. Both return false to keep the
+    // history command chain intact.
+    return extension.effect(() => disabled.value ? undefined : lexical.mergeRegister(editor.registerCommand(lexical.UNDO_COMMAND, () => {
+      announce(undone.peek());
+      return false;
+    }, lexical.COMMAND_PRIORITY_LOW), editor.registerCommand(lexical.REDO_COMMAND, () => {
+      announce(redone.peek());
+      return false;
+    }, lexical.COMMAND_PRIORITY_LOW)));
+  }
+});
+/**
+ * Platform-independent extension that announces
+ * `editor.setEditable(true|false)` transitions through the
+ * `AriaLiveRegionExtension`'s shared sink.
+ */
+const EditorModeAnnounceExtension = /* @__PURE__ */lexical.defineExtension({
+  build: (_editor, config) => extension.namedSignals(config),
+  config: /* @__PURE__ */lexical.safeCast({
+    disabled: false,
+    editable: 'Editor is editable',
+    readOnly: 'Editor is read-only'
+  }),
+  dependencies: [AriaLiveRegionExtension],
+  name: '@lexical/a11y/EditorModeAnnounce',
+  register(editor, _config, state) {
+    const {
+      disabled,
+      editable,
+      readOnly
+    } = state.getOutput();
+    const {
+      announce
+    } = state.getDependency(AriaLiveRegionExtension).output;
+    // Gate registration on `disabled` from an effect so a disabled announcer
+    // adds no listener overhead. Peek the message signals at dispatch time so
+    // changing them doesn't re-register.
+    return extension.effect(() => disabled.value ? undefined : editor.registerEditableListener(isEditable => {
+      announce(isEditable ? editable.peek() : readOnly.peek());
+    }));
+  }
+});
+
+/**
+ * The public output of the focus-trap, roving-tabindex and focus-manager
+ * extensions: register a container (reference counted) and get back an
+ * idempotent disposer. Callers register through this method instead of a
+ * mutable map and never see the container bookkeeping. It is the core
+ * {@link RefCountedRegistry} keyed by `HTMLElement`.
+ *
+ * Each extension creates the registry in `build` (where the editor is
+ * available for the per-container activation) and disposes it on `register`
+ * teardown via {@link RefCountedRegistry.dispose}.
+ */
+
+/**
+ * Platform-independent extension that traps Tab / Shift+Tab focus inside one
+ * or more containers. Register a container through the extension output
+ * ({@link ContainerRegistry.register}); the React adapter is
+ * `useLexicalFocusTrapRef` from `@lexical/react`.
+ */
+const FocusTrapExtension = /* @__PURE__ */lexical.defineExtension({
+  build: () => lexical.createRefCountedRegistry(registerFocusTrap),
+  name: '@lexical/a11y/FocusTrap',
+  register: (_editor, _config, state) => () => state.getOutput().dispose()
+});
+
+/**
+ * Platform-independent extension that wires the WAI-ARIA roving-tabindex
+ * pattern on one or more containers. Register a container through the
+ * extension output ({@link ContainerRegistry.register}); the React adapter is
+ * `useLexicalRovingTabIndexRef` from `@lexical/react`.
+ */
+const RovingTabIndexExtension = /* @__PURE__ */lexical.defineExtension({
+  build: () => lexical.createRefCountedRegistry(registerRovingTabIndex),
+  name: '@lexical/a11y/RovingTabIndex',
+  register: (_editor, _config, state) => () => state.getOutput().dispose()
+});
+
+/**
+ * Platform-independent extension that wires the editor-to-toolbar focus jump
+ * (Alt+F10 / Escape return) on one or more toolbars. Register a toolbar
+ * through the extension output ({@link ContainerRegistry.register}); the React
+ * adapter is `useLexicalFocusManagerRef` from `@lexical/react`.
+ */
+const FocusManagerExtension = /* @__PURE__ */lexical.defineExtension({
+  build: editor => lexical.createRefCountedRegistry((toolbar, options) => registerFocusManager(editor, toolbar, options)),
+  name: '@lexical/a11y/FocusManager',
+  register: (_editor, _config, state) => () => state.getOutput().dispose()
+});
+
+exports.AriaLiveRegionExtension = AriaLiveRegionExtension;
+exports.EditorModeAnnounceExtension = EditorModeAnnounceExtension;
+exports.FocusManagerExtension = FocusManagerExtension;
+exports.FocusTrapExtension = FocusTrapExtension;
+exports.HistoryAnnounceExtension = HistoryAnnounceExtension;
+exports.RovingTabIndexExtension = RovingTabIndexExtension;