@praxisui/charts

@praxisui/charts

Metadata-driven charting for Praxis UI Angular, with a stable public contract and an engine adapter boundary.

Documentation

• Official documentation: https://praxisui.dev
• Repository: https://github.com/codexrodrigues/praxis-ui-angular
• Recommended for: Angular hosts that need declarative analytics widgets aligned with the @praxisui/* runtime

What this package provides

• PraxisChartComponent for standalone chart rendering
• typed chart contracts for config, datasets, events and widget mapping
• internal Apache ECharts adapter behind a Praxis engine interface
• built-in loading, empty and error states
• mapping from canonical x-ui.chart contracts into Praxis widget/page structures
• support services for backend payload adaptation, stats requests and chart option building

Why this package exists

• keep the public API business-oriented instead of exposing raw engine options as the main contract
• preserve the option to swap the rendering engine later without rewriting host integrations
• align charts with the same metadata-driven model used by the rest of the Praxis UI platform

Install

npm i @praxisui/charts

Peer dependencies (Angular v20):

• @angular/core ^20.0.0
• @angular/common ^20.0.0
• @praxisui/core ^1.0.0-beta.68

Runtime dependency included by this package:

• echarts ^6.0.0

Quick Start

import { Component } from '@angular/core';
import {
  PraxisChartComponent,
  type PraxisChartPointEvent,
  type PraxisChartConfig,
} from '@praxisui/charts';

@Component({
  selector: 'app-chart-demo',
  standalone: true,
  imports: [PraxisChartComponent],
  template: `
    <praxis-chart
      [config]="config"
      (pointClick)="onPointClick($event)"
    ></praxis-chart>
  `,
})
export class ChartDemoComponent {
  readonly config: PraxisChartConfig = {
    title: 'Employees by Department',
    type: 'bar',
    dataSource: {
      kind: 'local',
      items: [
        { department: 'Engineering', total: 18 },
        { department: 'Finance', total: 6 },
        { department: 'HR', total: 4 },
      ],
    },
    axes: {
      x: {
        field: 'department',
        type: 'category',
        label: 'Department',
      },
      y: {
        field: 'total',
        type: 'value',
        label: 'Employees',
      },
    },
    series: [
      {
        id: 'employees',
        type: 'bar',
        metric: {
          field: 'total',
          aggregation: 'sum',
        },
        name: 'Employees',
      },
    ],
  };

  onPointClick(event: PraxisChartPointEvent) {
    console.log('chart point', event);
  }
}

Public Surface Highlights

• standalone components for charts, drilldown panel and runtime probe
• chart contracts such as PraxisChartConfig, PraxisChartDataSource and PraxisChartPointEvent
• providers and tokens for chart engine composition
• services for canonical mapping, backend payload adaptation and option building

See the public exports in projects/praxis-charts/src/public-api.ts.

Current Scope

This first published version is focused on the core runtime:

• the praxis-chart component
• canonical chart contracts and runtime models
• the initial ECharts-based engine adapter
• metadata and mapping hooks for registry and dynamic widget composition

Notes for Hosts

• the package is designed for the Praxis platform model, where chart semantics live in canonical contracts and not in engine-specific payloads
• if you are integrating charts into dynamic pages or widget shells, prefer the exported Praxis contracts and mappers over direct engine customization
• if you need raw ECharts tuning, treat it as adapter-level implementation detail unless the contract is promoted to the public surface intentionally