Skip to content

Add definition for composed selection range #1342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: main
Choose a base branch
from
Open

Add definition for composed selection range #1342

Changes from 7 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
7c48fa5
Add definition for composed live range
dizhang168 Dec 17, 2024
487cac0
Review, format changes
dizhang168 Jan 21, 2025
461aed7
Fix collapse logic for set the start or end
dizhang168 Jan 23, 2025
413348d
Fix for= typo
dizhang168 Jan 24, 2025
c7f38b1
Linking nit
domfarolino Jan 28, 2025
1f74a51
Remove em dash to fix spacing in rendered spec
domfarolino Jan 28, 2025
f5b6935
Review changes: rename composed live range, improve format of set the…
dizhang168 Jan 28, 2025
367288b
define composed selection range separately from live range
dizhang168 Feb 25, 2025
fe020ca
Update composed selection range definition
dizhang168 Feb 27, 2025
4760e78
Change to compare with shadow-including root instead of document node
dizhang168 Mar 5, 2025
d8ca5a5
legacy uncomposed range + format
dizhang168 Mar 13, 2025
99b212b
Merge remote-tracking branch 'upstream/main' into composed-live-range
dizhang168 Mar 21, 2025
700ca5e
Add composed position definition, rewrite set the start/end
dizhang168 Mar 24, 2025
1cf2b12
fix typo
dizhang168 Mar 24, 2025
59d9595
Name is composed range + improve spec language
dizhang168 Mar 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 72 additions & 23 deletions dom.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3034,6 +3034,14 @@ optional <i>suppress observers flag</i>, run these steps:
<li><p>For each <a>live range</a> whose <a for=range>end node</a> is an <a>inclusive descendant</a>
of <var>node</var>, set its <a for=range>end</a> to (<var>parent</var>, <var>index</var>).

<li><p>For each <a>composed selection range</a> whose <a for=range>start node</a> is a
<a>shadow-including inclusive descendant</a> of <var>node</var>, set its <a for=range>start</a> to
(<var>parent</var>, <var>index</var>).

<li><p>For each <a>composed selection range</a> whose <a for=range>end node</a> is a
<a>shadow-including inclusive descendant</a> of <var>node</var>, set its <a for=range>end</a> to
(<var>parent</var>, <var>index</var>).

<li><p>For each <a>live range</a> whose <a for=range>start node</a> is <var>parent</var> and
<a for=range>start offset</a> is greater than <var>index</var>, decrease its
<a for=range>start offset</a> by 1.
Expand Down Expand Up @@ -5775,7 +5783,7 @@ are:
<hr>

<p>The <dfn method for=Document><code>createRange()</code></dfn> method steps are to return a new
<a>live range</a> with (<a>this</a>, 0) as its <a for=range>start</a> an <a for=range>end</a>.
{{Range}} object with (<a>this</a>, 0) as its <a for=range>start</a> and <a for=range>end</a>.

<p class=note>The {{Range/Range()}} constructor can be used instead.

Expand Down Expand Up @@ -8141,12 +8149,21 @@ interface Range : AbstractRange {
};
</pre>

<p>Objects implementing the {{Range}} interface are known as
<dfn export id=concept-live-range>live ranges</dfn>.
<p>A <dfn export id=concept-live-range>live range</dfn> is a <a>range</a> that is affected by
mutations to the <a>node tree</a>.</p>

<p>Objects implementing the {{Range}} interface are <a>live ranges</a>.

<p class=note>Algorithms that modify a <a>tree</a> (in particular the <a for=/>insert</a>,
<a for=/>remove</a>, <a>replace data</a>, and <a lt="split a Text node">split</a> algorithms) modify
<a>live ranges</a> associated with that <a>tree</a>.
<a>live ranges</a> associated with that <a>tree</a>.</p>

<p>A <dfn export id=concept-composed-selection-range>composed selection range</dfn> is a
<a>live range</a> that has an associated {{Range}} object, a
<dfn export id=concept-legacy-selection-range for="composed selection range">legacy selection range</dfn>.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit, I don't like calling the normal Range as legacy. Nothing really legacy there.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not the Range object that's legacy, it's having to keep around a pretend range for the purposes of the selection API as it was designed pre-shadow-trees that's kinda legacy.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but I don't still like it. It is not legacy, in the sense that there would be some better thing to replace it or so (in case of light dom). "Legacy" doesn't explain what the range is for.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would you propose?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe the legacy selection range could be same-tree selection range, and composed selection range could be composed-tree selection range?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same-tree selection range sounds kinda nice. I personally think "composed selection range" is fine as-is.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Listing the naming options:

  1. "composed live range" and "cached live range"
  2. "composed selection range" and "legacy selection range"
  3. "composed-tree selection range" and "same-tree selection range"
  4. "composed selection range" and "same-tree selection range"
  5. "composed selection range" and "selection range"

