@kubex/zinc 1.0.106 → 1.0.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.0.106",
+  "version": "1.0.107",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",
@@ -46,9 +46,8 @@
     "@lit/task": "^1.0.1",
     "@shoelace-style/localize": "^3.2.1",
     "air-datepicker": "^3.5.3",
-    "apexcharts": "^4.5.0",
-    "chart.js": "^4.4.8",
     "composed-offset-position": "^0.0.6",
+    "echarts": "^6.0.0",
     "emoji-mart": "^5.6.0",
     "lit": "^2.7.6",
     "marked": "^18.0.2",
@@ -77,9 +76,9 @@
     "custom-element-vs-code-integration": "^1.5.0",
     "custom-element-vuejs-integration": "^1.4.0",
     "del": "^8.0.0",
-    "esbuild": "^0.25.0",
+    "esbuild": "^0.27.7",
     "esbuild-plugin-replace": "^1.4.0",
-    "esbuild-sass-plugin": "^3.3.1",
+    "esbuild-sass-plugin": "^3.7.0",
     "eslint": "^8.57.1",
     "eslint-plugin-chai-expect": "^3.1.0",
     "eslint-plugin-chai-friendly": "^0.7.2",
@@ -94,7 +93,7 @@
     "jsdom": "^26.0.0",
     "lodash": "^4.17.21",
     "lunr": "^2.3.9",
-    "markdown-it": "^14.1.0",
+    "markdown-it": "^14.1.1",
     "markdown-it-container": "^4.0.0",
     "markdown-it-ins": "^4.0.0",
     "markdown-it-kbd": "^2.2.2",

package/src/components/chart/builders.test.ts

