@antelopejs/dms 0.0.1

package/frontend-vue/layers/dms-ui/app/composables/chart/apexPlotOptions.ts

@@ -0,0 +1,100 @@
+import type { UseApexChartInput } from "./useApexChart.types";
+import type { ChartType } from "./types";
+
+const DEFAULT_BAR_RADIUS = 6;
+const DEFAULT_BAR_WIDTH_PCT = "60%";
+const DEFAULT_DONUT_HOLE = "70%";
+const DEFAULT_RADIAL_HOLE = "60%";
+const TRACK_BG = "rgba(120,120,120,0.1)";
+const HEATMAP_RADIUS = 4;
+const HEATMAP_DEFAULT_INTENSITY = 0.6;
+const HUNDRED_PERCENT = 100;
+
+type PlotBuilder = (props: UseApexChartInput) => Record<string, unknown>;
+
+function widthValue(
+  width: number | undefined,
+  fallback: string,
+): string | number {
+  return width === undefined ? fallback : width;
+}
+
+function buildBarPlotOptions(
+  input: UseApexChartInput,
+  isHorizontal: boolean,
+): Record<string, unknown> {
+  const widthKey = isHorizontal ? "barHeight" : "columnWidth";
+  const widthInput = isHorizontal ? input.barWidth : input.columnWidth;
+  return {
+    bar: {
+      horizontal: isHorizontal,
+      borderRadius: input.roundedCorners === false ? 0 : DEFAULT_BAR_RADIUS,
+      [widthKey]: widthValue(widthInput, DEFAULT_BAR_WIDTH_PCT),
+      distributed: input.distributed ?? false,
+    },
+  };
+}
+
+function donutSizeFor(arcWidth: number | undefined): string {
+  if (arcWidth === undefined) return DEFAULT_DONUT_HOLE;
+  return `${HUNDRED_PERCENT - arcWidth}%`;
+}
+
+function buildDonutPlot(props: UseApexChartInput): Record<string, unknown> {
+  return {
+    pie: {
+      donut: {
+        size: donutSizeFor(props.arcWidth),
+        labels: {
+          show: !!(props.centralLabel || props.centralSubLabel),
+          name: { show: !!props.centralSubLabel },
+          value: { show: !!props.centralLabel },
+          total: {
+            show: true,
+            label: props.centralSubLabel || props.title || "",
+            formatter: () => props.centralLabel ?? "",
+          },
+        },
+      },
+    },
+  };
+}
+
+function buildRadialBarPlot(props: UseApexChartInput): Record<string, unknown> {
+  return {
+    radialBar: {
+      hollow: { size: props.hollowSize || DEFAULT_RADIAL_HOLE },
+      track: { background: TRACK_BG },
+      dataLabels: {
+        total: {
+          show: !!props.showTotal,
+          label: props.title || "",
+        },
+      },
+    },
+  };
+}
+
+function buildHeatmapPlot(props: UseApexChartInput): Record<string, unknown> {
+  return {
+    heatmap: {
+      shadeIntensity: props.shadeIntensity ?? HEATMAP_DEFAULT_INTENSITY,
+      radius: HEATMAP_RADIUS,
+      distributed: props.distributed ?? false,
+    },
+  };
+}
+
+const PLOT_BUILDERS: Partial<Record<ChartType, PlotBuilder>> = {
+  bar: (props) => buildBarPlotOptions(props, props.orientation !== "vertical"),
+  column: (props) => buildBarPlotOptions(props, false),
+  donut: buildDonutPlot,
+  radialBar: buildRadialBarPlot,
+  heatmap: buildHeatmapPlot,
+};
+
+export function buildPlotOptions(
+  input: UseApexChartInput,
+): Record<string, unknown> {
+  return PLOT_BUILDERS[input.type]?.(input) ?? {};
+}

package/frontend-vue/layers/dms-ui/app/composables/chart/apexTypeConfigs.ts