All these names seem ok to me, I will let the majority decide.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on an email conversation I'm a bit less sure what the semantics of this range are. Say you have an element with a shadow root that contains the word "Test". The end user selects "es". getSelection() should not provide access to this shadow root, but apparently the set of changes proposed here do not enforce that. Or am I misunderstanding something?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created 2 issues to track the above conversation:
#1363 for the naming choices
#1362 for getSelection() still giving access to the shadow root
Lets discuss these topics at the upcoming Editing WG or WHATNOT meeting.


<p class=note>The <a for="composed selection range">legacy selection range</a> is used to maintain
backward compatibility with the {{Selection/getRangeAt()}} API.</p>

<p>The <dfn export id=concept-range-root for="live range">root</dfn> of a <a>live range</a> is the
<a for=tree>root</a> of its <a for=range>start node</a>.
Expand Down Expand Up @@ -8216,7 +8233,7 @@ but not its <a for=range>end node</a>, or vice versa.

<dl class=domintro>
<dt><code><var>range</var> = new <a constructor>Range()</a></code>
<dd>Returns a new <a>live range</a>.
<dd>Returns a new {{Range}} object.
</dl>

<p>The <dfn constructor for=Range lt="Range()"><code>new Range()</code></dfn> constructor steps are
Expand Down Expand Up @@ -8265,6 +8282,12 @@ steps:
<a>boundary point</a>
(<var>node</var>, <var>offset</var>).

<li>If <var>range</var> is the <a for="composed selection range">legacy selection range</a> of a
<a>composed selection range</a>, set <var>selection range</var> to that
<a>composed selection range</a>.

<li>Otherwise, set <var>selection range</var> to null.

<li>
<dl class=switch>
<dt>If these steps were invoked as "set the start"
Expand All @@ -8273,29 +8296,55 @@ steps:
<li>If <var>range</var>'s
<a for="live range">root</a> is not equal to
<var>node</var>'s <a for=tree>root</a>,
or if <var>bp</var> is
<a for="boundary point">after</a> the
<var>range</var>'s <a for=range>end</a>, set
<var>range</var>'s <a for=range>end</a>
set <var>range</var>'s <a for=range>end</a>
to <var>bp</var>.

<li>Otherwise, if <var>bp</var> is
<a for="boundary point">after</a> the
<var>range</var>'s <a for=range>end</a>, then:
<ol>
<li>Set <var>range</var>'s <a for=range>end</a>
to <var>bp</var>.

<li>If <var>selection range</var> is not null,
set <var>selection range</var>’s
<a for="range">end</a> to <var>bp</var>.
</ol>

<li>Set <var>range</var>'s
<a for=range>start</a> to <var>bp</var>.

<li>If <var>selection range</var> is not null,
set <var>selection range</var>’s
<a for="range">start</a> to <var>bp</var>.
</ol>
<dt>If these steps were invoked as "set the end"
<dd>
<ol>
<li>If <var>range</var>'s
<a for="live range">root</a> is not equal to
<var>node</var>'s <a for=tree>root</a>,
or if <var>bp</var> is
<a for="boundary point">before</a> the
<var>range</var>'s <a for=range>start</a>, set
<var>range</var>'s <a for=range>start</a>
set <var>range</var>'s <a for=range>start</a>
to <var>bp</var>.

<li>Otherwise, if <var>bp</var> is
<a for="boundary point">before</a> the
<var>range</var>'s <a for=range>start</a>, then:
<ol>
<li>Set <var>range</var>'s <a for=range>start</a>
to <var>bp</var>.

<li>If <var>selection range</var> is not null,
set <var>selection range</var>’s
<a for="range">start</a> to <var>bp</var>.
</ol>

<li>Set <var>range</var>'s
<a for=range>end</a> to <var>bp</var>.

