@foundrykit/utils 0.1.1 → 1.0.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/CHANGELOG.md +12 -0
- package/README.md +98 -87
- package/package.json +3 -3
- package/.turbo/turbo-build.log +0 -18
- package/.turbo/turbo-type-check.log +0 -5
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
# @foundrykit/utils
|
|
2
2
|
|
|
3
|
-
A collection of utility functions and helpers for common development tasks.
|
|
3
|
+
A collection of utility functions and helpers for common development tasks.
|
|
4
|
+
Provides type-safe utilities for class names, validation, formatting, and more.
|
|
4
5
|
|
|
5
6
|
## Features
|
|
6
7
|
|
|
7
|
-
- **Type-safe utilities** - Full TypeScript support with comprehensive type
|
|
8
|
+
- **Type-safe utilities** - Full TypeScript support with comprehensive type
|
|
9
|
+
definitions
|
|
8
10
|
- **Zero dependencies** - Lightweight with no external dependencies
|
|
9
11
|
- **Tree-shakable** - Only import what you need
|
|
10
12
|
- **Well-tested** - Comprehensive test coverage
|
|
@@ -19,25 +21,30 @@ pnpm add @foundrykit/utils
|
|
|
19
21
|
## Available Utilities
|
|
20
22
|
|
|
21
23
|
### Class Name Utilities
|
|
24
|
+
|
|
22
25
|
- **cn** - Conditional class name utility (clsx + tailwind-merge)
|
|
23
26
|
- **cva** - Class variance authority for component variants
|
|
24
27
|
|
|
25
28
|
### Validation Utilities
|
|
29
|
+
|
|
26
30
|
- **isValidEmail** - Email validation
|
|
27
31
|
- **isValidUrl** - URL validation
|
|
28
32
|
- **isValidPhone** - Phone number validation
|
|
29
33
|
|
|
30
34
|
### Formatting Utilities
|
|
35
|
+
|
|
31
36
|
- **formatDate** - Date formatting utilities
|
|
32
37
|
- **formatCurrency** - Currency formatting
|
|
33
38
|
- **formatNumber** - Number formatting
|
|
34
39
|
|
|
35
40
|
### Array Utilities
|
|
41
|
+
|
|
36
42
|
- **chunk** - Split array into chunks
|
|
37
43
|
- **unique** - Remove duplicates from array
|
|
38
44
|
- **groupBy** - Group array items by key
|
|
39
45
|
|
|
40
46
|
### Object Utilities
|
|
47
|
+
|
|
41
48
|
- **pick** - Pick specific keys from object
|
|
42
49
|
- **omit** - Omit specific keys from object
|
|
43
50
|
- **deepMerge** - Deep merge objects
|
|
@@ -51,25 +58,26 @@ pnpm add @foundrykit/utils
|
|
|
51
58
|
The primary utility for combining class names with Tailwind CSS:
|
|
52
59
|
|
|
53
60
|
```tsx
|
|
54
|
-
import { cn } from '@foundrykit/utils'
|
|
61
|
+
import { cn } from '@foundrykit/utils';
|
|
55
62
|
|
|
56
63
|
function Button({ className, variant, ...props }) {
|
|
57
64
|
return (
|
|
58
65
|
<button
|
|
59
66
|
className={cn(
|
|
60
67
|
// Base classes
|
|
61
|
-
|
|
62
|
-
|
|
68
|
+
'rounded px-4 py-2 font-medium',
|
|
69
|
+
|
|
63
70
|
// Conditional classes
|
|
64
|
-
variant ===
|
|
65
|
-
variant ===
|
|
66
|
-
|
|
71
|
+
variant === 'primary' && 'bg-blue-500 text-white hover:bg-blue-600',
|
|
72
|
+
variant === 'secondary' &&
|
|
73
|
+
'bg-gray-200 text-gray-900 hover:bg-gray-300',
|
|
74
|
+
|
|
67
75
|
// User-provided classes (merged intelligently)
|
|
68
76
|
className
|
|
69
77
|
)}
|
|
70
78
|
{...props}
|
|
71
79
|
/>
|
|
72
|
-
)
|
|
80
|
+
);
|
|
73
81
|
}
|
|
74
82
|
```
|
|
75
83
|
|
|
@@ -78,34 +86,37 @@ function Button({ className, variant, ...props }) {
|
|
|
78
86
|
Create type-safe component variants:
|
|
79
87
|
|
|
80
88
|
```tsx
|
|
81
|
-
import { cva } from '@foundrykit/utils'
|
|
89
|
+
import { cva } from '@foundrykit/utils';
|
|
82
90
|
|
|
83
91
|
const buttonVariants = cva(
|
|
84
92
|
// Base classes
|
|
85
|
-
|
|
93
|
+
'inline-flex items-center justify-center rounded-md font-medium transition-colors',
|
|
86
94
|
{
|
|
87
95
|
variants: {
|
|
88
96
|
variant: {
|
|
89
|
-
default:
|
|
90
|
-
destructive:
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
97
|
+
default: 'bg-primary text-primary-foreground hover:bg-primary/90',
|
|
98
|
+
destructive:
|
|
99
|
+
'bg-destructive text-destructive-foreground hover:bg-destructive/90',
|
|
100
|
+
outline:
|
|
101
|
+
'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
|
|
102
|
+
secondary:
|
|
103
|
+
'bg-secondary text-secondary-foreground hover:bg-secondary/80',
|
|
104
|
+
ghost: 'hover:bg-accent hover:text-accent-foreground',
|
|
105
|
+
link: 'text-primary underline-offset-4 hover:underline',
|
|
95
106
|
},
|
|
96
107
|
size: {
|
|
97
|
-
default:
|
|
98
|
-
sm:
|
|
99
|
-
lg:
|
|
100
|
-
icon:
|
|
108
|
+
default: 'h-10 px-4 py-2',
|
|
109
|
+
sm: 'h-9 rounded-md px-3',
|
|
110
|
+
lg: 'h-11 rounded-md px-8',
|
|
111
|
+
icon: 'h-10 w-10',
|
|
101
112
|
},
|
|
102
113
|
},
|
|
103
114
|
defaultVariants: {
|
|
104
|
-
variant:
|
|
105
|
-
size:
|
|
115
|
+
variant: 'default',
|
|
116
|
+
size: 'default',
|
|
106
117
|
},
|
|
107
118
|
}
|
|
108
|
-
)
|
|
119
|
+
);
|
|
109
120
|
|
|
110
121
|
function Button({ className, variant, size, ...props }) {
|
|
111
122
|
return (
|
|
@@ -113,64 +124,64 @@ function Button({ className, variant, size, ...props }) {
|
|
|
113
124
|
className={cn(buttonVariants({ variant, size }), className)}
|
|
114
125
|
{...props}
|
|
115
126
|
/>
|
|
116
|
-
)
|
|
127
|
+
);
|
|
117
128
|
}
|
|
118
129
|
```
|
|
119
130
|
|
|
120
131
|
### Validation Utilities
|
|
121
132
|
|
|
122
133
|
```tsx
|
|
123
|
-
import { isValidEmail, isValidUrl, isValidPhone } from '@foundrykit/utils'
|
|
134
|
+
import { isValidEmail, isValidUrl, isValidPhone } from '@foundrykit/utils';
|
|
124
135
|
|
|
125
136
|
// Email validation
|
|
126
|
-
isValidEmail(
|
|
127
|
-
isValidEmail(
|
|
137
|
+
isValidEmail('user@example.com'); // true
|
|
138
|
+
isValidEmail('invalid-email'); // false
|
|
128
139
|
|
|
129
140
|
// URL validation
|
|
130
|
-
isValidUrl(
|
|
131
|
-
isValidUrl(
|
|
141
|
+
isValidUrl('https://example.com'); // true
|
|
142
|
+
isValidUrl('not-a-url'); // false
|
|
132
143
|
|
|
133
144
|
// Phone validation
|
|
134
|
-
isValidPhone(
|
|
135
|
-
isValidPhone(
|
|
145
|
+
isValidPhone('+1-555-123-4567'); // true
|
|
146
|
+
isValidPhone('123'); // false
|
|
136
147
|
```
|
|
137
148
|
|
|
138
149
|
### Formatting Utilities
|
|
139
150
|
|
|
140
151
|
```tsx
|
|
141
|
-
import { formatDate, formatCurrency, formatNumber } from '@foundrykit/utils'
|
|
152
|
+
import { formatDate, formatCurrency, formatNumber } from '@foundrykit/utils';
|
|
142
153
|
|
|
143
154
|
// Date formatting
|
|
144
|
-
formatDate(new Date(),
|
|
145
|
-
formatDate(new Date(),
|
|
155
|
+
formatDate(new Date(), 'MMM dd, yyyy'); // "Jan 15, 2024"
|
|
156
|
+
formatDate(new Date(), 'relative'); // "2 hours ago"
|
|
146
157
|
|
|
147
158
|
// Currency formatting
|
|
148
|
-
formatCurrency(1234.56,
|
|
149
|
-
formatCurrency(1234.56,
|
|
159
|
+
formatCurrency(1234.56, 'USD'); // "$1,234.56"
|
|
160
|
+
formatCurrency(1234.56, 'EUR'); // "€1,234.56"
|
|
150
161
|
|
|
151
162
|
// Number formatting
|
|
152
|
-
formatNumber(1234567) // "1,234,567"
|
|
153
|
-
formatNumber(1234.56, { decimals: 2 }) // "1,234.56"
|
|
163
|
+
formatNumber(1234567); // "1,234,567"
|
|
164
|
+
formatNumber(1234.56, { decimals: 2 }); // "1,234.56"
|
|
154
165
|
```
|
|
155
166
|
|
|
156
167
|
### Array Utilities
|
|
157
168
|
|
|
158
169
|
```tsx
|
|
159
|
-
import { chunk, unique, groupBy } from '@foundrykit/utils'
|
|
170
|
+
import { chunk, unique, groupBy } from '@foundrykit/utils';
|
|
160
171
|
|
|
161
172
|
// Split array into chunks
|
|
162
|
-
chunk([1, 2, 3, 4, 5, 6], 2) // [[1, 2], [3, 4], [5, 6]]
|
|
173
|
+
chunk([1, 2, 3, 4, 5, 6], 2); // [[1, 2], [3, 4], [5, 6]]
|
|
163
174
|
|
|
164
175
|
// Remove duplicates
|
|
165
|
-
unique([1, 2, 2, 3, 3, 4]) // [1, 2, 3, 4]
|
|
176
|
+
unique([1, 2, 2, 3, 3, 4]); // [1, 2, 3, 4]
|
|
166
177
|
|
|
167
178
|
// Group by key
|
|
168
179
|
const users = [
|
|
169
|
-
{ name:
|
|
170
|
-
{ name:
|
|
171
|
-
{ name:
|
|
172
|
-
]
|
|
173
|
-
groupBy(users,
|
|
180
|
+
{ name: 'Alice', role: 'admin' },
|
|
181
|
+
{ name: 'Bob', role: 'user' },
|
|
182
|
+
{ name: 'Charlie', role: 'admin' },
|
|
183
|
+
];
|
|
184
|
+
groupBy(users, 'role');
|
|
174
185
|
// {
|
|
175
186
|
// admin: [{ name: "Alice", role: "admin" }, { name: "Charlie", role: "admin" }],
|
|
176
187
|
// user: [{ name: "Bob", role: "user" }]
|
|
@@ -180,25 +191,25 @@ groupBy(users, "role")
|
|
|
180
191
|
### Object Utilities
|
|
181
192
|
|
|
182
193
|
```tsx
|
|
183
|
-
import { pick, omit, deepMerge } from '@foundrykit/utils'
|
|
194
|
+
import { pick, omit, deepMerge } from '@foundrykit/utils';
|
|
184
195
|
|
|
185
196
|
const user = {
|
|
186
197
|
id: 1,
|
|
187
|
-
name:
|
|
188
|
-
email:
|
|
189
|
-
password:
|
|
190
|
-
}
|
|
198
|
+
name: 'John',
|
|
199
|
+
email: 'john@example.com',
|
|
200
|
+
password: 'secret',
|
|
201
|
+
};
|
|
191
202
|
|
|
192
203
|
// Pick specific keys
|
|
193
|
-
pick(user, [
|
|
204
|
+
pick(user, ['id', 'name']); // { id: 1, name: "John" }
|
|
194
205
|
|
|
195
206
|
// Omit specific keys
|
|
196
|
-
omit(user, [
|
|
207
|
+
omit(user, ['password']); // { id: 1, name: "John", email: "john@example.com" }
|
|
197
208
|
|
|
198
209
|
// Deep merge objects
|
|
199
|
-
const obj1 = { a: 1, b: { c: 2 } }
|
|
200
|
-
const obj2 = { b: { d: 3 }, e: 4 }
|
|
201
|
-
deepMerge(obj1, obj2) // { a: 1, b: { c: 2, d: 3 }, e: 4 }
|
|
210
|
+
const obj1 = { a: 1, b: { c: 2 } };
|
|
211
|
+
const obj2 = { b: { d: 3 }, e: 4 };
|
|
212
|
+
deepMerge(obj1, obj2); // { a: 1, b: { c: 2, d: 3 }, e: 4 }
|
|
202
213
|
```
|
|
203
214
|
|
|
204
215
|
## Advanced Usage
|
|
@@ -206,46 +217,46 @@ deepMerge(obj1, obj2) // { a: 1, b: { c: 2, d: 3 }, e: 4 }
|
|
|
206
217
|
### Custom Class Name Logic
|
|
207
218
|
|
|
208
219
|
```tsx
|
|
209
|
-
import { cn } from '@foundrykit/utils'
|
|
220
|
+
import { cn } from '@foundrykit/utils';
|
|
210
221
|
|
|
211
222
|
function StatusBadge({ status, className }) {
|
|
212
223
|
return (
|
|
213
224
|
<span
|
|
214
225
|
className={cn(
|
|
215
|
-
|
|
226
|
+
'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium',
|
|
216
227
|
{
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
228
|
+
'bg-green-100 text-green-800': status === 'active',
|
|
229
|
+
'bg-red-100 text-red-800': status === 'inactive',
|
|
230
|
+
'bg-yellow-100 text-yellow-800': status === 'pending',
|
|
220
231
|
},
|
|
221
232
|
className
|
|
222
233
|
)}
|
|
223
234
|
>
|
|
224
235
|
{status}
|
|
225
236
|
</span>
|
|
226
|
-
)
|
|
237
|
+
);
|
|
227
238
|
}
|
|
228
239
|
```
|
|
229
240
|
|
|
230
241
|
### Conditional Rendering with Classes
|
|
231
242
|
|
|
232
243
|
```tsx
|
|
233
|
-
import { cn } from '@foundrykit/utils'
|
|
244
|
+
import { cn } from '@foundrykit/utils';
|
|
234
245
|
|
|
235
246
|
function Card({ isActive, isDisabled, children, className }) {
|
|
236
247
|
return (
|
|
237
248
|
<div
|
|
238
249
|
className={cn(
|
|
239
|
-
|
|
240
|
-
isActive &&
|
|
241
|
-
isDisabled &&
|
|
242
|
-
!isActive && !isDisabled &&
|
|
250
|
+
'rounded-lg border p-4 transition-all',
|
|
251
|
+
isActive && 'border-blue-500 bg-blue-50',
|
|
252
|
+
isDisabled && 'cursor-not-allowed opacity-50',
|
|
253
|
+
!isActive && !isDisabled && 'hover:border-gray-300',
|
|
243
254
|
className
|
|
244
255
|
)}
|
|
245
256
|
>
|
|
246
257
|
{children}
|
|
247
258
|
</div>
|
|
248
|
-
)
|
|
259
|
+
);
|
|
249
260
|
}
|
|
250
261
|
```
|
|
251
262
|
|
|
@@ -257,13 +268,13 @@ Import only what you need:
|
|
|
257
268
|
|
|
258
269
|
```tsx
|
|
259
270
|
// Good - only imports cn
|
|
260
|
-
import { cn } from '@foundrykit/utils'
|
|
271
|
+
import { cn } from '@foundrykit/utils';
|
|
261
272
|
|
|
262
273
|
// Good - imports multiple utilities
|
|
263
|
-
import { cn, cva, isValidEmail } from '@foundrykit/utils'
|
|
274
|
+
import { cn, cva, isValidEmail } from '@foundrykit/utils';
|
|
264
275
|
|
|
265
276
|
// Avoid - imports everything
|
|
266
|
-
import * as utils from '@foundrykit/utils'
|
|
277
|
+
import * as utils from '@foundrykit/utils';
|
|
267
278
|
```
|
|
268
279
|
|
|
269
280
|
### Memoization
|
|
@@ -271,12 +282,12 @@ import * as utils from '@foundrykit/utils'
|
|
|
271
282
|
For expensive operations, consider memoization:
|
|
272
283
|
|
|
273
284
|
```tsx
|
|
274
|
-
import { useMemo } from 'react'
|
|
275
|
-
import { groupBy } from '@foundrykit/utils'
|
|
285
|
+
import { useMemo } from 'react';
|
|
286
|
+
import { groupBy } from '@foundrykit/utils';
|
|
276
287
|
|
|
277
288
|
function UserList({ users }) {
|
|
278
|
-
const usersByRole = useMemo(() => groupBy(users,
|
|
279
|
-
|
|
289
|
+
const usersByRole = useMemo(() => groupBy(users, 'role'), [users]);
|
|
290
|
+
|
|
280
291
|
return (
|
|
281
292
|
<div>
|
|
282
293
|
{Object.entries(usersByRole).map(([role, users]) => (
|
|
@@ -288,7 +299,7 @@ function UserList({ users }) {
|
|
|
288
299
|
</div>
|
|
289
300
|
))}
|
|
290
301
|
</div>
|
|
291
|
-
)
|
|
302
|
+
);
|
|
292
303
|
}
|
|
293
304
|
```
|
|
294
305
|
|
|
@@ -297,24 +308,24 @@ function UserList({ users }) {
|
|
|
297
308
|
All utilities include comprehensive TypeScript definitions:
|
|
298
309
|
|
|
299
310
|
```tsx
|
|
300
|
-
import { cn, cva } from '@foundrykit/utils'
|
|
311
|
+
import { cn, cva } from '@foundrykit/utils';
|
|
301
312
|
|
|
302
313
|
// Type-safe class name utility
|
|
303
|
-
const className: string = cn(
|
|
314
|
+
const className: string = cn('base-class', true && 'conditional-class');
|
|
304
315
|
|
|
305
316
|
// Type-safe variants
|
|
306
|
-
const buttonVariants = cva(
|
|
317
|
+
const buttonVariants = cva('base', {
|
|
307
318
|
variants: {
|
|
308
319
|
size: {
|
|
309
|
-
sm:
|
|
310
|
-
lg:
|
|
311
|
-
}
|
|
312
|
-
}
|
|
313
|
-
})
|
|
320
|
+
sm: 'text-sm',
|
|
321
|
+
lg: 'text-lg',
|
|
322
|
+
},
|
|
323
|
+
},
|
|
324
|
+
});
|
|
314
325
|
|
|
315
326
|
// TypeScript knows the available variants
|
|
316
|
-
const buttonClass = buttonVariants({ size:
|
|
317
|
-
const invalidClass = buttonVariants({ size:
|
|
327
|
+
const buttonClass = buttonVariants({ size: 'sm' }); // ✅ Valid
|
|
328
|
+
const invalidClass = buttonVariants({ size: 'xl' }); // ❌ Type error
|
|
318
329
|
```
|
|
319
330
|
|
|
320
331
|
## Contributing
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@foundrykit/utils",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"private": false,
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -24,8 +24,8 @@
|
|
|
24
24
|
"eslint": "^9.0.0",
|
|
25
25
|
"tsup": "^8.0.0",
|
|
26
26
|
"typescript": "^5.9.2",
|
|
27
|
-
"@foundrykit/eslint-config": "0.
|
|
28
|
-
"@foundrykit/typescript-config": "0.
|
|
27
|
+
"@foundrykit/eslint-config": "1.0.0",
|
|
28
|
+
"@foundrykit/typescript-config": "1.0.0"
|
|
29
29
|
},
|
|
30
30
|
"scripts": {
|
|
31
31
|
"build": "tsup",
|
package/.turbo/turbo-build.log
DELETED
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
> @foundrykit/utils@0.1.0 build /Users/isaacsneddon-jenkins/Desktop/projects/umi/projects/foundrykit/packages/utils
|
|
4
|
-
> tsup
|
|
5
|
-
|
|
6
|
-
[34mCLI[39m Building entry: src/index.ts
|
|
7
|
-
[34mCLI[39m Using tsconfig: tsconfig.json
|
|
8
|
-
[34mCLI[39m tsup v8.5.0
|
|
9
|
-
[34mCLI[39m Using tsup config: /Users/isaacsneddon-jenkins/Desktop/projects/umi/projects/foundrykit/packages/utils/tsup.config.ts
|
|
10
|
-
[34mCLI[39m Target: es2022
|
|
11
|
-
[34mCLI[39m Cleaning output folder
|
|
12
|
-
[34mESM[39m Build start
|
|
13
|
-
[32mESM[39m [1mdist/index.js [22m[32m196.00 B[39m
|
|
14
|
-
[32mESM[39m [1mdist/index.js.map [22m[32m357.00 B[39m
|
|
15
|
-
[32mESM[39m ⚡️ Build success in 153ms
|
|
16
|
-
DTS Build start
|
|
17
|
-
DTS ⚡️ Build success in 3382ms
|
|
18
|
-
DTS dist/index.d.ts 106.00 B
|