A declarative, JSON-driven dashboard component library for React.
npm install declarative-ui-coreA declarative, JSON-driven dashboard component library for React.
- JSON-driven: Define entire dashboards using a simple JSON schema
- Component library: Built-in support for charts (Vega-Lite), maps (MapLibre), tables, lists, and forms
- Grid layout: Responsive grid-based layouts using react-grid-layout
- Type-safe: Full TypeScript support with JSON Schema validation
- Extensible: Easy to add custom component types
Since this package is not yet published to a registry, you need to clone the repository and reference it locally:
1. Clone the repository:
``bash`
git clone git@code.devsnc.com:nicola-attico/declarative-ui.git
cd declarative-ui
npm install
npm run build
2. Add to your project's package.json:
`json`
{
"dependencies": {
"@declarative-ui/core": "file:../path/to/declarative-ui"
}
}
3. Install dependencies:
`bash`
npm install
Note: The file: path creates a symlink to the local package. This is the standard approach for local development before publishing.
Once published to a registry:
`bash`
npm install @declarative-ui/core
`typescript
import { CanvasRenderer, type Page } from '@declarative-ui/core';
const dashboardConfig: Page = {
layout: {
engine: "rgl",
cols: 24,
items: [
{ i: "chart1", x: 0, y: 0, w: 12, h: 8 }
]
},
components: {
chart1: {
type: "vegalite5",
title: "Sales Over Time",
dataRef: "salesData",
spec: {
$schema: "https://vega.github.io/schema/vega-lite/v5.json",
mark: "line",
encoding: {
x: { field: "date", type: "temporal" },
y: { field: "sales", type: "quantitative" }
}
}
}
},
data: {
salesData: {
source: "inline",
rows: [
{ date: "2024-01-01", sales: 100 },
{ date: "2024-01-02", sales: 150 }
]
}
}
};
function App() {
return
}
`
`json`
{
"type": "vegalite5",
"title": "Sales Trend",
"dataRef": "sales_data",
"spec": {
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
"mark": "line",
"encoding": {
"x": {"field": "date", "type": "temporal"},
"y": {"field": "value", "type": "quantitative"}
}
}
}
`json`
{
"type": "table",
"title": "Projects",
"dataRef": "project_data",
"config": {
"columns": [
{"key": "name", "label": "Project Name"},
{"key": "status", "label": "Status"}
]
}
}
`json`
{
"type": "list",
"title": "Team Members",
"dataRef": "team_data",
"config": {
"displayFields": ["name", "role", "department"]
}
}
For single-row key-value display:
`json`
{
"type": "list",
"dataRef": "summary_data",
"config": {
"mode": "kv"
}
}
`json`
{
"type": "map",
"title": "Office Locations",
"dataRef": "location_data",
"config": {
"style": "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
"options": {
"center": [0, 20],
"zoom": 2
}
}
}
Data must include lng and lat fields. If rows also include a name field, the map will render text labels for each point.
`json`
{
"type": "form",
"title": "User Input",
"config": {
"columns": [
{"key": "name", "label": "Full Name"},
{"key": "email", "label": "Email Address"}
]
}
}
`json`
{
"type": "markdown",
"title": "Documentation",
"config": {
"md": "# Heading\n\nParagraph with bold and italic.\n\n- List item 1\n- List item 2"
}
}
Markdown components do not use dataRef - all content is in config.md.
`json`
{
"type": "mermaid",
"title": "Process Flow",
"config": {
"mermaid": "flowchart TD\n A[\"Start\"] --> B[\"Process\"]\n B --> C[\"End\"]"
}
}
Mermaid components do not use dataRef - all diagram code is in config.mermaid. Supports flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, pie, and more. Includes zoom controls for better readability.
Note: When node labels contain special characters like parentheses, wrap labels in quotes: A["Label with (chars)"]
`bashInstall dependencies
npm install
The build process:
1. TypeScript compilation: Generates
.d.ts declaration files in dist/
2. Vite bundling: Creates optimized JavaScript bundleOutput structure:
`
dist/
├── index.js # Main bundle
├── index.d.ts # Root type definitions
├── index.css # Component styles
├── canvas/ # Type definitions for canvas modules
└── components/ # Type definitions for components
`$3
`bash
Watch mode (rebuilds on file changes)
npm run dev
`$3
Check that type definitions were generated:
`bash
ls dist/*.d.ts
Should show: dist/index.d.ts
`Adding to Your Project
$3
See the Installation section above for instructions on cloning and referencing the local package.
$3
`typescript
import { CanvasRenderer, PAGE_SCHEMA } from '@declarative-ui/core';function Canvas() {
const config: Page = {
layout: { engine: "rgl", cols: 24, items: [...] },
components: {...},
data: {...}
};
return ;
}
`$3
`typescript
import { PAGE_SCHEMA } from '@declarative-ui/core';
import Ajv from 'ajv';const ajv = new Ajv();
const validate = ajv.compile(PAGE_SCHEMA);
if (validate(yourConfig)) {
// Valid configuration
} else {
console.error(validate.errors);
}
``