@codelaw/rules-html 0.0.0-stage → 0.1.0

package/rules/html/attribute-allowed-values.md

@@ -0,0 +1,41 @@
+---
+id: html/attribute-allowed-values
+title: "Attributes have values HTML allows"
+languages: [html]
+fix: manual
+fix_reason: "the intended value can only be guessed"
+stability: preview
+ported_from: [html-validate/attribute-allowed-values, htmlhint/src-not-empty]
+since: 0.1.0
+---
+
+An attribute with a fixed set of values (`type`, `dir`, `loading`, …) uses one of them; a boolean attribute (`disabled`, `checked`) is written bare or with its own name; a numeric attribute holds a number.
+
+**Why:** Browsers fall back to a default for a value they don't know, so a typo silently changes behaviour.
+
+```codelaw
+native: html/attribute-allowed-values
+```
+
+## How to fix
+
+1. Check the attribute's allowed values (the message lists the one written).
+2. Correct the value, or remove the attribute to get the default.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="emial" name="email">
+<img src="a.png" alt="A" loading="later">
+```
+
+#### Do
+
+```html
+<input type="email" name="email">
+<img src="a.png" alt="A" loading="lazy">
+```

package/rules/html/attribute-misuse.md

@@ -0,0 +1,39 @@
+---
+id: html/attribute-misuse
+title: "Attributes are used only where they take effect"
+languages: [html]
+fix: manual
+fix_reason: "either the attribute or its context is wrong, and only the author knows which"
+stability: preview
+ported_from: [html-validate/attribute-misuse]
+since: 0.1.0
+---
+
+An attribute that only works in a given context is used there: `formaction` on a submit button, `target` on a link with `href`, `coords` with a `shape` that needs them, and similar.
+
+**Why:** Outside that context the browser ignores the attribute, so the author's intent is lost.
+
+```codelaw
+native: html/attribute-misuse
+```
+
+## How to fix
+
+1. Read the message: it names the attribute and what it needs.
+2. Add the missing context (for example `href` or `type="submit"`), or remove the attribute.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<button type="button" formaction="/save">Save</button>
+```
+
+#### Do
+
+```html
+<button type="submit" formaction="/save">Save</button>
+```

package/rules/html/autocomplete-password.md

@@ -0,0 +1,41 @@
+---
+id: html/autocomplete-password
+title: "Password fields say which password they want"
+languages: [html]
+fix: manual
+fix_reason: "whether the field asks for a new or the current password depends on the form"
+stability: preview
+options:
+  preferred: { type: "string", default: "", description: "one value every password field must use, such as `current-password`" }
+ported_from: [html-validate/autocomplete-password]
+since: 0.1.0
+---
+
+An `<input type="password">` has `autocomplete`, set to `new-password` or `current-password`, not `off`.
+
+**Why:** Password managers autofill password fields anyway; saying which kind stops them filling a saved password into a "new password" field.
+
+```codelaw
+native: html/autocomplete-password
+```
+
+## How to fix
+
+1. Use `autocomplete="current-password"` on a sign-in form.
+2. Use `autocomplete="new-password"` on a sign-up or change-password form.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<input type="password" name="pw">
+```
+
+#### Do
+
+```html
+<input type="password" name="pw" autocomplete="current-password">
+```

package/rules/html/button-type.cases.md

@@ -0,0 +1,28 @@
+# html/button-type — cases
+
+### case: a button inside a select is the picker button
+
+```html
+<select>
+  <button>Pick</button>
+  <option>a</option>
+</select>
+```
+
+```expect
+(none)
+```
+
+### case: attributes stay after the inserted type
+
+```html
+<button class="x">Go</button>
+```
+
+```expect
+1:1 html/button-type
+```
+
+```fixed
+<button type="button" class="x">Go</button>
+```

package/rules/html/button-type.md

@@ -0,0 +1,35 @@
+---
+id: html/button-type
+title: "<button> says what type it is"
+languages: [html]
+fix: suggest
+fix_reason: "`type=\"button\"` stops the button submitting its form; a button meant to submit needs `type=\"submit\"` instead"
+stability: preview
+ported_from: [html-validate/no-implicit-button-type, htmlhint/button-type-require]
+tags: [a11y]
+since: 0.1.0
+---
+
+A `<button>` has a `type` attribute (`button`, `submit` or `reset`).
+
+**Why:** Without one a button submits its form, so a button meant to open a menu also sends the form, also when the user presses Enter.
+
+```codelaw
+native: html/button-type
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<button>Open menu</button>
+```
+
+#### Do
+
+```html
+<button type="button">Open menu</button>
+```

