Arc Rider Docs · Markdown

Introduction

¿Qué es un widget?

¿Qué es un widget en React?

Un arcWidget es un componente configurable para una aplicación de negocio: por ejemplo una tabla, un calendario o un tablero Kanban. Pasas la representación como data y conectas los eventos con tu aplicación mediante callback props.

Un ejemplo completo

import {
  ArcWidgetBadge,
  ArcWidgetIcon,
  ArcWidgetKpiBar,
  ArcWidgetProgressBar,
  ArcWidgetTable,
  type ArcWidgetTableData,
  type ArcWidgetTableRow,
} from '@arcrider/arcwidgets-react';
import { useMemo, useState, type CSSProperties } from 'react';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';

type Theme = 'light' | 'dark'; type DbStatus = 'Active' | 'Idle' | 'Locked'; type DbRow = { id: string; schema: string; name: string; type: 'Table' | 'View'; rows: number; size: string; status: DbStatus; };

const STATUS_LOOK: Record< DbStatus, { fontColor: string; backgroundColor: string } > = { Active: { fontColor: '#15803D', backgroundColor: '#DCFCE7' }, Idle: { fontColor: '#52525B', backgroundColor: '#F4F4F5' }, Locked: { fontColor: '#991B1B', backgroundColor: '#FFE4E6' }, }; const STATUS_LOOK_DARK: Record< DbStatus, { fontColor: string; backgroundColor: string } > = { Active: { fontColor: '#86EFAC', backgroundColor: '#14532D' }, Idle: { fontColor: '#A1A1AA', backgroundColor: '#27272A' }, Locked: { fontColor: '#FDA4AF', backgroundColor: '#4C0519' }, };

const SCHEMA_THEME = { public: { light: { bg: '#E8F1FF', ink: '#2563EB', track: '#BFDBFE' }, dark: { bg: '#152033', ink: '#93C5FD', track: '#1E3A5F' }, }, auth: { light: { bg: '#FFF4E8', ink: '#C2410C', track: '#FED7AA' }, dark: { bg: '#24180E', ink: '#FDBA74', track: '#4A2E12' }, }, storage: { light: { bg: '#E8F8EF', ink: '#15803D', track: '#BBF7D0' }, dark: { bg: '#122018', ink: '#86EFAC', track: '#14532D' }, }, } as const; type SchemaName = keyof typeof SCHEMA_THEME; const SCHEMAS = Object.keys(SCHEMA_THEME) as SchemaName[]; const STATUSES: DbStatus[] = ['Active', 'Idle', 'Locked'];

const demoRows: DbRow[] = [ { id: 'tbl-users', schema: 'public', name: 'users', type: 'Table', rows: 1204, size: '4.2 MB', status: 'Active', }, { id: 'tbl-orders', schema: 'public', name: 'orders', type: 'Table', rows: 43012, size: '128.0 MB', status: 'Active', }, { id: 'tbl-products', schema: 'public', name: 'products', type: 'Table', rows: 890, size: '1.1 MB', status: 'Idle', }, { id: 'vw-revenue', schema: 'public', name: 'monthly_revenue', type: 'View', rows: 0, size: '0.0 MB', status: 'Idle', }, { id: 'tbl-sessions', schema: 'auth', name: 'sessions', type: 'Table', rows: 52, size: '0.4 MB', status: 'Active', }, { id: 'tbl-audit', schema: 'auth', name: 'audit_log', type: 'Table', rows: 12301, size: '45.0 MB', status: 'Locked', }, { id: 'tbl-identities', schema: 'auth', name: 'identities', type: 'Table', rows: 104, size: '0.8 MB', status: 'Active', }, { id: 'tbl-objects', schema: 'storage', name: 'objects', type: 'Table', rows: 4019, size: '12.5 MB', status: 'Idle', }, { id: 'tbl-buckets', schema: 'storage', name: 'buckets', type: 'Table', rows: 4, size: '0.1 MB', status: 'Idle', }, ];

const busyRows: DbRow[] = [ ...demoRows, ...Array.from({ length: 24 }, (_, index): DbRow => ({ id: busy-${index + 1}, schema: SCHEMAS[index % SCHEMAS.length], name: extra_${String(index + 1).padStart(2, '0')}, type: index % 5 === 0 ? 'View' : 'Table', rows: 20 + ((index * 37) % 9000), size: ${(0.1 + (index % 9) * 0.4).toFixed(1)} MB, status: STATUSES[index % STATUSES.length], })), ];

const rows = pack === 'empty' ? [] : pack === 'busy' ? busyRows : demoRows; const connections = pack === 'empty' ? 0 : pack === 'busy' ? 12 : 4;

const statusLabel: Record<DbStatus, string> = { Active: 'Active', Idle: 'Idle', Locked: 'Locked', }; const typeLabel = { Table: 'Table', View: 'View', };

