add sourceIndices helper function (#1022)

* add sourceIndices helper function

* wording

* cleanup

* document magic index values

Author: romainmenke

packages/css-parser-algorithms/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changes to CSS Parser Algorithms
 
+### Unreleased (minor)
+
+- Add `sourceIndices` helper function.
+
+This makes it easier to get the start and end indices of a node in the source string.  
+This function accepts any node that can be converted into an array of tokens.
+
 ### 2.2.0
 
 _June 1, 2023_

packages/css-parser-algorithms/dist/index.cjs

@@ -7,3 +7,4 @@ export { replaceComponentValues } from './util/replace-component-values';
 export { stringify } from './util/stringify';
 export { ComponentValueType } from './util/component-value-type';
 export { isCommentNode, isFunctionNode, isSimpleBlockNode, isTokenNode, isWhitespaceNode, } from './util/type-predicates';
+export { sourceIndices } from './util/source-indices';

packages/css-parser-algorithms/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { CSSToken } from '@csstools/css-tokenizer';
+interface TokenConvertible {
+    tokens(): Array<CSSToken>;
+}
+/**
+ * Returns the start and end index of a node in the CSS source string.
+ */
+export declare function sourceIndices(x: TokenConvertible | Array<TokenConvertible>): [number, number];
+export {};

packages/css-parser-algorithms/dist/index.mjs

@@ -13,3 +13,4 @@ export {
 	isTokenNode,
 	isWhitespaceNode,
 } from './util/type-predicates';
+export { sourceIndices } from './util/source-indices';

packages/css-parser-algorithms/dist/util/source-indices.d.ts

@@ -0,0 +1,44 @@
+import { CSSToken } from '@csstools/css-tokenizer';
+
+interface TokenConvertible {
+	tokens(): Array<CSSToken>
+}
+
+/**
+ * Returns the start and end index of a node in the CSS source string.
+ */
+export function sourceIndices(x: TokenConvertible | Array<TokenConvertible>): [number, number] {
+	if (Array.isArray(x)) {
+		const firstNode = x[0];
+
+		if (!firstNode) {
+			return [0, 0];
+		}
+
+		const lastNode = x[x.length - 1] || firstNode;
+
+		return [
+			// start index of the first node
+			sourceIndices(firstNode)[0],
+			// end index of the last node
+			sourceIndices(lastNode)[1],
+		];
+	}
+
+	const tokens = x.tokens();
+
+	const firstToken = tokens[0];
+	const lastToken = tokens[tokens.length - 1];
+
+	if (!firstToken || !lastToken) {
+		return [0, 0];
+	}
+
+	return [
+		// CSSTokens have this layout : [type, raw, start, end]
+		// start index of the first token
+		firstToken[2],
+		// end index of the last token
+		lastToken[3],
+	];
+}

packages/css-parser-algorithms/src/index.ts

@@ -0,0 +1,62 @@
+import { tokenize } from '@csstools/css-tokenizer';
+import assert from 'assert';
+import { parseCommaSeparatedListOfComponentValues, sourceIndices } from '@csstools/css-parser-algorithms';
+
+const onParseError = (err) => {
+	throw err;
+};
+
+{
+	const indicesAndParts = [
+		[[0, 49], '(image-set( url("image1.jpg") calc(2 * 1x)), 50px)'],
+		[[0, 49], '(image-set( url("image1.jpg") calc(2 * 1x)), 50px)'],
+		[[1, 42], 'image-set( url("image1.jpg") calc(2 * 1x))'],
+		[[11, 11], ' '],
+		[[12, 28], 'url("image1.jpg")'],
+		[[16, 27], '"image1.jpg"'],
+		[[29, 29], ' '],
+		[[30, 41], 'calc(2 * 1x)'],
+		[[35, 35], '2'],
+		[[36, 36], ' '],
+		[[37, 37], '*'],
+		[[38, 38], ' '],
+		[[39, 40], '1x'],
+		[[43, 43], ','],
+		[[44, 44], ' '],
+		[[45, 48], '50px'],
+		[[51, 65], ' something-else'],
+		[[51, 51], ' '],
+		[[52, 65], 'something-else'],
+	].reverse();
+
+	const source = '(image-set( url("image1.jpg") calc(2 * 1x)), 50px), something-else';
+
+	const tokens = tokenize({ css: source }, { onParseError: onParseError });
+	const list = parseCommaSeparatedListOfComponentValues(tokens, { onParseError: onParseError });
+	list.forEach((listItem) => {
+		{
+			const [y, part] = indicesAndParts.pop();
+			const x = sourceIndices(listItem);
+			assert.deepStrictEqual(x, y);
+			assert.deepStrictEqual(source.slice(x[0], x[1] + 1), part);
+		}
+
+		listItem.forEach((componentValue) => {
+			{
+				const [y, part] = indicesAndParts.pop();
+				const x = sourceIndices(componentValue);
+				assert.deepStrictEqual(x, y);
+				assert.deepStrictEqual(source.slice(x[0], x[1] + 1), part);
+			}
+
+			if ('walk' in componentValue) {
+				componentValue.walk((entry) => {
+					const [y, part] = indicesAndParts.pop();
+					const x = sourceIndices(entry.node);
+					assert.deepStrictEqual(x, y);
+					assert.deepStrictEqual(source.slice(x[0], x[1] + 1), part);
+				});
+			}
+		});
+	});
+}

packages/css-parser-algorithms/src/util/source-indices.ts

@@ -18,6 +18,8 @@ import './cases/query-with-type/0003.mjs';
 
 import './cases/replacer/0001.mjs';
 
+import './cases/source-indices/0001.mjs';
+
 import './cases/various/0001.mjs';
 import './cases/various/0002.mjs';
 import './cases/various/0003.mjs';