@circutor/charts-react 0.1.0 → 0.2.0

package/README.md

@@ -1,122 +1,155 @@
-### 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.
+```
+npm install @circutor/charts-react echarts
+```
 
-#### As a Web Component
+- `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
+
+```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' }],
+  },
+  {
+    groupName: 'L2',
+    color: '#20262C',
+    points: [{ duration: 20, voltage: 0.4, ts: '2025-01-26T23:04:34.840000+01:00', clickable: false }],
+  },
+];
+
+export function PowerQuality() {
+  return (
+    <IticChart
+      groups={groups}
+      aria-label="ITIC curve of the voltage events"
+      onPointClick={({ detail }) => console.log(detail.point, detail.group)}
+    />
+  );
+}
+```
 
-To use the chart as a Web Component, simply import it from the CDN in your HTML code.
+| 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. |
+| `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. |
 
-```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>
-```
+The `ITICChartMarks`, `ITICPoint`, `ITICPointClickDetail` and `ITICTooltipFormatter` types are exported by this package.
 
-Then, you can directly insert the chart into your HTML:
+The background is transparent; set it with the `--itic-chart-background` CSS custom property, e.g. `itic-chart { --itic-chart-background: #fafafb; }`.
 
-```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>
-```
+#### Clickable points
 
-<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>
-```
+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.
 
-</details>
+#### Your own data in points and groups
 
-#### From a React Application
+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:
 
-1. **Install the package**  
-   First, you need to install the `@circutor/charts-react` package in your project:
+```tsx
+import { IticChart, type ITICChartMarks, type ITICPoint } from '@circutor/charts-react';
 
-```
-npm install @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}
+  onPointClick={({ detail }) => openWaveforms(detail.point as EventPoint, detail.group as AssetGroup)}
+/>;
 ```
 
-2. **Import the component**  
-   Then, import the component into your React file:
+#### Translations and custom tooltips
 
-```javascript
-import { IticChart } from '@circutor/charts-react';`>
-```
+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:
 
-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:
+```tsx
+const formatDate = new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'medium', timeZone }).format;
 
-```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>
+// 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:
+  ```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 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.
+- 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
+  IticChart: ({ groups = [], onPointClick, 'aria-label': ariaLabel }: {
+    groups?: ITICChartMarks[];
+    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.groupName}-${index}`}
+            disabled={point.clickable === false}
+            onClick={() => onPointClick?.(new CustomEvent('pointClick', { detail: { point, group } }))}
+          >
+            {group.groupName} {point.ts}
+          </button>
+        )),
+      )}
+    </div>
+  ),
+}));
 ```
 
-Remember to consult the documentation for each component for more details and configuration options.
+Then `fireEvent.click(screen.getByText('L1 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, ITICTooltipFormatter } from '@circutor/charts';

package/package.json

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