fusee-framework 1.7.0 → 1.9.0

package/framework/core/compiler/plugins/compiler-plugin.js

@@ -0,0 +1,45 @@
+import { compile } from '../main-compiler.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IMPORT_RE = /^import\s+(?:\{[^}]*\}|[\w$]+)\s+from\s+['"]([^'"]+\.template\.html)['"]\s*;?/gm;
+
+export function fuseeCompilerPlugin() {
+    return {
+        name: 'vite-plugin-fusee-compiler',
+        enforce: 'pre',
+
+        transform(code, id) {
+            if (!id.endsWith('.js') && !id.endsWith('.ts')) 
+                return null;
+            if (!IMPORT_RE.test(code)) 
+                return null;
+
+            IMPORT_RE.lastIndex = 0;
+
+            let result = code;
+            let match;
+
+            while ((match = IMPORT_RE.exec(code)) !== null) {
+                const [fullImport, templatePath] = match;
+                const absPath = path.resolve(path.dirname(id), templatePath);
+                const source = fs.readFileSync(absPath, 'utf-8');
+                const { code: compiledCode } = compile(source, {
+                    runtimePath: 'fusee-framework/core/h.js'
+                });
+
+                const namedMatch = fullImport.match(/\{\s*render\s+as\s+([\w$]+)\s*\}/);
+                const defaultMatch = fullImport.match(/import\s+([\w$]+)\s+from/);
+                const localName = namedMatch ? namedMatch[1] : (defaultMatch ? defaultMatch[1] : 'render');
+                const inlined = compiledCode.replace(
+                    'export function render(',
+                    `function ${localName}(`
+                );
+
+                result = result.replace(fullImport, inlined);
+            }
+
+            return { code: result, map: null };
+        }
+    };
+}

package/framework/core/compiler/plugins/file-router-plugin.js

@@ -0,0 +1,301 @@
+import path from 'node:path'
+
+export function fileRouterPlugin(options = {}) {
+    const {
+        pagesDir = 'src/pages',
+        loadingComponent = null,
+    } = options
+
+    return {
+        name: 'vite-plugin-fusee-file-router',
+        async buildStart() { },
+
+        resolveId(id) {
+            if (id === 'virtual:fusee-routes') return '\0virtual:fusee-routes'
+        },
+
+        async load(id) {
+            if (id !== '\0virtual:fusee-routes') return null
+
+            const { globSync } = await import('fast-glob')
+            const files = globSync(`${pagesDir}/**/*.{js,ts,jsx,tsx}`, {
+                cwd: process.cwd(),
+                absolute: false,
+            })
+
+            const routes = compileFileRoutes(files, { pagesDir, loadingComponent })
+            return generateRoutesModule(routes, pagesDir)
+        },
+    }
+}
+
+export function compileFileRoutes(files, options = {}) {
+    const { pagesDir = 'src/pages' } = options
+
+    const entries = _parseFileEntries(files, pagesDir)
+    const tree = _buildRouteTree(entries, false)
+    _sortRoutesRecursive(tree)
+
+    return tree
+}
+
+export function generateRoutesModule(routes, pagesDir = 'src/pages') {
+    const imports = []
+    const lines = []
+
+    _collectImports(routes, pagesDir, imports)
+
+    lines.push('// [fusée] Auto-generated at build-time — do not edit')
+    lines.push('// Generated by compiler/plugins/file-router-plugin.js')
+    lines.push('')
+
+    for (const { varName, filePath } of imports) {
+        lines.push(`const ${varName} = () => import(${JSON.stringify(filePath)})`)
+    }
+
+    lines.push('')
+    lines.push(`export const routes = ${_serializeRoutes(routes)}`)
+    lines.push('')
+    lines.push('export default routes')
+
+    return lines.join('\n')
+}
+
+export function validateRoutes(routes) {
+    const warnings = []
+    const errors = []
+
+    _validateLevel(routes, '', warnings, errors)
+
+    return { warnings, errors }
+}
+
+function _validateLevel(routes, prefix, warnings, errors) {
+    const seenPaths = new Map()
+    const paramNames = new Set()
+
+    for (const route of routes) {
+        const fullPath = prefix + route.path
+        if (seenPaths.has(route.path)) {
+            errors.push(`Duplicate route path "${fullPath}" — defined in multiple page files`)
+        } else {
+            seenPaths.set(route.path, route)
+        }
+        const paramMatch = route.path.match(/^:([^/]+)/)
+        if (paramMatch) {
+            const paramName = paramMatch[1]
+            if (paramNames.size > 0 && !paramNames.has(paramName)) {
+                warnings.push(`Conflicting dynamic segments at "${prefix}*": found ":${[...paramNames][0]}" and ":${paramName}" — only one dynamic segment per level is allowed`)
+            }
+            paramNames.add(paramName)
+        }
+        if (route.children !== undefined && route.children.length === 0) {
+            warnings.push(`Layout route "${fullPath}" has no children — it will never render any content`)
+        }
+
+        if (route.children) {
+            _validateLevel(route.children, fullPath + '/', warnings, errors)
+        }
+    }
+}
+
+export function generateRouteTypes(routes) {
+    const paths = []
+    const paramTypes = []
+
+    _collectRoutePaths(routes, '', paths, paramTypes)
+
+    const pathUnion = paths.map(p => JSON.stringify(p)).join('\n  | ')
+    const paramEntries = paramTypes
+        .filter(e => Object.keys(e.params).length > 0)
+        .map(e => {
+            const paramFields = Object.entries(e.params)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join('; ')
+            return `  ${JSON.stringify(e.path)}: { ${paramFields} }`
+        })
+        .join('\n')
+
+    return [
+        '// [fusée] Auto-generated route types — do not edit',
+        '// Generated by compiler/plugins/file-router-plugin.js',
+        '',
+        '/** All valid application route paths */',
+        `export type AppRoute =`,
+        `  | ${pathUnion}`,
+        '',
+        '/** Route params per path (only paths with dynamic segments) */',
+        'export type RouteParams = {',
+        paramEntries,
+        '}',
+        '',
+        '/** Extract params for a specific route */',
+        'export type ParamsFor<T extends AppRoute> =',
+        '  T extends keyof RouteParams ? RouteParams[T] : Record<string, never>',
+        '',
+    ].join('\n')
+}
+
+function _parseFileEntries(files, pagesDir) {
+    return files.map(filePath => {
+        let cleanPath = filePath
+            .replace(new RegExp(`^${pagesDir}/?`), '')
+            .replace(/\.[jt]sx?$/, '')
+
+        const parts = cleanPath.split('/')
+        const rawFileName = parts.pop()
+        const rawDirSegs = parts
+        const dirSegments = rawDirSegs.map(_transformSegment)
+        const fileName = _transformSegment(rawFileName)
+        const isIndex = rawFileName === 'index'
+        const isCatchAll = /^\.\.\./.test(rawFileName)
+
+        return { filePath, dirSegments, fileName, isIndex, isCatchAll }
+    })
+}
+
+function _transformSegment(seg) {
+    return seg
+        .replace(/\[\.\.\.([^\]]+)\]/g, '*')
+        .replace(/\[([^\]]+)\]/g, ':$1')
+}
+
+function _buildRouteTree(entries, isChild) {
+    const filesHere = new Map()
+    const grouped   = new Map()
+
+    for (const entry of entries) {
+        if (entry.dirSegments.length === 0) {
+            filesHere.set(entry.fileName, entry)
+        } else {
+            const firstDir = entry.dirSegments[0]
+            if (!grouped.has(firstDir)) grouped.set(firstDir, [])
+            grouped.get(firstDir).push(entry)
+        }
+    }
+
+    let rootLayoutEntry = null
+    if (filesHere.has('_layout')) {
+        rootLayoutEntry = filesHere.get('_layout')
+        filesHere.delete('_layout')
+    }
+
+    const routes      = []
+    const usedAsLayout = new Set()
+
+    for (const [dirName, dirEntries] of grouped) {
+        const layoutEntry = filesHere.get(dirName)
+
+        if (layoutEntry) {
+            usedAsLayout.add(dirName)
+            const childEntries = dirEntries.map(e => ({
+                ...e,
+                dirSegments: e.dirSegments.slice(1)
+            }))
+            const children = _buildRouteTree(childEntries, true)
+            routes.push({
+                path:      isChild ? dirName : '/' + dirName,
+                filePath:  layoutEntry.filePath,
+                children,
+            })
+        } else {
+            for (const entry of dirEntries) {
+                const segments = [...entry.dirSegments]
+                if (!entry.isIndex) segments.push(entry.fileName)
+                routes.push({
+                    path:     isChild ? segments.join('/') : '/' + segments.join('/'),
+                    filePath: entry.filePath,
+                })
+            }
+        }
+    }
+
+    for (const [name, entry] of filesHere) {
+        if (usedAsLayout.has(name)) continue
+        if (entry.isIndex) {
+            routes.push({ path: isChild ? '' : '/', filePath: entry.filePath })
+        } else if (entry.isCatchAll || name === '*') {
+            routes.push({ path: '*', filePath: entry.filePath })
+        } else {
+            routes.push({ path: isChild ? name : '/' + name, filePath: entry.filePath })
+        }
+    }
+
+    if (rootLayoutEntry) {
+        return [{ path: '', filePath: rootLayoutEntry.filePath, children: routes }]
+    }
+
+    return routes
+}
+
+function _sortRoutesRecursive(routes) {
+    routes.sort(_compareRoutes)
+    for (const route of routes) {
+        if (route.children) _sortRoutesRecursive(route.children)
+    }
+}
+
+function _compareRoutes(a, b) {
+    if (a.path === '*' && b.path !== '*') return 1
+    if (a.path !== '*' && b.path === '*') return -1
+    const aWild = a.path.endsWith('/*')
+    const bWild = b.path.endsWith('/*')
+    if (aWild && !bWild) return 1
+    if (!aWild && bWild) return -1
+    const aDyn = a.path.includes(':')
+    const bDyn = b.path.includes(':')
+    if (aDyn && !bDyn) return 1
+    if (!aDyn && bDyn) return -1
+    if (a.children && !b.children) return -1
+    if (!a.children && b.children) return 1
+    return a.path.localeCompare(b.path)
+}
+
+let _importCounter = 0
+
+function _collectImports(routes, pagesDir, imports) {
+    for (const route of routes) {
+        if (route.filePath) {
+            const varName = `_page${_importCounter++}`
+            route._varName = varName
+            imports.push({ varName, filePath: './' + route.filePath })
+        }
+        if (route.children) 
+            _collectImports(route.children, pagesDir, imports)
+    }
+}
+
+function _serializeRoutes(routes) {
+    const items = routes.map(route => {
+        const parts = [`path: ${JSON.stringify(route.path)}`]
+        if (route._varName) {
+            parts.push(`component: ${route._varName}`)
+        }
+        if (route.children) {
+            parts.push(`children: ${_serializeRoutes(route.children)}`)
+        }
+        return `{ ${parts.join(', ')} }`
+    })
+    return `[\n  ${items.join(',\n  ')}\n]`
+}
+
+function _collectRoutePaths(routes, prefix, paths, paramTypes) {
+    for (const route of routes) {
+        const fullPath = prefix + route.path
+        if (fullPath) {
+            paths.push(fullPath)
+
+            const params = {}
+            const paramRe = /:([^/]+)/g
+            let m
+            while ((m = paramRe.exec(fullPath)) !== null) {
+                params[m[1]] = 'string'
+            }
+            paramTypes.push({ path: fullPath, params })
+        }
+
+        if (route.children) {
+            _collectRoutePaths(route.children, fullPath + '/', paths, paramTypes)
+        }
+    }
+}

