@7h3laughingman/foundry-types 13.351.0

package/src/client/appv1/sheets/journal-sheet.d.mts

@@ -0,0 +1,262 @@
+import { JournalEntryPageSource } from "../../../common/documents/journal-entry-page.mjs";
+import { ApplicationV1HeaderButton } from "../api/application-v1.mjs";
+import DocumentSheet, { DocumentSheetData, DocumentSheetV1Options } from "../api/document-sheet-v1.mjs";
+import { DirectorySearchMode, DocumentOwnershipLevel } from "./../../../common/constants.mjs";
+import { JournalEntryPageHeading } from "./../../_module.mjs";
+import { ContextMenuEntry } from "./../../applications/ux/context-menu.mjs";
+import JournalEntryPage from "./../../documents/journal-entry-page.mjs";
+import JournalEntry from "./../../documents/journal-entry.mjs";
+
+/**
+ * The Application responsible for displaying and editing a single JournalEntry document.
+ * @param object The JournalEntry instance which is being edited
+ * @param [options] Application options
+ */
+export default class JournalSheet<TJournalEntry extends JournalEntry> extends DocumentSheet<TJournalEntry> {
+    static override get defaultOptions(): DocumentSheetV1Options;
+
+    /**
+     * The cached list of processed page entries.
+     * This array is populated in the getData method.
+     */
+    protected _pages: JournalEntryPage<TJournalEntry>["_source"][];
+
+    /**
+     * Get the journal entry's current view mode.
+     * @see {@link JournalSheet.VIEW_MODES}
+     * @returns {number}
+     */
+    get mode(): JournalSheetViewMode;
+
+    /** The current search mode for this journal */
+    get searchMode(): DirectorySearchMode;
+
+    /** Toggle the search mode for this journal between "name" and "full" text search */
+    toggleSearchMode(): void;
+
+    /** The pages that are currently scrolled into view and marked as 'active' in the sidebar. */
+    get pagesInView(): HTMLElement[];
+
+    /** The index of the currently viewed page. */
+    get pageIndex(): number;
+
+    /** The currently active IntersectionObserver. */
+    get observer(): IntersectionObserver;
+
+    /** Is the table-of-contents sidebar currently collapsed? */
+    get sidebarCollapsed(): boolean;
+
+    /** Available view modes for journal entries. */
+    static VIEW_MODES: { SINGLE: 1; MULTIPLE: 2 };
+
+    /**
+     * The minimum amount of content that must be visible before the next page is marked as in view. Cannot be less than
+     * 25% without also modifying the IntersectionObserver threshold.
+     */
+    static INTERSECTION_RATIO: number;
+
+    /** Icons for page ownership. */
+    static OWNERSHIP_ICONS: Record<DocumentOwnershipLevel, string | undefined>;
+
+    get title(): string;
+
+    protected override _getHeaderButtons(): ApplicationV1HeaderButton[];
+
+    override getData(options?: Partial<DocumentSheetV1Options>): JournalSheetData<TJournalEntry> | Promise<JournalSheetData<TJournalEntry>>;
+
+    override get template(): string;
+
+    /** Guess the default view mode for the sheet based on the player's permissions to the Entry */
+    protected _inferDefaultMode(): string;
+
+    protected override _render(force?: boolean, options?: JournalSheetRenderOptions): Promise<void>;
+
+    protected override _getHeaderButtons(): ApplicationV1HeaderButton[];
+
+    /**
+     * Prepare pages for display.
+     * @returns The sorted list of pages.
+     */
+    protected _getPageData(): JournalEntryPage<TJournalEntry>[];
+
+    /**
+     * Identify which page of the journal sheet should be currently rendered.
+     * This can be controlled by options passed into the render method or by a subclass override.
+     * @param options Sheet rendering options
+     * @param [options.pageIndex] A numbered index of page to render
+     * @param [options.pageId]    The ID of a page to render
+     * @returns The currently displayed page index
+     */
+    protected _getCurrentPage(options?: { pageIndex?: number; pageId?: string }): number;
+
+    override activateListeners(html: JQuery): void;
+
+    /** Activate listeners after page content has been injected. */
+    protected _activatePageListeners(): void;
+
+    /**
+     * @param [options.mode]       Render the sheet in a given view mode, see {@link JournalSheet.VIEW_MODES}.
+     * @param [options.pageId]     Render the sheet with the page with the given ID in view.
+     * @param [options.pageIndex]  Render the sheet with the page at the given index in view.
+     * @param [options.anchor]     Render the sheet with the given anchor for the given page in view.
+     * @param [options.tempOwnership] Whether the journal entry or one of its pages is being shown to players
+     *                                who might otherwise not have permission to view it.
+     * @param [options.collapsed] Render the sheet with the TOC sidebar collapsed?
+     */
+    protected override _render(force?: boolean, options?: JournalSheetRenderOptions): Promise<void>;
+
+    /** Update child views inside the main sheet. */
+    protected _renderPageViews(): Promise<void>;
+
+    /**
+     * Add headings to the table of contents for the given page node.
+     * @param pageNode The HTML node of the page's rendered contents.
+     * @param toc      The page's table of contents.
+     */
+    protected _renderHeadings(pageNode: HTMLElement, toc: Record<string, JournalEntryPageHeading>): void;
+
+    /**
+     * Create an intersection observer to maintain a list of headings that are in view. This is much more performant than
+     * calling getBoundingClientRect on all headings whenever we want to determine this list.
+     * @protected
+     */
+    protected _observeHeadings(): void;
+
+    override close(options?: { force?: boolean }): Promise<void>;
+
+    /**
+     * Handle clicking the previous and next page buttons.
+     * @param event  The button click event.
+     */
+    protected _onAction(event: JQuery.TriggeredEvent): void;
+
+    /** Prompt the user with a Dialog for creation of a new JournalEntryPage */
+    createPage(): Promise<JournalEntryPage<TJournalEntry> | null>;
+
+    /** Turn to the previous page. */
+    previousPage(): Promise<this> | void;
+
+    /** Turn to the next page. */
+    nextPage(): Promise<this> | void;
+
+    /**
+     * Turn to a specific page.
+     * @param pageId   The ID of the page to turn to.
+     * @param [anchor] Optionally an anchor slug to focus within that page.
+     */
+    goToPage(pageId: string, anchor?: string): void;
+
+    /**
+     * Retrieve the sheet instance for rendering this page inline.
+     * @param pageId The ID of the page.
+     */
+    getPageSheet(pageId: string): JournalEntryPage<TJournalEntry> | undefined;
+
+    /**
+     * Determine whether a page is visible to the current user.
+     * @param page  The page.
+     */
+    isPageVisible(page: JournalEntryPage<TJournalEntry>): boolean;
+
+    /** Toggle the collapsed or expanded state of the Journal Entry table-of-contents sidebar. */
+    toggleSidebar(): void;
+
+    /** Update the disabled state of the previous and next page buttons. */
+    protected _updateButtonState(): void;
+
+    /**
+     * Edit one of this JournalEntry's JournalEntryPages.
+     * @param event  The originating page edit event.
+     */
+    protected _onEditPage(event: JQuery.TriggeredEvent): Promise<this> | undefined;
+
+    /**
+     * Handle clicking an entry in the sidebar to scroll that heading into view.
+     * @param event The originating click event.
+     */
+    protected _onClickPageLink(event: JQuery.TriggeredEvent): void;
+
+    /**
+     * Handle clicking an image to pop it out for fullscreen view.
+     * @param event The click event.
+     */
+    protected _onClickImage(event: PointerEvent): void;
+
+    /**
+     * Handle new pages scrolling into view.
+     * @param entries  An Array of elements that have scrolled into or out of view.
+     * @param observer The IntersectionObserver that invoked this callback.
+     */
+    protected _onPageScroll(entries: IntersectionObserverEntry[], observer: IntersectionObserver): void;
+
+    /** Highlights the currently viewed page in the sidebar. */
+    protected _activatePagesInView(): void;
+
+    /**
+     * If the set of active pages has changed, various elements in the sidebar will expand and collapse. For particularly
+     * long ToCs, this can leave the scroll position of the sidebar in a seemingly random state. We try to do our best to
+     * sync the sidebar scroll position with the current journal viewport.
+     */
+    protected _synchronizeSidebar(): void;
+
+    protected _contextMenu(html: JQuery): void;
+
+    /**
+     * Handle opening the context menu.
+     * @param target The element the context menu has been triggered for.
+     */
+    protected _onContextMenuOpen(target: HTMLElement): void;
+
+    /**
+     * Handle closing the context menu.
+     * @param target The element the context menu has been triggered for.
+     */
+    protected _onContextMenuClose(target: HTMLElement): void;
+
+    /**
+     * Get the set of ContextMenu options which should be used for JournalEntryPages in the sidebar.
+     * @returns {ContextMenuEntry[]}  The Array of context options passed to the ContextMenu instance.
+     */
+    protected _getEntryContextOptions(): ContextMenuEntry[];
+
+    protected override _updateObject(event: Event, formData: Record<string, unknown>): Promise<void>;
+
+    /**
+     * Handle requests to show the referenced Journal Entry to other Users
+     * Save the form before triggering the show request, in case content has changed
+     * @param event The triggering click event
+     */
+    protected _onShowPlayers(event: Event): Promise<void>;
+
+    protected override _canDragStart(selector: string): boolean;
+
+    protected override _canDragDrop(selector: string): boolean;
+
+    protected override _onDragStart(event: DragEvent): void;
+
+    protected override _onDrop(event: DragEvent): Promise<void>;
+
+    protected override _onSearchFilter(event: KeyboardEvent, query: string, rgx: RegExp, html: HTMLElement | null): void;
+}
+
+type JournalSheetViewMode = (typeof JournalSheet.VIEW_MODES)[keyof typeof JournalSheet.VIEW_MODES];
+
+interface JournalSheetRenderOptions extends DocumentRenderOptions {
+    pageId?: string;
+    pageIndex?: number;
+}
+
+interface JournalSheetData<TDocument extends JournalEntry> extends DocumentSheetData<TDocument> {
+    collapseMode: {
+        label: string;
+        icon: string;
+    };
+    searchIcon: string;
+    searchTooltip: string;
+    toc: JournalSheetPageData[];
+}
+
+interface JournalSheetPageData extends JournalEntryPageSource {
+    number: 0;
+    ownershipCls: string;
+}

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

