@rufous/ui 0.2.0-beta.1 → 0.2.1

package/README.md

@@ -1,14 +1,12 @@
-# @rufous/ui
+# Rufous UI
 
-> [!CAUTION]
-> **Stability: Experimental / Beta**
-> This package is currently in early development. Breaking changes, bugs, and API updates are expected. We recommend using it in non-critical environments until a stable `1.0.0` version is released.
+A polished React component library built with design tokens, TypeScript, and zero runtime dependencies beyond React. Every component supports the `sx` prop for scoped style overrides.
 
-A lightweight React UI component library with theming, buttons, inputs, dialogs, progress and a rich icon set.
+**Live Showcase → [ui.dev.rufous.com](https://ui.dev.rufous.com/)**
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @rufous/ui
@@ -18,21 +16,19 @@ yarn add @rufous/ui
 
 ---
 
-## 🔧 Setup
+## Setup
 
-Import the global styles once in your app entry (e.g. `src/main.tsx`, `pages/_app.tsx`).
+Import the global styles once in your app entry:
 
-```javascript
-import "@rufous/ui/style.css";
+```tsx
+import "@rufous/ui/main.css";
 ```
 
-Optional but recommended: wrap your app with the theme provider to enable theme utilities.
+Wrap your app with the theme provider:
 
 ```tsx
-import React from "react";
-import ReactDOM from "react-dom/client";
 import { RufousThemeProvider } from "@rufous/ui";
-import "@rufous/ui/style.css";
+import "@rufous/ui/main.css";
 
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <RufousThemeProvider>
@@ -43,265 +39,531 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
 
 ---
 
-## 🎨 Theming
+## Components
 
-`RufousThemeProvider` exposes `useRufousTheme` and `APP_THEMES`.
+### Buttons
 
 ```tsx
-import { useRufousTheme, APP_THEMES, Button } from "@rufous/ui";
+import { StandardButton, AddButton, SubmitButton, CancelButton } from "@rufous/ui";
 
-export function ThemeToggle() {
-  const { previewTheme } = useRufousTheme();
-  return (
-    <div style={{ display: "flex", gap: 12 }}>
-      <Button
-        onClick={() => previewTheme(APP_THEMES.default.name.toLowerCase())}
-      >
-        Light
-      </Button>
-      <Button
-        onClick={() => previewTheme(APP_THEMES.rufous.name.toLowerCase())}
-      >
-        Dark
-      </Button>
-    </div>
-  );
-}
+<StandardButton onClick={fn}>Standard</StandardButton>
+<AddButton onClick={fn}>Add Item</AddButton>
+<SubmitButton onClick={asyncFn}>Save</SubmitButton>
+<CancelButton onClick={fn}>Cancel</CancelButton>
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onClick` | `() => void \| Promise<void>` | — | Supports async; shows loader until resolved |
+| `isLoading` | `boolean` | `false` | External loading state control |
+| `disabled` | `boolean` | `false` | Disables the button |
+| `sx` | `SxProp` | — | Scoped style overrides |
+
 ---
 
-## 🧩 Components
+### TextField
 
-Below are the primary components exported by the library with usage patterns and key props.
+```tsx
+import { TextField } from "@rufous/ui";
+
+<TextField
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+  variant="outlined"
+  required
+/>
+```
 
-### Buttons
+| Prop | Type | Default |
+|------|------|---------|
+| `label` | `string` | — |
+| `variant` | `'outlined' \| 'filled' \| 'standard'` | `'outlined'` |
+| `size` | `'small' \| 'medium'` | `'medium'` |
+| `color` | `'primary' \| 'secondary' \| 'error' \| 'success' \| 'warning' \| 'info'` | `'primary'` |
+| `error` | `boolean` | `false` |
+| `helperText` | `ReactNode` | — |
+| `fullWidth` | `boolean` | `false` |
+| `InputProps` | `{ startAdornment?, endAdornment? }` | — |
+| `sx` | `SxProp` | — |
+
+---
+
+### Select
+
+```tsx
+import { Select } from "@rufous/ui";
+
+<Select
+  options={[{ value: "us", label: "United States" }]}
+  value={country}
+  onChange={setCountry}
+  label="Country"
+/>
+
+// Multiple selection
+<Select options={options} value={selected} onChange={setSelected} multiple label="Tags" />
+```
+
+---
+
+### DateField / DateRangeField
+
+```tsx
+import { DateField, DateRangeField } from "@rufous/ui";
+
+<DateField label="Start Date" value={date} onChange={setDate} />
+
+<DateRangeField
+  label="Date Range"
+  value={range}
+  onChange={setRange}
+/>
+```
+
+---
 
-All buttons accept native button props via `...rest`.
-
-- **StandardButton**: Base neutral button
-- **AddButton**: Prefixed with `+`
-- **SubmitButton**: Submit/async actions with built-in loading and double-click handling
-- **CancelButton**: Secondary/cancel action
-
-```tsx
-import {
-  StandardButton,
-  AddButton,
-  SubmitButton,
-  CancelButton,
-} from "@rufous/ui";
-
-export function ButtonsDemo() {
-  return (
-    <div style={{ display: "flex", gap: 12 }}>
-      <StandardButton onClick={() => alert("Standard")}>
-        Standard
-      </StandardButton>
-      <AddButton onClick={() => alert("Added")}>Add Item</AddButton>
-      <SubmitButton
-        onClick={async () => await new Promise((r) => setTimeout(r, 800))}
-      >
-        Save
-      </SubmitButton>
-      <CancelButton onClick={() => alert("Cancelled")}>Cancel</CancelButton>
-    </div>
-  );
-}
-```
-
-- **SubmitButton props**
-  - `type`: "button" | "submit" | "reset" (auto-managed when `onClick` provided)
-  - `onClick(e)`: supports async; shows loader until resolved
-  - `onDoubleClick(e)`: optional alternate handler; debounced vs single click
-  - `isLoading`: boolean external control of loader
-  - `bgGradiant`: boolean gradient background
-
-### Text Inputs
-
-- **FloatingInput**: Floating label text input
-
-```tsx
-import { FloatingInput } from "@rufous/ui";
-
-export function NameField() {
-  const [name, setName] = React.useState("");
-  return (
-    <FloatingInput
-      label="Your Name"
-      name="name"
-      value={name}
-      onChange={(e) => setName(e.target.value)}
-      required
-    />
-  );
-}
-```
-
-- **FloatingInput props**
-  - `label`: string (required)
-  - `name`: string (required)
-  - `id`: string (defaults to `name`)
-  - `type`: string = "text"
-  - `value`: string
-  - `onChange(e)`: (required for controlled usage)
-  - `required`: boolean = false
-  - `placeholder`: string
-  - `className`: string
-  - `...divProps` applied to the wrapper
-
-### Checkboxes
-
-- **Checkbox**: Controlled checkbox with label
+### Autocomplete
+
+```tsx
+import { Autocomplete } from "@rufous/ui";
+
+<Autocomplete
+  options={["React", "Vue", "Angular"]}
+  value={val}
+  onChange={setVal}
+  label="Framework"
+/>
+```
+
+---
+
+### Checkbox
 
 ```tsx
 import { Checkbox } from "@rufous/ui";
 
-export function Terms() {
-  const [checked, setChecked] = React.useState(false);
-  return (
-    <Checkbox
-      id="terms"
-      label="I agree to the terms"
-      checked={checked}
-      onChange={setChecked}
-    />
-  );
-}
-```
-
-- **Checkbox props**
-  - `id`: string
-  - `label`: string
-  - `checked`: boolean
-  - `onChange(nextChecked: boolean)`: required
-  - `disabled`: boolean = false
-  - `className`: string
-  - `style`: React.CSSProperties
-
-### Dialogs
-
-- **BaseDialog**: Unopinionated modal container with header, close button, footer actions
-
-```tsx
-import { BaseDialog, SubmitButton } from "@rufous/ui";
-
-export function ConfirmDialog({ open, onClose, onConfirm }) {
-  return (
-    <BaseDialog
-      open={open}
-      title="Confirm delete"
-      onClose={onClose}
-      onCancel={onClose}
-      onConfirm={onConfirm}
-      buttonAlign="flex-end"
-      showCancelButton
-      fullWidth
-    >
-      <p>Are you sure you want to delete this item?</p>
-    </BaseDialog>
-  );
-}
-```
-
-- **BaseDialog props (key)**
-  - `open`: boolean (required to show)
-  - `title`: string
-  - `onClose()`: close handler
-  - `onCancel()`: cancel handler
-  - `onConfirm()`: sync/async confirm; built-in loading toggle
-  - `cancelText`, `confirmText`, `submitText`: strings
-  - `isLoading`, `loading`, `disableConfirmBtn`: booleans
-  - `minWidth`, `minHeight`, `fullWidth`, `fullScreen`: sizing controls
-  - `buttonAlign`: "flex-start" | "center" | "flex-end"
-  - `showCloseButton`, `showCancelButton`, `formatTitle`
-  - `className`, `dialogBodyStyle`
+<Checkbox
+  label="I agree to the terms"
+  checked={checked}
+  onChange={setChecked}
+/>
+```
+
+---
+
+### Dialog
+
+```tsx
+import { BaseDialog } from "@rufous/ui";
+
+<BaseDialog
+  open={open}
+  title="Confirm Delete"
+  onClose={onClose}
+  onConfirm={onConfirm}
+  showCancelButton
+  fullWidth
+>
+  <p>Are you sure you want to delete this item?</p>
+</BaseDialog>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `open` | `boolean` | Controls visibility |
+| `title` | `string` | Dialog title |
+| `onClose` | `() => void` | Close handler |
+| `onConfirm` | `() => void \| Promise<void>` | Async confirm; shows loader |
+| `showCancelButton` | `boolean` | Show cancel button |
+| `fullWidth` | `boolean` | Full container width |
+| `sx` | `SxProp` | Scoped style overrides |
+
+---
+
+### Slider
+
+```tsx
+import { Slider } from "@rufous/ui";
+
+<Slider label="Volume" value={vol} onChange={setVol} valueLabelDisplay="auto" />
+
+// Range
+<Slider label="Price" value={[20, 80]} onChange={setRange} range min={0} max={200} />
+```
+
+---
+
+### Switch
+
+```tsx
+import { Switch } from "@rufous/ui";
+
+<Switch checked={on} onChange={setOn} label="Enable notifications" />
+```
+
+---
+
+### RadioGroup
+
+```tsx
+import { RadioGroup, Radio } from "@rufous/ui";
+
+<RadioGroup label="Payment" options={options} value={val} onChange={setVal} />
+
+// Composed
+<RadioGroup value={val} onChange={setVal}>
+  <Radio value="card" label="Credit Card" />
+  <Radio value="paypal" label="PayPal" />
+</RadioGroup>
+```
+
+---
+
+### Rating
+
+```tsx
+import { Rating } from "@rufous/ui";
+
+<Rating value={stars} onChange={setStars} />
+<Rating value={4.5} precision={0.5} readOnly />
+```
+
+---
+
+### ToggleButton
+
+```tsx
+import { ToggleButtonGroup, ToggleButton } from "@rufous/ui";
+
+// Exclusive (radio)
+<ToggleButtonGroup value={alignment} onChange={setAlignment} exclusive>
+  <ToggleButton value="left">Left</ToggleButton>
+  <ToggleButton value="center">Center</ToggleButton>
+  <ToggleButton value="right">Right</ToggleButton>
+</ToggleButtonGroup>
+
+// Multi-select
+<ToggleButtonGroup value={formats} onChange={setFormats}>
+  <ToggleButton value="bold"><strong>B</strong></ToggleButton>
+  <ToggleButton value="italic"><em>I</em></ToggleButton>
+</ToggleButtonGroup>
+```
+
+---
+
+### Avatar
+
+```tsx
+import { Avatar, AvatarGroup } from "@rufous/ui";
+
+<Avatar src="/photo.jpg" alt="Alice Johnson" size="medium" />
+<Avatar alt="Alice Johnson" color="#a41b06" />  // initials fallback
+
+<AvatarGroup max={4}>
+  <Avatar alt="Alice" />
+  <Avatar alt="Bob" color="#1565c0" />
+</AvatarGroup>
+```
+
+---
+
+### Chip
+
+```tsx
+import { Chip } from "@rufous/ui";
+
+<Chip label="React" color="primary" />
+<Chip label="Remove me" color="error" onDelete={() => {}} />
+<Chip label="Click me" color="default" variant="outlined" onClick={fn} />
+```
+
+---
+
+### Divider
+
+```tsx
+import { Divider } from "@rufous/ui";
+
+<Divider />
+<Divider variant="middle" />
+<Divider textAlign="center">OR</Divider>
+<Divider orientation="vertical" flexItem />
+```
+
+---
+
+### List
+
+```tsx
+import { List, ListItem, ListItemText, ListItemButton, ListItemIcon, ListSubheader } from "@rufous/ui";
+
+<List subheader={<ListSubheader>Inbox</ListSubheader>}>
+  <ListItemButton selected onClick={fn}>
+    <ListItemIcon>📩</ListItemIcon>
+    <ListItemText primary="Messages" secondary="3 unread" />
+  </ListItemButton>
+</List>
+```
+
+---
+
+### Typography
+
+```tsx
+import { Typography } from "@rufous/ui";
+
+<Typography variant="h1">Heading</Typography>
+<Typography variant="body1" color="textSecondary">Paragraph text</Typography>
+<Typography variant="caption" gutterBottom>Caption</Typography>
+```
+
+---
+
+### Skeleton
+
+```tsx
+import { Skeleton } from "@rufous/ui";
+
+<Skeleton variant="text" width={200} />
+<Skeleton variant="circular" width={40} height={40} />
+<Skeleton variant="rounded" width={300} height={120} animation="wave" />
+```
+
+---
+
+### Tooltip
+
+```tsx
+import { Tooltip } from "@rufous/ui";
+
+<Tooltip title="Delete this item" placement="top" arrow>
+  <button>Delete</button>
+</Tooltip>
+```
+
+---
 
 ### Progress
 
-- **CircularProgress**: Stroke-based loader
+```tsx
+import { CircularProgress, RufousLogoLoader } from "@rufous/ui";
+
+<CircularProgress size={36} />
+<RufousLogoLoader />
+```
+
+---
+
+### Box / Stack / Grid
 
 ```tsx
-import { CircularProgess } from "@rufous/ui"; // exported via SubmitButton internally as well
+import { Box, Stack, Grid } from "@rufous/ui";
+
+// Box — generic flex/layout container
+<Box display="flex" gap={16} padding={24}>...</Box>
+
+// Stack — 1D flex layout
+<Stack direction="row" spacing={2}>
+  <div>A</div>
+  <div>B</div>
+</Stack>
+
+// Grid — 12-column responsive grid
+<Grid container spacing={3}>
+  <Grid item xs={12} md={6}>Main</Grid>
+  <Grid item xs={12} md={6}>Sidebar</Grid>
+</Grid>
+```
+
+---
+
+### Paper / Card / Accordion
+
+```tsx
+import { Paper, Card, CardContent, CardHeader, CardActions, Accordion, AccordionSummary, AccordionDetails } from "@rufous/ui";
 
-export function LoadingExample() {
-  return <CircularProgess size={36} color="#a81c08" />;
-}
+<Paper elevation={3}>Content</Paper>
+
+<Card>
+  <CardHeader title="Title" subheader="Subtitle" />
+  <CardContent>Body</CardContent>
+  <CardActions><button>Action</button></CardActions>
+</Card>
+
+<Accordion>
+  <AccordionSummary>FAQ Question</AccordionSummary>
+  <AccordionDetails>Answer text here.</AccordionDetails>
+</Accordion>
 ```
 
-- **CircularProgess props**
-  - `size`: number = 50
-  - `color`: string = "#a81c08"
-  - `...divProps`
+---
 
-### Icons
+### Tabs
+
+```tsx
+import { Tabs, Tab } from "@rufous/ui";
+
+<Tabs value={tab} onChange={setTab}>
+  <Tab value="home" label="Home" />
+  <Tab value="settings" label="Settings" />
+</Tabs>
+```
 
-All icons are React components that accept standard `svg`/`div`-style props depending on implementation; at minimum `className`, event handlers, and often `color` when applicable.
+---
 
-Usage pattern:
+### Breadcrumbs
 
 ```tsx
-import { CopyIcon, EditIcon, DownloadIcon } from "@rufous/ui";
+import { Breadcrumbs } from "@rufous/ui";
+
+<Breadcrumbs separator="›">
+  <a href="/">Home</a>
+  <a href="/products">Products</a>
+  <span>Current</span>
+</Breadcrumbs>
+```
 
-export function IconRow() {
-  return (
-    <div style={{ display: "flex", gap: 10 }}>
-      <CopyIcon onClick={() => alert("Copied!")} />
-      <EditIcon />
-      <DownloadIcon />
-    </div>
-  );
-}
+---
+
+### Stepper
+
+```tsx
+import { Stepper, Step, StepLabel, StepContent } from "@rufous/ui";
+
+<Stepper activeStep={activeStep}>
+  {steps.map((label) => (
+    <Step key={label}>
+      <StepLabel>{label}</StepLabel>
+    </Step>
+  ))}
+</Stepper>
 ```
 
-Available icons include (non-exhaustive): `ActivateUserIcon`, `ArchivedIcon`, `AssignGroupIcon`, `CloseIcon`, `CopyIcon`, `DifficultyAllIcon`, `DifficultyEasyIcon`, `DifficultyMediumIcon`, `DifficultyHardIcon`, `DollarIcon`, `DownloadIcon`, `DownloadPdfIcon`, `EditChatIcon`, `EditIcon`, `EngagementIcon`, `FunctionIcon`, `HelpOutlinedIcon`, `HierarchyIcon`, `InactiveGroupIcon`, `IndustryIcon`, `InvoiceIcon`, `LocationPinIcon`, `LogsIcon`, `MinExperienceIcon`, `NineDotMenuIcon`, `NotificationIcon`, `ProjectIcon`, `QuestionStatusAllIcon`, `QuestionStatusPrivateIcon`, `QuestionStatusPublicIcon`, `QuestionTypeAllIcon`, `QuestionTypeCodingIcon`, `QuestionTypeDescriptiveIcon`, `QuestionTypeMultipleIcon`, `QuestionTypeSingleIcon`, `RefreshIcon`, `ResendInviteIcon`, `RolesIcon`, `RufousAiIcon`, `RufousBirdIcon`, `RufousLauncherIcon`, `SidebarIcon`, `SubscribeIcon`, `SuspendUserIcon`, `TickIcon`, `TimerIcon`, `TrashIcon`, `UnArchivedIcon`, `UnsubscribeIcon`, `UploadIcon`, `UserAssignIcon`, `ViewIcon`, `WorkItemIcon`, `SoftSkillsIcon`, `TechnicalSkillsIcon`, `QualificationsIcon`.
+---
+
+### Menu
+
+```tsx
+import { Menu, MenuItem, MenuList, MenuDivider } from "@rufous/ui";
+
+<Menu open={open} anchorEl={anchorRef.current} onClose={() => setOpen(false)}>
+  <MenuList>
+    <MenuItem icon="👤">Profile</MenuItem>
+    <MenuItem icon="⚙️">Settings</MenuItem>
+    <MenuDivider />
+    <MenuItem icon="🚪">Sign Out</MenuItem>
+  </MenuList>
+</Menu>
+```
 
 ---
 
-## 🧾 Exports
+### Drawer
 
-The package main re-exports everything you need from a single entry point:
+```tsx
+import { Drawer } from "@rufous/ui";
 
-```ts
-// main entry exports
-export { APP_THEMES } from "./utils/constants";
-export * from "./icons"; // all icons
-export * from "./Buttons"; // AddButton, SubmitButton, CancelButton, StandardButton
-export * from "./Dialogs"; // BaseDialog
-export {
-  RufousThemeProvider,
-  useRufousTheme,
-} from "./Contexts/rufousThemeProvider";
+<Drawer open={open} onClose={() => setOpen(false)} anchor="right" width={320}>
+  <div style={{ padding: 24 }}>Drawer content</div>
+</Drawer>
 ```
 
-Import from `@rufous/ui` directly:
+---
+
+### Snackbar
 
 ```tsx
-import {
-  SubmitButton,
-  BaseDialog,
-  RufousThemeProvider,
-  useRufousTheme,
-  APP_THEMES,
-} from "@rufous/ui";
+import { Snackbar } from "@rufous/ui";
+
+<Snackbar
+  open={open}
+  onClose={() => setOpen(false)}
+  message="Changes saved successfully"
+  severity="success"
+  autoHideDuration={4000}
+  anchorOrigin={{ vertical: "bottom", horizontal: "left" }}
+/>
 ```
 
 ---
 
-## 🧠 Notes
+### Link
 
-- Always import `@rufous/ui/style.css` once to get base styles.
-- `SubmitButton` manages `type` automatically when `onClick` is provided.
-- Dialog confirm button disables while running async `onConfirm` to prevent repeats.
+```tsx
+import { Link } from "@rufous/ui";
+
+<Link href="/docs" color="primary">Documentation</Link>
+<Link component="button" color="primary" onClick={fn}>Trigger action</Link>
+```
 
 ---
 
-## 🐛 Issues / Feedback
+### Popper / Popover
+
+```tsx
+import { Popper, Popover } from "@rufous/ui";
+
+// Popper — no backdrop, low-level
+<Popper open={open} anchorEl={anchorRef.current} placement="bottom-start">
+  <div>Custom dropdown content</div>
+</Popper>
 
-Please open an issue or PR in your repository to report bugs, request components, or propose improvements.
+// Popover — backdrop, closes on outside click
+<Popover open={open} anchorEl={anchorRef.current} onClose={() => setOpen(false)}>
+  <div style={{ padding: 20 }}>Popover content</div>
+</Popover>
+```
+
+---
+
+### Transitions
+
+```tsx
+import { Fade, Slide, Grow, Collapse, Zoom } from "@rufous/ui";
+
+<Fade in={show}><div>Fades in/out</div></Fade>
+<Slide in={show} direction="up"><div>Slides in from bottom</div></Slide>
+<Grow in={show}><div>Grows from center</div></Grow>
+<Collapse in={show}><div>Collapses vertically</div></Collapse>
+<Zoom in={show}><div>Zooms in/out</div></Zoom>
+```
+
+---
+
+### Icons
+
+```tsx
+import { CopyIcon, EditIcon, TrashIcon, DownloadIcon } from "@rufous/ui";
+
+<CopyIcon onClick={() => copy(text)} />
+<EditIcon />
+<TrashIcon />
+<DownloadIcon />
+```
+
+---
+
+## The `sx` Prop
+
+Every component accepts an `sx` prop for scoped, per-instance style overrides using nested CSS selectors. Values are injected as a scoped `<style>` tag — no inline style conflicts.
+
+```tsx
+import { TextField } from "@rufous/ui";
+import type { SxProp } from "@rufous/ui";
+
+<TextField
+  label="Search"
+  sx={{
+    borderRadius: "12px",
+    "& .rf-text-field__input": { fontSize: "0.9rem" },
+    "&:hover": { boxShadow: "0 0 0 3px rgba(164,27,6,0.15)" },
+  }}
+/>
+```
 
 ---
 
-## 📄 License
+## License
 
 MIT © Rufous UI