package/framework/core/compiler/plugins/router-plugin.js

@@ -0,0 +1,196 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function routerPlugin(options = {}) {
+    const {
+        typesOutput = 'src/types/router.d.ts',
+        pagesDir = 'src/pages',
+        strict = false,
+    } = options
+
+    return {
+        name: 'vite-plugin-fusee-router',
+
+        async generateBundle() {
+            let routes = []
+
+            try {
+                const { fileRouterPlugin, compileFileRoutes } = await import('./file-router-plugin.js')
+                const { globSync } = await import('fast-glob')
+                const files = globSync(`${pagesDir}/**/*.{js,ts,jsx,tsx}`, {
+                    cwd: process.cwd()
+                })
+                routes = compileFileRoutes(files, { pagesDir })
+            } catch {
+                return
+            }
+
+            const { warnings, errors } = validateRoutes(routes)
+            for (const w of warnings) this.warn(`[fusee router] ${w}`)
+            for (const e of errors) {
+                if (strict) this.error(`[fusee router] ${e}`)
+                else this.warn(`[fusee router] ${e}`)
+            }
+
+            if (typesOutput) {
+                const types = generateRouterTypes(routes)
+                const absPath = path.resolve(process.cwd(), typesOutput)
+                fs.mkdirSync(path.dirname(absPath), { recursive: true })
+                fs.writeFileSync(absPath, types, 'utf8')
+            }
+        },
+    }
+}
+
+export function validateRoutes(routes) {
+    const warnings = []
+    const errors = []
+    _validateLevel(routes, '', warnings, errors)
+    return { warnings, errors }
+}
+
+function _validateLevel(routes, prefix, warnings, errors) {
+    const seenStatic = new Map()
+    let dynamicSeg = null
+    let hasWildcard = false
+
+    for (let i = 0; i < routes.length; i++) {
+        const route = routes[i]
+        const fullPath = (prefix + '/' + route.path).replace(/\/+/g, '/') || '/'
+
+        if (hasWildcard && route.path !== '*') {
+            errors.push(`Route "${fullPath}" is defined after a wildcard "*" at the same level — it will never be reached`)
+        }
+
+        if (route.path === '*') {
+            if (hasWildcard) {
+                errors.push(`Duplicate wildcard "*" route at level "${prefix || '/'}"`)
+            }
+            hasWildcard = true
+            continue
+        }
+
+        const segment = route.path.split('/').filter(Boolean)[0] ?? ''
+
+        if (!segment.startsWith(':') && !segment.startsWith('*')) {
+            if (seenStatic.has(route.path)) {
+                errors.push(`Duplicate route path "${fullPath}" — defined more than once at the same level`)
+            } else {
+                seenStatic.set(route.path, route)
+            }
+        }
+
+        if (segment.startsWith(':')) {
+            if (dynamicSeg && dynamicSeg !== segment) {
+                warnings.push(`Conflicting dynamic segments at level "${prefix || '/'}": ` + `"${dynamicSeg}" and "${segment}" — only one dynamic segment per level is predictable. ` + `Consider renaming them consistently.`)
+            }
+            dynamicSeg = segment
+        }
+
+        if (route.children !== undefined && route.children.length === 0) {
+            warnings.push(`Layout route "${fullPath}" has no child routes — ` + `<router-view> inside it will never render`)
+        }
+
+        if (route.path === '' || route.path === '/') {
+            const conflict = routes.find(
+                r => r !== route && (r.path === '' || r.path === '/')
+            )
+            if (conflict) {
+                errors.push(`Duplicate index route at level "${prefix || '/'}" — ` + `both "" and "/" resolve to the same path`)
+            }
+        }
+
+        if (route.children?.length) {
+            _validateLevel(route.children, fullPath, warnings, errors)
+        }
+    }
+}
+
+export function generateRouterTypes(routes) {
+    const allPaths = []
+    const paramMap = {}
+
+    _collectPaths(routes, '', allPaths, paramMap)
+
+    const staticPaths = allPaths.filter(p => !p.includes(':') && p !== '*')
+    const dynamicPaths = allPaths.filter(p => p.includes(':'))
+
+    const pathUnion = [...staticPaths, ...dynamicPaths]
+        .map(p => JSON.stringify(p))
+        .join('\n  | ')
+
+    const paramEntries = Object.entries(paramMap)
+        .filter(([, params]) => Object.keys(params).length > 0)
+        .map(([p, params]) => {
+            const fields = Object.entries(params)
+                .map(([k]) => `    ${k}: string`)
+                .join('\n')
+            return `  ${JSON.stringify(p)}: {\n${fields}\n  }`
+        })
+        .join('\n')
+
+    return [
+        '// [fusée] Auto-generated router types — do not edit',
+        '// Generated by compiler/plugins/router-plugin.js',
+        '',
+        '/**',
+        ' * All valid application route paths.',
+        ' * Auto-completed in navigate(), <a href>, and useRoute().',
+        ' */',
+        'export type AppRoute =',
+        `  | ${pathUnion || "'/'"}`,
+        '',
+        '/**',
+        ' * Dynamic route params per path.',
+        ' * Only paths with `:param` segments appear here.',
+        ' */',
+        'export type RouteParams = {',
+        paramEntries,
+        '}',
+        '',
+        '/**',
+        ' * Extract params type for a specific route.',
+        ' * @example',
+        ' * type Params = ParamsFor<\'/users/:id\'> // { id: string }',
+        ' */',
+        'export type ParamsFor<T extends AppRoute> =',
+        '  T extends keyof RouteParams ? RouteParams[T] : Record<string, never>',
+        '',
+        '/**',
+        ' * Type-safe navigate() — accepts only valid AppRoute paths.',
+        ' * Import from fusee/router to get autocomplete.',
+        ' */',
+        'export declare function navigate(path: AppRoute): void',
+        '',
+        '/**',
+        ' * Current route params, typed as a record.',
+        ' * Use ParamsFor<T> for specific route param shapes.',
+        ' */',
+        'export declare function useRouteParams<T extends AppRoute = AppRoute>(): ParamsFor<T>',
+        '',
+    ].join('\n')
+}
+
+function _collectPaths(routes, prefix, allPaths, paramMap) {
+    for (const route of routes) {
+        const seg = route.path
+        const fullPath = seg === '' ? (prefix || '/') : prefix + (prefix.endsWith('/') ? '' : '/') + seg
+        const normalized = fullPath.replace(/\/+/g, '/') || '/'
+
+        if (normalized && !allPaths.includes(normalized)) {
+            allPaths.push(normalized)
+
+            const params = {}
+            const re = /:([^/]+)/g
+            let m
+            while ((m = re.exec(normalized)) !== null) {
+                params[m[1]] = 'string'
+            }
+            paramMap[normalized] = params
+        }
+
+        if (route.children?.length) {
+            _collectPaths(route.children, normalized === '/' ? '' : normalized, allPaths, paramMap)
+        }
+    }
+}