diff --git a/packages/color-field/README.md b/packages/color-field/README.md index e09c1430b3..52dcb6dee1 100644 --- a/packages/color-field/README.md +++ b/packages/color-field/README.md @@ -1,30 +1,44 @@ -## Description +## Overview -`` elements are textfields that allow users to input custom color values. -Color formats supported are `HEX, RGB, HSL, HSV, and shorthand HEX` +`` elements are textfields that allow users to input custom color values. They support multiple color formats including `HEX`, `RGB`, `HSL`, `HSV`, and shorthand `HEX` formats, providing a flexible interface for color selection in applications. -## Usage +### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/color-field?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/color-field) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/color-field?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/color-field) -``` +```bash yarn add @spectrum-web-components/color-field ``` Import the side effectful registration of `` via: -``` +```javascript import '@spectrum-web-components/color-field/sp-color-field.js'; ``` When looking to leverage the `ColorField` base class as a type and/or for extension purposes, do so via: -``` +```javascript import { ColorField } from '@spectrum-web-components/color-field'; ``` -## Sizes +### Anatomy + +The color field consists of several key parts: + +- **Input field**: The main text input area where users can type color values +- **Color handle**: An optional visual indicator showing the current color (when `view-color` attribute is enabled) +- **Validation feedback**: Visual indicators for valid and invalid color inputs +- **Size variations**: Different size options to match your design requirements + +```html + +``` + +### Options + +#### Sizes Small @@ -63,7 +77,7 @@ import { ColorField } from '@spectrum-web-components/color-field'; -## View Color +#### View Color When `view-color` is true, the color handle will be rendered. This is useful for development and debugging purposes. @@ -71,72 +85,168 @@ When `view-color` is true, the color handle will be rendered. This is useful for ``` -## Read Only +#### Quiet -A readonly color field +A quiet color field provides a more subtle appearance: ```html - + ``` -## Quiet +### States + +#### Standard -A Quiet color field +The default state of the color field, ready for user input: ```html - + ``` -## Invalid Input +#### Read Only -If the input value is not a valid color, `` will not accept it. +A readonly color field that displays the color value but prevents user modification: + +```html + +``` + +#### Invalid Input + +If the input value is not a valid color, `` will not accept it and may show validation feedback: ```html ``` -## Valid Input +### Behaviors + +#### Color Format Support -If the input value is a valid color, the `` will accept it and the color handle will be updated to reflect the new color. +The `` component accepts color values in various formats: `HEX`, `RGB`, `HSL`, `HSV`, and shorthand `HEX` -`` component accepts color values in various formats: `HEX, RGB, HSL, HSV, and shorthand HEX` +For a complete list of supported color formats, see the [ColorController documentation](/tools/color-controller#supported-color-formats). -- **HEX**: A hexadecimal color is specified with: `#RRGGBB`. `RR` (red), `GG` (green) and `BB` (blue) are hexadecimal integers between `00` and `FF` specifying the intensity of the color. + +HEX + + +A hexadecimal color is specified with: `#RRGGBB`. `RR` (red), `GG` (green) and `BB` (blue) are hexadecimal integers between `00` and `FF` specifying the intensity of the color. ```html - + ``` -- **Shorthand HEX**: Shorthand hexadecimal color values are also supported. `#RGB` is a shorthand for `#RRGGBB`. In the shorthand form, `R` (red), `G` (green), and `B` (blue) are hexadecimal characters between `0` and `F`. Each character is repeated to create the full 6-digit color code. For example, `#123` would expand to `#112233`. + +Shorthand HEX + + +Shorthand hexadecimal color values are also supported. `#RGB` is a shorthand for `#RRGGBB`. In the shorthand form, `R` (red), `G` (green), and `B` (blue) are hexadecimal characters between `0` and `F`. Each character is repeated to create the full 6-digit color code. For example, `#123` would expand to `#112233`. ```html ``` -- **RGB**: An RGB color value is specified with: rgb(red, green, blue). Each parameter defines the intensity of the color with a value between 0 and 255. + +RGB + + +An RGB color value is specified with: rgb(red, green, blue). Each parameter defines the intensity of the color with a value between 0 and 255. ```html - + ``` -- **RGBA**: An RGBA color value is specified with: `rgba(red, green, blue, alpha)`. The `alpha` parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). + +RGBA + + +An RGBA color value is specified with: `rgba(red, green, blue, alpha)`. The `alpha` parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). ```html ``` -- **HSL**: An HSL color value is specified with: hsl(hue, saturation, lightness). Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, and 240 is blue. Saturation and lightness are percentages. + +HSL + + +An HSL color value is specified with: hsl(hue, saturation, lightness). Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, and 240 is blue. Saturation and lightness are percentages. ```html ``` -- **HSV**: An HSV color value is specified with: hsv(hue, saturation, value). Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, and 240 is blue. Saturation and value are percentages. + +HSV + + +An HSV color value is specified with: hsv(hue, saturation, value). Hue is a degree on the color wheel from 0 to 360. 0 is red, 120 is green, and 240 is blue. Saturation and value are percentages. ```html ``` -## Events + + + +#### Events + +The `` component fires two types of events for color value changes: + +- **`input` event**: Fired when the value of the color-field has changed (fires on every keystroke) +- **`change` event**: Fired when an alteration to the value of the color-field has been committed by the user (fires when the user finishes editing) + +You can listen for these events to react to changes in the color value: + +```javascript +const colorField = document.querySelector('sp-color-field'); + +// Listen for real-time changes +colorField.addEventListener('input', (event) => { + console.log('Color value changed:', event.target.value); +}); + +// Listen for committed changes +colorField.addEventListener('change', (event) => { + console.log('Color value committed:', event.target.value); +}); +``` + +### Accessibility + +The `` component provides comprehensive accessibility support: + +#### Keyboard Navigation + +- **Tab Navigation**: The color field is keyboard accessible and can be navigated to using the Tab key +- **Input Validation**: Invalid color values are clearly indicated to assistive technologies +- **Focus Management**: Proper focus indicators are provided for keyboard users + +#### Focus Management + +The `` inherits comprehensive focus management capabilities from the `TextfieldBase` class: + +- **Focus Element**: The component automatically delegates focus to the underlying input element, ensuring proper keyboard navigation +- **Focus State Tracking**: The component tracks focus state with the `focused` property, which is reflected as an attribute for styling +- **Focus Event Handling**: Proper focus and blur event handling ensures accessibility compliance +- **Tab Index Management**: Automatic tab index management ensures the component is properly included in the tab order +- **Focus Delegation**: The component properly delegates focus to the underlying input element for keyboard navigation + +#### Screen Reader Support + +- **ARIA Labels**: The component uses appropriate ARIA attributes to describe its purpose and state +- **Value Announcements**: Changes to the color value are announced to screen readers +- **Validation Feedback**: Invalid input states are communicated to assistive technologies + +#### Color Accessibility + +- **Color Contrast**: The component ensures sufficient contrast for text and visual elements +- **Color Independence**: The component works effectively for users with color vision deficiencies +- **Alternative Input**: Multiple color format support provides flexibility for different user needs + +#### Best Practices -The sp-color-field component fires a change event when the color value is changed. You can listen for this event to react to changes in the color value. +- **Provide Labels**: Always include a descriptive label for the color field to provide context +- **Use View Color**: Enable the `view-color` attribute to provide visual feedback alongside text input +- **Validate Input**: Handle invalid color inputs gracefully and provide clear feedback to users