# gizweb/client/page

What GizWeb's page client (kernel.giz) needs of the browser that shows the page: its document, its window, its storage and the network. One kernel runs on two hosts: GizBrowser implements Page over its own document (browser/client.giz), and any other browser over the DOM (main.giz, whose host is the JavaScript of web/node/sys/dom.js). A node is a number: the host keeps what it stands for, and -1 is none. A node of a parsed document is a number too, until it is adopted.

```gizlang
import * as Page from "gizweb/client/page";
```

## Types

### `Got`

```gizlang
type Got = { status: i64; stale: bool; type: string; timing: string; url: string; body: string; }
```

The answer to a request: its status (0 when it did not connect), whether it is a stale refusal (the STALE header),
its content type, its Server-Timing header, the address it ended at (after redirects) and its body.

- `status`: `i64`
- `stale`: `bool`
- `type`: `string`
- `timing`: `string`
- `url`: `string`
- `body`: `string`

### `Event`

```gizlang
type Event = { prevented: bool; button: i64; modifiers: i64; key: string; composing: bool; x: f64; y: f64; submitter: i64; state: string; related: i64; files: i64; }
```

What an event says beyond its type and target: whether a listener of the page took its default, the pointer button,
the keys held (SHIFT, CONTROL, ALT, META bits), the key pressed and whether an input method composes it, where the
pointer is, a form's submitter (-1 none), a toggle's new state, the node the pointer came from or goes to (-1 none),
and the files a drag or a paste carries (dragover: whether it carries any).

- `prevented`: `bool`
- `button`: `i64`
- `modifiers`: `i64`
- `key`: `string`
- `composing`: `bool`
- `x`: `f64`
- `y`: `f64`
- `submitter`: `i64`
- `state`: `string`
- `related`: `i64`
- `files`: `i64`

### `Page`

```gizlang
interface Page { root(self: Self): i64; kind(self: Self, n: i64): i64; tag(self: Self, n: i64): string; parent(self: Self, n: i64): i64; first(self: Self, n: i64): i64; next(self: Self, n: i64): i64; data(self: Self, n: i64): string; setData(self: Self, n: i64, text: string): void; text(self: Self, n: i64): string; setText(self: Self, n: i64, text: string): void; get(self: Self, n: i64, name: string): Option<string>; set(self: Self, n: i64, name: string, value: string): void; unset(self: Self, n: i64, name: string): void; names(self: Self, n: i64): Vec<string>; insert(self: Self, parent: i64, n: i64, before: i64): void; detach(self: Self, n: i64): void; adopt(self: Self, n: i64): i64; parse(self: Self, markup: string): i64; query(self: Self, root: i64, selector: string, all: bool): Vec<i64>; closest(self: Self, n: i64, selector: string): i64; matches(self: Self, n: i64, selector: string): bool; byId(self: Self, id: string): i64; create(self: Self, tag: string): i64; shadow(self: Self, n: i64, like: i64): i64; focused(self: Self): i64; focus(self: Self, n: i64): void; selectAll(self: Self, n: i64): void; value(self: Self, n: i64): string; setValue(self: Self, n: i64, value: string): void; checked(self: Self, n: i64): bool; setChecked(self: Self, n: i64, on: bool): void; changed(self: Self, n: i64): bool; formData(self: Self, form: i64, by: i64): Vec<string>; controls(self: Self, form: i64): Vec<i64>; reset(self: Self, form: i64): void; click(self: Self, n: i64): void; dispatch(self: Self, n: i64, type: string): void; requestSubmit(self: Self, form: i64, by: i64): void; submit(self: Self, form: i64): void; showPopover(self: Self, n: i64): void; hidePopover(self: Self, n: i64): void; popovers(self: Self): Vec<i64>; showModal(self: Self, n: i64): void; close(self: Self, n: i64): void; box(self: Self, n: i64): Vec<f64>; takeFiles(self: Self, n: i64): void; drag(self: Self, text: string): void; dropMove(self: Self): void; passkey(self: Self, form: i64): void; }
```

