@circutor/charts 0.2.0 → 0.3.0

package/dist/esm/loader.js

@@ -5,7 +5,7 @@ import { g as globalScripts } from './app-globals-DQuL1Twl.js';
 const defineCustomElements = async (win, options) => {
   if (typeof window === 'undefined') return undefined;
   await globalScripts();
-  return bootstrapLazy([["itic-chart",[[1,"itic-chart",{"groups":[1],"xAxisName":[1,"x-axis-name"],"yAxisName":[1,"y-axis-name"],"tooltipFormatter":[16]},null,{"groups":[{"onOptionsChange":0}],"xAxisName":[{"onOptionsChange":0}],"yAxisName":[{"onOptionsChange":0}],"tooltipFormatter":[{"onOptionsChange":0}]}]]]], options);
+  return bootstrapLazy([["itic-chart",[[1,"itic-chart",{"groups":[1],"locale":[1],"timeZone":[1,"time-zone"]},null,{"groups":[{"onGroupsChange":0}],"locale":[{"onLocaleChange":0}],"timeZone":[{"onTimeZoneChange":0}]}]]]], options);
 };
 
 export { defineCustomElements };

package/dist/types/components/itic-chart/index.d.ts

@@ -1,26 +1,22 @@
 import { EventEmitter } from '../../stencil-public-runtime';
