@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/visual.md

@@ -0,0 +1,249 @@
+# Visual
+
+Illustrates the top of an onboarding or feature modal.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Visual.tsx)
+
+Figma: [Content/Visual](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-2662)
+
+## Overview
+
+A visual is a 208px illustrated panel that sits above a centered modal title. `kind` selects the artwork, and `passkey` is the only kind today.
+
+## Examples
+
+### Basic
+
+Set `kind` to `passkey` (default). The panel fills its container, and the artwork stays 374px wide and centered.
+
+```tsx
+import { style, Visual } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Visual kind="passkey" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '24rem !custom', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Visual/Basic.tsx)
+
+### Chip
+
+Add `Visual.Chip` for a short instruction. It sits 24px from the top and 12px from the end.
+
+```tsx
+import { style, Visual } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Visual kind="passkey">
+        <Visual.Chip>Touch to sign in</Visual.Chip>
+      </Visual>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '24rem !custom', width: '100% !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Visual/Chip.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Visual } from '@tempoxyz/ds'
+
+<Visual>
+  <Visual.Chip />
+</Visual>
+```
+
+## Guidelines
+
+### When to Use
+
+* Open an onboarding or feature modal, such as adding a passkey, above a centered title.
+
+### When Not to Use
+
+* Use [IconTile](/docs/components/icon-tile) for acknowledgment, success, and destructive confirmation modals.
+* Use a [Dialog](/docs/components/dialog) without a visual for form and review modals.
+
+### Use One Visual Above the Title
+
+**Do:** Place one visual above a centered title.
+
+```tsx
+/**
+ * Do example for "Use One Visual Above the Title" on the Visual page.
+ * Place one visual above a centered title.
+ * @module
+ */
+import { style, Visual } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Visual kind="passkey" />
+      <span {...styles.title()}>Add a passkey</span>
+      <span {...styles.description()}>Sign in with your fingerprint or face.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const description = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+    maxWidth: '24rem !custom',
+    textAlign: 'center',
+    width: '100% !custom',
+  })
+
+  export const title = style({
+    color: 'content.primary',
+    marginBlockStart: '16',
+    typography: 'heading.h4',
+  })
+}
+```
+
+**Don't:** Stack a visual and an [IconTile](/docs/components/icon-tile).
+
+```tsx
+/**
+ * Don't example for "Use One Visual Above the Title" on the Visual page.
+ * Don't stack a visual and an icon chip.
+ * @module
+ */
+import { IconTile, style, Visual } from '@tempoxyz/ds'
+import { Passkey } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <IconTile>
+        <Passkey />
+      </IconTile>
+      <Visual kind="passkey" />
+      <span {...styles.title()}>Add a passkey</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '16',
+    maxWidth: '24rem !custom',
+    textAlign: 'center',
+    width: '100% !custom',
+  })
+
+  export const title = style({ color: 'content.primary', typography: 'heading.h4' })
+}
+```
+
+### Keep the Chip to a Few Words
+
+The chip stays on one line, so a long label runs past the panel edge.
+
+**Do:** Write one short instruction in the chip.
+
+```tsx
+/**
+ * Do example for "Keep the Chip to a Few Words" on the Visual page.
+ * Write one short instruction in the chip.
+ * @module
+ */
+import { style, Visual } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Visual kind="passkey">
+        <Visual.Chip>Touch to sign in</Visual.Chip>
+      </Visual>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '24rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Write a sentence in the chip.
+
+```tsx
+/**
+ * Don't example for "Keep the Chip to a Few Words" on the Visual page.
+ * Don't write a sentence in the chip.
+ * @module
+ */
+import { style, Visual } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Visual kind="passkey">
+        <Visual.Chip>Place your finger on the sensor to finish signing in</Visual.Chip>
+      </Visual>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ maxWidth: '24rem !custom', width: '100% !custom' })
+}
+```
+
+## Content
+
+* **Chip:** Write an instruction of two to four words in sentence case, such as Touch to sign in, with no end punctuation.
+
+## Accessibility
+
+A visual renders a `<div>` with no role and takes no focus. Screen readers skip the artwork and read the chip text in place.
+
+### Semantics
+
+* **Artwork (aria-hidden):** Decorative, so screen readers skip it.
+* **Visual.Chip (span):** Plain text, read in place. The dot is hidden.
+
+### Your Responsibilities
+
+* **Name the Feature in the Title:** The artwork has no text alternative, so the modal title names the feature.
+* **Label a Meaningful Visual (aria-label):** If the visual carries meaning alone, set `role="img"` and an `aria-label`.
+
+## Related
+
+[IconTile](/docs/components/icon-tile)
+
+Use for icons at the top of other centered modals.
+
+[Dialog](/docs/components/dialog)
+
+Use for the modal that holds the visual.

