hyperpbi

HyperPBI

HyperPBI is an AI-native analytics runtime and portable dashboard specification. Declarative HyperPBI 2.0 JSON is prepared by one validation and dataset pipeline, then rendered by the same Studio and runtime in either the Power BI custom visual or the Playground embedded in the unified Next.js website. HyperPBI renders only implemented components and safe behaviors; it is not a general-purpose HTML or JavaScript application platform.

Project: hyperpbi.com · Source: austinwin/hyperpbi

HyperPBI does not call an AI service. Edit Mode builds a prompt from the current Field Manifest and authoring settings; the user copies that prompt to an externally approved AI, then pastes one JSON response back into HyperPBI for extraction, validation, preview, and saving.

AI / Visual Editor / JSON / Templates
                  ↓
         HyperPBI 2.0 Specification
                  ↓
        Shared HyperPBI Runtime
                  ↓
       Power BI Host | Web Host

Unified website and Playground

The Next.js application in apps/web is the single HyperPBI website and include the playground. Shared navigation connects the product introduction at /, the Component Explorer at /components, the local-first Playground at /playground, complete dashboards at /examples, and the documentation library at /docs.

The Playground is embedded as a Preact runtime island inside that application. It reuses HyperPbiStudio, HyperPbiRoot, schema preparation, runtime configuration, sanitizers, calculations, logical datasets, field handling, and component rendering from src; there is no web-only dashboard format or duplicate renderer.

From the repository root, run npm install and npm run dev, then open http://localhost:4178. Use npm run build for the complete production build, including root and web type checks, the shared runtime island, and the Next.js application.

For the web runtime, rest.get origins are frozen into the build trust policy. Set HYPERPBI_WEB_REST_HOSTS to comma-separated exact HTTPS origins or subdomain wildcard origins before npm run web:build / the full web build. Defaults include the miniup.app and miniup.io apex/subdomain families plus the HyperPBI demonstration origin. The dashboard specification may choose only an origin allowed by that build; it cannot expand the trust list.

The local workflow is:

  1. Create or import a project.
  2. Upload one or more CSV/XLSX files. A CSV creates one source and every workbook sheet creates one source.
  3. Inspect fields and preview rows, name sources, and select the default source exposed to the specification as powerbi.
  4. Author in the existing Studio, validate through the 2.0 preparation pipeline, and open full-viewport Play Mode.
  5. Let IndexedDB save specification, Runtime Configuration, editor state, source manifests, normalized fields/rows, and deterministic row keys.
  6. Copy/download portable specification and Runtime Configuration JSON, or export/import the complete .hyperpbi local project.

A .hyperpbi project is a Playground backup containing local normalized data and editor state. A portable Power BI specification contains the declarative dashboard only; Power BI must provide the required data to the visual. Before Power BI export, the Playground reports whether the project is compatible, safely compatible after rewriting the selected default source ID to powerbi, or not fully portable. It never collapses genuinely separate uploaded sources into one.

See architecture for host contracts, persistence, portability, Next.js deployment, and future service boundaries.

Dashboard examples

The /examples gallery loads complete dashboards from examples/dashboards. Every folder contains specification.json, runtime.json, data.csv, a complete project.hyperpbi Playground bundle, and host-specific instructions in README.md.

Dashboard Folder Power BI package
Talent Acquisition Command Center talent-acquisition Core
Capital Project Controls capital-project-controls Core
Retail Sales Operations retail-sales-operations Core
Urban Mobility Command Center urban-mobility-command-center Maps
Patient Care Operations patient-care-operations Core
Digital Banking Overview digital-banking-overview Core
Media & Web Performance media-web-performance Core
Industrial Network Telemetry industrial-network-telemetry Core
Dynamic GIS Analytics dynamic-gis-analytics Maps
Universal Dynamic Content universal-dynamic-content Maps
Pump Station Monitoring pump-station-monitoring Core
Groundwater Supply & Distribution groundwater-supply-distribution Core

