Reference · Panelith 0.1.0 · plain HTML edition; the interactive edition has search and live examples
Blocks
Every constructor in panelith.blocks. Each returns a plain dict; Pane.view(state) returns view(...) of them. See Blocks.
view#
view(*blocks: dict[str, Any] | None, direction: str = 'column', scroll: str | None = None, align: str | None = None, tags: list[str] | None = None) -> dict[str, Any]
The dict Pane.view returns: the block list plus root layout. align
is center (everything centred, the default look of a game pane) or
start (text and stats read from the left, for a report). tags
become tag-<name> classes on the body (for styling and for tests).
Used in: Blocks: a pane body composed in Python › Worked example: Super Boggle
grid#
grid(cells: list[Any], columns: int, *, trace: dict[str, Any] | None = None, disabled: bool = False, message: dict[str, Any] | None = None, pending: dict[str, Any] | None = None, key: str | None = None, grow: bool = True, height: int | None = None) -> dict[str, Any]
A grid of cells. With trace rules the user can drag a path across it;
the path comes back as the rules' event with payload {"path": [cell indexes]} when the pointer lifts.
| Argument | Meaning |
|---|---|
cells |
the cell texts, row-major; a cell may be {"text", "tone"}. |
columns |
how many cells per row. |
trace |
trace_rules(...), or None for a grid that is only looked at. |
disabled |
draw the grid but accept no gesture. |
message |
message(...), the status line under the grid. |
pending |
{"path": [...], "message": message(...)}: a verdict the live_event handler prepared for a path still being traced; if that is the path that lifts, the grid shows it at once. |
key |
stable identity across re-renders. |
grow |
fill the pane's spare room (the default). |
height |
fix the grid's height in pixels instead, for a grid that sits in a scrolling column with other blocks. |
Used in: Blocks: a pane body composed in Python › Worked example: Super Boggle
trace_rules#
trace_rules(*, event: str = 'trace', adjacency: int = 8, min_cells: int = 2, backtrack: bool = True, radius: float = 0.42, preview: bool = True, min_text: int | None = None, live_event: str | None = None, judge: dict[str, Any] | None = None) -> dict[str, Any]
How a drag across a grid behaves, enforced in the browser between frames.
A trace consumes the grid's current message: after the pointer lifts the
line shows a spinner until the reply replaces it, never the old verdict.
| Argument | Meaning |
|---|---|
event |
the pane event emitted when the pointer lifts, with {"path"}. |
adjacency |
8 (a king's move) or 4 (orthogonal neighbours only). |
min_cells |
a shorter path is dropped at the lift. |
backtrack |
moving back onto the previous cell undoes the last one. |
radius |
the inner disc of a cell (as a fraction) that counts as a hit. |
preview |
show the traced text in the message line as it grows. |
min_text |
with preview, hint N+ letters while the text is shorter. |
live_event |
also post the path each time it changes while the finger is down (one request in flight at a time); its handler can patch the grid's pending verdict so the lift shows it with no wait. |
judge |
judge(...): let the browser give the verdict itself. |
judge#
judge(*, salt: str, hashes: list[str], known: list[str] | None = None, min_text: int | None = None, points: dict[Any, int] | None = None, say: dict[str, str] | None = None, tone: dict[str, str] | None = None, key: Any = None) -> dict[str, Any]
A verdict the browser can give the moment a trace lifts, with no round
trip: hashes are fingerprint(salt, text) of the accepted texts (the salt
keeps them from reading as a word list), known the plain texts already
taken, min_text the shortest accepted. The outcome is one of ok,
known, short or miss; say gives each a message template with
{text}, {points} and {len}, tone a tone, points maps a length
(or "+" for longer) to what an ok earns. key should be the key the
server's own reply will carry, so the two render as one message. The
server still judges the submitted path; this only shows its answer early.
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 · Examples › Super Boggle · Examples › Starboard
fingerprint#
fingerprint(salt: str, text: str) -> str
FNV-1a (32 bits, hex) of salt + text, as the shell computes it.
Used in: Blocks: a pane body composed in Python › The block types · Blocks: a pane body composed in Python › The trace gesture
message#
message(text: str | None = None, hint: str | None = None, *, tone: Tone | None = None, key: Any = None) -> dict[str, Any]
A one-line status: text in the main voice, hint dimmer. A new key
replays the tone's animation (ok pops, bad shakes).
Used in: Blocks: a pane body composed in Python › Worked example: Super Boggle
text#
text(value: str, *, tone: Tone | None = None, size: str | None = None, key: str | None = None) -> dict[str, Any]
A paragraph. Newlines are kept. size is sm, lg or xl (default body size).
Used in: Panelith › How to read these docs · Panes, state and events › A kind is a class · Panes, state and events › State is the model · Panes, state and events › Actions · Panes, state and events › Worked example: a form that writes to an output pane · Commands, hotkeys and the launcher › The top bar and the brand
toolbar#
toolbar(*items: dict[str, Any] | None, justify: str = 'center', key: str | None = None) -> dict[str, Any]
A row of buttons and inline items (a countdown, a stat).
Used in: Blocks: a pane body composed in Python › Worked example: Super Boggle
button#
button(label: str, event: str, *, payload: dict[str, Any] | None = None, primary: bool = False, disabled: bool = False) -> dict[str, Any]
Emits event with payload when pressed.
Used in: Blocks: a pane body composed in Python › The block types · Blocks: a pane body composed in Python › Worked example: Super Boggle
countdown#
countdown(until: float, *, event: str | None = None, low: float | None = 15, label: str | None = None, tone: Tone | None = None) -> dict[str, Any]
m:ss until the server timestamp until, ticking in the browser against
the synced server clock.
| Argument | Meaning |
|---|---|
until |
an epoch timestamp (time.time() based) on the server's clock. |
event |
fire this pane event once when the countdown reaches zero. |
low |
turn red under this many seconds (None never). |
label |
a caption, when the countdown sits among stats. |
tone |
a colour tone while above low. |
Used in: Blocks: a pane body composed in Python › Worked example: Super Boggle
stats#
stats(*items: dict[str, Any] | None, size: str = 'md', justify: str | None = None, key: str | None = None) -> dict[str, Any]
Big numbers with captions. Items are stat(...) or countdown(...).
Used in: Widgets › blocks · Blocks: a pane body composed in Python › The block types · Blocks: a pane body composed in Python › Tones, tags and layout · Glossary
stat#
stat(value: Any, label: str, *, tone: Tone | None = None) -> dict[str, Any]
One big number (or short text) with a caption, inside stats(...).
Used in: Blocks: a pane body composed in Python › The block types
cards#
cards(*items: dict[str, Any] | None, wrap: bool = True, figure_px: int = 64, empty_text: str | None = None, justify: str | None = None, grow: bool = False, scroll: str | None = None, key: str | None = None) -> dict[str, Any]
Small cards (a figure, a title, a subtitle). wrap=False keeps them on
one line, usually with scroll="x".
Used in: Widgets › blocks · Blocks: a pane body composed in Python › The block types · Blocks: a pane body composed in Python › Tones, tags and layout · Glossary
card#
card(title: str, *, subtitle: str | None = None, figure: dict[str, Any] | None = None, tone: Tone | None = None, event: str | None = None, payload: dict[str, Any] | None = None, key: str | None = None) -> dict[str, Any]
With event, the card is a button.
Used in: Widgets › markdown · Blocks: a pane body composed in Python › The block types
figure#
figure(cells: list[Any], columns: int, path: list[int], *, px: int | None = None) -> dict[str, Any]
A small picture of a grid with a path drawn over it (a trace, replayed).
Used in: Blocks: a pane body composed in Python › The block types
chips#
chips(*items: dict[str, Any] | None, title: str | None = None, wrap: bool = True, grid: bool = False, grow: bool = False, scroll: str | None = None, key: str | None = None) -> dict[str, Any]
Small labels, clickable when given an event. grid lays them out in
equal columns that fit the width (a long list on a phone scrolls down,
never sideways); with grow and scroll="y" the block fills the pane
and scrolls on its own.
Used in: Panes, state and events › Events and handlers · Widgets › blocks · Blocks: a pane body composed in Python › The block types · Blocks: a pane body composed in Python › Tones, tags and layout · Glossary · Examples › Smaller pieces, all live
chip#
chip(value: str, *, tone: Tone | None = None, event: str | None = None, payload: dict[str, Any] | None = None) -> dict[str, Any]
One small label inside chips(...); with event it is a button.
Used in: Blocks: a pane body composed in Python › The block types
Common keys#
Every block accepts key (stable identity), most accept grow (take the spare room) and scroll (x or y). None entries in any item list are dropped. Tones are ok, warn, bad, accent, dim.