# gizweb:visual

Presentation declarations reference typed result fields. They carry no SQL, aggregation formula, storage mapping or independent Live state.

```gizlang
import * as Visual from "gizweb:visual";
```

## Types

### `Mark`

```gizlang
type Mark = | { kind: "bar"; } | { kind: "line"; } | { kind: "scatter"; } | { kind: "pie"; }
```

How a chart draws its points.

- `bar`
- `line`
- `scatter`
- `pie`

### `Chart`

```gizlang
type Chart = { mark: Mark; x: string; y: string; series: string; }
```

A chart: its mark and the fields of its x, y and series.

- `mark`: `M97.Mark`
- `x`: `string`
- `y`: `string`
- `series`: `string`

### `Place`

```gizlang
type Place = { column: i64; row: i64; width: i64; height: i64; }
```

The area of a dashboard panel: zero-based column and row, and its span.

- `column`: `i64`
- `row`: `i64`
- `width`: `i64`
- `height`: `i64`

## Functions

### `figure`

```gizlang
function figure(spec: Chart, names: Vec<string>, rows: Vec<Vec<Option<string>>>): Result<bytes, DbError>
```

The chart as a page shows it: a <giz-chart> element that holds the SVG of `svg` and the rows as a table (exact text;
the x cell is the row header; a NULL cell has data-null). Without script the SVG is the chart. With the giz-chart
enhancement (web/components/src/chart.js), ECharts draws the same table in the element's shadow root. The table is
what assistive technology reads in both cases.

Effects: fail.

### `svg`

```gizlang
function svg(spec: Chart, names: Vec<string>, rows: Vec<Vec<Option<string>>>): Result<bytes, DbError>
```

The chart drawn on the server as SVG: no script, so it shows at first paint,
prints, and is the form of a chart without JavaScript. `names` and `rows` are
a text result (none for NULL); y, and x of a scatter, must be decimal text. A
row with a NULL y is not drawn. At most 4096 rows.

Effects: fail.

### `pivotTable`

```gizlang
function pivotTable(view: Semantic.Crosstab, title: string): bytes
```

The pivot as an HTML table: it reads without JavaScript and CSS. Values are
exact text (Value.show). A NULL key or measure has `data-null`; a pair without
a result row is an empty cell with `data-empty`.

Effects: fail.

### `readPivot`

```gizlang
function readPivot(value: Json.Json): Result<Semantic.Pivot, DbError>
```

A pivot spec in a saved workbook. Semantic.pivot checks it against its metric.

Effects: fail.

### `pivotJson`

```gizlang
function pivotJson(spec: Semantic.Pivot): string
```

The pivot `spec` as JSON.

Effects: fail.

### `layout`

```gizlang
function layout(places: Vec<Place>, cells: Vec<i64>): Result<bool, DbError>
```

A dashboard layout: 1 to PANELS panels in a grid of GRID_COLUMNS by
GRID_ROWS, without overlap. `cells[i]` is the cell limit of panel i (for a
pivot, its `cells`). Their sum is at most CELL_BUDGET.

Effects: fail.

### `area`

```gizlang
function area(place: Place): string
```

The CSS grid area of a panel, for its style attribute. The dashboard element
declares `display:grid;grid-template-columns:repeat(12,minmax(0,1fr))`.

Effects: fail.

### `readPlace`

```gizlang
function readPlace(value: Json.Json): Result<Place, DbError>
```

The Place in JSON `value`, or why it is not one.

Effects: fail.

### `placeJson`

```gizlang
function placeJson(place: Place): string
```

The Place `place` as JSON.

Effects: fail.

## Constants

### `GRID_COLUMNS`

```gizlang
const GRID_COLUMNS = 12
```

The columns of a dashboard grid.

### `GRID_ROWS`

```gizlang
const GRID_ROWS = 64
```

The rows of a dashboard grid.

### `PANELS`

```gizlang
const PANELS = 64
```

The most panels of a dashboard.

### `CELL_BUDGET`

```gizlang
const CELL_BUDGET = 16384
```

The cells that all panels of one dashboard can show together.