ods-charts - npm Package Compare versions

Comparing version 0.0.1-alpha.1.0 to 0.1.0-alpha.1

dist/src/ods-charts.d.ts

@@ -1,11 +0,17 @@
-import { ODSChatsTheme } from './theme/ods-chart-theme';
+/**
+ * @packageDocumentation
+ *
+ * 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}.
+ *
+ * The {@link ODSChartsTheme} is used to build the ODS theme and the charts options.
+ *
+ */
+import { ODSChartsTheme } from './theme/ods-chart-theme';
 export * from './theme/ods-chart-theme';
-export declare class ODSCharts {
-    static odsChartsTheme: ODSChatsTheme;
-    constructor();
-}
-export declare const theme: (options?: import("./theme/ods-chart-theme").ODSChatsThemeOptions | undefined) => {
-    name: string;
-    theme: any;
-    options: import("./theme/ods-chart-theme").ODSChatsThemeOptions;
-};
+export * from './theme/css-themes/css-themes';
+export * from './theme/popover/ods-chart-popover-definitions';
+export declare const getThemeManager: typeof ODSChartsTheme.getThemeManager;

dist/src/theme/ods-chart-theme.d.ts

@@ -0,1 +1,3 @@
+import { ODSChartsCSSThemeDefinition, ODSChartsCSSThemesNames } from './css-themes/css-themes';
+import { ODSChartsPopoverConfig, ODSChartsPopoverDefinition } from './popover/ods-chart-popover-definitions';
 export declare enum ODSCHartsCategoricalColorsSet {
@@ -9,2 +11,32 @@ DEFAULT_SUPPORTING_COLORS = "supportingColors",
 }
+/**
+ * ODSCHartsCustomCategoricalColor is used to define a color.
+ *
+ * - It can be the string value of the color
+ *
+ * - Or it can be a {@link ODSCHartsCategoricalColor} to reference a color of one predefined set of Orange Design System colors.
+ *
+ * example
+ * ```
+ * {
+ *  colorPalette: ODSCharts.ODSCHartsCategoricalColorsSet.DARKER_TINTS,
+ *  colorIndex: 0,
+ * }
+ * ```
+ */
+export type ODSCHartsCustomCategoricalColor = ODSCHartsCategoricalColor | string;
+/**
+ * ODSCHartsCategoricalColor is a color extract from one set of color of Orange Design System.
+ */
+export interface ODSCHartsCategoricalColor {
+    /**
+     * The {@link ODSCHartsCategoricalColorsSet} to be used to extract a specific color.
+     * (example {@link ODSCHartsCategoricalColorsSet.DEFAULT_SUPPORTING_COLORS})
+     */
+    colorPalette: ODSCHartsCategoricalColorsSet;
+    /**
+     * Index of the color in the {@link ODSCHartsCategoricalColorsSet}
+     */
+    colorIndex: number;
+}
 export declare enum ODSCHartsSequentialColorsSet {
@@ -20,18 +52,198 @@ SEQUENTIAL_BLUE = "blue",
 }
