fusee-framework 1.7.0 → 1.9.0

package/framework/types/compiler/ast.d.ts

@@ -0,0 +1,166 @@
+export declare const NodeType: {
+    readonly ROOT: 'Root'
+    readonly ELEMENT: 'Element'
+    readonly COMPONENT: 'Component'
+    readonly TEXT: 'Text'
+    readonly INTERPOLATION: 'Interpolation'
+    readonly EXPRESSION: 'Expression'
+    readonly ATTRIBUTE: 'Attribute'
+    readonly BINDING: 'Binding'
+    readonly EVENT: 'Event'
+    readonly DIRECTIVE: 'Directive'
+    readonly SLOT_OUTLET: 'SlotOutlet'
+    readonly SLOT_CONTENT: 'SlotContent'
+}
+
+export type NodeTypeValue = typeof NodeType[keyof typeof NodeType]
+
+export interface Position {
+    line: number
+    col: number
+    offset: number
+}
+
+export interface SourceLocation {
+    start: Position
+    end: Position
+    source?: string
+}
+
+export interface BaseNode {
+    type: NodeTypeValue | 'If'
+    loc: SourceLocation | null
+}
+
+export interface RootNode extends BaseNode {
+    type: 'Root'
+    children: ChildNode[]
+    _hoisted?: AnyNode[]
+}
+
+export interface ElementNode extends BaseNode {
+    type: 'Element'
+    tag: string
+    props: PropNode[]
+    children: ChildNode[]
+    selfClosing: boolean
+    isStatic: boolean
+    hoisted: boolean
+}
+
+export interface ComponentNode extends BaseNode {
+    type: 'Component'
+    name: string
+    props: PropNode[]
+    slots: Record<string, ChildNode[]>
+    isStatic: boolean
+}
+
+export interface TextNode extends BaseNode {
+    type: 'Text'
+    content: string
+    isStatic: true
+}
+
+export interface InterpolationNode extends BaseNode {
+    type: 'Interpolation'
+    expression: ExpressionNode
+    isStatic: boolean
+}
+
+export interface ExpressionNode extends BaseNode {
+    type: 'Expression'
+    content: string
+    isStatic: boolean
+    _isForKey?: boolean
+}
+
+export interface AttributeNode extends BaseNode {
+    type: 'Attribute'
+    name: string
+    value: string | null
+}
+
+export interface BindingNode extends BaseNode {
+    type: 'Binding'
+    name: string
+    expression: ExpressionNode
+    isProp: boolean
+}
+
+export interface EventNode extends BaseNode {
+    type: 'Event'
+    name: string
+    expression: ExpressionNode
+    modifiers: string[]
+}
+
+export type DirectiveName = 'if' | 'else-if' | 'else' | 'for' | 'model' | 'show' | 'once' | 'ref' | 'html' | string
+
+export interface DirectiveNode extends BaseNode {
+    type: 'Directive'
+    name: DirectiveName
+    expression: ExpressionNode | null
+    arg: ForArg | null
+}
+
+export interface SlotOutletNode extends BaseNode {
+    type: 'SlotOutlet'
+    slotName: string
+    fallback: ChildNode[]
+}
+
+export interface SlotContentNode extends BaseNode {
+    type: 'SlotContent'
+    slotName: string
+    children: ChildNode[]
+}
+
+export interface IfNode {
+    type: 'If'
+    branches: IfBranch[]
+    loc: SourceLocation | null
+    isStatic: false
+}
+
+export interface IfBranch {
+    condition: ExpressionNode | null
+    node: ElementNode | ComponentNode
+}
+
+export interface ForArg {
+    item: string
+    source: string
+    index: string | null
+    loc: SourceLocation | null
+}
+
+export type PropNode = AttributeNode | BindingNode | EventNode | DirectiveNode
+export type ChildNode = ElementNode | ComponentNode | TextNode | InterpolationNode | SlotOutletNode | SlotContentNode | IfNode
+export type AnyNode = RootNode | ChildNode | PropNode | ExpressionNode | ForArg
+
+export declare function createLoc(start: Position, end: Position, source?: string): SourceLocation
+export declare function createPos(line: number, col: number, offset: number): Position
+export declare function createRoot(children?: ChildNode[], loc?: SourceLocation | null): RootNode
+export declare function createElement(tag: string, props?: PropNode[], children?: ChildNode[], selfClosing?: boolean, loc?: SourceLocation | null): ElementNode
+export declare function createComponent(name: string, props?: PropNode[], slots?: Record<string, ChildNode[]>, loc?: SourceLocation | null): ComponentNode
+export declare function createText(content: string, loc?: SourceLocation | null): TextNode
+export declare function createInterpolation(expression: ExpressionNode, loc?: SourceLocation | null): InterpolationNode
+export declare function createExpression(content: string, isStatic?: boolean, loc?: SourceLocation | null): ExpressionNode
+export declare function createAttribute(name: string, value: string | null, loc?: SourceLocation | null): AttributeNode
+export declare function createBinding(name: string, expression: ExpressionNode, isProp?: boolean, loc?: SourceLocation | null): BindingNode
+export declare function createEvent(name: string, expression: ExpressionNode, modifiers?: string[], loc?: SourceLocation | null): EventNode
+export declare function createDirective(name: DirectiveName, expression?: ExpressionNode | null, arg?: ForArg | null, loc?: SourceLocation | null): DirectiveNode
+export declare function createSlotOutlet(slotName?: string, fallback?: ChildNode[], loc?: SourceLocation | null): SlotOutletNode
+export declare function createSlotContent(slotName?: string, children?: ChildNode[], loc?: SourceLocation | null): SlotContentNode
+export declare function createForArg(item: string, source: string, index?: string | null, loc?: SourceLocation | null): ForArg
+
+export declare function isElement(node: AnyNode | null | undefined): node is ElementNode
+export declare function isComponent(node: AnyNode | null | undefined): node is ComponentNode
+export declare function isText(node: AnyNode | null | undefined): node is TextNode
+export declare function isInterpolation(node: AnyNode | null | undefined): node is InterpolationNode
+export declare function isDirective(node: AnyNode | null | undefined, name?: DirectiveName): node is DirectiveNode
+export declare function isStaticText(node: AnyNode | null | undefined): boolean
+export declare function findDirective(element: ElementNode | ComponentNode, name: DirectiveName): DirectiveNode | null
+export declare function getEvents(element: ElementNode | ComponentNode): EventNode[]
+export declare function cloneNode<T extends AnyNode>(node: T): T

