diff --git a/CHANGELOG.md b/CHANGELOG.md index efbcd1b..0176af4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file. See [standa --- +## [v0.3.0](https://github.com/hatemhosny/racing-bars/compare/v0.2.0...v0.3.0) (2024-09-07) + +### Highlights for this release + +- The charts are now responsive and works much better on smaller screens. Dynamically resizing the container element will also resize the chart. +- Added the option `valueDecimals` to control decimal spaces. +- The `labelsPosition` option can now be set to `"none"` to hide the labels (e.g. for icons only). + +In addition to some bug fixes. + +The website homepage now has a GUI editor for chart options. Also added search capability in the website. + +Thank you @AhmedElbohoty for the valuable contribution. + +### Bug Fixes + +- **api:** re-prepare data when `makeCumulative` option is changed by `changeOptions` API method ([80584ca](https://github.com/hatemhosny/racing-bars/commit/80584ca3622499a4b5c6e2b7f6b070ac31bfa758)) +- **data:** fix passing data to worker ([94aadd5](https://github.com/hatemhosny/racing-bars/commit/94aadd5a0bd3ebc7ec917dd3eacb43c7f8c132b5)) +- **renderer:** avoid icons overflow outside bars ([b75dedb](https://github.com/hatemhosny/racing-bars/commit/b75dedb51cde6778431a97d85c4000a104c993e8)) + +### Features + +- **options:** add labelPositions `"none"` ([4127c7a](https://github.com/hatemhosny/racing-bars/commit/4127c7a5dd49c5add1b1bf323815d0ccef965ec3)) +- **options:** add the option `valueDecimals` ([330202a](https://github.com/hatemhosny/racing-bars/commit/330202aa7b432e2ff6b509128c0da53226b3d064)) +- **options:** validate options ([0dccf85](https://github.com/hatemhosny/racing-bars/commit/0dccf850d4af29eda795a37490606dc11f80cf9c)) +- **renderer:** resize chart on resizing root element ([daec0cd](https://github.com/hatemhosny/racing-bars/commit/daec0cdebf95d15736edc52a4101fdd14c231f47)) +- **styles:** make the chart text & controls responsive ([eb2a353](https://github.com/hatemhosny/racing-bars/commit/eb2a35341dcda6fbfe3563d7c7cfc1d5f5253430)) +- **website:** add options editor GUI ([a023795](https://github.com/hatemhosny/racing-bars/commit/a023795a1f78bbb7ae3562a736641f09d50245b6)) +- **website:** add search ([00015fc](https://github.com/hatemhosny/racing-bars/commit/00015fce403e40099c8288a4d6fd4e6fffe32d71)) + +--- + ## [v0.2.0](https://github.com/hatemhosny/racing-bars/compare/v0.1.2...v0.2.0) (2024-09-01) ### Bug Fixes diff --git a/src/lib/load-data.ts b/src/lib/load-data.ts index cb5b631..cc657f0 100644 --- a/src/lib/load-data.ts +++ b/src/lib/load-data.ts @@ -1,6 +1,27 @@ import { json, csv, tsv, xml } from './d3'; import type { Options, Data, WideData } from './index'; +/** + * Loads data. + * + * @description This function loads data from the given URL based on the detected data type. + * The data type can be explicitly specified or automatically detected from the URL extension. + * The supported data types are 'json', 'csv', 'tsv', and 'xml'. + * + * @param {string} url - The URL from which to load data. + * @param {Options['dataType']} [type='auto'] - The data type must be one of ['json', 'csv', 'tsv', 'xml']. Defaults to 'auto'. + * + * @returns {Promise | Promise} A promise that resolves to the loaded data. + * + * @throws {Error} Throws an error if the data type is unsupported or if data loading fails. + * + * @example + * loadData('data.csv', 'auto') + * .then(data => console.log(data)) + * .catch(error => console.error(error)); + * + * @see {@link https://racing-bars.hatemhosny.dev/documentation/api#loaddata} + */ export function loadData( url: string, type: Options['dataType'] = 'auto', diff --git a/src/lib/race.ts b/src/lib/race.ts index e700812..8e24ddc 100644 --- a/src/lib/race.ts +++ b/src/lib/race.ts @@ -14,6 +14,44 @@ import { type Options, validateOptions } from './options'; import { registerEvents, DOMEventSubscriber, getTickDetails, type EventType } from './events'; import type { Race, ApiCallback } from './models'; +/** + * The main function that generates the racing bar chart. + * + * @param {Data[] | WideData[] | Promise | Promise | string} data + * The data for the race visualization can be one of: + * ```text + * 1- Array of `Data` objects. + * 2- Array of `WideData` objects. + * 3- Promise that resolves to an array of `Data` objects. + * 4- Promise that resolves to an array of `WideData` objects. + * 5- String representing the file path to load the data from. + * ``` + * @see {@link https://racing-bars.hatemhosny.dev/documentation/data/} for more information. + * + * @param {string | HTMLElement} [container] Optional. The container element or selector. + * If not provided, a new `
` element will be created and appended to the document body. + * + * @param {Partial} [options={}] Optional. Configuration object for chart options. Defaults to an empty object. + * @see {@link https://racing-bars.hatemhosny.dev/api/internal/interfaces/Options/} for detailed options. + * + * @returns {Promise} The function returns a promise that resolves to an object that allows interaction with the chart. + * + * @example + * const data: Data[] | WideData[] | Promise | Promise | string = [ ...fill with data... ]; + * + * const container = document.getElementById('race-container'); + * + * const options: Partial = { + * width: 800, + * height: 400, + * }; + * + * const raceAPI = await race(data, container, options); + * + * raceAPI.play(); + * + * @see {@link https://racing-bars.hatemhosny.dev/documentation/api#race} for more details. + */ export async function race( data: Data[] | WideData[] | Promise | Promise | string, container?: string | HTMLElement, diff --git a/src/lib/utils/utils.ts b/src/lib/utils/utils.ts index 60449e4..80e5e8c 100644 --- a/src/lib/utils/utils.ts +++ b/src/lib/utils/utils.ts @@ -86,6 +86,22 @@ export function shuffle(arr: string[], seed: number) { return array; } +/** + * Generates a unique identifier with a given prefix and length. + * + * @param {string} [prefix='racingbars'] - The prefix to be added to the generated identifier. Default is 'racingbars'. + * @param {number} [n=8] - The length of the generated identifier. Default is 8. + * + * @returns The generated unique identifier. + * + * @example + * ``` + * const id = generateId('hello', 5); + * console.log(id); // Output: helloxxxxx + * ``` + * + * @see {@link https://racing-bars.hatemhosny.dev/api/functions/generateId/} for more details. + */ export function generateId(prefix = 'racingbars', n = 8) { const rnd = Array(3) .fill(null) diff --git a/src/package.lib.json b/src/package.lib.json index a3b10d3..d3b26e1 100644 --- a/src/package.lib.json +++ b/src/package.lib.json @@ -1,6 +1,6 @@ { "name": "racing-bars", - "version": "0.2.0", + "version": "0.3.0", "description": "Bar chart race made easy 📶", "author": "Hatem Hosny", "license": "MIT", diff --git a/tsconfig.json b/tsconfig.json index 003e2c9..29747b3 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -13,7 +13,6 @@ "allowUmdGlobalAccess": true, "forceConsistentCasingInFileNames": true, "importHelpers": true, - "removeComments": true, /* Strict Type-Checking Options */ // "noImplicitAny": true /* Raise error on expressions and declarations with an implied 'any' type. */,