@@ -0,0 +1,109 @@
+import type { ChartType } from "./types";
+
+export interface ApexTypeConfig {
+  apexType: string;
+  isCircular: boolean;
+  defaultStroke: { curve?: string; width?: number; dashArray?: number };
+  supportsDataLabels: boolean;
+  sharedTooltip: boolean;
+}
+
+const SMOOTH_LINE_STROKE = { curve: "smooth", width: 3 } as const;
+const SMOOTH_BAND_STROKE = { curve: "smooth", width: 1 } as const;
+const NO_STROKE = { width: 0 } as const;
+const THIN_STROKE = { width: 2 } as const;
+const MEDIUM_STROKE = { width: 1 } as const;
+
+export const APEX_TYPE_CONFIGS: Record<ChartType, ApexTypeConfig> = {
+  line: {
+    apexType: "line",
+    isCircular: false,
+    defaultStroke: SMOOTH_LINE_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: true,
+  },
+  area: {
+    apexType: "area",
+    isCircular: false,
+    defaultStroke: SMOOTH_LINE_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: true,
+  },
+  rangeArea: {
+    apexType: "rangeArea",
+    isCircular: false,
+    defaultStroke: SMOOTH_BAND_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: true,
+  },
+  bar: {
+    apexType: "bar",
+    isCircular: false,
+    defaultStroke: NO_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: false,
+  },
+  column: {
+    apexType: "bar",
+    isCircular: false,
+    defaultStroke: NO_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: false,
+  },
+  scatter: {
+    apexType: "scatter",
+    isCircular: false,
+    defaultStroke: NO_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: false,
+  },
+  donut: {
+    apexType: "donut",
+    isCircular: true,
+    defaultStroke: THIN_STROKE,
+    supportsDataLabels: true,
+    sharedTooltip: false,
+  },
+  pie: {
+    apexType: "pie",
+    isCircular: true,
+    defaultStroke: THIN_STROKE,
+    supportsDataLabels: true,
+    sharedTooltip: false,
+  },
+  mixed: {
+    apexType: "line",
+    isCircular: false,
+    defaultStroke: SMOOTH_LINE_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: true,
+  },
+  radar: {
+    apexType: "radar",
+    isCircular: false,
+    defaultStroke: THIN_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: true,
+  },
+  radialBar: {
+    apexType: "radialBar",
+    isCircular: true,
+    defaultStroke: NO_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: false,
+  },
+  heatmap: {
+    apexType: "heatmap",
+    isCircular: false,
+    defaultStroke: NO_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: false,
+  },
+  candlestick: {
+    apexType: "candlestick",
+    isCircular: false,
+    defaultStroke: MEDIUM_STROKE,
+    supportsDataLabels: false,
+    sharedTooltip: false,
+  },
+};

package/frontend-vue/layers/dms-ui/app/composables/chart/events.ts

@@ -0,0 +1,44 @@
+import type { ChartType } from "./types";
+
+export const CHART_EVENT_NAMES = {
+  segmentClick: "DmsComponent.Chart.SegmentClick",
+  pointClick: "DmsComponent.Chart.PointClick",
+} as const;
+
+const SEGMENT_CHART_TYPES = new Set<ChartType>(["donut", "pie", "radialBar"]);
+
+export function isSegmentChart(type: ChartType): boolean {
+  return SEGMENT_CHART_TYPES.has(type);
+}
+
+export interface ChartClickPayload {
+  dataPointIndex: number;
+  seriesIndex: number;
+  /** Null on the types whose points hold a tuple rather than a scalar. */
+  value: number | null;
+  /** The point's tuple on those types: `[low, high]`, `[o, h, l, c]`. */
+  values?: number[];
+  seriesName: string;
+  label?: string;
+}
+
+export interface ClickPointValue {
+  value: number | null;
+  values?: number[];
+}
+
+interface PointWithY {
+  y?: unknown;
+}
+
+/**
+ * Projects a series point onto the click payload's value fields: scalars
+ * land in `value`, tuple points (rangeArea, candlestick) leave `value` null
+ * and carry their tuple in `values`.
+ */
+export function readPointValue(point: unknown): ClickPointValue {
+  if (typeof point === "number") return { value: point };
+  const y = (point as PointWithY | undefined)?.y;
+  if (Array.isArray(y)) return { value: null, values: y as number[] };
+  return { value: typeof y === "number" ? y : null };
+}

