From 9f6b61f4c536dd6dd824c2161e3a0ca695949805 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Fri, 18 Apr 2025 16:45:47 -0400 Subject: [PATCH 1/9] docs(number-field): updated for accessibility --- packages/number-field/README.md | 191 ++++++++++++++++++++++++++++---- 1 file changed, 169 insertions(+), 22 deletions(-) diff --git a/packages/number-field/README.md b/packages/number-field/README.md index 03173de8e5e..cbac45a28b7 100644 --- a/packages/number-field/README.md +++ b/packages/number-field/README.md @@ -1,4 +1,4 @@ -## Description +## Overview `` elements are used for numeric inputs. Upon interaction via the ArrowUp or ArrowDown keys, the scroll wheel, or the stepper UI, when not hidden by the `hide-stepper` attribute, the input value incrementally increases or decreases by the value of the `step` attribute. The shift key can be used to apply steps at 10 time (or the value of the `step-modifier` attribute times) their normal rate. @@ -24,7 +24,28 @@ When looking to leverage the `NumberField` base class as a type and/or for exten import { NumberField } from '@spectrum-web-components/number-field'; ``` -## Sizes +### Anatomy + +A number field consists of an input field for numeric values and optional stepper buttons for incrementing and decrementing the value. The stepper UI can be hidden using the `hide-stepper` attribute. + +```html + + What is the air-speed velocity of an unladen swallow? + + +``` + +### Options + +#### Sizes Small @@ -35,7 +56,7 @@ import { NumberField } from '@spectrum-web-components/number-field'; label="Size" value="1024" size="s" - style="--spectrum-stepper-width: 85px" + style="--spectrum-stepper-width: 170px" > ``` @@ -48,7 +69,7 @@ import { NumberField } from '@spectrum-web-components/number-field'; label="Size" value="1024" size="m" - style="--spectrum-stepper-width: 110px" + style="--spectrum-stepper-width: 220px" > ``` @@ -61,7 +82,7 @@ import { NumberField } from '@spectrum-web-components/number-field'; label="Size" value="1024" size="l" - style="--spectrum-stepper-width: 135px" + style="--spectrum-stepper-width: 270px" > ``` @@ -74,20 +95,22 @@ import { NumberField } from '@spectrum-web-components/number-field'; label="Size" value="1024" size="xl" - style="--spectrum-stepper-width: 160px" + style="--spectrum-stepper-width: 320px" > ``` -## Number formatting +#### Formatting An `` element will process its numeric value with `new Intl.NumberFormat(this.resolvedLanguage, this.formatOptions).format(this.value)` in order to prepare it for visual delivery in the input. In order to customize this processing supply your own `Intl.NumberFormatOptions` via the `formatOptions` property, or `format-options` attribute as seen below. `this.resolvedLanguage` represents the language in which the `` element is currently being delivered. By default, this value will represent the language established by the `lang` attribute on the root `` element while falling back to `navigator.language` when that is not present. This value can be customized via a language context provided by a parent element that listens for the `sp-language-context` event and supplies update language settings to the `callback` function contained therein. Applications leveraging the [``](./components/theme) element to manage the visual delivery or text direction of their content will be also be provided a reactive context for supplying language information to its descendants. -### Decimals + +Decimals + The following example uses the `signDisplay` option to include the plus sign for positive numbers, for example to display an offset from some value. In addition, it always displays a minimum of 1 digit after the decimal point, and allows up to 2 fraction digits. If the user enters more than 2 fraction digits, the result will be rounded. @@ -96,7 +119,7 @@ The following example uses the `signDisplay` option to include the plus sign for Sales tax ``` -### Currency values + +Currency values + The `style: 'currency'` option can be passed to the `formatOptions` property to treat the value as a currency value. The `currency` option must also be passed to set the currency code (e.g. `USD`) to use. In addition, the `currencyDisplay` option can be used to choose whether to display the currency `symbol`, currency `code`, or currency `name`. Finally, the `currencySign` option can be set to `accounting` to use accounting notation for negative numbers, which uses parentheses rather than a minus sign in some locales. @@ -131,7 +158,7 @@ If you need to allow the user to change the currency, you should include a separ Transaction amount Package width ` element itself. If pluralization or translation is important to the delivered interface, please be sure to handle passing those strings into to element via the `formatOptions` property reactively to the value of the element or locale of that page in question. -## Minimum and maximum values + +Minimum and maximum values + The `max` and `max` properties can be used to limit the entered value to a specific range. The value will be clamped when the user commits the value to the `` element. In addition, the increment and decrement buttons will be disabled when the value is within one step value from the bounds. Ranges can be open ended by only providing a value for either `min` or `max` rather than both. @@ -194,7 +227,9 @@ If a valid range is known ahead of time, it is a good idea to provide it to ` ``` -## Step values + +Step values + The step prop can be used to snap the value to certain increments. If there is a `min` defined, the steps are calculated starting from that minimum value. For example, if `min === 2`, and `step === 3`, the valid step values would be 2, 5, 8, 11, etc. If no `min` is defined, the steps are calculated starting from zero and extending in both directions. In other words, such that the values are evenly divisible by the step. A step can be any positive decimal. If no step is defined, any decimal value may be typed, but incrementing and decrementing snaps the value to an integer. @@ -230,11 +265,99 @@ If the user types a value that is between two steps and blurs the input, the val > ``` -## Default value + + + +### States + +#### Invalid + +The `invalid` attribute indicates that the number field's value is invalid. When set, appropriate ARIA attributes will be automatically applied. + +```html + + It's one banana, Michael, how much could it cost? + + +``` + +#### Valid + +The `valid` attribute indicates that the number field's value is valid. + +```html + + It's one banana, Michael, how much could it cost? + + +``` + +#### Required + +The `required` attribute sets the number field to an indeterminate state, visually distinct from both checked and unchecked states. + +```html +Number of tickets + +``` + +#### Disabled + +The `disabled` attribute prevents the number field from receiving focus or events. The number field will appear faded. + +```html +Number of tickets + +``` + +#### Read-only + +number fieldes have a `readonly` attribute for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed. + +```html +Number of tickets + +``` + +### Behaviors + +#### Default value The `` component doesn't manage a default value by itself. This means that consumers can set the value of the number-field as an empty string by clearing the input. If we want the number-field to reset to a `default-value` when the user clears the input, we can listen for the `change` event on the number-field component and set its value to the desired `default-value` if the input is empty. -```html-live +```html Default value of this number field is 42 @@ -245,6 +368,7 @@ The `` component doesn't manage a default value by itself. This const numberField = document.querySelector('#default'); numberField.addEventListener('change', (event) => { + alert('change'); const target = event.target; if (isNaN(target.value)) { target.value = '42'; @@ -252,14 +376,37 @@ The `` component doesn't manage a default value by itself. This }); }); - ``` +### Accessibility + +#### Labels + +Every number field must have a label that clearly describes its purpose. The label can be provided either via the `label` attribute or with an associated `` element. + +#### Keyboard Navigation + +Number fields support the following keyboard interactions: + +- ArrowUp and ArrowDown keys increment and decrement the value +- Shift + ArrowUp or ArrowDown applies steps at 10 times (or the value of `step-modifier`) the normal rate +- The scroll wheel can be used to increment and decrement the value when focused + +#### Help Text + +Consider providing help text to explain: + +- The expected format of the input +- Any minimum or maximum values +- The meaning of units or special formatting (e.g., currency, percentages) +- Step increments if they differ from the default + - -## States - -Use the `required` attribute to indicate a number field value is required. Dictate the validity or invalidity state of the text entry with the `valid` or `invalid` attributes. - -```html -Count - -
-Size - -``` From aab44cc4ccd3ac54e45e8fec8bc877ead966ec41 Mon Sep 17 00:00:00 2001 From: Nikki Massaro <5090492+nikkimk@users.noreply.github.com> Date: Wed, 30 Apr 2025 15:45:50 -0400 Subject: [PATCH 7/9] docs(number-field): fixed example --- packages/number-field/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/number-field/README.md b/packages/number-field/README.md index cf19710f45a..f734fa88ce3 100644 --- a/packages/number-field/README.md +++ b/packages/number-field/README.md @@ -362,7 +362,7 @@ The `` component doesn't manage a default value by itself. This Default value of this number field is 42 - + ```