You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@annotator.apache.org by ge...@apache.org on 2021/07/09 15:35:16 UTC
[incubator-annotator] branch main updated (bdc0b32 -> 6475023)
This is an automated email from the ASF dual-hosted git repository.
gerben pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-annotator.git.
from bdc0b32 Tiny fixes
new 32f9fda Improve CssSelector docs
new 6475023 Add warning about issue #112.
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
packages/dom/src/css.ts | 22 +++++++++++++++++++---
packages/dom/src/text-quote/match.ts | 4 ++++
packages/selector/src/text/match-text-quote.ts | 3 +++
3 files changed, 26 insertions(+), 3 deletions(-)
[incubator-annotator] 02/02: Add warning about issue #112.
Posted by ge...@apache.org.
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 647502382dd9d7e893c56ee0965a7179dfb3f7b4
Author: Gerben <ge...@treora.com>
AuthorDate: Fri Jul 9 17:32:39 2021 +0200
Add warning about issue #112.
---
packages/dom/src/text-quote/match.ts | 4 ++++
packages/selector/src/text/match-text-quote.ts | 3 +++
2 files changed, 7 insertions(+)
diff --git a/packages/dom/src/text-quote/match.ts b/packages/dom/src/text-quote/match.ts
index 2b29df6..87ef5d2 100644
--- a/packages/dom/src/text-quote/match.ts
+++ b/packages/dom/src/text-quote/match.ts
@@ -40,6 +40,10 @@ import { TextNodeChunker, EmptyScopeError } from '../text-node-chunker';
* return an (async) generator that produces each match in the order they are
* found in the text.
*
+ * *XXX Modifying the DOM (e.g. to highlight the text) while the search is still
+ * running can mess up and result in an error or an infinite loop. See [issue
+ * #112](https://github.com/apache/incubator-annotator/issues/112).*
+ *
* @example
* ```
* // Find the word ‘banana’.
diff --git a/packages/selector/src/text/match-text-quote.ts b/packages/selector/src/text/match-text-quote.ts
index 0531369..78dd96a 100644
--- a/packages/selector/src/text/match-text-quote.ts
+++ b/packages/selector/src/text/match-text-quote.ts
@@ -45,6 +45,9 @@ import type { Chunk, Chunker, ChunkRange } from './chunker';
* return an (async) generator that produces each match in the order they are
* found in the text.
*
+ * *XXX Modifying the Chunks while the search is still running can mess up and
+ * result in an error or an infinite loop. See [issue #112](https://github.com/apache/incubator-annotator/issues/112).*
+ *
* @example
* ```
* const selector = { type: 'TextQuoteSelector', exact: 'banana' };
[incubator-annotator] 01/02: Improve CssSelector docs
Posted by ge...@apache.org.
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 <ge...@treora.com>
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(