@circutor/charts-react 0.2.0 → 0.3.1

package/README.md

@@ -15,19 +15,21 @@ Each component imports only its own Web Component, so your bundler only includes
 
 ### ITIC chart
 
+The chart only takes data, plus the language and time zone. It decides what is shown and how: the tooltip, the translations, the axis names, the accessible name, and each phase's name, color and order.
+
 ```tsx
 import { IticChart } from '@circutor/charts-react';
 
 const groups = [
   {
-    groupName: 'L1,L2,L3',
-    color: '#00B388',
-    points: [{ duration: 230, voltage: 93.46, ts: '2024-06-26T20:23:45.220000+02:00' }],
+    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' }],
   },
   {
-    groupName: 'L2',
-    color: '#20262C',
-    points: [{ duration: 20, voltage: 0.4, ts: '2025-01-26T23:04:34.840000+01:00', clickable: false }],
+    phase: 'BN',
+    assetName: 'Cuadro general',
+    points: [{ duration: 20, voltage: 0.4, ts: '2025-01-26T23:04:34.840000+01:00', eventType: 'POWER_INTERRUPT', clickable: false }],
   },
 ];
 
@@ -35,7 +37,8 @@ export function PowerQuality() {
   return (
     <IticChart
       groups={groups}
-      aria-label="ITIC curve of the voltage events"
+      locale="es"
+      timeZone="Europe/Madrid"
       onPointClick={({ detail }) => console.log(detail.point, detail.group)}
     />
   );
@@ -44,66 +47,115 @@ export function PowerQuality() {
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `groups` | `ITICChartMarks[]` | – | Point groups: `groupName` (legend label), `color` and `points` (`duration` in ms, `voltage` in % of nominal, `ts` timestamp, optional `clickable`). |
-| `xAxisName` | `string` | `Duration (ms)` | Name of the duration axis. |
-| `yAxisName` | `string` | `Voltage (% of nominal voltage)` | Name of the voltage axis. |
-| `tooltipFormatter` | `(point, group) => string` | English tooltip | HTML of a point's tooltip. |
+| `groups` | `ITICChartMarks[]` | – | Point groups (see [Data](#data)). |
+| `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` | `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`. |
 | `onPointClick` | `(event: CustomEvent<ITICPointClickDetail>) => void` | – | A clickable point was clicked. `event.detail` holds the `point` and `group` objects you passed in `groups`. |
-| `aria-label` | `string` | – | Accessible name. The element has `role="img"`, since the chart is a canvas. |
+| `aria-label` | `string` | Translated "ITIC chart" | Accessible name. The element has `role="img"`, since the chart is a canvas. The default follows `locale`; a value you set is left alone. |
 
-The `ITICChartMarks`, `ITICPoint`, `ITICPointClickDetail` and `ITICTooltipFormatter` types are exported by this package.
+The `ITICChartMarks`, `ITICPoint` and `ITICPointClickDetail` types are exported by this package.
 
 The background is transparent; set it with the `--itic-chart-background` CSS custom property, e.g. `itic-chart { --itic-chart-background: #fafafb; }`.
 
+#### Data
+
+| 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 `onPointClick`. 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.
+
+#### Phases
+
+| 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 `onPointClick`. Set `clickable: false` on a point to turn both off, e.g. for events without waveforms.
 
 #### 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 `onPointClick` 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 `onPointClick`. 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.
-
 ### 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` wins over that default, e.g. `itic-chart { height: 300px; }`, or, to grow with a flex container:
@@ -112,11 +164,11 @@ 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.
-- Passing a new `groups` array redraws the chart; groups that are no longer present are removed.
+- Passing a new `groups` array, `locale` or `timeZone` redraws the chart; groups that are no longer present are removed.
 
 ### Next.js (App Router)
 
-- The 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 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
@@ -129,9 +181,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;
   }) => (
@@ -139,11 +193,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>
         )),
       )}
@@ -152,4 +206,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.

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
 export * from './components/stencil-generated/components';
-export type { ITICChartMarks, ITICPoint, ITICPointClickDetail, ITICTooltipFormatter } from '@circutor/charts';
+export type { ITICChartMarks, ITICPoint, ITICPointClickDetail } from '@circutor/charts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circutor/charts-react",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "React wrappers for the @circutor/charts Web Components",
   "author": "apinto <apinto@circutor.com>",
   "license": "ISC",
@@ -24,7 +24,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@circutor/charts": "^0.2.0",
+    "@circutor/charts": "^0.3.1",
     "@stencil/react-output-target": "^1.6.5"
   },
   "repository": {
@@ -34,5 +34,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8a3014c8d5a5691aa784640a5ad5008c661e7a57"
+  "gitHead": "cb1dba202f82c6b0493e8d262426ff6b2b70d3d5"
 }