package/framework/types/compiler/errors-codes.d.ts

@@ -0,0 +1,23 @@
+export declare const ErrorCode: {
+    readonly UNEXPECTED_CHAR: 'E001'
+    readonly UNTERMINATED_STRING: 'E002'
+    readonly UNTERMINATED_MUSTACHE: 'E003'
+    readonly UNTERMINATED_TAG: 'E004'
+    readonly MALFORMED_COMMENT: 'E005'
+    readonly UNEXPECTED_TOKEN: 'P001'
+    readonly MISSING_CLOSING_TAG: 'P002'
+    readonly UNEXPECTED_CLOSING_TAG: 'P003'
+    readonly INVALID_DIRECTIVE_SYNTAX: 'P004'
+    readonly INVALID_FOR_SYNTAX: 'P005'
+    readonly DUPLICATE_KEY: 'P006'
+    readonly V_ELSE_NO_IF: 'P007'
+    readonly EMPTY_EXPRESSION: 'P008'
+    readonly INVALID_SLOT_NAME: 'P009'
+    readonly DUPLICATE_DIRECTIVE: 'T001'
+    readonly FOR_MISSING_KEY: 'T002'
+    readonly MODEL_ON_NON_INPUT: 'T003'
+    readonly COMPONENT_NOT_REGISTERED: 'T004'
+    readonly UNKNOWN_IDENTIFIER: 'S001'
+    readonly STATIC_FOR_KEY: 'S002'
+    readonly UNKNOWN_NODE_TYPE: 'G001'
+}

package/framework/types/compiler/errors.d.ts

