[lexical-a11y][lexical-react][lexical-playground][lexical-website] Feature: @lexical/a11y framework-agnostic accessibility helpers + WCAG AA reference adoption

[mayrang]

Description

New @lexical/a11y package shipping framework-agnostic accessibility as @lexical/extension extensions, plus a small set of React adapter hooks in @lexical/react, a shared ref-counted-registry primitive added to core lexical, and reference adoption across the playground that takes the editor to WCAG 2.1 AA on the keyboard and with a screen reader. Builds on the keyboard accessibility RFC #6006 + KaiPrince's PR #7804 (focus indicator + dropdown focus return — already merged).

The accessibility behavior ships as six platform-independent extensions. They are framework-agnostic because @lexical/extension is: any host that builds an editor from extensions gets them, React hosts get thin adapter hooks, and non-React hosts (Svelte / Vue / Solid / vanilla) drive the same extension outputs from their own lifecycle. No framework type leaks into @lexical/a11y.

Closes #6006.

What ships

@lexical/a11y (new package) — framework-agnostic, depends only on lexical + @lexical/extension + @lexical/utils. Six extensions:

• AriaLiveRegionExtension — owns a single visually hidden aria-live region for the editor and exposes a stable announce(message) sink as its output, plus runtime-tunable politeness / owner signals. The region is bound to the editor's root element (via RootElementExtension), so it is created in the editor's own document — e.g. an iframe-portaled editor — not the top-level one, and follows the root across remounts. announce re-fires on a duplicate message via a trailing zero-width space. WAI-ARIA status message pattern (WCAG 4.1.3). A no-op until a region is mounted (a root element exists, or an owner is configured).
• HistoryAnnounceExtension — depends on AriaLiveRegionExtension; announces undo / redo ('Undone' / 'Redone', configurable) at COMMAND_PRIORITY_LOW, returning false to keep the command chain intact. A disabled signal toggles it at runtime.
• EditorModeAnnounceExtension — same shape, for editor.setEditable(true|false) transitions ('Editor is editable' / 'Editor is read-only'). Transition-based (silent on mount); also runtime-disabled.
• FocusTrapExtension — output is a reference-counted registry: register(container, {initialFocus, allowOutside}) => dispose. Tab / Shift+Tab fully managed inside the container; a document-level focusin listener pulls escaping focus back; restores the previously-focused element on dispose. initialFocus: 'firstFocusable' | 'container'.
• RovingTabIndexExtension — registry register(container, {orientation, itemSelector}) => dispose. WAI-ARIA roving-tabindex: arrow keys + Home / End rove among items, Tab leaves the group as a unit. Items are queried lazily per interaction, so additions / removals are picked up automatically.
• FocusManagerExtension — registry register(toolbar, {toolbarItemSelector}) => dispose. APG editor menubar pattern: Alt+F10 inside the editor focuses the toolbar's first roving item, Escape inside the toolbar returns focus to the editor; the editor's selection is preserved across the jump.

The three focus extensions share one core primitive: their output is a ContainerRegistry (reference-counted by container element), so the same container can be driven by more than one caller (or survive a re-entrant registration) without double-wiring, and the activation is torn down only when the last registration is released.

@lexical/react (adapters) — four thin hooks; each requires the matching extension in the editor's tree. New in this PR:

