@codelaw/rules-html 0.0.0-stage → 0.1.0

package/rules/html/no-implicit-close.cases.md

@@ -0,0 +1,38 @@
+# html/no-implicit-close — cases
+
+### case: a paragraph closed by a following block
+
+```html
+<p>One
+<div>Two</div>
+```
+
+```expect
+1:1 html/no-implicit-close
+```
+
+```fixed
+<p>One</p>
+<div>Two</div>
+```
+
+### case: table cells closed by the next row
+
+```html
+<table>
+  <tr><td>1
+  <tr><td>2</td></tr>
+</table>
+```
+
+```expect
+2:3 html/no-implicit-close
+2:7 html/no-implicit-close
+```
+
+```fixed
+<table>
+  <tr><td>1</td></tr>
+  <tr><td>2</td></tr>
+</table>
+```

package/rules/html/no-implicit-close.md

@@ -0,0 +1,40 @@
+---
+id: html/no-implicit-close
+title: "Elements are closed explicitly"
+languages: [html]
+fix: suggest
+fix_reason: "the end tag goes after the element's last content, so whitespace that followed it moves outside the element"
+stability: preview
+ported_from: [html-validate/no-implicit-close]
+since: 0.1.0
+---
+
+Elements whose end tag HTML lets you leave out (`<li>`, `<p>`, `<td>`, `<option>`, `<head>`, …) are closed with it anyway.
+
+**Why:** Implied end tags make nesting hard to read, and an element closed by the next tag is easy to break when markup moves.
+
+```codelaw
+native: html/no-implicit-close
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<ul>
+  <li>One
+  <li>Two
+</ul>
+```
+
+#### Do
+
+```html
+<ul>
+  <li>One</li>
+  <li>Two</li>
+</ul>
+```

package/rules/html/no-implicit-input-type.md

@@ -0,0 +1,34 @@
+---
+id: html/no-implicit-input-type
+title: "<input> says what type it is"
+languages: [html]
+fix: suggest
+fix_reason: "`type=\"text\"` is the default, but the field may have been meant as another type"
+stability: preview
+ported_from: [html-validate/no-implicit-input-type]
+since: 0.1.0
+---
+
+An `<input>` has a `type` attribute.
+
+**Why:** The default, `text`, is easy to leave by accident where `email`, `number` or `search` was meant.
+
+```codelaw
+native: html/no-implicit-input-type
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input name="q">
+```
+
+#### Do
+
+```html
+<input type="text" name="q">
+```

package/rules/html/no-inline-script.md

@@ -0,0 +1,42 @@
+---
+id: html/no-inline-script
+title: "No inline event handlers or javascript: URLs"
+languages: [html]
+fix: manual
+fix_reason: "the handler has to move into a script file"
+stability: preview
+ported_from: [htmlhint/inline-script-disabled]
+since: 0.1.0
+---
+
+Elements don't have inline event handlers (`onclick`, `onload`, …) or `javascript:` URLs.
+
+**Why:** Inline script mixes behaviour into markup, can't be cached or tested, and is blocked by a strict Content Security Policy.
+
+```codelaw
+native: html/no-inline-script
+```
+
+## How to fix
+
+1. Give the element an id or class.
+2. Attach the listener with `addEventListener` in a script file.
+3. Replace a `javascript:` link with a `<button>`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<button type="button" onclick="save()">Save</button>
+<a href="javascript:void(0)">Menu</a>
+```
+
+#### Do
+
+```html
+<button type="button" id="save">Save</button>
+<button type="button" id="menu">Menu</button>
+```

package/rules/html/no-inline-style.cases.md

@@ -0,0 +1,12 @@
+# html/no-inline-style — cases
+
+### case: display and custom properties are allowed by default
+
+```html
+<p style="display: none">a</p>
+<p style="--gap: 4px">b</p>
+```
+
+```expect
+(none)
+```

package/rules/html/no-inline-style.md

@@ -0,0 +1,42 @@
+---
+id: html/no-inline-style
+title: "No inline styles"
+languages: [html]
+fix: manual
+fix_reason: "the styles need a class and a stylesheet rule"
+stability: preview
+options:
+  allowedProperties: { type: "string[]", default: ["display"], description: "properties an inline style may set" }
+  allowVariables: { type: "boolean", default: true, description: "let inline styles set custom properties (`--name`)" }
+ported_from: [html-validate/no-inline-style, htmlhint/inline-style-disabled]
+since: 0.1.0
+---
+
+Elements don't have a `style` attribute, except one that only sets `display` or custom properties.
+
+**Why:** Inline styles can't be reused, override stylesheets with high specificity, and are blocked by a strict Content Security Policy.
+
+```codelaw
+native: html/no-inline-style
+```
+
+## How to fix
+
+1. Move the declarations into a stylesheet rule for a class.
+2. Replace the `style` attribute with that class.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<p style="color: red; font-weight: bold">Warning</p>
+```
+
+#### Do
+
+```html
+<p class="warning">Warning</p>
+```

