@7h3laughingman/foundry-types 13.351.0

package/src/client/nue/tour.d.mts

@@ -0,0 +1,283 @@
+import { TooltipDirection } from "./../helpers/interaction/tooltip-manager.mjs";
+
+/**
+ * A step in a Tour
+ */
+interface TourStep {
+    /** A machine-friendly id of the Tour Step */
+    id: string;
+
+    /** The title of the step, displayed in the tooltip header */
+    title: string;
+
+    /** Raw HTML content displayed during the step */
+    content: string;
+
+    /**
+     * A DOM selector which denotes an element to highlight during this step. If omitted, the step is displayed in the
+     * center of the screen.
+     */
+    selector?: string;
+
+    /**
+     * How the tooltip for the step should be displayed relative to the target element. If omitted, the best direction
+     * will be attempted to be auto-selected.
+     */
+    tooltipDirection?: TooltipDirection;
+
+    /** Whether the Step is restricted to the GM only. Defaults to false. */
+    restricted?: boolean;
+
+    /** Activates a particular sidebar tab. Usable in `SidebarTour` instances. */
+    sidebarTab?: string;
+
+    /** Activates a particular canvas layer and its respective control group. Usable in `CanvasTour` instances. */
+    layer?: string;
+
+    /** Activates a particular tool. Usable in `CanvasTour` instances. */
+    tool?: string;
+}
+
+/**
+ * Tour configuration data
+ */
+interface TourConfig {
+    /** The namespace this Tour belongs to. Typically, the name of the package which implements the tour should use */
+    namespace: string;
+
+    /** A machine-friendly id of the Tour, must be unique within the provided namespace */
+    id: string;
+
+    /** A human-readable name for this Tour. Localized. */
+    title: string;
+
+    /** The list of Tour Steps */
+    steps: TourStep[];
+
+    /** A human-readable description of this Tour. Localized. */
+    description?: string;
+
+    /** A map of localizations for the Tour that should be merged into the default localizations */
+    localization?: object;
+
+    /** Whether the Tour is restricted to the GM only. Defaults to false. */
+    restricted?: boolean;
+
+    /** Whether the Tour should be displayed in the Manage Tours UI. Defaults to false. */
+    display?: boolean;
+
+    /** Whether the Tour can be resumed or if it always needs to start from the beginning. Defaults to false. */
+    canBeResumed?: boolean;
+
+    /**
+     * A list of namespaced Tours that might be suggested to the user when this Tour is completed. The first
+     * non-completed Tour in the array will be recommended.
+     */
+    suggestedNextTours?: string[];
+}
+
+/**
+ * A Tour that shows a series of guided steps.
+ */
+export default abstract class Tour {
+    /**
+     * Construct a Tour by providing a configuration.
+     * @param config The configuration of the Tour
+     * @param options Additional options for configuring the tour
+     * @param options.id A tour ID that supercedes TourConfig#id
+     * @param options.namespace A tour namespace that supercedes TourConfig#namespace
+     */
+    constructor(config: TourConfig, options?: { id?: string; namespace?: string });
+
+    static STATUS: Readonly<{
+        UNSTARTED: "unstarted";
+        IN_PROGRESS: "in-progress";
+        COMPLETED: "completed";
+    }>;
+
+    /**
+     * Indicates if a Tour is currently in progress.
+     */
+    static get tourInProgress(): boolean;
+
+    /**
+     * Returns the active Tour, if any
+     */
+    static get activeTour(): Tour | null;
+
+    /**
+     * Handle a movement action to either progress or regress the Tour.
+     * @param movementDirections The Directions being moved in
+     */
+    static onMovementAction(movementDirections: string[]): true | void;
+
+    /**
+     * Configuration of the tour. This object is cloned to avoid mutating the original configuration.
+     */
+    config: TourConfig;
+
+    /**
+     * The HTMLElement which is the focus of the current tour step.
+     */
+    targetElement: HTMLElement;
+
+    /**
+     * The HTMLElement that fades out the rest of the screen
+     */
+    fadeElement: HTMLElement;
+
+    /**
+     * The HTMLElement that blocks input while a Tour is active
+     */
+    overlayElement: HTMLElement;
+
+    /**
+     * Padding around a Highlighted Element
+     */
+    static HIGHLIGHT_PADDING: number;
+
+    /**
+     * The unique identifier of the tour.
+     */
+    get id(): string;
+
+    set id(value: string);
+
+    /**
+     * The human-readable title for the tour.
+     */
+    get title(): string;
+
+    /**
+     * The human-readable description of the tour.
+     */
+    get description(): string;
+
+    /**
+     * The package namespace for the tour.
+     */
+    get namespace(): string;
+
+    set namespace(value: string);
+
+    /**
+     * The key the Tour is stored under in game.tours, of the form `${namespace}.${id}`
+     */
+    get key(): string;
+
+    /**
+     * The configuration of tour steps
+     */
+    get steps(): TourStep[];
+
+    /**
+     * Return the current Step, or null if the tour has not yet started.
+     */
+    get currentStep(): TourStep | null;
+
+    /**
+     * The index of the current step; -1 if the tour has not yet started, or null if the tour is finished.
+     */
+    get stepIndex(): number | null;
+
+    /**
+     * Returns True if there is a next TourStep
+     */
+    get hasNext(): boolean;
+
+    /**
+     * Returns True if there is a previous TourStep
+     */
+    get hasPrevious(): boolean;
+
+    /**
+     * Return whether this Tour is currently eligible to be started?
+     * This is useful for tours which can only be used in certain circumstances, like if the canvas is active.
+     */
+    get canStart(): boolean;
+
+    /**
+     * The current status of the Tour
+     */
+    get status(): TourStatus;
+
+    /* -------------------------------------------- */
+    /*  Tour Methods                                */
+    /* -------------------------------------------- */
+
+    /**
+     * Advance the tour to a completed state.
+     */
+    complete(): Promise<void>;
+
+    /**
+     * Exit the tour at the current step.
+     */
+    exit(): void;
+
+    /**
+     * Reset the Tour to an un-started state.
+     */
+    reset(): Promise<void>;
+
+    /**
+     * Start the Tour at its current step, or at the beginning if the tour has not yet been started.
+     */
+    start(): Promise<void>;
+
+    /**
+     * Progress the Tour to the next step.
+     */
+    next(): Promise<void>;
+
+    /**
+     * Rewind the Tour to the previous step.
+     */
+    previous(): Promise<void>;
+
+    /**
+     * Progresses to a given Step
+     * @param stepIndex The step to progress to
+     */
+    progress(stepIndex: number): Promise<void>;
+
+    /**
+     * Query the DOM for the target element using the provided selector
+     * @param selector A CSS selector
+     * @returns The target element, or null if not found
+     */
+    protected _getTargetElement(selector: string): HTMLElement | null;
+
+    /**
+     * Creates and returns a Tour by loading a JSON file
+     * @param filepath The path to the JSON file
+     */
+    static fromJSON(filepath: string): Promise<Tour>;
+
+    /* -------------------------------------------- */
+    /*  Event Handlers                              */
+    /* -------------------------------------------- */
+
+    /**
+     * Set-up operations performed before a step is shown.
+     */
+    protected abstract _preStep(): Promise<void>;
+
+    /**
+     * Clean-up operations performed after a step is completed.
+     */
+    protected abstract _postStep(): Promise<void>;
+
+    /**
+     * Renders the current Step of the Tour
+     */
+    protected _renderStep(): Promise<void>;
+
+    /**
+     * Reloads the Tour's current step from the saved progress
+     * @internal
+     */
+    _reloadProgress(): void;
+}
+
+export type TourStatus = (typeof Tour.STATUS)[keyof typeof Tour.STATUS];

