Page toolbar

PageToolbar is the bar a page with a period or live data starts with, under its header: "Updated 2 s ago · ● Live | ❚❚ Pause · since yesterday 11:29 · vs Oct 16 … · 1H 24H 7D 30D". It holds real blocks — a LiveToggle, a PeriodSelector and whatever a page puts on the left (a scope chip, a picker) — and draws them in one order and at one size, whatever order they were added in:

[leading blocks…] · spacer · updated label · Live / Pause · window · vs window · comparison menu · presets

On a narrow screen it wraps onto more lines, the controls staying on the right.

Every control in it is as tall as the others at its size — 24 px at xs, 28 px at sm, 32 px at md: the Live / Pause pill, the presets, the comparison menu, the refresh button. A bar is the same height on a live page, a page with a period only, and a page with both. A leading block of a module's own takes the same height from usePageToolbarSize().

Preview Code

Connecting to the DMS preview…

static pageToolbar = PageToolbar({ size: "sm" })
  .child("live", LiveToggle({ variant: "pill" }))
  .child("period", PeriodSelector({
    variant: "segmented",
    rangeLabel: "relative",
    presets: ["last-hour", "last-24h", "last-7-days", "last-30-days"],
    defaultPreset: "last-24h",
  }));

Usage

pageToolbar() builds one with the defaults every page shares, and a page puts it first:

import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
import { pageToolbar } from "@antelopejs/interface-dms/base/page-toolbar";

@RegisterPage()
export class Overview extends PageController("overview", {
  displayName: "Overview",
  live: { maxRate: 5, rememberKey: "api" },
}) {
  static toolbar = pageToolbar({
    // Any block: a scope chip, a picker, a badge.
    leading: { scope: CustomComponent("ScopeChip") },
    live: { missedLabel: "$api.live.new_requests" },
    period: {
      id: "api",
      rememberKey: "api",
      // A menu naming the compared window: "vs 16 – 17 Oct ▾".
      comparisons: ["previous-period", "previous-year", "none"],
    },
  });
  static kpis = /* … */;
}

The children are ordinary blocks: PageToolbar() with .child() builds the same toolbar by hand, and a page builder finds its LiveToggle and PeriodSelector where they always were.

Child ids and metadata

live and period take, besides the control's options, how the toolbar places that child: childId, the id roles name it by (live and period by default, exported as PAGE_TOOLBAR_LIVE_CHILD_ID and PAGE_TOOLBAR_PERIOD_CHILD_ID), and meta, its name, description and icon in the roles editor. A page moving to pageToolbar() keeps the ids its roles already grant, and needs no hand-built toolbar for it:

static toolbar = pageToolbar({
  // The toggle was granted as `toggle` before the page used the helper.
  live: { childId: "toggle", meta: { name: "$my.permissions.live.name" } },
  // `id` stays the period scope's id; `childId` would rename the child.
  period: { id: "my-scope", meta: { name: "$my.permissions.period.name" } },
}).meta({ name: "$my.permissions.toolbar.name" });

An option known only once the module is configured (a retention read in construct(), after the page class was built) goes through transformOptions on live or period: it runs each time the page is registered, over the options the helper built, and returns new ones. Do not reach for the toolbar's children to change them afterwards.

period: {
  id: "runs",
  comparisons: ["previous-period", "none"],
  // Year-back only when the runs are kept long enough to reach it.
  transformOptions: (options) => options && { ...options, comparisons: offeredComparisons() },
},

The comparison control is chosen from the comparisons given at build time: a transform that leaves a single comparison also sets comparisonControl: "hidden".

A page builder creates a new toolbar with the same children: the PageToolbar entry of ListBlockTypes carries them in initialChildren (id, type and options, the defaults above), so an editor reads them there instead of keeping its own copy.

Pages with and without live

• A live page (declared with live) shows the LiveToggle as always: "Updated 2 s ago", Live / Pause, the L key, "Paused · 40 new requests", Resume, the polling hint.
• A page without live has no Direct / Pause: the toggle draws nothing, and the toolbar shows when the page last read its data, with a refresh button. The time is the page's own: set when the page is shown, when its blocks read again on their events, and once a refresh (refreshPageBlocks()) is done.

// A report page: a period, no live data.
static toolbar = pageToolbar({ live: false, period: { id: "sales" } });

// A queue: live data, no period.
static toolbar = pageToolbar({ period: false });

The toolbar sits in the page body, first, like any block. It does not move into the page header.

Options

Next steps