@openfairygui/functions 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,422 @@
+import { Document, FileSystem, Package, ProjectSettings, PublishSettings, Transform } from "@openfairygui/core";
+
+//#region src/inspect.d.ts
+/**
+ * Summary report for a single resource category.
+ */
+interface InspectCategoryReport {
+  count: number;
+  details: Array<{
+    name: string;
+    id: string;
+    path?: string;
+    exported?: boolean;
+  }>;
+}
+/**
+ * Full inspection report for a FairyGUI project.
+ */
+interface InspectReport {
+  projectId: string;
+  projectType: number;
+  version: string;
+  packages: Array<{
+    name: string;
+    id: string;
+    publishName: string;
+    resources: {
+      images: InspectCategoryReport;
+      sounds: InspectCategoryReport;
+      fonts: InspectCategoryReport;
+      movieClips: InspectCategoryReport;
+      components: InspectCategoryReport;
+    };
+    componentDetails: Array<{
+      name: string;
+      id: string;
+      childCount: number;
+      controllerCount: number;
+      transitionCount: number;
+    }>;
+  }>;
+  totals: {
+    packages: number;
+    images: number;
+    sounds: number;
+    fonts: number;
+    movieClips: number;
+    components: number;
+    displayObjects: number;
+    gears: number;
+    controllers: number;
+    transitions: number;
+  };
+}
+/**
+ * Generates a detailed report of the project contents.
+ *
+ * Unlike other transforms, `inspect()` does NOT modify the document —
+ * it returns a structured report.
+ *
+ * ```ts
+ * const report = inspect(doc);
+ * console.log(`${report.totals.packages} packages, ${report.totals.components} components`);
+ * ```
+ */
+declare function inspect(doc: Document): InspectReport;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Severity of a validation issue.
+ */
+declare enum ValidationSeverity {
+  ERROR = "error",
+  WARNING = "warning",
+  INFO = "info"
+}
+/**
+ * A single validation issue found in the project.
+ */
+interface ValidationIssue {
+  severity: ValidationSeverity;
+  message: string;
+  /** Package name where the issue was found. */
+  packageName?: string;
+  /** Component name where the issue was found. */
+  componentName?: string;
+  /** Resource/object name related to the issue. */
+  resourceName?: string;
+}
+/**
+ * Result returned by `validate()`.
+ */
+interface ValidationResult {
+  ok: boolean;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+  infos: ValidationIssue[];
+}
+interface ValidateOptions {
+  /** If true, the transform throws on errors. Default: false. */
+  throwOnError?: boolean;
+}
+/**
+ * Validates a FairyGUI project for common issues:
+ * - Missing resource IDs
+ * - Broken `ui://` references (src pointing to non-existent resources)
+ * - Empty components (no children)
+ * - Controllers with no pages
+ * - Duplicate resource IDs within a package
+ *
+ * The validation result is stored in `doc.getRoot().getExtras()._validation`.
+ *
+ * ```ts
+ * await doc.transform(validate({ throwOnError: true }));
+ * ```
+ */
+declare function validate(_options?: ValidateOptions): Transform;
+//#endregion
+//#region src/prune.d.ts
+interface PruneOptions {
+  /** Remove components with no children. Default: false. */
+  emptyComponents?: boolean;
+  /** Remove unreferenced resources (images, sounds, fonts, movieclips not used in any component). Default: true. */
+  unusedResources?: boolean;
+}
+/**
+ * Removes unreferenced resources from the project.
+ *
+ * By default, removes image/sound/font/movieclip resources that are not
+ * referenced by any component's display objects via `src` or `ui://` URLs.
+ *
+ * ```ts
+ * await doc.transform(prune());
+ * await doc.transform(prune({ emptyComponents: true }));
+ * ```
+ */
+declare function prune(_options?: PruneOptions): Transform;
+//#endregion
+//#region src/rename.d.ts
+interface RenameOptions {
+  /** Package name to rename from. Required. */
+  packageName: string;
+  /** Resource name to rename from. Required. */
+  resourceName: string;
+  /** New name for the resource. Required. */
+  newName: string;
+  /** If true, also update all `ui://` references pointing to this resource. Default: true. */
+  updateReferences?: boolean;
+}
+/**
+ * Renames a resource and optionally updates all references to it.
+ *
+ * This searches all display objects' `src` attributes across all packages
+ * for `ui://` URLs that point to the renamed resource, and updates them
+ * to reflect the new name (the resource ID doesn't change, so references
+ * are already valid — but the name stored in package.xml is updated).
+ *
+ * ```ts
+ * await doc.transform(rename({
+ *   packageName: 'Basics',
+ *   resourceName: 'Button',
+ *   newName: 'PrimaryButton',
+ * }));
+ * ```
+ */
+declare function rename(options: RenameOptions): Transform;
+//#endregion
+//#region src/atlas.d.ts
+interface AtlasOptions {
+  /**
+   * Sharp module instance, injected by the caller.
+   * Required for actual image compositing and trimImage.
+   *
+   * ```ts
+   * import sharp from 'sharp';
+   * await doc.transform(atlas({ encoder: sharp }));
+   * ```
+   */
+  encoder?: unknown;
+  /** Maximum atlas texture size (width and height). Default: 2048. */
+  maxSize?: number;
+  /** Whether to use the fast editor-compatible packing heuristics. Default: true. */
+  fast?: boolean;
+  /** Allow rotating sprites 90° for better packing. Default: true. */
+  allowRotation?: boolean;
+  /** Pixel padding between sprites. Default: 1. */
+  padding?: number;
+  /** Constrain atlas dimensions to powers of two. Default: false. */
+  powerOfTwo?: boolean;
+  /** Force square atlas (width === height). Default: false. */
+  square?: boolean;
+  /** Allow spilling into multiple atlas pages. Default: true. */
+  multiPage?: boolean;
+  /**
+   * Trim transparent pixels from image edges before packing.
+   * Requires encoder (sharp). Stores offset/originalSize in Sprite nodes.
+   * Default: false.
+   */
+  trimImage?: boolean;
+  /**
+   * Base path for reading source images. If not set, images must have
+   * their pixel data stored in extras._imageData as Uint8Array.
+   */
+  basePath?: string;
+  /**
+   * Output directory for generated atlas PNGs.
+   * Required when encoder is provided.
+   */
+  outputPath?: string;
+  /**
+   * Optional mkdir function to ensure output directory exists.
+   * If not provided, the outputPath directory must already exist.
+   */
+  mkdir?: (path: string) => Promise<void>;
+  /**
+   * Optional raw file reader for reading .jta MovieClip files.
+   * Required for MovieClip frame atlas packing.
+   */
+  readFileRaw?: (path: string) => Promise<Uint8Array>;
+  /**
+   * Keep original input order when MaxRects tie-break scores are equal.
+   * This is an internal publish detail used to mirror editor/CLI behavior.
+   */
+  preserveInputOrderOnTie?: boolean;
+  /**
+   * Internal publish detail used by Unity binary output:
+   * allow single untrimmed PNG image packages to bypass the packer and
+   * write atlas0 directly, matching the reference CLI behavior.
+   */
+  directSingleImageOutput?: boolean;
+  /**
+   * Internal publish detail used by the direct-image-output path.
+   * When extractAlpha is enabled, the direct output shortcut must be disabled.
+   */
+  extractAlpha?: boolean;
+  /**
+   * When branchProcessing keeps branch resources, publish branch images into
+   * separate atlas pages/files per branch instead of mixing them with main.
+   */
+  separatedAtlasForBranch?: boolean;
+}
+/**
+ * Packs image resources into texture atlases.
+ *
+ * This transform performs MaxRects bin-packing on all ImageResource items
+ * within each package, creating Atlas and Sprite property nodes. When an
+ * `encoder` (sharp) is provided, it also composites the actual PNG files.
+ *
+ * When `trimImage` is enabled and encoder is available, transparent pixels
+ * at image edges are trimmed before packing. The trimmed offset and original
+ * dimensions are stored in the Sprite nodes for runtime reconstruction.
+ *
+ * ```ts
+ * import sharp from 'sharp';
+ * await doc.transform(atlas({
+ *   encoder: sharp,
+ *   maxSize: 2048,
+ *   trimImage: true,
+ *   basePath: './assets/',
+ *   outputPath: './dist/',
+ * }));
+ * ```
+ */
+declare function atlas(_options?: AtlasOptions): Transform;
+//#endregion
+//#region src/shared-types.d.ts
+type ExtrasMap = Record<string, unknown>;
+interface CliCodeGenerationSettings extends NonNullable<PublishSettings['codeGeneration']> {
+  allowGenCode?: boolean;
+  classNamePrefix?: string;
+  codePath?: string;
+  codeType?: string;
+  getMemberByName?: boolean;
+  ignoreNoname?: boolean;
+  memberNamePrefix?: string;
+  packageName?: string;
+}
+interface CliAtlasSettings extends NonNullable<PublishSettings['atlasSetting']> {
+  maxSize?: number;
+  paging?: boolean;
+  sizeOption?: string;
+  forceSquare?: boolean;
+  fast?: boolean;
+  allowRotation?: boolean;
+  padding?: number;
+  trimImage?: boolean;
+  extractAlpha?: boolean;
+}
+interface CliPublishSettings extends PublishSettings {
+  atlasSetting?: CliAtlasSettings;
+  codeGeneration?: CliCodeGenerationSettings;
+}
+type RootProjectSettings = ProjectSettings & {
+  publish?: CliPublishSettings;
+};
+interface PublishDependency {
+  id: string;
+  name: string;
+}
+interface HasOptionalFont {
+  getFont?(): string | string[] | null | undefined;
+}
+interface HasOptionalSrc {
+  getSrc?(): string | undefined;
+}
+interface HasOptionalUrl {
+  getUrl?(): string | undefined;
+}
+type PublishFileSystem = Pick<FileSystem, 'join' | 'mkdir' | 'writeFileRaw'> & {
+  deleteFile?: (path: string) => Promise<void>;
+  exists?: FileSystem['exists'];
+  readdir?: FileSystem['readdir'];
+  readFileRaw?: FileSystem['readFileRaw'];
+};
+//#endregion
+//#region src/codegen.d.ts
+declare const AUTO_GENERATED_CODE_MARK = "/** This is an automatically generated class by FairyGUI. Please do not modify it. **/";
+interface PublishCodeGenerationOptions {
+  basePath?: string;
+  fs: PublishFileSystem;
+  packages: Package[];
+}
+declare function publishCodeGeneration(doc: Document, options: PublishCodeGenerationOptions): Promise<void>;
+//#endregion
+//#region src/publish.d.ts
+interface PublishOptions {
+  /**
+   * Output directory for published files (.fui + atlas PNGs).
+   * Required.
+   */
+  output: string;
+  /**
+   * Compress the binary data with zlib raw deflate. Default: false.
+   */
+  compressed?: boolean;
+  /**
+   * File extension for the binary output. Default: 'fui'.
+   * Unity projects typically use 'bytes'.
+   */
+  fileExtension?: string;
+  /**
+   * Sharp module instance for atlas image compositing.
+   * If not provided, atlas packing only computes layout (no PNGs generated).
+   */
+  encoder?: unknown;
+  /**
+   * Base path for reading source images (project assets root).
+   * Required when encoder is provided.
+   */
+  basePath?: string;
+  /**
+   * Atlas packing options.
+   */
+  atlas?: Omit<AtlasOptions, 'encoder' | 'basePath' | 'outputPath'>;
+  /**
+   * Filter which packages to publish by name. If not set, all packages are published.
+   */
+  packages?: string[];
+  /**
+   * FileSystem abstraction for writing output files.
+   * Required for actual file output. Without it, only the Document model
+   * is updated (atlas layout computed, sprite nodes created).
+   */
+  fs?: PublishFileSystem;
+  /**
+   * Active branch name used when branchProcessing is "主干合并活跃分支".
+   * Empty or omitted means publishing the main branch.
+   */
+  branch?: string;
+}
+interface ResolvedPublishAtlasOptions extends Pick<AtlasOptions, 'maxSize' | 'fast' | 'allowRotation' | 'padding' | 'powerOfTwo' | 'square' | 'multiPage' | 'trimImage' | 'extractAlpha'> {}
+interface ResolvePublishOptionsOverrides {
+  compressed?: boolean;
+  fileExtension?: string;
+  packages?: string[];
+  atlas?: Partial<ResolvedPublishAtlasOptions>;
+}
+interface ResolvedPublishOptions {
+  compressed: boolean;
+  fileExtension: string;
+  packages?: string[];
+  atlas: ResolvedPublishAtlasOptions;
+}
+/**
+ * Resolve publish defaults from the document's project settings.
+ *
+ * This keeps the editor-aligned publish rules reusable across environments,
+ * while callers still provide environment-specific concerns such as fs/encoder/basePath.
+ */
+declare function resolvePublishOptions(doc: Document, overrides?: ResolvePublishOptionsOverrides): ResolvedPublishOptions;
+/**
+ * Publishes a FairyGUI project.
+ *
+ * Orchestrates:
+ * 1. Atlas packing (MaxRects layout + optional sharp compositing)
+ * 2. Per-package .fui binary serialization
+ * 3. File writing to the output directory
+ *
+ * ```ts
+ * import sharp from 'sharp';
+ * const io = new NodeIO();
+ * const doc = await io.readProject('./project.fairy');
+ *
+ * await doc.transform(publish({
+ *   output: './release/',
+ *   compressed: true,
+ *   encoder: sharp,
+ *   basePath: './assets/',
+ *   fileExtension: 'bytes',
+ *   fs: io.createFileSystem(),
+ * }));
+ * ```
+ */
+declare function publish(options: PublishOptions): Transform;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Wraps a transform function, assigning it a name for the transform stack.
+ */
+declare function createTransform(name: string, fn: Transform): Transform;
+//#endregion
+export { AUTO_GENERATED_CODE_MARK, type AtlasOptions, type CliAtlasSettings, type CliPublishSettings, type ExtrasMap, type HasOptionalFont, type HasOptionalSrc, type HasOptionalUrl, type InspectCategoryReport, type InspectReport, type PruneOptions, type PublishCodeGenerationOptions, type PublishDependency, type PublishFileSystem, type PublishOptions, type RenameOptions, type ResolvePublishOptionsOverrides, type ResolvedPublishAtlasOptions, type ResolvedPublishOptions, type RootProjectSettings, type ValidateOptions, type ValidationIssue, type ValidationResult, ValidationSeverity, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, validate };