package/rules/html/no-missing-references.md

@@ -0,0 +1,39 @@
+---
+id: html/no-missing-references
+title: "Id references point at an element"
+languages: [html]
+fix: manual
+fix_reason: "either the id or the reference is wrong, and only the author knows which"
+stability: preview
+ported_from: [html-validate/no-missing-references]
+since: 0.1.0
+---
+
+Attributes that refer to ids — `for`, `form`, `list`, `headers`, `aria-labelledby`, `aria-describedby`, `aria-controls` and the others — name ids that exist in the document.
+
+**Why:** A reference to a missing id silently does nothing: the label, description or relation is lost.
+
+```codelaw
+native: html/no-missing-references
+```
+
+## How to fix
+
+1. Correct the reference, or add the element it should point at.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="text" aria-describedby="hint">
+```
+
+#### Do
+
+```html
+<input type="text" aria-describedby="hint">
+<p id="hint">Use your work address.</p>
+```

package/rules/html/no-multiple-main.md

@@ -0,0 +1,40 @@
+---
+id: html/no-multiple-main
+title: "One visible <main> per document"
+languages: [html]
+fix: manual
+fix_reason: "which one is the main content is a design decision"
+stability: preview
+ported_from: [html-validate/no-multiple-main]
+since: 0.1.0
+---
+
+A document has at most one `<main>` without the `hidden` attribute.
+
+**Why:** Assistive technology jumps to "the" main content; with two, users land on one and miss the other.
+
+```codelaw
+native: html/no-multiple-main
+```
+
+## How to fix
+
+1. Keep one `<main>`; make the others `<section>`, `<aside>` or similar, or hide inactive ones with `hidden`.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<main>Feed</main>
+<main>Sidebar</main>
+```
+
+#### Do
+
+```html
+<main>Feed</main>
+<aside>Sidebar</aside>
+```

package/rules/html/no-raw-characters.cases.md

@@ -0,0 +1,84 @@
+# html/no-raw-characters — cases
+
+### case: a doctype tree-sitter cannot parse is not raw text
+
+```html
+<!DOCTYPE>
+<p>Hi</p>
+```
+
+```expect
+(none)
+```
+
+### case: an unterminated reference is a raw ampersand
+
+```html
+<p>a&nbsp b</p>
+```
+
+```expect
+1:5 html/no-raw-characters
+```
+
+```fixed
+<p>a&amp;nbsp b</p>
+```
+
+### case: = in an unquoted attribute
+
+```html
+<a href=/x?a=1>x</a>
+```
+
+```expect
+1:13 html/no-raw-characters
+```
+
+```fixed
+<a href=/x?a&equals;1>x</a>
+```
+
+### case: quoted attribute values may hold anything
+
+```html
+<a href="/x?a=1&b=2">x</a>
+```
+
+```expect
+(none)
+```
+
+### case: script content is not text
+
+```html
+<script>if (a < b && c) {}</script>
+```
+
+```expect
+(none)
+```
+
+### case: template tags are left alone
+
+```html
+<p><%= user.name %></p>
+```
+
+```expect
+(none)
+```
+
+### case: text tree-sitter cannot parse, with multi-byte characters
+
+```html
+<p>中文 & 日本語</p>
+```
+
+```expect
+1:7 html/no-raw-characters
+```
+
+```fixed
+<p>中文 &amp; 日本語</p>
+```

