Class NotificationSystem

constructor

• new NotificationSystem(): NotificationSystem

  Returns NotificationSystem

container

maxVisible

maxPersistent

durations

config

_eventManager

_timerManager

_queue

_maxQueueSize

init

• init(config?: INotificationInitConfig): boolean

  (Re-)initialises the notification system against a container element.

  init() is a full re-initialisation, not a merge (B.19). Every option is resolved from config alone, falling back to its built-in default when omitted, and the renderer always comes back enabled. Calling init(x) therefore lands on the same state whatever ran before it — including after a destroy().

  It used to be neither: position / animations / durations merged over the current state while maxVisible / maxPersistent fell back to the defaults, so a second partial init() silently reset two budgets and kept three other settings. Worse, enabled was never restored, and destroy() clears it — every recreate path came back mute unless the caller knew to enable() by hand. Per-field overrides (durations: { success: 4000 }) keep working: the config is layered over the defaults, not over the previous call.

  Parameters

  • config: INotificationInitConfig = {}

    Renderer configuration; every field falls back to its built-in default (see constants.ts).

  Returns boolean

  true when the container was found and the system is ready, false otherwise — nothing is rendered until a successful init().

show

• show(
      message: string,
      typeOrOptions?: string | NotifyOptions,
      duration?: number,
  ): HTMLElement | null | undefined

  Displays a notification toast. Two call signatures are supported:

  • show(message, type, duration) — positional
  • show(message, options) — options object

  Parameters

  • message: string

    Text to display.

  • typeOrOptions: string | NotifyOptions = "info"

    Notification type ("success" | "error" | "warning" | "info") or an options object.

  • Optionalduration: number

    Auto-dismiss duration (ms); ignored when typeOrOptions is an object.

  Returns HTMLElement | null | undefined

  The toast element, null when the queue rejected it, or undefined when the system is not initialised.

  Example

  GeoLeaf.Notifications.show("Message", "success", 3000);
  Copy

  Example

  GeoLeaf.Notifications.show("Message", {
      type: "success",
      duration: 3000,
      persistent: false,
      dismissible: true,
  });
  Copy

_typed

• _typed(
      type: NotifyType,
      message: string,
      durationOrOptions?: number | NotifyOptions,
  ): HTMLElement | null | undefined

  Shared body of the four type shortcuts: resolves their number | NotifyOptions | undefined second argument onto show.

  Parameters

  • type: NotifyType

    Notification type forced by the calling shortcut.

  • message: string

    Text to display.

  • OptionaldurationOrOptions: number | NotifyOptions

    Duration (ms) or an options object.

  Returns HTMLElement | null | undefined

success

• success(
      message: string,
      durationOrOptions?: number | NotifyOptions,
  ): HTMLElement | null | undefined

  Displays a success toast (default duration: 3 s).

  Parameters

  • message: string

    Text to display.

  • OptionaldurationOrOptions: number | NotifyOptions

    Duration (ms) or an options object.

  Returns HTMLElement | null | undefined

  Example

  GeoLeaf.Notifications.success("Save successful", 3000);
  GeoLeaf.Notifications.success("Save successful", { duration: 3000, persistent: false });
  Copy

error

• error(
      message: string,
      durationOrOptions?: number | NotifyOptions,
  ): HTMLElement | null | undefined

  Displays an error toast (highest priority, longest default duration: 5 s).

  Parameters

  • message: string

    Text to display.

  • OptionaldurationOrOptions: number | NotifyOptions

    Duration (ms) or an options object.

  Returns HTMLElement | null | undefined

  Example

  GeoLeaf.Notifications.error("Perte de connexion au serveur", { persistent: true });
  
  // Later, when connection is restored:
  GeoLeaf.Notifications.clearAll();
  GeoLeaf.Notifications.success("Connexion rétablie");
  Copy

warning

• warning(
      message: string,
      durationOrOptions?: number | NotifyOptions,
  ): HTMLElement | null | undefined

  Displays a warning toast (default duration: 4 s).

  Parameters

  • message: string

    Text to display.

  • OptionaldurationOrOptions: number | NotifyOptions

    Duration (ms) or an options object.

  Returns HTMLElement | null | undefined

  Example

  GeoLeaf.Notifications.warning("Mise à jour disponible", {
      persistent: true,
      dismissible: true, // user can dismiss
  });
  Copy

info

• info(
      message: string,
      durationOrOptions?: number | NotifyOptions,
  ): HTMLElement | null | undefined

  Displays an informational toast (default duration: 3 s).

  Parameters

  • message: string

    Text to display.

  • OptionaldurationOrOptions: number | NotifyOptions

    Duration (ms) or an options object.

  Returns HTMLElement | null | undefined

  Example

  GeoLeaf.Notifications.info("Nouvelle mise à jour disponible");
  GeoLeaf.Notifications.info("Message", { duration: 8000 }); // 8 seconds
  Copy

_enqueue

