feat(super-editor): native LTR/RTL paragraph direction toolbar (#3226)

* feat(super-editor): native LTR/RTL paragraph direction toolbar

Add ProseMirror commands `setParagraphDirection` / `clearParagraphDirection`,
toolbar buttons next to the indent controls, and `Mod-Alt-Shift-L/R` keymaps.
Buttons highlight to reflect the current paragraph's direction via the
headless toolbar registry.

Closes #3219.

* chore(super-editor): drop LTR/RTL keymap, ship buttons only

Matches Google Docs behavior — no default keyboard shortcut for paragraph
direction. The 4-key Mod-Alt-Shift-L/R chord (added to avoid colliding
with the existing Mod-Shift-L/R alignment binding) was awkward enough
that any future shortcut should be a deliberate single-key toggle.

* fix(super-editor): direction-rtl was silently applying LTR via no-payload path

The `direction-ltr` / `direction-rtl` registry entries delegated to
`createDirectCommandExecute('setParagraphDirection')`. Headless callers
that invoke `controller.execute('direction-rtl')` without a payload
ended up calling `editor.commands.setParagraphDirection()` with no
arguments — which defaulted `direction` to `undefined`, evaluated
`direction === 'rtl'` as false, and wrote `rightToLeft: false`. The RTL
toolbar id silently performed an LTR write.

Fix in two layers:

- A dedicated `createParagraphDirectionExecute(direction)` helper that
  bakes the fixed `{ direction, alignmentPolicy: 'matchDirection' }`
  payload into the registry execute so callers don't need to know the
  direction is encoded in the command id.
- Guard the command itself so a missing direction is a no-op rather
  than a silent LTR write — defense in depth for any other generic
  command-by-name pathway.

* fix(super-editor): ltr direction deletes pPr.rightToLeft instead of writing false

Writing `rightToLeft: false` round-trips as `<w:bidi w:val="0"/>` on export
(direct formatting that overrides any inherited style direction), so clicking
LTR on a vanilla paragraph injected `<w:bidi w:val="0"/>` into the DOCX even
though nothing semantically changed. Now LTR deletes the property, matching
`clearParagraphDirection` and leaving vanilla paragraphs untouched.

Replaces a previous test that locked in the buggy behavior; adds a regression
test for the vanilla-paragraph no-op case.

* fix(super-editor): address PR #3226 review feedback

Three issues caught in review:

1. Clicking LTR on a paragraph that inherits `rightToLeft: true` from its
   style was a silent no-op. The previous fix only deleted the inline
   override; with no inline value to delete, `shallowEqual` saw no change
   and skipped dispatch. LTR now re-resolves the cascade with the would-be
   inline state and writes an explicit `rightToLeft: false` when the
   style would still resolve to RTL. Vanilla paragraphs (no style-driven
   RTL) keep the delete-only behavior so they round-trip clean.

2. `defaultItems.test.js` was checking that the legacy XL_ITEMS list
   stays in overflow at narrow widths, but did not extend the list to
   the new `directionLtr` / `directionRtl` items even though they were
   added to `itemsToHideXL`. The test silently underverified the new
   items; now exercises them too.

3. Active-state highlight was never applied to items in the overflow
   popup (pre-existing bug in `super-toolbar.js`, surfaced by this
   feature because RTL/LTR's highlight is the only signal the buttons
   give). The active-state loop now iterates `toolbarItems` AND
   `overflowItems`.

* fix(super-editor): direction-ltr/direction-rtl payload type to `never`

The headless toolbar payload types for `direction-ltr` and `direction-rtl`
declared a `{ direction, alignmentPolicy? }` shape, but
`createParagraphDirectionExecute` bakes both fields in (direction from
the closure, alignmentPolicy hardcoded to `'matchDirection'`) and
ignores any payload.

A TS consumer doing `controller.execute('direction-ltr', { direction: 'rtl' })`
got LTR regardless of payload. Set both to `never` so the type matches
the runtime: this command takes no payload.

* test(super-editor): pin direction-ltr/direction-rtl execute contract

Adds 4 unit tests proving the runtime contract that justifies the
`never` payload type:

1. controller.execute('direction-ltr') -> setParagraphDirection(
     { direction: 'ltr', alignmentPolicy: 'matchDirection' })
2. controller.execute('direction-rtl') -> setParagraphDirection(
     { direction: 'rtl', alignmentPolicy: 'matchDirection' })
3. payload is ignored if passed (direction comes from the command id)
4. execute returns false when the editor command is unavailable

These pin the property that makes ToolbarPayloadMap['direction-*'] = never
a faithful declaration of the runtime, not a workaround.

* test(super-editor): comprehensive coverage for direction buttons

Adds regression coverage across the toolbar click path so the next time
someone touches `useToolbarItem({argument})` forwarding, the direction
buttons' state, or the `setParagraphDirection` payload shape, tests fail
loudly instead of silently breaking the buttons.

Unit tests (13 new):
- defaultItems.test.js: pin directionLtr/directionRtl item config
  (command, argument, aria-label) so config drift fails fast.
- ButtonGroup.test.js: pin item.argument.value forwarding through the
  click handler. Plain button click emits the static argument; explicit
  caller arg wins; disabled item skips emission. Catches the opus review
  concern about the new fallback affecting all buttons.
- toolbar-registry.test.ts: state-deriver tests for direction-ltr /
  direction-rtl across all three paragraphProperties.rightToLeft states
  (true / false / undefined). Pins active/value derivation.

Playwright behavior tests (5 new) in tests/behavior/tests/toolbar/
paragraph-direction.spec.ts: click the actual button users see, read
the ProseMirror doc, assert attrs change. Covers:
- RTL click sets paragraphProperties.rightToLeft = true
- LTR click on vanilla paragraph deletes the rightToLeft key
- RTL → LTR is one undo step (atomic transaction)
- Multi-paragraph selection applies to every paragraph
- Direction buttons reachable in overflow at narrow viewports

All 12751 super-editor unit tests pass.

* test(behavior): make paragraph-direction spec use correct fixture API

Two real bugs in the spec, not workarounds:

- Pin viewport to 1600x1200 in test.use. The Playwright config spreads
  `devices['Desktop Chrome']` (viewport 1280x720) which silently overrode
  the global 1600 default, putting the direction buttons in overflow.
  Below the XL cutoff (~1494px container width), the spec couldn't click
  the buttons directly. Wider viewport keeps them in the main toolbar.

- Fix multi-paragraph selection: setTextSelection takes positional
  (from, to) args, not an object; findTextPos returns a single number
  (the start position), not {from,to}. Earlier draft passed an object
  to setTextSelection so the selection collapsed to undefined/object
  and only the cursor's paragraph got RTL.

The narrow-viewport test deliberately resizes below XL and opens the
overflow popup explicitly, so the direct-click helper stays clean.

All 15 tests pass across chromium/firefox/webkit.

* test(behavior): expand paragraph-direction spec - alignment + active state

Adds two end-to-end coverage areas that the unit tests can't reach, and
fixes the undo-step test name to match what it actually verifies.

- alignmentPolicy plumbing: paragraph has explicit `justification: 'left'`,
  user clicks Right-to-left button, assert paragraph ends up with
  `rightToLeft: true` AND `justification: 'right'`. Proves the UI ->
  command path forwards `alignmentPolicy: 'matchDirection'`, not just the
  unit-level command logic.

- overflow active-state regression for 151cff8: at narrow viewport,
  click RTL via overflow popup, close, reopen, assert the RTL overflow
  button has the .active class (and LTR doesn't). Pre-fix this would
  silently miss because the active-state loop only iterated toolbarItems,
  not overflowItems.

- Rename "Right-to-left then Left-to-right is one undo step" to
  "Right-to-left click is one undo step" - the test only verified the
  RTL single-click case. A separate "LTR after RTL is its own undo step"
  was attempted but PM history coalesces rapid clicks into one step,
  so that's testing PM behavior, not the PR's contract.

All 21 tests pass across chromium/firefox/webkit.

* refactor(super-editor): remove direction buttons from default toolbar

Per review: directionLtr / directionRtl shouldn't ship in the default
toolbar config - they crowd the toolbar for every consumer (including
the majority who never touch RTL), and the XL_OVERFLOW_SAFETY_BUFFER had
to bump from 20 -> 84 specifically to accommodate them.

This commit:
- Removes the directionLtr / directionRtl `useToolbarItem` blocks and
  drops them from `toolbarItems` and `itemsToHideXL`.
- Reverts XL_OVERFLOW_SAFETY_BUFFER to 20 (was 84 with a 32px-each-for-
  direction comment).
- Updates defaultItems.test.js: XL_ITEMS no longer includes direction;
  the 3 direction-config tests are replaced with 2 "not in default
  toolbar" guard tests so a future re-add will fail loudly.
- Deletes tests/behavior/tests/toolbar/paragraph-direction.spec.ts
  (assumed buttons were in the default toolbar).

What stays:
- `setParagraphDirection` command + its unit tests
- Headless toolbar `direction-ltr` / `direction-rtl` ids + tests
  (typed payload still `never`; execute/state tests still pin contract)
- Icons (`paragraph-ltr-solid.svg`, `paragraph-rtl-solid.svg`)
- ButtonGroup argument forwarding tests (generic, not direction-specific)

Customer-side: wire the buttons into your own toolbar via the headless
toolbar API, or call `editor.commands.setParagraphDirection({ direction })`
directly.

* test(super-editor): reword ButtonGroup forwarding comment

Direction buttons are no longer default toolbar items (see 32153f8),
so the test comment shouldn't reference them as the example consumer of
this forwarding behavior. Rewords to "custom buttons" since the test
itself uses a direction-shaped payload only as an illustrative example.

---------

Co-authored-by: Caio Pizzol <97641911+caio-pizzol@users.noreply.github.com>
Co-authored-by: Caio Pizzol <caio@superdoc.dev>

Author: shri-scale

packages/super-editor/src/editors/v1/components/toolbar/ButtonGroup.test.js

@@ -56,3 +56,101 @@ describe('ButtonGroup dropdownOptions selected class', () => {
     expect(options[1].props.class).toBe('selected');
   });
 });
