Add better docs to types

Author: wooorm

.gitignore

@@ -7,3 +7,4 @@ coverage/
 node_modules/
 script/react-data.js
 yarn.lock
+!/index.d.ts

index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Info on a property.
+ */
+export interface Info {
+  /**
+   * Attribute name for the property that could be used in markup
+   * (such as `'aria-describedby'`, `'allowfullscreen'`, `'xml:lang'`,
+   * `'for'`, or `'charoff'`).
+   */
+  attribute: string
+  /**
+   * The property is *like* a `boolean`
+   * (such as `draggable`);
+   * these properties have both an on and off state when defined,
+   * *and* another state when not defined.
+   */
+  booleanish: boolean
+  /**
+   * The property is a `boolean`
+   * (such as `hidden`);
+   * these properties have an on state when defined and an off state when not
+   * defined.
+   */
+  boolean: boolean
+  /**
+   * The property is a list separated by spaces or commas
+   * (such as `strokeDashArray`).
+   */
+  commaOrSpaceSeparated: boolean
+  /**
+   * The property is a list separated by commas
+   * (such as `coords`).
+   */
+  commaSeparated: boolean
+  /**
+   * The property is defined by a space;
+   * this is the case for values in HTML
+   * (including data and ARIA),
+   * SVG, XML, XMLNS, and XLink;
+   * not defined properties can only be found through `find`.
+   */
+  defined: boolean
+  /**
+   * When working with the DOM,
+   * this property has to be changed as a field on the element,
+   * instead of through `setAttribute`
+   * (this is true only for `'checked'`, `'multiple'`, `'muted'`, and
+   * `'selected'`).
+   */
+  mustUseProperty: boolean
+  /**
+   * The property is a `number` (such as `height`).
+   */
+  number: boolean
+  /**
+   * The property is *like* a `boolean` (such as `download`);
+   * these properties have an on state *and* more states when defined and an
+   * off state when not defined.
+   */
+  overloadedBoolean: boolean
+  /**
+   * JavaScript-style camel-cased name;
+   * based on the DOM but sometimes different
+   * (such as `'ariaDescribedBy'`, `'allowFullScreen'`, `'xmlLang'`,
+   * `'htmlFor'`, `'charOff'`).
+   */
+  property: string
+  /**
+   * The property is a list separated by spaces
+   * (such as `className`).
+   */
+  spaceSeparated: boolean
+  /**
+   * Space of the property.
+   */
+  space: Space | null
+}
+
+/**
+ * Schema for a primary space.
+ */
+export interface Schema {
+  /**
+   * Object mapping normalized attributes and properties to properly cased
+   * properties.
+   */
+  normal: Record<string, string>
+  /**
+   * Object mapping properties to info.
+   */
+  property: Record<string, Info>
+  space: Space | null
+}
+
+/**
+ * Space of a property.
+ */
+export type Space = 'html' | 'svg' | 'xlink' | 'xmlns' | 'xml'
+
+export {find} from './lib/find.js'
+
+export {hastToReact} from './lib/hast-to-react.js'
+
+/**
+ * `Schema` for HTML,
+ * with info on properties from HTML itself and related embedded spaces
+ * (ARIA, XML, XMLNS, XLink).
+ */
+export const html: Schema
+
+export {normalize} from './lib/normalize.js'
+
+/**
+ * `Schema` for SVG,
+ * with info on properties from SVG itself and related embedded spaces
+ * (ARIA, XML, XMLNS, XLink).
+ */
+export const svg: Schema

index.js

@@ -1,8 +1,4 @@
-/**
- * @typedef {import('./lib/util/info.js').Info} Info
- * @typedef {import('./lib/util/schema.js').Schema} Schema
- */
-
+// Note: types exposed from `index.d.ts`.
 import {merge} from './lib/util/merge.js'
 import {xlink} from './lib/xlink.js'
 import {xml} from './lib/xml.js'

lib/find.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('./util/schema.js').Schema} Schema
+ * @import {Schema} from '../index.js'
  */
 
 import {normalize} from './normalize.js'
