@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/native-select.md

@@ -0,0 +1,204 @@
+# NativeSelect
+
+A native select styled as a field, which opens the browser's own picker.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/NativeSelect.tsx)
+
+Figma: [Native select](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3059-449)
+
+## Overview
+
+A native select is a 48px field with a chevron at its end. It renders a native `<select>`, so the browser draws the options in the platform picker, such as the wheel on a phone.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, NativeSelect, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Environment</Field.Label>
+      <NativeSelect defaultValue="">
+        <option disabled value="">
+          Select environment
+        </option>
+        <option value="production">Production</option>
+        <option value="staging">Staging</option>
+        <option value="development">Development</option>
+      </NativeSelect>
+      <Field.Description>Keys only work in the environment they belong to</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '20rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NativeSelect/Basic.tsx)
+
+### Invalid
+
+Set `invalid` on `Field.Root`, or on the select itself, to fill it red with a 1px red border. Explain the problem in a `Field.Error`.
+
+```tsx
+import { Field, NativeSelect, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Environment</Field.Label>
+      <NativeSelect defaultValue="">
+        <option disabled value="">
+          Select environment
+        </option>
+        <option value="production">Production</option>
+        <option value="staging">Staging</option>
+      </NativeSelect>
+      <Field.Error match>Select an environment for this key.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '20rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NativeSelect/Invalid.tsx)
+
+### Disabled
+
+Set `disabled` on `Field.Root` to disable the select and fade its chevron.
+
+```tsx
+import { Field, NativeSelect, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Field.Root disabled {...styles.field()}>
+      <Field.Label>Environment</Field.Label>
+      <NativeSelect defaultValue="production">
+        <option value="production">Production</option>
+        <option value="staging">Staging</option>
+      </NativeSelect>
+      <Field.Description>Keys keep the environment they were created in</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '20rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NativeSelect/Disabled.tsx)
+
+## Anatomy
+
+Import the component and nest native options in it.
+
+```tsx
+import { NativeSelect } from '@tempoxyz/ds'
+
+<NativeSelect>
+  <option />
+</NativeSelect>
+```
+
+## Guidelines
+
+### When to Use
+
+* Choose one value from a short list in a form, such as an environment, a network, or a country.
+* Use the platform picker on touch devices, where it fits the screen and the keyboard.
+
+### When Not to Use
+
+* Use [Select](/docs/components/select) when the options need icons, logos, or a styled popup.
+* Use [ChoiceGroup](/docs/components/choice-group) or [RadioGroup](/docs/components/radio-group) when a few options fit on screen.
+* Use [Combobox](/docs/components/combobox) when the list is long enough to need search.
+
+### Lead With a Placeholder Option
+
+Start with a disabled, empty `option` that names the choice, and set `defaultValue=""` so it shows until a value is picked. A disabled placeholder cannot be picked again.
+
+**Do:** Name the choice in the placeholder option.
+
+```tsx
+<Field.Root style={{ width: 240 }}>
+  <Field.Label>Environment</Field.Label>
+  <NativeSelect defaultValue="">
+    <option disabled value="">
+      Select environment
+    </option>
+    <option value="production">Production</option>
+  </NativeSelect>
+</Field.Root>
+```
+
+**Don't:** Start with an empty option that people can pick as a value.
+
+```tsx
+<Field.Root style={{ width: 240 }}>
+  <Field.Label>Environment</Field.Label>
+  <NativeSelect defaultValue="">
+    <option value="">--</option>
+    <option value="production">Production</option>
+  </NativeSelect>
+</Field.Root>
+```
+
+### Keep the Label Visible
+
+Give the select a `Field.Label`. The placeholder option disappears once a value is picked, so it cannot name the field.
+
+## Content
+
+* Name the choice in the placeholder, such as Select environment.
+* Write option labels in sentence case, and keep each to a few words.
+* Order options by frequency of use, or alphabetically when no order applies.
+
+## Accessibility
+
+`NativeSelect` renders a native `<select>` registered as the control of its `Field.Root`. The browser handles the keys and the picker.
+
+### Semantics
+
+* **Select (combobox):** A native select, announced with its label and its selected option.
+* **Invalid State (aria-invalid):** Marks the select invalid and fills it red. Explain the problem in an error.
+
+### Keyboard
+
+* **Move Focus In and Out (Tab):** Moves focus to the select, and out of it again, as for any field.
+* **Open the Picker (Space or Alt+Down Arrow):** Opens the platform picker. Other keys follow the native select.
+
+### Your Responsibilities
+
+* **Label the Select (Field.Label):** Give it a visible label in a field, or set `aria-label` when none fits.
+* **Explain Errors (Field.Error):** Say how to fix an invalid value in a `Field.Error`, not in red alone.
+
+## Related
+
+[Select](/docs/components/select)
+
+Use for options with icons or a styled popup.
+
+[Field](/docs/components/field)
+
+Use for labels, descriptions, and errors.
+
+[RadioGroup](/docs/components/radio-group)
+
+Use for a few options shown at once.
+
+[Forms](/docs/patterns/forms)
+
+Covers laying out fields and actions.

package/dist/docs/components/network-logo.md

@@ -0,0 +1,248 @@
+# NetworkLogo
+
+Shows the logo of the network a token lives on.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/NetworkLogo.tsx)
+
+## Overview
+
+A network logo renders a network's artwork as an inline SVG, cropped to a circle. The artwork keeps the network's brand colors in both color schemes.
+
+## Examples
+
+### Basic
+
+```tsx
+import { NetworkLogo, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <NetworkLogo network="tempo" />
+      Tempo
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NetworkLogo/Basic.tsx)
+
+### Network
+
+Set `network` to `base`, `ethereum`, `hyperevm`, `polygon`, `solana`, or `tempo`.
+
+```tsx
+import { NetworkLogo, style } from '@tempoxyz/ds'
+
+const networks = [
+  ['base', 'Base'],
+  ['ethereum', 'Ethereum'],
+  ['hyperevm', 'HyperEVM'],
+  ['polygon', 'Polygon'],
+  ['solana', 'Solana'],
+  ['tempo', 'Tempo'],
+] as const
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      {networks.map(([network, label]) => (
+        <div key={network} {...styles.row()}>
+          <NetworkLogo network={network} />
+          {label}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({ display: 'grid', gap: '12' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NetworkLogo/Network.tsx)
+
+### Size
+
+Set `size` to `medium` (20px, default) or `large` (32px).
+
+```tsx
+import { NetworkLogo, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <NetworkLogo network="ethereum" size="medium" />
+      <NetworkLogo network="ethereum" size="large" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NetworkLogo/Size.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { NetworkLogo } from '@tempoxyz/ds'
+
+<NetworkLogo />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show which network a token, an address, or a deposit belongs to, such as in a Receive flow or a network picker.
+
+### When Not to Use
+
+* Use [TokenLogo](/docs/components/token-logo) for the token itself.
+* Use [Identicon](/docs/components/identicon) for an account address.
+* Use [IconTile](/docs/components/icon-tile) for a feature or category icon.
+
+### Name the Network
+
+Many people don't know every network's logo.
+
+**Do:** Show the network name beside each logo.
+
+```tsx
+/**
+ * Do example for "Name the Network" on the NetworkLogo page.
+ * Show the network name beside each logo.
+ * @module
+ */
+import { NetworkLogo, style } from '@tempoxyz/ds'
+
+const networks = [
+  ['tempo', 'Tempo'],
+  ['base', 'Base'],
+  ['ethereum', 'Ethereum'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      {networks.map(([network, label]) => (
+        <div key={network} {...styles.row()}>
+          <NetworkLogo network={network} size="large" />
+          <span {...styles.name()}>{label}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '12' })
+
+  export const name = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+**Don't:** Ask people to tell networks apart by logo alone.
+
+```tsx
+/**
+ * Don't example for "Name the Network" on the NetworkLogo page.
+ * Logos alone ask people to recognize every network's brand.
+ * @module
+ */
+import { NetworkLogo, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <NetworkLogo network="tempo" size="large" />
+      <NetworkLogo network="base" size="large" />
+      <NetworkLogo network="ethereum" size="large" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Match Size to the Context
+
+* **Medium (20px):** Beside a network name in a value or chip.
+* **Large (32px):** In network rows and network pickers.
+
+### Keep the Brand Artwork
+
+**Do:** Use the logo as it renders, in its own colors.
+
+```tsx
+<NetworkLogo network="ethereum" size="large" />
+```
+
+**Don't:** Recolor the logo, or redraw it as a colored circle with a letter.
+
+```tsx
+<span
+  style={{
+    alignItems: 'center',
+    background: '#627eea',
+    borderRadius: 999,
+    color: 'white',
+    display: 'inline-flex',
+    font: '600 14px Inter',
+    height: 32,
+    justifyContent: 'center',
+    width: 32,
+  }}
+>
+  E
+</span>
+```
+
+## Accessibility
+
+A network logo renders an `<svg>` that is hidden from screen readers by default. It is not interactive and takes no focus.
+
+### Semantics
+
+* **Root (aria-hidden):** Hidden from screen readers, so the visible name beside it is read once.
+* **Named Logo (aria-label):** An `aria-label` gives the logo the `img` role, so screen readers announce it.
+
+### Your Responsibilities
+
+* **Name a Standalone Logo (aria-label):** If no visible text names the network, pass the network name as `aria-label`.
+
+## Related
+
+[TokenLogo](/docs/components/token-logo)
+
+Use for token logos.
+
+[AssetChip](/docs/components/asset-chip)
+
+Use for listing the assets a network supports.
+
+[ListGroup](/docs/components/list-group)
+
+Use for network lists.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers tokens, networks, and addresses.