package/rules/html/close-attr.md

@@ -0,0 +1,33 @@
+---
+id: html/close-attr
+title: "End tags have no attributes"
+languages: [html]
+fix: auto
+stability: preview
+ported_from: [html-validate/close-attr]
+since: 0.1.0
+---
+
+An end tag is just `</name>`, with no attributes.
+
+**Why:** HTML ignores attributes on an end tag, so they are dead text that looks meaningful.
+
+```codelaw
+native: html/close-attr
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<p>Text</p class="intro">
+```
+
+#### Do
+
+```html
+<p>Text</p>
+```

package/rules/html/close-order.cases.md

@@ -0,0 +1,38 @@
+# html/close-order — cases
+
+### case: a pre closes an open paragraph, so its end tag is stray
+
+```html
+<p>
+Text
+<pre>code</pre>
+more
+</p>
+```
+
+```expect
+5:1 html/close-order
+```
+
+### case: optional end tags are not unclosed
+
+```html
+<table>
+  <tr><td>1<td>2
+</table>
+```
+
+```expect
+(none)
+```
+
+### case: a missing start tag
+
+```html
+<head><title>t</title></head>
+</html>
+```
+
+```expect
+2:1 html/close-order
+```

package/rules/html/close-order.md

@@ -0,0 +1,47 @@
+---
+id: html/close-order
+title: "Elements are closed, and in the order they were opened"
+languages: [html]
+fix: manual
+fix_reason: "where the missing end tag belongs depends on the intended structure"
+stability: preview
+ported_from: [html-validate/close-order, htmlhint/tag-pair]
+since: 0.1.0
+---
+
+Every element whose end tag is required is closed, and no end tag closes an element that isn't open.
+
+**Why:** Browsers repair mismatched tags by guessing, and the guess often nests content differently from what the author meant.
+
+```codelaw
+native: html/close-order
+```
+
+## How to fix
+
+1. Find where the element named in the message should end.
+2. Add its end tag there, or remove an end tag that closes nothing.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<div>
+  <span>Text
+</div>
+```
+
+#### Do
+
+```html
+<div>
+  <span>Text</span>
+</div>
+```
+
+## Differences from the source
+
+Elements whose end tag HTML lets you leave out (`<li>`, `<p>`, `<td>`, …) are not reported here; `html/no-implicit-close` reports them.

package/rules/html/deprecated.md

@@ -0,0 +1,39 @@
+---
+id: html/deprecated
+title: "No obsolete elements"
+languages: [html]
+fix: manual
+fix_reason: "the replacement — CSS, a semantic element, or nothing — depends on the intent"
+stability: preview
+ported_from: [html-validate/deprecated, htmlhint/tag-no-obsolete]
+since: 0.1.0
+---
+
+The document uses no element HTML has made obsolete: `<center>`, `<font>`, `<marquee>`, `<frame>`, `<tt>` and the rest.
+
+**Why:** Obsolete elements have no defined meaning, and some are rendered differently, or not at all, by current browsers.
+
+```codelaw
+native: html/deprecated
+```
+
+## How to fix
+
+1. Read the message for the usual replacement.
+2. Use that element, or a class and CSS, instead.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<center>Welcome</center>
+```
+
+#### Do
+
+```html
+<div class="centered">Welcome</div>
+```

package/rules/html/doctype-html.md

