Skip to content

Tabs, pages & custom panes

The dashboard's tabs are the navigation structure (openspec navigation-specs, tui#52), the same the web app follows: a tree of nodes, each opening a built-in view (a View Id), a page spec, or holding children. The structure in use is

  1. your own ~/.config/virtufin/tui/navigation.json, if it validates;
  2. else the structure an admin shared on the context (cfg.navigation, from the web app's Navigation editor), followed live;
  3. else the built-in default virtufin-domain-devkit ships (the same default the web app has).

The pages and navigation views are always reachable: a structure without them gets a Config group holding them. The Navigation pane says which structure is in use and why another was skipped.

{
  "$schema": "https://app.virtufin.com/schemas/navigation.v1.schema.json",
  "version": 1,
  "nodes": [
    {"id": "home", "label": "Home", "view": "home"},
    {"id": "trading", "label": "Trading", "children": [
      {"id": "feeds", "label": "Feeds", "view": "feeds"},
      {"id": "analytics", "label": "Analytics", "children": [
        {"id": "pnl", "label": "P&L", "view": "pnl"},
        {"id": "overview", "label": "My overview", "page": "stopped_workers"}
      ]}
    ]}
  ]
}

How the TUI draws it (its representation profile): the first level is the top tabs, the second the sub-tabs (keys 1-9, 0 for the tenth, </> beyond); a top-level leaf (home) is a tab without sub-tabs; a deeper node is a sub-tab labelled with its groups (Analytics › P&L). A view names a built-in view (home, feeds, instruments, orderbook, indicators, portfolio, pnl, risk, strategy, scenario, workers, connections, scripts, triggers, states, eventstores, alerts, changes, events, ai, pages, navigation) or a custom pane below; a view the TUI lacks (services) shows a placeholder naming it. A page opens the context's shared page of that name.

The pane_order of config.toml is gone: a customised one was written to navigation.json once, an unchanged one dropped.

Editing your structure from the TUI

The Navigation pane (Config → Navigation) shows the structure in use, two levels:

Key Action
ctrl+up / ctrl+down Move the highlighted entry within its tab
d Delete the highlighted entry (the navigation table focused); protected entries (Pages, Navigation) stay
a Add the view highlighted in "Available views and custom panes" (or Enter on it) after the highlighted entry
t A new top-level tab holding the highlighted available view (prompts for id + label)

The first edit makes the structure your own (navigation.json); each edit is validated, saved and applied at once, new tabs included. "Use the shared structure" deletes navigation.json. The structure shared on the context is edited in the web app only.

Pages

A node with page renders a page spec shared on the context (openspec page-specs; written and shared in the web app's Pages view). The Pages view lists them; Enter renders one. The TUI draws Stack, Heading, Text, WorkerTable (the Worker Filter over the workers) and ValueStream (the value view of a topic, state key or read); a component that is a whole view (WorkerBrowser, ConnectionBrowser, ...) opens that pane in its place, with its keys; any other component shows a placeholder. A page that does not validate lists its errors.

To put a shared page or a custom pane in your tabs step by step, see Make a page and add it to the navigation. Pages are written and shared in the web app (https://app.docs.virtufin.com/).

Custom panes

Drop files into ~/.config/virtufin/tui/panes/ (created automatically). Two kinds, distinguished by what's alongside the .py file:

Script + form pane

A <name>.py with a sibling <name>.form.json — the same convention already used by the Scripts page's built-in examples (see create_worker.py / create_worker.form.json there for a full reference). The form's fields are collected and passed to your script as JSON via the VIRTUFIN_TUI_FORM_DATA env var when submitted; the script also receives the same VIRTUFIN_TUI_API_{HOST,PORT,TLS,KEY} / VIRTUFIN_TUI_WORKER_API_{HOST,PORT} env vars every script gets — see Scripts → The env-var contract for the full table and who sets these. Output streams to a log below the form. This is a one-shot action pane, not a continuously updating one. The form schema itself is defined by textual_jsonforms -- see docs/textual-jsonforms-spec.md in the repo root for the full field-type reference. (The same library also powers the Workers page's a/Add worker form, built dynamically from a worker's JSON-Schema config_schema rather than a hand-written .form.json.)

Live widget pane

A <name>.py with no sibling .form.json, defining a module-level class named exactly Pane:

from virtufin_tui.screens._page import Page

class Pane(Page):
    def compose(self):
        ...

    def on_mount(self):
        self.set_interval(1.0, self.refresh)

Pane subclasses Page, the base of the built-in pages: it is built with (stores, client) (self._stores is the dashboard's DataPump, self._client the active TuiClient). This gives you a genuine persistent page — live polling, subscriptions, whatever you need — not just a form submission. A plain textual.widget.Widget with the same __init__(self, stores, client, **kwargs) works too.

A Page gets the connection state from the dashboard in self.connection (the active context, its URL, whether it answers, and every context's health); override connection_changed() to redraw when it changes.

While no context is active, a pane shows "needs a context" instead of mounting, so client is never None in your page. A pane that works without a context (and handles client being None) sets the class attribute WORKS_UNBOUND = True, as Home and Config do.

A file matching neither pattern (no form, and no Pane class) is skipped and logged as a warning; it won't crash the TUI.