Refactor docs

Author: wooorm

lib/index.js

@@ -25,8 +25,8 @@
  *   like so:
  *
  *   ```js
- *   import {h} from 'hastscript'
  *   import deepmerge from 'deepmerge'
+ *   import {h} from 'hastscript'
  *   import {defaultSchema, sanitize} from 'hast-util-sanitize'
  *
  *   const schema = deepmerge(defaultSchema, {attributes: {'*': ['className']}})
@@ -69,26 +69,27 @@
  *
  *   ```js
  *   ancestors: {
- *     li: ['ol', 'ul'],
+ *     tbody: ['table'],
  *     // …
  *     tr: ['table']
  *   }
  *   ```
  * @property {Record<string, Array<PropertyDefinition>> | null | undefined} [attributes]
- *   Map of tag names to allowed *property names* (default:
+ *   Map of tag names to allowed property names (default:
  *   `defaultSchema.attributes`).
  *
  *   The special key `'*'` as a tag name defines property names allowed on all
  *   elements.
  *
  *   The special value `'data*'` as a property name can be used to allow all
- *   `data`properties.
+ *   `data` properties.
  *
  *   For example:
  *
  *   ```js
  *   attributes: {
  *     a: ['href'],
+ *     // …
  *     img: ['src', 'longDesc'],
  *     // …
  *     '*': [
@@ -97,56 +98,34 @@
  *       'acceptCharset',
  *       // …
  *       'vSpace',
- *       'width',
- *       'itemProp'
- *     ]
- *   }
- *   ```
- *
- *   Instead of a single string, which allows any *property value* of that
- *   property name, it’s also possible to provide an array to allow several
- *   values.
- *   For example, `input: ['type']` allows the `type` attribute set to any
- *   value on inputs.
- *   But `input: [['type', 'checkbox', 'radio']]` allows `type` only when set
- *   to one of the allowed values (`'checkbox'` or `'radio'`).
- *
- *   You can also use regexes, so for example `span: [['className', /^hljs-/]]`
- *   allows any class that starts with `hljs-` on `span` elements.
- *
- *   This is how the default GitHub schema allows only disabled checkbox
- *   inputs:
- *
- *   ```js
- *   attributes: {
- *     // …
- *     input: [
- *       ['type', 'checkbox'],
- *       ['disabled', true]
+ *       'value',
+ *       'width'
  *     ]
- *     // …
  *   }
  *   ```
  *
- *   Attributes also plays well with properties that accept space- or
- *   comma-separated values, such as `class`.
- *   Say you wanted to allow certain classes on `span` elements for syntax
- *   highlighting, that can be done like this:
- *
- *   ```js
- *   // …
- *   span: [
- *     ['className', 'token', 'number', 'operator']
- *   ]
- *   // …
- *   ```
+ *   Instead of a single string in the array, which allows any property value
+ *   for the field, you can use an array to allow several values.
+ *   For example, `input: ['type']` allows `type` set to any value on `input`s.
+ *   But `input: [['type', 'checkbox', 'radio']]` allows `type` when set to
+ *   `'checkbox'` or `'radio'`.
+ *
+ *   You can use regexes, so for example `span: [['className', /^hljs-/]]`
+ *   allows any class that starts with `hljs-` on `span`s.
+ *
+ *   When comma- or space-separated values are used (such as `className`), each
+ *   value in is checked individually.
+ *   For example, to allow certain classes on `span`s for syntax highlighting,
+ *   use `span: [['className', 'number', 'operator', 'token']]`.
+ *   This will allow `'number'`, `'operator'`, and `'token'` classes, but drop
+ *   others.
  * @property {Array<string> | null | undefined} [clobber]
- *   List of *property names* that clobber (default: `defaultSchema.clobber`).
+ *   List of property names that clobber (default: `defaultSchema.clobber`).
  *
  *   For example:
  *
  *   ```js
- *   clobber: ['name', 'id']
+ *   clobber: ['id', 'name']
  *   ```
  * @property {string | null | undefined} [clobberPrefix]
  *   Prefix to use before clobbering properties (default:
@@ -161,43 +140,46 @@
  *   Map of *property names* to allowed protocols (default:
  *   `defaultSchema.protocols`).
  *
- *   The listed property names can be set to URLs that are local (relative to
- *   the current website, such as `this`, `#this`, `/this`, or `?this`) or
- *   remote (such as `https://example.com`), in which case they must have a
- *   protocol that is allowed here.
+ *   This defines URLs that are always allowed to have local URLs (relative to
+ *   the current website, such as `this`, `#this`, `/this`, or `?this`), and
+ *   only allowed to have remote URLs (such as `https://example.com`) if they
+ *   use a known protocol.
  *
  *   For example:
  *
  *   ```js
  *   protocols: {
- *     href: ['http', 'https', 'mailto'],
+ *     href: ['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'],
  *     // …
  *     longDesc: ['http', 'https']
  *   }
  *   ```
  * @property {Record<string, Record<string, Properties[keyof Properties]>> | null | undefined} [required]