package/frontend-vue/layers/dms-ui/app/composables/chart/formatValue.ts

@@ -0,0 +1,156 @@
+import type { ValueFormat, ValuePrecision } from "./types";
+
+const PERCENT_DIVISOR = 100;
+const CURRENCY_FRACTION_DIGITS = 0;
+const PERCENT_FRACTION_DIGITS = 1;
+const COMPACT_FRACTION_DIGITS = 1;
+const DEFAULT_LOCALE = "en";
+const DEFAULT_CURRENCY = "EUR";
+
+const CURRENCY_PART_TYPE = "currency";
+const PERCENT_PART_TYPE = "percent";
+const COMPACT_PART_TYPE = "compact";
+
+const IDENTITY = (value: number) => value;
+const TO_PERCENT_RATIO = (value: number) => value / PERCENT_DIVISOR;
+
+interface NumberFormatConfig {
+  transform: (value: number) => number;
+  options: (currency: string) => Intl.NumberFormatOptions;
+  unitPartType: string | null;
+}
+
+const NUMBER_FORMAT_CONFIGS: Record<ValueFormat, NumberFormatConfig> = {
+  number: {
+    transform: IDENTITY,
+    options: () => ({}),
+    unitPartType: null,
+  },
+  currency: {
+    transform: IDENTITY,
+    options: (currency) => ({
+      style: "currency",
+      currency,
+      maximumFractionDigits: CURRENCY_FRACTION_DIGITS,
+    }),
+    unitPartType: CURRENCY_PART_TYPE,
+  },
+  percent: {
+    transform: TO_PERCENT_RATIO,
+    options: () => ({
+      style: "percent",
+      maximumFractionDigits: PERCENT_FRACTION_DIGITS,
+    }),
+    unitPartType: PERCENT_PART_TYPE,
+  },
+  compact: {
+    transform: IDENTITY,
+    options: () => ({
+      notation: "compact",
+      maximumFractionDigits: COMPACT_FRACTION_DIGITS,
+    }),
+    unitPartType: COMPACT_PART_TYPE,
+  },
+};
+
+function resolveConfig(format: ValueFormat): NumberFormatConfig {
+  return NUMBER_FORMAT_CONFIGS[format] ?? NUMBER_FORMAT_CONFIGS.number;
+}
+
+function precisionOptions(
+  options: Intl.NumberFormatOptions,
+  precision?: ValuePrecision,
+): Intl.NumberFormatOptions {
+  if (precision === undefined) return options;
+  if (precision === "native") {
+    return { ...options, maximumFractionDigits: undefined };
+  }
+  return {
+    ...options,
+    minimumFractionDigits: precision,
+    maximumFractionDigits: precision,
+  };
+}
+
+/** Formats a chart value, preserving legacy defaults unless precision is supplied. */
+export function formatValue(
+  value: number,
+  format: ValueFormat = "number",
+  locale = DEFAULT_LOCALE,
+  currency = DEFAULT_CURRENCY,
+  precision?: ValuePrecision,
+): string {
+  const config = resolveConfig(format);
+  return new Intl.NumberFormat(
+    locale,
+    precisionOptions(config.options(currency), precision),
+  ).format(config.transform(value));
+}
+
+const DELTA_SIGN_DISPLAY = "exceptZero";
+
+/**
+ * Formats a percentage delta the way the current locale writes it — decimal
+ * comma and non-breaking space in French, dot and tight percent in English —
+ * with an explicit sign on anything but zero.
+ */
+export function formatDeltaPercent(
+  delta: number,
+  locale = DEFAULT_LOCALE,
+): string {
+  return new Intl.NumberFormat(locale, {
+    style: "percent",
+    minimumFractionDigits: PERCENT_FRACTION_DIGITS,
+    maximumFractionDigits: PERCENT_FRACTION_DIGITS,
+    signDisplay: DELTA_SIGN_DISPLAY,
+  }).format(TO_PERCENT_RATIO(delta));
+}
+
+export interface FormattedValueParts {
+  value: string;
+  unit: string;
+  unitIsPrefix: boolean;
+}
+
+/** Splits the same formatted value into numeric and unit parts for KPI cards. */
+export function formatValueParts(
+  value: number,
+  format: ValueFormat = "number",
+  locale = DEFAULT_LOCALE,
+  currency = DEFAULT_CURRENCY,
+  precision?: ValuePrecision,
+): FormattedValueParts {
+  const config = resolveConfig(format);
+  if (!config.unitPartType) {
+    return {
+      value: formatValue(value, format, locale, currency, precision),
+      unit: "",
+      unitIsPrefix: false,
+    };
+  }
+
+  const parts = new Intl.NumberFormat(
+    locale,
+    precisionOptions(config.options(currency), precision),
+  ).formatToParts(config.transform(value));
+
+  const isUnitPart = (part: Intl.NumberFormatPart) =>
+    part.type === config.unitPartType;
+  const firstUnitIndex = parts.findIndex(isUnitPart);
+  const firstValueIndex = parts.findIndex(
+    (part) => !isUnitPart(part) && part.value.trim() !== "",
+  );
+
+  return {
+    value: parts
+      .filter((part) => !isUnitPart(part))
+      .map((part) => part.value)
+      .join("")
+      .trim(),
+    unit: parts
+      .filter(isUnitPart)
+      .map((part) => part.value)
+      .join(""),
+    unitIsPrefix: firstUnitIndex !== -1 && firstUnitIndex < firstValueIndex,
+  };
+}

