@circutor/charts-react 0.1.0 → 0.3.0

package/README.md

@@ -1,122 +1,209 @@
-### MYC Charts
+### @circutor/charts-react
 
-This repository aims to make the charts used by the Cloud team in their web applications accessible to the rest of the organization. This will facilitate their reuse, standardization, and maintenance across different projects.
+React components for the charts used by the Circutor Cloud team. They wrap the Web Components from [`@circutor/charts`](https://www.npmjs.com/package/@circutor/charts), so you get typed props and React-friendly usage.
 
-### How to Use
+### Install
 
-**Base Scenario**: We want to use the ITIC curve chart.
-
-#### As a Web Component
-
-To use the chart as a Web Component, simply import it from the CDN in your HTML code.
-
-```html
-<script
-  type="module"
-  src="https://unpkg.com/@circutor/charts/dist/charts/charts.esm.js"
-></script>
-<script
-  nomodule
-  src="https://unpkg.com/@circutor/charts/dist/charts/charts.js"
-></script>
 ```
-
-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"}]'
-></itic-chart>
-```
-
-<details>
-<summary>Complete example</summary>
-
-```html
-<!DOCTYPE html>
-<html lang="es">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Charts</title>
-
-    <script
-      type="module"
-      src="https://unpkg.com/@circutor/charts/dist/charts/charts.esm.js"
-    ></script>
-    <script
-      nomodule
-      src="https://unpkg.com/@circutor/charts/dist/charts/charts.js"
-    ></script>
-
-    <style>
-      body {
-        font-family: Arial, sans-serif;
-        text-align: center;
-        padding: 20px;
-      }
-      mi-componente {
-        display: block;
-        margin-top: 20px;
-      }
-    </style>
-  </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"}]'
-    ></itic-chart>
-  </body>
-</html>
+npm install @circutor/charts-react echarts
 ```
 
-</details>
-
-#### From a React Application
-
-1. **Install the package**  
-   First, you need to install the `@circutor/charts-react` package in your project:
-
-```
-npm install @circutor/charts-react
+- `echarts` 6 is a peer dependency of `@circutor/charts`: the charts use your application's copy, so it isn't bundled twice when your app also uses ECharts.
+- `react` and `react-dom` 18 or 19 must be installed in your application. `@circutor/charts` is installed automatically.
+
+Each component imports only its own Web Component, so your bundler only includes the charts you import.
+
+### 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 = [
+  {
+    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.4, ts: '2025-01-26T23:04:34.840000+01:00', eventType: 'POWER_INTERRUPT', clickable: false }],
+  },
+];
+
+export function PowerQuality() {
+  return (
+    <IticChart
+      groups={groups}
+      locale="es"
+      timeZone="Europe/Madrid"
+      onPointClick={({ detail }) => console.log(detail.point, detail.group)}
+    />
+  );
+}
 ```
 
-2. **Import the component**  
-   Then, import the component into your React file:
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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` | 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` 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. `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 {
+  waveforms: Waveform[];
+}
+interface AssetGroup extends ITICChartMarks {
+  points: EventPoint[];
+}
 
