@codelaw/rules-html 0.0.0-stage → 0.2.0

package/rules/html/require-sri.md

@@ -0,0 +1,41 @@
+---
+id: html/require-sri
+title: "Scripts and stylesheets carry an integrity hash"
+languages: [html]
+fix: manual
+fix_reason: "the hash must be computed from the exact file served"
+stability: preview
+options:
+  target: { type: "string", default: "all", description: "`all` checks every resource; `crossorigin` only those loaded from another origin" }
+ported_from: [html-validate/require-sri]
+since: 0.1.0
+---
+
+Every `<script src>` and `<link rel="stylesheet">` (and `modulepreload`, and `preload` of a script or style) has an `integrity` attribute.
+
+**Why:** Subresource Integrity makes the browser refuse a file that changed on the CDN or in transit.
+
+```codelaw
+native: html/require-sri
+```
+
+## How to fix
+
+1. Compute the file's hash, for example `openssl dgst -sha384 -binary lib.js | openssl base64 -A`.
+2. Add `integrity="sha384-…"` and `crossorigin="anonymous"`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<script src="https://cdn.example.com/lib.js"></script>
+```
+
+#### Do
+
+```html
+<script src="https://cdn.example.com/lib.js" integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" crossorigin="anonymous"></script>
+```

package/rules/html/script-element.md

@@ -0,0 +1,36 @@
+---
+id: html/script-element
+title: "<script> has an end tag"
+languages: [html]
+fix: suggest
+fix_reason: "the markup the open script swallowed starts being rendered"
+stability: preview
+ported_from: [html-validate/script-element]
+since: 0.1.0
+---
+
+A `<script>` is closed with `</script>`, also when it has `src`; `<script … />` is not a closed script.
+
+**Why:** HTML ignores the `/>`, so the browser reads everything up to the next `</script>` as script and the content in between disappears.
+
+```codelaw
+native: html/script-element
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<script src="app.js" />
+<p>Hello</p>
+```
+
+#### Do
+
+```html
+<script src="app.js"></script>
+<p>Hello</p>
+```

package/rules/html/script-type.md

@@ -0,0 +1,33 @@
+---
+id: html/script-type
+title: "No type on JavaScript scripts"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/script-type]
+since: 0.1.0
+---
+
+A `<script>` doesn't say `type="text/javascript"` or another JavaScript MIME type.
+
+**Why:** JavaScript is the default; the attribute adds nothing, and legacy types such as `text/ecmascript` mislead.
+
+```codelaw
+native: html/script-type
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<script type="text/javascript" src="app.js"></script>
+```
+
+#### Do
+
+```html
+<script src="app.js"></script>
+```

package/rules/html/target-blank-rel.cases.md

@@ -0,0 +1,35 @@
+# html/target-blank-rel — cases
+
+### case: noreferrer also prevents the opener
+
+```html
+<a href="/a" target="_blank" rel="noreferrer">a</a>
+```
+
+```expect
+(none)
+```
+
+### case: an existing rel gets noopener added
+
+```html
+<a href="/a" target="_blank" rel="external">a</a>
+```
+
+```expect
+1:14 html/target-blank-rel
+```
+
+```fixed
+<a href="/a" target="_blank" rel="external noopener">a</a>
+```
+
+### case: a link without href opens nothing
+
+```html
+<a target="_blank">a</a>
+```
+
+```expect
+(none)
+```

package/rules/html/target-blank-rel.md

@@ -0,0 +1,32 @@
+---
+id: html/target-blank-rel
+title: "Links that open a new tab set rel=\"noopener\""
+languages: [html]
+fix: auto
+stability: preview
+since: 0.1.0
+---
+
+An `<a>` or `<area>` with `target="_blank"` and an `href` (or a `<form>` with an `action`) has `rel="noopener"` or `rel="noreferrer"`.
+
+**Why:** Without it, older browsers give the opened page a handle on this one (`window.opener`), which it can use to redirect it.
+
+```codelaw
+native: html/target-blank-rel
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<a href="https://example.com" target="_blank">Example</a>
+```
+
+#### Do
+
+```html
+<a href="https://example.com" target="_blank" rel="noopener">Example</a>
+```

package/rules/html/tel-non-breaking.md

@@ -0,0 +1,37 @@
+---
+id: html/tel-non-breaking
+title: "Phone numbers don't wrap"
+languages: [html]
+fix: suggest
+fix_reason: "the text then contains non-breaking characters, which copy and search keep"
+stability: preview
+options:
+  ignoreClasses: { type: "string[]", default: [], description: "classes that already prevent wrapping" }
+  ignoreStyle: { type: "boolean", default: true, description: "skip links styled `white-space: nowrap` or `pre`" }
+ported_from: [html-validate/tel-non-breaking]
+since: 0.1.0
+---
+
+The text of a `tel:` link uses non-breaking spaces and hyphens.
+
+**Why:** A phone number broken over two lines is hard to read and to copy.
+
+```codelaw
+native: html/tel-non-breaking
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<a href="tel:5551234">555 1234</a>
+```
+
+#### Do
+
+```html
+<a href="tel:5551234">555&nbsp;1234</a>
+```

package/rules/html/text-content.md

@@ -0,0 +1,39 @@
+---
+id: html/text-content
+title: "Buttons have text"
+languages: [html]
+fix: manual
+fix_reason: "the button's name needs a human"
+stability: preview
+ported_from: [html-validate/text-content]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<button>` has text a screen reader can announce: content, `aria-label`, `aria-labelledby`, or an image with `alt`.
+
+**Why:** Without it the button is announced as just "button".
+
+```codelaw
+native: html/text-content
+```
+
+## How to fix
+
+1. Add visible text, or an `aria-label` that says what the button does.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<button type="button"><svg width="16" height="16"></svg></button>
+```
+
+#### Do
+
+```html
+<button type="button" aria-label="Close"><svg width="16" height="16"></svg></button>
+```

package/rules/html/th-scope.md

@@ -0,0 +1,47 @@
+---
+id: html/th-scope
+title: "Header cells in complex tables have scope"
+languages: [html]
+fix: manual
+fix_reason: "whether each header labels a row or a column is the author's call"
+stability: preview
+options:
+  strict: { type: "boolean", default: false, description: "check simple tables too" }
+ported_from: [html-validate/wcag/h63]
+tags: [a11y]
+since: 0.1.0
+---
+
+In a table whose headers are not just the first row or just the first column, every `<th>` has `scope` (`row`, `col`, `rowgroup` or `colgroup`).
+
+**Why:** Screen readers announce each cell with its headers; `scope` tells them which headers belong to which cells.
+
+```codelaw
+native: html/th-scope
+```
+
+## How to fix
+
+1. Add `scope="col"` to column headers and `scope="row"` to row headers.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<table>
+  <tr><th>Name</th><th>Age</th></tr>
+  <tr><th>Ada</th><td>36</td></tr>
+</table>
+```
+
+#### Do
+
+```html
+<table>
+  <tr><th scope="col">Name</th><th scope="col">Age</th></tr>
+  <tr><th scope="row">Ada</th><td>36</td></tr>
+</table>
+```

