useAisToast

useAisToast is a composable that works with AisToast to manage toast messages. It encapsulates operations on the message list allowing clients to invoke them where messages are generated (e.g. a form handler) without being tied to where the messages are stored or where the AisToast component is configured. useAisToast accepts a reference to a list of messages and an options object to customize message creation.

Introduction

The following example illustrates how the useAisToast composable is created and used to manage a list of AisUserMessage objects. The example purposely does not use AisToast to illustrate that the composable's focus is strictly on manipulating the list of messages. It is not tied directly to AisToast. Notice how message timeout is handled here by the composable. The duration expresses how long the message lives in the list and the composable enforces that.

Message duration: 2 seconds

<script setup lang="ts">
  import {ref} from 'vue'
  import {useAisToast} from '@ais-public/ais-components'
  import {AisBox} from '@ais-public/ais-components'
  import {AisButtonBar} from '@ais-public/ais-components'
  import {AisButton} from '@ais-public/ais-components'

  const messages = ref([])
  const toast = useAisToast(messages, { duration: 2000, dismissible: false })
</script>

<template>
  <div class="grid gap-6">
    <div v-if="messages.length" class="grid gap-3">
      <AisBox v-for="msg in messages">
        {{ msg.message }}
      </AisBox>
    </div>
    <AisButtonBar>
      <AisButton
        variant="primary" icon="new" fast hover click
        @click="toast.message('The quick brown fox jumped over the lazy dog.')"
      >
        Add Message
      </AisButton>
      <div>Message duration: 2 seconds</div>
    </AisButtonBar>
  </div>
</template>

AisUserMessage

useAisToast() exposes operations on the AisUserMessage type, which includes the following attributes. AisUserMessage adheres closely to the interface used by AisAlert.

import {AisVariant} from "@/types/AisVariant";

export interface AisUserMessage {
    uuid?: string,
    title?: string,
    message?: string,
    details?: string[],
    variant?: AisVariant,
    icon?: any,
    dismissible?: boolean,
    duration?: number,
    dismissLabel?: string,
}

AisToastOptions

useAisToast(messages: AisUserMessage[], options: AisToastOptions) takes an options object of type AisToastOptions. This interface extends AisUserMessage and allows developers to set options and default values for the composable. Currently, maxMessages is the only non-message option. It prevents the unbounded growth of the messages array and defaults to 5 messages.

import {AisUserMessage} from "@/types/AisUserMessage";

export interface AisToastOptions extends AisUserMessage {

  /**
   * Maximum number of messages to display. The composable treats the array as a queue.
   * When the maximum number of messages is reached, the oldest message is removed (FIFO).
   */
  maxMessages?: number;
}

AisToastComposable

useAisToast() returns an object of type AisToastComposable. The definition below shows all the functionality exposed by the composable.

import type {AisUserMessage} from "@/types/AisUserMessage";

export interface AisToastComposable {

  /**
   * Creates a message object with a unique id that combines the default options with the user provided options
   * @param message - User message
   * @param options - Options to specialize the message object
   * @returns {{AisUserMessage}}
   */
  createMessage: (message: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message object and adds it to the messages array
   * @param message - User message
   * @param options - Options to specialize the message object
   * @returns {{AisUserMessage}}
   */
  message: (message: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Replaces the current messages with a new message object
   * @param message - User message
   * @param options - Options to specialize the message object
   * @returns {{AisUserMessage}}
   */
  replace: (message: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Removes a message from the messages array
   * @param uuid - Unique identifier of the message
   */
  remove: (uuid: string) => void;

  /**
   * Creates a message using the default variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  defaultMessage: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the primary variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  primary: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the secondary variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  secondary: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the plain variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  plain: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the default variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  info: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the success variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  success: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the warning variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  warning: (msg: string, options?: AisUserMessage) => AisUserMessage;

  /**
   * Creates a message using the danger variant
   * @param msg - User message
   * @param options - Options to specialize the message object
   */
  danger: (msg: string, options?: AisUserMessage) => AisUserMessage;
}