What the kernel needs of the browser that shows the page (see the top of this file).

- `root` — The root element (html).
- `kind`
- `tag` — An element's tag, lower case.
- `parent`
- `first`
- `next`
- `data` — A text or comment node's text.
- `setData`
- `text` — A node's text content, and its children replaced by one text.
- `setText`
- `get`
- `set`
- `unset`
- `names` — An element's attribute names, in order.
- `insert` — N, of the page or of a parsed document, into PARENT before BEFORE (-1: last); a node of the page moves and keeps
the focus it holds (moveBefore).
- `detach`
- `adopt` — N of a parsed document as a node of the page, to insert.
- `parse` — MARKUP parsed as an HTML document, its declarative shadow roots attached and its out-of-order regions filled
(template[data-fill], web/kernel/fill.js): its root element.
- `query` — The elements below ROOT (the page's or a parsed one's, the root among them) that SELECTOR matches, in tree
order; ALL or the first.
- `closest` — The nearest of N and its ancestors that SELECTOR matches (element.closest), or -1.
- `matches`
- `byId`
- `create` — A new element of the page, not yet inserted.
- `shadow` — N's open shadow root, or -1; with LIKE (a parsed shadow root, not -1), one attached first when N has none, like
LIKE (its delegatesFocus). A host that draws shadow trees in place (GizBrowser) has none: parse flattened them.
- `focused`
- `focus`
- `selectAll` — The whole value of a text field selected.
- `value`
- `setValue`
- `checked`
- `setChecked`
- `changed` — Whether a control's value follows its markup no longer, and the host would show a new value attribute (a browser
keeps a dirty value itself: false).
- `formData` — A form's data (name, value in turn), with the submitter BY (-1 none), as FormData has it; a file's value is FILE
and its name.
- `controls` — The controls of a form, those inside it and those that name it (form=ID), in tree order.
- `reset`
- `click` — element.click(): its events, and its default action.
- `dispatch` — An event of TYPE that bubbles from N, as dispatchEvent sends it: the page's listeners, then the kernel's.
- `requestSubmit`
- `submit` — form.submit(): the form sent natively, with no submit event.
- `showPopover`
- `hidePopover`
- `popovers` — The open popovers, the first opened first.
- `showModal`
- `close`
- `box` — N's box (getBoundingClientRect: x, y, width, height), empty when it is not laid out; -1's is the window's (0, 0,
innerWidth, innerHeight).
- `takeFiles` — The files the current drop or paste carries into the file input N (the first only, unless it takes several),
then its change event; and the values a drag of items carries (dragstart: a move, as text).
- `drag`
- `dropMove` — The dragover under way may drop, as a move.
- `passkey` — A passkey form's device answer (WebAuthn): its fields filled, then the form sent again; or the reason it failed
in its data-err slot.

### `Turns`

```gizlang
interface Turns { begin(self: Self, timing: string): void; on(self: Self, n: i64, type: string, ev: Event): bool; popped(self: Self): void; hide(self: Self): void; close(self: Self): void; leaving(self: Self): bool; online(self: Self): void; error(self: Self, message: string, at: string): void; send(self: Self, name: string, body: string, done: (answer: string) => void): void; patched(self: Self, patches: string): void; }
```

The turns a host gives the page client (Kernel): what the browser's listeners call.

- `begin`
- `on`
- `popped`
- `hide`
- `close`
- `leaving`
- `online`
- `error`
- `send`
- `patched`

### `Host`

