Tray

Questions

Should variance use the population or the sample formula?

Describe a change, @ to add files

import { useState } from "react";
import {
  Button, Icon, IconButton, Tray, TrayBody, TrayFooter, TrayHeader, TrayOption,
  TrayTitle,
} from "@arcadia/ui";

function Question() {
  const [picked, setPicked] = useState("a");
  const options = [
    { id: "a", label: "Population (divide by N)", description: "Recommended" },
    { id: "b", label: "Sample (divide by N−1)" },
  ];
  return (
    <Tray aria-label="Questions" role="group">
      <TrayHeader>
        <TrayTitle>Questions</TrayTitle>
        <IconButton icon="minus" label="Minimise" size="xs" tone="muted" />
      </TrayHeader>
      <TrayBody layout="text">
        <span {...sx("cmp-strong", cmp.strong)}>
          Should variance use the population or the sample formula?
        </span>
      </TrayBody>
      <TrayBody role="radiogroup" aria-label="Answer">
        {options.map((o, i) => (
          <TrayOption
            key={o.id}
            badge={String.fromCharCode(65 + i)}
            label={o.label}
            description={o.description}
            selected={picked === o.id}
            onClick={() => setPicked(o.id)}
          />
        ))}
        <TrayOption
          badge={<Icon name="pencil" size="text" />}
          label="Other"
          selected={picked === "c"}
          onClick={() => setPicked("c")}
        />
      </TrayBody>
      <TrayFooter start={<Button size="sm" shape="pill" variant="text">Skip</Button>}>
        <Button size="sm" shape="pill" variant="primary" hint="⏎">Next</Button>
      </TrayFooter>
    </Tray>
  );
}

TSX

import { Tray, TrayBody, TrayHeader, TrayTitle } from "@arcadia/ui";

<Tray aria-label="Queued messages">
  <TrayHeader><TrayTitle>1 queued</TrayTitle></TrayHeader>
  <TrayBody layout="text">Also: lerp should not clamp t.</TrayBody>
</Tray>

Docked to the composer for questions, approvals, queued messages and the +, / and @ pickers. It sits on --bg-elevated with radius 20 and continuous corners (16 round), a soft shadow and the float edge drawn inside; it slides 4px from the composer and never zooms. Give it a name (aria-label, or aria-labelledby on its title) and a role that fits. TrayTitle takes the props of the <span> it renders.

Tray, Dialog or Confirm Dialog? A Tray asks during work and leaves the page usable. Use a Dialog for a task with its own controls, and a Confirm Dialog only to stop something that can't be undone.

The footer keeps its actions at the end. Actions that don't fit one row wrap under it, still at the end, so in a narrow window the last one (the primary) takes a row of its own and none is pushed past the tray's edge. Its start slot takes a count, a pager or a text button such as Skip: the button's label starts on the tray's text column, under the title, not on its padding.

A notice is a tray of its header alone: a glyph at the text's height, one line, the remedy at its end. Alone, the header is centred in its 40px and its end is a control side, as a footer's.

A tray that asks something docks to a hailing composer: the horizon holds its light while the product waits on you, and the warm answer button reads as part of that light.

Examples

Multiple choice

kind="multiple" options are checkboxes; the footer's start slot holds a count or a pager.

Which checks should run?

Describe a change, @ to add files

import { useState } from "react";
import {
  Button, Tray, TrayBody, TrayFooter, TrayHeader, TrayOption, TrayTitle,
} from "@arcadia/ui";

function Checks() {
  const [on, setOn] = useState(new Set(["lint"]));
  const toggle = (k: string) => setOn((s) => {
    const n = new Set(s);
    if (n.has(k)) n.delete(k); else n.add(k);
    return n;
  });
  return (
    <Tray aria-label="Checks to run" motion="static">
      <TrayHeader><TrayTitle>Which checks should run?</TrayTitle></TrayHeader>
      <TrayBody role="group" aria-label="Checks">
        <TrayOption
          kind="multiple"
          label="Lint"
          selected={on.has("lint")}
          onClick={() => toggle("lint")}
        />
        <TrayOption
          kind="multiple"
          label="Typecheck"
          selected={on.has("types")}
          onClick={() => toggle("types")}
        />
        <TrayOption
          kind="multiple"
          label="Unit tests"
          description="Slow"
          selected={on.has("tests")}
          onClick={() => toggle("tests")}
        />
        <TrayOption kind="multiple" label="Deploy" description="Needs a clean tree" disabled />
      </TrayBody>
      <TrayFooter divided start={`${on.size} selected`}>
        <Button size="sm" shape="pill" variant="primary" hint="⌘⏎">
          Submit
        </Button>
      </TrayFooter>
    </Tray>
  );
}

A confirmation

A neutral question about the page itself, in a tray instead of a dialog, so the work behind it stays in view. It asks nothing of the agent's turn, so the horizon stays dark.

Discard 3 unsaved changes?

The edits to settings.css and two other files are lost.

Describe a change, @ to add files

import {
  Button, Tray, TrayBody, TrayFooter, TrayHeader, TrayTitle,
} from "@arcadia/ui";

<Tray aria-label="Unsaved changes" role="alertdialog" motion="static">
  <TrayHeader><TrayTitle>Discard 3 unsaved changes?</TrayTitle></TrayHeader>
  <TrayBody layout="text">
    <span {...sx("cmp-detail", cmp.detail)}>
      The edits to settings.css and two other files are lost.
    </span>
  </TrayBody>
  <TrayFooter>
    <Button size="sm" shape="pill">Keep editing</Button>
    <Button size="sm" shape="pill" variant="danger">Discard</Button>
  </TrayFooter>
</Tray>