<li>If <var>selection range</var> is not null,
set <var>selection range</var>’s
<a for="range">end</a> to <var>bp</var>.
</ol>
</dl>
</ol>
Expand Down Expand Up @@ -8576,7 +8625,7 @@ method steps are:
(<var>new node</var>, <var>new offset</var>).
</ol>

<p>To <dfn export id=concept-range-extract for="live range">extract</dfn> a <a>live range</a>
<p>To <dfn export id=concept-range-extract for="live range">extract</dfn> a {{Range}} object
<var>range</var>, run these steps:

<ol>
Expand Down Expand Up @@ -8753,8 +8802,7 @@ method steps are:
<li><a>Append</a> <var>clone</var>
to <var>fragment</var>.

<li>Let <var>subrange</var> be a new <a>live range</a>
whose <a for=range>start</a> is
<li>Let <var>subrange</var> be a new {{Range}} object whose <a for=range>start</a> is
(<var>original start node</var>, <var>original start offset</var>) and
whose <a for=range>end</a> is
(<var>first partially contained child</var>, <var>first partially contained child</var>'s
Expand Down Expand Up @@ -8807,8 +8855,7 @@ method steps are:
<li><a>Append</a> <var>clone</var>
to <var>fragment</var>.

<li>Let <var>subrange</var> be a new <a>live range</a>
whose <a for=range>start</a> is
<li>Let <var>subrange</var> be a new {{Range}} object whose <a for=range>start</a> is
(<var>last partially contained child</var>, 0) and whose
<a for=range>end</a> is
(<var>original end node</var>, <var>original end offset</var>).
Expand All @@ -8832,7 +8879,7 @@ result of <a for="live range">extracting</a> <a>this</a>.

<p>To
<dfn export id=concept-range-clone for="live range" lt="clone the contents|cloning the contents">clone the contents</dfn>
of a <a>live range</a> <var>range</var>, run these steps:
of a {{Range}} object <var>range</var>, run these steps:

<ol>
<li><p>Let <var>fragment</var> be a new {{DocumentFragment}} <a for=/>node</a> whose
Expand Down Expand Up @@ -8960,7 +9007,7 @@ of a <a>live range</a> <var>range</var>, run these steps:
<li><a>Append</a> <var>clone</var>
to <var>fragment</var>.

<li>Let <var>subrange</var> be a new <a>live range</a>
<li>Let <var>subrange</var> be a new {{Range}} object
whose <a for=range>start</a> is
(<var>original start node</var>, <var>original start offset</var>) and
whose <a for=range>end</a> is
Expand Down Expand Up @@ -9018,7 +9065,7 @@ of a <a>live range</a> <var>range</var>, run these steps:
<li><a>Append</a> <var>clone</var>
to <var>fragment</var>.

<li>Let <var>subrange</var> be a new <a>live range</a>
<li>Let <var>subrange</var> be a new {{Range}} object
whose <a for=range>start</a> is
(<var>last partially contained child</var>, 0) and whose
<a for=range>end</a> is
Expand All @@ -9038,7 +9085,7 @@ of a <a>live range</a> <var>range</var>, run these steps:
result of <a for="live range">cloning the contents</a> of <a>this</a>.

<p>To <dfn export id=concept-range-insert for="live range">insert</dfn> a <a for=/>node</a>
<var>node</var> into a <a>live range</a> <var>range</var>, run these steps:
<var>node</var> into a {{Range}} object <var>range</var>, run these steps:

<ol>
<li>If <var>range</var>'s <a for=range>start node</a> is a {{ProcessingInstruction}} or {{Comment}}
Expand Down Expand Up @@ -9188,7 +9235,8 @@ check first thing, which matches everyone but Firefox.
</ol>

<p>The <dfn method for=Range><code>cloneRange()</code></dfn> method steps are to return a new
<a>live range</a> with the same <a for=range>start</a> and <a for=range>end</a> as <a>this</a>.
{{Range}} object with the same <a for=range>start</a> and <a for=range>end</a> as
<a>this</a>.

<p>The <dfn method for=Range><code>detach()</code></dfn> method steps are to do nothing.
<span class=note>Its functionality (disabling a {{Range}} object) was removed, but the method itself
Expand Down Expand Up @@ -10441,6 +10489,7 @@ David Håsäther,
David Hyatt,
Deepak Sherveghar,
Dethe Elza,
Di Zhang,
Dimitri Glazkov,
Domenic Denicola,
Dominic Cooney,
Expand Down