Open an example to preview the project, inspect its JSON, or open a copy in /playground. For Power BI, import data.csv as one table, add its columns to HyperPBI’s single Values field well, paste runtime.json into Runtime Configuration, and paste specification.json into Advanced JSON. Use the package shown in the table. Urban Mobility requests OpenStreetMap tiles, and the two Dynamic Content examples request MiniUp data. Import the .hyperpbi bundle in Playground.

See the dashboard example guide for regeneration, package-profile, and portability details.

Interactive 3D scenes

Add 3D scene from the Visual Inspector catalog to build an equipment layout from primitives, pump and tank assemblies, or embedded GLB and glTF models. The Scene editor provides object transforms, material controls, and dataset bindings. Select an asset to link charts, tables, and Power BI visuals by source row identity. Configure per-object rotation (including RPM fields), translation, scale, pulse, blink, and bounded GLB/glTF rigid-transform clip playback in the visual editor. Motion obeys reduced-motion and runtime budgets. Animation Studio. Three.js ships locally in both Core and Maps. 3D scene guide · Pump Station Monitoring

Author up to 128 objects per scene in Direct JSON, the default mode. To reuse one viewer across facilities, opt into a Power BI SceneJSON text column and select the station from a dropdown, table, or map. SceneJSON setup · Multi-Station 3D Explorer

Current status and schema versions

Power BI workflow

  1. Import the appropriate PBIVIZ package and bind the required Power BI fields to Values.
  2. Open the visual’s Edit command. Edit Mode starts in a focused guided experience for creating or revising a dashboard without navigating expert tools.
  3. Review the Field Manifest and dashboard setup, choose a prompt job, and copy the generated prompt to an approved external AI.
  4. Paste one JSON response into the Guided Builder and select Validate & Preview.
  5. Use Split, Editor, or Preview to compare the working dashboard with its validated result. A subsequent edit changes the status from Preview current to Preview out of date until Preview changes succeeds again.
  6. Resolve blocking errors in the Errors group and review non-blocking Warnings separately. Invalid input never replaces the last valid preview.
  7. Select Save & return. HyperPBI revalidates the current specification and runtime settings before it persists them and exits Edit Mode.

The default guided mode keeps the main workflow and help visible. Select Advanced controls when you need the complete workspace navigation: Create (AI Builder, Visual Inspector, Map Studio), Data & logic (Field mapping, Calculations), Test (Interaction testing, Map services), Advanced (Runtime settings, JSON editor), and Learn (Documentation, AI skill guide). Select Guided mode to return to the focused path. Narrow layouts shorten those two mode buttons to Advanced and Guided. Changing modes does not discard the dashboard or its validated preview.

The permanent Visual Inspector can select a rendered component, locate its canonical authoring JSON (including generated runtime ownership), edit that fragment, and preserve stable IDs. It provides searchable keyboard navigation, dataset-aware controls, descriptor-validated add/insert/move/duplicate/delete operations, responsive Tree and Properties panes, and bounded transaction undo/redo. Wide layouts support keyboard-accessible resizing. Compact layouts show one Inspector pane at a time, move a tree selection into Properties, and provide Back to hierarchy. Empty, no-match, and invalid-JSON states explain the next safe action. Every candidate is prepared and validated as a complete dashboard; invalid input remains a local draft and never replaces the last valid specification or preview.

Connect HyperPBI components and Power BI visuals

Recommended: use Visual Inspector → Connect components. Select a chart, table, or filter control; choose Connect to other components (recommended), then choose Filter or Highlight, the receiving component IDs (or all other components), the Power BI behavior, and an optional interaction field. Changes use the existing schema 2.0 interaction object. Advanced JSON remains available.

There is no separate interaction key to invent:

Complete example: bind the zone column and flow field/measure in HyperPBI’s Power BI Values well. Use the actual aliases shown by your Field Manifest, not display names copied blindly.

{
  "version": "2.0",
  "title": "Zone monitoring",
  "components": [
    {
      "type": "select",
      "id": "zone_filter",
      "label": "Zone",
      "field": "zone",
      "interaction": {
        "enabled": true,
        "internalMode": "filter",
        "internalScope": "others",
        "externalMode": "filter",
        "field": "zone"
      }
    },
    {
      "type": "barChart",
      "id": "zone_flow_chart",
      "title": "Flow by zone",
      "category": "zone",
      "measure": "flow",
      "interaction": {
        "internalMode": "highlight",
        "internalScope": "others",
        "externalMode": "selection",
        "clearOnSecondClick": true
      }
    },
    {
      "type": "table",
      "id": "zone_details",
      "columns": ["zone", "flow"],
      "pageSize": 10
    }
  ]
}

