ionbase-ui 0.51.0 → 0.69.0

package/dist/meta/NumberInput.json

@@ -0,0 +1,407 @@
+{
+  "name": "NumberInput",
+  "source": "src/components/NumberInput.tsx",
+  "propsType": "NumberInputProps",
+  "description": "NumberInput — a quantity, with formatting, bounds and steps.\n\nNOT `<input type=\"number\">`, and the list of reasons is the component:\n\n  It scrolls. A focused `type=\"number\"` changes value under the mouse wheel,\n  so a user scrolling the page past a price field edits the price. The wheel\n  is OFF here by default (`isWheelDisabled`), and a caller has to ask for it.\n\n  It cannot format. \"1,234.50\", \"€12\", \"15%\" are text to the browser's number\n  input, which rejects them. `formatOptions` takes `Intl.NumberFormatOptions`,\n  so currency, percent and units display and parse in the user's locale —\n  including \"1.234,50\" for a German user.\n\n  It is not a number to the browser's validation either. `type=\"text\"` with\n  the right `inputMode` gets the numeric keyboard on a phone without\n  Firefox letting letters in and Chrome silently reporting an empty value.\n\nEMPTY IS `null`, NOT `NaN`. React Aria reports an empty field as `NaN`, and\n`NaN === NaN` is false — so every \"is it empty\" check a caller writes is\nwrong. This converts at the boundary, both ways.\n\n− AND + SIT SIDE BY SIDE, NOT STACKED. Stacked chevrons split the field's\nheight in two, which puts a Small field's targets at 16px — under the 24px\nWCAG 2.5.8 asks. Side by side, every size clears it. They are out of the tab\norder, as React Aria sets them: the arrow keys do the same job from the field,\nand two extra tab stops per number on a form is a tax on every keyboard user.\n\nThe box is Input's, class for class, so every state — hover, focus, invalid,\nread-only, disabled — is Input's and cannot drift from it.",
+  "import": "import { NumberInput } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A quantity field: formats and parses in the user's locale, clamps to bounds, steps with − and + or the arrow keys, and never changes under the scroll wheel unless asked.",
+  "useWhen": [
+    "the value is a quantity someone might add to or compare — a price, a count, a percentage, a duration",
+    "the value has bounds or a step the field should enforce",
+    "the value needs formatting — currency, percent, units — in the user's locale"
+  ],
+  "useInstead": [
+    {
+      "when": "the value is made of digits but is not a quantity — a phone number, postcode, card number, account or order ID",
+      "use": "Input",
+      "why": "a number field strips leading zeros, adds grouping separators and offers + and −, all of which corrupt an identifier. Nobody increments a postcode"
+    },
+    {
+      "when": "the value is a phone number",
+      "use": "PhoneInput"
+    },
+    {
+      "when": "a rough value within a range matters more than an exact one — volume, a zoom level",
+      "use": "Input",
+      "why": "there is no Slider yet; do not stand one in with a stepper that takes forty presses"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms and table cells"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a form where this value is the main input"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` or `aria-label` — the accessible name. A unit shown by `formatOptions` is not a name"
+    ],
+    "guarantees": [
+      "Arrow Up and Down step the value from the field; Page Up and Down step by ten; Home and End go to the bounds",
+      "the − and + buttons are named and out of the tab order, because the arrow keys already do their job from the field",
+      "every size's step buttons are at least 24px square — WCAG 2.5.8",
+      "the field is `type=\"text\"` with the matching `inputMode`, so phones show a numeric keyboard without the native number input's parsing quirks"
+    ],
+    "notes": [
+      "the scroll wheel does not change the value unless `isWheelDisabled={false}` — a focused number input edited by scrolling past it is the classic bug",
+      "`onChange` fires on commit — blur, Enter, a step — not per keystroke. `null` means empty; `NaN` never reaches the caller"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<NumberInput label=\"Postcode\" />",
+      "do": "<Input label=\"Postcode\" inputMode=\"numeric\" />",
+      "why": "\"02134\" becomes 2,134 — leading zero gone, separator added, and a + button nobody should press"
+    },
+    {
+      "dont": "<Input type=\"number\" />",
+      "do": "<NumberInput />",
+      "why": "the native number input changes under the scroll wheel, cannot show currency or grouping, and reports an empty string for input it cannot parse"
+    },
+    {
+      "dont": "a unit typed into the label and the value — label=\"Price ($)\" with a \"$\" typed in",
+      "do": "formatOptions={{ style: 'currency', currency: 'USD' }}",
+      "why": "formatOptions displays and parses the unit in the user's locale; a hand-typed symbol is text the parser has to reject"
+    },
+    {
+      "dont": "checking `Number.isNaN(value)` for empty",
+      "do": "`value === null`",
+      "why": "this component converts the hook's NaN to null at the boundary, so NaN never arrives"
+    }
+  ],
+  "stylesheet": "src/styles/number-input.css",
+  "tokens": [
+    "--icon-default",
+    "--icon-disabled",
+    "--icon-secondary",
+    "--ion-input-height",
+    "--ion-input-icon-size",
+    "--radius-sm",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-pressed"
+  ],
+  "props": {
+    "value": {
+      "type": "number | null | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled value. `null` is empty — never `NaN`, which is what the\nunderlying hook uses and which fails every `===` check a caller writes."
+    },
+    "defaultValue": {
+      "type": "number | null | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled starting value. `null` for empty."
+    },
+    "onChange": {
+      "type": "((value: number | null) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Fires when the value is committed — on blur, Enter, a step button or an\narrow key — not on every keystroke. `null` when the field was cleared."
+    },
+    "size": {
+      "type": "NumberInputSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches Input's `size`: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "showStepper": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The − and + buttons. On by default; turn off for a dense table cell where\nthe arrow keys are enough.",
+      "default": true
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the control box (`.ion-input`)."
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the `.ion-field` wrapper when a label or helper is shown."
+    },
+    "autoFocus": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the element should receive focus on render."
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+    },
+    "aria-describedby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that describes the object."
+    },
+    "aria-details": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+    },
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Defines a string value that labels the current element."
+    },
+    "aria-labelledby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that labels the current element."
+    },
+    "onCopy": {
+      "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the user copies text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy)."
+    },
+    "onCut": {
+      "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the user cuts text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut)."
+    },
+    "onPaste": {
+      "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the user pastes text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste)."
+    },
+    "onCompositionEnd": {
+      "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a text composition system completes or cancels the current text\ncomposition session. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event)."
+    },
+    "onCompositionStart": {
+      "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a text composition system starts a new text composition session.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event)."
+    },
+    "onCompositionUpdate": {
+      "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a new character is received in the current text composition\nsession. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event)."
+    },
+    "onFocus": {
+      "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element receives focus."
+    },
+    "onBlur": {
+      "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element loses focus."
+    },
+    "onBeforeInput": {
+      "type": "FormEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the input value is about to be modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event)."
+    },
+    "onInput": {
+      "type": "FormEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the input value is modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)."
+    },
+    "onKeyDown": {
+      "type": "((e: KeyboardEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a key is pressed."
+    },
+    "onKeyUp": {
+      "type": "((e: KeyboardEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a key is released."
+    },
+    "onSelect": {
+      "type": "ReactEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
+    },
+    "step": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The amount that the input value changes with each increment or decrement \"tick\"."
+    },
+    "placeholder": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Temporary text that occupies the text input when it is empty."
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the input is disabled."
+    },
+    "isReadOnly": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the input can be selected but not changed by the user."
+    },
+    "isRequired": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether user input is required on the input before form submission."
+    },
+    "isInvalid": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the input value is invalid."
+    },
+    "validationState": {
+      "type": "ValidationState | undefined",
+      "required": false,
+      "origin": "aria",
+      "values": [
+        "valid",
+        "invalid"
+      ],
+      "tags": {
+        "deprecated": "Use `isInvalid` instead."
+      }
+    },
+    "validationBehavior": {
+      "type": "\"aria\" | \"native\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to use native HTML form validation to prevent form submission\nwhen the value is missing or invalid, or mark the field as required\nor invalid via ARIA.",
+      "values": [
+        "aria",
+        "native"
+      ],
+      "tags": {
+        "default": "'aria'"
+      }
+    },
+    "validate": {
+      "type": "((value: number) => ValidationError | true | null | undefined) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A function that returns an error message if a given value is invalid.\nValidation errors are displayed to the user when the form is submitted\nif `validationBehavior=\"native\"`. For realtime validation, use the `isInvalid`\nprop instead."
+    },
+    "description": {
+      "type": "ReactNode",
+      "required": false,
+      "origin": "aria",
+      "description": "A description for the field. Provides a hint such as specific requirements for what to choose."
+    },
+    "errorMessage": {
+      "type": "ReactNode | ((v: ValidationResult) => ReactNode)",
+      "required": false,
+      "origin": "aria",
+      "description": "An error message for the field."
+    },
+    "onFocusChange": {
+      "type": "((isFocused: boolean) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element's focus status changes."
+    },
+    "label": {
+      "type": "ReactNode",
+      "required": false,
+      "origin": "aria",
+      "description": "The content to display as the label."
+    },
+    "decrementAriaLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A custom aria-label for the decrement button. If not provided, the localized string \"Decrement\"\nis used."
+    },
+    "incrementAriaLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A custom aria-label for the increment button. If not provided, the localized string \"Increment\"\nis used."
+    },
+    "isWheelDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Enables or disables changing the value with scroll.",
+      "default": true
+    },
+    "formatOptions": {
+      "type": "Intl.NumberFormatOptions | undefined",
+      "required": false,
+      "origin": "other",
+      "description": "Formatting options for the value displayed in the number field.\nThis also affects what characters are allowed to be typed by the user."
+    },
+    "commitBehavior": {
+      "type": "\"validate\" | \"snap\" | undefined",
+      "required": false,
+      "origin": "other",
+      "description": "Controls the behavior of the number field when the user blurs the field after editing. 'snap'\nwill clamp the value to the min/max values, and snap to the nearest step value. 'validate' will\nnot clamp the value, and will validate that the value is within the min/max range and on a\nvalid step.",
+      "values": [
+        "validate",
+        "snap"
+      ],
+      "tags": {
+        "default": "'snap'"
+      }
+    },
+    "minValue": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The smallest value allowed for the input."
+    },
+    "maxValue": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The largest value allowed for the input."
+    }
+  },
+  "propCounts": {
+    "own": 7,
+    "aria": 37,
+    "dom": 278,
+    "other": 2
+  }
+}

