orbital-ds 0.9.0 → 0.10.0

package/dist/lib/echarts-presets.d.ts

@@ -0,0 +1,153 @@
+import { EChartsCoreOption } from 'echarts/core';
+
+/** Valor de una serie: `null` = sin dato (hueco), nunca 0. */
+type DsChartValue = number | null;
+interface DsSeries {
+    name: string;
+    data: DsChartValue[];
+    /** Grupo de apilado propio (si no, el de `stack` del constructor). */
+    stack?: string;
+}
+/** Formatea un valor en el tooltip y las etiquetas (p. ej. con Intl.NumberFormat). */
+type DsValueFormatter = (value: number) => string;
+/** Línea o área de referencia (las crean `referenceLine` y `referenceArea`). */
+type DsReference = {
+    kind: "line";
+    markLine: Record<string, unknown>;
+} | {
+    kind: "area";
+    markArea: Record<string, unknown>;
+};
+type Obj = Record<string, unknown>;
+interface CommonOptions {
+    /** Muestra la leyenda (por defecto, si hay más de una serie). */
+    legend?: boolean;
+    /** Formato de los valores (tooltip y ejes de valor). */
+    valueFormatter?: DsValueFormatter;
+    /** Opciones propias fusionadas por encima del resultado. */
+    extend?: Obj;
+}
+/**
+ * Línea de referencia (objetivo, umbral de SLA…). `axis` es el eje del VALOR: "y" en
+ * gráficos verticales (por defecto) y "x" en barras horizontales.
+ */
+declare function referenceLine(value: number, label?: string, { axis }?: {
+    axis?: "x" | "y";
+}): DsReference;
+/**
+ * Banda de referencia entre dos valores (franja horaria, zona de alerta…). Con `axis: "x"`
+ * acepta categorías del eje X (p. ej. "08:00" → "15:00"); con "y", valores.
+ */
+declare function referenceArea(from: number | string, to: number | string, label?: string, { axis }?: {
+    axis?: "x" | "y";
+}): DsReference;
+/**
+ * Escapa texto para HTML. Un `formatter` de tooltip que devuelve una cadena se pinta COMO
+ * HTML: todo lo interpolado (categorías, nombres de serie, etiquetas, valores formateados)
+ * puede venir de datos de usuario y debe pasar por aquí. El tooltip por defecto de ECharts
+ * (nombres y `valueFormatter`) ya escapa; las etiquetas de serie, markLine y markArea son
+ * texto del lienzo/SVG, no HTML.
+ */
+declare function escapeHtml(value: unknown): string;
+interface LineOptionInput extends CommonOptions {
+    categories: Array<string | number>;
+    series: DsSeries[];
+    /** Rellena el área bajo cada línea. */
+    area?: boolean;
+    /** Apila las series (true = un solo grupo, o el nombre del grupo). */
+    stack?: boolean | string;
+    smooth?: boolean;
+    /** Sin puntos en la línea (series largas). */
+    showSymbols?: boolean;
+    /** Une los huecos (`null`) en lugar de cortar la línea. */
+    connectNulls?: boolean;
+    references?: DsReference[];
+    yName?: string;
+    /** Activa el zoom horizontal con la rueda y el arrastre. */
+    zoom?: boolean;
+}
+declare function lineOption(input: LineOptionInput): EChartsCoreOption;
+interface BarOptionInput extends CommonOptions {
+    categories: Array<string | number>;
+    series: DsSeries[];
+    /** Barras horizontales (categorías en el eje Y). */
+    horizontal?: boolean;
+    stack?: boolean | string;
+    /**
+     * Ranking: ordena la PRIMERA serie de mayor a menor (horizontal por defecto, la mayor
+     * arriba) y reordena las demás igual.
+     */
+    ranking?: boolean;
+    /** Etiqueta con el valor al final de cada barra. */
+    showLabels?: boolean;
+    references?: DsReference[];
+}
+declare function barOption(input: BarOptionInput): EChartsCoreOption;
+interface ComboOptionInput extends Omit<CommonOptions, "valueFormatter"> {
+    categories: Array<string | number>;
+    /** Series de barras (eje izquierdo/inicial). */
+    bars: DsSeries[];
+    /** Series de línea (eje derecho/final). */
+    lines: DsSeries[];
+    barAxisName?: string;
+    lineAxisName?: string;
+    barFormatter?: DsValueFormatter;
+    lineFormatter?: DsValueFormatter;
+    stackBars?: boolean;
+    smooth?: boolean;
+    /** Referencias sobre el eje de las líneas (p. ej. objetivo de SLA). */
+    references?: DsReference[];
+}
+declare function comboOption(input: ComboOptionInput): EChartsCoreOption;
+interface HeatmapOptionInput extends CommonOptions {
+    /** Columnas (p. ej. horas "00"…"23"). */
+    xCategories: Array<string | number>;
+    /** Filas (p. ej. días "Lun"…"Dom"). */
+    yCategories: Array<string | number>;
+    /** Matriz [fila][columna]; `null` = sin dato (celda vacía, nunca 0). */
+    values: DsChartValue[][];
+    min?: number;
+    max?: number;
+    /** Muestra el valor en cada celda. */
+    showLabels?: boolean;
+    /** Muestra el mapa visual (escala) bajo el gráfico. */
+    showScale?: boolean;
+}
+declare function heatmapOption(input: HeatmapOptionInput): EChartsCoreOption;
+interface SankeyLink {
+    source: string;
+    target: string;
+    value: number;
+}
+interface SankeyOptionInput extends CommonOptions {
+    /** Nodos (si se omiten, salen de los enlaces). */
+    nodes?: string[];
+    links: SankeyLink[];
+    orient?: "horizontal" | "vertical";
+}
+declare function sankeyOption(input: SankeyOptionInput): EChartsCoreOption;
+interface GaugeOptionInput extends Omit<CommonOptions, "legend"> {
+    value: number | null;
+    min?: number;
+    max?: number;
+    /** Nombre bajo la cifra (p. ej. "SLA"). */
+    name?: string;
+    /** Marcas del eje (por defecto, 5 tramos). */
+    splitNumber?: number;
+}
+declare function gaugeOption(input: GaugeOptionInput): EChartsCoreOption;
+interface PieOptionInput extends CommonOptions {
+    data: Array<{
+        name: string;
+        value: number;
+    }>;
+    /** Donut (por defecto) o tarta llena. */
+    donut?: boolean;
+    /** Texto en el centro del donut (p. ej. el total). */
+    centerLabel?: string;
+    centerSubLabel?: string;
+    showLabels?: boolean;
+}
+declare function pieOption(input: PieOptionInput): EChartsCoreOption;
+
+export { type BarOptionInput, type ComboOptionInput, type DsChartValue, type DsReference, type DsSeries, type DsValueFormatter, type GaugeOptionInput, type HeatmapOptionInput, type LineOptionInput, type PieOptionInput, type SankeyLink, type SankeyOptionInput, barOption, comboOption, escapeHtml, gaugeOption, heatmapOption, lineOption, pieOption, referenceArea, referenceLine, sankeyOption };

