@oliasoft-open-source/charts-library 8.0.0-beta-1 → 8.0.0-beta-2

package/README.md

@@ -1,3 +1,433 @@
 # Chart Library
 
 Reusable charts for use in React applications.
+
+## Usage and defaults
+
+The component JSDoc contains usage examples with sample data, labels and an explicit height.
+Those example values are not defaults.
+
+The sections below show the complete library-normalized configuration for `getDefaultProps({ chart: {} })`.
+You do not need to pass these objects: omitted options receive these values automatically.
+
+- `undefined` means the library leaves that value unspecified; it does not mean zero or false.
+- Empty data is the default. Supply your own DS to draw a chart.
+- These are library defaults, not a dump of Chart.js or plugin defaults. Final rendering can also depend on
+  data, container size, theme, plugin configuration and, for LineChart, persisted control state.
+- Compatibility fields may appear in normalized output without affecting rendering; see their public type documentation.
+- Default unit-selector callbacks are no-ops; consumers own unit selection and data conversion.
+- The snapshots describe the initial empty configuration. Per-item defaults for supplied annotations and DS are
+  applied separately by their normalizers and renderers.
+
+## Migrating LineChart tooltips to 8.0
+
+Tooltip coordinate roles no longer depend on axis placement. The default title shows X and the DS row shows Y.
+Set `options.tooltip.titleAxis` to `'y'` when the title should show Y and the DS row should show X.
+Charts that previously relied on a top-positioned X axis must set this explicitly to preserve their tooltip order.
+If your application swaps X/Y coordinates, update `titleAxis` to keep the intended quantity in the title.
+This setting does not move axes, reverse scales or transpose data.
+
+The default DS row reads units from the corresponding axis `unit` string or `unit.selectedUnit` when non-empty,
+then falls back to units in square brackets in that axis label. The title appends its axis label.
+Each hovered DS uses its own axis bindings, including numbered IDs such as `x10` and `y10`.
+Time and category values retain their formatted labels. Custom `title`, `label` and `afterLabel` callbacks
+continue to override their respective defaults independently.
+
+## LineChart
+
+```ts
+const noop = () => {
+  // Default unit selection does not change consumer state.
+};
+
+const defaultChart = {
+  persistenceId: '',
+  controlsPortalId: '',
+  testId: undefined,
+  data: {
+    datasets: [],
+  },
+  options: {
+    title: '',
+    scales: {
+      x: {},
+      y: {},
+    },
+    axes: {
+      x: [
+        {
+          label: '',
+          position: 'bottom',
+          color: '',
+          unit: {
+            options: [],
+            selectedUnit: '',
+            setSelectedUnit: noop,
+          },
+        },
+      ],
+      y: [
+        {
+          label: '',
+          position: 'left',
+          color: '',
+          unit: {
+            options: [],
+            selectedUnit: '',
+            setSelectedUnit: noop,
+          },
+        },
+      ],
+    },
+    additionalAxesOptions: {
+      chartScaleType: 'linear',
+      reverse: false,
+      beginAtZero: false,
+      stepSize: undefined,
+      suggestedMin: undefined,
+      suggestedMax: undefined,
+      range: undefined,
+      autoAxisPadding: false,
+    },
+    chartStyling: {
+      width: undefined,
+      height: undefined,
+      maintainAspectRatio: false,
+      staticChartHeight: false,
+      performanceMode: true,
+      squareAspectRatio: false,
+      layoutPadding: {
+        top: 0,
+        bottom: 20,
+        left: 0,
+        right: 0,
+      },
+    },
+    tooltip: {
+      tooltips: true,
+      showLabelsInTooltips: false,
+      hideSimulationName: false,
+      scientificNotation: true,
+      callbacks: undefined,
+      titleAxis: 'x',
+    },
+    graph: {
+      lineTension: 0.01,
+      spanGaps: false,
+      showDataLabels: false,
+      showMinorGridlines: false,
+    },
+    annotations: {
+      labelAnnotation: {
+        showLabel: false,
+        text: '',
+        position: 'bottom-right',
+        fontSize: 12,
+        xOffset: 5,
+        yOffset: 5,
+        maxWidth: 300,
+        lineHeight: 12,
+      },
+      showAnnotations: false,
+      controlAnnotation: false,
+      enableDragAnnotation: false,
+      enableCalloutAnnotation: false,
+      lineMarkersAnnotation: {
+        enabled: false,
+        itemGapPx: 4,
+        edgePaddingPx: 8,
+        horizontalLineLengthPx: undefined,
+        lineDirection: undefined,
+        labelCollisionPx: 4,
+        labelCollisionClusterXPx: 36,
+        enableLabelCollisionResolver: true,
+        stickToEdge: true,
+        stickToGroup: false,
+        stickSide: 'right',
+        reverse: false,
+        xValue: undefined,
+        yValue: undefined,
+        yStartValue: undefined,
+        yEndValue: undefined,
+        xStartValue: undefined,
+        xEndValue: undefined,
+        lengthPx: undefined,
+        color: 'rgba(20,20,20,0.9)',
+        opacity: 1,
+        lineWidth: 1,
+        lineDash: [],
+        startTick: undefined,
+        endTick: undefined,
+        items: [],
+      },
+      annotationsData: [],
+    },
+    legend: {
+      display: true,
+      position: 'bottom-left',
+      align: 'center',
+      customLegend: {
+        customLegendPlugin: null,
+        customLegendContainerID: '',
+      },
+      usePointStyle: true,
+    },
+    chartOptions: {
+      showPoints: true,
+      showLine: true,
+      enableZoom: true,
+      enablePan: false,
+      enableDragAnnotation: false,
+      closeOnOutsideClick: false,
+    },
+    interactions: {
+      onLegendClick: undefined,
+      onHover: undefined,
+      onUnhover: undefined,
+      onAnimationComplete: undefined,
+    },
+    dragData: {
+      enableDragData: false,
+      showTooltip: true,
+      roundPoints: true,
+      dragX: true,
+      dragY: true,
+      onDragStart: undefined,
+      onDrag: undefined,
+      onDragEnd: undefined,
+    },
+    depthType: {},
+  },
+};
+```
+
+## BarChart
+
+```ts
+const defaultChart = {
+  testId: '',
+  controlsPortalId: '',
+  data: {
+    labels: [],
+    datasets: [],
+  },
+  options: {
+    title: '',
+    direction: 'vertical',
+    axes: {
+      x: [{}],
+      y: [{}],
+    },
+    additionalAxesOptions: {
+      chartScaleType: 'linear',
+      reverse: false,
+      stacked: false,
+      beginAtZero: true,
+      stepSize: undefined,
+      suggestedMin: undefined,
+      suggestedMax: undefined,
+      min: undefined,
+      max: undefined,
+      stackedX: undefined,
+      stackedY: undefined,
+    },
+    chartStyling: {
+      width: undefined,
+      height: undefined,
+      maintainAspectRatio: false,
+      staticChartHeight: false,
+      performanceMode: true,
+    },
+    tooltip: {
+      tooltips: true,
+      showLabelsInTooltips: false,
+      scientificNotation: true,
+    },
+    graph: {
+      showDataLabels: false,
+      showMinorGridlines: false,
+    },
+    scales: {},
+    annotations: {
+      showAnnotations: true,
+      controlAnnotation: false,
+      annotationsData: [],
+    },
+    legend: {
+      display: true,
+      position: 'top-left',
+      align: 'center',
+      customLegend: {
+        customLegendPlugin: null,
+        customLegendContainerID: '',
+      },
+    },
+    chartOptions: {
+      enableZoom: false,
+      enablePan: false,
+    },
+    interactions: {
+      onLegendClick: undefined,
+      onHover: undefined,
+      onUnhover: undefined,
+    },
+    dragData: {
+      enableDragData: false,
+      showTooltip: true,
+      roundPoints: true,
+      dragX: true,
+      dragY: true,
+      onDragStart: undefined,
+      onDrag: undefined,
+      onDragEnd: undefined,
+    },
+  },
+};
+```
+
+## PieChart
+
+```ts
+const defaultChart = {
+  testId: null,
+  data: {
+    labels: [],
+    datasets: [],
+  },
+  options: {
+    title: '',
+    chartStyling: {
+      width: undefined,
+      height: undefined,
+      maintainAspectRatio: false,
+      staticChartHeight: false,
+      performanceMode: true,
+    },
+    tooltip: {
+      tooltips: true,
+      showLabelsInTooltips: false,
+      scientificNotation: true,
+    },
+    graph: {
+      showDataLabels: false,
+      stacked: false,
+      cutout: 0,
+    },
+    legend: {
+      display: true,
+      useDataset: false,
+      position: 'bottom',
+      align: 'center',
+    },
+    chartOptions: {
+      enableZoom: false,
+      enablePan: false,
+    },
+    interactions: {
+      onLegendClick: undefined,
+      onHover: undefined,
+      onUnhover: undefined,
+    },
+  },
+};
+```
+
+## ScatterChart
+
+```ts
+import { GradientDirection } from '@oliasoft-open-source/charts-library';
+
+const defaultChart = {
+  testId: null,
+  data: {
+    labels: [],
+    datasets: [],
+  },
+  options: {
+    title: '',
+    axes: {
+      x: [{}],
+      y: [{}],
+    },
+    additionalAxesOptions: {
+      chartScaleType: 'linear',
+      reverse: false,
+      stacked: false,
+      beginAtZero: true,
+      stepSize: undefined,
+      suggestedMin: undefined,
+      suggestedMax: undefined,
+      min: undefined,
+      max: undefined,
+    },
+    direction: 'vertical',
+    chartStyling: {
+      width: 'auto',
+      height: 'auto',
+      maintainAspectRatio: false,
+      staticChartHeight: false,
+      performanceMode: true,
+      gradient: {
+        display: false,
+        gradientColors: [
+          {
+            offset: 0,
+            color: 'rgba(144,238,144,0.8)',
+          },
+          {
+            offset: 0.6,
+            color: 'rgba(255,255,224,0.8)',
+          },
+          {
+            offset: 0.8,
+            color: 'rgba(255,255,224,0.8)',
+          },
+          {
+            offset: 0.92,
+            color: 'rgba(255,182,193,0.5)',
+          },
+          {
+            offset: 0.99,
+            color: 'rgba(255,182,193,0.8)',
+          },
+        ],
+        direction: GradientDirection.BottomLeftToTopRight,
+      },
+    },
+    tooltip: {
+      enabled: true,
+      tooltips: true,
+      showLabelsInTooltips: false,
+      backgroundColor: '#333',
+      displayColors: false,
+      scientificNotation: true,
+    },
+    graph: {
+      showMinorGridlines: false,
+      showDataLabels: false,
+    },
+    scales: {},
+    legend: {
+      display: true,
+      useDataset: false,
+      position: 'bottom-left',
+      align: 'center',
+    },
+    annotations: {
+      showAnnotations: true,
+      controlAnnotation: false,
+      annotationsData: [],
+    },
+    chartOptions: {
+      enableZoom: false,
+      enablePan: false,
+    },
+    interactions: {
+      onLegendClick: undefined,
+      onHover: undefined,
+      onUnhover: undefined,
+      onAnimationComplete: undefined,
+    },
+  },
+};
+```