# orca.html

> A module of morca's API.

Writing HTML: every value escaped, markup only where it's said to be.

```mojo
var h = Html()
h.raw("<td>")
h.text(step.error)        # `<script>` comes out as text
h.raw("</td>")
h.link("/runs/7", "run 7")
```

`orca ui` writes its pages through this rather than a template engine: a
page is tables of records, and writing it in Mojo keeps each value's type
until the moment it's escaped.

## Structs

### `Html`

```mojo
struct Html
```

A page being written.

Implements: `Movable`, `Writable`

Fields:

- `out: String`

#### `__init__`

```mojo
def __init__(out self)
```

#### `raw`

```mojo
def raw[*Ts: Writable](mut self, *parts: *Ts.values)
```

Markup, written as it is. Only ever literals of this module's callers, never a value from the database or a request.

#### `text`

```mojo
def text[*Ts: Writable](mut self, *values: *Ts.values)
```

Values, each written and then escaped.

#### `link`

```mojo
def link(mut self, href: StringSpan, label: StringSpan)
```

`<a href="href">label</a>`, both escaped.

#### `link_out`

```mojo
def link_out(mut self, href: StringSpan, label: StringSpan)
```

A link that opens in a new tab: to code, or another site.

#### `code`

```mojo
def code(mut self, href: StringSpan, label: StringSpan, commit: StringSpan)
```

A link to source code on its host, set apart from links inside orca: an icon, `label` (where, as `file.mojo:26`) in monospace, and ↗; it opens in a new tab, and its title names the commit.

#### `code_named`

```mojo
def code_named(mut self, href: StringSpan, name: StringSpan, at: StringSpan, commit: StringSpan)
```

`code`'s link labelled with the function's `name`; where it is (`at`, as `file.mojo:26`) goes in the title, after the commit.

#### `cell`

```mojo
def cell[*Ts: Writable](mut self, *values: *Ts.values)
```

One `<td>` holding the values, escaped.

#### `mono`

```mojo
def mono[*Ts: Writable](mut self, *values: *Ts.values)
```

A `<td>` in the monospace font: an id, a partition, a time.

#### `num`

```mojo
def num[*Ts: Writable](mut self, *values: *Ts.values)
```

A `<td>` of a count, right-aligned in tabular figures.

#### `chip`

```mojo
def chip(mut self, href: StringSpan, label: StringSpan)
```

A link to a run, as a small chip of its number.

#### `status`

```mojo
def status(mut self, s: StringSpan)
```

A status as a badge, its class named after it (a space in the status is a hyphen in the class), with what it means on hover or keyboard focus (`orca.ui.terms`).

#### `help`

```mojo
def help(mut self, id: String, key: String, text: StringSpan[ImmStaticOrigin], docs: StringSpan[ImmStaticOrigin] = StringSpan(""))
```

A "?" after a fact's or a column's name that shows `text`, then a link to the docs (`docs`: a section of the docs page, or a URL) if there is one. CSS shows it on hover and keyboard focus, so it needs no script; to a screen reader the text is the button's description. `id` is unique in the page.

#### `term`

```mojo
def term(mut self, kind: StringSpan, value: StringSpan)
```

`value`, one of a fixed set (`kind` in `orca.ui.terms`): dotted underlined, with what it means on hover, keyboard focus or a tap; plain text if the set doesn't know it.

#### `finish`

```mojo
def finish(deinit self) -> String
```

The page written.

#### `write_to`

```mojo
def write_to(self, mut writer: T)
```

## Functions

### `escape`

```mojo
def escape(s: StringSpan) -> String
```

`s` with `&`, `<`, `>`, `"` and `'` as character references, safe in text and in a quoted attribute.

### `url_encode`

```mojo
def url_encode(s: StringSpan) -> String
```

`s` as one path segment or query value: unreserved bytes as they are, every other byte as `%XX`.

### `url_decode`

```mojo
def url_decode(s: StringSpan) -> String
```

`%XX` and `+` in a query value decoded; a malformed escape is kept as it is.

### `query_param`

```mojo
def query_param(url: String, name: StringSpan) -> String
```

A query parameter's value, decoded, or empty.

### `query_values`

```mojo
def query_values(url: String, name: StringSpan) -> List[String]
```

Each value of a query parameter given once or more, decoded, in order.