@openreachtech/furo-vue 1.3.1

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

@@ -0,0 +1,1089 @@
+import {
+  reactive,
+  onUnmounted,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+const DEFAULT_DURATION = 4000
+const DEFAULT_POSITION = 'bottom-right'
+const DEFAULT_SWIPE_DIRECTION = 'right'
+const DEFAULT_LABEL = 'Notifications'
+const DEFAULT_TYPE = 'info'
+const DEFAULT_CLOSE_TEXT = 'Close'
+const DEFAULT_MAX_VISIBLE = 3
+
+/**
+ * Vertical gap between stacked toasts, in pixels. Mirrors the static
+ * `--furo-toast-gap` CSS token so the JS-computed expand offsets line up with
+ * the CSS collapsed offsets.
+ */
+const STACK_GAP = 14
+
+/**
+ * How long to keep a dismissed toast mounted so its exit transition can play
+ * before the parent removes it. Mirrors the CSS exit transition duration.
+ */
+const EXIT_ANIMATION_MS = 250
+
+/**
+ * Swipe-to-dismiss direction per position: left-anchored toasts swipe left,
+ * right-anchored swipe right, centered toasts swipe toward their vertical edge.
+ */
+const SWIPE_DIRECTION_BY_POSITION = {
+  'top-left': 'left',
+  'bottom-left': 'left',
+  'top-right': 'right',
+  'bottom-right': 'right',
+  'top-center': 'up',
+  'bottom-center': 'down',
+}
+
+/**
+ * Exit transform per swipe direction — the toast leaves toward that edge.
+ */
+const SWIPE_EXIT_TRANSFORM_HASH = {
+  right: 'translateX(calc(100% + 1.5rem))',
+  left: 'translateX(calc(-100% - 1.5rem))',
+  up: 'translateY(calc(-100% - 1.5rem))',
+  down: 'translateY(calc(100% + 1.5rem))',
+}
+
+/**
+ * A loading toast must not auto-dismiss while the promise is pending — the
+ * parent resolves it by updating the entry. Use a very long duration instead
+ * of relying on the auto-close timer.
+ */
+const LOADING_DURATION = 1000000000
+
+/**
+ * Phosphor (`ph:`) icon name per toast type. A single small icon carries the
+ * only accent — the toast body stays neutral.
+ */
+const TYPE_ICON_NAME_HASH = {
+  info: 'ph:info',
+  success: 'ph:check-circle',
+  warning: 'ph:warning',
+  error: 'ph:x-circle',
+  loading: 'ph:circle-notch',
+}
+
+/**
+ * Context class for FuroToast organism.
+ *
+ * Presentational, controlled notification stack built on a headless toast
+ * primitive (`Provider` + `Viewport` + per-toast `Root`/`Title`/`Description`/
+ * `Action`/`Close`). The parent owns the `toasts` queue via `parcel.toasts`;
+ * this component renders the queue and emits `dismiss` / `action` by key so the
+ * parent can update its own array.
+ *
+ * Renders a collapsed stack: the newest toast sits on top and
+ * pushes older ones down/back (scaled + offset); hovering or focusing the stack
+ * expands it into a full list. Only the most recent `maxVisible` toasts render.
+ * Supports a `loading` type (spinner) for the promise pattern and a per-toast
+ * `actionPending` flag for async actions. No internal queue, no imperative API,
+ * registry-free. Domain-agnostic: no GraphQL or router imports.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroToastContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroToastContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    reactiveHash,
+  }) {
+    super({
+      props,
+      componentContext,
+
+      reactiveHash,
+    })
+
+    this.reactiveHash = reactiveHash
+
+    /** @type {Record<string, HTMLElement>} */
+    this.elementHash = {}
+
+    /** @type {Record<string, (element: HTMLElement | null) => void>} */
+    this.refCallbackHash = {}
+
+    /** @type {Record<string, ReturnType<typeof setTimeout>>} */
+    this.exitTimerHash = {}
+
+    /** @type {ResizeObserver | null} */
+    this.resizeObserver = null
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroToastContext ? X : never} T, X
+   * @override
+   * @param {FuroToastContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    reactiveHash = this.buildReactiveHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        reactiveHash,
+      })
+    )
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   DISMISS: 'dismiss'
+   *   ACTION: 'action'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      DISMISS: 'dismiss',
+      ACTION: 'action',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   dismiss: (payload: { key: ToastKey }) => void
+   *   action: (payload: { key: ToastKey, actionKey: string }) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.DISMISS]: payload => {},
+      [this.EMIT_EVENT_NAME.ACTION]: payload => {},
+    }
+  }
+
+  /**
+   * Build reactive hash — measured toast heights, mounted flags, and the
+   * expand/collapse UI flag.
+   *
+   * @override
+   * @returns {{
+   *   heightHash: Record<ToastKey, number>
+   *   mountedHash: Record<ToastKey, boolean>
+   *   uiState: { expanded: boolean }
+   * }}
+   */
+  static buildReactiveHash () {
+    return {
+      heightHash: /** @type {Record<ToastKey, number>} */ (reactive({})),
+      mountedHash: /** @type {Record<ToastKey, boolean>} */ (reactive({})),
+      uiState: reactive({
+        expanded: false,
+      }),
+    }
+  }
+
+  /**
+   * Build the per-toast stacking entries (pure math).
+   * Newest toast is last in the array and becomes the front of the stack.
+   *
+   * @param {{
+   *   toasts: Array<{ key: ToastKey }>
+   *   heightHash: Record<ToastKey, number>
+   *   gap: number
+   * }} params
+   * @returns {Array<StackEntry>}
+   */
+  static buildStackEntries ({
+    toasts,
+    heightHash,
+    gap,
+  }) {
+    const lastIndex = toasts.length - 1
+
+    return toasts.map((toast, index) => {
+      const toastsBefore = lastIndex - index
+
+      const offset = toasts
+        .slice(index + 1)
+        .reduce(
+          (total, newer) => total + (heightHash[newer.key] ?? 0) + gap,
+          0
+        )
+
+      return {
+        toastsBefore,
+        offset,
+        zIndex: index + 1,
+        isFront: index === lastIndex,
+        height: heightHash[toast.key] ?? 0,
+      }
+    })
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroToastContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroToastContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Setup component — start the height observer and dispose it on unmount.
+   *
+   * @template {X extends FuroToastContext ? X : never} T, X
+   * @override
+   * @returns {T} For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.resizeObserver = this.createResizeObserver()
+
+    onUnmounted(() => {
+      this.resizeObserver?.disconnect()
+
+      Object.values(this.exitTimerHash)
+        .map(timer => clearTimeout(timer))
+    })
+
+    return this
+  }
+
+  /**
+   * Create a ResizeObserver that re-measures toasts on content/size change.
+   *
+   * @returns {ResizeObserver | null}
+   */
+  createResizeObserver () {
+    if (typeof ResizeObserver === 'undefined') {
+      return null
+    }
+
+    return new ResizeObserver(entries => {
+      entries.map(entry =>
+        this.measureElement({
+          element: entry.target,
+        }))
+    })
+  }
+
+  /**
+   * Parcel passed from parent via props, with defaults applied.
+   *
+   * @override
+   * @returns {NonNullable<Props['parcel']>}
+   */
+  get parcel () {
+    return {
+      toasts: [],
+      position: DEFAULT_POSITION,
+      durationInMilliseconds: DEFAULT_DURATION,
+      swipeDirection: null,
+      label: DEFAULT_LABEL,
+      hotkey: null,
+      maxVisible: DEFAULT_MAX_VISIBLE,
+      richColors: false,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Resolve the swipe-to-dismiss direction. Honors an explicit
+   * `parcel.swipeDirection`; otherwise derives it from the position so a
+   * left toast swipes left and a right toast swipes right.
+   *
+   * @returns {ToastSwipeDirection}
+   */
+  extractSwipeDirection () {
+    return /** @type {ToastSwipeDirection} */ (
+      this.parcel?.swipeDirection
+      ?? SWIPE_DIRECTION_BY_POSITION[this.extractPosition()]
+      ?? DEFAULT_SWIPE_DIRECTION
+    )
+  }
+
+  /**
+   * Resolve the transform a toast uses to leave on swipe — toward the swipe edge.
+   *
+   * @returns {string}
+   */
+  extractSwipeExitTransform () {
+    return SWIPE_EXIT_TRANSFORM_HASH[this.extractSwipeDirection()]
+      ?? SWIPE_EXIT_TRANSFORM_HASH.right
+  }
+
+  /**
+   * Whether toasts render with full type-colored surfaces (rich colors).
+   *
+   * @returns {boolean}
+   */
+  isRichColors () {
+    return this.parcel?.richColors === true
+  }
+
+  /**
+   * Resolve the default auto-dismiss duration (ms).
+   *
+   * @returns {number}
+   */
+  extractDefaultDuration () {
+    return this.parcel?.durationInMilliseconds
+      ?? DEFAULT_DURATION
+  }
+
+  /**
+   * Resolve the maximum number of toasts rendered at once.
+   *
+   * @returns {number}
+   */
+  extractMaxVisible () {
+    return this.parcel?.maxVisible
+      ?? DEFAULT_MAX_VISIBLE
+  }
+
+  /**
+   * Normalize the parcel toasts into display-ready records, capped to the most
+   * recent `maxVisible` entries (newest last).
+   *
+   * @returns {Array<NormalizedToast>}
+   */
+  normalizeToasts () {
+    const toasts = this.parcel?.toasts
+      ?? []
+
+    const visibleToasts = toasts.slice(-this.extractMaxVisible())
+
+    return visibleToasts.map(toast => {
+      const type = toast.type ?? DEFAULT_TYPE
+      const actions = this.normalizeActions({ toast })
+
+      return {
+        key: toast.key,
+        title: toast.title ?? null,
+        description: toast.description ?? null,
+        type,
+        durationInMilliseconds: toast.durationInMilliseconds ?? null,
+        closeText: toast.closeText ?? DEFAULT_CLOSE_TEXT,
+        actions,
+        hasActions: actions.length > 0,
+        actionPending: toast.actionPending ?? false,
+        isLoading: type === 'loading',
+      }
+    })
+  }
+
+  /**
+   * Normalize a toast's action buttons into a serializable array.
+   * Accepts an `actions` array (`{ actionKey, label }`) or the single-action
+   * shorthand `actionText` (mapped to one `default` action).
+   *
+   * @param {{
+   *   toast: ToastEntry
+   * }} params
+   * @returns {Array<ToastActionDescriptor>}
+   */
+  normalizeActions ({
+    toast,
+  }) {
+    if (Array.isArray(toast.actions)) {
+      return toast.actions.map(action => ({
+        actionKey: action.actionKey,
+        label: action.label,
+      }))
+    }
+
+    const actionText = toast.actionText
+      ?? null
+
+    if (actionText !== null) {
+      return [
+        {
+          actionKey: 'default',
+          label: actionText,
+        },
+      ]
+    }
+
+    return []
+  }
+
+  /**
+   * Build the full per-toast view models: display fields + stacking geometry +
+   * mounted flag. Consumed by the template `v-for`.
+   *
+   * @returns {Array<ToastViewModel>}
+   */
+  createToastViewModels () {
+    const normalized = this.normalizeToasts()
+
+    const stackEntries = this.Ctor.buildStackEntries({
+      toasts: normalized,
+      heightHash: this.reactiveHash.heightHash,
+      gap: STACK_GAP,
+    })
+
+    return normalized.map((toast, index) => ({
+      ...toast,
+      ...stackEntries[index],
+      isMounted: this.isToastMounted({
+        key: toast.key,
+      }),
+    }))
+  }
+
+  /**
+   * Count toasts hidden by the `maxVisible` cap (still queued).
+   *
+   * @returns {number}
+   */
+  extractHiddenCount () {
+    const total = (this.parcel?.toasts ?? []).length
+
+    return Math.max(
+      0,
+      total - this.extractMaxVisible()
+    )
+  }
+
+  /**
+   * Height of the front (newest) visible toast — collapsed cards share it.
+   *
+   * @returns {number}
+   */
+  extractFrontHeight () {
+    const measuredToasts = this.normalizeToasts()
+      .filter(toast => (this.reactiveHash.heightHash[toast.key] ?? 0) > 0)
+
+    const frontToast = measuredToasts.at(-1)
+
+    if (!frontToast) {
+      return 0
+    }
+
+    return this.reactiveHash.heightHash[frontToast.key]
+  }
+
+  /**
+   * Vertical lift direction: top positions stack downward (+1), bottom upward (-1).
+   *
+   * @returns {number}
+   */
+  extractLift () {
+    const isTop = this.extractPosition()
+      .startsWith('top')
+
+    return isTop
+      ? 1
+      : -1
+  }
+
+  /**
+   * Extract viewport placement.
+   *
+   * @returns {ToastPosition}
+   */
+  extractPosition () {
+    return this.parcel?.position
+      ?? DEFAULT_POSITION
+  }
+
+  /**
+   * Extract viewport class names (root host + placement variant).
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractViewportClassNames () {
+    return {
+      'unit-toast-viewport': true,
+      [this.extractPosition()]: true,
+    }
+  }
+
+  /**
+   * Extract CSS custom properties applied to the viewport (shared by all toasts).
+   *
+   * @returns {Record<string, string | number>}
+   */
+  extractViewportStyle () {
+    return {
+      '--furo-toast-front-height': `${this.extractFrontHeight()}px`,
+      '--furo-toast-lift': this.extractLift(),
+      '--furo-toast-swipe-exit': this.extractSwipeExitTransform(),
+    }
+  }
+
+  /**
+   * Extract per-toast class names (type accent variant).
+   *
+   * @param {{
+   *   type: ToastType
+   * }} params
+   * @returns {Record<string, boolean>}
+   */
+  extractToastClassNames ({
+    type,
+  }) {
+    return {
+      'unit-toast': true,
+      [type]: true,
+      'rich-colors': this.isRichColors(),
+    }
+  }
+
+  /**
+   * Extract per-toast CSS custom properties for stacking geometry.
+   *
+   * @param {{
+   *   viewModel: ToastViewModel
+   * }} params
+   * @returns {Record<string, string | number>}
+   */
+  extractToastStyle ({
+    viewModel,
+  }) {
+    return {
+      '--furo-toast-z': viewModel.zIndex,
+      '--furo-toast-toasts-before': viewModel.toastsBefore,
+      '--furo-toast-offset': `${viewModel.offset}px`,
+      '--furo-toast-initial-height': `${viewModel.height}px`,
+    }
+  }
+
+  /**
+   * Extract the Phosphor icon name for a toast type.
+   *
+   * @param {{
+   *   type: ToastType
+   * }} params
+   * @returns {string}
+   */
+  extractToastIconName ({
+    type,
+  }) {
+    return TYPE_ICON_NAME_HASH[type]
+      ?? TYPE_ICON_NAME_HASH[DEFAULT_TYPE]
+  }
+
+  /**
+   * Extract attributes forwarded to the toast provider.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractProviderAttributes () {
+    const entries = [
+      ['duration', this.parcel?.durationInMilliseconds ?? null], // mapped to the primitive's `duration` (ms)
+      ['swipeDirection', this.extractSwipeDirection()],
+      ['label', this.parcel?.label ?? null],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Extract attributes forwarded to the toast viewport.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractViewportAttributes () {
+    const entries = [
+      ['hotkey', this.parcel?.hotkey ?? null],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Extract attributes forwarded to a single toast root host element.
+   * A loading toast is held open (long duration) until the parent resolves it.
+   *
+   * @param {{
+   *   toast: NormalizedToast
+   * }} params
+   * @returns {Record<string, unknown>}
+   */
+  extractToastRootAttributes ({
+    toast,
+  }) {
+    const resolvedDuration = toast.isLoading
+      ? LOADING_DURATION
+      : (toast.durationInMilliseconds ?? this.extractDefaultDuration())
+
+    return {
+      duration: resolvedDuration, // the primitive's root `duration` prop (ms)
+    }
+  }
+
+  /**
+   * Whether the stack is expanded (hovered / focused).
+   *
+   * @returns {boolean}
+   */
+  isExpanded () {
+    return this.reactiveHash.uiState.expanded
+  }
+
+  /**
+   * Whether a toast has completed its mount tick (drives the enter transition).
+   *
+   * @param {{
+   *   key: ToastKey
+   * }} params
+   * @returns {boolean}
+   */
+  isToastMounted ({
+    key,
+  }) {
+    return this.reactiveHash.mountedHash[key]
+      ?? false
+  }
+
+  /**
+   * Whether a title region should render for a toast (parcel text or `title` slot).
+   *
+   * @param {{
+   *   toast: NormalizedToast
+   * }} params
+   * @returns {boolean}
+   */
+  shouldRenderToastTitle ({
+    toast,
+  }) {
+    const hasTitleText = toast.title !== null
+    const hasTitleSlot = Boolean(this.slots?.title)
+
+    return hasTitleText || hasTitleSlot
+  }
+
+  /**
+   * Whether a description region should render for a toast (parcel text or `description` slot).
+   *
+   * @param {{
+   *   toast: NormalizedToast
+   * }} params
+   * @returns {boolean}
+   */
+  shouldRenderToastDescription ({
+    toast,
+  }) {
+    const hasDescriptionText = toast.description !== null
+    const hasDescriptionSlot = Boolean(this.slots?.description)
+
+    return hasDescriptionText || hasDescriptionSlot
+  }
+
+  /**
+   * Get a stable ref callback for a toast's inner element — memoized per key so
+   * Vue does not re-invoke it (with null then the element) on every render,
+   * which would spuriously unregister the toast and clear its exit timer.
+   *
+   * @param {{
+   *   key: ToastKey
+   * }} params
+   * @returns {(element: HTMLElement | null) => void}
+   */
+  getToastElementRef ({
+    key,
+  }) {
+    if (!this.refCallbackHash[key]) {
+      this.refCallbackHash[key] = element => this.registerToastElement({
+        key,
+        element,
+      })
+    }
+
+    return this.refCallbackHash[key]
+  }
+
+  /**
+   * Register (or unregister) a toast's measurable inner element.
+   *
+   * @param {{
+   *   key: ToastKey
+   *   element: HTMLElement | null
+   * }} params
+   */
+  registerToastElement ({
+    key,
+    element,
+  }) {
+    if (!element) {
+      this.unregisterToastElement({
+        key,
+      })
+
+      return
+    }
+
+    this.elementHash[key] = element
+    this.resizeObserver?.observe(element)
+
+    this.measureElement({
+      element,
+    })
+
+    this.scheduleToastMount({
+      key,
+    })
+  }
+
+  /**
+   * Stop observing a toast element and drop its measured state.
+   *
+   * @param {{
+   *   key: ToastKey
+   * }} params
+   */
+  unregisterToastElement ({
+    key,
+  }) {
+    const element = this.elementHash[key]
+      ?? null
+
+    if (element) {
+      this.resizeObserver?.unobserve(element)
+    }
+
+    // NOTE: do not clear the exit/dismiss timer here. The toast's inner element
+    // unmounts (via the headless primitive's exit) before the delayed dismiss
+    // fires; clearing the timer would strand the toast in the parent queue.
+    delete this.elementHash[key]
+    delete this.refCallbackHash[key]
+    delete this.reactiveHash.heightHash[key]
+    delete this.reactiveHash.mountedHash[key]
+  }
+
+  /**
+   * Measure an element's natural height into the height hash.
+   *
+   * @param {{
+   *   element: Element
+   * }} params
+   */
+  measureElement ({
+    element,
+  }) {
+    const match = Object.entries(this.elementHash ?? {})
+      .find(([, candidate]) => candidate === element)
+
+    if (!match) {
+      return
+    }
+
+    const height = /** @type {HTMLElement} */ (element).offsetHeight
+
+    if (height <= 0) {
+      return
+    }
+
+    this.reactiveHash.heightHash[match[0]] = height
+  }
+
+  /**
+   * Flip a toast to mounted on the next frame so the enter transition runs.
+   *
+   * @param {{
+   *   key: ToastKey
+   * }} params
+   */
+  scheduleToastMount ({
+    key,
+  }) {
+    if (this.isToastMounted({ key })) {
+      return
+    }
+
+    if (typeof requestAnimationFrame === 'undefined') {
+      this.reactiveHash.mountedHash[key] = true
+
+      return
+    }
+
+    requestAnimationFrame(() => {
+      this.reactiveHash.mountedHash[key] = true
+    })
+  }
+
+  /**
+   * Expand the stack on pointer enter / focus.
+   */
+  onStackExpand () {
+    this.reactiveHash.uiState.expanded = true
+  }
+
+  /**
+   * Collapse the stack on pointer leave / blur.
+   */
+  onStackCollapse () {
+    this.reactiveHash.uiState.expanded = false
+  }
+
+  /**
+   * Handle a toast open-state change from the root host element.
+   * Reka closes a toast on timeout, swipe, or the close button — when the
+   * resolved state is closed, request the parent to remove it.
+   *
+   * @param {{
+   *   key: ToastKey
+   *   isOpen: boolean
+   * }} params
+   */
+  onToastOpenChange ({
+    key,
+    isOpen,
+  }) {
+    if (isOpen) {
+      return
+    }
+
+    this.scheduleDismiss({
+      key,
+    })
+  }
+
+  /**
+   * Emit dismiss after the exit transition so the close/auto-dismiss animation
+   * (slide back toward the entry edge) can play before the parent removes the
+   * toast. The toast carries Reka's `data-state="closed"` during this window.
+   *
+   * @param {{
+   *   key: ToastKey
+   * }} params
+   */
+  scheduleDismiss ({
+    key,
+  }) {
+    if (typeof setTimeout === 'undefined') {
+      this.emitDismiss({ key })
+
+      return
+    }
+
+    this.exitTimerHash[key] = setTimeout(
+      () => {
+        delete this.exitTimerHash[key]
+
+        this.emitDismiss({ key })
+      },
+      EXIT_ANIMATION_MS
+    )
+  }
+
+  /**
+   * Emit the dismiss event for a toast.
+   *
+   * @param {{
+   *   key: ToastKey
+   * }} params
+   */
+  emitDismiss ({
+    key,
+  }) {
+    this.emit(
+      this.EMIT_EVENT_NAME.DISMISS,
+      {
+        key,
+      }
+    )
+  }
+
+  /**
+   * Handle an action-button click on a single toast.
+   *
+   * @param {{
+   *   key: ToastKey
+   *   actionKey: string
+   * }} params
+   */
+  onActionClick ({
+    key,
+    actionKey,
+  }) {
+    this.emit(
+      this.EMIT_EVENT_NAME.ACTION,
+      {
+        key,
+        actionKey,
+      }
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   reactiveHash: {
+ *     heightHash: Record<ToastKey, number>
+ *     mountedHash: Record<ToastKey, boolean>
+ *     uiState: {
+ *       expanded: boolean
+ *     }
+ *   }
+ * }} FuroToastContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroToastContextParams, 'reactiveHash'> & {
+ *   reactiveHash?: FuroToastContextParams['reactiveHash']
+ * }} FuroToastContextFactoryParams
+ */
+
+/**
+ * @typedef {'DISMISS' | 'ACTION'} EmitEventName
+ */
+
+/**
+ * @typedef {string | number} ToastKey
+ */
+
+/**
+ * @typedef {'info' | 'success' | 'warning' | 'error' | 'loading'} ToastType
+ */
+
+/**
+ * @typedef {(
+ *   'top-left'
+ *   | 'top-center'
+ *   | 'top-right'
+ *   | 'bottom-left'
+ *   | 'bottom-center'
+ *   | 'bottom-right'
+ * )} ToastPosition
+ */
+
+/**
+ * @typedef {'right' | 'left' | 'up' | 'down'} ToastSwipeDirection
+ */
+
+/**
+ * A single toast entry owned by the parent queue.
+ *
+ * @typedef {{
+ *   key: ToastKey
+ *   title?: string | null
+ *   description?: string | null
+ *   type?: ToastType
+ *   durationInMilliseconds?: number | null
+ *   closeText?: string
+ *   actionText?: string | null
+ *   actions?: Array<ToastActionDescriptor>
+ *   actionPending?: boolean
+ * }} ToastEntry
+ */
+
+/**
+ * A single action button on a toast (serializable — no handler functions).
+ *
+ * @typedef {{
+ *   actionKey: string
+ *   label: string
+ * }} ToastActionDescriptor
+ */
+
+/**
+ * Display-ready toast record produced by `normalizeToasts()`.
+ *
+ * @typedef {{
+ *   key: ToastKey
+ *   title: string | null
+ *   description: string | null
+ *   type: ToastType
+ *   durationInMilliseconds: number | null
+ *   closeText: string
+ *   actions: Array<ToastActionDescriptor>
+ *   hasActions: boolean
+ *   actionPending: boolean
+ *   isLoading: boolean
+ * }} NormalizedToast
+ */
+
+/**
+ * Per-toast stacking geometry produced by `buildStackEntries()`.
+ *
+ * @typedef {{
+ *   toastsBefore: number
+ *   offset: number
+ *   zIndex: number
+ *   isFront: boolean
+ *   height: number
+ * }} StackEntry
+ */
+
+/**
+ * Full per-toast view model (display + stacking + mounted) for the template.
+ *
+ * @typedef {NormalizedToast & StackEntry & {
+ *   isMounted: boolean
+ * }} ToastViewModel
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: ToastParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroToast>`.
+ * JSON-serializable only. Not an open passthrough to the internal primitive.
+ *
+ * @typedef {{
+ *   toasts?: Array<ToastEntry>
+ *   position?: ToastPosition
+ *   durationInMilliseconds?: number
+ *   swipeDirection?: ToastSwipeDirection
+ *   label?: string
+ *   hotkey?: Array<string> | null
+ *   maxVisible?: number
+ *   richColors?: boolean
+ * }} ToastParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroToastEmitHash, FuroToastSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroToastContext.EMIT_EVENT_HASH} FuroToastEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   title: {
+ *     toast: NormalizedToast
+ *   }
+ *   description: {
+ *     toast: NormalizedToast
+ *   }
+ * }>} FuroToastSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroToastContext
+ * }} FuroToastSetup
+ */