Skip to content
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

Upstream the innerText spec #1678

Merged
merged 10 commits into from
Aug 17, 2016
Merged

Upstream the innerText spec #1678

Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
1aba602
Upstream the innerText spec
zcorpan Aug 16, 2016
0783a61
Define the innerText setter better
zcorpan Aug 17, 2016
0db3154
Fix typo/logic error
zcorpan Aug 17, 2016
618de84
Add [TreatNullAs=EmptyString] to innerText
zcorpan Aug 17, 2016
d0bc7d5
Fix typos @annevk found
zcorpan Aug 17, 2016
45253f9
Define innerText setter for non-CSS UAs
zcorpan Aug 17, 2016
c2f3d8f
Address @annevk's comments
zcorpan Aug 17, 2016
653254c
Make 'required line break count' less confusing
zcorpan Aug 17, 2016
a1d419f
Re-add 'an then concatenating the results' and be more consistent
zcorpan Aug 17, 2016
16a8f1b
Address @domenic's comments
zcorpan Aug 17, 2016
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
195 changes: 193 additions & 2 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3160,7 +3160,7 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document">in a document</dfn> (legacy), and <dfn data-x-href="https://dom.spec.whatwg.org/#connected">connected</dfn> concepts</li>
<li>The <dfn data-noexport="" data-x="concept-slot" data-x-href="https://dom.spec.whatwg.org/#concept-slot">slot</dfn> concept, and its <dfn data-noexport="" data-x="slot-name" data-x-href="https://dom.spec.whatwg.org/#slot-name">name</dfn> and <dfn data-noexport="" data-x-href="https://dom.spec.whatwg.org/#slot-assigned-nodes">assigned nodes</dfn></li>
<li>The <dfn data-noexport="" data-x="finding flattened slotables" data-x-href="https://dom.spec.whatwg.org/#find-flattened-slotables">find flattened slotables</dfn> algorithm</li>
<li>The <dfn data-noexport="" data-x-href="https://dom.spec.whatwg.org/#concept-node-pre-insert">pre-insert</dfn>, <dfn data-noexport="" data-x="concept-node-insert" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert">insert</dfn>, <dfn data-noexport="" data-x="concept-node-append" data-x-href="https://dom.spec.whatwg.org/#concept-node-append">append</dfn>, <dfn data-noexport="" data-x="concept-node-replace" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace">replace</dfn>, <dfn data-noexport="" data-x="concept-node-remove" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove">remove</dfn>, and <dfn data-noexport="" data-x="concept-node-adopt" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt">adopt</dfn> algorithms for nodes</li>
<li>The <dfn data-noexport="" data-x-href="https://dom.spec.whatwg.org/#concept-node-pre-insert">pre-insert</dfn>, <dfn data-noexport="" data-x="concept-node-insert" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert">insert</dfn>, <dfn data-noexport="" data-x="concept-node-append" data-x-href="https://dom.spec.whatwg.org/#concept-node-append">append</dfn>, <dfn data-noexport="" data-x="concept-node-replace" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace">replace</dfn>, <dfn data-noexport="" data-x="concept-node-replace-all" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace-all">replace all</dfn>, <dfn data-noexport="" data-x="concept-node-remove" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove">remove</dfn>, and <dfn data-noexport="" data-x="concept-node-adopt" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt">adopt</dfn> algorithms for nodes</li>
<li>The <dfn data-noexport="" data-x="concept-element-attributes-change" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-change">change</dfn>, <dfn data-noexport="" data-x="concept-element-attributes-append" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-append">append</dfn>, <dfn data-noexport="" data-x="concept-element-attributes-remove" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-remove">remove</dfn>, <dfn data-noexport="" data-x="concept-element-attributes-replace" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-replace">replace</dfn>, and <dfn data-noexport="" data-x="concept-element-attributes-set-value" data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-set-value">set value</dfn> algorithms for attributes</li>
<li>The <dfn data-noexport="" data-x="concept-node-insert-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert-ext">insertion steps</dfn>,
<dfn data-noexport="" data-x="concept-node-remove-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove-ext">removing steps</dfn>,
Expand Down Expand Up @@ -3450,6 +3450,7 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css2/visudet.html#propdef-vertical-align">'vertical-align'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css2/generate.html#content">'content'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css2/visuren.html#value-def-inline-block">'inline-block'</dfn> value of the <span>'display'</span> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css2/visufx.html#propdef-visibility">'visibility'</dfn> property</li>
</ul>

<p>The CSS specification also defines the following border properties: <ref spec=CSS></p>
Expand Down Expand Up @@ -3544,6 +3545,10 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-backgrounds/#position">&lt;position></dfn> CSS data type</li>
</ul>

