@foundrykit/utils 1.0.5 → 1.0.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.
@@ -0,0 +1,17 @@
1
+
2
+ > @foundrykit/utils@1.0.7 build /home/runner/work/foundry/foundry/packages/utils
3
+ > tsup
4
+
5
+ CLI Building entry: src/index.ts
6
+ CLI Using tsconfig: tsconfig.json
7
+ CLI tsup v8.5.0
8
+ CLI Using tsup config: /home/runner/work/foundry/foundry/packages/utils/tsup.config.ts
9
+ CLI Target: es2022
10
+ CLI Cleaning output folder
11
+ ESM Build start
12
+ ESM dist/index.js 196.00 B
13
+ ESM dist/index.js.map 660.00 B
14
+ ESM ⚡️ Build success in 40ms
15
+ DTS Build start
16
+ DTS ⚡️ Build success in 2908ms
17
+ DTS dist/index.d.ts 402.00 B
@@ -0,0 +1,4 @@
1
+
2
+ > @foundrykit/utils@1.0.7 type-check /home/runner/work/foundry/foundry/packages/utils
3
+ > tsc --noEmit
4
+
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # @foundrykit/utils
2
2
 
3
+ ## 1.0.7
4
+
5
+ ### Patch Changes
6
+
7
+ - [#43](https://github.com/umi-labs/foundry/pull/43) [`b6fc94d`](https://github.com/umi-labs/foundry/commit/b6fc94d3b0f172aa309388f61bd5306af6405fdf) Thanks [@sneddonisaac](https://github.com/sneddonisaac)! - Package metadata now points at the `umi-labs/foundry` monorepo, and releases publish through npm trusted publishing.
8
+
9
+ - Updated dependencies [[`b6fc94d`](https://github.com/umi-labs/foundry/commit/b6fc94d3b0f172aa309388f61bd5306af6405fdf)]:
10
+ - @foundrykit/types@2.0.7
11
+
12
+ ## 1.0.6
13
+
14
+ ### Patch Changes
15
+
16
+ - Just a quick demo for Anvar
17
+
3
18
  ## 1.0.5
4
19
 
5
20
  ### Patch Changes
package/README.md CHANGED
@@ -1,16 +1,6 @@
1
1
  # @foundrykit/utils
2
2
 
3
- A collection of utility functions and helpers for common development tasks.
4
- Provides type-safe utilities for class names, validation, formatting, and more.
5
-
6
- ## Features
7
-
8
- - **Type-safe utilities** - Full TypeScript support with comprehensive type
9
- definitions
10
- - **Zero dependencies** - Lightweight with no external dependencies
11
- - **Tree-shakable** - Only import what you need
12
- - **Well-tested** - Comprehensive test coverage
13
- - **Performance optimized** - Efficient implementations
3
+ Shared utility helpers for the FoundryKit ecosystem.
14
4
 
15
5
  ## Installation
16
6
 
@@ -18,326 +8,29 @@ Provides type-safe utilities for class names, validation, formatting, and more.
18
8
  pnpm add @foundrykit/utils
19
9
  ```
20
10
 
21
- ## Available Utilities
22
-
23
- ### Class Name Utilities
24
-
25
- - **cn** - Conditional class name utility (clsx + tailwind-merge)
26
- - **cva** - Class variance authority for component variants
27
-
28
- ### Validation Utilities
29
-
30
- - **isValidEmail** - Email validation
31
- - **isValidUrl** - URL validation
32
- - **isValidPhone** - Phone number validation
33
-
34
- ### Formatting Utilities
35
-
36
- - **formatDate** - Date formatting utilities
37
- - **formatCurrency** - Currency formatting
38
- - **formatNumber** - Number formatting
39
-
40
- ### Array Utilities
41
-
42
- - **chunk** - Split array into chunks
43
- - **unique** - Remove duplicates from array
44
- - **groupBy** - Group array items by key
45
-
46
- ### Object Utilities
47
-
48
- - **pick** - Pick specific keys from object
49
- - **omit** - Omit specific keys from object
50
- - **deepMerge** - Deep merge objects
51
-
52
11
  ## Usage
53
12
 
54
- ### Class Name Utilities
55
-
56
- #### cn (Conditional Class Names)
57
-
58
- The primary utility for combining class names with Tailwind CSS:
59
-
60
13
  ```tsx
61
14
  import { cn } from '@foundrykit/utils';
62
15
 
63
- function Button({ className, variant, ...props }) {
64
- return (
65
- <button
66
- className={cn(
67
- // Base classes
68
- 'rounded px-4 py-2 font-medium',
69
-
70
- // Conditional classes
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
-
75
- // User-provided classes (merged intelligently)
76
- className
77
- )}
78
- {...props}
79
- />
80
- );
81
- }
82
- ```
83
-
84
- #### cva (Class Variance Authority)
85
-
86
- Create type-safe component variants:
87
-
88
- ```tsx
89
- import { cva } from '@foundrykit/utils';
90
-
91
- const buttonVariants = cva(
92
- // Base classes
93
- 'inline-flex items-center justify-center rounded-md font-medium transition-colors',
94
- {
95
- variants: {
96
- variant: {
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',
106
- },
107
- size: {
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',
112
- },
113
- },
114
- defaultVariants: {
115
- variant: 'default',
116
- size: 'default',
117
- },
118
- }
119
- );
120
-
121
- function Button({ className, variant, size, ...props }) {
16
+ function Button({ className, isActive }) {
122
17
  return (
123
18
  <button
124
- className={cn(buttonVariants({ variant, size }), className)}
125
- {...props}
19
+ className={cn('rounded px-4 py-2', isActive && 'bg-blue-500', className)}
126
20
  />
127
21
  );
128
22
  }
129
23
  ```
130
24
 
131
- ### Validation Utilities
132
-
133
- ```tsx
134
- import { isValidEmail, isValidUrl, isValidPhone } from '@foundrykit/utils';
135
-
136
- // Email validation
137
- isValidEmail('user@example.com'); // true
138
- isValidEmail('invalid-email'); // false
139
-
140
- // URL validation
141
- isValidUrl('https://example.com'); // true
142
- isValidUrl('not-a-url'); // false
143
-
144
- // Phone validation
145
- isValidPhone('+1-555-123-4567'); // true
146
- isValidPhone('123'); // false
147
- ```
148
-
149
- ### Formatting Utilities
150
-
151
- ```tsx
152
- import { formatDate, formatCurrency, formatNumber } from '@foundrykit/utils';
153
-
154
- // Date formatting
155
- formatDate(new Date(), 'MMM dd, yyyy'); // "Jan 15, 2024"
156
- formatDate(new Date(), 'relative'); // "2 hours ago"
157
-
158
- // Currency formatting
159
- formatCurrency(1234.56, 'USD'); // "$1,234.56"
160
- formatCurrency(1234.56, 'EUR'); // "€1,234.56"
161
-
162
- // Number formatting
163
- formatNumber(1234567); // "1,234,567"
164
- formatNumber(1234.56, { decimals: 2 }); // "1,234.56"
165
- ```
166
-
167
- ### Array Utilities
168
-
169
- ```tsx
170
- import { chunk, unique, groupBy } from '@foundrykit/utils';
171
-
172
- // Split array into chunks
173
- chunk([1, 2, 3, 4, 5, 6], 2); // [[1, 2], [3, 4], [5, 6]]
174
-
175
- // Remove duplicates
176
- unique([1, 2, 2, 3, 3, 4]); // [1, 2, 3, 4]
177
-
178
- // Group by key
179
- const users = [
180
- { name: 'Alice', role: 'admin' },
181
- { name: 'Bob', role: 'user' },
182
- { name: 'Charlie', role: 'admin' },
183
- ];
184
- groupBy(users, 'role');
185
- // {
186
- // admin: [{ name: "Alice", role: "admin" }, { name: "Charlie", role: "admin" }],
187
- // user: [{ name: "Bob", role: "user" }]
188
- // }
189
- ```
190
-
191
- ### Object Utilities
192
-
193
- ```tsx
194
- import { pick, omit, deepMerge } from '@foundrykit/utils';
195
-
196
- const user = {
197
- id: 1,
198
- name: 'John',
199
- email: 'john@example.com',
200
- password: 'secret',
201
- };
202
-
203
- // Pick specific keys
204
- pick(user, ['id', 'name']); // { id: 1, name: "John" }
205
-
206
- // Omit specific keys
207
- omit(user, ['password']); // { id: 1, name: "John", email: "john@example.com" }
208
-
209
- // Deep merge objects
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 }
213
- ```
214
-
215
- ## Advanced Usage
216
-
217
- ### Custom Class Name Logic
218
-
219
- ```tsx
220
- import { cn } from '@foundrykit/utils';
221
-
222
- function StatusBadge({ status, className }) {
223
- return (
224
- <span
225
- className={cn(
226
- 'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium',
227
- {
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',
231
- },
232
- className
233
- )}
234
- >
235
- {status}
236
- </span>
237
- );
238
- }
239
- ```
240
-
241
- ### Conditional Rendering with Classes
242
-
243
- ```tsx
244
- import { cn } from '@foundrykit/utils';
245
-
246
- function Card({ isActive, isDisabled, children, className }) {
247
- return (
248
- <div
249
- className={cn(
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',
254
- className
255
- )}
256
- >
257
- {children}
258
- </div>
259
- );
260
- }
261
- ```
262
-
263
- ## Performance Considerations
264
-
265
- ### Tree Shaking
266
-
267
- Import only what you need:
268
-
269
- ```tsx
270
- // Good - only imports cn
271
- import { cn } from '@foundrykit/utils';
272
-
273
- // Good - imports multiple utilities
274
- import { cn, cva, isValidEmail } from '@foundrykit/utils';
275
-
276
- // Avoid - imports everything
277
- import * as utils from '@foundrykit/utils';
278
- ```
279
-
280
- ### Memoization
281
-
282
- For expensive operations, consider memoization:
283
-
284
- ```tsx
285
- import { useMemo } from 'react';
286
- import { groupBy } from '@foundrykit/utils';
287
-
288
- function UserList({ users }) {
289
- const usersByRole = useMemo(() => groupBy(users, 'role'), [users]);
290
-
291
- return (
292
- <div>
293
- {Object.entries(usersByRole).map(([role, users]) => (
294
- <div key={role}>
295
- <h3>{role}</h3>
296
- {users.map(user => (
297
- <div key={user.id}>{user.name}</div>
298
- ))}
299
- </div>
300
- ))}
301
- </div>
302
- );
303
- }
304
- ```
305
-
306
- ## TypeScript Support
307
-
308
- All utilities include comprehensive TypeScript definitions:
309
-
310
- ```tsx
311
- import { cn, cva } from '@foundrykit/utils';
312
-
313
- // Type-safe class name utility
314
- const className: string = cn('base-class', true && 'conditional-class');
315
-
316
- // Type-safe variants
317
- const buttonVariants = cva('base', {
318
- variants: {
319
- size: {
320
- sm: 'text-sm',
321
- lg: 'text-lg',
322
- },
323
- },
324
- });
325
-
326
- // TypeScript knows the available variants
327
- const buttonClass = buttonVariants({ size: 'sm' }); // ✅ Valid
328
- const invalidClass = buttonVariants({ size: 'xl' }); // ❌ Type error
329
- ```
25
+ ## Available exports
330
26
 
331
- ## Contributing
27
+ - `cn` — merge class names with `clsx` and resolve conflicting Tailwind CSS
28
+ utilities via `tailwind-merge`.
332
29
 
333
- When adding new utilities:
30
+ ## Documentation
334
31
 
335
- 1. Ensure zero external dependencies
336
- 2. Add comprehensive TypeScript definitions
337
- 3. Include JSDoc documentation
338
- 4. Write unit tests
339
- 5. Follow existing naming conventions
340
- 6. Update this README
32
+ The export is documented with JSDoc in `src/index.ts`; hover in your editor for
33
+ the signature and usage notes.
341
34
 
342
35
  ## License
343
36
 
package/dist/index.d.ts CHANGED
@@ -1,5 +1,12 @@
1
1
  import { ClassValue } from 'clsx';
2
2
 
3
+ /**
4
+ * Merges class name inputs with `clsx` and resolves conflicting Tailwind CSS
5
+ * utilities with `tailwind-merge`, returning a single className string.
6
+ *
7
+ * @param inputs - Class values (strings, arrays, objects, conditionals).
8
+ * @returns The merged, conflict-resolved className string.
9
+ */
3
10
  declare function cn(...inputs: ClassValue[]): string;
4
11
 
5
12
  export { cn };
package/dist/index.js.map CHANGED
@@ -1 +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":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { type ClassValue, clsx } from 'clsx';\nimport { twMerge } from 'tailwind-merge';\n\n/**\n * Merges class name inputs with `clsx` and resolves conflicting Tailwind CSS\n * utilities with `tailwind-merge`, returning a single className string.\n *\n * @param inputs - Class values (strings, arrays, objects, conditionals).\n * @returns The merged, conflict-resolved className string.\n */\nexport function cn(...inputs: ClassValue[]) {\n return twMerge(clsx(inputs));\n}\n"],"mappings":";AAAA,SAA0B,YAAY;AACtC,SAAS,eAAe;AASjB,SAAS,MAAM,QAAsB;AAC1C,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B;","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@foundrykit/utils",
3
- "version": "1.0.5",
3
+ "version": "1.0.7",
4
4
  "type": "module",
5
5
  "private": false,
6
6
  "main": "./dist/index.js",
@@ -17,20 +17,23 @@
17
17
  },
18
18
  "dependencies": {
19
19
  "clsx": "^2.1.1",
20
- "tailwind-merge": "^3.3.1"
20
+ "tailwind-merge": "^3.3.1",
21
+ "@foundrykit/types": "2.0.7"
21
22
  },
22
23
  "devDependencies": {
23
24
  "@types/node": "^20.19.9",
24
- "eslint": "^9.0.0",
25
25
  "tsup": "^8.0.0",
26
26
  "typescript": "^5.9.2",
27
- "@foundrykit/eslint-config": "1.0.4",
28
- "@foundrykit/typescript-config": "1.0.4"
27
+ "@foundrykit/typescript-config": "1.0.6"
28
+ },
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/umi-labs/foundry.git",
32
+ "directory": "packages/utils"
29
33
  },
30
34
  "scripts": {
31
35
  "build": "tsup",
32
36
  "dev": "tsup --watch",
33
- "lint": "eslint . --max-warnings 0",
34
37
  "type-check": "tsc --noEmit"
35
38
  }
36
39
  }
package/src/config.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { ComponentConfig } from '@foundrykit/types';
1
+ import type { ComponentConfig } from '@foundrykit/types';
2
2
 
3
3
  export const utilsConfig: ComponentConfig = {
4
4
  name: 'Utils',
package/src/index.ts CHANGED
@@ -1,6 +1,13 @@
1
1
  import { type ClassValue, clsx } from 'clsx';
2
2
  import { twMerge } from 'tailwind-merge';
3
3
 
4
+ /**
5
+ * Merges class name inputs with `clsx` and resolves conflicting Tailwind CSS
6
+ * utilities with `tailwind-merge`, returning a single className string.
7
+ *
8
+ * @param inputs - Class values (strings, arrays, objects, conditionals).
9
+ * @returns The merged, conflict-resolved className string.
10
+ */
4
11
  export function cn(...inputs: ClassValue[]) {
5
12
  return twMerge(clsx(inputs));
6
13
  }
package/eslint.config.js DELETED
@@ -1,4 +0,0 @@
1
- import { baseConfig } from "@foundrykit/eslint-config/base"
2
-
3
- /** @type {import("eslint").Linter.Config} */
4
- export default baseConfig