-import { type ITICChartMarks, type ITICPointClickDetail, type ITICTooltipFormatter } from './itic-chart.options';
+import { type ITICChartMarks, type ITICPointClickDetail } from './itic-chart.options';
 export declare class IticChart {
     el: HTMLElement;
     /**
-     * Point groups, as an array or a JSON string. Extra fields in groups and points are kept and passed
-     * back in `pointClick` and `tooltipFormatter`.
+     * Point groups, as an array or a JSON string. Each group's `phase` code sets its name, color and order.
+     * Extra fields in groups and points are kept and passed back in `pointClick`.
      */
     groups: ITICChartMarks[] | string;
     /**
-     * Name of the duration (X) axis.
+     * Language of the texts, dates and numbers: `ca`, `de`, `en`, `es`, `fr` or `pt`. Only the language
+     * is used (`es-ES` → `es`); any other value falls back to `en`.
      */
-    xAxisName: string;
+    locale: string;
     /**
-     * Name of the voltage (Y) axis.
+     * IANA time zone of the dates in the tooltip (e.g. `Europe/Madrid`). Defaults to the browser's,
+     * which is also used, with a console error, when the value isn't valid.
      */
-    yAxisName: string;
-    /**
-     * Returns the HTML of a point's tooltip. JS/React property only (not an HTML attribute).
-     * The HTML is inserted as is: escaping the values is up to the formatter.
-     * Defaults to an English tooltip with phase, duration, voltage and timestamp.
-     */
-    tooltipFormatter?: ITICTooltipFormatter;
+    timeZone?: string;
     /**
      * Emitted when a clickable point is clicked (`clickable` isn't `false`). `detail` holds the original
      * point and group objects.
@@ -30,10 +26,18 @@ export declare class IticChart {
     private chart?;
     private resizeObserver?;
     private parsedGroups;
-    onOptionsChange(): void;
+    private validTimeZone?;
+    /** Last `aria-label` set by the chart: any other value was set by the consumer and is kept. */
+    private defaultAriaLabel?;
+    onGroupsChange(): void;
+    onLocaleChange(): void;
+    onTimeZoneChange(): void;
     connectedCallback(): void;
+    componentWillLoad(): void;
     componentDidLoad(): void;
     disconnectedCallback(): void;
+    private updateAriaLabel;
+    private validateTimeZone;
     private initChart;
     private updateChart;
     render(): any;

package/dist/types/components/itic-chart/itic-chart.i18n.d.ts

@@ -0,0 +1,13 @@
+import en from './i18n/en.json';
+/** Texts of the chart. `en.json` is the reference: every other language must have the same keys. */
+export type ITICMessages = typeof en;
+export declare const LOCALES: readonly ["ca", "de", "en", "es", "fr", "pt"];
+export type ITICLocale = (typeof LOCALES)[number];
+export declare const DEFAULT_LOCALE: ITICLocale;
+/** Keeps the language of a locale (`es-ES` → `es`), falling back to `en` when it isn't translated. */
+export declare function normalizeLocale(locale: string | null | undefined): ITICLocale;
+export declare const getMessages: (locale: ITICLocale) => ITICMessages;
+/** Translated event type, or the code as is when it isn't in the catalog. */
+export declare function translateEventType(messages: ITICMessages, code: string): string;
+/** Translated name of a phase code that has one (`ALL`, `NONE`), or `undefined`. */
+export declare function translatePhase(messages: ITICMessages, code: string): string | undefined;

package/dist/types/components/itic-chart/itic-chart.options.d.ts

@@ -1,18 +1,32 @@
 import type { EChartsOption } from 'echarts';
+import { type ITICLocale } from './itic-chart.i18n';
 export type ITICPoint = {
+    /** Duration of the event, in ms. */
     duration: number;
+    /** Voltage, in % of the nominal voltage. */
     voltage: number;
+    /** Date of the event, ISO 8601. */
     ts: string;
     /** Whether clicking the point emits `pointClick` and shows a pointer cursor. Defaults to `true`. */
     clickable?: boolean;
-    /** Any other field is kept as is and passed back in `pointClick` and `tooltipFormatter`. */
+    /** Event type code from the backend (e.g. `VOLTAGE_DIP`), translated in the tooltip. Unknown codes are shown as is. */
+    eventType?: string;
+    /** Status code from the backend, shown as is in the tooltip. */
+    status?: string;
+    /** Minimum voltage, in V. Hidden in the tooltip when missing or `0`. */
+    min?: number;
+    /** Maximum voltage, in V. Hidden in the tooltip when missing or `0`. */
+    max?: number;
+    /** Any other field is kept as is and passed back in `pointClick`. */
     [key: string]: unknown;
 };
 export type ITICChartMarks = {
+    /** Phase code (`AN`, `AB,BC,CA`, `ALL`, `NONE`…): sets the group's name, color and order. */
+    phase: string;
+    /** Name of the asset, shown in the tooltip. */
+    assetName?: string;
     points: ITICPoint[];
-    color: string;
-    groupName: string;
-    /** Any other field is kept as is and passed back in `pointClick` and `tooltipFormatter`. */
+    /** Any other field is kept as is and passed back in `pointClick`. */
     [key: string]: unknown;
 };
 /** `detail` of the `pointClick` event: the objects passed in `groups`, not copies. */
@@ -20,30 +34,31 @@ export type ITICPointClickDetail = {
     point: ITICPoint;
     group: ITICChartMarks;
 };
-/**
- * Returns the tooltip content of a point as HTML. The result is inserted as is: escape any value
- * that may contain HTML.
- */
-export type ITICTooltipFormatter = (point: ITICPoint, group: ITICChartMarks) => string;
 export type ITICChartSettings = {
-    xAxisName: string;
-    yAxisName: string;
-    tooltipFormatter: ITICTooltipFormatter;
+    locale: ITICLocale;
+    /** IANA time zone of the dates. `undefined` uses the browser's. Must be valid (see `isValidTimeZone`). */
+    timeZone?: string;
 };
+export declare const DEFAULT_SETTINGS: ITICChartSettings;
 /**
  * Normalizes the `groups` prop, which arrives as an array from JS/React
  * or as a JSON string when set as an HTML attribute.
  */
 export declare function parseGroups(groups: ITICChartMarks[] | string | null | undefined): ITICChartMarks[];
+export declare function isValidTimeZone(timeZone: string): boolean;
 export declare function escapeHtml(value: string): string;
-/** Default tooltip, in English. Escapes every value, since they come from the consumer. */
-export declare const defaultTooltipFormatter: ITICTooltipFormatter;
-export declare const DEFAULT_SETTINGS: ITICChartSettings;
+/**
+ * Returns the tooltip HTML of a point: one row per field, in the chart's language. Rows without a value
+ * are left out, and every value is escaped, since it comes from the consumer's data.
+ */
+export declare function createTooltipFormatter({ locale, timeZone }: ITICChartSettings): (point: ITICPoint, group: ITICChartMarks) => string;
+/** Formats the axis labels in the chart's language; ECharts always uses English separators. */
+export declare function createAxisLabelFormatter(locale: ITICLocale): (value: number) => string;
 export declare const isClickable: (point: ITICPoint) => boolean;
 export declare function buildChartOptions(groups: ITICChartMarks[], settings?: ITICChartSettings): EChartsOption;
 /**
- * Maps an ECharts click back to the original point and group, which `buildChartOptions` draws as
- * scatter series after the ITIC curve series, in the same order as `groups`.
+ * Maps an ECharts click back to the original point and group. `buildChartOptions` draws the groups as
+ * scatter series after the ITIC curve series, sorted with `sortGroups`.
  * Returns `undefined` for clicks outside the points and on points that aren't clickable.
  */
 export declare function findClickedPoint(groups: ITICChartMarks[], { componentType, seriesIndex, dataIndex }: {

package/dist/types/components/itic-chart/itic-chart.phases.d.ts

@@ -0,0 +1,17 @@
+import { type ITICMessages } from './itic-chart.i18n';
+export type ITICPhase = {
+    /** Name in the legend and the tooltip. Empty for `NONE`. */
+    name: string;
+    /** Fixed color, or `undefined` to use the ECharts palette. */
+    color?: string;
+};
+/** Name, in the given language, and color of a phase code. */
+export declare function getPhase(phase: unknown, messages: ITICMessages): ITICPhase;
+/**
+ * Sorts groups by phase name, then by code (e.g. `AN` and `AB` are both "L1"), with `NONE` and `ALL` last.
+ * Compares characters, not with a locale's rules, so the legend is the same in every language.
+ * Returns a new array with the same group objects; groups with the same code keep their order.
+ */
+export declare function sortGroups<T extends {
+    phase?: unknown;
+}>(groups: T[]): T[];

package/dist/types/components.d.ts

@@ -5,28 +5,23 @@
  * It contains typing information for all components that exist in this project.
  */
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
-import { ITICChartMarks, ITICPointClickDetail, ITICTooltipFormatter } from "./components/itic-chart/itic-chart.options";
-export { ITICChartMarks, ITICPointClickDetail, ITICTooltipFormatter } from "./components/itic-chart/itic-chart.options";
+import { ITICChartMarks, ITICPointClickDetail } from "./components/itic-chart/itic-chart.options";
+export { ITICChartMarks, ITICPointClickDetail } from "./components/itic-chart/itic-chart.options";
 export namespace Components {
     interface IticChart {
         /**
-          * Point groups, as an array or a JSON string. Extra fields in groups and points are kept and passed back in `pointClick` and `tooltipFormatter`.
+          * Point groups, as an array or a JSON string. Each group's `phase` code sets its name, color and order. Extra fields in groups and points are kept and passed back in `pointClick`.
          */
         "groups": ITICChartMarks[] | string;
         /**
-          * Returns the HTML of a point's tooltip. JS/React property only (not an HTML attribute). The HTML is inserted as is: escaping the values is up to the formatter. Defaults to an English tooltip with phase, duration, voltage and timestamp.
+          * Language of the texts, dates and numbers: `ca`, `de`, `en`, `es`, `fr` or `pt`. Only the language is used (`es-ES` → `es`); any other value falls back to `en`.
+          * @default 'en'
          */
-        "tooltipFormatter"?: ITICTooltipFormatter;
+        "locale": string;
         /**
-          * Name of the duration (X) axis.
-          * @default 'Duration (ms)'
+          * IANA time zone of the dates in the tooltip (e.g. `Europe/Madrid`). Defaults to the browser's, which is also used, with a console error, when the value isn't valid.
          */
-        "xAxisName": string;
-        /**
-          * Name of the voltage (Y) axis.
-          * @default 'Voltage (% of nominal voltage)'
-         */
-        "yAxisName": string;
+        "timeZone"?: string;
     }
 }
 export interface IticChartCustomEvent<T> extends CustomEvent<T> {
@@ -58,33 +53,28 @@ declare global {
 declare namespace LocalJSX {
     interface IticChart {
         /**
-          * Point groups, as an array or a JSON string. Extra fields in groups and points are kept and passed back in `pointClick` and `tooltipFormatter`.
+          * Point groups, as an array or a JSON string. Each group's `phase` code sets its name, color and order. Extra fields in groups and points are kept and passed back in `pointClick`.
          */
         "groups"?: ITICChartMarks[] | string;
         /**
-          * Emitted when a clickable point is clicked (`clickable` isn't `false`). `detail` holds the original point and group objects.
-         */
-        "onPointClick"?: (event: IticChartCustomEvent<ITICPointClickDetail>) => void;
-        /**
-          * Returns the HTML of a point's tooltip. JS/React property only (not an HTML attribute). The HTML is inserted as is: escaping the values is up to the formatter. Defaults to an English tooltip with phase, duration, voltage and timestamp.
+          * Language of the texts, dates and numbers: `ca`, `de`, `en`, `es`, `fr` or `pt`. Only the language is used (`es-ES` → `es`); any other value falls back to `en`.
+          * @default 'en'
          */
-        "tooltipFormatter"?: ITICTooltipFormatter;
+        "locale"?: string;
         /**
-          * Name of the duration (X) axis.
-          * @default 'Duration (ms)'
+          * Emitted when a clickable point is clicked (`clickable` isn't `false`). `detail` holds the original point and group objects.
          */
-        "xAxisName"?: string;
+        "onPointClick"?: (event: IticChartCustomEvent<ITICPointClickDetail>) => void;
         /**
-          * Name of the voltage (Y) axis.
-          * @default 'Voltage (% of nominal voltage)'
+          * IANA time zone of the dates in the tooltip (e.g. `Europe/Madrid`). Defaults to the browser's, which is also used, with a console error, when the value isn't valid.
          */
-        "yAxisName"?: string;
+        "timeZone"?: string;
     }
 
     interface IticChartAttributes {
         "groups": ITICChartMarks[] | string;
-        "xAxisName": string;
-        "yAxisName": string;
+        "locale": string;
+        "timeZone": string;
     }
 
     interface IntrinsicElements {

package/dist/types/index.d.ts

@@ -8,4 +8,4 @@
  * to consume components of this package as outlined in the `README.md`.
  */
 export type * from './components';
-export type { ITICChartMarks, ITICPoint, ITICPointClickDetail, ITICTooltipFormatter, } from './components/itic-chart/itic-chart.options';
+export type { ITICChartMarks, ITICPoint, ITICPointClickDetail, } from './components/itic-chart/itic-chart.options';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circutor/charts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Charts used by the Circutor Cloud team, as framework-agnostic Web Components",
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",
@@ -52,9 +52,6 @@
     "test:visual": "vitest run --project visual",
     "generate": "stencil generate"
   },
-  "dependencies": {
-    "dayjs": "^1.11.13"
-  },
   "peerDependencies": {
     "echarts": "^6.1.0"
   },
@@ -70,5 +67,5 @@
     "vitest": "^5.0.5"
   },
   "license": "MIT",
-  "gitHead": "8a3014c8d5a5691aa784640a5ad5008c661e7a57"
+  "gitHead": "00048fd4dea626e18224e8d3da1205d32f14e441"
 }

package/readme.md

@@ -15,7 +15,7 @@ To use the chart as a Web Component, simply import it from the CDN in your HTML
 ```html
 <script
   type="module"
-  src="https://unpkg.com/@circutor/charts@0.2.0/dist/charts/charts.esm.js"
+  src="https://unpkg.com/@circutor/charts@0.3.0/dist/charts/charts.esm.js"
 ></script>
 ```
 
@@ -23,7 +23,9 @@ Then, you can directly insert the chart into your HTML:
 
 ```html
 <itic-chart
-  groups='[{"groupName":"L1,L2,L3","points":[{"duration":230,"voltage":93.46,"ts":"2024-06-26T20:23:45.220000+02:00"}],"color":"#00B388"},{"groupName":"L2","points":[{"duration":20,"voltage":0.4000000000000057,"ts":"2025-01-26T23:04:34.840000+01:00"}],"color":"#20262C"}]'
+  locale="es"
+  time-zone="Europe/Madrid"
+  groups='[{"phase":"AN,BN,CN","assetName":"Cuadro general","points":[{"duration":230,"voltage":93.46,"ts":"2024-06-26T20:23:45.220000+02:00","eventType":"VOLTAGE_DIP"}]},{"phase":"BN","assetName":"Cuadro general","points":[{"duration":20,"voltage":0.4000000000000057,"ts":"2025-01-26T23:04:34.840000+01:00","eventType":"POWER_INTERRUPT"}]}]'
 ></itic-chart>
 ```
 
@@ -42,7 +44,7 @@ The CDN files include ECharts, so there is nothing else to load. Charts on the s
 
     <script
       type="module"
-      src="https://unpkg.com/@circutor/charts@0.2.0/dist/charts/charts.esm.js"
+      src="https://unpkg.com/@circutor/charts@0.3.0/dist/charts/charts.esm.js"
     ></script>
 
     <style>
@@ -59,7 +61,9 @@ The CDN files include ECharts, so there is nothing else to load. Charts on the s
   </head>
   <body>
     <itic-chart
-      groups='[{"groupName":"L1,L2,L3","points":[{"duration":230,"voltage":93.46,"ts":"2024-06-26T20:23:45.220000+02:00"}],"color":"#00B388"},{"groupName":"L2","points":[{"duration":20,"voltage":0.4000000000000057,"ts":"2025-01-26T23:04:34.840000+01:00"}],"color":"#20262C"}]'
+      locale="es"
+      time-zone="Europe/Madrid"
+      groups='[{"phase":"AN,BN,CN","assetName":"Cuadro general","points":[{"duration":230,"voltage":93.46,"ts":"2024-06-26T20:23:45.220000+02:00","eventType":"VOLTAGE_DIP"}]},{"phase":"BN","assetName":"Cuadro general","points":[{"duration":20,"voltage":0.4000000000000057,"ts":"2025-01-26T23:04:34.840000+01:00","eventType":"POWER_INTERRUPT"}]}]'
     ></itic-chart>
   </body>
 </html>
@@ -81,11 +85,11 @@ For example, to load only the ITIC chart:
 ```html
 <script
   type="module"
-  src="https://unpkg.com/@circutor/charts@0.2.0/dist/components/itic-chart.js"
+  src="https://unpkg.com/@circutor/charts@0.3.0/dist/components/itic-chart.js"
 ></script>
 ```
 
-- Pin the version in the URL (`@circutor/charts@0.2.0`). Without it, the CDN serves the latest release, which may include breaking changes.
+- Pin the version in the URL (`@circutor/charts@0.3.0`). Without it, the CDN serves the latest release, which may include breaking changes.
 - Use one method per page. If a tag is loaded both ways, the first script to register it wins and the other is downloaded for nothing.
 
 #### With a bundler (without React)
@@ -102,11 +106,10 @@ Import each chart from `@circutor/charts/components/<tag>`; importing it registe
 import '@circutor/charts/components/itic-chart';
 ```
 
-Function props (`tooltipFormatter`) and events (`pointClick`) are set from JavaScript:
+Events (`pointClick`) are listened to from JavaScript:
 
 ```js
 const chart = document.querySelector('itic-chart');
-chart.tooltipFormatter = (point, group) => `${escapeHtml(group.groupName)}: ${point.duration} ms`;
 chart.addEventListener('pointClick', event => openWaveforms(event.detail.point));
 ```
 
@@ -129,47 +132,53 @@ import { IticChart } from '@circutor/charts-react';
 Each wrapper imports only its own Web Component, so your bundler only includes the charts you import. ECharts comes from your application, shared with any other ECharts chart.
 
 3. **Use the component**  
-   Now, you can use the chart in your application like any other React component. Just pass the necessary data and configurations:
+   Now, you can use the chart in your application like any other React component. Pass the data, the user's language and time zone:
 
-```html
+```tsx
 <IticChart
-        groups={[
-          {
-            groupName: "L1,L2,L3",
-            points: [
-              {
-                duration: 230,
-                voltage: 93.46,
-                ts: "2024-06-26T20:23:45.220000+02:00",
-              },
-            ],
-            color: "#00B388",
-          },
-          {
-            groupName: "L2",
-            points: [
-              {
-                duration: 20,
-                voltage: 0.4000000000000057,
-                ts: "2025-01-26T23:04:34.840000+01:00",
-              },
-            ],
-            color: "#20262C",
-          },
-        ]}
-      ></IticChart>
+  locale="es"
+  timeZone="Europe/Madrid"
+  groups={[
+    {
+      phase: "AN,BN,CN",
+      assetName: "Cuadro general",
+      points: [
+        {
+          duration: 230,
+          voltage: 93.46,
+          ts: "2024-06-26T20:23:45.220000+02:00",
+          eventType: "VOLTAGE_DIP",
+        },
+      ],
+    },
+    {
+      phase: "BN",
+      assetName: "Cuadro general",
+      points: [
+        {
+          duration: 20,
+          voltage: 0.4000000000000057,
+          ts: "2025-01-26T23:04:34.840000+01:00",
+          eventType: "POWER_INTERRUPT",
+        },
+      ],
+    },
+  ]}
+  onPointClick={({ detail }) => openWaveforms(detail.point)}
+/>
 ```
 
 `@circutor/charts-react` expects `react` and `react-dom` 18 or 19 to be installed in your application.
 
 ### ITIC chart options
 
+The ITIC chart only takes data, plus the language and time zone. The chart decides what is shown and how: the tooltip, the translations, the axis names, the accessible name, and each phase's name, color and order. Every prop is data or a string, so the chart is the same in plain HTML and React.
+
 | Property (React prop) | Attribute | Type | Default | Description |
 |---|---|---|---|---|
-| `groups` | `groups` | `ITICChartMarks[] \| string` | – | Point groups: `groupName` (legend label), `color` and `points` (`duration` in ms, `voltage` in % of nominal, `ts` timestamp, optional `clickable`). As an attribute, a JSON string. |
-| `xAxisName` | `x-axis-name` | `string` | `Duration (ms)` | Name of the duration axis. |
-| `yAxisName` | `y-axis-name` | `string` | `Voltage (% of nominal voltage)` | Name of the voltage axis. |
-| `tooltipFormatter` | – | `(point, group) => string` | English tooltip | HTML of a point's tooltip. JS/React property only. |
+| `groups` | `groups` | `ITICChartMarks[] \| string` | – | Point groups (see [Data](#data)). As an attribute, a JSON string. |
+| `locale` | `locale` | `string` | `'en'` | Language of the texts, event types, axes, `aria-label`, translated phases, dates and numbers. Only the language is used (`es-ES` → `es`); anything other than `ca`, `de`, `en`, `es`, `fr` or `pt` falls back to `en`. |
+| `timeZone` | `time-zone` | `string` (IANA) | The browser's | Time zone of the dates in the tooltip, e.g. `Europe/Madrid`. An invalid value uses the browser's and logs a `console.error`. |
 
 | Event (React prop) | `detail` | Description |
 |---|---|---|
@@ -179,55 +188,109 @@ Each wrapper imports only its own Web Component, so your bundler only includes t
 |---|---|---|
 | `--itic-chart-background` | `transparent` | Background behind the whole chart. |
 
+#### Data
+
+Each group holds the events of one phase of an asset:
+
+| Group field | Type | Description |
+|---|---|---|
+| `phase` | `string` | Phase code (`AN`, `AB,BC,CA`, `ALL`, `NONE`…). Sets the group's name, color and order (see [Phases](#phases)). |
+| `assetName` | `string`, optional | Asset name, shown in the tooltip. |
+| `points` | `ITICPoint[]` | The voltage events. |
+
+| Point field | Type | Description |
+|---|---|---|
+| `duration` | `number` | Duration, in ms. |
+| `voltage` | `number` | Voltage, in % of the nominal voltage. |
+| `ts` | `string` | Date of the event, ISO 8601. |
+| `clickable` | `boolean`, optional | `false` hides the pointer cursor and emits no `pointClick`. Defaults to `true`. |
+| `eventType` | `string`, optional | Event type code from the backend (see [Event types](#event-types)), translated in the tooltip. |
+| `status` | `string`, optional | Status code from the backend, shown as is. |
+| `min` / `max` | `number`, optional | Minimum and maximum voltage, in V. |
+
+The axes have fixed ranges: duration from 1 to 100,000 ms (logarithmic) and voltage from 0 to 200%. **Points outside them aren't drawn** (e.g. a duration below 1 ms or a voltage above 200%).
+
+#### Tooltip
+
+The tooltip shows these rows, in this order, in the chart's `locale`. Rows without a value are left out, and every value is escaped, so data can't inject HTML.
+
+| Row (`en`) | Value | Left out when |
+|---|---|---|
+| Asset | `assetName` | missing or empty |
+| Date | `ts` with milliseconds, in `timeZone` (e.g. `Jun 26, 20:23:45.220`, `26 jun, 20:23:45,220`) | never; an invalid date is shown as is |
+| Event | translated `eventType`; unknown codes as is | missing or empty |
+| Duration | e.g. `1,500 ms` (`1500 ms` in `es`) | never |
+| Voltage | rounded to 1 decimal, e.g. `93.5%` (`93,5 %` in `es`) | never |
+| Status | `status` as is | missing or empty |
+| Phase | phase name; `-` for `NONE` | never |
+| Min / Max | 2 decimals, e.g. `207.12 V` | missing or `0` |
+
+Numbers use the separators of each language, also in the axis labels: in `es` the duration axis reads `1000`, `10.000`, `100.000` (Spanish doesn't group 4-digit numbers).
+
+The tooltip is added to `document.body`, not inside the chart, so containers with `overflow: hidden` don't clip it. Its styles are inline, so it looks the same.
+
+#### Phases
+
+The chart names, colors and sorts the groups from their `phase` code, so every app draws the same phases the same way:
+
+| Code | Name | Color |
+|---|---|---|
+| `AN`, `AB` | L1 | `#a67c52` |
+| `BN`, `BC` | L2 | `#20262C` |
+| `CN`, `CA` | L3 | `#B9BDC0` |
+| `AN,BN,CN`, `AB,BC,CA` | L1,L2,L3 | `#00B388` |
+| `ALL` | Translated: All, Todas, Totes, Alle, Toutes | `#4C5CC5` |
+| `A`, `B`, `C` | L1, L2, L3 | ECharts palette |
+| `AN,BN`, `AN,CN`, `BN,CN`, `AB,BC`, `AB,CA`, `BC,CA` | L1,L2 · L1,L3 · L2,L3 | ECharts palette |
+| `NONE` | No name | ECharts palette |
+| Any other | The code as is | ECharts palette |
+
+- Groups are sorted by name (`L1`, `L1,L2,L3`, `L2`, `L3`), then by code, whatever order they come in, with `NONE` and then `ALL` last. Groups with the same code keep their order.
+- Phase-neutral and phase-phase codes share names and colors: `AN` and `AB` in the same chart are two "L1" groups you can't tell apart, and one legend item toggles both.
+- `NONE` groups have no name, so they don't appear in the legend (their points are drawn) and their tooltip shows `-` as phase.
+- Phases without a fixed color take the next one of the ECharts palette, so the same code may get different colors in different charts.
+
+#### Event types
+
+`eventType` codes with a translation (in `ca`, `de`, `en`, `es`, `fr` and `pt`). Any other code is shown as is.
+
+| Code | `en` | `es` |
+|---|---|---|
+| `VOLTAGE_DIP` | Voltage dip | Hueco de tensión |
+| `VOLTAGE_SWELL` | Voltage swell | Aumento de tensión |
+| `POWER_INTERRUPT` | Power interruption | Interrupción |
+| `VOLTAGE_TRANSIENT` | Voltage transient | Transitorio de voltaje |
+| `VOLTAGE_VARIATION` | Voltage variation | Variación de voltaje |
+| `OVER_VOLTAGE` | Overvoltage | Sobretensión |
+| `SUB_VOLTAGE` | Subvoltage | Subtensión |
+
 #### Clickable points
 
 Every point is clickable by default: it shows a pointer cursor and emits `pointClick`. Set `clickable: false` on a point to turn both off, e.g. for events without waveforms. Clicks on the ITIC curve or on non-clickable points emit nothing.
 
 #### Your own data in points and groups
 
-Points and groups accept any extra field (e.g. `eventType`, `waveforms`, `assetName`). The chart doesn't read or validate them; it passes them back in `pointClick` and `tooltipFormatter`. Cast them to your own types there:
+Points and groups accept any extra field (e.g. `waveforms`). The chart doesn't read or validate them; it passes them back in `pointClick`. Cast them to your own types there:
 
 ```tsx
 import { IticChart, type ITICChartMarks, type ITICPoint } from '@circutor/charts-react';
 
 // Use `extends` (or `&`) so your types are assignable to the chart's
 interface EventPoint extends ITICPoint {
-  eventType: string;
   waveforms: Waveform[];
 }
 interface AssetGroup extends ITICChartMarks {
-  assetName: string;
   points: EventPoint[];
 }
 
 <IticChart
   groups={groups}
+  locale={locale}
+  timeZone={timeZone}
   onPointClick={({ detail }) => openWaveforms(detail.point as EventPoint, detail.group as AssetGroup)}
 />;
 ```
 
-#### Translations and custom tooltips
-
-The axis names and the default tooltip are in English. Pass `xAxisName`, `yAxisName` and a `tooltipFormatter` to translate them or to show other fields, formatting dates with your user's locale and time zone:
-
-```tsx
-const formatDate = new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'medium', timeZone }).format;
-
-// Define it outside the component (or with useCallback): a new function redraws the chart
-const tooltipFormatter: ITICTooltipFormatter = (point, group) =>
-  [
-    `<strong>${t('asset')}</strong>: ${escapeHtml((group as AssetGroup).assetName)}`,
-    `<strong>${t('timestamp')}</strong>: ${formatDate(new Date(point.ts))}`,
-    `<strong>${t('duration')}</strong>: ${point.duration} ms`,
-  ].join('<br/>');
-
-<IticChart groups={groups} xAxisName={t('duration')} yAxisName={t('voltage')} tooltipFormatter={tooltipFormatter} />;
-```
-
-> **The HTML returned by `tooltipFormatter` is inserted as is.** Escape any value that may contain HTML (names, free text) yourself. The default tooltip escapes every value.
-
-The tooltip is added to `document.body`, not inside the chart, so containers with `overflow: hidden` don't clip it. Its styles are inline, so it looks the same.
-
 ### Size and data updates
 
 - The chart takes the full width of its container and is `400px` high by default. Any CSS rule on `itic-chart` in your page wins over that default, e.g. `itic-chart { height: 300px; }`, or, to grow with a flex container:
@@ -236,19 +299,19 @@ The tooltip is added to `document.body`, not inside the chart, so containers wit
   .card itic-chart { flex: 1; min-height: 400px; }
   ```
   The chart redraws automatically whenever its size changes.
-- Updating `groups` (a new array from JS/React or a new JSON string in the attribute) redraws the chart; groups that are no longer present are removed.
+- Updating `groups` (a new array from JS/React or a new JSON string in the attribute), `locale` or `timeZone` redraws the chart; groups that are no longer present are removed.
 
 ### Accessibility
 
-The chart is drawn on a canvas, so the element gets `role="img"` (unless you set another `role`). Describe it with `aria-label`, which the React wrapper passes to the element:
+The chart is drawn on a canvas, so the element gets `role="img"` (unless you set another `role`) and a translated `aria-label` ("ITIC chart", "Curva ITIC"…) that follows `locale`. Set your own `aria-label` to describe it better; the chart then leaves it alone:
 
 ```tsx
-<IticChart groups={groups} aria-label="ITIC curve of the voltage events of Main panel" />
+<IticChart groups={groups} locale="es" aria-label="Curva ITIC de los eventos de tensión del cuadro general" />
 ```
 
 ### Next.js (App Router)
 
-- The React wrappers are client components (`'use client'`). A Server Component can render `<IticChart>` with serializable props (`groups`, axis names, `aria-label`), but `onPointClick` and `tooltipFormatter` are functions: pass them from your own `'use client'` component.
+- The React wrappers are client components (`'use client'`). A Server Component can render `<IticChart>` with serializable props (`groups`, `locale`, `timeZone`, `aria-label`), but `onPointClick` is a function: pass it from your own `'use client'` component.
 - Server-side rendering works without `next/dynamic` or `ssr: false`: importing the wrappers doesn't touch the DOM, the server renders an empty `<itic-chart>` and the chart draws in the browser after hydration, without hydration warnings.
 
 ### Testing with Vitest and jsdom
@@ -261,9 +324,11 @@ import { vi } from 'vitest';
 import type { ITICChartMarks, ITICPointClickDetail } from '@circutor/charts-react';
 
 vi.mock('@circutor/charts-react', () => ({
-  // One button per point, so tests can find points and click them
-  IticChart: ({ groups = [], onPointClick, 'aria-label': ariaLabel }: {
+  // One button per point, so tests can find points and click them. `locale` and `timeZone` are ignored.
+  IticChart: ({ groups = [], onPointClick, 'aria-label': ariaLabel = 'ITIC chart' }: {
     groups?: ITICChartMarks[];
+    locale?: string;
+    timeZone?: string;
     onPointClick?: (event: CustomEvent<ITICPointClickDetail>) => void;
     'aria-label'?: string;
   }) => (
@@ -271,11 +336,11 @@ vi.mock('@circutor/charts-react', () => ({
       {groups.flatMap(group =>
         group.points.map((point, index) => (
           <button
-            key={`${group.groupName}-${index}`}
+            key={`${group.phase}-${index}`}
             disabled={point.clickable === false}
             onClick={() => onPointClick?.(new CustomEvent('pointClick', { detail: { point, group } }))}
           >
-            {group.groupName} {point.ts}
+            {group.phase} {point.ts}
           </button>
         )),
       )}
@@ -284,4 +349,4 @@ vi.mock('@circutor/charts-react', () => ({
 }));
 ```
 
-Then `fireEvent.click(screen.getByText('L1 2024-06-26T20:23:45.220000+02:00'))` calls your `onPointClick` with the original point.
+Then `fireEvent.click(screen.getByText('AN 2024-06-26T20:23:45.220000+02:00'))` calls your `onPointClick` with the original point.