@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1-beta.20250704.94554

package/src/foundry/client/helpers/localization.d.mts

@@ -0,0 +1,240 @@
+import type { DotKeys, Identity, InexactPartial } from "#utils";
+
+/**
+ * A helper class which assists with localization and string translation
+ */
+declare class Localization {
+  /**
+   * @param serverLanguage - The default language configuration setting for the server
+   */
+  constructor(serverLanguage?: string);
+
+  /**
+   * The target language for localization
+   * @defaultValue `"en"`
+   */
+  lang: string;
+
+  /**
+   * The package authorized to provide default language configurations
+   * @defaultValue `"core"`
+   */
+  defaultModule: string;
+
+  /**
+   * The translation dictionary for the target language
+   * @defaultValue `{}`
+   */
+  translations: Localization.Translations;
+
+  /**
+   * Fallback translations if the target keys are not found
+   * @internal
+   * @defaultValue `{}`
+   */
+  protected _fallback: Localization.Translations;
+
+  /**
+   * Initialize the Localization module
+   * Discover available language translations and apply the current language setting
+   * @returns A Promise which resolves once languages are initialized
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Perform one-time localization of the fields in a DataModel schema, translating their label and hint properties.
+   * @param model   - The DataModel class to localize
+   * @param options - Options which configure how localization is performed
+   *
+   * @example
+   * JavaScript class definition and localization call.
+   * ```js
+   * class MyDataModel extends foundry.abstract.DataModel {
+   *   static defineSchema() {
+   *     return {
+   *       foo: new foundry.data.fields.StringField(),
+   *       bar: new foundry.data.fields.NumberField()
+   *     };
+   *   }
+   *   static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];
+   * }
+   *
+   * Hooks.on("i18nInit", () => {
+   *   Localization.localizeDataModel(MyDataModel);
+   * });
+   * ```
+   *
+   * JSON localization file
+   * ```json
+   * {
+   *   "MYMODULE": {
+   *     "MYDATAMODEL": {
+   *       "FIELDS" : {
+   *         "foo": {
+   *           "label": "Foo",
+   *           "hint": "Instructions for foo"
+   *         },
+   *         "bar": {
+   *           "label": "Bar",
+   *           "hint": "Instructions for bar"
+   *         }
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  static localizeDataModel(
+    model: foundry.abstract.DataModel.AnyConstructor,
+    options?: Localization.LocalizeDataModelOptions,
+  ): void;
+
+  /**
+   * Localize the "label" and "hint" properties for all fields in a data schema.
+   */
+  static localizeSchema(
+    schema: foundry.data.fields.SchemaField.Any,
+
+    /** @defaultValue `[]` */
+    prefixes?: string[],
+    options?: Localization.LocalizeSchemaOptions,
+  ): void;
+
+  /**
+   * Set a language as the active translation source for the session
+   * @param lang - A language string in CONFIG.supportedLanguages
+   * @returns A Promise which resolves once the translations for the requested language are ready
+   */
+  setLanguage(lang: string): Promise<void>;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _discoverSupportedLanguages(): never;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _getTranslations(lang: never): never;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _filterLanguagePaths(pkg: never, lang: never): never;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _loadTranslationFile(src: never): never;
+
+  /**
+   * Return whether a certain string has a known translation defined.
+   * @param stringId - The string key being translated
+   * @param fallback - Allow fallback translations to count? (default: `true`)
+   */
+  has(stringId: string, fallback?: boolean): boolean;
+
+  /**
+   * Localize a string by drawing a translation from the available translations dictionary, if available
+   * If a translation is not available, the original string is returned
+   * @param stringId - The string ID to translate
+   * @returns The translated string
+   *
+   * @example <caption>Localizing a simple string in JavaScript</caption>
+   * ```typescript
+   * {
+   *   "MYMODULE.MYSTRING": "Hello, this is my module!"
+   * }
+   * game.i18n.localize("MYMODULE.MYSTRING"); // Hello, this is my module!
+   * ```
+   *
+   * @example <caption>Localizing a simple string in Handlebars</caption>
+   * ```handlebars
+   * {{localize "MYMODULE.MYSTRING"}} <!-- Hello, this is my module! -->
+   * ```
+   */
+  localize(stringId: string): string;
+
+  /**
+   * Localize a string including variable formatting for input arguments.
+   * Provide a string ID which defines the localized template.
+   * Variables can be included in the template enclosed in braces and will be substituted using those named keys.
+   *
+   * @param stringId - The string ID to translate
+   * @param data     - Provided input data (default: `{}`)
+   * @returns The translated and formatted string
+   *
+   * @example <caption>Localizing a formatted string in JavaScript</caption>
+   * ```typescript
+   * {
+   *   "MYMODULE.GREETING": "Hello {name}, this is my module!"
+   * }
+   * game.i18n.format("MYMODULE.GREETING" {name: "Andrew"}); // Hello Andrew, this is my module!
+   * ```
+   *
+   * @example <caption>Localizing a formatted string in Handlebars</caption>
+   * ```handlebars
+   * {{localize "MYMODULE.GREETING" name="Andrew"}} <!-- Hello, this is my module! -->
+   * ```
+   */
+  format(stringId: string, data?: Record<string, string>): string;
+
+  /**
+   * Retrieve list formatter configured to the world's language setting.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat | Intl.ListFormat}
+   */
+  getListFormatter(options?: Localization.GetListFormatterOptions): Intl.ListFormat;
+
+  /**
+   * Sort an array of objects by a given key in a localization-aware manner.
+   * @param objects - The objects to sort, this array will be mutated
+   * @param key     - The key to sort the objects by. This can be provided in dot-notation.
+   */
+  sortObjects<T extends object>(objects: Array<T>, key: DotKeys<T>): T[];
+
+  #Localization: true;
+}
+
+declare namespace Localization {
+  interface Any extends AnyLocalization {}
+  interface AnyConstructor extends Identity<typeof AnyLocalization> {}
+
+  interface Translations {
+    [K: string]: string | Translations;
+  }
+
+  interface LocalizeDataModelOptions {
+    /**
+     * An array of localization key prefixes to use. If not specified, prefixes
+     * are learned from the DataModel.LOCALIZATION_PREFIXES static property.
+     */
+    prefixes?: string[] | undefined;
+
+    /**
+     * A localization path prefix used to prefix all field names within this model. This is generally not required.
+     */
+    prefixPath?: string | undefined;
+  }
+
+  type _LocalizeSchemaOptions = InexactPartial<{
+    /**
+     * @defaultValue `new Set()`
+     * @remarks Used for recursive calls, not intended to be passed externally
+     */
+    seenFields: Set<foundry.data.fields.DataField.Any>;
+  }>;
+
+  interface LocalizeSchemaOptions extends _LocalizeSchemaOptions, Pick<LocalizeDataModelOptions, "prefixPath"> {}
+
+  interface GetListFormatterOptions {
+    /**
+     * The list formatter style, either "long", "short", or "narrow".
+     * @defaultValue `"long"`
+     */
+    style?: Intl.ListFormatStyle | undefined;
+
+    /**
+     * The list formatter type, either "conjunction", "disjunction", or "unit".
+     * @defaultValue `"conjunction"`
+     */
+    type?: Intl.ListFormatType | undefined;
+  }
+}
+
+export default Localization;
+
+declare abstract class AnyLocalization extends Localization {
+  constructor(...args: never);
+}