+
+// PR #3226: ButtonGroup forwards a button item's static `argument` (set via
+// useToolbarItem({argument})) on click when no caller arg is passed. This is
+// how custom buttons carry fixed args like {direction, alignmentPolicy} into
+// emit('command'). If this breaks, such buttons become silent no-ops.
+describe('ButtonGroup button argument forwarding', () => {
+  // `type` and `command` are plain (not refs) in useToolbarItem; the rest are refs.
+  const createButtonItem = (argument) => ({
+    type: 'button',
+    command: 'setParagraphDirection',
+    id: ref('btn-test'),
+    name: ref('directionLtr'),
+    argument: argument === undefined ? undefined : ref(argument),
+    disabled: ref(false),
+    isNarrow: ref(false),
+    isWide: ref(false),
+    tooltip: ref('Test'),
+    icon: ref(null),
+    active: ref(false),
+    expand: ref(false),
+    attributes: ref({ ariaLabel: 'Test button' }),
+  });
+
+  // shallowMount stubs all children including SdTooltip; SdTooltip is what
+  // wraps the button branch via <template #trigger>. Provide a custom stub
+  // that renders its trigger slot so the ToolbarButton stub becomes findable.
+  const mountButtonItem = (item) =>
+    shallowMount(ButtonGroup, {
+      props: { toolbarItems: [item], overflowItems: [] },
+      global: {
+        stubs: {
+          SdTooltip: {
+            name: 'SdTooltip',
+            template: '<div><slot name="trigger" /></div>',
+          },
+        },
+      },
+    });
+
+  const findToolbarButton = (wrapper) => wrapper.findComponent({ name: 'ToolbarButton' });
+
+  it('plain button click forwards item.argument.value into command emission', () => {
+    const argument = { direction: 'ltr', alignmentPolicy: 'matchDirection' };
+    const wrapper = mountButtonItem(createButtonItem(argument));
+    const button = findToolbarButton(wrapper);
+
+    button.vm.$emit('buttonClick');
+
+    const events = wrapper.emitted('command');
+    expect(events).toHaveLength(1);
+    expect(events[0][0].argument).toEqual(argument);
+  });
+
+  it('emits null argument when item has no static argument', () => {
+    const wrapper = mountButtonItem(createButtonItem(undefined));
+    const button = findToolbarButton(wrapper);
+
+    button.vm.$emit('buttonClick');
+
+    const events = wrapper.emitted('command');
+    expect(events).toHaveLength(1);
+    expect(events[0][0].argument).toBeNull();
+  });
+
+  it('directionLtr-shaped item forwards {direction:ltr, alignmentPolicy:matchDirection}', () => {
+    const argument = { direction: 'ltr', alignmentPolicy: 'matchDirection' };
+    const wrapper = mountButtonItem(createButtonItem(argument));
+    const button = findToolbarButton(wrapper);
+
+    button.vm.$emit('buttonClick');
+
+    const events = wrapper.emitted('command');
+    expect(events[0][0].argument.direction).toBe('ltr');
+    expect(events[0][0].argument.alignmentPolicy).toBe('matchDirection');
+  });
+
+  it('directionRtl-shaped item forwards {direction:rtl, alignmentPolicy:matchDirection}', () => {
+    const argument = { direction: 'rtl', alignmentPolicy: 'matchDirection' };
+    const wrapper = mountButtonItem(createButtonItem(argument));
+    const button = findToolbarButton(wrapper);
+
+    button.vm.$emit('buttonClick');
+
+    const events = wrapper.emitted('command');
+    expect(events[0][0].argument.direction).toBe('rtl');
+    expect(events[0][0].argument.alignmentPolicy).toBe('matchDirection');
+  });
+
+  it('skips command emission when item is disabled', () => {
+    const disabledItem = { ...createButtonItem({ direction: 'ltr' }), disabled: ref(true) };
+    const wrapper = mountButtonItem(disabledItem);
+    const button = findToolbarButton(wrapper);
+
+    button.vm.$emit('buttonClick');
+
+    expect(wrapper.emitted('command')).toBeUndefined();
+  });
+});

