diff --git a/packages/color-handle/README.md b/packages/color-handle/README.md index f5614e56d75..64bd854cecf 100644 --- a/packages/color-handle/README.md +++ b/packages/color-handle/README.md @@ -1,45 +1,164 @@ -## Description +## Overview -The `` is used to select a colour on an ``, ``, or ``. It functions similarly to the handle on an ``. +The `` is used to select a color on an ``, ``, or ``. It provides a draggable control point for precise color selection within color components. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/color-handle?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/color-handle) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/color-handle?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/color-handle) -``` +**Note**: `` is a primitive component designed to be used within other color selection components. It's not typically used directly in applications, but rather as part of higher-level color components like ``, ``, or ``. + +```bash yarn add @spectrum-web-components/color-handle ``` Import the side effectful registration of `` via: -``` +```javascript import '@spectrum-web-components/color-handle/sp-color-handle.js'; ``` When looking to leverage the `ColorHandle` base class as a type and/or for extension purposes, do so via: -``` +```javascript import { ColorHandle } from '@spectrum-web-components/color-handle'; ``` -## Standard +### Anatomy + +The color handle consists of several key parts: + +- A visual handle element that indicates the current position +- Touch-responsive interaction areas +- Color display showing the current selected color +- Opacity checkerboard pattern for transparent colors +- An optional `sp-color-loupe` that appears above the handle when the properties `open = true` and `disabled = false` ```html ``` -## Disabled +### Options + +#### Color + +The `color` property sets the visual color displayed within the handle. This accepts any valid CSS color format. The default color is `rgba(255, 0, 0, 0.5)` (semi-transparent red). + +For a complete list of supported color formats, see the [ColorController documentation](/tools/color-controller#supported-color-formats). + +**Transparency Support**: When using transparent colors, the handle displays an opacity checkerboard pattern background to clearly show the transparency level. + +```html +
+ +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+
+``` + +### States + +#### Standard + +The default state of the color handle, ready for interaction: + +```html + +``` + +#### Disabled + +A disabled color handle shows that the control exists but is not available for interaction. This maintains layout continuity and communicates that the handle may become available later: ```html ``` -## Open +#### Open -When the `` uses the `open` property, the `` component can be used above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type. +When the `open` property is set, the `` component appears above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. The loupe automatically appears for touch input (`pointerType === 'touch'`). ```html
``` + +**Automatic Behavior**: The loupe automatically opens when touched and closes when the touch interaction ends. For mouse and stylus input, the loupe remains hidden by default unless explicitly set to `open="true"`. + +#### Focused + +The color handle can receive keyboard focus when used within interactive color components. The focused state is managed automatically by the parent component and is indicated visually: + +```html + +``` + +### Behaviors + +#### Pointer Interactions + +The color handle automatically manages pointer events to provide the optimal user experience: + +- **Touch Input**: When touched (`pointerType === 'touch'`), the color loupe automatically appears to prevent the finger from obscuring the selected color +- **Mouse/Stylus Input**: The loupe remains hidden by default for precision pointing devices +- **Pointer Capture**: The handle captures pointer events during interaction to ensure smooth dragging even when the pointer moves outside the handle area +- **Event Handling**: The component listens for `pointerdown`, `pointerup`, and `pointercancel` events to manage the interaction lifecycle + +#### Color Display + +The handle displays the current color with proper support for transparency: + +- Transparent colors are shown with an opacity checkerboard pattern background +- The color updates in real-time as the user interacts with the parent color component +- Supports all standard CSS color formats + +For a complete list of supported color formats, see the [ColorController documentation](/tools/color-controller#supported-color-formats). + +### Accessibility + +The `` is designed to work as part of accessible color selection components: + +#### Keyboard Support + +While the color handle itself is not directly keyboard accessible, it works in conjunction with its parent components ([``](/components/color-area), [``](/components/color-slider), [``](/components/color-wheel)) which provide comprehensive keyboard navigation. +Example: Keyboard accessibility with `sp-color-area` as parent component + +```html + +``` + +#### Screen Reader Support + +The color handle is rendered as a visual indicator and does not directly interface with screen readers. Accessibility is provided through the parent color component's ARIA implementation. + +#### Touch Accessibility + +- **Color Loupe**: Automatically appears for touch input to ensure the selected color remains visible +- **Large Touch Target**: The handle provides an appropriately sized touch target for mobile interaction +- **Pointer Capture**: Ensures reliable dragging behavior across different touch devices + +#### Focus Management + +Focus is managed by the parent color component, with the handle reflecting the focused state visually when its parent component has keyboard focus. diff --git a/tools/reactive-controllers/color-controller.md b/tools/reactive-controllers/color-controller.md index 2703bd44a7f..093acb508eb 100644 --- a/tools/reactive-controllers/color-controller.md +++ b/tools/reactive-controllers/color-controller.md @@ -6,33 +6,33 @@ The `ColorController` class is a comprehensive utility for managing and validati ### Features -- **Color Management**: The `ColorController` allows you to manage color values in multiple formats, including RGB, HSL, HSV, and Hex. -- **Validation**: It provides methods to validate color strings and ensure they conform to the expected formats. -- **Conversion**: The class can convert colors between different color spaces, making it versatile for various applications. -- **State Management**: It maintains the current color state and allows saving and restoring previous color values. +- **Color Management**: The `ColorController` allows you to manage color values in multiple formats, including RGB, HSL, HSV, and Hex. +- **Validation**: It provides methods to validate color strings and ensure they conform to the expected formats. +- **Conversion**: The class can convert colors between different color spaces, making it versatile for various applications. +- **State Management**: It maintains the current color state and allows saving and restoring previous color values. ### Properties -- **`color`**: Gets or sets the current color value. The color can be provided in various formats, including strings, objects, or instances of the `Color` class. -- **`colorValue`**: Gets the color value in various formats based on the original color input. -- **`hue`**: Gets or sets the hue value of the current color. +- **`color`**: Gets or sets the current color value. The color can be provided in various formats, including strings, objects, or instances of the `Color` class. +- **`colorValue`**: Gets the color value in various formats based on the original color input. +- **`hue`**: Gets or sets the hue value of the current color. ### Methods -- **`validateColorString(color: string): ColorValidationResult`**: - Validates a color string and returns the validation result, including the color space, coordinates, alpha value, and validity. +- **`validateColorString(color: string): ColorValidationResult`**: + Validates a color string and returns the validation result, including the color space, coordinates, alpha value, and validity. -- **`getColor(format: string | ColorSpace): ColorObject`**: - Converts the current color to the specified format. Throws an error if the format is not valid. +- **`getColor(format: string | ColorSpace): ColorObject`**: + Converts the current color to the specified format. Throws an error if the format is not valid. -- **`getHslString(): string`**: - Returns the current color in HSL string format. +- **`getHslString(): string`**: + Returns the current color in HSL string format. -- **`savePreviousColor(): void`**: - Saves the current color as the previous color. +- **`savePreviousColor(): void`**: + Saves the current color as the previous color. -- **`restorePreviousColor(): void`**: - Restores the previous color. +- **`restorePreviousColor(): void`**: + Restores the previous color. ## Usage @@ -118,5 +118,74 @@ class Host extends LitElement { } } +``` +## Supported Color Formats + +The `ColorController` supports a wide range of color formats for input and output: + + + + Format + Example Values + Description + + + + Hex3 + #f00, #0a5 + 3-digit hexadecimal + + + Hex4 + #f00f, #0a58 + 3-digit hexadecimal + alpha + + + Hex6 + #ff0000, #00aa55 + 6-digit hexadecimal + + + Hex8 + #ff0000ff, #00aa5580 + 6-digit hexadecimal + alpha + + + RGB + rgb(255, 0, 0), rgb(0, 170, 85) + Red, Green, Blue values (0-255) + + + RGBA + rgba(255, 0, 0, 1), rgba(0, 170, 85, 0.5) + RGB + Alpha channel (0-1) + + + HSL + hsl(0, 100%, 50%), hsl(150, 100%, 33%) + Hue (0-360°), Saturation, Lightness + + + HSLA + hsla(0, 100%, 50%, 1), hsla(150, 100%, 33%, 0.5) + HSL + Alpha channel (0-1) + + + HSV + hsv(0, 100%, 100%), hsv(150, 100%, 67%) + Hue (0-360°), Saturation, Value + + + HSVA + hsva(0, 100%, 100%, 1), hsva(150, 100%, 67%, 0.5) + HSV + Alpha channel (0-1) + + + Named Colors + red, rebeccapurple, darkseagreen + CSS color keywords (full list) + + + ```