Slate v2 table transform boundary ralplan

Date: 2026-05-18 Status: complete Owner: Slate Ralplan planning only Execution owner: ralph in .tmp/slate-v2 Completion id: 019e1fc0-dba0-7de1-9236-b484a144cda6 Current pass: closure-final-gates Score: 0.94, ready for Ralph execution

Verdict

Harsh answer: the table example is currently wrong.

The public hard cut away from Editable onCommand was correct, but the follow-up example rewrite overcorrected into raw onKeyDown for behavior that is really old Slate transform behavior. Backspace, Delete, and Enter are not app hotkeys. They are model transforms:

• Backspace -> deleteBackward
• Delete -> deleteForward
• Enter -> insertBreak

So table cell boundary behavior should be implemented as extension transform middleware, not as event.key branching inside <Editable onKeyDown>.

Intent And Boundary

Current Live State

API Target

No new public API is needed.

The API law changes:

If the behavior corresponds to a Slate transform name, author it through
defineEditorExtension({ transforms: { ... } }).

If the behavior corresponds to a browser/UI shortcut with no Slate transform
equivalent, author it through Editable onKeyDown.

Table Before

<Editable
  onKeyDown={(event) => {
    if (event.key === "Backspace") {
      const start = editor.read((state) => state.points.start(cellPath));
      return PointApi.equals(selection.anchor, start);
    }

    if (event.key === "Delete") {
      const end = editor.read((state) => state.points.end(cellPath));
      return PointApi.equals(selection.anchor, end);
    }

    if (event.key === "Enter") {
      return true;
    }
  }}
/>

Table After

const table = () =>
  defineEditorExtension<CustomEditor>()({
    name: 'table',
    transforms: {
      deleteBackward({ editor, next, unit }) {
        // Read selection and active table-cell inline, then stop at the cell start.
        next({ unit })
      },
      deleteForward({ editor, next, unit }) {
        // Read selection and active table-cell inline, then stop at the cell end.
        next({ unit })
      },
      insertBreak({ editor, next }) {
        // Read selection and active table-cell inline, then stop Enter in the cell.
        next()
      },
    },
  })

const editor = useSlateEditor({
  extensions: [table()],
  initialValue,
})

<Editable renderElement={Element} renderLeaf={Leaf} />

Keep the example checks inline when they are only used once. Do not add a helper pile just to hide the real Slate calls from the example.

Do not add a generic public table() package API in this slice. The example can own its small table() extension.

Examples To Update

Docs To Update

Tests And Proof

Ralph should add or update tests around behavior, not just deleted code.

Required proof:

• packages/slate/test/extension-methods-contract.ts: already proves transform middleware coverage for deleteBackward, deleteForward, and insertBreak; extend only if table-specific behavior needs a reusable package test.
• packages/slate-react/test/surface-contract.tsx: update docs/example contract so the tables/markdown/richtext examples teach transform middleware for transform-equivalent model behavior.
• New focused example contract if useful: table extension prevents deleteBackward, deleteForward, and insertBreak from escaping the active cell when selection is at the corresponding boundary.
• bun --filter slate-react test:vitest -- surface-contract keyboard-input-strategy-contract editable-behavior
• bun --filter slate typecheck
• bun --filter slate-react typecheck
• bun typecheck:site
• bun check

Browser proof is not mandatory for this planning pass, but Ralph should add it if any runtime input routing changes beyond examples/docs/tests.

Decision Brief

Principles:

1. Raw Slate keeps transform names as the source of truth for model behavior.
2. React event props remain raw escape hatches and app/UI shortcut hooks.
3. Cutting onCommand must not push old Slate transform behavior into keyboard-only handlers.
4. Plate owns rich keymap/table/product APIs; raw Slate examples should teach low-level Slate primitives.

Top drivers:

1. Legacy Slate developers expect deleteBackward, deleteForward, and insertBreak override behavior to survive as the transform middleware path.
2. DOM beforeinput, browser handles, programmatic calls, and tests can invoke these transforms without a keyboard event.
3. Example code is public API pedagogy; bad examples become bad ecosystem law.

Viable options:

Consequences:

