@rufous/ui 0.1.6 → 0.1.8

package/README.md

@@ -1,242 +1,569 @@
-# @rufous/ui
+# Rufous UI
 
-A modern and reusable UI component library for React.  
-Includes buttons, floating inputs, checkboxes, theme support, and icons.
+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.
+
+**Live Showcase → [ui.dev.rufous.com](https://ui.dev.rufous.com/)**
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @rufous/ui
-```
-
-or
-
-```bash
+# or
 yarn add @rufous/ui
 ```
 
 ---
 
-## 🎯 Usage
+## Setup
 
-Before using any components, **import the global styles**:
+Import the global styles once in your app entry:
 
-```javascript
+```tsx
 import "@rufous/ui/style.css";
 ```
 
+Wrap your app with the theme provider:
+
+```tsx
+import { RufousThemeProvider } from "@rufous/ui";
+import "@rufous/ui/style.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <RufousThemeProvider>
+    <App />
+  </RufousThemeProvider>
+);
+```
+
 ---
 
-## 🧩 Components Showcase
+## Components
+
+### Buttons
 
-Below are usage examples of all the components available in the showcase.
+```tsx
+import { StandardButton, AddButton, SubmitButton, CancelButton } from "@rufous/ui";
+
+<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 |
 
 ---
 
-### 🧱 Button
+### TextField
 
-```jsx
-import React from "react";
-import { Button } from "@rufous/ui";
-import "@rufous/ui/style.css";
+```tsx
+import { TextField } from "@rufous/ui";
 
-export default function Example() {
-  return (
-    <Button onClick={() => alert("Rufous Button clicked!")}>Click Me</Button>
-  );
-}
+<TextField
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+  variant="outlined"
+  required
+/>
 ```
 
+| 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` | — |
+
 ---
 
-### ✍️ Floating Input
+### Select
 
-```jsx
-import React, { useState } from "react";
-import { FloatingInput } from "@rufous/ui";
-import "@rufous/ui/style.css";
+```tsx
+import { Select } from "@rufous/ui";
 
-export default function Example() {
-  const [name, setName] = useState("");
+<Select
+  options={[{ value: "us", label: "United States" }]}
+  value={country}
+  onChange={setCountry}
+  label="Country"
+/>
 
-  return (
-    <FloatingInput
-      label="Your Name"
-      name="name"
-      value={name}
-      onChange={(e) => setName(e.target.value)}
-      required
-    />
-  );
-}
+// Multiple selection
+<Select options={options} value={selected} onChange={setSelected} multiple label="Tags" />
 ```
 
 ---
 
-### 🎨 Theme Provider
+### DateField / DateRangeField
 
-```jsx
-import React from "react";
-import { Button, useRufousTheme, APP_THEMES } from "@rufous/ui";
-import "@rufous/ui/style.css";
+```tsx
+import { DateField, DateRangeField } from "@rufous/ui";
+
+<DateField label="Start Date" value={date} onChange={setDate} />
+
+<DateRangeField
+  label="Date Range"
+  value={range}
+  onChange={setRange}
+/>
+```
 
-export default function Example() {
-  const { previewTheme } = useRufousTheme();
+---
+
+### Autocomplete
+
+```tsx
+import { Autocomplete } from "@rufous/ui";
 
-  return (
-    <>
-      <Button
-        onClick={() => previewTheme(APP_THEMES.default.name.toLowerCase())}
-      >
-        Light
-      </Button>
-      <Button
-        onClick={() => previewTheme(APP_THEMES.rufous.name.toLowerCase())}
-      >
-        Dark
-      </Button>
-    </>
-  );
-}
+<Autocomplete
+  options={["React", "Vue", "Angular"]}
+  value={val}
+  onChange={setVal}
+  label="Framework"
+/>
 ```
 
 ---
 
-### ☑️ Checkbox
+### Checkbox
 
-```jsx
-import React from "react";
+```tsx
 import { Checkbox } from "@rufous/ui";
-import "@rufous/ui/style.css";
 
-export default function Example() {
-  return (
-    <>
-      <Checkbox label="Unchecked" />
-      <Checkbox checked={true} label="Checked" />
-    </>
-  );
-}
+<Checkbox
+  label="I agree to the terms"
+  checked={checked}
+  onChange={setChecked}
+/>
 ```
 
 ---
 
-### 🖼 Icons (Extra Example)
+### 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>
+```
 
-```jsx
-import React from "react";
-import { CopyIcon, EditIcon } from "@rufous/ui";
-import "@rufous/ui/style.css";
+| 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" />
 
-export default function Example() {
-  return (
-    <div style={{ display: "flex", gap: "10px" }}>
-      <CopyIcon onClick={() => alert("Copied!")} />
-      <EditIcon onClick={() => alert("Edit clicked!")} />
-    </div>
-  );
-}
+// Range
+<Slider label="Price" value={[20, 80]} onChange={setRange} range min={0} max={200} />
 ```
 
 ---
 
-## 📋 Props Reference
+### Switch
 
-### **Button**
+```tsx
+import { Switch } from "@rufous/ui";
 
-| Prop    | Type     | Default | Description           |
-| ------- | -------- | ------- | --------------------- |
-| variant | string   | primary | Sets the button style |
-| size    | string   | medium  | Sets the button size  |
-| onClick | function | -       | Click event handler   |
+<Switch checked={on} onChange={setOn} label="Enable notifications" />
+```
 
 ---
 
-### **FloatingInput**
+### RadioGroup
+
+```tsx
+import { RadioGroup, Radio } from "@rufous/ui";
 
