@openfairygui/functions 0.2.0-alpha.7 → 0.2.0

package/src/codegen.ts

@@ -1,7 +1,7 @@
 import {
 	type Component,
-	type GComponent,
 	type Document,
+	type GComponent,
 	type GObject,
 	type Package,
 	ProjectType,
@@ -12,7 +12,10 @@ import {
 	UNITY_BINDER_TEMPLATE,
 	UNITY_COMPONENT_TEMPLATE,
 } from './codegen-templates.js';
-import type { CliCodeGenerationSettings, PublishFileSystem, RootProjectSettings } from './shared-types.js';
+import { formatPluginError, type LoadedPlugin } from './plugins/types.js';
+import { dirname, isAbsolutePathLike, trimTrailingSlashes } from './path-utils.js';
+import type { PublishFileSystem } from './publish/contracts.js';
+import type { CliCodeGenerationSettings, RootProjectSettings } from './shared-types.js';
 
 export const AUTO_GENERATED_CODE_MARK = '/** This is an automatically generated class by FairyGUI. Please do not modify it. **/';
 const DEFAULT_CLASS_NAME_PREFIX = 'UI_';
@@ -22,25 +25,15 @@ export interface PublishCodeGenerationOptions {
 	basePath?: string;
 	fs: PublishFileSystem;
 	packages: Package[];
+	plugins?: LoadedPlugin[];
 }
 
-interface ResolvedCodeGenerationSettings {
-	allowGenCode: boolean;
-	classNamePrefix: string;
-	memberNamePrefix: string;
-	packageName: string;
-	ignoreNoname: boolean;
-	getMemberByName: boolean;
-	codePath: string;
-	codeType: string;
-}
-
-interface ResolvedPackageCodegenPlan {
+export interface ResolvedPackageCodegenPlan {
 	outputDir: string;
 	packageFolderName: string;
 	packageNamespace: string;
 	binderClassName: string;
-	settings: ResolvedCodeGenerationSettings;
+	settings: CliCodeGenerationSettings;
 }
 
 interface FguiTypescriptVariant {
@@ -77,16 +70,22 @@ const SHARED_FGUI_TYPESCRIPT_VARIANT: FguiTypescriptVariant = {
 	runtimeNamespace: 'fgui',
 };
 
-interface CodegenMember {
+export interface CodegenMember {
 	index: number;
 	kind: 'child' | 'controller' | 'transition';
 	name: string;
 	originalName: string;
 	type: string;
 	ignored: boolean;
+	referencedComponent?: CodegenReferencedComponent;
+}
+
+export interface CodegenReferencedComponent {
+	component: Component;
+	package: Package;
 }
 
-interface CodegenClass {
+export interface CodegenClass {
 	classId: string;
 	className: string;
 	encodedClassName: string;
@@ -97,14 +96,28 @@ interface CodegenClass {
 	members: CodegenMember[];
 }
 
-export async function publishCodeGeneration(
-	doc: Document,
-	options: PublishCodeGenerationOptions,
-): Promise<void> {
+export async function publishCodeGeneration(doc: Document, options: PublishCodeGenerationOptions): Promise<void> {
 	const logger = doc.getLogger();
 	const settings = resolveCodeGenerationSettings(doc);
 	if (!settings.allowGenCode) return;
 
+	const plugins = options.plugins?.filter((plugin) => typeof plugin.plugin.genCode === 'function') ?? [];
+	if (plugins.length > 0) {
+		let handled = false;
+		for (const plugin of plugins) {
+			try {
+				await plugin.plugin.genCode(doc, settings, options);
+				handled = true;
+				logger.info(`publish: Generated code using plugin "${plugin.name}"`);
+			} catch (error) {
+				logger.warn(`publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`);
+			}
+		}
+		if (handled) {
+			return;
+		}
+	}
+
 	for (const pkg of options.packages) {
 		if (!pkg.getGenCode()) continue;
 
@@ -129,7 +142,7 @@ export async function publishCodeGeneration(
 	}
 }
 
-function resolveCodeGenerationSettings(doc: Document): ResolvedCodeGenerationSettings {
+export function resolveCodeGenerationSettings(doc: Document): Required<CliCodeGenerationSettings> {
 	const settings = (doc.getRoot().getSettings?.() ?? {}) as RootProjectSettings;
 	const publish = settings.publish ?? {};
 	const codeGeneration = publish.codeGeneration as CliCodeGenerationSettings | undefined;
@@ -159,11 +172,7 @@ function resolveCodeGenerationSettings(doc: Document): ResolvedCodeGenerationSet
 	};
 }
 
-function resolvePackageCodegenPlan(
-	pkg: Package,
-	settings: ResolvedCodeGenerationSettings,
-	options: PublishCodeGenerationOptions,
-): ResolvedPackageCodegenPlan | null {
+export function resolvePackageCodegenPlan(pkg: Package, settings: CliCodeGenerationSettings, options: PublishCodeGenerationOptions): ResolvedPackageCodegenPlan | null {
 	const rawCodePath = (pkg.getCodePath() || settings.codePath || '').trim();
 	if (!rawCodePath) return null;
 
@@ -276,17 +285,11 @@ async function cleanupGeneratedFiles(directory: string, fs: PublishFileSystem, e
 	}
 }
 
-function buildCodegenClasses(
-	doc: Document,
-	pkg: Package,
-	plan: ResolvedPackageCodegenPlan,
-): CodegenClass[] {
-	const exportedComponents = pkg.listComponents()
-		.filter((component) => component.getExported())
-		.sort((left, right) => left.getId().localeCompare(right.getId()));
+export function buildCodegenClasses(doc: Document, pkg: Package, plan: ResolvedPackageCodegenPlan): CodegenClass[] {
+	const codegenComponents = pkg.listComponents().sort((left, right) => left.getId().localeCompare(right.getId()));
 	const generatedById = new Map<string, CodegenClass>();
 
-	for (const component of exportedComponents) {
+	for (const component of codegenComponents) {
 		const encodedClassName = `${plan.settings.classNamePrefix}${normalizeTypeName(component.getName()) || 'Component'}`;
 		generatedById.set(component.getId(), {
 			classId: component.getId(),
@@ -300,7 +303,19 @@ function buildCodegenClasses(
 		});
 	}
 
-	for (const component of exportedComponents) {
+	for (const component of codegenComponents) {
+		const classInfo = generatedById.get(component.getId());
+		if (!classInfo) continue;
+		classInfo.members = buildCodegenMembers(doc, pkg, component, plan, generatedById);
+	}
+
+	for (const [componentId, classInfo] of generatedById) {
+		if (classInfo.members.every((member) => member.ignored)) {
+			generatedById.delete(componentId);
+		}
+	}
+
+	for (const component of codegenComponents) {
 		const classInfo = generatedById.get(component.getId());
 		if (!classInfo) continue;
 		classInfo.members = buildCodegenMembers(doc, pkg, component, plan, generatedById);
@@ -327,13 +342,17 @@ function buildCodegenMembers(
 	}
 
 	for (const child of component.listChildren()) {
+		if (!isRuntimeChild(child)) continue;
+		const index = childIndex++;
+		const resolvedChild = resolveChildType(doc, pkg, child, generatedById);
 		members.push(createMember(
 			ownerType,
 			'child',
-			resolveChildType(doc, pkg, child, generatedById),
+			resolvedChild.type,
 			child.getName(),
-			childIndex++,
+			index,
 			plan,
+			resolvedChild.referencedComponent,
 		));
 	}
 
@@ -355,6 +374,10 @@ function buildCodegenMembers(
 	return members;
 }
 
+function isRuntimeChild(child: GObject): boolean {
+	return child.propertyType !== 'GGroup' || (child as GObject & { getAdvanced?(): boolean }).getAdvanced?.() === true;
+}
+
 function createMember(
 	ownerType: string,
 	kind: CodegenMember['kind'],
@@ -362,6 +385,7 @@ function createMember(
 	originalName: string,
 	index: number,
 	plan: ResolvedPackageCodegenPlan,
+	referencedComponent?: CodegenReferencedComponent,
 ): CodegenMember {
 	const ignored = plan.settings.ignoreNoname && isDefaultMemberName(ownerType, kind, originalName);
 	return {
@@ -371,43 +395,59 @@ function createMember(
 		originalName,
 		type,
 		ignored,
+		referencedComponent,
 	};
 }
 
+interface ResolvedChildCodegenType {
+	type: string;
+	referencedComponent?: CodegenReferencedComponent;
+}
+
 function resolveChildType(
 	doc: Document,
 	pkg: Package,
 	child: GObject,
 	generatedById: Map<string, CodegenClass>,
-): string {
+): ResolvedChildCodegenType {
 	const src = (child as GObject & { getSrc?(): string }).getSrc?.();
 	if (src) {
-		const localResource = resolveChildSourceComponent(doc, pkg, src);
-		if (localResource) {
-			return generatedById.get(localResource.getId())?.encodedClassName
-				?? resolveComponentBaseType(localResource);
+		let referencedComponent: CodegenReferencedComponent | null = null;
+		if (src.startsWith('ui://')) {
+			const rest = src.slice(5);
+			const pkgId = rest.slice(0, 8);
+			const resourceId = rest.slice(8);
+			const targetPackage = doc.getRoot().listPackages().find((candidate) => candidate.getId() === pkgId);
+			const targetResource = targetPackage?.getResourceById(resourceId);
+			if (targetPackage && targetResource?.propertyType === 'Component') {
+				referencedComponent = { component: targetResource, package: targetPackage };
+			}
+		} else {
+			const packageId = (child as GComponent & { getPackageId?(): string }).getPackageId?.();
+			const targetPackage = packageId
+				? doc.getRoot().listPackages().find((candidate) => candidate.getId() === packageId)
+				: pkg;
+			const targetResource = targetPackage?.getResourceById(src);
+			if (targetPackage && targetResource?.propertyType === 'Component') {
+				referencedComponent = { component: targetResource, package: targetPackage };
+			}
+		}
+
+		if (referencedComponent) {
+			const localGeneratedClass = referencedComponent.package === pkg
+				? generatedById.get(referencedComponent.component.getId())
+				: undefined;
+			return {
+				type: localGeneratedClass?.encodedClassName ?? resolveComponentBaseType(referencedComponent.component),
+				referencedComponent,
+			};
 		}
 	}
 
 	const instanceExtType = (child as GComponent & { getInstanceExtType?(): string }).getInstanceExtType?.();
-	if (instanceExtType) return `G${instanceExtType}`;
-
-	return child.propertyType;
-}
+	if (instanceExtType) return { type: `G${instanceExtType}` };
 
-function resolveChildSourceComponent(doc: Document, pkg: Package, src: string): Component | null {
-	if (!src) return null;
-	if (src.startsWith('ui://')) {
-		const rest = src.slice(5);
-		const pkgId = rest.slice(0, 8);
-		const resourceId = rest.slice(8);
-		const targetPackage = doc.getRoot().listPackages().find((candidate) => candidate.getId() === pkgId);
-		const targetResource = targetPackage?.getResourceById(resourceId);
-		return targetResource?.propertyType === 'Component' ? targetResource : null;
-	}
-
-	const localResource = pkg.getResourceById(src);
-	return localResource?.propertyType === 'Component' ? localResource : null;
+	return { type: child.propertyType };
 }
 
 function resolveComponentBaseType(component: Component): string {
@@ -544,12 +584,12 @@ function resolveCodePath(
 	basePath: string | undefined,
 	fs: Pick<PublishFileSystem, 'join'>,
 ): string {
-	if (isAbsolutePath(codePath)) return trimTrailingSlashes(codePath);
+	if (isAbsolutePathLike(codePath)) return trimTrailingSlashes(codePath);
 	const projectBasePath = resolveProjectBasePath(basePath);
 	return projectBasePath ? trimTrailingSlashes(fs.join(projectBasePath, codePath)) : trimTrailingSlashes(codePath);
 }
 
-function resolveProjectBasePath(basePath: string | undefined): string {
+export function resolveProjectBasePath(basePath: string | undefined): string {
 	if (!basePath) return '';
 	const normalized = trimTrailingSlashes(basePath);
 	const assetsMatch = normalized.match(/^(.*)[/\\]assets(?:_[^/\\]+)?$/i);
@@ -557,20 +597,6 @@ function resolveProjectBasePath(basePath: string | undefined): string {
 	return dirname(normalized);
 }
 
-function dirname(filePath: string): string {
-	const trimmed = trimTrailingSlashes(filePath);
-	const match = trimmed.match(/^(.*)[/\\][^/\\]+$/);
-	return match?.[1] ?? '';
-}
-
-function trimTrailingSlashes(value: string): string {
-	return value.replace(/[/\\]+$/, '');
-}
-
-function isAbsolutePath(value: string): boolean {
-	return /^[a-z]:[/\\]/i.test(value) || value.startsWith('/') || value.startsWith('\\\\');
-}
-
 function isDefaultMemberName(ownerType: string, kind: CodegenMember['kind'], name: string): boolean {
 	if (kind === 'controller') {
 		return (ownerType === 'GButton' || ownerType === 'GComboBox') && name === 'button';
@@ -578,13 +604,13 @@ function isDefaultMemberName(ownerType: string, kind: CodegenMember['kind'], nam
 	if (kind === 'transition') return false;
 
 	if (ownerType === 'GButton' || ownerType === 'GLabel' || ownerType === 'GComboBox') {
-		return name === 'title' || name === 'icon';
+		if (name === 'title' || name === 'icon') return true;
 	}
 	if (ownerType === 'GProgressBar') {
-		return name === 'bar' || name === 'bar_v' || name === 'title' || name === 'ani';
+		if (name === 'bar' || name === 'bar_v' || name === 'title' || name === 'ani') return true;
 	}
 	if (ownerType === 'GSlider') {
-		return name === 'bar' || name === 'bar_v' || name === 'grip' || name === 'title' || name === 'ani';
+		if (name === 'bar' || name === 'bar_v' || name === 'grip' || name === 'title' || name === 'ani') return true;
 	}
 	return /^n\d+(?:_.*)?$/i.test(name);
 }
@@ -647,10 +673,10 @@ async function writeTextFile(fs: PublishFileSystem, filePath: string, content: s
 	await fs.writeFileRaw(filePath, encodeText(content));
 }
 
-function encodeText(value: string): Uint8Array {
+export function encodeText(value: string): Uint8Array {
 	return new TextEncoder().encode(value);
 }
 
-function decodeText(value: Uint8Array): string {
+export function decodeText(value: Uint8Array): string {
 	return new TextDecoder().decode(value);
 }

package/src/index.ts

@@ -1,9 +1,48 @@
 export { inspect, type InspectReport, type InspectCategoryReport } from './inspect.js';
-export { validate, type ValidateOptions, type ValidationResult, type ValidationIssue, ValidationSeverity } from './validate.js';
+export {
+	validate,
+	type ValidateOptions,
+	type ValidationResult,
+	type ValidationIssue,
+	ValidationSeverity,
+} from './validate.js';
 export { prune, type PruneOptions } from './prune.js';
 export { rename, type RenameOptions } from './rename.js';
 export { atlas, type AtlasOptions } from './atlas.js';
-export { publishCodeGeneration, AUTO_GENERATED_CODE_MARK, type PublishCodeGenerationOptions } from './codegen.js';
+export {
+	publishCodeGeneration,
+	AUTO_GENERATED_CODE_MARK,
+	type PublishCodeGenerationOptions,
+	type ResolvedPackageCodegenPlan,
+	resolvePackageCodegenPlan,
+	buildCodegenClasses,
+	type CodegenClass,
+	type CodegenMember,
+	type CodegenReferencedComponent,
+	encodeText,
+	decodeText,
+} from './codegen.js';
+
+export type {
+	CodeWriter,
+	ICodeWriterConfig,
+	MaybePromise,
+	LoadedPlugin,
+	Plugin,
+	PluginManifest,
+	PluginModule,
+} from './plugins/types.js';
+export type {
+	AtlasRasterBackend,
+	AtlasRasterCompositeInput,
+	AtlasRasterInput,
+	AtlasRasterMetadata,
+	AtlasRasterPipeline,
+	AtlasRasterResolvedBuffer,
+	PublishFileSystem,
+	PublishOutputFileSystem,
+	PublishSourceFileSystem,
+} from './publish/contracts.js';
 export {
 	restore,
 	type RestoreFileSystem,
@@ -24,6 +63,7 @@ export {
 } from './publish.js';
 export {
 	applyUamTransactionApp,
+	applyUamTransactionAppAsync,
 	type ApplyUamTransactionAppDiagnostic,
 	type ApplyUamTransactionAppError,
 	type ApplyUamTransactionAppInput,
@@ -38,6 +78,6 @@ export type {
 	HasOptionalSrc,
 	HasOptionalUrl,
 	PublishDependency,
-	PublishFileSystem,
 	RootProjectSettings,
+	CliCodeGenerationSettings,
 } from './shared-types.js';

package/src/node.ts

@@ -0,0 +1,8 @@
+export {
+	publishNode,
+	type PublishNodeOptions,
+} from './adapters/node/publish.js';
+export {
+	restoreNode,
+	type RestoreNodeOptions,
+} from './adapters/node/restore.js';

package/src/path-utils.ts

@@ -0,0 +1,40 @@
+export function trimTrailingSlashes(value: string): string {
+	return value.replace(/[/\\]+$/, '');
+}
+
+export function dirname(filePath: string): string {
+	const match = trimTrailingSlashes(filePath).match(/^(.*)[/\\][^/\\]+$/);
+	return match?.[1] ?? '';
+}
+
+export function basename(filePath: string): string {
+	const match = trimTrailingSlashes(filePath).match(/([^/\\]+)$/);
+	return match?.[1] ?? '';
+}
+
+export function isAbsolutePathLike(value: string): boolean {
+	return /^(?:[a-zA-Z]:[/\\]|[/\\]{1,2})/u.test(value);
+}
+
+export function normalizeComparablePath(value: string): string {
+	const normalized = trimTrailingSlashes(value).replace(/\\/g, '/');
+	const driveMatch = normalized.match(/^([a-z]:)(?:\/(.*))?$/i);
+	const drivePrefix = driveMatch?.[1].toLowerCase() ?? '';
+	const remainder = driveMatch ? (driveMatch[2] ?? '') : normalized;
+	const hasRoot = driveMatch ? true : remainder.startsWith('/');
+	const segments: string[] = [];
+
+	for (const segment of remainder.split('/').filter(Boolean)) {
+		if (segment === '.') continue;
+		if (segment === '..') {
+			if (segments.length > 0 && segments.at(-1) !== '..') segments.pop();
+			else if (!hasRoot) segments.push('..');
+			continue;
+		}
+		segments.push(segment);
+	}
+
+	const joined = segments.join('/');
+	const comparable = drivePrefix ? `${drivePrefix}/${joined}` : hasRoot ? `/${joined}` : joined || '.';
+	return comparable.replace(/\/$/, '').toLowerCase();
+}

package/src/plugins/types.ts

@@ -0,0 +1,56 @@
+import type { Document } from '@openfairygui/core';
+import type { PublishCodeGenerationOptions } from '../codegen.js';
+import type { PublishOptions } from '../publish.js';
+import type { CliCodeGenerationSettings } from '../shared-types.js';
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export interface PluginManifest {
+	name: string;
+	displayName?: string;
+	description?: string;
+	version?: string;
+	author?: {
+		name?: string;
+	};
+	icon?: string;
+	main: string;
+}
+
+export interface ICodeWriterConfig {
+	blockStart?: string;
+	blockEnd?: string;
+	blockFromNewLine?: boolean;
+	usingTabs?: boolean;
+	endOfLine?: string;
+	fileMark?: string;
+}
+
+export interface CodeWriter {
+	writeMark(): void;
+	writeln(fmt?: string, ...args: any[]): CodeWriter;
+	startBlock(): CodeWriter;
+	endBlock(): CodeWriter;
+	incIndent(): CodeWriter;
+	decIndent(): CodeWriter;
+	reset(): void;
+	toString(): string;
+	save(filePath: string): void;
+}
+
+export interface Plugin {
+	genCode?: (doc: Document, settings: Required<CliCodeGenerationSettings>, options: PublishCodeGenerationOptions) => MaybePromise<void>;
+	onPublishStart?: (doc: Document, options: PublishOptions) => MaybePromise<void>;
+	onPublishEnd?: (doc: Document, options: PublishOptions) => MaybePromise<void>;
+}
+
+export interface LoadedPlugin {
+	name: string;
+	plugin: Plugin;
+}
+
+export type PluginModule = Plugin & { default?: Plugin };
+
+export function formatPluginError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/publish/contracts.ts

@@ -0,0 +1,80 @@
+import type { FileSystem } from '@openfairygui/core';
+
+/**
+ * Source files required by a publish adapter.
+ *
+ * The host owns this filesystem: Node adapters use native paths while web
+ * adapters can use File System Access, OPFS, IndexedDB, ZIP, or memory.
+ */
+export type PublishSourceFileSystem = Pick<FileSystem, 'readFileRaw' | 'join'>;
+
+/**
+ * Output files required by a publish adapter.
+ */
+export type PublishOutputFileSystem = Pick<FileSystem, 'writeFileRaw' | 'mkdir' | 'join'>;
+
+/**
+ * Full filesystem contract consumed by the capability-injected publish core.
+ *
+ * Read, enumeration, and delete operations are optional because individual
+ * publish lanes only request them when needed.
+ */
+export type PublishFileSystem = PublishOutputFileSystem & {
+	deleteFile?: (path: string) => Promise<void>;
+	exists?: FileSystem['exists'];
+	readdir?: FileSystem['readdir'];
+	readFileRaw?: FileSystem['readFileRaw'];
+};
+
+export interface AtlasRasterMetadata {
+	width?: number;
+	height?: number;
+	channels?: number;
+	hasAlpha?: boolean;
+	trimOffsetLeft?: number;
+	trimOffsetTop?: number;
+}
+
+export interface AtlasRasterResolvedBuffer {
+	data: Uint8Array;
+	info: Required<Pick<AtlasRasterMetadata, 'width' | 'height' | 'channels'>> & AtlasRasterMetadata;
+}
+
+export interface AtlasRasterCompositeInput {
+	input: Uint8Array;
+	left: number;
+	top: number;
+}
+
+export type AtlasRasterInput =
+	| string
+	| Uint8Array
+	| {
+			create: {
+				width: number;
+				height: number;
+				channels: 4;
+				background: { r: number; g: number; b: number; alpha: number };
+			};
+	  };
+
+/**
+ * Host-provided raster pipeline used by atlas packing.
+ *
+ * Sharp and the browser Canvas adapter both satisfy this contract.
+ */
+export interface AtlasRasterPipeline {
+	ensureAlpha(): AtlasRasterPipeline;
+	resize(options: { width: number; height: number; fit?: 'fill' }): AtlasRasterPipeline;
+	raw(): AtlasRasterPipeline;
+	extract(options: { left: number; top: number; width: number; height: number }): AtlasRasterPipeline;
+	png(): AtlasRasterPipeline;
+	rotate(angle: number): AtlasRasterPipeline;
+	composite(inputs: AtlasRasterCompositeInput[]): AtlasRasterPipeline;
+	metadata(): Promise<AtlasRasterMetadata>;
+	toBuffer(options: { resolveWithObject: true }): Promise<AtlasRasterResolvedBuffer>;
+	toBuffer(options?: { resolveWithObject?: false }): Promise<Uint8Array>;
+	toFile(path: string): Promise<unknown>;
+}
+
+export type AtlasRasterBackend = (input: AtlasRasterInput) => AtlasRasterPipeline;