Intent to Prototype: document.fragmentDirective API

[David Bokan]

(Note - this is an extension to the already shipped "scroll-to-text"/text directive feature)

Contact emails

bo...@chromium.org, blink-inter...@google.com

Explainer

https://github.com/WICG/scroll-to-text-fragment/blob/main/fragment-directive-api.md

Specification

TODO: None yet

Summary

We propose exposing JavaScript APIs for working programmatically with text directives (a.k.a. Scroll-to-text highlights)

The new API enables authors to better work with text directives when they are used to navigate to their page:

• Exposes the previously unavailable text directive (everything in the URL fragment after “:~:”) in the URL to page authors via a structured API

• Exposes the DOM Range being highlighting

• Allows programmatically adding and removing text directive highlights

It also enables authors to create deep link navigations:

• Allows the browser to generate a text directive URL from an arbitrary DOM Range, making it easier for authors to create deep links to their own content.

Blink component

Blink>Scroll

Motivation

We’ve seen a few use cases crop up for working with text fragments:

• Being able to attach commentary/UI to a targeted text range [received as part of Mozilla’s feedback on the core text directive feature]

• Tools that wish to create text directive links of their own find it difficult since the rules around matching text are rather complicated (necessarily so). This API allows such tools/pages to give the browser a Range and receive a text directive string in return.

• Pages that use a cross-origin iframe to host content and want to enable text highlighting can coordinate between the embedder and embeddee by passing the text directive string to the embeddee and having it set the text directive on itself. The text directive is currently exposed (accidentally) on the performance API which pages can to read to achieve this behavior. An explicit API would allow us to remove the performance API hack which may enable more privacy-sensitive features to use the fragment directive mechanism.

Initial public proposal

https://github.com/WICG/scroll-to-text-fragment/issues/160

Search tags

text, scroll, fragment, directive, fragmentDirective, document

TAG review

TODO: None yet

TAG review status

Pending

Risks

No compat risk as this is a new API.

Usual interop risk of other vendors not implementing. Given this is extending a feature other vendors don’t yet implement, there’s some risk here this makes it more difficult to reach interop. We plan to mitigate this with detailed spec text and extensive web-platform tests.

One thing to highlight - the fragment directive (everything after `:~:` in the URL) is stripped from the URL during page load. This is done for compatibility, to ensure that target pages are not confused by the fragment directive. A page can already tell where the user gets scrolled to, and what text is at that location, so explicitly exposing the text directive data in an API doesn’t reveal anything new or sensitive to the page.

Interoperability and Compatibility

TODO
Gecko: No signal
WebKit: No signal
Web developers: No signals
Other signals:

Debuggability

Authors working with text directives today have no visibility into their inner workings. This API improves the situation and will allow us to provide some more useful output (e.g. by explaining in an exception why a TextDirective fails to parse).

Is this feature fully tested by web-platform-tests?

Yes - we’ve added tests to wpt_internal which can be simply upstreamed when shipping. Will continue to add extensive tests as the feature develops.

Flag name

--enable-blink-features=TextFragmentAPI

Requires code in //chrome?

False

Tracking bug

https://crbug.com/1214791

Estimated milestones

No milestones specified

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5073715822854144

This intent message was generated by Chrome Platform Status.

[David Bokan]

cc: flackr@,girard@,mehdika@

On Friday, November 5, 2021 at 5:11:18 PM UTC-4 David Bokan wrote:

(Note - this is an extension to the already shipped "scroll-to-text"/text directive feature)

Contact emails

bo...@chromium.org, blink-interact...@google.com