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

Author: bartveneman

API.md

@@ -4,6 +4,7 @@
 - `parse_selector`
 - `parse_atrule_prelude`
 - `walk`
+- `is_custom`
 - `tokenize`
 
 ---
@@ -799,6 +800,49 @@ traverse(ast, {
 
 ---
 
+## `is_custom(str)`
+
+Check if a string is a CSS custom property (starts with `--`).
+
+### Signature
+
+```typescript
+function is_custom(str: string): boolean
+```
+
+### Parameters
+
+- **`str`** (`string`) - The string to check
+
+### Returns
+
+`boolean` - `true` if the string starts with `--` (custom property), `false` otherwise
+
+### Examples
+
+```typescript
+import { parse, is_custom } from '@projectwallace/css-parser'
+
+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"
+	} else {
+		console.log('Standard property:', decl.name) // Logs: "color"
+	}
+}
+
+// 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)
+```
+
+---
+
 ## `tokenize(source, skip_comments?)`
 
 Tokenize CSS source code into a stream of tokens.

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 } 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
+}