@@ -0,0 +1,9 @@
+/** @module audio */
+
+export * from "./_types.mjs";
+export { default as BiquadFilterEffect } from "./biquad.mjs";
+export { default as AudioBufferCache } from "./cache.mjs";
+export { default as ConvolverEffect } from "./convolver.mjs";
+export { default as AudioHelper } from "./helper.mjs";
+export { default as Sound } from "./sound.mjs";
+export { default as AudioTimeout } from "./timeout.mjs";

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

@@ -0,0 +1,121 @@
+import Sound from "./sound.mjs";
+
+interface AudioBufferCacheEntry {
+    src: string;
+    buffer: AudioBuffer;
+    size: number;
+    locked?: boolean;
+    next?: AudioBufferCacheEntry;
+    previous?: AudioBufferCacheEntry;
+}
+
+interface SoundCreationOptions {
+    /** The source URL for the audio file */
+    src: string;
+
+    /** A specific AudioContext to attach the sound to */
+    context?: AudioContext;
+
+    /** Reuse an existing Sound for this source? */
+    singleton?: boolean;
+
+    /** Begin loading the audio immediately? */
+    preload?: boolean;
+
+    /** Begin playing the audio as soon as it is ready? */
+    autoplay?: boolean;
+
+    /** Options passed to the play method if autoplay is true */
+    autoplayOptions?: SoundPlaybackOptions;
+}
+
+interface SoundPlaybackOptions {
+    /** A delay in seconds by which to delay playback */
+    delay?: number;
+
+    /** A limited duration in seconds for which to play */
+    duration?: number;
+
+    /** A duration in milliseconds over which to fade in playback */
+    fade?: number;
+
+    /** Should sound playback loop? */
+    loop?: boolean;
+
+    /** Seconds of the AudioBuffer when looped playback should start. Only works for AudioBufferSourceNode. */
+    loopStart?: number;
+
+    /** Seconds of the Audio buffer when looped playback should restart. Only works for AudioBufferSourceNode. */
+    loopEnd?: number;
+
+    /** An offset in seconds at which to start playback */
+    offset?: number;
+
+    /** A callback function attached to the source node */
+    onended?: Function | null;
+
+    /** The volume at which to play the sound */
+    volume?: number;
+}
+
+type SoundScheduleCallback = (sound: Sound) => unknown;
+
+/**
+ * An object representing the raw and normalized audio data produced by an AnalyserNode
+ * for a given audio context (music, environment, interface).
+ */
+interface AnalysisDataValue {
+    /** Whether the analyzer is currently active. */
+    active: boolean;
+
+    /** If true, the analyzer remains active and will not be disabled after inactivity. */
+    keepAlive: boolean;
+
+    /** The AnalyserNode for this context, or null if inactive. */
+    node: AnalyserNode | null;
+
+    /** The FFT frequency data buffer used by the AnalyserNode. */
+    dataArray: Float32Array | null;
+
+    /** Raw average decibel values for each frequency band. */
+    db: { bass: number; mid: number; treble: number; all: number };
+
+    /** Normalized [0,1] values for the same bands. */
+    bands: { bass: number; mid: number; treble: number; all: number };
+
+    /** The timestamp when data was last requested. */
+    lastUsed: number;
+}
+
+/**
+ * An object mapping each audio context name (music, environment, interface)
+ * to an {@link foundry.audio.AnalysisDataValue}.
+ */
+interface AnalysisData {
+    /** Analysis data for the music context. */
+    music: AnalysisDataValue;
+
+    /** Analysis data for the ambient/environment context. */
+    environment: AnalysisDataValue;
+
+    /** Analysis data for the interface context. */
+    interface: AnalysisDataValue;
+
+    /** Whether the internal RAQ loop is currently running. */
+    analysisLoopActive: boolean;
+}
+
+type ContextName = "music" | "environment" | "interface";
+
+type BandName = "bass" | "mid" | "treble" | "all";
+
+interface AnalysisNodes {
+    /** The AnalyserNode for music, or null if not active.*/
+    music: AnalyserNode | null;
+
+    /** The AnalyserNode for ambient, or null if not active. */
+    environment: AnalyserNode | null;
+
+    /** The AnalyserNode for interface, or null if not active. */
+    interface: AnalyserNode | null;
+}

