typed-dom

typed-dom

Static typed DOM component builder.

Visualize DOM structures and Assist DOM access by static types of TypeScript.

API

TypedHTML: { [tagname]: (attrs?, children?, factory?) => TypedElement };

• attrs: Record<string, string>
• children: undefined | string | TypedElement[] | Record<string, TypedElement>
• factory: () => Element

import TypedHTML from 'typed-dom';

TypedHTML.p();
TypedHTML.p('text');
TypedHTML.p([TypedHTML.a()]);
TypedHTML.p({ link: TypedHTML.a() }]);
TypedHTML.p({ id: 'id' });
TypedHTML.p(() => document.createElement('p'));

Usage

Build a typed DOM object.

import TypedHTML from 'typed-dom';

const component = TypedHTML.article({ id: 'id' }, {
  style: TypedHTML.style(`$scope ul { width: 100px; }`),
  title: TypedHTML.h1(`title` as string),
  content: TypedHTML.ul([
    TypedHTML.li(`item` as string),
    TypedHTML.li(`item`),
  ])
});

Then this component has the following static type generated by type inference.

type ComponentTypeIs =
El<"article", Element, {
  style: El<"style", HTMLStyleElement, string>;
  title: El<"h1", HTMLHeadingElement, string>;
  content: El<"ul", HTMLUListElement, El<"li", HTMLLIElement, string>[]>;
}>;

// Note: El type is defined as follows.
export interface El<
  T extends string,
  E extends Element,
  C extends ElChildren
>
  extends AbstractTypedHTMLElement<T> {
  readonly element: E;
  children: C;
}
type ElChildren
  = ElChildren.Void
  | ElChildren.Text
  | ElChildren.Collection
  | ElChildren.Record;
namespace ElChildren {
  export type Void = undefined;
  export type Text = string;
  export type Collection = El<string, Element, any>[];
  export type Record = { [field: string]: El<string, Element, any>; };
}
abstract class AbstractTypedHTMLElement<T extends string> {
  private identifier: T;
}

You can know the internal structure via this type which can be used as the visualization. And you can access and manipulate the internal structure safely guided by this type.

// inspect
component.element.outerHTML; // '<article id="id"><style>#id ul { width: 100px; }</style><h1>title</h1><ul><li>item</li><li>item</li></ul></article>'
component.children.title.element.outerHTML; // '<h1>title</h1>'
component.children.title.children; // 'title'
component.children.content.element.outerHTML; // '<ul><li>item</li><li>item</li></ul>'
component.children.content.children[0].children; // 'item'

// update
// - text
component.children.title.children = 'Title';
component.children.title.element.outerHTML; // '<h1>Title</h1>'

// - struct
component.children.content.children = [
  TypedHTML.li('Item')
];
component.children.content.element.outerHTML; // '<ul><li>Item</li></ul>'

// - TypedHTML
component.children.title = TypedHTML.h1('Title!');
component.children.content = TypedHTML.ul([
  TypedHTML.li('Item!')
]);
component.element.outerHTML; // '<article id="id"><style>#id ul { width: 100px; }</style><h1>Title!</h1><ul><li>Item!</li></ul></article>'

Example

Micro DOM Components

Use micro DOM components to hide and manage the typed DOM object.

import TypedHTML from 'typed-dom';
import { sqid } from 'spica/sqid';

class MicroComponent {
  constructor(private readonly parent: HTMLElement) {
    this.parent.appendChild(this.dom.element);
  }
  private readonly dom = TypedHTML.div({ id: `${this.parent.id}-list-${sqid()}` }, {
    style: TypedHTML.style(`$scope ul { width: 100px; }`),
    content: TypedHTML.ul([
      TypedHTML.li(`item` as string)
    ])
  });
}

DOM Components

Use DOM components to manage the micro DOM components.

import TypedHTML from 'typed-dom';

class Component {
  constructor(private readonly parent: HTMLElement) {
    this.parent.appendChild(this.element);
  }
  private readonly element = TypedHTML.div({ id: 'id' }, [
    TypedHTML.style(`$scope { position: relative; }`)
  ]).element;
  private readonly children = Object.freeze({
    list: new MicroComponent(this.element)
  });
  destroy() {
    this.element.remove();
  }
}

Dependency

• unassert (in compiling source code)