```gizlang
interface Host { url(self: Self): string; resolve(self: Self, href: string, base: string): string; move(self: Self, url: string, replace: bool): void; open(self: Self, url: string): void; reload(self: Self): void; top(self: Self): void; copy(self: Self, n: i64, done: () => void): void; confirm(self: Self, question: string): bool; sheets(self: Self, hrefs: Vec<string>): void; transition(self: Self, run: () => void): void; online(self: Self): bool; hidden(self: Self): bool; stored(self: Self, key: string): Option<string>; store(self: Self, key: string, value: string): void; cookie(self: Self, name: string, value: string): void; now(self: Self): f64; later(self: Self, ms: i64, run: () => void): i64; cancel(self: Self, timer: i64): void; fetch(self: Self, method: string, url: string, headers: Vec<string>, body: string, done: (got: Got) => void): void; post(self: Self, url: string, headers: Vec<string>, form: i64, by: i64, picked: Vec<i64>, keepalive: bool, done: (got: Got) => void): void; upload(self: Self, url: string, form: i64, by: i64, progress: (sent: f64, total: f64) => void, done: (got: Got) => void): void; beacon(self: Self, url: string, body: string): void; act(self: Self, name: string, body: string, done: (answer: string) => void): void; socket(self: Self, url: string, event: (kind: i64, text: string) => void): i64; send(self: Self, socket: i64, text: string): void; closeSocket(self: Self, socket: i64): void; }
```

The window, storage, time and the network of the page (a host implements Page and Host on one value, or two).

- `url` — The address shown.
- `resolve` — HREF as an absolute address against BASE ("": the page's base), or "" when it is none.
- `move` — A step of the history to URL (pushState), or a replaced one (replaceState).
- `open` — The page at URL loaded in full, or the page again.
- `reload`
- `top` — The window and each scroller in the page at their top.
- `copy` — N's rendered text (innerText) to the clipboard; DONE runs once it is there.
- `confirm`
- `sheets` — The head's style sheets become HREFS: new ones load first, and the old ones go once they did.
- `transition` — RUN in a view transition when the host has them and the person allows motion, else at once.
- `online` — Whether the device is online, and the page hidden (visibilityState).
- `hidden`
- `stored` — A value kept for the next visit (localStorage), and a cookie for a year on every path.
- `store`
- `cookie`
- `now` — Milliseconds since the page began (performance.now).
- `later` — RUN after MS: its number, which cancel drops.
- `cancel`
- `fetch` — A request of METHOD to URL with HEADERS (name, value in turn; `cache-control: no-store` also skips the host's
cache) and BODY; DONE gets its answer in a later turn.
- `post` — A POST of FORM's data to URL: the entries of formData(FORM, BY) at PICKED (all when PICKED is empty), as a
multipart body when one of them is a file, else urlencoded; KEEPALIVE outlives the page. DONE gets the answer.
- `upload` — A multipart POST of FORM's data (with BY) to URL; PROGRESS hears how much went (sent, total); DONE the answer.
- `beacon` — The page's events sent as the page goes too (sendBeacon).
- `act` — The app's client module (html data-wasm) answers action NAME with BODY: its patches as JSON, or "" when the
server must. DONE gets it.
- `socket` — A WebSocket to URL, whose events (OPENED, MESSAGE, CLOSED) EVENT gets: its number.
- `send`
- `closeSocket`

## Constants

### `ELEMENT`

```gizlang
const ELEMENT = 1
```

A node's kind, as the DOM numbers them.

### `TEXT`

```gizlang
const TEXT = 3
```

A text node.

### `COMMENT`

```gizlang
const COMMENT = 8
```

A comment.

### `FRAGMENT`

```gizlang
const FRAGMENT = 11
```

A shadow root (a document fragment).

### `SHIFT`

```gizlang
const SHIFT = 1
```

Event.modifiers: the Shift key.

### `CONTROL`

```gizlang
const CONTROL = 2
```

Event.modifiers: the Control key.

### `ALT`

```gizlang
const ALT = 4
```

Event.modifiers: the Alt (Option) key.

### `META`

```gizlang
const META = 8
```

Event.modifiers: the Meta (Command) key.

### `OPENED`

```gizlang
const OPENED = 0
```

The live channel's events (Page.socket).

### `MESSAGE`

```gizlang
const MESSAGE = 1
```

The live channel got a message.

### `CLOSED`

```gizlang
const CLOSED = 3
```

The live channel closed.

### `FILE`

```gizlang
const FILE = "\u0000"
```

Page.formData marks a file's value with this first character; the rest is the file's name.

