@aurum-grid/charts 0.0.0-stage → 0.2.0

package/LICENSE.md

@@ -0,0 +1,24 @@
+# Aurum Grid Commercial License (draft template)
+
+> This is a starting-point template, not legal advice. Have a lawyer review it before you sell licences.
+
+Copyright (c) 2026 the Aurum Grid authors. All rights reserved.
+
+## 1. Evaluation
+You may install and use Aurum Grid ("the Software") free of charge for **30 days** to evaluate it. During and after
+evaluation the Software runs unmodified; after 30 days without a valid licence key it displays an
+"unlicensed" watermark and console notice.
+
+## 2. Annual developer licence
+A licence costs **USD 50 per developer per year**. Each licensed developer may use the Software to build an
+unlimited number of applications and deploy them to an unlimited number of end users. The licence key must be
+renewed every year to keep receiving updates and to keep the watermark removed in newly built versions.
+
+## 3. Restrictions
+You may not: (a) redistribute the Software as a standalone component library or competing product;
+(b) remove, alter or circumvent the licence checks or watermark; (c) share licence keys between developers
+beyond the purchased seat count.
+
+## 4. No warranty
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @aurum-grid/charts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Aurum Grid Charts: themeable SVG charts, standalone or grid-integrated.
+
+Part of **Aurum Grid** — the enterprise data grid. See the main documentation: https://github.com/YOUR_ORG/aurum-grid#readme
+
+Licensing: 30-day evaluation, then $50 per developer per year. See LICENSE.md.

package/dist/chart.d.ts

@@ -0,0 +1,146 @@
+import { type Datum } from './transform.js';
+export type ChartType = 'column' | 'bar' | 'stackedColumn' | 'stackedBar' | 'normalizedColumn' | 'normalizedBar' | 'line' | 'area' | 'stackedArea' | 'normalizedArea' | 'pie' | 'donut' | 'nightingale' | 'scatter' | 'bubble' | 'histogram' | 'boxPlot' | 'rangeBar' | 'heatmap' | 'waterfall' | 'funnel' | 'pyramid' | 'gauge' | 'radar' | 'radarArea' | 'radialBar' | 'treemap' | 'sunburst' | 'combo';
+export declare const CHART_TYPES: Array<{
+    value: ChartType;
+    label: string;
+}>;
+/** Chart types grouped the way the chart gallery shows them. */
+export declare const CHART_GROUPS: Array<{
+    group: string;
+    types: ChartType[];
+}>;
+export declare const PALETTES: Record<string, string[] | null>;
+export interface SeriesDef {
+    key: string;
+    name?: string;
+    /** CSS colour; defaults to the theme palette (--agc-1..8). */
+    color?: string;
+}
+export interface PointEvent {
+    category: string;
+    seriesKey: string;
+    value: number;
+    datum: Datum | null;
+}
+export interface ReferenceLine {
+    value: number;
+    label?: string;
+}
+export interface ThresholdBand {
+    from: number;
+    to: number;
+    tone: 'bad' | 'warn' | 'good';
+    label?: string;
+}
+export interface ChartOptions {
+    type: ChartType;
+    data: Datum[];
+    categoryKey: string;
+    series: SeriesDef[];
+    title?: string;
+    subtitle?: string;
+    /** Pixel height, or 'fill' to fill the container's height (the container must have a height). */
+    height?: number | 'fill';
+    width?: number;
+    legend?: boolean;
+    valueFormat?: (v: number) => string;
+    onPointClick?: (p: PointEvent) => void;
+    /** Highlight one category (others are dimmed) — used for cross-filter feedback. */
+    selectedCategory?: string | null;
+    xKey?: string;
+    yKey?: string;
+    sizeKey?: string;
+    bins?: number;
+    max?: number;
+    ariaLabel?: string;
+    emptyText?: string;
+    /** Dashed least-squares trend line for each line/column series. */
+    trendline?: boolean;
+    /** Forecast the first series this many periods ahead (Holt's linear method) with a shaded range. */
+    forecast?: number;
+    /** Annotate the highest and lowest points of the first series. */
+    highlights?: boolean;
+    referenceLines?: ReferenceLine[];
+    /** Gauge target marker (same units as the value). */
+    target?: number;
+    /** Gauge background bands. */
+    thresholds?: ThresholdBand[];
+    /** Radar: scale each axis 0–100 by its maximum so different units compare. */
+    normalize?: boolean;
+    /** Series keys drawn against a right-hand axis (as lines). */
+    secondaryAxis?: string[];
+    /** Sunburst: a second category field for the outer ring (raw, non-aggregated rows). */
+    subCategoryKey?: string;
+    dataLabels?: boolean;
+    palette?: string[] | null;
+    axisLabel?: string;
+}
+export declare const paletteVar: (i: number) => string;
+export declare function looksLikeTime(labels: string[]): boolean;
+export declare class Chart {
+    private container;
+    readonly root: HTMLDivElement;
+    private plot;
+    private svgEl;
+    private legendEl;
+    private tooltip;
+    private titleEl;
+    private tableEl;
+    private emptyEl;
+    private hidden;
+    private ro;
+    private lastSize;
+    private destroyed;
+    options: ChartOptions;
+    constructor(container: HTMLElement, options: ChartOptions);
+    update(patch: Partial<ChartOptions>): void;
+    setType(type: ChartType): void;
+    getSvg(): SVGSVGElement;
+    /** Standalone SVG with computed colours and fonts inlined, so it renders identically elsewhere. */
+    toSvgString(): string;
+    /** Rasterise the chart to PNG (2× by default). */
+    toPngBlob(scale?: number): Promise<Blob>;
+    private viewSize;
+    destroy(): void;
+    private fmt;
+    private visibleSeries;
+    private color;
+    private catColor;
+    render(): void;
+    private summary;
+    private renderLegend;
+    private renderTable;
+    /** The data table (for a visible "Show data" view). */
+    getDataTable(): HTMLTableElement;
+    private bindMark;
+    private text;
+    /** Text with a background "pill" so annotations stay legible over marks. */
+    private callout;
+    private renderCartesian;
+    private drawReferenceLines;
+    private renderPie;
+    private renderFunnel;
+    private renderTreemap;
+    private renderHeatmap;
+    private renderGauge;
+    private renderRadar;
+    private arcPath;
+    /** Nightingale rose: equal angles, radius ∝ √value so area stays proportional. */
+    private renderNightingale;
+    /** Radial bar: one ring per category, arc length ∝ value. */
+    private renderRadialBar;
+    /**
+     * Sunburst: inner ring = categories, outer ring = each category split by series
+     * (or by `subCategoryKey` when the data is not pre-aggregated).
+     */
+    private renderSunburst;
+    /** Pyramid: segments stacked into a triangle, height ∝ value. */
+    private renderPyramid;
+    /**
+     * Box plot (quartiles) and range bar (min–max with mean) per category, computed from raw rows:
+     * every row is one observation of series[0] in its category.
+     */
+    private renderStat;
+    private renderScatter;
+}
+export declare function createChart(container: HTMLElement, options: ChartOptions): Chart;