package/src/foundry/client/helpers/media/_module.d.mts

@@ -0,0 +1,8 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+export { default as CompendiumArt } from "./compendium-art.mjs";
+export { default as ImageHelper } from "./image-helper.mjs";
+export { default as VideoHelper } from "./video-helper.mjs";

package/src/foundry/client/helpers/media/compendium-art.d.mts

@@ -0,0 +1,107 @@
+import type { SchemaField } from "#common/data/fields.d.mts";
+import type { Identity } from "#utils";
+import type { PrototypeToken } from "../../data/_module.d.mts";
+
+/**
+ * A class responsible for managing package-provided art and applying it to Documents in compendium packs.
+ */
+declare class CompendiumArt extends Map<string, CompendiumArt.Info> {
+  /**
+   * @remarks
+   * @throws "You may not re-initialize the singleton {@linkcode CompendiumArt}. Use {@linkcode game.compendiumArt} instead."
+   */
+  constructor(iterable?: Iterable<[string, CompendiumArt.Info]> | null);
+
+  /**
+   * The key for the package manifest flag used to store the mapping information.
+   * @defaultValue `"compendiumArtMappings"`
+   */
+  FLAG: string;
+
+  /**
+   * The key for the setting used to store the World's art preferences.
+   * @defaultValue `"compendiumArtConfiguration"`
+   */
+  SETTING: string;
+
+  /**
+   * Whether art application is enabled. This should be switched off when performing client-side compendium migrations
+   * in order to avoid persisting injected data.
+   * @defaultValue `true`
+   */
+  enabled: boolean;
+
+  /**
+   * Retrieve all active packages that provide art mappings in priority order.
+   */
+  getPackages(): CompendiumArt.Descriptor[];
+
+  /**
+   * Collate Document art mappings from active packages.
+   * @internal
+   */
+  protected _registerArt(): Promise<void>;
+
+  #CompendiumArt: true;
+}
+
+declare namespace CompendiumArt {
+  interface Any extends AnyCompendiumArt {}
+  interface AnyConstructor extends Identity<typeof CompendiumArt> {}
+
+  interface Info {
+    /**
+     * The path to the Actor's portrait image.
+     */
+    actor?: string | undefined;
+
+    /**
+     * The path to the token image, or an object to merge into the Actor's prototype token.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    token?: string | SchemaField.AssignmentData<PrototypeToken.Schema> | undefined;
+
+    /**
+     *An optional credit string for use by the game system to apply in an appropriate place.
+     */
+    credit?: string | undefined;
+  }
+
+  /**
+   * A mapping of compendium pack IDs to Document IDs to art information.
+   */
+  type Mapping = Record<string, Record<string, Info>>;
+
+  interface Descriptor {
+    /**
+     * The ID of the package providing the art.
+     */
+    packageId: string;
+
+    /**
+     * The title of the package providing the art.
+     */
+    title: string;
+
+    /**
+     * The path to the art mapping file.
+     */
+    mapping: string;
+
+    /**
+     * An optional credit string for use by the game system to apply in an appropriate place.
+     */
+    credit: string | undefined;
+
+    /**
+     * The package's user-configured priority.
+     */
+    priority: number;
+  }
+}
+
+export default CompendiumArt;
+
+declare abstract class AnyCompendiumArt extends CompendiumArt {
+  constructor(...args: never);
+}

