feat: add is_custm(str: string): boolean helper (#87)

closes #85

Author: bartveneman

API.md

@@ -32,11 +32,13 @@ function parse(source: string, options?: ParserOptions): CSSNode
 `CSSNode` - Root stylesheet node with the following properties:
 
 **Core Properties:**
+
 - `type` - Node type constant (e.g., `STYLESHEET`, `STYLE_RULE`)
 - `type_name` - CSSTree-compatible type name (e.g., `'StyleSheet'`, `'Rule'`)
 - `text` - Full text of the node from source
 
 **Content Properties:**
+
 - `name` - Property name for declarations, at-rule name for at-rules, layer name for import layers
 - `property` - Alias for `name` (for declarations, more semantic)
 - `value` - Value text (for declarations), numeric value (for NUMBER/DIMENSION), string content without quotes (for STRING), URL content (for URL), or `null`
@@ -45,13 +47,15 @@ function parse(source: string, options?: ParserOptions): CSSNode
 - `prelude` - At-rule prelude text or `null`
 
 **Location Properties:**
+
 - `line` - Starting line number (1-based)
 - `column` - Starting column number (1-based)
 - `start` - Starting offset in source (0-based)
 - `length` - Length in source
 - `end` - End offset in source (calculated as `start + length`)
 
 **Flags:**
+
 - `is_important` - Whether declaration has `!important` (DECLARATION only)
 - `is_vendor_prefixed` - Whether node has vendor prefix (checks name/text based on type)
 - `has_error` - Whether node has syntax error
@@ -62,34 +66,40 @@ function parse(source: string, options?: ParserOptions): CSSNode
 - `has_next` - Whether node has a next sibling
 
 **Tree Structure:**
+
 - `first_child` - First child node or `null`
 - `next_sibling` - Next sibling node or `null`
 - `children` - Array of all child nodes
 - `block` - Block node containing declarations/nested rules (for style rules and at-rules with blocks)
 - `is_empty` - Whether block has no declarations or rules (only comments allowed)
 
 **Value Access (Declarations):**
+
 - `values` - Array of value nodes (for declarations)
 
 **Selector Properties:**
+
 - `selector_list` - Selector list from pseudo-classes like `:is()`, `:not()`, `:has()`, `:where()`, or `:nth-child(of)`
 - `nth` - An+B formula node from `:nth-child(of)` wrapper (for NTH_OF_SELECTOR nodes)
 - `selector` - Selector list from `:nth-child(of)` wrapper (for NTH_OF_SELECTOR nodes)
 - `nth_a` - The 'a' coefficient from An+B expressions like `"2n"` from `:nth-child(2n+1)` (for NTH_SELECTOR)
 - `nth_b` - The 'b' coefficient from An+B expressions like `"+1"` from `:nth-child(2n+1)` (for NTH_SELECTOR)
 
 **Attribute Selector Properties:**
+
 - `attr_operator` - Attribute operator constant (for ATTRIBUTE_SELECTOR): `ATTR_OPERATOR_NONE`, `ATTR_OPERATOR_EQUAL`, etc.
 - `attr_flags` - Attribute flags constant (for ATTRIBUTE_SELECTOR): `ATTR_FLAG_NONE`, `ATTR_FLAG_CASE_INSENSITIVE`, `ATTR_FLAG_CASE_SENSITIVE`
 
 **Compound Selector Helpers (SELECTOR nodes):**
+
 - `compound_parts()` - Iterator over first compound selector parts (zero allocation)
 - `first_compound` - Array of parts before first combinator
 - `all_compounds` - Array of compound arrays split by combinators
 - `is_compound` - Whether selector has no combinators
 - `first_compound_text` - Text of first compound selector (no node allocation)
 
 **Methods:**
+
 - `clone(options?)` - Clone node as a mutable plain object with children as arrays
 
 ### Example 1: Basic Parsing
@@ -613,11 +623,7 @@ console.log(nodes[0].text) // "(min-width: 768px)"
 Walk the AST in depth-first order, calling the callback for each node.
 
 ```typescript
-function walk(
-	node: CSSNode,
-	callback: (node: CSSNode, depth: number) => void | typeof SKIP | typeof BREAK,
-	depth?: number
-): boolean
+function walk(node: CSSNode, callback: (node: CSSNode, depth: number) => void | typeof SKIP | typeof BREAK, depth?: number): boolean
 ```
 
 ### Parameters
@@ -696,7 +702,7 @@ function traverse(
 	options?: {
 		enter?: (node: CSSNode) => void | typeof SKIP | typeof BREAK
 		leave?: (node: CSSNode) => void | typeof SKIP | typeof BREAK
-	}
+	},
 ): boolean
 ```
 
@@ -730,7 +736,7 @@ traverse(ast, {
 	leave(node) {
 		console.log(`${'  '.repeat(depth)}Leaving ${node.type_name}`)
 		depth--
-	}
+	},
 })
 ```
 
@@ -755,7 +761,7 @@ traverse(ast, {
 			console.log('Leaving media query at depth', depth)
 		}
 		depth--
-	}
+	},
 })
 // Output:
 // Entering media query at depth 2
@@ -790,7 +796,7 @@ traverse(ast, {
 		if (node.type === AT_RULE) {
 			context.pop()
 		}
-	}
+	},
 })
 // Output:
 // Rule: .top