Expected behavior: changing zone_filter filters the HyperPBI chart/table and requests a report-level filter on the underlying Power BI zone column. Clicking a chart bar highlights matching HyperPBI rows and requests selection of the contributing Power BI row identities. To target only the table instead, add "targets": ["zone_details"] to that chart’s interaction. External selection/filtering still operates at the report level, not just the listed internal targets.

Troubleshooting: In Advanced controls → Test → Interaction testing, click the source and inspect the last field/value, actual model target, selected identity count, result, and suggested fix. If internal interaction works but the report does not respond, verify the Values bindings, real column vs measure, Power BI Format → Edit interactions, and semantic model relationships. If using independent uploaded/remote datasets, matching string keys do not automatically join them; prepare a shared keyed dataset or a relationship in the model first. For full details see Interactions.

HyperPBI 2.0 authoring model

The minimal contract is:

{
  "version": "2.0",
  "components": []
}

Allowed root properties are version, title, theme, layout, state, app, leftPanel, rightPanel, toolbar, components, css, styles, calculations, data, and definitions. Under data, only sources and datasets are accepted. Version 2.0 rejects unknown root and component properties.

Every component needs a globally unique stable id that starts with a letter and contains only letters, digits, _, or - (maximum 100 characters). IDs connect inspector edits, UI-action targets, overlay state, interaction state, and pattern expansion, so improvements should preserve them whenever the same component remains.

Preparation follows the implementation pipeline: safe unambiguous authoring repairs; optional ID assignment; definition expansion; pattern expansion; design-system validation; dataset field resolution and static dataset schemas; component dataset validation; field-alias resolution; design-system expansion; strict schema 2.0 validation; then calculation/reference checks before render. Missing or non-2.0 versions are rejected before rendering.

Field aliases and Power BI metadata

The Field Manifest separates concepts that older documentation often conflated:

Concept Meaning
AI alias Stable camel-case identifier used in new 2.0 authoring
Canonical runtime key Internal normalized key used after preparation
Display name Power BI label shown to a person; not necessarily a valid reference
Source table/column Semantic-model origin used to construct external filter targets
True model measure Power BI measure (kind: "measure"); not a basic column-filter target
Query aggregation wrapper Query expression such as Sum(Sales.Amount) around a model column
Implicit aggregation isImplicitAggregation: true; the underlying item is still a model column
Dataset-derived field Row expression output local to a logical dataset
Dataset metric Grouped aggregate output local to a logical dataset
Dataset group field Group-by output; retains model-column origin metadata when available

Sum(Sales.Amount) must not be described as a model measure merely because the visual query summarizes it. A real model column with sourceTable and sourceColumn can support external filtering. Exact identity selection is separate: it requires Power BI identities or dataset source-row lineage.

Alias privacy modes range from sample-bearing profiles to masked, summary, fields-only, and types-only manifests. Do not place confidential sample values, credentials, AI keys, ArcGIS tokens, or private service URLs in prompts or dashboard JSON.

Logical datasets

Read-only remote sources live at data.sources; named datasets live at data.datasets. A dataset source may be powerbi, a declared remote source, another named dataset, or—in the Playground—an uploaded source ID. After source resolution, both runtime evaluation and static schema propagation use this order:

filter → derive → rename → select → groupBy/metrics → distinct → sort → limit

Components omit dataset to use the base powerbi data view or name one dataset to use only that output schema. Dataset chains are deterministic, cycle-checked, cached by canonical definition/input signatures, and retain source-row lineage through filtering, grouping, and deduplication. Static schemas keep generated fields available even when the runtime result has zero rows.

Logical datasets do not execute SQL, join arbitrary sources, call the network, or run JavaScript. See the data model reference.

Components and application patterns