@@ -0,0 +1,43 @@
+import type { SourceLocation } from './ast.js'
+import type { ErrorCode } from './errors-list.js'
+
+export type ErrorCodeValue = typeof ErrorCode[keyof typeof ErrorCode]
+
+export declare class CompileError extends Error {
+    readonly name: 'CompileError'
+    readonly code: ErrorCodeValue
+    readonly loc: SourceLocation | null
+    readonly source: string
+
+    constructor(code: ErrorCodeValue, loc: SourceLocation | null, source: string, ...args: string[])
+
+    format(filePath?: string): string
+    _buildSnippet(): string
+}
+
+export declare class CompileWarning {
+    readonly message: string
+    readonly code: ErrorCodeValue
+    readonly loc: SourceLocation | null
+    readonly source: string
+
+    constructor(code: ErrorCodeValue, loc: SourceLocation | null, source: string, ...args: string[])
+
+    format(filePath?: string): string
+}
+
+export declare class ErrorCollector {
+    readonly source: string
+    readonly errors: CompileError[]
+    readonly warnings: CompileWarning[]
+    readonly hasErrors: boolean
+    readonly hasWarnings: boolean
+
+    constructor(source: string)
+
+    error(code: ErrorCodeValue, loc: SourceLocation | null, ...args: string[]): CompileError
+    warn(code: ErrorCodeValue, loc: SourceLocation | null, ...args: string[]): CompileWarning
+    throwIfAny(): void
+}
+
+export declare function throwError(code: ErrorCodeValue, loc: SourceLocation | null, source: string, ...args: string[]): never

package/framework/types/compiler/generator.d.ts

@@ -0,0 +1,8 @@
+import type { RootNode } from './ast.js'
+
+export interface GenerateOptions {
+    runtimePath?: string
+    source?: string
+}
+
+export declare function generate(ast: RootNode, options?: GenerateOptions): string

package/framework/types/compiler/h.d.ts

@@ -0,0 +1,46 @@
+export interface FNode {
+    node: Node
+    effects: Array<() => void>
+    _isIf?: boolean
+    _isFor?: boolean
+    _isSlot?: boolean
+    _tag?: string
+    _component?: ComponentApi
+    _ifBranchNodes?: () => FNode[]
+    _getNodes?: () => FNode[]
+    _slotNodes?: FNode[]
+    props?: Record<string, unknown>
+    children?: FNode[]
+}
+
+export interface ComponentApi {
+    render(container: HTMLElement): unknown
+    unmount(): void
+    instance: unknown
+}
+
+export type StaticPropValue = string | boolean | null
+export type PropGetter<T = unknown> = () => T
+export interface EventDescriptor {
+    handler:   ((...args: unknown[]) => void) | null
+    modifiers: string[]
+}
+
+export type SlotMap = Record<string, () => FNode[]>
+export type PropsMap = Record<string, StaticPropValue | PropGetter | EventDescriptor | true>
+
+export declare function h(tag: string, props?: PropsMap, children?: FNode[], isStatic?: boolean): FNode
+export declare function hText(value: string | (() => string)): FNode
+export declare function hIf(branches: Array<[(() => boolean) | null, () => FNode[]]>): FNode
+export declare function hFor<T>(sourceGetter: () => T[], renderItem: (item: T, index?: number) => FNode, keyFn: (item: T, index?: number) => unknown): FNode
+export declare function hSlot(slots: SlotMap | null | undefined, name: string, fallback?: FNode[]): FNode
+export declare function createComponent(name: string, ComponentFn: ((...args: unknown[]) => ComponentApi) | undefined | null, rawProps?: PropsMap, rawSlots?: SlotMap): FNode
+
+export interface MountedApp {
+    unmount(): void
+}
+
+export declare function mount(renderFn: (ctx: unknown, components: Record<string, unknown>) => FNode[], ctx: unknown, components: Record<string, unknown>, container: HTMLElement): MountedApp
+
+export declare const _effect: (fn: () => void) => () => void
+export declare const _batch:  <T>(fn: () => T) => T

package/framework/types/compiler/lexer.d.ts