• Some examples get a small local extension even when the behavior is tiny.
• onKeyDown docs must be more precise: it is not the replacement for onCommand.
• Table remains an example, not a full table plugin.

Ecosystem Strategy Synthesis

Issue Accounting

ClawSweeper pass: applied, ledger/cache first. No broad live GitHub read was needed because the touched issue rows already exist in the generated live ledger, manual sync ledger, issue coverage matrix, fork dossier, and PR reference.

Generated live rows read:

• docs/slate-issues/gitcrawl-live-open-ledger.md:21 for #6034
• docs/slate-issues/gitcrawl-live-open-ledger.md:37 for #5961
• docs/slate-issues/gitcrawl-live-open-ledger.md:127 for #4658
• docs/slate-issues/gitcrawl-live-open-ledger.md:167 for #3408
• docs/slate-issues/gitcrawl-live-open-ledger.md:238 for #5355
• docs/slate-issues/gitcrawl-live-open-ledger.md:369 for #2558
• docs/slate-issues/gitcrawl-live-open-ledger.md:588 and :589 for #3586 and #3568
• docs/slate-issues/gitcrawl-live-open-ledger.md:387 for #4681

Manual sync rows read:

• docs/slate-issues/gitcrawl-v2-sync-ledger.md:23 for #6034
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:39 for #5961
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:129 for #4658
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:169 for #3408
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:240 for #5355
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:371 for #2558
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:389, :590, and :591 for #4681, #3586, and #3568

No new fixed or improved issue claim is accepted by this plan.

Fork dossier sync:

• Appended Table Transform Boundary Ralplan - 2026-05-18 to docs/slate-v2/ledgers/fork-issue-dossier.md.

Issue coverage matrix sync:

• docs/slate-v2/ledgers/issue-coverage-matrix.md unchanged. Existing rows cover every reviewed issue classification, and adding duplicate rows would make the ledger worse.

PR reference sync:

• Updated docs/slate-v2/references/pr-description.md summary, accepted native input boundary shape, and proof references. New exact fixed/improved claims: 0.

Applicable Implementation Review Matrix

High-Risk Pre-Mortem

Maintainer Objection Ledger

Pass-State Ledger

Scorecard

Total score: 0.94.

Status is complete for planning. The next owner is Ralph implementation in .tmp/slate-v2.

Ralph Implementation Phases

1. Rewrite tables.tsx to add table() extension and remove transform-equivalent onKeyDown branches.
2. Rewrite markdown-shortcuts.tsx so Enter/Backspace behavior lives in transforms.insertBreak / transforms.deleteBackward.
3. Rewrite richtext.tsx so Enter exit behavior lives in extension transforms.insertBreak; keep mark/block shortcut hotkeys in onKeyDown.
4. Update docs to state the transform-vs-event boundary.
5. Add/adjust behavior contracts and surface contracts.
6. Run /Users/zbeyens/git/slate-v2: focused tests, package typechecks, bun typecheck:site, and bun check.
7. Sync plate-2 issue/reference docs only if claims or accepted API narrative change.

Hard Cuts And Rejected Alternatives

• Do not reintroduce public Editable onCommand or EditableCommand*.
• Do not add editableKeyCommands, capabilities, keymap, or keyboardShortcuts to raw Slate for this problem.
• Do not turn the example-local table() helper into a public table package API.
• Do not move UI-only hotkeys into transform middleware just to chase symmetry.
• Do not add a new fixed issue claim for this plan.

Plan Deltas From Review

• Strengthened the verdict from "table example is wrong" to the API law: transform-equivalent behavior goes through transforms.*; UI shortcuts stay in onKeyDown.
• Added full issue accounting and fork dossier sync.
• Updated the PR reference to include the table transform boundary.
• Raised testing requirements from keydown behavior to transform-call behavior.
• Kept onKeyDown for mentions, image select-all, inlines navigation, iframe hotkeys, and code demo hotkeys.

Open Questions

None for the planning lane.

What would change the decision:

• If Slate later adds a first-class raw table package, the example-local table() helper should move into that package.
• If a future issue proves a transform middleware path cannot cover native beforeinput/programmatic calls, the middleware dispatch contract is the bug, not a reason to go back to onKeyDown.

