@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

For Local Development

Since this package is not yet published to a registry, you need to clone the repository and reference it locally:

1. Clone the repository:

   git clone [email protected]:nicola-attico/declarative-ui.git
   cd declarative-ui
   npm install
   npm run build

2. Add to your project's package.json:

   {
     "dependencies": {
       "@declarative-ui/core": "file:../path/to/declarative-ui"
     }
   }

3. Install dependencies:

   npm install

Note: The file: path creates a symlink to the local package. This is the standard approach for local development before publishing.

From npm (when published)

Once published to a registry:

npm install @declarative-ui/core

Usage

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 <CanvasRenderer page={dashboardConfig} />;
}

Component Types

vegalite5 - Charts and Visualizations

Uses Vega-Lite for declarative visualizations.

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

table - Data Tables

Display multiple rows in a structured table format.

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

list - Card-Based Lists

Display items as individual cards with selected fields.

{
  "type": "list",
  "title": "Team Members",
  "dataRef": "team_data",
  "config": {
    "displayFields": ["name", "role", "department"]
  }
}

For single-row key-value display:

{
  "type": "list",
  "dataRef": "summary_data",
  "config": {
    "mode": "kv"
  }
}

map - Interactive Maps

Geographic visualization using MapLibre GL.

{
  "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.

form - Input Forms

Input forms with labeled fields.

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

markdown - Formatted Text

Display formatted documentation and text using Markdown.

{
  "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.

mermaid - Diagrams

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

{
  "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

Prerequisites

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

Build Steps

# 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

Development Mode

# Watch mode (rebuilds on file changes)
npm run dev

Verifying the Build

Check that type definitions were generated:

ls dist/*.d.ts
# Should show: dist/index.d.ts

Adding to Your Project

Step 1: Install the Package

See the Installation section above for instructions on cloning and referencing the local package.

Step 2: Import and Use

import { CanvasRenderer, PAGE_SCHEMA } from '@declarative-ui/core';

function Canvas() {
  const config: Page = {
    layout: { engine: "rgl", cols: 24, items: [...] },
    components: {...},
    data: {...}
  };

  return <CanvasRenderer page={config} />;
}

Step 3: Validate JSON (Optional)

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