Reference · Panelith 0.1.0 · plain HTML edition; the interactive edition has search and live examples

Actions

Every constructor in panelith.actions, with the JSON the shell receives and what it does with it. A handler returns one, a list, or None.

`open_pane`#

open_pane(kind: str, *, name: str | None = None, state: dict[str, Any] | None = None, parent: str | None = None, placement: str = 'focused', focus: bool = True, cid: str | None = None, size: float | None = None) -> s.OpenPane

Open a pane of kind.

Argument	Meaning
`kind`	the kind id to open.
`name`	the tab's name; defaults to the kind's label.
`state`	the pane's first state; skips `initial_state` on the server.
`parent`	cid of the pane this one is tethered to (a child).
`placement`	`focused` (a tab in the focused pane), `below` / `beside` (a new pane split off the parent or the focused pane), `new` (a free pane nearby) or `tab` (a tab in the parent's own pane).
`focus`	make the new tab the active, focused one.
`cid`	surface this existing pane instead of opening a second one.
`size`	the share (0–1) of the split a new below/beside pane takes.

The shell receives a OpenPane:

Field	Type	Default	Description
`kind`	`str`	required	the kind to open
`name`	`str \| None`	`None`	the tab name; the kind's label when omitted
`state`	`dict[str, Any] \| None`	`None`	the pane's first state; skips `initial_state`
`parent`	`str \| None`	`None`	cid of the tab this one is tethered to
`placement`	`str`	`'focused'`	where a child goes relative to its parent; 'tab' = the parent's own pane — Options: `focused` · `below` · `beside` · `new` · `tab`
`focus`	`bool`	`True`	focus the new tab
`cid`	`str \| None`	`None`	reuse: surface this cid instead of opening a new tab if it exists
`size`	`float \| None`	`None`	fraction of the parent's row/column a new below/beside pane takes

`set_state`#

set_state(cid: str, state: dict[str, Any]) -> s.SetPaneState

Replace pane cid's whole state dict (the widget re-renders; view() runs).

The shell receives a SetPaneState:

Field	Type	Default	Description
`cid`	`str`	required	the pane
`state`	`dict[str, Any]`	required	the whole new state

`patch_state`#

patch_state(cid: str, **patch: Any) -> s.PatchPaneState

Merge patch into pane cid's state: send what changed, not the whole dict.

The shell receives a PatchPaneState:

Field	Type	Default	Description
`cid`	`str`	required	the pane
`patch`	`dict[str, Any]`	required	fields merged into the state

`set_subtabs`#

set_subtabs(cid: str, subtabs: list[tuple[str, str]] | list[dict[str, str]], active: str | None = None) -> s.SetSubtabs

Set a sub-tabbed pane's strip.

Argument	Meaning
`cid`	the pane.
`subtabs`	`(id, name)` pairs or `{"id", "name"}` dicts, in order.
`active`	the id to select; the first one when omitted.

The shell receives a SetSubtabs:

Field	Type	Default	Description
`cid`	`str`	required	the pane
`subtabs`	`list[Subtab]`	required	the strip, in order
`active`	`str \| None`	`None`	the selected id

`close_pane`#

close_pane(cid: str) -> s.ClosePane

Close the tab cid (its pane goes too when it was the last tab).

The shell receives a ClosePane:

Field	Type	Default	Description
`cid`	`str`	required	the tab to close

`focus_pane`#

focus_pane(cid: str) -> s.FocusPane

Focus the pane holding cid and make that tab active.

The shell receives a FocusPane:

Field	Type	Default	Description
`cid`	`str`	required	the tab to focus

`rename_tab`#

rename_tab(cid: str, name: str) -> s.RenameTab

Rename the tab cid.

The shell receives a RenameTab:

Field	Type	Default	Description
`cid`	`str`	required	the tab
`name`	`str`	required	its new name

`set_title`#

set_title(text: str | None) -> s.SetTitle

Put text in the centre of the top bar (None restores the placeholder).

The shell receives a SetTitle:

Field	Type	Default	Description
`text`	`str \| None`	required	the top bar's centre text; None restores the placeholder

`notify`#

notify(text: str, tone: str = 'info', ms: int = 2600) -> s.Notify

A toast. Tones are info, ok, warn and error; the block tones bad, accent and dim map onto them, so a handler can pass a block's tone straight through. Anything else shows as info.

The shell receives a Notify:

Field	Type	Default	Description
`text`	`str`	required	the toast text
`tone`	`str`	`'info'`	its colour — Options: `info` · `ok` · `warn` · `error`
`ms`	`int`	`2600`	how long it stays

Used in: Panes, state and events › Actions · Glossary

`refresh_list`#

refresh_list(list_id: str) -> s.RefreshList

Make the shell fetch list list_id's rows again (drawer and command bar).

The shell receives a RefreshList:

Field	Type	Default	Description
`list_id`	`str`	required	the list to fetch again

`open_command_bar`#

open_command_bar(sigil: str = '>', query: str = '') -> s.OpenCommandBar

Open the command bar with sigil and query already typed.

The shell receives a OpenCommandBar:

Field	Type	Default	Description
`sigil`	`str`	`'>'`	the sigil to open with
`query`	`str`	`''`	text typed after the sigil

`run_builtin`#

run_builtin(command_id: str) -> s.RunBuiltin

Run one of the shell's own commands (pane.maximize, app.help, ...), or list:<id> to toggle that list's drawer.

The shell receives a RunBuiltin:

Field	Type	Default	Description
`id`	`str`	required	a built-in command id, or `list:<id>`

`send_event`#

send_event(cid: str, name: str, **payload: Any) -> s.SendEvent

Deliver event name with payload to pane cid, as if its widget had sent it; this is how a command reaches a pane's own handler.

The shell receives a SendEvent:

Field	Type	Default	Description
`cid`	`str`	required	the pane
`name`	`str`	required	the event name
`payload`	`dict[str, Any]`	`{}`	the event payload

`spotlight`#

spotlight(target: str | None, text: str | None = None, *, ms: int | None = None, tone: str | None = None, dismiss: str = 'click', patch: dict[str, Any] | None = None) -> s.Spotlight

Ring one shell element and caption it. target is a data-pl hook (topbar.brand, cmdbar, drawer, launcher, help, pane:<cid>, tab:<cid>, header:<cid>, body:<cid>, divider:<col>, cmdbar.row:<id>, launcher.tile:<id>, toast, ...); None clears the spotlight. The shell retries a target for 1.5 s, so it may name a pane the same reply opens.

The shell receives a Spotlight:

Field	Type	Default	Description
`steps`	`list[SpotStep]`	`[]`	the stops, in order; empty clears the spotlight
`dismiss`	`str`	`'click'`	`click`: any click outside the caption dismisses; `auto`: only the caption buttons, Escape or `ms` do

Used in: Panes, state and events › Actions · Theme › Tokens · Testing an app › The browser: Playwright against the real shell · Glossary

`preview`#

preview(patch: dict[str, Any], target: str, text: str | None = None, *, ms: int | None = 20000) -> s.Spotlight

Show what a manifest change would look like, in place: the shell applies patch (a partial manifest: brand, theme, command_sigil, topbar, pane_header) for as long as the spotlight shows, rings target in the warn colour, and puts everything back when the visitor presses Done, Escape, clicks outside, or after ms. Nothing is persisted; a reload shows the real manifest.

Argument	Meaning
`patch`	the manifest fields to overlay (merged over the current ones).
`target`	the `data-pl` hook of the part that changes. — Options: a `data-pl` hook; the list is under spotlight
`text`	the caption.
`ms`	auto-dismiss after this long; None waits for the visitor.

The shell receives a Spotlight:

Field	Type	Default	Description
`steps`	`list[SpotStep]`	`[]`	the stops, in order; empty clears the spotlight
`dismiss`	`str`	`'click'`	`click`: any click outside the caption dismisses; `auto`: only the caption buttons, Escape or `ms` do

Used in: Blocks: a pane body composed in Python › The block types · Blocks: a pane body composed in Python › The trace gesture · Blocks: a pane body composed in Python › Worked example: Super Boggle

`tour`#

tour(*steps: tuple[str, str] | dict[str, Any] | s.SpotStep, dismiss: str = 'auto') -> s.Spotlight

A stepped spotlight: each step is (target, text), a dict with the SpotStep keys, or a SpotStep; the caption shows Next / Done.

The shell receives a Spotlight:

Field	Type	Default	Description
`steps`	`list[SpotStep]`	`[]`	the stops, in order; empty clears the spotlight
`dismiss`	`str`	`'click'`	`click`: any click outside the caption dismisses; `auto`: only the caption buttons, Escape or `ms` do

Used in: Panelith › How to read these docs · Panelith › Where to go · Panes, state and events › Actions · Panes, state and events › Lifecycle details · Glossary · Examples › The Tour

`set_route`#

set_route(path: str, *, push: bool = False) -> s.SetRoute

Record path in the URL hash (#/guide/panes#events) so the view is shareable; App.on_route receives it back on load.

Argument	Meaning
`path`	the hash without the `#`.
`push`	add a history entry instead of replacing the current one, so the browser's Back button returns to the previous path (which the shell then reports to `on_route`). Use it for page-level navigation, not for scrolling to a section.

The shell receives a SetRoute:

Field	Type	Default	Description
`path`	`str`	required	the hash to write, without the `#`
`push`	`bool`	`False`	add a history entry, so the browser's Back returns to the previous hash (the default replaces the current entry)

`open_url`#

open_url(url: str, *, new_tab: bool = True) -> s.OpenUrl

Open url in a new tab (the default) or navigate the current one.

The shell receives a OpenUrl:

Field	Type	Default	Description
`url`	`str`	required	the URL
`new_tab`	`bool`	`True`	open a new tab rather than navigating

Tones#

notify accepts info, ok, warn, error, bad, accent, dim; the block tones map onto the four toast tones.

Actions

open_pane#

set_state#

patch_state#

set_subtabs#

close_pane#

focus_pane#

rename_tab#

set_title#

notify#

refresh_list#

open_command_bar#

run_builtin#

send_event#

spotlight#

preview#

tour#

set_route#

open_url#

Tones#

`open_pane`#

`set_state`#

`patch_state`#

`set_subtabs`#

`close_pane`#

`focus_pane`#

`rename_tab`#

`set_title`#

`notify`#

`refresh_list`#

`open_command_bar`#

`run_builtin`#

`send_event`#

`spotlight`#

`preview`#

`tour`#

`set_route`#

`open_url`#