@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroToast/FuroToaster.vue

@@ -0,0 +1,44 @@
+<script>
+import {
+  defineComponent,
+} from 'vue'
+
+import FuroToast from './FuroToast.vue'
+
+import FuroToasterContext from './FuroToasterContext.js'
+
+export default defineComponent({
+  name: 'FuroToaster',
+
+  components: {
+    FuroToast,
+  },
+
+  setup (
+    props,
+    componentContext
+  ) {
+    const context = FuroToasterContext.create({
+      props,
+      componentContext,
+    })
+
+    return {
+      context,
+    }
+  },
+})
+</script>
+
+<template>
+  <FuroToast
+    :parcel="context.buildParcel()"
+    @dismiss="context.onDismiss({
+      key: $event.key,
+    })"
+    @action="context.onAction({
+      key: $event.key,
+      actionKey: $event.actionKey,
+    })"
+  />
+</template>

package/lib/components/organisms/FuroToast/FuroToasterContext.js

@@ -0,0 +1,113 @@
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import {
+  toastQueue,
+} from './toast.js'
+
+/**
+ * Context class for FuroToaster — the single mount point that renders the
+ * global imperative toast queue through the controlled `<FuroToast>` organism.
+ * Reads the shared `ToastQueue` singleton, forwards its parcel, and routes the
+ * component's `dismiss` / `action` events back to the queue.
+ *
+ * @extends {BaseFuroContext}
+ */
+export default class FuroToasterContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroToasterContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    queue,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.queue = queue
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroToasterContext ? X : never} T, X
+   * @override
+   * @param {FuroToasterContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    queue = toastQueue,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        queue,
+      })
+    )
+  }
+
+  /**
+   * Build the parcel forwarded to `<FuroToast>`.
+   *
+   * @returns {object}
+   */
+  buildParcel () {
+    return this.queue.buildParcel()
+  }
+
+  /**
+   * Handle a toast dismissal from `<FuroToast>`.
+   *
+   * @param {{
+   *   key: number | string
+   * }} params - Parameters of this method.
+   */
+  onDismiss ({
+    key,
+  }) {
+    this.queue.removeToast({
+      key,
+    })
+  }
+
+  /**
+   * Handle a toast action click from `<FuroToast>`.
+   *
+   * @param {{
+   *   key: number | string
+   *   actionKey: string
+   * }} params - Parameters of this method.
+   */
+  onAction ({
+    key,
+    actionKey,
+  }) {
+    this.queue.invokeAction({
+      key,
+      actionKey,
+    })
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   queue: import('./ToastQueue.js').default
+ * }} FuroToasterContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroToasterContextParams, 'queue'> & {
+ *   queue?: import('./ToastQueue.js').default
+ * }} FuroToasterContextFactoryParams
+ */

package/lib/components/organisms/FuroToast/ToastQueue.js