The generated catalog derives type, label, category, status, intended use, level, capabilities, required/allowed properties, interaction/UI-action support, accessibility guidance, related types, and valid examples from canonical TypeScript metadata.

Categories are Layout, Controls, Navigation, Display, Primitives, Feedback, Forms, Charts, Tables, Maps, Custom components, and Advanced components. The inventory includes svg, svgMarkup, advancedChart, and custom-content components.

Four 2.0 application patterns compile to existing runtime components with deterministic child IDs:

Reusable root definitions deep-merge objects, replace arrays, remove definition IDs, and require every use instance to provide its own stable ID. Patterns and definitions are authoring conveniences; they do not add renderer behavior.

Application-style layout

Every component supports mobile-first responsive rules at xs (0), sm (480), md (768), lg (1024), and xl (1280) container breakpoints. Rules can change span, order, visibility, direction, stacking, and layout columns without viewport-global CSS. Grids and split panes stack by default on compact containers; authored desktop spans return at lg unless an explicit rule overrides them.

heightMode: "fill" propagates a bounded flex/grid height through nested grids, cards, tabs, charts, tables, maps, and split panes. aspectRatio creates a ratio-bound surface, and minHeight supplies a safe lower bound. A split becomes viewer-resizable with resizable: true; sizes, minSizes, and maxSizes are pane percentages, handles support pointer and keyboard input, and persist: "none"|"session"|"local" controls per-visual saved sizes. See the flexible application dashboard example.

Compact Map Studio

Map Studio uses a 40 px floating icon rail and one adjustable settings drawer over the existing Leaflet map. Configure multiple layers, service/GeoJSON joins, symbols, label fonts, filters, selections, legends and structured popups without JSON. The color picker, popup blocks and layer settings update canonical HyperPBI 2.0 JSON with undo/redo. Public GeoJSON/ArcGIS URLs on miniup.app, miniup.io and their subdomains use the same generic source adapters; there is no dedicated MiniUp map integration.

See Map Studio, portable map definitions, and trusted rendering.

Visual Inspector now provides shared chart configuration for independent series, automatic/fixed axes, date and numeric formatting, gradients, labels, thresholds, annotations and zoom. It also creates field-bound components through a searchable metadata picker. See advanced visual authoring, the configuration example, and 1,200 sample readings. The active registry audit covers 83 components after GeoLibre removal; these improvements add no component types.

Charts, tables, maps, and SVG

Semantic charts include bar, horizontal bar, line, area, pie, donut, scatter, gauge, heatmap, combo, waterfall, sankey, treemap, funnel, radar, and small multiples. Their ECharts options can alter safe presentation but cannot replace generated datasets, axes, series types/counts, links, nodes, encodings, or transforms. Declarative events.zoom, events.rangeSelect, and events.brush persist view state and can link filtered/highlighted source rows to named components. drill.levels navigates preloaded logical datasets with dataset-aware fields, parent-key filtering, source lineage, and breadcrumbs. advancedChart is the sanitized JSON-only escape hatch for implemented ECharts configurations that a semantic chart cannot express.

table is the supported native detail table. It measures its scroll viewport and virtualizes configured large datasets with bounded overscan; CSV/XLSX export can use filtered rows, selected rows, or selected rows with filtered fallback, and excludes hidden columns. matrix renders every declared value metric across optional column groups, with per-metric formatting, totals, heatmaps, accessible headers, source-row interactions, deterministic row limits, and a visible cell-budget warning. Its shared aggregation policy requires numeric fields for numeric operations while count may omit a field. table.engine is not part of schema 2.0.

map uses the same single Values field well as every other HyperPBI component for Power BI-backed fields; reference-only service and GeoJSON maps require no Values fields. HyperPBI 2.0 maps provide explicit Power BI, ArcGIS Feature/Tile/Dynamic, inline/remote GeoJSON, and generic XYZ layers; simple, unique, class-break, continuous, proportional, cluster, true canvas heatmap, density-grid, rich icon, line, and polygon renderers; interactive multi-layer legends; rectangle, lasso, and circle selection; quick filters; safe popups/labels; and compact operational tools. A shared controller synchronizes click, legend, spatial, external Power BI, and other HyperPBI component interactions across selected, hovered, externally highlighted, dimmed, and filtered states. Map Studio configures the major capabilities while retaining advanced JSON. See the analytical map guide, map services, and the manifest-driven map gallery.

