meticulous-ui 3.8.5 → 3.8.7
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 +232 -81
- package/package.json +26 -6
package/README.md
CHANGED
|
@@ -1,22 +1,64 @@
|
|
|
1
1
|
# meticulous-ui
|
|
2
2
|
|
|
3
|
-
Build production-ready React apps faster with components, hooks, utilities, icons, and design tokens — all in one package ✨
|
|
4
|
-
⚡ Tree-shakable
|
|
5
|
-
🎯 TypeScript ready
|
|
6
|
-
♿ Accessible (ARIA + Semantic HTML)
|
|
7
|
-
🎨 23 color palettes
|
|
8
|
-
🧩 Components + Hooks + Utils
|
|
9
|
-
|
|
10
3
|
[](https://www.npmjs.com/package/meticulous-ui)
|
|
11
4
|
[](https://www.npmjs.com/package/meticulous-ui)
|
|
5
|
+
[](https://www.npmjs.com/package/meticulous-ui)
|
|
6
|
+
|
|
7
|
+
[](https://meticulous-ui.vercel.app/)
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://meticulous-ui.vercel.app/">Documentation</a> •
|
|
11
|
+
<a href="https://bundlephobia.com/package/meticulous-ui">Bundle Size</a> •
|
|
12
|
+
<a href="https://github.com/xe3110/meticulous-ui">GitHub</a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
An engineering-first React ecosystem — components, hooks, utilities, tokens, and icons unified in a single tree-shakeable package.
|
|
16
|
+
Built for scalable, production-grade applications.
|
|
17
|
+
|
|
18
|
+
⚡ Fully tree-shakeable
|
|
19
|
+
🪶 Side-effect free
|
|
20
|
+
🎯 TypeScript-first
|
|
21
|
+
♿ Accessible by default
|
|
22
|
+
💅 styled-components
|
|
12
23
|
|
|
13
24
|
---
|
|
14
25
|
|
|
15
|
-
##
|
|
26
|
+
## Why meticulous-ui?
|
|
27
|
+
|
|
28
|
+
Modern frontends rely on fragmented ecosystems:
|
|
29
|
+
|
|
30
|
+
- 🧩 One package for components
|
|
31
|
+
- 🪝 Another for hooks
|
|
32
|
+
- 🔧 Another for utilities
|
|
33
|
+
- 🎨 Another for icons
|
|
34
|
+
- 🎯 Another for tokens
|
|
35
|
+
|
|
36
|
+
This leads to:
|
|
37
|
+
|
|
38
|
+
- 📦 Dependency bloat
|
|
39
|
+
- ⚠️ Inconsistent APIs
|
|
40
|
+
- 🏋️ Larger bundles
|
|
41
|
+
- 🔧 Growing maintenance overhead
|
|
16
42
|
|
|
17
|
-
|
|
43
|
+
meticulous-ui consolidates all of it into **one install** while staying fully tree-shakeable — you only pay for what you import.
|
|
18
44
|
|
|
19
|
-
|
|
45
|
+
### Why not multiple packages?
|
|
46
|
+
|
|
47
|
+
Most frontend ecosystems force developers to combine disconnected packages — each with its own API conventions, versioning, peer dependency conflicts, and documentation. The result is a fragmented developer experience that compounds over time.
|
|
48
|
+
|
|
49
|
+
meticulous-ui treats components, hooks, utilities, tokens, and foundations as a **single cohesive system** — designed together, versioned together, and documented together. One mental model. One import. One upgrade.
|
|
50
|
+
|
|
51
|
+
### Best suited for
|
|
52
|
+
|
|
53
|
+
- Enterprise dashboards and internal tools
|
|
54
|
+
- Design system foundations
|
|
55
|
+
- Frontend platform teams
|
|
56
|
+
- TypeScript-heavy projects
|
|
57
|
+
- Performance-sensitive applications
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
20
62
|
|
|
21
63
|
```bash
|
|
22
64
|
npm install meticulous-ui
|
|
@@ -24,149 +66,258 @@ npm install meticulous-ui
|
|
|
24
66
|
yarn add meticulous-ui
|
|
25
67
|
```
|
|
26
68
|
|
|
27
|
-
|
|
69
|
+
### Peer dependencies
|
|
28
70
|
|
|
29
71
|
```bash
|
|
30
|
-
npm install react react-dom styled-components
|
|
72
|
+
npm install react@^18 react-dom@^18 styled-components@^6
|
|
31
73
|
```
|
|
32
74
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Unlike many UI libraries, meticulous-ui combines:
|
|
36
|
-
|
|
37
|
-
✅ Components
|
|
38
|
-
✅ Hooks
|
|
39
|
-
✅ Utilities
|
|
40
|
-
✅ Icons
|
|
41
|
-
✅ Tokens
|
|
42
|
-
✅ Tree-shaking
|
|
43
|
-
✅ Styled-components theming
|
|
44
|
-
|
|
45
|
-
One install instead of 5 packages.
|
|
75
|
+
---
|
|
46
76
|
|
|
47
|
-
##
|
|
77
|
+
## Quick Start
|
|
48
78
|
|
|
49
|
-
```
|
|
50
|
-
import { Button, Input, Shimmer,
|
|
79
|
+
```tsx
|
|
80
|
+
import { Button, Input, Toast, Shimmer, useLocalStorage, validateEmail } from 'meticulous-ui';
|
|
51
81
|
import blue from 'meticulous-ui/colors/blue';
|
|
52
82
|
|
|
53
83
|
function App() {
|
|
84
|
+
const [email, setEmail] = useLocalStorage<string>('email', '');
|
|
85
|
+
|
|
86
|
+
const handleSubmit = () => {
|
|
87
|
+
if (!validateEmail(email)) {
|
|
88
|
+
Toast.error('Invalid email');
|
|
89
|
+
return;
|
|
90
|
+
}
|
|
91
|
+
Toast.success('Submitted successfully');
|
|
92
|
+
};
|
|
93
|
+
|
|
54
94
|
return (
|
|
55
95
|
<>
|
|
56
|
-
{/* Loading skeleton */}
|
|
57
96
|
<Shimmer width={200} height={20} />
|
|
58
|
-
|
|
59
|
-
{
|
|
60
|
-
<Button theme={blue} onClick={() => console.log('clicked')}>
|
|
97
|
+
<Input label='Email' color='blue' value={email} onChange={(e) => setEmail(e.target.value)} />
|
|
98
|
+
<Button theme={blue} onClick={handleSubmit}>
|
|
61
99
|
Submit
|
|
62
100
|
</Button>
|
|
63
|
-
|
|
64
|
-
{/* Controlled input */}
|
|
65
|
-
<Input label='Email' color='blue' value={email} onChange={handleChange} />
|
|
66
101
|
</>
|
|
67
102
|
);
|
|
68
103
|
}
|
|
69
104
|
```
|
|
70
105
|
|
|
71
|
-
|
|
106
|
+
For minimal bundle size, import directly from component paths:
|
|
72
107
|
|
|
73
|
-
```
|
|
108
|
+
```ts
|
|
74
109
|
import Button from 'meticulous-ui/components/Button';
|
|
75
110
|
import blue from 'meticulous-ui/colors/blue';
|
|
76
111
|
```
|
|
77
112
|
|
|
78
|
-
|
|
113
|
+
meticulous-ui is fully tree-shakeable and side-effect free — optimized for Vite, Webpack, Rollup, and Next.js.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Documentation & Storybook
|
|
118
|
+
|
|
119
|
+
Full interactive docs: [https://meticulous-ui.vercel.app/](https://meticulous-ui.vercel.app/)
|
|
120
|
+
|
|
121
|
+
- Colors → [Tokens: Colors](https://meticulous-ui.vercel.app/?path=/story/tokens-colors--default)
|
|
122
|
+
- Icons → [Tokens: Icons](https://meticulous-ui.vercel.app/?path=/story/tokens-icons--default)
|
|
123
|
+
- Hooks → [Custom Hooks](https://meticulous-ui.vercel.app/?path=/story/hooks-custom-hooks)
|
|
124
|
+
- Utilities → [Engineering Utilities](https://meticulous-ui.vercel.app/?path=/story/utilities-api-utilities--retry)
|
|
125
|
+
- React helpers → [React Utilities](https://meticulous-ui.vercel.app/?path=/story/react-utilities-react-helper-functions)
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Ecosystem Architecture
|
|
130
|
+
|
|
131
|
+
meticulous-ui is organized into layered abstractions. Higher layers build on lower ones; you can use any layer independently.
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
┌─────────────────────────────────────────────────┐
|
|
135
|
+
│ Organisms │ Complex production-ready UI systems
|
|
136
|
+
│ Toast · Pagination · VideoPlayer │
|
|
137
|
+
├─────────────────────────────────────────────────┤
|
|
138
|
+
│ Molecules │ Composed interactive components
|
|
139
|
+
│ Dropdown · DatePicker · OtpInput │
|
|
140
|
+
├─────────────────────────────────────────────────┤
|
|
141
|
+
│ Atoms │ Basic UI building blocks
|
|
142
|
+
│ Button · Input · Checkbox · Switch │
|
|
143
|
+
├─────────────────────────────────────────────────┤
|
|
144
|
+
│ Foundations │ Layout & application primitives
|
|
145
|
+
│ Grid · RootComponent │
|
|
146
|
+
├──────────────────┬──────────────────────────────┤
|
|
147
|
+
│ Hooks │ Utilities │ Reusable logic, framework-agnostic
|
|
148
|
+
│ useLocalStorage │ validateEmail · formatDate │
|
|
149
|
+
├──────────────────┴──────────────────────────────┤
|
|
150
|
+
│ Tokens │ Design primitives
|
|
151
|
+
│ 23 color palettes · 100+ SVG icons │
|
|
152
|
+
└─────────────────────────────────────────────────┘
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
79
156
|
|
|
80
|
-
|
|
157
|
+
## Components
|
|
81
158
|
|
|
82
159
|
### Core UI
|
|
83
160
|
|
|
84
|
-
|
|
161
|
+
Button · Input · Textarea · Checkbox · RadioGroup · Dropdown · Selectbox · Switch · Link
|
|
85
162
|
|
|
86
163
|
### Feedback & Loading
|
|
87
164
|
|
|
88
|
-
|
|
165
|
+
Toast · ToastContainer · Spinner · Loader · PageLoader · Shimmer
|
|
89
166
|
|
|
90
167
|
### Overlays & Navigation
|
|
91
168
|
|
|
92
|
-
|
|
169
|
+
Modal · Pagination · Carousel
|
|
93
170
|
|
|
94
171
|
### Forms & Productivity
|
|
95
172
|
|
|
96
|
-
|
|
173
|
+
OtpInput · FileUploader · DatePicker
|
|
97
174
|
|
|
98
175
|
### Media
|
|
99
176
|
|
|
100
|
-
|
|
177
|
+
Image · VideoPlayer
|
|
101
178
|
|
|
102
179
|
### Typography
|
|
103
180
|
|
|
104
|
-
|
|
181
|
+
H1–H6 · P
|
|
105
182
|
|
|
106
|
-
### Utility
|
|
183
|
+
### Utility
|
|
107
184
|
|
|
108
|
-
|
|
185
|
+
Timer · RootComponent
|
|
109
186
|
|
|
110
|
-
|
|
187
|
+
---
|
|
111
188
|
|
|
112
|
-
##
|
|
189
|
+
## Tokens
|
|
113
190
|
|
|
114
|
-
|
|
115
|
-
Arrows, Commerce, Social, Media, Security, UI controls...
|
|
191
|
+
### Colors
|
|
116
192
|
|
|
117
|
-
|
|
193
|
+
23 production-ready palettes (blue, red, green, amber, grey, cider, and more) with multiple shades each.
|
|
194
|
+
→ [Explore colors](https://meticulous-ui.vercel.app/?path=/story/tokens-colors--default)
|
|
118
195
|
|
|
119
|
-
|
|
196
|
+
### Icons
|
|
120
197
|
|
|
121
|
-
|
|
122
|
-
|
|
198
|
+
100+ modern SVG icons across categories: arrows, commerce, social, media, security, UI controls.
|
|
199
|
+
→ [Explore icons](https://meticulous-ui.vercel.app/?path=/story/tokens-icons--default)
|
|
123
200
|
|
|
124
|
-
|
|
201
|
+
---
|
|
125
202
|
|
|
126
|
-
##
|
|
203
|
+
## Hooks
|
|
127
204
|
|
|
128
|
-
|
|
129
|
-
String, Number, Object, Validation, UI...
|
|
205
|
+
Custom hooks organized by purpose:
|
|
130
206
|
|
|
131
|
-
|
|
207
|
+
| Category | Examples |
|
|
208
|
+
| ----------- | -------------------------------------- |
|
|
209
|
+
| State | `useToggle`, `useCounter` |
|
|
210
|
+
| Lifecycle | `useMountEffect`, `usePrevious` |
|
|
211
|
+
| Storage | `useLocalStorage`, `useSessionStorage` |
|
|
212
|
+
| DOM/Browser | `useMediaQuery`, `useClickOutside` |
|
|
213
|
+
| Utility | `useDebounce`, `useThrottle` |
|
|
132
214
|
|
|
133
|
-
|
|
215
|
+
---
|
|
134
216
|
|
|
135
|
-
|
|
136
|
-
lazyImport, composeProviders, withSuspense, memoCompare...
|
|
217
|
+
## Engineering Utilities
|
|
137
218
|
|
|
138
|
-
|
|
219
|
+
Production-focused utility functions organized by domain:
|
|
139
220
|
|
|
140
|
-
|
|
221
|
+
| Category | Examples |
|
|
222
|
+
| -------------- | ------------------------------ |
|
|
223
|
+
| Validation | `validateEmail`, `validateUrl` |
|
|
224
|
+
| String | `truncate`, `slugify` |
|
|
225
|
+
| Number | `clamp`, `formatCurrency` |
|
|
226
|
+
| Date-time | `formatDate`, `timeAgo` |
|
|
227
|
+
| API | `retry`, `debounceAsync` |
|
|
228
|
+
| Auth | token helpers |
|
|
229
|
+
| Feature flags | `isFeatureEnabled` |
|
|
230
|
+
| Accessibility | `getFocusableElements` |
|
|
231
|
+
| Performance | `memoize`, `measureTime` |
|
|
232
|
+
| Error handling | `tryCatch`, `safeJSON` |
|
|
233
|
+
| Storage | `safeGet`, `safeSet` |
|
|
141
234
|
|
|
142
|
-
|
|
143
|
-
State, Lifecycle, DOM/Browser, Storage & Utility
|
|
235
|
+
---
|
|
144
236
|
|
|
145
|
-
|
|
237
|
+
## React Utilities
|
|
146
238
|
|
|
147
|
-
|
|
239
|
+
Helper functions for scalable React patterns:
|
|
148
240
|
|
|
149
|
-
|
|
241
|
+
- `lazyImport` — code-split any module with a consistent API
|
|
242
|
+
- `composeProviders` — flatten deeply nested providers
|
|
243
|
+
- `withSuspense` — wrap any component with a Suspense boundary
|
|
244
|
+
- `memoCompare` — custom comparator for `React.memo`
|
|
150
245
|
|
|
151
|
-
|
|
246
|
+
---
|
|
152
247
|
|
|
153
|
-
|
|
248
|
+
## Performance
|
|
154
249
|
|
|
155
|
-
|
|
250
|
+
meticulous-ui is built to have zero performance cost at the bundler level.
|
|
156
251
|
|
|
157
|
-
|
|
252
|
+
- ⚡ **Fully tree-shakeable** — unused code is eliminated at build time
|
|
253
|
+
- 🪶 **Side-effect free** — safe for aggressive dead code elimination
|
|
254
|
+
- 📦 **Import only what you use** — one component, one hook, or the whole library
|
|
255
|
+
- 🔀 **ESM + CJS** — works with every modern bundler and runtime
|
|
256
|
+
- 🚀 **Optimized for Vite, Webpack, Rollup, and Next.js** — no config needed
|
|
158
257
|
|
|
159
|
-
|
|
258
|
+
```ts
|
|
259
|
+
// pays for Button only — nothing else ships
|
|
260
|
+
import Button from 'meticulous-ui/components/Button';
|
|
160
261
|
|
|
262
|
+
// or use named imports — tree-shaking handles the rest
|
|
263
|
+
import { Button, useLocalStorage } from 'meticulous-ui';
|
|
161
264
|
```
|
|
162
265
|
|
|
163
|
-
|
|
164
|
-
|
|
266
|
+
Bundle size: [bundlephobia.com/package/meticulous-ui](https://bundlephobia.com/package/meticulous-ui)
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## Philosophy
|
|
165
271
|
|
|
166
|
-
|
|
167
|
-
|
|
272
|
+
- **Minimal dependencies** — no opinion on state management or routing
|
|
273
|
+
- **Consistent developer experience** — predictable APIs across all layers
|
|
274
|
+
- **Accessibility by default** — ARIA + semantic HTML throughout
|
|
275
|
+
- **Performance-first** — tree-shakeable, side-effect free, zero external CSS
|
|
276
|
+
- **Scalable architecture** — layered design you can adopt incrementally
|
|
168
277
|
|
|
169
|
-
|
|
170
|
-
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## Development Setup
|
|
171
281
|
|
|
282
|
+
```bash
|
|
283
|
+
npm install # install dependencies
|
|
284
|
+
npm run dev # start Storybook dev server
|
|
285
|
+
npm run build # build the library
|
|
172
286
|
```
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## Contributing
|
|
291
|
+
|
|
292
|
+
Contributions, bug reports, and feature requests are welcome.
|
|
293
|
+
|
|
294
|
+
**Adding a component**
|
|
295
|
+
|
|
296
|
+
1. Create the component under `src/components/<ComponentName>/`
|
|
297
|
+
2. Export it from the component's `index.ts` and from the root `src/index.ts`
|
|
298
|
+
3. Add a Storybook story under `src/stories/`
|
|
299
|
+
4. Use color tokens from `src/colors/` — never hardcode hex values
|
|
300
|
+
|
|
301
|
+
**Adding a hook or utility**
|
|
302
|
+
|
|
303
|
+
1. Add the function to the appropriate file under `src/hooks/` or `src/utils/`
|
|
304
|
+
2. Export it from the root `src/index.ts`
|
|
305
|
+
3. Add a Storybook story or docs entry if it has non-obvious usage
|
|
306
|
+
|
|
307
|
+
**General guidelines**
|
|
308
|
+
|
|
309
|
+
- All public APIs must be typed — no `any`
|
|
310
|
+
- Stories act as documentation; write them for the consumer, not the implementer
|
|
311
|
+
- Open an issue or discussion first for significant changes
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## Changelog
|
|
316
|
+
|
|
317
|
+
See [CHANGELOG.md](./CHANGELOG.md) for release history and migration guides between major versions.
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## License
|
|
322
|
+
|
|
323
|
+
ISC
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "meticulous-ui",
|
|
3
|
-
"version": "3.8.
|
|
3
|
+
"version": "3.8.7",
|
|
4
4
|
"license": "ISC",
|
|
5
5
|
"description": "A comprehensive React UI component library with a wide range of customizable components, icons, colors, and utilities for building modern web applications.",
|
|
6
6
|
"types": "./index.d.ts",
|
|
@@ -65,13 +65,33 @@
|
|
|
65
65
|
},
|
|
66
66
|
"keywords": [
|
|
67
67
|
"react",
|
|
68
|
-
"
|
|
69
|
-
"
|
|
68
|
+
"reactjs",
|
|
69
|
+
"react-components",
|
|
70
|
+
"ui-library",
|
|
70
71
|
"component-library",
|
|
72
|
+
"design-system",
|
|
73
|
+
"react-ui",
|
|
74
|
+
"typescript",
|
|
71
75
|
"styled-components",
|
|
72
|
-
"
|
|
73
|
-
"
|
|
76
|
+
"hooks",
|
|
77
|
+
"custom-hooks",
|
|
78
|
+
"utilities",
|
|
79
|
+
"frontend-toolkit",
|
|
80
|
+
"frontend-platform",
|
|
81
|
+
"enterprise-ui",
|
|
82
|
+
"tree-shaking",
|
|
83
|
+
"side-effects-free",
|
|
84
|
+
"zero-dependencies",
|
|
74
85
|
"accessible",
|
|
75
|
-
"
|
|
86
|
+
"accessibility",
|
|
87
|
+
"aria",
|
|
88
|
+
"storybook",
|
|
89
|
+
"design-tokens",
|
|
90
|
+
"icons",
|
|
91
|
+
"react-hooks",
|
|
92
|
+
"performance",
|
|
93
|
+
"scalable-ui",
|
|
94
|
+
"dashboard-ui",
|
|
95
|
+
"frontend-architecture"
|
|
76
96
|
]
|
|
77
97
|
}
|