-```javascript
-import { IticChart } from '@circutor/charts-react';`>
+<IticChart
+  groups={groups}
+  locale={locale}
+  timeZone={timeZone}
+  onPointClick={({ detail }) => openWaveforms(detail.point as EventPoint, detail.group as AssetGroup)}
+/>;
 ```
 
-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:
-
-```html
-<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>
+### 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:
+  ```css
+  .card { display: flex; flex-direction: column; }
+  .card itic-chart { flex: 1; min-height: 400px; }
+  ```
+  The chart redraws automatically whenever its size changes.
+- 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`, `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
+
+jsdom has no canvas, so ECharts can't draw there and logs `getContext()` errors. Mock the wrappers in a setup file (`setupFiles` in your Vitest config), so every test gets a plain element instead:
+
+```tsx
+// vitest.setup.tsx
+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. `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;
+  }) => (
+    <div role="img" aria-label={ariaLabel} data-testid="itic-chart">
+      {groups.flatMap(group =>
+        group.points.map((point, index) => (
+          <button
+            key={`${group.phase}-${index}`}
+            disabled={point.clickable === false}
+            onClick={() => onPointClick?.(new CustomEvent('pointClick', { detail: { point, group } }))}
+          >
+            {group.phase} {point.ts}
+          </button>
+        )),
+      )}
+    </div>
+  ),
+}));
 ```
 
-Remember to consult the documentation for each component for more details and configuration options.
+Then `fireEvent.click(screen.getByText('AN 2024-06-26T20:23:45.220000+02:00'))` calls your `onPointClick` with the original point.

package/dist/components/stencil-generated/components.js

@@ -1,12 +1,12 @@
 'use client';
 import { createComponent } from '@stencil/react-output-target/runtime';
 import React from 'react';
-import { IticChart as IticChartElement, defineCustomElement as defineIticChart } from "@circutor/charts/dist/components/itic-chart.js";
+import { IticChart as IticChartElement, defineCustomElement as defineIticChart } from "@circutor/charts/dist/bundler/itic-chart.js";
 export const IticChart = createComponent({
     tagName: 'itic-chart',
     elementClass: IticChartElement,
     react: React,
-    events: {},
+    events: { onPointClick: 'pointClick' },
     defineCustomElement: defineIticChart
 });
 //# sourceMappingURL=components.js.map

package/dist/components/stencil-generated/components.js.map

@@ -1 +1 @@
-{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../lib/components/stencil-generated/components.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAUb,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,SAAS,IAAI,gBAAgB,EAAE,mBAAmB,IAAI,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAIvI,MAAM,CAAC,MAAM,SAAS,GAAiG,eAAe,CAA0D;IAC5L,OAAO,EAAE,YAAY;IACrB,YAAY,EAAE,gBAAgB;IAE9B,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,EAAqB;IAC7B,mBAAmB,EAAE,eAAe;CACvC,CAAC,CAAC"}
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../lib/components/stencil-generated/components.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAUb,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,EAAE,SAAS,IAAI,gBAAgB,EAAE,mBAAmB,IAAI,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAIpI,MAAM,CAAC,MAAM,SAAS,GAAiG,eAAe,CAA0D;IAC5L,OAAO,EAAE,YAAY;IACrB,YAAY,EAAE,gBAAgB;IAE9B,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,EAAE,YAAY,EAAE,YAAY,EAAqB;IACzD,mBAAmB,EAAE,eAAe;CACvC,CAAC,CAAC"}

package/dist/types/components/stencil-generated/components.d.ts

@@ -1,5 +1,8 @@
-import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
-import type { Components } from "@circutor/charts/dist/components";
-import { IticChart as IticChartElement } from "@circutor/charts/dist/components/itic-chart.js";
-export type IticChartEvents = NonNullable<unknown>;
+import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
+import { type ITICPointClickDetail, type IticChartCustomEvent } from "@circutor/charts";
+import type { Components } from "@circutor/charts/dist/bundler";
+import { IticChart as IticChartElement } from "@circutor/charts/dist/bundler/itic-chart.js";
+export type IticChartEvents = {
+    onPointClick: EventName<IticChartCustomEvent<ITICPointClickDetail>>;
+};
 export declare const IticChart: StencilReactComponent<IticChartElement, IticChartEvents, Components.IticChart>;

package/dist/types/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circutor/charts-react",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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.1.0",
+    "@circutor/charts": "^0.3.0",
     "@stencil/react-output-target": "^1.6.5"
   },
   "repository": {
@@ -34,5 +34,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "44a514e1c49b34d4ab2a9e52d1354c3753c76e0b"
+  "gitHead": "00048fd4dea626e18224e8d3da1205d32f14e441"
 }