Webapp Builder

Sidemantic Webapp Builder

Build webapps around a validated Sidemantic semantic layer. Use the canonical built UI distribution, then wire runtime-specific data adapters to its documented props or mount functions.

In command examples, set SIDEMANTIC_PLUGIN_ROOT to the installed sidemantic plugin directory.

Component-First Pattern

Treat assets/ui-dist/ as the generated distribution of the sole component source in webapp/src. Never regenerate or fork component markup in a target project.

Copy React + Tailwind components for product apps:

uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \
  --kind react-tailwind \
  --target src/components/sidemantic

Copy the static component files for plain HTML demos or generated scaffolds:

uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \
  --kind static \
  --target public/sidemantic-components

Use --list to inspect the distribution. Existing target files are never overwritten unless --force is passed.

Available React primitives:

Analytics surfaces:

• DashboardShell: dense analytics page frame with status and toolbar slots.
• MetricCard: metric label, value, inline delta with comparison caption, loading, selected state.
• Leaderboard: ranked dimension rows with bars, selection, and stable data attributes.
• FilterPill: active filter display and removal.
• QueryDebugPanel (+ tokenizeSql): generated SQL/debug surface.
• DataPreviewTable: stable sample row preview.
• DataTable (+ columnTotal, paginateRows): sortable, paginated result table with optional client search, totals footer, and sticky header.
• LoadingState, EmptyState, ErrorState, StatusDot, ErrorBoundary: status surfaces.

Charts (hand-rolled SVG, theme-token driven, shared ChartTooltip/useChartTooltip):

• TimeSeriesChart: full-size metric series with crosshair, comparison overlay, brush-to-zoom.
• LineChart, Sparkline: compact trend lines.
• ColumnChart: categorical bars with a zero baseline.
• BarLineCombo: dual-axis bars + independently scaled line.
• StackedAreaChart: composition over time using the categorical --viz-N palette.
• DonutChart (+ donutSegments): part-of-whole with center total and legend.
• HistogramChart (+ binValues): distribution of one numeric field.
• ScatterChart: numeric x/y correlation, optional multi-series coloring.
• HeatmapChart: category-by-category intensity grid.
• WaterfallChart (+ waterfallSteps): contribution bridge with running totals.
• NetworkChart (+ layoutNetwork): deterministic force-directed graph.

Inputs and controls (dependency-free, accessible):

• Button, Select, Switch, Tabs: base controls in the data-tool idiom.
• Combobox (+ filterOptions): searchable listbox; single-select, or multiple with removable chips. Use Combobox for multi-select or long lists where typeahead beats scanning; Select for a short static single choice.
• DatePicker (+ monthGrid): single or range calendar, inline or popover, ISO string values.
• DateRangeControl: preset + custom date range with comparison-mode picker.
• GrainSelect, TimezoneSelect, ViewSwitcher: dashboard toolbar controls.
• Tooltip: hover tooltip for arbitrary triggers (header hints, truncated labels), on the same surface as chart tooltips.

Standard conventions shared by the primitives:

• Data passing: feed query-result rows straight into charts through the row adapters — rowsToCategories, rowsToBarLine, rowsToPoints, rowsToSeries (long-to-wide pivot), rowsToCells, rowsToTimeSeries — instead of hand-reshaping per call site. parseTemporal normalizes ISO strings, epoch seconds/milliseconds, and Date values.
• Tooltips: charts compose TooltipRows (heading + aligned label/value rows + series swatches) inside ChartTooltip, so every hover reads the same. Custom charts should do the same rather than inventing new tooltip markup.
• Palette: vizColor(index) / VIZ_COLOR_COUNT cycle the theme's --viz-1..--viz-6 categorical colors; override them (and all other tokens) via applyThemeTokens.

State primitives are conditional UI branches. Do not render loading, empty, and error examples as permanent app content unless the user explicitly asks for a component gallery.

Available static mount helpers in sidemantic-ui-static.js:

