@declarative-ui/core

A declarative, JSON-driven dashboard component library for React.

Features

- 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

Installation

$3

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.

$3

Once published to a registry:

`bash
npm install @declarative-ui/core
`

Usage

`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 ;
}
`

Component Types

$3

Uses Vega-Lite for declarative visualizations.

`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"}
}
}
}
`

$3

Display multiple rows in a structured table format.

`json
{
"type": "table",
"title": "Projects",
"dataRef": "project_data",
"config": {
"columns": [
{"key": "name", "label": "Project Name"},
{"key": "status", "label": "Status"}
]
}
}
`

$3

Display items as individual cards with selected fields.

`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"
}
}
`

$3

Geographic visualization using MapLibre GL.

`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.

$3

Input forms with labeled fields.

`json
{
"type": "form",
"title": "User Input",
"config": {
"columns": [
{"key": "name", "label": "Full Name"},
{"key": "email", "label": "Email Address"}
]
}
}
`

$3

Display formatted documentation and text using Markdown.

`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.

$3

Create flowcharts, sequence diagrams, and other diagrams using Mermaid syntax.

`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)"]

Building the Library

$3

- Node.js 20.19+ or 22.12+ (recommended)
- npm or yarn

$3

`bash


Install dependencies

npm install

Build library (generates JavaScript + TypeScript declarations)

npm run build
`

The build process:
1. TypeScript compilation: Generates .d.ts declaration files in dist/
2. Vite bundling: Creates optimized JavaScript bundle

Output 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);
}
``