@barocss/math-editor 0.5.0 → 0.6.1

package/dist/dom.js

@@ -1,5 +1,8 @@
+import { followReadableMathLayout } from './dom/readable-layout.js';
+import { attachMathHelp, requestMathHelp } from './dom/help.js';
 import { mathRunSpacing } from './math-spacing.js';
 import { mathLayout } from './math-layout.js';
+import { wrapSelectionShortcut } from './selection-shortcuts.js';
 import { transformRoot } from './root-transform.js';
 import { structureEditingContext, changeContextFence } from './context-tools.js';
 import { focusContextAction } from './dom/context-keyboard.js';
@@ -16,16 +19,16 @@ import { mountMathToolbar } from './dom/toolbar.js';
 export { mountMathToolbar } from './dom/toolbar.js';
 import { createMathSession, } from './session.js';
 import { translate, mathLocaleDirection } from './i18n.js';
-import { documentRows, isLiteralText, textNodes, setText, moveCaret, unwrapPrevious, unwrapEmptySlot, gridDeletionTarget, removeGrid, isGrid, toLatex, } from './model.js';
+import { documentRows, isLiteralText, textNodes, setText, moveCaret, unwrapPrevious, unwrapNext, unwrapEmptySlot, gridDeletionTarget, removeGrid, isGrid, toLatex, } from './model.js';
 import { activeGrid, activeMatrix, resizeMatrix } from './matrix.js';
 import { MATH_MATRIX_CLIPBOARD_TYPE, parseMatrixFragment, matrixFragment, matrixFromTSV, matrixRangeBetween, resolveMatrixRange, extendMatrixRange, focusMatrixCell, } from './matrix-range.js';
-import { joinPreviousLine } from './lines.js';
-import { moveVertical } from './vertical-navigation.js';
+import { joinPreviousLine, joinNextLine } from './lines.js';
+import { createVerticalNavigation } from './vertical-navigation.js';
 import { renderedCaretGeometry } from './dom/caret-geometry.js';
 import { extendsMathSelection, nativeSelectionAnchor, createSelectionMenuState, textSelectionBounds, } from './dom/selection.js';
-import { acceptSuggestion, findStateSuggestions, mathStructures } from './suggestions.js';
+import { acceptSuggestion, findStateSuggestions, mathStructures, } from './suggestions.js';
 import { tokenizeMathText, tokenIndexAt } from './tokens.js';
-import { fragmentLatex, parseFragment, MATH_CLIPBOARD_TYPE, extendKeyboardRange, collapseKeyboardRange, resolveRange, copyRange, wrappingKinds, } from './range.js';
+import { fragmentLatex, parseFragment, MATH_CLIPBOARD_TYPE, extendKeyboardRange, isTokenNavigationKey, collapseKeyboardRange, resolveRange, copyRange, wrappingKinds, } from './range.js';
 /** Native DOM renderer. No React or framework runtime is imported by this module. */
 export function mountMathEditor(host, initial = {}) {
     const doc = host.ownerDocument;
@@ -75,6 +78,7 @@ export function mountMathEditor(host, initial = {}) {
             onClose: closeLatex,
         });
     };
