@siyahi/ui 0.1.9-next.17 → 0.1.9-next.18

package/README.md

@@ -2,20 +2,31 @@
 
 # Siyahi
 
-Siyahi (Hindi for ink) is a small design system for data-heavy React apps:
-stock [shadcn/ui](https://ui.shadcn.com) on [Base UI](https://base-ui.com) and
-Tailwind CSS v4, shipped as one npm package, `@siyahi/ui`. It adds a theme with
-four meaning colours and a five-hue chart palette that pass WCAG contrast in
-light and dark, a few finance components, locale-aware formatters, a lint that
-keeps pages on the theme, and a catalogue site that is the documentation.
+A design system for data-heavy React apps: [shadcn/ui](https://ui.shadcn.com)
+on [Base UI](https://base-ui.com) and Tailwind CSS v4, with a shared theme,
+charts, tables and locale-aware formatters. Components ship in `@siyahi/ui`;
+checks and build helpers ship in `@siyahi/tools`.
 
-**Catalogue:** https://siyahi.jatinbansal.com
+**[Browse the catalogue](https://siyahi.jatinbansal.com)** for components and live examples.
+
+## For agents
+
+Install the public [Siyahi skill](https://github.com/jatinbansal1998/siyahi/blob/main/skills/siyahi/SKILL.md):
+
+```sh
+npx skills add jatinbansal1998/siyahi --skill siyahi --agent claude-code --agent codex
+```
+
+Read the installed package's `agents/manifest.json` to select components and
+recipes, then only the matching `agents/examples/*.tsx`. Exact prop types are in
+`dist/index.d.ts`. The skill guides reuse and verification; page structure and
+interactions remain yours. No other skill or local Siyahi checkout is required.
 
 ## Install
 
-Siyahi is pre-1.0; releases go out under the `next` tag. It needs React 19 and
-Tailwind CSS v4, compiled by the Tailwind Vite plugin: the package's stylesheet
-is Tailwind source, so a plain CSS import leaves every component unstyled.
+Releases use the `next` tag until 1.0. Siyahi needs React 19 and Tailwind CSS v4.
+Compile its stylesheet with the Tailwind Vite plugin; a plain CSS import leaves
+components unstyled.
 
 ```sh
 npm install @siyahi/ui@next tailwindcss @tailwindcss/vite
@@ -23,7 +34,7 @@ npm install --save-dev @siyahi/tools@next
 ```
 
 ```ts
-// vite.config.ts
+// vite.config.ts: add to your existing plugins
 import tailwindcss from "@tailwindcss/vite";
 import { preloadFonts } from "@siyahi/tools/vite";
 export default defineConfig({ plugins: [react(), tailwindcss(), preloadFonts()] });
@@ -45,234 +56,93 @@ createRoot(root).render(
 );
 ```
 
-`preloadFonts()` adds `<link rel="preload">` tags for Geist and Geist Mono to
-the built `index.html`, so the fonts download with the scripts instead of after
-the first paint. Until they arrive the theme draws Arial (or its Linux twins,
-Liberation Sans and Arimo) scaled to Geist's metrics, so nothing moves when
-Geist swaps in. An app that renders its own HTML adds the tags itself, with
-the hashed URLs of `geist-latin-wght-normal.woff2`,
-`geist-latin-ext-wght-normal.woff2` and `geist-mono-latin-wght-normal.woff2`.
-
-Everything comes from `@siyahi/ui`: the shadcn components, the registry
-add-ons (chart cards, data table, heatmaps, stat tiles, sidebar) and Siyahi's
-own components. Add `lucide-react` only if your
-own code imports icons. A Next.js app compiles the same stylesheet through
-`@tailwindcss/postcss` instead of the Vite plugin.
-
-### Also on GitHub releases
-
-Each explicit release from `main` also attaches both tarballs to a GitHub release
-(`v<version>`, plus a rolling `next`). They are a fallback if npm is unreachable:
-`npm install --allow-remote=root https://github.com/jatinbansal1998/siyahi/releases/download/v<version>/siyahi-ui-<version>.tgz`.
-
-## What is in it
-
-- **shadcn/ui components** in the `base-nova` style, shadcn's flat and compact
-  one, installed with the shadcn CLI and never edited.
-- **Registry add-ons**, copied once with their origin and licence recorded:
-  bar, area and line chart cards from shadcn's chart blocks, a data table on
-  TanStack Table, calendar, weekday and status heatmaps, a ranked
-  bar list, a `Sparkline`, the `MetricStrip` row of figures, the
-  `SectionCards` stat tile and the `sidebar-07` app shell.
-- **Siyahi components**: `Delta` (a signed figure with ▲ ▼), `PriceChart`
-  (TradingView Lightweight Charts in theme colours), `Treemap` (holdings heat
-  map; hover or tap a tile for its figures) with `TreemapLegend` (its colour
-  scale), `LocalTime` (a time in the configured zone with the viewer's own clock
-  in a tooltip), `ToneProgress` (Progress in a meaning colour), the page parts
-  `PageSection`, `PageSubheading`, `DataList` and `InlineCode`, the data table
-  parts `DataTableSortHeader` (sorts on one click) and `DataTableRowCount`
-  ("12 of 48"), `DataBar` (a figure in a table cell with a bar giving its size
-  against the column's largest), `PanelGrid` (data blocks side by side, with
-  hairlines between them on a ruled page), and `SiyahiProvider`.
-- **Surfaces**: by default a data block has no box. Every `Card` on a ruled
-  page, chart cards and stat tiles included, loses its fill, corner and ring,
-  and a `PanelGrid` draws hairlines between blocks; see Surfaces below. A
-  category (a sector, a
-  broker, a unit's kind) is an outline `Badge`: categories stay neutral, and
-  colour is left to the four meaning colours and the charts. On a narrow card
-  (header under 24rem, so any phone) a header action such as a toggle drops
-  under the title and description, left-aligned; a stat tile's badge stays
-  top right.
-- **Formatters**: `count`, `money`, `moneyCompact`, `pct` and `time`, or `useFormat()`
-  for the same bound to the provider's locale.
-  `useFormat().time(value, { withDate: true })` (or
-  `time(value, locale, { withDate: true })`) and `<LocalTime withDate>` write
-  the date first: `20 Oct 2026, 14:30 IST`.
-- **`report.css`** for static HTML reports that do not use React: the theme as
-  plain CSS variables plus base body styles, with no network requests.
-
-## Which component
-
-| Need                                                                    | Component                                                           |
-| ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| Values over time or another ordered axis (months, hours, price buckets) | `BarChartCard`, `AreaChartCard` or `LineChartCard`                  |
-| Counts or amounts per period, one series or several                     | `BarChartCard`; `stacked` when the series add up to a total         |
-| A running level, such as a portfolio's value against money put in       | `AreaChartCard`                                                     |
-| Series compared point by point, such as a return against an index       | `LineChartCard`                                                     |
-| Samples in time with limits and events marked                           | `LineChartCard` with `xDomain`, `xTicks` and `referenceLines`       |
-| Long category names, such as sectors                                    | `BarChartCard` with `horizontal`                                    |
-| A gain above zero and a loss below it                                   | a series with `color` and `negativeColor`                           |
-| Ranked counts or amounts by category (a name, a bar and a figure)       | `BarList`; give two lists one `max` to share a scale                |
-| Where a budget sits, a split of a whole, or losses against gains        | `DistributionBar`                                                   |
-| Headline figures with their change                                      | `SectionCards`, with a `Delta` in each badge                        |
-| Many figures of equal weight, each with its change and recent run       | `MetricStrip`                                                       |
-| A run of values beside a figure, in a tile, a strip or a table cell     | `Sparkline`; in a tile, `SectionCards`' `trend`                     |
-| A table column that should read as a bar chart                          | `DataBar` in the column's cell                                      |
-| One instrument's price history                                          | `PriceChart`                                                        |
-| Holdings sized by weight and coloured by change                         | `Treemap`                                                           |
-| Activity by day, by weekday and hour, or a status over time             | `CalendarHeatmap`, `WeekdayHeatmap`, `StatusHeatmap`                |
-| Rows to sort and filter                                                 | `DataTable`, inside a `Card`                                        |
-| A column that sorts on one click; a search and an "n of m" count        | `DataTableSortHeader`; `DataTableSearchFilter`, `DataTableRowCount` |
-| Stat tiles that pick a scope for the page                               | `SectionCards` with `selected` and `onSelect`                       |
-| A share or a part of a whole, coloured as a gain or a loss              | `ToneProgress`                                                      |
-| The colour scale under a `Treemap`                                      | `TreemapLegend`, with the map's `range`                             |
-| One part of a long page: rule, eyebrow, heading, lead, action           | `PageSection`, with `PageSubheading` inside                         |
-| Label and value pairs, such as a record's fields                        | `DataList` and `DataListItem`                                       |
-| A command or file to copy, wrapped or scrolling                         | `CodeBlock` with `CodeBlockCopyButton`                              |
-| A labelled copy action, such as "Copy all" for a section                | `CopyButton`                                                        |
-| Data blocks side by side: charts, tables, a strip of figures            | `PanelGrid`                                                         |
-| Boxes back, or no lines at all, for a page or a part of one             | `SiyahiProvider` with `surface="card"` or `surface="open"`          |
-| A command, file or identifier inside prose                              | `InlineCode`                                                        |
-| A signed figure (a gain, a loss, a change)                              | `Delta`                                                             |
-| A time, with the viewer's own clock on hover                            | `LocalTime`                                                         |
-
-The three chart cards take the rows, the field the x axis reads and the series,
-and own everything else: the card and its header action (a range or mode
-toggle), the axes, the dashed horizontal grid, Geist Mono ticks, a tooltip that
-names the hovered point and gives each series' formatted value, and the legend
-below. Props cover the rest: a footer, a placeholder while data loads,
-reference lines, a numeric x axis, a fixed value axis, axis titles, a second
-line under each tick, a picked category, sideways bars and straight segments.
-A page never puts Recharts axes, grids or tooltips together itself.
+`preloadFonts()` loads Geist and Geist Mono with the scripts. Add `lucide-react`
+only when your own code imports icons. Next.js compiles the stylesheet through
+`@tailwindcss/postcss` instead of the Vite plugin. Static HTML reports inline the
+package's `report.css` and follow `agents/report-rules.json`.
 
-```tsx
-<BarChartCard
-  title="Orders by hour"
-  data={[
-    { hour: 9, orders: 42 },
-    { hour: 10, orders: 31 },
-  ]}
-  xKey="hour"
-  xFormatter={(hour) => `${String(hour).padStart(2, "0")}:00`}
-  series={[{ key: "orders", label: "Orders", color: "var(--chart-1)" }]}
-  height={256}
-/>
-```
+If npm is unreachable, both package tarballs are attached to
+[GitHub releases](https://github.com/jatinbansal1998/siyahi/releases).
 
 ## Locale
 
-Numbers, money and times default to Indian English, rupees and IST:
-`₹1,53,110`, `₹2.4L`, `₹40Cr`, `14:30 IST`. In an Indian-region locale,
-`moneyCompact` prints amounts under one lakh in full (`₹99,999`), never as `K`.
-Pass another locale to the provider and every formatter and component under it
-follows:
+`useFormat()` provides `count`, `money`, `moneyCompact`, `pct` and `time`,
+bound to the provider's locale. Defaults are Indian English, rupees and India
+Standard Time: `₹1,53,110`, `₹2.4L`, `14:30 IST`. Use `Delta` for signed changes.
+Override the locale for a whole app or a nested section:
 
 ```tsx
 <SiyahiProvider locale={{ numberLocale: "en-US", currency: "USD", timeZone: "America/New_York" }}>
 ```
 
-The formatters print a minus sign and nothing else. A signed figure (a gain, a
-loss, a change) goes through `<Delta>`, which adds ▲ or ▼ and the meaning
-colour. Time zone names come from the runtime's ICU data; a slim Node or
-browser build may print `GMT+5:30` where a full one prints `IST`.
+## Responsive behavior
 
-## Surfaces
+Data tables suspend horizontal freezing below 40rem of their own available
+space, including narrow panels on a laptop. Pinning preferences, search, sort,
+selection and expansion stay intact. All columns remain reachable by scrolling;
+the scrolling region also accepts keyboard focus. For page-specific compact
+records, choose essential columns and keep every other field in accessible
+details or an explicit full-table view.
 
-A data block sits on the page in one of three ways, set by `SiyahiProvider`'s
-`surface`:
+The shipped `data-table-filters` recipe moves secondary filters into a `Sheet`
+using `useDataTable().isCompact`. Configure filtering explicitly when its
+controls render conditionally. Keep search and the active-filter count visible.
+Use container queries for layout and pointer capability for touch targets;
+a touch laptop needs the same reachable controls as a phone.
 
-- `"ruled"`, the default: no box. Every `Card` loses its fill, corner and ring,
-  and blocks side by side in a `PanelGrid` are parted by hairlines, with a rule
-  above and below the grid. One surface, as on a trading screen.
-- `"open"`: no box and no lines. The card's padding goes too, so a block's
-  content sits level with the page's text; for pages read top to bottom.
-- `"card"`: shadcn's own Nova card, a filled box with a 1px ring.
+Ranked lists wrap long labels in narrow panels. Horizontal charts reserve space
+for bars and wrap their category labels; exact axis ticks keep their normal
+text size and scroll when necessary. Heatmap examples expose values on selection
+and support one keyboard entry with arrow navigation. `WeekdayHeatmap` accepts
+`hours` and `weekdays` to show a relevant domain without changing data labels.
 
-A component outside any provider is ruled. A nested provider sets the surface
-for one part of a page. A picked `SectionCards` tile keeps its ring on every
-surface.
+## Surfaces
 
-```tsx
-<SiyahiProvider surface="open">
-  <PageSection title="Why XIRR fell">…</PageSection>
-</SiyahiProvider>
-```
+`SiyahiProvider` sets how data blocks sit on the page:
+
+- `surface="ruled"` (default, even outside a provider): 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.
 
-Pages are dense. A `PageSection` sits 24px under its rule with 16px to its
-content, so stack sections 24px apart (`flex flex-col gap-6`) and the rule sits
-midway. Stat tiles are 12px in from each edge with a 24px figure.
+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
+neutral outline badges, leaving colour for meaning and chart series.
 
 ## Dark mode
 
-The colour scheme follows the device (`prefers-color-scheme`). There is no
-toggle and no class to set. The theme's dark values sit under the same `dark`
-variant as the `dark:` utilities, so an app that wants its own toggle swaps one
-line after the import and sets the `dark` class on `<html>`:
+The theme follows the device through `prefers-color-scheme`. For an app-owned
+toggle, override the variant after the stylesheet import and set the `dark`
+class on `<html>`:
 
 ```css
 @import "@siyahi/ui/styles.css";
 @custom-variant dark (&:where(.dark, .dark *));
 ```
 
-Both the tokens and the utilities then follow the class. Set `color-scheme` on
-`<html>` yourself as well, so scrollbars and form controls match.
-
-## Lint
-
-`@siyahi/tools` ships an [oxlint](https://oxc.rs) plugin. Its rules run only in
-files that import `@siyahi/ui`, so older pages are left alone. They reject
-colour literals (hex, `rgb()`, `oklch()`), Tailwind palette colours, Tailwind
-arbitrary values such as `text-[13px]`, `dark:` and `light:` variants,
-numeric font sizes, and chart configs with a per-scheme `theme` map (shadcn's
-chart applies its dark half under a `.dark` class Siyahi never sets; name a
-chart token with `color: "var(--chart-1)"` instead). Two of the rules are
-[`@shadcn/lint`](https://github.com/shadcn-ui/lint)'s, scoped the same way.
-
-```sh
-npm install --save-dev @siyahi/tools@next oxlint
-```
-
-```json
-{
-  "jsPlugins": ["@siyahi/tools/lint"],
-  "settings": { "shadcn": { "ui": "@siyahi/ui", "themeImports": ["^@siyahi/ui/"] } },
-  "rules": {
-    "siyahi/no-color-literal": "error",
-    "siyahi/no-scheme-variant": "error",
-    "siyahi/no-numeric-font-size": "error",
-    "siyahi/no-chart-theme-map": "error",
-    "siyahi/no-raw-colors": "error",
-    "siyahi/no-arbitrary-values": "error"
-  }
-}
-```
-
-`@siyahi/tools` also has `siyahi-shots` (screenshots of a page at 1920 and 390
-pixels wide in both schemes, with layout checks), `siyahi-cls` (how far a page
-moves after its first paint on a slow network) and `siyahi-contrast` (the
-theme contrast check). See [packages/tools](packages/tools/README.md).
+Set `color-scheme` on `<html>` as well so native controls match.
 
-## This repository
+## Tools
 
-| Path              | What                                                                               |
-| ----------------- | ---------------------------------------------------------------------------------- |
-| `packages/ui`     | `@siyahi/ui`. The theme is `styles/siyahi.css`, the only file with colour values.  |
-| `packages/tools`  | `@siyahi/tools`: lint plugin, font preload, contrast, screenshot and shift checks. |
-| `apps/catalogue`  | The catalogue site, a Vite app deployed as a Cloudflare Worker.                    |
-| `assets/icon.svg` | The mark.                                                                          |
+`@siyahi/tools` provides theme lint rules, font preload, layout screenshots
+(`siyahi-shots`), loading-shift checks (`siyahi-cls`) and contrast checks
+(`siyahi-contrast`). See the
+[tools guide](https://github.com/jatinbansal1998/siyahi/blob/main/packages/tools/README.md)
+for configuration and commands.
 
-Development uses pnpm and [Vite+](https://viteplus.dev):
+## Development
 
 ```sh
 pnpm install
-pnpm --filter @siyahi/tools exec playwright install chromium   # once; the screenshot tests use it
-pnpm check      # format, lint, unused code, generated files, build, typecheck, tests
-pnpm dev        # the catalogue on localhost
+pnpm --filter @siyahi/tools exec playwright install chromium
+pnpm check
+pnpm dev
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before adding anything.
+Read [CONTRIBUTING.md](https://github.com/jatinbansal1998/siyahi/blob/main/CONTRIBUTING.md)
+before adding components. Source lives in `packages/ui`, `packages/tools` and
+`apps/catalogue`; the catalogue is the visual documentation.
 
 ## Licence
 
-MIT, see [LICENSE](LICENSE). Code copied from other projects keeps its own
-notice; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/agents/examples/accordion.tsx

@@ -0,0 +1,39 @@
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@siyahi/ui";
+
+const questions = [
+  [
+    "prices",
+    "When are prices updated?",
+    "At the exchange close each trading day, and every minute while markets are open.",
+  ],
+  ["lots", "How are lots matched?", "Sells are matched to the oldest buy first, as the tax rules require."],
+  ["brokers", "Can I add a second broker?", "Yes. Each broker is its own account, and the totals add them up."],
+] as const;
+
+function Questions() {
+  return questions.map(([value, question, answer]) => (
+    <AccordionItem key={value} value={value}>
+      <AccordionTrigger>{question}</AccordionTrigger>
+      <AccordionContent>{answer}</AccordionContent>
+    </AccordionItem>
+  ));
+}
+
+export default function AccordionExample() {
+  return (
+    <div className="grid gap-6 md:grid-cols-2">
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted-foreground">One open at a time</p>
+        <Accordion aria-label="One open at a time" defaultValue={["prices"]}>
+          <Questions />
+        </Accordion>
+      </div>
+      <div className="flex flex-col gap-2">
+        <p className="text-sm text-muted-foreground">Several open</p>
+        <Accordion aria-label="Several open" multiple defaultValue={["prices", "lots"]}>
+          <Questions />
+        </Accordion>
+      </div>
+    </div>
+  );
+}

package/agents/examples/alert.tsx

@@ -0,0 +1,25 @@
+import { Alert, AlertDescription, AlertTitle } from "@siyahi/ui";
+import { CircleAlertIcon, InfoIcon, TriangleAlertIcon } from "lucide-react";
+
+export default function AlertExample() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Alert>
+        <InfoIcon />
+        <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!" />
+        <AlertTitle>Two trades are unmatched</AlertTitle>
+        <AlertDescription>The contract notes list trades the ledger does not have yet.</AlertDescription>
+      </Alert>
+      <Alert variant="destructive">
+        <CircleAlertIcon />
+        <AlertTitle>Import failed</AlertTitle>
+        <AlertDescription>The statement could not be read. Download it again and retry.</AlertDescription>
+      </Alert>
+    </div>
+  );
+}

package/agents/examples/app-sidebar.tsx

@@ -0,0 +1,38 @@
+import { AppSidebar, SidebarProvider } from "@siyahi/ui";
+import {
+  BlocksIcon,
+  ChartAreaIcon,
+  CodeIcon,
+  FileTextIcon,
+  HouseIcon,
+  LayersIcon,
+  PaletteIcon,
+  SlidersHorizontalIcon,
+} from "lucide-react";
+
+// No `items` on a view, so each one is a plain link.
+const views = [
+  { title: "Overview", url: "#/overview", icon: <HouseIcon /> },
+  { title: "Foundations", url: "#/foundations", icon: <PaletteIcon /> },
+  { title: "Components", url: "#/components", icon: <LayersIcon /> },
+  { title: "Inputs and overlays", url: "#/inputs", icon: <SlidersHorizontalIcon /> },
+  { title: "Data", url: "#/data", icon: <ChartAreaIcon /> },
+  { title: "Blocks", url: "#/blocks", icon: <BlocksIcon />, isActive: true },
+  { title: "Reports", url: "#/reports", icon: <FileTextIcon /> },
+  // linkProps go onto the anchor: here a new tab, in an app often onMouseEnter to prefetch the view's data.
+  {
+    title: "Source",
+    url: "https://github.com/jatinbansal1998/siyahi",
+    icon: <CodeIcon />,
+    linkProps: { target: "_blank", rel: "noreferrer" },
+  },
+];
+
+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" />
+    </SidebarProvider>
+  );
+}

package/agents/examples/avatar.tsx

@@ -0,0 +1,14 @@
+import { Avatar, AvatarFallback } from "@siyahi/ui";
+
+export default function AvatarExample() {
+  return (
+    <div className="flex gap-2">
+      <Avatar>
+        <AvatarFallback>JB</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>HU</AvatarFallback>
+      </Avatar>
+    </div>
+  );
+}

package/agents/examples/badge.tsx

@@ -0,0 +1,18 @@
+import { Badge, Delta } from "@siyahi/ui";
+
+export default function BadgeExample() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge>Equity</Badge>
+      <Badge variant="secondary">Mutual fund</Badge>
+      <Badge variant="outline">Zerodha</Badge>
+      <Badge variant="destructive">Failed</Badge>
+      <Badge variant="outline">
+        <Delta value={0.042} />
+      </Badge>
+      <Badge variant="outline">
+        <Delta value={-0.013} />
+      </Badge>
+    </div>
+  );
+}

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

@@ -0,0 +1,22 @@
+import { BarList, Card, CardContent, CardDescription, CardHeader, CardTitle, useFormat } from "@siyahi/ui";
+
+const sectors = [
+  { name: "Information Technology and Services", value: 100 },
+  { name: "Fast Moving Consumer Goods", value: 70 },
+  { name: "Automobile and Auto Components", value: 50 },
+];
+
+export default function BarListLabelsExample() {
+  const { count } = useFormat();
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Orders by sector, ranked</CardTitle>
+        <CardDescription>Full labels and order counts stay readable in narrow panels</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <BarList data={sectors} valueFormatter={count} />
+      </CardContent>
+    </Card>
+  );
+}

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

@@ -0,0 +1,30 @@
+import { BarList, Card, CardContent, CardDescription, CardHeader, CardTitle, useFormat } from "@siyahi/ui";
+
+// The biggest unrealised gains and losses; made-up figures.
+const gains = [
+  { name: "INFY", value: 84000 },
+  { name: "TCS", value: 52000 },
+  { name: "HDFCBANK", value: 31000 },
+];
+const losses = [
+  { name: "ITC", value: 18400 },
+  { name: "WIPRO", value: 7600 },
+];
+
+export default function BarListSidesExample() {
+  const { money } = useFormat();
+  // One scale for both lists, so a small loss draws a short bar beside a large gain.
+  const max = Math.max(...[...gains, ...losses].map((row) => row.value));
+  return (
+    <Card>
+      <CardHeader>
+        <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)} />
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/bar-list.tsx

@@ -0,0 +1,24 @@
+import { BarList, Card, CardContent, CardDescription, CardHeader, CardTitle, Delta, useFormat } from "@siyahi/ui";
+
+// detail is the loss as a share of what the holding cost.
+const largestLosses = [
+  { name: "ITC", value: 18400, detail: <Delta value={-0.062} /> },
+  { name: "HDFCBANK", value: 12900, detail: <Delta value={-0.047} /> },
+  { name: "WIPRO", value: 7600, detail: <Delta value={-0.072} /> },
+  { name: "Asian Paints (India)", value: 4100, detail: <Delta value={-0.06} /> },
+];
+
+export default function BarListExample() {
+  const { money } = useFormat();
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Needs attention</CardTitle>
+        <CardDescription>Largest unrealised losses</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <BarList data={largestLosses} valueFormatter={(v) => money(v)} showPercentage />
+      </CardContent>
+    </Card>
+  );
+}

package/agents/examples/breadcrumb.tsx

@@ -0,0 +1,28 @@
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "@siyahi/ui";
+
+export default function BreadcrumbExample() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#/components">Portfolio</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#/components">Equity</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>INFY</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}

package/agents/examples/button.tsx

@@ -0,0 +1,21 @@
+import { Button } from "@siyahi/ui";
+import { DownloadIcon, RefreshCwIcon } from "lucide-react";
+
+export default function ButtonExample() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button>Save</Button>
+      <Button variant="outline">
+        <DownloadIcon />
+        Export
+      </Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="destructive">Delete</Button>
+      <Button variant="link">Link</Button>
+      <Button variant="outline" size="icon" aria-label="Refresh">
+        <RefreshCwIcon />
+      </Button>
+    </div>
+  );
+}

package/agents/examples/calendar.tsx

@@ -0,0 +1,15 @@
+import { Calendar } from "@siyahi/ui";
+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"
+    />
+  );
+}