diff --git a/.gitignore b/.gitignore index 58b805f..09e6370 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,8 @@ .DS_Store -node_modules/ \ No newline at end of file +node_modules/ + +# NPM tarballs +*.tgz + +# For people using vscode +.vscode \ No newline at end of file diff --git a/README.md b/README.md index 292ee54..5685304 100644 --- a/README.md +++ b/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,8 +58,8 @@ 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, @@ -67,10 +67,10 @@ Coloris({ // 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). diff --git a/dist/coloris.d.ts b/dist/coloris.d.ts new file mode 100644 index 0000000..f407e94 --- /dev/null +++ b/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; \ No newline at end of file diff --git a/gulpfile.babel.js b/gulpfile.babel.js index 30cc338..2bbb971 100644 --- a/gulpfile.babel.js +++ b/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); diff --git a/package-lock.json b/package-lock.json index 070682f..6649fe3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5,7 +5,6 @@ "requires": true, "packages": { "": { - "name": "Coloris", "version": "0.6.0", "license": "MIT", "devDependencies": { @@ -2177,6 +2176,7 @@ "anymatch": "^2.0.0", "async-each": "^1.0.1", "braces": "^2.3.2", + "fsevents": "^1.2.7", "glob-parent": "^3.1.0", "inherits": "^2.0.3", "is-binary-path": "^1.0.0", diff --git a/package.json b/package.json index e12a802..91d70a5 100644 --- a/package.json +++ b/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", diff --git a/src/coloris.d.ts b/src/coloris.d.ts new file mode 100644 index 0000000..c4645bb --- /dev/null +++ b/src/coloris.d.ts @@ -0,0 +1,204 @@ +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"; + + export interface Accessibility { + /** + * @default "Open color picker" + */ + open: string; + + /** + * @default "Close color picker" + */ + close: string; + + /** + * @default "Saturation: {s}. Brightness: {v}." + */ + marker: string; + + /** + * @default "Hue slider" + */ + hueSlider: string; + + /** + * @default "Opacity slider" + */ + alphaSlider: string; + + /** + * @default "Color swatch" + */ + input: string; + + /** + * @default "Color swatch" + */ + swatch: string; + + /** + * @default "Saturation and brightness selector. Use up, down, left and right arrow keys to select." + */ + instruction: string; + } + + /** + * 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[]; + + /** + * Accessibility messages for various aria attribute etc. + */ + a11y?: Accessibility; + } + + /** + * 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; \ No newline at end of file