package/frontend-vue/layers/dms-ui/app/composables/chart/resolveSparklineAccent.ts

@@ -0,0 +1,56 @@
+const POSITIVE_ACCENT = "success";
+const NEGATIVE_ACCENT = "error";
+const NEUTRAL_ACCENT = "neutral";
+const AUTO_ACCENT = "auto";
+
+export type SparklineTrend = "positive" | "negative" | "neutral";
+
+function trendFromDelta(delta: number): SparklineTrend {
+  if (delta > 0) return "positive";
+  if (delta < 0) return "negative";
+  return "neutral";
+}
+
+function trendFromSparkline(values: number[]): SparklineTrend {
+  if (values.length < 2) return "neutral";
+  const first = values[0]!;
+  const last = values[values.length - 1]!;
+  if (last > first) return "positive";
+  if (last < first) return "negative";
+  return "neutral";
+}
+
+const TREND_TO_ACCENT: Record<SparklineTrend, string> = {
+  positive: POSITIVE_ACCENT,
+  negative: NEGATIVE_ACCENT,
+  neutral: NEUTRAL_ACCENT,
+};
+
+const INVERTED_TREND: Record<SparklineTrend, SparklineTrend> = {
+  positive: "negative",
+  negative: "positive",
+  neutral: "neutral",
+};
+
+interface AutoAccentInput {
+  delta: number | null | undefined;
+  sparkline: number[];
+  invert?: boolean;
+}
+
+function detectTrend(input: AutoAccentInput): SparklineTrend {
+  if (input.delta !== null && input.delta !== undefined) {
+    return trendFromDelta(input.delta);
+  }
+  return trendFromSparkline(input.sparkline);
+}
+
+export function resolveSparklineAccent(
+  accent: string,
+  input: AutoAccentInput,
+): string {
+  if (accent !== AUTO_ACCENT) return accent;
+  const trend = detectTrend(input);
+  const finalTrend = input.invert ? INVERTED_TREND[trend] : trend;
+  return TREND_TO_ACCENT[finalTrend];
+}

package/frontend-vue/layers/dms-ui/app/composables/chart/types.ts