package/src/client/nue/tours/_module.d.mts

@@ -0,0 +1 @@
+export {};

package/src/client/nue/tours-collection.d.mts

@@ -0,0 +1,23 @@
+import Collection from "./../../common/utils/collection.mjs";
+import Tour from "./tour.mjs";
+
+/**
+ * A singleton Tour Collection class responsible for registering and activating Tours, accessible as game.tours.
+ * @see {@link foundry.Game#tours}
+ */
+export default class ToursCollection extends Collection<string, Tour> {
+    constructor();
+
+    /**
+     * Register a new Tour.
+     * @param namespace The namespace of the Tour
+     * @param id The machine-readable id of the Tour
+     * @param tour The constructed Tour
+     */
+    register(namespace: string, id: string, tour: Tour): void;
+
+    /**
+     * Set a Tour to the collection.
+     */
+    override set(key: string, tour: Tour): this;
+}

package/src/client/packages/_module.d.mts

@@ -0,0 +1,19 @@
+/** @module packages */
+
+import Module from "./module.mjs";
+import System from "./system.mjs";
+import World from "./world.mjs";
+
+export * from "./../../common/packages/_module.mjs";
+export * from "./_types.mjs";
+export { default as ClientPackageMixin } from "./client-package.mts";
+export { Module, System, World };
+
+/**
+ * A mapping of allowed package types and the classes which implement them.
+ */
+export const PACKAGE_TYPES: Readonly<{
+    world: World;
+    system: System;
+    module: Module;
+}>;

