Display Blocks

Overview

Seven builders cover the summaries and notices around a page's data: StatGroup, KeyValueList, NavCardGrid, EmptyState, Banner, Card and CodeBlock. Each returns a ComponentBuilder and registers its block type with an options schema, so ListBlockTypes() describes it to a page builder. Card is a container; the others are leaves. The task-shaped chapter is Display blocks.

import {
  Banner,
  Card,
  CodeBlock,
  EmptyState,
  KeyValueList,
  NavCardGrid,
  StatGroup,
} from "@antelopejs/interface-dms/base";

Every factory but EmptyState takes its options as optional, so a block placed before it is configured is the bare call StatGroup(). EmptyState(options) requires its options, title included.

Shared Vocabulary

display holds what the six share; the tones come from types/tone, also re-exported by the base barrel. color is for what is clicked (buttons, row actions, header actions, tabs), tone for what shows a state (pills, icon wells, banners, meters, notifications, blocks).

A block that can drop its frame does so with card?: boolean (KeyValueList, EmptyState, and the ActivityFeed, Meter and Section of Lists & settings); Card itself has padded. In the page editor a fetchUrl is picked in the data-source picker (widget dataSource).

List Blocks

StatGroupProps, KeyValueListProps and NavCardGridProps — and ActivityFeedProps (Lists & settings) — extend BaseComponentProps and BlockItemsSource. Their items are static; a fetchUrl replaces them with the items of its answer, { items: T[] }, in the same item shape. An ActivityFeed's answer may add a count (ActivityFeedResponse), drawn beside its title in place of its count option. When there is nothing to list, the block shows empty.

fetchUrl may name the record of the page it is on: {{params.X}} is filled with the route parameter X of the page URL ({{params.id:n}} for the n-th of a repeated name), {{query.X}} with its query parameter X, as in a form's fetchUrl. The block reads it again when they change and requests nothing while a token has no value. The same holds for the fetchUrl of KpiCard, TopListCard, Meter, ChartCard and the charts, and for TabProps.badgesUrl.

BlockFunctions.REFRESH_PAGE ("DmsComponent.Block.RefreshPage", no params in WatchFunctionParamMap) makes each of those blocks, and every TableView of the page, fetch again without remounting, keeping its values until the answer lands: .watch(FormEvents.SUBMIT_SUCCESS, BlockFunctions.REFRESH_PAGE) on a form that changes the record. The page header's buttons do it on their own after a change; frontend code calls refreshPageBlocks().

periodScope names the PeriodSelector whose period is added to the request, as for a KpiCard; the block refetches when it changes. realtimeTopic (string | string[]) names the topics the backend publishes on when the items change: the builder registers each against its page (RegisterPageTopic), and the block refetches on each event, keeping its items on screen. Meter takes both options for its own fetchUrl, and TabProps.realtimeTopic does the same for badgesUrl.

skeletonCount is the number of placeholder items the block draws while fetchUrl loads, so it keeps its height when the items land. Optional. Defaults to columns, or 4 (StatGroup); 5 (KeyValueList); columns, or 3 (NavCardGrid); maxItems, or 3 (ActivityFeed).

KeyValueListItem.copy draws a copy button copying the shown value; copyValue (a string) copies that text instead and implies copy.

STAT_GROUP_LAYOUTS is joined, cards; KEY_VALUE_TYPES is text, status, money, date, link, mono.

Composed Texts

StatGroupItem.eyebrow, .value and .detail, KeyValueListItem.label, .value and .detail, NavCardItem.title, .description, .state, .tag and .readout lines, ActivityFeedItem.title, .meta entries, .detail and .time, ActivityFeedProps.badge, MeterProps.hint and .valueLabel, MeterSegment.label, TopListItem.title, .description and .valueLabel, BannerProps.title and .description, and a layout banner's text are typed BlockText: a plain string as before, or a ComposedText the frontend writes in the reader's locale. The block schemas accept both (ValidateBlockOptions refuses a parameter of an unknown type) and describe the field with the text widget. The task-shaped guide is Composed texts.

ActivityFeedItem.params is a Record<string, ComposedTextParam>: the values a $-prefixed title or detail names, typed as a composed text's parameters, so a count picks the plural form. A plain string value is inserted as before, and a $-prefixed one is translated with the entry's other values.

Static Blocks

EmptyStateCode is { content, language?, copy? }: a snippet between the text and the actions, drawn as a CodeBlock.

EMPTY_STATE_VARIANTS is no-data, no-result, no-access, error; EMPTY_STATE_SIZES is sm, md, lg. BANNER_TONES is info, success, warning, error, primary; BANNER_SIZES is md, sm. CARD_VARIANTS is default, elevated. The three props extend BaseComponentProps (watchActions) like the list blocks. BannerTone is Extract<Tone, …> over BANNER_TONES. A banner's dismissKey defaults to the block's id on its page (welcome for .child("welcome", Banner(…))), which holds when blocks are added or moved. A banner's fetchUrl answers a BannerContent (the content fields of BannerProps, its actions being BannerAction[]: a BlockLinkAction or a BannerButtonAction, the label, icon, variant, color, target and confirm of a CustomButtonSerialized), or null, {} or a 204 for no banner; its fields override the options one by one. realtimeTopic registers each topic on the page the banner is placed on, as a chart's does.

Code Block

CodeBlockProps extends BaseComponentProps: code, language (CodeBlockLanguage, default text), copy (default true), title (BlockText), maxLines, wrap, fetchUrl and fetchUrlMethod. CODE_BLOCK_LANGUAGES is json, javascript, typescript, html, sql, shell, text. A fetchUrl answers a CodeBlockResponse, { code, language? }, which replaces code and language; it takes the {{params.X}} / {{query.X}} tokens and BlockFunctions.REFRESH_PAGE like the list blocks. CodeBlock(options?) takes its options as optional.

Card Slots

Card registers container: true and two slots, CARD_ACTIONS_SLOT ("actions", next to the head's link buttons) and CARD_FOOTER_SLOT ("footer", the foot band). Children without a slot render in the body; each slot holds one child.

Card({ title: "Connectors", count: 4 })
  .child("list", KeyValueList({ card: false, items }))
  .child("foot", HStack(), { slot: CARD_FOOTER_SLOT });

Live Toggle

LiveToggle(options?) (subpath live-toggle, block type LiveToggle, component dms-live-toggle-block, group data) is the Live / Pause switch of a page declared with live (PageLiveOptions from @antelopejs/interface-dms/page). LiveToggleProps extends BaseComponentProps: align (LIVE_TOGGLE_ALIGNS: left, center, right; default right) showUpdatedAt (default true), the time since the page last read its data, counted in the browser, variant (LIVE_TOGGLE_VARIANTS: segmented, pill; default segmented) and missedLabel, an i18n key or text given {count} naming the missed events while paused. The state belongs to the page, not to the block; on a page without live the block renders nothing.

import { LiveToggle } from "@antelopejs/interface-dms/base/live-toggle";

static toolbar = HStack().child("spacer", Spacer()).child("live", LiveToggle());