package/src/foundry/client/helpers/media/image-helper.d.mts

@@ -0,0 +1,235 @@
+import type { Identity, InexactPartial, ValueOf } from "#utils";
+import type FilePicker from "#client/applications/apps/file-picker.mjs";
+
+/**
+ * A helper class to provide common functionality for working with Image objects
+ */
+declare class ImageHelper {
+  /**
+   * Create thumbnail preview for a provided image path.
+   * @param src     - The string URL or DisplayObject of the texture to render to a thumbnail
+   * @param options - Additional named options passed to the {@linkcode ImageHelper.compositeCanvasTexture} method (default: `{}`)
+   * @returns The parsed and converted thumbnail data
+   */
+  static createThumbnail(
+    src: string | PIXI.DisplayObject,
+    options?: ImageHelper.CreateThumbnailOptions,
+  ): Promise<ImageHelper.ThumbnailReturn | null>;
+
+  /**
+   * Test whether a source file has a supported image extension type
+   * @param src - A requested image source path
+   * @returns Does the filename end with a valid image extension?
+   */
+  static hasImageExtension(src: string): boolean;
+
+  /**
+   * Composite a canvas object by rendering it to a single texture
+   * @param object  - The DisplayObject to render to a texture
+   * @param options - Additional named options (default: `{}`)
+   * @returns The composite Texture object
+   */
+  static compositeCanvasTexture(object: PIXI.DisplayObject, options?: ImageHelper.CompositeOptions): PIXI.Texture;
+
+  /**
+   * Extract a texture to a base64 PNG string
+   * @param texture - The Texture object to extract
+   * @param options - (default: `{}`)
+   * @returns A base64 png string of the texture
+   */
+  static textureToImage(texture: PIXI.Texture, options?: ImageHelper.TextureToImageOptions): Promise<string>;
+
+  /**
+   * Asynchronously convert a DisplayObject container to base64 using Canvas#toBlob and FileReader
+   * @param target  - A PIXI display object to convert
+   * @param type    - The requested mime type of the output, default is image/png
+   * @param quality - A number between 0 and 1 for image quality if image/jpeg or image/webp
+   * @returns A processed base64 string
+   * @privateRemarks Foundry doesn't mark `type` or `quality` as optional, but they're passed directly to `this.canvasToBase64`, where they *are* optional.
+   */
+  static pixiToBase64(
+    target: PIXI.DisplayObject,
+    type?: ImageHelper.IMAGE_MIME_TYPES,
+    quality?: number,
+  ): Promise<string>;
+
+  /**
+   * Asynchronously convert a canvas element to base64.
+   * @param type    - (default: `"image/png"`)
+   * @param quality - JPEG or WEBP compression from 0 to 1. Default is 0.92.
+   * @returns The base64 string of the canvas.
+   */
+  static canvasToBase64(
+    canvas: HTMLCanvasElement,
+    type?: ImageHelper.IMAGE_MIME_TYPES,
+    quality?: number,
+  ): Promise<string>;
+
+  /**
+   * Upload a base64 image string to a persisted data storage location
+   * @param base64   - The base64 string
+   * @param fileName - The file name to upload
+   * @param filePath - The file path where the file should be uploaded
+   * @param options  - Additional options which affect uploading
+   * @returns A promise which resolves to the FilePicker upload response
+   */
+  static uploadBase64(
+    base64: string,
+    fileName: string,
+    filePath: string,
+    options?: ImageHelper.UploadBase64Options,
+  ): Promise<FilePicker.UploadReturn>;
+
+  /**
+   * Create a canvas element containing the pixel data.
+   * @param pixels - Buffer used to create the image data.
+   * @param width  - Buffered image width.
+   * @param height - Buffered image height.
+   */
+  static pixelsToCanvas(
+    pixels: Uint8ClampedArray,
+    width: number,
+    height: number,
+    options?: ImageHelper.PixelsToCanvasOptions,
+  ): HTMLCanvasElement;
+}
+
+declare namespace ImageHelper {
+  interface Any extends AnyImageHelper {}
+  interface AnyConstructor extends Identity<typeof AnyImageHelper> {}
+
+  type IMAGE_MIME_TYPES = ValueOf<typeof CONST.IMAGE_FILE_EXTENSIONS>;
+
+  /** @internal */
+  type _CompositeOptions = InexactPartial<{
+    /**
+     * Center the texture in the rendered frame?
+     * @defaultValue `true`
+     */
+    center: boolean;
+
+    /**
+     * The desired height of the output texture
+     * @defaultValue The height of the object passed to {@linkcode ImageHelper.compositeCanvasTexture}
+     */
+    height: number;
+
+    /**
+     * A horizontal translation to apply to the object
+     * @defaultValue `0`
+     */
+    tx: number;
+
+    /**
+     * A vertical translation to apply to the object
+     * @defaultValue `0`
+     */
+    ty: number;
+
+    /**
+     * The desired width of the output texture
+     * @defaultValue The width of the object passed to {@linkcode ImageHelper.compositeCanvasTexture}
+     */
+    width: number;
+  }>;
+
+  /**
+   * An interface for options for the {@linkcode ImageHelper.createThumbnail} and {@linkcode ImageHelper.compositeCanvasTexture}
+   * methods.
+   */
+  interface CompositeOptions extends _CompositeOptions {}
+
+  interface CreateThumbnailOptions extends CompositeOptions, TextureToImageOptions {}
+
+  /** @internal */
+  type _TextureToImageOptions = InexactPartial<{
+    /**
+     * Image format, e.g. "image/jpeg" or "image/webp".
+     * @defaultValue `"image/png"`
+     */
+    format: IMAGE_MIME_TYPES;
+
+    /**
+     * JPEG or WEBP compression from 0 to 1. Default is 0.92.
+     * @defaultValue `0.92`
+     */
+    quality: number;
+  }>;
+
+  interface TextureToImageOptions extends _TextureToImageOptions {}
+
+  /** @internal */
+  type _UploadBase64Options = InexactPartial<{
+    /**
+     * The data storage location to which the file should be uploaded
+     * @defaultValue `"data"`
+     */
+    storage: FilePicker.SourceType;
+
+    /**
+     * The MIME type of the file being uploaded
+     * @remarks Will be extracted from the base64 data, if not provided.
+     */
+    type: IMAGE_MIME_TYPES;
+
+    /**
+     * Display a UI notification when the upload is processed.
+     * @defaultValue `true`
+     */
+    notify: boolean;
+  }>;
+
+  interface UploadBase64Options extends _UploadBase64Options {}
+
+  /**
+   * An interface for return values of the {@linkcode ImageHelper.createThumbnail} method.
+   */
+  interface ThumbnailReturn {
+    /**
+     * The height of the {@linkcode PIXI.Sprite}, created by {@linkcode ImageHelper.createThumbnail}
+     */
+    height: number;
+
+    /**
+     * The originally passed `string` URL or DisplayObject
+     */
+    src: string | PIXI.DisplayObject;
+
+    /**
+     * The Texture, returned from {@linkcode ImageHelper.compositeCanvasTexture}, with `destroy(true)` already called on it.
+     */
+    texture: PIXI.Texture;
+
+    /**
+     * The base64 encoded image data, returned from {@linkcode ImageHelper.textureToImage}
+     */
+    thumb: string;
+
+    /**
+     * The width of the {@linkcode PIXI.Sprite}, created by {@linkcode ImageHelper.createThumbnail}
+     */
+    width: number;
+  }
+
+  type _PixelsToCanvasOptions = InexactPartial<{
+    /**
+     * The element to use.
+     * @remarks If not provided, a new HTMLCanvasElement is created.
+     */
+    element: HTMLCanvasElement;
+
+    /** Specified width for the element (default to buffer image width). */
+    ew: number;
+
+    /** Specified height for the element (default to buffer image height). */
+    eh: number;
+  }>;
+
+  interface PixelsToCanvasOptions extends _PixelsToCanvasOptions {}
+}
+
+export default ImageHelper;
+
+declare abstract class AnyImageHelper extends ImageHelper {
+  constructor(...args: never);
+}