# orca.ui.layout

> A module of morca's API.

Every page's frame (`page_html`): its head, the nav, the slots the server fills in with who's logged in (`orca.web.server`), and the scripts every page has (`_POLL` for live fragments, `_TABS`, `_TIPS`, `_PEEK` for code on hover); and what every page draws with: cards, facts, help, action buttons, and the 404 and 400 pages.

## Functions

### `docs_link`

```mojo
def docs_link(anchor: StringSpan[ImmStaticOrigin]) -> String
```

A small link to the docs' section, beside a heading.

### `ask_attrs`

```mojo
def ask_attrs(mut h: Html, question: String, body: String = "", yes: String = "", no: String = "", danger: Bool = True)
```

The attributes that make a form, or a submit button, ask `question` first (`_ASK`): `body` says what will happen, `yes` and `no` are the buttons' words (the submit button's and "Go back" if empty), and `danger` makes yes red.

### `cmd_box`

```mojo
def cmd_box(mut h: Html, kind: String, cmd: String)
```

A shell command in a box with a Copy button; `kind` names it (`data-cmd`) for a script that rewrites it as a form changes.

### `page_html`

```mojo
def page_html(title: String, active: StringSpan[ImmStaticOrigin], body: Html) -> String
```

### `act_button`

```mojo
def act_button(mut h: Html, action: String, label: StringSpan[ImmStaticOrigin], verb: StringSpan[ImmStaticOrigin], cli: String, danger: Bool = False, step: String = "", ask: String = "", tell: String = "", yes: String = "", no: String = "", harm: Bool = True, partitions: String = "")
```

A small form posting to `action`, beside the status it changes: a button labelled `label` whose title is the command line that does the same, with "Log in to `verb`" in its place while login is needed. A `danger` one (red), or one with a question `ask`, asks first where there's JavaScript (`ask_attrs`): `ask`, or "`label`?", with `tell` saying what will happen and `yes`/`no` on the buttons; yes is red unless `harm` is false. `step` and `partitions`, if given, are posted as those fields.

### `help_tip`

```mojo
def help_tip(mut h: Html, id: String, key: String, text: StringSpan[ImmStaticOrigin], docs: StringSpan[ImmStaticOrigin] = StringSpan(""))
```

A "?" after a fact's name (`Html.help`).

### `with_header_help`

```mojo
def with_header_help(html: String, prefix: String) -> String
```

`html` with a "?" in every table header `orca.ui.terms` has help for, by its text (and the table its `data-help` names), as `help_tip` writes one; ids `help-<prefix>-<n>`. One pass over the page, so every table, whoever wrote it, gets them.

### `fact_term`

```mojo
def fact_term(mut h: Html, key: StringSpan[ImmStaticOrigin], id: StringSpan[ImmStaticOrigin], help: StringSpan[ImmStaticOrigin], docs: StringSpan[ImmStaticOrigin] = StringSpan(""))
```

A fact's `<dt>`: its name with its help.

### `fact_item`

```mojo
def fact_item(mut h: Html, key: StringSpan[ImmStaticOrigin], id: StringSpan[ImmStaticOrigin], help: StringSpan[ImmStaticOrigin], docs: StringSpan[ImmStaticOrigin] = StringSpan(""))
```

A fact's `<dt>`, its name with its help, then its `<dd>` opened.

### `card_open`

```mojo
def card_open(mut h: Html, id: StringSpan[ImmStaticOrigin], title: StringSpan[ImmStaticOrigin], help: StringSpan[ImmStaticOrigin], docs: StringSpan[ImmStaticOrigin] = StringSpan(""), facts: Bool = True)
```

A run page's card opened: its anchor `id`, then its heading with a "?" (`help`, its id `card-<id>`), closed. The caller ends the `<section>`.

### `not_found`

```mojo
def not_found(what: String) -> Page
```

### `bad_request`

```mojo
def bad_request(why: String) -> Page
```

A 400: the form asked for something the UI never does.

## Aliases

### `ASK_DIALOG`

```mojo
comptime ASK_DIALOG = "<dialog id=\22ask\22 class=\22ask\22 role=\22alertdialog\22 aria-labelledby=\22ask-title\22 aria-describedby=\22ask-body\22><form method=\22dialog\22 class=\22ask__form\22><h2 id=\22ask-title\22 class=\22ask__title\22></h2><p id=\22ask-body\22 class=\22ask__body\22></p><div class=\22ask__btns\22><button type=\22submit\22 value=\22no\22 class=\22ask__no\22 autofocus>Go back</button><button type=\22submit\22 value=\22yes\22 class=\22ask__yes\22>OK</button></div></form></dialog>"
```

The dialog `_ASK` fills in and shows, once per page.

### `USER_SLOT`

```mojo
comptime USER_SLOT = "<!--orca-user-->"
```

Where `serve` puts who's logged in, or a link to log in.

### `AUTH_SLOT`

```mojo
comptime AUTH_SLOT = "orca-auth"
```

The `<body>`'s class until the page is answered: `anon` when login is on and no one is logged in, which hides the inline action buttons and shows their "Log in to ..." links instead.

### `HERE_SLOT`

```mojo
comptime HERE_SLOT = "__orca_here__"
```

Where a "Log in to ..." link comes back to: the page's own path and query, encoded, filled in when the page is answered.

### `LIVE_EVERY`

```mojo
comptime LIVE_EVERY = 5
```

Seconds between refreshes of a list with a run going on.

### `IDLE_EVERY`

```mojo
comptime IDLE_EVERY = 30
```

Seconds between refreshes of a list's newest page with nothing going on: slow, only to show the runs a schedule or sensor starts.