@stacksjs/iconify-generator 0.1.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 ADDED
@@ -0,0 +1,98 @@
1
+ # @stacksjs/iconify-generator
2
+
3
+ Generator for creating Iconify icon packages for stx.
4
+
5
+ ## Installation
6
+
7
+ This package is typically used through the stx CLI and doesn't need to be installed separately.
8
+
9
+ ## Usage via stx CLI
10
+
11
+ ### List Available Icon Collections
12
+
13
+ ```bash
14
+ stx iconify list
15
+ ```
16
+
17
+ ### Generate a Complete Icon Collection
18
+
19
+ ```bash
20
+ stx iconify generate lucide
21
+ ```
22
+
23
+ ### Generate Specific Icons
24
+
25
+ ```bash
26
+ stx iconify generate lucide --icons home,settings,user,heart,star
27
+ ```
28
+
29
+ ### Custom Output Directory
30
+
31
+ ```bash
32
+ stx iconify generate mdi --output ./my-packages
33
+ ```
34
+
35
+ ## Direct Usage
36
+
37
+ You can also use the generator programmatically:
38
+
39
+ ```typescript
40
+ import { fetchCollections, generatePackage } from '@stacksjs/iconify-generator'
41
+
42
+ // List all available collections
43
+ const collections = await fetchCollections()
44
+ console.log(Object.keys(collections))
45
+
46
+ // Generate a package
47
+ await generatePackage(
48
+ 'lucide', // Collection prefix
49
+ './packages', // Output directory
50
+ ['home', 'settings', 'user'] // Optional: specific icons
51
+ )
52
+ ```
53
+
54
+ ## Generated Package Structure
55
+
56
+ Each generated package includes:
57
+
58
+ - `src/` - TypeScript source files for each icon
59
+ - `package.json` - Package configuration
60
+ - `build.ts` - Build script
61
+ - `README.md` - Usage documentation
62
+
63
+ ## Building Generated Packages
64
+
65
+ After generating a package:
66
+
67
+ ```bash
68
+ cd packages/iconify-{collection}
69
+ bun install
70
+ bun run build
71
+ ```
72
+
73
+ ## Features
74
+
75
+ - Fetches icon data from Iconify API
76
+ - Generates TypeScript icon components
77
+ - Creates fully typed packages
78
+ - Supports tree-shaking
79
+ - Customizable icon selection
80
+ - Automatic package.json and README generation
81
+
82
+ ## API
83
+
84
+ ### `fetchCollections(): Promise<Record<string, IconifyCollection>>`
85
+
86
+ Fetches all available icon collections from Iconify.
87
+
88
+ ### `fetchCollectionIcons(prefix: string, icons?: string[]): Promise<IconifyCollectionData>`
89
+
90
+ Fetches icons from a specific collection.
91
+
92
+ ### `generatePackage(prefix: string, outputDir: string, icons?: string[]): Promise<void>`
93
+
94
+ Generates a complete icon package.
95
+
96
+ ## License
97
+
98
+ MIT
package/package.json ADDED
@@ -0,0 +1,38 @@
1
+ {
2
+ "name": "@stacksjs/iconify-generator",
3
+ "type": "module",
4
+ "version": "0.1.6",
5
+ "description": "Generator for Iconify icon packages",
6
+ "author": "Chris Breuer <chris@stacksjs.org>",
7
+ "license": "MIT",
8
+ "keywords": [
9
+ "iconify",
10
+ "icons",
11
+ "generator",
12
+ "svg",
13
+ "stx"
14
+ ],
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.ts",
18
+ "import": "./dist/index.js"
19
+ }
20
+ },
21
+ "main": "./dist/index.js",
22
+ "module": "./dist/index.js",
23
+ "types": "./dist/index.d.ts",
24
+ "bin": {
25
+ "stx-iconify": "./dist/cli.js"
26
+ },
27
+ "files": [
28
+ "dist",
29
+ "src"
30
+ ],
31
+ "scripts": {
32
+ "build": "bun build.ts",
33
+ "dev": "bun build.ts --watch"
34
+ },
35
+ "dependencies": {
36
+ "@stacksjs/iconify-core": "0.0.1"
37
+ }
38
+ }
package/src/cli.ts ADDED
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env bun
2
+ import { join } from 'node:path'
3
+ import process from 'node:process'
4
+ import { fetchCollections, generatePackage } from './index'
5
+
6
+ const args = process.argv.slice(2)
7
+
8
+ async function main() {
9
+ if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
10
+ console.log(`
11
+ stx-iconify - Generate Iconify icon packages for stx
12
+
13
+ Usage:
14
+ stx-iconify <command> [options]
15
+
16
+ Commands:
17
+ list List all available icon collections
18
+ generate <prefix> Generate an icon package for a collection
19
+ generate <prefix> <icons...> Generate specific icons from a collection
20
+
21
+ Options:
22
+ --output, -o <dir> Output directory for packages (default: ./packages)
23
+ --docs, -d <dir> Generate documentation in specified directory
24
+ --help, -h Show this help message
25
+
26
+ Examples:
27
+ stx-iconify list
28
+ stx-iconify generate mdi
29
+ stx-iconify generate lucide home settings user
30
+ stx-iconify generate tabler --output ./packages
31
+ stx-iconify generate lucide --docs ./docs/collections
32
+ stx-iconify generate mdi --output ./packages --docs ./docs/collections
33
+ `)
34
+ process.exit(0)
35
+ }
36
+
37
+ const command = args[0]
38
+
39
+ if (command === 'list') {
40
+ console.log('\nšŸ“š Fetching available icon collections...\n')
41
+ const collections = await fetchCollections()
42
+
43
+ const sortedCollections = Object.entries(collections)
44
+ .sort((a, b) => b[1].total - a[1].total)
45
+
46
+ console.log('Available collections:\n')
47
+ for (const [prefix, info] of sortedCollections) {
48
+ console.log(` ${prefix.padEnd(30)} ${info.name} (${info.total} icons)`)
49
+ }
50
+ console.log(`\nTotal: ${sortedCollections.length} collections`)
51
+ }
52
+ else if (command === 'generate') {
53
+ const prefix = args[1]
54
+ if (!prefix) {
55
+ console.error('Error: Please specify a collection prefix')
56
+ console.error('Usage: stx-iconify generate <prefix> [icons...]')
57
+ process.exit(1)
58
+ }
59
+
60
+ let outputDir = join(process.cwd(), 'packages')
61
+ let docsDir: string | undefined
62
+ const icons: string[] = []
63
+
64
+ // Parse remaining args
65
+ for (let i = 2; i < args.length; i++) {
66
+ if (args[i] === '--output' || args[i] === '-o') {
67
+ outputDir = args[i + 1]
68
+ i++
69
+ }
70
+ else if (args[i] === '--docs' || args[i] === '-d') {
71
+ docsDir = args[i + 1]
72
+ i++
73
+ }
74
+ else if (!args[i].startsWith('--') && !args[i].startsWith('-')) {
75
+ icons.push(args[i])
76
+ }
77
+ }
78
+
79
+ await generatePackage(prefix, outputDir, icons.length > 0 ? icons : undefined, docsDir)
80
+ console.log('\nāœ“ Package generated successfully!')
81
+ console.log(`\nTo use the package:`)
82
+ console.log(` 1. cd packages/iconify-${prefix}`)
83
+ console.log(` 2. bun install`)
84
+ console.log(` 3. bun run build`)
85
+ }
86
+ else {
87
+ console.error(`Unknown command: ${command}`)
88
+ console.error('Run "stx-iconify --help" for usage information')
89
+ process.exit(1)
90
+ }
91
+ }
92
+
93
+ main().catch((error) => {
94
+ console.error('Error:', error.message)
95
+ process.exit(1)
96
+ })
package/src/index.ts ADDED
@@ -0,0 +1,823 @@
1
+ /* eslint-disable no-console */
2
+ import type { IconData } from '@stacksjs/iconify-core'
3
+ import { mkdir, writeFile } from 'node:fs/promises'
4
+ import { join } from 'node:path'
5
+
6
+ export interface IconifyCollection {
7
+ prefix: string
8
+ name: string
9
+ total: number
10
+ author?: {
11
+ name: string
12
+ url?: string
13
+ }
14
+ license?: {
15
+ title: string
16
+ spdx: string
17
+ url?: string
18
+ }
19
+ height?: number
20
+ category?: string
21
+ palette?: boolean
22
+ }
23
+
24
+ export interface IconifyIconData {
25
+ body: string
26
+ width?: number
27
+ height?: number
28
+ left?: number
29
+ top?: number
30
+ rotate?: number
31
+ hFlip?: boolean
32
+ vFlip?: boolean
33
+ }
34
+
35
+ export interface IconifyCollectionData {
36
+ prefix: string
37
+ lastModified: number
38
+ icons: Record<string, IconifyIconData>
39
+ aliases?: Record<string, {
40
+ parent: string
41
+ hFlip?: boolean
42
+ vFlip?: boolean
43
+ rotate?: number
44
+ }>
45
+ width?: number
46
+ height?: number
47
+ }
48
+
49
+ const ICONIFY_API = 'https://api.iconify.design'
50
+
51
+ /**
52
+ * Fetch available icon collections from Iconify
53
+ */
54
+ export async function fetchCollections(): Promise<Record<string, IconifyCollection>> {
55
+ const response = await fetch(`${ICONIFY_API}/collections`)
56
+ if (!response.ok) {
57
+ throw new Error(`Failed to fetch collections: ${response.statusText}`)
58
+ }
59
+ return await response.json()
60
+ }
61
+
62
+ /**
63
+ * Fetch icons from a specific collection
64
+ */
65
+ export async function fetchCollectionIcons(
66
+ prefix: string,
67
+ icons?: string[],
68
+ ): Promise<IconifyCollectionData> {
69
+ // Try to load from @iconify/json package first
70
+ try {
71
+ const iconifyJsonPath = require.resolve('@iconify/json')
72
+ // The resolve gives us the main module path, get the package directory
73
+ const basePath = `${iconifyJsonPath.substring(0, iconifyJsonPath.lastIndexOf('/node_modules/@iconify/json/'))}/node_modules/@iconify/json`
74
+ const jsonPath = `${basePath}/json/${prefix}.json`
75
+
76
+ const file = Bun.file(jsonPath)
77
+ if (await file.exists()) {
78
+ const data: IconifyCollectionData = await file.json()
79
+
80
+ // If specific icons are requested, filter them
81
+ if (icons && icons.length > 0) {
82
+ const filteredIcons: Record<string, IconifyIconData> = {}
83
+ for (const iconName of icons) {
84
+ if (data.icons[iconName]) {
85
+ filteredIcons[iconName] = data.icons[iconName]
86
+ }
87
+ }
88
+ return {
89
+ ...data,
90
+ icons: filteredIcons,
91
+ }
92
+ }
93
+
94
+ return data
95
+ }
96
+ }
97
+ catch {
98
+ // Fall through to API if local file not found
99
+ }
100
+
101
+ // Fallback to API (only works for specific icons, not full collections)
102
+ const url = icons && icons.length > 0
103
+ ? `${ICONIFY_API}/${prefix}.json?icons=${icons.join(',')}`
104
+ : `${ICONIFY_API}/${prefix}.json`
105
+
106
+ const response = await fetch(url)
107
+ if (!response.ok) {
108
+ throw new Error(`Failed to fetch icons for ${prefix}: ${response.statusText}`)
109
+ }
110
+ return await response.json()
111
+ }
112
+
113
+ /**
114
+ * Convert Iconify icon data to our IconData format
115
+ */
116
+ export function convertIconData(data: IconifyIconData, defaultWidth = 24, defaultHeight = 24): IconData {
117
+ return {
118
+ body: data.body,
119
+ width: data.width || defaultWidth,
120
+ height: data.height || defaultHeight,
121
+ viewBox: `0 0 ${data.width || defaultWidth} ${data.height || defaultHeight}`,
122
+ }
123
+ }
124
+
125
+ /**
126
+ * Generate TypeScript icon data file
127
+ */
128
+ export function generateIconData(
129
+ name: string,
130
+ iconData: IconData,
131
+ ): string {
132
+ const camelCaseName = toCamelCase(name)
133
+
134
+ return `import type { IconData } from '@stacksjs/iconify-core'
135
+
136
+ export const ${camelCaseName}: IconData = ${JSON.stringify(iconData, null, 2)}
137
+
138
+ export default ${camelCaseName}
139
+ `
140
+ }
141
+
142
+ /**
143
+ * Generate stx icon component file
144
+ */
145
+ export function generateIconComponent(
146
+ _name: string,
147
+ iconData: IconData,
148
+ ): string {
149
+ return `<script>
150
+ // Get props with defaults (handle undefined)
151
+ const iconWidth = (typeof width !== 'undefined' ? width : null) || (typeof size !== 'undefined' ? size : null) || ${iconData.width || 24}
152
+ const iconHeight = (typeof height !== 'undefined' ? height : null) || (typeof size !== 'undefined' ? size : null) || ${iconData.height || 24}
153
+ const iconColor = typeof color !== 'undefined' ? color : 'currentColor'
154
+ const viewBox = "${iconData.viewBox || `0 0 ${iconData.width || 24} ${iconData.height || 24}`}"
155
+
156
+ // Build transform
157
+ const transforms = []
158
+ if (typeof hFlip !== 'undefined' && hFlip) transforms.push('scaleX(-1)')
159
+ if (typeof vFlip !== 'undefined' && vFlip) transforms.push('scaleY(-1)')
160
+ if (typeof rotate !== 'undefined' && rotate) {
161
+ const rotateNum = typeof rotate === 'string' ? parseInt(rotate, 10) : rotate
162
+ const deg = typeof rotateNum === 'number' && rotateNum < 4 ? rotateNum * 90 : rotateNum
163
+ transforms.push(\`rotate(\${deg}deg)\`)
164
+ }
165
+
166
+ const transform = transforms.length > 0 ? transforms.join(' ') : ''
167
+ const transformStyle = transform ? \`transform: \${transform};\` : ''
168
+
169
+ // Build style
170
+ const styles = []
171
+ if (transformStyle) styles.push(transformStyle)
172
+ if (typeof style !== 'undefined' && style) styles.push(style)
173
+
174
+ const styleAttr = styles.length > 0 ? \` style="\${styles.join(' ')}"\` : ''
175
+ const classAttr = typeof className !== 'undefined' && className ? \` class="\${className}"\` : ''
176
+
177
+ // Icon body
178
+ let body = ${JSON.stringify(iconData.body)}
179
+ if (iconColor && iconColor !== 'currentColor') {
180
+ body = body.replace(/currentColor/g, iconColor)
181
+ }
182
+
183
+ // Generate SVG
184
+ const svg = \`<svg xmlns="http://www.w3.org/2000/svg" width="\${iconWidth}" height="\${iconHeight}" viewBox="\${viewBox}"\${classAttr}\${styleAttr}>\${body}</svg>\`
185
+ </script>
186
+
187
+ {!! svg !!}
188
+ `
189
+ }
190
+
191
+ /**
192
+ * Generate index file for a collection
193
+ */
194
+ export function generateIndexFile(iconNames: string[]): string {
195
+ const dataExports = iconNames.map((name) => {
196
+ const camelCaseName = toCamelCase(name)
197
+ return `export { default as ${camelCaseName} } from './${name}.js'`
198
+ }).join('\n')
199
+
200
+ return `// Icon data exports
201
+ ${dataExports}
202
+
203
+ export * from './types.js'
204
+ `
205
+ }
206
+
207
+ /**
208
+ * Generate types file
209
+ */
210
+ export function generateTypesFile(prefix: string): string {
211
+ return `import type { IconData, IconProps } from '@stacksjs/iconify-core'
212
+
213
+ export type { IconData, IconProps }
214
+
215
+ export type ${toPascalCase(prefix)}Icon = IconData
216
+ `
217
+ }
218
+
219
+ /**
220
+ * Generate package.json for a collection
221
+ */
222
+ export function generatePackageJson(
223
+ prefix: string,
224
+ collectionInfo: IconifyCollection,
225
+ _iconCount: number,
226
+ ): string {
227
+ const packageJson = {
228
+ name: `@stacksjs/iconify-${prefix}`,
229
+ type: 'module',
230
+ version: '0.0.1',
231
+ description: `${collectionInfo.name} icons for stx from Iconify`,
232
+ author: collectionInfo.author?.name || 'Iconify',
233
+ license: collectionInfo.license?.spdx || 'MIT',
234
+ repository: {
235
+ type: 'git',
236
+ url: 'https://github.com/stacksjs/stx.git',
237
+ directory: `packages/iconify-${prefix}`,
238
+ },
239
+ keywords: [
240
+ 'iconify',
241
+ 'icons',
242
+ 'svg',
243
+ prefix,
244
+ collectionInfo.name,
245
+ 'stx',
246
+ ],
247
+ sideEffects: false,
248
+ exports: {
249
+ '.': {
250
+ types: './dist/index.d.ts',
251
+ import: './dist/index.js',
252
+ },
253
+ './*': './dist/*',
254
+ },
255
+ main: './dist/index.js',
256
+ module: './dist/index.js',
257
+ types: './dist/index.d.ts',
258
+ files: [
259
+ 'dist',
260
+ ],
261
+ scripts: {
262
+ build: 'bun build.ts',
263
+ },
264
+ dependencies: {
265
+ '@stacksjs/iconify-core': 'workspace:*',
266
+ },
267
+ }
268
+
269
+ return JSON.stringify(packageJson, null, 2)
270
+ }
271
+
272
+ /**
273
+ * Generate build.ts file for a collection
274
+ */
275
+ export function generateBuildFile(prefix: string): string {
276
+ return `import { join, dirname } from 'node:path'
277
+ import { fileURLToPath } from 'node:url'
278
+ import dts from 'bun-plugin-dtsx'
279
+
280
+ const __dirname = dirname(fileURLToPath(import.meta.url))
281
+
282
+ await Bun.build({
283
+ entrypoints: [join(__dirname, 'src/index.ts')],
284
+ outdir: join(__dirname, 'dist'),
285
+ target: 'bun',
286
+ format: 'esm',
287
+ plugins: [dts()],
288
+ minify: false,
289
+ sourcemap: 'external',
290
+ splitting: true,
291
+ })
292
+
293
+ console.log('āœ“ Built @stacksjs/iconify-${prefix}')
294
+ `
295
+ }
296
+
297
+ /**
298
+ * Generate README for a collection
299
+ */
300
+ export function generateReadme(
301
+ prefix: string,
302
+ collectionInfo: IconifyCollection,
303
+ iconCount: number,
304
+ ): string {
305
+ return `# @stacksjs/iconify-${prefix}
306
+
307
+ ${collectionInfo.name} icons for stx from Iconify.
308
+
309
+ ## Installation
310
+
311
+ \`\`\`bash
312
+ bun add @stacksjs/iconify-${prefix}
313
+ \`\`\`
314
+
315
+ ## Usage
316
+
317
+ ### In stx templates
318
+
319
+ \`\`\`html
320
+ <script>
321
+ import { home } from '@stacksjs/iconify-${prefix}'
322
+ import { renderIcon } from '@stacksjs/iconify-core'
323
+
324
+ export const homeIcon = renderIcon(home, { size: 24, color: 'currentColor' })
325
+ </script>
326
+
327
+ <div class="icon">
328
+ {!! homeIcon !!}
329
+ </div>
330
+ \`\`\`
331
+
332
+ ### In TypeScript/JavaScript
333
+
334
+ \`\`\`typescript
335
+ import { home, account, settings } from '@stacksjs/iconify-${prefix}'
336
+ import { renderIcon } from '@stacksjs/iconify-core'
337
+
338
+ const svg = renderIcon(home, {
339
+ size: 24,
340
+ color: '#000000',
341
+ })
342
+ \`\`\`
343
+
344
+ ## Available Icons
345
+
346
+ This package contains ${iconCount} icons from ${collectionInfo.name}.
347
+
348
+ ## License
349
+
350
+ ${collectionInfo.license?.title || 'MIT'}
351
+
352
+ ${collectionInfo.license?.url ? `License: ${collectionInfo.license.url}` : ''}
353
+
354
+ ## Credits
355
+
356
+ - Icons: ${collectionInfo.author?.name || 'Iconify'}${collectionInfo.author?.url ? ` (${collectionInfo.author.url})` : ''}
357
+ - Iconify: https://iconify.design/
358
+ `
359
+ }
360
+
361
+ /**
362
+ * Generate documentation file for a collection
363
+ */
364
+ export function generateDocumentation(
365
+ prefix: string,
366
+ collectionInfo: IconifyCollection,
367
+ iconNames: string[],
368
+ ): string {
369
+ const iconCount = iconNames.length
370
+ const exampleIcons = iconNames.slice(0, 5).map(toCamelCase)
371
+ const exampleComponents = exampleIcons.map(name => `${name.charAt(0).toUpperCase()}${name.slice(1)}Icon`)
372
+
373
+ // Generate full icon list
374
+ const allIconsList = iconNames.map((name) => {
375
+ const camelName = toCamelCase(name)
376
+ return `- \`${camelName}\``
377
+ }).join('\n')
378
+
379
+ return `# ${collectionInfo.name}
380
+
381
+ > ${collectionInfo.name} icons for stx from Iconify
382
+
383
+ ## Overview
384
+
385
+ This package provides access to ${iconCount} icons from the ${collectionInfo.name} collection through the stx iconify integration.
386
+
387
+ **Collection ID:** \`${prefix}\`
388
+ **Total Icons:** ${iconCount}
389
+ ${collectionInfo.author?.name ? `**Author:** ${collectionInfo.author.name}${collectionInfo.author.url ? ` ([Website](${collectionInfo.author.url}))` : ''}` : ''}
390
+ ${collectionInfo.license?.title ? `**License:** ${collectionInfo.license.title}${collectionInfo.license.url ? ` ([Details](${collectionInfo.license.url}))` : ''}` : ''}
391
+ ${collectionInfo.category ? `**Category:** ${collectionInfo.category}` : ''}
392
+ ${collectionInfo.palette !== undefined ? `**Palette:** ${collectionInfo.palette ? 'Yes (color icons)' : 'No (monotone icons)'}` : ''}
393
+
394
+ ## Installation
395
+
396
+ \`\`\`bash
397
+ bun add @stacksjs/iconify-${prefix}
398
+ \`\`\`
399
+
400
+ ## Quick Start
401
+
402
+ ### Component Usage (Recommended)
403
+
404
+ Icons are available as .stx components that can be used directly in templates:
405
+
406
+ \`\`\`html
407
+ <${exampleComponents[0] || 'Icon'} height="1em" />
408
+ <${exampleComponents[0] || 'Icon'} width="1em" height="1em" />
409
+ <${exampleComponents[0] || 'Icon'} height="24" />
410
+ \`\`\`
411
+
412
+ ### With Properties
413
+
414
+ \`\`\`html
415
+ <!-- Using size property -->
416
+ <${exampleComponents[0] || 'Icon'} size="24" />
417
+ <${exampleComponents[0] || 'Icon'} size="1em" />
418
+
419
+ <!-- Using width and height -->
420
+ <${exampleComponents[0] || 'Icon'} width="24" height="32" />
421
+
422
+ <!-- With color -->
423
+ <${exampleComponents[0] || 'Icon'} size="24" color="red" />
424
+ <${exampleComponents[0] || 'Icon'} size="24" color="#4a90e2" />
425
+
426
+ <!-- With CSS class -->
427
+ <${exampleComponents[0] || 'Icon'} size="24" class="icon-primary" />
428
+
429
+ <!-- With all properties -->
430
+ <${exampleComponents[0] || 'Icon'}
431
+ size="32"
432
+ color="#4a90e2"
433
+ class="my-icon"
434
+ style="opacity: 0.8;"
435
+ />
436
+ \`\`\`
437
+
438
+ ### In stx Templates
439
+
440
+ \`\`\`html
441
+ <!DOCTYPE html>
442
+ <html>
443
+ <head>
444
+ <title>Icon Demo</title>
445
+ <style>
446
+ .icon-grid {
447
+ display: flex;
448
+ gap: 1rem;
449
+ align-items: center;
450
+ }
451
+ </style>
452
+ </head>
453
+ <body>
454
+ <div class="icon-grid">
455
+ <${exampleComponents[0] || 'Icon'} size="24" />
456
+ <${exampleComponents[1] || 'Icon'} size="24" color="#4a90e2" />
457
+ <${exampleComponents[2] || 'Icon'} size="32" class="my-icon" />
458
+ </div>
459
+ </body>
460
+ </html>
461
+ \`\`\`
462
+
463
+ ### Data-Only Import
464
+
465
+ You can also import icon data and use the \`renderIcon\` function directly:
466
+
467
+ \`\`\`typescript
468
+ import { ${exampleIcons.slice(0, 3).join(', ')} } from '@stacksjs/iconify-${prefix}'
469
+ import { renderIcon } from '@stacksjs/iconify-core'
470
+
471
+ const svg = renderIcon(${exampleIcons[0] || 'icon'}, { size: 24 })
472
+ \`\`\`
473
+
474
+ ## Icon Properties
475
+
476
+ All icon component functions and \`renderIcon\` accept the following properties:
477
+
478
+ | Property | Type | Default | Description |
479
+ |----------|------|---------|-------------|
480
+ | \`size\` | \`string \\| number\` | - | Icon size (sets both width and height) |
481
+ | \`width\` | \`string \\| number\` | - | Icon width (overrides size) |
482
+ | \`height\` | \`string \\| number\` | - | Icon height (overrides size) |
483
+ | \`color\` | \`string\` | \`'currentColor'\` | Icon color (CSS color or hex) |
484
+ | \`hFlip\` | \`boolean\` | \`false\` | Flip horizontally |
485
+ | \`vFlip\` | \`boolean\` | \`false\` | Flip vertically |
486
+ | \`rotate\` | \`0 \\| 90 \\| 180 \\| 270\` | \`0\` | Rotation in degrees |
487
+ | \`class\` | \`string\` | - | Additional CSS classes |
488
+ | \`style\` | \`string\` | - | Inline styles |
489
+
490
+ ## Color
491
+
492
+ ${collectionInfo.palette ? '### Color Icons\n\nThis collection contains color icons. While you can still set a color property, it may override the original colors.' : '### Monotone Icons\n\nMonotone icons use \`currentColor\` by default, allowing you to change icon color via the \`color\` property or CSS:'}
493
+
494
+ \`\`\`html
495
+ <!-- Via color property -->
496
+ <${exampleComponents[0] || 'Icon'} size="24" color="red" />
497
+ <${exampleComponents[0] || 'Icon'} size="24" color="#4a90e2" />
498
+
499
+ <!-- Via inline style -->
500
+ <${exampleComponents[0] || 'Icon'} size="24" style="color: green;" />
501
+
502
+ <!-- Via CSS class -->
503
+ <${exampleComponents[0] || 'Icon'} size="24" class="text-primary" />
504
+ \`\`\`
505
+
506
+ ${!collectionInfo.palette
507
+ ? `\`\`\`css
508
+ /* In your CSS */
509
+ .text-primary {
510
+ color: #4a90e2;
511
+ }
512
+
513
+ .icon:hover {
514
+ color: #357abd;
515
+ }
516
+ \`\`\``
517
+ : ''}
518
+
519
+ ## Size
520
+
521
+ Unlike other components, SVG + CSS components do not set icon size by default. This has advantages and disadvantages.
522
+
523
+ **Disadvantages:**
524
+ - You need to set size yourself.
525
+
526
+ **Advantages:**
527
+ - You have full control over icon size.
528
+
529
+ You can change icon size by:
530
+ - Setting \`width\` and \`height\` properties
531
+ - Using CSS
532
+
533
+ ### Properties
534
+
535
+ All icon components support \`width\` and \`height\` properties.
536
+
537
+ Value is a string or number.
538
+
539
+ You do not need to set both properties. If you set one property, the other property will automatically be calculated from the icon's width/height ratio.
540
+
541
+ **Examples:**
542
+
543
+ \`\`\`html
544
+ <${exampleComponents[0] || 'DraftsIcon'} height="1em" />
545
+ <${exampleComponents[0] || 'DraftsIcon'} width="1em" height="1em" />
546
+ <${exampleComponents[0] || 'DraftsIcon'} height="24" />
547
+ \`\`\`
548
+
549
+ You can also use the \`size\` property as a shorthand for setting both width and height:
550
+
551
+ \`\`\`html
552
+ <${exampleComponents[0] || 'DraftsIcon'} size="24" />
553
+ <${exampleComponents[0] || 'DraftsIcon'} size="1em" />
554
+ \`\`\`
555
+
556
+ ### CSS Sizing
557
+
558
+ You can also control icon size via CSS:
559
+
560
+ \`\`\`css
561
+ .${toCamelCase(prefix)}-icon {
562
+ width: 1em;
563
+ height: 1em;
564
+ }
565
+ \`\`\`
566
+
567
+ \`\`\`html
568
+ <${exampleComponents[0] || 'DraftsIcon'} class="${toCamelCase(prefix)}-icon" />
569
+ \`\`\`
570
+
571
+ ## Available Icons
572
+
573
+ This package contains **${iconCount}** icons:
574
+
575
+ ${allIconsList}
576
+
577
+ ## Usage Examples
578
+
579
+ ### Navigation Menu
580
+
581
+ \`\`\`html
582
+ <nav>
583
+ <a href="/"><${exampleComponents[0] || 'Icon'} size="20" class="nav-icon" /> Home</a>
584
+ <a href="/about"><${exampleComponents[1] || 'Icon'} size="20" class="nav-icon" /> About</a>
585
+ <a href="/contact"><${exampleComponents[2] || 'Icon'} size="20" class="nav-icon" /> Contact</a>
586
+ <a href="/settings"><${exampleComponents[3] || 'Icon'} size="20" class="nav-icon" /> Settings</a>
587
+ </nav>
588
+
589
+ <style>
590
+ nav {
591
+ display: flex;
592
+ gap: 1rem;
593
+ }
594
+ nav a {
595
+ display: flex;
596
+ align-items: center;
597
+ gap: 0.5rem;
598
+ }
599
+ .nav-icon {
600
+ color: currentColor;
601
+ }
602
+ </style>
603
+ \`\`\`
604
+
605
+ ### Custom Styling
606
+
607
+ \`\`\`html
608
+ <${exampleComponents[0] || 'Icon'}
609
+ size="24"
610
+ class="icon icon-primary"
611
+ style="opacity: 0.8; transition: opacity 0.2s;"
612
+ />
613
+
614
+ <style>
615
+ .icon-primary {
616
+ color: #4a90e2;
617
+ }
618
+ .icon-primary:hover {
619
+ opacity: 1;
620
+ }
621
+ </style>
622
+ \`\`\`
623
+
624
+ ### Status Indicators
625
+
626
+ \`\`\`html
627
+ <div class="status-grid">
628
+ <div class="status-item">
629
+ <${exampleComponents[0] || 'Icon'} size="16" color="#22c55e" />
630
+ <span>Success</span>
631
+ </div>
632
+ <div class="status-item">
633
+ <${exampleComponents[1] || 'Icon'} size="16" color="#f59e0b" />
634
+ <span>Warning</span>
635
+ </div>
636
+ <div class="status-item">
637
+ <${exampleComponents[2] || 'Icon'} size="16" color="#ef4444" />
638
+ <span>Error</span>
639
+ </div>
640
+ </div>
641
+ \`\`\`
642
+
643
+ ## Best Practices
644
+
645
+ 1. **Use Components Directly**: Import and use icon components in your templates
646
+ \`\`\`html
647
+ <!-- Recommended -->
648
+ <${exampleComponents[0] || 'Icon'} size="24" />
649
+ <${exampleComponents[1] || 'Icon'} size="24" color="#4a90e2" />
650
+ \`\`\`
651
+
652
+ 2. **Use CSS for Theming**: Apply consistent styling through CSS classes
653
+ \`\`\`css
654
+ .icon {
655
+ color: currentColor;
656
+ opacity: 0.8;
657
+ transition: opacity 0.2s;
658
+ }
659
+
660
+ .icon:hover {
661
+ opacity: 1;
662
+ }
663
+ \`\`\`
664
+
665
+ \`\`\`html
666
+ <${exampleComponents[0] || 'Icon'} size="24" class="icon" />
667
+ \`\`\`
668
+
669
+ 3. **Set Appropriate Sizes**: Use \`1em\` for inline icons, fixed pixel sizes for standalone icons
670
+ \`\`\`html
671
+ <!-- Inline with text -->
672
+ <p>Click the <${exampleComponents[0] || 'Icon'} height="1em" /> icon to continue</p>
673
+
674
+ <!-- Standalone -->
675
+ <${exampleComponents[0] || 'Icon'} size="24" />
676
+ \`\`\`
677
+
678
+ 4. **Use Data Import for Advanced Use Cases**: When you need more control
679
+ \`\`\`html
680
+ @js
681
+ import { ${exampleIcons[0] || 'icon'} } from '@stacksjs/iconify-${prefix}'
682
+ import { renderIcon } from '@stacksjs/iconify-core'
683
+ global.customIcon = renderIcon(${exampleIcons[0] || 'icon'}, { size: 24 })
684
+ @endjs
685
+
686
+ {!! customIcon !!}
687
+ \`\`\`
688
+
689
+ ## TypeScript Support
690
+
691
+ This package includes full TypeScript support with type definitions for all icons.
692
+
693
+ \`\`\`typescript
694
+ import type { IconData } from '@stacksjs/iconify-core'
695
+ import { ${exampleIcons[0] || 'icon'} } from '@stacksjs/iconify-${prefix}'
696
+
697
+ // Icons are typed as IconData
698
+ const myIcon: IconData = ${exampleIcons[0] || 'icon'}
699
+ \`\`\`
700
+
701
+ ## Related Packages
702
+
703
+ - [\`@stacksjs/iconify-core\`](../iconify#installation) - Core rendering functions and utilities
704
+ - [Iconify Integration Guide](../iconify) - Complete guide to using Iconify with stx
705
+ - [stx Documentation](../) - Main stx documentation
706
+
707
+ ## License
708
+
709
+ ${collectionInfo.license?.title || 'MIT'}
710
+
711
+ ${collectionInfo.license?.url ? `See [license details](${collectionInfo.license.url}) for more information.` : ''}
712
+
713
+ ## Credits
714
+
715
+ - **Icons**: ${collectionInfo.author?.name || 'Iconify'}${collectionInfo.author?.url ? ` ([Website](${collectionInfo.author.url}))` : ''}
716
+ - **Iconify**: [https://iconify.design/](https://iconify.design/)
717
+ - **Icon Set**: [View on Iconify](https://icon-sets.iconify.design/${prefix}/)
718
+
719
+ ## Resources
720
+
721
+ - [Browse all icons in this collection](https://icon-sets.iconify.design/${prefix}/)
722
+ - [Iconify documentation](https://iconify.design/docs/)
723
+ - [stx iconify integration guide](../../docs/iconify.md)
724
+ `
725
+ }
726
+
727
+ /**
728
+ * Generate a complete icon package
729
+ */
730
+ export async function generatePackage(
731
+ prefix: string,
732
+ outputDir: string,
733
+ icons?: string[],
734
+ docsDir?: string,
735
+ ): Promise<void> {
736
+ console.log(`\nšŸ“¦ Generating package for ${prefix}...`)
737
+
738
+ // Fetch collection info
739
+ const collections = await fetchCollections()
740
+ const collectionInfo = collections[prefix]
741
+
742
+ if (!collectionInfo) {
743
+ throw new Error(`Collection ${prefix} not found`)
744
+ }
745
+
746
+ console.log(` Collection: ${collectionInfo.name}`)
747
+ console.log(` Total icons: ${collectionInfo.total}`)
748
+
749
+ // Fetch icons
750
+ const collectionData = await fetchCollectionIcons(prefix, icons)
751
+ const iconNames = Object.keys(collectionData.icons)
752
+
753
+ console.log(` Generating ${iconNames.length} icons...`)
754
+
755
+ // Create package directory structure
756
+ const packageDir = join(outputDir, `iconify-${prefix}`)
757
+ const srcDir = join(packageDir, 'src')
758
+
759
+ await mkdir(srcDir, { recursive: true })
760
+
761
+ // Generate icon files
762
+ const defaultWidth = collectionData.width || 24
763
+ const defaultHeight = collectionData.height || 24
764
+
765
+ for (const iconName of iconNames) {
766
+ const iconData = collectionData.icons[iconName]
767
+ const converted = convertIconData(iconData, defaultWidth, defaultHeight)
768
+
769
+ // Generate data file (.ts)
770
+ const dataFile = generateIconData(iconName, converted)
771
+ await writeFile(join(srcDir, `${iconName}.ts`), dataFile)
772
+
773
+ // Generate component file (.stx) with -icon suffix for PascalCase component names
774
+ const componentFile = generateIconComponent(iconName, converted)
775
+ await writeFile(join(srcDir, `${iconName}-icon.stx`), componentFile)
776
+ }
777
+
778
+ // Generate index file
779
+ const indexContent = generateIndexFile(iconNames)
780
+ await writeFile(join(srcDir, 'index.ts'), indexContent)
781
+
782
+ // Generate types file
783
+ const typesContent = generateTypesFile(prefix)
784
+ await writeFile(join(srcDir, 'types.ts'), typesContent)
785
+
786
+ // Generate package.json
787
+ const packageJsonContent = generatePackageJson(prefix, collectionInfo, iconNames.length)
788
+ await writeFile(join(packageDir, 'package.json'), packageJsonContent)
789
+
790
+ // Generate build file
791
+ const buildContent = generateBuildFile(prefix)
792
+ await writeFile(join(packageDir, 'build.ts'), buildContent)
793
+
794
+ // Generate README
795
+ const readmeContent = generateReadme(prefix, collectionInfo, iconNames.length)
796
+ await writeFile(join(packageDir, 'README.md'), readmeContent)
797
+
798
+ // Generate documentation if docsDir is provided
799
+ if (docsDir) {
800
+ const docsPath = join(docsDir, `iconify-${prefix}.md`)
801
+ const docContent = generateDocumentation(prefix, collectionInfo, iconNames)
802
+ await mkdir(docsDir, { recursive: true })
803
+ await writeFile(docsPath, docContent)
804
+ console.log(` āœ“ Generated documentation in ${docsPath}`)
805
+ }
806
+
807
+ console.log(` āœ“ Generated ${iconNames.length} icons in ${packageDir}`)
808
+ }
809
+
810
+ /**
811
+ * Convert kebab-case to camelCase
812
+ */
813
+ export function toCamelCase(str: string): string {
814
+ return str.replace(/-([a-z0-9])/g, g => g[1].toUpperCase())
815
+ }
816
+
817
+ /**
818
+ * Convert kebab-case to PascalCase
819
+ */
820
+ export function toPascalCase(str: string): string {
821
+ const camel = toCamelCase(str)
822
+ return camel.charAt(0).toUpperCase() + camel.slice(1)
823
+ }