El artículo 16 llevó al panel de operaciones los componentes de silverpoint que reciben un valor y los que muestran datos. Este sigue con los que quedan: la tabla, los componentes compuestos y las ventanas superpuestas, las que se abren encima de la página.

Lo que vas a construir

Una tabla con las incidencias del día. Se ordena por servicio, gravedad, hora o duración, y muestra cinco filas por página. Un botón abre un modal para reconocer una incidencia abierta, y al reconocerla una notificación lo confirma.

El modal para reconocer una incidencia sobre la tabla ordenada por duración, y la tabla con la incidencia reconocida y la notificación

A la izquierda, el modal abierto sobre la tabla ordenada por minutos, de mayor a menor. A la derecha, la misma tabla con INC-1038 reconocida y la notificación abajo.

La tabla

SpTable dibuja una tabla nativa: <table>, <caption>, <th scope="col">. Cada columna es una fila con key y title, y puede llevar align, sortable y width. Cada celda muestra el valor de su campo como texto; no hay celdas a medida.

PropQué hace
columnsLas columnas, en orden
dataLas filas que se dibujan
captionEl título de la tabla, que también la nombra
sortKey, sortOrderLa columna ordenada y su sentido, asc o desc
onSortSe llama con la clave de la columna cuyo encabezado se pulsa
striped, hoverable, borderedFilas tramadas alternas, realce al pasar el puntero, bordes
emptyTextEl texto sin filas; por defecto, «No data»
rowKeyEl campo que identifica cada fila

La tabla no ordena: avisa. El encabezado de una columna con sortable es un botón, y al pulsarlo onSort recibe la clave. Ordenas tú, con uiSortRows de @silverpoint/core/ui (en Reflex, sort_rows), y le pasas a la tabla las filas ordenadas con sortKey y sortOrder para que dibuje la flecha y ponga aria-sort en esa columna.

uiSortRows es estable, pone los números antes que el texto, compara el texto en minúsculas sin tener en cuenta el idioma y deja al final las filas sin valor. Como el orden es tuyo, también puedes ordenar en el servidor o con tu propia función.

Los datos

Doce incidencias del día, en src/incidents.ts. En Vue es el mismo archivo, y en Angular va en src/app/incidents.ts:

export type Incident = {
  id: string;
  service: string;
  severity: string;
  opened: string;
  minutes: number;
  status: string;
};

export const INCIDENTS: Incident[] = [
  { id: 'INC-1031', service: 'API', severity: 'sev2', opened: '00:42', minutes: 18, status: 'resolved' },
  { id: 'INC-1032', service: 'Search', severity: 'sev3', opened: '02:15', minutes: 7, status: 'resolved' },
  { id: 'INC-1033', service: 'Checkout', severity: 'sev1', opened: '07:58', minutes: 46, status: 'resolved' },
  { id: 'INC-1034', service: 'API', severity: 'sev3', opened: '08:20', minutes: 5, status: 'resolved' },
  { id: 'INC-1035', service: 'Checkout', severity: 'sev2', opened: '09:47', minutes: 23, status: 'resolved' },
  { id: 'INC-1036', service: 'Search', severity: 'sev2', opened: '10:31', minutes: 31, status: 'resolved' },
  { id: 'INC-1037', service: 'API', severity: 'sev1', opened: '11:56', minutes: 12, status: 'resolved' },
  { id: 'INC-1038', service: 'Checkout', severity: 'sev2', opened: '12:09', minutes: 38, status: 'open' },
  { id: 'INC-1039', service: 'Search', severity: 'sev3', opened: '13:44', minutes: 9, status: 'open' },
  { id: 'INC-1040', service: 'API', severity: 'sev2', opened: '14:02', minutes: 16, status: 'open' },
  { id: 'INC-1041', service: 'Checkout', severity: 'sev3', opened: '15:30', minutes: 4, status: 'open' },
  { id: 'INC-1042', service: 'API', severity: 'sev1', opened: '16:18', minutes: 27, status: 'open' },
];

