@jobber/components 8.26.1 → 8.26.2

package/dist/docs/InputNumberExperimental/InputNumberExperimental.md

@@ -3,26 +3,53 @@
 ## Summary
 
 `InputNumberExperimental` collects a single numeric value in a form. Reach for
-it when the value benefits from being nudged up or down — quantities, prices,
-durations, or counts.
+it when the value benefits from being nudged up or down, such as quantities,
+prices, durations, or counts.
 
-Most fields need only the prop-driven usage below. For the rare layout the props
-can't express, the same field can be composed from parts — see the **Implement**
+Most fields only need the props shown below. For rare layouts the props can't
+handle, you can build the same field from smaller pieces. See the **Implement**
 tab.
 
 ### When to use
 
-* The value is a number the user increments or decrements (quantity, price,
-  days, repetitions).
-* A stepper, min/max bounds, or number formatting would help the user.
+* The value is a number the user increments or decrements, like a quantity,
+  price, day count, or number of repetitions
+* A stepper, min/max bounds, or number formatting would help the user
 
 ### When not to use
 
-* The value is a sequence of digits that is never calculated with — phone
+* The value is a sequence of digits that is never calculated with, such as phone
   numbers, credit-card numbers, or postal codes. A stepper adds no value there;
   use [InputText](../InputText/InputText.md) instead.
 
-## Basic usage
+## Anatomy
+
+`InputNumberExperimental` typically includes:
+
+* Label (required): names the value the field collects
+* Value field (required): the number the user types or steps through
+* Stepper (optional): increment and decrement controls that change the value by
+  `step`
+* Prefix or suffix (optional): a unit or symbol shown alongside the value, like
+  $ or kg
+* Loading indicator (optional): replaces the stepper while background work runs
+
+## Behavior
+
+* The field is controlled through `value`, where a number sets the value and
+  `null` leaves it empty.
+* `onValueCommitted` fires when the user commits a value: on blur, on Enter, or
+  when they use the stepper or arrow keys. Use `onValueChange` for per-keystroke
+  updates.
+* The stepper buttons and the Up and Down arrow keys change the value by `step`
+  (default 1).
+* `min` and `max` bound the value, and the stepper stops at each limit.
+* `loading` hides the stepper and shows an indicator in its place. The field
+  stays editable, so use `readOnly` or `disabled` to lock it.
+
+## Options
+
+### Basic
 
 Pass `label`, a controlled `value`, and `onValueCommitted`. Bounds (`min` /
 `max`) and `step` are optional.
@@ -50,11 +77,9 @@ export function InputNumberExperimentalBasicExample(
 }
 ```
 
-## Options
-
 ### Prefixes and suffixes
 
-Use `prefix` / `suffix` to add a unit or symbol. A suffix can be a label, an
+Use `prefix` or `suffix` to add a unit or symbol. A suffix can be a label, an
 icon, or a clickable icon that runs an action (give it an `ariaLabel`).
 
 ```tsx
@@ -101,7 +126,7 @@ export function InputNumberExperimentalAffixesExample() {
 
 ### Sizes
 
-Three sizes are available. `default` fits almost every form; use `small` only in
+3 sizes are available. `default` fits almost every form; use `small` only in
 tight spaces and `large` only in especially spacious layouts.
 
 ```tsx
@@ -189,8 +214,8 @@ export function InputNumberExperimentalFormattingExample() {
 ### Loading
 
 `loading` shows a non-blocking indicator in the stepper's slot for background
-work (for example, saving). The field stays editable and the stepper is hidden
-while loading.
+work, like saving. The field stays editable and the stepper is hidden while
+loading.
 
 ```tsx
 import React, { useState } from "react";
@@ -222,25 +247,59 @@ Put the unit in the label or an affix, not both.
 | Label "Weight", suffix "kg"     | Label "Weight (kg)", suffix "kg"        |
 | Label "Duration", suffix "days" | Label "Duration in days", suffix "days" |
 
-### Keep labels short and sentence-cased
+### Keep labels short and sentence case
 
 | ✅ Do     | ❌ Don't                 |
 | -------- | ----------------------- |
 | Quantity | Enter the quantity here |
 | Discount | DISCOUNT %              |
 
+### Put the symbol where it's read
+
+Use a prefix for a leading symbol and a suffix for a trailing unit, matching how
+the value is spoken.
+
+| ✅ Do                 | ❌ Don't              |
+| -------------------- | -------------------- |
+| Prefix "$", value 40 | Suffix "$", value 40 |
+| Suffix "%", value 15 | Prefix "%", value 15 |
+
+### Keep validation errors helpful
+
+When a value breaks `min` or `max`, provide helpful guidance on what values will
+be accepted as opposed to just providing a generic error.
+
+| ✅ Do                           | ❌ Don't       |
+| ------------------------------ | ------------- |
+| Enter a value between 1 and 99 | Invalid input |
+| Quantity can't be more than 50 | Error         |
+
+### Use numbers as opposed to spelling them
+
+Use numerals in labels, helper text, affixes, and bounds.
+
+| ✅ Do        | ❌ Don't         |
+| ----------- | --------------- |
+| Max 3 items | Max three items |
+
 ## Do's and Don'ts
 
+#### Do:
+
 * ✅ Use for values the user increments or decrements
-* ✅ Set `min` / `max` when the value has real bounds
+* ✅ Set `min` and `max` when the value has real bounds
 * ✅ Use `format` for currency, percent, and decimals rather than formatting the
   value yourself
-* ❌ Don't use it for digit sequences that are never calculated with (phone,
-  credit card)
-* ❌ Don't disable the field to communicate an error — show an `error` message
-  instead
+* ✅ Use `loading` for background work so the field stays usable
+
+#### Don't:
+
+* ❌ Use it for digit sequences that are never calculated with, like phone or
+  credit card numbers
+* ❌ Disable the field to communicate an error; show an `error` message instead
+* ❌ Repeat the unit in both the label and an affix
 
-## Accessibility
+## Accessibility notes
 
 The field is a native number input, so it is reachable and operable by keyboard
 and assistive technology.
@@ -252,13 +311,13 @@ and assistive technology.
 | Enter            | Commits the current value       |
 | Type             | Replaces the value              |
 
-Give a clickable affix a clear `ariaLabel` describing its action (for example,
-"Clear value").
+Give a clickable affix a clear `ariaLabel` describing its action, like "Clear
+value".
 
 ## Related components
 
-* For digit sequences that are not calculated with (phone, credit card), use
-  [InputText](../InputText/InputText.md).
+* For digit sequences that are not calculated with, like phone or credit card
+  numbers, use [InputText](../InputText/InputText.md).
 * For dates, use [InputDate](../InputDate/InputDate.md).
 
 

package/dist/styles.css

@@ -4176,6 +4176,11 @@ a._7BLGtYNuJOU-.zgRx3ehZ2z8-:hover {
   line-height: 0;
 }
 
+.yL7--3ni8BM- p {
+  margin-top: 1px;
+  margin-top: var(--space-minuscule);
+}
+
 .qWsLxPjCBI8- {
   display: inline-block;
   margin-bottom: 4px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/components",
-  "version": "8.26.1",
+  "version": "8.26.2",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.cjs",
@@ -540,5 +540,5 @@
     "> 1%",
     "IE 10"
   ],
-  "gitHead": "f743b743aa382bf927e6f6959e99e0e8d25048dc"
+  "gitHead": "7d6fff8d16519d467ff260b676141d4e15d865ee"
 }