luaniverse 4.0.40
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 +710 -0
- package/dist/index.cjs +6304 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1229 -0
- package/dist/index.d.ts +1229 -0
- package/dist/index.js +6023 -0
- package/dist/index.js.map +1 -0
- package/dist/safelist.js +234 -0
- package/dist/safelist.txt +210 -0
- package/dist/styles.css +363 -0
- package/dist/tailwind.preset.js +90 -0
- package/package.json +118 -0
package/README.md
ADDED
|
@@ -0,0 +1,710 @@
|
|
|
1
|
+
# Luaniverse
|
|
2
|
+
|
|
3
|
+
**Lua Design System** - A React component library for Lua applications
|
|
4
|
+
|
|
5
|
+
[](https://badge.fury.io/js/@lua-global%2Fluaniverse)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install @lua-global/luaniverse
|
|
12
|
+
# or
|
|
13
|
+
yarn add @lua-global/luaniverse
|
|
14
|
+
# or
|
|
15
|
+
pnpm add @lua-global/luaniverse
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
### Importing Components
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { Button, IconButton, Badge, Textarea } from '@lua-global/luaniverse';
|
|
24
|
+
import { UserIcon, Trash, PDF, PNG, Chat, Clock, Minus, Plus, Tag } from '@lua-global/luaniverse';
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Styling
|
|
28
|
+
|
|
29
|
+
Import the CSS file in your app's entry point:
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
import '@lua-global/luaniverse/styles';
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Available Exports:**
|
|
36
|
+
- `@lua-ai-global/luaniverse` - Components and utilities
|
|
37
|
+
- `@lua-ai-global/luaniverse/styles` - CSS styles and design tokens
|
|
38
|
+
- `@lua-ai-global/luaniverse/tailwind` - Tailwind preset for utility classes
|
|
39
|
+
|
|
40
|
+
> 💡 **Quick Setup**: See [INTEGRATION.md](./INTEGRATION.md) for step-by-step consumer app setup instructions.
|
|
41
|
+
|
|
42
|
+
### Tailwind CSS Configuration
|
|
43
|
+
|
|
44
|
+
**⚠️ IMPORTANT**: Luaniverse requires BOTH the Tailwind preset AND the styles to work correctly. Missing either will cause components to lose their backgrounds and styling.
|
|
45
|
+
|
|
46
|
+
#### Step 1: Add the Tailwind Preset
|
|
47
|
+
|
|
48
|
+
Update your `tailwind.config.js` to use the Luaniverse preset:
|
|
49
|
+
|
|
50
|
+
```js
|
|
51
|
+
// tailwind.config.js
|
|
52
|
+
import { luaniversePreset } from '@lua-ai-global/luaniverse/tailwind';
|
|
53
|
+
|
|
54
|
+
export default {
|
|
55
|
+
presets: [luaniversePreset], // 🔥 Required for component styling
|
|
56
|
+
content: [
|
|
57
|
+
// Your content paths
|
|
58
|
+
'./src/**/*.{js,jsx,ts,tsx}',
|
|
59
|
+
'./app/**/*.{js,jsx,ts,tsx}',
|
|
60
|
+
// 🔥 Required: Include luaniverse components for class detection
|
|
61
|
+
'./node_modules/@lua-ai-global/luaniverse/**/*.{js,jsx,ts,tsx}',
|
|
62
|
+
],
|
|
63
|
+
// Your additional config...
|
|
64
|
+
};
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Or with CommonJS:
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
// tailwind.config.js
|
|
71
|
+
const { luaniversePreset } = require('@lua-ai-global/luaniverse/tailwind');
|
|
72
|
+
|
|
73
|
+
module.exports = {
|
|
74
|
+
presets: [luaniversePreset],
|
|
75
|
+
content: [
|
|
76
|
+
'./src/**/*.{js,jsx,ts,tsx}',
|
|
77
|
+
'./node_modules/@lua-ai-global/luaniverse/**/*.{js,jsx,ts,tsx}',
|
|
78
|
+
],
|
|
79
|
+
};
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
#### Step 2: Import the Styles
|
|
83
|
+
|
|
84
|
+
In your main CSS file, import the Luaniverse styles:
|
|
85
|
+
|
|
86
|
+
```css
|
|
87
|
+
/* app.css or globals.css */
|
|
88
|
+
@import '@lua-ai-global/luaniverse/styles'; /* 🔥 Required for design tokens */
|
|
89
|
+
@import 'tailwindcss';
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
#### Why Both Are Required
|
|
93
|
+
|
|
94
|
+
- **Preset**: Enables utility classes like `bg-popover`, `text-card-foreground`
|
|
95
|
+
- **Styles**: Provides CSS variables (`--primary`, `--popover`) and typography system
|
|
96
|
+
|
|
97
|
+
**❌ Without preset**: Components lose backgrounds (transparent dropdowns)
|
|
98
|
+
**❌ Without styles**: Components lose design tokens and typography
|
|
99
|
+
**✅ With both**: Components work perfectly!
|
|
100
|
+
|
|
101
|
+
### Dark Mode Support
|
|
102
|
+
|
|
103
|
+
Luaniverse comes with built-in dark mode support. The library uses Tailwind's class-based dark mode strategy.
|
|
104
|
+
|
|
105
|
+
#### Enabling Dark Mode
|
|
106
|
+
|
|
107
|
+
To enable dark mode in your application:
|
|
108
|
+
|
|
109
|
+
1. **Add the dark class to your HTML:**
|
|
110
|
+
```html
|
|
111
|
+
<html class="dark">
|
|
112
|
+
<!-- Your app content -->
|
|
113
|
+
</html>
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
2. **Or toggle it programmatically:**
|
|
117
|
+
```tsx
|
|
118
|
+
// Toggle dark mode
|
|
119
|
+
document.documentElement.classList.toggle('dark');
|
|
120
|
+
|
|
121
|
+
// Enable dark mode
|
|
122
|
+
document.documentElement.classList.add('dark');
|
|
123
|
+
|
|
124
|
+
// Disable dark mode
|
|
125
|
+
document.documentElement.classList.remove('dark');
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
3. **With React state management:**
|
|
129
|
+
```tsx
|
|
130
|
+
function App() {
|
|
131
|
+
const [darkMode, setDarkMode] = useState(false);
|
|
132
|
+
|
|
133
|
+
useEffect(() => {
|
|
134
|
+
document.documentElement.classList.toggle('dark', darkMode);
|
|
135
|
+
}, [darkMode]);
|
|
136
|
+
|
|
137
|
+
return (
|
|
138
|
+
<div className={darkMode ? 'dark' : ''}>
|
|
139
|
+
<Button onClick={() => setDarkMode(!darkMode)}>
|
|
140
|
+
Toggle Dark Mode
|
|
141
|
+
</Button>
|
|
142
|
+
{/* Your app content */}
|
|
143
|
+
</div>
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
#### Dark Mode Features
|
|
149
|
+
|
|
150
|
+
- **Automatic Color Adaptation** - All components automatically adapt their colors for dark mode
|
|
151
|
+
- **Maintained Accessibility** - Focus indicators and contrast ratios remain WCAG compliant in dark mode
|
|
152
|
+
- **Brand Consistency** - Primary and destructive colors maintain brand identity across themes
|
|
153
|
+
- **Smooth Transitions** - Built-in CSS transitions for theme switching
|
|
154
|
+
|
|
155
|
+
## Troubleshooting
|
|
156
|
+
|
|
157
|
+
### Missing Component Backgrounds
|
|
158
|
+
|
|
159
|
+
**Problem**: Dropdown menus, cards, or other components appear transparent or unstyled.
|
|
160
|
+
|
|
161
|
+
**Cause**: Missing Tailwind preset or incomplete setup.
|
|
162
|
+
|
|
163
|
+
**Solution**: Ensure you have both parts of the setup:
|
|
164
|
+
|
|
165
|
+
1. ✅ **Preset added** to `tailwind.config.js`
|
|
166
|
+
2. ✅ **Styles imported** in your CSS
|
|
167
|
+
3. ✅ **Content paths** include `./node_modules/@lua-ai-global/luaniverse/**/*.{js,jsx,ts,tsx}`
|
|
168
|
+
|
|
169
|
+
```js
|
|
170
|
+
// ✅ Correct setup
|
|
171
|
+
import { luaniversePreset } from '@lua-ai-global/luaniverse/tailwind';
|
|
172
|
+
|
|
173
|
+
export default {
|
|
174
|
+
presets: [luaniversePreset], // Enables bg-popover, bg-card utilities
|
|
175
|
+
content: [
|
|
176
|
+
'./src/**/*.{js,jsx,ts,tsx}',
|
|
177
|
+
'./node_modules/@lua-ai-global/luaniverse/**/*.{js,jsx,ts,tsx}', // Required!
|
|
178
|
+
],
|
|
179
|
+
};
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
```css
|
|
183
|
+
/* ✅ Required in your CSS */
|
|
184
|
+
@import '@lua-ai-global/luaniverse/styles';
|
|
185
|
+
@import 'tailwindcss';
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Missing Typography Utilities
|
|
189
|
+
|
|
190
|
+
**Problem**: Custom typography classes like `text-h1`, `link-primary` don't work.
|
|
191
|
+
|
|
192
|
+
**Solution**: Make sure you've imported the styles (they contain custom `@utility` definitions).
|
|
193
|
+
|
|
194
|
+
### Build Errors
|
|
195
|
+
|
|
196
|
+
**Problem**: Build fails with Tailwind-related errors.
|
|
197
|
+
|
|
198
|
+
**Solution**: Check that your content paths are correct and that you're using a compatible Tailwind version (v3.3+ or v4+).
|
|
199
|
+
|
|
200
|
+
## Components
|
|
201
|
+
|
|
202
|
+
### Button
|
|
203
|
+
|
|
204
|
+
A versatile button component with multiple variants, sizes, and states.
|
|
205
|
+
|
|
206
|
+
```tsx
|
|
207
|
+
import { Button } from '@lua-global/luaniverse';
|
|
208
|
+
|
|
209
|
+
function App() {
|
|
210
|
+
return (
|
|
211
|
+
<div>
|
|
212
|
+
<Button>Default Button</Button>
|
|
213
|
+
<Button variant="primary">Primary Button</Button>
|
|
214
|
+
<Button variant="outline">Outline Button</Button>
|
|
215
|
+
<Button variant="destructive">Destructive Button</Button>
|
|
216
|
+
<Button size="large">Large Button</Button>
|
|
217
|
+
<Button loading>Loading Button</Button>
|
|
218
|
+
</div>
|
|
219
|
+
);
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
#### Button Props
|
|
224
|
+
|
|
225
|
+
| Prop | Type | Default | Description |
|
|
226
|
+
|------|------|---------|-------------|
|
|
227
|
+
| `variant` | `'default' \| 'primary' \| 'outline-solid' \| 'tertiary' \| 'secondary' \| 'muted' \| 'destructive'` | `'default'` | The visual style variant |
|
|
228
|
+
| `size` | `'small' \| 'default' \| 'large'` | `'default'` | The size of the button |
|
|
229
|
+
| `loading` | `boolean` | `false` | Shows loading spinner when true |
|
|
230
|
+
| `disabled` | `boolean` | `false` | Disables the button |
|
|
231
|
+
| `asChild` | `boolean` | `false` | Render as a child element |
|
|
232
|
+
| `startAdornment` | `React.ReactNode` | - | Icon or element before the text |
|
|
233
|
+
| `endAdornment` | `React.ReactNode` | - | Icon or element after the text |
|
|
234
|
+
| `aria-label` | `string` | - | Accessible label for the button |
|
|
235
|
+
| `aria-describedby` | `string` | - | Additional description for complex actions |
|
|
236
|
+
|
|
237
|
+
#### Button Variants
|
|
238
|
+
|
|
239
|
+
- **default**: Black background with white text (adapts to white background in dark mode)
|
|
240
|
+
- **primary**: Blue background with white text
|
|
241
|
+
- **outline**: White background with blue border and text
|
|
242
|
+
- **tertiary**: White background with gray border (adapts to dark gray in dark mode)
|
|
243
|
+
- **secondary**: Gray background using CSS variables
|
|
244
|
+
- **muted**: Transparent background with hover states
|
|
245
|
+
- **destructive**: Red background with white text
|
|
246
|
+
|
|
247
|
+
#### Button Examples
|
|
248
|
+
|
|
249
|
+
```tsx
|
|
250
|
+
// With Luaniverse icons
|
|
251
|
+
import { UserIcon, Camera } from '@lua-global/luaniverse';
|
|
252
|
+
|
|
253
|
+
<Button startAdornment={<UserIcon size={16} />}>
|
|
254
|
+
Profile
|
|
255
|
+
</Button>
|
|
256
|
+
|
|
257
|
+
<Button endAdornment={<Camera size={16} />}>
|
|
258
|
+
Take Photo
|
|
259
|
+
</Button>
|
|
260
|
+
|
|
261
|
+
// Loading state
|
|
262
|
+
<Button loading>
|
|
263
|
+
Processing...
|
|
264
|
+
</Button>
|
|
265
|
+
|
|
266
|
+
// As a link
|
|
267
|
+
<Button asChild>
|
|
268
|
+
<a href="/dashboard">Go to Dashboard</a>
|
|
269
|
+
</Button>
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### IconButton
|
|
273
|
+
|
|
274
|
+
A button component designed specifically for icons with proper accessibility features and sizing.
|
|
275
|
+
|
|
276
|
+
```tsx
|
|
277
|
+
import { IconButton } from '@lua-global/luaniverse';
|
|
278
|
+
import { UserIcon, Trash, XIcon } from '@lua-global/luaniverse';
|
|
279
|
+
|
|
280
|
+
function App() {
|
|
281
|
+
return (
|
|
282
|
+
<div>
|
|
283
|
+
<IconButton aria-label="User profile">
|
|
284
|
+
<UserIcon size={20} />
|
|
285
|
+
</IconButton>
|
|
286
|
+
<IconButton variant="destructive" aria-label="Delete item">
|
|
287
|
+
<Trash size={20} />
|
|
288
|
+
</IconButton>
|
|
289
|
+
<IconButton variant="muted" aria-label="Close dialog">
|
|
290
|
+
<XIcon size={20} />
|
|
291
|
+
</IconButton>
|
|
292
|
+
</div>
|
|
293
|
+
);
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
#### IconButton Props
|
|
298
|
+
|
|
299
|
+
| Prop | Type | Default | Description |
|
|
300
|
+
|------|------|---------|-------------|
|
|
301
|
+
| `variant` | `'default' \| 'primary' \| 'outline-solid' \| 'tertiary' \| 'secondary' \| 'muted' \| 'destructive'` | `'default'` | The visual style variant |
|
|
302
|
+
| `size` | `'small' \| 'default' \| 'large'` | `'default'` | The size of the button |
|
|
303
|
+
| `loading` | `boolean` | `false` | Shows loading spinner when true |
|
|
304
|
+
| `disabled` | `boolean` | `false` | Disables the button |
|
|
305
|
+
| `asChild` | `boolean` | `false` | Render as a child element |
|
|
306
|
+
| `aria-label` | `string` | **Required** | Accessible label describing the action |
|
|
307
|
+
| `aria-describedby` | `string` | - | Additional description for complex actions |
|
|
308
|
+
|
|
309
|
+
#### IconButton Sizes
|
|
310
|
+
|
|
311
|
+
- **small**: 28px × 28px button with 16px recommended icon size
|
|
312
|
+
- **default**: 40px × 40px button with 20px recommended icon size
|
|
313
|
+
- **large**: 48px × 48px button with 24px recommended icon size
|
|
314
|
+
|
|
315
|
+
#### IconButton Examples
|
|
316
|
+
|
|
317
|
+
```tsx
|
|
318
|
+
import { IconButton } from '@lua-global/luaniverse';
|
|
319
|
+
import { UserIcon, Trash, Camera, ArrowLeft } from '@lua-global/luaniverse';
|
|
320
|
+
|
|
321
|
+
// Navigation
|
|
322
|
+
<IconButton variant="muted" aria-label="Go back">
|
|
323
|
+
<ArrowLeft size={20} />
|
|
324
|
+
</IconButton>
|
|
325
|
+
|
|
326
|
+
// Actions
|
|
327
|
+
<IconButton variant="primary" aria-label="Take photo">
|
|
328
|
+
<Camera size={20} />
|
|
329
|
+
</IconButton>
|
|
330
|
+
|
|
331
|
+
// Destructive actions
|
|
332
|
+
<IconButton variant="destructive" aria-label="Delete permanently">
|
|
333
|
+
<Trash size={20} />
|
|
334
|
+
</IconButton>
|
|
335
|
+
|
|
336
|
+
// Loading state
|
|
337
|
+
<IconButton loading aria-label="Saving changes">
|
|
338
|
+
<UserIcon size={20} />
|
|
339
|
+
</IconButton>
|
|
340
|
+
|
|
341
|
+
// Different sizes
|
|
342
|
+
<IconButton size="small" aria-label="Small action">
|
|
343
|
+
<UserIcon size={16} />
|
|
344
|
+
</IconButton>
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### Badge
|
|
348
|
+
|
|
349
|
+
A flexible badge component for displaying status, counts, and labels with multiple variants and color options.
|
|
350
|
+
|
|
351
|
+
```tsx
|
|
352
|
+
import { Badge } from '@lua-global/luaniverse';
|
|
353
|
+
|
|
354
|
+
function App() {
|
|
355
|
+
return (
|
|
356
|
+
<div>
|
|
357
|
+
<Badge>Default</Badge>
|
|
358
|
+
<Badge variant="secondary">Secondary</Badge>
|
|
359
|
+
<Badge variant="destructive">Error</Badge>
|
|
360
|
+
<Badge variant="outline">Outline</Badge>
|
|
361
|
+
<Badge variant="success">Success</Badge>
|
|
362
|
+
<Badge variant="warning">Warning</Badge>
|
|
363
|
+
</div>
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
#### Badge Props
|
|
369
|
+
|
|
370
|
+
| Prop | Type | Default | Description |
|
|
371
|
+
|------|------|---------|-------------|
|
|
372
|
+
| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline-solid' \| 'success' \| 'warning'` | `'default'` | The visual style variant |
|
|
373
|
+
| `asChild` | `boolean` | `false` | Render as a child element |
|
|
374
|
+
| `aria-label` | `string` | - | Accessible label for the badge |
|
|
375
|
+
|
|
376
|
+
#### Badge Variants
|
|
377
|
+
|
|
378
|
+
- **default**: Primary color background with white text
|
|
379
|
+
- **secondary**: Gray background using CSS variables
|
|
380
|
+
- **destructive**: Red background for errors and warnings
|
|
381
|
+
- **outline**: Transparent background with border
|
|
382
|
+
- **success**: Green background for positive status
|
|
383
|
+
- **warning**: Yellow background for cautionary information
|
|
384
|
+
|
|
385
|
+
#### Badge Examples
|
|
386
|
+
|
|
387
|
+
```tsx
|
|
388
|
+
// Status badges
|
|
389
|
+
<Badge variant="success">Active</Badge>
|
|
390
|
+
<Badge variant="destructive">Error</Badge>
|
|
391
|
+
<Badge variant="warning">Pending</Badge>
|
|
392
|
+
|
|
393
|
+
// Count badges
|
|
394
|
+
<Badge>3</Badge>
|
|
395
|
+
<Badge variant="secondary">New</Badge>
|
|
396
|
+
|
|
397
|
+
// As a link
|
|
398
|
+
<Badge asChild>
|
|
399
|
+
<a href="/notifications">5 unread</a>
|
|
400
|
+
</Badge>
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### Textarea
|
|
404
|
+
|
|
405
|
+
A multi-line text input component with built-in label, description, error states, and accessibility features.
|
|
406
|
+
|
|
407
|
+
```tsx
|
|
408
|
+
import { Textarea } from '@lua-global/luaniverse';
|
|
409
|
+
|
|
410
|
+
function App() {
|
|
411
|
+
return (
|
|
412
|
+
<div>
|
|
413
|
+
<Textarea
|
|
414
|
+
label="Message"
|
|
415
|
+
placeholder="Enter your message..."
|
|
416
|
+
/>
|
|
417
|
+
<Textarea
|
|
418
|
+
label="Feedback"
|
|
419
|
+
description="Please provide detailed feedback"
|
|
420
|
+
error="This field is required"
|
|
421
|
+
/>
|
|
422
|
+
</div>
|
|
423
|
+
);
|
|
424
|
+
}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
#### Textarea Props
|
|
428
|
+
|
|
429
|
+
| Prop | Type | Default | Description |
|
|
430
|
+
|------|------|---------|-------------|
|
|
431
|
+
| `label` | `string` | - | Label text displayed above the textarea |
|
|
432
|
+
| `description` | `string` | - | Helper text displayed below the textarea |
|
|
433
|
+
| `error` | `string` | - | Error message displayed below the textarea |
|
|
434
|
+
| `success` | `string` | - | Success message displayed below the textarea |
|
|
435
|
+
| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Resize behavior |
|
|
436
|
+
| `disabled` | `boolean` | `false` | Disables the textarea |
|
|
437
|
+
| `aria-describedby` | `string` | - | Additional description references |
|
|
438
|
+
| `aria-invalid` | `boolean` | - | Indicates validation state |
|
|
439
|
+
|
|
440
|
+
#### Textarea Examples
|
|
441
|
+
|
|
442
|
+
```tsx
|
|
443
|
+
// Basic textarea
|
|
444
|
+
<Textarea
|
|
445
|
+
label="Comments"
|
|
446
|
+
placeholder="Add your comments..."
|
|
447
|
+
/>
|
|
448
|
+
|
|
449
|
+
// With description
|
|
450
|
+
<Textarea
|
|
451
|
+
label="Bio"
|
|
452
|
+
description="Tell us about yourself (max 500 characters)"
|
|
453
|
+
placeholder="Write your bio..."
|
|
454
|
+
/>
|
|
455
|
+
|
|
456
|
+
// Error state
|
|
457
|
+
<Textarea
|
|
458
|
+
label="Required Field"
|
|
459
|
+
error="This field is required"
|
|
460
|
+
placeholder="Please enter text..."
|
|
461
|
+
/>
|
|
462
|
+
|
|
463
|
+
// Success state
|
|
464
|
+
<Textarea
|
|
465
|
+
label="Feedback"
|
|
466
|
+
success="Thank you for your feedback!"
|
|
467
|
+
value="Great product!"
|
|
468
|
+
/>
|
|
469
|
+
|
|
470
|
+
// Disabled state
|
|
471
|
+
<Textarea
|
|
472
|
+
label="Read Only"
|
|
473
|
+
disabled
|
|
474
|
+
value="This content cannot be edited"
|
|
475
|
+
/>
|
|
476
|
+
|
|
477
|
+
// Custom resize behavior
|
|
478
|
+
<Textarea
|
|
479
|
+
label="Notes"
|
|
480
|
+
resize="both"
|
|
481
|
+
placeholder="Resize me in any direction..."
|
|
482
|
+
/>
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
## Icons
|
|
486
|
+
|
|
487
|
+
Luaniverse includes a comprehensive collection of icons for Lua applications.
|
|
488
|
+
|
|
489
|
+
### Standard Icons
|
|
490
|
+
|
|
491
|
+
Standard icons inherit their parent's text color by default, making them work properly with different backgrounds and themes.
|
|
492
|
+
|
|
493
|
+
```tsx
|
|
494
|
+
import {
|
|
495
|
+
ArrowLeft, ArrowUp, Camera, Chat, Clock, ImageIcon, Logo, MapPin,
|
|
496
|
+
Microphone, Minus, Paperclip, PaperPlane, PaperPlaneTilt, Plus,
|
|
497
|
+
RecordIcon, SignOut, Tag, Trash, UserIcon, VideoCamera, XIcon
|
|
498
|
+
} from '@lua-global/luaniverse';
|
|
499
|
+
|
|
500
|
+
function App() {
|
|
501
|
+
return (
|
|
502
|
+
<div>
|
|
503
|
+
<UserIcon size={24} />
|
|
504
|
+
<Camera size={24} color="#3B82F6" />
|
|
505
|
+
<Trash size={24} aria-label="Delete item" />
|
|
506
|
+
<XIcon size={24} title="Close dialog" />
|
|
507
|
+
</div>
|
|
508
|
+
);
|
|
509
|
+
}
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
#### Available Standard Icons
|
|
513
|
+
|
|
514
|
+
- **ArrowLeft** - Left-pointing arrow for navigation
|
|
515
|
+
- **ArrowUp** - Up-pointing arrow for navigation
|
|
516
|
+
- **Camera** - Camera icon for photo actions
|
|
517
|
+
- **Chat** - Chat/message icon for communication
|
|
518
|
+
- **Clock** - Clock icon for time and scheduling
|
|
519
|
+
- **ImageIcon** - Generic image icon
|
|
520
|
+
- **Logo** - Lua logo
|
|
521
|
+
- **MapPin** - Location/map pin icon
|
|
522
|
+
- **Microphone** - Microphone for audio recording
|
|
523
|
+
- **Minus** - Minus/remove icon for actions
|
|
524
|
+
- **Paperclip** - Attachment icon
|
|
525
|
+
- **PaperPlane** - Send/paper plane icon
|
|
526
|
+
- **PaperPlaneTilt** - Tilted paper plane variant
|
|
527
|
+
- **Plus** - Plus/add icon for actions
|
|
528
|
+
- **RecordIcon** - Recording indicator
|
|
529
|
+
- **SignOut** - Sign out/logout icon
|
|
530
|
+
- **Tag** - Tag/label icon for categorization
|
|
531
|
+
- **Trash** - Delete/trash icon
|
|
532
|
+
- **UserIcon** - User profile icon
|
|
533
|
+
- **VideoCamera** - Video camera icon
|
|
534
|
+
- **XIcon** - Close/cancel icon
|
|
535
|
+
|
|
536
|
+
### File Icons
|
|
537
|
+
|
|
538
|
+
File icons maintain their recognizable brand colors for easy file type identification.
|
|
539
|
+
|
|
540
|
+
```tsx
|
|
541
|
+
import {
|
|
542
|
+
PDF, PNG, JPG, MP4, MP3, DOC, XLS, PPT, Zip, CSS, JS, JSON,
|
|
543
|
+
HTML, SVG, AI, PSD, Fig, Sketch
|
|
544
|
+
} from '@lua-global/luaniverse';
|
|
545
|
+
|
|
546
|
+
function FileList() {
|
|
547
|
+
return (
|
|
548
|
+
<div>
|
|
549
|
+
<PDF aria-label="PDF document" />
|
|
550
|
+
<PNG aria-label="PNG image" />
|
|
551
|
+
<JS aria-label="JavaScript file" />
|
|
552
|
+
<DOC aria-label="Word document" />
|
|
553
|
+
</div>
|
|
554
|
+
);
|
|
555
|
+
}
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
#### Available File Icons
|
|
559
|
+
|
|
560
|
+
**Images**: PDF, PNG, JPG, SVG, AI, PSD, Fig, Sketch
|
|
561
|
+
**Documents**: DOC, XLS, PPT
|
|
562
|
+
**Media**: MP4, MP3
|
|
563
|
+
**Code**: CSS, JS, JSON, HTML
|
|
564
|
+
**Archives**: Zip
|
|
565
|
+
|
|
566
|
+
### Icon Props
|
|
567
|
+
|
|
568
|
+
All icons accept these common props:
|
|
569
|
+
|
|
570
|
+
| Prop | Type | Default | Description |
|
|
571
|
+
|------|------|---------|-------------|
|
|
572
|
+
| `size` | `number` | `24` | The size of the icon in pixels |
|
|
573
|
+
| `color` | `string` | `"currentColor"` | The color of the icon (standard icons only) |
|
|
574
|
+
| `aria-label` | `string` | - | Accessible label for the icon |
|
|
575
|
+
| `aria-describedby` | `string` | - | Additional description |
|
|
576
|
+
| `aria-hidden` | `boolean` | - | Hide from screen readers (for decorative icons) |
|
|
577
|
+
| `title` | `string` | - | Tooltip text that appears on hover |
|
|
578
|
+
|
|
579
|
+
### Icon Accessibility
|
|
580
|
+
|
|
581
|
+
Icons are designed with accessibility in mind and include **default aria-labels** based on their names:
|
|
582
|
+
|
|
583
|
+
```tsx
|
|
584
|
+
// Automatic aria-label (aria-label="User")
|
|
585
|
+
<UserIcon size={24} />
|
|
586
|
+
|
|
587
|
+
// Custom aria-label overrides the default
|
|
588
|
+
<UserIcon size={24} aria-label="User profile" />
|
|
589
|
+
|
|
590
|
+
// Icons with tooltips
|
|
591
|
+
<Trash size={24} title="Delete this item permanently" />
|
|
592
|
+
|
|
593
|
+
// Decorative icons in buttons (button provides the label)
|
|
594
|
+
<button aria-label="Delete item">
|
|
595
|
+
<Trash size={20} aria-hidden={true} />
|
|
596
|
+
</button>
|
|
597
|
+
|
|
598
|
+
// Default aria-labels for common icons:
|
|
599
|
+
<XIcon /> {/* aria-label="Close" */}
|
|
600
|
+
<ArrowLeft /> {/* aria-label="Arrow left" */}
|
|
601
|
+
<PaperPlane /> {/* aria-label="Send" */}
|
|
602
|
+
<MagnifyingGlass /> {/* aria-label="Search" */}
|
|
603
|
+
<Plus /> {/* aria-label="Plus" */}
|
|
604
|
+
<Minus /> {/* aria-label="Minus" */}
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
#### Default Aria-Labels
|
|
608
|
+
|
|
609
|
+
Standard icons automatically get meaningful aria-labels:
|
|
610
|
+
- **XIcon** → "Close"
|
|
611
|
+
- **ArrowLeft** → "Arrow left"
|
|
612
|
+
- **PaperPlane** → "Send"
|
|
613
|
+
- **MagnifyingGlass** → "Search"
|
|
614
|
+
- **UserIcon** → "User"
|
|
615
|
+
- **Plus/Minus** → "Plus"/"Minus"
|
|
616
|
+
- And many more based on component names
|
|
617
|
+
|
|
618
|
+
This improves accessibility out of the box while still allowing customization.
|
|
619
|
+
|
|
620
|
+
## Development
|
|
621
|
+
|
|
622
|
+
### Prerequisites
|
|
623
|
+
|
|
624
|
+
- Node.js >= 18
|
|
625
|
+
- pnpm >= 8
|
|
626
|
+
|
|
627
|
+
### Setup
|
|
628
|
+
|
|
629
|
+
```bash
|
|
630
|
+
# Install dependencies
|
|
631
|
+
pnpm install
|
|
632
|
+
|
|
633
|
+
# Start development
|
|
634
|
+
pnpm dev
|
|
635
|
+
|
|
636
|
+
# Build library
|
|
637
|
+
pnpm build
|
|
638
|
+
|
|
639
|
+
# Run Storybook
|
|
640
|
+
pnpm storybook
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
### Building
|
|
644
|
+
|
|
645
|
+
The library is built with [tsup](https://tsup.egoist.dev/) for optimal bundling:
|
|
646
|
+
|
|
647
|
+
- **ESM**: `dist/index.mjs`
|
|
648
|
+
- **CJS**: `dist/index.js`
|
|
649
|
+
- **Types**: `dist/index.d.ts`
|
|
650
|
+
- **Styles**: `dist/styles.css`
|
|
651
|
+
|
|
652
|
+
### Tree Shaking
|
|
653
|
+
|
|
654
|
+
The library is fully tree-shakable. Import only what you need:
|
|
655
|
+
|
|
656
|
+
```tsx
|
|
657
|
+
// ✅ Tree-shakable - only Button and UserIcon are bundled
|
|
658
|
+
import { Button, UserIcon } from '@lua-global/luaniverse';
|
|
659
|
+
|
|
660
|
+
// ❌ Imports everything
|
|
661
|
+
import * as Luaniverse from '@lua-global/luaniverse';
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
## Accessibility
|
|
665
|
+
|
|
666
|
+
Luaniverse components are built with accessibility as a priority:
|
|
667
|
+
|
|
668
|
+
- **WCAG AA Compliance** - All components meet accessibility standards
|
|
669
|
+
- **Keyboard Navigation** - Full keyboard support with proper focus management
|
|
670
|
+
- **Screen Reader Support** - Proper ARIA labels and descriptions
|
|
671
|
+
- **High Contrast** - Works with high contrast modes and themes
|
|
672
|
+
- **Development Warnings** - Console warnings for missing accessibility attributes in development
|
|
673
|
+
|
|
674
|
+
### Accessibility Best Practices
|
|
675
|
+
|
|
676
|
+
```tsx
|
|
677
|
+
// ✅ Good - Descriptive labels
|
|
678
|
+
<IconButton aria-label="Delete this message">
|
|
679
|
+
<Trash size={20} />
|
|
680
|
+
</IconButton>
|
|
681
|
+
|
|
682
|
+
// ✅ Good - Additional context
|
|
683
|
+
<IconButton
|
|
684
|
+
aria-label="Delete"
|
|
685
|
+
aria-describedby="delete-description"
|
|
686
|
+
>
|
|
687
|
+
<Trash size={20} />
|
|
688
|
+
</IconButton>
|
|
689
|
+
|
|
690
|
+
// ❌ Bad - No accessible label
|
|
691
|
+
<IconButton>
|
|
692
|
+
<Trash size={20} />
|
|
693
|
+
</IconButton>
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
## Contributing
|
|
697
|
+
|
|
698
|
+
1. Fork the repository
|
|
699
|
+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
700
|
+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
701
|
+
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
702
|
+
5. Open a Pull Request
|
|
703
|
+
|
|
704
|
+
## License
|
|
705
|
+
|
|
706
|
+
MIT License - see the [LICENSE](LICENSE) file for details.
|
|
707
|
+
|
|
708
|
+
## Support
|
|
709
|
+
|
|
710
|
+
For questions and support, please open an issue on [GitHub](https://github.com/lua-global/luaniverse/issues).
|