export const COLUMNS = [
  { key: 'id', title: 'Incident' },
  { key: 'service', title: 'Service', sortable: true },
  { key: 'severity', title: 'Severity', sortable: true },
  { key: 'opened', title: 'Opened', sortable: true },
  { key: 'minutes', title: 'Minutes', sortable: true, align: 'end' as const },
  { key: 'status', title: 'Status' },
];

export const PAGE_SIZE = 5;

align: 'end' as const mantiene el literal para que el tipo encaje con el de las columnas.

La paginación

SpPagination no corta las filas: dibuja los botones de página y avisa del cambio. Le das el total (total) y el tamaño de página (pageSize, 10 por defecto), y cortas tú las filas de la página actual. Con showTotal escribe el rango, «6–10 of 12»; totalTemplate cambia ese texto.

ControladoCambio
ReactcurrentonChange(page)
Vuev-model:currentupdate:current
Angular[(current)](currentChange)
Reflexcurrenton_change

Las ventanas superpuestas

ComponentePara quéCómo funciona
SpModalUn diálogo que bloquea la páginaUn <dialog> abierto con showModal()
SpDrawerUn diálogo pegado a un lado (side)Un <dialog>, modal salvo con modal={false}
SpPopoverContenido junto a su disparador, sin bloquearUn popover de la API Popover
SpTooltipUn texto corto al pasar el puntero o al enfocarUn popover manual, que no cierra los demás
SpSelectUna opción de una listaUn combobox de solo selección
SpDropdownMenuUn menú de accionesonSelect recibe la clave de la acción
SpToastUn aviso que se cierra soloUn elemento de la lista de SpToaster

Todas usan la plataforma: el navegador pone la ventana encima de la página, atrapa el foco del modal y lo cierra con Escape.

El disparador es un botón nativo

Cada ventana se abre con un <button type="button"> nativo, que recibe su ARIA (aria-haspopup, aria-expanded, aria-controls) y su apertura:

FrameworkDónde va
ReactLa prop trigger, trigger={<button type="button">…</button>}
VueLa ranura #trigger
AngularUn <button type="button" spTrigger> proyectado; SpTrigger se importa del subpath de la ventana
Reflextrigger="…", un texto que se dibuja como botón, o trigger=rx.el.button(…, type="button")

En React no pases un SpButton como disparador: descarta el ARIA que recibe.

El estado abierto

ControladoNo controladoCambio
ReactopendefaultOpenonOpenChange(open)
Vuev-model:opendefault-openupdate:open
Angular[(open)][defaultOpen](openChange)
Reflexopendefault_openon_open_change

onOpenChange también se llama cuando la plataforma cierra la ventana: con Escape o con un clic fuera. Un modal con dismissible={false} ignora los dos.

Las notificaciones

Se pone un SpToaster cerca de la raíz y, dentro, un SpToast por aviso. Un aviso se cierra a los 5000 ms, la duration del contenedor, salvo que tenga la suya. Mientras tiene el puntero o el foco, la cuenta se para, y F8 lleva el foco al contenedor.

La tabla de incidencias en React

import { useState } from 'react';
import { uiSortRows } from '@silverpoint/core/ui';
import { SpButton } from '@silverpoint/react/ui/button';
import { SpModal } from '@silverpoint/react/ui/modal';
import { SpPagination } from '@silverpoint/react/ui/pagination';
import { SpSelect } from '@silverpoint/react/ui/select';
import { SpTable } from '@silverpoint/react/ui/table';
import { SpToast, SpToaster } from '@silverpoint/react/ui/toast';
import { COLUMNS, INCIDENTS, PAGE_SIZE } from './incidents';

