@openreachtech/furo-vue 1.3.1

package/types/generated/components/organisms/FuroToast/FuroToastContext.d.ts

@@ -0,0 +1,543 @@
+/**
+ * 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<null, Props, EmitEventName> {
+    /**
+     * 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 override create<T extends X extends typeof FuroToastContext ? X : never, X>(this: T, { props, componentContext, reactiveHash, }: FuroToastContextFactoryParams): InstanceType<T>;
+    /**
+     * Get emit event name.
+     *
+     * @override
+     * @returns {Readonly<{
+     *   DISMISS: 'dismiss'
+     *   ACTION: 'action'
+     * }>}
+     */
+    static override get EMIT_EVENT_NAME(): Readonly<{
+        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(): {
+        dismiss: (payload: {
+            key: ToastKey;
+        }) => void;
+        action: (payload: {
+            key: ToastKey;
+            actionKey: string;
+        }) => void;
+    };
+    /**
+     * 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 override buildReactiveHash(): {
+        heightHash: Record<ToastKey, number>;
+        mountedHash: Record<ToastKey, boolean>;
+        uiState: {
+            expanded: boolean;
+        };
+    };
+    /**
+     * 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, }: {
+        toasts: Array<{
+            key: ToastKey;
+        }>;
+        heightHash: Record<ToastKey, number>;
+        gap: number;
+    }): Array<StackEntry>;
+    /**
+     * Constructor.
+     *
+     * @param {FuroToastContextParams} params - Parameters of this constructor.
+     */
+    constructor({ props, componentContext, reactiveHash, }: FuroToastContextParams);
+    reactiveHash: {
+        heightHash: Record<ToastKey, number>;
+        mountedHash: Record<ToastKey, boolean>;
+        uiState: {
+            expanded: boolean;
+        };
+    };
+    /** @type {Record<string, HTMLElement>} */
+    elementHash: Record<string, HTMLElement>;
+    /** @type {Record<string, (element: HTMLElement | null) => void>} */
+    refCallbackHash: Record<string, (element: HTMLElement | null) => void>;
+    /** @type {Record<string, ReturnType<typeof setTimeout>>} */
+    exitTimerHash: Record<string, ReturnType<typeof setTimeout>>;
+    /** @type {ResizeObserver | null} */
+    resizeObserver: ResizeObserver | null;
+    /**
+     * get: Constructor of this class.
+     *
+     * @override
+     * @returns {typeof FuroToastContext}
+     */
+    override get Ctor(): typeof FuroToastContext;
+    /**
+     * 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}
+     */
+    override setupComponent<T extends X extends FuroToastContext ? X : never, X>(this: T): T;
+    /**
+     * Create a ResizeObserver that re-measures toasts on content/size change.
+     *
+     * @returns {ResizeObserver | null}
+     */
+    createResizeObserver(): ResizeObserver | null;
+    /**
+     * 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(): ToastSwipeDirection;
+    /**
+     * Resolve the transform a toast uses to leave on swipe — toward the swipe edge.
+     *
+     * @returns {string}
+     */
+    extractSwipeExitTransform(): string;
+    /**
+     * Whether toasts render with full type-colored surfaces (rich colors).
+     *
+     * @returns {boolean}
+     */
+    isRichColors(): boolean;
+    /**
+     * Resolve the default auto-dismiss duration (ms).
+     *
+     * @returns {number}
+     */
+    extractDefaultDuration(): number;
+    /**
+     * Resolve the maximum number of toasts rendered at once.
+     *
+     * @returns {number}
+     */
+    extractMaxVisible(): number;
+    /**
+     * Normalize the parcel toasts into display-ready records, capped to the most
+     * recent `maxVisible` entries (newest last).
+     *
+     * @returns {Array<NormalizedToast>}
+     */
+    normalizeToasts(): Array<NormalizedToast>;
+    /**
+     * 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, }: {
+        toast: ToastEntry;
+    }): Array<ToastActionDescriptor>;
+    /**
+     * Build the full per-toast view models: display fields + stacking geometry +
+     * mounted flag. Consumed by the template `v-for`.
+     *
+     * @returns {Array<ToastViewModel>}
+     */
+    createToastViewModels(): Array<ToastViewModel>;
+    /**
+     * Count toasts hidden by the `maxVisible` cap (still queued).
+     *
+     * @returns {number}
+     */
+    extractHiddenCount(): number;
+    /**
+     * Height of the front (newest) visible toast — collapsed cards share it.
+     *
+     * @returns {number}
+     */
+    extractFrontHeight(): number;
+    /**
+     * Vertical lift direction: top positions stack downward (+1), bottom upward (-1).
+     *
+     * @returns {number}
+     */
+    extractLift(): number;
+    /**
+     * Extract viewport placement.
+     *
+     * @returns {ToastPosition}
+     */
+    extractPosition(): ToastPosition;
+    /**
+     * Extract viewport class names (root host + placement variant).
+     *
+     * @returns {Record<string, boolean>}
+     */
+    extractViewportClassNames(): Record<string, boolean>;
+    /**
+     * Extract CSS custom properties applied to the viewport (shared by all toasts).
+     *
+     * @returns {Record<string, string | number>}
+     */
+    extractViewportStyle(): Record<string, string | number>;
+    /**
+     * Extract per-toast class names (type accent variant).
+     *
+     * @param {{
+     *   type: ToastType
+     * }} params
+     * @returns {Record<string, boolean>}
+     */
+    extractToastClassNames({ type, }: {
+        type: ToastType;
+    }): Record<string, boolean>;
+    /**
+     * Extract per-toast CSS custom properties for stacking geometry.
+     *
+     * @param {{
+     *   viewModel: ToastViewModel
+     * }} params
+     * @returns {Record<string, string | number>}
+     */
+    extractToastStyle({ viewModel, }: {
+        viewModel: ToastViewModel;
+    }): Record<string, string | number>;
+    /**
+     * Extract the Phosphor icon name for a toast type.
+     *
+     * @param {{
+     *   type: ToastType
+     * }} params
+     * @returns {string}
+     */
+    extractToastIconName({ type, }: {
+        type: ToastType;
+    }): string;
+    /**
+     * Extract attributes forwarded to the toast provider.
+     *
+     * @returns {Record<string, unknown>}
+     */
+    extractProviderAttributes(): Record<string, unknown>;
+    /**
+     * Extract attributes forwarded to the toast viewport.
+     *
+     * @returns {Record<string, unknown>}
+     */
+    extractViewportAttributes(): Record<string, unknown>;
+    /**
+     * 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, }: {
+        toast: NormalizedToast;
+    }): Record<string, unknown>;
+    /**
+     * Whether the stack is expanded (hovered / focused).
+     *
+     * @returns {boolean}
+     */
+    isExpanded(): boolean;
+    /**
+     * Whether a toast has completed its mount tick (drives the enter transition).
+     *
+     * @param {{
+     *   key: ToastKey
+     * }} params
+     * @returns {boolean}
+     */
+    isToastMounted({ key, }: {
+        key: ToastKey;
+    }): boolean;
+    /**
+     * Whether a title region should render for a toast (parcel text or `title` slot).
+     *
+     * @param {{
+     *   toast: NormalizedToast
+     * }} params
+     * @returns {boolean}
+     */
+    shouldRenderToastTitle({ toast, }: {
+        toast: NormalizedToast;
+    }): boolean;
+    /**
+     * Whether a description region should render for a toast (parcel text or `description` slot).
+     *
+     * @param {{
+     *   toast: NormalizedToast
+     * }} params
+     * @returns {boolean}
+     */
+    shouldRenderToastDescription({ toast, }: {
+        toast: NormalizedToast;
+    }): boolean;
+    /**
+     * 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, }: {
+        key: ToastKey;
+    }): (element: HTMLElement | null) => void;
+    /**
+     * Register (or unregister) a toast's measurable inner element.
+     *
+     * @param {{
+     *   key: ToastKey
+     *   element: HTMLElement | null
+     * }} params
+     */
+    registerToastElement({ key, element, }: {
+        key: ToastKey;
+        element: HTMLElement | null;
+    }): void;
+    /**
+     * Stop observing a toast element and drop its measured state.
+     *
+     * @param {{
+     *   key: ToastKey
+     * }} params
+     */
+    unregisterToastElement({ key, }: {
+        key: ToastKey;
+    }): void;
+    /**
+     * Measure an element's natural height into the height hash.
+     *
+     * @param {{
+     *   element: Element
+     * }} params
+     */
+    measureElement({ element, }: {
+        element: Element;
+    }): void;
+    /**
+     * Flip a toast to mounted on the next frame so the enter transition runs.
+     *
+     * @param {{
+     *   key: ToastKey
+     * }} params
+     */
+    scheduleToastMount({ key, }: {
+        key: ToastKey;
+    }): void;
+    /**
+     * Expand the stack on pointer enter / focus.
+     */
+    onStackExpand(): void;
+    /**
+     * Collapse the stack on pointer leave / blur.
+     */
+    onStackCollapse(): void;
+    /**
+     * 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, }: {
+        key: ToastKey;
+        isOpen: boolean;
+    }): void;
+    /**
+     * 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, }: {
+        key: ToastKey;
+    }): void;
+    /**
+     * Emit the dismiss event for a toast.
+     *
+     * @param {{
+     *   key: ToastKey
+     * }} params
+     */
+    emitDismiss({ key, }: {
+        key: ToastKey;
+    }): void;
+    /**
+     * Handle an action-button click on a single toast.
+     *
+     * @param {{
+     *   key: ToastKey
+     *   actionKey: string
+     * }} params
+     */
+    onActionClick({ key, actionKey, }: {
+        key: ToastKey;
+        actionKey: string;
+    }): void;
+}
+export type FuroToastContextParams = import("../../../contexts/BaseFuroContext.js").BaseFuroContextParams & {
+    props: Props;
+    componentContext: ComponentContext;
+    reactiveHash: {
+        heightHash: Record<ToastKey, number>;
+        mountedHash: Record<ToastKey, boolean>;
+        uiState: {
+            expanded: boolean;
+        };
+    };
+};
+export type FuroToastContextFactoryParams = Omit<FuroToastContextParams, "reactiveHash"> & {
+    reactiveHash?: FuroToastContextParams["reactiveHash"];
+};
+export type EmitEventName = "DISMISS" | "ACTION";
+export type ToastKey = string | number;
+export type ToastType = "info" | "success" | "warning" | "error" | "loading";
+export type ToastPosition = ("top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right");
+export type ToastSwipeDirection = "right" | "left" | "up" | "down";
+/**
+ * A single toast entry owned by the parent queue.
+ */
+export type ToastEntry = {
+    key: ToastKey;
+    title?: string | null;
+    description?: string | null;
+    type?: ToastType;
+    durationInMilliseconds?: number | null;
+    closeText?: string;
+    actionText?: string | null;
+    actions?: Array<ToastActionDescriptor>;
+    actionPending?: boolean;
+};
+/**
+ * A single action button on a toast (serializable — no handler functions).
+ */
+export type ToastActionDescriptor = {
+    actionKey: string;
+    label: string;
+};
+/**
+ * Display-ready toast record produced by `normalizeToasts()`.
+ */
+export type NormalizedToast = {
+    key: ToastKey;
+    title: string | null;
+    description: string | null;
+    type: ToastType;
+    durationInMilliseconds: number | null;
+    closeText: string;
+    actions: Array<ToastActionDescriptor>;
+    hasActions: boolean;
+    actionPending: boolean;
+    isLoading: boolean;
+};
+/**
+ * Per-toast stacking geometry produced by `buildStackEntries()`.
+ */
+export type StackEntry = {
+    toastsBefore: number;
+    offset: number;
+    zIndex: number;
+    isFront: boolean;
+    height: number;
+};
+/**
+ * Full per-toast view model (display + stacking + mounted) for the template.
+ */
+export type ToastViewModel = NormalizedToast & StackEntry & {
+    isMounted: boolean;
+};
+export type Props = import("vue").HTMLAttributes & {
+    parcel?: ToastParcel | null;
+};
+/**
+ * Closed-set Furo behavior for `<FuroToast>`.
+ * JSON-serializable only. Not an open passthrough to the internal primitive.
+ */
+export type ToastParcel = {
+    toasts?: Array<ToastEntry>;
+    position?: ToastPosition;
+    durationInMilliseconds?: number;
+    swipeDirection?: ToastSwipeDirection;
+    label?: string;
+    hotkey?: Array<string> | null;
+    maxVisible?: number;
+    richColors?: boolean;
+};
+export type ComponentContext = import("vue").SetupContext<FuroToastEmitHash, FuroToastSlots>;
+export type FuroToastEmitHash = typeof FuroToastContext.EMIT_EVENT_HASH;
+export type FuroToastSlots = import("vue").SlotsType<{
+    title: {
+        toast: NormalizedToast;
+    };
+    description: {
+        toast: NormalizedToast;
+    };
+}>;
+export type FuroToastSetup = (props: Props, componentContext: ComponentContext) => {
+    context: FuroToastContext;
+};
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js';