@siyahi/ui 0.1.9-next.23 → 0.1.9-next.25

package/agents/examples/change-grid-money.tsx

@@ -0,0 +1,36 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChangeGrid, type ChangeGridRow } from "@siyahi/ui";
+
+// Profit or loss per store per quarter; made-up figures.
+const quarters = ["Q1", "Q2", "Q3", "Q4"];
+const stores: [string, number[]][] = [
+  ["Koramangala", [412_000, 386_000, 455_000, 520_000]],
+  ["Indiranagar", [218_000, -42_000, 131_000, 264_000]],
+  ["Whitefield", [-86_000, -124_000, 38_000, 61_000]],
+  ["Online", [305_000, 344_000, 398_000, 471_000]],
+  ["Jayanagar", [96_000, -158_000, -212_000, -64_000]],
+];
+const rows: ChangeGridRow[] = stores.map(([label, values]) => ({
+  label,
+  values,
+  total: values.reduce((sum, value) => sum + value, 0),
+}));
+
+export default function ChangeGridMoneyExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Profit by store and quarter</CardTitle>
+        <CardDescription>After rent and wages. The year adds its quarters.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <ChangeGrid
+          label="Profit by store and quarter"
+          columns={quarters}
+          rows={rows}
+          format="money"
+          totalLabel="Year"
+        />
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/change-grid.tsx