• Data adapters: aliasForSemanticRef, toComponentResult, toComponentQuery, filterZeroMetricRows.
• Formatting: labelize, formatValue, metricConfigFor, metricValueFormat, formatDateLike, seriesRangeLabel.
• Renderers: renderMetricCards, renderMetricSummaryCards, renderLeaderboard, renderDimensionLeaderboardCards, renderFilterPills, renderSparkline, renderColumnChart, renderHighlightedQueryDebug, renderDataPreview, renderValidationState, renderState.
• UI helpers: renderSelectOptions, setControlsDisabled, syncScrollPosition.
• Filter state helpers: normalizeFilterValue, toggleFilterValue, removeFilterValue, removeFilterDimension.

Use those static helpers before writing one-off DOM wiring. They are intentionally generic: they work for metric explorers, focused dashboards, debug tools, and browser-only demos as long as the app passes semantic query metadata plus row results into them. Runtime adapters for Python APIs, Pyodide, Rust WASM, DuckDB-WASM, or product backends should stay outside the copied component files.

Core Workflow

1. Load-check the semantic layer before building UI. Use info and the inspector in noninteractive agent work. Use validate only when the current CLI exits cleanly in your environment:

uv run sidemantic info path/to/models
uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models \
  --db path/to/data.duckdb \
  --require-execute

2. Generate an app inventory:

uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models \
  --db path/to/data.duckdb \
  --require-execute \
  --output /tmp/sidemantic-app-spec.json

Use --leaderboard-dimension field_name when domain judgment says one dimension should drive the first leaderboard. Without it, the inspector prefers common categorical dimensions over identifiers and booleans.

Keep the inspection inventory outside public or committed directories: it contains internal SQL, model metadata, and sampled data. Connection strings and raw database errors are omitted. Only the scaffold's allowlisted selected dashboard data belongs in the published app; review that dataset before publishing. The static scaffold does not publish generated SQL or unrelated models and samples.

3. Copy component source into the project before building UI:

uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/copy_components.py \
  --kind react-tailwind \
  --target src/components/sidemantic

Adapt imports, class names, and styling conventions after copying. Preserve the data contract conventions: data-metric, data-dimension, data-value, and data-testid hooks for metric totals, dimension leaderboards, and query debug surfaces.

For a minimal static app scaffold from the executed spec:

uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/scaffold_static_app.py \
  /tmp/sidemantic-app-spec.json \
  --output dist/sidemantic-dashboard \
  --title "Metrics Dashboard"

The scaffold copies readable source from assets/templates/static-dashboard/ and the static component files. If you need a richer generated app, edit those copied source files in the target project; do not bury application JavaScript in Python strings or generated HTML fragments.

4. Choose the app shape:

• Existing app: follow its framework, routing, styling, and data-fetch patterns.
• New product webapp: use Bun, React Router v7 as framework, Tailwind v3, and Hono only when a TypeScript API/proxy is needed.
• Python-backed analytics app: use sidemantic.api_server.create_app() or start_api_server() when a FastAPI API is acceptable.
• Browser-only demo: use the sidemantic-wasm npm package (Sidemantic Rust WASM) + DuckDB-WASM, or Pyodide + DuckDB-WASM, only for static demos or docs pages that must run without a backend.
• Notebook or Python embedded view: use sidemantic.widget.MetricsExplorer instead of rebuilding the widget.
• MCP app surface: use sidemantic server mcp --apps --http --port 4100 and existing chart resources when the target is an MCP Apps-compatible host.

5. Implement a narrow query contract. Prefer structured query payloads over ad hoc SQL strings:

{
  "metrics": ["orders.revenue"],
  "dimensions": ["orders.order_date__day"],
  "filters": ["orders.status = 'completed'"],
  "order_by": ["orders.order_date__day"],
  "limit": 500
}

6. Build the UI around the copied components and query contract:

• Metric cards: aggregate value, compact sparkline, selected state.
• Dimension leaderboards: top values for the selected metric, horizontal bars, click-to-filter.
• Filter pills: active dimension filters plus brush/date-range filters, removable.
• Time controls: date range, grain select, brushable sparklines when a time dimension exists.
• Optional debug surfaces: generated SQL, raw rows preview, query timing. Use these in demos and internal tools, not as default product chrome.

