Skip to content

Commit 167e6f7

Browse files
committed
Add docs to types
1 parent 2d809f5 commit 167e6f7

File tree

1 file changed

+65
-17
lines changed

1 file changed

+65
-17
lines changed

lib/index.js

Lines changed: 65 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,57 @@
1414
* @typedef {import('estree-jsx').JSXIdentifier} JSXIdentifier
1515
*
1616
* @typedef Options
17-
* @property {'automatic'|'classic'} [runtime='classic']
17+
* Configuration (optional).
18+
*
19+
* > 👉 **Note**: you can also configure `runtime`, `importSource`, `pragma`,
20+
* > and `pragmaFrag` from within files through comments.
21+
* @property {'automatic' | 'classic'} [runtime='classic']
22+
* Choose the runtime.
23+
*
24+
* Comment form: `@jsxRuntime theRuntime`.
1825
* @property {string} [importSource='react']
26+
* Place to import `jsx`, `jsxs`, `jsxDEV`, and/or `Fragment` from, when the
27+
* effective runtime is automatic.
28+
*
29+
* Comment form: `@jsxImportSource theSource`.
30+
*
31+
* > 👉 **Note**: `/jsx-runtime` or `/jsx-dev-runtime` is appended to this
32+
* > provided source.
33+
* > In CJS, that can resolve to a file, as in `theSource/jsx-runtime.js`,
34+
* > but for ESM an export map needs to be set up to point to files:
35+
* >
36+
* > ```js
37+
* > // …
38+
* > "exports": {
39+
* > // …
40+
* > "./jsx-runtime": "./path/to/jsx-runtime.js",
41+
* > "./jsx-dev-runtime": "./path/to/jsx-runtime.js"
42+
* > // …
43+
* > ```
1944
* @property {string} [pragma='React.createElement']
45+
* Identifier or member expression to call when the effective runtime is
46+
* classic.
47+
*
48+
* Comment form: `@jsx identifier`.
2049
* @property {string} [pragmaFrag='React.Fragment']
50+
* Identifier or member expression to use as a symbol for fragments when the
51+
* effective runtime is classic.
52+
*
53+
* Comment form: `@jsxFrag identifier`.
2154
* @property {boolean} [development=false]
55+
* Import `jsxDEV` from `theSource/jsx-dev-runtime.js` and add location info
56+
* on where a component originated from.
57+
*
58+
* This helps debugging but adds a lot of code that you don’t want in
59+
* production.
60+
* Only used in the automatic runtime.
2261
* @property {string} [filePath]
62+
* File path to the original source file.
63+
* Used in the location info when using the automatic runtime with
64+
* `development: true`.
2365
*
2466
* @typedef Annotations
25-
* @property {'automatic'|'classic'} [jsxRuntime]
67+
* @property {'automatic' | 'classic'} [jsxRuntime]
2668
* @property {string} [jsx]
2769
* @property {string} [jsxFrag]
2870
* @property {string} [jsxImportSource]
@@ -35,11 +77,17 @@ import {name as isIdentifierName} from 'estree-util-is-identifier-name'
3577
const regex = /@(jsx|jsxFrag|jsxImportSource|jsxRuntime)\s+(\S+)/g
3678

3779
/**
38-
* @template {Node} T
39-
* @param {T} tree
80+
* Turn JSX in `tree` into function calls: `<x />` -> `h('x')`!
81+
*
82+
* @template {Node} Tree
83+
* @param {Tree} tree
84+
* Tree to transform.
4085
* @param {Options} [options={}]
41-
* @returns {T}
86+
* Configuration (optional).
87+
* @returns {Tree}
88+
* Given, modified, tree.
4289
*/
90+
// To do next major: do not return the given Node.
4391
export function buildJsx(tree, options = {}) {
4492
let automatic = options.runtime === 'automatic'
4593
/** @type {Annotations} */
@@ -194,15 +242,15 @@ export function buildJsx(tree, options = {}) {
194242
}
195243
}
196244

197-
/** @type {MemberExpression|Literal|Identifier} */
245+
/** @type {MemberExpression | Literal | Identifier} */
198246
let name
199247
/** @type {Array<Property>} */
200248
let fields = []
201249
/** @type {Array<Expression>} */
202250
const objects = []
203-
/** @type {Array<Expression|SpreadElement>} */
251+
/** @type {Array<Expression | SpreadElement>} */
204252
let parameters = []
205-
/** @type {Expression|undefined} */
253+
/** @type {Expression | undefined} */
206254
let key
207255

208256
// Do the stuff needed for elements.
@@ -215,7 +263,7 @@ export function buildJsx(tree, options = {}) {
215263
name = create(name, {type: 'Literal', value: name.name})
216264
}
217265

218-
/** @type {boolean|undefined} */
266+
/** @type {boolean | undefined} */
219267
let spread
220268
const attributes = node.openingElement.attributes
221269
let index = -1
@@ -289,9 +337,9 @@ export function buildJsx(tree, options = {}) {
289337
objects.push({type: 'ObjectExpression', properties: fields})
290338
}
291339

292-
/** @type {Expression|undefined} */
340+
/** @type {Expression | undefined} */
293341
let props
294-
/** @type {MemberExpression|Literal|Identifier} */
342+
/** @type {MemberExpression | Literal | Identifier} */
295343
let callee
296344

297345
if (objects.length > 1) {
@@ -450,11 +498,11 @@ function toProperty(node) {
450498
}
451499

452500
/**
453-
* @param {JSXMemberExpression|JSXNamespacedName|JSXIdentifier} node
454-
* @returns {MemberExpression|Identifier|Literal}
501+
* @param {JSXMemberExpression | JSXNamespacedName | JSXIdentifier} node
502+
* @returns {MemberExpression | Identifier | Literal}
455503
*/
456504
function toIdentifier(node) {
457-
/** @type {MemberExpression|Identifier|Literal} */
505+
/** @type {MemberExpression | Identifier | Literal} */
458506
let replace
459507

460508
if (node.type === 'JSXMemberExpression') {
@@ -486,16 +534,16 @@ function toIdentifier(node) {
486534

487535
/**
488536
* @param {string} id
489-
* @returns {Identifier|Literal|MemberExpression}
537+
* @returns {Identifier | Literal | MemberExpression}
490538
*/
491539
function toMemberExpression(id) {
492540
const identifiers = id.split('.')
493541
let index = -1
494-
/** @type {Identifier|Literal|MemberExpression|undefined} */
542+
/** @type {Identifier | Literal | MemberExpression | undefined} */
495543
let result
496544

497545
while (++index < identifiers.length) {
498-
/** @type {Identifier|Literal} */
546+
/** @type {Identifier | Literal} */
499547
const prop = isIdentifierName(identifiers[index])
500548
? {type: 'Identifier', name: identifiers[index]}
501549
: {type: 'Literal', value: identifiers[index]}

0 commit comments

Comments
 (0)