Skip to content

[cssom-view-1] Add FormControlRange geometry APIs (getClientRects/getBoundingClientRects) #12904

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

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

[cssom-view-1] Add FormControlRange geometry APIs (getClientRects/getBoundingClientRects) #12904

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d4a94e8
initial changes
stephanieyzhang Oct 6, 2025
09c8acb
updates
stephanieyzhang Oct 6, 2025
fd9d120
remove unnecessary sections and add links
stephanieyzhang Oct 16, 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
Prev Previous commit
remove unnecessary sections and add links
  • Loading branch information
@stephanieyzhang
stephanieyzhang committed Oct 16, 2025
commit fd9d120bda03c2e9d00aa0845a33964e98de5223
118 changes: 58 additions & 60 deletions cssom-view-1/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,10 @@ spec:css-borders-4; type:property; text:border-top-width
spec:css-borders-4; type:property; text:border-left-width
spec:cssom-view-1; type:dictionary; text:MouseEventInit
spec:cssom-view-1; type:dfn; for:MediaQueryList; text:media
spec:dom; type:interface; text:FormControlRange
spec:dom; type:method; for:FormControlRange; text:getClientRects()
spec:dom; type:method; for:FormControlRange; text:getBoundingClientRect()
spec:dom; type:dfn; for:FormControlRange; text:value string
</pre>

<style>
Expand Down Expand Up @@ -2006,10 +2010,6 @@ partial interface Range {
};
</pre>

<pre class='link-defaults'>
spec:dom; type:interface; text:FormControlRange
</pre>

The <dfn method for=Range>getClientRects()</dfn> method, when invoked, must return an empty
{{DOMRectList}} object if the range is not in the document and otherwise a {{DOMRectList}} object
containing a list of {{DOMRect}} objects in content order that matches the following constraints:
Expand Down Expand Up @@ -2048,74 +2048,72 @@ Note: The {{DOMRect}} object returned by {{Range/getBoundingClientRect()}} is no
range-bounding-client-rect-with-display-contents.html
</wpt>

<h2 id=formcontrolrange-geometry>FormControlRange geometry</h2>
<h2 id=extensions-to-the-formcontrolrange-interface> Extensions to the {{FormControlRange}}
Interface</h2>

<p>This section defines {{FormControlRange/getClientRects()}} and
{{FormControlRange/getBoundingClientRect()}} for {{FormControlRange}} (interface defined in [[DOM]]).
They mirror {{Range/getClientRects()}} and {{Range/getBoundingClientRect()}}, but operate on the
selected portion of a text control’s <em>value</em>.</p>
This section defines {{FormControlRange/getClientRects()}} and
{{FormControlRange/getBoundingClientRect()}} for {{FormControlRange}}. They mirror {{Range}}’s
{{Range/getClientRects()}} and {{Range/getBoundingClientRect()}}, but operate on the selected
portion of a text control’s {{FormControlRange/value string}}.

<p class=note>The IDL for these methods appears in [[DOM]]; it is not repeated here to avoid
duplication.</p>
The <dfn export for=FormControlRange>associated control</dfn> of a {{FormControlRange}} is the
<code>&lt;textarea></code> or text-supporting <code>&lt;input></code> whose {{FormControlRange/value
string}} the range indexes into.

<p>The <dfn>associated control</dfn> of a {{FormControlRange}} is the <code>&lt;textarea></code> or
text-supporting <code>&lt;input></code> whose editable <em>value</em> the range indexes into.</p>
<p class=note>For consistency with {{Range}}, {{FormControlRange/getClientRects()}} returns an empty
{{DOMRectList}} when the range is {{AbstractRange/collapsed}}.</p>

<p class=note>User agents typically represent the control’s value with a single internal text node.
If a future implementation were to use multiple nodes, this specification would need adjustment;
until then, algorithms assume a single backing text node.</p>
<div algorithm="getClientRects() for FormControlRange">

<p class=note>Unlike {{Range/getClientRects()}}, which historically returns an empty list for a
collapsed {{Range}}, this specification explicitly preserves that legacy behavior for
{{FormControlRange/getClientRects()}}: a collapsed {{FormControlRange}} also returns an empty
{{DOMRectList}}. Authors that need caret metrics should use
{{FormControlRange/getBoundingClientRect()}}.</p>
The steps for {{FormControlRange/getClientRects()}} are the same as {{Range}}’s
{{Range/getClientRects()}}, except that the rectangles are computed relative to the rendered text
within the control’s {{FormControlRange/value string}}.

