Add supported data fields to Data of mdast

Author: wooorm

index.d.ts

@@ -1,5 +1,4 @@
-import type {Data, Literal} from 'hast'
-import type {State} from './lib/state.js'
+import type {Data, ElementContent, Literal, Properties} from 'hast'
 
 // Expose types.
 export type {Handler, Handlers, Options, State} from './lib/state.js'
@@ -44,3 +43,35 @@ declare module 'hast' {
     raw: Raw
   }
 }
+
+// Register data on mdast.
+declare module 'mdast' {
+  interface Data {
+    /**
+     * Field supported by `mdast-util-to-hast` to signal that a node should
+     * result in something with these children.
+     *
+     * When this is defined, when a parent is created, these children will
+     * be used.
+     */
+    hChildren?: ElementContent[] | undefined
+
+    /**
+     * Field supported by `mdast-util-to-hast` to signal that a node should
+     * result in a particular element, instead of its default behavior.
+     *
+     * When this is defined, an element with the given tag name is created.
+     * For example, when setting `hName` to `'b'`, a `<b>` element is created.
+     */
+    hName?: string | undefined
+
+    /**
+     * Field supported by `mdast-util-to-hast` to signal that a node should
+     * result in an element with these properties.
+     *
+     * When this is defined, when an element is created, these properties will
+     * be used.
+     */
+    hProperties?: Properties | undefined
+  }
+}

lib/state.js

@@ -13,27 +13,6 @@
  */
 
 /**
- * @typedef EmbeddedHastFields
- *   hast fields.
- * @property {string | undefined} [hName]
- *   Generate a specific element with this tag name instead.
- * @property {HastProperties | undefined} [hProperties]
- *   Generate an element with these properties instead.
- * @property {Array<HastElementContent> | undefined} [hChildren]
- *   Generate an element with this content instead.
- *
- *   To do: type data!
- *
- * @typedef {Record<string, unknown> & EmbeddedHastFields} MdastData
- *   mdast data with embedded hast fields.
- *
- *   To do: type data!
- *
- * @typedef {MdastNodes & {data?: MdastData | undefined}} MdastNodeWithData
- *   mdast node with embedded hast data.
- *
- *   To do: type data!
- *
  * @callback Handler
  *   Handle a node.
  * @param {State} state
@@ -309,7 +288,6 @@ function applyData(from, to) {
       hChildren !== null &&
       hChildren !== undefined
     ) {
-      // @ts-expect-error: assume valid children are defined.
       result.children = hChildren
     }
   }

readme.md

@@ -269,11 +269,14 @@ Raw string of HTML embedded into HTML AST (TypeScript).
 ###### Type
 
 ```ts
-import type {Literal} from 'hast'
+import type {Data, Literal} from 'hast'
 
 interface Raw extends Literal {
   type: 'raw'
+  data?: RawData | undefined
 }
+
+interface RawData extends Data {}
 ```
 
 ### `State`
@@ -1341,10 +1344,10 @@ Raw nodes are typically ignored but are handled by
 ## Types
 
 This package is fully typed with [TypeScript][].
-It also exports [`Handler`][api-handler], [`Handlers`][api-handlers],
+It exports the [`Handler`][api-handler], [`Handlers`][api-handlers],
 [`Options`][api-options], [`Raw`][api-raw], and [`State`][api-state] types.
 
-It also registers the `Raw` node type with `@types/mdast`.
+It also registers the `Raw` node type with `@types/hast`.
 If you’re working with the syntax tree (and you pass
 `allowDangerousHtml: true`), make sure to import this utility somewhere in your
 types, as that registers the new node type in the tree.
@@ -1364,6 +1367,24 @@ visit(tree, function (node) {
 })
 ```
 
+Finally, it also registers the `hChildren`, `hName`, and `hProperties` fields
+on `Data` of `@types/mdast`.
+If you’re working with the syntax tree, make sure to import this utility
+somewhere in your types, as that registers the data fields in the tree.
+
+```js
+/**
+ * @typedef {import('mdast-util-to-hast')}
+ */
+
+import {visit} from 'unist-util-visit'
+
+/** @type {import('hast').Root} */
+const tree = { /* … */ }
+
+console.log(tree.data?.hName) // Types as `string | undefined`.
+```
+
 ## Compatibility
 
 Projects maintained by the unified collective are compatible with maintained

test/core.js

@@ -39,6 +39,7 @@ test('toHast', async function (t) {
     assert.deepEqual(
       toHast({
         type: 'strong',
+        // @ts-expect-error: remove when `h` is updated to support new hast.
         data: {hChildren: [h('i', 'bravo')]},
         children: [{type: 'text', value: 'charlie'}]
       }),