@@ -0,0 +1,145 @@
+/** Serializable X-axis settings, matching the DMS server contract. */
+export interface ChartXAxis {
+  /** Requested intervals; ignored by ApexCharts on datetime axes. */
+  tickAmount?: number;
+  /** Label rotation in degrees. */
+  rotate?: number;
+  /** Suppress overlapping labels. */
+  hideOverlappingLabels?: boolean;
+  /** ApexCharts datetime tokens, for example "dd MMM". */
+  datetimeFormat?: string;
+}
+
+/** Vue-only formatter; timestamp is supplied by ApexCharts for datetime labels. */
+export type ChartXAxisFormatter = (value: string, timestamp?: number) => string;
+
+export const CHART_TYPES = [
+  "line",
+  "area",
+  "rangeArea",
+  "bar",
+  "column",
+  "scatter",
+  "donut",
+  "pie",
+  "mixed",
+  "radar",
+  "radialBar",
+  "heatmap",
+  "candlestick",
+] as const;
+
+export type ChartType = (typeof CHART_TYPES)[number];
+
+export const CIRCULAR_CHART_TYPES: ChartType[] = ["donut", "pie", "radialBar"];
+
+export interface ChartSeriesPoint {
+  x: string | number | Date;
+  y: number | null;
+  label?: string;
+}
+
+export interface ChartCandlePoint {
+  x: string | number | Date;
+  y: [number, number, number, number];
+}
+
+export interface ChartRangePoint {
+  x: string | number | Date;
+  y: [number, number];
+}
+
+export interface ChartSeries {
+  name: string;
+  data: Array<ChartSeriesPoint | ChartCandlePoint | ChartRangePoint | number>;
+  type?: ChartType;
+  color?: string;
+  /** Stroke width in pixels; overrides chart and comparison defaults. */
+  strokeWidth?: number;
+  /** Dash length in pixels; zero draws a solid stroke. Overrides comparison defaults. */
+  strokeDashArray?: number;
+}
+
+export type ChartCurve = "smooth" | "straight" | "stepline";
+
+/** Opt-in expansion of native Y bounds to include annotation lines and bands. */
+export interface ChartAutoYRange {
+  /** Outward fraction of each bound's magnitude (or 1 at zero). Defaults to 0.08. */
+  padding?: number;
+}
+
+export interface ChartAnnotation {
+  y: number;
+  y2?: number;
+  label?: string;
+  color?: string;
+  dashed?: boolean;
+}
+
+export interface DonutRecord {
+  label: string;
+  value: number;
+}
+
+export interface ChartCardResponse {
+  value: number;
+  delta?: number;
+  previousValue?: number;
+  series: ChartSeries[];
+  comparisonSeries?: ChartSeries[];
+}
+
+export interface KpiCardResponse {
+  value: number;
+  delta?: number;
+  previousValue?: number;
+  sparkline?: number[];
+}
+
+export interface TopListItem {
+  id: string | number;
+  title: string;
+  description?: string;
+  value: number;
+  delta?: number | null;
+  sparkline?: number[];
+  icon?: string;
+  avatar?: { src: string; alt?: string };
+  to?: string;
+}
+
+export interface TopListCardResponse {
+  items: TopListItem[];
+}
+
+export interface ChartResponse {
+  series: ChartSeries[];
+}
+
+export type ValueFormat = "number" | "currency" | "percent" | "compact";
+
+/** Fixed fraction digits, or Intl defaults; omitted preserves legacy formatting. */
+export type ValuePrecision = number | "native";
+
+export type ComparisonStyle = "dashed" | "solid" | "dimmed";
+
+export type UiColor =
+  | "primary"
+  | "secondary"
+  | "success"
+  | "info"
+  | "warning"
+  | "error"
+  | "neutral";
+
+export const NESTED_CHART_INJECT_KEY = Symbol("DmsChartCardNested");
+
+export interface NestedChartContext {
+  cardSeries: ChartSeries[];
+  cardComparisonSeries: ChartSeries[];
+  isLoading: boolean;
+  hideLegend?: boolean;
+  valueFormat?: ValueFormat;
+  currencyCode?: string;
+  valuePrecision?: ValuePrecision;
+}