<div algorithm>
<p>The <dfn method for=FormControlRange>getClientRects()</dfn> method, when invoked, must run these
steps:</p>
<ol>
<li><p>If the <a>associated control</a> is not <a>connected</a> or its computed <code>display</code>
is <code>none</code>, return an empty {{DOMRectList}}.</p></li>
<li><p>Update style and layout for the <a>associated control</a>.</p></li>
<li><p>Let <var>value length</var> be the current length of the <a>associated control</a>'s value.</p></li>
<li><p>Let <var>start</var> be min(this range’s start boundary point offset, <var>value length</var>)
and <var>end</var> be min(this range’s end boundary point offset, <var>value length</var>).</p></li>
<li><p>If <var>start</var> &gt; <var>end</var>, set <var>end</var> to <var>start</var>. <span class=note>This collapses backwards ranges per current implementations.</span></p></li>
<li><p>If <var>start</var> = <var>end</var>, return an empty {{DOMRectList}}.</p></li>
<li><p>Let <var>text</var> be the single text node that backs the control’s editable value. If none, return an empty {{DOMRectList}}.</p></li>
<li><p>Let <var>r</var> be a conceptual {{Range}} whose start is (<var>text</var>, <var>start</var>) and end is (<var>text</var>, <var>end</var>).</p></li>
<li><p>Return <var>r</var>.{{Range/getClientRects()}}.</p></li>
</ol>
<ol>
<li>If the <a>associated control</a> is not [=connected=] or its computed <code>display</code>
is <code>none</code>, return an empty {{DOMRectList}}.</li>

<li>Update style and layout for the <a>associated control</a>.</li>

<li>Let <var>value length</var> be the current length of the <a>associated control</a>’s
{{FormControlRange/value string}}.</li>

<li>Let <var>start</var> be min(<a>this</a>'s {{AbstractRange/startOffset}}, <var>value length</var>)
and let <var>end</var> be min(<a>this</a>'s {{AbstractRange/endOffset}}, <var>value length</var>).</li>

<li>If <var>start</var> = <var>end</var>, return an empty {{DOMRectList}}.</li>

<li>Let <var>text</var> be the single {{Text}} node that backs the control’s editable value. If
none, return an empty {{DOMRectList}}.</li>

<li>Let <var>r</var> be a {{Range}} whose start is (<var>text</var>, <var>start</var>) and whose
end is (<var>text</var>, <var>end</var>).</li>

<li>Return <var>r</var>.{{Range/getClientRects()}}.</li>
</ol>
</div>

<div algorithm>
<p>The <dfn method for=FormControlRange>getBoundingClientRect()</dfn> method, when invoked, must run
these steps:</p>
<ol>
<li><p>Let <var>rects</var> be the result of {{FormControlRange/getClientRects()}}.</p></li>
<li>
<p>If <var>rects</var> is empty:</p>
<div algorithm="getBoundingClientRect() for FormControlRange">

The steps for {{FormControlRange/getBoundingClientRect()}} are the same as {{Range}}’s
{{Range/getBoundingClientRect()}}, except that the bounding rectangle is computed relative to the
rendered text within the control’s {{FormControlRange/value string}} .

<ol>
<li><p>If this range is {{AbstractRange/collapsed}} and the <a>associated control</a> is visible
(its computed <code>display</code> is not <code>none</code>), return a zero-width [=scaled=]
{{DOMRect}} positioned at the caret (insertion point). Its block-size (height in horizontal
writing modes) is the line box block-size at that position, with any <a>transforms</a> that
apply to the control and its ancestors applied.</p></li>
<li><p>Otherwise, return a {{DOMRect}} whose {{DOMRect/x}}, {{DOMRect/y}}, {{DOMRect/width}}, and
{{DOMRect/height}} members are zero.</p></li>
<li>Let <var>rects</var> be the result of {{FormControlRange/getClientRects()}}.</li>

<li>If <var>rects</var> is empty, return a {{DOMRect}} whose {{DOMRect/x}}, {{DOMRect/y}},
{{DOMRect/width}}, and {{DOMRect/height}} members are zero.</li>

<li>Otherwise, return a {{DOMRect}} describing the smallest rectangle that includes every
rectangle in <var>rects</var>, as for {{Range}}’s {{Range/getBoundingClientRect()}}.</li>
</ol>
</li>
<li><p>Otherwise, return a {{DOMRect}} describing the smallest rectangle that includes every
rectangle in <var>rects</var> whose width or height is not zero, as for
{{Range/getBoundingClientRect()}}.</p></li>
</ol>
</div>

<p class=note>If implementations later expose a caret rectangle via
{{FormControlRange/getClientRects()}} for collapsed ranges, this section will be updated. Authors
SHOULD NOT rely on observing an empty list vs. a zero-width caret rectangle to detect collapse;
use {{AbstractRange/collapsed}}.</p>
<!-- WPT test names will be updated once they have been merged in. -->
<wpt>
FormControlRange-geometry.html
</wpt>

<h2 id=extensions-to-the-mouseevent-interface>Extensions to the {{MouseEvent}} Interface</h2>

Expand Down