@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/amount.md

@@ -0,0 +1,794 @@
+# Amount
+
+Formats a number as money or a token amount.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Amount.tsx)
+
+## Overview
+
+Formats a number in `en-US` with tabular figures, as money or followed by a token symbol.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Amount } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Amount symbol="PathUSD" value="1250.50" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Basic.tsx)
+
+### Size
+
+Set `size` to `sm` (default), `md`, `lg`, or `xl`.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+        <Amount key={size} size={size} symbol="PathUSD" value={1250.5} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Size.tsx)
+
+### Currency
+
+Set `currency` to an ISO 4217 code for money, or `symbol` to follow the number with a token symbol. Pass one, not both.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount currency="USD" size="lg" value={1234.5} />
+      <Amount currency="EUR" value={1234.5} />
+      <Amount size="lg" symbol="PathUSD" value={1234.5} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Currency.tsx)
+
+### Align
+
+Set `align` to `left` (default), `center`, or `right`.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      {(['left', 'center', 'right'] as const).map((align) => (
+        <Amount align={align} currency="USD" key={align} size="md" value={1234.5} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Align.tsx)
+
+### Sign
+
+Set `sign` to `+`, `-`, or `−` to prefix the amount.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount align="center" sign="+" size="md" symbol="PathUSD" value="1250.50" />
+      <Amount align="right" currency="USD" sign="−" size="md" value={1234.5} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Sign.tsx)
+
+### Strikethrough
+
+Set `strikethrough` to mark a superseded amount.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount size="md" strikethrough symbol="PathUSD" value={1250.5} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Strikethrough.tsx)
+
+### Precise
+
+Set `precise` to show two significant digits for a currency value below the smallest shown unit.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount currency="USD" value={0.0004} />
+      <Amount currency="USD" precise value={0.0004} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Precise.tsx)
+
+### Max Decimals
+
+Set `maxDecimals` to cap the fraction digits shown.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount symbol="PathUSD" value="1.23456" />
+      <Amount maxDecimals={2} symbol="PathUSD" value="1.23456" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/MaxDecimals.tsx)
+
+### Locale
+
+Set `locale` to a BCP 47 tag, such as `de-DE`, to change grouping, decimal marks, and currency symbols. It defaults to `en-US`, so server and browser render the same text.
+
+```tsx
+import { Amount, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount currency="USD" value="1250.50" />
+      <Amount currency="USD" locale="de-DE" value="1250.50" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Locale.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Amount } from '@tempoxyz/ds'
+
+<Amount />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show balances, payment amounts, fees, and converted values, such as 1,250.50 USDC or $1,250.50.
+* Show amounts in tables, rows, and review screens with consistent formatting.
+
+### When Not to Use
+
+* Use [AmountInput](/docs/components/amount-input) when people enter an amount.
+* Use `Table.Cell` with `numeric` in a [Table](/docs/components/table) for counts and metrics without a unit, such as TPS or block height.
+
+### Always Show the Unit
+
+**Do:** Pass `symbol` for a token amount and `currency` for money.
+
+```tsx
+/**
+ * Do example for "Always Show the Unit" on the Amount page.
+ * Pass `symbol` for a token amount and `currency` for money.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount size="md" symbol="USDC" value="1250.50" />
+      <Amount currency="USD" value="1250.50" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '4' })
+}
+```
+
+**Don't:** Show an amount without its token or currency.
+
+```tsx
+/**
+ * Don't example for "Always Show the Unit" on the Amount page.
+ * Don't show an amount without its token or currency.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Amount size="md" value="1250.50" />
+      <Amount value="1250.50" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '4' })
+}
+```
+
+### Choose Currency or Symbol
+
+* **Currency:** Money and converted values, such as a portfolio total.
+* **Symbol:** Token amounts, such as what an account holds or sends.
+
+Show a stablecoin balance in its token, such as PathUSD, even if it tracks the dollar. If you have a rate, add a converted value with `currency` as a second line.
+
+### Pass Exact Decimal Strings
+
+Pass `value` as a decimal string, such as a token balance converted from base units. Without `currency`, a string keeps its own fraction digits, including trailing zeros.
+
+**Do:** Pass decimal strings, such as `"0.30"`.
+
+```tsx
+/**
+ * Do example for "Pass Exact Decimal Strings" on the Amount page.
+ * Pass decimal strings, such as `"0.30"`.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Available balance</span>
+        <Amount align="right" symbol="USDC" value="1250.10" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Total fees</span>
+        <Amount align="right" symbol="USDC" value="0.30" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+**Don't:** Pass numbers. They drop trailing zeros and show floating-point errors.
+
+```tsx
+/**
+ * Don't example for "Pass Exact Decimal Strings" on the Amount page.
+ * Don't pass numbers. They drop trailing zeros and show floating-point errors.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Available balance</span>
+        <Amount align="right" symbol="USDC" value={1250.1} />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Total fees</span>
+        <Amount align="right" symbol="USDC" value={0.1 + 0.2} />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+### Set Decimals by Purpose
+
+* **With `currency`:** Shows the currency's own digits, two for USD. `maxDecimals={0}` renders `$5`.
+* **Without `currency`:** Shows every digit of the string. Set `maxDecimals` in lists, and show the exact value in details and review screens.
+* **Rounding:** `0.999` with `maxDecimals={2}` renders `1.00`. Show the exact balance wherever people choose how much to send.
+
+**Do:** Use one decimal count down a column so decimal points line up.
+
+```tsx
+/**
+ * Do example for "Set Decimals by Purpose" on the Amount page.
+ * Use one decimal count down a column so decimal points line up.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Main wallet</span>
+        <Amount align="right" symbol="USDC" value="1250.50" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Savings</span>
+        <Amount align="right" symbol="USDC" value="84.10" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Payroll</span>
+        <Amount align="right" symbol="USDC" value="312.00" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+**Don't:** Mix decimal counts in one column.
+
+```tsx
+/**
+ * Don't example for "Set Decimals by Purpose" on the Amount page.
+ * Don't mix decimal counts in one column.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Main wallet</span>
+        <Amount align="right" symbol="USDC" value="1250.504812" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Savings</span>
+        <Amount align="right" symbol="USDC" value="84.1" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Payroll</span>
+        <Amount align="right" symbol="USDC" value="312.0005" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+### Show Values Below a Cent Precisely
+
+A currency value below its smallest unit renders as a bound, such as `<$0.01`.
+
+**Do:** Set `precise` on network fees to show two significant digits.
+
+```tsx
+/**
+ * Do example for "Show Values Below a Cent Precisely" on the Amount page.
+ * Set `precise` on network fees to show two significant digits.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>You send</span>
+        <Amount align="right" symbol="USDC" value="250.00" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Network fee</span>
+        <Amount align="right" currency="USD" precise value="0.0004" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+**Don't:** Show a fee people pay as a bound.
+
+```tsx
+/**
+ * Don't example for "Show Values Below a Cent Precisely" on the Amount page.
+ * Don't show a fee people pay as a bound.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>You send</span>
+        <Amount align="right" symbol="USDC" value="250.00" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Network fee</span>
+        <Amount align="right" currency="USD" value="0.0004" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+### Show Direction With a Sign
+
+Set `sign="+"` for money in and `sign="−"` for money out. Pass `value` without its own minus, or the amount shows two signs. Prefer the minus sign `−` to the hyphen `-`.
+
+**Do:** Mark incoming and outgoing amounts with `+` and `−`.
+
+```tsx
+/**
+ * Do example for "Show Direction With a Sign" on the Amount page.
+ * Mark incoming and outgoing amounts with `+` and `−`.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Received from Jane</span>
+        <Amount align="right" sign="+" symbol="USDC" value="120.00" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Sent to 0x91bd…07e1</span>
+        <Amount align="right" sign="−" symbol="USDC" value="48.50" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+**Don't:** Show direction with green and red alone.
+
+```tsx
+/**
+ * Don't example for "Show Direction With a Sign" on the Amount page.
+ * Don't show direction with green and red alone.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Received from Jane</span>
+        <span {...styles.credit()}>120.00 USDC</span>
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Sent to 0x91bd…07e1</span>
+        <span {...styles.debit()}>48.50 USDC</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const credit = style({
+    color: 'content.positive',
+    fontVariantNumeric: 'tabular-nums !custom',
+    typography: 'body.b2Strong',
+  })
+
+  export const debit = style({
+    color: 'content.negative',
+    fontVariantNumeric: 'tabular-nums !custom',
+    typography: 'body.b2Strong',
+  })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+  })
+}
+```
+
+### Mark Superseded Amounts in Words
+
+Use `strikethrough` for an amount that no longer applies, such as an expired fee quote, and show the new amount beside it.
+
+**Do:** Say it in text, such as Was $0.02.
+
+```tsx
+/**
+ * Do example for "Mark Superseded Amounts in Words" on the Amount page.
+ * Say it in text, such as Was $0.02.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Network fee</span>
+      <div {...styles.values()}>
+        <span {...styles.label()}>Was</span>
+        <Amount currency="USD" strikethrough value="0.02" />
+        <Amount currency="USD" value="0.01" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+
+  export const values = style({ alignItems: 'baseline', display: 'flex', gap: '8' })
+}
+```
+
+**Don't:** Rely on the line. Screen readers don't announce it.
+
+```tsx
+/**
+ * Don't example for "Mark Superseded Amounts in Words" on the Amount page.
+ * Don't rely on the line. Screen readers don't announce it.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.label()}>Network fee</span>
+      <div {...styles.values()}>
+        <Amount currency="USD" strikethrough value="0.02" />
+        <Amount currency="USD" value="0.01" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '16',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+
+  export const values = style({ alignItems: 'baseline', display: 'flex', gap: '8' })
+}
+```
+
+### Size by Importance
+
+* **Small (sm):** The default, for lists, tables, and rows.
+* **Medium (md):** Card values and review totals.
+* **Large (lg):** A balance at the top of a page.
+* **Extra Large (xl):** The single balance on a home screen.
+
+Amount renders as a block and ignores the alignment of a table cell. Set `align="right"` in an end-aligned column.
+
+## Content
+
+* Label each amount by its role, such as You send, Network fee, or Available balance.
+* Don't repeat the unit in text, such as USD after $1,250.50.
+* Don't abbreviate amounts people act on, such as 1.2K.
+
+## Accessibility
+
+Renders a `<span>` with no role. Screen readers read the formatted text as written. How they read symbols, such as `$`, `−`, or the `<` in `<$0.01`, depends on the screen reader and its settings.
+
+### Semantics
+
+* **Root (span):** Plain text. Screen readers read the number with its sign and unit.
+* **Locale (locale):** Formats in `en-US`. Set `locale` to the page language for other separators.
+* **Strikethrough (strikethrough):** Visual only. Say in text that an amount is superseded.
+
+### Your Responsibilities
+
+* **Mark Inexact Amounts:** Say in text if an amount is a bound or estimate, such as "Less than $0.01".
+* **Announce Live Updates (aria-live):** Amount does not announce updates. Put awaited ones, such as a quote, in a live region.
+* **Label Direction in Words:** Keep the sign, and label direction in words, such as "Received" and "Sent".
+
+## Related
+
+[AmountInput](/docs/components/amount-input)
+
+Use for entering amounts.
+
+[TokenLogo](/docs/components/token-logo)
+
+Use for the token icon beside an amount.
+
+[Table](/docs/components/table)
+
+Use for laying out amounts.
+
+[ListGroup](/docs/components/list-group)
+
+Use for laying out amounts.
+
+[Payments](/docs/patterns/payments)
+
+Covers send and review screens.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers token amounts and fees.