@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250721081834 → 13.346.0-beta.20250722114330

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.346.0-beta.20250721081834",
+  "version": "13.346.0-beta.20250722114330",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./src/index.d.mts",

package/src/foundry/client/applications/ui/notifications.d.mts

@@ -1,3 +1,5 @@
+import type { Brand, Coalesce } from "#utils";
+
 /**
  * A common framework for displaying notifications to the client.
  * Submitted notifications are added to a queue, and up to {@link Notifications.MAX_ACTIVE} notifications are
@@ -47,38 +49,35 @@ declare class Notifications {
    * @returns The ID of the notification (positive integer)
    * @remarks `type` and `options` use parameter defaults so `null` causes an error
    */
-  notify<T extends Notifications.Type = "info">(
+  notify<T extends Notifications.Type | undefined = undefined>(
     message: string,
     type?: T,
     options?: Notifications.NotifyOptions,
-  ): Readonly<Notifications.Notification<T>>;
+  ): Notifications.Notification<Coalesce<T, "info">>;
 
   /**
    * Display a notification with the "info" type
    * @param message - The content of the notification message
    * @param options - Notification options passed to the notify function
-   * @returns The ID of the notification (positive integer)
-   * @remarks `options` use parameter defaults so `null` causes an error
+   * @returns The registered notification
    */
-  info(message: string, options?: Notifications.NotifyOptions): Readonly<Notifications.Notification<"info">>;
+  info(message: string, options?: Notifications.NotifyOptions): Notifications.Notification<"info">;
 
   /**
    * Display a notification with the "warning" type
    * @param message - The content of the notification message
    * @param options - Notification options passed to the notify function
-   * @returns The ID of the notification (positive integer)
-   * @remarks `options` use parameter defaults so `null` causes an error
+   * @returns The registered notification
    */
-  warn(message: string, options?: Notifications.NotifyOptions): Readonly<Notifications.Notification<"warning">>;
+  warn(message: string, options?: Notifications.NotifyOptions): Notifications.Notification<"warning">;
 
   /**
    * Display a notification with the "error" type
    * @param message - The content of the notification message
    * @param options - Notification options passed to the notify function
-   * @returns The ID of the notification (positive integer)
-   * @remarks `options` use parameter defaults so `null` causes an error
+   * @returns The registered notification
    */
-  error(message: string, options?: Notifications.NotifyOptions): Readonly<Notifications.Notification<"error">>;
+  error(message: string, options?: Notifications.NotifyOptions): Notifications.Notification<"error">;
 
   /**
    * Display a notification with the "success" type.
@@ -86,27 +85,34 @@ declare class Notifications {
    * @param options - Notification options passed to the notify function
    * @returns The registered notification
    */
-  success(message: string, options?: Notifications.NotifyOptions): Readonly<Notifications.Notification<"success">>;
+  success(message: string, options?: Notifications.NotifyOptions): Notifications.Notification<"success">;
 
   /**
    * Update the progress of the notification.
    * @param notification - A Notification or ID to update
    * @param update       - An incremental progress update
    */
-  update(notification: Notifications.Notification | number, update: Notifications.UpdateOptions): void;
+  update(notification: Notifications.Notification | Notifications.ID, update: Notifications.UpdateOptions): void;
 
   /**
    * Remove the notification linked to the ID.
    * @param id - The Notification or ID to remove
    */
-  remove(id: Notifications.Notification | number): void;
+  remove(id: Notifications.Notification | Notifications.ID): void;
+
+  /**
+   * Does the notification linked to the ID exist?.
+   * @param notification - The Notification or ID to remove
+   * @remarks Foundry writing "The Notification or ID to remove" is likely unintentional.
+   */
+  has(id: Notifications.Notification | Notifications.ID): boolean;
 
   /**
    * Clear all notifications.
    */
   clear(): void;
 
-  #private: true;
+  #Notifications: true;
 }
 
 declare abstract class AnyNotifications extends Notifications {
@@ -119,8 +125,10 @@ declare namespace Notifications {
 
   type Type = "info" | "warning" | "error" | "success";
 
+  type ID = Brand<number, "Notifications.ID">;
+
   interface Notification<T extends Type = Type> {
-    id: number;
+    id: Notifications.ID;
     type: T;
     timestamp: number;
     message: string;
@@ -129,79 +137,74 @@ declare namespace Notifications {
     active: boolean;
     progress: boolean;
     pct: number;
-    element?: HTMLLIElement;
-    remove?: () => void;
-    update?: (pct: number) => void;
+    element?: HTMLLIElement | undefined;
+    remove?: (() => void) | undefined;
+    update?: ((update: Notifications.UpdateOptions) => void) | undefined;
   }
 
   interface FormatOptions {
     /**
      * Whether to escape the values of `format`
      * @defaultValue `true`
-     * @remarks `null` equivalent to `false`
      */
-    escape?: boolean | null | undefined;
+    escape?: boolean | undefined;
 
     /**
      * Whether to clean the provided message string as untrusted user input.
      * No cleaning is applied if `format` is passed and `escape` is true or `localize` is true and `format` is not passed.
      * @defaultValue `true`
-     * @remarks `null` equivalent to `false`
      */
-    clean?: boolean | null | undefined;
+    clean?: boolean | undefined;
 
     /**
      * A mapping of formatting strings passed to Localization#format
      */
-    format?: Record<string, string> | null | undefined;
+    format?: Record<string, string> | undefined;
   }
 
   interface NotifyOptions extends FormatOptions {
     /**
      * Should the notification be permanently displayed until dismissed
      * @defaultValue `false`
-     * @remarks Overridden as `true` if `progress` is true. `null` equivalent to `false`
      */
-    permanent?: boolean | null | undefined;
+    permanent?: boolean | undefined;
 
     /**
      * Does this Notification include a progress bar?
      * @defaultValue `false`
-     * @remarks `null` equivalent to `false`
      */
-    progress?: boolean | null | undefined;
+    progress?: boolean | undefined;
 
     /**
      * Whether to localize the message content before displaying it
      * @defaultValue `false`
      */
-    localize?: boolean;
+    localize?: boolean | undefined;
 
     /**
      * Whether to log the message to the console
      * @defaultValue `true`
-     * @remarks `null` equivalent to `false`
      */
-    console?: boolean | null | undefined;
+    console?: boolean | undefined;
   }
 
   interface UpdateOptions extends FormatOptions {
     /**
      * An update to the string message
      */
-    message?: string | null | undefined;
+    message?: string | undefined;
 
     /**
      * Localize updates to presented progress text
      * @defaultValue `false`
-     * @remarks `null` equivalent to `false`
      */
-    localize?: boolean | null | undefined;
+    localize?: boolean | undefined;
 
     /**
      * An update to the completion percentage
+     * @remarks Only allows numbers in the range `[0, 1]`
      */
-    pct?: number | null | undefined;
+    pct?: number | undefined;
   }
 }