package/dist/docs/components.md

@@ -0,0 +1,203 @@
+# Overview
+
+Components for building Tempo products, grouped by the job each one does.
+
+## Principles
+
+* **Native First:** Components render native elements such as `<button>`, `<input>`, and `<table>`, and accept their attributes, refs, classes, and styles.
+* **Accessible Behavior:** Components that coordinate focus, keyboard, or popups build on Base UI primitives, which supply keyboard support and ARIA wiring.
+* **Composable Parts:** Larger components split into named parts, such as `Dialog.Root` and `Dialog.Title`, so you control the markup between them.
+* **Shared Tokens:** Every component reads Tempo variables for color, spacing, type, and motion. A variable scope on a wrapper restyles everything inside it.
+
+## Actions
+
+Controls that start an action or copy a value.
+
+- [Button](/docs/components/button): Triggers an action, such as submitting a form or sending a payment.
+- [ButtonGroup](/docs/components/button-group): Lays out the actions at the foot of a dialog or focused flow.
+- [CopyButton](/docs/components/copy-button): Copies a value to the clipboard and confirms the copy.
+- [SplitButton](/docs/components/split-button): Pairs a primary action with a menu of alternatives.
+
+## Forms and Inputs
+
+Controls that collect values, and the parts that label and group them. Wrap each control in a [Field](/docs/components/field) to link its label, description, and error.
+
+- [AmountInput](/docs/components/amount-input): Accepts a decimal amount, such as a payment or transfer value.
+- [Autocomplete](/docs/components/autocomplete): A text input that suggests values while people type.
+- [Calendar](/docs/components/calendar): A month grid for picking one date or a date range.
+- [Checkbox](/docs/components/checkbox): Turns a single independent option on or off.
+- [CheckboxGroup](/docs/components/checkbox-group): Shares one value array across a group of checkboxes.
+- [Choicebox](/docs/components/choicebox): A selectable tile with an optional icon, title, and description.
+- [ChoiceGroup](/docs/components/choice-group): A segmented control for a few mutually exclusive options.
+- [Combobox](/docs/components/combobox): A text input that filters a list of fixed options while people type.
+- [DatePicker](/docs/components/date-picker): Shows the selected date and opens a calendar in a popup.
+- [Field](/docs/components/field): Links a label, description, and error message to a control.
+- [Fieldset](/docs/components/fieldset): Groups related fields under a shared legend.
+- [NativeSelect](/docs/components/native-select): A native select styled as a field, which opens the browser's own picker.
+- [NumberField](/docs/components/number-field): A numeric input with increment and decrement buttons.
+- [OtpField](/docs/components/otp-field): Accepts a one-time passcode, one character per slot.
+- [RadioGroup](/docs/components/radio-group): Lets you pick a single option from a short list.
+- [Select](/docs/components/select): Opens a list of options for choosing one value.
+- [Slider](/docs/components/slider): Picks a single value or a range by dragging.
+- [Switch](/docs/components/switch): Toggles a setting that applies immediately.
+- [Textarea](/docs/components/textarea): A multi-line text field.
+- [TextInput](/docs/components/text-input): A text field with optional prefix, suffix, and clear button.
+
+## Feedback and Status
+
+Components that report progress, results, and system state.
+
+- [Alert](/docs/components/alert): Shows an inline message tied to nearby content.
+- [Banner](/docs/components/banner): Shows a full-width message about the system or page.
+- [Callout](/docs/components/callout): Sets a short passage of body text apart in a subtle box.
+- [Empty](/docs/components/empty): Fills a region that has nothing to show yet.
+- [Gauge](/docs/components/gauge): Shows a measurement within a range as a ring.
+- [LoadingDots](/docs/components/loading-dots): Shows three pulsing dots for inline loading.
+- [Progress](/docs/components/progress): Shows how far a task has advanced.
+- [Skeleton](/docs/components/skeleton): Holds the place of content while it loads.
+- [Spinner](/docs/components/spinner): Shows that something is loading.
+- [StatusChip](/docs/components/status-chip): Names the status of a payment, an authorization, or a network.
+- [StatusIndicator](/docs/components/status-indicator): Names the status of a system or a service with a dot and a label.
+- [StatusRow](/docs/components/status-row): Follows the status of one payment or task while it runs.
+- [Toast](/docs/components/toast): Shows a brief notification that dismisses itself.
+
+## Overlays
+
+Popups that open above the page from a trigger.
+
+- [AlertDialog](/docs/components/alert-dialog): Asks you to confirm a critical action before it happens.
+- [Dialog](/docs/components/dialog): Opens a modal popup over the page.
+- [Drawer](/docs/components/drawer): Slides a modal panel in from an edge of the viewport.
+- [Menu](/docs/components/menu): Opens a list of actions from a button.
+- [Popover](/docs/components/popover): Opens a non-modal popup anchored to a trigger.
+- [Tooltip](/docs/components/tooltip): Shows a short label for a control on hover or focus.
+
+## Navigation
+
+Components that move between pages, views, and steps.
+
+- [Breadcrumbs](/docs/components/breadcrumbs): Shows where the current page sits in the site hierarchy.
+- [Pagination](/docs/components/pagination): Moves between pages of a long list.
+- [SidebarMenu](/docs/components/sidebar-menu): Vertical navigation for sidebars and drawers.
+- [Stepper](/docs/components/stepper): Shows progress through a fixed sequence of steps.
+- [Tabs](/docs/components/tabs): Switches between related views.
+
+## Layout
+
+Primitives that size, space, and arrange content. They carry no meaning, so pair them with semantic elements where structure matters.
+
+- [AppShell](/docs/components/app-shell): Places a sticky sidebar beside the main content column.
+- [Container](/docs/components/container): Centers content at a maximum width.
+- [Frame](/docs/components/frame): Lays out a header, body, and footer in a column.
+- [Grid](/docs/components/grid): Lays out children on a responsive grid.
+- [Inline](/docs/components/inline): Lays out children in a horizontal row.
+- [Inset](/docs/components/inset): Pads content with spacing tokens.
+- [Separator](/docs/components/separator): Draws a rule between groups of content.
+- [Stack](/docs/components/stack): Lays out children in a vertical column.
+- [Surface](/docs/components/surface): A card container for grouping related content.
+
+## Data Display
+
+Components that present content and records.
+
+- [Accordion](/docs/components/accordion): Stacks collapsible sections that each reveal a labelled panel.
+- [AgentLogo](/docs/components/agent-logo): Shows the logo of an AI agent that works with a wallet.
+- [Avatar](/docs/components/avatar): Represents a person, contact, or wallet with an image, initials, or an icon.
+- [Badge](/docs/components/badge): Labels a status or category in a compact chip.
+- [BarChart](/docs/components/bar-chart): Shows values over time as stacked bars, such as the daily spend of each agent.
+- [Code](/docs/components/code): Sets a command, identifier, or value apart inside a sentence.
+- [GetStartedVisual](/docs/components/get-started-visual): Illustrates one step of a get started flow at the top of its card.
+- [HeroVisual](/docs/components/hero-visual): Shows animated streaks and a title beside the steps of a setup flow.
+- [IconTile](/docs/components/icon-tile): Anchors a centered modal with one icon in a rounded square.
+- [Kbd](/docs/components/kbd): Shows a keyboard key or shortcut.
+- [ListGroup](/docs/components/list-group): Stacks rows for details, pickers, checklists, and settings.
+- [Snippet](/docs/components/snippet): Shows a command or value with a copy button.
+- [SplitBar](/docs/components/split-bar): Splits one total between two parts, with a legend under the bar.
+- [SuccessHero](/docs/components/success-hero): Confirms that a setup flow finished, on a dark card of animated streaks.
+- [Table](/docs/components/table): Displays tabular data in rows and columns.
+- [TempoLogo](/docs/components/tempo-logo): Shows the Tempo brand logo.
+- [VerificationCode](/docs/components/verification-code): Shows a code that a person compares with the one another app shows.
+- [Visual](/docs/components/visual): Illustrates the top of an onboarding or feature modal.
+
+## Blockchain
+
+Components for onchain values such as addresses, amounts, and tokens.
+
+- [AddressCard](/docs/components/address-card): Shows a wallet address to receive funds, with its QR code and networks.
+- [Amount](/docs/components/amount): Formats a number as money or a token amount.
+- [AssetChip](/docs/components/asset-chip): Labels a supported asset or network in a small chip, which can also pick one.
+- [BadgedLogo](/docs/components/badged-logo): Marks a token or an app with a small badge on the corner of its logo.
+- [Hex](/docs/components/hex): Shows a hex string, such as an address, truncated to fit.
+- [Identicon](/docs/components/identicon): Shows a unique gradient avatar derived from an address.
+- [NetworkLogo](/docs/components/network-logo): Shows the logo of the network a token lives on.
+- [Qr](/docs/components/qr): Renders a value as a QR code.
+- [SecretValue](/docs/components/secret-value): Masks a secret and adds reveal and copy buttons.
+- [Token](/docs/components/token): Shows which token an amount is in, and opens a picker to change it.
+- [TokenLogo](/docs/components/token-logo): Shows a token logo by contract address or symbol.
+
+## Choosing a Component
+
+### Choosing One Option
+
+* **[RadioGroup](/docs/components/radio-group):** Two to five options, all visible at once.
+* **[ChoiceGroup](/docs/components/choice-group):** Two to four short options that switch a view or mode.
+* **[Choicebox](/docs/components/choicebox):** A few options that each need an icon or description.
+* **[Select](/docs/components/select):** Many options, or limited space.
+* **[Combobox](/docs/components/combobox):** A long list to filter by typing.
+* **[Autocomplete](/docs/components/autocomplete):** Free text with suggested values.
+
+### On and Off
+
+* **[Switch](/docs/components/switch):** A setting that applies the moment you flip it.
+* **[Checkbox](/docs/components/checkbox):** A choice that applies on form submit, or agreement to terms.
+
+### Messages
+
+* **[Banner](/docs/components/banner):** A message about the whole product or page, such as an outage.
+* **[Alert](/docs/components/alert):** A message about a specific section or field.
+* **[Toast](/docs/components/toast):** Confirms that an action finished.
+* **[AlertDialog](/docs/components/alert-dialog):** An action that needs a decision before it continues.
+
+### Loading
+
+* **[Skeleton](/docs/components/skeleton):** Content with a known shape.
+* **[Progress](/docs/components/progress):** A task with a measurable amount of work.
+* **[Spinner](/docs/components/spinner):** A region or control that is busy for an unknown time.
+* **[LoadingDots](/docs/components/loading-dots):** A short wait inside a line of text.
+
+### Popups
+
+* **[Dialog](/docs/components/dialog):** A focused task that blocks the page.
+* **[Drawer](/docs/components/drawer):** A long form or details panel that keeps page context visible.
+* **[Menu](/docs/components/menu):** A list of actions.
+* **[Popover](/docs/components/popover):** Interactive content anchored to a trigger, without a block on the page.
+* **[Tooltip](/docs/components/tooltip):** A label for an icon button.
+
+### Showing a Status
+
+* **[Table](/docs/components/table) cell `status`:** A status in a table row, as a colored word such as Failed.
+* **[StatusChip](/docs/components/status-chip):** The status of a payment, an authorization, or a network, at the end of a row or beside a title.
+* **[StatusIndicator](/docs/components/status-indicator):** The live state of a system, a service, or a connection, such as Degraded.
+* **[StatusRow](/docs/components/status-row):** One running task that a person follows until it finishes.
+* **[Badge](/docs/components/badge):** A category or an attribute, such as Testnet or Nightly.
+
+### Lists of Records
+
+* **[Table](/docs/components/table):** Many records with the same fields, such as payouts or team members, to compare by column.
+* **[ListGroup](/docs/components/list-group):** The fields of one record, a short list to pick from or open, or table rows below 640px.
+* **[Surface](/docs/components/surface) in a [Grid](/docs/components/grid):** A few similar items that each stand alone, such as metric tiles. Don't make a card per record.
+
+### Identifiers
+
+* **[Hex](/docs/components/hex):** An address or a hash in a row, a card, or a details view. It truncates in the middle to fit its container, down to the prefix and one character on each side, and overflows a narrower one.
+* **[Table](/docs/components/table) cell `mono`:** An address or a hash in a table column, shortened with `formatHex` to `0x4f2a…91c3`. Link the row to a details view with a Hex.
+* **[Snippet](/docs/components/snippet):** A URL, a command, or another value that isn't hex.
+* **[SecretValue](/docs/components/secret-value):** A private key or another secret, hidden until a reveal.
+
+Set `copy` on a Hex wherever people need the full value. [Building From Intent](/docs/foundations/intent) shows how to choose by the job of the content.
+
+### Copying Values
+
+* **[Snippet](/docs/components/snippet):** A command or value with its own copy button.
+* **[CopyButton](/docs/components/copy-button):** Copy beside content that you lay out yourself.
+* **[SecretValue](/docs/components/secret-value):** A value that stays hidden until a reveal.