@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/split-bar.md

@@ -0,0 +1,139 @@
+# SplitBar
+
+Splits one total between two parts, with a legend under the bar.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/SplitBar.tsx)
+
+Figma: [Data/Split Bar](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-4474)
+
+## Overview
+
+A split bar renders a thin bar that two parts share in proportion to their values, and a legend that names each part with its value. A part of zero draws no segment, so the other part fills the bar.
+
+## Examples
+
+### Basic
+
+```tsx
+import { SplitBar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <SplitBar
+      items={[
+        { label: 'Available', text: '$75.62', value: 75.62 },
+        { label: 'Agents', text: '$8.58', value: 8.58 },
+      ]}
+    />
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SplitBar/Basic.tsx)
+
+### One Part
+
+A part of 0 keeps its legend entry and draws no segment.
+
+```tsx
+import { SplitBar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <SplitBar
+      items={[
+        { label: 'Available', text: '$75.62', value: 75.62 },
+        { label: 'Agents', text: '$0.00', value: 0 },
+      ]}
+    />
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SplitBar/Empty.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { SplitBar } from '@tempoxyz/ds'
+
+<SplitBar />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show how a balance splits between two uses, such as the available funds and the funds set aside for agents.
+
+### When Not to Use
+
+* Use [BarChart](/docs/components/bar-chart) for values over time.
+* Use [Progress](/docs/components/progress) for the progress of one task.
+* Use [Gauge](/docs/components/gauge) for one value against a limit.
+
+### Show the Values
+
+**Do:** Give each part its amount, in the unit people act on.
+
+```tsx
+import { SplitBar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <SplitBar
+      items={[
+        { label: 'Available', text: '$75.62', value: 75.62 },
+        { label: 'Agents', text: '$8.58', value: 8.58 },
+      ]}
+    />
+  )
+}
+```
+
+**Don't:** Show percentages alone when people act on amounts.
+
+```tsx
+import { SplitBar } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <SplitBar
+      items={[
+        { label: 'Available', text: '90%', value: 90 },
+        { label: 'Agents', text: '10%', value: 10 },
+      ]}
+    />
+  )
+}
+```
+
+## Content
+
+### Name the Parts
+
+Name each part with one or two words, such as Available and Agents. Format each value as the rest of the page does, such as $75.62.
+
+## Accessibility
+
+A split bar renders a `<div>` whose bar is hidden from screen readers. The legend carries each label and value as text, in reading order.
+
+### Semantics
+
+* **Bar (aria-hidden):** Screen readers skip the bar and read the legend.
+
+### Your Responsibilities
+
+* **Name the Total (SC 1.3.1):** Place a heading or a label before the bar that names what it splits.
+
+## Related
+
+[BarChart](/docs/components/bar-chart)
+
+Use for values over time.
+
+[Progress](/docs/components/progress)
+
+Use for the progress of one task.

package/dist/docs/components/split-button.md

@@ -0,0 +1,464 @@
+# SplitButton
+
+Pairs a primary action with a menu of alternatives.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/SplitButton.tsx)
+
+## Overview
+
+A split button places the most common action beside a trigger that opens a menu of alternatives.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Menu, SplitButton } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <SplitButton.Root aria-label="Save">
+      <SplitButton.Action>Save</SplitButton.Action>
+      <Menu.Root>
+        <SplitButton.Trigger aria-label="More save options" />
+        <Menu.Popup align="end">
+          <Menu.Item>Save as draft</Menu.Item>
+          <Menu.Item>Save and close</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+    </SplitButton.Root>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SplitButton/Basic.tsx)
+
+### Variant
+
+Set `variant` on `SplitButton.Root` to `primary` (default), `secondary`, or `tertiary`.
+
+```tsx
+import { Menu, SplitButton, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
+        <SplitButton.Root key={variant} variant={variant}>
+          <SplitButton.Action>Save</SplitButton.Action>
+          <Menu.Root>
+            <SplitButton.Trigger aria-label="More save options" />
+            <Menu.Popup align="end">
+              <Menu.Item>Save as draft</Menu.Item>
+              <Menu.Item>Save and close</Menu.Item>
+            </Menu.Popup>
+          </Menu.Root>
+        </SplitButton.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SplitButton/Variant.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Menu, SplitButton } from '@tempoxyz/ds'
+
+<SplitButton.Root>
+  <SplitButton.Action />
+  <Menu.Root>
+    <SplitButton.Trigger />
+    <Menu.Popup />
+  </Menu.Root>
+</SplitButton.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Offer a main action with a few variations, such as Export CSV with Export JSON and Schedule export.
+* Keep the common choice one press away, such as Create key with Create test key.
+
+### When Not to Use
+
+* Use a [Button](/docs/components/button) with a [Menu](/docs/components/menu) when no option is the clear default.
+* Use two [Buttons](/docs/components/button) when both actions matter equally.
+* Use [Select](/docs/components/select) or [ChoiceGroup](/docs/components/choice-group) to choose a value or mode, not to run an action.
+* Use a separate [Button](/docs/components/button) for destructive actions, confirmed with an [AlertDialog](/docs/components/alert-dialog).
+
+### Make the Action the Common Choice
+
+`SplitButton.Action` runs without opening the menu, so give it the option most people pick. If people often open the menu first, move the popular option into the action, or use a [Menu](/docs/components/menu) button.
+
+**Do:** Put the option most people pick on the action.
+
+```tsx
+/**
+ * Do example for "Make the Action the Common Choice" on the SplitButton page.
+ * Put the option most people pick on the action.
+ * @module
+ */
+import { Menu, SplitButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <SplitButton.Root aria-label="Keys">
+        <SplitButton.Action>Create key</SplitButton.Action>
+        <Menu.Root>
+          <SplitButton.Trigger aria-label="More key options" />
+        </Menu.Root>
+      </SplitButton.Root>
+      <div {...styles.popup()}>
+        <div {...styles.item()}>Create test key</div>
+        <div {...styles.item()}>Import key</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    borderRadius: 'xs',
+    color: 'content.primary',
+    display: 'flex',
+    minHeight: '40',
+    paddingInline: '12',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    minWidth: '14rem !custom',
+    padding: '12',
+  })
+
+  export const stack = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '4',
+  })
+}
+```
+
+**Don't:** Put a rare option on the action and the common one in the menu.
+
+```tsx
+/**
+ * Don't example for "Make the Action the Common Choice" on the SplitButton page.
+ * Don't put a rare option on the action and the common one in the menu.
+ * @module
+ */
+import { Menu, SplitButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <SplitButton.Root aria-label="Keys">
+        <SplitButton.Action>Import key</SplitButton.Action>
+        <Menu.Root>
+          <SplitButton.Trigger aria-label="More key options" />
+        </Menu.Root>
+      </SplitButton.Root>
+      <div {...styles.popup()}>
+        <div {...styles.item()}>Create key</div>
+        <div {...styles.item()}>Create test key</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    borderRadius: 'xs',
+    color: 'content.primary',
+    display: 'flex',
+    minHeight: '40',
+    paddingInline: '12',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    minWidth: '14rem !custom',
+    padding: '12',
+  })
+
+  export const stack = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '4',
+  })
+}
+```
+
+### Keep Alternatives Related
+
+Make every menu item a variation of the action, such as a different format or timing, and use two to five of them. Put unrelated commands, or a longer list, in a [Menu](/docs/components/menu).
+
+**Do:** Fill the menu with variations of the main action.
+
+```tsx
+/**
+ * Do example for "Keep Alternatives Related" on the SplitButton page.
+ * Fill the menu with variations of the main action.
+ * @module
+ */
+import { Menu, SplitButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <SplitButton.Root aria-label="Export" variant="secondary">
+        <SplitButton.Action>Export CSV</SplitButton.Action>
+        <Menu.Root>
+          <SplitButton.Trigger aria-label="More export options" />
+        </Menu.Root>
+      </SplitButton.Root>
+      <div {...styles.popup()}>
+        <div {...styles.item()}>Export JSON</div>
+        <div {...styles.item()}>Schedule export</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    borderRadius: 'xs',
+    color: 'content.primary',
+    display: 'flex',
+    minHeight: '40',
+    paddingInline: '12',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    minWidth: '14rem !custom',
+    padding: '12',
+  })
+
+  export const stack = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '4',
+  })
+}
+```
+
+**Don't:** Collect unrelated or destructive commands behind the trigger.
+
+```tsx
+/**
+ * Don't example for "Keep Alternatives Related" on the SplitButton page.
+ * Don't collect unrelated or destructive commands behind the trigger.
+ * @module
+ */
+import { Menu, SplitButton, style, variants } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <SplitButton.Root aria-label="Export" variant="secondary">
+        <SplitButton.Action>Export CSV</SplitButton.Action>
+        <Menu.Root>
+          <SplitButton.Trigger aria-label="More options" />
+        </Menu.Root>
+      </SplitButton.Root>
+      <div {...styles.popup()}>
+        <div {...styles.item()}>Rename dashboard</div>
+        <div {...styles.item()}>Share</div>
+        <div {...styles.item({ intent: 'negative' })}>Delete dashboard</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = variants({
+    base: {
+      alignItems: 'center',
+      borderRadius: 'xs',
+      color: 'content.primary',
+      display: 'flex',
+      minHeight: '40',
+      paddingInline: '12',
+      typography: 'body.b2Strong',
+    },
+    defaultVariants: { intent: 'default' },
+    variants: {
+      intent: {
+        default: {},
+        negative: { color: 'content.negative' },
+      },
+    },
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    minWidth: '14rem !custom',
+    padding: '12',
+  })
+
+  export const stack = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '4',
+  })
+}
+```
+
+### Match the Buttons Around It
+
+Set `variant` and `size` on `SplitButton.Root`, and both buttons follow. A split button counts toward the one `primary` action per section, so use `secondary` when the view already has one. Use `small` in toolbars and table headers.
+
+**Do:** Match the size of nearby buttons, and leave `primary` to the main action.
+
+```tsx
+/**
+ * Do example for "Match the Buttons Around It" on the SplitButton page.
+ * Match the size of nearby buttons, and leave `primary` to the main action.
+ * @module
+ */
+import { Button, Menu, SplitButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <SplitButton.Root aria-label="Export" size="small" variant="secondary">
+        <SplitButton.Action>Export CSV</SplitButton.Action>
+        <Menu.Root>
+          <SplitButton.Trigger aria-label="More export options" />
+        </Menu.Root>
+      </SplitButton.Root>
+      <Button size="small">Send payment</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+**Don't:** Add a second `primary` action, or a size that differs from its neighbors.
+
+```tsx
+/**
+ * Don't example for "Match the Buttons Around It" on the SplitButton page.
+ * Don't add a second `primary` action, or a size that differs from its neighbors.
+ * @module
+ */
+import { Button, Menu, SplitButton, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <SplitButton.Root aria-label="Export">
+        <SplitButton.Action>Export CSV</SplitButton.Action>
+        <Menu.Root>
+          <SplitButton.Trigger aria-label="More export options" />
+        </Menu.Root>
+      </SplitButton.Root>
+      <Button size="small">Send payment</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+## Content
+
+### Name the Action and Its Object
+
+Label `SplitButton.Action` with a verb and an object, such as Export CSV. A bare Export hides which variation runs.
+
+### Make Each Item Stand Alone
+
+Repeat the verb in each menu item, such as Export JSON, not JSON, so each item reads as a complete action.
+
+## Accessibility
+
+`SplitButton` renders a group with a primary [Button](/docs/components/button) and a menu trigger. The trigger follows the [WAI-ARIA menu button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/).
+
+### Semantics
+
+* **SplitButton.Root (group):** Holds both buttons, named by its `aria-label`.
+* **SplitButton.Action (button):** The primary action, as a native button.
+* **SplitButton.Trigger (aria-haspopup):** A native button that announces its menu and open state.
+* **Menu (menu):** Named by the trigger. Items are announced as menu items.
+* **Chevron (reduced motion):** Rotates while the menu is open. Flips without animation under reduced motion.
+
+### Keyboard
+
+* **Move Between Buttons (Tab):** Moves focus to the action, then to the trigger.
+* **Run the Action (Enter or Space):** On the action, runs the primary action.
+* **Open to the First Item (Enter, Space, or Down Arrow):** Opens the menu and focuses the first item.
+* **Open to the Last Item (Up Arrow):** Opens the menu and focuses the last item.
+* **Move Between Items (Down Arrow and Up Arrow):** Move between items, and wrap at the ends.
+* **Jump to the Ends (Home and End):** Move to the first and last item.
+* **Activate an Item (Enter):** Activates the focused item and closes the menu.
+* **Close the Menu (Escape):** Closes the menu.
+
+### Your Responsibilities
+
+* **Name the Group (aria-label):** Name the root, such as "Save", so the pair reads as one group.
+* **Name the Trigger (aria-label):** Name the alternatives, such as "More save options". The chevron is the trigger's only content.
+* **Keep Actions Reachable:** If the primary action fails or is disabled, keep every menu action reachable another way.
+
+## Related
+
+[Button](/docs/components/button)
+
+Use for single actions.
+
+[Menu](/docs/components/menu)
+
+Use for lists of actions without a default.
+
+[AlertDialog](/docs/components/alert-dialog)
+
+Use for confirming destructive actions.
+
+[Forms](/docs/patterns/forms)
+
+Covers placing actions.