@markuplint/types 5.0.0-rc.2 → 5.0.0-rc.5

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

@@ -4,8 +4,6 @@ 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) {
@@ -29,8 +27,10 @@ export const checkGlobalDateAndTimeString = () => function checkGlobalDateAndTim
         /\D?/,
         // mm
         /[^+:Z-]*/,
-        // :ss.sss
-        /(:[^+Z-]*)?/,
+        // :ss.sss — restricted to digits and the decimal point so that an
+        // invalid fraction separator (e.g. `,`) is left in the timezone
+        // segment, where `parseTimeZone` rejects it.
+        /(:[\d.]*)?/,
         // time-zone
         /.*/,
     ]);

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

@@ -1,10 +1,5 @@
 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,11 +24,6 @@ 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,13 +1,9 @@
 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,8 +2,6 @@ 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) {
@@ -44,8 +42,6 @@ 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,7 +1,5 @@
 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,8 +2,6 @@ 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,7 +1,5 @@
 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,8 +2,6 @@ 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,15 +1,7 @@
 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,20 +3,12 @@ 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,7 +1,5 @@
 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,8 +2,6 @@ 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,7 +1,5 @@
 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,8 +2,6 @@ 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) {

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

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

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

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

package/lib/whatwg/check-email.js

@@ -1,6 +1,4 @@
 /**
- * Checks whether a string is a valid email address per the HTML spec.
- *
  * The regex below is the **verbatim** pattern from the HTML Living Standard.
  * It intentionally uses explicit ASCII ranges (`[a-zA-Z0-9]`) instead of `\w`
  * because the spec restricts valid characters to ASCII only. `\w` is equivalent

package/lib/whatwg/check-http-equiv-content-type.d.ts

@@ -0,0 +1,12 @@
+import type { CustomSyntaxChecker } from '../types.js';
+/**
+ * Validates the `content` attribute value of `<meta http-equiv="content-type">`
+ * against the HTML Living Standard §4.2.5.2 "Encoding declaration" grammar:
+ *
+ *   ASCII case-insensitive "text/html;"
+ *   , optionally ASCII whitespace
+ *   , "charset=utf-8"
+ *
+ * @see https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-content-type
+ */
+export declare const checkHTTPEquivContentType: CustomSyntaxChecker;

package/lib/whatwg/check-http-equiv-content-type.js

@@ -0,0 +1,32 @@
+import { log } from '../debug.js';
+import { matched, unmatched } from '../match-result.js';
+// HTML LS's Encoding declaration state requires the literal string
+// "charset=utf-8" — not an arbitrary Encoding LS label. Unlike the
+// `charset` content attribute (a plain `enum: ["utf-8"]` in
+// spec.meta.jsonc), this value is free-form text, so the literal is
+// enforced here via regex instead.
+const CONTENT_TYPE_RE = /^text\/html;[\t\n\f\r ]*charset=utf-8$/i;
+/**
+ * Validates the `content` attribute value of `<meta http-equiv="content-type">`
+ * against the HTML Living Standard §4.2.5.2 "Encoding declaration" grammar:
+ *
+ *   ASCII case-insensitive "text/html;"
+ *   , optionally ASCII whitespace
+ *   , "charset=utf-8"
+ *
+ * @see https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-content-type
+ */
+export const checkHTTPEquivContentType = () => function checkHTTPEquivContentType(value) {
+    log('CHECK: meta http-equiv="content-type" content');
+    if (!CONTENT_TYPE_RE.test(value)) {
+        return unmatched(value, 'syntax-error', {
+            expects: [
+                {
+                    type: 'format',
+                    value: 'text/html; charset=<encoding>',
+                },
+            ],
+        });
+    }
+    return matched();
+};

package/lib/whatwg/check-http-equiv-refresh.d.ts

@@ -0,0 +1,21 @@
+import type { CustomSyntaxChecker } from '../types.js';
+/**
+ * Validates the `content` attribute value of `<meta http-equiv="refresh">`
+ * against the HTML Living Standard §4.2.5.3 "Refresh" conformance grammar.
+ *
+ * The grammar (distinct from the more lenient parse algorithm browsers use
+ * to execute the refresh):
+ *
+ * 1. Optionally, ASCII whitespace.
+ * 2. A valid non-negative integer.
+ * 3. Optionally:
+ *    1. Either a ";" (U+003B) or a "," (U+002C).
+ *    2. Optionally, ASCII whitespace.
+ *    3. Either:
+ *       - An ASCII case-insensitive match for "URL", followed by "=",
+ *         followed by a valid URL potentially surrounded by spaces.
+ *       - A valid URL potentially surrounded by spaces.
+ *
+ * @see https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-refresh
+ */
+export declare const checkHTTPEquivRefresh: CustomSyntaxChecker;

package/lib/whatwg/check-http-equiv-refresh.js

@@ -0,0 +1,106 @@
+import { log } from '../debug.js';
+import { matched, unmatched } from '../match-result.js';
+import { checkURL } from './check-url.js';
+// `ASCII whitespace` per Infra: TAB, LF, FF, CR, SPACE.
+// https://infra.spec.whatwg.org/#ascii-whitespace
+const ASCII_WHITESPACE = /[\t\n\f\r ]/;
+// `ASCII digit` per Infra. `\d` happens to match the same set today in
+// JavaScript regexes, but the HTML LS grammar is specific to U+0030–U+0039,
+// so we pin the class to that range to protect against accidental Unicode
+// broadening if the `u` flag or a future regex flavour drifts it.
+// oxlint: use-the-regex-literal-shorthand warns on `[0-9]`; suppress here so
+// the spec intent survives auto-fix passes.
+// eslint-disable-next-line regexp/prefer-d
+const ASCII_DIGIT = /[0-9]/;
+function isAsciiWhitespace(ch) {
+    return ASCII_WHITESPACE.test(ch);
+}
+function isAsciiDigit(ch) {
+    return ASCII_DIGIT.test(ch);
+}
+/**
+ * Validates the `content` attribute value of `<meta http-equiv="refresh">`
+ * against the HTML Living Standard §4.2.5.3 "Refresh" conformance grammar.
+ *
+ * The grammar (distinct from the more lenient parse algorithm browsers use
+ * to execute the refresh):
+ *
+ * 1. Optionally, ASCII whitespace.
+ * 2. A valid non-negative integer.
+ * 3. Optionally:
+ *    1. Either a ";" (U+003B) or a "," (U+002C).
+ *    2. Optionally, ASCII whitespace.
+ *    3. Either:
+ *       - An ASCII case-insensitive match for "URL", followed by "=",
+ *         followed by a valid URL potentially surrounded by spaces.
+ *       - A valid URL potentially surrounded by spaces.
+ *
+ * @see https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-refresh
+ */
+export const checkHTTPEquivRefresh = () => function checkHTTPEquivRefresh(value) {
+    log('CHECK: meta http-equiv="refresh" content');
+    let i = 0;
+    const len = value.length;
+    // 1. Optional leading ASCII whitespace.
+    while (i < len && isAsciiWhitespace(value[i]))
+        i++;
+    // 2. Required: a valid non-negative integer.
+    const digitStart = i;
+    while (i < len && isAsciiDigit(value[i]))
+        i++;
+    if (digitStart === i) {
+        return unmatched(value, 'syntax-error', {
+            expects: [{ type: 'format', value: 'non-negative integer' }],
+        });
+    }
+    // No clause-3 block: the remainder of the string must be empty.
+    if (i === len)
+        return matched();
+    // 3.1 Required separator ";" or ",". Whitespace alone does not open
+    // the optional clause — the conformance text names the punctuation
+    // explicitly, and refusing bare whitespace is how we catch the
+    // `refresh-missing-semicolon` fixture.
+    const sep = value[i];
+    if (sep !== ';' && sep !== ',') {
+        return unmatched(value, 'unexpected-token', {
+            expects: [
+                { type: 'const', value: ';' },
+                { type: 'const', value: ',' },
+            ],
+        });
+    }
+    i++;
+    // 3.2 Optional ASCII whitespace.
+    while (i < len && isAsciiWhitespace(value[i]))
+        i++;
+    // 3.3 URL part — either "URL=<url>" (case-insensitive) or a bare URL.
+    if (i === len) {
+        // Clause 3 was opened by the separator but clause 3.3 is
+        // missing. A trailing `;` with nothing after breaks the grammar.
+        return unmatched(value, 'missing-token', {
+            expects: [{ type: 'common', value: 'URL' }],
+        });
+    }
+    const rest = value.slice(i);
+    let urlStr;
+    if (rest.length >= 4 && rest.slice(0, 3).toLowerCase() === 'url' && rest[3] === '=') {
+        urlStr = rest.slice(4);
+    }
+    else {
+        // Fall back to the bare-URL alternative. If the tail begins with
+        // something that looks like a keyword but is not "URL=" (e.g.,
+        // `href=...`), HTML LS still accepts it as long as the full tail
+        // parses as a valid URL — a relative-URL string with "=" in its
+        // path is legal per URL LS. That is why nu-validator's
+        // `refresh-invalid-keyword` over-detection is not a markuplint
+        // gap; see `snapshots/excluded-ids.json`.
+        urlStr = rest;
+    }
+    const urlResult = checkURL()(urlStr);
+    if (!urlResult.matched) {
+        return unmatched(value, urlResult.reason, {
+            expects: [{ type: 'common', value: 'URL' }],
+        });
+    }
+    return matched();
+};

package/lib/whatwg/check-media-query-list.d.ts

@@ -0,0 +1,61 @@
+import type { CustomSyntaxChecker } from '../types.js';
+/**
+ * Validates a `media` attribute value against the Media Queries Level 5
+ * grammar and authoring constraints.
+ *
+ * Catches three classes of conformance error that nu-validator reports but
+ * `whatwg-mimetype`-style checks do not:
+ *
+ * 1. **Syntax errors** — unbalanced parens, stray semicolons inside `()`,
+ *    unrecognised dimensions. Detected via `css-tree`'s `mediaQueryList`
+ *    parser entry-point.
+ * 2. **Unknown / deprecated media types** — anything outside
+ *    {`all`, `screen`, `print`} (e.g., `alla`, `notscreen`, `projection`).
+ *    Per [Media Queries Level 5 §2.3](https://www.w3.org/TR/mediaqueries-5/#media-types),
+ *    deprecated types are syntactically valid but author conformance
+ *    forbids them.
+ * 3. **Deprecated media features** — `device-width` / `device-height` /
+ *    `device-aspect-ratio` and their min-/max- variants. MDN's `@media`
+ *    reference marks them as
+ *    [deprecated since Media Queries Level 4](https://developer.mozilla.org/en-US/docs/Web/CSS/@media).
+ * 4. **Wrong-type feature values** — `(min-width: 400)` (unitless
+ *    non-zero number for a `<length>` feature), `(min-width: 400dpi)`
+ *    (resolution unit on a length feature), `(color: 1em)` (length
+ *    on an integer feature). The matrix covers length / integer /
+ *    resolution / ratio features per Media Queries Level 5 §4. Unknown
+ *    features are passed through unchanged so forward-compat additions
+ *    do not regress to errors.
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/
+ */
+export declare const checkMediaQueryList: CustomSyntaxChecker;
+/**
+ * Exists so callers that embed a `<media-condition>` inside a larger grammar
+ * (`<source-size-list>` in `<sizes>`) can enforce the same forbidden-in-authoring
+ * rule that {@link checkMediaQueryList} applies to `<media-query-list>` values.
+ *
+ * @see https://www.w3.org/TR/mediaqueries-5/#general-enclosed — "Authors must
+ * not use `<general-enclosed>` in their stylesheets. It exists only for
+ * future-compatibility, so that new syntax additions do not invalidate too
+ * much of a `<media-condition>` in older user agents."
+ *
+ * Contract:
+ *
+ * - css-tree emits `GeneralEnclosed` only when the enclosed tokens fail
+ *   `<media-feature>` grammar (`(min-width:)` empty value, `(123)` non-ident);
+ *   well-formed `(<ident>: <value>)` shapes parse as `Feature`, so unknown
+ *   feature names keep passing (forward-compatibility).
+ * - Returns `null` on any css-tree parse failure — the enclosing checker owns
+ *   grammar-error reporting. Only a *successful* parse reaching the fallback
+ *   surfaces here.
+ * - Programmer-error throws (`TypeError` etc.) bubble up; only Tier-3 css-tree
+ *   `SyntaxError` shapes are swallowed via `isCssTreeParseError`.
+ *
+ * @param snippet raw parenthesised group extracted from the outer value
+ * @returns first match's `{ raw, offset }` (offset is 0-based within `snippet`
+ *   — callers add their own outer offset when reporting), or `null` if none
+ */
+export declare function findGeneralEnclosed(snippet: string): {
+    readonly raw: string;
+    readonly offset: number;
+} | null;