@siyahi/ui 0.1.9-next.20 → 0.1.9-next.22

package/DESIGN.md

@@ -0,0 +1,42 @@
+# Siyahi design guidelines
+
+These rules bind every page built on `@siyahi/ui`: The Book, Dash and any other
+app. Agents must follow them when designing or changing UI; a reviewer treats a
+breach as a defect. The catalogue (https://siyahi.jatinbansal.com) shows each
+component; this file says how to use them.
+
+## Colour
+
+Colour is placed, not spread. A page is neutral greys plus colour that carries
+a meaning:
+
+- **Ink indigo** is the accent: links, focus rings, the selected sidebar item,
+  the first chart series and an `accent` `Callout`. Buttons, badges and toggles
+  stay monochrome.
+- **Green and red** mean a gain and a loss. A signed figure is `Delta`: the figure in the text colour with its
+  `+` or `−`, and only a small trend icon in green or red. In plain text (labels, tooltips) write the sign; never
+  colour a run of figures green and red.
+  **Amber** means caution. None of them decorates.
+- **Emphasis tints the whole surface.** A caution is `WarningAlert`; a point set
+  apart is `Callout` (`neutral`, `accent`, `warning`, `positive`,
+  `negative`); a quotation is `Quote`. Each takes a faint wash of its colour
+  inside a 1px border of the same colour all round. Large marks follow the same
+  rule: gain and loss bars are a tint inside a full-colour edge, not solid
+  slabs.
+- **Never a stripe down one side.** Do not mark a notice, card, row or quote
+  with a left (or any single-side) coloured border; tint the box or add an
+  icon. 1px neutral dividers between columns are separators, not accents, and
+  are fine.
+- **Edges that matter reach 3:1; the rest stay faint.** A field's edge (input,
+  textarea, select, input group, the command search) is `--input`, at 3:1 on the
+  canvas and the card; dividers, card rings, gridlines and the outlines of
+  buttons, toggles and code blocks are the faint `--border`. Focus is an opaque
+  `--ring`, or the opaque destructive red on a destructive control. A selected
+  toggle or pill tab fills with the foreground. A chart bar that a selection
+  dims keeps its full-colour outline and fades only inside.
+- **Destructive is not loss.** `--destructive` (delete, an invalid field) is a
+  deeper red than `--negative` (a loss figure), so its label reads on its own
+  tint; never use one for the other.
+- Categories (a broker, a sector, an asset class) stay neutral: outline badges,
+  never a hue each. Ordered buckets (largest 5, next 5, rest) use steps of one
+  colour, not separate hues.

package/README.md

@@ -100,10 +100,10 @@ and support one keyboard entry with arrow navigation. `WeekdayHeatmap` accepts
 
 `SiyahiProvider` sets how data blocks sit on the page:
 
-- `surface="ruled"` (default, even outside a provider): unboxed blocks;
-  `PanelGrid` draws hairlines between them.
+- `surface="card"` (default, even outside a provider): each block is a card
+  lifted off a faintly tinted canvas.
+- `surface="ruled"`: unboxed blocks; `PanelGrid` draws hairlines between them.
 - `surface="open"`: no boxes or rules; card padding is removed.
-- `surface="card"`: shadcn's filled Nova cards with a ring.
 
 Nest a provider to change one section. Stack `PageSection` blocks with
 `flex flex-col gap-6`; use `PanelGrid` for blocks side by side. Categories use

package/agents/examples/alert.tsx