package/rules/html/unique-landmark.md

@@ -0,0 +1,41 @@
+---
+id: html/unique-landmark
+title: "Repeated landmarks have distinct names"
+languages: [html]
+fix: manual
+fix_reason: "the names need a human"
+stability: preview
+ported_from: [html-validate/unique-landmark]
+tags: [a11y]
+since: 0.1.0
+---
+
+When a landmark appears more than once (two `<nav>`, two `<aside>`, …), each has a unique, non-empty `aria-label` or `aria-labelledby`.
+
+**Why:** Screen-reader users jump between landmarks by name; two unnamed `<nav>` are indistinguishable.
+
+```codelaw
+native: html/unique-landmark
+```
+
+## How to fix
+
+1. Give each landmark of the same kind its own `aria-label`, or point `aria-labelledby` at its heading.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<nav><a href="/">Home</a></nav>
+<nav><a href="/help">Help</a></nav>
+```
+
+#### Do
+
+```html
+<nav aria-label="Main"><a href="/">Home</a></nav>
+<nav aria-label="Footer"><a href="/help">Help</a></nav>
+```

package/rules/html/unrecognized-char-ref.cases.md

@@ -0,0 +1,41 @@
+# html/unrecognized-char-ref — cases
+
+### case: numeric references are not looked up
+
+```html
+<p>&#169; &#xA9;</p>
+```
+
+```expect
+(none)
+```
+
+### case: query strings in URLs may hold unterminated names
+
+```html
+<a href="/s?q=1&copy=2">x</a>
+```
+
+```expect
+(none)
+```
+
+### case: a legacy name without its semicolon
+
+```html
+<p>&copy 2024</p>
+```
+
+```expect
+1:4 html/unrecognized-char-ref
+```
+
+### case: an unknown name
+
+```html
+<p>&nbps;</p>
+```
+
+```expect
+1:4 html/unrecognized-char-ref
+```

package/rules/html/unrecognized-char-ref.md

@@ -0,0 +1,42 @@
+---
+id: html/unrecognized-char-ref
+title: "Character references exist and are terminated"
+languages: [html]
+fix: manual
+fix_reason: "the intended character is not always clear"
+stability: preview
+options:
+  ignoreCase: { type: "boolean", default: false, description: "compare names without case" }
+  requireSemicolon: { type: "boolean", default: true, description: "report references without `;`" }
+ported_from: [html-validate/unrecognized-char-ref]
+since: 0.1.0
+---
+
+Every named character reference (`&name;`) is one HTML defines, and ends with `;`.
+
+**Why:** An unknown reference is shown literally, and an unterminated one may be read with the text after it.
+
+```codelaw
+native: html/unrecognized-char-ref
+```
+
+## How to fix
+
+1. Correct the name, or escape the `&` as `&` if no reference was meant.
+2. End the reference with `;`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<p>Price: 5&euros; &copy 2024</p>
+```
+
+#### Do
+
+```html
+<p>Price: 5&euro; &copy; 2024</p>
+```

