@jallall/oidea-ui 0.1.0

package/README.md

@@ -0,0 +1,448 @@
+# @oidea/ui
+
+Reusable React components and design tokens used by Oidea applications. The package includes accessible UI primitives, application-level building blocks, data visualization components, and the complete Oidea visual theme.
+
+## Requirements
+
+- React 18 or 19
+- React DOM 18 or 19
+- Node.js 20 or newer for local development
+
+The package is written in TypeScript and includes its own type declarations. It works in JavaScript projects too.
+
+## Installation
+
+```bash
+npm install @oidea/ui react react-dom
+```
+
+Applications using `OideaQueryProvider` or the TanStack integrations should also install:
+
+```bash
+npm install @tanstack/react-query@^5 @tanstack/react-router@^1 @tanstack/react-table@^8
+```
+
+## Quick start
+
+Import the stylesheet once at the root of your application:
+
+```tsx
+// main.tsx, app.tsx, or your root layout
+import "@oidea/ui/styles.css"
+```
+
+Components can then be imported directly from the package:
+
+```tsx
+import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@oidea/ui"
+
+export function Example() {
+  return (
+    <Card className="max-w-md">
+      <CardHeader>
+        <CardTitle>Invoice ready</CardTitle>
+      </CardHeader>
+      <CardContent className="flex items-center gap-3">
+        <Badge color="#123526" size="sm">Approved</Badge>
+        <Button>View invoice</Button>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Providers
+
+Most components do not need a provider. If your application uses React Query, `OideaQueryProvider` supplies a sensible default `QueryClient`:
+
+```tsx
+import { OideaQueryProvider } from "@oidea/ui"
+import "@oidea/ui/styles.css"
+
+export function App() {
+  return (
+    <OideaQueryProvider>
+      <Routes />
+    </OideaQueryProvider>
+  )
+}
+```
+
+Pass your own client when you need custom query behavior:
+
+```tsx
+import { QueryClient } from "@tanstack/react-query"
+import { OideaQueryProvider } from "@oidea/ui"
+
+const queryClient = new QueryClient()
+
+export function App() {
+  return <OideaQueryProvider client={queryClient}><Routes /></OideaQueryProvider>
+}
+```
+
+## Badges
+
+### Badge
+
+`Badge` supports visual variants, four sizes, arbitrary CSS colors, links through `asChild`, and normal HTML attributes.
+
+```tsx
+import { Badge } from "@oidea/ui"
+
+export function BadgeExamples() {
+  return (
+    <div className="flex items-center gap-2">
+      <Badge variant="default" size="xs">New</Badge>
+      <Badge variant="outline" size="md">Draft</Badge>
+      <Badge color="#7c3aed" size="lg">Premium</Badge>
+      <Badge color="rebeccapurple">Custom color</Badge>
+    </div>
+  )
+}
+```
+
+Available sizes are `xs`, `sm`, `md`, and `lg`. Available variants are `default`, `secondary`, `destructive`, `outline`, `ghost`, and `link`. A `color` value overrides the variant's foreground, background, and border colors.
+
+### StatusBadge
+
+Use `StatusBadge` for semantic statuses. Its tones are `success`, `warning`, `gold`, `danger`, `neutral`, `muted`, and `info`.
+
+```tsx
+import { StatusBadge } from "@oidea/ui"
+
+<StatusBadge tone="success" size="sm" dot>Paid</StatusBadge>
+<StatusBadge tone="danger">Rejected</StatusBadge>
+<StatusBadge color="#2563eb" size="lg" dot>Processing</StatusBadge>
+```
+
+`tone` defaults to `neutral`. An arbitrary `color` overrides the selected tone and also colors the optional dot.
+
+## Toast notifications
+
+The included toaster is powered by Sonner. Render `Toaster` once near the root, then use Sonner's `toast` function anywhere in the application:
+
+```tsx
+import { Toaster, toast } from "@oidea/ui"
+
+export function App() {
+  return (
+    <>
+      <button onClick={() => toast.success("Invoice saved")}>Save</button>
+      <Toaster position="top-right" richColors />
+    </>
+  )
+}
+```
+
+## Data tables
+
+`DataTable` provides typed columns, local sorting, search, pagination, loading skeletons, selectable rows, and manual/infinite data loading.
+
+```tsx
+import { DataTable, type DataTableColumn } from "@oidea/ui"
+
+type Invoice = {
+  id: string
+  customer: string
+  total: number
+}
+
+const columns: DataTableColumn<Invoice>[] = [
+  {
+    id: "customer",
+    header: "Customer",
+    cell: (invoice) => invoice.customer,
+    sortAccessor: (invoice) => invoice.customer,
+  },
+  {
+    id: "total",
+    header: "Total",
+    cell: (invoice) => `₦${invoice.total.toLocaleString()}`,
+    sortAccessor: (invoice) => invoice.total,
+    align: "right",
+  },
+]
+
+export function InvoiceTable({ invoices }: { invoices: Invoice[] }) {
+  return (
+    <DataTable
+      columns={columns}
+      data={invoices}
+      rowKey={(invoice) => invoice.id}
+      searchable
+      paginated
+      searchAccessor={(invoice) => `${invoice.customer} ${invoice.total}`}
+      onRowClick={(invoice) => console.log(invoice.id)}
+    />
+  )
+}
+```
+
+For server-managed data, set `manualData`, supply `totalCount`, and use `hasMore`, `loadingMore`, and `onLoadMore`.
+
+## Tabs
+
+The package includes two tab systems:
+
+- `Tabs`, `TabsList`, `TabsTrigger`, and `TabsContent` are Radix-based UI primitives.
+- `AppTabs`, `AppTabsList`, and `AppTabsTab` provide Oidea's animated application-tab appearance.
+
+The `App` prefix prevents naming conflicts when both systems are imported together.
+
+## Routing and application sidebar
+
+The package integrates with TanStack Router while leaving your route definitions and application data under your control. Create the route tree in your application, then render it with `OideaRouterProvider`:
+
+```tsx
+import {
+  OideaRouterProvider,
+  Outlet,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from "@oidea/ui"
+
+const rootRoute = createRootRoute({ component: Outlet })
+
+const dashboardRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/dashboard",
+  component: () => <h1>Dashboard</h1>,
+})
+
+const routeTree = rootRoute.addChildren([dashboardRoute])
+const router = createRouter({ routeTree })
+
+export function App() {
+  return <OideaRouterProvider router={router} />
+}
+```
+
+For full TanStack Router type registration, add this in your application:
+
+```tsx
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: typeof router
+  }
+}
+```
+
+`AppSidebar` accepts configurable navigation groups and automatically marks the current TanStack route as active:
+
+```tsx
+import { BarChart3, FileText, LayoutDashboard } from "lucide-react"
+import { AppSidebar, SidebarProvider } from "@oidea/ui"
+
+const groups = [
+  {
+    label: "Platform",
+    items: [
+      { to: "/dashboard", label: "Dashboard", icon: LayoutDashboard },
+      { to: "/invoices", label: "Invoices", icon: FileText },
+      { to: "/reports", label: "Reports", icon: BarChart3 },
+    ],
+  },
+]
+
+<SidebarProvider>
+  <AppSidebar
+    brand={<strong>My application</strong>}
+    brandTo="/dashboard"
+    groups={groups}
+    footer={<span>Signed in</span>}
+  />
+</SidebarProvider>
+```
+
+`RouterShell` combines the responsive sidebar, sidebar provider, mobile trigger, header, and route content:
+
+```tsx
+import { Outlet, RouterShell } from "@oidea/ui"
+
+export function AuthenticatedLayout() {
+  return (
+    <RouterShell
+      sidebar={{ groups, brand: <strong>My application</strong>, brandTo: "/dashboard" }}
+      header={<span>Workspace</span>}
+    >
+      <Outlet />
+    </RouterShell>
+  )
+}
+```
+
+Each navigation item supports `to`, `label`, an optional icon, `disabled`, and a custom `isActive(pathname)` matcher.
+
+## Component groups
+
+### UI primitives
+
+Alert, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Chart, Checkbox, Collapsible, Command, Dialog, Dropdown Menu, Form, Input, Label, Pagination, Popover, Progress, Radio Group, Scroll Area, Select, Separator, Sheet, Sidebar, Skeleton, Sonner Toaster, Switch, Table, Tabs, Textarea, Toggle, Toggle Group, and Tooltip.
+
+### Application components
+
+Action Item List, Activity Timeline, Aging Bucket Bars, App Page Header, App Sidebar, App Surface, Avatar Thumbnail, Avatar Tile, Confirm Dialog, Data Table, Detail Drawer, Drawer Field, Drawer Section, Empty State, Filter Bar, Filter Chips, Health Score Ring, Hero Stat Card, Period Selector, Reference Combobox, Router Shell, Search Input, Stat Card, Status Badge, Status Filters, Step Indicator, Submission Funnel, animated App Tabs, and Trend Card.
+
+### Charts
+
+Area Chart, Bar Chart, Donut Chart, and Sparkline. Chart components are built on Recharts and use the Oidea theme variables by default.
+
+## Complete component reference
+
+Every example below assumes the component is imported from `@oidea/ui`. Import `@oidea/ui/styles.css` once in the application root.
+
+### All 34 UI primitive modules
+
+| Module | Main exports | Minimal use |
+| --- | --- | --- |
+| Alert | `Alert`, `AlertTitle`, `AlertDescription` | `<Alert><AlertTitle>Notice</AlertTitle><AlertDescription>Details</AlertDescription></Alert>` |
+| Avatar | `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarBadge`, `AvatarGroup`, `AvatarGroupCount` | `<Avatar><AvatarImage src="/user.jpg" /><AvatarFallback>AJ</AvatarFallback></Avatar>` |
+| Badge | `Badge` | `<Badge color="#2563eb" size="sm">New</Badge>` |
+| Breadcrumb | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | `<Breadcrumb><BreadcrumbList><BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator /><BreadcrumbPage>Invoices</BreadcrumbPage></BreadcrumbList></Breadcrumb>` |
+| Button | `Button` | `<Button variant="default" size="sm">Save</Button>` |
+| Calendar | `Calendar`, `CalendarDayButton` | `<Calendar mode="single" selected={date} onSelect={setDate} />` |
+| Card | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | `<Card><CardHeader><CardTitle>Title</CardTitle></CardHeader><CardContent>Content</CardContent></Card>` |
+| Chart | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent` | `<ChartContainer config={{ total: { label: "Total", color: "#123526" } }}>{rechartsContent}</ChartContainer>` |
+| Checkbox | `Checkbox` | `<Checkbox checked={checked} onCheckedChange={setChecked} />` |
+| Collapsible | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | `<Collapsible><CollapsibleTrigger>Details</CollapsibleTrigger><CollapsibleContent>Hidden content</CollapsibleContent></Collapsible>` |
+| Command | `Command`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut`, `CommandDialog` | `<Command><CommandInput placeholder="Search" /><CommandList><CommandItem>Invoice</CommandItem></CommandList></Command>` |
+| Dialog | `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose` | `<Dialog><DialogTrigger asChild><Button>Open</Button></DialogTrigger><DialogContent><DialogTitle>Dialog</DialogTitle></DialogContent></Dialog>` |
+| Dropdown Menu | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem` and checkbox, radio, label, separator, shortcut, and submenu helpers | `<DropdownMenu><DropdownMenuTrigger asChild><Button>Actions</Button></DropdownMenuTrigger><DropdownMenuContent><DropdownMenuItem>Edit</DropdownMenuItem></DropdownMenuContent></DropdownMenu>` |
+| Form | `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `useFormField` | `<Form {...form}><FormField control={form.control} name="email" render={({ field }) => <FormItem><FormLabel>Email</FormLabel><FormControl><Input {...field} /></FormControl><FormMessage /></FormItem>} /></Form>` |
+| Input | `Input` | `<Input type="email" placeholder="name@example.com" />` |
+| Label | `Label` | `<Label htmlFor="email">Email</Label>` |
+| Pagination | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` | `<Pagination><PaginationContent><PaginationItem><PaginationPrevious href="?page=1" /></PaginationItem><PaginationItem><PaginationLink href="?page=2">2</PaginationLink></PaginationItem></PaginationContent></Pagination>` |
+| Popover | `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor`, `PopoverHeader`, `PopoverTitle`, `PopoverDescription` | `<Popover><PopoverTrigger asChild><Button>Open</Button></PopoverTrigger><PopoverContent>Content</PopoverContent></Popover>` |
+| Progress | `Progress` | `<Progress value={65} />` |
+| Radio Group | `RadioGroup`, `RadioGroupItem` | `<RadioGroup value={value} onValueChange={setValue}><RadioGroupItem value="monthly" /></RadioGroup>` |
+| Scroll Area | `ScrollArea`, `ScrollBar` | `<ScrollArea className="h-64">Long content<ScrollBar /></ScrollArea>` |
+| Select | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator` | `<Select value={value} onValueChange={setValue}><SelectTrigger><SelectValue placeholder="Choose" /></SelectTrigger><SelectContent><SelectItem value="one">One</SelectItem></SelectContent></Select>` |
+| Separator | `Separator` | `<Separator orientation="horizontal" />` |
+| Sheet | `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetDescription`, `SheetFooter`, `SheetClose` | `<Sheet><SheetTrigger asChild><Button>Open</Button></SheetTrigger><SheetContent><SheetTitle>Details</SheetTitle></SheetContent></Sheet>` |
+| Sidebar | `SidebarProvider`, `Sidebar`, `SidebarTrigger`, `SidebarInset`, plus header, footer, group, menu, submenu, badge, action, rail, input, and skeleton helpers | `<SidebarProvider><Sidebar><SidebarContent>Navigation</SidebarContent></Sidebar><SidebarInset><SidebarTrigger />Page</SidebarInset></SidebarProvider>` |
+| Skeleton | `Skeleton` | `<Skeleton className="h-6 w-40" />` |
+| Sonner | `Toaster`, `toast` | `<><Button onClick={() => toast.success("Saved")}>Save</Button><Toaster /></>` |
+| Switch | `Switch` | `<Switch checked={enabled} onCheckedChange={setEnabled} />` |
+| Table | `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` | `<Table><TableHeader><TableRow><TableHead>Name</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Acme</TableCell></TableRow></TableBody></Table>` |
+| Tabs | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | `<Tabs defaultValue="first"><TabsList><TabsTrigger value="first">First</TabsTrigger></TabsList><TabsContent value="first">Content</TabsContent></Tabs>` |
+| Textarea | `Textarea` | `<Textarea placeholder="Add a note" rows={4} />` |
+| Toggle Group | `ToggleGroup`, `ToggleGroupItem` | `<ToggleGroup type="single" value={view} onValueChange={setView}><ToggleGroupItem value="grid">Grid</ToggleGroupItem></ToggleGroup>` |
+| Toggle | `Toggle` | `<Toggle pressed={active} onPressedChange={setActive}>Bold</Toggle>` |
+| Tooltip | `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent` | `<TooltipProvider><Tooltip><TooltipTrigger asChild><Button>Info</Button></TooltipTrigger><TooltipContent>Helpful text</TooltipContent></Tooltip></TooltipProvider>` |
+
+The primitive components forward their underlying HTML or Radix props. This means attributes such as `disabled`, `aria-*`, event handlers, controlled state, and `className` remain available.
+
+### All 32 application component modules
+
+| Component | Purpose and essential props | Minimal use |
+| --- | --- | --- |
+| `ActionItemList` | Action queue. Pass `items` containing `id`, `title`, and optional `description`, `tone`, `icon`, `count`, `href`, or `onClick`. | `<ActionItemList items={[{ id: "1", title: "Review invoice", tone: "warning", count: 3 }]} />` |
+| `ActivityTimeline` | Chronological events. Pass `entries`; `density` is `comfortable` or `compact`. | `<ActivityTimeline entries={[{ id: "1", title: "Created", timestamp: "10:30", tone: "success" }]} />` |
+| `AgingBucketBars` | Proportional aging distribution with optional legend and formatter. | `<AgingBucketBars buckets={[{ id: "current", label: "Current", value: 80 }, { id: "late", label: "Late", value: 20 }]} />` |
+| `AppPageHeader` | Responsive page heading with `eyebrow`, `title`, `description`, and `actions`. | `<AppPageHeader title="Invoices" description="Manage invoices" actions={<Button>New</Button>} />` |
+| `AppSidebar` | TanStack Router-aware navigation. Pass `groups`; optionally pass `brand`, `brandTo`, `footer`, and `collapsible`. | `<AppSidebar groups={[{ label: "Main", items: [{ to: "/dashboard", label: "Dashboard" }] }]} />` |
+| `AppSurface` | Card-like page section. Supports `title`, `description`, `actions`, `footer`, and `padding`. | `<AppSurface title="Summary" padding="default">Content</AppSurface>` |
+| `AvatarThumbnail` | Initials or icon tile with configurable `tint` and numeric `size`. | `<AvatarThumbnail initials="AJ" tint="#c9a87c" size={40} />` |
+| `AvatarTile` | Identity row composed from `thumbnail`, `title`, `subtitle`, `titleSuffix`, and `trailing`. | `<AvatarTile thumbnail={<AvatarThumbnail initials="AJ" />} title="Abdul Jalal" subtitle="Admin" />` |
+| `ConfirmDialog` | Controlled confirmation dialog with customizable labels and destructive/default tone. | `<ConfirmDialog open={open} onOpenChange={setOpen} title="Delete?" onConfirm={removeItem} />` |
+| `DataTable` | Typed table with sorting, search, pagination, loading, density, and manual/infinite loading modes. | `<DataTable columns={columns} data={rows} rowKey={(row) => row.id} searchable paginated />` |
+| `DetailDrawer` | Controlled left/right details sheet. Pass `open`, `onOpenChange`, `title`, `children`; sizes are `sm`, `md`, and `lg`. | `<DetailDrawer open={open} onOpenChange={setOpen} title="Invoice" size="lg">Details</DetailDrawer>` |
+| `DrawerField` | Label/value row for drawer content, with optional helper text. | `<DrawerField label="Status" value="Paid" helper="Updated today" />` |
+| `DrawerSection` | Groups drawer content under an optional title and description. | `<DrawerSection title="Customer"><DrawerField label="Name" value="Acme" /></DrawerSection>` |
+| `EmptyState` | Empty-result presentation with optional icon, title, description, and action. | `<EmptyState title="No invoices" description="Create the first invoice." action={<Button>New</Button>} />` |
+| `FilterBar` | Search field with clear behavior and dedicated `chips`, `period`, and `actions` slots. | `<FilterBar search={search} onSearchChange={setSearch} searchPlaceholder="Search invoices" chips={<FilterChips options={options} selected={statuses} onChange={setStatuses} />} />` |
+| `FilterChips` | Multi-select chip list. Options use `id`, `label`, and optional count/icon; pass `selected` and `onChange`. | `<FilterChips options={[{ id: "paid", label: "Paid" }]} selected={["paid"]} onChange={setStatuses} />` |
+| `HealthScoreRing` | Circular numeric health score with configurable `value`, `max`, `size`, `thickness`, label, caption, and tone. | `<HealthScoreRing value={92} label="Healthy" />` |
+| `HeroStatCard` | Prominent metric card requiring `tone`, `icon`, `label`, `value`, and `currency`; supports subtitle and numeric delta. | `<HeroStatCard label="Revenue" value="2.4m" currency="NGN" tone="dark" icon={Wallet} />` |
+| `PeriodSelector` | Controlled date preset/custom-range picker. Pass a `PeriodRange` as `value` and handle `onChange`. | `<PeriodSelector value={period} onChange={setPeriod} />` |
+| `ReferenceCombobox` | Searchable controlled reference selector. Options use `value`, `label`, and optional `helper`. | `<ReferenceCombobox options={countries} value={country} onValueChange={setCountry} placeholder="Country" />` |
+| `RouterShell` | Responsive TanStack route layout combining `AppSidebar`, header, trigger, and page content. | `<RouterShell sidebar={{ groups }} header="Workspace"><Outlet /></RouterShell>` |
+| `SearchInput` | Controlled search input with search and clear icons. | `<SearchInput value={search} onChange={setSearch} placeholder="Search" />` |
+| `StatCard` | Metric card with `label`, `value`, optional delta, icon, helper, and semantic tone. | `<StatCard label="Invoices" value={128} delta={{ value: "12%", direction: "up" }} tone="success" />` |
+| `StatusBadge` | Semantic/custom-color status label. Sizes are `xs`–`lg`; supports `dot`. | `<StatusBadge tone="success" size="sm" dot>Paid</StatusBadge>` |
+| `StatusFilterPopover` | Multi-select status filter inside a popover. Pass typed options, `selected`, and `onChange`. | `<StatusFilterPopover options={options} selected={statuses} onChange={setStatuses} />` |
+| `StatusFilter` | Inline multi-select status selector. Options contain `id`, `label`, and a selected-state `toneClass`. | `<StatusFilter options={options} selected={statuses} onChange={setStatuses} />` |
+| `StepIndicator` | Numbered progress indicator. Pass step labels and a zero-based `currentStep`; sizes are `sm` and `md`. | `<StepIndicator steps={["Account", "Business", "Done"]} currentStep={1} />` |
+| `SubmissionFunnel` | Stage conversion visualization. Pass stages with `id`, `label`, `value`, optional helper and tone. | `<SubmissionFunnel stages={[{ id: "received", label: "Received", value: 100 }, { id: "accepted", label: "Accepted", value: 82, tone: "success" }]} />` |
+| `AppTabs` | Controlled animated app-tab context. Pass `value` and `onChange`. | `<AppTabs value={tab} onChange={setTab}><AppTabsList><AppTabsTab value="all" count={12}>All</AppTabsTab></AppTabsList></AppTabs>` |
+| `AppTabsList` | Layout for `AppTabsTab` children with start/center/end alignment and optional actions. | `<AppTabsList align="start" actions={<Button>Export</Button>}>{tabs}</AppTabsList>` |
+| `AppTabsTab` | Individual animated app tab. Requires `value`; supports `count` and `disabled`. | `<AppTabsTab value="pending" count={4}>Pending</AppTabsTab>` |
+| `TrendCard` | Metric card with sparkline. Pass `label`, `value`, numeric `data`, optional delta, tone, and line/area variant. | `<TrendCard label="Volume" value="1,240" data={[10, 14, 12, 18]} tone="success" />` |
+
+### All 4 chart modules
+
+Chart data points for area and bar charts require a `label` property plus numeric series keys.
+
+| Component | Essential props | Minimal use |
+| --- | --- | --- |
+| `AreaChart` | `data`, `series`; optional `height`, `variant`, axes, grid, legend, curve, and formatter. | `<AreaChart data={[{ label: "Jan", revenue: 10 }, { label: "Feb", revenue: 15 }]} series={[{ key: "revenue", label: "Revenue" }]} />` |
+| `BarChart` | `data`, `series`; optional `stacked`, horizontal/vertical layout, axes, grid, radius, and formatter. | `<BarChart data={[{ label: "Paid", total: 20 }]} series={[{ key: "total", label: "Invoices" }]} />` |
+| `DonutChart` | `data` entries with `key`, `label`, `value`, optional color; supports size, thickness, center text, and formatter. | `<DonutChart data={[{ key: "paid", label: "Paid", value: 75 }, { key: "open", label: "Open", value: 25 }]} centerValue="100" />` |
+| `Sparkline` | Numeric `data`; optional area/line variant, color, height, width, and stroke width. | `<Sparkline data={[4, 8, 6, 12]} color="#123526" variant="line" />` |
+
+These 70 modules expose more than 150 composable exports because compound modules such as Dialog, Dropdown Menu, Sidebar, Table, and Form contain multiple related subcomponents. TypeScript declarations provide the complete prop contract and editor autocomplete for every export.
+
+## Styling and customization
+
+Always import `@oidea/ui/styles.css`. It contains Tailwind-generated component styles, animations, and Oidea's CSS variables.
+
+All components accept `className` where applicable, so layout and presentation can be extended without modifying package source:
+
+```tsx
+<Button className="w-full rounded-xl">Continue</Button>
+```
+
+Theme values can be overridden after the package stylesheet:
+
+```css
+:root {
+  --primary: #123526;
+  --ring: #c9a87c;
+  --radius: 0.75rem;
+}
+```
+
+Common variables include `--background`, `--foreground`, `--card`, `--primary`, `--secondary`, `--accent`, `--destructive`, `--border`, `--input`, `--ring`, and `--radius`.
+
+## TypeScript
+
+Types are bundled automatically. Props can be imported from the main entry point:
+
+```tsx
+import type { DataTableColumn, OideaQueryProviderProps, StatusBadgeProps } from "@oidea/ui"
+```
+
+## Development
+
+```bash
+git clone https://github.com/jalal-codr/oidea-ui.git
+cd oidea-ui
+npm install
+npm run dev
+```
+
+Useful commands:
+
+```bash
+npm run typecheck
+npm test
+npm run lint
+npm run build
+```
+
+## Publishing
+
+The README is automatically displayed on the npm package page. Before publishing, authenticate with npm and run:
+
+```bash
+npm login
+npm publish
+```
+
+The `prepublishOnly` script runs the test suite and production build automatically. The package is configured as a public scoped package.
+
+## License
+
+UNLICENSED. Contact the repository owner before redistributing or using the package outside authorized projects.

package/dist/components/app/action-item-list.d.ts

@@ -0,0 +1,22 @@
+import { ComponentType, ReactNode } from 'react';
+export type ActionItemTone = 'critical' | 'warning' | 'info' | 'success' | 'neutral';
+export interface ActionItem {
+    id: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    tone?: ActionItemTone;
+    title: string;
+    description?: ReactNode;
+    meta?: string;
+    count?: number;
+    onClick?: () => void;
+    href?: string;
+}
+interface ActionItemListProps {
+    items: ActionItem[];
+    className?: string;
+    empty?: ReactNode;
+}
+export declare function ActionItemList({ items, className, empty }: ActionItemListProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined>;
+export {};

package/dist/components/app/activity-timeline.d.ts

@@ -0,0 +1,20 @@
+import { ComponentType, ReactNode } from 'react';
+export type TimelineTone = 'neutral' | 'success' | 'warning' | 'critical' | 'info';
+export interface TimelineEntry {
+    id: string;
+    title: string;
+    description?: ReactNode;
+    timestamp: ReactNode;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    tone?: TimelineTone;
+    actor?: string;
+}
+interface ActivityTimelineProps {
+    entries: TimelineEntry[];
+    className?: string;
+    density?: 'comfortable' | 'compact';
+}
+export declare function ActivityTimeline({ entries, className, density, }: ActivityTimelineProps): import("react").JSX.Element;
+export {};

package/dist/components/app/aging-bucket-bars.d.ts

@@ -0,0 +1,16 @@
+export interface AgingBucket {
+    id: string;
+    label: string;
+    value: number;
+    color?: string;
+}
+interface AgingBucketBarsProps {
+    buckets: AgingBucket[];
+    total?: number;
+    formatValue?: (v: number) => string;
+    className?: string;
+    height?: number;
+    showLegend?: boolean;
+}
+export declare function AgingBucketBars({ buckets, total, formatValue, className, height, showLegend, }: AgingBucketBarsProps): import("react").JSX.Element;
+export {};

package/dist/components/app/app-page-header.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+interface AppPageHeaderProps {
+    eyebrow?: string;
+    title: string;
+    description?: string;
+    actions?: ReactNode;
+    className?: string;
+}
+export declare function AppPageHeader({ eyebrow, title, description, actions, className, }: AppPageHeaderProps): import("react").JSX.Element;
+export {};

package/dist/components/app/app-sidebar.d.ts

@@ -0,0 +1,27 @@
+import { ComponentType, ReactNode } from 'react';
+export interface AppSidebarItem {
+    to: string;
+    label: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Override the default prefix-based active-route check. */
+    isActive?: (pathname: string) => boolean;
+    disabled?: boolean;
+}
+export interface AppSidebarGroup {
+    label?: ReactNode;
+    items: AppSidebarItem[];
+}
+export interface AppSidebarProps {
+    groups: AppSidebarGroup[];
+    /** Brand content shown at the top of the sidebar. */
+    brand?: ReactNode;
+    /** Destination used when the brand is clicked. Omit to render a static brand. */
+    brandTo?: string;
+    footer?: ReactNode;
+    collapsible?: "offcanvas" | "icon" | "none";
+    className?: string;
+}
+/** A configurable application sidebar integrated with TanStack Router. */
+export declare function AppSidebar({ groups, brand, brandTo, footer, collapsible, className, }: AppSidebarProps): import("react").JSX.Element;

package/dist/components/app/app-surface.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+interface AppSurfaceProps {
+    title?: string;
+    description?: string;
+    actions?: ReactNode;
+    footer?: ReactNode;
+    children: ReactNode;
+    className?: string;
+    contentClassName?: string;
+    padding?: 'default' | 'tight' | 'flush';
+}
+export declare function AppSurface({ title, description, actions, footer, children, className, contentClassName, padding, }: AppSurfaceProps): import("react").JSX.Element;
+export {};

package/dist/components/app/avatar-thumbnail.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+export interface AvatarThumbnailProps {
+    initials?: string;
+    icon?: ReactNode;
+    tint?: string;
+    size?: number;
+    className?: string;
+}
+export declare function AvatarThumbnail({ initials, icon, tint, size, className, }: AvatarThumbnailProps): import("react").JSX.Element;

package/dist/components/app/avatar-tile.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+export interface AvatarTileProps {
+    thumbnail: ReactNode;
+    title: ReactNode;
+    titleSuffix?: ReactNode;
+    subtitle?: ReactNode;
+    trailing?: ReactNode;
+    className?: string;
+}
+export declare function AvatarTile({ thumbnail, title, titleSuffix, subtitle, trailing, className, }: AvatarTileProps): import("react").JSX.Element;

package/dist/components/app/charts/area-chart.d.ts

@@ -0,0 +1,21 @@
+interface AreaChartProps<TKey extends string> {
+    data: Array<Record<string, string | number> & {
+        label: string;
+    }>;
+    series: Array<{
+        key: TKey;
+        label: string;
+        color?: string;
+    }>;
+    className?: string;
+    height?: number;
+    variant?: 'area' | 'line';
+    yAxis?: boolean;
+    xAxis?: boolean;
+    grid?: boolean;
+    legend?: boolean;
+    curve?: 'monotone' | 'linear' | 'step';
+    formatValue?: (v: number) => string;
+}
+export declare function AreaChart<TKey extends string>({ data, series, className, height, variant, yAxis, xAxis, grid, legend, curve, formatValue, }: AreaChartProps<TKey>): import("react").JSX.Element;
+export {};

package/dist/components/app/charts/bar-chart.d.ts

@@ -0,0 +1,21 @@
+interface BarChartProps<TKey extends string> {
+    data: Array<Record<string, string | number> & {
+        label: string;
+    }>;
+    series: Array<{
+        key: TKey;
+        label: string;
+        color?: string;
+    }>;
+    className?: string;
+    height?: number;
+    stacked?: boolean;
+    layout?: 'vertical' | 'horizontal';
+    yAxis?: boolean;
+    xAxis?: boolean;
+    grid?: boolean;
+    radius?: number;
+    formatValue?: (v: number) => string;
+}
+export declare function BarChart<TKey extends string>({ data, series, className, height, stacked, layout, yAxis, xAxis, grid, radius, formatValue, }: BarChartProps<TKey>): import("react").JSX.Element;
+export {};

package/dist/components/app/charts/donut-chart.d.ts

@@ -0,0 +1,16 @@
+interface DonutChartProps {
+    data: Array<{
+        key: string;
+        label: string;
+        value: number;
+        color?: string;
+    }>;
+    className?: string;
+    size?: number;
+    thickness?: number;
+    centerLabel?: string;
+    centerValue?: string;
+    formatValue?: (v: number) => string;
+}
+export declare function DonutChart({ data, className, size, thickness, centerLabel, centerValue, formatValue, }: DonutChartProps): import("react").JSX.Element;
+export {};

package/dist/components/app/charts/index.d.ts

@@ -0,0 +1,4 @@
+export { AreaChart } from './area-chart';
+export { BarChart } from './bar-chart';
+export { DonutChart } from './donut-chart';
+export { Sparkline } from './sparkline';