@@ -11,9 +11,34 @@ const dash = /-[a-z]/g
 const cap = /[A-Z]/g
 
 /**
+ * Look up info on a property.
+ *
+ * In most cases the given `schema` contains info on the property.
+ * All standard,
+ * most legacy,
+ * and some non-standard properties are supported.
+ * For these cases,
+ * the returned `Info` has hints about the value of the property.
+ *
+ * `name` can also be a valid data attribute or property,
+ * in which case an `Info` object with the correctly cased `attribute` and
+ * `property` is returned.
+ *
+ * `name` can be an unknown attribute,
+ * in which case an `Info` object with `attribute` and `property` set to the
+ * given name is returned.
+ * It is not recommended to provide unsupported legacy or recently specced
+ * properties.
+ *
+ *
  * @param {Schema} schema
+ *   Schema;
+ *   either the `html` or `svg` export
  * @param {string} value
+ *   An attribute-like or property-like name;
+ *   it will be passed through `normalize` to hopefully find the correct info.
  * @returns {Info}
+ *   Info.
  */
 export function find(schema, value) {
   const normal = normalize(value)

lib/hast-to-react.js

@@ -1,8 +1,10 @@
 /**
- * `hast` is close to `React`, but differs in a couple of cases.
+ * Special cases for React (`Record<string, string>`).
  *
- * To get a React property from a hast property, check if it is in
- * `hastToReact`, if it is, then use the corresponding value,
+ * `hast` is close to `React` but differs in a couple of cases.
+ * To get a React property from a hast property,
+ * check if it is in `hastToReact`.
+ * If it is, use the corresponding value;
  * otherwise, use the hast property.
  *
  * @type {Record<string, string>}

lib/normalize.js

@@ -1,6 +1,11 @@
 /**
+ * Get the cleaned case insensitive form of an attribute or property.
+ *
  * @param {string} value
+ *   An attribute-like or property-like name.
  * @returns {string}
+ *   Value that can be used to look up the properly cased property on a
+ *   `Schema`.
  */
 export function normalize(value) {
   return value.toLowerCase()

lib/util/create.js

@@ -1,15 +1,14 @@
 /**
- * @typedef {import('./schema.js').Properties} Properties
- * @typedef {import('./schema.js').Normal} Normal
- *
- * @typedef {Record<string, string>} Attributes
- *
- * @typedef {Object} Definition
- * @property {Record<string, number|null>} properties
- * @property {(attributes: Attributes, property: string) => string} transform
- * @property {string} [space]
- * @property {Attributes} [attributes]
+ * @import {Info, Space} from '../../index.js'
+ */
+
+/**
+ * @typedef Definition
+ * @property {Record<string, string>} [attributes]
  * @property {Array<string>} [mustUseProperty]
+ * @property {Record<string, number | null>} properties
+ * @property {Space} [space]
+ * @property {(attributes: Record<string, string>, property: string) => string} transform
  */
 
 import {normalize} from '../normalize.js'
@@ -23,9 +22,9 @@ const own = {}.hasOwnProperty
  * @returns {Schema}
  */
 export function create(definition) {
-  /** @type {Properties} */
+  /** @type {Record<string, Info>} */
   const property = {}
-  /** @type {Normal} */
+  /** @type {Record<string, string>} */
   const normal = {}
   /** @type {string} */
   let prop

lib/util/info.js

@@ -1,25 +1,28 @@
+/**
+ * @import {Info as InfoType} from '../../index.js'
+ */
+
+/** @type {InfoType} */
 export class Info {
   /**
-   * @constructor
    * @param {string} property
    * @param {string} attribute
    */
   constructor(property, attribute) {
-    /** @type {string} */
-    this.property = property
-    /** @type {string} */
     this.attribute = attribute
+    this.property = property
   }
 }
 
-/** @type {string|null} */
-Info.prototype.space = null
-Info.prototype.boolean = false
+Info.prototype.attribute = ''
 Info.prototype.booleanish = false
-Info.prototype.overloadedBoolean = false
-Info.prototype.number = false
-Info.prototype.commaSeparated = false
-Info.prototype.spaceSeparated = false
+Info.prototype.boolean = false
 Info.prototype.commaOrSpaceSeparated = false
-Info.prototype.mustUseProperty = false
+Info.prototype.commaSeparated = false
 Info.prototype.defined = false
+Info.prototype.mustUseProperty = false
+Info.prototype.number = false
+Info.prototype.overloadedBoolean = false
+Info.prototype.property = ''
+Info.prototype.spaceSeparated = false
+Info.prototype.space = null

lib/util/merge.js

@@ -1,19 +1,18 @@
 /**
- * @typedef {import('./schema.js').Properties} Properties
- * @typedef {import('./schema.js').Normal} Normal
+ * @import {Info, Space} from '../../index.js'
  */
 
 import {Schema} from './schema.js'
 
 /**
  * @param {Schema[]} definitions
- * @param {string} [space]
+ * @param {Space} [space]
  * @returns {Schema}
  */
 export function merge(definitions, space) {
-  /** @type {Properties} */
+  /** @type {Record<string, Info>} */
   const property = {}
-  /** @type {Normal} */
+  /** @type {Record<string, string>} */
   const normal = {}
   let index = -1
 

lib/util/schema.js

@@ -1,28 +1,25 @@
 /**
- * @typedef {import('./info.js').Info} Info
- * @typedef {Record<string, Info>} Properties
- * @typedef {Record<string, string>} Normal
+ * @import {Schema as SchemaType, Space} from '../../index.js'
  */
 
+/** @type {SchemaType} */
 export class Schema {
   /**
    * @constructor
-   * @param {Properties} property
-   * @param {Normal} normal
-   * @param {string} [space]
+   * @param {SchemaType['property']} property
+   * @param {SchemaType['normal']} normal
+   * @param {Space | null | undefined} [space]
    */
   constructor(property, normal, space) {
-    this.property = property
     this.normal = normal
+    this.property = property
+
     if (space) {
       this.space = space
     }
   }
 }
 
-/** @type {Properties} */
-Schema.prototype.property = {}
-/** @type {Normal} */
 Schema.prototype.normal = {}
-/** @type {string|null} */
+Schema.prototype.property = {}
 Schema.prototype.space = null