API Reference
Blocks
Read-only content blocks plus the stat, chart, list and live-region builders. Layout blocks (stack/grid/section/flex) take option arrays rather than fluent methods and are documented in authoring-pages.md.
Read-only content blocks plus the stat, chart, list and live-region builders. Layout blocks (stack/grid/section/flex) take option arrays rather than fluent methods and are documented in authoring-pages.md.
TextBlock
Tbtop\Admin\Dsl\TextBlock
| Method | What it does |
|---|---|
variant(Closure|string $variant): self | Typographic style applied to the rendered text. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
AlertBlock
Tbtop\Admin\Dsl\AlertBlock
| Method | What it does |
|---|---|
color(Color|Closure|string $color): self | Alert tint (e.g. info/success/warning/danger). Defaults to 'info'. |
title(Closure|string|null $title): self | Optional heading rendered above the message; pass null to clear it. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
MarkdownBlock
Tbtop\Admin\Dsl\MarkdownBlock
| Method | What it does |
|---|---|
allowHtml(): self | Allow raw HTML in the markdown source to pass through unchanged. Use only for trusted, author-controlled content. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
DisplayValueBlock
Tbtop\Admin\Dsl\DisplayValueBlock
| Method | What it does |
|---|---|
badge(array|string $map): self | Ships the raw value plus its color and label maps and lets the client render the badge — unlike date/money, nothing is baked server-side. $map is an inline map ['new' => ['label' => 'New', 'color' => Color::Info]] (both keys optional) or an enum class (HasLabel/HasColor, keyed by ->value, ->name for a pure enum). An unmatched value renders as stored, in gray. The color-only map ['paid' => Color::Success] is deprecated (removed in 1.0). |
boolean(?string $trueIcon = null, ?string $falseIcon = null, Color|string|null $trueColor = null, Color|string|null $falseColor = null): self | Kind sugar: renders the value as a boolean icon (mirrors Column::boolean()); the raw value ships, the client renders the icon. |
copyable(Closure|string $copyMessage = 'Copied', Closure|int $copyMessageDuration = 2000): static | Renders a copy-to-clipboard button next to the value. What lands on the clipboard is whatever reached the client, which is not always the stored value: server-formatted kinds (money/date/datetime/ number) and formatUsing() bake their output into the wire, so a money column copies "12.34 USD", not the cents. Kinds the client renders (badge/boolean/icon) and form fields copy the raw value. |
date(?string $format = null): self | Formats server-side and bakes the string into the wire — no format meta ships. |
datetime(?string $format = null): self | Formats server-side and bakes the string into the wire — no format meta ships. |
field(string $name): self | Bind this block to a modal-data field by name (client resolves the raw value from useModalData() at render time, like a form field's name). Incompatible with baked kinds (date/datetime/number/money) since their formatting runs once at author time, before any live value exists. |
icon(array $map): self | Ships the raw value plus its icon map and lets the client render the icon. An unmatched value falls back to plain text. |
money(string $currency): self | Formats server-side and bakes the string into the wire. Takes minor units — the value is divided by 100, same as Column::money(). |
multiline(bool $enabled = true): self | Renders the value with whitespace-pre-line client-side, so embedded newlines (e.g. a payload string baked as "key: value\nkey: value") render as line breaks instead of collapsing into one line. Independent of kind/field() — a plain-text concern, not a formatting one. |
number(?int $decimals = null): self | Formats server-side and bakes the string into the wire — no format meta ships. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
DisplayImageBlock
Tbtop\Admin\Dsl\DisplayImageBlock
| Method | What it does |
|---|---|
alt(Closure|string $alt): self | Accessible alt text for the rendered image. |
asLink(): self | Render as a file-download link instead of an inline image. |
caption(Closure|string $caption): self | Caption text rendered below the image/link. |
circular(): self | Circular image shape. Last shape call wins. |
square(): self | Square image shape (sharp corners). Last shape call wins. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
Stat
Tbtop\Admin\Dsl\Stat
| Method | What it does |
|---|---|
color(Color|Closure|string $color): self | Tint for the value/icon (a Color or a registered color token). |
delta(Closure|string $text, Closure|string $direction): self | Change indicator (e.g. "+12%") rendered next to the value. $direction is 'up', 'down' or 'flat' and picks the arrow and tint. |
description(Closure|string|null $description, Closure|string|null $color = null): self | Sub-label under the value, optionally tinted to carry meaning ('success'/'warning'/'danger'); the default is muted text. Either argument may be a Closure; a closure-supplied color is checked when it resolves. The description closure also re-runs on each poll() tick. |
disabled(Closure|bool $disabled = true): static | Server-decided initial disabled state, e.g. disabled(fn () => ! $user->isAdmin()). The node still ships and its value still submits: this is a starting state, not access control — enforce permissions server-side, and use disabledIf() for state that follows the form. |
disabledIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side evaluation: the field still ships on the wire and its value still submits — only the input's interactivity is disabled. Contrast with when(), which drops the node from the wire entirely. Pass a Cond, or the shorthand ($field, $op, $value). |
hiddenIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side visibility: the node still ships on the wire and its value still submits with the form even while hidden. Contrast with when(), which drops the node from the wire entirely and 404s its endpoints. Pass a Cond, or the shorthand ($field, $op, $value) — e.g. hiddenIf('type', '=', 'guest'). $field resolves against the enclosing form's values; on a table row action it resolves against the row's columns instead (hiddenIf('status', '!=', 'pending')). |
icon(Closure|string $name, Closure|string $position = 'left'): static | $name is a kebab-case Lucide icon name (e.g. 'circle-check') resolved against the client's icon registry; register custom names client-side via registerIcon before using them here. $position is 'left' (default) or 'right', placing the icon relative to the label. Either may be a Closure; a closure-supplied position is validated when it resolves. |
meta(string $key, mixed $value): static | Sets one of the node meta keys directly: id, hidden, disabled, hiddenIf, disabledIf. Unvalidated — any other key ships and the client ignores it. For an arbitrary wire option use set() instead. |
openInNewTab(bool $newTab = true): self | Deprecated (removed in 1.0): use url()->openUrlInNewTab(). |
openUrlInNewTab(bool $condition = true): self | Open url() in a new browser tab instead of navigating in place. No effect without url(). |
params(array $fields): self | Filter fields rendered in the card above the value (regular field builders, e.g. select('period')->options([...])->default('7d')). Their values reach the value() closure as $params['name']; each change refetches the stat from the page data endpoint, keyed by its label. Text-ish kinds debounce first; keep the set small — a tile has little room. Values arrive from the query string: give each field rules() (e.g. 'in:7,30') — a failing value answers 422 before the closure runs. Not combinable with url(): toNode() throws, a control can't live inside a link. Build the stat with $s->stat(): a bare Stat::make() isn't registered for the endpoint. |
poll(Closure|int $seconds): self | Poll the stat's data endpoint every $seconds, re-invoking the value closure on each tick instead of once at page render. The 5-second floor is enforced twice: below it this throws, and the client clamps whatever reaches it. Stamps options.source so the client fetches from the page data endpoint, keyed by this stat's label. A Closure's result is checked against the floor when it resolves. |
sparkline(array $numbers, string $position = 'inline'): self | Mini trend chart from a plain list of numbers — no axes or labels, so the series only has to be ordered, not scaled. |
sparklineColor(Closure|string $color): self | Tint applied to the sparkline chart. Default: current chart color. A Closure's result is checked when it resolves. |
tooltip(Closure|string $text): static | Tooltip text shown on hover. |
trend(Closure|string $direction): self | Small trend arrow rendered after the description, inheriting its color. A Closure's result is checked when it resolves. |
url(string $url): self | Make the whole card a link — an internal path navigates in place, an external URL opens as a plain link. |
value(mixed $value): self | The headline number/text. Accepts a scalar or a Closure resolved server-side at render time (and on each poll() tick or params() change). The closure may take array $params: the current params() values keyed by field name — their defaults at render, null for a field without one (empty array without params()). |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
ChartBuilder
Tbtop\Admin\Dsl\ChartBuilder
| Method | What it does |
|---|---|
disabled(Closure|bool $disabled = true): static | Server-decided initial disabled state, e.g. disabled(fn () => ! $user->isAdmin()). The node still ships and its value still submits: this is a starting state, not access control — enforce permissions server-side, and use disabledIf() for state that follows the form. |
disabledIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side evaluation: the field still ships on the wire and its value still submits — only the input's interactivity is disabled. Contrast with when(), which drops the node from the wire entirely. Pass a Cond, or the shorthand ($field, $op, $value). |
hiddenIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side visibility: the node still ships on the wire and its value still submits with the form even while hidden. Contrast with when(), which drops the node from the wire entirely and 404s its endpoints. Pass a Cond, or the shorthand ($field, $op, $value) — e.g. hiddenIf('type', '=', 'guest'). $field resolves against the enclosing form's values; on a table row action it resolves against the row's columns instead (hiddenIf('status', '!=', 'pending')). |
meta(string $key, mixed $value): static | Sets one of the node meta keys directly: id, hidden, disabled, hiddenIf, disabledIf. Unvalidated — any other key ships and the client ignores it. For an arbitrary wire option use set() instead. |
params(array $fields): self | Filter fields rendered above the chart (regular field builders, e.g. select('interval')->options([...])->default('month')). Their values reach the query() closure as $params['name']. Text-ish kinds debounce before refetching; every change costs one request, so keep the set small. Values arrive from the query string: give each field rules() (e.g. 'in:day,month') — a failing value answers 422 before the query runs. |
poll(Closure|int $seconds): self | Re-fetch the chart's data endpoint every $seconds. The 5-second floor is enforced twice: below it this throws, and the client clamps whatever reaches it. Only meaningful together with ->query(). A Closure's result is checked against the floor when it resolves. |
query(callable $fn): static | Makes the chart dynamic: data comes from the page data endpoint instead of $opts. $fn: fn(Request $request, array $params): array — $params holds the current values of the params() fields keyed by field name (empty array without params()). Return a list of flat rows (arrays or a query result) containing the xKey/nameKey column and every series dataKey, e.g. [['period' => '2026-08', 'count' => 12], ...]. |
set(string $key, mixed $value): self | Escape hatch: writes $key directly into the serialized chart node options, bypassing any dedicated fluent method. Key names are NOT validated against the schema — a typo or unsupported key ships silently. Prefer a real fluent method when one exists. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |
ListBuilder
Tbtop\Admin\Dsl\ListBuilder
| Method | What it does |
|---|---|
disabled(Closure|bool $disabled = true): static | Server-decided initial disabled state, e.g. disabled(fn () => ! $user->isAdmin()). The node still ships and its value still submits: this is a starting state, not access control — enforce permissions server-side, and use disabledIf() for state that follows the form. |
disabledIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side evaluation: the field still ships on the wire and its value still submits — only the input's interactivity is disabled. Contrast with when(), which drops the node from the wire entirely. Pass a Cond, or the shorthand ($field, $op, $value). |
hiddenIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side visibility: the node still ships on the wire and its value still submits with the form even while hidden. Contrast with when(), which drops the node from the wire entirely and 404s its endpoints. Pass a Cond, or the shorthand ($field, $op, $value) — e.g. hiddenIf('type', '=', 'guest'). $field resolves against the enclosing form's values; on a table row action it resolves against the row's columns instead (hiddenIf('status', '!=', 'pending')). |
items(callable $fn): self | Row source for the list. $fn runs server-side at serialization time (no request payload — same lazy-resolution shape as Stat::value) and returns each row either as ['title' => ..., 'meta'?, 'color'?, 'url'?, 'openUrlInNewTab'?] or as $s->listItem(...); the two forms mix freely. 'title' is required, 'color' is one of success|warning|danger|muted, 'openUrlInNewTab' is a bool with no effect without 'url'. Unknown array keys are ignored. |
meta(string $key, mixed $value): static | Sets one of the node meta keys directly: id, hidden, disabled, hiddenIf, disabledIf. Unvalidated — any other key ships and the client ignores it. For an arbitrary wire option use set() instead. |
ListItem
Tbtop\Admin\Dsl\ListItem
| Method | What it does |
|---|---|
color(string $color): self | Status dot color: success|warning|danger|muted (validated at serialization). |
meta(string $meta): self | Muted secondary text on the right of the row (e.g. "2h ago"). |
openUrlInNewTab(bool $condition = true): self | Open url() in a new browser tab instead of navigating in place. No effect without url(). |
url(string $url): self | Make the row a link — an internal path navigates in place, an external URL opens as a plain link. |
LiveRegionBuilder
Tbtop\Admin\Dsl\LiveRegionBuilder
| Method | What it does |
|---|---|
dependsOn(array|string $fields): self | Declare the form field(s) whose value changes reload this region. Their current values reach the render closure as ['field' => value]. |
disabled(Closure|bool $disabled = true): static | Server-decided initial disabled state, e.g. disabled(fn () => ! $user->isAdmin()). The node still ships and its value still submits: this is a starting state, not access control — enforce permissions server-side, and use disabledIf() for state that follows the form. |
disabledIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side evaluation: the field still ships on the wire and its value still submits — only the input's interactivity is disabled. Contrast with when(), which drops the node from the wire entirely. Pass a Cond, or the shorthand ($field, $op, $value). |
hiddenIf(Cond|string $condOrField, string $op = '', mixed $value = null): static | Client-side visibility: the node still ships on the wire and its value still submits with the form even while hidden. Contrast with when(), which drops the node from the wire entirely and 404s its endpoints. Pass a Cond, or the shorthand ($field, $op, $value) — e.g. hiddenIf('type', '=', 'guest'). $field resolves against the enclosing form's values; on a table row action it resolves against the row's columns instead (hiddenIf('status', '!=', 'pending')). |
meta(string $key, mixed $value): static | Sets one of the node meta keys directly: id, hidden, disabled, hiddenIf, disabledIf. Unvalidated — any other key ships and the client ignores it. For an arbitrary wire option use set() instead. |
render(callable $fn): self | The region's content, re-rendered server-side each time a declared dependsOn() field changes (one round-trip per change). $fn receives only the dependsOn()-filtered deps, not the full form state, and must return display nodes only — no fields. |
when(Closure|bool $condition): static | Server-side existence gate: false (or a closure resolving falsy) means the node is dropped before serialization — absent from the wire, and any endpoint scoped to it (action, query, data) answers 404. Not the same as hiddenIf()/disabledIf(), which ship the node and let the client hide/disable it while its value still submits. |