Add more docs to types

Author: wooorm

lib/index.js

@@ -16,29 +16,205 @@
  * Normalized input.
  *
  * @typedef Schema
- * Sanitization configuration.
+ * Schema that defines what nodes and properties are allowed.
+ *
+ * The default schema is `defaultSchema`, which follows how GitHub cleans.
+ * If any top-level key is missing in the given schema, the corresponding
+ * value of the default schema is used.
+ *
+ * To extend the standard schema with a few changes, clone `defaultSchema`
+ * like so:
+ *
+ * ```js
+ * import {h} from 'hastscript'
+ * import deepmerge from 'deepmerge' // You can use `structuredClone` in modern JS.
+ * import {sanitize, defaultSchema} from 'hast-util-sanitize'
+ *
+ * const schema = deepmerge(defaultSchema, {attributes: {'*': ['className']}})
+ *
+ * const tree = sanitize(h('div', {className: ['foo']}), schema)
+ *
+ * // `tree` still has `className`.
+ * console.log(tree)
+ * // {
+ * // type: 'element',
+ * // tagName: 'div',
+ * // properties: {className: ['foo']},
+ * // children: []
+ * // }
+ * ```
  * @property {Attributes | null | undefined} [attributes]
- * Map of tag names to allowed properties.
+ * Map of tag names to allowed *property names*.
+ *
+ * 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.
+ *
+ * For example:
+ *
+ * ```js
+ * attributes: {
+ * a: ['href'],
+ * img: ['src', 'longDesc'],
+ * // …
+ * '*': [
+ * 'abbr',
+ * 'accept',
+ * '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:
  *
- * The special `'*'` key defines property names allowed on all elements.
+ * ```js
+ * attributes: {
+ * // …
+ * input: [
+ * ['type', 'checkbox'],
+ * ['disabled', true]
+ * ]
+ * // …
+ * }
+ * ```
+ *
+ * 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']
+ * ]
+ * // …
+ * ```
  * @property {Record<string, Record<string, PropertyValue>> | null | undefined} [required]
- * Map of tag names to required property names and their default property value.
+ * Map of tag names to required *property names* and their default *property
+ * value*.
+ *
+ * If the defined keys do not exist in an element’s properties, they are added
+ * and set to the specified value.
+ *
+ * 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`.
+ *
+ * For example:
+ *
+ * ```js
+ * required: {
+ * input: {type: 'checkbox', disabled: true}
+ * }
+ * ```
  * @property {Array<string> | null | undefined} [tagNames]
  * List of allowed tag names.
+ *
+ * For example:
+ *
+ * ```js
+ * tagNames: [
+ * 'h1',
+ * 'h2',
+ * 'h3',
+ * // …
+ * 'strike',
+ * 'summary',
+ * 'details'
+ * ]
+ * ```
  * @property {Record<string, Array<string>> | null | undefined} [protocols]
- * Map of protocols to allow in property values.
+ * Map of *property names* to allowed 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.
+ *
+ * For example:
+ *
+ * ```js
+ * protocols: {
+ * href: ['http', 'https', 'mailto'],
+ * // …
+ * longDesc: ['http', 'https']
+ * }
+ * ```
  * @property {Record<string, Array<string>> | null | undefined} [ancestors]
- * Map of tag names to their required ancestor elements.
+ * Map of tag names to a list of tag names which are required ancestors.
+ *
+ * Elements with these tag names will be ignored if they occur outside of one
+ * of their allowed parents.
+ *
+ * For example:
+ *
+ * ```js
+ * ancestors: {
+ * li: ['ol', 'ul'],
+ * // …
+ * tr: ['table']
+ * }
+ * ```
  * @property {Array<string> | null | undefined} [clobber]
- * List of allowed property names which can clobber.
+ * List of *property names* that clobber (`Array<string>`).
+ *
+ * For example:
+ *
+ * ```js
+ * clobber: ['name', 'id']
+ * ```
  * @property {string | null | undefined} [clobberPrefix]
- * Prefix to use before potentially clobbering property names.
+ * Prefix to use before clobbering properties.
+ *
+ * For example:
+ *
+ * ```js
+ * clobberPrefix: 'user-content-'
+ * ```
  * @property {Array<string> | null | undefined} [strip]
- * Names of elements to strip from the tree.
- * @property {boolean | null | undefined} [allowComments]
- * Whether to allow comments.
- * @property {boolean | null | undefined} [allowDoctypes]
- * Whether to allow doctypes.
+ * List of tag names to strip from the tree.
+ *
+ * By default, unsafe elements are replaced by their children.
+ * Some elements should however be entirely stripped from the tree.
+ *
+ * For example:
+ *
+ * ```js
+ * strip: ['script']
+ * ```
+ * @property {boolean | null | undefined} [allowComments=false]
+ * Whether to allow comment nodes.
+ *
+ * For example:
+ *
+ * ```js
+ * allowComments: true
+ * ```
+ * @property {boolean | null | undefined} [allowDoctypes=false]
+ * Whether to allow doctype nodes.
+ *
+ * ```js
+ * allowDoctypes: true
+ * ```
  *
  * @typedef {(schema: Schema, value: any, node: any, stack: Array<string>) => unknown} Handler
  * @typedef {Record<string, Handler>} NodeDefinition
@@ -65,12 +241,14 @@ const nodeSchema = {
 }
 
 /**
- * Utility to sanitize a tree
+ * Sanitize a tree.
  *
  * @param {Node} node
- * Hast tree to sanitize
+ * Tree to clean.
  * @param {Schema | null | undefined} [schema]
- * Schema defining how to sanitize - defaults to Github style sanitation
+ * Schema defining how to sanitize.
+ * @returns {Node}
+ * New, sanitized, tree.
  */
 export function sanitize(node, schema) {
  /** @type {Node} */
@@ -420,19 +598,23 @@ function handlePropertyValue(schema, value, prop, definition) {
  * @returns {boolean}
  */
 function safeProtocol(schema, value, prop) {
+ const protocols =
+ schema.protocols && own.call(schema.protocols, prop)
+ ? schema.protocols[prop].concat()
+ : []
+
+ // Not listed.
+ if (protocols.length === 0) {
+ return true
+ }
+
  const url = String(value)
  const colon = url.indexOf(':')
  const questionMark = url.indexOf('?')
  const numberSign = url.indexOf('#')
  const slash = url.indexOf('/')
- const protocols =
- schema.protocols && own.call(schema.protocols, prop)
- ? schema.protocols[prop].concat()
- : []
- let index = -1
 
  if (
- protocols.length === 0 ||
  colon < 0 ||
  // If the first colon is after a `?`, `#`, or `/`, it’s not a protocol.
  (slash > -1 && colon > slash) ||
@@ -442,6 +624,8 @@ function safeProtocol(schema, value, prop) {
  return true
  }
 
+ let index = -1
+
  while (++index < protocols.length) {
  if (
  colon === protocols[index].length &&

lib/schema.js

@@ -1,4 +1,10 @@
-/** @type {import('./index.js').Schema} */
+/**
+ * Default schema.
+ *
+ * Follows GitHub style sanitation.
+ *
+ * @type {import('./index.js').Schema}
+ */
 export const defaultSchema = {
  strip: ['script'],
  clobberPrefix: 'user-content-',