@markuplint/types 4.8.1 → 4.8.2

package/lib/token/token.js

@@ -1,3 +1,10 @@
+/**
+ * Represents a single token within a parsed string value.
+ *
+ * Tracks the token's value, type (whitespace, comma, or identifier),
+ * offset position within the original string, and provides methods
+ * for matching and comparison operations.
+ */
 export class Token {
     /**
      * @deprecated Use {@link getPosition} instead. Will be removed in v5.0.0.
@@ -12,12 +19,26 @@ export class Token {
     static getLine(value, offset) {
         return value.slice(0, offset).split(/\n/).length;
     }
+    /**
+     * Calculates the line and column position at the given offset within a string.
+     *
+     * @param value - The source string
+     * @param offset - The character offset to calculate the position for
+     * @returns The line number (1-based) and column number (1-based)
+     */
     static getPosition(value, offset) {
         const lines = value.slice(0, offset).split(/\n/);
         const line = lines.length;
         const column = (lines.at(-1) ?? '').length + 1;
         return { line, column };
     }
+    /**
+     * Determines the token type based on the first character.
+     *
+     * @param value - The token string value
+     * @param separators - Optional separator characters to detect
+     * @returns The token type number (WhiteSpace, Comma, or Ident)
+     */
     static getType(value, separators) {
         if (Token.whitespace.includes(value[0] ?? '')) {
             return Token.WhiteSpace;
@@ -31,6 +52,13 @@ export class Token {
         }
         return Token.Ident;
     }
+    /**
+     * Calculates a new position by shifting from a token's offset.
+     *
+     * @param token - The base token to shift from
+     * @param offset - The additional offset to apply
+     * @returns The shifted offset, line, and column
+     */
     static shiftLocation(token, offset) {
         const shifted = token.offset + offset;
         const { line, column } = Token.getPosition(token.originalValue, shifted);
@@ -40,21 +68,38 @@ export class Token {
             column,
         };
     }
+    /**
+     * @param value - The token string value
+     * @param offset - The offset position within the original string
+     * @param originalValue - The complete original string this token was parsed from
+     * @param separators - Optional separator characters used for type detection
+     */
     constructor(value, offset, originalValue, separators) {
         this.type = Token.getType(value, separators);
         this.value = value;
         this.offset = offset;
         this.originalValue = originalValue;
     }
+    /**
+     * The character length of the token value.
+     */
     get length() {
         return this.value.length;
     }
+    /**
+     * Creates a copy of this token.
+     *
+     * @returns A new Token instance with the same value, offset, and original value
+     */
     clone() {
         return new Token(this.value, this.offset, this.originalValue);
     }
     /**
+     * Checks whether this token's value contains the given value.
      *
-     * @param value The token value or the token type or its list
+     * @param value - The token value, type number, regex, or array to check against
+     * @param caseInsensitive - Whether to perform case-insensitive comparison
+     * @returns Whether this token includes the given value
      */
     includes(value, caseInsensitive) {
         if (Array.isArray(value)) {
@@ -72,8 +117,11 @@ export class Token {
         return this.type === value;
     }
     /**
+     * Checks whether this token exactly matches the given value.
      *
-     * @param value The token value or the token type or its list
+     * @param value - The token value, type number, regex, or array to match against
+     * @param caseInsensitive - Whether to perform case-insensitive comparison
+     * @returns Whether this token matches the given value
      */
     matches(value, caseInsensitive) {
         if (Array.isArray(value)) {
@@ -90,6 +138,11 @@ export class Token {
         }
         return this.type === value;
     }
+    /**
+     * Converts this token to a plain JSON-serializable object.
+     *
+     * @returns An object with type, value, and offset properties
+     */
     toJSON() {
         return {
             type: this.type,
@@ -97,10 +150,21 @@ export class Token {
             offset: this.offset,
         };
     }
+    /**
+     * Parses the token value as a floating-point number.
+     *
+     * @returns The parsed number, or 0 if parsing fails
+     */
     toNumber() {
         const num = Number.parseFloat(this.value);
         return Number.isNaN(num) ? 0 : num;
     }
+    /**
+     * Creates an unmatched result positioned at this token's location.
+     *
+     * @param options - Optional settings including ref, reason, and expected values
+     * @returns An unmatched result with this token's position information
+     */
     unmatched(options) {
         const { line, column } = Token.getPosition(this.originalValue, this.offset);
         return {

package/lib/token/types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A single token value: a literal string, a regular expression pattern, or a token type number.
+ */
 export type TokenValueScalar = string | Readonly<RegExp> | number;
+/**
+ * An array of token values for matching against multiple patterns.
+ */
 export type TokenValueArray = readonly TokenValue[];
+/**
+ * A token value used for matching: either a scalar or an array of token values.
+ */
 export type TokenValue = TokenValueScalar | TokenValueArray;

package/lib/types.d.ts

@@ -1,6 +1,26 @@
 import type { cssSyntaxMatch } from './css-syntax.js';
+/**
+ * Re-exported types from the auto-generated schema definitions.
+ *
+ * - `Type` - Union of all possible type definitions (keyword, list, enum, number, directive)
+ * - `List` - Defines space-separated or comma-separated token sequences
+ * - `Enum` - Defines a fixed set of allowed string values
+ * - `CssSyntax` - String literal union of all recognized CSS value definition syntax names
+ * - `KeywordDefinedType` - Union of CSS syntax, extended types, and HTML attribute requirements
+ * - `Number` - Defines numeric validation with optional range constraints
+ * - `Directive` - Defines composite attribute values with separators and individual token validation
+ */
 export type { Type, List, Enum, CssSyntax, KeywordDefinedType, Number, Directive } from './types.schema.js';
+/**
+ * The outcome of a type validation check. Either a successful match
+ * or a detailed mismatch containing error location and reason.
+ */
 export type Result = UnmatchedResult | MatchedResult;
+/**
+ * Represents a failed type validation result. Contains detailed information
+ * about what went wrong, including the position within the input string
+ * where the mismatch occurred and the specific reason for the failure.
+ */
 export type UnmatchedResult = {
     readonly matched: false;
     readonly ref: string | null;
@@ -12,6 +32,11 @@ export type UnmatchedResult = {
     readonly reason: UnmatchedResultReason;
     readonly passCount?: number;
 } & UnmatchedResultOptions;
+/**
+ * Optional metadata attached to an unmatched result, providing additional
+ * context such as the part of the value that failed, what was expected,
+ * and potential corrections or fallbacks.
+ */
 export type UnmatchedResultOptions = {
     readonly partName?: string;
     readonly expects?: readonly Expect[];
@@ -19,6 +44,12 @@ export type UnmatchedResultOptions = {
     readonly candidate?: string;
     readonly fallbackTo?: string;
 };
+/**
+ * Describes the specific reason a type validation failed. Can be a simple
+ * string identifier for common failure modes (e.g., `'syntax-error'`,
+ * `'typo'`, `'out-of-range'`) or a structured object for range violations
+ * that includes the boundary values.
+ */
 export type UnmatchedResultReason = 'syntax-error' | 'typo' | 'missing-token' | 'missing-comma' | 'unexpected-token' | 'unexpected-space' | 'unexpected-newline' | 'unexpected-comma' | 'empty-token' | 'out-of-range' | 'doesnt-exist-in-enum' | 'duplicated' | 'illegal-combination' | 'illegal-order' | 'extra-token' | 'must-be-percent-encoded' | 'must-be-serialized' | {
     readonly type: 'out-of-range';
     readonly gt?: number;
@@ -34,23 +65,76 @@ export type UnmatchedResultReason = 'syntax-error' | 'typo' | 'missing-token' |
     readonly gte: number;
     readonly lte?: number;
 };
+/**
+ * Represents a successful type validation result, indicating that the
+ * checked value conforms to the specified type definition.
+ */
 export type MatchedResult = {
     readonly matched: true;
 };
+/**
+ * Describes an expected value or format that the input should conform to.
+ * Used in error reporting to communicate what the validator anticipated.
+ */
 export type Expect = {
     readonly type: 'const' | 'format' | 'syntax' | 'regexp' | 'common';
     readonly value: string;
 };
+/**
+ * A predicate function that checks whether a string value conforms
+ * to a specific primitive type format (e.g., a valid custom element name).
+ *
+ * @param value - The string value to check
+ * @returns True if the value is valid for the primitive type
+ */
 export type FormattedPrimitiveTypeCheck = (value: string) => boolean;
+/**
+ * A factory function that creates a {@link FormattedPrimitiveTypeCheck} predicate,
+ * optionally configured with the given options.
+ *
+ * @template O - The type of the optional configuration object passed to the factory
+ * @param options - Optional configuration for the created checker
+ * @returns A predicate function that validates strings against the primitive type
+ */
 export type FormattedPrimitiveTypeCreator<O = never> = (options?: O) => FormattedPrimitiveTypeCheck;
+/**
+ * A read-only map of type definition names to their corresponding custom
+ * syntax or CSS syntax definitions. Used by the type checker to resolve
+ * keyword types during validation.
+ */
 export type Defs = Readonly<Record<string, CustomCssSyntax | CustomSyntax>>;
+/**
+ * Defines a custom type using a programmatic checker function.
+ * Unlike CSS syntax definitions, custom syntax types use an imperative
+ * `is` function to validate values.
+ */
 export type CustomSyntax = {
     readonly ref: string;
     readonly expects?: readonly Expect[];
     readonly is: CustomSyntaxCheck;
 };
+/**
+ * A function that validates a string value against a custom syntax rule
+ * and returns a detailed result indicating match or mismatch.
+ *
+ * @param value - The string value to validate
+ * @returns A result indicating whether the value matches the custom syntax
+ */
 export type CustomSyntaxCheck = (value: string) => Result;
+/**
+ * A factory function that creates a {@link CustomSyntaxCheck} validator,
+ * optionally configured with the given options.
+ *
+ * @template O - The type of the optional configuration object passed to the factory
+ * @param options - Optional configuration for the created checker
+ * @returns A function that validates strings against the custom syntax
+ */
 export type CustomSyntaxChecker<O = {}> = (options?: O) => CustomSyntaxCheck;
+/**
+ * Defines a custom type using CSS value definition syntax for matching.
+ * The `syntax` property specifies the CSS grammar to apply, along with
+ * any supplementary definitions needed for parsing.
+ */
 export type CustomCssSyntax = {
     readonly ref: string;
     readonly caseSensitive?: boolean;
@@ -68,6 +152,11 @@ export type CustomCssSyntax = {
         readonly properties?: Readonly<Record<string, string>>;
     };
 };
+/**
+ * Represents a single token produced by the CSS syntax tokenizer.
+ * Each token captures its type, raw string value, position within
+ * the input, and a balance index for matching paired delimiters.
+ */
 export type CSSSyntaxToken = {
     readonly type: number;
     readonly value: string;
@@ -75,5 +164,23 @@ export type CSSSyntaxToken = {
     readonly balance: number;
     readonly node?: any;
 };
+/**
+ * A custom tokenizer function used within CSS syntax definitions to
+ * perform token-level matching. It receives the current token, a
+ * function to peek ahead in the token stream, and the CSS syntax
+ * match utility.
+ *
+ * @param token - The current CSS syntax token to inspect, or null if at end of input
+ * @param getNextToken - A lookahead function that retrieves a token at the given offset
+ * @param match - The CSS syntax matching function for recursive grammar matching
+ * @returns The number of tokens consumed by this tokenizer (0 if no match)
+ */
 export type CssSyntaxTokenizer = (token: Readonly<CSSSyntaxToken> | null, getNextToken: GetNextToken, match: typeof cssSyntaxMatch) => number;
+/**
+ * A lookahead function that retrieves a CSS syntax token at a given
+ * offset from the current position in the token stream.
+ *
+ * @param length - The offset (number of tokens ahead) to look up
+ * @returns The token at the given offset, or null if beyond the end of the token stream
+ */
 export type GetNextToken = (length: number) => CSSSyntaxToken | null;

package/lib/w3c/check-serialized-permissions-policy.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../types.js';
 /**
+ * Validates a serialized permissions policy string according to the W3C specification.
+ *
  * @see https://w3c.github.io/webappsec-permissions-policy/#serialized-permissions-policy
  *
  * > Policy Directives in HTML attributes are represented as their

package/lib/w3c/check-serialized-permissions-policy.js

@@ -2,6 +2,8 @@ import { log } from '../debug.js';
 import { matched, unmatched } from '../match-result.js';
 import { TokenCollection } from '../token/index.js';
 /**
+ * Validates a serialized permissions policy string according to the W3C specification.
+ *
  * @see https://w3c.github.io/webappsec-permissions-policy/#serialized-permissions-policy
  *
  * > Policy Directives in HTML attributes are represented as their

package/lib/whatwg/check-autocomplete.d.ts

@@ -1,5 +1,10 @@
 import type { CustomSyntaxChecker } from '../types.js';
 /**
+ * Validates the `autocomplete` attribute value according to the WHATWG specification.
+ *
+ * Supports "on"/"off" keywords, optional named groups (`section-*`),
+ * address parts (shipping/billing), contacting tokens, and autofill field names.
+ *
  * @see https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-autocomplete
  */
 export declare const checkAutoComplete: CustomSyntaxChecker;

package/lib/whatwg/check-autocomplete.js

@@ -90,6 +90,11 @@ const URL_PART_OF_ADDRESS = 'https://html.spec.whatwg.org/multipage/form-control
 const URL_AUTOFILL_FIELD = 'https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-field';
 const URL_CONTACTABLE_FIELD = 'https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofilling-form-controls:-the-autocomplete-attribute:attr-fe-autocomplete-tel';
 /**
+ * Validates the `autocomplete` attribute value according to the WHATWG specification.
+ *
+ * Supports "on"/"off" keywords, optional named groups (`section-*`),
+ * address parts (shipping/billing), contacting tokens, and autofill field names.
+ *
  * @see https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-autocomplete
  */
 export const checkAutoComplete = () => value => {
@@ -195,6 +200,7 @@ export const checkAutoComplete = () => value => {
         }
     }
     if (head.matches(contactingTokens, true)) {
+        // eslint-disable-next-line no-useless-assignment
         hasContactingToken = true;
         const contactableFiledToken = tail[0];
         if (!contactableFiledToken) {

package/lib/whatwg/check-datetime/date-string.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a date string in the format `YYYY-MM-DD`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates
  */
 export declare const checkDateString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/date-string.js

@@ -2,6 +2,8 @@ import { log } from '../../debug.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a date string in the format `YYYY-MM-DD`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates
  */
 export const checkDateString = () => function checkDateString(value) {

package/lib/whatwg/check-datetime/datetime-tokens.d.ts

@@ -1,3 +1,16 @@
 import type { TokenEachCheck } from '../../token/token-collection.js';
+/**
+ * Collection of token check functions for datetime component validation.
+ *
+ * Each property is a {@link TokenEachCheck} function that validates a specific
+ * datetime component (year, month, date, hour, minute, second, etc.)
+ * according to the WHATWG specification.
+ */
 export declare const datetimeTokenCheck: Record<'year' | 'month' | 'date' | 'hour' | 'minute' | 'second' | 'secondFractionalPart' | 'week' | 'hyphen' | 'colon' | 'extra' | 'colonOrEnd' | 'decimalPointOrEnd' | 'localDateTimeSeparator' | 'normalizedlocalDateTimeSeparator' | 'plusOrMinusSign' | 'weekSign', TokenEachCheck> & Record<'_year' | '_month', number | null>;
+/**
+ * Calculates the maximum ISO week number for a given year.
+ *
+ * @param year - The year to calculate for
+ * @returns The maximum week number (52 or 53) for the year
+ */
 export declare function getMaxWeekNum(year: number): number;

package/lib/whatwg/check-datetime/datetime-tokens.js

@@ -1,5 +1,12 @@
 import { log } from '../../debug.js';
 import { matched, unmatched } from '../../match-result.js';
+/**
+ * Collection of token check functions for datetime component validation.
+ *
+ * Each property is a {@link TokenEachCheck} function that validates a specific
+ * datetime component (year, month, date, hour, minute, second, etc.)
+ * according to the WHATWG specification.
+ */
 export const datetimeTokenCheck = {
     /**
      * Temporary year state
@@ -489,6 +496,12 @@ const daysOfMonth = [
     // 12
     31,
 ];
+/**
+ * Calculates the maximum ISO week number for a given year.
+ *
+ * @param year - The year to calculate for
+ * @returns The maximum week number (52 or 53) for the year
+ */
 export function getMaxWeekNum(year) {
     let date = 31;
     while (date > 0) {

package/lib/whatwg/check-datetime/duration-string.d.ts

@@ -1,6 +1,13 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a duration string in ISO 8601-like format (e.g., `PT1H30M`).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations
  */
 export declare const checkDurationISO8601LikeString: CustomSyntaxChecker;
+/**
+ * Validates a duration string in component list format (e.g., `1h 30m 5s`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations
+ */
 export declare const checkDurationComponentListString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/duration-string.js

@@ -3,6 +3,8 @@ import { matched, unmatched } from '../../match-result.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a duration string in ISO 8601-like format (e.g., `PT1H30M`).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations
  */
 export const checkDurationISO8601LikeString = () => function checkDurationISO8601LikeString(value) {
@@ -201,6 +203,11 @@ export const checkDurationISO8601LikeString = () => function checkDurationISO860
     }
     return res;
 };
+/**
+ * Validates a duration string in component list format (e.g., `1h 30m 5s`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations
+ */
 export const checkDurationComponentListString = () => function checkDurationComponentListString(value) {
     log('CHECK: duration-string (duration component list)');
     if (!value) {

package/lib/whatwg/check-datetime/global-date-and-time-string.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a global date and time string (date + time + time-zone offset).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#global-dates-and-times
  */
 export declare const checkGlobalDateAndTimeString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/global-date-and-time-string.js

@@ -4,6 +4,8 @@ import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 import { parseTimeZone } from './time-zone-offset-string.js';
 /**
+ * Validates a global date and time string (date + time + time-zone offset).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#global-dates-and-times
  */
 export const checkGlobalDateAndTimeString = () => function checkGlobalDateAndTimeString(value) {

package/lib/whatwg/check-datetime/index.d.ts

@@ -1,5 +1,10 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a datetime string against all WHATWG date and time formats.
+ *
+ * Tries each format (date, time, month, yearless date, local/global date-time,
+ * time-zone offset, week, year, and duration strings) and returns the best match.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates-and-times
  */
 export declare const checkDateTime: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/index.js

@@ -24,6 +24,11 @@ const checks = [
     checkDurationComponentListString(),
 ];
 /**
+ * Validates a datetime string against all WHATWG date and time formats.
+ *
+ * Tries each format (date, time, month, yearless date, local/global date-time,
+ * time-zone offset, week, year, and duration strings) and returns the best match.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates-and-times
  */
 export const checkDateTime = () => value => {

package/lib/whatwg/check-datetime/local-date-and-time-string.d.ts

@@ -1,9 +1,13 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a local date and time string (date + `T` or space + time, no time-zone).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-local-date-and-time-string
  */
 export declare const checkLocalDateAndTimeString: CustomSyntaxChecker;
 /**
+ * Validates a normalized local date and time string (uses `T` separator only, omits zero seconds).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-normalised-local-date-and-time-string
  */
 export declare const checkNormalizedLocalDateAndTimeString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/local-date-and-time-string.js

@@ -2,6 +2,8 @@ import { log } from '../../debug.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a local date and time string (date + `T` or space + time, no time-zone).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-local-date-and-time-string
  */
 export const checkLocalDateAndTimeString = () => function checkLocalDateAndTimeString(value) {
@@ -42,6 +44,8 @@ export const checkLocalDateAndTimeString = () => function checkLocalDateAndTimeS
     return res;
 };
 /**
+ * Validates a normalized local date and time string (uses `T` separator only, omits zero seconds).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-normalised-local-date-and-time-string
  */
 export const checkNormalizedLocalDateAndTimeString = () => function checkNormalizedLocalDateAndTimeString(value) {

package/lib/whatwg/check-datetime/month-string.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a month string in the format `YYYY-MM`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-month-string
  */
 export declare const checkMonthString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/month-string.js

@@ -2,6 +2,8 @@ import { log } from '../../debug.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a month string in the format `YYYY-MM`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-month-string
  */
 export const checkMonthString = () => function checkMonthString(value) {

package/lib/whatwg/check-datetime/time-string.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a time string in the format `HH:MM[:SS[.sss]]`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#times
  */
 export declare const checkTimeString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/time-string.js

@@ -2,6 +2,8 @@ import { log } from '../../debug.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a time string in the format `HH:MM[:SS[.sss]]`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#times
  */
 export const checkTimeString = () => function checkTimeString(value) {

package/lib/whatwg/check-datetime/time-zone-offset-string.d.ts

@@ -1,7 +1,15 @@
 import type { Token } from '../../token/index.js';
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a time-zone offset string (`Z`, `+HH:MM`, or `-HH:MM`).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#time-zones
  */
 export declare const checkTimeZoneOffsetString: CustomSyntaxChecker;
+/**
+ * Parses and validates a time-zone offset string (e.g., `Z`, `+09:00`, `-05:30`).
+ *
+ * @param zone - The time-zone string or token to validate
+ * @returns The validation result
+ */
 export declare function parseTimeZone(zone: string | Readonly<Token>): import("../../types.js").Result;

package/lib/whatwg/check-datetime/time-zone-offset-string.js

@@ -3,12 +3,20 @@ import { matched, unmatched } from '../../match-result.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a time-zone offset string (`Z`, `+HH:MM`, or `-HH:MM`).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#time-zones
  */
 export const checkTimeZoneOffsetString = () => function checkTimeZoneOffsetString(value) {
     log('CHECK: time-zone-offset-string');
     return parseTimeZone(value);
 };
+/**
+ * Parses and validates a time-zone offset string (e.g., `Z`, `+09:00`, `-05:30`).
+ *
+ * @param zone - The time-zone string or token to validate
+ * @returns The validation result
+ */
 export function parseTimeZone(zone) {
     const value = typeof zone === 'string' ? zone : zone.value;
     const zoneTokens = TokenCollection.fromPatterns(zone, [

package/lib/whatwg/check-datetime/week-string.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a week string in the format `YYYY-Www`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#weeks
  */
 export declare const checkWeekString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/week-string.js

@@ -2,6 +2,8 @@ import { log } from '../../debug.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a week string in the format `YYYY-Www`.
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#weeks
  */
 export const checkWeekString = () => function checkWeekString(value) {

package/lib/whatwg/check-datetime/year-string.d.ts

@@ -1,5 +1,7 @@
 import type { CustomSyntaxChecker } from '../../types.js';
 /**
+ * Validates a year string (four or more digits, greater than zero).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html
  */
 export declare const checkYearString: CustomSyntaxChecker;

package/lib/whatwg/check-datetime/year-string.js

@@ -2,6 +2,8 @@ import { log } from '../../debug.js';
 import { TokenCollection } from '../../token/index.js';
 import { datetimeTokenCheck } from './datetime-tokens.js';
 /**
+ * Validates a year string (four or more digits, greater than zero).
+ *
  * @see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html
  */
 export const checkYearString = () => function checkYearString(value) {