@thl-ui/charts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thl-ui contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @thl-ui/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.
+thl-ui charts: dependency-free SVG geometry for line, bar, pie and sparkline charts.
+
+Part of [thl-ui](https://thl.tandd.dev): one UI kit for React, Vue and Angular with a headless TypeScript core, global config, 12 skins, dark mode and i18n (en, ja, vi, zh).
+
+The chart math behind the `LineChart`, `BarChart`, `PieChart` and `Sparkline` components in the framework adapters. Pure functions that return SVG paths, with no dependencies.
+
+```bash
+npm i @thl-ui/charts
+```
+
+```ts
+import { lineChart, niceTicks, smoothPath } from '@thl-ui/charts';
+```
+
+Colors follow the semantic tokens, so charts follow the active skin and dark mode. For complex charts you can still use Chart.js or ECharts next to thl-ui.
+
+## Live demos
+
+| Framework | Package | Live demo |
+|---|---|---|
+| React ≥ 18 | [`@thl-ui/react`](https://www.npmjs.com/package/@thl-ui/react) | [thl-react.tandd.dev](https://thl-react.tandd.dev) |
+| Vue ≥ 3.5 | [`@thl-ui/vue`](https://www.npmjs.com/package/@thl-ui/vue) | [thl-vue.tandd.dev](https://thl-vue.tandd.dev) |
+| Angular ≥ 20 | [`@thl-ui/angular`](https://www.npmjs.com/package/@thl-ui/angular) | [thl-angular.tandd.dev](https://thl-angular.tandd.dev) |
+
+Each demo is the full 74-page admin template, built with the packages installed from npm. Open the ⚙ panel to switch skin, layout, dark mode and language.
+
+## Links
+
+- Docs: [thl.tandd.dev/components/charts](https://thl.tandd.dev/components/charts) (English, 日本語, Tiếng Việt, 简体中文)
+- Source and issues: [GitLab](https://gitlab.com/tandd.packages/thl-ui)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @thl-ui/charts — dependency-free SVG chart geometry.
+ * Chart geometry for thl-ui. Pure functions return
+ * paths/coords; each adapter renders <svg> with them, so output is identical across frameworks.
+ */
+export interface Series {
+    name: string;
+    data: number[];
+    color?: string;
+}
+export interface Box {
+    width: number;
+    height: number;
+    padding?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+export declare const chartColors: string[];
+export declare const colorAt: (i: number, s?: {
+    color?: string;
+}) => string;
+/** "Nice" axis ticks. */
+export declare function niceTicks(min: number, max: number, count?: number): number[];
+/** Smooth path through points (monotone-ish cardinal spline). */
+export declare function smoothPath(pts: Array<[number, number]>, tension?: number): string;
+export interface XYChart {
+    width: number;
+    height: number;
+    yTicks: Array<{
+        value: number;
+        y: number;
+    }>;
+    xLabels: Array<{
+        label: string;
+        x: number;
+    }>;
+    series: Array<{
+        name: string;
+        color: string;
+        line: string;
+        area: string;
+        points: Array<{
+            x: number;
+            y: number;
+            value: number;
+            label: string;
+        }>;
+    }>;
+    plot: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Line / area chart. */
+export declare function lineChart(series: Series[], labels: string[], box: Box, o?: {
+    smooth?: boolean;
+    min?: number;
+    max?: number;
+    stacked?: boolean;
+}): XYChart;
+export interface BarChart {
+    width: number;
+    height: number;
+    yTicks: Array<{
+        value: number;
+        y: number;
+    }>;
+    xLabels: Array<{
+        label: string;
+        x: number;
+    }>;
+    bars: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        color: string;
+        value: number;
+        series: string;
+        label: string;
+    }>;
+    plot: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Grouped or stacked bars. */
+export declare function barChart(series: Series[], labels: string[], box: Box, o?: {
+    stacked?: boolean;
+    gap?: number;
+    max?: number;
+}): BarChart;
+/** Arc path for pie/donut slices. Angles in radians, 0 = 12 o'clock, clockwise. */
+export declare function arcPath(cx: number, cy: number, r: number, inner: number, a0: number, a1: number): string;
+export interface PieSlice {
+    label: string;
+    value: number;
+    percent: number;
+    color: string;
+    path: string;
+    labelX: number;
+    labelY: number;
+}
+/** Pie / donut. */
+export declare function pieChart(data: Array<{
+    label: string;
+    value: number;
+    color?: string;
+}>, size: number, o?: {
+    donut?: number;
+    padAngle?: number;
+}): PieSlice[];
+/** Ring gauge: returns stroke-dasharray values for a circle. */
+export declare function gauge(value: number, max?: number, size?: number, stroke?: number): {
+    r: number;
+    cx: number;
+    cy: number;
+    circumference: number;
+    offset: number;
+    percent: number;
+};
+/** Sparkline (line & bar). */
+export declare function sparkline(data: number[], width: number, height: number, type?: 'line' | 'bar'): {
+    bars: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        value: number;
+    }[];
+    line: string;
+    area: string;
+    last?: undefined;
+} | {
+    bars: never[];
+    line: string;
+    area: string;
+    last: [number, number];
+};
+export declare const formatTick: (v: number, locale?: string) => string;

package/dist/index.js

@@ -0,0 +1,172 @@
+export const chartColors = [
+    'var(--thl-color-primary)',
+    'var(--thl-color-success)',
+    'var(--thl-color-warning)',
+    'var(--thl-color-danger)',
+    'var(--thl-color-info)',
+    'var(--thl-color-purple)',
+    'var(--thl-color-inverse)',
+];
+export const colorAt = (i, s) => s?.color ?? chartColors[i % chartColors.length];
+/** "Nice" axis ticks. */
+export function niceTicks(min, max, count = 5) {
+    if (min === max) {
+        max = min + 1;
+    }
+    const span = max - min;
+    const step0 = span / Math.max(1, count);
+    const mag = 10 ** Math.floor(Math.log10(step0));
+    const norm = step0 / mag;
+    const step = (norm >= 5 ? 10 : norm >= 2 ? 5 : norm >= 1 ? 2 : 1) * mag;
+    const lo = Math.floor(min / step) * step, hi = Math.ceil(max / step) * step;
+    const out = [];
+    for (let v = lo; v <= hi + step / 2; v += step)
+        out.push(Number(v.toFixed(10)));
+    return out;
+}
+function frame(box) {
+    const p = box.padding ?? { top: 10, right: 10, bottom: 28, left: 40 };
+    return { x0: p.left, y0: p.top, w: box.width - p.left - p.right, h: box.height - p.top - p.bottom, p };
+}
+/** Smooth path through points (monotone-ish cardinal spline). */
+export function smoothPath(pts, tension = 0.2) {
+    if (pts.length < 2)
+        return pts.length ? `M${pts[0][0]},${pts[0][1]}` : '';
+    let d = `M${pts[0][0]},${pts[0][1]}`;
+    for (let i = 0; i < pts.length - 1; i++) {
+        const p0 = pts[i - 1] ?? pts[i], p1 = pts[i], p2 = pts[i + 1], p3 = pts[i + 2] ?? p2;
+        const c1 = [p1[0] + (p2[0] - p0[0]) * tension, p1[1] + (p2[1] - p0[1]) * tension];
+        const c2 = [p2[0] - (p3[0] - p1[0]) * tension, p2[1] - (p3[1] - p1[1]) * tension];
+        d += ` C${c1[0].toFixed(2)},${c1[1].toFixed(2)} ${c2[0].toFixed(2)},${c2[1].toFixed(2)} ${p2[0]},${p2[1]}`;
+    }
+    return d;
+}
+const linePath = (pts) => pts.map((p, i) => `${i ? 'L' : 'M'}${p[0]},${p[1]}`).join(' ');
+/** Line / area chart. */
+export function lineChart(series, labels, box, o = {}) {
+    const f = frame(box);
+    const all = series.flatMap((s) => s.data);
+    const ticks = niceTicks(o.min ?? Math.min(0, ...all), o.max ?? Math.max(...all, 1));
+    const lo = ticks[0], hi = ticks[ticks.length - 1];
+    const n = Math.max(1, labels.length - 1);
+    const sx = (i) => f.x0 + (labels.length === 1 ? f.w / 2 : (i / n) * f.w);
+    const sy = (v) => f.y0 + f.h - ((v - lo) / (hi - lo || 1)) * f.h;
+    return {
+        width: box.width,
+        height: box.height,
+        plot: { x: f.x0, y: f.y0, width: f.w, height: f.h },
+        yTicks: ticks.map((value) => ({ value, y: Number(sy(value).toFixed(2)) })),
+        xLabels: labels.map((label, i) => ({ label, x: Number(sx(i).toFixed(2)) })),
+        series: series.map((s, si) => {
+            const pts = s.data.map((v, i) => [Number(sx(i).toFixed(2)), Number(sy(v).toFixed(2))]);
+            const line = o.smooth ? smoothPath(pts) : linePath(pts);
+            const base = Number(sy(Math.max(lo, 0)).toFixed(2));
+            const area = pts.length ? `${line} L${pts[pts.length - 1][0]},${base} L${pts[0][0]},${base} Z` : '';
+            return { name: s.name, color: colorAt(si, s), line, area, points: pts.map(([x, y], i) => ({ x, y, value: s.data[i], label: labels[i] })) };
+        }),
+    };
+}
+/** Grouped or stacked bars. */
+export function barChart(series, labels, box, o = {}) {
+    const f = frame(box);
+    const totals = labels.map((_, i) => series.reduce((a, s) => a + Math.max(0, s.data[i] ?? 0), 0));
+    const max = o.max ?? (o.stacked ? Math.max(...totals, 1) : Math.max(...series.flatMap((s) => s.data), 1));
+    const ticks = niceTicks(0, max);
+    const hi = ticks[ticks.length - 1];
+    const band = f.w / Math.max(1, labels.length);
+    const gap = o.gap ?? 0.3;
+    const inner = band * (1 - gap);
+    const sy = (v) => f.y0 + f.h - (v / hi) * f.h;
+    const bars = [];
+    labels.forEach((label, i) => {
+        const bx = f.x0 + i * band + (band - inner) / 2;
+        let acc = 0;
+        series.forEach((s, si) => {
+            const v = s.data[i] ?? 0;
+            const color = colorAt(si, s);
+            if (o.stacked) {
+                const y = sy(acc + v);
+                bars.push({ x: bx, y, width: inner, height: sy(acc) - y, color, value: v, series: s.name, label });
+                acc += v;
+            }
+            else {
+                const w = inner / series.length;
+                const y = sy(v);
+                bars.push({ x: bx + si * w, y, width: Math.max(1, w - 2), height: f.y0 + f.h - y, color, value: v, series: s.name, label });
+            }
+        });
+    });
+    return {
+        width: box.width,
+        height: box.height,
+        plot: { x: f.x0, y: f.y0, width: f.w, height: f.h },
+        yTicks: ticks.map((value) => ({ value, y: sy(value) })),
+        xLabels: labels.map((label, i) => ({ label, x: f.x0 + i * band + band / 2 })),
+        bars: bars.map((b) => ({ ...b, x: +b.x.toFixed(2), y: +b.y.toFixed(2), width: +b.width.toFixed(2), height: +Math.max(0, b.height).toFixed(2) })),
+    };
+}
+/** Arc path for pie/donut slices. Angles in radians, 0 = 12 o'clock, clockwise. */
+export function arcPath(cx, cy, r, inner, a0, a1) {
+    const full = a1 - a0 >= Math.PI * 2 - 1e-6;
+    if (full)
+        a1 = a0 + Math.PI * 2 - 1e-4;
+    const pt = (rad, a) => [cx + rad * Math.sin(a), cy - rad * Math.cos(a)].map((v) => +v.toFixed(3));
+    const large = a1 - a0 > Math.PI ? 1 : 0;
+    const [x0, y0] = pt(r, a0), [x1, y1] = pt(r, a1);
+    if (inner <= 0)
+        return `M${cx},${cy} L${x0},${y0} A${r},${r} 0 ${large} 1 ${x1},${y1} Z`;
+    const [x2, y2] = pt(inner, a1), [x3, y3] = pt(inner, a0);
+    return `M${x0},${y0} A${r},${r} 0 ${large} 1 ${x1},${y1} L${x2},${y2} A${inner},${inner} 0 ${large} 0 ${x3},${y3} Z`;
+}
+/** Pie / donut. */
+export function pieChart(data, size, o = {}) {
+    const total = data.reduce((a, d) => a + Math.max(0, d.value), 0) || 1;
+    const r = size / 2, cx = r, cy = r, inner = (o.donut ?? 0) * r;
+    let a = 0;
+    return data.map((d, i) => {
+        const sweep = (Math.max(0, d.value) / total) * Math.PI * 2;
+        const a0 = a + (o.padAngle ?? 0) / 2, a1 = a + sweep - (o.padAngle ?? 0) / 2;
+        const mid = a + sweep / 2;
+        a += sweep;
+        const lr = inner ? (r + inner) / 2 : r * 0.62;
+        return {
+            label: d.label,
+            value: d.value,
+            percent: (d.value / total) * 100,
+            color: colorAt(i, d),
+            path: arcPath(cx, cy, r, inner, a0, Math.max(a0, a1)),
+            labelX: +(cx + lr * Math.sin(mid)).toFixed(2),
+            labelY: +(cy - lr * Math.cos(mid)).toFixed(2),
+        };
+    });
+}
+/** Ring gauge: returns stroke-dasharray values for a circle. */
+export function gauge(value, max = 100, size = 120, stroke = 8) {
+    const r = (size - stroke) / 2;
+    const c = 2 * Math.PI * r;
+    const pct = Math.max(0, Math.min(1, value / (max || 1)));
+    return { r, cx: size / 2, cy: size / 2, circumference: +c.toFixed(3), offset: +(c * (1 - pct)).toFixed(3), percent: Math.round(pct * 100) };
+}
+/** Sparkline (line & bar). */
+export function sparkline(data, width, height, type = 'line') {
+    const min = Math.min(...data), max = Math.max(...data);
+    const sy = (v) => +(height - 2 - ((v - min) / (max - min || 1)) * (height - 4)).toFixed(2);
+    if (type === 'bar') {
+        const w = width / data.length;
+        return {
+            bars: data.map((v, i) => ({
+                x: +(i * w + 1).toFixed(2),
+                y: sy(v),
+                width: +Math.max(1, w - 2).toFixed(2),
+                height: +(height - sy(v)).toFixed(2),
+                value: v,
+            })),
+            line: '',
+            area: '',
+        };
+    }
+    const pts = data.map((v, i) => [+((i / Math.max(1, data.length - 1)) * width).toFixed(2), sy(v)]);
+    const line = linePath(pts);
+    return { bars: [], line, area: `${line} L${width},${height} L0,${height} Z`, last: pts[pts.length - 1] };
+}
+export const formatTick = (v, locale) => new Intl.NumberFormat(locale, { notation: Math.abs(v) >= 10000 ? 'compact' : 'standard', maximumFractionDigits: 1 }).format(v);

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@thl-ui/charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "thl-ui charts: dependency-free SVG geometry for line, bar, pie and sparkline charts.",
+  "keywords": [
+    "thl-ui",
+    "ui",
+    "components",
+    "admin",
+    "dashboard",
+    "charts",
+    "svg",
+    "sparkline"
+  ],
+  "license": "MIT",
+  "homepage": "https://thl.tandd.dev/components/charts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tandd.packages/thl-ui.git",
+    "directory": "packages/charts"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/tandd.packages/thl-ui/-/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}