Add docs to types

Author: wooorm

index.js

@@ -1,17 +1,28 @@
 /**
  * @typedef {import('./lib/types.js').Element} Element
- * @typedef {import('./lib/types.js').HastNode} HastNode
+ * @typedef {import('./lib/types.js').Node} Node
  * @typedef {import('./lib/types.js').Space} Space
  */
 
 import {any} from './lib/any.js'
 import {parse} from './lib/parse.js'
 
 /**
+ * Check that the given `node` matches `selector`.
+ *
+ * This only checks the element itself, not the surrounding tree.
+ * Thus, nesting in selectors is not supported (`p b`, `p > b`), neither are
+ * selectors like `:first-child`, etc.
+ * This only checks that the given element matches the selector.
+ *
  * @param {string} selector
- * @param {HastNode} [node]
- * @param {Space} [space]
+ *   CSS selector, such as (`h1`, `a, b`).
+ * @param {Node|undefined} [node]
+ *   Node that might match `selector`, should be an element.
+ * @param {Space|undefined} [space='html']
+ *   Name of namespace (`'svg'` or `'html'`).
  * @returns {boolean}
+ *   Whether `node` matches `selector`.
  */
 export function matches(selector, node, space) {
   return Boolean(
@@ -20,21 +31,38 @@ export function matches(selector, node, space) {
 }
 
 /**
+ * Select the first element that matches `selector` in the given `tree`.
+ * Searches the tree in *preorder*.
+ *
  * @param {string} selector
- * @param {HastNode} [node]
- * @param {Space} [space]
+ *   CSS selector, such as (`h1`, `a, b`).
+ * @param {Node|undefined} [tree]
+ *   Tree to search.
+ * @param {Space|undefined} [space='html']
+ *   Name of namespace (`'svg'` or `'html'`).
  * @returns {Element|null}
+ *   First element in `tree` that matches `selector` or `null` if nothing is
+ *   found.
+ *   This could be `tree` itself.
  */
-export function select(selector, node, space) {
-  return any(parse(selector), node, {space, one: true})[0] || null
+export function select(selector, tree, space) {
+  return any(parse(selector), tree, {space, one: true})[0] || null
 }
 
 /**
+ * Select all elements that match `selector` in the given `tree`.
+ * Searches the tree in *preorder*.
+ *
  * @param {string} selector
- * @param {HastNode} [node]
- * @param {Space} [space]
+ *   CSS selector, such as (`h1`, `a, b`).
+ * @param {Node|undefined} [tree]
+ *   Tree to search.
+ * @param {Space|undefined} [space='html']
+ *   Name of namespace (`'svg'` or `'html'`).
  * @returns {Array<Element>}
+ *   Elements in `tree` that match `selector`.
+ *   This could include `tree` itself.
  */
-export function selectAll(selector, node, space) {
-  return any(parse(selector), node, {space})
+export function selectAll(selector, tree, space) {
+  return any(parse(selector), tree, {space})
 }

lib/any.js

@@ -3,7 +3,7 @@
  * @typedef {import('./types.js').Selectors} Selectors
  * @typedef {import('./types.js').Rule} Rule
  * @typedef {import('./types.js').RuleSet} RuleSet
- * @typedef {import('./types.js').HastNode} HastNode
+ * @typedef {import('./types.js').Node} Node
  * @typedef {import('./types.js').SelectIterator} SelectIterator
  * @typedef {import('./types.js').SelectState} SelectState
  */
@@ -15,7 +15,7 @@ import {nest} from './nest.js'
 import {pseudo} from './pseudo.js'
 import {test} from './test.js'
 
-/** @type {(query: Selectors|RuleSet|Rule, element: HastNode, state: SelectState) => Array<Element>} */
+/** @type {(query: Selectors|RuleSet|Rule, element: Node, state: SelectState) => Array<Element>} */
 const type = zwitch('type', {
   unknown: unknownType,
   invalid: invalidType,
@@ -24,7 +24,7 @@ const type = zwitch('type', {
 
 /**
  * @param {Selectors|RuleSet|Rule} query
- * @param {HastNode|undefined} node
+ * @param {Node|undefined} node
  * @param {SelectState} state
  * @returns {Array<Element>}
  */
@@ -34,7 +34,7 @@ export function any(query, node, state) {
 
 /**
  * @param {Selectors} query
- * @param {HastNode} node
+ * @param {Node} node
  * @param {SelectState} state
  * @returns {Array<Element>}
  */
@@ -51,7 +51,7 @@ function selectors(query, node, state) {
 
 /**
  * @param {RuleSet} query
- * @param {HastNode} node
+ * @param {Node} node
  * @param {SelectState} state
  * @returns {Array<Element>}
  */
@@ -61,7 +61,7 @@ function ruleSet(query, node, state) {
 
 /**
  * @param {Rule} query
- * @param {HastNode} tree
+ * @param {Node} tree
  * @param {SelectState} state
  * @returns {Array<Element>}
  */

lib/enter-state.js

@@ -1,9 +1,9 @@
 /**
  * @typedef {import('./types.js').SelectState} SelectState
- * @typedef {import('./types.js').HastNode} HastNode
+ * @typedef {import('./types.js').Node} Node
  * @typedef {import('./types.js').ElementChild} ElementChild
  * @typedef {import('./types.js').Direction} Direction
- * @typedef {import('unist-util-visit/complex-types').Visitor<ElementChild>} Visitor
+ * @typedef {import('unist-util-visit/complex-types.js').Visitor<ElementChild>} Visitor
  */
 
 import {direction} from 'direction'
@@ -15,7 +15,7 @@ import {element} from './util.js'
 
 /**
  * @param {SelectState} state
- * @param {HastNode} node
+ * @param {Node} node
  * @returns {() => void}
  */
 // eslint-disable-next-line complexity

lib/nest.js

@@ -4,7 +4,7 @@
  * @typedef {import('./types.js').Parent} Parent
  * @typedef {import('./types.js').SelectState} SelectState
  * @typedef {import('./types.js').SelectIterator} SelectIterator
- * @typedef {import('./types.js').HastNode} HastNode
+ * @typedef {import('./types.js').Node} Node
  * @typedef {import('./types.js').Handler} Handler
  */
 
@@ -14,7 +14,7 @@ import {parent, element} from './util.js'
 
 const own = {}.hasOwnProperty
 
-/** @type {(query: Rule, node: HastNode, index: number|null, parent: Parent|null, state: SelectState) => void} */
+/** @type {(query: Rule, node: Node, index: number|null, parent: Parent|null, state: SelectState) => void} */
 const handle = zwitch('nestingOperator', {
   unknown: unknownNesting,
   // @ts-expect-error: hush.

lib/test.js

@@ -1,6 +1,6 @@
 /**
  * @typedef {import('./types.js').Rule} Rule
- * @typedef {import('./types.js').HastNode} HastNode
+ * @typedef {import('./types.js').Node} Node
  * @typedef {import('./types.js').Parent} Parent
  * @typedef {import('./types.js').SelectState} SelectState
  */
@@ -14,7 +14,7 @@ import {element} from './util.js'
 
 /**
  * @param {Rule} query
- * @param {HastNode} node
+ * @param {Node} node
  * @param {number|null} index
  * @param {Parent|null} parent
  * @param {SelectState} state

lib/types.js

@@ -1,14 +1,13 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('unist').Parent} Parent
  *
  * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').Content} Content
  * @typedef {import('hast').Element} Element
+ * @typedef {import('hast').ElementContent} ElementChild
  * @typedef {import('hast').Properties} Properties
- * @typedef {Element|Root} HastParent
- * @typedef {import('hast').Parent['children'][number]|Root} HastNode
- * @typedef {Element['children'][number]} ElementChild
- * @typedef {Properties[string]} PropertyValue
+ * @typedef {Root|Content} Node
+ * @typedef {Extract<Node, import('hast').Parent>} Parent
+ * @typedef {Properties[keyof Properties]} PropertyValue
  *
  * @typedef {import('css-selector-parser').Selector} Selector
  * @typedef {import('css-selector-parser').Selectors} Selectors
@@ -18,8 +17,8 @@
  * @typedef {import('css-selector-parser').AttrValueType} AttrValueType
  * @typedef {Selector|Rule|RulePseudo} Query
  *
- * Fix for types.
  * @typedef RuleAttr
+ *   Fix for types from `css-selector-parser`.
  * @property {string} name
  * @property {string} [operator]
  * @property {AttrValueType} [valueType]
@@ -68,15 +67,15 @@
 /**
  * @callback SelectIterator
  * @param {Rule} query
- * @param {HastNode} node
+ * @param {Node} node
  * @param {number} index
  * @param {Parent|null} parent
  * @param {SelectState} state
  */
 
 /**
  * @typedef {(
- *  ((query: Rule, node: HastNode, index: number|null, parent: Parent|null, state: SelectState) => void)
+ *  ((query: Rule, node: Node, index: number|null, parent: Parent|null, state: SelectState) => void)
  * )} Handler
  */
 

readme.md

@@ -83,16 +83,26 @@ There is no default export.
 
 ### `matches(selector, node[, space])`
 
-Check that the given `node` ([`Node`][node], should be [element][]) matches the
-CSS selector `selector` (`string`, stuff like `a, b` is also supported).
-Also accepts a `space` (enum, `'svg'` or `'html'`, default: `'html'`)
-Returns whether the node matches or not (`boolean`).
+Check that the given `node` matches `selector`.
 
 This only checks the element itself, not the surrounding tree.
 Thus, nesting in selectors is not supported (`p b`, `p > b`), neither are
 selectors like `:first-child`, etc.
 This only checks that the given element matches the selector.
 
+###### Parameters
+
+*   `selector` (`string`)
+    — CSS selector, such as (`h1`, `a, b`)
+*   `node` ([`Node`][node], optional)
+    — node that might match `selector`, should be an element
+*   `space` (`'svg'` or `'html'`, default: `'html'`)
+    — name of namespace
+
+###### Returns
+
+Whether `node` matches `selector` (`boolean`).
+
 ###### Example
 
 ```js
@@ -106,15 +116,27 @@ matches('.classy', h('a', {className: ['classy']})) // => true
 matches('#id', h('a', {id: 'id'})) // => true
 matches('[lang|=en]', h('a', {lang: 'en'})) // => true
 matches('[lang|=en]', h('a', {lang: 'en-GB'})) // => true
-// ...
+// …
 ```
 
 ### `select(selector, tree[, space])`
 
-Select the first [element][] (or `null`) matching the CSS selector `selector` in
-the given `tree` ([`Node`][node]), which could be the tree itself.
-Searches the [tree][] in *[preorder][]*.
-Also accepts a `space` (enum, `'svg'` or `'html'`, default: `'html'`)
+Select the first element that matches `selector` in the given `tree`.
+Searches the tree in *[preorder][]*.
+
+###### Parameters
+
+*   `selector` (`string`)
+    — CSS selector, such as (`h1`, `a, b`)
+*   `tree` ([`Node`][node], optional)
+    — tree to search
+*   `space` (`'svg'` or `'html'`, default: `'html'`)
+    — name of namespace
+
+###### Returns
+
+First element in `tree` that matches `selector` or `null` if nothing is found.
+This could be `tree` itself.
 
 ###### Example
 
@@ -147,10 +169,22 @@ Yields:
 
 ### `selectAll(selector, tree[, space])`
 
-Select all [element][]s (`Array<Element>`) matching the CSS selector `selector`
-in the given `tree` ([`Node`][node]), which could include the tree itself.
-Searches the [tree][] in *[preorder][]*.
-Also accepts a `space` (enum, `'svg'` or `'html'`, default: `'html'`)
+Select all elements that match `selector` in the given `tree`.
+Searches the tree in *preorder*.
+
+###### Parameters
+
+*   `selector` (`string`)
+    — CSS selector, such as (`h1`, `a, b`)
+*   `tree` ([`Node`][node], optional)
+    — tree to search
+*   `space` (`'svg'` or `'html'`, default: `'html'`)
+    — name of namespace
+
+###### Returns
+
+Elements in `tree` that match `selector`.
+This could include `tree` itself.
 
 ###### Example
 
@@ -385,16 +419,12 @@ abide by its terms.
 
 [coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
 
-[tree]: https://github.com/syntax-tree/unist#tree
-
 [preorder]: https://github.com/syntax-tree/unist#preorder
 
 [hast]: https://github.com/syntax-tree/hast
 
 [node]: https://github.com/syntax-tree/hast#nodes
 
-[element]: https://github.com/syntax-tree/hast#element
-
 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
 
 [unist-util-visit]: https://github.com/syntax-tree/unist-util-visit