Add TypeScript type declarations file

.gitignore

@@ -1,2 +1,8 @@
 .DS_Store
-node_modules/
+node_modules/
+
+# NPM tarballs
+*.tgz
+
+# For people using vscode
+.vscode

README.md

@@ -3,7 +3,7 @@
 
 ![Coloris in light, dark and polaroid themes](https://raw.githubusercontent.com/mdbassit/Coloris/gh-pages/images/coloris-light-dark-polaroid.jpg)
 
-A lightweight and elegant JavaScript color picker written in vanilla ES6.  
+A lightweight and elegant JavaScript color picker written in vanilla ES6.
 Convert any text input field into a color field.
 
 [**View demo**](https://coloris.js.org/examples.html)
@@ -48,7 +48,7 @@ That's it. All done!
 
 ```js
 Coloris({
-  // The default behavious is to append the color picker's dialog to the end of the document's
+  // The default behavior is to append the color picker's dialog to the end of the document's
   // body. but it is possible to append it to a custom parent instead. This is especially useful
   // if the color fields are in a scrollable container and you want color picker' dialog to stay
   // anchored to them. You will need to set the position of the container to relative or absolute.
@@ -58,19 +58,19 @@ Coloris({
   el: '.color-field',
 
   // The bound input fields are wrapped in a div that adds a thumbnail showing the current color
-  // and a button to open the color picker (for accessibility only). If you wish to keep your 
-  // fields unaltered, set this to false, in which case you will lose the color thumbnail and 
+  // and a button to open the color picker (for accessibility only). If you wish to keep your
+  // fields unaltered, set this to false, in which case you will lose the color thumbnail and
   // the accessible button (not recommended).
   wrap: true,
 
   // Available themes: light, dark, polaroid, polaroid-dark.
   // More themes might be added in the future.
   theme: 'light',
 
-  // The margin between the input fields and the color picker's dialog.
+  // The margin in pixels between the input fields and the color picker's dialog.
   margin: 2,
 
-  // Set the prefered color string format:
+  // Set the preferred color string format:
   //  * hex: outputs #RRGGBB or #RRGGBBAA (default).
   //  * rgb: outputs rgb(R, G, B) or rgba(R, G, B, A).
   //  * hsl: outputs hsl(H, S, L) or hsla(H, S, L, A).
@@ -107,7 +107,7 @@ Coloris({
 
 ### Events
 
-An "input" event is triggered on the bound input field whenever a new color is selected.  
+An "input" event is triggered on the bound input field whenever a new color is selected.
 A "change" event is triggered when the color picker is closed and if the color has changed since it was opened.
 
 ### Closing the color picker
@@ -146,7 +146,21 @@ Alternatively, you can start a gulp watch task to automatically build when the s
 npm run start
 ```
 
+# TypeScript
+
+This package includes TypeScript declarations. Since this project is a global
+library, you need to either add a triple slash reference or add an entry to the
+types array in the `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["Coloris"]
+  }
+}
+```
+
 ## License
 
-Copyright (c) 2021 Momo Bassit.  
+Copyright (c) 2021 Momo Bassit.
 **Coloris** is licensed under the [MIT license](https://github.com/mdbassit/Coloris/blob/main/LICENSE).

dist/coloris.d.ts

@@ -0,0 +1,157 @@
+declare namespace Coloris {
+  /**
+   * All color themes supported by the color picker. More themes might be added
+   * in the future.
+   */
+  export type ColorTheme =
+    | "light"
+    | "dark"
+    | "polaroid"
+    | "polaroid-dark";
+
+  /**
+   * Color format used by the color picker. The format affects which value is
+   * shown in the input field.
+   * - `hex` outputs `#RRGGBB` or `#RRGGBBAA`.
+   * - `rgb` outputs `rgb(R, G, B)` or `rgba(R, G, B, A)`.
+   * - `hsl` outputs `hsl(H, S, L)` or `hsla(H, S, L, A)`.
+   * - `mixed` outputs `#RRGGBB` when alpha is 1; otherwise `rgba(R, G, B, A)`.
+   */
+  export type ColorFormat =
+    | "hex"
+    | "rgb"
+    | "hsl"
+    | "mixed";
+
+  /**
+   * Configuration for the optional clear button on the color picker.
+   */
+  export interface ClearButtonOptions {
+    /**
+     * Whether the clear button is displayed when the color picker is opened.
+     */
+    show: boolean;
+
+    /**
+     * The label text shown on the clear button.
+     */
+    label: string;
+  }
+
+  export interface ColorisOptions {
+    /**
+     * A custom CSS selector to bind the color picker to. This must point to
+     * one or more {@link HTMLInputElement}s.
+     */
+    el: string;
+
+    /**
+     * CSS selector for the parent.
+     *
+     * When `null`, the default behaviour is to append the color picker's dialog
+     * to the end of the document's body. But it is possible to append it to a
+     * custom parent instead. This is especially useful if the color fields are
+     * in a scrollable container and you want color picker' dialog to stay
+     * anchored to them. You will need to set the position of the container to
+     * relative or absolute.
+     *
+     * @default null
+     */
+    parent?: null | string;
+
+    /**
+     * The bound input fields are wrapped in a div that adds a thumbnail
+     * showing the current color and a button to open the color picker (for
+     * accessibility only).
+     *
+     * If you wish to keep your fields unaltered, set this to `false`, in which
+     * case you will lose the color thumbnail and the accessible button (not
+     * recommended).
+     *
+     * @default true
+     */
+    wrap?: boolean;
+
+    /**
+     * The color theme to use for the color picker. More themes might be added
+     * in the future.
+     *
+     * @default "light"
+     */
+    theme?: ColorTheme;
+
+    /**
+     * The margin in pixels between the input fields and the color picker's
+     * dialog.
+     *
+     * @default 2
+     */
+    margin?: number;
+
+    /**
+     * Sets the preferred color string format. The format affects which value is
+     * shown in the input field. See {@link ColorFormat} for more details.
+     *
+     * @default "hex"
+     */
+    format?: ColorFormat;
+
+    /**
+     * Enable or disable alpha support.
+     *
+     * When disabled, it will strip the alpha value from the existing color
+     * value in all formats.
+     *
+     * @default true
+     */
+    alpha?: boolean;
+
+    /**
+     * Shows a clear button and set its label. By default, no clear button is
+     * shown.
+     *
+     * @default undefined
+     */
+    clearButton?: ClearButtonOptions;
+
+    /**
+     * An array of the desired color swatches to display. If omitted or the
+     * array is empty, the color swatches will be disabled.
+     *
+     * @default []
+     */
+    swatches?: string[];
+  }
+
+  /**
+   * The main entry point or namespace for Coloris. This object is callable and
+   * can be used to initialize Coloris. It also contains several utility
+   * methods.
+   */
+  export interface ColorisEntryPoint {
+    /**
+     * Converts an input field to a color picker input.
+     */
+    (opts: ColorisOptions): void;
+
+    /**
+     * The color picker dialog can be closed by clicking anywhere on the
+     * page or by pressing the ESC on the keyboard. The later will also
+     * revert the color to its original value.
+     *
+     * If you would like to close the dialog programmatically, you can do so
+     * by calling this method.
+     *
+     * @param {boolean} revert When `true`, resets the color to its original
+     * value. Defaults to `false`.
+     */
+    close: (revert?: boolean) => void;
+  }
+}
+
+/**
+ * The main entry point or namespace for Coloris. This object is callable and
+ * can be used to initialize Coloris. It also contains several utility
+ * methods.
+ */
+declare const Coloris: Coloris.ColorisEntryPoint;

gulpfile.babel.js

@@ -10,7 +10,8 @@ const path = {
   src: './src/*',
   dist: './dist',
   js: './src/*.js',
-  css: './src/*.css'
+  css: './src/*.css',
+  dts: './src/*.d.ts'
 };
 
 function minifyJS() {
@@ -44,12 +45,16 @@ function copySourceCSS() {
     return src(path.css).pipe(dest(path.dist));
 }
 
+function copySourceDts() {
+  return src(path.dts).pipe(dest(path.dist));
+}
+
 function watchFiles() {
   watch(path.js, minifyJS);
-  watch(path.css, parallel(minifyCSS, copySourceCSS));
+  watch(path.css, parallel(minifyCSS, copySourceCSS, copySourceDts));
 }
 
-export const build = parallel(minifyJS, minifyCSS, copySourceCSS);
+export const build = parallel(minifyJS, minifyCSS, copySourceCSS, copySourceDts);
 
 export default series(build, watchFiles);
 

package.json

@@ -4,7 +4,8 @@
   "description": "A lightweight and elegant color picker.",
   "author": "Momo Bassit",
   "license": "MIT",
-  "main": "coloris.js",
+  "main": "dist/coloris.js",
+  "types": "dist/coloris.d.ts",
   "devDependencies": {
     "@babel/core": "^7.15.5",
     "@babel/preset-env": "^7.15.6",