@@ -0,0 +1,325 @@
+import {
+  reactive,
+} from 'vue'
+
+const DEFAULT_TYPE = 'info'
+
+/**
+ * Realm-wide key, so duplicate copies of this module still reach one queue.
+ */
+const SHARED_INSTANCE_KEY = Symbol.for('@openreachtech/furo-vue/toastQueue')
+
+/** @type {ToastConfig} */
+const DEFAULT_CONFIG = {
+  position: 'bottom-right',
+  durationInMilliseconds: 4000,
+  maxVisible: 3,
+  label: 'Notifications',
+  hotkey: null,
+  richColors: false,
+}
+
+/**
+ * Imperative toast queue backing the global `toast` helper.
+ *
+ * Holds the reactive toast list and viewport config, and bridges function
+ * handlers (`actions[].onClick`) to the controlled `<FuroToast>` parcel: the
+ * parcel it builds is JSON-serializable (handlers stripped), while the handlers
+ * stay here and are invoked from the component's `action` event. This keeps the
+ * `FuroToast` organism controlled and registry-free; the imperative singleton
+ * lives only in this opt-in layer.
+ */
+export default class ToastQueue {
+  /**
+   * Constructor.
+   *
+   * @param {{
+   *   stateReactive: ToastQueueState
+   * }} params - Parameters of this constructor.
+   */
+  constructor ({
+    stateReactive,
+  }) {
+    this.stateReactive = stateReactive
+
+    this.nextId = 1
+
+    /** @type {Record<string, Record<string, () => void>>} */
+    this.actionHandlerHash = {}
+  }
+
+  /**
+   * Factory method.
+   *
+   * @param {{
+   *   stateReactive?: ToastQueueState
+   * }} [params] - Parameters of this factory method.
+   * @returns {ToastQueue}
+   */
+  static create ({
+    stateReactive = this.buildStateReactive(),
+  } = {}) {
+    return new this({
+      stateReactive,
+    })
+  }
+
+  /**
+   * Resolve the one queue shared by every copy of this module in the realm.
+   *
+   * @returns {ToastQueue}
+   */
+  static resolveSharedInstance () {
+    globalThis[SHARED_INSTANCE_KEY] ??= this.create()
+
+    return globalThis[SHARED_INSTANCE_KEY]
+  }
+
+  /**
+   * Build the reactive state (toast list + viewport config).
+   *
+   * @returns {ToastQueueState}
+   */
+  static buildStateReactive () {
+    return reactive({
+      toasts: [],
+      config: {
+        ...DEFAULT_CONFIG,
+      },
+    })
+  }
+
+  /**
+   * get: current toast entries.
+   *
+   * @returns {Array<QueuedToast>}
+   */
+  get toasts () {
+    return this.stateReactive.toasts
+  }
+
+  /**
+   * Build the parcel forwarded to `<FuroToast>` (config merged with the queue).
+   *
+   * @returns {object}
+   */
+  buildParcel () {
+    return {
+      ...this.stateReactive.config,
+      toasts: this.stateReactive.toasts,
+    }
+  }
+
+  /**
+   * Reserve and return the next stable toast key.
+   *
+   * @returns {number}
+   */
+  reserveKey () {
+    const key = this.nextId
+
+    this.nextId += 1
+
+    return key
+  }
+
+  /**
+   * Register a toast's action handlers and return serializable descriptors.
+   *
+   * @param {{
+   *   key: number | string
+   *   actions: Array<{ label: string, onClick?: () => void }>
+   * }} params - Parameters of this method.
+   * @returns {Array<{ actionKey: string, label: string }>}
+   */
+  registerActions ({
+    key,
+    actions,
+  }) {
+    const descriptors = actions.map((action, index) => ({
+      actionKey: `action-${index}`,
+      label: action.label,
+    }))
+
+    const handlerEntries = actions.map((action, index) => [
+      `action-${index}`,
+      action.onClick ?? (() => {}),
+    ])
+
+    this.actionHandlerHash[key] = Object.fromEntries(handlerEntries)
+
+    return descriptors
+  }
+
+  /**
+   * Push a new toast onto the queue.
+   *
+   * @param {{
+   *   title?: string | null
+   *   description?: string | null
+   *   type?: string
+   *   durationInMilliseconds?: number | null
+   *   closeText?: string | null
+   *   actions?: Array<{ label: string, onClick?: () => void }>
+   * }} [params] - Parameters of this method.
+   * @returns {number} The new toast key.
+   */
+  addToast ({
+    title = null,
+    description = null,
+    type = DEFAULT_TYPE,
+    durationInMilliseconds = null,
+    closeText = null,
+    actions = [],
+  } = {}) {
+    const key = this.reserveKey()
+
+    const descriptors = this.registerActions({
+      key,
+      actions,
+    })
+
+    this.stateReactive.toasts = [
+      ...this.stateReactive.toasts,
+      {
+        key,
+        title,
+        description,
+        type,
+        durationInMilliseconds,
+        closeText,
+        actions: descriptors,
+      },
+    ]
+
+    return key
+  }
+
+  /**
+   * Patch an existing toast (e.g. loading → success). Re-registers handlers
+   * when the patch carries new actions.
+   *
+   * @param {{
+   *   key: number | string
+   *   patch: Partial<QueuedToast>
+   * }} params - Parameters of this method.
+   */
+  updateToast ({
+    key,
+    patch,
+  }) {
+    const index = this.stateReactive.toasts.findIndex(toast => toast.key === key)
+
+    if (index === -1) {
+      return
+    }
+
+    const current = this.stateReactive.toasts[index]
+
+    const nextActions = Array.isArray(patch.actions)
+      ? this.registerActions({
+        key,
+        actions: patch.actions,
+      })
+      : current.actions
+
+    const nextToasts = [
+      ...this.stateReactive.toasts,
+    ]
+
+    nextToasts[index] = {
+      ...current,
+      ...patch,
+      actions: nextActions,
+    }
+
+    this.stateReactive.toasts = nextToasts
+  }
+
+  /**
+   * Remove a toast from the queue.
+   *
+   * @param {{
+   *   key: number | string
+   * }} params - Parameters of this method.
+   */
+  removeToast ({
+    key,
+  }) {
+    this.stateReactive.toasts = this.stateReactive.toasts
+      .filter(toast => toast.key !== key)
+
+    delete this.actionHandlerHash[key]
+  }
+
+  /**
+   * Remove all toasts.
+   */
+  clearToasts () {
+    this.stateReactive.toasts = []
+
+    this.actionHandlerHash = {}
+  }
+
+  /**
+   * Merge viewport configuration (position, duration, maxVisible, …).
+   *
+   * @param {ToastConfig} [params] - Configuration to merge.
+   */
+  configure (params = {}) {
+    Object.assign(
+      this.stateReactive.config,
+      params
+    )
+  }
+
+  /**
+   * Invoke a toast's action handler by key.
+   *
+   * @param {{
+   *   key: number | string
+   *   actionKey: string
+   * }} params - Parameters of this method.
+   */
+  invokeAction ({
+    key,
+    actionKey,
+  }) {
+    const handler = this.actionHandlerHash[key]?.[actionKey]
+      ?? null
+
+    if (handler === null) {
+      return
+    }
+
+    handler()
+  }
+}
+
+/**
+ * A toast entry stored in the queue (serializable; handlers live separately).
+ *
+ * @typedef {{
+ *   key: number | string
+ *   title: string | null
+ *   description: string | null
+ *   type: string
+ *   durationInMilliseconds: number | null
+ *   closeText: string | null
+ *   actions: Array<{ actionKey: string, label: string }>
+ * }} QueuedToast
+ */
+
+/**
+ * Viewport configuration shared by all toasts — the `<FuroToast>` parcel
+ * without the per-toast queue.
+ *
+ * @typedef {Omit<import('./FuroToastContext.js').ToastParcel, 'toasts'>} ToastConfig
+ */
+
+/**
+ * @typedef {import('vue').Reactive<{
+ *   toasts: Array<QueuedToast>
+ *   config: ToastConfig
+ * }>} ToastQueueState
+ */

