jsdoc: Add jsdoc race APIs

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

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<Data[]> | Promise<WideData[]>} 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',

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<Data[]> | Promise<WideData[]> | 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 `<div>` element will be created and appended to the document body.
+ *
+ * @param {Partial<Options>} [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<Race>} The function returns a promise that resolves to an object that allows interaction with the chart.
+ *
+ * @example
+ * const data: Data[] | WideData[] | Promise<Data[]> | Promise<WideData[]> | string = [ ...fill with data... ];
+ *
+ * const container = document.getElementById('race-container');
+ *
+ * const options: Partial<Options>  = {
+ *   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<Data[]> | Promise<WideData[]> | string,
   container?: string | HTMLElement,

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)

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",

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. */,