package/dist/meta/PhoneInput.json

@@ -122,41 +122,11 @@
       "origin": "own",
       "description": "Spread onto the dial-code `<button>`. This is how a country picker gets\nattached — see the note on scope below."
     },
-    "type": {
-      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
-      "tags": {
-        "default": "'text'"
-      },
-      "default": "tel"
-    },
-    "disabled": {
-      "type": "boolean | undefined",
-      "required": false,
-      "origin": "own",
-      "tags": {
-        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-      }
-    },
-    "form": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
-    },
-    "name": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
-    },
-    "value": {
-      "type": "string | undefined",
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
       "required": false,
       "origin": "aria",
-      "description": "The current value (controlled)."
+      "description": "Handler that is called when the value changes."
     },
     "defaultValue": {
       "type": "string | undefined",
@@ -347,12 +317,6 @@
       "origin": "aria",
       "description": "Handler that is called when the element loses focus."
     },
-    "onChange": {
-      "type": "((value: string) => void) | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "Handler that is called when the value changes."
-    },
     "onBeforeInput": {
       "type": "FormEventHandler<HTMLInputElement> | undefined",
       "required": false,
@@ -383,6 +347,42 @@
       "origin": "aria",
       "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
     },
+    "type": {
+      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+      "tags": {
+        "default": "'text'"
+      },
+      "default": "tel"
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "form": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The current value (controlled)."
+    },
     "size": {
       "type": "InputSize | undefined",
       "required": false,

package/dist/meta/Popover.json

@@ -157,10 +157,10 @@
       "origin": "own",
       "description": "Matches the Figma `Placement` variant, and names where the POPOVER sits —\nnot where the arrow points. A preference, not a guarantee: it flips when\nthere is no room, and the arrow follows.",
       "values": [
-        "right",
-        "left",
         "top",
-        "bottom"
+        "bottom",
+        "right",
+        "left"
       ]
     },
     "size": {