first commit

docs/media/fonts/font-subset/src/utils/unicode-ranges.md

@@ -0,0 +1,65 @@
+# Utils: unicode-ranges
+
+## Purpose
+
+Parses CSS/OpenType-style Unicode range notation into a `Set<number>` of integer codepoints. Font subsetting workflows need to know which codepoints to retain; this utility bridges the human-readable range format (e.g. `U+0020-007F`) and the numeric representation that font adapters operate on.
+
+## Features
+
+- Parses single codepoints: `U+XXXX`
+- Parses inclusive ranges: `U+XXXX-XXXX`
+- Case-insensitive for both the `U+` prefix and hex digits
+- Merges multiple ranges into a single `Set<number>` with no duplicates
+- Throws `FontCompressError(INVALID_OPTIONS)` for malformed syntax or reversed ranges
+- Zero external dependencies
+
+## Usage: Basic Example
+
+```typescript
+import { parseUnicodeRanges } from "@suaveplan/font-compress/utils/unicode-ranges";
+
+// ASCII printable range
+const ascii = parseUnicodeRanges(["U+0020-007F"]);
+console.log(ascii.has(0x41)); // true  ("A")
+console.log(ascii.size);      // 96
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { parseUnicodeRanges } from "@suaveplan/font-compress/utils/unicode-ranges";
+import { FontCompressError } from "@suaveplan/font-compress";
+
+// Multi-range merge — Latin + Latin Extended
+const ranges = parseUnicodeRanges(["U+0020-007F", "U+00A0-00FF"]);
+console.log(ranges.size); // 192
+
+// Catching parse errors
+try {
+    parseUnicodeRanges(["0020-007F"]); // missing U+ prefix
+} catch (e) {
+    if (e instanceof FontCompressError) {
+        console.error(e.code);    // "FONT_COMPRESS.INVALID_OPTIONS"
+        console.error(e.message); // describes the bad input
+    }
+}
+```
+
+## API Reference
+
+### `parseUnicodeRanges(ranges: string[]): Set<number>`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `ranges` | `string[]` | Array of range strings in `U+XXXX` or `U+XXXX-XXXX` format |
+
+**Returns** a `Set<number>` containing every integer codepoint covered by the union of all input ranges.
+
+**Throws** `FontCompressError` with code `FONT_COMPRESS.INVALID_OPTIONS` when:
+
+- A string does not match the `U+XXXX` or `U+XXXX-XXXX` pattern
+- The start codepoint of a range exceeds the end codepoint
+
+## Implementation Notes
+
+The regex `^[Uu]\+([0-9A-Fa-f]{1,6})(?:-([0-9A-Fa-f]{1,6}))?$` validates the entire string in a single pass, avoiding character-by-character parsing. Codepoints up to 6 hex digits are supported (`U+10FFFF` = 1114111), covering the full Unicode range. For very large ranges (e.g. `U+0000-FFFF` = 65536 entries), callers should be aware that `Set` construction is O(n) in the number of codepoints.