packages/super-editor/src/editors/v1/components/toolbar/ButtonGroup.vue

@@ -114,7 +114,11 @@ const handleToolbarButtonClick = (item, argument = null) => {
   }
 
   emit('item-clicked');
-  emit('command', { item, argument });
+  // Forward the item's static `argument` (set via `useToolbarItem({ argument })`)
+  // when no caller-provided argument exists. Lets buttons carry fixed args like
+  // `{ direction: 'rtl' }` without needing a dropdown.
+  const resolved = argument ?? item.argument?.value ?? null;
+  emit('command', { item, argument: resolved });
 };
 
 const handleToolbarButtonTextSubmit = (item, argument) => {

packages/super-editor/src/editors/v1/components/toolbar/constants.js

@@ -88,6 +88,8 @@ export const HEADLESS_ITEM_MAP = {
   linkedStyles: 'linked-style',
   indentleft: 'indent-decrease',
   indentright: 'indent-increase',
+  directionLtr: 'direction-ltr',
+  directionRtl: 'direction-rtl',
   clearFormatting: 'clear-formatting',
   copyFormat: 'copy-format',
 };

packages/super-editor/src/editors/v1/components/toolbar/defaultItems.test.js

@@ -95,3 +95,25 @@ describe('makeDefaultItems LG compact styles', () => {
     expect(linkedStyles.attributes.value.className).not.toContain('toolbar-item--linked-styles-compact');
   });
 });
