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