superplane-dashboard-and-widgets

SuperPlane dashboard and widgets

Use this skill when working on per-canvas dashboards: the workflow v2 overlay, typed panels, widget renderers, YAML import/export, or backend validation.

Canonical reference: docs/prd/dashboard-and-widgets.md — read it for full schemas, examples, and maintenance notes. This skill is the operational subset for agents.

---

Product rules (do not break)

• One dashboard per canvas (not templates). Stored in canvas_dashboards as JSON panels + layout.
• Dashboard mode hides the graph; 12-column react-grid-layout (DashboardView).
• Edit (panels, layout, YAML import): canvases:update, not template, canvas not deleted.
• Run (node panel Run, table row actions): same as edit — InvokeNodeTriggerHook; UI uses canRunNodes.
• YAML import is replace-all (max 50 panels, 1 MiB payload).
• User-facing name: SuperPlane (capital P).
• Row actions are kind: trigger only — they fire trigger nodes; they do not call HTTP Request nodes directly.

---

Layer map

Invariant: panelTypes.ts validators, canvas_dashboard_yml.go, and widget types.ts must agree. Frontend fast-fail; backend authoritative on import.

Node references: always accept id or name via resolveDashboardNode in DashboardContext.tsx.

---

Panel types

New panels: templateForPanelType in panelTypes.ts. Draft states (e.g. empty memory namespace) should stay valid where possible.

---

Data sources (useWidgetData)

{ kind: "memory", namespace: string, fieldPath?: string }
{ kind: "executions", node?: string, limit?: number }
{ kind: "runs", limit?: number }

Execution rows get status, nodeName, durationMs. Status vocabulary: passed, failed, running, pending, cancelled, unknown.

---

Table panels (most complex)

Columns

Non-empty field; optional label, format (text, number, status, relative, link, trend, …), show, href. format: trend also accepts trendBetter (up/down, default up) and trendDisplay (percent/value/none, default percent); the cell compares against the row directly below in the filtered/sorted table (or the first already-loaded row still hidden by the progressive display window).

Filters

render.where[] — AND list; ops: eq, neq, contains, not_contains, gt, lt, exists, not_exists.

Row actions (trigger)

Required: kind: trigger, node (id or name). Optional: hook (default run), template, payload, confirm, show, variant, icon.

Runtime flow: WidgetTable → mergeTriggerPayload → onTriggerNode → useDashboardTriggerNode → InvokeNodeTriggerHook → invalidate events/runs/memory queries.

Legacy fields normalized in FE: target → node, triggerName → template.

Manual-run gate: only the built-in start and schedule triggers expose a user-invokable run hook. The UI filters on node.component against the hardcoded allowlist in web_src/src/pages/app/console/manualRunTriggers.ts — TablePanelForm hides non-manual triggers from the dropdown, WidgetTable hides their row actions, and NodesPanelCard/NodesPanelForm hide the Run affordance. Backend authorization stays in InvokeNodeTriggerHook; adding a new manual-run trigger requires a matching entry in the frontend allowlist.

Expressions

• {{ CEL }} — @marcbachmann/cel-js via widget/celExpr.ts; row env + now (Unix seconds). The adapter upfront-coerces safe-integer JS numbers (and, on retry, numeric strings) to BigInt for int arithmetic, and normalizes safe-integer BigInt results back to plain number on the way out.
• Legacy show — e.g. status == "running" (showExpression.ts, rowVisibility.ts).
• Prefer structured where for simple validated filters.

Lint: loose equality in legacy expressions is intentional (scalar normalization). Do not add eslint-disable for == in dashboard code; refactor instead.

Editor memory hints: MemoryDiscoveryPanel.tsx, useMemoryCatalog.ts (suggestions only; YAML still validated).

Markdown variables

• content.variables[] carries named live data refs; body uses {{ name.field }} (or {{ name.$["Node"].data.x }} for runs).
• Sources: { kind: "memory", namespace, orderBy?, direction?, matches?, mode?, limit? } (default mode: single first-row wins, orderBy: createdAt desc) or { kind: "run", select: latest | latest_passed | latest_failed }.
• mode: list resolves the memory variable to the full sorted array of matching rows (optionally capped by limit), unlocking CEL list macros (rows.map(r, ...).filter(...)) inside {{ }}; pair with the join(list, sep) builtin in celExpr.ts to flatten into Markdown / HTML.
• Resolution lives in useMarkdownVariables.ts (pickMemoryRows is the exported helper that branches on mode); interpolation in markdownInterpolation.ts (reuses celExpr.compileTemplate/evalTemplate). Validation: markdownVariables.ts (FE, including validateMarkdownContent) + validateMarkdownContent / validateHTMLContent in pkg/models/console_yml.go (BE).
• Run vars expose status, nodeName, payload, durationMs, and a $ map of node executions (same shape as the table widget).

HTML widget safety

