/** * Whether the event target is a plain text-like `` — the controls where * pressing Enter should submit an inline editor. Excludes textareas (Enter * inserts a newline) and richer controls that handle Enter themselves (e.g. a * dropdown that opens its menu on Enter), so a keyboard user isn't forced to * submit instead of operating the control. */ export function isTextLikeInput(target: EventTarget | null): boolean { const el = target as HTMLElement | null if (!el || el.tagName !== 'INPUT') { return false } const type = (el as HTMLInputElement).type return ['text', 'search', 'url', 'email', 'tel', 'password', 'number'].includes(type) } export type EditorSubmitShortcut = 'enter' | 'command-enter' | 'control-enter' /** * The user-facing shortcut to show for the currently focused editor control. * Plain Enter is truthful only for simple text-like inputs; other controls need * the platform's primary modifier to avoid clashing with their own Enter key * behavior. A text input nested inside a dropdown (its search filter, see * `SDropdownSectionFilter` / `SInputAsyncDropdown`) keeps Enter to itself * too, so only the modifier gesture reaches the editor from there. */ export function editorSubmitShortcutForTarget( target: EventTarget | null, platform = currentPlatform() ): EditorSubmitShortcut { if ( isTextLikeInput(target) && !(target as HTMLElement).closest('.SDropdown, .SInputAsyncDropdown') ) { return 'enter' } return hasCommandShortcutModifier(platform) ? 'command-enter' : 'control-enter' } const commandShortcutPlatforms = new Set([ 'ios', 'ipados', 'macos', // `navigator.platform` fallback values. 'ipad', 'iphone', 'macintel' ]) function hasCommandShortcutModifier(platform: string): boolean { return commandShortcutPlatforms.has(platform.toLowerCase()) } function currentPlatform(): string { if (typeof navigator === 'undefined') { return '' } const nav = navigator as Navigator & { userAgentData?: { platform?: string } } return nav.userAgentData?.platform ?? nav.platform ?? '' } /** * Keydown handler for a text input nested inside a dropdown-like control (a * search filter): Enter operates the control, not an enclosing inline editor, * so it is stopped — with its default prevented — unless it carries the * universal submit modifier (Cmd/Ctrl, see {@link isEditorSubmitKeydown}). * Shift/Alt+Enter are contained too: the editor's submit predicate would read * them off a text-like input as a plain submitting Enter. The Enter that * commits an IME composition belongs to the IME — swallowing its default would * drop the composed text — so it passes untouched (the editor ignores it). */ export function stopNonSubmitEnterKeydown(event: KeyboardEvent): void { if (event.isComposing) { return } if (event.key === 'Enter' && !event.metaKey && !event.ctrlKey) { event.stopPropagation() event.preventDefault() } } /** * Whether an Enter keydown should submit an inline editor. Ctrl/Cmd+Enter * submits from any control — it's the near-universal "submit" gesture (GitHub, * Gmail, Slack, …) and never clashes with a textarea's newline or a control that * handles bare Enter itself (e.g. a dropdown opening its menu). Bare Enter * submits only from a plain text-like input (see {@link isTextLikeInput}). * * Shift+Enter is left for newlines, and Alt/Option+Enter has no consistent * submit meaning (Excel uses it for an in-cell newline), so neither submits. * The Enter that commits an IME composition (e.g. CJK input) never submits. */ export function isEditorSubmitKeydown(event: KeyboardEvent): boolean { if (event.key !== 'Enter') { return false } // Ignore the Enter that commits an IME composition (e.g. CJK input): it // confirms the candidate rather than submitting. if (event.isComposing) { return false } return event.ctrlKey || event.metaKey || isTextLikeInput(event.target) } /** * Whether a keydown should cancel an inline editor: Escape, except the Escape * that cancels an in-progress IME composition (which reverts the candidate and * should leave the editor open). */ export function isEditorCancelKeydown(event: KeyboardEvent): boolean { return event.key === 'Escape' && !event.isComposing } /** * Dispatch a keydown for an inline editor (opened from a cell or sheet field): * cancel on Escape, submit on Enter — using the IME- and modifier-aware rules * in {@link isEditorCancelKeydown} / {@link isEditorSubmitKeydown}. * * `shield` is for an editor nested in a surface that itself closes on Escape * (e.g. a sheet): Escape is always kept from propagating to that surface — even * the Escape that only cancels an IME composition (where the edit stays open) — * so the surface can't close underneath the editor. * * NOTE for future inline/sheet-editable fields: several field types currently * throw on `formInputComponent()` (not yet editable). When making one editable, * if its input is a composite control with its own nested text input (e.g. a * dropdown's search filter), that nested input must keep Enter/Escape from * bubbling to this handler — {@link stopNonSubmitEnterKeydown} is the Enter * half; see `SDropdownSectionFilter` — otherwise typing a value and pressing * Enter would submit/cancel the whole editor. */ export function dispatchEditorKeydown( event: KeyboardEvent, handlers: { cancel: () => void; submit: () => void; shield?: boolean } ): void { if (event.key === 'Escape') { if (handlers.shield) { event.stopPropagation() } if (isEditorCancelKeydown(event)) { event.preventDefault() handlers.cancel() } return } if (isEditorSubmitKeydown(event)) { event.preventDefault() handlers.submit() } } /** * Focus the first focusable editor control (an input, textarea, contenteditable, * or any `[tabindex]`) inside the container — used to focus an inline editor when * it opens. * * Candidates inside `skip` (default `.actions`, the editor's action row) are * ignored, so focus never lands on a Cancel/Save button — those are `[tabindex]` * elements too — when the field input has no focusable control of its own (e.g. * a radio/checkbox group). In that case nothing is focused. Pass `skip: ''` to * disable. */ export function focusFirstEditable(container: HTMLElement | null, skip = '.actions'): void { const candidates = Array.from( container?.querySelectorAll('input, textarea, [contenteditable], [tabindex]') ?? [] ) candidates.find((el) => !skip || !el.closest(skip))?.focus() }