Skip to content
This repository was archived by the owner on Aug 9, 2023. It is now read-only.

Commit ab9f564

Browse files
wooormwooorm
committed
Mark as legacy
1 parent 6f6e746 commit ab9f564

File tree

2 files changed

+11
-360
lines changed

2 files changed

+11
-360
lines changed

‎package.json

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,9 @@
11
{
22
"name": "hast-to-hyperscript",
33
"version": "10.0.1",
4-
"description": "hast utility to transform to something else (react, vue, etc) through a hyperscript DSL",
4+
"description": "Legacy hast utility to transform to something else",
55
"license": "MIT",
6-
"keywords": [
7-
"unist",
8-
"hast",
9-
"hast-util",
10-
"util",
11-
"utility",
12-
"html",
13-
"change",
14-
"transform",
15-
"rehype",
16-
"vdom",
17-
"virtual",
18-
"dom",
19-
"hyperscript",
20-
"dsl"
21-
],
6+
"keywords": [],
227
"repository": "syntax-tree/hast-to-hyperscript",
238
"bugs": "https://github.com/syntax-tree/hast-to-hyperscript/issues",
249
"funding": {

‎readme.md

Lines changed: 9 additions & 343 deletions
Original file line numberDiff line numberDiff line change
@@ -1,357 +1,23 @@
11
# hast-to-hyperscript
22

3-
[![Build][build-badge]][build]
4-
[![Coverage][coverage-badge]][coverage]
5-
[![Downloads][downloads-badge]][downloads]
6-
[![Size][size-badge]][size]
7-
[![Sponsors][sponsors-badge]][collective]
8-
[![Backers][backers-badge]][collective]
9-
[![Chat][chat-badge]][chat]
3+
**Stability: Legacy**.
4+
This package is no longer recommended for use.
5+
It’s still covered by semantic-versioning guarantees and not yet deprecated,
6+
but use of this package should be avoided.
7+
Please use [`hast-util-to-jsx-runtime`][hast-util-to-jsx-runtime] instead,
8+
which is much better.
109

11-
[hast][] utility to turn hast into React, Preact, Vue, etc.
12-
13-
## Contents
14-
15-
* [What is this?](#what-is-this)
16-
* [When should I use this?](#when-should-i-use-this)
17-
* [Install](#install)
18-
* [Use](#use)
19-
* [API](#api)
20-
* [`toH(h, tree[, options|prefix])`](#tohh-tree-optionsprefix)
21-
* [`function h(name, props, children)`](#function-hname-props-children)
22-
* [Examples](#examples)
23-
* [Example: React](#example-react)
24-
* [Example: Preact](#example-preact)
25-
* [Example: Vue](#example-vue)
26-
* [Types](#types)
27-
* [Compatibility](#compatibility)
28-
* [Security](#security)
29-
* [Related](#related)
30-
* [Contribute](#contribute)
31-
* [License](#license)
32-
33-
## What is this?
34-
35-
This package is a utility that can be used to turn hast into something else
36-
through a “hyperscript” interface.
37-
38-
[`hyperscript`][hyperscript] is a rather old package that made HTML from
39-
JavaScript and its API was later modelled by `createElement` from
40-
[`react`][react] (and [`preact`][preact]) and `h` from
41-
`hyperscript`, [`virtual-dom`][virtual-dom] (and [`vue`][vue]).
42-
43-
This package uses that API to translate between hast and anything else.
44-
45-
## When should I use this?
46-
47-
you can use this utility when you need to turn hast into something else,
48-
either through a “hyperscript” interface that already exists (`createElement`
49-
from `react` and `preact` or `h` from `hyperscript`, `virtual-dom`, `vue`),
50-
or through such a translation function that you make yourself.
51-
52-
## Install
53-
54-
This package is [ESM only][esm].
55-
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
56-
57-
```sh
58-
npm install hast-to-hyperscript
59-
```
60-
61-
In Deno with [`esm.sh`][esmsh]:
62-
63-
```js
64-
import {toH} from 'https://esm.sh/hast-to-hyperscript@10'
65-
```
66-
67-
In browsers with [`esm.sh`][esmsh]:
68-
69-
```html
70-
<script type="module">
71-
import {toH} from 'https://esm.sh/hast-to-hyperscript@10?bundle'
72-
</script>
73-
```
74-
75-
## Use
76-
77-
```js
78-
import {toH} from 'hast-to-hyperscript'
79-
import h from 'hyperscript'
80-
81-
const tree = {
82-
type: 'element',
83-
tagName: 'p',
84-
properties: {id: 'alpha', className: ['bravo']},
85-
children: [
86-
{type: 'text', value: 'charlie '},
87-
{
88-
type: 'element',
89-
tagName: 'strong',
90-
properties: {style: 'color: red;'},
91-
children: [{type: 'text', value: 'delta'}]
92-
},
93-
{type: 'text', value: ' echo.'}
94-
]
95-
}
96-
97-
// Transform (`hyperscript` needs `outerHTML` to serialize):
98-
const doc = toH(h, tree).outerHTML
99-
100-
console.log(doc)
101-
```
102-
103-
Yields:
104-
105-
```html
106-
<p class="bravo" id="alpha">charlie <strong>delta</strong> echo.</p>
107-
```
108-
109-
## API
110-
111-
This package exports the identifiers `toH`.
112-
There is no default export.
113-
114-
### `toH(h, tree[, options|prefix])`
115-
116-
turn hast into React, Preact, Vue, etc.
117-
118-
###### Parameters
119-
120-
* `h` ([`Function`][h]) — hyperscript function
121-
* `tree` ([`Node`][node]) — tree to transform
122-
* `prefix` — treated as `{prefix: prefix}`
123-
* `options.prefix` (`string` or `boolean`, optional)
124-
— prefix to use as a prefix for keys passed in `props` to `h()`,
125-
this behavior is turned off by passing `false` and turned on by passing
126-
a `string`.
127-
By default, `h-` is used as a prefix if the given `h` is detected as being
128-
`virtual-dom/h` or `React.createElement`
129-
* `options.space` (enum, `'svg'` or `'html'`, default: `'html'`)
130-
— whether `node` is in the `'html'` or `'svg'` space.
131-
If an `<svg>` element is found when inside the HTML space, `toH`
132-
automatically switches to the SVG space when entering the element, and
133-
switches back when exiting
134-
135-
###### Returns
136-
137-
`*` — Anything returned by calling `h()`.
138-
139-
### `function h(name, props, children)`
140-
141-
Create an element from the given values.
142-
143-
###### Parameters
144-
145-
* `this` (`Node`) — node that is currently transformed
146-
* `name` (`string`) — tag name of element to create
147-
* `props` (`Record<string, string>`) — attributes to set
148-
* `children` (`Array<any>`) — list of children (results of previously called
149-
`h()`)
150-
151-
###### Returns
152-
153-
`*` — Anything.
154-
155-
##### Caveats
156-
157-
###### Nodes
158-
159-
Most hyperscript implementations only support elements and texts.
160-
hast supports doctype, comment, and root nodes as well.
161-
162-
* If anything other than an `element` or `root` node is given, `toH` throws
163-
* If a `root` is given with no children, an empty `div` element is returned
164-
* If a `root` is given with one element child, that element is transformed
165-
* Otherwise, the children are wrapped in a `div` element
166-
167-
If unknown nodes (a node with a type not defined by hast) are found as
168-
descendants of the given tree, they are ignored: only text and element are
169-
transformed.
170-
171-
###### Support
172-
173-
Although there are lots of libraries mentioning support for a hyperscript-like
174-
interface, there are significant differences between them.
175-
For example, [`hyperscript`][hyperscript] doesn’t support classes in `props` and
176-
[`virtual-dom/h`][virtual-dom] needs an `attributes` object inside `props` most
177-
of the time.
178-
`toH` works around these differences for:
179-
180-
* [`createElement` from `react`][react]
181-
* `createElement` from Vue 2 and [`h` from `vue` 3+][vue]
182-
* [`virtual-dom/h`][virtual-dom]
183-
* [`hyperscript`][hyperscript]
184-
185-
## Examples
186-
187-
### Example: React
188-
189-
```js
190-
import {createElement} from 'react'
191-
import {renderToStaticMarkup} from 'react-dom/server'
192-
import {h} from 'hastscript'
193-
import {toH} from 'hast-to-hyperscript'
194-
195-
const tree = h('h1', ['Hello, ', h('em', 'world'), '!'])
196-
197-
console.log(renderToStaticMarkup(toH(createElement, tree)));
198-
```
199-
200-
Yields:
201-
202-
```html
203-
<h1>Hello, <em>world</em>!</h1>
204-
```
205-
206-
### Example: Preact
207-
208-
```js
209-
import {createElement} from 'preact'
210-
import render from 'preact-render-to-string'
211-
import {h} from 'hastscript'
212-
import {toH} from 'hast-to-hyperscript'
213-
214-
const tree = h('h1', ['Hello, ', h('em', 'world'), '!'])
215-
216-
console.log(render(toH(createElement, tree)));
217-
```
218-
219-
Yields:
220-
221-
```html
222-
<h1>Hello, <em>world</em>!</h1>
223-
```
224-
225-
### Example: Vue
226-
227-
```js
228-
import * as vue from 'vue'
229-
import serverRenderer from '@vue/server-renderer'
230-
import {h} from 'hastscript'
231-
import {toH} from 'hast-to-hyperscript'
232-
233-
const tree = h('h1', ['Hello, ', h('em', 'world'), '!'])
234-
235-
console.log(await serverRenderer.renderToString(
236-
vue.createSSRApp(() => toH(vue.h, tree))
237-
))
238-
```
239-
240-
Yields:
241-
242-
```html
243-
<h1>Hello, <em>world</em>!</h1>
244-
```
245-
246-
## Types
247-
248-
This package is fully typed with [TypeScript][].
249-
It exports the additional types `CreateElementLike` and `Options`.
250-
251-
## Compatibility
252-
253-
Projects maintained by the unified collective are compatible with all maintained
254-
versions of Node.js.
255-
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
256-
Our projects sometimes work with older versions, but this is not guaranteed.
257-
258-
## Security
259-
260-
Use of `hast-to-hyperscript` can open you up to a
261-
[cross-site scripting (XSS)][xss] attack if the hast tree is unsafe.
262-
Use [`hast-util-sanitize`][hast-util-sanitize] to make the hast tree safe.
263-
264-
## Related
265-
266-
* [`hastscript`](https://github.com/syntax-tree/hastscript)
267-
— hyperscript compatible interface for creating nodes
268-
* [`hast-util-sanitize`][hast-util-sanitize]
269-
— sanitize nodes
270-
* [`hast-util-from-dom`](https://github.com/syntax-tree/hast-util-from-dom)
271-
— transform a DOM tree to hast
272-
* [`unist-builder`](https://github.com/syntax-tree/unist-builder)
273-
— create any unist tree
274-
* [`xastscript`](https://github.com/syntax-tree/xastscript)
275-
— create a xast tree
276-
277-
## Contribute
278-
279-
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
280-
started.
281-
See [`support.md`][support] for ways to get help.
282-
283-
This project has a [code of conduct][coc].
284-
By interacting with this repository, organization, or community you agree to
285-
abide by its terms.
10+
Legacy [documentation for this package](https://github.com/syntax-tree/hast-to-hyperscript/tree/6f6e746)
11+
is still available in Git.
28612

28713
## License
28814

28915
[MIT][license] © [Titus Wormer][author]
29016

29117
<!-- Definitions -->
29218

293-
[build-badge]: https://github.com/syntax-tree/hast-to-hyperscript/workflows/main/badge.svg
294-
295-
[build]: https://github.com/syntax-tree/hast-to-hyperscript/actions
296-
297-
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-to-hyperscript.svg
298-
299-
[coverage]: https://codecov.io/github/syntax-tree/hast-to-hyperscript
300-
301-
[downloads-badge]: https://img.shields.io/npm/dm/hast-to-hyperscript.svg
302-
303-
[downloads]: https://www.npmjs.com/package/hast-to-hyperscript
304-
305-
[size-badge]: https://img.shields.io/bundlephobia/minzip/hast-to-hyperscript.svg
306-
307-
[size]: https://bundlephobia.com/result?p=hast-to-hyperscript
308-
309-
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
310-
311-
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
312-
313-
[collective]: https://opencollective.com/unified
314-
315-
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
316-
317-
[chat]: https://github.com/syntax-tree/unist/discussions
318-
319-
[npm]: https://docs.npmjs.com/cli/install
320-
321-
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
322-
323-
[esmsh]: https://esm.sh
324-
325-
[typescript]: https://www.typescriptlang.org
326-
32719
[license]: license
32820

32921
[author]: https://wooorm.com
33022

331-
[health]: https://github.com/syntax-tree/.github
332-
333-
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
334-
335-
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
336-
337-
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
338-
339-
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
340-
341-
[hyperscript]: https://github.com/hyperhype/hyperscript
342-
343-
[react]: https://reactjs.org/docs/react-api.html#createelement
344-
345-
[preact]: https://preactjs.com/guide/v8/api-reference/#preacth--preactcreateelement
346-
347-
[virtual-dom]: https://github.com/Matt-Esch/virtual-dom/tree/master/virtual-hyperscript#hselector-properties-children
348-
349-
[vue]: https://vuejs.org/api/render-function.html#h
350-
351-
[hast]: https://github.com/syntax-tree/hast
352-
353-
[node]: https://github.com/syntax-tree/hast#nodes
354-
355-
[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
356-
357-
[h]: #function-hname-props-children
23+
[hast-util-to-jsx-runtime]: https://github.com/syntax-tree/hast-util-to-jsx-runtime

0 commit comments

Comments
 (0)