@@ -1,5 +1,5 @@
-import { Alert, AlertDescription, AlertTitle } from "@siyahi/ui";
-import { CircleAlertIcon, InfoIcon, TriangleAlertIcon } from "lucide-react";
+import { Alert, AlertDescription, AlertTitle, WarningAlert } from "@siyahi/ui";
+import { CircleAlertIcon, InfoIcon } from "lucide-react";
 
 export default function AlertExample() {
   return (
@@ -9,12 +9,10 @@ export default function AlertExample() {
         <AlertTitle>Prices are delayed</AlertTitle>
         <AlertDescription>Quotes refresh every fifteen minutes during market hours.</AlertDescription>
       </Alert>
-      <Alert>
-        {/* Alert sets its icons to the text colour with a stronger selector; the ! lets the icon's colour win. */}
-        <TriangleAlertIcon className="text-warning!" />
+      <WarningAlert>
         <AlertTitle>Two trades are unmatched</AlertTitle>
         <AlertDescription>The contract notes list trades the ledger does not have yet.</AlertDescription>
-      </Alert>
+      </WarningAlert>
       <Alert variant="destructive">
         <CircleAlertIcon />
         <AlertTitle>Import failed</AlertTitle>

package/agents/examples/app-sidebar.tsx

@@ -32,7 +32,9 @@ export default function AppSidebarExample() {
   return (
     // In an app, AppSidebar sits fixed at the edge; collapsible="none" draws it in place here.
     <SidebarProvider className="min-h-0">
-      <AppSidebar collapsible="none" navMain={views} navLabel="Views" className="rounded-lg border" />
+      <div className="flex overflow-hidden rounded-lg border">
+        <AppSidebar collapsible="none" navMain={views} navLabel="Views" />
+      </div>
     </SidebarProvider>
   );
 }

package/agents/examples/bar-list-sides.tsx

@@ -21,9 +21,19 @@ export default function BarListSidesExample() {
         <CardTitle>What drives the P&L</CardTitle>
         <CardDescription>The biggest ₹ gains and losses, on one scale</CardDescription>
       </CardHeader>
-      <CardContent className="grid gap-6 md:grid-cols-2">
-        <BarList data={gains} max={max} color="var(--positive)" valueFormatter={(v) => money(v)} />
-        <BarList data={losses} max={max} color="var(--negative)" valueFormatter={(v) => money(v)} />
+      {/* Each list is a column of its own, headed and ruled off, with its figures at its own right edge, so a
+          gain's figure never reads as the label of the loss beside it. */}
+      <CardContent>
+        <div className="grid gap-6 md:grid-cols-2 md:gap-0 md:divide-x">
+          <div className="md:pr-6">
+            <h3 className="text-muted-foreground mb-2 text-xs font-medium">Gains</h3>
+            <BarList data={gains} max={max} color="var(--positive)" valueFormatter={(v) => money(v)} />
+          </div>
+          <div className="md:pl-6">
+            <h3 className="text-muted-foreground mb-2 text-xs font-medium">Losses</h3>
+            <BarList data={losses} max={max} color="var(--negative)" valueFormatter={(v) => money(v)} />
+          </div>
+        </div>
       </CardContent>
     </Card>
   );

package/agents/examples/button-states.tsx

@@ -0,0 +1,23 @@
+import { Button, Toggle } from "@siyahi/ui";
+import { DownloadIcon, Loader2Icon, PinIcon } from "lucide-react";
+
+export default function ButtonStatesExample() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button disabled>Save</Button>
+      <Button variant="outline" disabled>
+        <DownloadIcon />
+        Export
+      </Button>
+      {/* Busy: the label stays and the icon spins, so the button keeps its width while the work runs. */}
+      <Button disabled aria-busy>
+        <Loader2Icon className="motion-safe:animate-spin" />
+        Saving
+      </Button>
+      <Toggle variant="outline" defaultPressed aria-label="Pin to top">
+        <PinIcon />
+        Pinned
+      </Toggle>
+    </div>
+  );
+}

package/agents/examples/calendar.tsx

@@ -4,12 +4,8 @@ import { useState } from "react";
 export default function CalendarExample() {
   const [date, setDate] = useState<Date | undefined>(new Date(2026, 9, 20));
   return (
-    <Calendar
-      mode="single"
-      selected={date}
-      onSelect={setDate}
-      defaultMonth={new Date(2026, 9, 1)}
-      className="w-fit rounded-lg border"
-    />
+    <div className="w-fit rounded-lg border">
+      <Calendar mode="single" selected={date} onSelect={setDate} defaultMonth={new Date(2026, 9, 1)} />
+    </div>
   );
 }

package/agents/examples/callout.tsx

@@ -0,0 +1,33 @@
+import { Callout, Quote, WarningAlert, AlertDescription, AlertTitle } from "@siyahi/ui";
+import { LightbulbIcon, InfoIcon, TriangleAlertIcon, TrendingUpIcon, TrendingDownIcon } from "lucide-react";
+
+export default function CalloutExample() {
+  return (
+    <div className="grid max-w-2xl gap-3">
+      <Callout tone="accent" icon={<LightbulbIcon />} title="The takeaway">
+        Two of eleven gold rules made a profit in the final test; <strong>none</strong> held up in both metals.
+      </Callout>
+      <Callout icon={<InfoIcon />} title="How the test was run">
+        One mini lot per trade, after charges and a harsher assumed execution cost.
+      </Callout>
+      <Callout tone="warning" icon={<TriangleAlertIcon />} title="Do not use the combined result">
+        Its test used later information, so its profit claims are withdrawn.
+      </Callout>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <Callout tone="positive" icon={<TrendingUpIcon />} title="Best rule">
+          A failed range break reverses: <strong>▲₹10,616</strong>.
+        </Callout>
+        <Callout tone="negative" icon={<TrendingDownIcon />} title="Worst rule">
+          Break the first-hour range: <strong>▼₹70,679</strong>.
+        </Callout>
+      </div>
+      <Quote source="eMudhra's incident notice, 21 Oct 2026">
+        The affected intermediate keys were generated with insufficient entropy and have been revoked.
+      </Quote>
+      <WarningAlert>
+        <AlertTitle>Ledger history is incomplete</AlertTitle>
+        <AlertDescription>Dhan's cash ledger starts in April 2024; earlier flows are missing.</AlertDescription>
+      </WarningAlert>
+    </div>
+  );
+}

package/agents/examples/card.tsx

@@ -28,7 +28,9 @@ export default function CardExample() {
       <CardContent>
         <p className="text-3xl font-semibold">{money(4512300)}</p>
       </CardContent>
-      <CardFooter className="text-muted-foreground">Updated after the market close</CardFooter>
+      <CardFooter>
+        <p className="text-muted-foreground">Updated after the market close</p>
+      </CardFooter>
     </Card>
   );
 }

