npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

typed-xhtml

v4.1.3

Published

TypeSafe HTML templates using TypeScript. No need to learn a template library.

Downloads

9

Readme

Typed HTML

Forked from https://github.com/nicojs/typed-html.

HTML templates have never been this easy. Type safe using plain TypeScript with a minimal runtime footprint. No need to learn a template language, if you know TypeScript, you're set.

This:

// example.tsx
const item = 'item';
const icon = 'icon-add';
const ul = <ul>
    <li>{item}</li>
</ul>;

typeof ul; // string

const button = <button onclick="handleClick">
    <i class={icon}></i>
</button>;

typeof button; // string

console.log(ul);
console.log(button);

Prints:

<ul>
    <li>item</li>
</ul>
<button onclick="handleClick">
    <i class="icon-add"></i>
</button>

Getting started

Install:

npm install --save typed-xhtml

Configure your TypeScript compiler for JSX:

{
    "compilerOptions": {
        "jsx": "react",
        "jsxFactory": "elements.createElement",
        "jsxFragmentFactory": "elements.Fragment"
    }
}

Although we're configuring the compiler to use React, this is not what is being used. Instead, we redirect all jsx element to typed-html's elements.createElement.

Now create a *.tsx file. For example: example.tsx with the following content:

// example.tsx
import * as elements from 'typed-html';

const w = 'world';
const helloWorld = <p>Hello <strong>{w}</strong></p>;

typeof helloWorld; // => Just a string of course

However, the following piece of code will NOT compile:

<foo></foo>; // => Error: Property 'foo' does not exist on type 'JSX.IntrinsicElements'.
<a foo="bar"></a>; // => Error:  Property 'foo' does not exist on type 'HtmlAnchorTag'

Supported environments

Typed HTML supports both NodeJS and (since 2.0) the browser.

For use in the browser, use a bundler like webpack or rollup to bundle the package for you.

import * as elements from 'typed-html';

Supported scenarios

All template scenarios are supported with plain TypeScript.

Control flow

Conditional template with ?

<div>Random > 0.5: {Math.random() > .5 ? <strong>yes</strong> : 'no'}</div>

Repeat a template with Array.map

const items = ['item', 'item2'];
<ul>
    {items.map(i => <li>{i}</li>)}
</ul>;

Helper templates

Want a helper template? Just call a function

function listItem(n: number) {
    return <li>{n}</li>;
}
<ul>
    {[1, 2].map(listItem)}
</ul>

Using a helper template like an element

Want a helper component? Create a function that implements CustomElementHandler and you can call it like an HTML element.

import {Attributes, CustomElementHandler} from "typed-html"

function Button(attributes: Attributes | undefined, contents: string[]) {
    return <div><button type="button" class="original-class" {...attributes}>{contents}</button></div>;
}
// Or 
const Button: CustomElementHandler = (attributes, contents) => <div><button type="button" class="original-class" {...attributes}>{contents}</button></div>;
}
    
console.log(<Button style="color:#f00">Button Text</Button>);

Prints:

<div>
    <button type="button" class="original-class" style="color:#f00">Button Text</button>
</div>

Sanitization

Security is included by default.

const script = '<script>alert("hacked!")</script>';
const body = <body>{script}</body>;

Will result in:

<body>&lt;script&gt;alert(&quot;hacked!&quot;);&lt;/script&gt;</body>

If you want raw strings to be used without escaping, use elements.safeHtml:

const script = elements.safeHtml('<script>alert("intentionally hacked!")</script>');
const body = <body>{script}</body>;

Will result in:

<body><script>alert("intentionally hacked!")</script></body>

Supported HTML

All HTML elements and attributes are supported, except for the svg.

  • Supported html elements: https://dev.w3.org/html5/html-author/#the-elements
  • Supported html events: http://htmlcss.wikia.com/wiki/HTML5_Event_Attributes

Missing an element or attribute? Please create an issue or a PR to add it. It's easy to add.

Void elements

Void elements (elements without closing tags) are supported, however you should close them in TypeScript.

const img = <img href="/foo/bar.png">; // => Error! JSX element 'img' has no corresponding closing tag.

In the example above, closing the image tag is required for valid TSX code:

const img = <img href="/foo/bar.png" />; // => '<img href="/foo/bar.png" />'

Attribute types

All HTML attributes support a string value, however some attributes also support a number, Date or boolean(or absent value) type:

<meter value={1} min={0} max={5} low={1} high={4} optimum={3}></meter>; 
// => <meter value="1" min="0" max="5" low="1" high="4" optimum="3"></meter>
<ol start={3}></ol>;
<progress value={3} max={4}></progress>;
<td colspan={3} rowspan={3}></td>;
<th colspan={3} rowspan={3}></th>;

const date = new Date('1914-12-20T08:00');
<time datetime={date}></time>; 
// => <time datetime="1914-12-20T08:00:00.000Z"></time>
<ins datetime={date}>updated</ins>;
<del datetime={date}>old</del>;

// => <form> <input type="checkbox" checked> </form>
<form novalidate={false}> 
    <input type="checkbox" checked disabled={false}></input>
</form>

Custom elements

You can add custom elements by adding them to the intrinsic elements yourself:

// MyCustomElements.d.ts

declare namespace JSX {
    interface CustomElement {
        customAttribute?: string;
    }
    interface IntrinsicElements {
        myCustomElement: CustomElement;
    }
}

Now you can use it:

// UseCustomElement.ts
import * as elements from 'typed-html';

const myElement = <myCustomElement customAttribute="customValue"></myCustomElement>
console.log(myElement);

This prints:

<my-custom-element custom-attribute="customValue"></my-custom-element>

Custom attributes

Custom attribute names are already supported out-of-the-box for attributes with a dash (-) in the name. For example:

<button data-menu-item="3"></button>

Transformation

As a browser is case insensitive when it comes to element and attribute names, it is common practice to use kebab case for this. However <custom-element></custom-element> is not allowed in TypeScript. Therefore typed-html will transform <customElement></customElement> to <custom-element></custom-element>.

This transformation also works for custom attributes you define on a custom element yourself. For example:

<customElement aCustomAttr="value"></customElement>

Becomes

<custom-element a-custom-attr="value"></custom-element>

How this all works

The way this works is by using TypeScript's jsx support, but not for jsx/react interoperability. Instead, it defines the normal html tags as IntrinsicElements in the JSX namespace.

At runtime, the elements.createElement function is called for every html tag. It simply converts the given element to a string with minimal overhead.

This:

<ol start={2}>{[1, 2].map(i => <li>{i}</li>)}</ol>

Compiles to:

elements.createElement("ol", { start: 2 }, [1, 2].map(function (li) { 
    return elements.createElement("li", null, li); 
}));

Which translates to:

<ol start="2">
    <li>1</li>
    <li>2</li>
</ol>