• useLexicalAriaLiveRegion(): (message: string) => void — a stable announce.
• useLexicalFocusTrapRef(isActive, initialFocus?, allowOutside?): RefCallback<HTMLElement> — attach with ref={trapRef}; registers the node while isActive, releases on detach / deactivate. allowOutside (held in a ref, so an inline lambda doesn't re-create the trap) lets portaled panels keep focus.
• useLexicalRovingTabIndexRef(options?): RefCallback<HTMLElement>.
• useLexicalFocusManagerRef(options?): RefCallback<HTMLElement>.

The Ref hooks return a RefCallback that registers / releases the attached node through the extension's reference-counted registry — changing the options re-registers with the new config without leaking the old one.

lexical (core) — adds createRefCountedRegistry<Key, Options>(activate) / RefCountedRegistry (a small first-activate / last-release reference-counting map keyed by object identity). addRootElementEvents now uses it to share a single document selectionchange listener across every editor / root element registered against a document (replacing the hand-rolled count), which also makes the per-document keying correct for shadow-DOM / iframe hosts. Behavior-preserving.

@lexical/extension — adds RootElementExtension, exposing editor.getRootElement() as a reactive Signal<HTMLElement | null> (consumed by AriaLiveRegionExtension, and by the playground autocomplete that previously hand-rolled the same watchedSignal).

lexical-playground (reference adoption) — wires the adapters across the main toolbar, floating text-format toolbar, modal, and equation node (see "Eleven areas").

lexical-website (docs) — concepts/keyboard-accessibility.md documents the contract per surface; the new extensions and RootElementExtension are listed on the Included Extensions page.

Using @lexical/a11y

With @lexical/extension directly (any host):

import {
  AriaLiveRegionExtension,
  EditorModeAnnounceExtension,
  FocusTrapExtension,
  HistoryAnnounceExtension,
  RovingTabIndexExtension,
} from '@lexical/a11y';
import {getExtensionDependencyFromEditor} from '@lexical/extension';
import {configExtension, defineExtension} from 'lexical';

const AppExtension = defineExtension({
  dependencies: [
    HistoryAnnounceExtension,
    EditorModeAnnounceExtension,
    RovingTabIndexExtension,
    // localized strings via configExtension if needed:
    // configExtension(HistoryAnnounceExtension, {undone: '…', redone: '…'}),
  ],
  name: '[root]',
});

// When a toolbar mounts, register it; call the returned disposer to release:
const registry = getExtensionDependencyFromEditor(editor, RovingTabIndexExtension).output;
const dispose = registry.register(toolbarEl, {orientation: 'horizontal'});
// later: dispose();

From React (LexicalComposer / extension host):

function Toolbar() {
  const rovingRef = useLexicalRovingTabIndexRef({orientation: 'horizontal'});
  return <div ref={rovingRef} role="toolbar" aria-label="Editor toolbar">…</div>;
}

Non-React hosts (Svelte / Vue / Solid / vanilla) read the same extension output and call registry.register(node, options) / the returned disposer from their own mount / cleanup hooks — no framework-specific adapter package ships in this PR.

Eleven areas covered

Grouped by WAI-ARIA APG pattern.

Operate (keyboard)

1. Main toolbar role="toolbar" + aria-label — screen readers group the toolbar buttons.
2. Main toolbar roving tabindex — ArrowRight / ArrowLeft / Home / End move between buttons; Tab leaves the toolbar in one step. useLexicalRovingTabIndexRef.
3. FloatingTextFormatToolbar roving tabindex + role="toolbar" — mirrors the main toolbar.
4. Alt+F10 editor ↔ toolbar jump with Escape return + selection restore — useLexicalFocusManagerRef.
5. Modal focus trap — useLexicalFocusTrapRef. Tab / Shift+Tab fully managed; document-level focusin recovery. Modal lands initial focus on the dialog container (tabIndex={-1}) so screen readers announce the dialog body via aria-labelledby before any control.

Perceive (visual + announce)

6. EquationNode role="math" + dynamic aria-label — cached, re-applied on updateDOM.
7. Editor mode announce — EditorModeAnnounceExtension announces editable ↔ read-only transitions via aria-live.
8. Undo / Redo announce — HistoryAnnounceExtension announces the action via aria-live.
9. Forced-colors (@media (forced-colors: active)) — toolbar buttons, editor border, and modal :focus outline pick up system Highlight / CanvasText; toolbar icons and the logo switch to mask-image with background-color: CanvasText so they render as system foreground. Color-meaning icons (font-color, bg-color) keep background-image so the picker color is preserved.
10. prefers-reduced-motion: reduce — collapses transitions / animations to 0.01ms.

Understand (page contract)

11. Keyboard accessibility concepts page — concepts/keyboard-accessibility.md documents the contract per surface (toolbar / modal / editor) in one place.

Considered but dropped

• TabIndentationExtension releaseOnEscape opt-in — verified Lexical's default editor.blur() on Escape already moves Tab focus past the editor on Chrome and Safari (macOS), so the opt-in was redundant for WCAG 2.1.2.
• LexicalNode.getRole / getAriaLabel core API — only one consumer (EquationNode); the existing direct dom.setAttribute pattern already covers it.
• EquationNode tabindex="0" — Tab inside contenteditable is consumed by TabIndentationExtension, and the Tab outline overlapped the NodeSelection outline. Equation stays announced via role="math" + aria-label; reach it by caret traversal.

Backwards compatibility

• Everything in @lexical/a11y and the four @lexical/react adapters is new and unreleased — no existing signatures change.
• The only core change is internal: addRootElementEvents now shares its selectionchange listener through the new createRefCountedRegistry. The observable behavior (one shared document listener, attached on first root, removed after the last) is unchanged.
• The focus trap installs a document-level focusin listener: focus landing outside an active trap is pulled back inside (use allowOutside, or portal panels inside the container). Only one trap should be active at a time.
• Modal initial focus is the dialog container, not the first focusable — no outline ring on open (the inner :focus outline stays); screen reader users hear the dialog title first.

Test plan

Before

The playground had no keyboard-accessibility wiring for the toolbar / modal / equation surfaces; no @lexical/a11y package.

After

Automated

• pnpm tsc / pnpm flow — clean.
• pnpm vitest run --project unit — passes. New unit tests for the six @lexical/a11y extensions (incl. shadow-DOM variants), the four React adapter hooks, the core createRefCountedRegistry (ref-counting / idempotent dispose / re-registration), and the addRootElementEvents selectionchange ref-count.
• prettier + eslint + the build-export audit — clean.

Chrome / Safari (macOS) — keyboard + DOM

• Toolbar role="toolbar" + aria-label; roving tabindex (Arrow / Home / End, single-step Tab out, tabIndex 0 on active / -1 on rest) on both the main and floating toolbars.
• Alt+F10 editor → toolbar; Escape returns focus to the editor with the pre-jump selection restored; default Escape blurs the editor and Tab leaves it.
• Modal focus trap: initial focus on the dialog container; Tab / Shift+Tab cycle within; never escapes; close returns focus to the opener. Safari no longer flashes the URL bar between trap boundaries.
• EquationNode DOM has role="math" + aria-label="Equation: …", updated on edit.

Screen readers

• VoiceOver (macOS) and Narrator (Windows 11): toolbar grouping, dialog title announced before controls, equation aria-label, editable ↔ read-only announcements, Undo / Redo announcements.

Visual preferences

• Windows High Contrast / forced-colors: buttons, border, modal :focus use system colors; toolbar icons + logo render as system foreground via mask-image; color-picker icons keep their SVG colors.
• prefers-reduced-motion: reduce (macOS + DevTools emulation): transitions collapse to ~0.01ms.

Mobile — physical keyboard

• iOS Safari / Android Chrome + bluetooth keyboard: Escape blurs the editor; Tab moves to the next focusable.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview, Comment	Jul 1, 2026 12:03am
lexical-playground	Ready	Preview, Comment	Jul 1, 2026 12:03am

[etrepum]

@mayrang I think I'm done working with claude to add a little more polish to this, let me know what you think of the current API