- *   Map of tag names to required *property names* and their default *property
- *   value* (default: `defaultSchema.required`).
- *
- *   If the defined keys do not exist in an element’s properties, they are added
- *   and set to the specified value.
+ *   Map of tag names to required property names with a default value
+ *   (default: `defaultSchema.required`).
  *
- *   Note that properties are first checked based on the schema at `attributes`,
- *   so properties could be removed by that step and then added again through
- *   `required`.
+ *   This defines properties that must be set.
+ *   If a field does not exist (after the element was made safe), these will be
+ *   added with the given value.
  *
  *   For example:
  *
  *   ```js
  *   required: {
- *     input: {type: 'checkbox', disabled: true}
+ *     input: {disabled: true, type: 'checkbox'}
  *   }
  *   ```
+ *
+ *   > 👉 **Note**: properties are first checked based on `schema.attributes`,
+ *   > then on `schema.required`.
+ *   > That means properties could be removed by `attributes` and then added
+ *   > again with `required`.
  * @property {Array<string> | null | undefined} [strip]
  *   List of tag names to strip from the tree (default: `defaultSchema.strip`).
  *
- *   By default, unsafe elements are replaced by their children.
- *   Some elements should however be entirely stripped from the tree.
+ *   By default, unsafe elements (those not in `schema.tagNames`) are replaced
+ *   by what they contain.
+ *   This option can drop their contents.
  *
  *   For example:
  *
@@ -211,13 +193,13 @@
  *
  *   ```js
  *   tagNames: [
- *     'h1',
- *     'h2',
- *     'h3',
+ *     'a',
+ *     'abbr',
+ *     'b',
  *     // …
- *     'strike',
- *     'summary',
- *     'details'
+ *     'ul',
+ *     'var',
+ *     'wbr'
  *   ]
  *   ```
  *
@@ -241,7 +223,7 @@ const own = {}.hasOwnProperty
  * @param {Readonly<Nodes>} node
  *   Unsafe tree.
  * @param {Readonly<Schema> | null | undefined} [options]
- *   Schema defining how to sanitize (default: `defaultSchema`).
+ *   Configuration (default: `defaultSchema`).
  * @returns {Nodes}
  *   New, safe tree.
  */
@@ -382,7 +364,6 @@ function element(state, unsafe) {
   state.stack.pop()
 
   let safeElement = false
-  let index = -1
 
   if (
     name.length > 0 &&
@@ -395,6 +376,8 @@ function element(state, unsafe) {
     // ancestor.
     if (state.schema.ancestors && own.call(state.schema.ancestors, name)) {
       const ancestors = state.schema.ancestors[name]
+      let index = -1
+
       safeElement = false
 
       while (++index < ancestors.length) {

lib/schema.js

@@ -8,24 +8,24 @@
 export const defaultSchema = {
   ancestors: {
     tbody: ['table'],
-    tfoot: ['table'],
-    thead: ['table'],
     td: ['table'],
     th: ['table'],
+    thead: ['table'],
+    tfoot: ['table'],
     tr: ['table']
   },
   attributes: {
     a: ['href'],
+    blockquote: ['cite'],
+    del: ['cite'],
+    div: ['itemScope', 'itemType'],
     img: ['longDesc', 'src'],
     input: [
       ['disabled', true],
       ['type', 'checkbox']
     ],
-    li: [['className', 'task-list-item']],
-    div: ['itemScope', 'itemType'],
-    blockquote: ['cite'],
-    del: ['cite'],
     ins: ['cite'],
+    li: [['className', 'task-list-item']],
     q: ['cite'],
     '*': [
       'abbr',
@@ -111,10 +111,7 @@ export const defaultSchema = {
     longDesc: ['http', 'https']
   },
   required: {
-    input: {
-      disabled: true,
-      type: 'checkbox'
-    }
+    input: {disabled: true, type: 'checkbox'}
   },
   strip: ['script'],
   tagNames: [