Elements

A view is a tree of these elements, returned from a view handler. Each also has a text form, which gr plugin render prints and a plugin's tests read.

col

Children stacked, one per line.

• Key: optional
• Children: any
• As text: children, one per line

row

Inline children laid out across, text truncated at the end.

• Key: optional
• Children: inline
• As text: children joined by two spaces

divider

A hairline across the view.

• Key: optional
• Children: none
• As text: ---

text

Words in the view's type, by role.

• Key: optional
• Children: strings
• As text: the text

markdown

One string of Markdown, at most 64 KB.

• Key: optional
• Children: one-string
• As text: the markdown

icon

One of the editor's icons, by name.

• Key: optional
• Children: none
• As text: (name)

tag

A short label, at most 24 characters, drawn as the editor's tag.

• Key: optional
• Children: one-string
• As text: [text]

key

Keys on a chip: given keys, or the person's keys for a command or action.

• Key: optional
• Children: none
• As text: the keys

button

The editor's one button control, of the kind named.

• Key: required
• Children: none
• Acts: press
• As text: [ label ]

input

One line of input.

• Key: required
• Children: none
• Acts: submit, change
• As text: [value or placeholder]

list

Items with a selection the editor keeps. Windowed (rows asked for) when count is set.

• Key: required
• Children: item
• Acts: activate, select
• As text: items, the selected prefixed > , others two spaces

item

A row of a list. With open, Enter opens it without a round trip.

• Key: required
• Children: inline
• As text: content, then detail and aside

tree

Nodes the person opens and closes. Enter on a node with children opens or closes it and sends no activate; on a leaf it activates it, or opens what its open says without a round trip.

• Key: required
• Children: node
• Acts: activate, open, close
• As text: a line a shown node: > for the selected one and a space for the others, two spaces a level, then + closed, - open or a space for a leaf, a space and the label; a closed node's children are not written

node

A node of a tree. With open, Enter on it opens that without a round trip.

• Key: required
• Children: node
• As text: the label, then detail

section

A titled group.

• Key: optional
• Children: any
• As text: ## title, then children

empty

What a view says when it has nothing.

• Key: optional
• Children: strings
• As text: the text

toggle

A switch, drawn as the editor's settings draw theirs: Space or a click flips it, and its plugin hears change with the new value (true or false). The editor keeps whether it is on; value is taken when it arrives and whenever it changes, so a view that renders the value it heard keeps the switch where the person put it. Inline in a row, or a line of its own.

• Key: required
• Children: none
• Acts: change
• As text: [x] label while on, [ ] label while off
• Since API 0.2.

select

A choice of one among at most 200 options, drawn as the editor's settings draw theirs: Enter, Space or a click opens its options in a menu under it, where j, k and Enter, or a click, choose. Its plugin hears change with the chosen option's value when the choice changes. The editor keeps the choice; value is taken when it arrives and whenever it changes. Options' values are unique.

• Key: required
• Children: none
• Acts: change
• As text: [label v], the chosen option's label, else the placeholder
• Since API 0.2.

progress

How far something has got: a bar filled to value, from 0 to 1, or with no value a bar that moves to say work goes on without a measure (still where the person asks for less motion).

• Key: optional
• Children: none
• As text: [####......] 40% label, ten marks a bar; [ .... ] label with no value
• Since API 0.2.

table

Rows in columns, with a selection the editor keeps, as a list's. Its children are items, each holding one inline element or string a column, in order (an item's open keeps its meaning; detail and aside are ignored). Windowed (rows asked for with the rows event) when count is set, and as fast at 100,000 rows as a windowed list. The plugin sorts: a click on a column's title, or s on the column h and l move to, sends sort with that column, and the plugin answers with a new tree whose sort says how it now stands. Keys as a list's, plus h and l.

• Key: required
• Children: item
• Acts: activate, select, sort
• As text: the titles, then the rows with each column padded to the widest of the rows shown and its title (end-aligned columns padded before), the selected row prefixed > and others two spaces; the sorted column's title ends ^ ascending or v descending; a windowed table then says (N rows, the first M shown)
• Since API 0.2.

tabs

Tabs over a part of a view, one shown at a time: a strip of the tabs' titles, drawn as the editor draws its own tabs, and under it the selected tab's children; the other tabs' are not laid out, and the keys pass them by. A click on a tab, or gt and gT (<C-PageDown> and <C-PageUp>) while the keys are in the view, selects another, round the ends, and its plugin hears select with the tab's key. The keys go to the tabs they are in, else to the first that shows. The editor keeps which tab is selected; selected is taken when it arrives and whenever it changes, and with none, or one no tab has, the first is selected. Tabs that end a view or a pane, the selected tab ending in a list or a tree, give that list the rest of the room to scroll in, as a view's own last list has.

