@antelopejs/dms 0.0.1

package/frontend-vue/tests/chart-colors.test.ts

@@ -0,0 +1,177 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { reactive } from "vue";
+import type { ChartColorValue } from "@antelopejs/interface-dms/base/chart";
+import { useApexChart } from "../layers/dms-ui/app/composables/chart/useApexChart";
+import type { UseApexChartInput } from "../layers/dms-ui/app/composables/chart/useApexChart.types";
+import {
+  clearChartColorCache,
+  readThemeMuted,
+  resolveChartColor,
+  resolveChartColors,
+} from "../layers/dms-ui/app/composables/chart/useChartTheme";
+
+const FALLBACK = "#7c3aed";
+const LIGHT = "rgb(124, 58, 237)";
+const DARK = "rgb(167, 139, 250)";
+const TOKENS: ChartColorValue[] = [
+  "primary-500",
+  "accent-50",
+  "neutral-950",
+  "--usage",
+  "var(--usage)",
+];
+let computedColor = LIGHT;
+const probe = { style: { backgroundColor: "" } };
+const appendChild = vi.fn();
+const removeChild = vi.fn();
+
+function mockBrowser() {
+  vi.stubGlobal("document", {
+    body: { appendChild, removeChild },
+    createElement: vi.fn(() => probe),
+  });
+  vi.stubGlobal("getComputedStyle", () => ({ backgroundColor: computedColor }));
+}
+
+beforeEach(() => {
+  computedColor = LIGHT;
+  clearChartColorCache();
+  vi.clearAllMocks();
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe("chart color tokens", () => {
+  it("falls back without accessing the DOM during SSR", () => {
+    expect(resolveChartColors(TOKENS)).toEqual(TOKENS.map(() => FALLBACK));
+    expect(resolveChartColor(undefined)).toBe(FALLBACK);
+  });
+
+  it.each([
+    ["primary", "--ui-primary"],
+    ["neutral", "--ui-text-toned"],
+    ["primary-500", "--ui-color-primary-500"],
+    ["accent-50", "--ui-color-primary-50"],
+    ["neutral-950", "--ui-color-neutral-950"],
+    ["--usage", "--usage"],
+    ["var(--usage)", "--usage"],
+  ])("resolves %s via %s", (input, variable) => {
+    mockBrowser();
+    expect(resolveChartColor(input)).toBe(LIGHT);
+    expect(probe.style.backgroundColor).toBe(`var(${variable}, ${FALLBACK})`);
+    expect(removeChild).toHaveBeenCalledWith(probe);
+  });
+
+  it.each([
+    "#abcdef",
+    "rgb(1, 2, 3)",
+    "hsl(0, 50%, 50%)",
+    "unknown",
+    "primary-123",
+  ])("preserves legacy passthrough %s", (color) => {
+    expect(resolveChartColor(color)).toBe(color);
+  });
+
+  it.each(["", "transparent", "rgba(0, 0, 0, 0)"])(
+    "falls back for unusable computed color %s",
+    (color) => {
+      mockBrowser();
+      computedColor = color;
+      expect(resolveChartColor("--missing")).toBe(FALLBACK);
+    },
+  );
+
+  it("shares cache entries across equivalent spellings", () => {
+    mockBrowser();
+    resolveChartColors([
+      "primary-500",
+      "--ui-color-primary-500",
+      "var(--ui-color-primary-500)",
+    ]);
+    expect(appendChild).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not cache SSR fallback before hydration", () => {
+    expect(resolveChartColor("primary-500")).toBe(FALLBACK);
+    mockBrowser();
+    expect(resolveChartColor("primary-500")).toBe(LIGHT);
+  });
+
+  it("keeps text and chart fallbacks independent for the same variable", () => {
+    mockBrowser();
+    computedColor = "transparent";
+    expect(readThemeMuted()).toBe("#6b7280");
+    expect(resolveChartColor("--ui-text-muted")).toBe(FALLBACK);
+  });
+
+  it("recomputes Apex colors after theme cache invalidation and revision", () => {
+    mockBrowser();
+    const input = reactive<UseApexChartInput>({
+      type: "line",
+      series: [],
+      colors: TOKENS,
+      themeRevision: 0,
+    });
+    const chart = useApexChart(() => input);
+    expect(chart.options.value.colors).toEqual(TOKENS.map(() => LIGHT));
+    computedColor = DARK;
+    clearChartColorCache();
+    input.themeRevision = 1;
+    expect(chart.options.value.colors).toEqual(TOKENS.map(() => DARK));
+  });
+
+  it("resolves series overrides and annotation colors", () => {
+    mockBrowser();
+    const chart = useApexChart(() => ({
+      type: "line",
+      series: [{ name: "usage", color: "primary-500", data: [] }],
+      annotations: [{ y: 10, color: "var(--usage)" }],
+    }));
+    expect(chart.options.value.colors).toEqual([LIGHT]);
+    expect(chart.series.value).toEqual([
+      expect.objectContaining({ color: LIGHT }),
+    ]);
+    expect(chart.options.value.annotations).toMatchObject({
+      yaxis: [expect.objectContaining({ borderColor: LIGHT })],
+    });
+  });
+
+  it("refreshes mixed series colors without mutating the input", () => {
+    mockBrowser();
+    const input = reactive<UseApexChartInput>({
+      type: "mixed",
+      series: [{ name: "usage", data: [] }],
+      seriesDefs: [{ name: "usage", type: "line", color: "primary-500" }],
+      themeRevision: 0,
+    });
+    const chart = useApexChart(() => input);
+    expect(chart.series.value).toEqual([
+      expect.objectContaining({ color: LIGHT }),
+    ]);
+    computedColor = DARK;
+    clearChartColorCache();
+    input.themeRevision = 1;
+    expect(chart.series.value).toEqual([
+      expect.objectContaining({ color: DARK }),
+    ]);
+    expect(input.series[0]?.color).toBeUndefined();
+    expect(input.seriesDefs?.[0]?.color).toBe("primary-500");
+  });
+
+  it("normalizes modern color spaces through an sRGB canvas", () => {
+    mockBrowser();
+    computedColor = "oklch(0.5 0.2 280)";
+    const context = {
+      fillStyle: "",
+      fillRect: vi.fn(),
+      getImageData: () => ({ data: [92, 76, 200, 255] }),
+    };
+    vi.mocked(document.createElement).mockReturnValueOnce(
+      probe as unknown as HTMLDivElement,
+    );
+    vi.mocked(document.createElement).mockReturnValueOnce({
+      getContext: () => context,
+    } as unknown as HTMLCanvasElement);
+    expect(resolveChartColor("primary-500")).toBe("rgba(92, 76, 200, 1)");
+    expect(context.fillStyle).toBe(computedColor);
+  });
+});

package/frontend-vue/tests/chart-options.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import type {
+  ChartXAxis as ServerXAxis,
+  LineChartProps,
+} from "@antelopejs/interface-dms/base/chart";
+import { reactive } from "vue";
+import { useApexChart } from "../layers/dms-ui/app/composables/chart/useApexChart";
+import type { UseApexChartInput } from "../layers/dms-ui/app/composables/chart/useApexChart.types";
+import type {
+  ChartAnnotation,
+  ChartSeries,
+  ChartXAxis,
+} from "../layers/dms-ui/app/composables/chart/types";
+
+const SERIES: ChartSeries[] = [
+  { name: "p50 – p99", data: [{ x: "10:00", y: [12, 48] }] },
+];
+
+describe("typed X axis", () => {
+  it("keeps the server settings serializable and the formatter Vue-only", () => {
+    expectTypeOf<ChartXAxis>().toEqualTypeOf<ServerXAxis>();
+    expectTypeOf<LineChartProps>().not.toHaveProperty("xAxisFormatter");
+    const settings: ServerXAxis = {
+      tickAmount: 2,
+      rotate: 0,
+      hideOverlappingLabels: true,
+      datetimeFormat: "dd MMM",
+    };
+    expect(JSON.parse(JSON.stringify(settings))).toEqual(settings);
+  });
+
+  it("preserves defaults when settings are absent or empty", () => {
+    const baseline = sectionOf(optionsFor({}), "xaxis");
+    expect(sectionOf(optionsFor({ xAxis: {} }), "xaxis")).toEqual(baseline);
+    expect(baseline.type).toBe("category");
+    expect(baseline.tickAmount).toBeUndefined();
+    expect(sectionOf(baseline, "labels").datetimeUTC).toBe(false);
+  });
+
+  it("keeps theme labels and explicit zero/false settings", () => {
+    const axis = sectionOf(
+      optionsFor({
+        xAxis: {
+          tickAmount: 2,
+          rotate: 0,
+          hideOverlappingLabels: false,
+        },
+      }),
+      "xaxis",
+    );
+    expect(axis.tickAmount).toBe(2);
+    expect(sectionOf(axis, "labels")).toMatchObject({
+      rotate: 0,
+      hideOverlappingLabels: false,
+      style: { fontSize: "11px" },
+    });
+    expect(axis.axisBorder).toEqual({ show: false });
+  });
+
+  it.each(["category", "numeric", "datetime"] as const)(
+    "formats %s at runtime",
+    (xaxisType) => {
+      const formatter = (value: string, timestamp?: number) =>
+        `${timestamp ?? value} units`;
+      const axis = sectionOf(
+        optionsFor({
+          xaxisType,
+          xAxis: { datetimeFormat: "dd MMM" },
+          xAxisFormatter: formatter,
+        }),
+        "xaxis",
+      );
+      const labels = sectionOf(axis, "labels");
+      expect(labels.formatter).toBe(formatter);
+      expect(labels.format).toBe(
+        xaxisType === "datetime" ? "dd MMM" : undefined,
+      );
+      expect(formatter("16")).toBe("16 units");
+      expect(formatter("date", 123)).toBe("123 units");
+    },
+  );
+
+  it("keeps rawOptions as the final whole-section override", () => {
+    const rawAxis = { type: "numeric", tickAmount: 7 };
+    expect(
+      sectionOf(
+        optionsFor({
+          xAxis: { tickAmount: 2 },
+          xAxisFormatter: (value) => `Day ${value}`,
+          rawOptions: [{ key: "xaxis", value: JSON.stringify(rawAxis) }],
+        }),
+        "xaxis",
+      ),
+    ).toEqual(rawAxis);
+  });
+
+  it("updates and removes settings and formatters reactively", () => {
+    const input = reactive<UseApexChartInput>({
+      type: "line",
+      series: SERIES,
+      xAxis: { tickAmount: 2 },
+      xAxisFormatter: (value) => `Jour ${value}`,
+    });
+    const chart = useApexChart(() => input);
+    expect(sectionOf(chart.options.value, "xaxis").tickAmount).toBe(2);
+    input.xAxis = { tickAmount: 4 };
+    expect(sectionOf(chart.options.value, "xaxis").tickAmount).toBe(4);
+    input.xAxis = undefined;
+    input.xAxisFormatter = undefined;
+    expect(sectionOf(chart.options.value, "xaxis").tickAmount).toBeUndefined();
+    expect(
+      sectionOf(sectionOf(chart.options.value, "xaxis"), "labels").formatter,
+    ).toBeUndefined();
+  });
+});
+
+function optionsFor(
+  input: Partial<UseApexChartInput>,
+): Record<string, unknown> {
+  const chart = useApexChart(() => ({
+    type: "line",
+    series: SERIES,
+    ...input,
+  }));
+  return chart.options.value;
+}
+
+function sectionOf(
+  options: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> {
+  return options[key] as Record<string, unknown>;
+}
+
+describe("rangeArea", () => {
+  it("maps to the Apex rangeArea type", () => {
+    const chart = useApexChart(() => ({ type: "rangeArea", series: SERIES }));
+    expect(chart.apexType.value).toBe("rangeArea");
+  });
+
+  it("fills the band with a flat opacity", () => {
+    const fill = sectionOf(optionsFor({ type: "rangeArea" }), "fill");
+    expect(fill.opacity).toBeGreaterThan(0);
+    expect(fill.type).toBeUndefined();
+  });
+
+  it("honours an explicit fillOpacity", () => {
+    const fill = sectionOf(
+      optionsFor({ type: "rangeArea", fillOpacity: 0.5 }),
+      "fill",
+    );
+    expect(fill.opacity).toBe(0.5);
+  });
+
+  it("promotes a mixed chart carrying a band to the rangeArea type", () => {
+    const chart = useApexChart(() => ({
+      type: "mixed",
+      series: SERIES,
+      seriesDefs: [
+        { name: "p50 – p99", type: "rangeArea" },
+        { name: "p95", type: "line" },
+      ],
+    }));
+    expect(chart.apexType.value).toBe("rangeArea");
+    const config = sectionOf(chart.options.value, "chart");
+    expect(config.type).toBe("rangeArea");
+  });
+
+  it("keeps a band-free mixed chart on the line type", () => {
+    const chart = useApexChart(() => ({
+      type: "mixed",
+      series: SERIES,
+      seriesDefs: [{ name: "orders", type: "column" }],
+    }));
+    expect(chart.apexType.value).toBe("line");
+  });
+});
+
+describe("curve", () => {
+  it("defaults to the type's own curve", () => {
+    expect(sectionOf(optionsFor({}), "stroke").curve).toBe("smooth");
+  });
+
+  it("applies stepline", () => {
+    expect(sectionOf(optionsFor({ curve: "stepline" }), "stroke").curve).toBe(
+      "stepline",
+    );
+  });
+
+  it("takes precedence over smooth", () => {
+    const stroke = sectionOf(
+      optionsFor({ curve: "stepline", smooth: false }),
+      "stroke",
+    );
+    expect(stroke.curve).toBe("stepline");
+  });
+
+  it("still lets smooth false fall back to straight", () => {
+    expect(sectionOf(optionsFor({ smooth: false }), "stroke").curve).toBe(
+      "straight",
+    );
+  });
+});
+
+describe("annotations", () => {
+  const CAP: ChartAnnotation = { y: 250, label: "spend cap", color: "#f59e0b" };
+
+  it("stays absent when none are declared", () => {
+    expect(optionsFor({}).annotations).toBeUndefined();
+    expect(optionsFor({ annotations: [] }).annotations).toBeUndefined();
+  });
+
+  it("maps a reference line onto the Y axis", () => {
+    const annotations = sectionOf(
+      optionsFor({ annotations: [CAP] }),
+      "annotations",
+    );
+    const [line] = annotations.yaxis as Array<Record<string, unknown>>;
+    expect(line!.y).toBe(250);
+    expect(line!.borderColor).toBe("#f59e0b");
+    expect(line!.strokeDashArray).toBeGreaterThan(0);
+    expect((line!.label as Record<string, unknown>).text).toBe("spend cap");
+  });
+
+  it("draws a solid line when dashed is false", () => {
+    const annotations = sectionOf(
+      optionsFor({ annotations: [{ ...CAP, dashed: false }] }),
+      "annotations",
+    );
+    const [line] = annotations.yaxis as Array<Record<string, unknown>>;
+    expect(line!.strokeDashArray).toBe(0);
+  });
+
+  it("resolves theme color names to usable CSS colors", () => {
+    const annotations = sectionOf(
+      optionsFor({ annotations: [{ y: 4, label: "cap", color: "warning" }] }),
+      "annotations",
+    );
+    const [line] = annotations.yaxis as Array<Record<string, unknown>>;
+    expect(line!.borderColor).not.toBe("warning");
+    expect(String(line!.borderColor)).toMatch(/^(#|rgb|hsl)/);
+    expect((line!.label as Record<string, unknown>).style).toMatchObject({
+      color: line!.borderColor,
+    });
+  });
+
+  it("shades a band when y2 is set", () => {
+    const annotations = sectionOf(
+      optionsFor({ annotations: [{ y: 10, y2: 40, color: "#10b981" }] }),
+      "annotations",
+    );
+    const [band] = annotations.yaxis as Array<Record<string, unknown>>;
+    expect(band!.y2).toBe(40);
+    expect(band!.fillColor).toBe("#10b981");
+    expect(band!.opacity).toBeGreaterThan(0);
+    expect(band!.label).toBeUndefined();
+  });
+});
+
+describe("syncGroup", () => {
+  it("leaves the chart ungrouped by default", () => {
+    const chart = sectionOf(optionsFor({}), "chart");
+    expect(chart.group).toBeUndefined();
+    expect(chart.id).toBeUndefined();
+  });
+
+  it("exposes the group and a per-chart id", () => {
+    const chart = sectionOf(
+      optionsFor({ syncGroup: "service-metrics", chartId: "latency" }),
+      "chart",
+    );
+    expect(chart.group).toBe("service-metrics");
+    expect(chart.id).toBe("latency");
+  });
+
+  it("leaves the id to Apex when no chart id is given", () => {
+    const chart = sectionOf(optionsFor({ syncGroup: "grid" }), "chart");
+    expect(chart.group).toBe("grid");
+    expect(chart.id).toBeUndefined();
+  });
+});

package/frontend-vue/tests/chart-series-styles.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import { ref } from "vue";
+import { useApexChart } from "../layers/dms-ui/app/composables/chart/useApexChart";
+import type { ChartSeries } from "../layers/dms-ui/app/composables/chart/types";
+import type { UseApexChartInput } from "../layers/dms-ui/app/composables/chart/useApexChart.types";
+
+const PLAIN: ChartSeries = { name: "Actual", data: [1, 2, 3] };
+const STYLED: ChartSeries = {
+  name: "Estimate",
+  data: [2, 3, 4],
+  strokeWidth: 2,
+  strokeDashArray: 6,
+};
+
+function strokeFor(input: Partial<UseApexChartInput> = {}) {
+  return useApexChart(() => ({ type: "line", series: [PLAIN], ...input }))
+    .options.value.stroke;
+}
+
+describe("series stroke styles", () => {
+  it("preserves scalar defaults and comparison defaults when omitted", () => {
+    expect(strokeFor()).toEqual({
+      curve: "smooth",
+      width: 3,
+      lineCap: "round",
+    });
+    expect(
+      strokeFor({ series: [PLAIN, PLAIN], comparisonSeriesCount: 1 }),
+    ).toMatchObject({ width: [3, 1.5], dashArray: [0, 4] });
+  });
+
+  it("keeps styles attached through reactive reorder, insertion and removal", () => {
+    const series = ref([PLAIN, STYLED]);
+    const chart = useApexChart(() => ({ type: "line", series: series.value }));
+    expect(chart.options.value.stroke).toMatchObject({
+      width: [3, 2],
+      dashArray: [0, 6],
+    });
+    series.value = [STYLED, PLAIN];
+    expect(chart.options.value.stroke).toMatchObject({
+      width: [2, 3],
+      dashArray: [6, 0],
+    });
+    series.value = [PLAIN, STYLED, PLAIN];
+    expect(chart.options.value.stroke).toMatchObject({
+      width: [3, 2, 3],
+      dashArray: [0, 6, 0],
+    });
+    series.value = [STYLED];
+    expect(chart.options.value.stroke).toMatchObject({
+      width: [2],
+      dashArray: [6],
+    });
+    series.value = [PLAIN];
+    expect(chart.options.value.stroke).toEqual(strokeFor());
+    series.value = [];
+    expect(chart.options.value.stroke).toEqual(strokeFor());
+  });
+
+  it("overrides global width and comparison styling, including explicit zero", () => {
+    const solid: ChartSeries = { ...PLAIN, strokeWidth: 0, strokeDashArray: 0 };
+    expect(
+      strokeFor({
+        series: [STYLED, solid],
+        strokeWidth: 8,
+        comparisonSeriesCount: 1,
+      }),
+    ).toMatchObject({ width: [2, 0], dashArray: [6, 0] });
+    expect(
+      strokeFor({
+        series: [STYLED, PLAIN],
+        strokeWidth: 8,
+        comparisonSeriesCount: 1,
+      }),
+    ).toMatchObject({ width: [2, 8], dashArray: [6, 4] });
+  });
+
+  it.each(["solid", "dimmed"] as const)(
+    "overrides %s comparison dashes",
+    (comparisonStyle) => {
+      expect(
+        strokeFor({
+          series: [PLAIN, STYLED],
+          comparisonSeriesCount: 1,
+          comparisonStyle,
+        }),
+      ).toMatchObject({ width: [3, 2], dashArray: [0, 6] });
+    },
+  );
+
+  it("resolves each property independently", () => {
+    expect(
+      strokeFor({
+        series: [
+          { ...PLAIN, strokeWidth: 5 },
+          { ...PLAIN, strokeDashArray: 3 },
+        ],
+      }),
+    ).toMatchObject({ width: [5, 3], dashArray: [0, 3] });
+  });
+
+  it("preserves styles when mixed definitions project type and color", () => {
+    const chart = useApexChart(() => ({
+      type: "mixed",
+      series: [PLAIN, STYLED],
+      comparisonSeriesCount: 1,
+      seriesDefs: [
+        { name: "Actual", type: "column" },
+        { name: "Estimate", type: "line", color: "#ff0000" },
+      ],
+    }));
+    expect(chart.options.value.stroke).toMatchObject({
+      width: [3, 2],
+      dashArray: [0, 6],
+    });
+    expect(chart.series.value).toEqual([
+      { ...PLAIN, type: "column" },
+      { ...STYLED, type: "line", color: "#ff0000" },
+    ]);
+  });
+
+  it("keeps rawOptions as whole-section replacement, not a deep merge", () => {
+    const rawStroke = { width: [9], dashArray: [1] };
+    expect(
+      strokeFor({
+        series: [STYLED],
+        rawOptions: [{ key: "stroke", value: JSON.stringify(rawStroke) }],
+      }),
+    ).toEqual(rawStroke);
+  });
+});

package/frontend-vue/tests/chart-value-precision.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatValue,
+  formatValueParts,
+} from "../layers/dms-ui/app/composables/chart/formatValue";
+import type { ValueFormat } from "../layers/dms-ui/app/composables/chart/types";
+
+describe("chart value precision", () => {
+  it("preserves all legacy defaults", () => {
+    expect(formatValue(9.39, "currency", "fr-FR")).toBe("9 €");
+    expect(formatValue(9.3912)).toBe("9.391");
+    expect(formatValue(9.39, "percent")).toBe("9.4%");
+    expect(formatValue(1234, "compact")).toBe("1.2K");
+  });
+
+  it.each(["fr-FR", "en-GB", "ja-JP", "ar-KW"])(
+    "uses native currency digits in %s",
+    (locale) => {
+      for (const currency of ["EUR", "JPY", "KWD"]) {
+        for (const value of [9.391, 0, -9.391]) {
+          const expected = new Intl.NumberFormat(locale, {
+            style: "currency",
+            currency,
+          }).format(value);
+          expect(
+            formatValue(value, "currency", locale, currency, "native"),
+          ).toBe(expected);
+        }
+      }
+    },
+  );
+
+  it.each<ValueFormat>(["number", "currency", "percent", "compact"])(
+    "supports fixed precision for %s",
+    (format) => {
+      expect(formatValue(9.3, format, "en", "JPY", 2)).toContain("9.30");
+      expect(formatValue(9.3, format, "en", "KWD", 0)).not.toContain(".");
+    },
+  );
+
+  it("keeps KPI parts aligned with full strings and unit placement", () => {
+    expect(
+      formatValueParts(9.39, "currency", "fr-FR", "EUR", "native"),
+    ).toEqual({ value: "9,39", unit: "€", unitIsPrefix: false });
+    expect(formatValueParts(9.39, "currency", "en-US", "EUR", 3)).toEqual({
+      value: "9.390",
+      unit: "€",
+      unitIsPrefix: true,
+    });
+    expect(formatValueParts(9.3, "number", "fr-FR", "EUR", 2).value).toBe(
+      "9,30",
+    );
+  });
+});