@@ -0,0 +1,211 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call */
+import {
+  buildAreaOption,
+  buildBarOption,
+  type BuilderProps,
+  buildLineOption,
+  buildSankeyOption,
+} from './builders';
+import { expect } from '@open-wc/testing';
+
+const baseProps: BuilderProps = {
+  type: 'bar',
+  data: [{ name: 'Sales', data: [10, 20, 30] }],
+  categories: ['Q1', 'Q2', 'Q3'],
+  stacked: false,
+  enableAnimations: false,
+  datapointSize: 1,
+  theme: 'light',
+};
+
+describe('buildBarOption', () => {
+  it('maps a single series into bar type with categories', () => {
+    const opt = buildBarOption(baseProps);
+    expect(opt.series).to.have.lengthOf(1);
+    expect((opt.series as any[])[0].type).to.equal('bar');
+    expect((opt.series as any[])[0].name).to.equal('Sales');
+    expect((opt.series as any[])[0].data).to.deep.equal([10, 20, 30]);
+    expect((opt.xAxis as any).type).to.equal('category');
+    expect((opt.xAxis as any).data).to.deep.equal(['Q1', 'Q2', 'Q3']);
+  });
+
+  it('applies stacking when stacked=true', () => {
+    const opt = buildBarOption({
+      ...baseProps,
+      stacked: true,
+      data: [
+        { name: 'A', data: [1, 2] },
+        { name: 'B', data: [3, 4] },
+      ],
+    });
+    expect((opt.series as any[])[0].stack).to.equal('total');
+    expect((opt.series as any[])[1].stack).to.equal('total');
+  });
+
+  it('does not stack when stacked=false', () => {
+    const opt = buildBarOption({
+      ...baseProps,
+      data: [
+        { name: 'A', data: [1, 2] },
+        { name: 'B', data: [3, 4] },
+      ],
+    });
+    expect((opt.series as any[])[0].stack).to.be.undefined;
+  });
+
+  it('appends y-axis suffix via formatter', () => {
+    const opt = buildBarOption({ ...baseProps, yAxisAppend: '%' });
+    const formatter = ((opt.yAxis as any).axisLabel.formatter) as (v: number) => string;
+    expect(formatter(42)).to.equal('42%');
+  });
+
+  it('maps per-series color to itemStyle.color', () => {
+    const opt = buildBarOption({
+      ...baseProps,
+      data: [{ name: 'Sales', data: [1, 2, 3], color: '#ff0000' }],
+    });
+    expect((opt.series as any[])[0].itemStyle.color).to.equal('#ff0000');
+  });
+
+  it('maps colors array to option.color', () => {
+    const opt = buildBarOption({ ...baseProps, colors: ['#abc', '#def'] });
+    expect(opt.color).to.deep.equal(['#abc', '#def']);
+  });
+
+  it('disables animation by default', () => {
+    const opt = buildBarOption(baseProps);
+    expect(opt.animation).to.equal(false);
+  });
+
+  it('enables animation when enableAnimations=true', () => {
+    const opt = buildBarOption({ ...baseProps, enableAnimations: true });
+    expect(opt.animation).to.equal(true);
+  });
+});
+
+describe('buildLineOption', () => {
+  const baseLineProps: BuilderProps = {
+    type: 'line',
+    data: [{ name: 'Revenue', data: [10, 20, 30] }],
+    categories: ['Jan', 'Feb', 'Mar'],
+    stacked: false,
+    enableAnimations: false,
+    datapointSize: 3,
+    theme: 'light',
+  };
+
+  it('maps a series to line type', () => {
+    const opt = buildLineOption(baseLineProps);
+    expect((opt.series as any[])[0].type).to.equal('line');
+  });
+
+  it('applies symbolSize from datapointSize', () => {
+    const opt = buildLineOption(baseLineProps);
+    expect((opt.series as any[])[0].symbolSize).to.equal(3);
+  });
+
+  it('uses datetime x-axis when xAxisType=datetime', () => {
+    const opt = buildLineOption({ ...baseLineProps, xAxisType: 'datetime' });
+    expect((opt.xAxis as any).type).to.equal('time');
+  });
+
+  it('does not apply areaStyle for plain line', () => {
+    const opt = buildLineOption(baseLineProps);
+    expect((opt.series as any[])[0].areaStyle).to.be.undefined;
+  });
+});
+
+describe('buildAreaOption', () => {
+  const baseAreaProps: BuilderProps = {
+    type: 'area',
+    data: [{ name: 'Traffic', data: [100, 200, 300] }],
+    categories: ['Mon', 'Tue', 'Wed'],
+    stacked: false,
+    enableAnimations: false,
+    datapointSize: 1,
+    theme: 'light',
+  };
+
+  it('maps a series to line type with areaStyle set', () => {
+    const opt = buildAreaOption(baseAreaProps);
+    expect((opt.series as any[])[0].type).to.equal('line');
+    expect((opt.series as any[])[0].areaStyle).to.be.an('object');
+  });
+
+  it('applies stacking when stacked=true', () => {
+    const opt = buildAreaOption({
+      ...baseAreaProps,
+      stacked: true,
+      data: [
+        { name: 'A', data: [1, 2] },
+        { name: 'B', data: [3, 4] },
+      ],
+    });
+    expect((opt.series as any[])[0].stack).to.equal('total');
+  });
+});
+
+describe('buildSankeyOption', () => {
+  const sankeyProps: BuilderProps = {
+    type: 'sankey',
+    data: [{
+      name: 'Flow',
+      data: [
+        { source: 'A', target: 'B', value: 10 },
+        { source: 'A', target: 'C', value: 5 },
+        { source: 'B', target: 'D', value: 7 },
+      ],
+    }],
+    categories: [],
+    stacked: false,
+    enableAnimations: false,
+    datapointSize: 1,
+    theme: 'light',
+  };
+
+  it('builds one sankey series with links mapped from edges', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    const series = (opt.series as any[])[0];
+    expect(series.type).to.equal('sankey');
+    expect(series.links).to.deep.equal([
+      { source: 'A', target: 'B', value: 10 },
+      { source: 'A', target: 'C', value: 5 },
+      { source: 'B', target: 'D', value: 7 },
+    ]);
+  });
+
+  it('derives unique nodes from edge source/target values', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    const series = (opt.series as any[])[0];
+    const names = series.data.map((n: any) => n.name).sort();
+    expect(names).to.deep.equal(['A', 'B', 'C', 'D']);
+  });
+
+  it('omits xAxis and yAxis (sankey has no cartesian axes)', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    expect(opt.xAxis).to.be.undefined;
+    expect(opt.yAxis).to.be.undefined;
+  });
+
+  it('passes through explicit nodes when provided on the series object', () => {
+    const withNodes = {
+      ...sankeyProps,
+      data: [{
+        name: 'Flow',
+        nodes: [
+          { name: 'A', itemStyle: { color: '#f00' } },
+          { name: 'B' }, { name: 'C' }, { name: 'D' },
+        ],
+        data: sankeyProps.data[0].data,
+      }] as any,
+    };
+    const opt = buildSankeyOption(withNodes);
+    const series = (opt.series as any[])[0];
+    expect(series.data[0]).to.deep.equal({ name: 'A', itemStyle: { color: '#f00' } });
+  });
+
+  it('uses tooltip trigger=item (not axis) for sankey', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    expect((opt.tooltip as any).trigger).to.equal('item');
+  });
+});

