@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/amount-input.md

@@ -0,0 +1,305 @@
+# AmountInput
+
+Accepts a decimal amount, such as a payment or transfer value.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AmountInput.tsx)
+
+Figma: [Inputs/Amount Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1389) (`AmountInput.Root`)
+
+## Overview
+
+An amount input is a filled card with the label, the amount in heading-size digits, a token chip, and the balance. It keeps the value as a raw string and rejects input that is not a non-negative decimal.
+
+## Examples
+
+### Basic
+
+Place the `Field.Label`, a [Token](token.md), and a `Field.Description` inside `AmountInput.Root`. They take their own rows above and below the amount.
+
+```tsx
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <AmountInput.Root>
+        <Field.Label>You send</Field.Label>
+        <AmountInput.Control placeholder="0.00" />
+        <Token address="0x20c0000000000000000000000000000000000000" symbol="pathUSD" />
+        <Field.Description>Balance 2,480.32</Field.Description>
+      </AmountInput.Root>
+    </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/AmountInput/Basic.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { AmountInput, Token } from '@tempoxyz/ds'
+
+<AmountInput.Root>
+  <AmountInput.Control />
+</AmountInput.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Enter a money or token amount, such as for Send, Convert, or Add funds.
+* Put it first in a dialog body, above the recipient field.
+
+### When Not to Use
+
+* Use [NumberField](number-field.md) for whole quantities adjusted in steps, such as webhook retries.
+* Use [TextInput](text-input.md) for identifiers with digits, such as a 0x address or a bank account number.
+* Use [OtpField](otp-field.md) for one-time verification codes.
+* Use [Amount](amount.md) to show a read-only value, such as a balance or a network fee.
+
+### Name the Token Beside the Digits
+
+Put a [Token](token.md) after `AmountInput.Control`. Give it `readOnly` when the token is fixed, and pass it to a picker trigger's `render` when the token can change.
+
+**Do:** Name the token beside the amount with a [Token](token.md).
+
+```tsx
+/**
+ * Do example for "Name the Token Beside the Digits" on the AmountInput page.
+ * Name the token beside the amount with a `Token`.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <AmountInput.Root defaultValue="120.50">
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control placeholder="0.00" />
+        <Token readOnly symbol="PathUSD" />
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Leave the token to the page around the card.
+
+```tsx
+/**
+ * Don't example for "Name the Token Beside the Digits" on the AmountInput page.
+ * Don't leave the token to the page around the card.
+ * @module
+ */
+import { AmountInput, Field, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <AmountInput.Root defaultValue="120.50">
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control placeholder="0.00" />
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+### Show the Available Balance
+
+Put the spendable balance in a `Field.Description` inside the card, such as Balance: 250.00 USDC, with the decimals and token code used elsewhere in the product.
+
+**Do:** Show the spendable balance in the card, below the amount.
+
+```tsx
+/**
+ * Do example for "Show the Available Balance" on the AmountInput page.
+ * Show the spendable balance in the card, below the amount.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <AmountInput.Root>
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control placeholder="0.00" />
+        <Token readOnly symbol="USDC" />
+        <Field.Description>Balance: 250.00 USDC</Field.Description>
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Leave the balance to another part of the page.
+
+```tsx
+/**
+ * Don't example for "Show the Available Balance" on the AmountInput page.
+ * Don't leave the balance to another part of the page.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <AmountInput.Root>
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control placeholder="0.00" />
+        <Token readOnly symbol="USDC" />
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+### Explain Invalid Amounts in Text
+
+The root allows any number of fraction digits. Check the value against the token's decimals, such as 6 for USDC, and against the balance. Set `invalid` on the `Field.Root` and add a `Field.Error` that names the limit.
+
+* **Separator:** A period or a lone comma separates decimals, so `1,5` is `1.5` and `0,250` is `0.250`. A lone comma groups thousands when one to three digits without a leading zero precede it and three follow it, as in `1,250`. Several commas group thousands. With both separators, the last one separates decimals, so `1.250,50` is `1250.50`.
+* **Value:** Keep the raw string from `onValueChange`. Convert it with exact decimal math, not floating-point numbers.
+
+**Do:** Name the limit in a `Field.Error`, such as the token's decimals.
+
+```tsx
+/**
+ * Do example for "Explain Invalid Amounts in Text" on the AmountInput page.
+ * Name the limit in a `Field.Error`, such as the token's decimals.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <AmountInput.Root defaultValue="12.5000001" invalid>
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control />
+        <Token readOnly symbol="USDC" />
+        <Field.Error match>Enter an amount with up to 6 decimal places.</Field.Error>
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Rely on the red fill alone.
+
+```tsx
+/**
+ * Don't example for "Explain Invalid Amounts in Text" on the AmountInput page.
+ * Don't rely on the red fill alone.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <AmountInput.Root defaultValue="12.5000001" invalid>
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control />
+        <Token readOnly symbol="USDC" />
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+### Stack Two Cards for a Conversion
+
+For a conversion, place a From card and a To card one above the other, with a small arrow [Button](button.md) between them that swaps the two.
+
+## Content
+
+* **Label:** Use You send and You receive on a send or convert screen, and Amount in other forms.
+* **Balance:** Write Balance and the amount, such as Balance 2,480.32.
+
+## Accessibility
+
+`AmountInput` renders a native text input for decimal amounts inside the card.
+
+### Semantics
+
+* **AmountInput.Control (textbox):** A text input with a decimal keypad. Name it with `Field.Label`, or `aria-label` if no label fits.
+* **Animated Digits (aria-hidden):** Decorative. Screen readers read the value from the input, not from the morphing digits.
+* **Invalid (aria-invalid):** Set `invalid` on the root, or on the `Field.Root`, to fill the card red and mark the input.
+* **Reduced Motion (prefers-reduced-motion):** The digits stop morphing and change at once. The nudge on an invalid amount doesn't play.
+
+### Keyboard
+
+* **Move to the TextInput (Tab):** Moves focus to the input, then to the token chip when it is a button.
+* **Ignore Other Keys (Letters):** Keystrokes that don't form a non-negative decimal leave the value unchanged.
+
+The ignored keystrokes have no announcement. State the accepted format, such as the decimal limit, in the description.
+
+### Your Responsibilities
+
+* **Label the Field (Field.Label):** Give the field a visible label, and name the token in the chip or the description.
+* **Explain Invalid Amounts (Field.Error):** Say what is allowed, such as "Enter up to 250.00 USDC", not only with the red fill.
+
+## Related
+
+[Amount](amount.md)
+
+Use for displaying amounts.
+
+[Field](field.md)
+
+Use for the label, balance, and error.
+
+[NumberField](number-field.md)
+
+Use for stepped quantities.
+
+[Token](token.md)
+
+Use for the token pill beside the amount.
+
+[Payments](../patterns/payments.md)
+
+Covers send, review, and confirmation flows.