Fast Driver Gates

• /Users/zbeyens/git/slate-v2: bun --filter slate-react test:vitest -- surface-contract keyboard-input-strategy-contract editable-behavior
• /Users/zbeyens/git/slate-v2: bun --filter slate typecheck
• /Users/zbeyens/git/slate-v2: bun --filter slate-react typecheck
• /Users/zbeyens/git/slate-v2: bun typecheck:site
• /Users/zbeyens/git/slate-v2: bun check
• /Users/zbeyens/git/plate-2: node tooling/scripts/completion-check.mjs after Slate Ralplan closure, not during pending passes.

Ralph Execution Result

Status: implemented in /Users/zbeyens/git/slate-v2.

Files changed:

• site/examples/ts/tables.tsx
• site/examples/ts/markdown-shortcuts.tsx
• site/examples/ts/richtext.tsx
• docs/libraries/slate-react/editable.md
• docs/concepts/08-plugins.md
• docs/walkthroughs/05-executing-commands.md
• docs/walkthroughs/04-applying-custom-formatting.md
• packages/slate-react/test/surface-contract.tsx
• packages/slate-react/test/editable-behavior.tsx
• docs/solutions/logic-errors/2026-05-09-heading-start-enter-must-normalize-split-block-type.md

Proof:

• Red gate: bun --filter slate-react test:vitest -- surface-contract failed on the old table keydown example.
• Green gate: bun --filter slate-react test:vitest -- surface-contract passed.
• Focused gate: bun --filter slate-react test:vitest -- surface-contract keyboard-input-strategy-contract editable-behavior passed.
• Type gates passed: bun --filter slate typecheck, bun --filter slate-react typecheck, bun typecheck:site.
• Lint/format gate passed: bun lint:fix.
• Full fast gate passed: bun check.

Diff-review verdict: no must-fix issue found. Remaining onKeyDown rows are UI hotkeys or tests/docs that intentionally describe UI hotkeys; no Backspace, Delete, or Enter table/markdown/richtext model behavior remains in raw keydown.

Compound learning: updated the existing heading-start Enter solution note so it points at transforms.insertBreak instead of the stale keydown owner.

Final User-Review Handoff

Accepted handoff:

• API law: transform-equivalent behavior moves to transforms.*.
• Public API: no new core/slate-react API.
• Table example: onKeyDown boundary branches -> local table() extension.
• Markdown/richtext examples: Enter/Backspace model behavior -> transforms.
• Keep list: UI-only hotkeys, mentions autocomplete, inlines navigation, images mod+a, iframe hotkeys, code demo hotkeys remain onKeyDown.
• Proof: focused transform behavior tests, surface docs tests, site typecheck, and bun check.

Before/after shape:

// Before: keyboard-only event branch
<Editable
  onKeyDown={(event) => {
    if (event.key === "Backspace") return isAtStartOfTableCell(editor);
    if (event.key === "Delete") return isAtEndOfTableCell(editor);
    if (event.key === "Enter") return isInTableCell(editor);
    return false;
  }}
/>

// After: Slate model transform middleware
const table = () =>
  defineEditorExtension<CustomEditor>()({
    name: "table",
    transforms: {
      deleteBackward({ editor, next, unit }) {
        if (isAtStartOfTableCell(editor)) return;
        next({ unit });
      },
      deleteForward({ editor, next, unit }) {
        if (isAtEndOfTableCell(editor)) return;
        next({ unit });
      },
      insertBreak({ editor, next }) {
        if (isInTableCell(editor)) return;
        next();
      },
    },
  });

Final Completion Gates

• Related issue discovery complete.
• Issue ledger and PR reference synced or explicitly unchanged.
• ClawSweeper related-issue pass complete through existing ledgers and fork dossier append.
• All review passes complete.
• Score >= 0.92, no dimension below 0.85.
• No public API surface left in maybe-language.
• No new fixed/improved issue claim added.
• Final handoff includes accepted decisions and before/after shape.
• Completion state may be marked done for the planning lane.