Refactor docs

Author: wooorm

index.js

@@ -1,7 +1,9 @@
 /**
- * @typedef {import('hast-util-to-jsx-runtime').Components} Components
  * @typedef {import('hast-util-to-jsx-runtime').ExtraProps} ExtraProps
+ * @typedef {import('./lib/index.js').AllowElement} AllowElement
+ * @typedef {import('./lib/index.js').Components} Components
  * @typedef {import('./lib/index.js').Options} Options
+ * @typedef {import('./lib/index.js').UrlTransform} UrlTransform
  */
 
 export {Markdown as default, defaultUrlTransform} from './lib/index.js'

lib/index.js

@@ -7,15 +7,15 @@
  * @typedef {import('hast').Nodes} Nodes
  * @typedef {import('hast').Parents} Parents
  * @typedef {import('hast').Root} Root
- * @typedef {import('hast-util-to-jsx-runtime').Components} Components
+ * @typedef {import('hast-util-to-jsx-runtime').Components} JsxRuntimeComponents
  * @typedef {import('remark-rehype').Options} RemarkRehypeOptions
  * @typedef {import('unist-util-visit').BuildVisitor<Root>} Visitor
  * @typedef {import('unified').PluggableList} PluggableList
  */
 
 /**
  * @callback AllowElement
- *   Decide if `element` should be allowed.
+ *   Filter elements.
  * @param {Readonly<Element>} element
  *   Element to check.
  * @param {number} index
@@ -25,6 +25,9 @@
  * @returns {boolean | null | undefined}
  *   Whether to allow `element` (default: `false`).
  *
+ * @typedef {Partial<JsxRuntimeComponents>} Components
+ *   Map tag names to components.
+ *
  * @typedef Deprecation
  *   Deprecation.
  * @property {string} from
@@ -37,20 +40,20 @@
  * @typedef Options
  *   Configuration.
  * @property {AllowElement | null | undefined} [allowElement]
- *   Function called to check if an element is allowed (when truthy) or not,
- *   `allowedElements` or `disallowedElements` is used first!
+ *   Filter elements (optional);
+ *   `allowedElements` / `disallowedElements` is used first.
  * @property {ReadonlyArray<string> | null | undefined} [allowedElements]
- *   Tag names to allow (cannot combine w/ `disallowedElements`), all tag names
- *   are allowed by default.
+ *   Tag names to allow (default: all tag names);
+ *   cannot combine w/ `disallowedElements`.
  * @property {string | null | undefined} [children]
- *   Markdown to parse.
+ *   Markdown.
  * @property {string | null | undefined} [className]
- *   Wrap the markdown in a `div` with this class name.
- * @property {Partial<Components> | null | undefined} [components]
- *   Map tag names to React components.
+ *   Wrap in a `div` with this class name.
+ * @property {Components | null | undefined} [components]
+ *   Map tag names to components.
  * @property {ReadonlyArray<string> | null | undefined} [disallowedElements]
- *   Tag names to disallow (cannot combine w/ `allowedElements`), all tag names
- *   are allowed by default.
+ *   Tag names to disallow (default: `[]`);
+ *   cannot combine w/ `allowedElements`.
  * @property {PluggableList | null | undefined} [rehypePlugins]
  *   List of rehype plugins to use.
  * @property {PluggableList | null | undefined} [remarkPlugins]
@@ -60,16 +63,16 @@
  * @property {boolean | null | undefined} [skipHtml=false]
  *   Ignore HTML in markdown completely (default: `false`).
  * @property {boolean | null | undefined} [unwrapDisallowed=false]
- *   Extract (unwrap) the children of not allowed elements (default: `false`);
- *   normally when say `strong` is disallowed, it and it’s children are dropped,
+ *   Extract (unwrap) what’s in disallowed elements (default: `false`);
+ *   normally when say `strong` is not allowed, it and it’s children are dropped,
  *   with `unwrapDisallowed` the element itself is replaced by its children.
  * @property {UrlTransform | null | undefined} [urlTransform]
  *   Change URLs (default: `defaultUrlTransform`)
  *
  * @callback UrlTransform
- *   Transform URLs.
+ *   Transform all URLs.
  * @param {string} url
- *   URL to transform.
+ *   URL.
  * @param {string} key
  *   Property name (example: `'href'`).
  * @param {Readonly<Element>} node
@@ -139,8 +142,7 @@ const deprecations = [
  * Component to render markdown.
  *
  * @param {Readonly<Options>} options
- *   Configuration (required).
- *   Note: React types require that props are passed.
+ *   Props.
  * @returns {JSX.Element}
  *   React element.
  */

package.json

@@ -82,6 +82,7 @@
     "hast-util-to-jsx-runtime": "^2.0.0",
     "html-url-attributes": "^3.0.0",
     "mdast-util-to-hast": "^13.0.0",
+    "micromark-util-sanitize-uri": "^2.0.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.0.0",
     "unified": "^11.0.0",