@@ -0,0 +1,27 @@
+import type { SourceLocation } from './ast.js'
+
+export declare const TokenType: {
+    readonly TAG_OPEN: 'TAG_OPEN'
+    readonly TAG_OPEN_CLOSE: 'TAG_OPEN_CLOSE'
+    readonly TAG_CLOSE: 'TAG_CLOSE'
+    readonly TAG_SELF_CLOSE: 'TAG_SELF_CLOSE'
+    readonly COMMENT: 'COMMENT'
+    readonly ATTR_NAME: 'ATTR_NAME'
+    readonly ATTR_EQUALS: 'ATTR_EQUALS'
+    readonly ATTR_VALUE: 'ATTR_VALUE'
+    readonly TEXT: 'TEXT'
+    readonly MUSTACHE_OPEN: 'MUSTACHE_OPEN'
+    readonly MUSTACHE_EXPR: 'MUSTACHE_EXPR'
+    readonly MUSTACHE_CLOSE: 'MUSTACHE_CLOSE'
+    readonly EOF: 'EOF'
+}
+
+export type TokenTypeValue = typeof TokenType[keyof typeof TokenType]
+
+export interface Token {
+    type: TokenTypeValue
+    value: string
+    loc: SourceLocation
+}
+
+export declare function tokenize(source: string): Token[]

package/framework/types/compiler/main-compiler.d.ts

@@ -0,0 +1,60 @@
+import type { RootNode } from './ast.js'
+import type { Token } from './lexer.js'
+import type { CompileWarning } from './errors.js'
+import type { CompileError } from './errors.js'
+
+export interface CompileOptions {
+    components?: string[] | Set<string>
+    runtimePath?: string
+    filename?: string
+    throwOnWarning?: boolean
+    scope?: string[]
+}
+
+export interface CompileResult {
+    code: string
+    ast: RootNode
+    tokens: Token[]
+    warnings: CompileWarning[]
+}
+
+export interface ParseOnlyResult {
+    ast: RootNode
+    tokens: Token[]
+}
+
+export interface BatchEntry {
+    id: string
+    source: string
+}
+
+export interface BatchResult {
+    id: string
+    code: string | null
+    warnings: CompileWarning[]
+    error: CompileError | null
+}
+
+export declare function compile(source: string, options?: CompileOptions): CompileResult
+export declare function parseOnly(source: string, options?: Pick<CompileOptions, 'components'>): ParseOnlyResult
+export declare function transformOnly(ast: RootNode, options?: Pick<CompileOptions, 'components' | 'scope'> & { source?: string }): { ast: RootNode; warnings: CompileWarning[] }
+export declare function compileBatch(templates: BatchEntry[], sharedOptions?: CompileOptions): BatchResult[]
+
+export interface FuseePluginOptions {
+    runtimePath?: string
+    components?: string[]
+    scope?: string[]
+}
+
+export declare function fuseePlugin(options?: FuseePluginOptions): {
+    name: 'vite-plugin-fusee'
+    transform(src: string, id: string): { code: string; map: null } | null
+}
+
+export { fileRouterPlugin } from './plugins/file-router-plugin.js'
+export { actionsPlugin } from './plugins/actions-plugin.js'
+export { routerPlugin } from './plugins/router-plugin.js'
+export { fuseeCompilerPlugin } from './plugins/compiler-plugin.js'
+export { compileFileRoutes, generateRoutesModule, generateRouteTypes, validateRoutes as validateFileRoutes } from './plugins/file-router-plugin.js'
+export { validateActions, generateClientStubs, generateServerRoutes, generateActionTypes } from './plugins/actions-plugin.js'
+export { validateRoutes, generateRouterTypes } from './plugins/router-plugin.js'

package/framework/types/compiler/parser.d.ts

@@ -0,0 +1,4 @@
+import type { Token } from './lexer.js'
+import type { RootNode } from './ast.js'
+
+export declare function parse(tokens: Token[], source: string, components?: Set<string>): RootNode

package/framework/types/compiler/plugins/actions.d.ts