<p>The term <dfn data-noexport=""
data-x-href="https://drafts.csswg.org/css-display/#block-level">block-level</dfn> is defined in
the <cite>CSS Display</cite> specification. <ref spec=CSSDISPLAY></p>

<p>The following features are defined in the <cite>CSS Fonts</cite> specification: <ref
spec=CSSFONTS></p>

Expand Down Expand Up @@ -3581,13 +3586,18 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
<ul class="brief">
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#propdef-border-spacing">'border-spacing'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#border-collapse-property">'border-collapse'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#table-cell">'table-cell'</dfn> value of the <span>'display'</span> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#table-cell">'table-cell'</dfn>,
<dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#table-row">'table-row'</dfn>,
<dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#table-caption">'table-caption'</dfn>, and
<dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-tables/#table">'table'</dfn>
values of the <span>'display'</span> property</li>
</ul>

<p>The following features are defined in the <cite>CSS Text</cite> specification:
<ref spec=CSSTEXT></p>

<ul class="brief">
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-text/#text-transform-property">'text-transform'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-text/#white-space-property">'white-space'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-text/#text-align-property">'text-align'</dfn> property</li>
<li>The <dfn data-noexport="" data-x-href="https://drafts.csswg.org/css-text/#letter-spacing-property">'letter-spacing'</dfn> property</li>
Expand Down Expand Up @@ -9651,6 +9661,8 @@ interface <dfn>HTMLElement</dfn> : <span>Element</span> {
[<span>CEReactions</span>] attribute <span>HTMLMenuElement</span>? <span data-x="dom-contextMenu">contextMenu</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-spellcheck">spellcheck</span>;
void <span data-x="dom-forceSpellCheck">forceSpellCheck</span>();

[<span>CEReactions</span>, TreatNullAs=EmptyString] attribute DOMString <span data-x="dom-innerText">innerText</span>;
};
<span>HTMLElement</span> implements <span>GlobalEventHandlers</span>;
<span>HTMLElement</span> implements <span>DocumentAndElementEventHandlers</span>;
Expand Down Expand Up @@ -11962,6 +11974,175 @@ interface <dfn>DOMStringMap</dfn> {
</div>


<h4>The <code data-x="dom-innerText">innerText</code> IDL attribute</h4>
Copy link
Member

Choose a reason for hiding this comment

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

I wonder if a better title might be something like Manipulating an element's "as rendered" text? It seems to me like other section titles usually don't talk about a specific IDL attribute. I don't feel strongly though.

Copy link
Member Author

Choose a reason for hiding this comment

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

It's a bit of a mix currently. Having "innerText" in the heading makes it easier to find. But if we also add outerText we can maybe change the heading at that point.


<dl class="domintro">

<dt><var>element</var> . <code subdfn data-x="dom-innerText">innerText</code> [ = <var>value</var> ]</dt>

<dd>

<p>Returns the element's text content "as rendered".</p>

<p>Can be set, to replace the element's children with the given value, but with line breaks
Copy link
Member

Choose a reason for hiding this comment

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

line breaks

converted to <code>br</code> elements.</p>

</dl>
Copy link
Member

Choose a reason for hiding this comment

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

Should we add a warning about how developers usually want to use textContent instead?

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't know, it's not clear to me that is usually true. For getting, innerText seems a lot more useful if you want the text but not the contents of scripts and don't want formatting of the HTML source to affect the given text. For setting, you would have to use <pre> but you might want spaces to collapse or don't want monospace font, or you could use <p> with white-space: pre-line (or so) but then you rely on CSS to preserve presumably important line breaks.

textContent is gives more consistent results cross-browser, though.


<div w-nodev>

<p>On getting, the <dfn><code data-x="dom-innerText">innerText</code></dfn> attribute must follow
these steps:</p>

<ol>
<li><p>If this element is not <span>being rendered</span>, or if the user agent is a non-CSS user
Copy link
Member

Choose a reason for hiding this comment

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

@domenic and I started using "this element" (or equivalent) in other algorithms. I think that would be a clearer way to refer to the object on which the IDL attribute is defined.

agent, then return the same value as the <code>textContent</code> IDL attribute on this
element.</p></li>

<li>
<p>Compute a list of items each of which is a string or a positive integer (a <i>required line
break count</i>), by applying the following recursive procedure to each child node
Copy link
Member

Choose a reason for hiding this comment

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

Make this end in parenthesis?

Copy link
Member Author

Choose a reason for hiding this comment

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

Hmm I suppose " and concatenating the results" should be removed here.

Copy link
Member Author

Choose a reason for hiding this comment

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

Hmm, no this should still be there. Each child produces a list, and we want to concatenate those lists into one...

<var>node</var> of this element in <span>tree order</span>, and then concatenating the results
to a single list of items.</p>

Copy link
Member

Choose a reason for hiding this comment

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

This looks like a note, mark it up as such and avoid normative requirements?

<p class="note">Intuitively, a <i>required line break count</i> item means that a certain number
of line breaks appear at that point, but they can be collapsed with the line breaks induced by
adjacent integer items, reminiscient to CSS margin-collapsing.</p>
Copy link
Member

Choose a reason for hiding this comment

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

s/integer items/required line break count items?

Spelling is "reminiscent"


<ol>
<li><p>Let <var>items</var> be the result of recursively applying this procedure to each child
of <var>node</var> in <span>tree order</span>, and then concatenating the results to a single
Copy link
Member

Choose a reason for hiding this comment

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

then return*

list of items.</p></li>

<li><p>If <var>node</var>'s <span>computed value</span> of <span>'visibility'</span> is not
Copy link
Member

Choose a reason for hiding this comment

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

then return*

Copy link
Member

Choose a reason for hiding this comment

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

This happens a few more times.

'visible', then return <var>items</var>.</p></li>
Copy link
Member

Choose a reason for hiding this comment

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

I guess this is the same concern as the factoring thing @annevk mentioned, but saying "return" inside a getter and that not being the result of the getter is pretty confusing. "Let the result of these substeps be items and abort these substeps"? Meh...

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah... I went with your suggestion for now but it's not great.


<li>
<p>If <var>node</var> is a <code>Text</code> node child of an <code>rp</code> element, then
return a single string item containing the text of <var>node</var>.
Copy link
Member

Choose a reason for hiding this comment

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

"text" should be https://dom.spec.whatwg.org/#concept-cd-data


<p class="note">The <code>rp</code> element is normally 'display:none' but we want to include
its text.</p>
</li>

<li>
<p>If <var>node</var> has no associated CSS box, then return <var>items</var>.</p>

<p class="note"><var>items</var> can be non-empty due to 'display:contents'.</p>
</li>

<li><p>If <var>node</var> is a <code>Text</code> node, then for each CSS text box produced by
<var>node</var>, in content order, compute the text of the box after application of the CSS
<span>'white-space'</span> processing rules and <span>'text-transform'</span> rules, and return
a list of the resulting strings. The CSS <span>'white-space'</span> processing rules are
slightly modified: collapsible spaces at the end of lines are always collapsed, but they are
Copy link
Member

Choose a reason for hiding this comment

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

then append

only removed if the line is the last line of the block, or it ends with a <code>br</code>
element. Soft hyphens should be preserved. <ref spec=CSSTEXT></p></li>

<li><p>If <var>node</var> is a <code>br</code> element, then append a string containing a
single U+000A LINE FEED (LF) character to <var>items</var>.

<li><p>If <var>node</var>'s <span>computed value</span> of <span>'display'</span> is
<span>'table-cell'</span>, and <var>node</var>'s CSS box is not the last
<span>'table-cell'</span> box of its enclosing 'table-row' box, then append a string containing
Copy link
Member

Choose a reason for hiding this comment

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

<span> around 'table-row'?

a single U+0009 CHARACTER TABULATION (tab) character to <var>items</var>.</p></li>

<li><p>If <var>node</var>'s <span>computed value</span> of <span>'display'</span> is
<span>'table-row'</span>, and <var>node</var>'s CSS box is not the last
<span>'table-row'</span> box of the nearest ancestor <span>'table'</span> box, then append a
string containing a single U+000A LINE FEED (LF) character to <var>items</var>.</p></li>

<li><p>If <var>node</var> is a <code>p</code> element, then add 2 (a <i>required line break
count</i>) at the beginning and end of <var>items</var>.</p></li>

<li>
<p>If <var>node</var>'s <span>used value</span> of <span>'display'</span> is
<span>block-level</span> or <span>'table-caption'</span>, then add 1 (a <i>required line break
count</i>) at the beginning and end of <var>items</var>. <ref spec=CSSDISPLAY></p>

<p class="note">Floats and absolutely-positioned elements fall into this category.</p>
</li>

<li><p>Return <var>items</var>.</p></li>
</ol>
</li>

Copy link
Member

Choose a reason for hiding this comment

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

This should presumably do some starts with matching? We only add "required line break count of ..." after all.

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't follow.

Copy link
Member

Choose a reason for hiding this comment

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

The string being added is "required line break count of 2" / "required line break count of 1", not this string.

Copy link
Member Author

Choose a reason for hiding this comment

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

Ah, I see. Those items are not strings. They are integers, basically. I suppose it could be made less confusing...

<li><p>Delete any string items whose strings are empty.</p></li>

<li><p>Delete any runs of consecutive <i>required line break count</i> items at the start or end
of the list.</p></li>

<li><p>Replace each remaining run of consecutive <i>required line break count</i> items with a
string consisting of as many U+000A LINE FEED (LF) characters as the maximum of the values in the
<i>required line break count</i> items.</p></li>

Copy link
Member

Choose a reason for hiding this comment

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

comma after e.g.

<li><p>Return the concatenation of the string items.</p></li>
</ol>

<p class="note">Note that descendant nodes of most replaced elements (e.g., <code>textarea</code>,
Copy link
Member

Choose a reason for hiding this comment

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

"a ranges" -> "a range" | "ranges"

<code>select</code>, and <code>video</code> &mdash; but not <code>button</code>) are not rendered
by CSS, strictly speaking, and therefore have no CSS boxes for the purposes of this algorithm.</p>

<p class="big-issue">This algorithm is amenable to being generalized to work on <span
data-x="concept-range">ranges</span>. Then we can use it as the basis for <code>Selection</code>'s
stringifier and maybe expose it directly on <span data-x="concept-range">ranges</span>. See <a
href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=10583">Bugzilla bug 10583</a>.</p>

<p>On setting, the <code data-x="dom-innerText">innerText</code> attribute must follow these
Copy link
Member

Choose a reason for hiding this comment

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

this element's

steps:</p>

<ol>
<li><p>Let <var>document</var> be this element's <span>node document</span>.</p></li>

Copy link
Member

Choose a reason for hiding this comment

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

"the new value being assigned" -> "the given value"

<li><p>Let <var>fragment</var> be a new <code>DocumentFragment</code> object whose <span>node
document</span> is <var>document</var>.</p></li>

<li><p>Let <var>input</var> be the given value.</p></li>

<li><p>Let <var>pointer</var> be a pointer into <var>input</var>, initially pointing at the start
of the string.</p></li>

<li><p>Let <var>text</var> be the empty string.</p></li>

<li>
<p>While <var>pointer</var> is not past the end of <var>input</var>:</p>

<ol>
<li><p><span>Collect a sequence of characters</span> that are not U+000A LINE FEED (LF) or
U+000D CARRIAGE RETURN (CR) characters. Set <var>text</var> to the collected
characters.</p></li>

<li><p>If <var>text</var> is not the empty string, then <span
data-x="concept-node-append">append</span> a new <code>Text</code> node whose <span
data-x="concept-cd-data">data</span> is <var>text</var> and <span>node document</span> is
<var>document</var>, to <var>fragment</var>.</p></li>

<li>
<p>While <var>pointer</var> is not past the end of <var>input</var>, and the character at
<var>position</var> is either a U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)
character:</p>

