@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/inline.md

@@ -0,0 +1,233 @@
+# Inline
+
+Lays out children in a horizontal row.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Inline.tsx)
+
+## Overview
+
+Inline applies a spacing token `gap` between its children and centers them vertically by default.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Inline, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inline gap="8">
+      <span {...styles.chip()}>Public</span>
+      <span {...styles.chip()}>Private</span>
+    </Inline>
+  )
+}
+
+namespace styles {
+  export const chip = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Inline/Basic.tsx)
+
+### Justify
+
+Set `justify` to `start` (default), `center`, `end`, or `between`.
+
+```tsx
+import { Inline, Stack, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Stack gap="16">
+      {(['start', 'center', 'end', 'between'] as const).map((justify) => (
+        <Inline justify={justify} key={justify}>
+          <span>{justify}</span>
+          <Inline gap="8">
+            <span {...styles.chip()}>Public</span>
+            <span {...styles.chip()}>Private</span>
+          </Inline>
+        </Inline>
+      ))}
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const chip = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Inline/Justify.tsx)
+
+### Wrap
+
+Set `wrap` to reflow items onto new lines instead of overflowing.
+
+```tsx
+import { Inline, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inline gap="8" wrap>
+      {['Stablecoins', 'Payments', 'Payroll', 'Remittance', 'Treasury', 'Settlement'].map(
+        (label) => (
+          <span key={label} {...styles.chip()}>
+            {label}
+          </span>
+        ),
+      )}
+    </Inline>
+  )
+}
+
+namespace styles {
+  export const chip = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Inline/Wrap.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Inline } from '@tempoxyz/ds'
+
+<Inline />
+```
+
+## Guidelines
+
+### When to Use
+
+* Place related items in a row, such as buttons, badges, or an icon beside its label.
+* Put a label and its value on one line, such as Network fee and 0.01 USDC.
+
+### When Not to Use
+
+* Use [Stack](/docs/components/stack) for a vertical column.
+* Use [Grid](/docs/components/grid) to align items in rows and columns.
+* Use `Frame.Actions` of [Frame](/docs/components/frame) for the actions at the bottom of a card or dialog.
+
+### Set Wrap When Content Varies
+
+If a row can outgrow a 320px screen, such as badges, filters, or button groups, set `wrap`.
+
+**Do:** Set `wrap` so badges reflow onto a new line.
+
+```tsx
+/**
+ * Do example for "Set Wrap When Content Varies" on the Inline page.
+ * Set `wrap` so badges reflow onto a new line.
+ * @module
+ */
+import { Badge, Inline } from '@tempoxyz/ds'
+
+const labels = ['Payments', 'Payouts', 'Webhooks', 'Fee payer', 'Treasury', 'Settlement']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Inline gap="8" wrap>
+      {labels.map((label) => (
+        <Badge key={label}>{label}</Badge>
+      ))}
+    </Inline>
+  )
+}
+```
+
+**Don't:** Let a row of badges run past its container.
+
+```tsx
+/**
+ * Don't example for "Set Wrap When Content Varies" on the Inline page.
+ * Don't let a row of badges run past its container.
+ * @module
+ */
+import { Badge, Inline, style } from '@tempoxyz/ds'
+
+const labels = ['Payments', 'Payouts', 'Webhooks', 'Fee payer', 'Treasury', 'Settlement']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.frame()}>
+      <Inline gap="8">
+        {labels.map((label) => (
+          <Badge key={label}>{label}</Badge>
+        ))}
+      </Inline>
+    </div>
+  )
+}
+
+namespace styles {
+  export const frame = style({ width: '100% !custom' })
+}
+```
+
+### Align by Content
+
+* **Center (align="center"):** The default, for icons, buttons, and badges.
+* **Baseline (align="baseline"):** For text in different sizes, such as an amount and its symbol.
+* **Between (justify="between"):** Pushes a value or action to the far end of the row.
+
+### Pick a Gap From the Scale
+
+* **Tags and Icons (8):** The default, for badges and icons with labels.
+* **Buttons (12):** Between buttons.
+* **Clusters (24 or 32):** Between separate clusters in a toolbar.
+
+## Accessibility
+
+Inline has no role, name, or keyboard behavior.
+
+### Semantics
+
+* **Default Element (div):** Has no role. Screen readers pass over it.
+* **Semantic Element (render):** If the row holds items or links, render a list or nav, such as `render={<ul />}`.
+
+### Your Responsibilities
+
+* **Match DOM and Visual Order (Tab):** Don't reorder children with CSS or reversed directions. Reading and focus follow the DOM ([SC 1.3.2](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html), [SC 2.4.3](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html)).
+
+## Related
+
+[Stack](/docs/components/stack)
+
+Use for vertical spacing.
+
+[Button](/docs/components/button)
+
+Use for ordering actions in a row.
+
+[Badge](/docs/components/badge)
+
+Use for status labels.
+
+[Layout](/docs/foundations/layout)
+
+Covers the spacing scale.

package/dist/docs/components/inset.md

@@ -0,0 +1,225 @@
+# Inset
+
+Pads content with spacing tokens.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Inset.tsx)
+
+## Overview
+
+Inset pads its content on every side or per axis, and adds no other styles.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Inset, Stack, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inset space="24" {...styles.card()}>
+      <Stack gap="12">
+        <span>Card content</span>
+        <span>Second line</span>
+      </Stack>
+    </Inset>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Inset/Basic.tsx)
+
+### Space
+
+Set `space` to pad every side.
+
+```tsx
+import { Inline, Inset, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inline align="start" gap="16" wrap>
+      {(['8', '16', '24', '32'] as const).map((space) => (
+        <Inset key={space} space={space} {...styles.card()}>
+          space {space}
+        </Inset>
+      ))}
+    </Inline>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Inset/Space.tsx)
+
+### Block
+
+Set `block` or `inline` to override `space` on one axis.
+
+```tsx
+import { Inset, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Inset block="24" inline="32" {...styles.card()}>
+      Block 6, inline 8
+    </Inset>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Inset/Block.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Inset } from '@tempoxyz/ds'
+
+<Inset />
+```
+
+## Guidelines
+
+### When to Use
+
+* Pad a region with no padding of its own, such as a custom panel or a band of page content.
+* Pad each axis differently, such as `block="16"` and `inline="24"` around a toolbar.
+
+### When Not to Use
+
+* Use [Surface](/docs/components/surface) for a card. Its `size` sets padding and corner radius.
+* Use [Container](/docs/components/container) for page gutters that grow with the viewport.
+* Use the `gap` of [Stack](/docs/components/stack), [Inline](/docs/components/inline), or [Grid](/docs/components/grid) for space between siblings.
+
+### Don't Double the Padding
+
+[Surface](/docs/components/surface), [Dialog](/docs/components/dialog), and `AppShell.Main` of [AppShell](/docs/components/app-shell) already pad their content.
+
+**Do:** Place content directly in a Surface, so it lines up with the cards beside it.
+
+```tsx
+/**
+ * Do example for "Don't Double the Padding" on the Inset page.
+ * Place content directly in a Surface, so it lines up with the cards beside it.
+ * @module
+ */
+import { style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium">
+        <Surface.Title>Balance</Surface.Title>
+        <Surface.Description>1,250.00 USDC</Surface.Description>
+      </Surface>
+      <Surface size="medium">
+        <Surface.Title>Activity</Surface.Title>
+        <Surface.Description>3 payments today</Surface.Description>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Add an Inset inside a Surface, which moves its content off the shared edge.
+
+```tsx
+/**
+ * Don't example for "Don't Double the Padding" on the Inset page.
+ * Don't add an Inset inside a Surface, which moves its content off the shared edge.
+ * @module
+ */
+import { Inset, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.canvas()}>
+      <Surface size="medium">
+        <Surface.Title>Balance</Surface.Title>
+        <Surface.Description>1,250.00 USDC</Surface.Description>
+      </Surface>
+      <Surface size="medium">
+        <Inset space="16">
+          <Surface.Title>Activity</Surface.Title>
+          <Surface.Description>3 payments today</Surface.Description>
+        </Inset>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    padding: '12',
+    width: '100% !custom',
+  })
+}
+```
+
+### Match Surface Padding
+
+Use `16` or `24` for most regions, so they line up with a `medium` or `large` [Surface](/docs/components/surface).
+
+* **Medium (16):** Matches a `medium` Surface, such as a dashboard tile.
+* **Large (24):** Matches a `large` Surface, such as a page card.
+
+## Accessibility
+
+An inset adds padding only. It has no role, name, or keyboard behavior.
+
+### Semantics
+
+* **Default Element (div):** Has no role. Screen readers pass over it.
+* **Semantic Element (render):** Render a section or aside when needed, such as `render= {<section aria-labelledby="…" />}`.
+
+### Your Responsibilities
+
+Keep large inline padding off narrow viewports, so content [reflows](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) at 320px without horizontal scrolling.
+
+## Related
+
+[Surface](/docs/components/surface)
+
+Use for padded cards.
+
+[Stack](/docs/components/stack)
+
+Use for space between siblings.
+
+[Layout](/docs/foundations/layout)
+
+Covers the spacing scale.