-export declare enum ODSChartMode {
+export declare enum ODSChartsMode {
     LIGHT = "light",
     DARK = "dark"
 }
-export interface ODSChatsThemeOptions {
-    mode?: ODSChartMode;
-    categoricalColors?: ODSCHartsCategoricalColorsSet;
+export interface ODSChartsThemeOptions {
+    /**
+     * The mode of the theme can be {@link ODSChartsMode.LIGHT} or  {@link ODSChartsMode.DARK}.
+     *
+     * Default mode is {@link ODSChartsMode.LIGHT}
+     */
+    mode?: ODSChartsMode;
+    /**
+     * categoricalColors is the set of colors to be used to graph the chart.
+     *
+     * It can be
+     * - one of the predefined {@link ODSCHartsCategoricalColorsSet} defined in Orange Design System
+     *
+     * example: `ODSCharts.ODSCHartsCategoricalColorsSet.DEFAULT_SUPPORTING_COLORS`.
+     *
+     * - Or it can be an array of colors {@link ODSCHartsCustomCategoricalColor}
+     *
+     * example:
+     * ```
+     *      [
+     *        {
+     *          colorPalette:
+     *            ODSCharts.ODSCHartsCategoricalColorsSet
+     *              .DEFAULT_SUPPORTING_COLORS,
+     *          colorIndex: 2,
+     *        },
+     *        {
+     *          colorPalette:
+     *            ODSCharts.ODSCHartsCategoricalColorsSet.SEQUENTIAL_GREEN,
+     *          colorIndex: 0,
+     *        },
+     *      ]
+     * ```
+     * Default categoricalColors is {@link ODSCHartsCategoricalColorsSet.DEFAULT_SUPPORTING_COLORS}
+     */
+    categoricalColors?: ODSCHartsCategoricalColorsSet | ODSCHartsCustomCategoricalColor[];
+    /**
+     * visualMapColor is the set of colours to be used if map graphs (like Heatmap)
+     *
+     * Default visualMapColor is {@link ODSCHartsSequentialColorsSet.SEQUENTIAL_BLUE}
+     */
     visualMapColor?: ODSCHartsSequentialColorsSet;
+    /**
+     * lineStyle soecifies the style of line in lineCharts.
+     *
+     * It can be {@link ODSChartsLineStyle.BROKEN}, {@link ODSChartsLineStyle.SMOOTH} of {@link ODSChartsLineStyle.BROKEN_WITH_POINTS}.
+     *
+     * Default lineStyle is {@link ODSChartsLineStyle.SMOOTH}
+     */
     lineStyle?: ODSChartsLineStyle;
+    /**
+     * cssTheme is the css styles to be used for designing legends and popover elements.
+     *
+     * - It is possible to use one of the delivered value of {@link ODSChartsCSSThemes}
+     * - It is also possible to defined a cssTheme for any other framework with a {@link ODSChartsCSSThemeDefinition}
+     *
+     * Default cssTheme is {@link ODSChartsCSSThemes.NONE}
+     */
+    cssTheme?: ODSChartsCSSThemeDefinition;
 }
-export declare class ODSChatsTheme {
-    getTheme(options?: ODSChatsThemeOptions): {
-        name: string;
-        theme: any;
-        options: ODSChatsThemeOptions;
-    };
+/**
+ * ODSChartsTheme is the object get by `ODSCharts.getThemeManager`({@link ODSChartsThemeOptions})
+ *
+ * This manager is used to
+ * - get the ODS theme, register it, and use it
+ * ```
+ * // register this theme to echarts
+ * echarts.registerTheme(themeManager.name , themeManager.theme);
+ * // initiate the with the generated theme
+ * var myChart = echarts.init(div, themeManager.name)
+ * ```
+ * - to build the graph options
+ * ```
+ * // Set the data to be displayed.
+ * themeManager.setDataOptions(<dataOptions>);
+ * // Register the externalization of the legend.
+ * themeManager.externalizeLegends(...);
+ * // Manage window 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());
+ * ```
+ */
+export declare class ODSChartsTheme {
+    name: string;
+    theme: any;
+    options: ODSChartsThemeOptions;
+    private dataOptions;
+    private chartLegendManager;
+    private chartResizeManager;
+    private chartPopoverManager;
+    cssThemeName: ODSChartsCSSThemesNames;
+    private constructor();
+    /**
+     * Entry point of the library. It returns the generated theme manager.
+     *
+     * This manager is used to retrieve the Echarts theme and manage the chart options in accordance with the Orange Design System.
+     *
+     * The method takes the theme configuration as a parameter {@link ODSChartsThemeOptions}.
+     * @param options: default option used to genarate the theme
+     * @returns the theme manager
+     */
+    static getThemeManager(options?: ODSChartsThemeOptions): ODSChartsTheme;
+    /**
+     * setDataOptions is used to set the graph data.
+     *
+     * Example:
+     * ```
+     *     lineChartODSTheme
+     *       .setDataOptions({
+     *         xAxis: {
+     *           data: ['shirt', 'cardigan', 'chiffon', 'pants', 'heels', 'socks'],
+     *         },
+     *         series: [
+     *           {
+     *             name: 'sales',
+     *             type: 'bar',
+     *             data: [5, 20, 36, 10, 10, 20],
+     *           },
+     *         ],
+     *       })
+     * ```
+     * @param options
+     * @returns returns back the theme manager object
+     */
+    setDataOptions(options: any): ODSChartsTheme;
+    /**
+     * getThemeOptions() can be used to get the options that should be added to charts options to implement the Orange Design System.
+     *
+     * 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
+     */
+    getThemeOptions(dataOptions?: any): any;
+    /**
+     * externalizeLegends() configure the manager to externalize the legends from the graphs to put it directly in your HTML document.
+     *
+     * The generated legends
+     * - will implement the Orange Design System
+     * - will be link with the graph.
+     *
+     * externalizeLegends() needs:
+     * - echart: the initialzed eCharts object
+     * - legendHolderSelector: the css selector of the legends container
+     *
+     * optionnaly you can use this call to set dataOptions
+     * @returns returns back the theme manager object
+     */
+    externalizeLegends(echart: any, legendHolderSelector: string, dataOptions?: any): ODSChartsTheme;
+    /**
+     * externalizePopover() configure the manager to externalize the management of popover or tooltip.
+     *
+     * 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 ECharts templating to externalize tooltip/popover HTML element, implemting Orange Design system
+     *
+     * optionnaly you can use this call to set dataOptions
+     * @returns returns back the theme manager object
+     */
+    externalizePopover(popoverConfig?: ODSChartsPopoverConfig, popoverDefinition?: ODSChartsPopoverDefinition, dataOptions?: any): ODSChartsTheme;
+    /**
+     * manageChartResize() ensures that the graph resizes correctly when the window is resized
+     *
+     * manageChartResize() needs:
+     * - echart: the initialzed eCharts object
+     * - chartId: an unique id to identify the chart
+     *
+     * optionnaly you can use this call to set dataOptions
+     * @returns returns back the theme manager object
+     */
+    manageChartResize(echart: any, chartId: string, dataOptions?: any): ODSChartsTheme;
+    /**
+     * getChartOptions() build the eCharts options merging
+     * - options implementing the Orange Design System
+     * - optionally options implementing {@link externalizeLegends},
+     * - optionally options implementing {@link externalizePopover},
+     * - optionally options implementing {@link manageChartResize},
+     * - data from {@link setDataOptions}
+     *
+     * optionnaly you can use this call to set dataOptions
+     * @returns the Echarts options
+     */
+    getChartOptions(dataOptions?: any): any;
 }

package.json

 {
   "name": "ods-charts",
   "description": "ODS Charts is based on Apache ECharts and provides Orange charts components.",
-  "version": "0.0.1-alpha.1.0",
+  "version": "0.1.0-alpha.1",
   "author": "",
@@ -11,7 +11,19 @@ "contributors": [],
   ],
+  "main": "./dist/ods-charts.js",
+  "types": "./dist/ods-charts.d.js",
   "scripts": {
-    "build": "webpack"
+    "build": "webpack",
+    "serve": "serve .",
+    "serve:vue": "serve test/vue/dist/",
+    "serve:angular": "serve test/angular/dist/angular/",
+    "serve:angular-tour-of-heroes": "serve test/angular-tour-of-heroes/dist/angular-tour-of-heroes/",
+    "serve:react": "serve test/react/build/",
+    "serve:any": "serve",
+    "typedoc": "typedoc --out docs/api src/ods-charts.ts --disableSources --excludePrivate --excludeProtected  --readme docs/README.md"
   },
   "devDependencies": {
+    "echarts": "^5.4.3",
+    "serve": "^14.2.1",
     "ts-loader": "^9.4.4",
+    "typedoc": "^0.25.3",
     "typescript": "^5.1.6",
@@ -18,0 +30,0 @@ "webpack": "^5.88.2",

README.md

@@ -5,2 +5,7 @@ <h1 align="center">Orange Design System Charts</h1>
   ODS Charts provides Orange Charts components to developers.
+  <br>
+  <br>
+  <a href="https://github.com/Orange-OpenSource/ods-charts/issues/new?assignees=-&labels=bug&template=bug_report.yml">Report bug</a>
+  ·
+  <a href="https://github.com/Orange-OpenSource/ods-charts/issues/new?assignees=&labels=feature&template=feature_request.yml">Request feature</a>
 </p>
@@ -10,24 +15,33 @@
 
-- [Examples](#examples)
+- [Quick start](#quick-start)
+- [Bugs and feature requests](#bugs-and-feature-requests)
+- [Contributing](#contributing)
+- [Versioning](#versioning)
 - [Copyright and license](#copyright-and-license)
 
-## Examples
+## Quick start
 
-Build the library:
+Several quick start options are available:
 
-```bash
-npm i
-npm run build
-```
+- Clone the repo: `git clone https://github.com/Orange-OpenSource/ods-charts.git`
+- Install with [npm](https://www.npmjs.com/): `npm install ods-charts`
 
-Then launch a local server:
+## Bugs and feature requests
 
-```bash
-php -S localhost:8008
-```
+Have a bug or a feature request? Please first read the [issue guidelines](https://github.com/Orange-OpenSource/ods-charts/blob/main/CONTRIBUTING.md#using-the-issue-tracker) and search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](https://github.com/Orange-OpenSource/ods-charts/issues/new/choose).
 
-And go directly to http://localhost:8008/docs/examples/
+## Contributing
 
+Please read through our [contributing guidelines](https://github.com/Orange-OpenSource/ods-charts/blob/main/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development.
+
+Please refer to the [developer guide](https://github.com/Orange-OpenSource/ods-charts/blob/main/DEVELOP.md) for information on how to build the library.
+
+## Versioning
+
+For transparency into our release cycle and in striving to maintain backward compatibility, ODS Charts is maintained under [the Semantic Versioning guidelines](https://semver.org/). Sometimes we screw up, but we adhere to those rules whenever possible.
+
+See [the Releases section of our GitHub project](https://github.com/Orange-OpenSource/ods-charts/releases) for changelogs for each release version of ODS Charts.
+
 ## Copyright and license
 
 Code released under the MIT License.

New alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

300309

increased by181.2%

Number of package files

42

increased by27.27%

Lines of code

3821

increased by122.41%

Number of lines in readme file

46

increased by43.75%

Worsened metrics

Dev dependency count

7

increased by75%

No dependency changes