nxt-color-picker 22.0.0 → 22.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +138 -40
- package/fesm2022/nxt-color-picker.mjs +2402 -1689
- package/fesm2022/nxt-color-picker.mjs.map +1 -1
- package/package.json +2 -1
- package/types/nxt-color-picker.d.ts +474 -233
package/README.md
CHANGED
|
@@ -1,40 +1,138 @@
|
|
|
1
|
-
# Angular color picker
|
|
2
|
-
|
|
3
|
-
[](https://github.com/Liquid-JS/nxt-components/blob/master/LICENSE)
|
|
4
|
-
[](https://www.npmjs.com/package/nxt-color-picker)
|
|
5
|
-
[](https://www.npmjs.com/package/nxt-color-picker)
|
|
6
|
-
|
|
7
|
-
A color picker widget for Angular with no dependencies.
|
|
8
|
-
|
|
9
|
-
## Quick links
|
|
10
|
-
|
|
11
|
-
- [Demo](https://liquid-js.github.io/nxt-components/demo/color-picker)
|
|
12
|
-
- [Getting started](https://liquid-js.github.io/nxt-components/demo/color-picker/getting-started)
|
|
13
|
-
- [API docs](https://liquid-js.github.io/nxt-components/nxt-color-picker)
|
|
14
|
-
|
|
15
|
-
### Installing
|
|
16
|
-
|
|
17
|
-
```sh
|
|
18
|
-
npm install --save nxt-color-picker
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
### Import color picker directive
|
|
22
|
-
|
|
23
|
-
```ts
|
|
24
|
-
import { ColorPickerDirective } from 'nxt-color-picker'
|
|
25
|
-
|
|
26
|
-
@Component({
|
|
27
|
-
...
|
|
28
|
-
imports: [
|
|
29
|
-
...
|
|
30
|
-
ColorPickerDirective
|
|
31
|
-
]
|
|
32
|
-
})
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
### Include it in HTML template
|
|
36
|
-
|
|
37
|
-
```html
|
|
38
|
-
<input [(nxtColor)]="color"
|
|
39
|
-
[style.background]="color"/>
|
|
40
|
-
```
|
|
1
|
+
# Angular color picker
|
|
2
|
+
|
|
3
|
+
[](https://github.com/Liquid-JS/nxt-components/blob/master/LICENSE)
|
|
4
|
+
[](https://www.npmjs.com/package/nxt-color-picker)
|
|
5
|
+
[](https://www.npmjs.com/package/nxt-color-picker)
|
|
6
|
+
|
|
7
|
+
A color picker widget for Angular with no dependencies.
|
|
8
|
+
|
|
9
|
+
## Quick links
|
|
10
|
+
|
|
11
|
+
- [Demo](https://liquid-js.github.io/nxt-components/demo/color-picker)
|
|
12
|
+
- [Getting started](https://liquid-js.github.io/nxt-components/demo/color-picker/getting-started)
|
|
13
|
+
- [API docs](https://liquid-js.github.io/nxt-components/nxt-color-picker)
|
|
14
|
+
|
|
15
|
+
### Installing
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install --save nxt-color-picker
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Import color picker directive
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { ColorPickerDirective } from 'nxt-color-picker'
|
|
25
|
+
|
|
26
|
+
@Component({
|
|
27
|
+
...
|
|
28
|
+
imports: [
|
|
29
|
+
...
|
|
30
|
+
ColorPickerDirective
|
|
31
|
+
]
|
|
32
|
+
})
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Include it in HTML template
|
|
36
|
+
|
|
37
|
+
```html
|
|
38
|
+
<input [(nxtColor)]="color"
|
|
39
|
+
[style.background]="color"/>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Forms
|
|
43
|
+
|
|
44
|
+
`ColorPickerControlDirective` makes the color picker a form control, with `formControl`, `formControlName`, `ngModel`
|
|
45
|
+
or signal forms' `formField`, in place of `[(nxtColor)]`:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { ColorPickerControlDirective, ColorPickerDirective } from 'nxt-color-picker'
|
|
49
|
+
|
|
50
|
+
@Component({
|
|
51
|
+
...
|
|
52
|
+
imports: [
|
|
53
|
+
...
|
|
54
|
+
ColorPickerDirective,
|
|
55
|
+
ColorPickerControlDirective
|
|
56
|
+
]
|
|
57
|
+
})
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```html
|
|
61
|
+
<input nxtColor formControlName="color" outputFormat="hex" />
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The value is the color in the output format, or the CMYK color with `cmykEnabled`, and `null` without one; colors
|
|
65
|
+
that only differ in spaces or case are the same value, so they don't change it. The input shows the color, also when
|
|
66
|
+
the dialog changes it, but not while it's typed in. The control is touched when the dialog closes, or when the input
|
|
67
|
+
loses focus while the dialog is closed, and the picker follows the form's disabled state.
|
|
68
|
+
|
|
69
|
+
### Clearing
|
|
70
|
+
|
|
71
|
+
With `clearable`, the user can remove the color: the dialog has a Clear button, and emptying the input clears it.
|
|
72
|
+
The color is then an empty string, and a form control's value `null`.
|
|
73
|
+
|
|
74
|
+
```html
|
|
75
|
+
<input nxtColor formControlName="color" clearable />
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Keyboard
|
|
79
|
+
|
|
80
|
+
The dialog opens when the field has focus, and the field keeps it, so typing a color and Tab work as usual. To use
|
|
81
|
+
the dialog by keyboard:
|
|
82
|
+
|
|
83
|
+
- **Arrow Down** in the field opens the dialog and moves focus into it. Tab and Shift+Tab move between its
|
|
84
|
+
controls and stay within it.
|
|
85
|
+
- The saturation and brightness area and the hue and opacity sliders move with the **arrow keys** by 1%, by 10%
|
|
86
|
+
with **Shift**, and with **Page Up** and **Page Down**; **Home** and **End** move a slider to its ends. In the
|
|
87
|
+
area, Up and Down change the brightness.
|
|
88
|
+
- **Enter** keeps the color and **Escape** goes back to the color the dialog opened with. Both close the dialog
|
|
89
|
+
and return focus to the field.
|
|
90
|
+
|
|
91
|
+
The field has `aria-haspopup="dialog"` and `aria-expanded`, the dialog, its sliders, inputs and buttons and the
|
|
92
|
+
preset colors are named, and the sliders announce their values. The format arrows and the preset colors work with
|
|
93
|
+
Enter and Space.
|
|
94
|
+
|
|
95
|
+
### Texts
|
|
96
|
+
|
|
97
|
+
The texts the dialog shows and announces are English and translated with `@angular/localize`, as messages with ids
|
|
98
|
+
like `@@nxt-color-picker.button.ok`. `provideColorPickerTexts` changes them, for the app or for the color pickers in
|
|
99
|
+
a component; the others stay as they are. It takes the texts, or a function that gives them, e.g. from signals, which
|
|
100
|
+
the dialog follows, so an app can change them at run time:
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
import { provideColorPickerTexts } from 'nxt-color-picker'
|
|
104
|
+
|
|
105
|
+
providers: [provideColorPickerTexts({ ok: 'Apply', presetColors: 'Brand colors' })]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`ColorPickerTexts` lists them all, from the dialog's name to the Clear button.
|
|
109
|
+
|
|
110
|
+
### Theming
|
|
111
|
+
|
|
112
|
+
The dialog takes its colors and sizes from CSS custom properties, so it can match an app's design. Set them on
|
|
113
|
+
`nxt-color-picker`, or on an element the dialog is in, e.g. the overlay container:
|
|
114
|
+
|
|
115
|
+
```css
|
|
116
|
+
nxt-color-picker {
|
|
117
|
+
--nxt-color-picker-background: #fff;
|
|
118
|
+
--nxt-color-picker-text-color: #222b45;
|
|
119
|
+
--nxt-color-picker-border: 1px solid #e4e9f2;
|
|
120
|
+
--nxt-color-picker-border-radius: 0.25rem;
|
|
121
|
+
--nxt-color-picker-input-background: #f7f9fc;
|
|
122
|
+
--nxt-color-picker-input-border-color: #e4e9f2;
|
|
123
|
+
--nxt-color-picker-input-focus-border-color: #3366ff;
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
| Property | Styles |
|
|
128
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
129
|
+
| `--nxt-color-picker-background`, `-text-color`, `-font-family`, `-font-size` | the dialog |
|
|
130
|
+
| `--nxt-color-picker-border`, `-border-radius`, `-shadow` | the dialog's frame |
|
|
131
|
+
| `--nxt-color-picker-border-color` | the separator and the arrow pointing at the field |
|
|
132
|
+
| `--nxt-color-picker-focus-outline`, `-focus-outline-offset`, `-focus-outline-width` | the focused slider, preset or button |
|
|
133
|
+
| `--nxt-color-picker-arrow-color` | the arrows that change the input format |
|
|
134
|
+
| `--nxt-color-picker-input-background`, `-input-border-color`, `-input-border-width`, `-input-border-radius`, `-input-text-color`, `-input-placeholder-color`, `-input-height` | the dialog's inputs |
|
|
135
|
+
| `--nxt-color-picker-input-hover-*`, `-input-focus-*`, `-input-disabled-*` (`background`, `border-color`, and `text-color` when disabled) | the inputs under the pointer, with focus and disabled |
|
|
136
|
+
| `--nxt-color-picker-button-color`, `-button-background`, `-button-padding`, `-button-border`, `-button-border-radius`, `-button-font-size`, `-button-font-weight` | the OK, Cancel and Clear buttons |
|
|
137
|
+
|
|
138
|
+
Without them the dialog looks as it always has.
|