package/rules/html/valid-autocomplete.cases.md

@@ -0,0 +1,42 @@
+# html/valid-autocomplete — cases
+
+### case: a section and a hint before the field
+
+```html
+<input type="text" name="a" autocomplete="section-ship shipping address-line1">
+```
+
+```expect
+(none)
+```
+
+### case: a multi-line field belongs on a textarea
+
+```html
+<input type="text" name="a" autocomplete="street-address">
+<textarea name="b" autocomplete="street-address"></textarea>
+```
+
+```expect
+1:43 html/valid-autocomplete
+```
+
+### case: on and off are not combined with fields
+
+```html
+<input type="text" name="a" autocomplete="off">
+```
+
+```expect
+(none)
+```
+
+### case: form takes only on or off
+
+```html
+<form autocomplete="email"></form>
+```
+
+```expect
+1:21 html/valid-autocomplete
+```

package/rules/html/valid-autocomplete.md

@@ -0,0 +1,42 @@
+---
+id: html/valid-autocomplete
+title: "autocomplete values are valid"
+languages: [html]
+fix: manual
+fix_reason: "the right field name depends on what the field collects"
+stability: preview
+ported_from: [html-validate/valid-autocomplete]
+tags: [a11y]
+since: 0.1.0
+---
+
+`autocomplete` holds a valid token list: optional `section-*`, then `shipping`/`billing`, then `home`/`work`/… for contact fields, then one field name that fits the input type, then optional `webauthn`. `<form>` takes only `on` or `off`.
+
+**Why:** Browsers ignore an invalid value, so autofill and password managers can't help the user.
+
+```codelaw
+native: html/valid-autocomplete
+```
+
+## How to fix
+
+1. Pick the field name that describes the data (the WHATWG autofill list).
+2. Order the tokens as described above, or use `off`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="email" name="email" autocomplete="mail">
+<input type="number" name="n" autocomplete="email">
+```
+
+#### Do
+
+```html
+<input type="email" name="email" autocomplete="email">
+<input type="number" name="n" autocomplete="off">
+```

package/rules/html/valid-for.md

@@ -0,0 +1,40 @@
+---
+id: html/valid-for
+title: "A label points at a control"
+languages: [html]
+fix: manual
+fix_reason: "either the id or the element is wrong, and only the author knows which"
+stability: preview
+ported_from: [html-validate/valid-for]
+since: 0.1.0
+---
+
+A `<label for>` refers to the id of a form control a label can name (`input`, `select`, `textarea`, `button`, `meter`, `output`, `progress`).
+
+**Why:** Pointed at a `<div>` or `<span>`, the label names nothing, and clicking it does nothing.
+
+```codelaw
+native: html/valid-for
+```
+
+## How to fix
+
+1. Point `for` at the control's id, or make the target a form control.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<label for="name">Name</label>
+<div id="name"></div>
+```
+
+#### Do
+
+```html
+<label for="name">Name</label>
+<input type="text" id="name">
+```

package/rules/html/valid-id.md

@@ -0,0 +1,40 @@
+---
+id: html/valid-id
+title: "Ids are well-formed"
+languages: [html]
+fix: manual
+fix_reason: "renaming an id breaks the CSS, scripts and links that use it"
+stability: preview
+options:
+  relaxed: { type: "boolean", default: false, description: "only require a non-empty id without whitespace" }
+ported_from: [html-validate/valid-id]
+since: 0.1.0
+---
+
+An `id` is not empty and has no whitespace; it starts with a letter and uses only letters, digits, `-` and `_`.
+
+**Why:** Whitespace makes the id unusable; other characters need escaping in CSS selectors and are easy to get wrong.
+
+```codelaw
+native: html/valid-id
+```
+
+## How to fix
+
+1. Rename the id, and update everything that refers to it.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<div id="1st item"></div>
+```
+
+#### Do
+
+```html
+<div id="first-item"></div>
+```

package/rules/html/void-content.md

@@ -0,0 +1,34 @@
+---
+id: html/void-content
+title: "Void elements have no end tag"
+languages: [html]
+fix: suggest
+fix_reason: "`</br>` is read as a second line break, so removing it changes the rendering"
+stability: preview
+ported_from: [html-validate/void-content]
+since: 0.1.0
+---
+
+Void elements (`<br>`, `<img>`, `<input>`, `<meta>`, …) are written without an end tag.
+
+**Why:** They can't have content; browsers ignore most such end tags, and read `</br>` and `</p>` as new elements.
+
+```codelaw
+native: html/void-content
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="text" name="q"></input>
+```
+
+#### Do
+
+```html
+<input type="text" name="q">
+```