ionbase-ui 0.13.1 → 0.17.0

package/dist/meta/Input.json

@@ -0,0 +1,558 @@
+{
+  "name": "Input",
+  "source": "src/components/Input.tsx",
+  "propsType": "InputProps",
+  "description": "Input covers both Figma components on the Input page: the field itself\n(`Input`, 80:275) and the label/helper stack around it (`Form Field`,\n80:330). They are separate there because a Figma component cannot make a\nslot optional without a boolean; here the wrapper simply isn't rendered when\nthere is nothing to put in it.\n\n`useTextField` owns the wiring that is tedious and easy to get subtly wrong:\nit generates the ids, points `aria-labelledby` at the label and\n`aria-describedby` at whichever of the helper or error message is actually\nshowing, and sets `aria-invalid`. Hand-rolling that is where form fields\nusually lose their accessibility.\n\nFigma's seven states map to three props and three CSS states. Hover and Focus\nare interaction; Filled is the placeholder distinction, which CSS already\nexpresses; Default, Invalid, Disabled and Read-only are props.",
+  "import": "import { Input } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A single-line text field, together with its label, helper text and error message.",
+  "useWhen": [
+    "collecting one line of free text",
+    "the field needs a label, helper text, or validation messaging"
+  ],
+  "useInstead": [
+    {
+      "when": "the user picks from a fixed set of options",
+      "use": "Select"
+    },
+    {
+      "when": "it is a phone number",
+      "use": "PhoneInput",
+      "why": "country code and formatting are handled for you"
+    },
+    {
+      "when": "it is a single boolean",
+      "use": "Checkbox or Toggle"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms, table filters, toolbars"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms — search, sign-in"
+      }
+    }
+  },
+  "slots": {
+    "leadingIcon": {
+      "accepts": "Icon",
+      "note": "decorative; omit Icon's `label`"
+    },
+    "trailingIcon": {
+      "accepts": "Icon",
+      "note": "decorative unless it is interactive, in which case it needs its own button and name"
+    },
+    "leadingAddon": {
+      "note": "a static prefix such as a protocol or currency; not focusable"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "ids are generated and wired — the label points at the input via aria-labelledby",
+      "aria-describedby points at whichever of the helper text or error message is actually showing",
+      "aria-invalid is set from isInvalid"
+    ],
+    "requires": [
+      "`label`, or `aria-label` when the field is visually self-evident and no label is rendered"
+    ],
+    "notes": [
+      "The label/helper/error wrapper is only rendered when there is something to put in it — Figma models it as a separate `Form Field` component, this does not."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "using `placeholder` as the label",
+      "do": "pass `label`",
+      "why": "the placeholder disappears on focus, so the user loses the field's name exactly when typing"
+    },
+    {
+      "dont": "rendering your own <label htmlFor>",
+      "do": "pass `label`",
+      "why": "the component generates the id; an external htmlFor will not match it"
+    },
+    {
+      "dont": "showing an error by putting the message in `description`",
+      "do": "set `isInvalid` and pass `errorMessage`",
+      "why": "only errorMessage drives aria-invalid and the described-by wiring"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
+  "stylesheet": "src/styles/input.css",
+  "tokens": [
+    "--border-default",
+    "--border-disabled",
+    "--border-error-strong",
+    "--border-focus",
+    "--border-strong",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-regular",
+    "--icon-disabled",
+    "--icon-interactive",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--icon-tertiary",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-input-border-width",
+    "--ion-input-font-size",
+    "--ion-input-gap",
+    "--ion-input-height",
+    "--ion-input-icon-size",
+    "--ion-input-line-height",
+    "--ion-input-padding-x",
+    "--ion-input-radius",
+    "--radius-md",
+    "--radius-sm",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-32",
+    "--spacing-40",
+    "--spacing-48",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--surface-page",
+    "--text-disabled",
+    "--text-error",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "size": {
+      "type": "InputSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "autoCapitalize": {
+      "type": "\"none\" | \"off\" | \"on\" | \"sentences\" | \"words\" | \"characters\" | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Narrower than React's own typing, which also allows any `string`.\n`autoCapitalize` is declared on `AriaTextFieldOptions` rather than\n`AriaTextFieldProps`, so `keyof AriaTextFieldProps` above cannot omit it —\nand the wide DOM version does not satisfy what `useTextField` accepts.",
+      "values": [
+        "none",
+        "off",
+        "on",
+        "sentences",
+        "words",
+        "characters"
+      ]
+    },
+    "leadingIcon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Leading icon. Figma's `Show Leading Icon` + `Leading Icon` swap."
+    },
+    "trailingIcon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Trailing icon. Figma's `Show Trailing Icon` + `Trailing Icon` swap."
+    },
+    "leadingAddon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "A segment butted against the left of the control, sharing its outline —\nFigma's `Input/Phone` (80:372) country-code block.\n\nDistinct from `leadingIcon`, which sits *inside* the box: an addon has its\nown surface and border and is a sibling of the control, so the two cannot\nbe the same slot. It lives here rather than in `PhoneInput` because the\n`.ion-field` wrapper has to enclose the addon and the control together —\nbuilding it outside would put the label above only half the control and\nbreak the `aria-labelledby` wiring `useTextField` sets up.\n\nPhone is the only addon Figma specifies. This is a slot, not a system:\nresist growing a trailing counterpart or an addon variant ladder until a\ndesign actually calls for one."
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the control box (`.ion-input`). Always lands here —\nnever on the form-field wrapper. Use `wrapperClassName` for that."
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the `.ion-field` wrapper when a label or helper is shown."
+    },
+    "aria-activedescendant": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the currently active element when DOM focus is on a composite widget, textbox,\ngroup, or application."
+    },
+    "aria-autocomplete": {
+      "type": "\"inline\" | \"list\" | \"none\" | \"both\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates whether inputting text could trigger display of one or more predictions of the user's\nintended value for an input and specifies how predictions would be presented if they are made.",
+      "values": [
+        "inline",
+        "list",
+        "none",
+        "both"
+      ]
+    },
+    "aria-haspopup": {
+      "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+    },
+    "aria-controls": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+    },
+    "enterKeyHint": {
+      "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
+      "values": [
+        "enter",
+        "done",
+        "go",
+        "next",
+        "previous",
+        "search",
+        "send"
+      ]
+    },
+    "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: string) => 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."
+    },
+    "autoFocus": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the element should receive focus on render."
+    },
+    "onFocus": {
+      "type": "((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element receives focus."
+    },
+    "onBlur": {
+      "type": "((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element loses focus."
+    },
+    "onFocusChange": {
+      "type": "((isFocused: boolean) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element's focus status changes."
+    },
+    "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."
+    },
+    "placeholder": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Temporary text that occupies the text input when it is empty."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The current value (controlled)."
+    },
+    "defaultValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The default value (uncontrolled)."
+    },
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the value changes."
+    },
+    "label": {
+      "type": "ReactNode",
+      "required": false,
+      "origin": "aria",
+      "description": "The content to display as the label."
+    },
+    "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."
+    },
+    "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."
+    },
+    "excludeFromTabOrder": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+    },
+    "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)."
+    },
+    "autoComplete": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
+    },
+    "maxLength": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The maximum number of characters supported by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength)."
+    },
+    "minLength": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
+    },
+    "pattern": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Regex pattern that the value of the input must match to be valid. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern)."
+    },
+    "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'"
+      }
+    },
+    "inputMode": {
+      "type": "\"none\" | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"numeric\" | \"decimal\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Hints at the type of data that might be entered by the user while editing the element or its\ncontents. See\n[MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute).",
+      "values": [
+        "none",
+        "search",
+        "text",
+        "url",
+        "tel",
+        "email",
+        "numeric",
+        "decimal"
+      ]
+    },
+    "autoCorrect": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An attribute that takes as its value a space-separated string that describes what, if any, type\nof autocomplete functionality the input should provide. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete)."
+    },
+    "spellCheck": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An enumerated attribute that defines whether the element may be checked for spelling errors.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "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)."
+    },
+    "aria-errormessage": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element that provides an error message for the object."
+    }
+  },
+  "propCounts": {
+    "own": 8,
+    "aria": 51,
+    "dom": 265,
+    "other": 0
+  }
+}