package/agents/examples/change-bar.tsx

@@ -0,0 +1,104 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  ChangeBar,
+  DataTable,
+  DataTableBody,
+  DataTableCompactColumnsToggle,
+  DataTableFootnote,
+  DataTableHeader,
+  DataTableRoot,
+  DataTableSortHeader,
+  DataTableToolbarSection,
+  useFormat,
+  type DataTableColumnDef,
+} from "@siyahi/ui";
+
+interface Holding {
+  symbol: string;
+  /** Value at the close of 31 January and of 28 February, in rupees; made-up figures. */
+  january: number;
+  february: number;
+  change: number;
+}
+
+const holding = (symbol: string, january: number, february: number): Holding => ({
+  symbol,
+  january,
+  february,
+  change: february / january - 1,
+});
+
+const holdings: Holding[] = [
+  holding("ICICIBANK", 231900, 258000),
+  holding("HDFCBANK", 248300, 262500),
+  holding("TCS", 161300, 166000),
+  holding("NIFTYBEES", 250400, 255600),
+  holding("ITC", 283100, 276000),
+  holding("INFY", 241800, 224400),
+];
+
+// Every bar is a share of the column's largest move, and the column holds gains and losses, so the bars diverge.
+const largestChange = Math.max(...holdings.map((h) => Math.abs(h.change)));
+const diverging = holdings.some((h) => h.change < 0) && holdings.some((h) => h.change > 0);
+
+function Money({ amount, muted = false }: { amount: number; muted?: boolean }) {
+  const text = useFormat().money(amount);
+  return muted ? <span className="text-muted-foreground">{text}</span> : text;
+}
+
+const header = () => <DataTableSortHeader />;
+
+const columns: DataTableColumnDef<Holding>[] = [
+  { accessorKey: "symbol", header, size: 130, meta: { label: "Holding", compact: true } },
+  {
+    accessorKey: "january",
+    header,
+    size: 130,
+    meta: { label: "31 Jan", variant: "number" },
+    cell: ({ row }) => <Money amount={row.original.january} muted />,
+  },
+  {
+    accessorKey: "february",
+    header,
+    size: 130,
+    meta: { label: "28 Feb", variant: "number", compact: true },
+    cell: ({ row }) => <Money amount={row.original.february} />,
+  },
+  {
+    accessorKey: "change",
+    header,
+    size: 150,
+    meta: { label: "Change", variant: "number", compact: true },
+    cell: ({ row }) => <ChangeBar value={row.original.change} max={largestChange} diverging={diverging} />,
+  },
+];
+
+export default function ChangeBarExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>ICICIBANK rose 11.3% in February, INFY fell 7.2%</CardTitle>
+        <CardDescription>Each holding's value at the end of February against the end of January</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <DataTableRoot data={holdings} columns={columns}>
+          <DataTableToolbarSection>
+            <DataTableCompactColumnsToggle />
+          </DataTableToolbarSection>
+          <DataTable aria-label="February against January">
+            <DataTableHeader />
+            <DataTableBody />
+            <DataTableFootnote>
+              Each percent is the change on January's value, and the bar is its size against the largest move. Gains run
+              right of the centre line, losses left.
+            </DataTableFootnote>
+          </DataTable>
+        </DataTableRoot>
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/chart-area.tsx