package/src/client/packages/_types.d.mts

@@ -0,0 +1,12 @@
+export * from "./../../common/packages/_types.mjs";
+
+export interface PackageCompatibilityBadge {
+    /** A type in "safe", "unsafe", "warning", "neutral" applied as a CSS class */
+    type: string;
+    /** A tooltip string displayed when hovering over the badge */
+    tooltip: string;
+    /** An optional text label displayed in the badge */
+    label?: string;
+    /** An optional icon displayed in the badge */
+    icon?: string;
+}

package/src/client/packages/client-package.mts

@@ -0,0 +1,145 @@
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+import Collection from "./../../common/utils/collection.mjs";
+import { BasePackage, Module, RelatedPackage, System } from "./_module.mjs";
+import { PackageCompatibilityBadge, PackageManifestData } from "./_types.mjs";
+
+/**
+ * A client-side mixin used for all Package types.
+ */
+
+export default function ClientPackageMixin<TBase extends ConstructorOf<BasePackage>>(BasePackage: TBase) {
+    class ClientPackage extends BasePackage {
+        /**
+         * Is this package marked as a favorite?
+         * This boolean is currently only populated as true in the /setup view of the software.
+         */
+        declare favorite: boolean;
+
+        /**
+         * Associate package availability with certain badge for client-side display.
+         */
+        getVersionBadge(): PackageCompatibilityBadge | null {
+            return null;
+        }
+
+        /**
+         * Retrieve a Package of this type from its collection.
+         * @param id The package ID to retrieve
+         * @returns The retrieved package instance, or undefined
+         */
+        static get(id: string): ClientPackage | undefined {
+            id;
+            return undefined;
+        }
+
+        /* -------------------------------------------- */
+
+        /**
+         * Determine a version badge for the provided compatibility data.
+         * @param {number} availability                The availability level.
+         * @param {Partial<PackageManifestData>} data  The compatibility data.
+         * @param {object} [options]
+         * @param {Collection<string, Module>} [options.modules]  A specific collection of modules to test availability
+         *                                                        against. Tests against the currently installed modules by
+         *                                                        default.
+         * @param {Collection<string, System>} [options.systems]  A specific collection of systems to test availability
+         *                                                        against. Tests against the currently installed systems by
+         *                                                        default.
+         */
+        static getVersionBadge(
+            availability: number,
+            data: Partial<PackageManifestData>,
+            options?: { modules?: Collection<string, Module>; systems?: Collection<string, System> },
+        ): PackageCompatibilityBadge | null {
+            availability;
+            data;
+            options;
+            return null;
+        }
+
+        /**
+         * List missing dependencies and format them for display.
+         * @param {number} availability                The availability value.
+         * @param {Partial<PackageManifestData>} data  The compatibility data.
+         * @param {Iterable<RelatedPackage>} deps      The dependencies to format.
+         * @param {object} [options]
+         * @param {Collection<string, Module>} [options.modules]  A specific collection of modules to test availability
+         *                                                        against. Tests against the currently installed modules by
+         *                                                        default.
+         * @param {Collection<string, System>} [options.systems]  A specific collection of systems to test availability
+         *                                                        against. Tests against the currently installed systems by
+         *                                                        default.
+         * @returns {string}
+         * @protected
+         */
+        static _formatBadDependenciesTooltip(
+            availability: number,
+            data: Partial<PackageManifestData>,
+            deps: Iterable<RelatedPackage>,
+            options?: { modules?: Collection<string, Module>; systems?: Collection<string, System> },
+        ): string {
+            availability;
+            data;
+            deps;
+            options;
+            return "";
+        }
+
+        /* -------------------------------------------- */
+
+        /**
+         * List any installed systems that are incompatible with this module's systems relationship, and format them for
+         * display.
+         * @param {Partial<PackageManifestData>} data             The compatibility data.
+         * @param {Iterable<RelatedPackage>} relationships        The system relationships.
+         * @param {object} [options]
+         * @param {Collection<string, System>} [options.systems]  A specific collection of systems to test against. Tests
+         *                                                        against the currently installed systems by default.
+         * @returns {string}
+         * @protected
+         */
+        static _formatIncompatibleSystemsTooltip(
+            data: Partial<PackageManifestData>,
+            relationships: Iterable<RelatedPackage>,
+            options?: { systems?: Collection<string, System> },
+        ): string {
+            data;
+            relationships;
+            options;
+            return "";
+        }
+
+        /**
+         * When a package has been installed, add it to the local game data.
+         */
+        install(): void {}
+
+        /**
+         * When a package has been uninstalled, remove it from the local game data.
+         */
+        uninstall(): void {}
+
+        /**
+         * Remove a package from the local game data when it has been uninstalled.
+         * @param {string} id  The package ID.
+         */
+        static uninstall(id: string): void {
+            id;
+        }
+
+        /**
+         * Retrieve the latest Package manifest from a provided remote location.
+         * @param manifest A remote manifest URL to load
+         * @param options Additional options which affect package construction
+         * @param options.strict Whether to construct the remote package strictly
+         * @returns A Promise which resolves to a constructed ServerPackage instance
+         * @throws An error if the retrieved manifest data is invalid
+         */
+        static async fromRemoteManifest(manifest: string, options?: { strict?: boolean }): Promise<ClientPackage | null> {
+            manifest;
+            options;
+            return null;
+        }
+    }
+    return ClientPackage;
+}