@@ -0,0 +1,42 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, ChangeGrid, type ChangeGridRow } from "@siyahi/ui";
+
+// A café chain's sales growth on the month before, per financial year (April to March); made-up figures.
+const months = ["Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "Jan", "Feb", "Mar"];
+const growth: Omit<ChangeGridRow, "total">[] = [
+  {
+    label: "FY24",
+    values: [0.031, 0.012, -0.024, 0.008, 0.017, -0.006, 0.041, 0.052, 0.063, -0.038, 0.004, 0.022],
+  },
+  {
+    label: "FY25",
+    values: [0.018, -0.011, -0.032, 0.014, 0.009, 0, 0.036, 0.047, 0.071, -0.044, -0.008, 0.019],
+  },
+  // The year is under way: months still to come have no figure.
+  {
+    label: "FY26",
+    values: [0.026, 0.015, -0.018, 0.021, 0.012, 0.007, 0.044, null, null, null, null, null],
+  },
+];
+
+// Months compound: a year's growth is the product of (1 + each month), less one.
+const rows: ChangeGridRow[] = growth.map(({ label, values }) => ({
+  label,
+  values,
+  total: values.reduce<number>((year, month) => year * (1 + (month ?? 0)), 1) - 1,
+}));
+
+export default function ChangeGridExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Sales growth by month</CardTitle>
+        <CardDescription>
+          Each month against the one before. Deeper tints are larger changes; the year compounds its months.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <ChangeGrid label="Sales growth by month and financial year" columns={months} rows={rows} totalLabel="Year" />
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/delta.tsx

@@ -2,12 +2,17 @@ import { Delta } from "@siyahi/ui";
 
 export default function DeltaExample() {
   return (
-    <div className="flex flex-wrap items-center gap-6">
-      <Delta value={0.0234} />
-      <Delta value={-0.0108} />
-      <Delta value={0} />
-      <Delta value={18250} format="money" />
-      <Delta value={-4300} format="money" />
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-center gap-6">
+        <Delta value={0.0234} />
+        <Delta value={-0.0108} />
+        <Delta value={0} />
+        <Delta value={18250} format="money" />
+        <Delta value={-4300} format="money" />
+      </div>
+      <p>
+        Revenue was <Delta value={0.031} /> on last month, and refunds <Delta value={-1200} format="money" />.
+      </p>
     </div>
   );
 }

package/agents/examples/drawdown-chart.tsx

@@ -0,0 +1,35 @@
+import { DrawdownChartCard, useFormat } from "@siyahi/ui";
+
+// A bakery's cash balance at the end of each week of 2026: it climbs, falls through the summer when an oven is
+// replaced, and falls again in the quiet weeks of the new year; made-up figures.
+const weeks = Array.from({ length: 52 }, (_, i) => {
+  const date = new Date(Date.UTC(2026, 0, 4 + i * 7));
+  const trend = 600_000 + i * 9_000;
+  const oven = i >= 22 && i < 34 ? -180_000 + (i - 22) * 12_000 : 0;
+  const quiet = i >= 46 ? -(i - 45) * 22_000 : 0;
+  const wobble = ((i * 53) % 17) * 3_000 - 24_000;
+  return { week: date.toISOString().slice(0, 10), balance: trend + oven + quiet + wobble };
+});
+
+const month = (iso: string) => new Date(iso).toLocaleString("en-IN", { month: "short", timeZone: "UTC" });
+const day = (iso: string) =>
+  new Date(iso).toLocaleString("en-IN", { day: "numeric", month: "short", year: "numeric", timeZone: "UTC" });
+
+export default function DrawdownChartExample() {
+  const { money } = useFormat();
+  return (
+    <DrawdownChartCard
+      title="Cash below its best"
+      description="Each week's balance against the highest it had been so far. At zero the bakery was at a new high."
+      data={weeks}
+      xKey="week"
+      levelKey="balance"
+      levelFormatter={money}
+      label="Below its best"
+      xFormatter={month}
+      xTooltipFormatter={(iso) => `Week ending ${day(iso)}`}
+      xTicks={weeks.filter((_, i) => i % 9 === 0).map(({ week }) => week)}
+      height={260}
+    />
+  );
+}

package/agents/examples/heatmap-calendar-signed.tsx

@@ -0,0 +1,67 @@
+import { useState } from "react";
+import {
+  CalendarHeatmap,
+  CalendarHeatmapBlock,
+  CalendarHeatmapBody,
+  CalendarHeatmapFooter,
+  CalendarHeatmapLegend,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  useFormat,
+} from "@siyahi/ui";
+
+// A café's profit or loss each day for six months: weekends earn most, rainy Mondays lose; made-up figures.
+const data = Array.from({ length: 182 }, (_, i) => {
+  const day = new Date(Date.UTC(2026, 4, 1 + i));
+  const weekday = day.getUTCDay();
+  const base = weekday === 0 || weekday === 6 ? 9000 : weekday === 1 ? -2500 : 3000;
+  const swing = ((i * 37) % 23) * 400 - 4400;
+  return { date: day.toISOString().slice(0, 10), value: base + swing };
+});
+
+export default function HeatmapCalendarSignedExample() {
+  const [picked, setPicked] = useState<(typeof data)[number] | null>(null);
+  const { money } = useFormat();
+  const signed = (value: number) => `${value > 0 ? "+" : value < 0 ? "−" : ""}${money(Math.abs(value))}`;
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Profit by day</CardTitle>
+        <CardDescription>
+          May to October. Square green days made money and round red days lost it; deeper is more.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <CalendarHeatmap
+          data={data}
+          signed
+          weekStart={1}
+          labels={{ heatmapLabel: "Profit by day, May to October", cellLabel: "{{date}}: {{value}} rupees" }}
+        >
+          <CalendarHeatmapBody>
+            {({ activity, dayIndex, weekIndex }) => (
+              <CalendarHeatmapBlock
+                activity={activity}
+                dayIndex={dayIndex}
+                weekIndex={weekIndex}
+                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 tabular-nums">
+                {picked ? `${picked.date}: ${signed(picked.value)}` : "Select a day for its profit or loss."}
+              </p>
+              <CalendarHeatmapLegend labels={{ less: "Loss", more: "Profit" }} valueFormatter={money} />
+            </div>
+          </CalendarHeatmapFooter>
+        </CalendarHeatmap>
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/heatmap-status.tsx

@@ -13,10 +13,13 @@ import {
 } from "@siyahi/ui";
 
 // One cell per day for the last 60 days, as a status the heatmap colours:
-// 3 healthy (quiet grey), 2 degraded (--warning), 1 critical (--destructive).
+// 3 healthy (quiet grey), 2 degraded (a half bar in --warning), 1 critical (a full bar in --destructive),
+// 0 no data (a hollow outline).
 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 };
+  // Two days in September the monitor itself was down, so there is no reading: 0.
+  const value = i === 30 || i === 31 ? 0 : i % 17 === 5 ? 1 : i % 11 === 3 ? 2 : 3;
+  return { date: day.toISOString().slice(0, 10), value };
 });
 
 export default function HeatmapStatusExample() {
@@ -30,7 +33,7 @@ export default function HeatmapStatusExample() {
         <CardDescription>Daily health: healthy, degraded or critical</CardDescription>
       </CardHeader>
       <CardContent>
-        <StatusHeatmap data={data} statusValues={[3, 2, 1]}>
+        <StatusHeatmap data={data} statusValues={[3, 2, 1, 0]}>
           <StatusHeatmapBody>
             {({ activity, dayIndex }) => (
               <StatusHeatmapBlock
@@ -48,7 +51,6 @@ export default function HeatmapStatusExample() {
                   ? `${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 />
             </div>
           </StatusHeatmapFooter>

package/agents/examples/histogram-chart.tsx

@@ -0,0 +1,28 @@
+import { HistogramChartCard, useFormat } from "@siyahi/ui";
+
+// 2,000 checkout requests' response times in milliseconds: most are quick, a long tail is slow. Made-up figures from a
+// fixed sequence, so the page draws the same every time.
+let seed = 7;
+const next = () => {
+  seed = (seed * 16807) % 2147483647;
+  return seed / 2147483647;
+};
+const times = Array.from({ length: 2000 }, () => Math.round(80 + 900 * next() ** 3 + 120 * next()));
+
+export default function HistogramChartExample() {
+  const { count } = useFormat();
+  return (
+    <HistogramChartCard
+      title="Checkout response times"
+      description="The last 2,000 requests, counted in 100 ms buckets. Lines mark the median and the 95th percentile."
+      values={times}
+      valueFormatter={(ms) => `${count(ms)} ms`}
+      tickFormatter={count}
+      countLabel="Requests"
+      marks={["median", "p95"]}
+      xLabel="Response time (ms)"
+      yLabel="Requests"
+      height={280}
+    />
+  );
+}

package/agents/examples/scatter-chart-quadrants.tsx

@@ -0,0 +1,63 @@
+import { useState } from "react";
+import { ScatterChartCard, useFormat, type ScatterPoint } from "@siyahi/ui";
+
+// A grocer's products this quarter against last: x is the change in shelf price, y the change in units sold, and
+// size the quarter's revenue; made-up figures. Largest first, so the biggest sellers take the labels.
+const products: ScatterPoint[] = [
+  { name: "Basmati rice 5 kg", x: 0.06, y: -0.04, size: 1_840_000 },
+  { name: "Sunflower oil 1 L", x: -0.08, y: 0.12, size: 1_520_000 },
+  { name: "Full-cream milk", x: 0.03, y: 0.05, size: 1_310_000 },
+  { name: "Atta 10 kg", x: 0.04, y: -0.09, size: 1_120_000 },
+  { name: "Tea 500 g", x: -0.02, y: 0.08, size: 760_000 },
+  { name: "Paneer 200 g", x: 0.09, y: 0.11, size: 640_000 },
+  { name: "Toor dal 1 kg", x: 0.12, y: -0.18, size: 590_000 },
+  { name: "Biscuits family pack", x: -0.05, y: -0.03, size: 420_000 },
+  { name: "Instant noodles", x: 0.01, y: 0.21, size: 380_000 },
+  { name: "Dish soap", x: -0.1, y: -0.07, size: 260_000 },
+  { name: "Ghee 500 ml", x: 0.07, y: 0.02, size: 240_000 },
+  { name: "Coffee 200 g", x: -0.04, y: 0.15, size: 190_000 },
+];
+
+export default function ScatterChartQuadrantsExample() {
+  const [selected, setSelected] = useState<ScatterPoint | null>(null);
+  const { moneyCompact, pct } = useFormat();
+  const signed = (value: number) => `${value > 0 ? "+" : value < 0 ? "−" : ""}${pct(Math.abs(value))}`;
+  return (
+    <ScatterChartCard
+      title="Products by price and sales"
+      description="This quarter against last. Across is the change in shelf price, up the change in units sold; a dot's area is the quarter's revenue."
+      points={products}
+      height={380}
+      xLabel="Change in price"
+      yLabel="Change in units sold"
+      xFormatter={signed}
+      yFormatter={signed}
+      sizeLabel="Revenue"
+      sizeFormatter={(value) => moneyCompact(value)}
+      selected={selected}
+      onSelect={setSelected}
+      footer={
+        <p data-slot="scatter-selection" aria-live="polite" className="tabular-nums">
+          {selected ? (
+            <>
+              <span className="font-medium">{selected.name}</span> · price {signed(selected.x)} · units{" "}
+              {signed(selected.y ?? 0)} · {moneyCompact(selected.size ?? 0)} revenue
+            </>
+          ) : (
+            <span className="text-muted-foreground">Tap a dot, or Tab to the chart and use the arrow keys</span>
+          )}
+        </p>
+      }
+      quadrants={{
+        x: 0,
+        y: 0,
+        labels: {
+          topLeft: "Cheaper, selling more",
+          topRight: "Dearer, still selling more",
+          bottomLeft: "Cheaper, selling less",
+          bottomRight: "Dearer, selling less",
+        },
+      }}
+    />
+  );
+}

package/agents/examples/scatter-chart.tsx

@@ -0,0 +1,75 @@
+import { ScatterChartCard, useFormat, type ScatterPoint } from "@siyahi/ui";
+import { useState } from "react";
+
+interface Store extends ScatterPoint {
+  region: string;
+  sales: number;
+}
+
+// x is the store's share of the month's sales and y its growth on the same month last year; the numbers are made up
+// for the catalogue. The Guwahati store opened this year, so it has no growth to plot. Largest first, so the biggest
+// stores take the labels.
+const stores: Store[] = [
+  { name: "Delhi Saket", region: "North", x: 0.112, y: 0.27, sales: 2760000 },
+  { name: "Bengaluru MG", region: "South", x: 0.106, y: -0.06, sales: 2625000 },
+  { name: "Chennai T Nagar", region: "South", x: 0.104, y: 0.44, sales: 2580000 },
+  { name: "Kolkata Park St", region: "East", x: 0.103, y: 0.16, sales: 2556000 },
+  { name: "Mumbai Online", key: "mumbai-online", region: "West", x: 0.091, y: 0.38, sales: 2244000 },
+  { name: "Pune Camp", region: "West", x: 0.067, y: 0.09, sales: 1660000 },
+  { name: "Mumbai Bandra", key: "mumbai-bandra", region: "West", x: 0.061, y: 0.12, sales: 1520000 },
+  { name: "Hyderabad", region: "South", x: 0.052, y: -0.14, sales: 1290000 },
+  { name: "Ahmedabad", region: "West", x: 0.044, y: 0.05, sales: 1090000 },
+  { name: "Surat", region: "West", x: 0.04, y: -0.21, sales: 980000 },
+  { name: "Kochi", region: "South", x: 0.035, y: 0.58, sales: 870000 },
+  { name: "Lucknow", region: "North", x: 0.031, y: -0.02, sales: 770000 },
+  { name: "Jaipur", region: "North", x: 0.026, y: -0.33, sales: 640000 },
+  { name: "Bhubaneswar", region: "East", x: 0.021, y: 0.22, sales: 520000 },
+  { name: "Indore", region: "Central", x: 0.018, y: 0.31, sales: 450000 },
+  { name: "Bhopal", region: "Central", x: 0.012, y: -0.09, sales: 300000 },
+  { name: "Patna", region: "East", x: 0.009, y: 0.47, sales: 220000 },
+  { name: "Nagpur", region: "Central", x: 0.007, y: 0.02, sales: 170000 },
+  { name: "Shillong", region: "Northeast", x: 0.004, y: -0.18, sales: 100000 },
+  { name: "Guwahati", region: "Northeast", x: 0.021, y: null, sales: 520000 },
+];
+
+export default function ScatterChartExample() {
+  const [selected, setSelected] = useState<Store | null>(null);
+  const { money, pct } = useFormat();
+  const growth = (y: number | null) => (y === null ? "new this year" : `${y < 0 ? "−" : "+"}${pct(Math.abs(y))}`);
+  const missing = stores.filter((s) => s.y === null).length;
+  return (
+    <ScatterChartCard
+      title="Stores by size and growth"
+      description="Across is the store's share of sales (log scale), up its growth on last year. Hover or tap a dot."
+      points={stores}
+      height={360}
+      xLabel="Share of sales"
+      yLabel="Growth"
+      xScale="log"
+      xFormatter={(x) => pct(x)}
+      yFormatter={(y) => growth(y)}
+      details={(s) => [
+        ["Region", s.region],
+        ["Sales", money(s.sales)],
+        ["Growth", growth(s.y)],
+      ]}
+      selected={selected}
+      onSelect={setSelected}
+      footer={
+        <>
+          <p data-slot="scatter-selection" aria-live="polite" className="tabular-nums">
+            {selected ? (
+              <>
+                <span className="font-medium">{selected.name}</span> · {selected.region} · {money(selected.sales)} ·{" "}
+                {growth(selected.y)}
+              </>
+            ) : (
+              <span className="text-muted-foreground">Tap a dot for its figures</span>
+            )}
+          </p>
+          <p className="text-muted-foreground">{missing} store opened this year and has no growth to plot.</p>
+        </>
+      }
+    />
+  );
+}

package/agents/examples/slope-chart-market.tsx

@@ -0,0 +1,33 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, SlopeChart, type SlopeItem } from "@siyahi/ui";
+
+// Each aisle's share of one grocery store's sales against its share across the region's stores; made-up figures.
+const items: SlopeItem[] = [
+  { name: "Fresh fruit and vegetables", from: 0.18, to: 0.24 },
+  { name: "Dairy and eggs", from: 0.14, to: 0.15 },
+  { name: "Bakery", from: 0.07, to: 0.11 },
+  { name: "Rice, flour and pulses", from: 0.16, to: 0.12 },
+  { name: "Snacks and drinks", from: 0.15, to: 0.13 },
+  { name: "Household and cleaning", from: 0.11, to: 0.08 },
+  { name: "Personal care", from: 0.09, to: 0.08 },
+  { name: "Frozen food", from: 0.06, to: 0.05 },
+  { name: "Baby care", from: 0.04, to: 0.04 },
+];
+
+// The aisles at least three points away from the region, either way.
+const apart = items.filter(({ from, to }) => Math.abs(to - from) >= 0.03).map(({ name }) => name);
+
+export default function SlopeChartMarketExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Our aisles against the region</CardTitle>
+        <CardDescription>
+          Share of sales by aisle. Aisles three points or more away from the region are drawn in colour.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <SlopeChart items={items} fromLabel="Region" toLabel="This store, this year" highlighted={apart} />
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/slope-chart.tsx

@@ -0,0 +1,26 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, SlopeChart, type SlopeItem } from "@siyahi/ui";
+
+// Each channel's share of a bookshop's sales, last year and this; made-up figures.
+const items: SlopeItem[] = [
+  { name: "In store", from: 0.46, to: 0.38 },
+  { name: "Own website", from: 0.18, to: 0.27 },
+  { name: "Marketplaces", from: 0.21, to: 0.2 },
+  { name: "Schools and libraries", from: 0.09, to: 0.1 },
+  { name: "Events and fairs", from: 0.06, to: 0.05 },
+];
+
+export default function SlopeChartExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Sales by channel</CardTitle>
+        <CardDescription>
+          Each channel's share of the year's sales. The website gained what the shop lost.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <SlopeChart items={items} fromLabel="2025" toLabel="2026" highlighted={["In store", "Own website"]} />
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/waterfall-chart-stores.tsx

@@ -0,0 +1,27 @@
+import { WaterfallChartCard, useFormat, type WaterfallStep } from "@siyahi/ui";
+
+// Revenue from last year to this, store by store; made-up figures.
+const steps: WaterfallStep[] = [
+  { kind: "total", label: "Last year", value: 4_820_000 },
+  { kind: "change", label: "Koramangala flagship", value: 640_000 },
+  { kind: "change", label: "Indiranagar high street", value: 310_000 },
+  { kind: "change", label: "Whitefield mall kiosk", value: -420_000 },
+  { kind: "change", label: "Online orders and delivery", value: 880_000 },
+  { kind: "change", label: "Jayanagar (closed in June)", value: -560_000 },
+  { kind: "total", label: "This year" },
+];
+
+export default function WaterfallChartStoresExample() {
+  const { money, moneyCompact } = useFormat();
+  return (
+    <WaterfallChartCard
+      title="Revenue, last year to this"
+      description="What each store added or lost on the way from last year's total to this year's"
+      steps={steps}
+      horizontal
+      valueFormatter={money}
+      yTickFormatter={moneyCompact}
+      height={steps.length * 48 + 64}
+    />
+  );
+}

package/agents/examples/waterfall-chart.tsx

@@ -0,0 +1,37 @@
+import { WaterfallChartCard, useFormat, type WaterfallStep } from "@siyahi/ui";
+
+// A bakery's profit for the year, April to March, month by month; made-up figures.
+const months: [string, number][] = [
+  ["Apr", 42000],
+  ["May", 38000],
+  ["Jun", -12000],
+  ["Jul", 26000],
+  ["Aug", 31000],
+  ["Sep", -8000],
+  ["Oct", 54000],
+  ["Nov", 61000],
+  ["Dec", 72000],
+  ["Jan", -21000],
+  ["Feb", 18000],
+  ["Mar", 35000],
+];
+const steps: WaterfallStep[] = [
+  ...months.map(([label, value]): WaterfallStep => ({ kind: "change", label, value })),
+  // No value: the year's total is wherever the months left it.
+  { kind: "total", label: "Year" },
+];
+
+export default function WaterfallChartExample() {
+  const { money, moneyCompact } = useFormat();
+  return (
+    <WaterfallChartCard
+      title="Profit for the year, month by month"
+      description="April to March, before tax. Each bar starts where the month before left off."
+      steps={steps}
+      labels={{ rise: "Profit", fall: "Loss", total: "Year to date" }}
+      valueFormatter={money}
+      yTickFormatter={moneyCompact}
+      height={300}
+    />
+  );
+}