Add more info on property names and values · syntax-tree/hast@6b0a9ce (original) (raw)

`@@ -16,10 +16,10 @@ The reason for introducing a new “virtual” DOM is primarily:

`

16

16

` a lean and stripped down virtual DOM can be used everywhere

`

17

17

`* Most virtual DOMs do not focus on ease of use in transformations

`

18

18

`* Other virtual DOMs cannot represent the syntax of HTML in its

`

19

``

`-

entirety, think comments, document types, and character data

`

``

19

`+

entirety (think comments, document types, and character data)

`

20

20

`* Neither HTML nor virtual DOMs focus on positional information

`

21

21

``

22

``

`-

HAST is a subset of [Unist][], and implemented by [rehype][].

`

``

22

`+

HAST is a subset of [Unist][] and implemented by [rehype][].

`

23

23

``

24

24

`This document may not be released. See [releases][] for released

`

25

25

`` documents. The latest released version is [2.1.0][latest].

``

`@@ -223,22 +223,74 @@ interface Properties {}

`

223

223

`##### Property names

`

224

224

``

225

225

`` Property names are keys on [properties][properties] objects and

``

226

``

`-

reflect HTML attribute names. Often, they have the same value as

`

227

``

`` -

the corresponding HTML attribute (for example, href is a property

``

228

``

`` -

name reflecting the href attribute name).

``

229

``

`-

If the HTML attribute name contains one or more dashes, the HAST

`

230

``

`` -

property name must be camel-cased (for example, ariaLabel is a

``

231

``

`` -

property reflecting the aria-label attribute).

``

232

``

`-

If the HTML attribute is a reserved ECMAScript keyword, a common

`

233

``

`` -

alternative must be used. This is the case for class, which uses

``

234

``

`` -

className in HAST (and DOM), and for, which uses htmlFor.

``

235

``

-

236

``

`` -

DOM uses other prefixes and suffixes too, for example, relList

``

237

``

`` -

for HTML rel attributes. This does not occur in HAST.

``

238

``

-

239

``

`-

When possible, HAST properties must be camel-cased if the HTML property

`

240

``

`` -

name originates from multiple words. For example, the minlength HTML

``

241

``

`` -

attribute is cased as minLength, and typemustmatch as typeMustMatch.

``

``

226

`+

reflect HTML, SVG, ARIA, XML, XMLNS, or XLink attribute names.

`

``

227

`+

Often, they have the same value as the corresponding attribute

`

``

228

`` +

(for example, id is a property name reflecting the id attribute

``

``

229

`+

name), but there are some notable differences.

`

``

230

+

``

231

`` +

These rules aren’t simple. Use hastscript (or

``

``

232

`` +

property-information directly) to help.

``

``

233

+

``

234

`+

The following rules are used to disambiguate the names of attributes and their

`

``

235

`+

corresponding HAST property name.

`

``

236

`+

These rules are based on how ARIA is reflected in the DOM, and

`

``

237

`+

differs from how some (older) HTML attributes are reflected in the DOM.

`

``

238

+

``

239

`+

1. Any name referencing a combinations of multiple words (such as “stroke

`

``

240

`+

miter limit”) becomes a camel-cased property name capitalising each word

`

``

241

`+

boundary.

`

``

242

`+

This includes combinations that are sometimes written as several words.

`

``

243

`` +

For example, stroke-miterlimit becomes strokeMiterLimit, autocorrect

``

``

244

`` +

becomes autoCorrect, and allowfullscreen becomes allowFullScreen.

``

``

245

`+

1. Any name that can be hyphenated, becomes a camel-cased property name

`

``

246

`+

capitalising each boundary.

`

``

247

`` +

For example, “read-only” becomes readOnly.

``

``

248

`+

1. Compound words that are not used with spaces or hyphens are treated as a

`

``

249

`+

normal word and the previous rules apply.

`

``

250

`+

For example, “placeholder”, “strikethrough”, and “playback” stay the same.

`

``

251

`+

1. Acronyms in names are treated as a normal word and the previous rules apply.

`

``

252

`` +

For example, itemid become itemId and bgcolor becomes bgColor.

``

``

253

+

``

254

`+

Exceptions

`

``

255

+

``

256

`+

Some jargon is seen as one word even though it may not be seen as such by

`

``

257

`+

dictionaries.

`

``

258

`` +

For example, nohref becomes noHref, playsinline becomes playsInline,

``

``

259

`` +

and accept-charset becomes acceptCharset.

``

``

260

+

``

261

`` +

The HTML attributes class and for respectively become className and

``

``

262

`` +

htmlFor in alignment with the DOM.

``

``

263

`+

No other attributes gain different names as properties, other than a change in

`

``

264

`+

casing.

`

``

265

+

``

266

`+

Notes

`

``

267

+

``

268

`+

The HAST rules for property names differ from how HTML is reflected in the DOM

`

``

269

`+

for the following attributes:

`

``

270

+

``

271

`+

`

242

294

``

243

295

`##### Property values

`

244

296

``

`` @@ -247,13 +299,11 @@ property name. For example, the following HTML <div hidden></div>

``

247

299

`` contains a hidden (boolean) attribute, which is reflected as a hidden

``

248

300

`` property name set to true (boolean) as value in HAST, and

``

249

301

`` <input minlength="5">, which contains a minlength (valid

``

250

``

`` -

non-negative integer) attribute, is reflected as a property minLength

``

``

302

`` +

integer) attribute, is reflected as a property minLength

``

251

303

`` set to 5 (number) in HAST.

``

252

304

``

253

``

`` -

In JSON, the property value null must be treated as if the

``

254

``

`-

property was not included.

`

255

``

`` -

In JavaScript, both null and undefined must be similarly

``

256

``

`-

ignored.

`

``

305

`` +

In JSON, the value null must be treated as if the property was not included.

``

``

306

`` +

In JavaScript, both null and undefined must be similarly ignored.

``

257

307

``

258

308

`The DOM is strict in reflecting those properties, and HAST is not,

`

259

309

`` where the DOM treats <div hidden=no></div> as having a true

``

`` @@ -262,7 +312,7 @@ as having a 0 (number) value for the width attribute, these should

``

262

312

`` be reflected as 'no' and 'yes', respectively, in HAST.

``

263

313

``

264

314

`> The reason for this is to allow plug-ins and utilities to inspect

`

265

``

`-

these values.

`

``

315

`+

these non-standard values.

`

266

316

``

267

317

`The DOM also specifies comma- and space-separated lists attribute

`

268

318

`values. In HAST, these should be treated as ordered lists.

`

`@@ -444,3 +494,9 @@ Thanks to @kthjm

`

444

494

`[license]: https://creativecommons.org/licenses/by/4.0/

`

445

495

``

446

496

`[author]: http://wooorm.com

`

``

497

+

``

498

`+

`

``

499

+

``

500

`+

`

``

501

+

``

502

`+

`