tenebrous-dicebot/api/node_modules/jsx-dom/README.md

jsx-dom

Use JSX for creating DOM elements. Supports ES Module and TypeScript.

Installation

npm install --save jsx-dom
yarn install jsx-dom

Usage

Note: jsx-dom is ESM only. If you absolutely need CommonJS support, use jsx-dom-cjs instead.

Note: If you are using React Automatic Runtime, simply set jsxImportSource to jsx-dom or jsx-dom/min and you can omit the import.

import React from "jsx-dom"

// DOM Elements.
document.body.appendChild(
  <div id="greeting" class="alert">
    Hello World
  </div>
)

// Functional components
// `defaultProps` and `props.children` are supported natively and work as you expect.
function Hello(props) {
  return (
    <div>
      Hello, {props.firstName} {props.lastName}!
    </div>
  )
}
Hello.defaultProps = {
  firstName: "John",
}

document.body.appendChild(<Hello firstName="Johnny" lastName="Appleseed" />)

// Class components
// `defaultProps` and `props.children` are supported natively and work as you expect.
// In terms of React jsx-dom class components have no state,
// so `render` function will be called only once.
class Welcome extends React.Component {
  static defaultProps = {
    firstName: "John",
  }

  render() {
    return (
      <div>
        Welcome, {this.props.firstName} {this.props.lastName}!
      </div>
    )
  }
}

document.body.appendChild(<Welcome firstName="Johnny" lastName="Appleseed" />)

Syntax

jsx-dom is based on the React JSX syntax with a few additions:

Class

1. class is supported as an attribute as well as className.

2. class can take:

   • a string
   • an object with the format { [key: string]: boolean }. Keys with a truthy value will be added to the classList
   • an array of values where falsy values (see below) are filtered out
   • an array of any combination of the above, including deeply nested arrays

Note that false, true, null, undefined will be ignored per React documentations, and everything else will be used. For example,

<div class="greeting" />
<div class={[ condition && "class" ]} />
<div class={{ hidden: isHidden, "has-item": !!array.length }} />
<div class={[ classArray1, classArray2, ["nested", ["further"]] ]} />

Style

1. style accepts both strings and objects. Unitless properties supported by React are also supported.

<div style="background: transparent;" />
<div style={{ background: "transparent", fontFamily: "serif", fontSize: 16 }} />

Children

Passing children as an explicit attribute, when there is no other JSX child node, is also supported.

<div children={["Total: ", 20]} />

Other Attributes

1. dataset accepts an object, where keys with a null or undefined value will be ignored.

<div dataset={{ user: "guest", isLoggedIn: false }} />

2. Attributes starts with on and has a function value will be treated as an event listener and attached to the node by setting the property directly (e.g. node.onclick = ...).

<div onClick={e => e.preventDefault()} />

3. innerHTML, innerText and textContent are accepted.

4. ref accepts either 1) a callback (node: Element) => void that allows access to the node after being created, or 2) a React style ref object. This is useful when you have a nested node tree and need to access a node inside without creating an intermediary variable.

// Callback
<input ref={node => $(node).typehead({ hint: true })} />

// React.createRef
import React, { createRef } from "jsx-dom"

const textbox = createRef()
render(
  <div>
    <label>Username:</label>
    <input ref={textbox} />
  </div>
)

window.onerror = () => {
  textbox.current.focus()
}

// React.useRef
import React, { useRef } from "jsx-dom"

function Component() {
  const textbox = useRef()
  const onClick = () => textbox.current.focus()

  return (
    <div onClick={onClick}>
      <label>Username:</label>
      <input ref={textbox} />
    </div>
  )
}

Functional and class components

You can write functional and class components and receive passed props in the same way in React. Unlike React, props.children is guaranteed to be an array.

SVG and Namespaces

import React from "jsx-dom"

document.body.appendChild(
  <div class="flag" style={{ display: "flex" }}>
    <h1>Flag of Italy</h1>
    <svg width="150" height="100" viewBox="0 0 3 2" class="flag italy">
      <rect width="1" height="2" x="0" fill="#008d46" />
      <rect width="1" height="2" x="1" fill="#ffffff" />
      <rect width="1" height="2" x="2" fill="#d2232c" />
    </svg>
  </div>
)

Below is a list of SVG tags included.

svg, animate, circle, clipPath, defs, desc, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence, filter, foreignObject, g, image, line, linearGradient, marker, mask, metadata, path, pattern, polygon, polyline, radialGradient, rect, stop, switch, symbol, text, textPath, tspan, use, view

If you do not need SVG and CSS property automatic type conversion support, you can import from jsx-dom/min for a smaller build.

import React, { SVGNamespace } from "jsx-dom"

function Anchor() {
  return <a namespaceURI={SVGNamespace}>I am an SVG element!</a>
}

If you need to create an SVG element that is not in the list, or you want to specify a custom namespace, use the attribute namespaceURI.

jsx-dom also includes a few utility functions to facilitate the process of refactoring from or to React.

useText

While this is technically not a hook in the React sense, it functions like one and facilitates simple DOM text changes.

import React, { useText } from "jsx-dom"

function Component() {
  const [text, setText] = useText("Downloading")

  fetch("./api").then(() => setText("Done!"))

  return (
    <div>Status: {text}</div>
  )
}

useClassList

import React, { useClassList } from "jsx-dom"

function Component() {
  const cls = useClassList(["main", { ready: false }])
  setTimeout(() => {
    cls.add("long-wait")
    cls.toggle("ready")
  }, 2000)

  return (
    <div class={cls}>Status</div>
  )
}

Goodies

Some extra features are provided by this package:

function preventDefault(event: Event): Event

function stopPropagation(event: Event): Event

/** `namespaceURI` string for SVG Elements. */
const SVGNamespace: string

function className(value: any): string

Type aliases for convenience

/** Short type aliases for HTML elements */
namespace HTML {
    type Anchor = HTMLAnchorElement
    type Button = HTMLButtonElement
    type Div = HTMLDivElement
    ...
}

/** Short type aliases for SVG elements */
namespace SVG {
    type Anchor = SVGAElement
    type Animate = SVGAnimateElement
    ...
}

API

The following functions are included for compatibility with React API:

function createFactory(component: string): (props: object) => JSX.Element
function useRef<T>(initialValue?: T): RefObject<T>

The following functions will not have memoization, and are only useful if you are migrating from/to React.

function memo<P, T extends (props: P) => JSX.Element>(render: T): T
function useMemo<T>(fn: () => T, deps: any[]): T
function useCallback<T extends Function>(fn: T, deps: any[]): T

Browser Support

There is no support for Internet Explorer, although it will very likely work if you bring your own polyfill.

Known Issues

• <div />, and other tags, are inferred as a general JSX.Element in TypeScript instead of HTMLDivElement (or the equivalent types). This is a known bug and its fix depends on TypeScript#21699.

• html library is not currently compatible with jsx-dom.