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