@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/color-picker.md

@@ -0,0 +1,201 @@
+<!-- index: ./index.md -->
+# color-picker
+
+`data-ui="color-picker"` · Color panel and color field in four notations.
+
+## Import
+
+```ts
+import {
+  provideColorPickerDefaults,
+  SlColorField,
+  SlColorPicker,
+} from '@slotted/angular/color-picker';
+```
+
+Selector: `div[slColorPicker], div[slColorField]` · exportAs: `slColorPicker, slColorField`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker defaultValue="#2563EB" (valueChange)="color.set($event.value)"></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div[slColorPicker] | yes |
+| `area` | div, drawn by the panel | no |
+| `area-thumb` | div role="slider" | no |
+| `channel` | div, drawn by the panel | no |
+| `channel-thumb` | div role="slider" | no |
+| `row` | div, drawn by the panel | no |
+| `swatch` | span role="img" | no |
+| `previous` | button | no |
+| `input` | input, in a text-field frame | no |
+| `format` | button with slMenuTriggerFor | no |
+| `eyedropper` | button | no |
+| `presets` | div role="radiogroup" | no |
+| `preset` | button role="radio" | no |
+| `contrast` | div aria-live="polite" | no |
+| `contrast-sample` | span | no |
+| `contrast-ratio` | span | no |
+| `contrast-level` | span | no |
+| `gamut` | p role="status" | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `'outline' \| 'subtle'` | outline | slColorField | The text-field frame of the field |
+| `required` | `boolean` | from the field | slColorField | aria-required on the text, never the native attribute |
+| `value` | `string` | — | slColorPicker, slColorField | Present means controlled: a colour in hex, rgb, hsl or oklch |
+| `defaultValue` | `string` | #000000 | slColorPicker, slColorField | What an uncontrolled picker starts from |
+| `format` | `'hex' \| 'rgb' \| 'hsl' \| 'oklch'` | hex | slColorPicker, slColorField, provideColorPickerDefaults | The notation the value is written in; defaults to the value’s own, then to the provider’s. defaultFormat is the uncontrolled half |
+| `alpha` | `boolean` | true | slColorPicker, slColorField | Whether the colour carries an alpha channel |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slColorPicker, slColorField, provideColorPickerDefaults | The step, read from the field first |
+| `presets` | `readonly string[]` | — | slColorPicker, slColorField, provideColorPickerDefaults | Colours offered as one press |
+| `contrastWith` | `string` | — | slColorPicker, slColorField | The background the contrast is measured against; absent, no contrast is drawn |
+| `disabled` | `boolean` | from the field, or false | slColorPicker, slColorField | Out of the tab order; the colour greyed |
+| `readOnly` | `boolean` | from the field, or false | slColorPicker, slColorField | Focusable and legible; nothing moves |
+| `invalid` | `boolean` | from the field, or false | slColorPicker, slColorField | data-invalid on the root; aria-invalid on the text |
+| `open` | `boolean` | false | slColorField | Present means the consumer owns whether the panel is open; defaultOpen is the uncontrolled half |
+| `messages` | `Partial<ColorPickerMessages>` | — | slColorPicker, slColorField | Words laid over the language in force, key by key: what each control is called, the gamut sentence and the contrast levels |
+| `div[slColorField]` | `component` | — | a form | A text-field whose start is the swatch (data-part="trigger"), opening the panel in a popover; its aria-label moves onto the text. [(open)] is a model |
+| `provideColorPickerDefaults` | `(defaults: Partial<ColorPickerDefaults>) => Provider` | — | an injector | The notation, the palette and the size an application takes once |
+| `exportAs` | `slColorPicker, slColorField` | — | templates | Reach the instance; current() is the value in its notation |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<string>` | Before the colour moves, in the current notation: reason "pointer", "keyboard", "select" (a preset, the restore, a notation change) or "programmatic" (the eyedropper). cancel() refuses the move. |
+| `(formatChange)` | `ChangeRequest<ColorFormat>` | Before the notation changes, with reason "select". |
+| `ControlValueAccessor` | `the form’s own value` | On both slColorPicker and slColorField, whenever the colour moves and nobody refused it. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle` | `outline` |
+| `format` | `hex`, `rgb`, `hsl`, `oklch` | `hex` |
+| `alpha` | `true`, `false` | `true` |
+
+## Rules
+
+- Each thumb is a slider with a name and a value text in words — "Hue, 221°", "Opacity, 60 %", "Saturation and brightness, 84 %, 92 %" — so the colour is never told by colour alone; the area thumb carries aria-roledescription "2D slider", the React Aria convention for a slider with two axes.
+- The keyboard is the APG slider for each channel and the APG radio group for the presets; in a right-to-left document the horizontal arrows follow the mirrored axis.
+- The contrast part names the level in words beside the ratio, and it is aria-live polite, so a reader adjusting the colour hears when it crosses AA.
+- The text is always left-to-right: a colour notation reads the same in every language.
+- Forced colours keep the reader’s colours visible: the area, the channels, the swatches and the presets opt out of the system palette, because a colour picker whose colours are replaced shows nothing.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-color-picker-channel-size`, `--slotted-color-picker-thumb-size`, `--slotted-color-picker-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-md`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-shadow-sm`, `--slotted-space-1`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+
+## Examples
+
+### A field that holds a colour
+
+The swatch in the field’s start opens the panel in a popover; the text takes any notation and keeps the one shown. In a Field, the label names the text.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Cor primária</label>
+  <div slColorField [formControl]="primary" [presets]="brand"></div>
+</div>
+```
+
+### Choosing the parts
+
+The parts are chosen by inputs: alpha off and no presets leave the area, the hue and the row, for a settings row with no room for more.
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker [alpha]="false" [presets]="[]" defaultValue="#16A34A"></div>
+```
+
+### Four notations, one colour
+
+The value comes back in the notation shown. Change it in the menu and the value is rewritten; type another notation and it is converted to this one.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slColorPicker
+  defaultValue="#2563EB"
+  [format]="format()"
+  (formatChange)="format.set($event.value)"
+></div>
+```
+
+### Opacity
+
+The alpha channel fades the colour over the transparency grid, drawn from the theme’s own surfaces. alpha={false} removes it for a colour that must be opaque — a brand colour, a text colour.
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker defaultValue="rgb(22 163 74 / 60%)"></div>
+<div slColorPicker defaultValue="#16A34A" [alpha]="false"></div>
+```
+
+### A palette as one press
+
+The presets are a radio group: arrow keys move and choose. The chosen one is ringed; a value that matches none leaves the first focusable.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideColorPickerDefaults({ presets: ['#0F172A', '#DC2626', '#16A34A', '#2563EB'] })];
+```
+
+### Contrast against the background it will sit on
+
+contrastWith names the background; the panel shows Aa in the colour over it, the WCAG ratio and the level in words. An alpha colour is composited first, because that is what the reader sees.
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker defaultValue="#64748B" contrastWith="#FFFFFF"></div>
+```
+
+### Disabled, read-only and out of gamut
+
+Disabled greys the colour and takes the panel out of the tab order; read-only keeps the sliders focusable and moves nothing; an oklch colour outside sRGB is said, never quietly clipped.
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker disabled defaultValue="#64748B"></div>
+<div slColorPicker readOnly defaultValue="#DB2777"></div>
+<div slColorPicker defaultValue="oklch(0.9 0.3 150)"></div>
+```
+
+### Setting it once
+
+The provider carries the notation and the palette; the words come from the language in force.
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker #picker="slColorPicker" [formControl]="color"></div>
+```
+
+### What the keyboard does
+
+Tab reaches the area, each channel, the restore, the text, the notation, the eyedropper and the chosen preset. Arrows move by 1, Shift and PageUp/PageDown by 10, Home and End to the ends of a channel; in a right-to-left document the horizontal arrows follow the mirrored axis.
+
+Excerpt — not a complete module
+
+```html
+<div slColorPicker defaultValue="#2563EB"></div>
+```