This is an automated email from the ASF dual-hosted git repository. gerben pushed a commit to branch css-selector in repository https://gitbox.apache.org/repos/asf/incubator-annotator.git
commit f375738cdb0f4a1f369bb49f91b23c1dbc5f396e Author: Gerben <[email protected]> AuthorDate: Tue May 25 00:59:21 2021 +0200 Add describeCss & tests - css-selector-generator gives an error when a scope is passed.. - using @mdev/finder instead gave syntax errors due to ‘export’ token. May be worth trying to fix? Should we stop our insistence on Ranges both for scopes and matches? Makes little sense for CssSelector. --- packages/dom/package.json | 3 +- packages/dom/src/css.ts | 31 +++++++++++++---- packages/dom/test/css/describe.test.ts | 55 +++++++++++++++++++++++++++++ packages/dom/test/css/match-cases.ts | 63 ++++++++++++++++++++++++++++++++++ packages/dom/test/css/match.test.ts | 62 +++++++++++++++++++++++++++++++++ yarn.lock | 40 ++++++++++++++++++++- 6 files changed, 246 insertions(+), 8 deletions(-) diff --git a/packages/dom/package.json b/packages/dom/package.json index ff22835..d0eab1e 100644 --- a/packages/dom/package.json +++ b/packages/dom/package.json @@ -14,7 +14,8 @@ "exports": "./lib/index.js", "main": "./lib/index.js", "dependencies": { - "@babel/runtime-corejs3": "^7.13.10" + "@babel/runtime-corejs3": "^7.13.10", + "css-selector-generator": "^3.0.1" }, "devDependencies": { "@apache-annotator/selector": "^0.1.0" diff --git a/packages/dom/src/css.ts b/packages/dom/src/css.ts index c8c0db5..e0b22f9 100644 --- a/packages/dom/src/css.ts +++ b/packages/dom/src/css.ts @@ -18,6 +18,7 @@ * under the License. */ +import cssSelectorGenerator from 'css-selector-generator'; import type { CssSelector, Matcher } from '@apache-annotator/selector'; import { ownerDocument } from './owner-document'; @@ -32,18 +33,25 @@ import { ownerDocument } from './owner-document'; * The function is curried, taking first the selector and then the scope. * * As there may be multiple matches for a given selector, the matcher will - * return an (async) generator that produces each match in the order they are - * found in the text. + * return an (async) iterable that produces each match in the order they are + * found in the document. + * + * Note that the Web Annotation specification does not mention whether an + * ‘ambiguous’ CssSelector should indeed match all elements that match the + * selector value, or perhaps only the first. This implementation returns all + * matches to give users the freedom to follow either interpretation. This is + * also in line with more clearly defined behaviour of the TextQuoteSelector: + * + * > “If […] the user agent discovers multiple matching text sequences, then the + * > selection SHOULD be treated as matching all of the matches.” * * Each matching element is returned as a {@link https://developer.mozilla.org/en-US/docs/Web/API/Range * | Range} surrounding that element. This in order to make its output reusable * as the scope for any subsequents selectors that {@link * Selector.refinedBy | refine} this CssSelector. * - * @param selector - The {@link CssSelector} to be - * anchored - * @returns A {@link Matcher} function that applies - * `selector` to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range + * @param selector - The {@link CssSelector} to be anchored + * @returns A {@link Matcher} function that applies `selector` to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range * | Range} * * @public @@ -66,3 +74,14 @@ export function createCssSelectorMatcher( } }; } + +export async function describeCss( + element: HTMLElement, + scope?: HTMLElement, +): Promise<CssSelector> { + const selector = cssSelectorGenerator(element, { root: scope ?? element.ownerDocument.body }); + return { + type: 'CssSelector', + value: selector, + }; +} diff --git a/packages/dom/test/css/describe.test.ts b/packages/dom/test/css/describe.test.ts new file mode 100644 index 0000000..3d0fed6 --- /dev/null +++ b/packages/dom/test/css/describe.test.ts @@ -0,0 +1,55 @@ +/** + * @license + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { assert } from 'chai'; +import { describeCss } from '../../src/css'; +import { testCases } from './match-cases'; +import { evaluateXPath } from '../utils'; + +const domParser = new DOMParser(); + +describe('describeCss', () => { + describe('css matcher finds back described element', () => { + for (const [name, { html, scopeXPath, expected }] of Object.entries( + testCases, + )) { + const elementXPath = expected[0]; + it(`case: '${name}'`, async () => { + const doc = domParser.parseFromString(html, 'text/html'); + const element = evaluateXPath(doc, elementXPath) as HTMLElement; + const scopeElement = scopeXPath + ? evaluateXPath(doc, scopeXPath) as HTMLElement + : undefined; + const cssSelector = await describeCss( + element, + scopeElement, + ); + + // Match it again to see if ends up at the same element. + // const scopeRange = doc.createRange(); + // scopeRange.selectNodeContents(scopeElement ?? doc); + // testMatcher(doc, scopeRange, cssSelector, [elementXPath]); + const matchingElements = (scopeElement ?? doc).querySelectorAll(cssSelector.value); + assert.equal(matchingElements.length, 1, 'Expected a selector with a single match'); + assert.equal(matchingElements[0], element); + }); + } + }); +}); diff --git a/packages/dom/test/css/match-cases.ts b/packages/dom/test/css/match-cases.ts new file mode 100644 index 0000000..26fbe03 --- /dev/null +++ b/packages/dom/test/css/match-cases.ts @@ -0,0 +1,63 @@ +/** + * @license + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import type { CssSelector } from '@apache-annotator/selector'; + +export const testCases: { + [name: string]: { + html: string; + selector: CssSelector; + scopeXPath?: string; + expected: string[]; + }; +} = { + 'simple': { + html: '<b>lorem <i>ipsum</i> dolor <i>amet</i> yada <i>yada</i></b>', + selector: { + type: 'CssSelector', + value: 'i:nth-child(2)', + }, + expected: ['//b/i[2]'], + }, + 'multiple matches': { + html: '<b>lorem <i>ipsum</i> dolor <i>amet</i> yada <i>yada</i></b>', + selector: { + type: 'CssSelector', + value: 'i', + }, + expected: [ + '//b/i[1]', + '//b/i[2]', + '//b/i[3]', + ], + }, + 'with scope': { + html: '<b>lorem <i>ipsum</i> dolor <u><i>amet</i> yada <i>yada</i></u></b>', + selector: { + type: 'CssSelector', + value: 'i', + }, + scopeXPath: '//u', + expected: [ + '//u/i[1]', + '//u/i[2]', + ], + }, +}; diff --git a/packages/dom/test/css/match.test.ts b/packages/dom/test/css/match.test.ts new file mode 100644 index 0000000..9d4c18f --- /dev/null +++ b/packages/dom/test/css/match.test.ts @@ -0,0 +1,62 @@ +/** + * @license + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { assert } from 'chai'; +import type { CssSelector } from '@apache-annotator/selector'; +import { createCssSelectorMatcher } from '../../src/css'; +import { testCases } from './match-cases'; +import { evaluateXPath } from '../utils'; + +const domParser = new DOMParser(); + +describe('CreateCssSelectorMatcher', () => { + for (const [name, { html, selector, scopeXPath, expected }] of Object.entries( + testCases, + )) { + it(`works for case: '${name}'`, async () => { + const doc = domParser.parseFromString(html, 'text/html'); + + const scopeElement = scopeXPath ? evaluateXPath(doc, scopeXPath) : doc; + const scope = doc.createRange(); + scope.selectNodeContents(scopeElement); + + await testMatcher(doc, scope, selector, expected); + }); + } +}); + +async function testMatcher( + doc: Document, + scope: Range, + selector: CssSelector, + expected: string[], +) { + const matcher = createCssSelectorMatcher(selector); + const matches = []; + for await (const value of matcher(scope)) matches.push(value); + assert.equal(matches.length, expected.length, 'Unexpected number of matches'); + matches.forEach((match, i) => { + const expectedElement = evaluateXPath(doc, expected[i]); + // The match should be a Range that exactly contains the expected element. + assert.equal(match.startContainer.childNodes[match.startOffset], expectedElement); + assert.equal(match.endContainer, match.startContainer); + assert.equal(match.endOffset, match.startOffset + 1); + }); +} diff --git a/yarn.lock b/yarn.lock index 5dbf5f7..cbb0ad0 100644 --- a/yarn.lock +++ b/yarn.lock @@ -978,6 +978,11 @@ unique-filename "^1.1.1" which "^1.3.1" +"@fczbkk/power-set-generator@^1.0.0": + version "1.0.2" + resolved "https://registry.yarnpkg.com/@fczbkk/power-set-generator/-/power-set-generator-1.0.2.tgz#d6266c75c2d3e31fc1bf4597f23fd1049a52dd7e"; + integrity sha512-RIaL+cRjzcYdwpfNkcSUeu1qJhap0CWUG77Oz922tQbSi+6BQuwlDV867z9Ca/BfssTC1+MBB0qzMnzNdklvLA== + "@istanbuljs/load-nyc-config@^1.0.0": version "1.0.0" resolved "https://registry.yarnpkg.com/@istanbuljs/load-nyc-config/-/load-nyc-config-1.0.0.tgz#10602de5570baea82f8afbfa2630b24e7a8cfe5b"; @@ -2990,6 +2995,13 @@ caniuse-lite@^1.0.30001181: resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001205.tgz#d79bf6a6fb13196b4bb46e5143a22ca0242e0ef8"; integrity sha512-TL1GrS5V6LElbitPazidkBMD9sa448bQDDLrumDqaggmKFcuU2JW1wTOHJPukAcOMtEmLcmDJEzfRrf+GjM0Og== +cartesian@^1.0.1: + version "1.0.1" + resolved "https://registry.yarnpkg.com/cartesian/-/cartesian-1.0.1.tgz#ae3fc8a63e2ba7e2c4989ce696207457bcae65af"; + integrity sha1-rj/Ipj4rp+LEmJzmliB0V7yuZa8= + dependencies: + xtend "^4.0.1" + caseless@~0.12.0: version "0.12.0" resolved "https://registry.yarnpkg.com/caseless/-/caseless-0.12.0.tgz#1b681c21ff84033c826543090689420d187151dc"; @@ -3535,6 +3547,11 @@ core-js-pure@^3.0.0: resolved "https://registry.yarnpkg.com/core-js-pure/-/core-js-pure-3.3.4.tgz#01d2842f552a866265dc77ededb2ccd668ff2879"; integrity sha512-hqxt6XpR4zIMNUY920oNyAtwaq4yg8IScmXumnfyRWF9+ur7wtjr/4eCdfTJzY64jmi8WRCwIqNBKzYeOKdvnw== +core-js@^3.9.1: + version "3.12.1" + resolved "https://registry.yarnpkg.com/core-js/-/core-js-3.12.1.tgz#6b5af4ff55616c08a44d386f1f510917ff204112"; + integrity sha512-Ne9DKPHTObRuB09Dru5AjwKjY4cJHVGu+y5f7coGn1E9Grkc3p2iBwE9AI/nJzsE29mQF7oq+mhYYRqOMFN1Bw== + [email protected], core-util-is@~1.0.0: version "1.0.2" resolved "https://registry.yarnpkg.com/core-util-is/-/core-util-is-1.0.2.tgz#b5fd54220aa2bc5ab57aab7140c940754503c1a7"; @@ -3636,6 +3653,17 @@ crypto-browserify@^3.11.0: randombytes "^2.0.0" randomfill "^1.0.3" +css-selector-generator@^3.0.1: + version "3.0.1" + resolved "https://registry.yarnpkg.com/css-selector-generator/-/css-selector-generator-3.0.1.tgz#adbe620cb935ae28ffb409f2e7f82974ad8f6d33"; + integrity sha512-uTps8C4UH7WtwFNq+ty7Tu6deGiFFO1qcxJvyUXI/kbClVpogPEVFB6Dr972PyXMEu9CRmZO8ikVot5NgijSSg== + dependencies: + "@fczbkk/power-set-generator" "^1.0.0" + cartesian "^1.0.1" + core-js "^3.9.1" + iselement "^1.1.4" + regenerator-runtime "^0.13.7" + cssom@^0.4.4: version "0.4.4" resolved "https://registry.yarnpkg.com/cssom/-/cssom-0.4.4.tgz#5a66cf93d2d0b661d80bf6a44fb65f5c2e4e0a10"; @@ -6037,6 +6065,11 @@ isarray@^2.0.5: resolved "https://registry.yarnpkg.com/isarray/-/isarray-2.0.5.tgz#8af1e4c1221244cc62459faf38940d4e644a5723"; integrity sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw== +iselement@^1.1.4: + version "1.1.4" + resolved "https://registry.yarnpkg.com/iselement/-/iselement-1.1.4.tgz#7e55b52a8ebca50a7e2e80e5b8d2840f32353146"; + integrity sha1-flW1Ko68pQp+LoDluNKEDzI1MUY= + isexe@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10"; @@ -8378,6 +8411,11 @@ regenerator-runtime@^0.13.4: resolved "https://registry.yarnpkg.com/regenerator-runtime/-/regenerator-runtime-0.13.4.tgz#e96bf612a3362d12bb69f7e8f74ffeab25c7ac91"; integrity sha512-plpwicqEzfEyTQohIKktWigcLzmNStMGwbOUbykx51/29Z3JOGYldaaNGK7ngNXV+UcoqvIMmloZ48Sr74sd+g== +regenerator-runtime@^0.13.7: + version "0.13.7" + resolved "https://registry.yarnpkg.com/regenerator-runtime/-/regenerator-runtime-0.13.7.tgz#cac2dacc8a1ea675feaabaeb8ae833898ae46f55"; + integrity sha512-a54FxoJDIr27pgf7IgeQGxmqUNYrcV338lf/6gH456HZ/PhX+5BcwHXG9ajESmwe6WRO0tAzRUrRmNONWgkrew== + regenerator-transform@^0.14.2: version "0.14.2" resolved "https://registry.yarnpkg.com/regenerator-transform/-/regenerator-transform-0.14.2.tgz#949d9d87468ff88d5a7e4734ebb994a892de1ff2"; @@ -10349,7 +10387,7 @@ xmlchars@^2.2.0: resolved "https://registry.yarnpkg.com/xmlchars/-/xmlchars-2.2.0.tgz#060fe1bcb7f9c76fe2a17db86a9bc3ab894210cb"; integrity sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw== -xtend@^4.0.0, xtend@~4.0.1: +xtend@^4.0.0, xtend@^4.0.1, xtend@~4.0.1: version "4.0.2" resolved "https://registry.yarnpkg.com/xtend/-/xtend-4.0.2.tgz#bb72779f5fa465186b1f438f674fa347fdb5db54"; integrity sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==