@@ -0,0 +1,36 @@
+---
+id: html/doctype-html
+title: "The doctype is the HTML5 one"
+languages: [html]
+fix: suggest
+fix_reason: "switching to standards mode can change the page's layout"
+stability: preview
+ported_from: [html-validate/doctype-html, htmlhint/doctype-html5]
+since: 0.1.0
+---
+
+The doctype is `<!DOCTYPE html>`, not an HTML 4 or XHTML one.
+
+**Why:** Legacy doctypes can put the browser in a quirks or "almost standards" mode, which lays pages out differently.
+
+```codelaw
+native: html/doctype-html
+```
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<p>Hello</p>
+```
+
+#### Do
+
+```html
+<!DOCTYPE html>
+<p>Hello</p>
+```

package/rules/html/element-name.cases.md

@@ -0,0 +1,21 @@
+# html/element-name — cases
+
+### case: svg children have their own names
+
+```html
+<svg><foreignObject></foreignObject><linearGradient></linearGradient></svg>
+```
+
+```expect
+(none)
+```
+
+### case: namespaced names are left alone
+
+```html
+<o:p></o:p>
+```
+
+```expect
+(none)
+```

package/rules/html/element-name.md

@@ -0,0 +1,42 @@
+---
+id: html/element-name
+title: "Element names are HTML elements or valid custom elements"
+languages: [html]
+fix: manual
+fix_reason: "renaming an element changes its CSS and script hooks"
+stability: preview
+options:
+  allow: { type: "string[]", default: [], description: "more element names to accept" }
+ported_from: [html-validate/element-name]
+since: 0.1.0
+---
+
+Every element is either an HTML element or a custom element whose name starts with a lowercase letter and contains a hyphen.
+
+**Why:** An unknown element without a hyphen is a typo or an invalid custom element, and the browser treats it as an inline element with no meaning.
+
+```codelaw
+native: html/element-name
+```
+
+## How to fix
+
+1. If the name is a typo of an HTML element, correct it.
+2. If it is a custom element, give it a hyphenated name and rename its definition.
+3. If a framework needs the name, add it to the `allow` option.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<widget>Hi</widget>
+```
+
+#### Do
+
+```html
+<x-widget>Hi</x-widget>
+```

package/rules/html/element-permitted-content.cases.md

@@ -0,0 +1,54 @@
+# html/element-permitted-content — cases
+
+### case: obsolete elements are left to html/deprecated
+
+```html
+<p>Use <tt>make</tt> here.</p>
+```
+
+```expect
+(none)
+```
+
+### case: a transparent link passes its content through
+
+```html
+<p><a href="/a"><div>Block</div></a></p>
+```
+
+```expect
+1:17 html/element-permitted-content
+```
+
+### case: the svg content model is not HTML
+
+```html
+<p><svg><g><rect width="1" height="1"></rect></g></svg></p>
+```
+
+```expect
+(none)
+```
+
+### case: a list nested directly in a list
+
+```html
+<ul>
+  <li>One</li>
+  <ul><li>Two</li></ul>
+</ul>
+```
+
+```expect
+3:3 html/element-permitted-content
+```
+
+### case: content of a template is checked against its own parent
+
+```html
+<template><td>1</td></template>
+```
+
+```expect
+(none)
+```

package/rules/html/element-permitted-content.md