package/rules/html/no-raw-characters.md

@@ -0,0 +1,35 @@
+---
+id: html/no-raw-characters
+title: "Special characters are escaped"
+languages: [html]
+fix: auto
+stability: preview
+options:
+  relaxed: { type: "boolean", default: false, description: "don't report `&`" }
+ported_from: [html-validate/no-raw-characters, htmlhint/spec-char-escape]
+since: 0.1.0
+---
+
+Text doesn't contain a raw `<` or an `&` that could be read as a character reference, and an unquoted attribute value doesn't contain `"`, `'`, `<`, `=`, `>`, `` ` `` or such an `&`.
+
+**Why:** The parser can read them as markup: `&copy=1` becomes `©=1`, and `<` may start a tag.
+
+```codelaw
+native: html/no-raw-characters
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<p>Fish & chips</p>
+```
+
+#### Do
+
+```html
+<p>Fish &amp; chips</p>
+```

package/rules/html/no-redundant-aria-label.md

@@ -0,0 +1,36 @@
+---
+id: html/no-redundant-aria-label
+title: "aria-label doesn't repeat the label"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/no-redundant-aria-label]
+tags: [a11y]
+since: 0.1.0
+---
+
+A form control doesn't have an `aria-label` equal to the text of its `<label for>`.
+
+**Why:** The label already names the control; the copy drifts out of date when only the visible label is edited.
+
+```codelaw
+native: html/no-redundant-aria-label
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<label for="q">Search</label>
+<input type="text" id="q" aria-label="Search">
+```
+
+#### Do
+
+```html
+<label for="q">Search</label>
+<input type="text" id="q">
+```

package/rules/html/no-redundant-for.md

@@ -0,0 +1,34 @@
+---
+id: html/no-redundant-for
+title: "A wrapping label has no for"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/no-redundant-for]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<label>` that wraps its control doesn't also point at it with `for`.
+
+**Why:** Wrapping already associates them; the `for` is one more id reference to keep in sync.
+
+```codelaw
+native: html/no-redundant-for
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<label for="q">Search <input type="text" id="q"></label>
+```
+
+#### Do
+
+```html
+<label>Search <input type="text" id="q"></label>
+```

package/rules/html/no-redundant-role.md

@@ -0,0 +1,42 @@
+---
+id: html/no-redundant-role
+title: "No role the element already has"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/no-redundant-role]
+tags: [a11y]
+since: 0.1.0
+---
+
+An element's `role` is not the role it has anyway, such as `<ul role="list">`, `<button role="button">` or `<a href role="link">`.
+
+**Why:** The attribute repeats the element and suggests the element was chosen for its looks.
+
+```codelaw
+native: html/no-redundant-role
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<ul role="list">
+  <li>One</li>
+</ul>
+```
+
+#### Do
+
+```html
+<ul>
+  <li>One</li>
+</ul>
+```
+
+## Differences from the source
+
+Some Safari versions drop the list role of a `<ul>` styled with `list-style: none`; `role="list"` is a known workaround. Turn the rule off for such lists.

package/rules/html/no-utf8-bom.md