@@ -962,3 +968,91 @@ for (let node of ast) {
 	}
 }
 ```
+
+---
+
+## `@projectwallace/css-parser/string-utils`
+
+### `is_custom(str)`
+
+Check if a string is a CSS custom property (starts with `--`).
+
+```typescript
+import { parse } from '@projectwallace/css-parser'
+import { is_custom } from '@projectwallace/css-parser/string-utils'
+
+const ast = parse(':root { --primary: blue; color: red; }')
+const block = ast.first_child.block
+
+for (const decl of block.children) {
+	if (is_custom(decl.name)) {
+		console.log('Custom property:', decl.name) // Logs: "--primary"
+	}
+}
+
+// Direct usage
+is_custom('--primary-color') // true
+is_custom('--my-var') // true
+is_custom('color') // false
+is_custom('-webkit-transform') // false (vendor prefix, not custom)
+```
+
+### `is_vendor_prefixed(str)`
+
+Check if a string has a vendor prefix (`-webkit-`, `-moz-`, `-ms-`, `-o-`).
+
+```typescript
+import { is_vendor_prefixed } from '@projectwallace/css-parser/string-utils'
+
+// Detect vendor prefixes
+is_vendor_prefixed('-webkit-transform') // true
+is_vendor_prefixed('-moz-appearance') // true
+is_vendor_prefixed('-ms-filter') // true
+is_vendor_prefixed('-o-border-image') // true
+
+// Not vendor prefixes
+is_vendor_prefixed('--custom-property') // false (custom property)
+is_vendor_prefixed('border-radius') // false (standard property)
+is_vendor_prefixed('transform') // false (no prefix)
+```
+
+### `str_equals(a, b)`
+
+Case-insensitive string equality check without allocations. The first parameter must be lowercase.
+
+```typescript
+import { str_equals } from '@projectwallace/css-parser/string-utils'
+
+// First parameter MUST be lowercase
+str_equals('media', 'MEDIA') // true
+str_equals('media', 'Media') // true
+str_equals('media', 'media') // true
+str_equals('media', 'print') // false
+```
+
+### `str_starts_with(str, prefix)`
+
+Case-insensitive prefix check without allocations. The prefix parameter must be lowercase.
+
+```typescript
+import { str_starts_with } from '@projectwallace/css-parser/string-utils'
+
+// prefix MUST be lowercase
+str_starts_with('WEBKIT-transform', 'webkit') // true
+str_starts_with('Mozilla', 'moz') // true
+str_starts_with('transform', 'trans') // true
+str_starts_with('color', 'border') // false
+```
+
+### `str_index_of(str, search)`
+
+Case-insensitive substring search without allocations. Returns the index of the first occurrence. The search parameter must be lowercase.
+
+```typescript
+import { str_index_of } from '@projectwallace/css-parser/string-utils'
+
+// search MUST be lowercase
+str_index_of('background-COLOR', 'color') // 11
+str_index_of('HELLO', 'e') // 1
+str_index_of('transform', 'x') // -1 (not found)
+```

src/index.ts

@@ -8,6 +8,7 @@ export { parse_declaration } from './parse-declaration'
 export { parse_value } from './parse-value'
 export { tokenize } from './tokenize'
 export { walk, traverse, SKIP, BREAK } from './walk'
+export { is_custom, is_vendor_prefixed, str_equals, str_starts_with, str_index_of } from './string-utils'
 
 // Advanced/class-based API
 export { type ParserOptions } from './parse'

src/string-utils.test.ts

@@ -5,6 +5,7 @@ import {
 	str_starts_with,
 	str_index_of,
 	is_vendor_prefixed,
+	is_custom,
 	CHAR_SPACE,
 	CHAR_TAB,
 	CHAR_NEWLINE,
@@ -350,6 +351,52 @@ describe('string-utils', () => {
 			expect(is_vendor_prefixed(source, 6, 20)).toBe(true) // "-webkit-suffix"
 		})
 	})
+
+	describe('is_custom', () => {
+		it('should detect custom property with --', () => {
+			expect(is_custom('--primary-color')).toBe(true)
+		})
+
+		it('should detect another custom property', () => {
+			expect(is_custom('--my-var')).toBe(true)
+		})
+
+		it('should detect shortest valid custom property', () => {
+			expect(is_custom('--x')).toBe(true)
+		})
+
+		it('should not detect exactly two hyphens', () => {
+			expect(is_custom('--')).toBe(false)
+		})
+
+		it('should not detect vendor prefix as custom', () => {
+			expect(is_custom('-webkit-transform')).toBe(false)
+		})
+
+		it('should not detect -moz- vendor prefix as custom', () => {
+			expect(is_custom('-moz-appearance')).toBe(false)
+		})
+
+		it('should not detect standard property with hyphen as custom', () => {
+			expect(is_custom('border-radius')).toBe(false)
+		})
+
+		it('should not detect standard property as custom', () => {
+			expect(is_custom('color')).toBe(false)
+		})
+
+		it('should not detect single hyphen as custom', () => {
+			expect(is_custom('-')).toBe(false)
+		})
+
+		it('should not detect empty string as custom', () => {
+			expect(is_custom('')).toBe(false)
+		})
+
+		it('should not detect single character as custom', () => {
+			expect(is_custom('a')).toBe(false)
+		})
+	})
 })
 
 	describe('str_index_of', () => {

src/string-utils.ts

@@ -199,3 +199,22 @@ export function is_vendor_prefixed(source: string, start?: number, end?: number)
 	}
 	return false
 }
+
+/**
+ * Check if a string is a CSS custom property (starts with --)
+ *
+ * @param str - The string to check
+ * @returns true if the string starts with -- (custom property)
+ *
+ * Examples:
+ * - `--primary-color` → true
+ * - `--my-var` → true
+ * - `-webkit-transform` → false (vendor prefix, not custom)
+ * - `border-radius` → false (standard property)
+ * - `color` → false
+ */
+export function is_custom(str: string): boolean {
+	// Must start with two hyphens and have at least one character after
+	if (str.length < 3) return false
+	return str.charCodeAt(0) === CHAR_MINUS_HYPHEN && str.charCodeAt(1) === CHAR_MINUS_HYPHEN
+}