package/dist/lib/echarts-presets.js

@@ -0,0 +1,311 @@
+function referenceLine(value, label, { axis = "y" } = {}) {
+  return {
+    kind: "line",
+    markLine: {
+      silent: true,
+      symbol: "none",
+      lineStyle: { type: "dashed" },
+      label: { show: Boolean(label), formatter: () => label ?? "", position: "insideEndTop" },
+      data: [{ [axis === "y" ? "yAxis" : "xAxis"]: value, name: label }]
+    }
+  };
+}
+function referenceArea(from, to, label, { axis = typeof from === "string" ? "x" : "y" } = {}) {
+  const key = axis === "y" ? "yAxis" : "xAxis";
+  return {
+    kind: "area",
+    markArea: {
+      silent: true,
+      label: { show: Boolean(label), formatter: () => label ?? "", position: "insideTop" },
+      data: [[{ [key]: from, name: label }, { [key]: to }]]
+    }
+  };
+}
+function withReferences(series, refs) {
+  if (!refs?.length) return series;
+  const lines = refs.filter((r) => r.kind === "line");
+  const areas = refs.filter((r) => r.kind === "area");
+  const out = { ...series };
+  if (lines.length) {
+    out.markLine = {
+      ...lines[0].markLine,
+      data: lines.flatMap((l) => l.markLine.data.map((d) => ({ ...d, label: l.markLine.label })))
+    };
+  }
+  if (areas.length) {
+    out.markArea = {
+      ...areas[0].markArea,
+      data: areas.flatMap(
+        (a) => a.markArea.data.map(([start, end]) => [{ ...start, label: a.markArea.label }, end])
+      )
+    };
+  }
+  return out;
+}
+function escapeHtml(value) {
+  return String(value ?? "").replace(/[&<>"']/g, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch]);
+}
+function tooltip(trigger, valueFormatter, extra = {}) {
+  return {
+    trigger,
+    ...valueFormatter ? { valueFormatter: (v) => typeof v === "number" ? valueFormatter(v) : String(v ?? "\u2013") } : {},
+    ...extra
+  };
+}
+function legend(show, count) {
+  return { show: show ?? count > 1, top: 0, type: "scroll" };
+}
+function valueAxis(valueFormatter, extra = {}) {
+  return {
+    type: "value",
+    ...valueFormatter ? { axisLabel: { formatter: (v) => valueFormatter(v) } } : {},
+    ...extra
+  };
+}
+function finish(option, extend) {
+  return { aria: { enabled: true }, ...option, ...extend };
+}
+function lineOption(input) {
+  const { categories, series, area = false, stack, smooth = false, showSymbols = true, connectNulls = false } = input;
+  const group = stack === true ? "total" : stack || void 0;
+  return finish(
+    {
+      tooltip: tooltip("axis", input.valueFormatter),
+      legend: legend(input.legend, series.length),
+      xAxis: { type: "category", data: categories, boundaryGap: false },
+      yAxis: valueAxis(input.valueFormatter, input.yName ? { name: input.yName } : {}),
+      ...input.zoom ? { dataZoom: [{ type: "inside" }] } : {},
+      series: series.map(
+        (s, i) => withReferences(
+          {
+            type: "line",
+            name: s.name,
+            data: s.data,
+            smooth,
+            showSymbol: showSymbols,
+            connectNulls,
+            ...s.stack || group ? { stack: s.stack ?? group } : {},
+            ...area ? { areaStyle: { opacity: group ? 0.6 : 0.15 } } : {},
+            emphasis: { focus: "series" }
+          },
+          i === 0 ? input.references : void 0
+        )
+      )
+    },
+    input.extend
+  );
+}
+function barOption(input) {
+  const horizontal = input.horizontal ?? Boolean(input.ranking);
+  const group = input.stack === true ? "total" : input.stack || void 0;
+  let categories = input.categories;
+  let series = input.series;
+  if (input.ranking && series.length) {
+    const order = categories.map((_, i) => i).sort((a, b) => (series[0].data[b] ?? -Infinity) - (series[0].data[a] ?? -Infinity));
+    categories = order.map((i) => input.categories[i]);
+    series = series.map((s) => ({ ...s, data: order.map((i) => s.data[i] ?? null) }));
+  }
+  const category = { type: "category", data: categories, ...horizontal ? { inverse: true } : {} };
+  const value = valueAxis(input.valueFormatter);
+  const fmt = input.valueFormatter;
+  return finish(
+    {
+      tooltip: tooltip("axis", fmt, { axisPointer: { type: "shadow" } }),
+      legend: legend(input.legend, series.length),
+      xAxis: horizontal ? value : category,
+      yAxis: horizontal ? category : value,
+      series: series.map(
+        (s, i) => withReferences(
+          {
+            type: "bar",
+            name: s.name,
+            data: s.data,
+            ...s.stack || group ? { stack: s.stack ?? group } : {},
+            ...input.showLabels ? {
+              label: {
+                show: true,
+                position: group ? "inside" : horizontal ? "right" : "top",
+                ...fmt ? { formatter: (p) => typeof p.value === "number" ? fmt(p.value) : "" } : {}
+              }
+            } : {},
+            emphasis: { focus: "series" }
+          },
+          i === 0 ? input.references : void 0
+        )
+      )
+    },
+    input.extend
+  );
+}
+function comboOption(input) {
+  const { barFormatter, lineFormatter } = input;
+  const fmtFor = (axis) => axis === 0 ? barFormatter : lineFormatter;
+  return finish(
+    {
+      tooltip: tooltip("axis", void 0, { axisPointer: { type: "cross" } }),
+      legend: legend(input.legend, input.bars.length + input.lines.length),
+      xAxis: { type: "category", data: input.categories },
+      yAxis: [
+        valueAxis(barFormatter, input.barAxisName ? { name: input.barAxisName } : {}),
+        valueAxis(lineFormatter, { ...input.lineAxisName ? { name: input.lineAxisName } : {}, splitLine: { show: false } })
+      ],
+      series: [
+        ...input.bars.map((s) => ({
+          type: "bar",
+          name: s.name,
+          data: s.data,
+          yAxisIndex: 0,
+          ...input.stackBars || s.stack ? { stack: s.stack ?? "bars" } : {},
+          ...fmtFor(0) ? { tooltip: { valueFormatter: (v) => typeof v === "number" ? fmtFor(0)(v) : "\u2013" } } : {}
+        })),
+        ...input.lines.map(
+          (s, i) => withReferences(
+            {
+              type: "line",
+              name: s.name,
+              data: s.data,
+              yAxisIndex: 1,
+              smooth: input.smooth ?? false,
+              ...fmtFor(1) ? { tooltip: { valueFormatter: (v) => typeof v === "number" ? fmtFor(1)(v) : "\u2013" } } : {}
+            },
+            i === 0 ? input.references : void 0
+          )
+        )
+      ]
+    },
+    input.extend
+  );
+}
+function heatmapOption(input) {
+  const data = [];
+  const nums = [];
+  input.values.forEach(
+    (row, y) => row.forEach((v, x) => {
+      data.push([x, y, v ?? "-"]);
+      if (v != null) nums.push(v);
+    })
+  );
+  const min = input.min ?? (nums.length ? Math.min(...nums) : 0);
+  const max = input.max ?? (nums.length ? Math.max(...nums) : 1);
+  const showScale = input.showScale ?? true;
+  const fmt = input.valueFormatter;
+  return finish(
+    {
+      tooltip: tooltip("item", void 0, {
+        formatter: (p) => {
+          const [x, y, v] = p.value;
+          const shown = typeof v === "number" ? fmt ? fmt(v) : v : "\u2013";
+          return `${escapeHtml(input.yCategories[y])} \xB7 ${escapeHtml(input.xCategories[x])}: ${escapeHtml(shown)}`;
+        }
+      }),
+      grid: { top: 8, bottom: showScale ? 56 : 8 },
+      xAxis: { type: "category", data: input.xCategories, splitArea: { show: true } },
+      yAxis: { type: "category", data: input.yCategories, inverse: true, splitArea: { show: true } },
+      visualMap: {
+        show: showScale,
+        min,
+        max,
+        calculable: true,
+        orient: "horizontal",
+        left: "center",
+        bottom: 0,
+        ...fmt ? { formatter: (v) => fmt(v) } : {}
+      },
+      series: [
+        {
+          type: "heatmap",
+          data,
+          label: { show: Boolean(input.showLabels) },
+          emphasis: { itemStyle: { borderWidth: 1 } }
+        }
+      ]
+    },
+    input.extend
+  );
+}
+function sankeyOption(input) {
+  const names = input.nodes ?? [...new Set(input.links.flatMap((l) => [l.source, l.target]))];
+  return finish(
+    {
+      tooltip: tooltip("item", input.valueFormatter),
+      series: [
+        {
+          type: "sankey",
+          orient: input.orient ?? "horizontal",
+          data: names.map((name) => ({ name })),
+          links: input.links,
+          emphasis: { focus: "adjacency" },
+          nodeAlign: "justify",
+          draggable: false
+        }
+      ]
+    },
+    input.extend
+  );
+}
+function gaugeOption(input) {
+  const fmt = input.valueFormatter;
+  return finish(
+    {
+      series: [
+        {
+          type: "gauge",
+          min: input.min ?? 0,
+          max: input.max ?? 100,
+          splitNumber: input.splitNumber ?? 5,
+          startAngle: 210,
+          endAngle: -30,
+          progress: { show: true, roundCap: true },
+          pointer: { show: false },
+          axisTick: { show: false },
+          splitLine: { show: false },
+          axisLabel: { show: false },
+          anchor: { show: false },
+          title: { show: Boolean(input.name), offsetCenter: [0, "30%"] },
+          detail: {
+            valueAnimation: true,
+            offsetCenter: [0, "-5%"],
+            formatter: (v) => input.value == null ? "\u2013" : fmt ? fmt(v) : String(v)
+          },
+          data: [{ value: input.value ?? 0, name: input.name ?? "" }]
+        }
+      ]
+    },
+    input.extend
+  );
+}
+function pieOption(input) {
+  const donut = input.donut ?? true;
+  return finish(
+    {
+      tooltip: tooltip("item", input.valueFormatter),
+      legend: { ...legend(input.legend ?? true, input.data.length), top: void 0, bottom: 0 },
+      ...donut && input.centerLabel ? { title: { text: input.centerLabel, subtext: input.centerSubLabel, left: "center", top: "middle", itemGap: 4 } } : {},
+      series: [
+        {
+          type: "pie",
+          radius: donut ? ["55%", "75%"] : "75%",
+          center: ["50%", "48%"],
+          avoidLabelOverlap: true,
+          label: { show: Boolean(input.showLabels) },
+          labelLine: { show: Boolean(input.showLabels) },
+          emphasis: { scale: true },
+          data: input.data
+        }
+      ]
+    },
+    input.extend
+  );
+}
+export {
+  barOption,
+  comboOption,
+  escapeHtml,
+  gaugeOption,
+  heatmapOption,
+  lineOption,
+  pieOption,
+  referenceArea,
+  referenceLine,
+  sankeyOption
+};

package/dist/lib/echarts-server.d.ts

@@ -0,0 +1,15 @@
+import { EChartsCoreOption } from 'echarts/core';
+import { DsChartTokens, DsEchartsTheme } from './echarts-theme.js';
+
+interface RenderEChartOptions {
+    width: number;
+    height: number;
+    /** Valores del tema (piel `light` o `dark` de `<tema>.tokens.json`), o un tema ya montado. */
+    tokens?: DsChartTokens;
+    theme?: DsEchartsTheme;
+    /** Sin animación por defecto: en un documento no se ve. */
+    animation?: boolean;
+}
+declare function renderEChartToSvg(option: EChartsCoreOption, { width, height, tokens, theme, animation }: RenderEChartOptions): string;
+
+export { type RenderEChartOptions, renderEChartToSvg };

package/dist/lib/echarts-server.js

@@ -0,0 +1,15 @@
+import { echarts } from "./echarts-setup";
+import { dsEchartsThemeFromTokens } from "./echarts-theme";
+function renderEChartToSvg(option, { width, height, tokens, theme, animation = false }) {
+  const tema = theme ?? (tokens ? dsEchartsThemeFromTokens(tokens, { reducedMotion: !animation }) : void 0);
+  const chart = echarts.init(null, tema, { renderer: "svg", ssr: true, width, height });
+  try {
+    chart.setOption({ animation, ...option });
+    return chart.renderToSVGString();
+  } finally {
+    chart.dispose();
+  }
+}
+export {
+  renderEChartToSvg
+};

package/dist/lib/echarts-setup.d.ts

@@ -0,0 +1,4 @@
+import * as echarts from 'echarts/core';
+export { echarts };
+export { EChartsCoreOption as DsEChartOption } from 'echarts/core';
+import '@base-ui/react/direction-provider';

package/dist/lib/echarts-setup.js

@@ -0,0 +1,60 @@
+import {
+  BarChart,
+  FunnelChart,
+  GaugeChart,
+  HeatmapChart,
+  LineChart,
+  PieChart,
+  RadarChart,
+  SankeyChart,
+  ScatterChart
+} from "echarts/charts";
+import {
+  AriaComponent,
+  DatasetComponent,
+  DataZoomComponent,
+  GraphicComponent,
+  GridComponent,
+  LegendComponent,
+  MarkAreaComponent,
+  MarkLineComponent,
+  MarkPointComponent,
+  TitleComponent,
+  TooltipComponent,
+  TransformComponent,
+  VisualMapComponent
+} from "echarts/components";
+import * as echarts from "echarts/core";
+import { LabelLayout, UniversalTransition } from "echarts/features";
+import { CanvasRenderer, SVGRenderer } from "echarts/renderers";
+echarts.use([
+  BarChart,
+  FunnelChart,
+  GaugeChart,
+  HeatmapChart,
+  LineChart,
+  PieChart,
+  RadarChart,
+  SankeyChart,
+  ScatterChart,
+  AriaComponent,
+  DatasetComponent,
+  DataZoomComponent,
+  GraphicComponent,
+  GridComponent,
+  LegendComponent,
+  MarkAreaComponent,
+  MarkLineComponent,
+  MarkPointComponent,
+  TitleComponent,
+  TooltipComponent,
+  TransformComponent,
+  VisualMapComponent,
+  LabelLayout,
+  UniversalTransition,
+  CanvasRenderer,
+  SVGRenderer
+]);
+export {
+  echarts
+};

package/dist/lib/echarts-theme.d.ts

@@ -0,0 +1,36 @@
+/** Valores de un tema que necesita un gráfico (lo que trae `<tema>.tokens.json`). */
+interface DsChartTokens {
+    palette: string[];
+    foreground: string;
+    muted: string;
+    border: string;
+    surface: string;
+    surfaceForeground: string;
+    fontSans: string;
+    fontDisplay: string;
+    motionBaseMs: number;
+    motionSlowMs: number;
+}
+interface DsEchartsTheme {
+    color: string[];
+    backgroundColor: string;
+    textStyle: {
+        fontFamily: string;
+        color: string;
+    };
+    [key: string]: unknown;
+}
+/** Color CSS cualquiera (oklch, color-mix…) → `rgba(r, g, b, a)`. Fuera del navegador lo devuelve tal cual. */
+declare function dsResolveColor(value: string): string;
+/** Lee del navegador los valores del tema ACTIVO (con la marca de la app). */
+declare function dsChartTokens(el?: Element): DsChartTokens;
+/** Paleta de series del tema activo, en RGB. */
+declare function dsChartPalette(el?: Element): string[];
+/** Tema de ECharts a partir de los valores de un tema (navegador o servidor). */
+declare function dsEchartsThemeFromTokens(t: DsChartTokens, { reducedMotion }?: {
+    reducedMotion?: boolean | undefined;
+}): DsEchartsTheme;
+/** Tema de ECharts para el tema ACTIVO en el navegador. */
+declare function dsEchartsTheme(el?: Element): DsEchartsTheme;
+
+export { type DsChartTokens, type DsEchartsTheme, dsChartPalette, dsChartTokens, dsEchartsTheme, dsEchartsThemeFromTokens, dsResolveColor };