-
+
+
```
-To customize this transition, you can use `.box.active` in combination with `.box.active .inner`.
+To customize this transition, you can use `.color-input__box--active` in combination with `.color-input__box-inner--active`.
For example:
```css
-.color-input.user .box.active {
+div.color-input__box--active {
/* "outline" color */
background: #0f0f0f;
}
-.color-input.user .box.active .inner {
+div.color-input__box-inner--active {
/* different transition effect */
transform: scale(.9) rotate(90deg);
}
```
+## Popup offset
+
+The popup gets a default offset from the box which is equal to `10px`. If you would like to use a different offset, you should set it with a `--popup-offset` css property defined on the popup.
+
+Example:
+```css
+div.color-input__popup {
+ --popup-offset: 20px;
+}
+```
+
## Example CSS
```css
-.color-input.user .box {
+div.color-input__box {
/* make clickable box a 100x100 circle */
width: 100px;
height: 100px;
border-radius: 50px;
}
-.color-input.user .picker-popup {
+div.color-input__popup {
/* dark mode for popup window */
background: #000;
color: #fbfbfb;
/* and make it wide */
width: 400px;
}
-.color-input.user .slider {
+div.color-input__slider {
/* thin out the sliders and make them wider */
height: 2px;
width: 92%;
}
-.color-input.user .saturation-area {
+div.color-input__saturation-area {
/* bigger picking area */
height: 150px;
}
-.color-input.user .slider-pointer {
+div.color-input__slider-pointer {
/* make slider pointers square-ish and 10x10 */
border-radius: 4px;
width: 10px;
height: 10px;
}
-.color-input.user .saturation-pointer {
+div.color-input__saturation-pointer {
/* increase saturation pointer size */
width: 40px;
height: 40px;
@@ -446,42 +481,68 @@ For example:
## Styling guidelines
-### Root element is _not_ the `.box`
+### Use stylesheets, no need to set inline styles
-Here's the base structure of the component:
-```xml
-
-```
-Root element wraps arond the clickable box, but if you want to change box styles, you should select it like this: `.color-input.user .box`.
+Inline styles will only let you style the root element, when typically you will want to style more than that.
-Generally, you should attempt to style the root element only if you want to customize the flow: properties like `margin`, `position`, `display`.
+### Use specificity or custom class to override default styles
-_Changing size of the root element independently from the box will mess with how the popup is positioned._
+Read more about the both approaches [here](#customizing-factory-styles).
-### Use stylesheets, no need to pass inline styles
+### Don't expect the popup to be nested within the root
+
+As the popup is teleported to the body, the following nested css selectors won't work:
+```xml
+
+```
+```css
+/* ❌ example of selector that won't work */
+.my-custom-class .color-input__popup {}
+```
+Instead, think of box and popup as two _separate roots_ that both get your custom class. And then both of those have some children that you can access with nested selectors:
+```css
+.my-custom-class.color-input__popup {}
+.my-custom-class.color-input__box {}
+.my-custom-class .color-input__slider {}
+.my-custom-class .color-input__box-inner {}
+```
+And likewise...
-Inline styles will only let you style the root element, which is typically not what you want to style very often.
+### Don't expect your custom class to point only to the box
-### Use `.color-input.user` to override default styles
+As described above, _both the box and the popup_ will get your custom class, so don't try to use your custom class without the specifying selector, that will apply the styles to both the box and the popup:
+```css
+/* ❌ example of what not to do */
+.my-custom-class {
+ width: 50px;
+ height: 50px;
+}
+```
+Instead, use a specifying classname:
+```css
+.my-custom-class.color-input__box {}
+.my-custom-class.color-input__popup {}
+```
-There is no need to use `!important`. Default styles are easily overridable by adding specificity to the selectors with `.color-input.user .
`.
+### Use preprocesser nesting to reduce typing
-And if you use scss that's even more natural with nesting:
+If you use a style preprocessor (like sass), you can use it's nesting to reduce the amount of typing and produce a cleaner and more readable code:
```scss
-.color-input.user {
- .box {}
- .picker-popup {}
- // etc
+div.color-input {
+ &__box {
+ &--disabled {}
+ &--active {}
+ }
+ &__popup {}
+ &__slider {}
}
```
-### Set margin on the root element
+### Don't use scoped styles
+
+With scoped styles you won't be able to reach component's inner elements, so you should use global styles.
-`margin` is one of the few properties that should belong to the `.color-input` itself.
-Setting margin on the `.box` instead will increase the space around it _inside_ the root element, and that _will mess with how the popup is positioned._
+If, for some reason, you need to use several vue-color-input instances that should be styled differently, you can set different class names on them to provide instance-based scope.
# Events
@@ -490,70 +551,67 @@ The instance provides hooks for custom event handling.
Most events carry payload with current state of the corresponding color component.
-Notice that event data is always passed in __hsv__ format.
+Note that event data is always passed in __hsv__ format.
## Event names
-| event | description | payload |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
-| __pickEnd__ | color picking process is finished, popup will close now | |
-| __mounted__ | lifecycle hook, emitted from root component's mounted() | |
-| __beforeUnmount__ | lifecycle hook, emitted from root component's beforeUnmount() | |
-| __pickStart__ | color picking process is initiated, popup is opening | |
-| __saturationInputStart__ | saturation-brightness adjustment has begun.
This is only emitted when pointerdown inside saturation-brightness area is registered.
This will _not_ emit when text inputs are edited | current state of saturation & value (hsv)
`{ s: 0.5, v: 0.5 }` |
-| __saturationInputEnd__ | saturation-brightness adjustment has ended.
This is only emitted when pointerup of the saturation-brightness area is registered.
This will _not_ emit when text inputs are edited | current state of saturation & value (hsv)
`{ s: 0.5, v: 0.5 }` |
-| __saturationInput__ | saturation-brightness is being adjusted.
This will emit every time saturation-brightness is changed, including text inputs | current state of saturation & value (hsv)
`{ s: 0.5, v: 0.5 }` |
-| __hueInputStart__ | hue adjustment has begun.
This is only emitted when pointerdown over the hue slider is registered.
This will _not_ emit when hue is changed from text inputs | current state of hue
`{ h: 180 }` |
-| __hueInputEnd__ | hue adjustment has ended.
This is only emitted when pointerup of the hue slider is registered.
This will _not_ emit when hue is changed from text inputs | current state of hue
`{ h: 180 }` |
-| __hueInput__ | hue is being adjusted.
This will emit every time hue is changed, including text inputs | current state of hue
`{ h: 180 }` |
-| __alphaInputStart__ | alpha adjustment has begun.
This is only emitted when pointerdown over the alpha slider is registered.
This will _not_ emit when alpha is changed from text inputs | current state of alpha
`{ a: 0.5 }` |
-| __alphaInputEnd__ | alpha adjustment has ended.
This is only emitted when pointerup of the alpha slider is registered.
This will _not_ emit when alpha is changed from text inputs | current state of alpha
`{ a: 0.5 }` |
-| __alphaInput__ | alpha is being adjusted.
This will emit every time alpha is changed, including text inputs | current state of alpha
`{ a: 0.5 }` |
-| __change__ | the color has changed by user interaction.
This will emit every time _any_ parameter is changed.
This _will_ emit when color is changed from text inputs as well, on blur | current state of all color components
`{ h: 180, s: 0.5, v: 0.5, a: 0.5 }` |
+Generally you don't need to rely on events to retrieve color data from this component. Instead, you should use [v-model](#v-model) two-way binding.
+
+But if you want to setup some additional hooks, the component emits following events:
+
+| event | description | payload |
+|---|---|---|
+| __pickStart__ | color picking process is initiated, popup is opening | |
+| __pickEnd__ | color picking process is finished, popup will close now | |
+| __mounted__ | lifecycle hook, emitted from root component's mounted() | |
+| __beforeUnmount__ | lifecycle hook, emitted from root component's beforeUnmount() | |
+| __saturationInputStart__ | saturation-brightness adjustment has begun. This is only emitted when pointerdown inside saturation-brightness area is registered. This will _not_ emit when text inputs are edited | current state of saturation & value (hsv) `{ s: 0.5, v: 0.5 }` |
+| __saturationInputEnd__ | saturation-brightness adjustment has ended. This is only emitted when pointerup of the saturation-brightness area is registered. This will _not_ emit when text inputs are edited | current state of saturation & value (hsv) `{ s: 0.5, v: 0.5 }` |
+| __saturationInput__ | saturation-brightness is being adjusted. This will emit every time saturation-brightness is changed, including text inputs | current state of saturation & value (hsv) `{ s: 0.5, v: 0.5 }` |
+| __hueInputStart__ | hue adjustment has begun. This is only emitted when pointerdown over the hue slider is registered. This will _not_ emit when hue is changed from text inputs | current state of hue `{ h: 180 }` |
+| __hueInputEnd__ | hue adjustment has ended. This is only emitted when pointerup of the hue slider is registered. This will _not_ emit when hue is changed from text inputs | current state of hue `{ h: 180 }` |
+| __hueInput__ | hue is being adjusted. This will emit every time hue is changed, including text inputs | current state of hue `{ h: 180 }` |
+| __alphaInputStart__ | alpha adjustment has begun. This is only emitted when pointerdown over the alpha slider is registered. This will _not_ emit when alpha is changed from text inputs | current state of alpha `{ a: 0.5 }` |
+| __alphaInputEnd__ | alpha adjustment has ended. This is only emitted when pointerup of the alpha slider is registered. This will _not_ emit when alpha is changed from text inputs | current state of alpha `{ a: 0.5 }` |
+| __alphaInput__ | alpha is being adjusted. This will emit every time alpha is changed, including text inputs | current state of alpha `{ a: 0.5 }` |
+| __change__ | the color has changed by user interaction. This will emit every time _any_ parameter is changed. This _will_ emit when color is changed from text inputs as well, on blur | current state of all color components `{ h: 180, s: 0.5, v: 0.5, a: 0.5 }` |
## Example
```xml
-
+
```
-# $refs & methods
+# Exposed methods and properties
-You shouldn't _need_ to manually access instance elements or methods, but if you feel like it, you can.
+You shouldn't _need_ to manually access instance methods and properties, but if you feel like it, you can.
This can be done by specifying a `ref` property on the instance.
-The following section implies you have a vue-color-input instance with a `ref` property set to `"colorInput"`:
+The following section implies you have a vue-color-input instance with a `ref` variable named `colorInput` in a script setup context:
```xml
-
+
```
-
-## Instances
-
-```javascript
-const colorInput = this.$refs.colorInput // root instance
-const picker = colorInput.$refs.picker // popup color picker instance
-```
-
-## Elements
-
```javascript
-colorInput.$refs.root // root element
-colorInput.$refs.box // box root element
-picker.$refs.rootPicker // color picker root element
+const colorInput = ref()
```
-## Methods
+## Exposed methods
```javascript
-colorInput.pickStart() // begin color selection (show popup)
-colorInput.pickEnd() // end color selection (hide popup)
+colorInput.value.pickStart() // begin color selection (show popup)
+colorInput.value.pickEnd() // end color selection (hide popup)
```
-## `color` property
+## Exposed properties
```javascript
-colorInput.color // tinycolor instance
+colorInput.value.color // tinycolor instance
+colorInput.value.active // boolean - is the picker currently active
```
diff --git a/README.md b/README.md
index 9541a64..0a37fa6 100644
--- a/README.md
+++ b/README.md
@@ -35,26 +35,11 @@ npm i vue-color-input
### Import
```javascript
import ColorInput from 'vue-color-input'
-
-
-// install it with use()
-
-app.use(ColorInput)
-
-// OR register component globally
-
-app.component('ColorInput', ColorInput)
-
-// OR locally
-
-export.default {
- components: { ColorInput }
-}
```
### Use
```xml
-
+
```
diff --git a/babel.config.js b/babel.config.js
deleted file mode 100644
index bd13c1b..0000000
--- a/babel.config.js
+++ /dev/null
@@ -1,3 +0,0 @@
-module.exports = {
- presets: ['@babel/preset-env']
-}
\ No newline at end of file
diff --git a/build/rollup.config.js b/build/rollup.config.js
deleted file mode 100644
index a96cf63..0000000
--- a/build/rollup.config.js
+++ /dev/null
@@ -1,177 +0,0 @@
-// rollup.config.js
-import fs from 'fs';
-import path from 'path';
-import vue from 'rollup-plugin-vue';
-import alias from '@rollup/plugin-alias';
-import commonjs from '@rollup/plugin-commonjs';
-import resolve from '@rollup/plugin-node-resolve';
-import replace from '@rollup/plugin-replace';
-import babel from '@rollup/plugin-babel';
-import PostCSS from 'rollup-plugin-postcss';
-import { terser } from 'rollup-plugin-terser';
-import minimist from 'minimist';
-import Sass from 'rollup-plugin-sass'; // added this for using scss
-import svg from 'rollup-plugin-svg'; // added this to inline svg
-import autoprefixer from 'autoprefixer';
-
-
-// Get browserslist config and remove ie from es build targets
-const esbrowserslist = fs.readFileSync('./.browserslistrc')
- .toString()
- .split('\n')
- .filter((entry) => entry && entry.substring(0, 2) !== 'ie');
-
-// Extract babel preset-env config, to combine with esbrowserslist
-// const babelPresetEnvConfig = require('../babel.config')
-// .presets.filter((entry) => entry[0] === '@babel/preset-env')[0][1];
-
-const argv = minimist(process.argv.slice(2));
-
-const projectRoot = path.resolve(__dirname, '..');
-
-const baseConfig = {
- input: 'src/entry.js',
- plugins: {
- preVue: [
- alias({
- entries: [
- {
- find: '@',
- replacement: `${path.resolve(projectRoot, 'src')}`,
- },
- ],
- }),
- svg({ // added this
- base64: true
- }),
- ],
- replace: {
- 'process.env.NODE_ENV': JSON.stringify('production'),
- },
- vue: {
- preprocessStyles: true,
- // css: false, // convert style blocks to import statements
- },
- postVue: [
- resolve({
- extensions: ['.js', '.jsx', '.ts', '.tsx', '.vue'],
- }),
- Sass(), // added this
- PostCSS({
- include: /.css$/,
- plugins: [ autoprefixer() ], // added autoprefixer
- }),
- commonjs(),
- ],
- babel: {
- exclude: 'node_modules/**',
- extensions: ['.js', '.jsx', '.ts', '.tsx', '.vue'],
- babelHelpers: 'bundled',
- },
- },
-};
-
-// ESM/UMD/IIFE shared settings: externals
-// Refer to https://rollupjs.org/guide/en/#warning-treating-module-as-external-dependency
-const external = [
- // list external dependencies, exactly the way it is written in the import statement.
- // eg. 'jquery'
- 'vue',
- 'tinycolor2' // externalize tinycolor dependency
-];
-
-// UMD/IIFE shared settings: output.globals
-// Refer to https://rollupjs.org/guide/en#output-globals for details
-const globals = {
- // Provide global variable names to replace your external imports
- // eg. jquery: '$'
- vue: 'Vue',
-};
-
-// Customize configs for individual targets
-const buildFormats = [];
-if (!argv.format || argv.format === 'es') {
- const esConfig = {
- ...baseConfig,
- input: 'src/entry.esm.js',
- external,
- output: {
- file: 'dist/color-input.esm.js',
- format: 'esm',
- exports: 'named',
- },
- plugins: [
- replace(baseConfig.plugins.replace),
- ...baseConfig.plugins.preVue,
- vue(baseConfig.plugins.vue),
- ...baseConfig.plugins.postVue,
- babel({
- ...baseConfig.plugins.babel,
- presets: [
- [
- '@babel/preset-env',
- {
- // ...babelPresetEnvConfig,
- targets: esbrowserslist,
- },
- ],
- ],
- }),
- ],
- };
- buildFormats.push(esConfig);
-}
-
-if (!argv.format || argv.format === 'cjs') {
- const umdConfig = {
- ...baseConfig,
- external,
- output: {
- compact: true,
- file: 'dist/color-input.ssr.js',
- format: 'cjs',
- name: 'ColorInput',
- exports: 'auto',
- globals,
- },
- plugins: [
- replace(baseConfig.plugins.replace),
- ...baseConfig.plugins.preVue,
- vue(baseConfig.plugins.vue),
- ...baseConfig.plugins.postVue,
- babel(baseConfig.plugins.babel),
- ],
- };
- buildFormats.push(umdConfig);
-}
-
-if (!argv.format || argv.format === 'iife') {
- const unpkgConfig = {
- ...baseConfig,
- external: [ 'vue' ], // include tinycolor in unpkg version
- output: {
- compact: true,
- file: 'dist/color-input.min.js',
- format: 'iife',
- name: 'ColorInput',
- exports: 'auto',
- globals,
- },
- plugins: [
- replace(baseConfig.plugins.replace),
- ...baseConfig.plugins.preVue,
- vue(baseConfig.plugins.vue),
- ...baseConfig.plugins.postVue,
- babel(baseConfig.plugins.babel),
- terser({
- output: {
- ecma: 5,
- },
- }),
- ],
- };
- buildFormats.push(unpkgConfig);
-}
-
-// Export config
-export default buildFormats;
diff --git a/dev/demo-styles.css b/dev/demo-styles.css
index 144181d..3caef50 100644
--- a/dev/demo-styles.css
+++ b/dev/demo-styles.css
@@ -1,20 +1,21 @@
-.color-input.user .box {
+div.color-input__box {
width: 100px;
height: 100px;
- border-radius: 50px;
}
-.color-input.user .box.active {
+div.color-input__box--active {
background: #0f0f0f;
}
-.color-input.user .box.active .inner {
- transform: scale(.9) rotate(90deg);
+div.color-input__box-inner--active {
+ transform: scale(.88);
}
-.color-input.user .box.disabled {}
-.color-input.user .picker-popup {}
-.color-input.user .slider {}
-.color-input.user .slider-pointer {}
-.color-input.user .saturation-pointer {}
-.color-input.user .picker-popup-enter-from,
-.color-input.user .picker-popup-leave-to {}
-.color-input.user .picker-popup-enter-active,
-.color-input.user .picker-popup-leave-active {}
\ No newline at end of file
+div.color-input__box--disabled {}
+
+div.color-input__popup {}
+div.color-input__slider {}
+div.color-input__slider-pointer {}
+div.color-input__saturation-pointer {}
+
+div.color-input__popup--enter-from,
+div.color-input__popup--leave-to {}
+div.color-input__popup--enter-active,
+div.color-input__popup--leave-active {}
diff --git a/dev/serve-setup.vue b/dev/serve-setup.vue
new file mode 100644
index 0000000..d4b29e2
--- /dev/null
+++ b/dev/serve-setup.vue
@@ -0,0 +1,27 @@
+
+
+
+
+
+
+
+
diff --git a/dev/serve.js b/dev/serve.js
index 6e917ad..5725ed9 100644
--- a/dev/serve.js
+++ b/dev/serve.js
@@ -1,8 +1,9 @@
import { createApp } from 'vue';
import Dev from './serve.vue';
+import DevSetup from './serve-setup.vue';
const app = createApp(Dev);
app.config.unwrapInjectedRef = true;
app.mount('#app');
-document.title = 'vue-color-input';
\ No newline at end of file
+document.title = 'vue-color-input';
diff --git a/dev/serve.vue b/dev/serve.vue
index 91e9e0e..da23ed1 100644
--- a/dev/serve.vue
+++ b/dev/serve.vue
@@ -2,7 +2,7 @@
-
+
Style it
@@ -97,9 +99,9 @@
+