/**
* 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()
}