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

package/DESIGN.md

@@ -0,0 +1,30 @@
+# 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, always with ▲ or ▼ (`Delta`).
+  **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.
+- 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/bar-list-sides.tsx

@@ -21,9 +21,17 @@ 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 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>
       </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/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/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/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/heatmap-calendar.tsx

@@ -3,6 +3,8 @@ import {
   CalendarHeatmap,
   CalendarHeatmapBlock,
   CalendarHeatmapBody,
+  CalendarHeatmapFooter,
+  CalendarHeatmapLegend,
   useFormat,
   Card,
   CardContent,
@@ -18,32 +20,40 @@ 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="items-center justify-between gap-x-6 gap-y-2 whitespace-normal">
+            <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` }} />
+          </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>
   );

package/agents/examples/heatmap-status.tsx

@@ -8,17 +8,20 @@ import {
   StatusHeatmap,
   StatusHeatmapBlock,
   StatusHeatmapBody,
+  StatusHeatmapFooter,
+  StatusHeatmapLegend,
 } from "@siyahi/ui";
 
 // One cell per day for the last 60 days, as a status the heatmap colours:
-// 3 healthy (--positive), 2 degraded (--warning), 1 critical (--negative).
+// 3 healthy (quiet grey), 2 degraded (--warning), 1 critical (--destructive).
 const data = Array.from({ length: 60 }, (_, i) => {
   const day = new Date(Date.UTC(2026, 7, 22 + i));
   return { date: day.toISOString().slice(0, 10), value: i % 17 === 5 ? 1 : i % 11 === 3 ? 2 : 3 };
 });
 
 export default function HeatmapStatusExample() {
-  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);
 
   return (
     <Card>
@@ -27,24 +30,27 @@ export default function HeatmapStatusExample() {
         <CardDescription>Daily health: healthy, degraded or critical</CardDescription>
       </CardHeader>
       <CardContent>
-        <StatusHeatmap data={data}>
+        <StatusHeatmap data={data} statusValues={[3, 2, 1]}>
           <StatusHeatmapBody>
             {({ activity, dayIndex }) => (
               <StatusHeatmapBlock
                 activity={activity}
                 dayIndex={dayIndex}
-                onCellClick={(cell) =>
-                  setSelected(
-                    `${cell.date}: ${["unknown", "critical", "degraded", "healthy"][cell.value] ?? "unknown"}`,
-                  )
-                }
+                selected={activity.date === picked?.date}
+                onCellClick={(cell) => setPicked(cell.date === picked?.date ? null : cell)}
               />
             )}
           </StatusHeatmapBody>
+          <StatusHeatmapFooter className="items-center justify-between gap-x-6 gap-y-2 whitespace-normal">
+            <p aria-live="polite" className="text-sm">
+              {picked
+                ? `${picked.date}: ${["unknown", "critical", "degraded", "healthy"][picked.value] ?? "unknown"}`
+                : "Select a day for its health. Use arrow keys to move between days."}
+            </p>
+            {/* No day lacks data, so the legend leaves out "No Data". */}
+            <StatusHeatmapLegend className="gap-3" />
+          </StatusHeatmapFooter>
         </StatusHeatmap>
-        <p aria-live="polite" className="mt-3 text-sm">
-          {selected ?? "Select a day for its health. Use arrow keys to move between days."}
-        </p>
       </CardContent>
     </Card>
   );

package/agents/examples/heatmap-weekday.tsx

@@ -9,6 +9,7 @@ import {
   WeekdayHeatmap,
   WeekdayHeatmapBlock,
   WeekdayHeatmapBody,
+  WeekdayHeatmapLegend,
 } from "@siyahi/ui";
 
 // Orders placed by weekday and hour of the trading session.
@@ -19,9 +20,15 @@ const data = [1, 2, 3, 4, 5].flatMap((weekday) =>
     value: ((weekday * 5 + hour * 3) % 9) + (hour === 9 ? 6 : 0),
   })),
 );
+const busiest = data.reduce((top, cell) => (cell.value > top.value ? cell : top));
+const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const hourLabel = (hour: number) => `${String(hour).padStart(2, "0")}:00`;
 
 export default function HeatmapWeekdayExample() {
-  const [selected, setSelected] = useState<string | null>(null);
+  // The page owns the pick: a second tap on the same cell clears it.
+  const [picked, setPicked] = useState<(typeof data)[number] | null>(null);
+  const isPicked = (cell: { weekday: number; hour: number }) =>
+    cell.weekday === picked?.weekday && cell.hour === picked.hour;
   const { count } = useFormat();
   return (
     <Card>
@@ -29,24 +36,39 @@ export default function HeatmapWeekdayExample() {
         <CardTitle>When orders are placed</CardTitle>
         <CardDescription>Weekday by hour in India Standard Time, market hours only</CardDescription>
       </CardHeader>
+      {/* Seven hours by five days is a small grid: capped, it keeps square cells, and the legend and the answer
+          sit beside it instead of a wide empty card. */}
       <CardContent>
-        <WeekdayHeatmap data={data} hours={[9, 10, 11, 12, 13, 14, 15]} weekdays={[1, 2, 3, 4, 5]}>
-          <WeekdayHeatmapBody>
+        <WeekdayHeatmap
+          data={data}
+          hours={[9, 10, 11, 12, 13, 14, 15]}
+          weekdays={[1, 2, 3, 4, 5]}
+          className="gap-4 lg:flex-row lg:items-center lg:gap-8"
+        >
+          <WeekdayHeatmapBody className="lg:w-md lg:shrink-0">
             {({ activity }) => (
               <WeekdayHeatmapBlock
                 activity={activity}
-                onCellClick={(cell) =>
-                  setSelected(
-                    `${["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"][cell.weekday]}, ${String(cell.hour).padStart(2, "0")}:00 IST: ${count(cell.value)} orders`,
-                  )
-                }
+                selected={isPicked(activity)}
+                onCellClick={(cell) => setPicked(isPicked(cell) ? null : cell)}
               />
             )}
           </WeekdayHeatmapBody>
+          <div className="flex flex-col items-start gap-3 text-sm">
+            <WeekdayHeatmapLegend
+              className="ml-0"
+              labels={{ less: "0 orders", more: `${count(busiest.value)} orders an hour` }}
+            />
+            <p>
+              Busiest: {DAYS[busiest.weekday]} at {hourLabel(busiest.hour)}, {count(busiest.value)} orders
+            </p>
+            <p aria-live="polite" className="text-muted-foreground">
+              {picked
+                ? `${DAYS[picked.weekday]}, ${hourLabel(picked.hour)} IST: ${count(picked.value)} orders`
+                : "Select a cell for its order count. Use arrow keys to move between cells."}
+            </p>
+          </div>
         </WeekdayHeatmap>
-        <p aria-live="polite" className="mt-3 text-sm">
-          {selected ?? "Select a cell for its order count. Use arrow keys to move between cells."}
-        </p>
       </CardContent>
     </Card>
   );

package/agents/examples/input-states.tsx

@@ -0,0 +1,33 @@
+import { Input } from "@siyahi/ui";
+
+// A field is its label, the input and one line under it: a hint, or the error that replaces it.
+export default function InputStatesExample() {
+  return (
+    <div className="grid max-w-sm gap-5">
+      <div className="grid gap-1.5">
+        <label htmlFor="budget" className="text-sm font-medium">
+          Monthly budget
+        </label>
+        <Input id="budget" inputMode="numeric" defaultValue="25,000" aria-describedby="budget-hint" />
+        <p id="budget-hint" className="text-sm text-muted-foreground">
+          In rupees, before brokerage
+        </p>
+      </div>
+      <div className="grid gap-1.5">
+        <label htmlFor="folio" className="text-sm font-medium">
+          Folio number
+        </label>
+        <Input id="folio" defaultValue="12/34" aria-invalid aria-describedby="folio-error" />
+        <p id="folio-error" className="text-sm text-destructive">
+          A folio is digits only, such as 1234567
+        </p>
+      </div>
+      <div className="grid gap-1.5">
+        <label htmlFor="broker" className="text-sm font-medium text-muted-foreground">
+          Broker
+        </label>
+        <Input id="broker" defaultValue="Kite" disabled />
+      </div>
+    </div>
+  );
+}

package/agents/examples/metric-strip.tsx

@@ -19,13 +19,19 @@ export default function MetricStripExample() {
       trend: [3600000, 3685000, 3770000, 3855000, 3940000, 4025000],
     },
     { label: "XIRR", value: pct(0.142), change: -0.004, trend: [0.151, 0.149, 0.152, 0.144, 0.146, 0.142] },
-    { label: "Realised", value: moneyCompact(-61200), change: -61200, changeFormat: "money" },
+    {
+      label: "Realised",
+      value: moneyCompact(-61200),
+      change: -61200,
+      changeFormat: "money",
+      trend: [14200, -3800, 9100, 2600, -18400, -61200],
+    },
     { label: "Dividends", value: moneyCompact(38400), change: 0.18, trend: [4100, 0, 12800, 3300, 9900, 8300] },
-    { label: "Holdings", value: count(42), note: "3 bought in Oct" },
+    { label: "Holdings", value: count(42), note: "3 bought in Oct", trend: [38, 39, 39, 40, 39, 42] },
   ];
   return (
     <MetricStrip
-      title="October"
+      title="Portfolio up 3.1% in October"
       description="Month-end figures with the six-month run behind each"
       action={
         <ToggleGroup defaultValue={["1M"]} variant="outline" size="sm" aria-label="Period">