• Key: required
• Children: tab
• Acts: select
• As text: [Title] Other Third, the selected tab's title in brackets, then the selected tab's children
• Since API 0.2.

tab

One tab of a tabs, and only of one: its title on the strip, and the blocks it holds, laid out while it is selected.

• Key: required
• Children: any
• As text: its children, while its tabs selects it
• Since API 0.2.

split

Two to four panes side by side (direction row) or one over another (col), each of its children one pane that scrolls on its own; a list, a table or a tree that ends a pane fills the rest of it. The person drags the line between two panes to share the room otherwise, and the editor keeps where they put it: sizes is taken when it arrives and whenever it changes. A split that ends a view or a pane fills the rest of it; one with more below it stands as tall as its panes need, and no taller than the view. Tab and S-Tab take the keys across every pane's lists, trees and controls, in order.

• Key: required
• Children: any
• As text: its children one after another, --- between two
• Since API 0.2.

code

A snippet of code, read-only, highlighted as the editor highlights a file of its language. The plugin gives the text: a tree never names a file for the editor to read. Its lines are numbered from start_line when there is one, and a mark points at a line in a tone. A click on it opens open, when it has one. A line wider than the pane is cut at its edge; the snippet stands as tall as its lines.

• Key: optional
• Children: none
• As text: the text; with start_line, each line after its number, the numbers right-aligned and two spaces from it
• Since API 0.2.

image

A PNG of the plugin's own folder: the version that runs, whose bytes its approval's hash covers, never a file of the workspace. The editor asks the daemon for it and draws it at its size in logical pixels, or at width and height, kept within the pane's width with its shape kept. One that cannot be drawn (missing, not a PNG, over 4 MiB or over 4096 by 4096 pixels) is its alt in a box, and the plugin's log says why once.

• Key: optional
• Children: none
• As text: [image: alt]
• Since API 0.2.

term

A terminal this plugin opened with $.terminal.open, shown in the view: the editor paints the terminal's own screen in the element's rows, as its terminal panes paint one. Tab or a click gives it the keys, and while it has them every key goes to the terminal as in a terminal pane; the terminal's own way out leaves it (Ctrl+\ then Ctrl+N to its normal mode, where Tab, Shift+Tab and q are the view's again). Needs the terminal capability, since the plugin could not have opened one otherwise; a terminal the plugin did not open is drawn as an empty box saying why. A terminal shown in a view is not also shown in a pane.

• Key: required
• Children: none
• As text: [terminal: title], the title it was opened with, else its id
• Since API 0.2.

part

One of the editor's own parts, shown in the view: the editor paints the part itself in the element's rows, as its panes paint it, and its keys and commands are the editor's. Tab or a click gives it the keys, and while it has them every key goes to the part as in its pane, but in its normal mode Tab, Shift+Tab and q, which are the view's: Tab moves the keys from one part to the next as between panes. The plugin chooses only which part and, by args, what it is on; it reads nothing of what the part shows and gets no event of it. A part a pane shows already stays in that pane, and the view draws a box saying so; a name this editor does not have is drawn as the box of an element it does not know.

• Key: required
• Children: none
• As text: [part: name]
• Since API 0.2.

grid

Its children in equal columns, a row of them at a time: as many columns as columns says, and fewer where the pane has no room for them, so a grid of three in a narrow pane stands as two, or as one. Each row of cells stands as tall as its tallest cell, and each cell as tall as what it holds: a list or a tree in a cell does not scroll by itself. A grid of cards is a dashboard: <grid columns={3}><card title="Build" detail="2 min ago"><text tone="success">passing</text></card><card title="Tests"><progress value={0.8} label="812 of 1015" /></card><card title="Coverage"><text bold>74%</text></card></grid>. An agent's ```graphide mockup has the same grid.

• Key: optional
• Children: any
• As text: its children one after another
• Since API 0.3.

card

A raised box round its children, stacked a small gap apart, under a line of its title, strong, and its detail, quiet, at the far end. A card in a card is a box in a box. In a grid each card is a cell, and the cards of a row stand as tall as one another: <card title="Sync" detail="live"><progress value={0.6} label="3 of 5 files" /><row><button key="pause" label="Pause" /></row></card>. An agent's ```graphide mockup has the same card.

• Key: optional
• Children: any
• As text: its title and detail on a line, then its children
• Since API 0.3.

Tones and icons

A tone prop takes one of default, bright, muted, faint, accent, success, warning, error. An icon takes one of close, check, plus, minus, more, up, down, overview, search, gear, send, architecture, graph, agents.