package/src/client/audio/biquad.d.mts

@@ -0,0 +1,29 @@
+/**
+ * A sound effect which applies a biquad filter.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/BiquadFilterNode}
+ */
+export default class BiquadFilterEffect extends BiquadFilterNode {
+    /**
+     * A ConvolverEffect is constructed by passing the following parameters.
+     * @param context The audio context required by the BiquadFilterNode
+     * @param options Additional options which modify the BiquadFilterEffect behavior
+     * @param options.type The filter type to apply
+     * @param options.intensity The initial intensity of the effect
+     */
+    constructor(context: AudioContext, options?: { type?: BiquadFilterType; intensity?: number });
+
+    /**
+     * Adjust the intensity of the effect on a scale of 0 to 10.
+     */
+    get intensity(): number;
+
+    set intensity(intensity);
+
+    /**
+     * Update the state of the effect node given the active flag and numeric intensity.
+     * @param options Options which are updated
+     * @param options.intensity A new effect intensity
+     * @param options.type A new filter type
+     */
+    update(options?: { intensity?: number; type?: BiquadFilterType }): void;
+}

package/src/client/audio/cache.d.mts

@@ -0,0 +1,58 @@
+import { AudioBufferCacheEntry } from "./_types.mjs";
+
+/**
+ * A specialized cache used for audio buffers.
+ * This is an LRU cache which expires buffers from the cache once the maximum cache size is exceeded.
+ */
+export default class AudioBufferCache extends Map<string, AudioBufferCacheEntry> {
+    /**
+     * Construct an AudioBufferCache providing a maximum disk size beyond which entries are expired.
+     * @param cacheSize The maximum cache size in bytes. 1GB by default.
+     */
+    constructor(cacheSize?: number);
+
+    /**
+     * A string representation of the current cache utilization.
+     */
+    get usage(): {
+        current: number;
+        max: number;
+        pct: number;
+        currentString: string;
+        maxString: string;
+        pctString: string;
+    };
+
+    /* -------------------------------------------- */
+    /*  Cache Methods                               */
+    /* -------------------------------------------- */
+
+    /**
+     * Retrieve an AudioBuffer from the cache.
+     * @param src The audio buffer source path
+     * @returns The cached audio buffer, or undefined
+     */
+    getBuffer(src: string): AudioBuffer | undefined;
+    /**
+     * Insert an AudioBuffer into the buffers cache.
+     * @param src The audio buffer source path
+     * @param buffer The audio buffer to insert
+     */
+    setBuffer(src: string, buffer: AudioBuffer): this;
+
+    /**
+     * Delete an entry from the cache.
+     * @param src The audio buffer source path
+     * @returns Was the buffer deleted from the cache?
+     */
+    delete(src: string): boolean;
+
+    /**
+     * Lock a buffer, preventing it from being expired even if it is least-recently-used.
+     * @param src The audio buffer source path
+     * @param locked Lock the buffer, preventing its expiration?
+     */
+    lock(src: string, locked?: boolean): void;
+
+    override toString(): string;
+}