@@ -0,0 +1,45 @@
+---
+id: html/element-permitted-content
+title: "Elements contain only content HTML allows there"
+languages: [html]
+fix: manual
+fix_reason: "the right structure depends on what the markup is for"
+stability: preview
+ported_from: [html-validate/element-permitted-content]
+since: 0.1.0
+---
+
+Each element contains only the elements its content model allows: no `<div>` inside a `<span>` or `<p>`, nothing interactive inside a link or button, no `<li>` directly inside a `<div>`.
+
+**Why:** Browsers repair forbidden nesting by moving elements, so the DOM differs from the markup and styles and scripts miss.
+
+```codelaw
+native: html/element-permitted-content
+```
+
+## How to fix
+
+1. Move the element named in the message out of the parent it can't be in.
+2. Or change the parent to one that allows it (for example `<div>` instead of `<span>`).
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<p><div>Block</div></p>
+<a href="/a"><button type="button">Go</button></a>
+```
+
+#### Do
+
+```html
+<div><p>Block</p></div>
+<a href="/a">Go</a>
+```
+
+## Differences from the source
+
+Obsolete elements (`<tt>`, `<font>`, `<acronym>`, …) have no content model in the element table, so html-validate reports them wherever they are; here they are left to `html/deprecated`, which reports each once.

package/rules/html/element-permitted-occurrences.md

@@ -0,0 +1,45 @@
+---
+id: html/element-permitted-occurrences
+title: "Elements that may appear once do"
+languages: [html]
+fix: manual
+fix_reason: "which of the duplicates to keep is the author's call"
+stability: preview
+ported_from: [html-validate/element-permitted-occurrences]
+since: 0.1.0
+---
+
+Children that may appear only once in their parent do: one `<caption>`, `<thead>` and `<tfoot>` per table, one `<title>` and `<base>` per head, one `<legend>` per fieldset.
+
+**Why:** The browser uses the first one and ignores the rest.
+
+```codelaw
+native: html/element-permitted-occurrences
+```
+
+## How to fix
+
+1. Merge the duplicates into one, or remove the extra one.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<table>
+  <caption>Prices</caption>
+  <caption>2024</caption>
+  <tr><td>1</td></tr>
+</table>
+```
+
+#### Do
+
+```html
+<table>
+  <caption>Prices, 2024</caption>
+  <tr><td>1</td></tr>
+</table>
+```

package/rules/html/element-permitted-order.md

@@ -0,0 +1,44 @@
+---
+id: html/element-permitted-order
+title: "Children come in the order HTML requires"
+languages: [html]
+fix: manual
+fix_reason: "moving markup may change how it is styled"
+stability: preview
+ported_from: [html-validate/element-permitted-order]
+since: 0.1.0
+---
+
+Children with a required order are in it: in a table, `<caption>` then `<colgroup>`, `<thead>`, `<tbody>`/`<tr>`, `<tfoot>`; `<summary>` first in `<details>`; `<legend>` first in `<fieldset>`; `<source>` before `<img>` in `<picture>`.
+
+**Why:** Out of order, browsers ignore or move the element, so it doesn't do its job.
+
+```codelaw
+native: html/element-permitted-order
+```
+
+## How to fix
+
+1. Move the element named in the message before the one it must precede.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<details>
+  <p>More text</p>
+  <summary>Read more</summary>
+</details>
+```
+
+#### Do
+
+```html
+<details>
+  <summary>Read more</summary>
+  <p>More text</p>
+</details>
+```

package/rules/html/element-permitted-parent.cases.md

@@ -0,0 +1,11 @@
+# html/element-permitted-parent — cases
+
+### case: li in a template
+
+```html
+<template><li>a</li></template>
+```
+
+```expect
+(none)
+```

package/rules/html/element-permitted-parent.md

@@ -0,0 +1,43 @@
+---
+id: html/element-permitted-parent
+title: "Elements have a parent HTML allows"
+languages: [html]
+fix: manual
+fix_reason: "whether to wrap the element or change it depends on the intended structure"
+stability: preview
+ported_from: [html-validate/element-permitted-parent]
+since: 0.1.0
+---
+
+Elements that need a particular parent have it: `<li>` in `<ul>`, `<ol>` or `<menu>`; `<title>` and `<base>` in `<head>`; `<head>` and `<body>` in `<html>`.
+
+**Why:** Elsewhere they lose their meaning: an `<li>` outside a list is not a list item to assistive technology.
+
+```codelaw
+native: html/element-permitted-parent
+```
+
+## How to fix
+
+1. Wrap the element in the parent it needs.
+2. Or replace it with an element that fits where it is.
+
+## Examples
+
+### HTML
+
+#### Don't
+
+```html
+<div>
+  <li>Apples</li>
+</div>
+```
+
+#### Do
+
+```html
+<ul>
+  <li>Apples</li>
+</ul>
+```