-| Prop     | Type     | Default | Description            |
-| -------- | -------- | ------- | ---------------------- |
-| label    | string   | -       | Floating label text    |
-| name     | string   | -       | Input name attribute   |
-| value    | string   | -       | Input value            |
-| onChange | function | -       | Change event handler   |
-| required | boolean  | false   | Mark field as required |
+<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>
+```
 
 ---
 
-### **Checkbox**
+### Rating
+
+```tsx
+import { Rating } from "@rufous/ui";
 
-| Prop     | Type     | Default | Description          |
-| -------- | -------- | ------- | -------------------- |
-| label    | string   | -       | Checkbox label       |
-| checked  | boolean  | false   | Checked state        |
-| onChange | function | -       | Change event handler |
+<Rating value={stars} onChange={setStars} />
+<Rating value={4.5} precision={0.5} readOnly />
+```
 
 ---
 
-## 📌 Quick Start Example
+### ToggleButton
 
-Here’s a **full example** using multiple components:
+```tsx
+import { ToggleButtonGroup, ToggleButton } from "@rufous/ui";
 
-```jsx
-import React, { useState } from "react";
-import {
-  Button,
-  FloatingInput,
-  Checkbox,
-  CopyIcon,
-  EditIcon,
-  useRufousTheme,
-  APP_THEMES,
-} from "@rufous/ui";
-import "@rufous/ui/style.css";
+// 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
+
+```tsx
+import { CircularProgress, RufousLogoLoader } from "@rufous/ui";
+
+<CircularProgress size={36} />
+<RufousLogoLoader />
+```
+
+---
+
+### Box / Stack / Grid
+
+```tsx
+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";
+
+<Paper elevation={3}>Content</Paper>
+
+<Card>
+  <CardHeader title="Title" subheader="Subtitle" />
+  <CardContent>Body</CardContent>
+  <CardActions><button>Action</button></CardActions>
+</Card>
 
-export default function App() {
-  const [name, setName] = useState("");
-  const { previewTheme } = useRufousTheme();
+<Accordion>
+  <AccordionSummary>FAQ Question</AccordionSummary>
+  <AccordionDetails>Answer text here.</AccordionDetails>
+</Accordion>
+```
+
+---
+
+### Tabs
+
+```tsx
+import { Tabs, Tab } from "@rufous/ui";
+
+<Tabs value={tab} onChange={setTab}>
+  <Tab value="home" label="Home" />
+  <Tab value="settings" label="Settings" />
+</Tabs>
+```
+
+---
+
+### Breadcrumbs
+
+```tsx
+import { Breadcrumbs } from "@rufous/ui";
+
+<Breadcrumbs separator="›">
+  <a href="/">Home</a>
+  <a href="/products">Products</a>
+  <span>Current</span>
+</Breadcrumbs>
+```
+
+---
+
+### Stepper
+
+```tsx
+import { Stepper, Step, StepLabel, StepContent } from "@rufous/ui";
+
+<Stepper activeStep={activeStep}>
+  {steps.map((label) => (
+    <Step key={label}>
+      <StepLabel>{label}</StepLabel>
+    </Step>
+  ))}
+</Stepper>
+```
+
+---
 
-  return (
-    <div style={{ padding: "20px" }}>
-      <h1>Rufous UI Demo</h1>
+### Menu
 
-      <Button onClick={() => alert("Hello!")}>Click Me</Button>
+```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>
+```
+
+---
+
+### Drawer
+
+```tsx
+import { Drawer } from "@rufous/ui";
+
+<Drawer open={open} onClose={() => setOpen(false)} anchor="right" width={320}>
+  <div style={{ padding: 24 }}>Drawer content</div>
+</Drawer>
+```
+
+---
+
+### Snackbar
+
+```tsx
+import { Snackbar } from "@rufous/ui";
+
+<Snackbar
+  open={open}
+  onClose={() => setOpen(false)}
+  message="Changes saved successfully"
+  severity="success"
+  autoHideDuration={4000}
+  anchorOrigin={{ vertical: "bottom", horizontal: "left" }}
+/>
+```
+
+---
+
+### Link
+
+```tsx
+import { Link } from "@rufous/ui";
+
+<Link href="/docs" color="primary">Documentation</Link>
+<Link component="button" color="primary" onClick={fn}>Trigger action</Link>
+```
+
+---
+
+### 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>
+
+// 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 />
+```
+
+---
 
-      <FloatingInput
-        label="Your Name"
-        name="name"
-        value={name}
-        onChange={(e) => setName(e.target.value)}
-        required
-      />
+## The `sx` Prop
 
-      <Checkbox label="Accept Terms" />
+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.
 
-      <div style={{ marginTop: "10px" }}>
-        <Button
-          onClick={() => previewTheme(APP_THEMES.default.name.toLowerCase())}
-        >
-          Light Theme
-        </Button>
-        <Button
-          onClick={() => previewTheme(APP_THEMES.rufous.name.toLowerCase())}
-        >
-          Dark Theme
-        </Button>
-      </div>
+```tsx
+import { TextField } from "@rufous/ui";
+import type { SxProp } from "@rufous/ui";
 
-      <div style={{ display: "flex", gap: "10px", marginTop: "10px" }}>
-        <CopyIcon onClick={() => alert("Copied!")} />
-        <EditIcon onClick={() => alert("Edit clicked!")} />
-      </div>
-    </div>
-  );
-}
+<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