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

package/dist/index.js

@@ -19020,6 +19020,7 @@ var MouseEvents = /* @__PURE__ */ function(MouseEvents) {
 	MouseEvents["MOUSEUP"] = "mouseup";
 	return MouseEvents;
 }({});
+/** Annotation shape identifiers. */
 var AnnotationType$1 = /* @__PURE__ */ function(AnnotationType) {
 	AnnotationType["POINT"] = "point";
 	AnnotationType["BOX"] = "box";
@@ -19028,6 +19029,7 @@ var AnnotationType$1 = /* @__PURE__ */ function(AnnotationType) {
 	AnnotationType["LABEL"] = "label";
 	return AnnotationType;
 }({});
+/** Allowed axes for annotation dragging. */
 var DragAxis = /* @__PURE__ */ function(DragAxis) {
 	DragAxis["X"] = "x";
 	DragAxis["Y"] = "y";
@@ -19036,6 +19038,7 @@ var DragAxis = /* @__PURE__ */ function(DragAxis) {
 }({});
 //#endregion
 //#region src/components/common/plugins/gradient-background-plugin/enums.ts
+/** Direction of the background gradient between chart-area edges or corners. */
 var GradientDirection = /* @__PURE__ */ function(GradientDirection) {
 	GradientDirection[GradientDirection["TopToBottom"] = 0] = "TopToBottom";
 	GradientDirection[GradientDirection["BottomToTop"] = 1] = "BottomToTop";
@@ -19049,11 +19052,13 @@ var GradientDirection = /* @__PURE__ */ function(GradientDirection) {
 }({});
 //#endregion
 //#region src/components/common/enums.ts
+/** Cartesian axis identifiers. */
 var AxisType = /* @__PURE__ */ function(AxisType) {
 	AxisType["X"] = "x";
 	AxisType["Y"] = "y";
 	return AxisType;
 }({});
+/** Legend/layout positions. Individual options accept only the positions relevant to their layout. */
 var Position = /* @__PURE__ */ function(Position) {
 	Position["Bottom"] = "bottom";
 	Position["Top"] = "top";
@@ -19065,6 +19070,7 @@ var Position = /* @__PURE__ */ function(Position) {
 	Position["BottomRight"] = "bottom-right";
 	return Position;
 }({});
+/** Chart.js chart-kind identifiers used by the library. */
 var ChartType = /* @__PURE__ */ function(ChartType) {
 	ChartType["LINE"] = "line";
 	ChartType["BAR"] = "bar";
@@ -19073,6 +19079,7 @@ var ChartType = /* @__PURE__ */ function(ChartType) {
 	ChartType["SCATTER"] = "scatter";
 	return ChartType;
 }({});
+/** CSS cursors used during chart interactions. */
 var CursorStyle = /* @__PURE__ */ function(CursorStyle) {
 	CursorStyle["Pointer"] = "pointer";
 	CursorStyle["Initial"] = "initial";
@@ -19082,6 +19089,7 @@ var CursorStyle = /* @__PURE__ */ function(CursorStyle) {
 	CursorStyle["Move"] = "move";
 	return CursorStyle;
 }({});
+/** Chart.js scale-family identifiers. */
 var ScaleType = /* @__PURE__ */ function(ScaleType) {
 	ScaleType["Category"] = "category";
 	ScaleType["Linear"] = "linear";
@@ -19090,16 +19098,19 @@ var ScaleType = /* @__PURE__ */ function(ScaleType) {
 	ScaleType["TimeSeries"] = "timeseries";
 	return ScaleType;
 }({});
+/** Cartesian rendering orientation; this does not select LineChart tooltip content. */
 var ChartDirection = /* @__PURE__ */ function(ChartDirection) {
 	ChartDirection["VERTICAL"] = "vertical";
 	ChartDirection["HORIZONTAL"] = "horizontal";
 	return ChartDirection;
 }({});
+/** Legacy tooltip label keys. */
 var TooltipLabel = /* @__PURE__ */ function(TooltipLabel) {
 	TooltipLabel["Y"] = "yLabel";
 	TooltipLabel["X"] = "xLabel";
 	return TooltipLabel;
 }({});
+/** Alignment identifiers used by chart layout and legend options. */
 var AlignOptions = /* @__PURE__ */ function(AlignOptions) {
 	AlignOptions["End"] = "end";
 	AlignOptions["Start"] = "start";
@@ -19108,10 +19119,12 @@ var AlignOptions = /* @__PURE__ */ function(AlignOptions) {
 	AlignOptions["Left"] = "left";
 	return AlignOptions;
 }({});
+/** Legacy point classification identifiers. */
 var PointType = /* @__PURE__ */ function(PointType) {
 	PointType["Casing"] = "casing";
 	return PointType;
 }({});
+/** Annotation shape identifiers. */
 var AnnotationType = /* @__PURE__ */ function(AnnotationType) {
 	AnnotationType["Box"] = "box";
 	AnnotationType["Ellipse"] = "ellipse";
@@ -19120,6 +19133,7 @@ var AnnotationType = /* @__PURE__ */ function(AnnotationType) {
 	AnnotationType["Label"] = "label";
 	return AnnotationType;
 }({});
+/** Point marker shapes compatible with Chart.js. */
 var PointStyle = /* @__PURE__ */ function(PointStyle) {
 	PointStyle["Circle"] = "circle";
 	PointStyle["Square"] = "rect";
@@ -19127,10 +19141,12 @@ var PointStyle = /* @__PURE__ */ function(PointStyle) {
 	PointStyle["Triangle"] = "triangle";
 	return PointStyle;
 }({});
+/** Hover interaction modes used by the library. */
 var ChartHoverMode = /* @__PURE__ */ function(ChartHoverMode) {
 	ChartHoverMode["Nearest"] = "nearest";
 	return ChartHoverMode;
 }({});
+/** Interaction mode identifiers; availability depends on the chart controls. */
 var PanZoomMode = /* @__PURE__ */ function(PanZoomMode) {
 	PanZoomMode["X"] = "x";
 	PanZoomMode["Y"] = "y";
@@ -19138,10 +19154,12 @@ var PanZoomMode = /* @__PURE__ */ function(PanZoomMode) {
 	PanZoomMode["Z"] = "z";
 	return PanZoomMode;
 }({});
+/** Keyboard modifier identifiers used by chart interactions. */
 var Key = /* @__PURE__ */ function(Key) {
 	Key["Shift"] = "Shift";
 	return Key;
 }({});
+/** DOM event names used by chart interaction handlers. */
 var Events = /* @__PURE__ */ function(Events) {
 	Events["Mousemove"] = "mousemove";
 	Events["Mouseout"] = "mouseout";
@@ -19236,6 +19254,7 @@ var LOGARITHMIC_STEPS = [
 	1e3,
 	1e4
 ];
+/** Default categorical DS colour palette. Treat the exported array as read-only. */
 var COLORS = [
 	"#3366cc",
 	"#dc3912",
@@ -23284,16 +23303,19 @@ var calloutConnectorPlugin = {
 };
 //#endregion
 //#region src/components/line-chart/plugins/line-markers-plugin/types.ts
+/** Left/right attachment side for line markers. */
 var LineMarkerSide = /* @__PURE__ */ function(LineMarkerSide) {
 	LineMarkerSide["Left"] = "left";
 	LineMarkerSide["Right"] = "right";
 	return LineMarkerSide;
 }({});
+/** Orientation of a line marker. */
 var LineMarkerDirection = /* @__PURE__ */ function(LineMarkerDirection) {
 	LineMarkerDirection["Vertical"] = "vertical";
 	LineMarkerDirection["Horizontal"] = "horizontal";
 	return LineMarkerDirection;
 }({});
+/** Label placement relative to a line marker. */
 var LineMarkerLabelPosition = /* @__PURE__ */ function(LineMarkerLabelPosition) {
 	LineMarkerLabelPosition["Left"] = "left";
 	LineMarkerLabelPosition["Right"] = "right";
@@ -23302,6 +23324,7 @@ var LineMarkerLabelPosition = /* @__PURE__ */ function(LineMarkerLabelPosition)
 	LineMarkerLabelPosition["OnLine"] = "onLine";
 	return LineMarkerLabelPosition;
 }({});
+/** Horizontal alignment of marker label text. */
 var LineMarkerTextAlign = /* @__PURE__ */ function(LineMarkerTextAlign) {
 	LineMarkerTextAlign["Left"] = "left";
 	LineMarkerTextAlign["Right"] = "right";
@@ -24679,6 +24702,44 @@ var LineChart = (props) => {
 		})]
 	}, getChartKey(state, languageKey));
 };
+/**
+* Renders an interactive line chart with multiple axes, annotations, a legend and chart controls.
+*
+* Pass partial configuration through `chart`; omitted settings receive component defaults.
+* The example uses sample data, labels and a height of 320 pixels; these are not default values.
+*
+* @remarks
+* Defaults: bottom X axis, left Y axis, visible lines and points, bottom-left legend, and zoom enabled.
+* Pan, data labels, minor grid lines and annotations are disabled. No fixed width or height is assigned.
+* Performance mode is enabled by default, disabling animations.
+* The linked reference lists the complete normalized default configuration.
+*
+* @see https://gitlab.com/oliasoft-open-source/charts-library/-/blob/master/README.md#linechart
+*
+* @param props - Chart data and options, plus optional header, subheader and table content.
+* @returns The chart canvas and its associated UI.
+* @example
+* ```tsx
+* <LineChart chart={{
+*   data: {
+*     datasets: [{
+*       label: 'DS A',
+*       data: [{ x: 0, y: 10 }, { x: 1, y: 20 }, { x: 2, y: 15 }],
+*     }],
+*   },
+*   options: {
+*     axes: {
+*       x: [{ label: 'X', position: 'bottom' }],
+*       y: [{ label: 'Y', position: 'left' }],
+*     },
+*     chartStyling: { height: 320 },
+*     legend: { display: true, position: 'bottom-left' },
+*     graph: { lineTension: 0.01, showDataLabels: false },
+*     chartOptions: { showLine: true, showPoints: true },
+*   },
+* }} />
+* ```
+*/
 var LineChartWithLegend = (props) => {
 	const { options, data: { datasets = [] } = {} } = getDefaultProps$3(props);
 	return /* @__PURE__ */ jsx(LegendProvider, {
@@ -24690,12 +24751,17 @@ var LineChartWithLegend = (props) => {
 //#endregion
 //#region src/components/line-chart/initialize/initialize-line-chart.ts
 /**
-* Initialize the charts library with the provided configurations.
-* This function will store the configuration options in a config object.
-* @param {object} options - An object containing the configuration options for the library.
-* @param {object} options.translations - The translations to be used in the library.
-* @param {string} options.languageKey - The language key to be stored in the config object, used for translations.
-* @param {...object} options - Any additional options to be stored in the config object.
+* Updates the shared chart configuration, including the language and translated control labels.
+*
+* Call during application setup before rendering charts. Configuration is shared across chart instances;
+* this is not a per-chart configuration API. Each call sets the language key (default `en`) and updates
+* the supplied configuration entries. Non-primitive entries other than translations are shallow-copied.
+*
+* @param options - Language key, translations and other shared configuration entries.
+* @example
+* ```ts
+* initializeLineChart({ languageKey: 'en' });
+* ```
 */
 var initializeLineChart = ({ languageKey = "en", ...options }) => {
 	setConfig(INIT_KEYS.LANGUAGE_KEY, languageKey);
@@ -24925,11 +24991,6 @@ var usePieChartConfig = (chart) => {
 //#endregion
 //#region src/components/pie-chart/pie-chart.tsx
 Chart$1.register(LinearScale, CategoryScale, LogarithmicScale, ArcElement, plugin_legend, plugin_tooltip, plugin_title, index, plugin$1, plugin);
-/**
-* this is a pie chart component
-* @param {props: IPieChartProps} IPieChartProps
-* ./pie-chart.interface
-*/
 var PieChart = (props) => {
 	setDefaultTheme();
 	const chart = getDefaultProps$2(props);
@@ -24971,6 +25032,41 @@ var PieChart = (props) => {
 		})
 	});
 };
+/**
+* Renders pie segments with optional data labels, a legend and an inner cutout.
+*
+* Pass partial configuration through `chart`; omitted settings receive component defaults.
+* The example uses sample data, labels and a height of 320 pixels; these are not default values.
+*
+* @remarks
+* Defaults: a full pie (cutout 0), a bottom legend, and no fixed width or height.
+* Data labels, stacking, zoom and pan are disabled. Pie charts do not have Cartesian axes.
+* Performance mode is enabled by default, disabling animations.
+* The linked reference lists the complete normalized default configuration.
+*
+* @see https://gitlab.com/oliasoft-open-source/charts-library/-/blob/master/README.md#piechart
+*
+* @param props - Chart data and options.
+* @returns The chart canvas and its associated UI.
+* @example
+* ```tsx
+* <PieChart chart={{
+*   data: {
+*     labels: ['A', 'B', 'C'],
+*     datasets: [{
+*       label: 'DS A',
+*       data: [10, 20, 15],
+*       backgroundColor: ['#3366cc', '#dc3912', '#ff9900'],
+*     }],
+*   },
+*   options: {
+*     chartStyling: { height: 320 },
+*     legend: { display: true, position: 'bottom' },
+*     graph: { cutout: 0, showDataLabels: false },
+*   },
+* }} />
+* ```
+*/
 var PieChartWithLegend = (props) => {
 	const { options } = getDefaultProps$2(props);
 	return /* @__PURE__ */ jsx(LegendProvider, {
@@ -39328,6 +39424,45 @@ var BarChart = (props) => {
 		})]
 	}, languageKey);
 };
+/**
+* Renders vertical or horizontal bars with optional stacking, annotations and a legend.
+*
+* Pass partial configuration through `chart`; omitted settings receive component defaults.
+* The example uses sample data, labels and a height of 320 pixels; these are not default values.
+*
+* @remarks
+* Defaults: vertical bars, a top-left legend, zero included in automatic scale bounds, and annotations enabled.
+* Zoom, pan, stacking and data labels are disabled. No fixed width or height is assigned.
+* Performance mode is enabled by default, disabling animations.
+* The linked reference lists the complete normalized default configuration.
+*
+* @see https://gitlab.com/oliasoft-open-source/charts-library/-/blob/master/README.md#barchart
+*
+* @param props - Chart data and options.
+* @returns The chart canvas and its associated UI.
+* @example
+* ```tsx
+* <BarChart chart={{
+*   data: {
+*     labels: ['A', 'B', 'C'],
+*     datasets: [{
+*       label: 'DS A',
+*       data: [{ x: 'A', y: 10 }, { x: 'B', y: 20 }, { x: 'C', y: 15 }],
+*     }],
+*   },
+*   options: {
+*     direction: 'vertical',
+*     axes: {
+*       x: [{ label: 'Category', position: 'bottom' }],
+*       y: [{ label: 'Value', position: 'left' }],
+*     },
+*     chartStyling: { height: 320 },
+*     legend: { display: true, position: 'top-left' },
+*     graph: { showDataLabels: false },
+*   },
+* }} />
+* ```
+*/
 var BarChartWithLegend = (props) => {
 	const { options } = getDefaultProps$1(props);
 	return /* @__PURE__ */ jsx(LegendProvider, {
@@ -39726,6 +39861,43 @@ var ScatterChart = (props) => {
 		})
 	});
 };
+/**
+* Renders Cartesian points with a legend, optional annotations and a background gradient.
+*
+* Pass partial configuration through `chart`; omitted settings receive component defaults.
+* The example uses sample data, labels and a height of 320 pixels; these are not default values.
+*
+* @remarks
+* Defaults: automatic width and height, a bottom-left legend, zero included in automatic scale bounds,
+* and annotations enabled. Zoom, pan, data labels, minor grid lines and the background gradient are disabled.
+* Performance mode is enabled by default, disabling animations.
+* The linked reference lists the complete normalized default configuration.
+*
+* @see https://gitlab.com/oliasoft-open-source/charts-library/-/blob/master/README.md#scatterchart
+*
+* @param props - Chart data and options.
+* @returns The chart canvas and its associated UI.
+* @example
+* ```tsx
+* <ScatterChart chart={{
+*   data: {
+*     datasets: [{
+*       label: 'DS A',
+*       data: [{ x: 1, y: 10 }, { x: 2, y: 20 }, { x: 3, y: 15 }],
+*     }],
+*   },
+*   options: {
+*     axes: {
+*       x: [{ label: 'X', position: 'bottom' }],
+*       y: [{ label: 'Y', position: 'left' }],
+*     },
+*     chartStyling: { height: 320 },
+*     legend: { display: true, position: 'bottom-left' },
+*     graph: { showDataLabels: false, showMinorGridlines: false },
+*   },
+* }} />
+* ```
+*/
 var ScatterChartWithLegend = (props) => {
 	const { options } = getDefaultProps(props);
 	return /* @__PURE__ */ jsx(LegendProvider, {
@@ -39737,6 +39909,17 @@ var ScatterChartWithLegend = (props) => {
 //#region src/components/common/helpers/get-grouped-color-scheme/get-grouped-color-scheme.ts
 extend([lchPlugin]);
 var MIN_LIGHTNESS = 15;
+/**
+* Builds a darkest-first palette by varying LCH lightness while retaining the starting hue and chroma.
+*
+* @param length - Requested number of colours. Use a non-negative integer; zero returns an empty array.
+* @param startingColor - Colour understood by colord. A length of one returns this string unchanged.
+* @returns CSS LCH colour strings, except for the unchanged single-colour case.
+* @example
+* ```ts
+* const colors = getGroupedColorScheme(3, '#3366cc');
+* ```
+*/
 var getGroupedColorScheme = (length, startingColor) => {
 	if (length === 1) return [startingColor];
 	const { h: hue, c: chroma } = colord(startingColor).toLch();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oliasoft-open-source/charts-library",
-  "version": "8.0.0-beta-1",
+  "version": "8.0.0",
   "description": "React Chart Library (based on Chart.js and react-chart-js-2)",
   "homepage": "https://gitlab.com/oliasoft-open-source/charts-library",
   "bugs": {