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.

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

Range.extractContents() and Range.surroundContents() describe behaviour incorrectly #35854

Open
TAPgiles opened this issue Sep 12, 2024 · 3 comments
Labels
Content:WebAPI Web API docs needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened.

Comments

@TAPgiles
Copy link

TAPgiles commented Sep 12, 2024

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/Range/extractContents

(Also https://developer.mozilla.org/en-US/docs/Web/API/Range/surroundContents)

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

Both pages describe:

moves content of the Range

This is not the behaviour as far as I can see in 126.0.6478.214 (Official Build) (64-bit), if a text node is the startContainer or endContainer or both. And is not the intended behaviour according to the spec:

To clone the contents of a live range range, run these steps...

(Unsure why that doesn't also apply to elements, but there you go.)

A range that is "partial" through text nodes (even if the offsets are at the beginning and end of the text nodes in question) will be cloned. They are not the original nodes. As such, they are not "moved." And that is the intended and correct behaviour. Therefore, the wording in the reference page is misleading at best or just wrong.

The closest I see to any explanation of this is in the extractContents() page:

Partially selected nodes are cloned to include the parent tags necessary to make the document fragment valid.

Which does not explain the definition of a "partially selected node" which is a misleading term anyway. In practise, the usage on the extractContents() page means "if a text node is the starting or ending boundary node." Whether or not all of that text node is included in the range.

And does not always have anything to do with parent tags. In fact, I've not been able to see any case in my testing where the parent tag is cloned. Maybe they are "included", but that term is not explained either and I cannot figure out what is meant by it.

What did you expect to see?

An accurate description of the behaviour, without unexplained terms, or with such terms properly explained:

The Range.extractContents() method moves all nodes within the Range from the document tree into a DocumentFragment. Where a text node is the starting or ending boundary of the Range, a clone of it is added to the fragment instead.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

@TAPgiles TAPgiles added the needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. label Sep 12, 2024
@github-actions github-actions bot added the Content:WebAPI Web API docs label Sep 12, 2024
@TAPgiles
Copy link
Author

With further testing, it seems maybe they are the original nodes? There's some weird stuff going on. In some situations they are clones (correct to spec) and in other situations they are the original nodes? Maybe?

@TAPgiles
Copy link
Author

After further testing, I've figured out the specific point that is incorrect in the explanation. The issue has been updated to reflect that now.

@TAPgiles TAPgiles reopened this Sep 12, 2024
@TAPgiles
Copy link
Author

In case it proved useful, attached is a simple file I used for testing this. Specifically the surroundContents() method.
range-surroundContents-test.zip

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:WebAPI Web API docs needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened.
Projects
None yet
Development

No branches or pull requests

1 participant