package/src/components/chart/builders.ts

@@ -0,0 +1,221 @@
+// src/components/chart/builders.ts
+import type { EChartsOption } from 'echarts';
+
+export type ChartType = 'area' | 'bar' | 'line' | 'sankey';
+
+export interface SeriesItem {
+  name: string;
+  data: any[];
+  color?: string;
+}
+
+export interface SankeyEdge {
+  source: string;
+  target: string;
+  value: number;
+}
+
+export interface BuilderProps {
+  type: ChartType;
+  data: SeriesItem[];
+  categories: string[];
+  xAxisType?: 'datetime' | 'category' | 'numeric';
+  yAxisAppend?: string;
+  stacked: boolean;
+  enableAnimations: boolean | number;
+  datapointSize: number;
+  colors?: string[];
+  theme: 'light' | 'dark';
+  smooth?: boolean;
+  scale?: boolean | number;
+  textColor?: string;
+  borderColor?: string;
+}
+
+function commonOption(props: BuilderProps): EChartsOption {
+  const fallback = props.theme === 'dark' ? 'rgb(161, 161, 170)' : 'rgb(113, 113, 122)';
+  const textColor = props.textColor ?? fallback;
+  const animEnabled = props.enableAnimations !== false && props.enableAnimations !== 0;
+  const animDuration = typeof props.enableAnimations === 'number' ? props.enableAnimations : 1500;
+  return {
+    animation: animEnabled,
+    animationDuration: animDuration,
+    animationEasing: 'cubicOut',
+    ...(props.colors ? { color: props.colors } : {}),
+    textStyle: { color: textColor },
+    tooltip: {
+      trigger: 'axis',
+      valueFormatter: props.yAxisAppend
+        ? (v: number | string) => `${v}${props.yAxisAppend}`
+        : undefined,
+    },
+    legend: {
+      top: 0,
+      right: 0,
+      icon: 'circle',
+      textStyle: { color: textColor },
+    },
+    grid: {
+      left: 40,
+      right: 20,
+      top: 40,
+      bottom: 30,
+    },
+  };
+}
+
+function hasNoData(data: SeriesItem[]): boolean {
+  return data.length === 0 || data.every((s) => !s.data || s.data.length === 0);
+}
+
+function buildYAxis(props: BuilderProps) {
+  const emptyOpts = hasNoData(props.data) ? { min: 0, max: 6 } : {};
+  const scaleOpts = props.scale
+    ? {
+        scale: true,
+        ...(typeof props.scale === 'number'
+          ? { boundaryGap: [`${props.scale}%`, `${props.scale}%`] as [string, string] }
+          : {}),
+      }
+    : {};
+  const splitLineOpts = props.borderColor
+    ? { splitLine: { lineStyle: { color: props.borderColor } } }
+    : {};
+  return {
+    type: 'value' as const,
+    ...splitLineOpts,
+    ...emptyOpts,
+    ...scaleOpts,
+    axisLabel: props.yAxisAppend
+      ? { formatter: (v: number) => `${v}${props.yAxisAppend}` }
+      : {},
+  };
+}
+
+function buildXAxis(props: BuilderProps, edgeToEdge = false) {
+  const axisLineOpts = props.borderColor
+    ? { axisLine: { lineStyle: { color: props.borderColor } } }
+    : {};
+  if (props.xAxisType === 'datetime') return { type: 'time' as const, ...axisLineOpts };
+  if (props.xAxisType === 'numeric') return { type: 'value' as const, ...axisLineOpts };
+  return {
+    type: 'category' as const,
+    data: props.categories,
+    ...(edgeToEdge ? { boundaryGap: false } : {}),
+    ...axisLineOpts,
+  };
+}
+
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return */
+function normalizeData(data: any[]): any[] {
+  return data.map((d: any) => {
+    if (d && typeof d === 'object' && !Array.isArray(d) && 'x' in d && 'y' in d) {
+      return [d.x, d.y];
+    }
+    return d;
+  });
+}
+/* eslint-enable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return */
+
+function seriesFromProps(
+  props: BuilderProps,
+  seriesType: 'bar' | 'line',
+  extra: (s: SeriesItem) => Record<string, unknown> = () => ({}),
+) {
+  return props.data.map((s) => ({
+    type: seriesType,
+    name: s.name,
+    data: normalizeData(s.data),
+    ...(s.color ? { itemStyle: { color: s.color } } : {}),
+    ...(props.stacked ? { stack: 'total' } : {}),
+    ...(props.enableAnimations !== false && props.enableAnimations !== 0 && seriesType === 'bar'
+      ? { animationDelay: (idx: number) => idx * 50 }
+      : {}),
+    ...extra(s),
+  }));
+}
+
+export function buildBarOption(props: BuilderProps): EChartsOption {
+  return {
+    ...commonOption(props),
+    xAxis: buildXAxis(props),
+    yAxis: buildYAxis(props),
+    series: seriesFromProps(props, 'bar'),
+  };
+}
+
+export function buildLineOption(props: BuilderProps): EChartsOption {
+  return {
+    ...commonOption(props),
+    xAxis: buildXAxis(props, true),
+    yAxis: buildYAxis(props),
+    series: seriesFromProps(props, 'line', () => ({
+      symbolSize: props.datapointSize,
+      smooth: props.smooth,
+    })),
+  };
+}
+
+export function buildAreaOption(props: BuilderProps): EChartsOption {
+  return {
+    ...commonOption(props),
+    xAxis: buildXAxis(props, true),
+    yAxis: buildYAxis(props),
+    series: seriesFromProps(props, 'line', () => ({
+      symbolSize: props.datapointSize,
+      smooth: props.smooth,
+      areaStyle: { opacity: 0.1 },
+    })),
+  };
+}
+
+function deriveNodes(edges: SankeyEdge[]): { name: string }[] {
+  const seen = new Set<string>();
+  const nodes: { name: string }[] = [];
+  for (const edge of edges) {
+    if (!seen.has(edge.source)) {
+      seen.add(edge.source);
+      nodes.push({ name: edge.source });
+    }
+    if (!seen.has(edge.target)) {
+      seen.add(edge.target);
+      nodes.push({ name: edge.target });
+    }
+  }
+  return nodes;
+}
+
+export function buildSankeyOption(props: BuilderProps): EChartsOption {
+  const first = props.data[0] ?? { name: '', data: [] };
+  const edges = (first.data ?? []) as SankeyEdge[];
+  const explicitNodes = (first as { nodes?: { name: string }[] }).nodes;
+  const nodes = explicitNodes ?? deriveNodes(edges);
+  const fallback = props.theme === 'dark' ? 'rgb(161, 161, 170)' : 'rgb(113, 113, 122)';
+  const textColor = props.textColor ?? fallback;
+
+  const animEnabled = props.enableAnimations !== false && props.enableAnimations !== 0;
+  const animDuration = typeof props.enableAnimations === 'number' ? props.enableAnimations : 1500;
+  return {
+    animation: animEnabled,
+    animationDuration: animDuration,
+    animationEasing: 'cubicOut',
+    ...(props.colors ? { color: props.colors } : {}),
+    textStyle: { color: textColor },
+    tooltip: { trigger: 'item' },
+    series: [{
+      type: 'sankey',
+      name: first.name,
+      data: nodes,
+      links: edges,
+      label: {
+        color: textColor,
+        textBorderWidth: 0,
+      },
+      lineStyle: {
+        color: 'source',
+        opacity: props.theme === 'dark' ? 0.4 : 0.3,
+      },
+      emphasis: { focus: 'adjacency' },
+    }],
+  };
+}