package/src/client/packages/module.d.mts

@@ -0,0 +1,12 @@
+import { DataModelConstructionContext } from "./../../common/abstract/_types.mjs";
+import BaseModule, { ModuleSource } from "./../../common/packages/base-module.mjs";
+import ClientPackageMixin from "./client-package.mjs";
+
+export default class Module extends ClientPackageMixin(BaseModule) {
+    constructor(data: DeepPartial<ModuleSource> & { active: boolean }, options?: DataModelConstructionContext<null>);
+
+    /**
+     * Is this package currently active?
+     */
+    active: boolean;
+}

package/src/client/packages/system.d.mts

@@ -0,0 +1,9 @@
+import { DataModelConstructionContext } from "./../../common/abstract/_types.mjs";
+import BaseSystem, { SystemSource } from "./../../common/packages/base-system.mjs";
+import ClientPackageMixin from "./../packages/client-package.mjs";
+
+export default class System extends ClientPackageMixin(BaseSystem) {
+    constructor(data: DeepPartial<SystemSource>, options?: DataModelConstructionContext<null>);
+
+    protected override _configure(options?: Record<string, unknown>): void;
+}

package/src/client/packages/world.d.mts

@@ -0,0 +1,28 @@
+import { DataModelConstructionContext } from "./../../common/abstract/_types.mjs";
+import BaseWorld, { WorldSource } from "./../../common/packages/base-world.mjs";
+import Collection from "./../../common/utils/collection.mjs";
+import ClientPackageMixin from "./../packages/client-package.mjs";
+import { Module, PackageCompatibilityBadge, PackageManifestData, RelatedPackage, System } from "./_module.mjs";
+
+export default class World extends ClientPackageMixin(BaseWorld) {
+    static override getVersionBadge(
+        availability: number,
+        data: Partial<PackageManifestData>,
+        options?: { modules?: Collection<string, Module>; systems?: Collection<string, System> },
+    ): PackageCompatibilityBadge | null;
+
+    constructor(data: DeepPartial<WorldSource>, options?: DataModelConstructionContext<null>);
+
+    /**
+     * Provide data for a system badge displayed for the world which reflects the system ID and its availability
+     * @param system A specific system to use, otherwise use the installed system.
+     */
+    getSystemBadge(system?: System): PackageCompatibilityBadge | null;
+
+    static override _formatBadDependenciesTooltip(
+        availability: number,
+        data: Partial<PackageManifestData>,
+        deps: Iterable<RelatedPackage>,
+        options?: { modules?: Collection<string, Module>; systems?: Collection<string, System> },
+    ): string;
+}