+    const stopHelp = attachMathHelp(root, () => session.getSnapshot().locale);
     const t = (value) => translate(session.getSnapshot().locale, value);
     const currentInput = () => surface.querySelector('input');
     const cancelDrag = () => {
@@ -87,6 +91,7 @@ export function mountMathEditor(host, initial = {}) {
     const notify = (key) => {
         status.textContent = t(key);
     };
+    const verticalNavigation = createVerticalNavigation();
     const apply = (next) => {
         editing = true;
         selectedGrid = undefined;
@@ -102,12 +107,15 @@ export function mountMathEditor(host, initial = {}) {
     const candidates = () => {
         const snapshot = session.getSnapshot(), state = snapshot.state, active = textNodes(state.document).find((n) => n.id === state.caret.id);
         const result = findStateSuggestions(state, snapshot.locale);
-        if (!editing ||
+        if (options.suggestionMenu === false ||
+            !editing ||
             isLiteralText(state.document, state.caret.id) ||
             snapshot.range ||
             snapshot.matrixRange ||
             dismissed === `${active.id}:${active.text}:${state.caret.start}`)
             result.candidates = [];
+        else if (options.filterSuggestions)
+            result.candidates = [...options.filterSuggestions(result.candidates, result.query, state)];
         return result;
     };
     const choose = (index) => {
@@ -167,12 +175,18 @@ export function mountMathEditor(host, initial = {}) {
         const itemRect = option.getBoundingClientRect();
         const listRect = list.getBoundingClientRect();
         const scaleY = listRect.height / list.offsetHeight || 1;
-        if (itemRect.top < listRect.top)
-            list.scrollTop -= (listRect.top - itemRect.top) / scaleY;
-        else if (itemRect.bottom > listRect.bottom)
-            list.scrollTop += (itemRect.bottom - listRect.bottom) / scaleY;
+        list.scrollTop +=
+            (itemRect.top + itemRect.height / 2 - listRect.top) / scaleY -
+                list.clientTop -
+                list.clientHeight / 2;
     };
     const renderMenu = () => {
+        if (options.suggestionMenu === false) {
+            menu.hidden = true;
+            menu.replaceChildren();
+            currentInput()?.setAttribute('aria-expanded', 'false');
+            return;
+        }
         syncMathTheme(root, menu);
         const result = candidates(), input = currentInput();
         menu.replaceChildren();
@@ -201,8 +215,9 @@ export function mountMathEditor(host, initial = {}) {
             const list = element('div', 'me-suggestions');
             list.setAttribute('role', 'listbox');
             list.setAttribute('aria-label', t('selection.toolbar'));
-            for (const item of mathStructures.filter((item) => wrappingKinds.includes(item.kind))) {
-                const button = suggestionButton(item.glyph, t(item.label), t(item.detail));
+            for (const item of mathStructures.filter((item) => wrappingKinds.includes(item.kind) &&
+                (!options.selectionKinds || options.selectionKinds.includes(item.kind)))) {
+                const button = suggestionButton(item.glyph, t(item.kind === 'fraction' ? 'selection.asNumerator' : item.label), t(item.detail));
                 button.setAttribute('aria-selected', String(list.children.length === candidateIndex));
                 button.disabled = !canWrap;
                 button.setAttribute('aria-label', translate(snapshot.locale, 'selection.wrap', { kind: t(item.label) }));
@@ -212,6 +227,18 @@ export function mountMathEditor(host, initial = {}) {
                     perform({ type: 'structure', kind: item.kind });
                 };
                 list.append(button);
+                if (item.kind === 'fraction') {
+                    const denominator = suggestionButton('□/▧', t('selection.asDenominator'), t(item.detail));
+                    denominator.setAttribute('aria-selected', String(list.children.length === candidateIndex));
+                    denominator.setAttribute('aria-label', t('selection.asDenominator'));
+                    denominator.disabled = !canWrap;
+                    denominator.onclick = () => {
+                        if (!snapshot.range)
+                            session.selectRange(selectedRange);
+                        perform({ type: 'structure', kind: 'fraction', fractionSlot: 'denominator' });
+                    };
+                    list.append(denominator);
+                }
             }
             menu.append(list);
             const selected = surface.querySelectorAll('.me-dom-selected, .me-range-highlight');
@@ -475,7 +502,12 @@ export function mountMathEditor(host, initial = {}) {
                                 dismissed = '';
                                 apply(replaceToken());
                             });
-                            input.onkeydown = keydown;
+                            input.onkeydown = (event) => {
+                                // Native arrow movement can precede select/keyup, especially during key repeat.
+                                // Read the live caret before testing token and structure boundaries.
+                                syncCaret();
+                                keydown(event);
+                            };
                             run.append(input);
                         }
                         else {
@@ -663,6 +695,38 @@ export function mountMathEditor(host, initial = {}) {
         }
         return false;
     }
+    function tokenNavigation(event) {
+        if (composing || !isTokenNavigationKey(event, win.navigator.platform))
+            return false;
+        const snapshot = session.getSnapshot();
+        if (snapshot.matrixRange)
+            return false;
+        event.preventDefault();
+        const state = snapshot.state;
+        const selection = snapshot.range ??
+            (state.caret.start !== state.caret.end
+                ? {
+                    anchor: { id: state.caret.id, offset: state.caret.start },
+                    focus: { id: state.caret.id, offset: state.caret.end },
+                }
+                : undefined);
+        if (event.shiftKey) {
+            session.selectRange(extendKeyboardRange(state, selection, event.key, 'token'));
+            surface.focus();
+        }
+        else {
+            const point = collapseKeyboardRange(state.document, selection, event.key) ??
+                extendKeyboardRange(state, undefined, event.key, 'token').focus;
+            editing = true;
+            session.select({
+                id: point.id,
+                start: point.offset,
+                end: point.offset,
+                affinity: event.key === 'ArrowLeft' ? 'forward' : 'backward',
+            });
+        }
+        return true;
+    }
     function keyboardSelect(event) {
         if (composing ||
             event.isComposing ||
@@ -678,6 +742,18 @@ export function mountMathEditor(host, initial = {}) {
         surface.focus();
         return true;
     }
+    function directSelectionKey(event) {
+        if (composing || event.isComposing)
+            return false;
+        const snapshot = session.getSnapshot();
+        const next = wrapSelectionShortcut(snapshot.state, snapshot.range, event);
+        if (!next)
+            return false;
+        event.preventDefault();
+        if (next !== snapshot.state)
+            apply(next);
+        return true;
+    }
     function selectionMenuKey(event) {
         if (menu.hidden ||
             menu.dataset.kind !== 'selection' ||
@@ -713,6 +789,12 @@ export function mountMathEditor(host, initial = {}) {
         return true;
     }
     function keydown(event) {
+        if (!['ArrowUp', 'ArrowDown', 'Escape'].includes(event.key) ||
+            event.shiftKey ||
+            event.altKey ||
+            event.ctrlKey ||
+            event.metaKey)
+            verticalNavigation.reset();
         event.stopPropagation();
         if (event.isComposing || composing)
             return;
@@ -739,7 +821,9 @@ export function mountMathEditor(host, initial = {}) {
             return;
         }
         if (matrixSelectionKey(event) ||
+            tokenNavigation(event) ||
             keyboardSelect(event) ||
+            directSelectionKey(event) ||
             selectionMenuKey(event) ||
             keyboardCollapse(event))
             return;
@@ -789,6 +873,17 @@ export function mountMathEditor(host, initial = {}) {
             }
             return;
         }
+        const acceptsSuggestion = event.key === 'Enter' &&
+            !event.shiftKey &&
+            result.candidates.length > 0 &&
+            ((!result.candidates[0].wrapOperand &&
+                !result.candidates[0].transformRootId &&
+                !result.candidates[0].transformFenceId) ||
+                operandMenuKey === `${active.id}:${active.text}:${c.start}`);
+        if (options.onEditKeyDown?.(event, snapshot, acceptsSuggestion)) {
+            event.preventDefault();
+            return;
+        }
         if (event.key === 'Enter') {
             event.preventDefault();
             const action = mathEnterAction({
@@ -819,7 +914,7 @@ export function mountMathEditor(host, initial = {}) {
         if (activeGrid(state) &&
             event.altKey &&
             event.shiftKey &&
-            ['ArrowUp', 'ArrowLeft'].includes(event.key)) {
+            ['ArrowUp', 'Backspace'].includes(event.key)) {
             event.preventDefault();
             apply(resizeMatrix(state, event.key === 'ArrowUp' ? 'row' : 'column', 'delete'));
             return;
@@ -858,7 +953,7 @@ export function mountMathEditor(host, initial = {}) {
         }
         if (!event.shiftKey && ['ArrowUp', 'ArrowDown'].includes(event.key)) {
             const direction = event.key === 'ArrowUp' ? -1 : 1;
-            const next = moveVertical(state, direction, renderedCaretGeometry(surface));
+            const next = verticalNavigation.move(state, direction, renderedCaretGeometry(surface));
             if (next !== state) {
                 event.preventDefault();
                 session.select(next.caret);
@@ -896,6 +991,14 @@ export function mountMathEditor(host, initial = {}) {
                 }
                 return;
             }
+            if (event.key === 'Delete' && c.end === active.text.length) {
+                const joined = joinNextLine(state);
+                const next = joined !== state ? joined : unwrapNext(state);
+                if (next !== state) {
+                    event.preventDefault();
+                    apply(next);
+                }
+            }
             if (event.key === 'Backspace' && c.start === 0) {
                 const joined = joinPreviousLine(state), next = joined !== state ? joined : unwrapPrevious(state);
                 if (next !== state) {
@@ -945,6 +1048,7 @@ export function mountMathEditor(host, initial = {}) {
         };
     };
     surface.onpointerdown = (event) => {
+        verticalNavigation.reset();
         if (event.button || composing || drag || event.target.closest('.me-line-number'))
             return;
         const point = pointAt(event.clientX, event.clientY);
@@ -1050,6 +1154,8 @@ export function mountMathEditor(host, initial = {}) {
     doc.addEventListener('pointercancel', cancelPointer, true);
     win.addEventListener('blur', cancelDrag);
     surface.onkeydown = (event) => {
+        if (event.target !== currentInput())
+            verticalNavigation.reset();
         if (event.target === currentInput())
             return;
         event.stopPropagation();
@@ -1063,7 +1169,9 @@ export function mountMathEditor(host, initial = {}) {
             return;
         }
         if (matrixSelectionKey(event) ||
+            tokenNavigation(event) ||
             keyboardSelect(event) ||
+            directSelectionKey(event) ||
             selectionMenuKey(event) ||
             keyboardCollapse(event))
             return;
@@ -1129,6 +1237,12 @@ export function mountMathEditor(host, initial = {}) {
         if (composing)
             return;
         const data = event.clipboardData, fragment = parseFragment(data?.getData(MATH_CLIPBOARD_TYPE) ?? ''), text = data?.getData('text/plain') ?? '';
+        if (data?.getData(MATH_CLIPBOARD_TYPE) && !fragment) {
+            event.preventDefault();
+            event.stopPropagation();
+            notify('clipboard.invalid');
+            return;
+        }
         const matrixSource = data?.getData(MATH_MATRIX_CLIPBOARD_TYPE) ?? '';
         const matrix = matrixSource ? parseMatrixFragment(matrixSource) : matrixFromTSV(text);
         const snapshot = session.getSnapshot();
@@ -1189,6 +1303,8 @@ export function mountMathEditor(host, initial = {}) {
         toolbar?.setDisabled(composing);
     };
     const unsubscribe = session.subscribe((snapshot, changed) => {
+        if (changed)
+            verticalNavigation.reset();
         if (changed) {
             cancelDrag();
             selectionMenu.reset();
@@ -1197,6 +1313,7 @@ export function mountMathEditor(host, initial = {}) {
         if (changed)
             options.onChange?.(snapshot.state.document, snapshot.latex);
     });
+    const stopReadableLayout = followReadableMathLayout(surface);
     const stopPosition = followMathMenuPosition(root, () => {
         if (!menu.hidden)
             drawMenu();
@@ -1205,6 +1322,10 @@ export function mountMathEditor(host, initial = {}) {
     render();
     return {
         session,
+        showHelp() {
+            if (!destroyed)
+                requestMathHelp(root);
+        },
         focus() {
             editing = true;
             render();
@@ -1223,10 +1344,12 @@ export function mountMathEditor(host, initial = {}) {
             destroyed = true;
             cancelDrag();
             unsubscribe();
+            stopHelp();
             latexPanel?.destroy();
             toolbar?.destroy();
             root.removeEventListener('focusout', blur);
             stopPosition();
+            stopReadableLayout();
             doc.removeEventListener('pointermove', movePointer, true);
             doc.removeEventListener('pointerup', endPointer, true);
             doc.removeEventListener('pointercancel', cancelPointer, true);

package/dist/enter-policy.js

@@ -4,7 +4,7 @@ export function mathEnterAction(context) {
         return 'suggestion';
     if (context.gridKind && context.shiftKey)
         return 'grid-row';
-    if (context.mode === 'inline' || context.behavior === 'commit')
+    if (context.mode === 'inline' || (context.behavior === 'commit' && !context.shiftKey))
         return 'commit';
     if (context.gridKind)
         return context.gridKind === 'matrix' ? 'none' : 'grid-row';

package/dist/lines.d.ts

@@ -3,4 +3,6 @@ import { type MathState } from './model.js';
 export declare function splitLine(state: MathState): MathState;
 /** Backspace at the start of a top-level line merges it with the previous line. */
 export declare function joinPreviousLine(state: MathState): MathState;
+/** Delete at the end of a top-level line joins the following line without moving the caret. */
+export declare function joinNextLine(state: MathState): MathState;
 export declare function moveLineVertical(state: MathState, direction: -1 | 1): MathState;

package/dist/lines.js

@@ -39,6 +39,21 @@ export function joinPreviousLine(state) {
         delete document.additionalLines;
     return { document, caret: { id: tail.id, start: offset, end: offset } };
 }
+/** Delete at the end of a top-level line joins the following line without moving the caret. */
+export function joinNextLine(state) {
+    if (state.caret.start !== state.caret.end)
+        return state;
+    const lines = documentRows(state.document);
+    const index = lines.findIndex((line) => line.children.at(-1)?.id === state.caret.id);
+    const tail = lines[index]?.children.at(-1);
+    const head = lines[index + 1]?.children[0];
+    if (index < 0 ||
+        tail?.type !== 'text' ||
+        head?.type !== 'text' ||
+        state.caret.end !== tail.text.length)
+        return state;
+    return joinPreviousLine({ ...state, caret: { id: head.id, start: 0, end: 0 } });
+}
 export function moveLineVertical(state, direction) {
     const lines = documentRows(state.document);
     const index = lines.findIndex((line) => line.children.some((node) => node.type === 'text' && node.id === state.caret.id));

package/dist/locales/en.js

@@ -92,7 +92,8 @@ export default {
         "grid.addColumn": "Add column",
         "grid.deleteColumn": "Delete column",
         "grid.deleteRowShortcut": "Delete row: Alt(⌥)+Shift+↑",
-        "grid.deleteColumnShortcut": "Delete column: Alt(⌥)+Shift+←",
+        "grid.deleteColumnShortcut": "Delete column: Alt(⌥)+Shift+Backspace",
+        "clipboard.invalid": "The copied formula data is invalid. The formula was not changed.",
         "clipboard.cut": "Selected math cut.",
         "clipboard.copied": "Selected math copied as structure and LaTeX.",
         "clipboard.pasted": "Pasted.",
@@ -101,13 +102,15 @@ export default {
         "grid.selectionHint": "Structure selected · Backspace/Delete to remove · Esc to cancel",
         "selection.toolbar": "Wrap selected math",
         "selection.highlighted": "Wrap highlighted range",
+        "selection.asNumerator": "Use as numerator",
+        "selection.asDenominator": "Use as denominator",
         "selection.singleRowRequired": "Select a range within one row.",
         "suggestion.label": "Math suggestions",
         "suggestion.composing": "Composing · Choose after committing",
         "suggestion.keyboardHint": "↑ ↓ to choose · Enter to apply",
         "suggestion.imeHint": "Suggestion preview · Enter and arrows are reserved for the IME",
         "suggestion.keepSource": "Keep typing, or use Space / Esc to keep the source",
-        "matrix.keyboardHint": "Shift+Enter add row · Shift+Space add column · Alt(⌥)+Shift+↑ delete row · Alt(⌥)+Shift+← delete column",
+        "matrix.keyboardHint": "Shift+Enter add row · Shift+Space add column · Alt(⌥)+Shift+↑ delete row · Alt(⌥)+Shift+Backspace delete column",
         "aligned.inputHint": "Left: left-hand side · Right: start with =",
         "cases.inputHint": "Left: expression · Right: condition",
         "grid.keyboardHint": "Enter add row · Alt(⌥)+Shift+↑ delete row",
@@ -155,6 +158,7 @@ export default {
         "template.detail": "Editable math template",
         "template.quadratic": "Quadratic formula",
         "template.pythagorean": "Pythagorean theorem",
+        "symbol.prime": "Prime",
         "symbol.degree": "Degree",
         "symbol.angle": "Angle",
         "symbol.plus": "Plus",
@@ -353,7 +357,21 @@ export default {
         "context.indexedRoot": "Indexed root",
         "context.fenceKeyboardHint": "F6: tools · ← →: choose · Enter: apply · Esc: back to input",
         "suggestion.transformFence": "Change brackets: {kind}",
-        "suggestion.transformFenceDetail": "Keep the enclosed formula and cursor position"
+        "suggestion.transformFenceDetail": "Keep the enclosed formula and cursor position",
+        "help.title": "Keyboard & clipboard help",
+        "help.intro": "Keep typing with these controls. Close help to return to your formula.",
+        "help.units": "Move by a variable, number or whole structure. Add Shift to extend selection. Inside a slot, reach the current token edge before leaving the structure.",
+        "help.slots": "Move to the next or previous editable slot.",
+        "help.select": "Extend the formula selection.",
+        "help.wrap": "With math selected: wrap in brackets, absolute value, a fraction, a power or a subscript.",
+        "help.suggestions": "Open suggestions and available transformations, even without a toolbar.",
+        "help.menu": "Choose a suggestion, apply it, or dismiss the menu.",
+        "help.clipboard": "Copy, cut or paste. Editor data preserves structure when the browser retains it. Ordinary text pastes literally.",
+        "help.latex": "Open Paste as LaTeX. Paste the source, then Ctrl/Cmd+Enter to insert. Invalid input leaves the formula unchanged.",
+        "help.history": "Undo or redo an edit.",
+        "help.lines": "Enter follows the host/mode policy. Shift+Enter adds a grid row or a block line. Inline mode never adds a top-level formula line.",
+        "help.open": "Open this help while the formula has focus.",
+        "help.platform": "Cmd on macOS, Ctrl on Windows/Linux. Alt is Option on macOS. Some keyboards require Fn+F1. Host or OS shortcuts can take precedence."
     },
     "aliases": {}
 };

package/dist/locales/en.json

@@ -91,7 +91,8 @@
         "grid.addColumn": "Add column",
         "grid.deleteColumn": "Delete column",
         "grid.deleteRowShortcut": "Delete row: Alt(⌥)+Shift+↑",
-        "grid.deleteColumnShortcut": "Delete column: Alt(⌥)+Shift+←",
+        "grid.deleteColumnShortcut": "Delete column: Alt(⌥)+Shift+Backspace",
+        "clipboard.invalid": "The copied formula data is invalid. The formula was not changed.",
         "clipboard.cut": "Selected math cut.",
         "clipboard.copied": "Selected math copied as structure and LaTeX.",
         "clipboard.pasted": "Pasted.",
@@ -100,13 +101,15 @@
         "grid.selectionHint": "Structure selected · Backspace/Delete to remove · Esc to cancel",
         "selection.toolbar": "Wrap selected math",
         "selection.highlighted": "Wrap highlighted range",
+        "selection.asNumerator": "Use as numerator",
+        "selection.asDenominator": "Use as denominator",
         "selection.singleRowRequired": "Select a range within one row.",
         "suggestion.label": "Math suggestions",
         "suggestion.composing": "Composing · Choose after committing",
         "suggestion.keyboardHint": "↑ ↓ to choose · Enter to apply",
         "suggestion.imeHint": "Suggestion preview · Enter and arrows are reserved for the IME",
         "suggestion.keepSource": "Keep typing, or use Space / Esc to keep the source",
-        "matrix.keyboardHint": "Shift+Enter add row · Shift+Space add column · Alt(⌥)+Shift+↑ delete row · Alt(⌥)+Shift+← delete column",
+        "matrix.keyboardHint": "Shift+Enter add row · Shift+Space add column · Alt(⌥)+Shift+↑ delete row · Alt(⌥)+Shift+Backspace delete column",
         "aligned.inputHint": "Left: left-hand side · Right: start with =",
         "cases.inputHint": "Left: expression · Right: condition",
         "grid.keyboardHint": "Enter add row · Alt(⌥)+Shift+↑ delete row",
@@ -154,6 +157,7 @@
         "template.detail": "Editable math template",
         "template.quadratic": "Quadratic formula",
         "template.pythagorean": "Pythagorean theorem",
+        "symbol.prime": "Prime",
         "symbol.degree": "Degree",
         "symbol.angle": "Angle",
         "symbol.plus": "Plus",
@@ -352,7 +356,21 @@
         "context.indexedRoot": "Indexed root",
         "context.fenceKeyboardHint": "F6: tools · ← →: choose · Enter: apply · Esc: back to input",
         "suggestion.transformFence": "Change brackets: {kind}",
-        "suggestion.transformFenceDetail": "Keep the enclosed formula and cursor position"
+        "suggestion.transformFenceDetail": "Keep the enclosed formula and cursor position",
+        "help.title": "Keyboard & clipboard help",
+        "help.intro": "Keep typing with these controls. Close help to return to your formula.",
+        "help.units": "Move by a variable, number or whole structure. Add Shift to extend selection. Inside a slot, reach the current token edge before leaving the structure.",
+        "help.slots": "Move to the next or previous editable slot.",
+        "help.select": "Extend the formula selection.",
+        "help.wrap": "With math selected: wrap in brackets, absolute value, a fraction, a power or a subscript.",
+        "help.suggestions": "Open suggestions and available transformations, even without a toolbar.",
+        "help.menu": "Choose a suggestion, apply it, or dismiss the menu.",
+        "help.clipboard": "Copy, cut or paste. Editor data preserves structure when the browser retains it. Ordinary text pastes literally.",
+        "help.latex": "Open Paste as LaTeX. Paste the source, then Ctrl/Cmd+Enter to insert. Invalid input leaves the formula unchanged.",
+        "help.history": "Undo or redo an edit.",
+        "help.lines": "Enter follows the host/mode policy. Shift+Enter adds a grid row or a block line. Inline mode never adds a top-level formula line.",
+        "help.open": "Open this help while the formula has focus.",
+        "help.platform": "Cmd on macOS, Ctrl on Windows/Linux. Alt is Option on macOS. Some keyboards require Fn+F1. Host or OS shortcuts can take precedence."
     },
     "aliases": {}
 }

package/dist/locales/ko.js

@@ -92,7 +92,8 @@ export default {
         "grid.addColumn": "열 추가",
         "grid.deleteColumn": "열 삭제",
         "grid.deleteRowShortcut": "행 삭제: Alt(⌥)+Shift+↑",
-        "grid.deleteColumnShortcut": "열 삭제: Alt(⌥)+Shift+←",
+        "grid.deleteColumnShortcut": "열 삭제: Alt(⌥)+Shift+Backspace",
+        "clipboard.invalid": "복사한 수식 데이터가 올바르지 않습니다. 기존 수식은 유지됩니다.",
         "clipboard.cut": "선택한 수식을 잘라냈습니다.",
         "clipboard.copied": "선택한 수식을 구조와 LaTeX로 복사했습니다.",
         "clipboard.pasted": "붙여넣었습니다.",
@@ -101,13 +102,15 @@ export default {
         "grid.selectionHint": "수식 구조 전체 선택 · Backspace/Delete로 삭제 · Esc로 취소",
         "selection.toolbar": "선택한 수식 감싸기",
         "selection.highlighted": "강조된 범위 감싸기",
+        "selection.asNumerator": "분자로 넣기",
+        "selection.asDenominator": "분모로 넣기",
         "selection.singleRowRequired": "한 줄 안의 범위를 선택해 주세요.",
         "suggestion.label": "수식 추천",
         "suggestion.composing": "한글 조합 중 · 확정 후 선택",
         "suggestion.keyboardHint": "↑ ↓ 선택 · Enter 적용",
         "suggestion.imeHint": "후보 미리보기 · Enter와 방향키는 한글 입력에 사용됩니다",
         "suggestion.keepSource": "계속 입력하거나 Space · Esc로 원문 유지",
-        "matrix.keyboardHint": "Shift+Enter 행 추가 · Shift+Space 열 추가 · Alt(⌥)+Shift+↑ 행 삭제 · Alt(⌥)+Shift+← 열 삭제",
+        "matrix.keyboardHint": "Shift+Enter 행 추가 · Shift+Space 열 추가 · Alt(⌥)+Shift+↑ 행 삭제 · Alt(⌥)+Shift+Backspace 열 삭제",
         "aligned.inputHint": "왼쪽: 좌변 · 오른쪽: =부터 입력",
         "cases.inputHint": "왼쪽: 식 · 오른쪽: 조건",
         "grid.keyboardHint": "Enter 행 추가 · Alt(⌥)+Shift+↑ 행 삭제",
@@ -155,6 +158,7 @@ export default {
         "template.detail": "편집 가능한 수식 템플릿",
         "template.quadratic": "근의 공식",
         "template.pythagorean": "피타고라스 정리",
+        "symbol.prime": "프라임",
         "symbol.degree": "도",
         "symbol.angle": "각 기호",
         "symbol.plus": "더하기",
@@ -353,7 +357,21 @@ export default {
         "context.indexedRoot": "n제곱근",
         "context.fenceKeyboardHint": "F6: 도구로 이동 · ← →: 선택 · Enter: 적용 · Esc: 입력으로",
         "suggestion.transformFence": "괄호 변경: {kind}",
-        "suggestion.transformFenceDetail": "안의 수식과 커서 위치를 유지합니다"
+        "suggestion.transformFenceDetail": "안의 수식과 커서 위치를 유지합니다",
+        "help.title": "단축키와 복사·붙여넣기",
+        "help.intro": "키보드로 수식을 편집하는 방법입니다. 도움말을 닫으면 수식으로 돌아갑니다.",
+        "help.units": "변수·숫자·구조 단위로 이동합니다. Shift를 함께 누르면 선택합니다. 구조 안에서는 현재 항목의 경계로 이동한 뒤 구조 밖으로 나갑니다.",
+        "help.slots": "다음 또는 이전 입력 칸으로 이동합니다.",
+        "help.select": "수식의 선택 범위를 늘립니다.",
+        "help.wrap": "수식을 선택한 상태에서 괄호·절대값·분수·지수·아래첨자로 감쌉니다.",
+        "help.suggestions": "툴바 없이도 제안 목록과 가능한 변형을 엽니다.",
+        "help.menu": "제안을 고르고 적용하거나 목록을 닫습니다.",
+        "help.clipboard": "복사·잘라내기·붙여넣기입니다. 브라우저가 편집기 데이터를 유지하면 구조도 보존됩니다. 일반 텍스트는 글자로 붙여넣습니다.",
+        "help.latex": "LaTeX 붙여넣기를 엽니다. 원문을 붙여넣고 Ctrl/Cmd+Enter로 삽입합니다. 잘못된 입력은 기존 수식을 바꾸지 않습니다.",
+        "help.history": "편집을 실행 취소하거나 다시 실행합니다.",
+        "help.lines": "Enter는 모드와 연동 설정을 따릅니다. Shift+Enter는 행렬의 행 또는 블록 수식의 줄을 추가합니다. 인라인 모드는 수식의 바깥 줄을 추가하지 않습니다.",
+        "help.open": "수식에 포커스가 있을 때 도움말을 엽니다.",
+        "help.platform": "macOS에서는 Cmd, Windows/Linux에서는 Ctrl을 사용합니다. macOS의 Alt는 Option입니다. 일부 키보드는 Fn+F1이 필요합니다. 운영체제나 연동 편집기의 단축키가 우선할 수 있습니다."
     },
     "aliases": {
         "function-sin": ["사인"],

package/dist/locales/ko.json

@@ -91,7 +91,8 @@
         "grid.addColumn": "열 추가",
         "grid.deleteColumn": "열 삭제",
         "grid.deleteRowShortcut": "행 삭제: Alt(⌥)+Shift+↑",
-        "grid.deleteColumnShortcut": "열 삭제: Alt(⌥)+Shift+←",
+        "grid.deleteColumnShortcut": "열 삭제: Alt(⌥)+Shift+Backspace",
+        "clipboard.invalid": "복사한 수식 데이터가 올바르지 않습니다. 기존 수식은 유지됩니다.",
         "clipboard.cut": "선택한 수식을 잘라냈습니다.",
         "clipboard.copied": "선택한 수식을 구조와 LaTeX로 복사했습니다.",
         "clipboard.pasted": "붙여넣었습니다.",
@@ -100,13 +101,15 @@
         "grid.selectionHint": "수식 구조 전체 선택 · Backspace/Delete로 삭제 · Esc로 취소",
         "selection.toolbar": "선택한 수식 감싸기",
         "selection.highlighted": "강조된 범위 감싸기",
+        "selection.asNumerator": "분자로 넣기",
+        "selection.asDenominator": "분모로 넣기",
         "selection.singleRowRequired": "한 줄 안의 범위를 선택해 주세요.",
         "suggestion.label": "수식 추천",
         "suggestion.composing": "한글 조합 중 · 확정 후 선택",
         "suggestion.keyboardHint": "↑ ↓ 선택 · Enter 적용",
         "suggestion.imeHint": "후보 미리보기 · Enter와 방향키는 한글 입력에 사용됩니다",
         "suggestion.keepSource": "계속 입력하거나 Space · Esc로 원문 유지",
-        "matrix.keyboardHint": "Shift+Enter 행 추가 · Shift+Space 열 추가 · Alt(⌥)+Shift+↑ 행 삭제 · Alt(⌥)+Shift+← 열 삭제",
+        "matrix.keyboardHint": "Shift+Enter 행 추가 · Shift+Space 열 추가 · Alt(⌥)+Shift+↑ 행 삭제 · Alt(⌥)+Shift+Backspace 열 삭제",
         "aligned.inputHint": "왼쪽: 좌변 · 오른쪽: =부터 입력",
         "cases.inputHint": "왼쪽: 식 · 오른쪽: 조건",
         "grid.keyboardHint": "Enter 행 추가 · Alt(⌥)+Shift+↑ 행 삭제",
@@ -154,6 +157,7 @@
         "template.detail": "편집 가능한 수식 템플릿",
         "template.quadratic": "근의 공식",
         "template.pythagorean": "피타고라스 정리",
+        "symbol.prime": "프라임",
         "symbol.degree": "도",
         "symbol.angle": "각 기호",
         "symbol.plus": "더하기",
@@ -352,7 +356,21 @@
         "context.indexedRoot": "n제곱근",
         "context.fenceKeyboardHint": "F6: 도구로 이동 · ← →: 선택 · Enter: 적용 · Esc: 입력으로",
         "suggestion.transformFence": "괄호 변경: {kind}",
-        "suggestion.transformFenceDetail": "안의 수식과 커서 위치를 유지합니다"
+        "suggestion.transformFenceDetail": "안의 수식과 커서 위치를 유지합니다",
+        "help.title": "단축키와 복사·붙여넣기",
+        "help.intro": "키보드로 수식을 편집하는 방법입니다. 도움말을 닫으면 수식으로 돌아갑니다.",
+        "help.units": "변수·숫자·구조 단위로 이동합니다. Shift를 함께 누르면 선택합니다. 구조 안에서는 현재 항목의 경계로 이동한 뒤 구조 밖으로 나갑니다.",
+        "help.slots": "다음 또는 이전 입력 칸으로 이동합니다.",
+        "help.select": "수식의 선택 범위를 늘립니다.",
+        "help.wrap": "수식을 선택한 상태에서 괄호·절대값·분수·지수·아래첨자로 감쌉니다.",
+        "help.suggestions": "툴바 없이도 제안 목록과 가능한 변형을 엽니다.",
+        "help.menu": "제안을 고르고 적용하거나 목록을 닫습니다.",
+        "help.clipboard": "복사·잘라내기·붙여넣기입니다. 브라우저가 편집기 데이터를 유지하면 구조도 보존됩니다. 일반 텍스트는 글자로 붙여넣습니다.",
+        "help.latex": "LaTeX 붙여넣기를 엽니다. 원문을 붙여넣고 Ctrl/Cmd+Enter로 삽입합니다. 잘못된 입력은 기존 수식을 바꾸지 않습니다.",
+        "help.history": "편집을 실행 취소하거나 다시 실행합니다.",
+        "help.lines": "Enter는 모드와 연동 설정을 따릅니다. Shift+Enter는 행렬의 행 또는 블록 수식의 줄을 추가합니다. 인라인 모드는 수식의 바깥 줄을 추가하지 않습니다.",
+        "help.open": "수식에 포커스가 있을 때 도움말을 엽니다.",
+        "help.platform": "macOS에서는 Cmd, Windows/Linux에서는 Ctrl을 사용합니다. macOS의 Alt는 Option입니다. 일부 키보드는 Fn+F1이 필요합니다. 운영체제나 연동 편집기의 단축키가 우선할 수 있습니다."
     },
     "aliases": {
         "function-sin": ["사인"],

package/dist/math-editor-toolbar.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { requestMathHelp } from './dom/help.js';
 import { useState } from 'react';
 import { mathStructures } from './suggestions.js';
 import { wrappingKinds } from './range.js';
@@ -17,7 +18,7 @@ export function MathEditorToolbar({ locale, kinds, maxItems = 8, excludedStructu
     const visibleCount = Math.max(0, Math.floor(Number.isFinite(maxItems) ? maxItems : 8));
     const items = mathStructures.filter((s) => s.kind && !excludedStructures.includes(s.kind) && (!kinds || kinds.includes(s.kind)));
     const t = (key, parameters) => translate(locale, key, parameters);
-    return (_jsxs("div", { className: "me-tools", role: "toolbar", "aria-label": t('toolbar.label'), children: [(expanded ? items : items.slice(0, visibleCount)).map((s) => (_jsxs("button", { type: "button", "aria-label": t(s.label), disabled: composing || (hasRange && (!canWrap || !wrappingKinds.includes(s.kind))), onMouseDown: (event) => event.preventDefault(), onClick: () => onInsertStructure(s.kind), children: [_jsx("span", { children: s.glyph }), t(s.label)] }, s.kind))), expanded && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "data-math-tool": "quick", disabled: composing || cellRange, onMouseDown: (event) => event.preventDefault(), onClick: onQuick, children: t('quick.title') }), _jsx("button", { type: "button", "data-math-tool": "paste-latex", disabled: composing || cellRange, onMouseDown: (event) => event.preventDefault(), onClick: onPasteLatex, title: t('clipboard.latexShortcut'), children: t('clipboard.latexTitle') }), _jsxs("select", { disabled: composing || hasRange, className: "me-matrix-size", "aria-label": t('matrix.preset'), value: "", onChange: (event) => {
+    return (_jsxs("div", { className: "me-tools", role: "toolbar", "aria-label": t('toolbar.label'), children: [_jsx("button", { type: "button", "data-math-tool": "help", disabled: composing, title: `${t('help.title')} (F1)`, "aria-keyshortcuts": "F1", onMouseDown: (event) => event.preventDefault(), onClick: (event) => requestMathHelp(event.currentTarget), children: t('help.title') }), (expanded ? items : items.slice(0, visibleCount)).map((s) => (_jsxs("button", { type: "button", "aria-label": t(s.label), disabled: composing || (hasRange && (!canWrap || !wrappingKinds.includes(s.kind))), onMouseDown: (event) => event.preventDefault(), onClick: () => onInsertStructure(s.kind), children: [_jsx("span", { children: s.glyph }), t(s.label)] }, s.kind))), expanded && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "data-math-tool": "quick", disabled: composing || cellRange, onMouseDown: (event) => event.preventDefault(), onClick: onQuick, children: t('quick.title') }), _jsx("button", { type: "button", "data-math-tool": "paste-latex", disabled: composing || cellRange, onMouseDown: (event) => event.preventDefault(), onClick: onPasteLatex, title: t('clipboard.latexShortcut'), children: t('clipboard.latexTitle') }), _jsxs("select", { disabled: composing || hasRange, className: "me-matrix-size", "aria-label": t('matrix.preset'), value: "", onChange: (event) => {
                             const value = event.target.value;
                             onMatrixPreset(value);
                         }, children: [_jsx("option", { value: "", disabled: true, children: t('matrix.presetPlaceholder') }), [2, 3, 4].map((size) => (_jsx("option", { value: size, children: t('matrix.insert', { rows: size, columns: size }) }, size))), [2, 3, 4].map((size) => (_jsx("option", { value: `identity-${size}`, children: t('matrix.insertIdentity', { rows: size, columns: size }) }, `identity-${size}`)))] }), _jsxs("select", { className: "me-matrix-size", "aria-label": t('template.label'), value: "", disabled: composing || cellRange, onChange: (event) => onTemplate(event.target.value), children: [_jsx("option", { value: "", disabled: true, children: t('template.placeholder') }), mathTemplates.map((item) => (_jsx("option", { value: item.id, children: t(item.label, item.labelParameters) }, item.id)))] }), _jsx("button", { type: "button", "aria-expanded": symbolsOpen, disabled: composing || cellRange, onClick: onToggleSymbols, children: t('symbols.title') }), _jsx("span", { className: "me-divider" }), symbols.map((s) => (_jsx("button", { type: "button", "aria-label": t(s.label), disabled: composing || hasRange, onMouseDown: (event) => event.preventDefault(), onClick: () => onInsertSymbol(s.value), children: s.value }, s.label)))] })), _jsx("button", { type: "button", className: "me-toolbar-toggle", "aria-expanded": expanded, onMouseDown: (event) => event.preventDefault(), onClick: () => setExpanded((value) => !value), children: t(expanded ? 'toolbar.less' : 'toolbar.more') }), _jsx("button", { type: "button", disabled: !canUndo || composing, onMouseDown: (event) => event.preventDefault(), onClick: onUndo, children: t('history.undo') }), _jsx("button", { type: "button", disabled: !canRedo || composing, onMouseDown: (event) => event.preventDefault(), onClick: onRedo, children: t('history.redo') }), children] }));