Refactor some more docs

Author: wooorm

lib/index.js

@@ -29,6 +29,7 @@
  *   import {h} from 'hastscript'
  *   import {defaultSchema, sanitize} from 'hast-util-sanitize'
  *
+ *   // This allows `className` on all elements.
  *   const schema = deepmerge(defaultSchema, {attributes: {'*': ['className']}})
  *
  *   const tree = sanitize(h('div', {className: ['foo']}), schema)
@@ -88,16 +89,14 @@
  *
  *   ```js
  *   attributes: {
- *     a: ['href'],
- *     // …
- *     img: ['src', 'longDesc'],
+ *     'ariaDescribedBy', 'ariaLabel', 'ariaLabelledBy', …, 'href'
  *     // …
  *     '*': [
  *       'abbr',
  *       'accept',
  *       'acceptCharset',
  *       // …
- *       'vSpace',
+ *       'vAlign',
  *       'value',
  *       'width'
  *     ]
@@ -125,7 +124,7 @@
  *   For example:
  *
  *   ```js
- *   clobber: ['id', 'name']
+ *   clobber: ['ariaDescribedBy', 'ariaLabelledBy', 'id', 'name']
  *   ```
  * @property {string | null | undefined} [clobberPrefix]
  *   Prefix to use before clobbering properties (default:
@@ -136,7 +135,7 @@
  *   ```js
  *   clobberPrefix: 'user-content-'
  *   ```
- * @property {Record<string, Array<string>> | null | undefined} [protocols]
+ * @property {Record<string, Array<string> | null | undefined> | null | undefined} [protocols]
  *   Map of *property names* to allowed protocols (default:
  *   `defaultSchema.protocols`).
  *
@@ -149,9 +148,9 @@
  *
  *   ```js
  *   protocols: {
- *     href: ['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'],
+ *     cite: ['http', 'https'],
  *     // …
- *     longDesc: ['http', 'https']
+ *     src: ['http', 'https']
  *   }
  *   ```
  * @property {Record<string, Record<string, Properties[keyof Properties]>> | null | undefined} [required]
@@ -194,12 +193,10 @@
  *   ```js
  *   tagNames: [
  *     'a',
- *     'abbr',
  *     'b',
  *     // …
  *     'ul',
- *     'var',
- *     'wbr'
+ *     'var'
  *   ]
  *   ```
  *

lib/schema.js

@@ -134,13 +134,13 @@ export const defaultSchema = {
       'width'
     ]
   },
-  clobberPrefix: 'user-content-',
   clobber: ['ariaDescribedBy', 'ariaLabelledBy', 'id', 'name'],
+  clobberPrefix: 'user-content-',
   protocols: {
-    href: ['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'],
     cite: ['http', 'https'],
-    src: ['http', 'https'],
-    longDesc: ['http', 'https']
+    href: ['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'],
+    longDesc: ['http', 'https'],
+    src: ['http', 'https']
   },
   required: {
     input: {disabled: true, type: 'checkbox'}

readme.md

@@ -159,6 +159,7 @@ import deepmerge from 'deepmerge'
 import {h} from 'hastscript'
 import {defaultSchema, sanitize} from 'hast-util-sanitize'
 
+// This allows `className` on all elements.
 const schema = deepmerge(defaultSchema, {attributes: {'*': ['className']}})
 
 const tree = sanitize(h('div', {className: ['foo']}), schema)
@@ -229,16 +230,16 @@ For example:
 
 ```js
 attributes: {
-  a: ['href'],
-  // …
-  img: ['src', 'longDesc'],
+  a: [
+    'ariaDescribedBy', 'ariaLabel', 'ariaLabelledBy', /* … */, 'href'
+  ],
   // …
   '*': [
     'abbr',
     'accept',
     'acceptCharset',
     // …
-    'vSpace',
+    'vAlign',
     'value',
     'width'
   ]
@@ -269,7 +270,7 @@ List of [*property names*][name] that clobber (`Array<string>`, default:
 For example:
 
 ```js
-clobber: ['id', 'name']
+clobber: ['ariaDescribedBy', 'ariaLabelledBy', 'id', 'name']
 ```
 
 ###### `clobberPrefix`
@@ -297,9 +298,9 @@ For example:
 
 ```js
 protocols: {
-  href: ['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'],
+  cite: ['http', 'https'],
   // …
-  longDesc: ['http', 'https']
+  src: ['http', 'https']
 }
 ```
 
@@ -349,12 +350,10 @@ For example:
 ```js
 tagNames: [
   'a',
-  'abbr',
   'b',
   // …
   'ul',
-  'var',
-  'wbr'
+  'var'
 ]
 ```
 
@@ -365,15 +364,21 @@ It exports the additional type [`Schema`][api-schema].
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 14.14+ and 16.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line, `hast-util-sanitize@^4`,
+compatible with Node.js 12.
 
 ## Security
 
 By default, `hast-util-sanitize` will make everything safe to use.
-But when used incorrectly, deviating from the defaults can open you up to a
+Assuming you understand that certain attributes (including a limited set of
+classes) can be generated by users, and you write your CSS (and JS)
+accordingly.
+When used incorrectly, deviating from the defaults can open you up to a
 [cross-site scripting (XSS)][xss] attack.
 
 Use `hast-util-sanitize` after the last unsafe thing: everything after it could
@@ -412,9 +417,9 @@ abide by its terms.
 
 [downloads]: https://www.npmjs.com/package/hast-util-sanitize
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/hast-util-sanitize.svg
+[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-sanitize
 
-[size]: https://bundlephobia.com/result?p=hast-util-sanitize
+[size]: https://bundlejs.com/?q=hast-util-sanitize
 
 [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg