@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/calendar.md

@@ -0,0 +1,375 @@
+# Calendar
+
+A month grid for picking one date or a date range.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Calendar.tsx)
+
+## Overview
+
+Shows one month at a time. The month buttons page through months, and each day is a button.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Calendar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Calendar defaultValue={new Date()} />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Calendar/Basic.tsx)
+
+### Mode
+
+Set `mode="range"` to select a `{ from, to }` range. The default is `single`.
+
+```tsx
+import { Calendar } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+export function Demo() {
+  const [range, setRange] = useState<Calendar.Range | null>(null)
+
+  return <Calendar mode="range" onValueChange={setRange} value={range} />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Calendar/Mode.tsx)
+
+### Disabled Dates
+
+Set `min`, `max`, or `isDateDisabled` to mark unavailable days.
+
+```tsx
+import { Calendar } from '@tempoxyz/ds'
+
+export function Demo() {
+  const today = new Date()
+
+  return (
+    <Calendar
+      isDateDisabled={(date) => date.getDay() === 0}
+      max={new Date(today.getFullYear(), today.getMonth() + 1, 20)}
+      min={new Date(today.getFullYear(), today.getMonth() - 1, 5)}
+    />
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Calendar/DisabledDates.tsx)
+
+### Locale
+
+Set `locale` to format the month and weekdays. The default is the browser's locale.
+
+```tsx
+import { Calendar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Calendar locale="de-DE" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Calendar/Locale.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Calendar } from '@tempoxyz/ds'
+
+<Calendar />
+```
+
+## Guidelines
+
+### When to Use
+
+* Pick a date near today with the grid always on screen, such as a start date in a side panel.
+* Pick a date range with `mode="range"`, such as the period for an activity export.
+* Show which days are available, such as business days for a bank withdrawal.
+
+### When Not to Use
+
+* If the date is one field in a form, use [DatePicker](/docs/components/date-picker). It opens the same calendar in a popup.
+* Use [TextInput](/docs/components/text-input) for dates far from today, such as a date of birth.
+* Use [ChoiceGroup](/docs/components/choice-group) for preset ranges, such as 24H, 7D, and 30D above a chart.
+
+### Explain Unavailable Days
+
+Set `min`, `max`, or `isDateDisabled`, and state the rule in text beside the calendar, not in a tooltip on each day. The month buttons can't page past `min` or `max`.
+
+**Do:** State the rule below the calendar, such as Bank withdrawals settle on business days.
+
+```tsx
+/**
+ * Do example for "Explain Unavailable Days" on the Calendar page.
+ * State the rule below the calendar, such as Bank withdrawals settle on business days.
+ * @module
+ */
+import { Calendar, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Calendar
+        defaultMonth={new Date(2026, 9, 1)}
+        isDateDisabled={(date) => date.getDay() === 0 || date.getDay() === 6}
+      />
+      <span {...styles.note()}>Bank withdrawals settle on business days.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const note = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+**Don't:** Disable days without saying why.
+
+```tsx
+/**
+ * Don't example for "Explain Unavailable Days" on the Calendar page.
+ * Don't disable days without saying why.
+ * @module
+ */
+import { Calendar } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Calendar
+      defaultMonth={new Date(2026, 9, 1)}
+      isDateDisabled={(date) => date.getDay() === 0 || date.getDay() === 6}
+    />
+  )
+}
+```
+
+### Show a Range in Text Too
+
+In range mode, `onValueChange` runs on every press: `{ from }` after the first, `{ from, to }` after the second. Apply a filter only after `to` is set.
+
+**Do:** Show the selected range as text, such as Oct 1 to 14, 2026.
+
+```tsx
+/**
+ * Do example for "Show a Range in Text Too" on the Calendar page.
+ * Show the selected range as text, such as Oct 1 to 14, 2026.
+ * @module
+ */
+import { Calendar, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.range()}>Oct 1 to 14, 2026</span>
+      <Calendar
+        defaultValue={{ from: new Date(2026, 9, 1), to: new Date(2026, 9, 14) }}
+        mode="range"
+      />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const range = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+**Don't:** Rely on the highlighted days alone to show the range.
+
+```tsx
+/**
+ * Don't example for "Show a Range in Text Too" on the Calendar page.
+ * Don't rely on the highlighted days alone to show the range.
+ * @module
+ */
+import { Calendar } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Calendar
+      defaultValue={{ from: new Date(2026, 9, 1), to: new Date(2026, 9, 14) }}
+      mode="range"
+    />
+  )
+}
+```
+
+### Start on the Month of the Task
+
+`defaultMonth` falls back to the selected day's month, then the current month. Set it to the month of the task, such as the start of a statement period. To sync the page with a typed [TextInput](/docs/components/text-input), control it with `month` and `onMonthChange`.
+
+**Do:** Open on the month the task is about.
+
+```tsx
+/**
+ * Do example for "Start on the Month of the Task" on the Calendar page.
+ * Open on the month the task is about.
+ * @module
+ */
+import { Calendar, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.label()}>Start of the September statement</span>
+      <Calendar defaultMonth={new Date(2026, 8, 1)} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+**Don't:** Open on the current month when the task is about another one.
+
+```tsx
+/**
+ * Don't example for "Start on the Month of the Task" on the Calendar page.
+ * Don't open on the current month when the task is about another one.
+ * @module
+ */
+import { Calendar, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.label()}>Start of the September statement</span>
+      <Calendar defaultMonth={new Date(2026, 9, 1)} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+### Follow the Locale
+
+`locale` defaults to the browser's locale, and `weekStartsOn` to that locale's first weekday. Leave both unset unless the product uses a fixed locale. The month button names default to English, so translate them through `labels`.
+
+**Do:** Let the locale set the first weekday, and translate `labels`.
+
+```tsx
+/**
+ * Do example for "Follow the Locale" on the Calendar page.
+ * Let the locale set the first weekday, and translate `labels`.
+ * @module
+ */
+import { Calendar } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Calendar
+      defaultMonth={new Date(2026, 9, 1)}
+      labels={{ next: 'Nächster Monat', previous: 'Vorheriger Monat' }}
+      locale="de-DE"
+    />
+  )
+}
+```
+
+**Don't:** Override `weekStartsOn` against the locale, such as Sunday first in German.
+
+```tsx
+/**
+ * Don't example for "Follow the Locale" on the Calendar page.
+ * Don't override `weekStartsOn` against the locale, such as Sunday first in German.
+ * @module
+ */
+import { Calendar } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Calendar
+      defaultMonth={new Date(2026, 9, 1)}
+      labels={{ next: 'Nächster Monat', previous: 'Vorheriger Monat' }}
+      locale="de-DE"
+      weekStartsOn={0}
+    />
+  )
+}
+```
+
+## Content
+
+If a date maps to a time, such as a statement cutoff, name the time zone, such as UTC.
+
+## Accessibility
+
+Follows the [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/), as in the [date picker dialog example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/).
+
+### Semantics
+
+* **Month Grid (grid):** A table labelled by the month heading.
+* **Weeks and Weekdays (gridcell):** Weekday names are column headers, and each week is a row of day cells.
+* **Days (button):** Named with the full localized date, such as "Tuesday, October 20, 2026".
+* **Today and Selection (aria-selected):** Today is marked as the current date. Selected days, including every day in a range, are marked.
+* **Unavailable Days (aria-disabled):** Days outside the allowed range stay focusable and announced.
+* **Month Buttons:** Named "Previous month" and "Next month". Translate them with `labels`.
+
+### Keyboard
+
+* **Move into the Calendar (Tab):** Moves focus to the month buttons, then to one day in the grid.
+* **Next or Previous Day (Right Arrow and Left Arrow):** Moves focus to the next or previous day.
+* **Next or Previous Week (Down Arrow and Up Arrow):** Moves focus to the same day in the next or previous week.
+* **First or Last Day of the Week (Home and End):** Moves focus to the first or last day of the week.
+* **Next or Previous Month (Page Down and Page Up):** Moves focus to the same day in the next or previous month.
+* **Next or Previous Year (Shift+Page Down or Page Up):** Moves focus to the same day in the next or previous year.
+* **Select the Focused Day (Enter or Space):** Selects the focused day. In `range` mode, the first press sets the start, the second the end.
+
+### Focus
+
+Focus starts on the selected day or today. Moving past the shown month turns the page, and focus stops at `min` and `max`.
+
+### Announcements
+
+Turning the page announces the new month in a polite live region.
+
+### Your Responsibilities
+
+* **Localize Labels (labels):** Translate the month buttons. Set `locale` to match the page language.
+* **Explain Unavailable Days (isDateDisabled):** Explain the rule in nearby text, such as "Weekends are unavailable".
+
+## Related
+
+[DatePicker](/docs/components/date-picker)
+
+Use for a date field in a form.
+
+[TextInput](/docs/components/text-input)
+
+Use for typed dates.
+
+[ChoiceGroup](/docs/components/choice-group)
+
+Use for preset ranges.
+
+[Field](/docs/components/field)
+
+Use for labelling the date and its constraints.

package/dist/docs/components/callout.md

@@ -0,0 +1,96 @@
+# Callout
+
+Sets a short passage of body text apart in a subtle box.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Callout.tsx)
+
+Figma: [Callout](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3506-2664)
+
+## Overview
+
+A callout renders body text in a subtle box, padded 24px above and below and 32px at the sides. It sets a summary or an aside apart from the text around it, and adds no role or announcement.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Callout } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <Callout>
+      Stablecoin payments move fiat-referenced digital assets over blockchain networks. The onchain
+      transfer is only one part of the end-to-end payment.
+    </Callout>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Callout/Basic.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Callout } from '@tempoxyz/ds'
+
+<Callout />
+```
+
+## Guidelines
+
+### When to Use
+
+* Set a summary, a definition, or an aside apart from the body of an article or a docs page.
+
+### When Not to Use
+
+* Use an [Alert](/docs/components/alert) for a message about a status or an outcome.
+* Use a [Banner](/docs/components/banner) for a message about the whole page or product.
+* Use a [Snippet](/docs/components/snippet) for code that people copy.
+
+### Keep the Passage Optional
+
+**Do:** Use it for context that a reader can skip without missing a step.
+
+```tsx
+<Callout style={{ width: 360 }}>
+  Tempo settles a payment in under a second, with fees paid in stablecoins.
+</Callout>
+```
+
+**Don't:** Use it for an error or a warning. Use an Alert instead.
+
+```tsx
+<Callout style={{ width: 360 }}>Your payment failed. Check the address and try again.</Callout>
+```
+
+### Keep One Callout per Section
+
+* **One Passage (1):** Sets one passage apart, so the reader notices it among the body text.
+* **Short Text (3 lines):** Holds a few lines at most. Move a longer passage into the body text.
+
+## Content
+
+* Write complete sentences in the same voice as the text around the callout.
+* Keep it to one idea in two or three lines.
+
+## Accessibility
+
+A callout renders a `<div>` with no role, so screen readers read its text in place.
+
+* **Root (div):** Reads its text in place, as part of the surrounding content, with no role.
+* **Landmark (role):** If the callout is an aside, set `role="note"` and an `aria-label` that names it.
+* **Contrast (4.5:1):** Renders primary text on the subtle fill, above 4.5:1 in both color schemes.
+
+## Related
+
+[Alert](/docs/components/alert)
+
+Use for a message about a status or an outcome.
+
+[Banner](/docs/components/banner)
+
+Use for a message about the whole page.