package/src/client/audio/convolver.d.mts

@@ -0,0 +1,50 @@
+/**
+ * A sound effect which applies a convolver filter.
+ * The convolver effect splits the input sound into two separate paths:
+ * 1. A "dry" node which is the original sound
+ * 2. A "wet" node which contains the result of the convolution
+ * This effect mixes between the dry and wet channels based on the intensity of the reverb effect.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ConvolverNode}
+ */
+export default class ConvolverEffect extends ConvolverNode {
+    /**
+     * A ConvolverEffect is constructed by passing the following parameters.
+     * @param {AudioContext} context      The audio context required by the ConvolverNode
+     * @param {object} [options]          Additional options which modify the ConvolverEffect behavior
+     * @param {string} [options.impulseResponsePath]  The file path to the impulse response buffer to use
+     * @param {number} [options.intensity]            The initial intensity of the effect
+     */
+    constructor(context: AudioContext, options?: { impulseResponsePath?: string; intensity?: number });
+
+    /**
+     * Adjust the intensity of the effect on a scale of 0 to 10.
+     */
+    get intensity(): number;
+
+    set intensity(value);
+
+    /**
+     * Update the state of the effect node given the active flag and numeric intensity.
+     * @param options Options which are updated
+     * @param options.intensity A new effect intensity
+     */
+    update(options?: { intensity?: number }): void;
+
+    override disconnect(): void;
+    override disconnect(output: number): void;
+    override disconnect(destinationNode: AudioNode): void;
+    override disconnect(destinationNode: AudioNode, output: number): void;
+    override disconnect(destinationNode: AudioNode, output: number, input: number): void;
+    override disconnect(destinationParam: AudioParam): void;
+    override disconnect(destinationParam: AudioParam, output: number): void;
+
+    override connect(destinationNode: AudioNode, output?: number, input?: number): AudioNode;
+    override connect(destinationParam: AudioParam, output?: number): void;
+
+    /**
+     * Additional side effects performed when some other AudioNode connects to this one.
+     * This behavior is not supported by the base WebAudioAPI but is needed here for more complex effects.
+     * @param sourceNode An upstream source node that is connecting to this one
+     */
+    onConnectFrom(sourceNode: AudioNode): void;
+}