Map demos

Five version 2 examples under examples/specs demonstrate the stabilized map runtime; Power BI-backed examples use compact CSV data under examples/data:

The separate Flexible operations workspace example combines fill sizing, a persisted split, breakpoint stacking, spatial selection, chart event linking, hierarchical dataset drill, virtualized detail, and CSV/XLSX export.

Power BI coordinate and geometry layers support feature clicks and native row selection. ArcGIS Feature layers support queries, details, selection, and joins. ArcGIS Dynamic layers support temporary click identify details but not joins or persistent selection. ArcGIS Tile layers remain display-only with no identify, popup, join, or selection.

Map Studio candidate edits are validated with the exact current Runtime Config. Feature click, legend, rectangle, lasso, circle, Select visible, Invert, quick-filter reconciliation, external Power BI state, and linked HyperPBI state use one analytical interaction pipeline. ArcGIS tile/dynamic definition changes rebuild only the affected mounted overlay while preserving the viewport; access denial removes already-loaded content. ArcGIS root inspection is one bounded summary request, with lazy selected-item metadata and separate spatial/group/table classification. Join cardinality and unmatched policies are enforced and diagnosed; blank/invalid numeric aggregation inputs never fabricate zero, and empty numeric groups return null. Computed class breaks reduce to the supported distinct/ramp count, and map diagnostics use canonical RFC 6901 pointers scoped to the exact selected layer.

svg is the preferred governed vector system for diagrams, schematics, pictorial marks, and custom gauges. It uses structured allowlisted elements, bindings, scales, conditions, state, bounded repeats, normal interactions, ID isolation, animation presets, and reduced-motion handling. svgMarkup defaults to a sanitized raw SVG document; explicit trusted SVG mode preserves authored markup inside a sandboxed document. See SVG visuals.

For content, distinguish text, markdown, Standard or trusted html/custom, declarative svg, and Standard or trusted svgMarkup. Prefer a first-class component when one fits.

Interactions

HyperPBI has three separate declarative systems:

  1. uiAction changes interface state: tabs, steps, sidebar, overlays, toasts, scrolling, filter clearing, and a safe refresh no-op.
  2. Universal interaction controls internal none|highlight|filter behavior and external Power BI none|auto|selection|filter behavior.
  3. interactions maps supported component events to allowlisted custom payload actions.

externalMode: "auto" resolves to filter for controls and selection for data-point/custom components. target/targets can restrict internal linked behavior to named component IDs. External filter mode requires a model-column target; true measures, dataset-derived fields, and dataset metrics cannot directly filter Power BI. Dataset lineage can map a derived/grouped row back to contributing source identities for selection. See interactions.

Edit Mode, prompts, and repair

Prompt jobs are Create dashboard, Improve current dashboard, Add section, Redesign selected section, and Repair invalid JSON. Create/improve/repair normally return a complete specification. Add-section returns a strict change package for before, after, a descriptor-compatible nested containerPath, or a root components|toolbar|leftPanel|rightPanel destination; redesign returns one replacement using the selected stable ID. Edit Mode validates the complete result, then promotes that same prepared JSON to the working draft and preview in one transaction. Normal improvements and repairs return complete JSON, not JSON Patch.

Preview current means the visible preview was prepared from the exact working specification and Runtime settings. Any later change makes it Preview out of date while leaving the last valid result visible for comparison; Not previewed means no current candidate has completed preview preparation. Use Preview changes for normal edits; targeted AI packages use Validate resulting dashboard & Preview before promotion. Diagnostics are separated by severity: errors block preview and save, while warnings remain visible without being presented as equivalent failures. Save & return performs final validation and preview preparation against the current working values; it saves only when that validation succeeds.

Prompt composition includes only relevant component modules, Field Manifest data under the chosen privacy mode, recommended patterns, applicable datasets/maps/tables/charts/SVG guidance, current JSON for improvement, selected ID for redesign, and structured diagnostics for repair.

