@raxrai/stylelab-ui 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +220 -0
  2. package/dist/index.cjs +13901 -0
  3. package/dist/index.cjs.map +1 -0
  4. package/dist/index.d.mts +418 -0
  5. package/dist/index.d.ts +418 -0
  6. package/dist/index.mjs +13875 -0
  7. package/dist/index.mjs.map +1 -0
  8. package/package.json +66 -0
  9. package/styles/stylelab.css +107 -0
package/README.md ADDED
@@ -0,0 +1,220 @@
1
+ # StyleLab UI
2
+
3
+ A themeable, accessible React UI library with **8 themes**: Minimal, Night, Glass, Neubrutal, Clay, Cyberpunk, Retro, and Motion. Built with Tailwind CSS v4, CVA, and Lucide icons. NPM-ready with CJS/ESM build and zero heavy dependencies (peer: React).
4
+
5
+ ## Run locally
6
+
7
+ ```bash
8
+ npm install
9
+ npm run dev
10
+ ```
11
+
12
+ Open [http://localhost:3000/gallery](http://localhost:3000/gallery) to see all components and the sticky theme switcher.
13
+
14
+ ## Build library for distribution
15
+
16
+ ```bash
17
+ npm run build:lib
18
+ ```
19
+
20
+ Output: `dist/` (CJS, ESM, and `.d.ts`). The package is already configured for npm (`main`, `module`, `types`, `exports`, `files`). To publish, see **[docs/PUBLISHING-TO-NPM.md](docs/PUBLISHING-TO-NPM.md)** for detailed steps.
21
+
22
+ ---
23
+
24
+ ## Documentation
25
+
26
+ - **[docs/COMPONENTS.md](docs/COMPONENTS.md)** — Full component API: every prop, type, hook, and global (themes, `getThemeClass`, `cn`, etc.).
27
+ - **[docs/PUBLISHING-TO-NPM.md](docs/PUBLISHING-TO-NPM.md)** — How to publish this package to npm (maintainers).
28
+
29
+ ---
30
+
31
+ ## Installation
32
+
33
+ ```bash
34
+ npm install @raxrai/stylelab-ui react react-dom
35
+ ```
36
+
37
+ Peer dependencies: `react` and `react-dom` (>=18). Other runtime deps (e.g. `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`, `framer-motion`) are bundled, so no extra install is required.
38
+
39
+ ### Tailwind + styles
40
+
41
+ Your app must use **Tailwind CSS v4**. Import StyleLab design tokens in your global CSS after Tailwind:
42
+
43
+ ```css
44
+ @import "tailwindcss";
45
+ @import "@raxrai/stylelab-ui/styles";
46
+ ```
47
+
48
+ ### ThemeProvider
49
+
50
+ ```tsx
51
+ import { ThemeProvider } from "@raxrai/stylelab-ui";
52
+
53
+ export default function RootLayout({ children }) {
54
+ return (
55
+ <html>
56
+ <body>
57
+ <ThemeProvider defaultTheme="minimal">{children}</ThemeProvider>
58
+ </body>
59
+ </html>
60
+ );
61
+ }
62
+ ```
63
+
64
+ ### Use components
65
+
66
+ ```tsx
67
+ import { Button, Card, useTheme } from "@raxrai/stylelab-ui";
68
+
69
+ export function MyPage() {
70
+ const { theme, setTheme } = useTheme();
71
+ return (
72
+ <div>
73
+ <Button variant="primary">Click me</Button>
74
+ <Card>Content</Card>
75
+ </div>
76
+ );
77
+ }
78
+ ```
79
+
80
+ **Themes:** `minimal` | `night` | `glass` | `neubrutal` | `clay` | `cyberpunk` | `retro` | `motion`
81
+
82
+ ### Exports
83
+
84
+ **Components:** Accordion, Alert, Avatar, AvatarGroup, Badge, BentoGrid, Breadcrumbs, Button, Calendar, Card, CommandPalette, DashboardShell, DataTable, DocumentAccordion, Dropdown, Flashcard, GraphicCard, Input, Modal, Navbar, PricingCard, ProgressBar, SectionHeader, Sidebar, Skeleton, Slider, StatsCard, Tabs, Terminal, Timeline, Toast, Toggle, Tooltip.
85
+
86
+ **Global:** ThemeProvider, useTheme, getThemeClass, THEMES, StyleLabTheme, cn, getNextListIndex, useFocusTrap, useClickOutside, useKeyboardNavigation.
87
+
88
+ Full API (props, types, usage): see [docs/COMPONENTS.md](docs/COMPONENTS.md).
89
+
90
+ ---
91
+
92
+ ## Component Prop API (overview)
93
+
94
+ ### Button
95
+
96
+ | Prop | Type | Default | Description |
97
+ |------------|--------------------------|------------|--------------------------------------|
98
+ | `as` | `"button"` \| `"a"` | `"button"` | Polymorphic root element |
99
+ | `variant` | `"primary"` \| `"secondary"` \| `"ghost"` | `"primary"` | Visual variant |
100
+ | `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | Size |
101
+ | `isLoading`| `boolean` | `false` | Shows spinner and disables |
102
+ | `leftIcon` | `ReactNode` | — | Icon before children |
103
+ | `rightIcon`| `ReactNode` | — | Icon after children |
104
+ | `className`| `string` | — | Merged with CVA classes |
105
+ | `ref` | `ForwardedRef` | — | Forwarded to root DOM element |
106
+
107
+ ### Input
108
+
109
+ | Prop | Type | Default | Description |
110
+ |-------------|------------|---------|--------------------------------|
111
+ | `label` | `string` | — | Accessible label |
112
+ | `error` | `string` | — | Error message (role="alert") |
113
+ | `helperText`| `string` | — | Hint below input |
114
+ | `prefix` | `ReactNode`| — | Left addon |
115
+ | `suffix` | `ReactNode`| — | Right addon |
116
+ | `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | Size (CVA) |
117
+ | `className` | `string` | — | Merged with CVA |
118
+
119
+ ### Toggle
120
+
121
+ | Prop | Type | Default | Description |
122
+ |-------------------|------------|---------|--------------------------------|
123
+ | `checked` | `boolean` | — | Controlled state |
124
+ | `defaultChecked` | `boolean` | `false` | Uncontrolled initial state |
125
+ | `onCheckedChange`| `(v: boolean) => void` | — | Callback on change |
126
+ | `aria-label` | `string` | `"Toggle"` | Accessible name |
127
+
128
+ Uses a hidden `<input type="checkbox">` for semantics and form compatibility.
129
+
130
+ ### Badge
131
+
132
+ | Prop | Type | Default | Description |
133
+ |------------|----------|-----------|----------------------|
134
+ | `variant` | `"default"` \| `"success"` \| `"warning"` \| `"error"` | `"default"` | Style variant |
135
+ | `dot` | `boolean`| `false` | Leading dot indicator |
136
+
137
+ ### Slider
138
+
139
+ | Prop | Type | Default | Description |
140
+ |-----------------|----------|---------|--------------------------|
141
+ | `min` / `max` | `number` | `0` / `100` | Range bounds |
142
+ | `step` | `number` | `1` | Step value |
143
+ | `value` | `number` | — | Controlled value |
144
+ | `defaultValue` | `number` | `50` | Uncontrolled initial |
145
+ | `onValueChange` | `(v: number) => void` | — | Change callback |
146
+ | `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | Track size |
147
+
148
+ ### Tabs
149
+
150
+ | Prop | Type | Default | Description |
151
+ |----------------|-------------------------|---------|----------------------------|
152
+ | `items` | `{ label, value, content }[]` | — | Tab list |
153
+ | `value` | `string` | — | Controlled active tab |
154
+ | `defaultValue` | `string` | — | Uncontrolled initial |
155
+ | `onValueChange`| `(value: string) => void` | — | Callback on tab change |
156
+
157
+ Arrow keys (Left/Right) move focus and change tab; theme from context or `theme` prop.
158
+
159
+ ### Card
160
+
161
+ | Prop | Type | Default | Description |
162
+ |--------------|------------|---------|--------------------------|
163
+ | `header` | `ReactNode`| — | Optional header slot |
164
+ | `footer` | `ReactNode`| — | Optional footer slot |
165
+ | `padding` | `"none"` \| `"sm"` \| `"md"` | `"md"` | Inner padding |
166
+ | `isHoverable`| `boolean` | `false` | Hover shadow transition |
167
+
168
+ ### Accordion
169
+
170
+ | Prop | Type | Default | Description |
171
+ |----------------|----------|---------|-----------------------------|
172
+ | `items` | `{ id, title, content }[]` | — | Items |
173
+ | `allowMultiple`| `boolean`| `false` | Allow multiple panels open |
174
+
175
+ Uses manual height animation (no external libs).
176
+
177
+ ### Modal
178
+
179
+ | Prop | Type | Default | Description |
180
+ |----------|------------|---------|----------------------------|
181
+ | `open` | `boolean` | — | Visibility |
182
+ | `onClose`| `() => void` | — | Close handler |
183
+ | `title` | `string` | — | Optional title (and close) |
184
+ | `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | Max width |
185
+
186
+ Implements focus trap and scroll lock when open.
187
+
188
+ ### Tooltip
189
+
190
+ | Prop | Type | Default | Description |
191
+ |-------------|----------|---------|--------------------|
192
+ | `content` | `ReactNode` | — | Tooltip body |
193
+ | `placement` | `"top"` \| `"bottom"` \| `"left"` \| `"right"` | `"top"` | Position |
194
+
195
+ ### Dropdown
196
+
197
+ | Prop | Type | Default | Description |
198
+ |----------------|-------------------------|---------|--------------------------|
199
+ | `trigger` | `ReactNode` | — | Button / element to open |
200
+ | `items` | `{ value, label, disabled? }[]` | — | Options |
201
+ | `value` / `defaultValue` | `string` | — | Controlled / initial |
202
+ | `onValueChange`| `(value: string) => void` | — | Selection callback |
203
+
204
+ Keyboard: Enter/Space to open, Arrows to move, Enter to select, Escape to close.
205
+
206
+ ---
207
+
208
+ ## Utilities & hooks
209
+
210
+ ```tsx
211
+ import { cn, useFocusTrap, useClickOutside, useKeyboardNavigation, getNextListIndex } from "@raxrai/stylelab-ui";
212
+ ```
213
+
214
+ - **cn(...)** – `clsx` + `tailwind-merge` for class names.
215
+ - **useFocusTrap(active, options?)** – Traps focus in a container ref (e.g. Modal).
216
+ - **useClickOutside(ref(s), handler, options?)** – Fires when click is outside ref(s).
217
+ - **useKeyboardNavigation({ onEscape, onArrowLeft, onArrowRight, ... })** – Document-level key handlers.
218
+ - **getNextListIndex(current, direction, length)** – Index for arrow-key list/tab navigation.
219
+
220
+ ---