This is an automated email from the ASF dual-hosted git repository. gerben pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/incubator-annotator.git
commit 32f9fda679d35d375ae0cfc4480f44fc322ed98d Author: Gerben <[email protected]> AuthorDate: Fri Jul 9 17:06:55 2021 +0200 Improve CssSelector docs --- packages/dom/src/css.ts | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/packages/dom/src/css.ts b/packages/dom/src/css.ts index 86deb91..12da683 100644 --- a/packages/dom/src/css.ts +++ b/packages/dom/src/css.ts @@ -28,8 +28,6 @@ import { toRange } from './to-range'; * CssSelector}. * * The given CssSelector returns all elements within `scope` that it matches. - * However, the selector is evaluated relative to the Document as a whole. - * *(XXX is this intentional, a mistake, or compromise?)* * * The function is curried, taking first the selector and then the scope. * @@ -46,6 +44,24 @@ import { toRange } from './to-range'; * > “If […] the user agent discovers multiple matching text sequences, then the * > selection SHOULD be treated as matching all of the matches.” * + * Note that if `scope` is *not* a Document, the [Web Annotation Data Model](https://www.w3.org/TR/2017/REC-annotation-model-20170223/#css-selector) + * leaves the behaviour undefined. This implementation will, in such a case, + * evaluate the selector relative to the document containing the scope, but only + * return those matches that are fully enclosed within the scope. There might be + * edge cases where this is not a perfect inverse of {@link describeCss}. + * + * @example + * ``` + * const matches = createCssSelectorMatcher({ + * type: 'CssSelector', + * value: '#target', + * }); + * for await (const match of matches) { + * console.log(match); + * } + * // <div id="target" …> + * ``` + * * @param selector - The {@link CssSelector} to be anchored. * @returns A {@link Matcher} function that applies `selector` to a given * `scope`. @@ -89,7 +105,7 @@ export function createCssSelectorMatcher( * * @param element - The element that the selector should describe. * @param scope - The node that serves as the ‘document’ for purposes of finding - * a unique selector. Defaults to the full Document that contains `element`. + * an unambiguous selector. Defaults to the Document that contains `element`. * @returns The selector unambiguously describing `element` within `scope`. */ export async function describeCss(