package/lib/components/organisms/FuroToast/toast.js

@@ -0,0 +1,64 @@
+import ToastQueue from './ToastQueue.js'
+
+/**
+ * Realm-wide toast queue backing the `toast` helper and consumed by
+ * `<FuroToaster>`. See `docs/furo-toast.md` for the SSR caveat.
+ */
+export const toastQueue = ToastQueue.resolveSharedInstance()
+
+/**
+ * Global imperative toast helper, reached as
+ * `import { toast } from '@openreachtech/furo-vue'`.
+ */
+export const toast = {
+  /**
+   * Show a toast.
+   *
+   * @param {{
+   *   title?: string | null
+   *   description?: string | null
+   *   type?: string
+   *   durationInMilliseconds?: number | null
+   *   closeText?: string | null
+   *   actions?: Array<{ label: string, onClick?: () => void }>
+   * }} [params] - Toast options.
+   * @returns {number} The toast key (use it with `hide` / `update`).
+   */
+  show: params => toastQueue.addToast(params),
+
+  /**
+   * Hide (dismiss) a toast by key.
+   *
+   * @param {number | string} key - The toast key returned by `show`.
+   */
+  hide: key => {
+    toastQueue.removeToast({ key })
+  },
+
+  /**
+   * Update an existing toast (e.g. loading → success).
+   *
+   * @param {number | string} key - The toast key.
+   * @param {object} patch - Fields to merge into the toast.
+   */
+  update: (key, patch) => {
+    toastQueue.updateToast({ key, patch })
+  },
+
+  /**
+   * Remove all toasts.
+   */
+  clear: () => {
+    toastQueue.clearToasts()
+  },
+
+  /**
+   * Configure the viewport (position, durationInMilliseconds, maxVisible,
+   * richColors, …) for all toasts.
+   *
+   * @param {import('./ToastQueue.js').ToastConfig} [params] - Configuration to merge.
+   */
+  configure: params => {
+    toastQueue.configure(params)
+  },
+}