@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/separator.md

@@ -0,0 +1,379 @@
+# Separator
+
+Draws a rule between groups of content.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Separator.tsx)
+
+Figma: [Elements/Divider](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3269)
+
+## Overview
+
+Separator renders a 1px rule between thematic groups, such as menu sections or toolbar clusters. A horizontal rule sits centered in a 16px row. With `children`, it centers a short label between two rules, such as `or` between two ways to sign in.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Separator, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span>Above</span>
+      <Separator />
+      <span>Below</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    maxWidth: '16rem !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Separator/Basic.tsx)
+
+### Orientation
+
+Set `orientation` to `horizontal` (default) or `vertical`.
+
+```tsx
+import { Separator, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span>Left</span>
+      <Separator orientation="vertical" />
+      <span>Right</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12', height: '24' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Separator/Orientation.tsx)
+
+### Label
+
+Pass a short label as `children` to join two alternatives. A vertical separator ignores it.
+
+```tsx
+import { Button, Separator, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Button variant="secondary">Continue with passkey</Button>
+      <Separator>or</Separator>
+      <Button variant="secondary">Continue with email</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'grid', gap: '16', width: '320' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Separator/Label.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Separator } from '@tempoxyz/ds'
+
+<Separator />
+```
+
+## Guidelines
+
+### When to Use
+
+* Divide groups that spacing alone does not separate, such as line items and a total.
+* Divide clusters of toolbar controls, with `orientation="vertical"`.
+* Join two alternatives with a label, such as `or` between two ways to sign in.
+
+### When Not to Use
+
+* Use [ListGroup](/docs/components/list-group) or [Table](/docs/components/table) for lists of records. They draw their own dividers.
+* Use `SidebarMenu.Group` in a [SidebarMenu](/docs/components/sidebar-menu) and `Menu.Separator` in a [Menu](/docs/components/menu).
+
+### Try Space First
+
+A larger gap separates most groups, such as a [Stack](/docs/components/stack) with `gap="24"`. Add a separator only if the groups still run together, or one row must stand apart, such as a total.
+
+**Do:** Separate the total from the line items above it.
+
+```tsx
+/**
+ * Do example for "Try Space First" on the Separator page.
+ * Separate the total from the line items above it.
+ * @module
+ */
+import { Separator, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.summary()}>
+      <div {...styles.row()}>
+        <span>Amount</span>
+        <span>250.00 USDC</span>
+      </div>
+      <div {...styles.row()}>
+        <span>Network fee</span>
+        <span>0.01 USDC</span>
+      </div>
+      <Separator />
+      <div {...styles.total()}>
+        <span>Total</span>
+        <span>250.01 USDC</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2',
+  })
+
+  export const summary = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '12',
+    width: '100% !custom',
+  })
+
+  export const total = style({
+    color: 'content.primary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+**Don't:** Rule off every row.
+
+```tsx
+/** Don't example for "Try Space First" on the Separator page. Don't rule off every row. @module */
+import { Separator, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.summary()}>
+      <Separator />
+      <div {...styles.row()}>
+        <span>Amount</span>
+        <span>250.00 USDC</span>
+      </div>
+      <Separator />
+      <div {...styles.row()}>
+        <span>Network fee</span>
+        <span>0.01 USDC</span>
+      </div>
+      <Separator />
+      <div {...styles.total()}>
+        <span>Total</span>
+        <span>250.01 USDC</span>
+      </div>
+      <Separator />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2',
+  })
+
+  export const summary = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '12',
+    width: '100% !custom',
+  })
+
+  export const total = style({
+    color: 'content.primary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+### Keep Rules Inside Containers
+
+The edge of a [Surface](/docs/components/surface) or popup already ends the group.
+
+**Do:** Place separators only between groups.
+
+```tsx
+/**
+ * Do example for "Keep Rules Inside Containers" on the Separator page.
+ * Place separators only between groups.
+ * @module
+ */
+import { Separator, 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" {...styles.summary()}>
+        <div {...styles.row()}>
+          <span>Amount</span>
+          <span>250.00 USDC</span>
+        </div>
+        <div {...styles.row()}>
+          <span>Network fee</span>
+          <span>0.01 USDC</span>
+        </div>
+        <Separator />
+        <div {...styles.total()}>
+          <span>Total</span>
+          <span>250.01 USDC</span>
+        </div>
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const row = style({
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2',
+  })
+
+  export const summary = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const total = style({
+    color: 'content.primary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+**Don't:** Place a separator at the top or bottom edge of a Surface.
+
+```tsx
+/**
+ * Don't example for "Keep Rules Inside Containers" on the Separator page.
+ * Don't place a separator at the top or bottom edge of a Surface.
+ * @module
+ */
+import { Separator, 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" {...styles.summary()}>
+        <Separator />
+        <div {...styles.row()}>
+          <span>Amount</span>
+          <span>250.00 USDC</span>
+        </div>
+        <div {...styles.row()}>
+          <span>Network fee</span>
+          <span>0.01 USDC</span>
+        </div>
+        <Separator />
+        <div {...styles.total()}>
+          <span>Total</span>
+          <span>250.01 USDC</span>
+        </div>
+        <Separator />
+      </Surface>
+    </div>
+  )
+}
+
+namespace styles {
+  export const canvas = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    padding: '12',
+    width: '100% !custom',
+  })
+
+  export const row = style({
+    color: 'content.secondary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2',
+  })
+
+  export const summary = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const total = style({
+    color: 'content.primary',
+    display: 'flex',
+    justifyContent: 'space-between',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+## Accessibility
+
+### Semantics
+
+* **Element (separator):** Exposed as a boundary between groups. Some screen readers announce "separator", and others skip it.
+* **Orientation (aria-orientation):** Follows `orientation`. A vertical separator stretches to the height of its row, at least 1em.
+* **Label (div):** A separator hides its children from screen readers, so a labeled one renders a `div` without the role. Screen readers read the label in place, and the rules stay hidden.
+* **No Focus:** Not focusable, with no keyboard behavior.
+
+### Your Responsibilities
+
+* **Use Headings for Structure (SC 1.3.1):** A separator does not [name the group](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) that follows it.
+* **Separate Meaningful Groups:** Use it only between meaningful groups. Draw a decorative line with a CSS border.
+
+## Related
+
+[Stack](/docs/components/stack)
+
+Use for spacing groups apart.
+
+[ListGroup](/docs/components/list-group)
+
+Use for divided lists.
+
+[Menu](/docs/components/menu)
+
+Use for separators between menu groups.