+
+// PR #3226: direction buttons (directionLtr / directionRtl) are intentionally
+// NOT in the default toolbar. The command (`setParagraphDirection`) and the
+// headless toolbar ids (`direction-ltr` / `direction-rtl`) stay available;
+// customers wire them into their own UI via the headless toolbar API or by
+// calling the command directly. Pin "not in default" here so a future
+// re-add in makeDefaultItems fails this test instead of silently shipping.
+describe('makeDefaultItems direction buttons not in default toolbar', () => {
+  function getItem(defaultItems, overflowItems, name) {
+    return [...defaultItems, ...overflowItems].find((item) => item.name.value === name);
+  }
+
+  it('directionLtr is not in the default toolbar items', () => {
+    const { defaultItems, overflowItems } = buildItems(2000);
+    expect(getItem(defaultItems, overflowItems, 'directionLtr')).toBeUndefined();
+  });
+
+  it('directionRtl is not in the default toolbar items', () => {
+    const { defaultItems, overflowItems } = buildItems(2000);
+    expect(getItem(defaultItems, overflowItems, 'directionRtl')).toBeUndefined();
+  });
+});

packages/super-editor/src/editors/v1/components/toolbar/super-toolbar.js

@@ -712,7 +712,11 @@ export class SuperToolbar extends EventEmitter {
       return;
     }
 