• _enqueue(
      message: string,
      options: Partial<
          {
              type: NotifyType;
              duration: number
              | undefined;
              persistent: boolean;
              dismissible: boolean;
          },
      > & { type?: string },
  ): HTMLElement | null | undefined

  Adds a notification to the priority queue, evicting a lower-priority entry when the queue is full, then processes the queue.

  Parameters

  • message: string

    Text to display.

  • options: Partial<
        {
            type: NotifyType;
            duration: number
            | undefined;
            persistent: boolean;
            dismissible: boolean;
        },
    > & { type?: string }

    Partially resolved display options.

  Returns HTMLElement | null | undefined

  The toast element, or null when the entry was rejected.

_makeSpaceForPriority

• _makeSpaceForPriority(
      nextItem: INotificationQueueEntry,
      temporaryToasts: HTMLElement[],
  ): boolean

  Evicts one visible temporary toast to make room for a pending error.

  Only a toast that is not already being removed frees a slot: _remove() is a no-op on one that is, and the actual DOM removal is deferred by the exit animation. temporaryToasts — the live counter _processQueue loops on — is therefore updated here, so a burst of errors handled in a single pass cannot re-target the same toast over and over and overflow maxVisible.

  Parameters

  • nextItem: INotificationQueueEntry
  • temporaryToasts: HTMLElement[]

  Returns boolean

  true only when a slot was genuinely freed.

_processQueue

• _processQueue(): HTMLElement | null

  Drains as much of the queue as the visible-toast budget allows.

  Returns HTMLElement | null

  The last toast displayed by this pass, or null when none was.

_showImmediate

• _showImmediate(
      message: string,
      options: {
          type: NotifyType;
          duration: number | undefined;
          persistent: boolean;
          dismissible: boolean;
      },
  ): HTMLElement

  Renders one notification straight away — called by the queue once a slot is free.

  Parameters

  • message: string

    Text to display.

  • options: {
        type: NotifyType;
        duration: number | undefined;
        persistent: boolean;
        dismissible: boolean;
    }

    Fully resolved display options.

  Returns HTMLElement

  The toast element appended to the container.

_appendCloseButton

• _appendCloseButton(toast: HTMLElement): void

  Builds the toast's dismiss button and registers its click on the renderer's OWN listener manager, recording the id on the toast so _remove can release it.

  ⚠️ Deliberately not createElement({ onClick }). That prop is not a plain addEventListener: dom-helpers routes it to GeoLeaf.Utils.events whenever that global exists — and in production it always does, pointing at the GLOBAL manager. Every toast therefore left a permanent entry there, holding a strong reference to a button detached seconds later, while _eventManager (created by init() for precisely this, destroyed by destroy()) stayed empty (CAPACITÉS backlog B.35d).

  Parameters

  • toast: HTMLElement

  Returns void

_releaseCloseListener

• _releaseCloseListener(toast: HTMLElement): void

  Drops the toast's close-button entry from the manager. Idempotent — the dataset key is cleared first, so a second call is a no-op.

  Parameters

  • toast: HTMLElement

  Returns void

_remove

• _remove(toast: HTMLElement, isReorganization?: boolean): void

  Removes a notification: marks it, plays the exit animation, then detaches it and re-processes the queue. A no-op on a toast already being removed.

  Parameters

  • toast: HTMLElement

    The toast element to remove.

  • isReorganization: boolean = false

    true when the toast is evicted to free a slot rather than dismissed on its own terms (plays a different animation).

  Returns void

clearAll

• clearAll(): void

  Dismisses every visible toast and empties the pending queue.

  Returns void

dismiss

• dismiss(toastEl: HTMLElement): void

  Dismisses one specific notification by its DOM reference.

  Parameters

  • toastEl: HTMLElement

    Toast element returned by show / info / success / etc.

  Returns void

disable

• disable(): void

  Temporarily suspends rendering — queued items wait for enable.

  Returns void

enable

• enable(): void

  Resumes rendering and flushes anything that piled up while disabled.

  Returns void

destroy

• destroy(): void

  Tears the system down: releases every timer and listener, detaches all toasts, empties the queue and marks the renderer disabled.

  A subsequent init brings it back enabled on its own (B.19) — the recreate path needs no enable() of its own.

  Returns void

getStatus

• getStatus(): NotifyStatus

  Snapshot of the current renderer state (visible counts, queue depth, budgets).

  Read-only and computed on call — it counts the toasts actually in the DOM rather than a tally kept alongside, so it cannot drift from what the user sees.

  Returns NotifyStatus

  The counts, the two budgets (maxVisible, maxPersistent) and the enabled / initialised flags.

  Example

  const s = GeoLeaf.Notifications.getStatus();
  // {
  //   enabled: true,
  //   initialized: true,
  //   activeToasts: 1,
  //   temporaryToasts: 1,
  //   persistentToasts: 0,
  //   queued: 0,
  //   maxVisible: 3,
  //   maxPersistent: 2,
  // }
  Copy