readme.md
1# hastscript [![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Size][size-badge]][size] [![Chat][chat-badge]][chat]
2
3[Hyperscript][] (and [`virtual-hyperscript`][virtual-hyperscript])
4compatible DSL for creating virtual [HAST][] trees in HTML and SVG.
5
6## Installation
7
8[npm][]:
9
10```bash
11npm install hastscript
12```
13
14## Usage
15
16```javascript
17var h = require('hastscript')
18var s = require('hastscript/svg')
19
20// Child nodes as an array
21console.log(
22 h('.foo#some-id', [
23 h('span', 'some text'),
24 h('input', {type: 'text', value: 'foo'}),
25 h('a.alpha', {class: 'bravo charlie', download: 'download'}, [
26 'delta',
27 'echo'
28 ])
29 ])
30)
31
32// Child nodes as arguments
33console.log(
34 h(
35 'form',
36 {method: 'POST'},
37 h('input', {type: 'text', name: 'foo'}),
38 h('input', {type: 'text', name: 'bar'}),
39 h('input', {type: 'submit', value: 'send'})
40 )
41)
42
43console.log(
44 s('svg', {xmlns: 'http://www.w3.org/2000/svg', viewbox: '0 0 500 500'}, [
45 s('title', 'SVG `<circle>` element'),
46 s('circle', {cx: 120, cy: 120, r: 100})
47 ])
48)
49```
50
51Yields:
52
53```js
54{ type: 'element',
55 tagName: 'div',
56 properties: { className: [ 'foo' ], id: 'some-id' },
57 children:
58 [ { type: 'element',
59 tagName: 'span',
60 properties: {},
61 children: [ { type: 'text', value: 'some text' } ] },
62 { type: 'element',
63 tagName: 'input',
64 properties: { type: 'text', value: 'foo' },
65 children: [] },
66 { type: 'element',
67 tagName: 'a',
68 properties: { className: [ 'alpha', 'bravo', 'charlie' ], download: true },
69 children:
70 [ { type: 'text', value: 'delta' },
71 { type: 'text', value: 'echo' } ] } ] }
72{ type: 'element',
73 tagName: 'form',
74 properties: { method: 'POST' },
75 children:
76 [ { type: 'element',
77 tagName: 'input',
78 properties: { type: 'text', name: 'foo' },
79 children: [] },
80 { type: 'element',
81 tagName: 'input',
82 properties: { type: 'text', name: 'bar' },
83 children: [] },
84 { type: 'element',
85 tagName: 'input',
86 properties: { type: 'submit', value: 'send' },
87 children: [] } ] }
88{ type: 'element',
89 tagName: 'svg',
90 properties: { xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 500 500' },
91 children:
92 [ { type: 'element',
93 tagName: 'title',
94 properties: {},
95 children: [ { type: 'text', value: 'SVG `<circle>` element' } ] },
96 { type: 'element',
97 tagName: 'circle',
98 properties: { cx: 120, cy: 120, r: 100 },
99 children: [] } ] }
100```
101
102## API
103
104### `h(selector?[, properties][, ...children])`
105
106### `s(selector?[, properties][, ...children])`
107
108DSL to create virtual [HAST][] trees for HTML or SVG.
109
110##### Parameters
111
112###### `selector`
113
114Simple CSS selector (`string`, optional). Can contain a tag name (`foo`), IDs
115(`#bar`), and classes (`.baz`).
116If there is no tag name in the selector, `h` defaults to a `div` element,
117and `s` to a `g` element.
118
119###### `properties`
120
121Map of properties (`Object.<*>`, optional).
122
123###### `children`
124
125(Lists of) child nodes (`string`, `Node`, `Array.<string|Node>`, optional).
126When strings are encountered, they are normalised to [`text`][text] nodes.
127
128##### Returns
129
130[`Element`][element].
131
132## Contribute
133
134See [`contributing.md` in `syntax-tree/hast`][contributing] for ways to get
135started.
136
137This organisation has a [Code of Conduct][coc]. By interacting with this
138repository, organisation, or community you agree to abide by its terms.
139
140## License
141
142[MIT][license] © [Titus Wormer][author]
143
144<!-- Definitions -->
145
146[build-badge]: https://img.shields.io/travis/syntax-tree/hastscript.svg
147
148[build]: https://travis-ci.org/syntax-tree/hastscript
149
150[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hastscript.svg
151
152[coverage]: https://codecov.io/github/syntax-tree/hastscript
153
154[downloads-badge]: https://img.shields.io/npm/dm/hastscript.svg
155
156[downloads]: https://www.npmjs.com/package/hastscript
157
158[size-badge]: https://img.shields.io/bundlephobia/minzip/hastscript.svg
159
160[size]: https://bundlephobia.com/result?p=hastscript
161
162[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
163
164[chat]: https://spectrum.chat/unified/rehype
165
166[npm]: https://docs.npmjs.com/cli/install
167
168[license]: license
169
170[author]: https://wooorm.com
171
172[hast]: https://github.com/syntax-tree/hast
173
174[element]: https://github.com/syntax-tree/hast#element
175
176[virtual-hyperscript]: https://github.com/Matt-Esch/virtual-dom/tree/master/virtual-hyperscript
177
178[hyperscript]: https://github.com/dominictarr/hyperscript
179
180[text]: https://github.com/syntax-tree/unist#text
181
182[contributing]: https://github.com/syntax-tree/hast/blob/master/contributing.md
183
184[coc]: https://github.com/syntax-tree/hast/blob/master/code-of-conduct.md
185
