From 8c7d2017a62c5f9a79de7ea633a11ea13cb20cf0 Mon Sep 17 00:00:00 2001 From: Jacques Lebourgeois Date: Fri, 15 Nov 2024 09:29:56 +0100 Subject: [PATCH] doc(lib) Make documentation easier to read, to facilitate use of the various functions and their configuration --- .gitignore | 1 + README.md | 2 + docs/README.md | 24 +++++ package.json | 2 +- src/ods-charts.ts | 8 +- .../legends/ods-chart-legends-definitions.ts | 2 +- src/theme/ods-chart-theme.ts | 92 +++++++++++-------- .../popover/ods-chart-popover-definitions.ts | 15 +-- 8 files changed, 95 insertions(+), 51 deletions(-) diff --git a/.gitignore b/.gitignore index ab585901..5b9abbde 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ /dist ods-charts*.tgz /docs/api +/test_local \ No newline at end of file diff --git a/README.md b/README.md index 2c4e806b..9ccdd514 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,8 @@ myChart.setOption(themeManager.getChartOptions(dataOptions)); The `themeManager` returned by `getThemeManager()` can be used to add other features supported by the ODS Charts library. +Read the [API documentaion](https://ods-charts.netlify.app/api/) for details on this legends, popover, tooltip... features. + Read the [documentation](https://ods-charts.netlify.app/) for information on the library content and examples. ## Status diff --git a/docs/README.md b/docs/README.md index aa39b0ce..4f19556b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,30 @@ Once the library integrated, via use `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) to get the {@link ODSChartsTheme}. +The ODS Charts library is configured + +- by settings options on {@link ODSChartsThemeOptions} +- by calling features on {@link ODSChartsTheme} + +{@link ODSChartsTheme.getThemeManager} + +### Theme options + +The theme is configured with {@link ODSChartsThemeOptions}: + +- {@link ODSChartsThemeOptions.categoricalColors}: colors to be used to graph the chart. +- {@link ODSChartsThemeOptions.cssTheme}: optionaly indicates a external theme to be used like boosted. +- {@link ODSChartsThemeOptions.lineStyle}: style of line in lineCharts. +- {@link ODSChartsThemeOptions.mode}: fixes the light or dark mode. + +### Graph features + +And additional features can be added calling methods on {@link ODSChartsTheme}: + +- {@link ODSChartsTheme.externalizeLegends}: to add Orange Design System theme to legends. +- {@link ODSChartsTheme.externalizePopover}: to add Orange Design System theme to popover or tooltip. +- {@link ODSChartsTheme.manageChartResize}`: to dynamically adapt graph size the its container. + The {@link ODSChartsTheme} is used to build the ODS theme and the charts options. ## Examples diff --git a/package.json b/package.json index 4c7a0cbd..91a7c718 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,7 @@ "serve:any": "serve", "serve:react": "serve test/react/build/", "serve:vue": "serve test/vue/dist/", - "typedoc": "typedoc --out docs/api src/ods-charts.ts --disableSources --excludePrivate --excludeProtected --readme docs/README.md && node build/add_head.mjs", + "typedoc": "typedoc --out docs/api src/ods-charts.ts --skipErrorChecking --disableSources --excludePrivate --excludeProtected --readme docs/README.md && node build/add_head.mjs", "watch": "webpack --watch --mode development" }, "devDependencies": { diff --git a/src/ods-charts.ts b/src/ods-charts.ts index 3628e13f..28d3b5be 100644 --- a/src/ods-charts.ts +++ b/src/ods-charts.ts @@ -9,13 +9,9 @@ /** * @packageDocumentation * - * Once the library integrated, via - * - script <script src="...ods-charts.js"> - * - or an import * as ODSCharts from 'ods-charts' + * This page is an index of the module's classes, interfaces and enumeration. * - * use `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) to get the {@link ODSChartsTheme}. - * - * The {@link ODSChartsTheme} is used to build the ODS theme and the charts options. + * Their use is introduced on the [home page](./#md:documentation). * */ import { ODSChartsTheme } from './theme/ods-chart-theme'; diff --git a/src/theme/legends/ods-chart-legends-definitions.ts b/src/theme/legends/ods-chart-legends-definitions.ts index d748c9a5..31abf578 100644 --- a/src/theme/legends/ods-chart-legends-definitions.ts +++ b/src/theme/legends/ods-chart-legends-definitions.ts @@ -7,7 +7,7 @@ // /** - * Definition of a container used to display legends. + * Definition of a container used to display legends, refer to {@link ODSChartsTheme.externalizeLegends}. * * Example of use: * ``` diff --git a/src/theme/ods-chart-theme.ts b/src/theme/ods-chart-theme.ts index 2ec8e2cb..ec03f586 100644 --- a/src/theme/ods-chart-theme.ts +++ b/src/theme/ods-chart-theme.ts @@ -141,6 +141,9 @@ export enum ODSChartsMode { DARK = 'dark', } +/** + * `ODSChartsThemeOptions` is used to set options of the theme [ODSCharts.getThemeManager( ODSChartsThemeOptions)](../#md:documentation). + */ export interface ODSChartsThemeOptions { /** * The mode of the theme can be {@link ODSChartsMode.LIGHT} or {@link ODSChartsMode.DARK}. @@ -276,7 +279,7 @@ const THEMES: { }; /** - * ODSChartsTheme is the object get by `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) + * ODSChartsTheme is the object get by `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}), refer to {@link ODSChartsTheme.getThemeManager} * * This manager is used to * - get the ODS theme, register it, and use it @@ -292,13 +295,16 @@ const THEMES: { * themeManager.setDataOptions(); * // Register the externalization of the legend. * themeManager.externalizeLegends(...); - * // Manage window size changed + * // Manage chart container size changed * themeManager.manageChartResize(...); * // Register the externalization of the tooltip/popup * themeManager.externalizePopover(...); * // Display the chart using the configured theme and data. * myChart.setOption(themeManager.getChartOptions()); * ``` + * + * See {@link ODSChartsTheme.getThemeManager} for details. + * */ export class ODSChartsTheme { private dataOptions: any; @@ -319,13 +325,27 @@ export class ODSChartsTheme { } /** - * Entry point of the library. It returns the generated theme manager. + * Entry point of the library. * - * This manager is used to retrieve the Apache ECharts theme and manage the chart options in accordance with the Orange Design System. + * Once the library integrated, via + * - script <script src="...ods-charts.js"> + * - or an import \* as ODSCharts from 'ods-charts' + * + * use `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions}) to get the {@link ODSChartsTheme}. + * + * It returns the generated theme manager. * - * The method takes the theme configuration as a parameter {@link ODSChartsThemeOptions}. - * @param options default option used to generate the theme - * @returns the theme manager + * @param options options used to generate the theme. + * - {@link ODSChartsThemeOptions.categoricalColors}: colors to be used to graph the chart. + * - {@link ODSChartsThemeOptions.cssTheme}: optionaly indicates a external theme to be used like boosted. + * - {@link ODSChartsThemeOptions.lineStyle}: style of line in lineCharts. + * - {@link ODSChartsThemeOptions.mode}: fixes the light or dark mode. + * @returns the theme manager. + * This manager is used to retrieve the Apache ECharts theme and manage the chart options in accordance with the Orange Design System. + * It is used to add features: + * - {@link ODSChartsTheme.externalizeLegends}: to add Orange Design System theme to legends. + * - {@link ODSChartsTheme.externalizePopover}: to add Orange Design System theme to popover or tooltip. + * - {@link ODSChartsTheme.manageChartResize}`: to dynamically adapt graph size the its container. */ public static getThemeManager(options?: ODSChartsThemeOptions): ODSChartsTheme { if (!options) { @@ -378,7 +398,7 @@ export class ODSChartsTheme { } /** - * setDataOptions is used to set the graph data. + * Set the original [Apache Echarts data options](https://echarts.apache.org/en/option.html) of your graph. * * Example: * ``` @@ -396,8 +416,8 @@ export class ODSChartsTheme { * ], * }) * ``` - * @param options - * @returns returns back the theme manager object + * @param options the [Apache Echarts data options](https://echarts.apache.org/en/option.html) of your graph. + * @returns the theme manager object */ public setDataOptions(options: any): ODSChartsTheme { this.dataOptions = options; @@ -427,7 +447,9 @@ export class ODSChartsTheme { * getThemeOptions() does not need to be called if you use getChartOptions() as getChartOptions() internally already calls it. * * getThemeOptions() needs graph data, already set or given in the dataOptions parameter - * @returns returns back the theme manager object + * + * @param dataOptions optionally you can use this call to set dataOptions, if not already set. + * @returns modifications to be made to the [Apache Echarts data options](https://echarts.apache.org/en/option.html) to implement the Orange Design System. */ public getThemeOptions(dataOptions?: any): any { if (dataOptions) { @@ -529,12 +551,14 @@ export class ODSChartsTheme { * - will implement the Orange Design System * - will be link with the graph. * - * externalizeLegends() needs: - * - echart: the initialized eCharts object - * - legendHolderSelector: the CSS selector of the legends container if it a string. But it can also be a {@link ODSChartsLegendHolderDefinition} or an array of {@link ODSChartsLegendHolderDefinition} - * - * optionally you can use this call to set dataOptions - * @returns returns back the theme manager object + * @param echart the initialized eCharts object + * @param legendHolderSelector + * legendHolderSelectorcan be + * - a string, and then is interprated as the CSS selector of the legends container + * - a {@link ODSChartsLegendHolderDefinition} if you want to sepcify the orientation of the legends holder or specify the series to be displayed in the legends holder + * - an array of {@link ODSChartsLegendHolderDefinition} if you want to group legends in several legends holders + * @param dataOptions optionally you can use this call to set dataOptions, if not already set. + * @returns the theme manager object itself to be able to chain calls. */ public externalizeLegends( echart: any, @@ -553,16 +577,12 @@ export class ODSChartsTheme { * * The generated tooltips or popover will implement the Orange Design System. * - * externalizePopover() needs: - * - popoverConfig: the configuration of the externalizePopover feature {@link ODSChartsPopoverConfig} - * - popoverDefinition: a renderer {@link ODSChartsPopoverDefinition} of the popover/tooltip - * - * {@link ODSChartsPopoverManagers} gives preconfigured renderer - * - * default value is {@link ODSChartsPopoverManagers.NONE}: uses default Apache ECharts template to externalize tooltip/popover HTML element, implementing Orange Design system - * - * optionally you can use this call to set dataOptions - * @returns returns back the theme manager object + * @param popoverConfig the configuration of the externalizePopover feature {@link ODSChartsPopoverConfig} + * @param popoverDefinition renderer {@link ODSChartsPopoverDefinition} of the popover/tooltip. **{@link ODSChartsPopoverManagers}** is used to + * specify preconfigured renderer for Apache ECharts, Boosted 5 or Boosted 4 renderer. + * default value is {@link ODSChartsPopoverManagers.NONE}, that means it uses default Apache ECharts template to externalize tooltip/popover HTML element, implementing Orange Design system + * @param dataOptions optionally you can use this call to set dataOptions, if not already set. + * @returns the theme manager object itself to be able to chain calls. */ public externalizePopover(popoverConfig: ODSChartsPopoverConfig = {}, popoverDefinition?: ODSChartsPopoverDefinition, dataOptions?: any): ODSChartsTheme { if (dataOptions) { @@ -576,14 +596,12 @@ export class ODSChartsTheme { } /** - * manageChartResize() ensures that the graph resizes correctly when the window is resized - * - * manageChartResize() needs: - * - echart: the initialized eCharts object - * - chartId: an unique id to identify the chart + * manageChartResize() ensures that the graph resizes correctly when its container is resized * - * optionally you can use this call to set dataOptions - * @returns returns back the theme manager object + * @param echart the initialized eCharts object. + * @param chartId an unique id that identify the chart container in the DOM. + * @param dataOptions optionally you can use this call to set dataOptions, if not already set. + * @returns the theme manager object itself to be able to chain calls. */ public manageChartResize(echart: any, chartId: string, dataOptions?: any): ODSChartsTheme { if (dataOptions) { @@ -595,14 +613,14 @@ export class ODSChartsTheme { /** * getChartOptions() build the eCharts options merging - * - options implementing the Orange Design System + * - options implementing the Orange Design System {@link ODSChartsThemeOptions} * - optionally options implementing {@link externalizeLegends}, * - optionally options implementing {@link externalizePopover}, * - optionally options implementing {@link manageChartResize}, * - data from {@link setDataOptions} * - * optionally you can use this call to set dataOptions - * @returns the Apache ECharts options + * @param dataOptions optionally you can use this call to set dataOptions, if not already set. + * @returns the Apache ECharts options to use in [Apache Echarts setOption()](https://echarts.apache.org/en/option.html) call. */ public getChartOptions(dataOptions?: any): any { if (dataOptions) { diff --git a/src/theme/popover/ods-chart-popover-definitions.ts b/src/theme/popover/ods-chart-popover-definitions.ts index c29d412a..21e052ee 100644 --- a/src/theme/popover/ods-chart-popover-definitions.ts +++ b/src/theme/popover/ods-chart-popover-definitions.ts @@ -40,10 +40,11 @@ export class ODSChartsPopoverItem { /** * {@link ODSChartsPopoverDefinition} defines the interface of the manager of externalized - * popover or tooltip. + * popover or tooltip {@link ODSChartsTheme.externalizePopover}. * + * {@link ODSChartsPopoverDefinition} is not used directly. Instead, we use the variable **{@link ODSChartsPopoverDefinition}. * {@link ODSChartsPopoverManagers} gives 3 default {@link ODSChartsPopoverDefinition} - * managers. + * managers for Apache ECharts, Boosted 5 and Boosted 4. * * You probably need to use one of those. * @@ -138,7 +139,7 @@ export enum ODSChartsPopoverTooltipTrigger { } /** - * Configuration of the externalizePopover feature. + * Configuration of the externalizePopover feature {@link ODSChartsTheme.externalizePopover}. * */ export class ODSChartsPopoverConfig { @@ -303,10 +304,12 @@ class BOOSTED4_Definition extends ODSChartsPopoverDefinitionWithRenderer { } /** + * `ODSChartsPopoverManagers` is used to specify popoverDefinition parameter (popup/tooltip renderer) of {@link ODSChartsTheme.externalizePopover}. + * * Available popover/tooltip renderer: - * - ODSChartsPopoverManagers.NONE: to use default ECharts template to externalize tooltip/popover HTML element, implementing Orange Design System - * - ODSChartsPopoverManagers.BOOSTED5: to use Boosted 5 tooltip/popover - * - ODSChartsPopoverManagers.BOOSTED4: to use Boosted 4 tooltip/popover + * - `ODSChartsPopoverManagers.NONE`: to use default ECharts template to externalize tooltip/popover HTML element, implementing Orange Design System + * - `ODSChartsPopoverManagers.BOOSTED5`: to use Boosted 5 tooltip/popover + * - `ODSChartsPopoverManagers.BOOSTED4`: to use Boosted 4 tooltip/popover */ export const ODSChartsPopoverManagers: { [name in ODSChartsCSSThemesNames]?: ODSChartsPopoverDefinition;