gizlang:html

HTML as a typed value. Markup in source compiles to it:

function Row(t: Todo): Html { return <li class="todo" data-k={t.id}><input type="checkbox" checked={t.done}/>{t.title}</li>; }

The compiler joins each element's fixed parts into one constant at compile time and writes the holes in between: text is escaped, numbers are written, Html goes in as it is, a flag attribute is there or not. So a page is one buffer filled in order, and text never becomes markup unless the program says raw. A tag that starts upper case is a component, a function called with its attributes as a record and its children as Html.

import * as Html from "gizlang:html";

Types

Html

type Html = { markup: bytes; }

Rendered HTML: markup whose text is escaped. Markup in source, raw and the functions here make one.

• markup: bytes

Content

interface Content { writeHtml(self: Self, out: mut bytes): void effects { fail }; }

What an element's children may hold: text (escaped), numbers and Html.

• writeHtml

AttributeValue

interface AttributeValue { writeAttribute(self: Self, out: mut bytes, name: string): void effects { fail }; }

What an attribute's value may be: text and numbers ( name="value", escaped), or a flag (the bare name when true, nothing when false).

• writeAttribute

ShadowProps

type ShadowProps = { delegatesFocus: bool; }

Declarative shadow DOM, rendered by the browser's HTML parser before any script runs. Put this component directly inside its host element. Keep meaningful content in light DOM and project it through a slot, so a browser without declarative shadow DOM still has the document's content.

<giz-card><Shadow delegatesFocus={false}><slot/></Shadow><p>Hello</p></giz-card>

The root is open: enhancement code can reuse host.shadowRoot instead of discarding the server's tree. Clonable roots follow the host when the owning DOM transport clones it. This does not load a module or create a registry.

• delegatesFocus: bool

Functions

escape

function escape(out: mut bytes, value: string): void

Text as HTML content or attribute value: & < > " ' escaped.

Effects: fail.

attribute

function attribute(out: mut bytes, name: string, value: string): void

name="value", the value escaped: an attribute that code writing bytes puts after a tag's name. Markup writes its attributes itself.

Effects: fail.

escaped

function escaped(value: string): string

Escaped HTML text or attribute content as a string, using the same writer as markup. For whole typed elements prefer markup instead of concatenation.

Effects: fail.

escapeBytes

function escapeBytes(out: mut bytes, data: bytes, from: i64, to: i64): void

DATA[FROM, TO) escaped into OUT, plain runs copied whole (web/markdown escapes its source in place with it).

Effects: fail.

raw

function raw(markup: string): Html

Markup the program vouches for, as it is (a stylesheet, a script, HTML it made).

empty

function empty(): Html

No markup.

slotStart

function slotStart(name: string): Html

The opening mark of the content for the slot NAME of a component.

Effects: fail.

slotEnd

function slotEnd(name: string): Html

The closing mark of the content for the slot NAME.

Effects: fail.

slot

function slot(children: Html, name: string): Html

The content that the caller marked for the slot NAME, or nothing.

Effects: fail.

unslotted

function unslotted(children: Html): Html

The children without the content that was marked for a named slot.

Effects: fail.

each

function each<T, F>(items: Vec<T>, render: F): Html

render(item) for each item, in order: {each(todos, (t: Todo) => <li>{t.title}</li>)}.

when

function when<F>(condition: bool, render: F): Html

render() when the condition holds, else nothing.

plainText

function plainText(html: bytes): string

The text of HTML markup: tags and comments dropped, the bodies of script and style dropped, <br> read as a space, and character references read back (the five that escape writes, &nbsp; and other names pages use most, and decimal or hex numbers).

Effects: fail.

unescape

function unescape(text: string): string

TEXT with its character references read back, as plainText reads them.

Effects: fail.

Shadow

function Shadow(p: ShadowProps, children: Html): Html

A declarative shadow root (an open template element) with CHILDREN.

Effects: fail.

markupBuffer

function markupBuffer(): bytes

Markup lowering: the hidden buffer of an element.

markupOpen

function markupOpen(out: mut bytes, first: string): i64

Markup lowering: opens the buffer with the first fixed part.

markupText

function markupText(after: i64, out: mut bytes, part: string): i64

Markup lowering: appends a fixed part.

Effects: fail.

markupChild

function markupChild<T extends Content>(after: i64, out: mut bytes, value: T): i64

Markup lowering: appends a hole, through its writeHtml.

markupAttribute

function markupAttribute<T extends AttributeValue>(after: i64, out: mut bytes, name: string, value: T): i64

name is the attribute's name with the space before it (" checked").

markupClose

function markupClose(after: i64, out: mut bytes): Html

Markup lowering: closes the buffer as Html and empties it.

markupAppend

function markupAppend(out: mut bytes, first: string): i64

Markup lowering: appends the first fixed part to a buffer that has bytes (out += <p/>).

Effects: fail.

markupTake

function markupTake(after: i64, out: mut bytes): bytes

Markup lowering: takes the bytes of the buffer and empties it.

Methods

Html.text

function Html.text(self: Html): string

The markup as text, for a response body.

Effects: fail.

string.writeHtml

function string.writeHtml(self: string, out: mut bytes): void

Writes the string as HTML text, with escapes.

Effects: fail.

i64.writeHtml

function i64.writeHtml(self: i64, out: mut bytes): void

Writes the integer as HTML text.

Effects: fail.

f64.writeHtml

function f64.writeHtml(self: f64, out: mut bytes): void

Writes the number as HTML text.

Effects: fail.

Html.writeHtml

function Html.writeHtml(self: Html, out: mut bytes): void

Writes the markup as it is.

Effects: fail.

string.writeAttribute

function string.writeAttribute(self: string, out: mut bytes, name: string): void

Writes NAME="value" with the string escaped.

Effects: fail.

i64.writeAttribute

function i64.writeAttribute(self: i64, out: mut bytes, name: string): void

Writes NAME="value" with the integer.

Effects: fail.

f64.writeAttribute

function f64.writeAttribute(self: f64, out: mut bytes, name: string): void

Writes NAME="value" with the number.

Effects: fail.

bool.writeAttribute

function bool.writeAttribute(self: bool, out: mut bytes, name: string): void

Writes NAME when the value is true, and nothing when it is false.

Effects: fail.