• Render pipeline (HtmlBody.tsx): interpolate variables → DOMPurify allow-list → scope <style> blocks → dangerouslySetInnerHTML into div[data-console-html-root="<id>"].
• Sanitizer (htmlSanitize.ts) blocks <script> and all on* handlers, removes head-like and resource-fetching elements (link, meta, base, iframe, object, embed, audio, video, form, svg, math, …), allows <img src>/<img srcset> for http(s)/relative URLs (cross-origin image fetches are permitted by policy), strips poster/background/data/xlink:href, restricts href/src/srcset to http(s)/mailto:/tel:/fragments, and rewrites every <style> rule to scope selectors under the widget root while dropping @import, url(...), and unknown at-rules.
• Tailwind v4 classes must be in the curated @source inline(...) safelist in web_src/src/App.css to apply at runtime — extend it conservatively, never bypass it.

---

Chart and number

Chart render.type: bar, stacked-bar, line, area, donut. xField + series[]; omit series[].field to count rows per bucket.

Number aggregations: count, sum, avg, min, max, first, last — non-count requires field.

Scorecard shares the number aggregation vocabulary but is single-KPI only (no multi-KPI / composite memory). Comparison model:

• Change = current value vs the immediately previous value in the series. The series is derived from sparklineField when set, or the primary field as a fallback. Only first / last aggregations expose a natural "previous" (adjacent anchor via pickChangeAnchors); combining aggregations (sum / avg / min / max / count) hide the chip. Reuses computeTrend (widgetTrend.ts) for percent/absolute math.
• Target = literal number or {{ CEL }} (evaluated against the newest filtered row + now), used for optional showProgress and fallback status color.
• better: "up" | "down" controls the polarity for the value change, the sparkline, and the vs-target status.
• The form relabels the two directional aggregations as Latest / Earliest because all data sources are newest-first (first → Latest, last → Earliest). Persisted YAML still uses first / last.

Helpers live in widget/scorecardMath.ts (extractScorecardSeries, pickChangeAnchors, resolveScorecardTarget, computeScorecardProgress, computeScorecardChange, resolveScorecardStatus, formatScorecardChangeLabel). Rendering is in widget/WidgetScorecard.tsx; the sparkline itself comes from the shared widget/Sparkline.tsx (shared with WidgetNumber) with a className prop for status coloring.

---

YAML

apiVersion: v1
kind: Dashboard
metadata:
  canvasId: <uuid>   # export only; ignored on import
  name: <display>
spec:
  panels: [{ id, type, content }]
  layout: [{ i, x, y, w, h, minW?, minH? }]

• FE: dashboardYaml.ts — parse/serialize + validatePanelContent
• BE: DashboardFromYML / DashboardToYML in canvas_dashboard_yml.go
• Unknown fields rejected; missing panels/layout → empty lists

---

Agent workflows

Fix a dashboard bug

1. Reproduce in dashboard mode (not template); note panel type and dataSource.kind.
2. Trace: panel card → useWidgetData → widget renderer → (if trigger) useDashboardTriggerNode.
3. Check permissions in pkg/authorization/interceptor.go if RPC-related.
4. Add/update test under web_src/src/pages/workflowv2/dashboard/**/*.spec.ts.

Add or change panel content fields

1. widget/types.ts (if widget-facing)
2. panelTypes.ts — interface, templateForPanelType, validatePanelContent, normalization
3. canvas_dashboard_yml.go — mirror validation
4. Panel card + form component
5. YAML tests: dashboardYaml.spec.ts, canvas_dashboard_yml_test.go

Add a new panel type

1. PANEL_TYPES, PANEL_TYPE_META, validator, template
2. AllowedDashboardPanelTypes in Go
3. *PanelCard.tsx + DashboardView PanelCardRouter
4. Update docs/prd/dashboard-and-widgets.md

Add a data source kind

1. Extend types in widget/types.ts + panelTypes.ts
2. DataSourceForm.tsx editor
3. Branch in useWidgetData.ts
4. Backend YAML validator + tests

Configure memory table (user/agent task)

Use PRD example; namespace must match canvas memory keys. Row actions target trigger nodes only.

---

Verification

# Frontend unit tests (dashboard package)
cd web_src && npm run test:run -- src/pages/workflowv2/dashboard

# After UI edits (Docker dev env)
make format.js
make check.lint.ui
make check.build.ui

# After Go validation/API edits
make format.go
make lint
make check.build.app
go test ./pkg/models -run 'TestDashboard|TestValidateDashboardContent'
go test ./pkg/grpc/actions/canvases -run CanvasDashboard

---

Repo conventions

• No web_src/src/utils/* — use lib/ or hooks/.
• Dashboard has strict ESLint budget — refactor touched code; do not raise the budget.
• Split large components for Fast Refresh where the codebase already does.
• Never hand-write DB migrations; make db.migration.create NAME=<dash-name> if persistence changes.
• AGENTS.md: protobuf enum mapping, authorization on new RPCs.

---

Quick file index