@markuplint/types 4.8.1 → 5.0.0-alpha.0

package/docs/validators.md

@@ -0,0 +1,524 @@
+# Validators
+
+## Overview
+
+The `@markuplint/types` package provides a layered validation system for HTML attribute values. Validators are functions that check whether a given string conforms to a specific type defined by web standards (WHATWG, W3C, RFC) or common primitive formats.
+
+### Role in the Type System
+
+Validators sit at the core of the type-checking pipeline. When markuplint evaluates an attribute value, it:
+
+1. Resolves the attribute's expected type from the schema (e.g., `DateTime`, `BCP47`, `Uint`)
+2. Looks up the corresponding validator in the `defs` registry (`src/defs.ts`)
+3. Invokes the validator, which returns a `Result` -- either `MatchedResult` or `UnmatchedResult` with detailed error information
+
+### Validator Patterns
+
+Validators follow two primary patterns:
+
+- **`FormattedPrimitiveTypeCreator`** -- A factory that returns a boolean predicate `(value: string) => boolean`. Used for simpler checks like `isInt`, `isAbsURL`, `isCustomElementName`. These are wrapped with the `matches()` helper when registered in `defs.ts`.
+- **`CustomSyntaxChecker`** -- A factory that returns `(value: string) => Result`, providing detailed match/unmatch information with error positions, reasons, and suggestions. Used for complex validators like `checkDateTime`, `checkAutoComplete`, `checkSerializedPermissionsPolicy`.
+
+### Categories
+
+Validators are organized into four categories by the specification they implement:
+
+| Category  | Directory        | Description                            |
+| --------- | ---------------- | -------------------------------------- |
+| Primitive | `src/primitive/` | Basic numeric and string format checks |
+| WHATWG    | `src/whatwg/`    | HTML Living Standard microsyntaxes     |
+| RFC       | `src/rfc/`       | IETF RFC-defined formats               |
+| W3C       | `src/w3c/`       | W3C specification formats              |
+
+---
+
+## Primitive Validators
+
+Primitive validators handle fundamental numeric and unit-based format checks. They are used both directly and as building blocks for higher-level validators.
+
+**Source:** `src/primitive/index.ts`
+
+| Function        | File                            | Description                                | Parameters                                                                    | Return                          |
+| --------------- | ------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------- |
+| `isInt`         | `primitive/is-int.ts`           | Checks for valid signed integer            | `value: string`                                                               | `boolean`                       |
+| `isFloat`       | `primitive/is-float.ts`         | Checks for valid floating-point number     | `value: string`                                                               | `boolean`                       |
+| `isUint`        | `primitive/is-uint.ts`          | Checks for valid non-negative integer      | `value: string`, `options?: { gt?: number }`                                  | `boolean`                       |
+| `isNonZeroUint` | `primitive/is-non-zero-uint.ts` | Checks for valid non-negative integer > 0  | `value: string`                                                               | `boolean`                       |
+| `isQuantity`    | `primitive/is-quantity.ts`      | Checks for number + unit suffix            | `value: string`, `units: string[]`, `numberType?: 'int' \| 'uint' \| 'float'` | `boolean`                       |
+| `range`         | `primitive/range.ts`            | Checks if value is within a numeric range  | `value: string`, `from: number`, `to: number`                                 | `boolean`                       |
+| `splitUnit`     | `primitive/split-unit.ts`       | Splits a value into numeric and unit parts | `value: string`                                                               | `{ num: string, unit: string }` |
+
+### Validation Logic Details
+
+**`isInt`** -- Uses the regex `/^-?\d+$/` to match an optional leading minus sign followed by one or more digits. Implements the [WHATWG signed integers](https://html.spec.whatwg.org/dev/common-microsyntaxes.html#signed-integers) microsyntax.
+
+```typescript
+// src/primitive/is-int.ts
+export function isInt(value: string) {
+  return /^-?\d+$/.test(value);
+}
+```
+
+**`isFloat`** -- Trims the value and parses it with `Number.parseFloat()`, checking that the result is finite. This allows standard floating-point notation including scientific notation. Loosely based on the [WHATWG floating-point numbers](https://html.spec.whatwg.org/dev/common-microsyntaxes.html#floating-point-numbers) microsyntax. Note that `Number.parseFloat()` is more permissive than the strict WHATWG grammar (e.g., it accepts leading-dot values like `".5"` and ignores trailing non-numeric characters).
+
+```typescript
+// src/primitive/is-float.ts
+export function isFloat(value: string) {
+  return value === value.trim() && Number.isFinite(Number.parseFloat(value));
+}
+```
+
+**`isUint`** -- Matches `/^\d+$/` for non-negative integers. Optionally accepts a `gt` constraint to require the parsed value to be strictly greater than a given number. Implements the [WHATWG non-negative integers](https://html.spec.whatwg.org/dev/common-microsyntaxes.html#non-negative-integers) microsyntax.
+
+**`isNonZeroUint`** -- Matches `/^\d+$/` and additionally rejects strings consisting entirely of zeros (`/^0+$/`). This ensures the value is a positive integer.
+
+**`isQuantity`** -- Composes `splitUnit` with `isInt`/`isUint`/`isFloat` to validate strings like `"10px"` or `"1.5em"`. First splits the value into numeric and unit parts, checks the unit against a list of allowed suffixes (case-insensitive), then validates the numeric part according to the specified `numberType`.
+
+**`range`** -- Parses the value as a float and checks whether it falls within the inclusive range `[from, to]`. Returns `false` if the value cannot be parsed as a number.
+
+**`splitUnit`** -- Uses the regex `/(^-?\.\d+|^-?\d+(?:\.\d+(?:e[+-]\d+)?)?)([a-z]+$)/i` to separate a value like `"10px"` into `{ num: "10", unit: "px" }`. If no unit suffix is found, returns `{ num: value, unit: "" }`.
+
+---
+
+## WHATWG Validators
+
+WHATWG validators implement the microsyntaxes defined in the [HTML Living Standard](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html).
+
+### DateTime Subsystem
+
+The DateTime subsystem validates all date and time formats defined by the WHATWG specification. It is the most complex validator group, consisting of 12 individual format checkers that share a common token validation layer.
+
+**Entry point:** `src/whatwg/check-datetime/index.ts`
+
+The top-level `checkDateTime` function tries all formats using `checkMultiTypes` and returns the best match:
+
+```typescript
+// src/whatwg/check-datetime/index.ts
+const checks = [
+  checkDateString(),
+  checkTimeString(),
+  checkMonthString(),
+  checkYearlessDateString(),
+  checkLocalDateAndTimeString(),
+  checkNormalizedLocalDateAndTimeString(),
+  checkTimeZoneOffsetString(),
+  checkGlobalDateAndTimeString(),
+  checkWeekString(),
+  checkYearString(),
+  checkDurationISO8601LikeString(),
+  checkDurationComponentListString(),
+];
+
+export const checkDateTime: CustomSyntaxChecker = () => value => {
+  return checkMultiTypes(value, checks);
+};
+```
+
+#### DateTime Format Checkers
+
+| Function                                | File                             | Format                        | Example                | Spec Reference                                                                                                                                   |
+| --------------------------------------- | -------------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `checkDateString`                       | `date-string.ts`                 | `YYYY-MM-DD`                  | `2024-01-15`           | [Dates](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates)                                                                  |
+| `checkMonthString`                      | `month-string.ts`                | `YYYY-MM`                     | `2024-01`              | [Months](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-month-string)                                                    |
+| `checkWeekString`                       | `week-string.ts`                 | `YYYY-Www`                    | `2024-W03`             | [Weeks](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#weeks)                                                                  |
+| `checkTimeString`                       | `time-string.ts`                 | `HH:MM[:SS[.sss]]`            | `14:30:00`             | [Times](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#times)                                                                  |
+| `checkYearlessDateString`               | `yearless-date-string.ts`        | `MM-DD`                       | `01-15`                | [Yearless dates](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#yearless-dates)                                                |
+| `checkYearString`                       | `year-string.ts`                 | `YYYY` (4+ digits, > 0)       | `2024`                 | [Common microsyntaxes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html)                                                         |
+| `checkLocalDateAndTimeString`           | `local-date-and-time-string.ts`  | `YYYY-MM-DDThh:mm[:ss[.sss]]` | `2024-01-15T14:30`     | [Local dates and times](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-local-date-and-time-string)                       |
+| `checkNormalizedLocalDateAndTimeString` | `local-date-and-time-string.ts`  | Normalized local date-time    | `2024-01-15T14:30`     | [Normalized local dates and times](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-normalised-local-date-and-time-string) |
+| `checkGlobalDateAndTimeString`          | `global-date-and-time-string.ts` | Date + time + time-zone       | `2024-01-15T14:30:00Z` | [Global dates and times](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#global-dates-and-times)                                |
+| `checkTimeZoneOffsetString`             | `time-zone-offset-string.ts`     | `Z` or `+HH:MM` / `-HH:MM`    | `+09:00`               | [Time zones](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#time-zones)                                                        |
+| `checkDurationISO8601LikeString`        | `duration-string.ts`             | ISO 8601-like (`PnDTnHnMnS`)  | `PT1H30M`              | [Durations](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations)                                                          |
+| `checkDurationComponentListString`      | `duration-string.ts`             | Component list (`1h 30m 5s`)  | `1h 30m 5s`            | [Durations](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations)                                                          |
+
+#### Shared Token Definitions
+
+All datetime checkers share a common token validation layer defined in `datetime-tokens.ts`. The `datetimeTokenCheck` object provides reusable `TokenEachCheck` functions for each datetime component:
+
+```mermaid
+graph TD
+    A[checkDateTime] --> B[checkMultiTypes]
+    B --> C[checkDateString]
+    B --> D[checkTimeString]
+    B --> E[checkMonthString]
+    B --> F[checkYearlessDateString]
+    B --> G[checkLocalDateAndTimeString]
+    B --> H[checkNormalizedLocalDateAndTimeString]
+    B --> I[checkGlobalDateAndTimeString]
+    B --> J[checkTimeZoneOffsetString]
+    B --> K[checkWeekString]
+    B --> L[checkYearString]
+    B --> M[checkDurationISO8601LikeString]
+    B --> N[checkDurationComponentListString]
+
+    C --> O[datetimeTokenCheck]
+    D --> O
+    E --> O
+    F --> O
+    G --> O
+    H --> O
+    I --> O
+    J --> O
+    K --> O
+    L --> O
+    M --> O
+    N --> O
+
+    O --> P[year]
+    O --> Q[month]
+    O --> R[date]
+    O --> S[hour]
+    O --> T[minute]
+    O --> U[second]
+    O --> V[secondFractionalPart]
+    O --> W[week]
+    O --> X[hyphen / colon / separators]
+```
+
+The shared token checks validate:
+
+| Token Check                        | Validates              | Constraints                                   |
+| ---------------------------------- | ---------------------- | --------------------------------------------- |
+| `year`                             | Year component         | 4+ ASCII digits, value > 0                    |
+| `month`                            | Month component        | Exactly 2 digits, 1--12                       |
+| `date`                             | Day-of-month component | Exactly 2 digits, 1--maxday (leap-year aware) |
+| `hour`                             | Hour component         | Exactly 2 digits, 0--23                       |
+| `minute`                           | Minute component       | Exactly 2 digits, 0--59                       |
+| `second`                           | Second component       | Exactly 2 digits, 0--59                       |
+| `secondFractionalPart`             | Fractional seconds     | 1--3 ASCII digits                             |
+| `week`                             | ISO week number        | Exactly 2 digits, 1--maxweek for the year     |
+| `hyphen`                           | `-` separator          | Exactly U+002D                                |
+| `colon`                            | `:` separator          | Exactly U+003A                                |
+| `colonOrEnd`                       | `:` or end of input    | Optional colon                                |
+| `decimalPointOrEnd`                | `.` or end of input    | Optional period                               |
+| `localDateTimeSeparator`           | `T` or space           | Date-time boundary                            |
+| `normalizedlocalDateTimeSeparator` | `T` only               | Strict normalized form                        |
+| `plusOrMinusSign`                  | `+` or `-`             | Time-zone sign                                |
+| `weekSign`                         | `W`                    | Week string marker                            |
+| `extra`                            | Trailing content       | Must be empty (rejects extra tokens)          |
+
+The `datetimeTokenCheck` object also maintains `_year` and `_month` as mutable state during validation, enabling the `date` checker to compute the correct maximum day for the given year and month (including leap year logic).
+
+### Autocomplete Validator
+
+**Source:** `src/whatwg/check-autocomplete.ts`
+
+Validates the `autocomplete` attribute value according to the [WHATWG autofill specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-autocomplete).
+
+The validator uses **backward parsing** (right-to-left), matching the WHATWG specification algorithm. The attribute value is parsed as an ordered set of space-separated tokens (ASCII case-insensitive). It recognizes:
+
+- **Keywords:** `on`, `off` (standalone, no other tokens allowed)
+- **Named groups:** Tokens starting with `section-` (optional prefix)
+- **Address parts:** `shipping`, `billing` (optional)
+- **Contacting tokens:** `home`, `work`, `mobile`, `fax`, `pager` (optional, only valid before contactable field names)
+- **Autofill field names:** `name`, `given-name`, `postal-code`, `cc-number`, etc. (44 names)
+- **Contactable field names:** `tel`, `tel-country-code`, `email`, `impp`, etc. (10 names)
+- **WebAuthn:** `webauthn` (optional trailing token with category re-determination)
+
+The backward parsing algorithm:
+
+1. Determine the field name from the **last** token and classify into Normal, Contact, or Credential category
+2. Handle `webauthn` credential token: if present, consume it and re-determine the category from the preceding token
+3. Optionally consume a contacting token (only valid for Contact category fields)
+4. Reject contacting tokens preceding Normal category fields
+5. Optionally consume `shipping`/`billing`
+6. Optionally consume `section-*` named group
+7. Report any remaining tokens as extra
+
+The grammar enforced is: `[section-*] [shipping|billing] [home|work|...] <field-name> [webauthn]`. A field name is always required -- prefix-only values (e.g., `section-foo` or `shipping` alone) are rejected. Duplicate tokens, incorrect ordering, and unrecognized tokens produce detailed error results with Levenshtein-distance-based typo correction candidates.
+
+### Link Type Validator
+
+**Source:** `src/whatwg/check-link-type.ts`
+
+Validates link type values (the `rel` attribute) against the [WHATWG link types registry](https://html.spec.whatwg.org/multipage/links.html#linkTypes) and the [Microformats existing-rel-values](https://microformats.org/wiki/existing-rel-values) registry.
+
+The validator is parameterized by element context:
+
+| Option            | Context              | Description                                |
+| ----------------- | -------------------- | ------------------------------------------ |
+| `el: 'link'`      | `<link>` in `<head>` | All link types allowed on the link element |
+| `el: 'body link'` | `<link>` in `<body>` | Only link types with `body-ok` flag        |
+| `el: 'a, area'`   | `<a>`, `<area>`      | Link types allowed on anchor/area elements |
+| `el: 'form'`      | `<form>`             | Link types allowed on form elements        |
+
+The validator explicitly rejects keywords from the Microformats dropped, rejected, non-HTML, and dropped-without-prejudice lists. It builds an enumeration of allowed keywords for the given context and delegates to `checkList` for final validation.
+
+This is registered in `defs.ts` as four separate type definitions: `LinkTypeForLinkElement`, `LinkTypeForLinkElementInBody`, `LinkTypeForAnchorAndAreaElement`, and `LinkTypeForFormElement`.
+
+### MIME Type Validator
+
+**Source:** `src/whatwg/check-mime-type.ts`
+
+Validates MIME type strings according to the [WHATWG MIME Sniffing specification](https://mimesniff.spec.whatwg.org/#valid-mime-type).
+
+The validator integrates the `whatwg-mimetype` npm package for parsing. It:
+
+1. Attempts to parse the value using `MIMEType.parse()`
+2. If parsing succeeds, checks whether the serialized essence matches the input
+3. Optionally restricts to MIME types with no parameters (via the `withoutParameters` option)
+4. Reports extra tokens or syntax errors with appropriate candidates
+
+```typescript
+// Invocation in defs.ts
+MIMEType: {
+  ref: 'https://mimesniff.spec.whatwg.org/#valid-mime-type',
+  is: checkMIMEType(),
+},
+```
+
+### URL and Name Validators
+
+These validators implement simple predicate-based checks for various WHATWG-defined name formats.
+
+| Function                | File                                 | Validates                          | Logic                                                                               |
+| ----------------------- | ------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------- |
+| `isAbsURL`              | `whatwg/is-abs-url.ts`               | Absolute URL                       | Uses `new URL(value)` constructor; returns `false` on `ERR_INVALID_URL`             |
+| `isBrowserContextName`  | `whatwg/is-browser-context-name.ts`  | Browsing context name (deprecated) | Non-empty and does not start with `_`                                               |
+| `isCustomElementName`   | `whatwg/is-custom-element-name.ts`   | Custom element name                | Must start with `[a-z]`, contain `-`, use only PCENChar, and not be a reserved name |
+| `isItempropName`        | `whatwg/is-itemprop-name.ts`         | Itemprop property name             | Must not contain `:`, `.`, or space                                                 |
+| `isNavigableTargetName` | `whatwg/is-navigable-target-name.ts` | Navigable target name              | Non-empty, no ASCII tab/newline, does not start with `_`                            |
+
+**`isCustomElementName`** is the most complex, implementing the [PotentialCustomElementName](https://html.spec.whatwg.org/multipage/custom-elements.html#prod-potentialcustomelementname) production rule. It rejects the eight reserved names (`annotation-xml`, `color-profile`, `font-face`, `font-face-src`, `font-face-uri`, `font-face-format`, `font-face-name`, `missing-glyph`), requires a leading ASCII lowercase alpha, a mandatory hyphen, and validates all characters against the PCENChar character class.
+
+**`isBrowserContextName`** is deprecated in favor of `isNavigableTargetName`.
+
+All of these are `FormattedPrimitiveTypeCreator` factories -- they return `() => (value: string) => boolean`.
+
+---
+
+## RFC Validators
+
+### BCP 47 (Language Tags)
+
+**Source:** `src/rfc/is-bcp-47.ts`
+
+Validates language tags according to [BCP 47](https://tools.ietf.org/rfc/bcp/bcp47.html) (RFC 5646 + RFC 4647).
+
+The validator integrates the `bcp-47` npm package. It parses the value and checks that either a valid `language` subtag or a `privateuse` subtag (e.g., `x-default`) is present:
+
+```typescript
+// src/rfc/is-bcp-47.ts
+export const isBCP47: FormattedPrimitiveTypeCreator = () => {
+  return value => {
+    const { language, privateuse } = parse(value);
+    return !!language || (privateuse != null && privateuse.length > 0);
+  };
+};
+```
+
+This is registered in `defs.ts` as the `BCP47` type, used for the `lang` and `hreflang` attributes on HTML elements.
+
+---
+
+## W3C Validators
+
+### Serialized Permissions Policy
+
+**Source:** `src/w3c/check-serialized-permissions-policy.ts`
+
+Validates serialized permissions policy strings according to the [W3C Permissions Policy specification](https://w3c.github.io/webappsec-permissions-policy/#serialized-permissions-policy).
+
+The validator parses the ABNF grammar:
+
+```abnf
+serialized-permissions-policy = serialized-policy-directive *(";" serialized-policy-directive)
+serialized-policy-directive   = feature-identifier [RWS allow-list]
+feature-identifier            = 1*( ALPHA / DIGIT / "-")
+allow-list                    = allow-list-value *(RWS allow-list-value)
+allow-list-value              = serialized-origin / "*" / "'self'" / "'src'" / "'none'"
+```
+
+> **Note:** The ABNF above reflects the implementation's grammar, which makes `allow-list` optional (`[RWS allow-list]`). The W3C specification defines `serialized-policy-directive = feature-identifier RWS allow-list` with a mandatory `allow-list`. This deviation is intentional -- the implementation accepts feature identifiers without an explicit allow-list.
+
+Key validation steps:
+
+1. Splits the value on `;` into policy directives
+2. For each directive, extracts the feature identifier and validates it matches `/^[\da-z-]+$/i`
+3. For each allow-list value, checks against the keywords `*`, `'self'`, `'src'`, `'none'`, or validates as a serialized origin
+4. Serialized origins are validated using the `URL` constructor, rejecting pathnames, queries, hashes, usernames, passwords, and characters that must be percent-encoded (`'`, `*`, `,`, `;`)
+
+---
+
+## Adding New Validators
+
+Follow these steps to add a new validator to the system.
+
+### Step 1: Create the Validator File
+
+Place the file in the appropriate directory based on the specification:
+
+- `src/primitive/` for basic format checks
+- `src/whatwg/` for WHATWG HTML spec validators
+- `src/rfc/` for RFC-defined formats
+- `src/w3c/` for W3C specification formats
+
+**Template for a `FormattedPrimitiveTypeCreator`:**
+
+```typescript
+// src/whatwg/is-my-format.ts
+import type { FormattedPrimitiveTypeCreator } from '../types.js';
+
+/**
+ * Checks whether a string is a valid my-format value.
+ *
+ * @see https://spec.example.org/my-format
+ */
+export const isMyFormat: FormattedPrimitiveTypeCreator = () => {
+  return value => {
+    // Validation logic returning boolean
+    return /^[a-z]+-[a-z]+$/.test(value);
+  };
+};
+```
+
+**Template for a `CustomSyntaxChecker`:**
+
+```typescript
+// src/whatwg/check-my-syntax.ts
+import type { CustomSyntaxChecker } from '../types.js';
+
+import { matched, unmatched } from '../match-result.js';
+
+/**
+ * Validates a my-syntax value.
+ *
+ * @see https://spec.example.org/my-syntax
+ */
+export const checkMySyntax: CustomSyntaxChecker = () => value => {
+  if (!value) {
+    return unmatched(value, 'empty-token');
+  }
+  // Validation logic returning Result
+  return matched();
+};
+```
+
+### Step 2: Export from the Directory Index
+
+If you placed the validator in a directory with an `index.ts`, add the export:
+
+```typescript
+// src/primitive/index.ts
+export { isMyFormat } from './is-my-format.js';
+```
+
+### Step 3: Register in defs.ts
+
+Import the validator and add it to the `defs` object:
+
+```typescript
+// src/defs.ts
+import { isMyFormat } from './whatwg/is-my-format.js';
+// or
+import { checkMySyntax } from './whatwg/check-my-syntax.js';
+
+export const defs: Defs = {
+  // ... existing definitions ...
+
+  // For FormattedPrimitiveTypeCreator (wrap with matches()):
+  MyFormat: {
+    ref: 'https://spec.example.org/my-format',
+    expects: [
+      {
+        type: 'format',
+        value: 'my format',
+      },
+    ],
+    is: matches(isMyFormat()),
+  },
+
+  // For CustomSyntaxChecker (use directly):
+  MySyntax: {
+    ref: 'https://spec.example.org/my-syntax',
+    expects: [
+      {
+        type: 'format',
+        value: 'my syntax',
+      },
+    ],
+    is: checkMySyntax(),
+  },
+};
+```
+
+### Step 4: Add Tests
+
+Create a test file alongside the validator:
+
+```typescript
+// src/whatwg/is-my-format.spec.ts
+import { isMyFormat } from './is-my-format.js';
+
+const check = isMyFormat();
+
+test('valid values', () => {
+  expect(check('foo-bar')).toBe(true);
+  expect(check('hello-world')).toBe(true);
+});
+
+test('invalid values', () => {
+  expect(check('')).toBe(false);
+  expect(check('UPPER-CASE')).toBe(false);
+});
+```
+
+### Concrete Example: Adding a Hypothetical `isDataURL` Validator
+
+Suppose you need to validate `data:` URLs specifically.
+
+**1. Create the file:**
+
+```typescript
+// src/whatwg/is-data-url.ts
+import type { FormattedPrimitiveTypeCreator } from '../types.js';
+
+/**
+ * Checks whether a string is a valid data URL.
+ *
+ * @see https://fetch.spec.whatwg.org/#data-urls
+ */
+export const isDataURL: FormattedPrimitiveTypeCreator = () => {
+  return value => {
+    return /^data:[^,]*,/.test(value);
+  };
+};
+```
+
+**2. Register in `defs.ts`:**
+
+```typescript
+import { isDataURL } from './whatwg/is-data-url.js';
+
+// Inside the defs object:
+DataURL: {
+  ref: 'https://fetch.spec.whatwg.org/#data-urls',
+  expects: [
+    {
+      type: 'format',
+      value: 'data URL',
+    },
+  ],
+  is: matches(isDataURL()),
+},
+```
+
+**3. Add tests:**
+
+```typescript
+// src/whatwg/is-data-url.spec.ts
+import { isDataURL } from './is-data-url.js';
+
+const check = isDataURL();
+
+test('valid data URLs', () => {
+  expect(check('data:text/plain,Hello')).toBe(true);
+  expect(check('data:text/html,<h1>Hello</h1>')).toBe(true);
+  expect(check('data:image/png;base64,abc123...')).toBe(true);
+});
+
+test('invalid data URLs', () => {
+  expect(check('https://example.com')).toBe(false);
+  expect(check('data:')).toBe(false);
+});
+```

package/lib/check-base.d.ts

@@ -1,10 +1,90 @@
-import type { Type, Result, List, CustomSyntax, CustomCssSyntax, Enum, KeywordDefinedType, Number, Directive, Defs } from './types.js';
+import type { Type, Result, List, CustomSyntax, CustomCssSyntax, Enum, KeywordDefinedType, Number, Directive, Pattern, Defs } from './types.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Validates a string value against a specified type definition using the provided
+ * set of custom type definitions. This is the core type-checking dispatcher that
+ * routes validation to the appropriate checker based on the type's structure
+ * (keyword, list, enum, number, or directive).
+ *
+ * @param value - The string value to validate
+ * @param type - The type definition to validate against
+ * @param defs - A map of custom type definitions (both CSS syntax and custom syntax) used for resolving keyword types
+ * @param ref - An optional reference identifier used for error reporting context
+ * @param cache - Whether to use cached results for repeated checks with the same inputs
+ * @returns A result indicating whether the value matches the type, or details about the mismatch
+ * @throws Error if the type does not match any known type structure
+ */
 export declare function checkBase(value: string, type: ReadonlyDeep<Type>, defs: Defs, ref?: string, cache?: boolean): Result;
+/**
+ * Determines whether a type definition is a keyword-based type.
+ * Keyword types are represented as plain strings (e.g., CSS syntax names
+ * like `"<color>"` or extended types like `"URL"`).
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a keyword-defined type string
+ */
 export declare function isKeyword(type: ReadonlyDeep<Type>): type is ReadonlyDeep<KeywordDefinedType>;
+/**
+ * Determines whether a type definition represents a list type.
+ * List types define space-separated or comma-separated token sequences
+ * and are identified by having a `separator` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a list definition
+ */
 export declare function isList(type: ReadonlyDeep<Type>): type is ReadonlyDeep<List>;
+/**
+ * Determines whether a type definition represents an enumerated type.
+ * Enum types define a fixed set of allowed string values and are
+ * identified by having an `enum` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is an enum definition
+ */
 export declare function isEnum(type: ReadonlyDeep<Type>): type is ReadonlyDeep<Enum>;
+/**
+ * Determines whether a type definition represents a numeric type.
+ * Number types specify either `float` or `integer` validation with
+ * optional range constraints, and are identified by having a `type`
+ * property set to one of those values.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a number definition
+ */
 export declare function isNumber(type: ReadonlyDeep<Type>): type is ReadonlyDeep<Number>;
+/**
+ * Determines whether a type definition represents a directive type.
+ * Directive types allow separating and individually validating parts of
+ * an attribute value, and are identified by having a `directive` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a directive definition
+ */
 export declare function isDirective(type: ReadonlyDeep<Type>): type is ReadonlyDeep<Directive>;
+/**
+ * Determines whether a type definition represents a pattern type.
+ * Pattern types validate attribute values against a regular expression
+ * or plain string, and are identified by having a `pattern` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a pattern definition
+ */
+export declare function isPattern(type: ReadonlyDeep<Type>): type is ReadonlyDeep<Pattern>;
+/**
+ * Determines whether a custom type definition uses CSS syntax matching.
+ * CSS syntax definitions are either plain strings or objects with a `syntax`
+ * property that specifies CSS value definition syntax for matching.
+ *
+ * @param type - The custom type definition to test
+ * @returns True if the definition uses CSS syntax matching
+ */
 export declare function isCSSSyntax(type: CustomSyntax | CustomCssSyntax): type is CustomCssSyntax;
+/**
+ * Determines whether a custom type definition uses a programmatic custom
+ * syntax checker rather than CSS syntax matching. This is the inverse
+ * of {@link isCSSSyntax}.
+ *
+ * @param type - The custom type definition to test
+ * @returns True if the definition uses a custom programmatic checker function
+ */
 export declare function isCustomSyntax(type: CustomSyntax | CustomCssSyntax): type is CustomSyntax;