function parseMb(size: string): number { const value = Number.parseFloat(size); if (Number.isNaN(value)) return 0; return size.includes('GB') ? value * 1024 : value; }

function formatMb(mb: number): string { if (mb >= 1024) return ${(mb / 1024).toFixed(1)} GB; return ${mb.toFixed(1)} MB; }

function groupBySchema(list: DbRow[]) { const groups = new Map<string, DbRow[]>(); for (const row of list) { const next = groups.get(row.schema) ?? []; next.push(row); groups.set(row.schema, next); } return [...groups.entries()]; }

function StatusBadge({ status, theme }: { status: DbStatus; theme: Theme }) { const look = (theme === 'dark' ? STATUS_LOOK_DARK : STATUS_LOOK)[status]; return ( <ArcWidgetBadge data={{ value: statusLabel[status], fontColor: look.fontColor, backgroundColor: look.backgroundColor, borderColor: look.backgroundColor, borderRadius: '6px', fontSize: '10px', fontWeight: '600', paddingX: '8px', paddingY: '3px', }} /> ); }

function leafRow( row: DbRow, selectedIds: Set<string>, toggleSelection: (id: string) => void, theme: Theme, accent: string, ): ArcWidgetTableRow { return { id: row.id, clickable: true, rowHeight: '36px', rowPaddingY: '4px', rowColor: selectedIds.has(row.id) ? theme === 'dark' ? '#27272A' : '#F4F4F5' : '', columns: [ { width: 'fraction', clickable: true, value: ( <div className="flex-row"> <input className="table-check" type="checkbox" checked={selectedIds.has(row.id)} onChange={() => toggleSelection(row.id)} onClick={(event) => event.stopPropagation()} style={{ '--check-color': accent } as CSSProperties} /> <span className="cell-name cell-name--child">{row.name}</span> </div> ), sort: { value: row.name }, }, { value: ( <span className="cell-name cell-name--child"> {typeLabel[row.type]} </span> ), width: '100px', }, { value: <StatusBadge status={row.status} theme={theme} />, width: '100px', }, { value: ( <span className="cell-num cell-num--child"> {row.rows.toLocaleString('en-US')} </span> ), width: '80px', alignX: 'right', sort: { value: row.rows }, }, { value: <span className="cell-num cell-num--child">{row.size}</span>, width: '110px', alignX: 'right', }, ], }; }

function buildTableData( list: DbRow[], selectedIds: Set<string>, toggleSelection: (id: string) => void, theme: Theme, ): ArcWidgetTableData { const dark = theme === 'dark'; const line = dark ? '#2A3A4E' : '#E4E4E7'; return { height: '360px', collapsible: { enabled: true, expandColumn: 0, indentColumn: 0, indentSize: '32px', } as ArcWidgetTableData['collapsible'] & { indentSize: string }, rowHoverAction: { hoverActive: true, backgroundColor: dark ? '#16202A' : '#FAFAFA', }, scrollBar: { showScrollBar: true, height: '6px', backgroundColor: dark ? '#1A2430' : '#F4F4F5', handle: { backgroundColor: dark ? '#6B8499' : '#A1A1AA', borderRadius: '6px', }, }, header: { showHeader: true, height: '32px', backgroundColor: dark ? '#121820' : '#FAFAFA', fontColor: dark ? '#9AADC0' : '#71717A', fontSize: '11px', columns: [ { title: 'Name', width: 'fraction' }, { title: 'Type', width: '100px' }, { title: 'Status', width: '100px' }, { title: 'Rows', width: '80px', alignX: 'right' }, { title: 'Size', width: '110px', alignX: 'right' }, ], }, styles: { backgroundColor: dark ? '#0B1016' : '#FFFFFF', fontColor: dark ? '#9AADC0' : '#52525B', borderRadius: '8px', borders: { color: line, width: '1px', outer: { color: line, width: '1px' }, columns: false, rows: { color: line, width: '1px' }, }, }, table: groupBySchema(list).map(([schema, children]) => { const look = SCHEMA_THEME[schema as SchemaName]?.[theme] ?? { bg: dark ? '#16202A' : '#F4F4F5', ink: dark ? '#E4E4E7' : '#3F3F46', track: dark ? '#1A2430' : '#E4E4E7', }; const totalRows = children.reduce((sum, child) => sum + child.rows, 0); const totalMb = children.reduce( (sum, child) => sum + parseMb(child.size), 0, ); const active = children.filter( (child) => child.status === 'Active', ).length; return { id: schema-${schema}, clickable: true, rowHeight: '36px', rowPaddingY: '4px', rowColor: look.bg, columns: [ { width: 'fraction', fontColor: look.ink, value: ( <span className="cell-name cell-name--parent" style={{ color: look.ink }} > {schema} </span> ), sort: { value: schema }, }, { fontColor: look.ink, value: ( <span className="cell-name cell-name--parent-meta" style={{ color: look.ink }} > {${children.length} objects} </span> ), width: '100px', }, { width: '100px', value: ( <ArcWidgetProgressBar data={{ valueProgress: active, valueTotal: children.length, width: '72px', height: '6px', progressColor: look.ink, backgroundColor: look.track, borderRadius: '4px', }} /> ), }, { fontColor: look.ink, value: ( <span className="cell-num" style={{ color: look.ink }}> {totalRows.toLocaleString('en-US')} </span> ), width: '80px', alignX: 'right', sort: { value: totalRows }, }, { width: '110px', alignX: 'right', fontColor: look.ink, value: ( <span className="size-sum"> <ArcWidgetIcon data={{ name: 'sigma', iconSet: 'phosphor', style: 'regular', iconSize: '12px', color: look.ink, }} /> <span className="cell-num" style={{ color: look.ink }}> {formatMb(totalMb)} </span> </span> ), }, ], items: children.map((child) => leafRow(child, selectedIds, toggleSelection, theme, look.ink), ), }; }), footer: { showFooter: true, showActionButton: false, height: '58px', styles: { height: '58px', minHeight: '58px' }, backgroundColor: dark ? '#121820' : '#FAFAFA', leftSideContent: ( <span className="table-footer__count"> {selectedIds.size === 0 ? 'No objects selected' : ${selectedIds.size} object${selectedIds.size === 1 ? '' : 's'} selected} </span> ), rightSideContent: ( <div className="table-footer__actions"> <button type="button" className="btn btn--ghost" disabled={selectedIds.size === 0} > {'Drop Tables'} </button> <button type="button" className="btn btn--primary" disabled={selectedIds.size === 0} > {'Export'} {selectedIds.size > 0 ? (${selectedIds.size}) : ''} </button> </div> ), }, emptyTable: { title: 'No data', value: 'The query returned 0 rows.', }, }; }