export function Incidents() {
  const [rows, setRows] = useState(INCIDENTS);
  const [sortKey, setSortKey] = useState('opened');
  const [sortOrder, setSortOrder] = useState<'asc' | 'desc'>('desc');
  const [page, setPage] = useState(1);
  const [open, setOpen] = useState(false);
  const [picked, setPicked] = useState<string | null>(null);
  const [acknowledged, setAcknowledged] = useState('');
  const [toastOpen, setToastOpen] = useState(false);

  const visible = uiSortRows(rows, sortKey, sortOrder).slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
  const openIds = rows.filter((row) => row.status === 'open').map((row) => row.id);

  function sort(key: string) {
    setSortOrder(key === sortKey && sortOrder === 'asc' ? 'desc' : 'asc');
    setSortKey(key);
    setPage(1);
  }

  function acknowledge() {
    setRows(rows.map((row) => (row.id === picked ? { ...row, status: 'acknowledged' } : row)));
    setAcknowledged(picked ?? '');
    setPicked(null);
    setOpen(false);
    setToastOpen(true);
  }

  return (
    <section>
      <SpTable
        caption="Incidents today"
        columns={COLUMNS}
        data={visible}
        rowKey="id"
        sortKey={sortKey}
        sortOrder={sortOrder}
        onSort={sort}
        striped
      />
      <SpPagination total={rows.length} pageSize={PAGE_SIZE} current={page} onChange={setPage} showTotal />
      <SpModal
        title="Acknowledge an incident"
        description="The on-call team stops being paged for it."
        trigger={<button type="button">Acknowledge an incident</button>}
        open={open}
        onOpenChange={setOpen}
        footer={
          <SpButton variant="primary" disabled={!picked} onClick={acknowledge}>
            Acknowledge
          </SpButton>
        }
      >
        <SpSelect
          label="Incident"
          placeholder="Choose an open incident"
          items={openIds}
          value={picked}
          onChange={setPicked}
        />
      </SpModal>
      <SpToaster>
        <SpToast
          kind="success"
          title="Incident acknowledged"
          description={`${acknowledged} no longer pages the on-call team.`}
          open={toastOpen}
          onOpenChange={setToastOpen}
        />
      </SpToaster>
    </section>
  );
}

El orden empieza por la hora de apertura, de la más reciente a la más antigua. Pulsar una columna la ordena de menor a mayor, y pulsarla otra vez, al revés; cada cambio vuelve a la primera página. setPage, setOpen, setPicked y setToastOpen se pasan tal cual, porque los manejadores reciben el valor.

El botón Acknowledge está deshabilitado hasta que se elige una incidencia. Al reconocerla, la fila pasa a acknowledged, el modal se cierra y la notificación se abre.

En src/index.css, una regla para el disparador:

button[aria-haspopup='dialog'] {
  padding: 6px 14px;
  border: 1px solid #3b3a36;
  border-radius: 2px;
  background: transparent;
  font: inherit;
  cursor: pointer;
}