If a control is visible, it must change the app state or data. Do not satisfy interaction requirements by only changing a status label. Removing a filter must recompute metric cards, leaderboards, charts, and preview rows. Clicking a leaderboard row must add or toggle a filter. Selecting a metric must change the leaderboard ranking metric.

7. Verify end to end:

uv run sidemantic info path/to/models
uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/inspect_layer.py path/to/models --db path/to/data.duckdb --require-execute
uv run sidemantic query "SELECT metric_name FROM model_name LIMIT 5" --models path/to/models --db path/to/data.duckdb
uv run ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_app.py dist/sidemantic-dashboard
bunx --bun -p playwright node ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs --url http://127.0.0.1:5174/
bun run build

For frontend changes, run the app on a 4xxx-5xxx port and verify with browser screenshots at desktop and mobile widths. If browser tooling is unavailable, run verify_static_app.py or another deterministic DOM/data check and state that real browser visual verification was not run.

For interactive dashboards, verify behavior, not just render counts:

• Remove a filter pill and confirm at least one metric value changes.
• Click a leaderboard row and confirm metrics, chart bars, selected row state, and preview rows reflect that value.
• Click the same active leaderboard row or remove its pill and confirm the broader result set returns.
• Select a different metric card and confirm the leaderboard ranking metric changes.
• Confirm visible sparklines and column charts stay clipped inside their cards at desktop and mobile widths.

For static dashboards that use the bundled component contracts, use the smoke-test script after starting a local server:

bunx --bun -p playwright playwright install chromium  # first run only, if Playwright reports a missing browser
bunx --bun -p playwright node ${SIDEMANTIC_PLUGIN_ROOT}/skills/webapp-builder/scripts/verify_static_interactions.mjs \
  --url http://127.0.0.1:4519/

The script clicks filter pills, leaderboard rows, metric cards, and reset controls, and fails if visible data does not change.

Query Patterns

Use the generated app spec first. For deeper implementation details, read references/webapp-patterns.md.

Default query set:

• Time series: selected metrics grouped by model.time_dimension__grain, ordered by time, capped around 500 points.
• Totals: selected metrics with no dimensions.
• Dimension leaderboard: selected metric grouped by one dimension, ordered descending, capped to 5-10 rows.
• Preview table: ungrouped/raw rows only when the app needs a data inspector.

Use inspect_layer.py --require-execute when a database is available. This adds result.columns, result.sample_rows, and sample_row_count to each compiled query and exits nonzero if execution is missing or fails. Use plain --execute only when a warning is acceptable.

For crossfilter leaderboards, exclude the dimension's own filter while querying that same dimension. If device_os = iOS is active, the device OS card should still show peer OS values while other cards show values within iOS.

Use explicit aliases at API boundaries so UI column names stay stable. The inspector emits output_aliases and, with --execute, actual result columns. Do not make display components depend on database-specific column casing or quoted identifiers.

Run DuckDB validation serially against a file database. Do not run the inspector and sidemantic query concurrently against the same .duckdb path; DuckDB file locks can make valid workflows fail.

API Modes

When the app can call Python directly, prefer the existing HTTP API:

• GET /health
• GET /models
• GET /graph
• POST /compile
• POST /query?format=json
• POST /query?format=arrow
• POST /sql

When building a TypeScript frontend with a separate backend, keep Sidemantic execution in Python unless the project already has a stable Python service. A Hono server can proxy to the Sidemantic API, add auth/session context, and normalize responses.

Never concatenate user-entered filter values into SQL in the frontend. Pass structured filter values to a server-side query builder or quote them with the same rules as Sidemantic/widget code.

The CLI sidemantic query auto-adds default time dimensions for metrics when a model has default_time_dimension. For exact app query shapes like true totals, prefer the inspector-generated SQL/result samples or the Python/API structured query path using skip_default_time_dimensions=True internally.