@@ -0,0 +1,45 @@
+---
+id: html/no-utf8-bom
+title: "No UTF-8 byte-order mark"
+languages: [html]
+fix: manual
+fix_reason: "the mark is in the file's bytes, outside the text a fix can edit; the editor's encoding setting removes it"
+stability: preview
+ported_from: [html-validate/no-utf8-bom]
+since: 0.1.0
+---
+
+An HTML file doesn't start with a UTF-8 byte-order mark (`EF BB BF`).
+
+**Why:** UTF-8 needs no byte-order mark. Served or concatenated, the mark can show up as stray characters, or break a server-side include or a `<!DOCTYPE>` that must come first.
+
+```codelaw
+native: html/no-utf8-bom
+```
+
+## How to fix
+
+1. Save the file as UTF-8 without a byte-order mark. In VS Code, click the encoding in the status bar, choose *Save with Encoding*, then *UTF-8*.
+2. Or strip it from the command line: `sed -i '1s/^\xEF\xBB\xBF//' <file>` (GNU sed).
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<!DOCTYPE html>
+<html lang="en"><title>Home</title></html>
+```
+
+#### Do
+
+```html
+<!DOCTYPE html>
+<html lang="en"><title>Home</title></html>
+```
+
+## Differences from the source
+
+Only the file itself is checked: an HTML region inside another file (a Markdown fence, a template) holds no byte-order mark of its own.

package/rules/html/prefer-button.md

@@ -0,0 +1,39 @@
+---
+id: html/prefer-button
+title: "Buttons are <button> elements"
+languages: [html]
+fix: manual
+fix_reason: "the element changes, so CSS and scripts that select `input` need updating"
+stability: preview
+ported_from: [html-validate/prefer-button]
+since: 0.1.0
+---
+
+Buttons are written as `<button>`, not `<input type="button">`, `submit`, `reset` or `image`.
+
+**Why:** `<button>` can hold markup and is styled and labelled more consistently.
+
+```codelaw
+native: html/prefer-button
+```
+
+## How to fix
+
+1. Replace the `<input>` with a `<button>` of the same type, moving `value` into the content.
+2. Update the CSS selectors and scripts that targeted the input.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="submit" value="Send">
+```
+
+#### Do
+
+```html
+<button type="submit">Send</button>
+```

package/rules/html/prefer-native-element.md

@@ -0,0 +1,40 @@
+---
+id: html/prefer-native-element
+title: "Native elements instead of ARIA roles"
+languages: [html]
+fix: manual
+fix_reason: "swapping the element changes its styles and scripts"
+stability: preview
+ported_from: [html-validate/prefer-native-element]
+tags: [a11y]
+since: 0.1.0
+---
+
+An element doesn't take a role a native element provides, such as `role="button"` on a `<div>` or `role="navigation"` on a `<div>`.
+
+**Why:** Native elements bring keyboard handling, focus and semantics for free; a role brings only the announcement.
+
+```codelaw
+native: html/prefer-native-element
+```
+
+## How to fix
+
+1. Replace the element with the native one the message names.
+2. Remove the `role` and any keyboard handling the native element now provides.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<div role="button" tabindex="0">Save</div>
+```
+
+#### Do
+
+```html
+<button type="button">Save</button>
+```

package/rules/html/prefer-tbody.md

@@ -0,0 +1,41 @@
+---
+id: html/prefer-tbody
+title: "Table rows are in <tbody>"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/prefer-tbody]
+since: 0.1.0
+---
+
+A table's `<tr>` rows sit in a `<tbody>` (or `<thead>`/`<tfoot>`), not directly in `<table>`.
+
+**Why:** Browsers insert the `<tbody>` anyway, so the markup doesn't match the DOM that CSS and scripts see.
+
+```codelaw
+native: html/prefer-tbody
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<table>
+  <tr><td>1</td></tr>
+</table>
+```
+
+#### Do
+
+```html
+<table>
+  <tbody><tr><td>1</td></tr></tbody>
+</table>
+```
+
+## Differences from the source
+
+The fix is offered when the rows are next to each other; rows separated by other elements are only reported.