Dibuja el disparador, que es un botón nativo y sale sin estilo. La tabla no necesita ninguna regla: desde la 0.10.0, las celdas de SpTable se alinean al inicio. Hasta la 0.9.2 las alineaba a la derecha la regla .sp-table td de styles.css, la de las tablas de datos de los gráficos (silverpoint#12).

La tabla de incidencias en Vue

<script setup lang="ts">
import { computed, ref } from 'vue';
import { uiSortRows } from '@silverpoint/core/ui';
import { SpButton } from '@silverpoint/vue/ui/button';
import { SpModal } from '@silverpoint/vue/ui/modal';
import { SpPagination } from '@silverpoint/vue/ui/pagination';
import { SpSelect } from '@silverpoint/vue/ui/select';
import { SpTable } from '@silverpoint/vue/ui/table';
import { SpToast, SpToaster } from '@silverpoint/vue/ui/toast';
import { COLUMNS, INCIDENTS, PAGE_SIZE } from '../incidents';

const rows = ref(INCIDENTS);
const sortKey = ref('opened');
const sortOrder = ref<'asc' | 'desc'>('desc');
const page = ref(1);
const open = ref(false);
const picked = ref<string | null>(null);
const acknowledged = ref('');
const toastOpen = ref(false);

const visible = computed(() =>
  uiSortRows(rows.value, sortKey.value, sortOrder.value).slice((page.value - 1) * PAGE_SIZE, page.value * PAGE_SIZE),
);
const openIds = computed(() => rows.value.filter((row) => row.status === 'open').map((row) => row.id));

function sort(key: string) {
  sortOrder.value = key === sortKey.value && sortOrder.value === 'asc' ? 'desc' : 'asc';
  sortKey.value = key;
  page.value = 1;
}

function acknowledge() {
  rows.value = rows.value.map((row) => (row.id === picked.value ? { ...row, status: 'acknowledged' } : row));
  acknowledged.value = picked.value ?? '';
  picked.value = null;
  open.value = false;
  toastOpen.value = true;
}
</script>

<template>
  <section>
    <SpTable
      caption="Incidents today"
      :columns="COLUMNS"
      :data="visible"
      row-key="id"
      :sort-key="sortKey"
      :sort-order="sortOrder"
      striped
      @sort="sort"
    />
    <SpPagination v-model:current="page" :total="rows.length" :page-size="PAGE_SIZE" show-total />
    <SpModal
      v-model:open="open"
      title="Acknowledge an incident"
      description="The on-call team stops being paged for it."
    >
      <template #trigger><button type="button">Acknowledge an incident</button></template>
      <SpSelect v-model="picked" label="Incident" placeholder="Choose an open incident" :items="openIds" />
      <template #footer>
        <SpButton variant="primary" :disabled="!picked" @click="acknowledge">Acknowledge</SpButton>
      </template>
    </SpModal>
    <SpToaster>
      <SpToast
        v-model:open="toastOpen"
        kind="success"
        title="Incident acknowledged"
        :description="`${acknowledged} no longer pages the on-call team.`"
      />
    </SpToaster>
  </section>
</template>

v-model:current, v-model:open y v-model hacen el trabajo de los pares de React. El encabezado emite sort, y el disparador y el pie van en las ranuras #trigger y #footer.

La tabla de incidencias en Angular

import { Component, computed, signal } from '@angular/core';
import { uiSortRows } from '@silverpoint/core/ui';
import { SpButton } from '@silverpoint/angular/ui/button';
import { SpCardFooter, SpModal, SpTrigger } from '@silverpoint/angular/ui/modal';
import { SpPagination } from '@silverpoint/angular/ui/pagination';
import { SpSelect } from '@silverpoint/angular/ui/select';
import { SpTable } from '@silverpoint/angular/ui/table';
import { SpToast, SpToaster } from '@silverpoint/angular/ui/toast';
import { COLUMNS, INCIDENTS, PAGE_SIZE } from './incidents';

@Component({
  selector: 'app-incidents-table',
  imports: [SpButton, SpCardFooter, SpModal, SpPagination, SpSelect, SpTable, SpToast, SpToaster, SpTrigger],
  template: `
    <section>
      <sp-table
        caption="Incidents today"
        [columns]="columns"
        [data]="visible()"
        rowKey="id"
        [sortKey]="sortKey()"
        [sortOrder]="sortOrder()"
        striped
        (sort)="sort($event)"
      />
      <sp-pagination [(current)]="page" [total]="rows().length" [pageSize]="pageSize" showTotal />
      <sp-modal
        [(open)]="open"
        title="Acknowledge an incident"
        description="The on-call team stops being paged for it."
      >
        <button type="button" spTrigger>Acknowledge an incident</button>
        <sp-select [(value)]="picked" label="Incident" placeholder="Choose an open incident" [items]="openIds()" />
        <ng-template spFooter>
          <button type="button" spButton variant="primary" [disabled]="!picked()" (click)="acknowledge()">
            Acknowledge
          </button>
        </ng-template>
      </sp-modal>
      <sp-toaster>
        <sp-toast
          [(open)]="toastOpen"
          kind="success"
          title="Incident acknowledged"
          [description]="acknowledged() + ' no longer pages the on-call team.'"
        />
      </sp-toaster>
    </section>
  `,
})
export class IncidentsTable {
  protected readonly columns = COLUMNS;
  protected readonly pageSize = PAGE_SIZE;
  protected readonly rows = signal(INCIDENTS);
  protected readonly sortKey = signal('opened');
  protected readonly sortOrder = signal<'asc' | 'desc'>('desc');
  protected readonly page = signal(1);
  protected readonly open = signal(false);
  protected readonly picked = signal<string | null>(null);
  protected readonly acknowledged = signal('');
  protected readonly toastOpen = signal(false);

  protected readonly visible = computed(() =>
    uiSortRows(this.rows(), this.sortKey(), this.sortOrder()).slice(
      (this.page() - 1) * PAGE_SIZE,
      this.page() * PAGE_SIZE,
    ),
  );
  protected readonly openIds = computed(() => this.rows().filter((row) => row.status === 'open').map((row) => row.id));

  protected sort(key: string) {
    this.sortOrder.set(key === this.sortKey() && this.sortOrder() === 'asc' ? 'desc' : 'asc');
    this.sortKey.set(key);
    this.page.set(1);
  }

  protected acknowledge() {
    const picked = this.picked();
    this.rows.update((rows) => rows.map((row) => (row.id === picked ? { ...row, status: 'acknowledged' } : row)));
    this.acknowledged.set(picked ?? '');
    this.picked.set(null);
    this.open.set(false);
    this.toastOpen.set(true);
  }
}

[(current)], [(open)] y [(value)] se unen a signals. El pie del modal es un <ng-template spFooter>, y su botón es la directiva spButton sobre un <button> nativo, como en el artículo 16. La regla de src/styles.css es la de React.

La tabla de incidencias en Reflex

En Reflex el orden, la página y las ventanas abiertas viven en el estado. visible es una variable calculada que ordena con sort_rows y corta la página:

class IncidentsState(rx.State):
    rows: list[dict] = INCIDENTS
    sort_key: str = "opened"
    sort_order: str = "desc"
    page: int = 1
    open: bool = False
    picked: str | None = None
    acknowledged: str = ""
    toast_open: bool = False

    @rx.var
    def visible(self) -> list[dict]:
        start = (self.page - 1) * PAGE_SIZE
        return sort_rows(self.rows, self.sort_key, self.sort_order)[
            start : start + PAGE_SIZE
        ]

    @rx.var
    def open_ids(self) -> list[str]:
        return [row["id"] for row in self.rows if row["status"] == "open"]

    @rx.event
    def sort(self, key: str):
        self.sort_order = (
            "desc" if key == self.sort_key and self.sort_order == "asc" else "asc"
        )
        self.sort_key = key
        self.page = 1

    @rx.event
    def set_page(self, page: int):
        self.page = page

    @rx.event
    def set_open(self, open: bool):
        self.open = open

    @rx.event
    def set_picked(self, key: str):
        self.picked = key

    @rx.event
    def set_toast_open(self, open: bool):
        self.toast_open = open

    @rx.event
    def acknowledge(self):
        self.rows = [
            {**row, "status": "acknowledged"} if row["id"] == self.picked else row
            for row in self.rows
        ]
        self.acknowledged = self.picked or ""
        self.picked = None
        self.open = False
        self.toast_open = True


def incidents_table() -> rx.Component:
    return rx.el.section(
        sp_table(
            COLUMNS,
            IncidentsState.visible,
            caption="Incidents today",
            row_key="id",
            sort_key=IncidentsState.sort_key,
            sort_order=IncidentsState.sort_order,
            on_sort=IncidentsState.sort,
            striped=True,
        ),
        sp_pagination(
            total=IncidentsState.rows.length(),
            page_size=PAGE_SIZE,
            current=IncidentsState.page,
            on_change=IncidentsState.set_page,
            show_total=True,
        ),
        sp_modal(
            sp_select(
                IncidentsState.open_ids,
                label="Incident",
                placeholder="Choose an open incident",
                value=IncidentsState.picked,
                on_change=IncidentsState.set_picked,
            ),
            trigger="Acknowledge an incident",
            title="Acknowledge an incident",
            description="The on-call team stops being paged for it.",
            footer=sp_button(
                "Acknowledge",
                variant="primary",
                disabled=IncidentsState.picked.is_none(),
                on_click=IncidentsState.acknowledge,
            ),
            open=IncidentsState.open,
            on_open_change=IncidentsState.set_open,
        ),
        sp_toaster(
            sp_toast(
                "Incident acknowledged",
                IncidentsState.acknowledged + " no longer pages the on-call team.",
                kind="success",
                open=IncidentsState.toast_open,
                on_open_change=IncidentsState.set_toast_open,
            ),
        ),
        style={
            "display": "grid",
            "gap": "16px",
            "justify_items": "start",
            "max_width": "720px",
        },
    )


def index() -> rx.Component:
    return rx.el.main(incidents_table(), style={"padding": "32px"})


app = rx.App(
    style={
        "background": "#f4f1ea",
        ".sp-table": {"justify_self": "stretch"},
    }
)
app.add_page(index)

Las filas se definen como tuplas y se convierten en diccionarios con FIELDS. sort_rows ordena igual que uiSortRows, así que la tabla se ve igual que en los otros tres frameworks.

El disparador es un texto, trigger="Acknowledge an incident", que se convierte en un botón dibujado con sp_trigger. Por eso aquí no hace falta la regla del botón de los otros tres. Un rx.el.button también sirve.

Hasta reflex-silverpoint-react 0.9.1, el texto fallaba cuando la ventana se controla desde el estado, como aquí con open y on_open_change: la página se rompía con SilverpointTrigger is not defined. Reflex compila el modal en un módulo aparte, que no recibía la definición del disparador. La 0.10.0 lo corrigió (reflex-silverpoint-react#44).

El teclado

  • Los encabezados ordenables son botones: se alcanzan con Tab y se pulsan con Enter o con la barra espaciadora.
  • Al abrir el modal, el foco entra en él, en el botón de cerrar, y no sale con Tab mientras está abierto.
  • Escape cierra el modal y el foco vuelve al disparador. En la prueba, en los cuatro frameworks, el foco volvió a Acknowledge an incident.
  • SpSelect sigue el patrón de combobox de solo selección de la APG: se abre con la flecha abajo o la barra espaciadora, se recorre con las flechas y se elige con Enter. Con la lista abierta, Escape cierra la lista y deja el modal abierto.

Los componentes compuestos

ComponenteMuestra
SpDescriptionsPares de etiqueta y valor, en columns columnas (3 por defecto)
SpCollapsePaneles que se abren y se cierran (SpCollapseItem); con accordion, uno a la vez
SpEmptyEl estado vacío de una lista o de una tabla
SpResultEl resultado de una acción: éxito, error, información o advertencia
SpBreadcrumbLas páginas hasta la actual
SpAvatarUna foto o unas iniciales; SpAvatarGroup apila varias
SpTimelineListSucesos en orden, cada uno hecho, actual, pendiente o con error

Con ellos se completa el detalle de una incidencia: SpDescriptions para sus campos, SpTimelineList para lo que pasó y SpEmpty cuando no hay ninguna abierta.

Problemas comunes

  • La tabla no se ordena al pulsar el encabezado. Es lo esperado: ordena tú en onSort y pásale sortKey y sortOrder.
  • Las celdas salen alineadas a la derecha. Tienes una versión anterior a la 0.10.0 (silverpoint#12). Actualiza los paquetes. Si pasa solo en la compilación de producción de una aplicación de Reflex con varias páginas, mira el artículo 26.
  • En Reflex, SilverpointTrigger is not defined. Tienes reflex-silverpoint-react anterior a la 0.10.0, la ventana se controla desde el estado y su disparador es un texto o un sp_trigger. Actualiza el paquete.
  • El rótulo del select no se ve. label es el nombre accesible y no se dibuja, como en SpTextarea.

Lo que viene

El panel ya tiene sus tablas y sus ventanas. El artículo 18 vuelve a los gráficos: exportar uno a SVG para usarlo fuera de la aplicación.

La guía de componentes de la documentación tiene la referencia de cada uno.