package/src/client/ui.d.mts

@@ -0,0 +1,86 @@
+/**
+ * A collection of application instances
+ * @module ui
+ */
+
+import * as applications from "./applications/_module.mjs";
+import * as appv1 from "./appv1/_module.mjs";
+import Macro from "./documents/macro.mjs";
+
+export let activeWindow: appv1.api.Application | applications.api.ApplicationV2 | null;
+
+export const actors: applications.sidebar.tabs.ActorDirectory;
+
+export const cards: applications.sidebar.tabs.CardsDirectory;
+
+export const chat: applications.sidebar.tabs.ChatLog;
+
+export const combat: applications.sidebar.tabs.CombatTracker;
+
+export const compendium: applications.sidebar.tabs.CompendiumDirectory;
+
+export const controls: applications.ui.SceneControls;
+
+export const hotbar: applications.ui.Hotbar<Macro>;
+
+export const items: applications.sidebar.tabs.ItemDirectory;
+
+export const journal: applications.sidebar.tabs.JournalDirectory;
+
+export const macros: applications.sidebar.tabs.MacroDirectory;
+
+export const menu: applications.ui.MainMenu;
+
+export const nav: applications.ui.SceneNavigation;
+
+export const notifications: applications.ui.Notifications;
+
+export const pause: applications.ui.GamePause;
+
+export const players: applications.ui.Players;
+
+export const playlists: applications.sidebar.tabs.PlaylistDirectory;
+
+export const scenes: applications.sidebar.tabs.SceneDirectory;
+
+export const settings: applications.sidebar.tabs.Settings;
+
+export const sidebar: applications.sidebar.Sidebar;
+
+export const tables: applications.sidebar.tabs.RollTableDirectory;
+
+export const webrtc: applications.apps.av.CameraViews;
+
+export const windows: Record<string, appv1.api.Application>;
+
+export interface FoundryUI<
+    TActorDirectory extends applications.sidebar.tabs.ActorDirectory,
+    TItemDirectory extends applications.sidebar.tabs.ItemDirectory,
+    TChatLog extends applications.sidebar.tabs.ChatLog,
+    TCompendiumDirectory extends applications.sidebar.tabs.CompendiumDirectory,
+    TCombatTracker extends applications.sidebar.tabs.CombatTracker,
+    THotbar extends applications.ui.Hotbar<Macro>,
+> {
+    actors: TActorDirectory;
+    cards: applications.sidebar.tabs.CardsDirectory;
+    chat: TChatLog;
+    combat: TCombatTracker;
+    compendium: TCompendiumDirectory;
+    controls: applications.ui.SceneControls;
+    hotbar: THotbar;
+    items: TItemDirectory;
+    journal: applications.sidebar.tabs.JournalDirectory;
+    macros: applications.sidebar.tabs.MacroDirectory;
+    menu: applications.ui.MainMenu;
+    nav: applications.ui.SceneNavigation;
+    notifications: applications.ui.Notifications;
+    pause: applications.ui.GamePause;
+    players: applications.ui.Players;
+    playlists: applications.sidebar.tabs.PlaylistDirectory;
+    scenes: applications.sidebar.tabs.SceneDirectory;
+    settings: applications.sidebar.tabs.Settings;
+    sidebar: applications.sidebar.Sidebar;
+    tables: applications.sidebar.tabs.RollTableDirectory;
+    webrtc: applications.apps.av.CameraViews;
+    windows: Record<string, appv1.api.Application>;
+}

package/src/client/utils/_module.d.mts

@@ -0,0 +1,4 @@
+/** @module utils */
+
+export * from "./../../common/utils/_module.mjs";
+export * from "./helpers.mjs";