@@ -0,0 +1,30 @@
+export interface ActionsPluginOptions {
+    serverActionsFile?: string
+    clientActionsFile?: string
+    baseUrl?: string
+    typesOutput?: string
+}
+
+export interface ActionDef {
+    name: string
+    exportName: string
+}
+
+export interface ActionValidationResult {
+    warnings: string[]
+    errors: string[]
+}
+
+export declare function actionsPlugin(options?: ActionsPluginOptions): {
+    name: 'vite-plugin-fusee-actions'
+    configResolved(config: { root: string }): void
+    resolveId(id: string): string | undefined
+    load(id: string): Promise<string | null>
+    buildEnd(): Promise<void>
+    handleHotUpdate(ctx: { file: string; server: unknown }): void
+}
+
+export declare function validateActions(serverActions: ActionDef[], clientActions: string[]): ActionValidationResult
+export declare function generateClientStubs(actions: ActionDef[], options?: { baseUrl?: string }): string
+export declare function generateServerRoutes(actions: ActionDef[], options?: { serverActionsFile?: string; baseUrl?: string }): string
+export declare function generateActionTypes(actions: ActionDef[]): string

package/framework/types/compiler/plugins/compiler-plugin.d.ts

@@ -0,0 +1,5 @@
+export declare function fuseeCompilerPlugin(): {
+    name: 'vite-plugin-fusee-compiler'
+    enforce: 'pre'
+    transform(code: string, id: string): { code: string; map: null } | null
+}

package/framework/types/compiler/plugins/file-router-plugins.d.ts

@@ -0,0 +1,32 @@
+export interface FileRouterPluginOptions {
+    pagesDir?: string
+    loadingComponent?: unknown
+}
+
+export interface RouteNode {
+    path: string
+    filePath?: string
+    children?: RouteNode[]
+}
+
+export interface RouteValidationResult {
+    warnings: string[]
+    errors: string[]
+}
+
+export interface ImportEntry {
+    varName: string
+    filePath: string
+}
+
+export declare function fileRouterPlugin(options?: FileRouterPluginOptions): {
+    name: 'vite-plugin-fusee-file-router'
+    buildStart(): Promise<void>
+    resolveId(id: string): string | undefined
+    load(id: string): Promise<string | null>
+}
+
+export declare function compileFileRoutes(files: string[], options?: { pagesDir?: string }): RouteNode[]
+export declare function generateRoutesModule(routes: RouteNode[], pagesDir?: string): string
+export declare function validateRoutes(routes: RouteNode[]): RouteValidationResult
+export declare function generateRouteTypes(routes: RouteNode[]): string

package/framework/types/compiler/plugins/router-plugin.d.ts

@@ -0,0 +1,24 @@
+export interface RouterPluginOptions {
+    typesOutput?: string
+    pagesDir?: string
+    strict?: boolean
+}
+
+export interface RouteNode {
+    path: string
+    filePath?: string
+    children?: RouteNode[]
+}
+
+export interface RouteValidationResult {
+    warnings: string[]
+    errors: string[]
+}
+
+export declare function routerPlugin(options?: RouterPluginOptions): {
+    name: 'vite-plugin-fusee-router'
+    generateBundle(): Promise<void>
+}
+
+export declare function validateRoutes(routes: RouteNode[]): RouteValidationResult
+export declare function generateRouterTypes(routes: RouteNode[]): string

package/framework/types/compiler/transformer.d.ts

@@ -0,0 +1,28 @@
+import type { RootNode }       from './ast.js'
+import type { CompileWarning } from './errors.js'
+
+export interface TransformOptions {
+    components?: Set<string>
+    source?: string
+    scope?: string[]
+}
+
+export interface TransformResult {
+    ast: RootNode
+    warnings: CompileWarning[]
+}
+
+/**
+ * Run all transformer steps on the Root AST (mutates in-place).
+ *
+ * Steps:
+ *  1. markStatic — bottom-up static marking
+ *  2. hoistStatic — collect f-once + multi-static-child subtrees
+ *  3. chainConditionals — f-if / f-else-if / f-else -> IfNode
+ *  4. validateFor — warn on f-for without :key  (T002)
+ *  5. validateModel — warn on f-model on non-input  (T003)
+ *  6. validateComponents — warn on unregistered component  (T004)
+ *  7. analyseScope — resolve identifiers (needs `scope`)
+ *  8. validateExpressions — warn on unknown identifiers (S001) + static :key (S002)
+ */
+export declare function transform(ast: RootNode, options?: TransformOptions): TransformResult