# hast-util-to-estree
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[hast][github-hast] utility to transform to [estree][github-estree] (JSX).
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`toEstree(tree[, options])`](#toestreetree-options)
* [`defaultHandlers`](#defaulthandlers)
* [`ElementAttributeNameCase`](#elementattributenamecase)
* [`Handle`](#handle)
* [`Options`](#options)
* [`Space`](#space)
* [`State`](#state)
* [`StylePropertyNameCase`](#stylepropertynamecase)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)
## What is this?
This package is a utility that takes a
[hast][github-hast] (HTML)
syntax tree as input and turns it into an
[estree][github-estree] (JavaScript)
syntax tree (with a JSX extension).
This package also supports embedded MDX nodes.
## When should I use this?
This project is useful when you want to embed HTML as JSX inside JS while
working with syntax trees.
This is used in [MDX][mdxjs].
## Install
This package is [ESM only][github-gist-esm].
In Node.js (version 16+), install with [npm][npmjs-install]:
```sh
npm install hast-util-to-estree
```
In Deno with [`esm.sh`][esmsh]:
```js
import {toEstree} from 'https://esm.sh/hast-util-to-estree@3'
```
In browsers with [`esm.sh`][esmsh]:
```html
```
## Use
Say our module `example.html` contains:
```html
Hi!
{'\n'}
{'\n'}
{}
{'\n'}
{'\n'}
{'\n'}
```
## API
This package exports the identifiers [`defaultHandlers`][api-default-handlers]
and [`toEstree`][api-to-estree].
There is no default export.
### `toEstree(tree[, options])`
Transform a hast tree (with embedded MDX nodes) into an estree (with JSX
nodes).
##### Notes
###### Comments
Comments are attached to the tree in their neighbouring nodes (`recast`,
`babel` style) and also added as a `comments` array on the program node
(`espree` style).
You may have to do `program.comments = undefined` for certain compilers.
###### Frameworks
There are differences between what JSX frameworks accept, such as whether they
accept `class` or `className`, or `background-color` or `backgroundColor`.
For JSX components written in MDX, the author has to be aware of this
difference and write code accordingly.
For hast elements transformed by this project, this will be handled through
options.
| Framework | `elementAttributeNameCase` | `stylePropertyNameCase` |
| --------- | -------------------------- | ----------------------- |
| Preact | `'html'` | `'dom'` |
| React | `'react'` | `'dom'` |
| Solid | `'html'` | `'css'` |
| Vue | `'html'` | `'dom'` |
###### Parameters
* `tree` ([`HastNode`][github-hast-nodes])
— hast tree
* `options` ([`Options`][api-options], optional)
— configuration
###### Returns
estree program node ([`Program`][github-estree-program]).
The program’s last child in `body` is most likely an `ExpressionStatement`,
whose expression is a `JSXFragment` or a `JSXElement`.
Typically, there is only one node in `body`, however, this utility also supports
embedded MDX nodes in the HTML
(when [`mdast-util-mdx`][github-mdast-util-mdx] is used with mdast to parse
markdown before passing its nodes through to hast).
When MDX ESM import/exports are used, those nodes are added before the fragment
or element in body.
There aren’t many great estree serializers out there that support JSX.
To do that, you can use [`estree-util-to-js`][github-estree-util-to-js].
Or, use [`estree-util-build-jsx`][github-estree-util-build-jsx]
to turn JSX into function calls,
and then serialize with whatever (`astring`, `escodegen`).
### `defaultHandlers`
Default handlers for elements (`Record`).
Each key is a node type, each value is a [`Handle`][api-handle].
### `ElementAttributeNameCase`
Specify casing to use for attribute names (TypeScript type).
HTML casing is for example `class`, `stroke-linecap`, `xml:lang`.
React casing is for example `className`, `strokeLinecap`, `xmlLang`.
###### Type
```ts
type ElementAttributeNameCase = 'html' | 'react'
```
### `Handle`
Turn a hast node into an estree node (TypeScript type).
###### Parameters
* `node` ([`HastNode`][github-hast-nodes])
— expected hast node
* `state` ([`State`][api-state])
— info passed around about the current state
###### Returns
JSX child (`JsxChild`, optional).
You can also add more results to `state.esm` and `state.comments`.
### `Options`
Configuration (TypeScript type).
###### Fields
* `elementAttributeNameCase`
([`ElementAttributeNameCase`][api-element-attribute-name-case], default:
`'react'`)
— specify casing to use for attribute names; this casing is used for hast
elements, not for embedded MDX JSX nodes (components that someone authored
manually)
* `handlers` (`Record`, optional)
— custom handlers
* `space` ([`Space`][api-space], default: `'html'`)
— which space the document is in; when an `