export default function Example() { const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set()); const [theme, setTheme] = useState<Theme>('dark'); const toggleSelection = (id: string) => { setSelectedIds((prev) => { const next = new Set(prev); if (next.has(id)) next.delete(id); else next.add(id); return next; }); }; const tableData = useMemo( () => buildTableData(rows, selectedIds, toggleSelection, theme), [selectedIds, theme], ); const totalRows = rows.reduce((sum, row) => sum + row.rows, 0); const totalMb = rows.reduce((sum, row) => sum + parseMb(row.size), 0); const dark = theme === 'dark'; const kpiValue = dark ? '#F4F4F5' : '#18181B'; const kpiBorder = dark ? '#2A3A4E' : '#E4E4E7'; const kpiBg = dark ? '#121820' : '#FAFAFA'; const kpiCard = ( card: number, title: string, value: string, color = kpiValue, ) => ({ card, title, value, settings: { fontSizeLabel: '10px', fontSizeValue: '18px', colorValue: color, borderColor: kpiBorder, backgroundColor: kpiBg, }, });

return ( &lt;div className=&quot;explorer&quot; data-theme={theme}&gt; &lt;style&gt;{ .explorer { --ex-fg:#18181b; --ex-muted:#71717a; --ex-bg:#ffffff; --ex-elev:#fafafa; --ex-line:#e4e4e7; --ex-fill:#f4f4f5; --ex-accent:#18181b; --ex-on-accent:#ffffff; --ex-font:ui-sans-serif,system-ui,-apple-system,&quot;Segoe UI&quot;,sans-serif; --ex-mono:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,&quot;Liberation Mono&quot;,&quot;Courier New&quot;,monospace; display:grid; gap:12px; background:var(--ex-bg); color:var(--ex-fg); font-family:var(--ex-font); font-size:12px; line-height:1.4; } .explorer[data-theme=dark] { --ex-fg:#f4f4f5; --ex-muted:#9aadc0; --ex-bg:#0b1016; --ex-elev:#121820; --ex-line:#2a3a4e; --ex-fill:#1a2430; --ex-accent:#f4f4f5; --ex-on-accent:#0b1016; } .explorer * { box-sizing:border-box; } .explorer__toolbar { display:flex; justify-content:flex-end; } .explorer__kpis { min-height:72px; } .explorer__stage { min-width:0; height:360px; } .theme-switch { display:inline-flex; align-items:center; padding:3px; border:1px solid var(--ex-line); border-radius:999px; background:var(--ex-elev); gap:2px; } .theme-switch button { appearance:none; display:inline-flex; align-items:center; gap:5px; border:0; background:transparent; color:var(--ex-muted); border-radius:999px; padding:4px 10px; font:inherit; font-size:11px; font-weight:500; cursor:pointer; margin:0; } .theme-switch button.is-active { background:var(--ex-accent); color:var(--ex-on-accent); } .table-footer__count { font-size:11px; color:var(--ex-muted); } .table-footer__actions { display:flex; align-items:center; gap:8px; } .flex-row { display:flex; align-items:center; gap:8px; } .cell-name { font-family:var(--ex-font); font-size:12px; font-weight:400; color:var(--ex-fg); } .cell-name--parent { font-weight:700; } .cell-name--parent-meta { font-weight:500; } .cell-name--child { color:var(--ex-muted); } .cell-num { display:block; width:100%; text-align:right; font-family:var(--ex-mono); font-size:11px; font-weight:400; font-variant-numeric:tabular-nums; color:var(--ex-fg); } .cell-num--child { color:var(--ex-muted); } .size-sum { display:flex; align-items:center; justify-content:flex-end; gap:5px; width:100%; } .table-check { appearance:none; width:15px; height:15px; margin:0; flex:0 0 15px; border:1.5px solid var(--check-color,#71717a); border-radius:4px; background:transparent; cursor:pointer; } .table-check:checked { background:var(--check-color,#71717a); } .table-check:checked::after { content:&quot;&quot;; display:block; width:4px; height:7px; margin:1px auto 0; border:solid var(--ex-bg); border-width:0 1.5px 1.5px 0; transform:rotate(45deg); } .btn { appearance:none; border:1px solid var(--ex-line); background:transparent; color:inherit; font:inherit; border-radius:6px; padding:5px 12px; font-size:12px; cursor:pointer; font-weight:500; margin:0; } .btn--primary { background:var(--ex-accent); color:var(--ex-on-accent); border-color:var(--ex-accent); } .btn--ghost { color:var(--ex-fg); } .btn:disabled { opacity:.5; cursor:not-allowed; } }&lt;/style&gt; &lt;div className=&quot;explorer__toolbar&quot;&gt; &lt;div className=&quot;theme-switch&quot; role=&quot;group&quot; aria-label={'Color theme'}&gt; &lt;button type=&quot;button&quot; className={theme === 'light' ? 'is-active' : ''} aria-pressed={theme === 'light'} onClick={() =&gt; setTheme('light')} &gt; &lt;ArcWidgetIcon data={{ name: 'sun', iconSet: 'phosphor', style: theme === 'light' ? 'fill' : 'regular', iconSize: '14px', color: theme === 'light' ? '#18181B' : '#A1A1AA', }} /&gt; &lt;span&gt;{'Light'}&lt;/span&gt; &lt;/button&gt; &lt;button type=&quot;button&quot; className={theme === 'dark' ? 'is-active' : ''} aria-pressed={theme === 'dark'} onClick={() =&gt; setTheme('dark')} &gt; &lt;ArcWidgetIcon data={{ name: 'moon', iconSet: 'phosphor', style: theme === 'dark' ? 'fill' : 'regular', iconSize: '14px', color: theme === 'dark' ? '#F4F4F5' : '#71717A', }} /&gt; &lt;span&gt;{'Dark'}&lt;/span&gt; &lt;/button&gt; &lt;/div&gt; &lt;/div&gt; &lt;div className=&quot;explorer__kpis&quot;&gt; &lt;ArcWidgetKpiBar data={{ settings: { height: '72px', fontSizeLabel: '10px', fontSizeValue: '18px', colorLabel: dark ? '#9AADC0' : '#71717A', borderColor: kpiBorder, backgroundColor: kpiBg, }, cards: [ kpiCard(1, 'Total Rows', totalRows.toLocaleString('en-US')), kpiCard(2, 'Total Size', formatMb(totalMb)), kpiCard( 3, 'Connections', String(connections), dark ? '#86EFAC' : '#15803D', ), ], }} /&gt; &lt;/div&gt; &lt;div className=&quot;explorer__stage&quot;&gt; &lt;ArcWidgetTable key={intro-explorer-${theme}} id=&quot;intro-explorer&quot; data={tableData} /&gt; &lt;/div&gt; &lt;/div&gt; ); }</code></pre>

Las métricas y la tabla salen de los mismos datos de React. El tema y la selección quedan en el state local. Para el acceso a datos, el almacenamiento y la navegación usas tu propia API y los componentes de tu aplicación.

Las piezas

  • data contiene la configuración específica del widget.
  • id identifica opcionalmente la instancia.
  • Los callback props como onCellClick informan las interacciones.
  • Los slots de contenido permiten elementos de React propios y otros widgets.

<a href="/docs/react/intro/setup-react">Configurar React</a> · <a href="/docs/react/intro/react-components">Todos los componentes</a> · <a href="/docs/react/patterns/nested-widget-descriptors">Combinar componentes</a>.