modapp-base-component

ModApp Base Component

Collection of base components following the component interface of modapp.

Installation

With npm:

npm install modapp-base-component

With yarn:

yarn add modapp-base-component

Usage

Import any selected component and use it.

import { Txt } from 'modapp-base-component';

let txt = new Txt("Hello World!");
txt.render(document.body);

JSX with Elem

JSX can be used as authoring syntax for Elem trees. JSX does not render anything by itself. Lowercase tags compile into structured JSX values that the opt-in JSX Elem adapter knows how to consume. JSX support is opt-in through the modapp-base-component/jsx entrypoint, so the base package stays free from JSX adapter code unless you choose to use it.

Install babel/preset-react:

npm install --save-dev @babel/preset-react

Configure Babel with the automatic JSX runtime:

{
  "presets": [
    ["@babel/preset-react", {
      "runtime": "automatic",
      "importSource": "modapp-base-component/jsx"
    }]
  ]
}

If ESLint is used, install eslint-plugin-react:

npm install --save-dev eslint-plugin-react

And make sure to allow jsx in the eslint config:

"plugins": {
  /*...*/
  "react"
},
"parserOptions": {
  /*...*/
  "ecmaFeatures": {
    "jsx": true
  }
},
"rules": {
  /*...*/
  "react/jsx-uses-vars": "error",
}

Lowercase tags create structured JSX values used with new Elem(...):

import { Elem, Txt } from 'modapp-base-component/jsx';

let elem = new Elem(
  <ul className="example">
    <li>First item</li>
    <li>{new Txt("Second item")}</li>
  </ul>
);

elem.render(document.body);

The same root can also be written using Elem.fromJSX implicitly through JSX:

import { Elem } from 'modapp-base-component/jsx';

let elem = <Elem as="span">Hello</Elem>;
elem.render(document.body);

Capitalized tags can return components directly when the component exposes a static fromJSX(props) adapter:

import { Txt } from 'modapp-base-component/jsx';

let txt = <Txt text="Hello World!" />;
txt.render(document.body);

The modapp-base-component/jsx entrypoint exports JSX-enabled wrappers for the public components, including Button, Checkbox, Context, Elem, Fragment, Html, Input, Pair, Radio, Select, Textarea, Transition, and Txt.

Custom JSX component tags must expose a static fromJSX(props) method that returns a renderable component instance.

For RootElem-based components, reuse the same prop mapping through mapJsxProps:

import { mapJsxProps, Txt } from 'modapp-base-component/jsx';

class MyTxt extends Txt {
  static fromJSX(props) {
    return new MyTxt(props?.text || "", mapJsxProps(props, {
      omit: { text: true },
      ignore: { tagName: true, duration: true }
    }));
  }
}

Supported JSX in v1:

• Lowercase DOM tags such as <div> and <ul>
• Inline component instances in expressions, such as {new Txt("Hello")}
• Capitalized component tags that expose fromJSX(props), such as <Txt text="Hello" />
• <Elem as="tag">...</Elem> as shorthand for creating a root Elem node, defaulting to div
• nodeId for Elem node lookup ids, while normal id stays a DOM attribute

Unsupported JSX in v1:

• Fragments such as <>...</>
• Child content for Txt, such as <Txt>Hello</Txt>
• Refs, keys, hooks, or reconciliation

mapJsxProps always treats nodeId as reserved and omits it from component option mapping. Use omit to drop adapter-specific props entirely and ignore to pass adapter-specific options through unchanged.

All components follows modapp's component interface:

Component Interface

A UI component

Kind: global interface

• Component
  • .render(el) ⇒ HTMLElement | DocumentFragment | null
  • .unrender()

component.render(el) ⇒ HTMLElement | DocumentFragment | null

Renders the component by appending its own element(s) to the provided parent element.
The provided element is not required to be empty, and may therefor contain other child elements.
The component is not required to append any element in case it has nothing to render.
Render is never called two times in succession without a call to unrender in between.

Kind: instance method of Component
Returns: HTMLElement | DocumentFragment | null - Element or document fragment appended to el. May be null or undefined if no elements was appended.

Param	Type	Description
el	HTMLElement | DocumentFragment	Parent element in which to render the contents

component.unrender()

Unrenders the component and removes its element(s) from the parent element.
Only called after render and never called two times in succession without a call to render in between.

Kind: instance method of Component