@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/container.md

@@ -0,0 +1,257 @@
+# Container
+
+Centers content at a maximum width.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Container.tsx)
+
+## Overview
+
+A container centers content at a maximum width, with inline padding that grows on wider viewports. It sets width only.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Container, Inline, Inset, Stack, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Container size="narrow">
+      <Stack gap="24">
+        <Inline justify="between">
+          <span>Stack, Inline and Container</span>
+          <Inline gap="8">
+            <span {...styles.chip()}>Public</span>
+            <span {...styles.chip()}>Private</span>
+          </Inline>
+        </Inline>
+        <Inset space="24" {...styles.card()}>
+          <Stack gap="12">
+            <span>Card content</span>
+            <span>Second line</span>
+          </Stack>
+        </Inset>
+      </Stack>
+    </Container>
+  )
+}
+
+namespace styles {
+  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
+
+  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/Container/Basic.tsx)
+
+### Size
+
+Set `size` to `narrow`, `medium`, `wide` (default), or `full`.
+
+```tsx
+import { Container, Inset, Stack, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Stack gap="12">
+      {(['narrow', 'medium', 'wide', 'full'] as const).map((size) => (
+        <Container key={size} size={size}>
+          <Inset space="16" {...styles.card()}>
+            {size}
+          </Inset>
+        </Container>
+      ))}
+    </Stack>
+  )
+}
+
+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/Container/Size.tsx)
+
+### Gutter
+
+Set `gutter={false}` to remove the inline padding.
+
+```tsx
+import { Container, Inset, Stack, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Stack gap="12">
+      <Container size="narrow">
+        <Inset space="16" {...styles.card()}>
+          With gutter
+        </Inset>
+      </Container>
+      <Container gutter={false} size="narrow">
+        <Inset space="16" {...styles.card()}>
+          Without gutter
+        </Inset>
+      </Container>
+    </Stack>
+  )
+}
+
+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/Container/Gutter.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Container } from '@tempoxyz/ds'
+
+<Container />
+```
+
+## Guidelines
+
+### When to Use
+
+* Center content on pages without a sidebar, such as sign-in or a receipt.
+* Cap the width of a full-width band, such as a header, to line it up with the page.
+
+### When Not to Use
+
+* Use [AppShell](/docs/components/app-shell) for pages with persistent navigation. `AppShell.Main` already caps and pads the content column.
+* Use [Inset](/docs/components/inset) to pad content inside a region, and [Surface](/docs/components/surface) for a card.
+* Use [Stack](/docs/components/stack) or [Grid](/docs/components/grid) to arrange the content inside the container.
+
+### Pick a Size by Content
+
+* **Narrow (48rem):** Forms, settings, sign-in, and a send flow.
+* **Medium (64rem):** Detail pages, such as a transaction or API key.
+* **Wide (80rem):** The default, for dashboards and tables.
+* **Full (none):** Edge-to-edge charts and maps.
+
+Give body text in a `wide` container its own narrower column.
+
+### Keep the Gutter on Page Containers
+
+Keep the gutter on any container that touches the viewport edge. If a parent already pads the content, set `gutter={false}`.
+
+**Do:** Keep the gutter, so content stays off the screen edge.
+
+```tsx
+/**
+ * Do example for "Keep the Gutter on Page Containers" on the Container page.
+ * Keep the gutter, so content stays off the screen edge.
+ * @module
+ */
+import { Container, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.viewport()}>
+      <Container size="narrow" {...styles.page()}>
+        <h1 {...styles.title()}>Send payment</h1>
+        <Surface size="medium">Recipient 0x71C7…976F</Surface>
+      </Container>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', gap: '12' })
+
+  export const title = style({ margin: '0', typography: 'heading.h3' })
+
+  export const viewport = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    paddingBlock: '24',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Remove the gutter from a container at the viewport edge.
+
+```tsx
+/**
+ * Don't example for "Keep the Gutter on Page Containers" on the Container page.
+ * Don't remove the gutter from a container at the viewport edge.
+ * @module
+ */
+import { Container, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.viewport()}>
+      <Container gutter={false} size="narrow" {...styles.page()}>
+        <h1 {...styles.title()}>Send payment</h1>
+        <Surface size="medium">Recipient 0x71C7…976F</Surface>
+      </Container>
+    </div>
+  )
+}
+
+namespace styles {
+  export const page = style({ display: 'flex', flexDirection: 'column', gap: '12' })
+
+  export const title = style({ margin: '0', typography: 'heading.h3' })
+
+  export const viewport = style({
+    backgroundColor: 'background.primary',
+    borderRadius: 'sm',
+    boxSizing: 'border-box',
+    paddingBlock: '24',
+    width: '100% !custom',
+  })
+}
+```
+
+## Accessibility
+
+A container has no role, name, or keyboard behavior.
+
+### Semantics
+
+* **Default Element (div):** Carries no role by default.
+* **Semantic Element (render):** Set a landmark with `render={<main />}`.
+
+### Your Responsibilities
+
+* **Render Landmarks Directly (render):** Render `main` on the container, not on an extra wrapper, and don't nest a second `main` inside it.
+* **Reflow at 320px (SC 1.4.10):** Content must [reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) without horizontal scrolling. Check addresses and hashes.
+
+## Related
+
+[AppShell](/docs/components/app-shell)
+
+Use for pages with a sidebar.
+
+[Stack](/docs/components/stack)
+
+Use for spacing content inside the container.
+
+[Layout](/docs/foundations/layout)
+
+Covers widths, spacing, and breakpoints.
+
+[Responsive Layout](/docs/patterns/responsive-layout)
+
+Covers adapting pages across breakpoints.