Picker

The + menu: ListRows in a tray below the composer, labels only; a disabled row says why. Pickers are static, so they open instantly.

Describe a change, @ to add files

import { Icon, ListRow, Separator, Tray, TrayBody } from "@arcadia/ui";

<Tray placement="below" motion="static" aria-label="Commands and modes">
  <TrayBody>
    <ListRow
      leading="agent"
      label="Agent"
      emphasis
      highlighted
      meta={<Icon name="check" size="text" />}
    />
    <ListRow leading="plan" label="Plan" emphasis />
    <ListRow leading="ask" label="Ask" emphasis />
    <Separator inset />
    <ListRow leading="at" label="Mention a file" emphasis />
    <ListRow
      leading="compact"
      label="Compact context"
      description="Unavailable while running"
      descriptionYields={false}
      emphasis
      disabled
    />
  </TrayBody>
</Tray>

A notice

Its header alone: what the message box holds can't go as it is, and the one move that fixes it.

Large model isn't available: its provider is signed out.

Describe a change, @ to add files

import { Button, Icon, Tray, TrayHeader, TrayTitle } from "@arcadia/ui";

<Tray aria-label="Model unavailable" role="status" motion="static">
  <TrayHeader>
    <Icon name="alert" size="text" />
    <TrayTitle>Large model isn&apos;t available: its provider is signed out.</TrayTitle>
    <Button size="sm" shape="pill" variant="secondary">Use Fast model</Button>
  </TrayHeader>
</Tray>

Enter and exit

Pass open to let the tray keep itself mounted for its exit fade. Only event-driven trays animate.

A 120ms slide in, a 90ms fade out

Reduced motion keeps the fades and drops the 4px travel.

import { useState } from "react";
import { Button, Tray, TrayBody, TrayHeader, TrayTitle } from "@arcadia/ui";

function Replay() {
  const [open, setOpen] = useState(true);
  return (
    <div {...sx("cmp-stream", cmp.stream)}>
      <div>
        <Button size="sm" variant="outline" onClick={() => setOpen(!open)}>
          {open ? "Close" : "Open"} tray
        </Button>
      </div>
      <Tray open={open} aria-label="Queued">
        <TrayHeader><TrayTitle>A 120ms slide in, a 90ms fade out</TrayTitle></TrayHeader>
        <TrayBody layout="text">
          Reduced motion keeps the fades and drops the 4px travel.
        </TrayBody>
      </Tray>
    </div>
  );
}

rootStyle takes where the tray sits and the knobs below, each a token of its kind.

--tray-bg: PaintDefault var(--bg-elevated); Surface fill.
--tray-radius: Ref<Radius>Default var(--radius-frame-tray); Corner radius.
--tray-pad: Ref<Space>Default var(--space-1-5); Inset around a body of rows (6px). Their corners follow this inset.
--tray-max-h: Ref<Measure>Default min(420px, 50vh); Tallest height (420, at most half the viewport); the body scrolls.
--tray-px: Ref<Space> | DerivedDefault calc(var(--tray-pad) + var(--space-1) + (var(--control-xs) - var(--icon-md)) / 2); Inline padding of the header, the footer's start and a text body: the rows' first ink (the pad plus a row's text side, 12), so a heading sits on the text it labels (R3).

--tray-pad sets the row inset. Both TrayOption and ListRow corners follow the tray radius minus that inset.

TrayOption supplies role="radio" or "checkbox" with aria-checked; the surrounding body owns the group role, as above (radiogroup, group). A tray is not modal: focus stays where it was when one arrives, so announce a new question with a live region or move focus to it on purpose.

The keys belong to the flow around the tray. A question flow should handle these:

1 to 9: Pick an option by its number
↓↑: Move between options
Space: Toggle a checkbox option
Enter: Submit the answer

placement: "above" | "below"Default "above"; Which side of the composer it docks to. above rises from below; below drops from above.
motion: "enter" | "static"Default "enter"; enter: 120ms rise + fade on mount, 90ms fade on close. Only event-driven trays animate (a question or approval arriving, a message queued). static: appears and leaves instantly: hydrated trays and the +, / and @ pickers, which open at once.
open: boolean; Omit to mount and unmount the tray yourself (no exit motion). Pass it to let the tray keep itself mounted for its exit fade (data-exiting, inert) and unmount afterwards.
rootStyle: RootStyle<TrayKnobs>; Typed StyleX override: where the tray sits (layout) and its --tray-* knobs.

Rest props go to <div> props and render.

No props of its own. Rest props go to <div> props and render.

layout: "rows" | "text"Default "rows"; rows: ListRows / TrayOptions inset 6px. text: prose aligned with the header text.
glide: booleanDefault false; One highlight that glides between the rows (a picker's +, / or @ list); see Glide.

Rest props go to <div> props and render.

divided: booleanDefault false; Hairline above the footer.
start: ReactNode; Left-aligned group (a pager, a hint, a text button on the text column); the children stay at the end.

Rest props go to <div> props and render.

kind: "single" | "multiple"Default "single"; single: a lettered/numbered badge, role="radio". multiple: a checkbox, role="checkbox".
badge: ReactNode; Badge content for single ("1", "A", or an Icon for "Other").
selected: booleanDefault false
label: ReactNode; The option text (or pass it as children).
description: ReactNode; Quieter text after the label (text-3).
disabled: booleanDefault false; Text-4, not selectable.

Rest props go to <button> props and render.

Usage

Examples

Multiple choice

A confirmation

Picker

A notice

Enter and exit

Customising

Accessibility

API reference

Tray

TrayHeader No own props

TrayBody 2 props

TrayFooter 2 props

TrayOption 6 props