<ol>
<li><p>If the character at <var>position</var> is a U+000D CARRIAGE RETURN (CR) character and
the next character is a U+000A LINE FEED (LF) character, then advance <var>position</var> to
the next character in <var>input</var>.</p></li>

<li><p>Advance <var>position</var> to the next character in <var>input</var>.</p></li>

<li><p><span data-x="concept-node-append">Append</span> the result of <span
data-x="create an element">creating an element</span> given <var>document</var>,
<code>br</code>, and the <span>HTML namespace</span>, to <var>fragment</var>.</p></li>
Copy link
Member

Choose a reason for hiding this comment

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

No comma after HTML namespace, I think

</ol>
</li>
</ol>
</li>

<li><p><span data-x="concept-node-replace-all">Replace all</span> with <var>fragment</var> within
this element.</p></li>
</ol>

</div>

<h4>Requirements relating to the bidirectional algorithm</h4>

<div w-nodev>
Expand Down Expand Up @@ -118617,6 +118798,9 @@ INSERT INTERFACES HERE
<dt id="refsCSSCOLOR">[CSSCOLOR]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-color/">CSS Color Module Level 3</a></cite>, T. &Ccedil;elik, C. Lilley, L. Baron. W3C.</dd>

<dt id="refsCSSDISPLAY">[CSSDISPLAY]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-font-loading/">CSS Display</a></cite>, T. Atkins, E. Etemad. W3C.</dd>

<dt id="refsCSSFONTLOAD">[CSSFONTLOAD]</dt>
<dd><cite><a href="https://drafts.csswg.org/css-font-loading/">CSS Font Loading</a></cite>, T. Atkins, J. Daggett. W3C.</dd>

Expand Down Expand Up @@ -119949,6 +120133,13 @@ INSERT INTERFACES HERE
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Permissive
Document License</a>.</p>

<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <code
data-x="dom-innerText">innerText</code> IDL attribute can be found in the <a
href="https://github.com/rocallahan/innerText-spec"><code>rocallahan/innerText-spec</code>
repository</a>, which is available under the <a itemprop="license"
href="https://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0
License</a>.</p>

<p>For about ten years starting in 2003, this specification was almost entirely written by Ian
Hickson (Google, ian@hixie.ch). More recently, Simon Pieters (Opera, simonp@opera.com), Anne van
Kesteren (Mozilla, annevk@annevk.nl), Philip J&auml;genstedt (Google, philip@foolip.org), and
Expand Down