@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/text-input.md

@@ -0,0 +1,624 @@
+# TextInput
+
+A text field with optional prefix, suffix, and clear button.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/TextInput.tsx)
+
+Figma: [Inputs/Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3846) (`TextInput.Group`), [Inputs/Search Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-2265) (`TextInput.Group`), [Inputs/Text Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1285) (`TextInput.Group`), [Search](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3365) (`TextInput.Group`), [Text Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3316) (`TextInput.Group`)
+
+## Overview
+
+An input is a filled text field composed from a group, an optional prefix and suffix, a control, and a clear button.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>To</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control autoComplete="email" placeholder="Address, email or contact" />
+      </TextInput.Group>
+      <Field.Description>Paste an address or pick a contact</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Basic.tsx)
+
+### Icons
+
+Put an icon that gives the field its meaning, such as `Search` or `Mail`, in `TextInput.Prefix`. Put an icon for an action on the field, such as paste, in `TextInput.Suffix`.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+import { Clipboard, Search } from '@tempoxyz/ds/icons'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Recipient</Field.Label>
+      <TextInput.Group>
+        <TextInput.Prefix>
+          <Search />
+        </TextInput.Prefix>
+        <TextInput.Control defaultValue="maya@studio.co" />
+        <TextInput.Suffix>
+          <Clipboard />
+        </TextInput.Suffix>
+      </TextInput.Group>
+      <Field.Description>Paste an address or pick a contact</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Icons.tsx)
+
+### Search
+
+Add a `Search` icon in `TextInput.Prefix` and a `TextInput.Clear`. The clear button shows once the field has a value, and Escape empties the field before it closes an enclosing [Dialog](/docs/components/dialog).
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <TextInput.Group>
+        <TextInput.Prefix>
+          <Search />
+        </TextInput.Prefix>
+        <TextInput.Control
+          aria-label="Search contacts"
+          defaultValue="Maya"
+          placeholder="Name, email or address"
+          type="search"
+        />
+        <TextInput.Clear />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Search.tsx)
+
+### Variant
+
+Set `variant` on `TextInput.Group` to `default` (default) or `outlined`, which draws a 1px line instead of the fill.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      {(['default', 'outlined'] as const).map((variant) => (
+        <Field.Root key={variant}>
+          <Field.Label>To</Field.Label>
+          <TextInput.Group variant={variant}>
+            <TextInput.Control placeholder="Address, email or contact" />
+          </TextInput.Group>
+          <Field.Description>Paste an address or pick a contact</Field.Description>
+        </Field.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Variant.tsx)
+
+### Size
+
+Set `size` on `TextInput.Group` to `medium` (default) or `large`, a 52px search bar with 20px icons and larger corners.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      {(['medium', 'large'] as const).map((size) => (
+        <Field.Root key={size}>
+          <TextInput.Group size={size}>
+            <TextInput.Prefix>
+              <Search />
+            </TextInput.Prefix>
+            <TextInput.Control
+              aria-label="Search tokens"
+              placeholder="Search tokens"
+              type="search"
+            />
+            <TextInput.Clear />
+          </TextInput.Group>
+        </Field.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Size.tsx)
+
+### Appearance
+
+Set `appearance` on `TextInput.Group` to `base` (default) or `overlay`, which draws a translucent fill and white text over an image or video.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.backdrop()}>
+      <Field.Root {...styles.field()}>
+        <TextInput.Group appearance="overlay" size="large">
+          <TextInput.Prefix>
+            <Search />
+          </TextInput.Prefix>
+          <TextInput.Control aria-label="Search places" placeholder="Search places" type="search" />
+          <TextInput.Clear />
+        </TextInput.Group>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  // A dark gradient stands in for the image or video under an overlay field.
+  export const backdrop = style({
+    backgroundImage: 'linear-gradient(135deg, #3d3d3d, #141414) !custom',
+    borderRadius: 'sm',
+    padding: '32',
+  })
+
+  export const field = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Appearance.tsx)
+
+### Invalid
+
+Set `invalid` or `success` on `TextInput.Group`, or inherit either from `Field.Root`. A state set after mount plays a one-shot nudge or pop.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Send />
+      <Field.Root
+        validate={(value) => (String(value).includes('@') ? null : 'Enter a valid email.')}
+        validationMode="onChange"
+      >
+        <Field.Label>Email</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="alice@example.com" type="email" />
+        </TextInput.Group>
+        <Field.Description>Remove the @ to swap in the error.</Field.Description>
+        <Field.Error />
+      </Field.Root>
+      <Field.Root invalid>
+        <Field.Label>Email</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="alice" type="email" />
+        </TextInput.Group>
+        <Field.Description>Used for receipts.</Field.Description>
+        <Field.Error match>Enter a valid email.</Field.Error>
+      </Field.Root>
+    </div>
+  )
+}
+
+function Send() {
+  const [amount, setAmount] = useState('')
+  const invalid = Number(amount) > 1240.5
+
+  return (
+    <Field.Root invalid={invalid} success={amount !== '' && !invalid}>
+      <Field.Label>You send</Field.Label>
+      <TextInput.Group>
+        <TextInput.Prefix>$</TextInput.Prefix>
+        <TextInput.Control inputMode="decimal" onValueChange={setAmount} placeholder="0.00" />
+        <TextInput.Suffix>USDC</TextInput.Suffix>
+      </TextInput.Group>
+      <Field.Description>Balance 1,240.50 USDC</Field.Description>
+      <Field.Error match={invalid}>Exceeds your balance.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Invalid.tsx)
+
+### Disabled
+
+Disable a field only when the app sets the value, and say why in the `Field.Description`.
+
+```tsx
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root disabled {...styles.field()}>
+      <Field.Label>Network</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="Tempo" />
+      </TextInput.Group>
+      <Field.Description>Set by the app you are paying</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { TextInput } from '@tempoxyz/ds'
+
+<TextInput.Group>
+  <TextInput.Prefix />
+  <TextInput.Control />
+  <TextInput.Suffix />
+  <TextInput.Clear />
+</TextInput.Group>
+```
+
+## Guidelines
+
+### When to Use
+
+* Collect one line of text, such as an email or a 0x address.
+* Search a list or table, with a `Search` icon in `TextInput.Prefix` and a `TextInput.Clear`.
+
+### When Not to Use
+
+* Use [AmountInput](/docs/components/amount-input) for token and fiat amounts. It rejects non-decimals and adds a Max action.
+* Use [NumberField](/docs/components/number-field) for quantities that step up and down.
+* Use [Textarea](/docs/components/textarea) for text over one line.
+* Use [OtpField](/docs/components/otp-field) for one-time passcodes.
+* Use [Select](/docs/components/select) or [Combobox](/docs/components/combobox) if the value must come from a list, and [Autocomplete](/docs/components/autocomplete) if a list only suggests values.
+
+### Always Show a Label
+
+A placeholder disappears on the first keystroke. Use it only for a format example, such as `0x…`. Leave out the visible label only when the dialog title already names the field, such as a search field, and set `aria-label`.
+
+**Do:** Name the field in a `Field.Label` and keep the placeholder as a format hint.
+
+```tsx
+/**
+ * Do example for "Always Show a Label" on the TextInput page.
+ * Name the field in a `Field.Label` and keep the placeholder as a format hint.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Recipient address</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control placeholder="0x…" />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Use the placeholder as the only label.
+
+```tsx
+/**
+ * Don't example for "Always Show a Label" on the TextInput page.
+ * Don't use the placeholder as the only label.
+ * @module
+ */
+import { style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <TextInput.Group {...styles.field()}>
+      <TextInput.Control aria-label="Recipient address" placeholder="Recipient address" />
+    </TextInput.Group>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+### Size the Field to Its Value
+
+`TextInput.Group` fills its container. If the value is short, narrow it with `style` or `className`.
+
+**Do:** Give a short value a short field, and a long value the full column.
+
+```tsx
+/**
+ * Do example for "Size the Field to Its Value" on the TextInput page.
+ * Give a short value a short field, and a long value the full column.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.form()}>
+      <Field.Root>
+        <Field.Label>TokenLogo symbol</Field.Label>
+        <TextInput.Group {...styles.short()}>
+          <TextInput.Control defaultValue="USDC" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Webhook URL</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="https://api.example.com/hooks" type="url" />
+        </TextInput.Group>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const form = style({
+    display: 'grid',
+    gap: '16',
+    maxWidth: '18rem !custom',
+    width: '100% !custom',
+  })
+
+  export const short = style({ width: '7rem !custom' })
+}
+```
+
+**Don't:** Stretch a four-character symbol across the column or squeeze a URL into a small box.
+
+```tsx
+/**
+ * Don't example for "Size the Field to Its Value" on the TextInput page.
+ * Don't stretch a four-character symbol across the column or squeeze a URL into a small box.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.form()}>
+      <Field.Root>
+        <Field.Label>TokenLogo symbol</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="USDC" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Webhook URL</Field.Label>
+        <TextInput.Group {...styles.short()}>
+          <TextInput.Control defaultValue="https://api.example.com/hooks" type="url" />
+        </TextInput.Group>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const form = style({
+    display: 'grid',
+    gap: '16',
+    maxWidth: '18rem !custom',
+    width: '100% !custom',
+  })
+
+  export const short = style({ width: '7rem !custom' })
+}
+```
+
+### Use Prefixes and Suffixes for Fixed Context
+
+Put a currency symbol, protocol, or search icon in `TextInput.Prefix`, and a unit such as `USDC` in `TextInput.Suffix`.
+
+**Do:** Show the unit in `TextInput.Suffix` so people type only the number.
+
+```tsx
+/**
+ * Do example for "Use Prefixes and Suffixes for Fixed Context" on the TextInput page.
+ * Show the unit in `TextInput.Suffix` so people type only the number.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Slippage tolerance</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="0.5" inputMode="decimal" />
+        <TextInput.Suffix>%</TextInput.Suffix>
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '9rem !custom' })
+}
+```
+
+**Don't:** Make people type the unit into the value.
+
+```tsx
+/**
+ * Don't example for "Use Prefixes and Suffixes for Fixed Context" on the TextInput page.
+ * Don't make people type the unit into the value.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Slippage tolerance</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="0.5%" />
+      </TextInput.Group>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '9rem !custom' })
+}
+```
+
+* **Content:** Keep prefixes and suffixes to a symbol, icon, or one short word. Put other buttons beside the group, not in a suffix.
+* **Icons:** Use a leading icon for meaning, such as `Search`, and a trailing icon for an action on the field, such as paste or scan.
+* **Clear:** `TextInput.Clear` appears only inside a `Field.Root` once the control has a value. Add it to search fields and filters, not to one-time forms.
+
+### Help Browsers and Keyboards Fill the Field
+
+Set `type`, `inputMode`, and `autoComplete` on `TextInput.Control` to select the on-screen keyboard and enable saved values.
+
+* **Email (email):** Set `type="email"` and `autoComplete="email"`.
+* **Name (name):** Set `autoComplete="name"`.
+* **URL or Webhook (url):** Set `type="url"` and `autoComplete="url"`.
+* **Search (search):** Set `type="search"`.
+* **0x Address (off):** Turn off autofill, capitalizing, and spellcheck.
+* **Numeric Code (numeric):** Set `inputMode="numeric"` and turn off autofill.
+
+Avoid `type="number"` for amounts and identifiers. It drops leading zeros, accepts `e`, and some browsers change the value on scroll.
+
+For labels, descriptions, errors, and validation timing, see [Field](/docs/components/field).
+
+## Accessibility
+
+An input renders a native `<input>` inside a styled group. Inside a `Field.Root`, it links to the label, description, and error. See [Accessibility](/docs/foundations/accessibility) for the baseline.
+
+### Semantics
+
+* **TextInput.Control (textbox):** A native input whose role follows its type.
+* **TextInput.Group (div):** Has no role of its own.
+* **Invalid and Success (aria-invalid):** `invalid` sets `aria-invalid`. `success` sets no ARIA state.
+* **TextInput.Prefix and TextInput.Suffix:** Plain text, such as "$" or "USDC". Not part of the input's name.
+* **TextInput.Clear (button):** Labelled "Clear". Its hit area extends past its circle.
+
+### Keyboard
+
+* **Move to the TextInput (Tab):** Moves focus to the input, then to the clear button when shown.
+* **Clear the TextInput (Enter or Space):** On the clear button, empties the input and returns focus to it.
+* **Clear Before Closing (Escape):** With a clear button, Escape empties a filled input first.
+
+All other keys follow the native input.
+
+### Size and Motion
+
+* **Target Size (48px):** Every field is 48px tall, above the 24px WCAG 2.2 minimum.
+* **Reduced Motion (reduce):** Under reduced motion, the nudge and pop don't play.
+
+### Your Responsibilities
+
+* **Label Every TextInput (Field.Label):** Use a visible label, or an `aria-label` when none fits. A prefix icon doesn't name it.
+* **Name the Unit:** If the unit matters, put it in the label or description, such as "Amount in USDC".
+* **Declare the Purpose (autoComplete):** Set it with `type` and `inputMode` to declare the field's purpose. WCAG requires it for personal data.
+* **Explain Invalid Values (Field.Error):** Don't rely on the red fill alone. Explain an invalid value in text, such as "Enter an amount above 0".
+
+## Related
+
+[Field](/docs/components/field)
+
+Use for labels, descriptions, and errors.
+
+[AmountInput](/docs/components/amount-input)
+
+Use for token and fiat amounts.
+
+[Textarea](/docs/components/textarea)
+
+Use for multi-line text.
+
+[Combobox](/docs/components/combobox)
+
+Use for picking from a long list by typing.
+
+[Forms](/docs/patterns/forms)
+
+Covers laying out fields and actions.
+
+[Errors and Validation](/docs/patterns/errors-and-validation)
+
+Covers when and where to show errors.