dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / src / web / editing / exec_command.lucb
#==============================================================================================
#
# exec_command - Document.execCommand() and the queryCommand*() methods
#
# DESCRIPTION:
# Port of LibWeb/Editing/ExecCommand.cpp (all of it): the DOM::Document methods of the
# execCommand spec (exec_command, query_command_enabled/indeterm/state/supported/value)
# and the value-override bookkeeping. The command table, the active range and the
# editing algorithms they call are Editing/ (phase 4) and live in the closure stubs.
#
# Copyright (c) 2024-2025, Jelle Raaijmakers <jelle@ladybird.org>
# SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================
# mark: Helpers =================================================================================
## exec_command step 4: the commands it fires no input events for (the Miscellaneous commands, plus the clipboard ones).
let exec_command_miscellaneous_commands: str[9] = ["copy", "cut", "defaultParagraphSeparator", "paste", "redo", "selectAll", "styleWithCSS", "undo", "useCSS"]
## query_command_enabled: the Miscellaneous commands that are always enabled.
let exec_command_always_enabled_commands: str[5] = ["defaultParagraphSeparator", "redo", "styleWithCSS", "undo", "useCSS"]
## query_command_enabled: the commands not enabled when the editing host is plaintext-only.
let exec_command_plaintext_only_disabled_commands: str[25] = [
"backColor",
"bold",
"createLink",
"fontName",
"fontSize",
"foreColor",
"formatBlock", # AD-HOC: https://github.com/w3c/editing/issues/478
"hiliteColor",
"indent",
"insertHorizontalRule",
"insertImage",
"insertOrderedList",
"insertUnorderedList",
"italic",
"justifyCenter",
"justifyFull",
"justifyLeft",
"justifyRight",
"outdent",
"removeFormat",
"strikethrough",
"subscript",
"superscript",
"underline",
"unlink"]
## query_command_indeterm: the standard inline value commands.
let exec_command_standard_inline_value_commands: str[4] = ["backColor", "fontName", "foreColor", "hiliteColor"]
## `command.is_one_of(names...)` for FlyStrings compared by content.
func exec_command_is_one_of(command: const ak.FlyString*, names: const str[]) -> bool:
for name in names:
if ak.fly_string_eq_string_view(command, ak.sv(name)):
return true
return false
## `command.is_one_of_ignoring_ascii_case(names...)`.
func exec_command_is_one_of_ignoring_ascii_case(command: const ak.FlyString*, names: const str[]) -> bool:
for name in names:
if ak.fly_string_equals_ignoring_ascii_case_string_view(command, ak.sv(name)):
return true
return false
## `return WebIDL::InvalidStateError::create(realm(), message)` from an ExceptionOr function.
func exec_command_throw_invalid_state(document: DomDocument*, message: str) -> never!:
return try dom_document_throw(idl_invalid_state_error_create(dom_document_realm(document), ak.utf16_string_from_str(message)))
## `inline_activated_values.contains_slow(value)` over Utf16Views.
func exec_command_inline_values_contain(values: const ak.Vector[ak.Utf16View]*, value: const ak.Utf16String*) -> bool:
for candidate in ak.vector_span_const(values):
if ak.utf16_string_base_eq_utf16_view(&value.utf16_string_base, &candidate):
return true
return false
## `Editing::effective_command_value(node, command).value_or({})`.
func exec_command_effective_value_or_empty(node: DomNode*?, command: ak.FlyString) -> ak.Utf16String:
if let value = editing_effective_command_value(node, command):
return value
return ak.Utf16String()
# mark: execCommand =============================================================================
## Ported from ExecCommand.cpp:20 Web::DOM::Document::exec_command.
# https://w3c.github.io/editing/docs/execCommand/#execcommand()
pub func dom_document_exec_command(this: DomDocument*, command: ak.FlyString, show_ui: bool, value: ak.Utf16String) -> bool!:
# AD-HOC: This is not directly mentioned in the spec, but all major browsers limit editing API calls to HTML documents
if not dom_document_is_html_document(this):
try exec_command_throw_invalid_state(this, "execCommand is only supported on HTML documents")
# AD-HOC: All major browsers refuse to recursively execute execCommand() (e.g. inside input event handlers).
if this.m_inside_exec_command:
return false
# TemporaryChange guard_recursion { m_inside_exec_command, true };
let previous_inside_exec_command = this.m_inside_exec_command
this.m_inside_exec_command = true
defer this.m_inside_exec_command = previous_inside_exec_command
# 1. If only one argument was provided, let show UI be false.
# 2. If only one or two arguments were provided, let value be the empty string.
# NOTE: these steps are dealt by the default values for both show_ui and value
# 3. If command is not supported or not enabled, return false.
# NOTE: query_command_enabled() also checks if command is supported
let enabled = dom_document_query_command_enabled(this, command) else trap("MUST: query_command_enabled")
if not enabled:
return false
# 4. If command is not in the Miscellaneous commands section:
#
# We don't fire events for copy/cut/paste/undo/redo/selectAll because they should all have their own events. We
# don't fire events for styleWithCSS/useCSS because it's not obvious where to fire them, or why anyone would
# want them. We don't fire events for unsupported commands, because then if they became supported and were
# classified with the exec_command_miscellaneous_commands events, we'd have to stop firing events for consistency's sake.
#
# AD-HOC: The defaultParagraphSeparator command is also in the Miscellaneous commands section
let command_definition = editing_find_command_definition(command) else trap("VERIFY: optional_command.has_value()")
var affected_editing_host: DomNode*? = none
if not exec_command_is_one_of(&command_definition.command, exec_command_miscellaneous_commands):
# 1. Let affected editing host be the editing host that is an inclusive ancestor of the active range's start
# node and end node, and is not the ancestor of any editing host that is an inclusive ancestor of the active
# range's start node and end node.
#
# NOTE: Because either the start or end node of the range could be inside an editing host that is part of the
# other node's editing host, we can probe both and see if either one is the other's ancestor.
# NOTE: We can reuse ->editing_host() here since query_command_enabled() above already checked that both the
# start and end nodes are either editable or an editing host.
let range = editing_active_range(this) else trap("VERIFY: an active range")
let start_node_editing_host = dom_node_editing_host(dom_abstract_range_start_container(range.dom_abstract_range())) else trap("VERIFY: the start node has an editing host")
let end_node_editing_host = dom_node_editing_host(dom_abstract_range_end_container(range.dom_abstract_range())) else trap("VERIFY: the end node has an editing host")
affected_editing_host = end_node_editing_host if tree_node_is_ancestor_of(start_node_editing_host, end_node_editing_host) else start_node_editing_host
# 2. Fire an event named "beforeinput" at affected editing host using InputEvent, with its
# bubbles and cancelable attributes initialized to true, and its data attribute
# initialized to null.
# 3. If the value returned by the previous step is false, return false.
# 4. If command is not enabled, return false.
#
# We have to check again whether the command is enabled, because the beforeinput handler might have done
# something annoying like getSelection().removeAllRanges().
# 5. Let affected editing host be the editing host that is an inclusive ancestor of the active range's start
# node and end node, and is not the ancestor of any editing host that is an inclusive ancestor of the active
# range's start node and end node.
#
# This new affected editing host is what we'll fire the input event at in a couple of lines. We want to
# compute it beforehand just to be safe: bugs in the command action might remove the selection or something
# bad like that, and we don't want to have to handle it later. We recompute it after the beforeinput event
# is handled so that if the handler moves the selection to some other editing host, the input event will be
# fired at the editing host that was actually affected.
# AD-HOC: No, we don't. Neither Chrome nor Firefox fire the "beforeinput" event for execCommand(). This is an
# open discussion for the spec: https://github.com/w3c/editing/issues/200
# https://w3c.github.io/editing/docs/execCommand/#preserves-overrides
# If a command preserves overrides, then before taking its action, the user agent must record current overrides.
var overrides: ak.Vector[EditingRecordedOverride]
if command_definition.preserves_overrides:
overrides = editing_record_current_overrides(this)
# NOTE: Step 7 below asks us whether the DOM tree was modified, so keep track of the document versions.
let old_dom_tree_version = dom_document_dom_tree_version(this)
let old_character_data_version = dom_document_character_data_version(this)
# 5. Take the action for command, passing value to the instructions as an argument.
let action = command_definition.action else trap("VERIFY: the command has an action")
let command_result = action(this, value)
# https://w3c.github.io/editing/docs/execCommand/#preserves-overrides
# After taking the action, if the active range is collapsed, it must restore states and values from the recorded
# list.
if not ak.vector_is_empty(&overrides):
if let selection = this.m_selection:
if selection_selection_is_collapsed(selection):
editing_restore_states_and_values(this, &overrides)
# 6. If the previous step returned false, return false.
if not command_result:
return false
# 7. If the action modified DOM tree, then fire an event named "input" at affected editing host using InputEvent,
# with its isTrusted and bubbles attributes initialized to true, inputType attribute initialized to the mapped
# value of command, and its data attribute initialized to null.
let tree_was_modified = dom_document_dom_tree_version(this) != old_dom_tree_version or dom_document_character_data_version(this) != old_character_data_version
if tree_was_modified:
if let editing_host = affected_editing_host:
var event_init: UiEventsInputEventInit = ---
ui_events_input_event_init_init_fields(&event_init)
event_init.ui_event_init.event_init.bubbles = true
event_init.input_type = command_definition.mapped_value
# AD-HOC: For insertText, we do what other browsers do and set data to value.
if ak.fly_string_eq_string_view(&command, ak.sv("insertText")):
event_init.data = value
let event = (DomEvent*)ui_events_input_event_create_from_platform_event(dom_document_realm(this), html_event_names_input, event_init)
dom_event_set_is_trusted(event, true)
_ = dom_event_target_dispatch_event(editing_host.dom_event_target(), event)
# AD-HOC: Scroll the cursor into view after executing a command.
if let selection = dom_document_get_selection(this):
selection_selection_scroll_focus_into_view(selection)
# 8. Return true.
return true
# mark: queryCommand* ===========================================================================
## Ported from ExecCommand.cpp:144 Web::DOM::Document::query_command_enabled.
# https://w3c.github.io/editing/docs/execCommand/#querycommandenabled()
pub func dom_document_query_command_enabled(this: DomDocument*, command: ak.FlyString) -> bool!:
# AD-HOC: This is not directly mentioned in the spec, but all major browsers limit editing API calls to HTML documents
if not dom_document_is_html_document(this):
try exec_command_throw_invalid_state(this, "queryCommandEnabled is only supported on HTML documents")
# 2. Return true if command is both supported and enabled, false otherwise.
let supported = dom_document_query_command_supported(this, command) else trap("MUST: query_command_supported")
if not supported:
return false
# https://w3c.github.io/editing/docs/execCommand/#enabled
# Among commands defined in this specification, those listed in Miscellaneous commands are always enabled, except
# for the cut command and the paste command.
# NOTE: cut and paste are actually in the Clipboard commands section
if exec_command_is_one_of_ignoring_ascii_case(&command, exec_command_always_enabled_commands):
return true
# AD-HOC: selectAll requires a selection object to exist.
if ak.fly_string_equals_ignoring_ascii_case_string_view(&command, ak.sv("selectAll")):
return dom_document_get_selection(this) != none
# The other commands defined here are enabled if the active range is not null,
let active_range = editing_active_range(this) else return false
# its start node is either editable or an editing host,
let start_node = dom_abstract_range_start_container(active_range.dom_abstract_range())
if not dom_node_is_editable_or_editing_host(start_node):
return false
# FIXME: the editing host of its start node is not an EditContext editing host,
_ = dom_node_editing_host(start_node)
# its end node is either editable or an editing host,
let end_node = dom_abstract_range_end_container(active_range.dom_abstract_range())
if not dom_node_is_editable_or_editing_host(end_node):
return false
# FIXME: the editing host of its end node is not an EditContext editing host,
_ = dom_node_editing_host(end_node)
# and there is some editing host that is an inclusive ancestor of both its start node and its end node.
var inclusive_ancestor_editing_host: DomNode*? = none
var ancestor: DomNode*? = start_node
while let candidate = ancestor:
if dom_node_is_editing_host(candidate) and tree_node_is_inclusive_ancestor_of(candidate, end_node):
inclusive_ancestor_editing_host = candidate
break
ancestor = tree_node_parent(candidate)
let editing_host = inclusive_ancestor_editing_host else return false
# NOTE: Commands can define additional conditions for being enabled, and currently the only condition mentioned in
# the spec is that certain commands must not be enabled if the editing host is in the plaintext-only state.
if let html_element = as_if_html_element(editing_host.cell()):
if html_element_content_editable_state(html_element) == HtmlContentEditableState.plaintext_only and exec_command_is_one_of_ignoring_ascii_case(&command, exec_command_plaintext_only_disabled_commands):
return false
return true
## query_command_indeterm's callback for standard inline value commands: two formattable nodes with distinct
## effective command values.
struct ExecCommandDistinctValues:
var command: ak.FlyString
var first_node_value: ak.Utf16String?
var has_distinct_values: bool
static func call(context: void*?, descendant: DomNode*) -> TraversalDecision:
let state = (ExecCommandDistinctValues*)(context else trap("indeterm: no state"))
if not editing_is_formattable_node(descendant):
return TraversalDecision.continue_
let node_value = editing_effective_command_value(descendant, state.command) else return TraversalDecision.continue_
if let first = state.first_node_value:
if not ak.utf16_string_base_eq_utf16_string_base(&first.utf16_string_base, &node_value.utf16_string_base):
state.has_distinct_values = true
return TraversalDecision.break_
else:
state.first_node_value = node_value
return TraversalDecision.continue_
## query_command_indeterm's callback for inline command activated values: at least one match and one mismatch.
struct ExecCommandMatchAndMismatch:
var command: ak.FlyString
var inline_activated_values: const ak.Vector[ak.Utf16View]*
var has_at_least_one_match: bool
var has_at_least_one_mismatch: bool
static func call(context: void*?, descendant: DomNode*) -> TraversalDecision:
let state = (ExecCommandMatchAndMismatch*)(context else trap("indeterm: no state"))
if not editing_is_formattable_node(descendant):
return TraversalDecision.continue_
let node_value = editing_effective_command_value(descendant, state.command) else return TraversalDecision.continue_
if exec_command_inline_values_contain(state.inline_activated_values, &node_value):
state.has_at_least_one_match = true
else:
state.has_at_least_one_mismatch = true
if state.has_at_least_one_match and state.has_at_least_one_mismatch:
return TraversalDecision.break_
return TraversalDecision.continue_
## Ported from ExecCommand.cpp:239 Web::DOM::Document::query_command_indeterm.
# https://w3c.github.io/editing/docs/execCommand/#querycommandindeterm()
pub func dom_document_query_command_indeterm(this: DomDocument*, command: ak.FlyString) -> bool!:
# AD-HOC: This is not directly mentioned in the spec, but all major browsers limit editing API calls to HTML documents
if not dom_document_is_html_document(this):
try exec_command_throw_invalid_state(this, "queryCommandIndeterm is only supported on HTML documents")
# 1. If command is not supported or has no indeterminacy, return false.
let command_definition = editing_find_command_definition(command) else return false
if command_definition.indeterminate == none:
# https://w3c.github.io/editing/docs/execCommand/#inline-command-activated-values
# If a command is a standard inline value command, it is indeterminate if among formattable nodes that are
# effectively contained in the active range, there are two that have distinct effective command values.
if exec_command_is_one_of(&command_definition.command, exec_command_standard_inline_value_commands):
var state = ExecCommandDistinctValues(command = command_definition.command, first_node_value = none, has_distinct_values = false)
let range = editing_active_range(this)
editing_for_each_node_effectively_contained_in_range(range, ak.Function1[DomNode*, TraversalDecision](call = ExecCommandDistinctValues.call, context = &state))
return state.has_distinct_values
# If a command has inline command activated values defined but nothing else defines when it is indeterminate,
# it is indeterminate if among formattable nodes effectively contained in the active range, there is at least
# one whose effective command value is one of the given values and at least one whose effective command value
# is not one of the given values.
if not ak.vector_is_empty(&command_definition.inline_activated_values):
let range = editing_active_range(this)
var state = ExecCommandMatchAndMismatch(command = command_definition.command, inline_activated_values = &command_definition.inline_activated_values, has_at_least_one_match = false, has_at_least_one_mismatch = false)
editing_for_each_node_effectively_contained_in_range(range, ak.Function1[DomNode*, TraversalDecision](call = ExecCommandMatchAndMismatch.call, context = &state))
return state.has_at_least_one_match and state.has_at_least_one_mismatch
return false
# 2. Return true if command is indeterminate, otherwise false.
let indeterminate = command_definition.indeterminate else trap("unreachable: checked above")
return indeterminate(this)
## query_command_state's callback collecting the formattable nodes effectively contained in the active range.
func exec_command_collect_formattable_node(context: void*?, descendant: DomNode*) -> TraversalDecision:
let formattable_nodes = (ak.Vector[DomNode*]*)(context else trap("state: no list"))
if editing_is_formattable_node(descendant):
ak.vector_append_t(formattable_nodes, descendant)
return TraversalDecision.continue_
## Ported from ExecCommand.cpp:315 Web::DOM::Document::query_command_state.
# https://w3c.github.io/editing/docs/execCommand/#querycommandstate()
pub func dom_document_query_command_state(this: DomDocument*, command: ak.FlyString) -> bool!:
# AD-HOC: This is not directly mentioned in the spec, but all major browsers limit editing API calls to HTML documents
if not dom_document_is_html_document(this):
try exec_command_throw_invalid_state(this, "queryCommandState is only supported on HTML documents")
# 1. If command is not supported or has no state, return false.
let command_definition = editing_find_command_definition(command) else return false
let state_override = dom_document_command_state_override(this, command_definition.command)
if command_definition.state == none and state_override == none:
# https://w3c.github.io/editing/docs/execCommand/#inline-command-activated-values
# If a command has inline command activated values defined, its state is true if either no formattable node is
# effectively contained in the active range, and the active range's start node's effective command value is one
# of the given values;
let inline_values = &command_definition.inline_activated_values
if ak.vector_is_empty(inline_values):
return false
let range = editing_active_range(this) else return false
var formattable_nodes: ak.Vector[DomNode*]
editing_for_each_node_effectively_contained_in_range(range, ak.Function1[DomNode*, TraversalDecision](call = exec_command_collect_formattable_node, context = &formattable_nodes))
if ak.vector_is_empty(&formattable_nodes):
let start_value = exec_command_effective_value_or_empty(dom_abstract_range_start_container(range.dom_abstract_range()), command_definition.command)
return exec_command_inline_values_contain(inline_values, &start_value)
# or if there is at least one formattable node effectively contained in the active range, and all of them have
# an effective command value equal to one of the given values.
for node in ak.vector_span(&formattable_nodes):
let node_value = exec_command_effective_value_or_empty(node, command_definition.command)
if not exec_command_inline_values_contain(inline_values, &node_value):
return false
return true
# 2. If the state override for command is set, return it.
if let state_override_value = state_override:
return state_override_value
# 3. Return true if command's state is true, otherwise false.
let state = command_definition.state else trap("VERIFY: the command has a state")
return state(this)
## Ported from ExecCommand.cpp:364 Web::DOM::Document::query_command_supported.
# https://w3c.github.io/editing/docs/execCommand/#querycommandsupported()
pub func dom_document_query_command_supported(this: DomDocument*, command: ak.FlyString) -> bool!:
# AD-HOC: This is not directly mentioned in the spec, but all major browsers limit editing API calls to HTML documents
if not dom_document_is_html_document(this):
try exec_command_throw_invalid_state(this, "queryCommandSupported is only supported on HTML documents")
# When the queryCommandSupported(command) method on the Document interface is invoked, the user agent must return
# true if command is supported and available within the current script on the current site, and false otherwise.
# AD-HOC: Supported commands should have an action defined. Currently, ::preserveWhitespace does not have one.
let command_definition = editing_find_command_definition(command) else return false
return command_definition.action != none
## Ported from ExecCommand.cpp:378 Web::DOM::Document::query_command_value.
# https://w3c.github.io/editing/docs/execCommand/#querycommandvalue()
pub func dom_document_query_command_value(this: DomDocument*, command: ak.FlyString) -> ak.String!:
# AD-HOC: This is not directly mentioned in the spec, but all major browsers limit editing API calls to HTML documents
if not dom_document_is_html_document(this):
try exec_command_throw_invalid_state(this, "queryCommandValue is only supported on HTML documents")
# 1. If command is not supported or has no value, return the empty string.
let command_definition = editing_find_command_definition(command) else return ak.String()
let value_override = dom_document_command_value_override(this, command_definition.command)
if command_definition.value == none and value_override == none:
return ak.String()
# 2. If command is "fontSize" and its value override is set, convert the value override to an
# integer number of pixels and return the legacy font size for the result.
if ak.fly_string_eq_string_view(&command_definition.command, ak.sv("fontSize")):
if let override_value = value_override:
let override_view = ak.utf16_string_base_utf16_view(&override_value.utf16_string_base)
let pixel_size = editing_font_size_to_pixel_size(&override_view)
let legacy_size = editing_legacy_font_size(gfx.css_pixels_to_int_const(&pixel_size))
return ak.utf16_string_base_to_utf8_but_should_be_ported_to_utf16(&legacy_size.utf16_string_base)
# 3. If the value override for command is set, return it.
if let override_value = value_override:
return ak.utf16_string_base_to_utf8_but_should_be_ported_to_utf16(&override_value.utf16_string_base)
# 4. Return command's value.
let value = command_definition.value else trap("VERIFY: the command has a value")
let command_value = value(this)
return ak.utf16_string_base_to_utf8_but_should_be_ported_to_utf16(&command_value.utf16_string_base)
# mark: Value overrides =========================================================================
## Ported from ExecCommand.cpp:409 Web::DOM::Document::set_command_value_override.
# https://w3c.github.io/editing/docs/execCommand/#value-override
pub func dom_document_set_command_value_override(this: DomDocument*, command: ak.FlyString, value: ak.Utf16String):
_ = ak.hash_map_set(&this.m_command_value_override, command, value)
# The value override for the backColor command must be the same as the value override for the hiliteColor command,
# such that setting one sets the other to the same thing and unsetting one unsets the other.
if ak.fly_string_eq_string_view(&command, ak.sv("backColor")):
_ = ak.hash_map_set(&this.m_command_value_override, ak.fly_string_from_str("hiliteColor"), value)
elif ak.fly_string_eq_string_view(&command, ak.sv("hiliteColor")):
_ = ak.hash_map_set(&this.m_command_value_override, ak.fly_string_from_str("backColor"), value)
## Ported from ExecCommand.cpp:422 Web::DOM::Document::clear_command_value_override.
# https://w3c.github.io/editing/docs/execCommand/#value-override
pub func dom_document_clear_command_value_override(this: DomDocument*, command: ak.FlyString):
_ = ak.hash_map_remove_k(&this.m_command_value_override, command)
# The value override for the backColor command must be the same as the value override for the hiliteColor command,
# such that setting one sets the other to the same thing and unsetting one unsets the other.
if ak.fly_string_eq_string_view(&command, ak.sv("backColor")):
_ = ak.hash_map_remove_k(&this.m_command_value_override, ak.fly_string_from_str("hiliteColor"))
elif ak.fly_string_eq_string_view(&command, ak.sv("hiliteColor")):
_ = ak.hash_map_remove_k(&this.m_command_value_override, ak.fly_string_from_str("backColor"))