@memelabui/ui 0.8.1 → 0.9.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.
- package/README.md +427 -429
- package/dist/index.cjs +2308 -844
- package/dist/index.d.cts +272 -25
- package/dist/index.d.ts +272 -25
- package/dist/index.js +2307 -846
- package/dist/styles/index.css +2775 -2496
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,429 +1,427 @@
|
|
|
1
|
-
# @memelabui/ui
|
|
2
|
-
|
|
3
|
-
Shared UI component library for MemeLab projects. Dark-first glassmorphism design system built with React, TypeScript, and Tailwind CSS.
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@memelabui/ui)
|
|
6
|
-
|
|
7
|
-
## Install
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
pnpm add @memelabui/ui
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Peer dependencies: `react >= 18`, `react-dom >= 18`, `tailwindcss >= 3.4`.
|
|
14
|
-
|
|
15
|
-
## Setup
|
|
16
|
-
|
|
17
|
-
### 1. Tailwind preset
|
|
18
|
-
|
|
19
|
-
```ts
|
|
20
|
-
// tailwind.config.ts
|
|
21
|
-
import memelabPreset from '@memelabui/ui/preset';
|
|
22
|
-
|
|
23
|
-
export default {
|
|
24
|
-
presets: [memelabPreset],
|
|
25
|
-
content: [
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
|
68
|
-
|
|
69
|
-
| `.
|
|
70
|
-
| `.surface`
|
|
71
|
-
| `.
|
|
72
|
-
| `.
|
|
73
|
-
| `.
|
|
74
|
-
| `.
|
|
75
|
-
| `.
|
|
76
|
-
| `.
|
|
77
|
-
| `.
|
|
78
|
-
| `.
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
<
|
|
90
|
-
<
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
<
|
|
96
|
-
<
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
|
110
|
-
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
- Need
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
<
|
|
126
|
-
<
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
<
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
|
144
|
-
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `Textarea`
|
|
148
|
-
| `Select`
|
|
149
|
-
| `Combobox`
|
|
150
|
-
| `Checkbox`
|
|
151
|
-
| `RadioGroup` / `RadioItem` | Radio button group
|
|
152
|
-
| `Toggle`
|
|
153
|
-
| `Slider`
|
|
154
|
-
| `TagInput`
|
|
155
|
-
| `ColorInput`
|
|
156
|
-
| `FormField`
|
|
157
|
-
|
|
158
|
-
```tsx
|
|
159
|
-
// Full form with Toggle + Input + Select
|
|
160
|
-
<Card variant="glass" hoverable>
|
|
161
|
-
<h2 className="section-title">Bot Personality</h2>
|
|
162
|
-
<Input label="Bot name" value="MemeBot" />
|
|
163
|
-
<Textarea label="Personality" placeholder="Friendly, humorous..." />
|
|
164
|
-
<Select label="Response style">
|
|
165
|
-
<option value="concise">Concise</option>
|
|
166
|
-
<option value="detailed">Detailed</option>
|
|
167
|
-
</Select>
|
|
168
|
-
<Toggle
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
|
187
|
-
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
|
202
|
-
|
|
203
|
-
| `
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
|
210
|
-
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `
|
|
215
|
-
| `
|
|
216
|
-
| `
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
|
223
|
-
|
|
224
|
-
| `
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
|
240
|
-
|
|
241
|
-
| `
|
|
242
|
-
| `
|
|
243
|
-
| `
|
|
244
|
-
| `
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
|
289
|
-
|
|
|
290
|
-
| `
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
|
295
|
-
|
|
296
|
-
| `
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
<
|
|
325
|
-
|
|
326
|
-
<
|
|
327
|
-
<
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
}
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
:
|
|
385
|
-
--ml-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
- **
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
MIT
|
|
1
|
+
# @memelabui/ui
|
|
2
|
+
|
|
3
|
+
Shared UI component library for MemeLab projects. Dark-first glassmorphism design system built with React, TypeScript, and Tailwind CSS.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@memelabui/ui)
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @memelabui/ui
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Peer dependencies: `react >= 18`, `react-dom >= 18`, `tailwindcss >= 3.4`.
|
|
14
|
+
|
|
15
|
+
## Setup
|
|
16
|
+
|
|
17
|
+
### 1. Tailwind preset
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
// tailwind.config.ts
|
|
21
|
+
import memelabPreset from '@memelabui/ui/preset';
|
|
22
|
+
|
|
23
|
+
export default {
|
|
24
|
+
presets: [memelabPreset],
|
|
25
|
+
content: ['./src/**/*.{ts,tsx}', './node_modules/@memelabui/ui/dist/**/*.{js,mjs}'],
|
|
26
|
+
};
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The preset adds MemeLab colors (`primary`, `accent`, `surface`, `glow`), animations, border radius, and box shadow tokens to your Tailwind config. No component CSS is duplicated — component styles come from the CSS import below.
|
|
30
|
+
|
|
31
|
+
### 2. Import styles
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// main.tsx (before your app code)
|
|
35
|
+
import '@memelabui/ui/styles';
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
This imports base styles, CSS variables (`--ml-*` tokens), glassmorphism utility classes, and component animations. Must be imported once at the root of your app.
|
|
39
|
+
|
|
40
|
+
### 3. Use components
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
import { Button, Card, Input, ToastProvider } from '@memelabui/ui';
|
|
44
|
+
|
|
45
|
+
function App() {
|
|
46
|
+
return (
|
|
47
|
+
<ToastProvider>
|
|
48
|
+
<Card variant="glass" hoverable>
|
|
49
|
+
<h2 className="section-title">Login</h2>
|
|
50
|
+
<Input label="Email" placeholder="you@example.com" />
|
|
51
|
+
<Button variant="primary" className="mt-4">
|
|
52
|
+
Submit
|
|
53
|
+
</Button>
|
|
54
|
+
</Card>
|
|
55
|
+
</ToastProvider>
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## CSS Utility Classes
|
|
63
|
+
|
|
64
|
+
These classes are available globally after importing `@memelabui/ui/styles`. They provide the MemeLab visual foundation.
|
|
65
|
+
|
|
66
|
+
| Class | Purpose | When to use |
|
|
67
|
+
| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
68
|
+
| `.glass` | Glassmorphism panel — translucent `bg`, `backdrop-filter: blur(16px)`, inset border, rounded | Visual shell for containers. **Does not include padding** — use `Card` component for padded cards |
|
|
69
|
+
| `.surface` | Surface panel — slightly more opaque `bg`, `blur(12px)`, border shadow | Alternative to `.glass` with stronger background. Also **no padding** |
|
|
70
|
+
| `.surface-hover` | Hover elevation transition — adds `box-shadow` on hover | Pair with `.glass` or `.surface` for interactive cards |
|
|
71
|
+
| `.section-title` | Card section heading — `font-semibold`, `border-bottom`, `mb-4` | Use inside `Card` for titled sections (settings, forms) |
|
|
72
|
+
| `.text-gradient` | Gradient text (violet to pink) | Branding, hero headings |
|
|
73
|
+
| `.animated-gradient` | Animated gradient background | Decorative elements, loading placeholders |
|
|
74
|
+
| `.page-container` | Centered max-w-80rem container with responsive padding | Page-level wrapper |
|
|
75
|
+
| `.orb` / `.orb-purple` / `.orb-blue` / `.orb-pink` | Decorative blurred orbs | Background effects (see `PageShell`) |
|
|
76
|
+
| `.pb-safe` / `.pt-safe` | iOS safe area padding | Mobile bottom/top bars |
|
|
77
|
+
| `.no-scrollbar` | Hides scrollbar | Horizontal scroll areas, custom scrolling |
|
|
78
|
+
| `.link-soft` | Subtle underline link | Secondary navigation links |
|
|
79
|
+
|
|
80
|
+
### Important: `.glass` / `.surface` vs `Card`
|
|
81
|
+
|
|
82
|
+
The `.glass` and `.surface` CSS classes are **visual treatments only** — they add background, blur, border, and shadow. They intentionally do **not** include padding because they're used across diverse elements (headers, sidebars, modals, custom layouts).
|
|
83
|
+
|
|
84
|
+
**For content cards, always use the `Card` component** instead of raw `.glass`/`.surface` classes. `Card` provides built-in padding (`p-5` by default) plus correct ARIA semantics.
|
|
85
|
+
|
|
86
|
+
```tsx
|
|
87
|
+
// Correct — Card handles padding automatically
|
|
88
|
+
<Card variant="glass" hoverable>
|
|
89
|
+
<h2 className="section-title">Settings</h2>
|
|
90
|
+
<Input label="Name" />
|
|
91
|
+
</Card>
|
|
92
|
+
|
|
93
|
+
// Avoid — raw classes require manual padding
|
|
94
|
+
<div className="glass surface-hover p-5">
|
|
95
|
+
<h2 className="section-title">Settings</h2>
|
|
96
|
+
<Input label="Name" />
|
|
97
|
+
</div>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Components
|
|
103
|
+
|
|
104
|
+
### Cards & Containers
|
|
105
|
+
|
|
106
|
+
Use these to wrap content sections. Each has different levels of structure.
|
|
107
|
+
|
|
108
|
+
| Component | When to use | Key props |
|
|
109
|
+
| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
|
|
110
|
+
| `Card` | Generic content container with glassmorphism | `variant` (`'surface'` / `'glass'`), `hoverable`, `padding` (`'none'` / `'sm'` / `'md'` / `'lg'`) |
|
|
111
|
+
| `SectionCard` | Settings/config section with title, description, and optional right slot | `title`, `description?`, `right?`, `overlay?` |
|
|
112
|
+
| `StatCard` | Dashboard metric tile with clickable, compact, and compound variants | `value`, `label`, `icon?`, `trend?`, `size?`, `secondaryMetric?`, `href?`, `loading?` |
|
|
113
|
+
| `CollapsibleSection` | Expandable/collapsible content block | `title`, `defaultOpen?` |
|
|
114
|
+
|
|
115
|
+
**Choosing the right card:**
|
|
116
|
+
|
|
117
|
+
- Building a **settings form section** (title + form fields)? Use `SectionCard`
|
|
118
|
+
- Showing a **dashboard metric** (number + label + icon)? Use `StatCard`
|
|
119
|
+
- Need a **generic container** with glass/surface styling? Use `Card`
|
|
120
|
+
- Need an **expandable block**? Use `CollapsibleSection`
|
|
121
|
+
|
|
122
|
+
```tsx
|
|
123
|
+
// Settings page section
|
|
124
|
+
<SectionCard title="AI Provider" description="Choose the AI model for your bot">
|
|
125
|
+
<Select label="Provider" />
|
|
126
|
+
<Input label="Model" placeholder="Default" />
|
|
127
|
+
</SectionCard>
|
|
128
|
+
|
|
129
|
+
// Dashboard metric
|
|
130
|
+
<StatCard value="1,234" label="Messages today" trend={{ value: 12, label: 'vs last week' }} />
|
|
131
|
+
|
|
132
|
+
// Generic glass card
|
|
133
|
+
<Card variant="glass" hoverable padding="lg">
|
|
134
|
+
<p>Any content here</p>
|
|
135
|
+
</Card>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Form Inputs
|
|
139
|
+
|
|
140
|
+
All form components accept `label`, `error`, and `helperText` props with automatic ARIA linkage (`aria-invalid`, `aria-describedby`). They use `forwardRef` for ref forwarding and spread all native HTML attributes.
|
|
141
|
+
|
|
142
|
+
| Component | When to use | Key props |
|
|
143
|
+
| -------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
|
|
144
|
+
| `Input` | Single-line text input | `label?`, `error?`, `helperText?`, `hasError?` + all `<input>` attrs |
|
|
145
|
+
| `SearchInput` | Search field with icon and clear button | `onClear?` + all `Input` props |
|
|
146
|
+
| `DateRangePicker` | Date range input with presets, calendar popover, and mobile drawer | `value`, `onChange`, `presets?`, `maxRangeDays?`, `compact?` |
|
|
147
|
+
| `Textarea` | Multi-line text input | `label?`, `error?` + all `<textarea>` attrs |
|
|
148
|
+
| `Select` | Native dropdown select | `label?`, `error?` + all `<select>` attrs |
|
|
149
|
+
| `Combobox` | Searchable select with keyboard navigation | `options`, `value`, `onChange`, `placeholder?` |
|
|
150
|
+
| `Checkbox` | Checkbox with label and indeterminate support | `label?`, `indeterminate?`, `checked`, `onChange` |
|
|
151
|
+
| `RadioGroup` / `RadioItem` | Radio button group | `value`, `onChange` on Group; `value`, `label` on Item |
|
|
152
|
+
| `Toggle` | On/off switch | `checked`, `onChange(boolean)`, `label?`, `busy?`, `size?` |
|
|
153
|
+
| `Slider` | Range slider with value display | `min`, `max`, `value`, `onChange` |
|
|
154
|
+
| `TagInput` | Tag input with Enter/comma/paste support | `value: string[]`, `onChange`, `maxTags?` |
|
|
155
|
+
| `ColorInput` | Hex color picker with swatch | `value`, `onChange` |
|
|
156
|
+
| `FormField` | Generic wrapper for any input (label + error + helper) | `label`, `error?`, `helperText?`, `children` |
|
|
157
|
+
|
|
158
|
+
```tsx
|
|
159
|
+
// Full form with Toggle + Input + Select
|
|
160
|
+
<Card variant="glass" hoverable>
|
|
161
|
+
<h2 className="section-title">Bot Personality</h2>
|
|
162
|
+
<Input label="Bot name" value="MemeBot" />
|
|
163
|
+
<Textarea label="Personality" placeholder="Friendly, humorous..." />
|
|
164
|
+
<Select label="Response style">
|
|
165
|
+
<option value="concise">Concise</option>
|
|
166
|
+
<option value="detailed">Detailed</option>
|
|
167
|
+
</Select>
|
|
168
|
+
<Toggle label="Respond to @mentions" checked={mentionEnabled} onChange={setMentionEnabled} />
|
|
169
|
+
</Card>
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### Buttons
|
|
173
|
+
|
|
174
|
+
| Component | When to use | Key props |
|
|
175
|
+
| ---------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
176
|
+
| `Button` | Primary actions, form submits, navigation | `variant` (`'primary'` / `'secondary'` / `'danger'` / `'success'` / `'warning'` / `'ghost'`), `loading?`, `size?` |
|
|
177
|
+
| `IconButton` | Icon-only actions (close, menu, refresh) | `aria-label` (required), `variant?`, `size?` |
|
|
178
|
+
| `ProgressButton` | Button with shimmer loading state | `loading?`, `progress?` |
|
|
179
|
+
|
|
180
|
+
### Data Display
|
|
181
|
+
|
|
182
|
+
| Component | When to use | Key props |
|
|
183
|
+
| ------------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
184
|
+
| `Badge` / `Pill` | Status labels, tags, categories | `variant` (`'neutral'` / `'primary'` / `'success'` / `'danger'` / `'warning'` / `'accent'` / `'successSolid'` / `'dangerSolid'`), `size?` |
|
|
185
|
+
| `Table` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` | Table primitives | Compound — compose like native `<table>` |
|
|
186
|
+
| `DataTable` | CMS tables with sorting, filters, search, and pagination | `data`, `columns`, `filters?`, `sortBy?`, `page?`, `pageSize?`, `loading?` |
|
|
187
|
+
| `Timeline` | Activity history, audits, and event feeds | `events`, `groupBy?`, `order?`, `timestampPosition?`, `maxVisible?` |
|
|
188
|
+
| `Tabs` / `TabList` / `Tab` / `TabPanel` | Tabbed content switching | `variant` (`'underline'` / `'pill'`); compound pattern |
|
|
189
|
+
| `EmptyState` | Empty content placeholder | `icon?`, `title`, `description?`, `action?` |
|
|
190
|
+
| `Skeleton` | Loading placeholder | `width?`, `height?`, `rounded?` |
|
|
191
|
+
| `Spinner` | Loading indicator | `size` (`'sm'` / `'md'` / `'lg'`) |
|
|
192
|
+
| `Avatar` | User avatar with fallback | `src?`, `name?`, `size?` |
|
|
193
|
+
| `Divider` | Separator line | `orientation?`, `label?` |
|
|
194
|
+
| `ActiveFilterPills` | Filter pill bar with clear-all | `filters`, `onRemove`, `onClearAll` |
|
|
195
|
+
| `DotIndicator` | Remaining count dots | `count`, `max?` |
|
|
196
|
+
|
|
197
|
+
### Navigation
|
|
198
|
+
|
|
199
|
+
| Component | When to use | Key props |
|
|
200
|
+
| ------------- | --------------------------- | -------------------------------- |
|
|
201
|
+
| `Pagination` | Page navigation | `page`, `totalPages`, `onPageChange` |
|
|
202
|
+
| `Stepper` | Multi-step wizard indicator | `steps`, `activeStep` |
|
|
203
|
+
| `Breadcrumbs` | Breadcrumb path with collapse support | `items`, `maxItems?`, `renderLink?`, `separator?` |
|
|
204
|
+
|
|
205
|
+
### Overlay & Popups
|
|
206
|
+
|
|
207
|
+
| Component | When to use | Key props |
|
|
208
|
+
| ------------------ | -------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
209
|
+
| `Modal` | Dialog / fullscreen overlay | `isOpen`, `onClose`, `children` |
|
|
210
|
+
| `ConfirmDialog` | Confirmation prompts (delete, discard) | `isOpen`, `onConfirm`, `onClose`, `title`, `message` |
|
|
211
|
+
| `Tooltip` | Hover/focus info text | `content`, `children` (trigger) |
|
|
212
|
+
| `Dropdown` | Dropdown menu (context menu, actions) | Compound: `DropdownTrigger` + `DropdownMenu` + `DropdownItem` + `DropdownSeparator` |
|
|
213
|
+
| `Popover` | Click-triggered popup | `trigger`, `children` (content) |
|
|
214
|
+
| `Drawer` | Slide-in side panel | `open`, `onClose`, `position` (`'left'` / `'right'` / `'bottom'`) |
|
|
215
|
+
| `MutationOverlay` | Saving/saved/error status indicator | `status` (`'idle'` / `'saving'` / `'saved'` / `'error'`) |
|
|
216
|
+
| `NotificationBell` | Notification button with badge | `count`, `onClick` |
|
|
217
|
+
|
|
218
|
+
### Progress & Status
|
|
219
|
+
|
|
220
|
+
| Component | When to use | Key props |
|
|
221
|
+
| --------------- | --------------------------- | ------------------------------------ |
|
|
222
|
+
| `ProgressBar` | Linear progress indicator | `value`, `max?`, `variant?`, `size?` |
|
|
223
|
+
| `CooldownRing` | Circular countdown timer | `remaining`, `total` |
|
|
224
|
+
| `StageProgress` | Multi-stage process tracker | `stages`, `currentStage` |
|
|
225
|
+
|
|
226
|
+
### Typography
|
|
227
|
+
|
|
228
|
+
| Component | When to use | Key props |
|
|
229
|
+
| --------- | --------------------------- | ------------------------------------------------------------------ |
|
|
230
|
+
| `Heading` | Section headings h1-h6 | `as` (`'h1'` - `'h6'`), `size?`, `gradient?` |
|
|
231
|
+
| `Text` | Body text, captions, labels | `as` (`'p'` / `'span'`), `size?`, `color?`, `weight?`, `truncate?` |
|
|
232
|
+
|
|
233
|
+
### Layout
|
|
234
|
+
|
|
235
|
+
These components provide the overall page structure. Use them together for full-page layouts.
|
|
236
|
+
|
|
237
|
+
| Component | When to use | Key props |
|
|
238
|
+
| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
239
|
+
| `PageShell` | Page wrapper with animated gradient orbs | `children` |
|
|
240
|
+
| `DashboardLayout` | Full dashboard layout or built-in app shell | `navbar`, `sidebar`, `children`, `brand`, `user`, `headerActions`, `navItems` |
|
|
241
|
+
| `Navbar` | Fixed top navigation bar with glass effect | `logo?`, `children` (right-side content), `glass?` |
|
|
242
|
+
| `Sidebar` | Collapsible side navigation | `collapsed?`, `onToggle?`, `children` (nav items) |
|
|
243
|
+
| `Stack` | Flex container | `direction?`, `gap?`, `align?`, `justify?` |
|
|
244
|
+
| `ScrollArea` | Scrollable container with styled scrollbar | `children` |
|
|
245
|
+
|
|
246
|
+
**Full page layout example:**
|
|
247
|
+
|
|
248
|
+
```tsx
|
|
249
|
+
import { Button, Card, DashboardLayout, Input } from '@memelabui/ui';
|
|
250
|
+
|
|
251
|
+
function App() {
|
|
252
|
+
return (
|
|
253
|
+
<DashboardLayout
|
|
254
|
+
brand={<span className="text-gradient font-bold">MyApp</span>}
|
|
255
|
+
headerActions={<Button variant="ghost">Sign out</Button>}
|
|
256
|
+
navItems={[
|
|
257
|
+
{ label: 'Overview', icon: '📊', href: '/dashboard', active: true },
|
|
258
|
+
{ label: 'Settings', icon: '⚙️', href: '/settings' },
|
|
259
|
+
]}
|
|
260
|
+
maxWidth="full"
|
|
261
|
+
>
|
|
262
|
+
<Card variant="glass" hoverable>
|
|
263
|
+
<h2 className="section-title">Settings</h2>
|
|
264
|
+
<Input label="Bot name" />
|
|
265
|
+
</Card>
|
|
266
|
+
</DashboardLayout>
|
|
267
|
+
);
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
### Feedback
|
|
272
|
+
|
|
273
|
+
| Component | When to use | Key props |
|
|
274
|
+
| ---------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
275
|
+
| `ToastProvider` / `useToast` | Toast notifications (wrap app root in Provider) | `useToast()` returns `{ toast }` function |
|
|
276
|
+
| `Alert` | Inline notification banner | `variant` (`'info'` / `'success'` / `'warning'` / `'error'`), `title?`, `children` |
|
|
277
|
+
| `CopyField` | Read-only field with copy/reveal support | `value`, `masked?`, `description?`, `copyOnClick?`, `maskFormatter?` |
|
|
278
|
+
| `Transition` | Enter/exit animations | `show`, `preset` (`'fade'` / `'scale'` / `'slide'`) |
|
|
279
|
+
|
|
280
|
+
### Accessibility
|
|
281
|
+
|
|
282
|
+
| Component | When to use |
|
|
283
|
+
| ---------------- | -------------------------------------------------------- |
|
|
284
|
+
| `VisuallyHidden` | Screen reader-only text (hidden visually but accessible) |
|
|
285
|
+
|
|
286
|
+
### Hooks
|
|
287
|
+
|
|
288
|
+
| Hook | When to use | Returns |
|
|
289
|
+
| ------------------------- | ---------------------------------------------- | --------------------------------- |
|
|
290
|
+
| `useClipboard` | Copy text with status feedback | `{ copy, copied }` |
|
|
291
|
+
| `useDisclosure` | Toggle open/close state for modals, menus | `{ isOpen, open, close, toggle }` |
|
|
292
|
+
| `useMediaQuery` | Respond to viewport changes | `boolean` |
|
|
293
|
+
| `useDebounce` | Debounce fast-changing values (search, resize) | debounced value |
|
|
294
|
+
| `useHotkeys` | Global keyboard shortcuts | bind key combos to callbacks |
|
|
295
|
+
| `useIntersectionObserver` | Lazy loading, infinite scroll | `{ ref, isIntersecting }` |
|
|
296
|
+
| `useSharedNow` | Live clock for "X ago" labels, countdowns | `Date` that updates every N ms |
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## Common Patterns
|
|
301
|
+
|
|
302
|
+
### Settings page with sections
|
|
303
|
+
|
|
304
|
+
```tsx
|
|
305
|
+
import { Card, Input, Textarea, Select, Toggle } from '@memelabui/ui';
|
|
306
|
+
|
|
307
|
+
function SettingsPage() {
|
|
308
|
+
return (
|
|
309
|
+
<div className="space-y-6">
|
|
310
|
+
<Card variant="glass" hoverable>
|
|
311
|
+
<h2 className="section-title">Bot Personality</h2>
|
|
312
|
+
<div className="space-y-4">
|
|
313
|
+
<Input label="Bot name" value={name} onChange={...} />
|
|
314
|
+
<Textarea label="Personality description" value={desc} onChange={...} />
|
|
315
|
+
<div className="grid grid-cols-3 gap-4">
|
|
316
|
+
<Select label="Style"><option>Concise</option></Select>
|
|
317
|
+
<Select label="Language"><option>Auto</option></Select>
|
|
318
|
+
<Input label="Max length" type="number" />
|
|
319
|
+
</div>
|
|
320
|
+
</div>
|
|
321
|
+
</Card>
|
|
322
|
+
|
|
323
|
+
<Card variant="glass" hoverable>
|
|
324
|
+
<h2 className="section-title">Triggers</h2>
|
|
325
|
+
<div className="space-y-3">
|
|
326
|
+
<Toggle label="Respond to @mentions" checked={...} onChange={...} />
|
|
327
|
+
<Toggle label="Respond to keywords" checked={...} onChange={...} />
|
|
328
|
+
<TagInput value={keywords} onChange={...} placeholder="Add keyword" />
|
|
329
|
+
</div>
|
|
330
|
+
</Card>
|
|
331
|
+
</div>
|
|
332
|
+
);
|
|
333
|
+
}
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### Dashboard with stats
|
|
337
|
+
|
|
338
|
+
```tsx
|
|
339
|
+
import { StatCard, SectionCard, Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@memelabui/ui';
|
|
340
|
+
|
|
341
|
+
function Dashboard() {
|
|
342
|
+
return (
|
|
343
|
+
<>
|
|
344
|
+
<div className="grid grid-cols-3 gap-4 mb-6">
|
|
345
|
+
<StatCard value="1,234" label="Messages" trend={{ value: 12, label: 'vs last week' }} />
|
|
346
|
+
<StatCard value="89%" label="Response rate" />
|
|
347
|
+
<StatCard value="2.3s" label="Avg. response" />
|
|
348
|
+
</div>
|
|
349
|
+
|
|
350
|
+
<SectionCard title="Recent Activity" description="Last 24 hours">
|
|
351
|
+
<Table>
|
|
352
|
+
<TableHeader>
|
|
353
|
+
<TableRow>
|
|
354
|
+
<TableHead>Time</TableHead>
|
|
355
|
+
<TableHead>Message</TableHead>
|
|
356
|
+
</TableRow>
|
|
357
|
+
</TableHeader>
|
|
358
|
+
<TableBody>
|
|
359
|
+
<TableRow>
|
|
360
|
+
<TableCell>12:30</TableCell>
|
|
361
|
+
<TableCell>Hello bot!</TableCell>
|
|
362
|
+
</TableRow>
|
|
363
|
+
</TableBody>
|
|
364
|
+
</Table>
|
|
365
|
+
</SectionCard>
|
|
366
|
+
</>
|
|
367
|
+
);
|
|
368
|
+
}
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
## Customization
|
|
374
|
+
|
|
375
|
+
Override CSS variables to customize the theme. Values must be **space-separated RGB channels** (not hex) for Tailwind opacity support:
|
|
376
|
+
|
|
377
|
+
```css
|
|
378
|
+
:root {
|
|
379
|
+
--ml-bg: 10 10 15; /* Page background */
|
|
380
|
+
--ml-primary: 139 92 246; /* Primary color (buttons, toggles, active states) */
|
|
381
|
+
--ml-accent: 102 126 234; /* Accent / gradient start */
|
|
382
|
+
--ml-glow-purple: 118 75 162; /* Gradient middle */
|
|
383
|
+
--ml-glow-pink: 240 147 251; /* Gradient end */
|
|
384
|
+
--ml-surface-50: 20 20 32; /* Surface tint */
|
|
385
|
+
--ml-surface-100: 30 30 48; /* Surface tint darker */
|
|
386
|
+
}
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
Additional tokens:
|
|
390
|
+
|
|
391
|
+
| Token | Default | Purpose |
|
|
392
|
+
| ---------------------- | ------------------------ | ---------------------------- |
|
|
393
|
+
| `--ml-glass-bg` | `rgba(255,255,255,0.05)` | Glass panel background |
|
|
394
|
+
| `--ml-glass-blur` | `16px` | Glass backdrop blur |
|
|
395
|
+
| `--ml-glass-border` | `rgba(255,255,255,0.1)` | Glass inset border |
|
|
396
|
+
| `--ml-radius-md` | `0.75rem` | Default border radius |
|
|
397
|
+
| `--ml-font-sans` | System font stack | Base font family |
|
|
398
|
+
| `--ml-transition-fast` | `150ms ease` | Hover/focus transition speed |
|
|
399
|
+
|
|
400
|
+
## Features
|
|
401
|
+
|
|
402
|
+
- **Dark-first glassmorphism** design system
|
|
403
|
+
- **Zero runtime dependencies** — only peer deps (react, react-dom, tailwindcss)
|
|
404
|
+
- **Tree-shakeable** — each component independently importable
|
|
405
|
+
- **Fully accessible** — ARIA attributes, keyboard navigation, focus management, `prefers-reduced-motion` support
|
|
406
|
+
- **SSR-safe** — no `document`/`window` access during server render
|
|
407
|
+
- **TypeScript-first** — all components and hooks fully typed with exported types
|
|
408
|
+
- **Tailwind preset** — tokens, colors, and animations included
|
|
409
|
+
|
|
410
|
+
## Development
|
|
411
|
+
|
|
412
|
+
```bash
|
|
413
|
+
pnpm dev # Storybook on :6006
|
|
414
|
+
pnpm build # Build package (tsup + postcss)
|
|
415
|
+
pnpm test # Run tests (vitest watch)
|
|
416
|
+
pnpm test:ci # Run tests once
|
|
417
|
+
pnpm typecheck # TypeScript check
|
|
418
|
+
pnpm lint # ESLint
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
## License
|
|
422
|
+
|
|
423
|
+
MIT
|
|
424
|
+
|
|
425
|
+
|
|
426
|
+
|
|
427
|
+
|