-    this.toolbarItems.forEach((item) => {
+    // Overflow items still appear in the overflow popup and need their
+    // active-state highlight (e.g., bold pressed, direction matched) to
+    // reflect the current selection. Iterating only `toolbarItems` left
+    // them frozen in their last-rendered state.
+    [...this.toolbarItems, ...this.overflowItems].forEach((item) => {
       item.resetDisabled();
       this.#applyHeadlessState(item);
     });

packages/super-editor/src/editors/v1/components/toolbar/toolbarIcons.js

@@ -60,6 +60,8 @@ import copyIconSvg from '@superdoc/common/icons/copy-solid.svg?raw';
 import pasteIconSvg from '@superdoc/common/icons/paste-solid.svg?raw';
 import strikethroughSvg from '@superdoc/common/icons/strikethrough.svg?raw';
 import paragraphIconSvg from '@superdoc/common/icons/paragraph-solid.svg?raw';
+import paragraphLtrIconSvg from '@superdoc/common/icons/paragraph-ltr-solid.svg?raw';
+import paragraphRtlIconSvg from '@superdoc/common/icons/paragraph-rtl-solid.svg?raw';
 
 export const toolbarIcons = {
   undo: rotateLeftIconSvg,
@@ -89,6 +91,8 @@ export const toolbarIcons = {
   numberedListLowerAlphaParen: listLowerAlphaParenIconSvg,
   indentLeft: outdentIconSvg,
   indentRight: indentIconSvg,
+  directionLtr: paragraphLtrIconSvg,
+  directionRtl: paragraphRtlIconSvg,
   pageBreak: fileHalfDashedIconSvg,
   copyFormat: paintRollerIconSvg,
   clearFormatting: textSlashIconSvg,

packages/super-editor/src/editors/v1/components/toolbar/toolbarTexts.js

@@ -29,6 +29,8 @@ export const toolbarTexts = {
   numberedList: 'Numbered list',
   indentLeft: 'Left indent',
   indentRight: 'Right indent',
+  directionLtr: 'Left-to-right',
+  directionRtl: 'Right-to-left',
   zoom: 'Zoom',
   undo: 'Undo',
   redo: 'Redo',

packages/super-editor/src/editors/v1/core/commands/index.js

@@ -44,6 +44,7 @@ export * from './insertSectionBreakAtSelection.js';
 // Paragraph
 export * from './textIndent.js';
 export * from './lineHeight.js';
+export * from './paragraphDirection.js';
 
 // Run
 export * from './backspaceEmptyRunParagraph.js';

packages/super-editor/src/editors/v1/core/commands/paragraphDirection.js

@@ -0,0 +1,97 @@
+import { resolveHypotheticalParagraphProperties } from '@extensions/paragraph/resolvedPropertiesCache.js';
+
+/**
+ * Set paragraph direction (LTR/RTL) on every paragraph in the current selection.
+ * @category Command
+ * @param {Object} input
+ * @param {"ltr"|"rtl"} input.direction
+ * @param {"matchDirection"} [input.alignmentPolicy] - When set to "matchDirection",
+ *   mirror an *explicit* `justification` of "left" ↔ "right" so the alignment
+ *   follows the new direction. Leaves "center", "both", and unset values alone.
+ * @returns {Function} ProseMirror command function
+ * @example
+ * editor.commands.setParagraphDirection({ direction: 'rtl', alignmentPolicy: 'matchDirection' })
+ */
+export const setParagraphDirection = ({ direction, alignmentPolicy } = {}) => {
+  // Guard against headless callers that invoke this through a generic
+  // "execute by command name" pathway without a payload — a missing
+  // direction must be a no-op, not a silent LTR write.
+  if (direction !== 'ltr' && direction !== 'rtl') return () => false;
+  return walkParagraphs((pPr, { editor, $pos }) => {
+    const next = { ...pPr };
+    if (direction === 'rtl') {
+      next.rightToLeft = true;
+    } else {
+      // AIDEV-NOTE: LTR first tries to delete the inline override (so a
+      // vanilla paragraph round-trips without `<w:bidi w:val="0"/>`). But
+      // if the paragraph inherits `rightToLeft: true` from its style (or
+      // any other level of the OOXML cascade), deleting alone leaves the
+      // resolved direction as RTL — clicking LTR would be a silent no-op.
+      // Re-resolve the cascade against the would-be inline state; if RTL
+      // still wins, force an explicit `false` to override the style.
+      delete next.rightToLeft;
+      const resolved = resolveHypotheticalParagraphProperties(editor, $pos, next);
+      if (resolved?.rightToLeft === true) {
+        next.rightToLeft = false;
+      }
+    }
+    if (alignmentPolicy === 'matchDirection') {
+      const j = pPr.justification;
+      if (j === 'left' && direction === 'rtl') next.justification = 'right';
+      else if (j === 'right' && direction === 'ltr') next.justification = 'left';
+    }
+    return next;
+  });
+};
+
+/**
+ * Clear an explicit paragraph direction override on every paragraph in the
+ * current selection. The paragraph reverts to its auto-resolved direction.
+ * @category Command
+ * @returns {Function} ProseMirror command function
+ * @example
+ * editor.commands.clearParagraphDirection()
+ */
+export const clearParagraphDirection = () =>
+  walkParagraphs((pPr) => {
+    const next = { ...pPr };
+    delete next.rightToLeft;
+    return next;
+  });
+
+function walkParagraphs(transform) {
+  return ({ editor, state, dispatch }) => {
+    const { from, to } = state.selection;
+    const tr = state.tr;
+    let touched = false;
+
+    state.doc.nodesBetween(from, to, (node, pos) => {
+      if (node.type.name !== 'paragraph') return true;
+
+      const existing = node.attrs.paragraphProperties || {};
+      const updated = transform(existing, { editor, node, $pos: state.doc.resolve(pos) });
+
+      if (shallowEqual(existing, updated)) return false;
+
+      tr.setNodeMarkup(pos, undefined, {
+        ...node.attrs,
+        paragraphProperties: updated,
+      });
+      touched = true;
+      return false;
+    });
+
+    if (touched && dispatch) dispatch(tr);
+    return touched;
+  };
+}
+
+function shallowEqual(a, b) {
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  for (const k of ka) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}