@@ -9,18 +9,19 @@ const data = [
   { month: "Oct", value: 4512300, invested: 4025000 },
 ];
 
-// Drawn in this order, so value sits over the money put in.
+// The title states the finding, not the measure: what the reader would say after looking.
+// The first series fills; the money put in draws as a line over it.
 const series: ChartSeries<(typeof data)[number]> = [
-  { key: "invested", label: "Invested", color: "var(--chart-2)" },
   { key: "value", label: "Value", color: "var(--chart-1)" },
+  { key: "invested", label: "Invested", color: "var(--chart-2)" },
 ];
 
 export default function ChartAreaExample() {
   const { money, moneyCompact } = useFormat();
   return (
     <AreaChartCard
-      title="Portfolio value"
-      description="Month-end value against money put in"
+      title="₹4.9L ahead of the money put in"
+      description="Portfolio value against money invested, at each month end"
       action={
         <ToggleGroup defaultValue={["6M"]} variant="outline" size="sm" aria-label="Range">
           <ToggleGroupItem value="6M">6M</ToggleGroupItem>

package/agents/examples/chart-bar-flows.tsx

@@ -8,9 +8,10 @@ const data = [
   { month: "Oct", in: 70000, out: -66000 },
 ];
 
+// Money moving is not a gain or a loss, so in and out take chart colours, not green and red.
 const series: ChartSeries<(typeof data)[number]> = [
-  { key: "in", label: "In", color: "var(--positive)" },
-  { key: "out", label: "Out", color: "var(--negative)" },
+  { key: "in", label: "In", color: "var(--chart-1)" },
+  { key: "out", label: "Out", color: "var(--chart-2)" },
 ];
 
 export default function ChartBarFlowsExample() {

package/agents/examples/chart-bar-sectors.tsx

@@ -60,6 +60,8 @@ export default function ChartBarSectorsExample() {
       xTickDetail={(row) => `${pct(row.you)} vs ${pct(row.index)} · ${gap(row)}`}
       series={series}
       valueFormatter={(v) => pct(v)}
+      // A tick format puts the value axis along the bottom of the sideways bars.
+      yTickFormatter={(v) => pct(v, 0)}
       // Sideways, y is still the value: the axis runs 0 to 40% and the cap is a value level.
       yDomain={[0, 0.4]}
       referenceLines={[{ y: 0.3, label: "cap 30%", labelPosition: "insideBottomRight" }]}

package/agents/examples/collapsible.tsx

@@ -8,8 +8,8 @@ export default function CollapsibleExample() {
         <ChevronsUpDownIcon />
         How lots are matched
       </CollapsibleTrigger>
-      <CollapsibleContent className="text-muted-foreground">
-        Sells are matched to the oldest buy first, as the tax rules require.
+      <CollapsibleContent>
+        <p className="text-muted-foreground">Sells are matched to the oldest buy first, as the tax rules require.</p>
       </CollapsibleContent>
     </Collapsible>
   );

package/agents/examples/command.tsx

@@ -3,25 +3,27 @@ import { ChartLineIcon, LandmarkIcon, WalletIcon } from "lucide-react";
 
 export default function CommandExample() {
   return (
-    <Command className="rounded-lg border">
-      <CommandInput placeholder="Jump to a page" />
-      <CommandList>
-        <CommandEmpty>No page matches.</CommandEmpty>
-        <CommandGroup heading="Pages">
-          <CommandItem>
-            <WalletIcon />
-            Holdings
-          </CommandItem>
-          <CommandItem>
-            <ChartLineIcon />
-            Realized
-          </CommandItem>
-          <CommandItem>
-            <LandmarkIcon />
-            Cash flow
-          </CommandItem>
-        </CommandGroup>
-      </CommandList>
-    </Command>
+    <div className="overflow-hidden rounded-lg border">
+      <Command>
+        <CommandInput placeholder="Jump to a page" />
+        <CommandList>
+          <CommandEmpty>No page matches.</CommandEmpty>
+          <CommandGroup heading="Pages">
+            <CommandItem>
+              <WalletIcon />
+              Holdings
+            </CommandItem>
+            <CommandItem>
+              <ChartLineIcon />
+              Realized
+            </CommandItem>
+            <CommandItem>
+              <LandmarkIcon />
+              Cash flow
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    </div>
   );
 }

package/agents/examples/context-menu.tsx

@@ -3,8 +3,10 @@ import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger }
 export default function ContextMenuExample() {
   return (
     <ContextMenu>
-      <ContextMenuTrigger className="flex h-24 w-full items-center justify-center rounded-lg border border-dashed text-muted-foreground">
-        Right-click or long-press here
+      <ContextMenuTrigger className="w-full">
+        <div className="flex h-24 items-center justify-center rounded-lg border border-dashed text-muted-foreground">
+          Right-click or long-press here
+        </div>
       </ContextMenuTrigger>
       <ContextMenuContent>
         <ContextMenuItem>Copy symbol</ContextMenuItem>

package/agents/examples/data-table-compact.tsx

@@ -0,0 +1,95 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  DataTable,
+  DataTableBody,
+  DataTableCompactColumnsToggle,
+  DataTableHeader,
+  DataTableRoot,
+  DataTableRowCount,
+  DataTableSortHeader,
+  DataTableToolbarSection,
+  Delta,
+  useDataTable,
+  useFormat,
+  type DataTableColumnDef,
+} from "@siyahi/ui";
+
+interface Holding {
+  symbol: string;
+  sector: string;
+  quantity: number;
+  value: number;
+  change: number;
+}
+
+const holdings: Holding[] = [
+  { symbol: "INFY", sector: "IT", quantity: 120, value: 224400, change: 0.018 },
+  { symbol: "HDFCBANK", sector: "Banks", quantity: 150, value: 262500, change: -0.006 },
+  { symbol: "TCS", sector: "IT", quantity: 40, value: 166000, change: 0.004 },
+  { symbol: "ITC", sector: "Fast Moving Consumer Goods", quantity: 600, value: 276000, change: -0.012 },
+];
+
+const header = () => <DataTableSortHeader />;
+
+// While the Day column is hidden to fit, the day's move rides under the value it belongs to.
+function ValueCell({ holding }: { holding: Holding }) {
+  const format = useFormat();
+  const { compactColumns } = useDataTable<Holding>();
+  if (!compactColumns?.hidden.has("change")) return format.money(holding.value);
+  return (
+    <div className="flex flex-col items-end">
+      {format.money(holding.value)}
+      <Delta value={holding.change} />
+    </div>
+  );
+}
+
+const columns: DataTableColumnDef<Holding>[] = [
+  { accessorKey: "symbol", header, size: 140, meta: { label: "Symbol", compact: true } },
+  { accessorKey: "sector", header, size: 120, meta: { label: "Sector" } },
+  { accessorKey: "quantity", header, size: 100, meta: { label: "Qty", variant: "number" } },
+  {
+    accessorKey: "value",
+    header,
+    size: 140,
+    meta: { label: "Value", variant: "number", compact: true },
+    cell: ({ row }) => <ValueCell holding={row.original} />,
+  },
+  {
+    accessorKey: "change",
+    header,
+    size: 110,
+    meta: { label: "Day", variant: "number" },
+    cell: ({ row }) => <Delta value={row.original.change} />,
+  },
+];
+
+export default function DataTableCompactExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Holdings on a phone</CardTitle>
+        <CardDescription>
+          Symbol and value are the key columns. When the columns do not fit, the others hide from the right, and the
+          day's move rides under the value once its column is gone; All columns brings back the rest
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <DataTableRoot data={holdings} columns={columns}>
+          <DataTableToolbarSection>
+            <DataTableCompactColumnsToggle />
+            <DataTableRowCount unit="holdings" />
+          </DataTableToolbarSection>
+          <DataTable aria-label="Holdings on a phone">
+            <DataTableHeader />
+            <DataTableBody />
+          </DataTable>
+        </DataTableRoot>
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/distribution-bar-tug.tsx

@@ -33,28 +33,30 @@ export default function DistributionBarTugExample() {
         <CardTitle>The tug-of-war</CardTitle>
         <CardDescription>Each closed position, losses left of break-even and gains right</CardDescription>
       </CardHeader>
-      <CardContent className="flex flex-col gap-2">
-        <DistributionBar
-          min={-reach}
-          max={reach}
-          showLegend={false}
-          markers={[{ at: 0 }]}
-          highlighted={focus?.name ?? null}
-          onHover={setFocus}
-          segments={positions.map(({ name, value }) => ({
-            name,
-            value,
-            color: value > 0 ? "var(--positive)" : "var(--negative)",
-          }))}
-        />
-        <div className="grid grid-cols-3 text-xs text-muted-foreground tabular-nums">
-          <span>
-            losers <Delta value={lost} format="money" />
-          </span>
-          <span className="text-center">break-even</span>
-          <span className="text-right">
-            winners <Delta value={won} format="money" />
-          </span>
+      <CardContent>
+        <div className="flex flex-col gap-2">
+          <DistributionBar
+            min={-reach}
+            max={reach}
+            showLegend={false}
+            markers={[{ at: 0 }]}
+            highlighted={focus?.name ?? null}
+            onHover={setFocus}
+            segments={positions.map(({ name, value }) => ({
+              name,
+              value,
+              color: value > 0 ? "var(--positive)" : "var(--negative)",
+            }))}
+          />
+          <div className="grid grid-cols-3 text-xs text-muted-foreground tabular-nums">
+            <span>
+              losers <Delta value={lost} format="money" />
+            </span>
+            <span className="text-center">break-even</span>
+            <span className="text-right">
+              winners <Delta value={won} format="money" />
+            </span>
+          </div>
         </div>
       </CardContent>
       <CardFooter className="min-h-12" aria-live="polite">

package/agents/examples/heatmap-calendar.tsx

@@ -3,6 +3,8 @@ import {
   CalendarHeatmap,
   CalendarHeatmapBlock,
   CalendarHeatmapBody,
+  CalendarHeatmapFooter,
+  CalendarHeatmapLegend,
   useFormat,
   Card,
   CardContent,
@@ -18,32 +20,42 @@ const data = Array.from({ length: 365 }, (_, i) => {
   const value = weekday === 0 || weekday === 6 ? 0 : (i * 7 + weekday * 3) % 6;
   return { date: day.toISOString().slice(0, 10), value };
 });
+const busiest = Math.max(...data.map((day) => day.value));
 
 export default function HeatmapCalendarExample() {
-  const [selected, setSelected] = useState<string | null>(null);
+  // The page owns the pick: a second tap on the same day clears it.
+  const [picked, setPicked] = useState<(typeof data)[number] | null>(null);
   const { count } = useFormat();
   return (
     <Card>
       <CardHeader>
         <CardTitle>Trades per day</CardTitle>
-        <CardDescription>Counts use a single-hue fade of --chart-1</CardDescription>
+        <CardDescription>The last 12 months; counts use a single-hue fade of --chart-1</CardDescription>
       </CardHeader>
       <CardContent>
-        <CalendarHeatmap data={data}>
+        <CalendarHeatmap data={data} labels={{ heatmapLabel: "Trades per day over the last 12 months" }}>
           <CalendarHeatmapBody>
             {({ activity, dayIndex, weekIndex }) => (
               <CalendarHeatmapBlock
                 activity={activity}
                 dayIndex={dayIndex}
                 weekIndex={weekIndex}
-                onCellClick={(cell) => setSelected(`${cell.date}: ${count(cell.value)} trades`)}
+                selected={activity.date === picked?.date}
+                onCellClick={(cell) => setPicked(cell.date === picked?.date ? null : cell)}
               />
             )}
           </CalendarHeatmapBody>
+          <CalendarHeatmapFooter className="whitespace-normal">
+            <div className="flex w-full flex-wrap items-center justify-between gap-x-6 gap-y-2">
+              <p aria-live="polite" className="text-sm">
+                {picked
+                  ? `${picked.date}: ${count(picked.value)} trades`
+                  : "Select a day for its trade count. Use arrow keys to move between days."}
+              </p>
+              <CalendarHeatmapLegend labels={{ less: "0 trades", more: `${count(busiest)} trades` }} />
+            </div>
+          </CalendarHeatmapFooter>
         </CalendarHeatmap>
-        <p aria-live="polite" className="mt-3 text-sm">
-          {selected ?? "Select a day for its trade count. Use arrow keys to move between days."}
-        </p>
       </CardContent>
     </Card>
   );