The importer accepts one JSON object directly or inside one Markdown fence and can extract one unambiguous object from surrounding text. Multiple candidate objects, comments, smart quotes, or truncated JSON produce diagnostics rather than speculative repair. AI import is strict: the response must declare version 2.0, every component must already have a stable ID, and unknown properties are rejected. It never substitutes fields, changes aggregations, deletes components, removes interactions, or rewrites business logic.

Security

See the full security model.

Package profiles

npm run package:core
npm run package:maps

The packaging script produces *-core.pbiviz and *-maps.pbiviz. Each profile is built once and inspected from its ZIP archive. Exact base names derive from the PBIVIZ packager.

Development commands

npm install
npm run dev
npm run build
npm run web:start
npm run web:sites:build
npm run typecheck
npm test
npm run test:browser
npm run lint
npm run examples:generate
npm run examples:check
npm run docs:generate
npm run docs:check
npm run package:core
npm run package:maps
npm run package:verify

npm run dev builds the shared browser runtime and starts the unified Next.js site at http://localhost:4178. npm run build runs the complete production type-check and build pipeline. The lower-level playground:* and web:* commands remain available to maintainers who need to isolate one workspace; they are not separate public websites.

npm run examples:generate deterministically regenerates the dashboard folders and manifest. npm run examples:check validates strict schema preparation, Power BI portability, data limits, documentation, and checked-in project bundles.

npm run docs:generate is documentation-only. It executes canonical TypeScript metadata without building the visual. It fully regenerates:

It also refreshes the marked generated inventory region in:

Do not hand-edit the fully generated reference outputs or the marked region. The rest of README.md remains hand-maintained. The Next.js /components route consumes the generated JSON inventory, while /docs renders the Markdown references.

Documentation index

Document Purpose
Architecture and unified website Next.js shell, shared runtime islands, host bridges, projects, portability, deployment
Dashboard examples Ten complete dashboards, Playground loading, Power BI import, package profiles
User guide Power BI and Edit Mode workflow
2.0 specification Root, components, app, styles, behavior, diagnostics
Generated component catalog Canonical component inventory and examples
AI authoring Prompt jobs, modules, privacy, and output contracts
ChatGPT guideline Concise external-AI response rules
AI skill Generated checked-in authoring skill
Data model Fields, datasets, lineage, caching, zero rows
Calculations Root calculations and expression DSL
Interactions UI actions, universal behavior, custom events
Custom content Text, Markdown, HTML, custom, SVG variants
SVG visuals Structured SVG, markup fallback, limits, motion
Map services Power BI geometry, ArcGIS, providers, packaging
Repair workflow Extraction, diagnostics, and bounded repairs
Migration/versioning Schema 2.0 boundary and standalone legacy converter
Security Sanitizers, URL/provider policy, privacy boundaries

Documentation maintenance

Canonical component inventory lives in src/catalog/componentDescriptors.ts. Each explicit descriptor owns maturity, authoring complexity, schema properties, field traversal handlers, Inspector controls, documentation, renderer mode, child containers, and a valid example. Strict validator maps, prompts, and generated documentation derive from that registry. Update the descriptor and renderer together, then run npm run docs:generate; do not hand-edit generated catalogs.

HyperPBI 2.0 authoring uses Field Manifest aliases or canonical resolved field keys, including documented nested table, detail, template, SVG, interaction, dataset, and Power BI-backed map positions. Display names are not accepted as aliases. ArcGIS service fields and joined aliases are separate namespaces and are never treated as Power BI aliases.

Dataset contracts come from src/data/datasets.ts and src/data/datasetSchema.ts; SVG constants from src/components/svg/svgTypes.ts; AI contract composition from src/ai/promptComposer.ts; and the canonical embedded/check-in skill from HYPERPBI_SKILL_MARKDOWN in src/docs/hyperpbiHelp.ts.

Known limitations

Dynamic Content

Use dynamicContent to load interactive details from a public HTTPS API in a card, panel, modal, or dashboard region. Map feature popups use the same renderer. Both examples use MiniUp and open as editable projects. Dynamic GIS Analytics · Universal Dynamic Content · Dynamic Content guide

This site is open source. Improve this page.