calendar/packages/embeds/LIFECYCLE.md

Cal.com Embed Lifecycle Events

This document details the lifecycle events and states of Cal.com embeds, showing the interaction flow between the parent page and the iframe.

Core Lifecycle Sequence

sequenceDiagram
    participant Parent as Parent (User Page)
    participant Embed as Embed (iframe)
    participant Store as EmbedStore(iframe)
    participant UI as UI Components(iframe)
    
    Note over Parent: embed.js loads
    
    alt Inline Embed
        Parent->>Parent: Create cal-element
        Parent->>Parent: Create iframe (visibility: hidden)
        Parent->>Parent: Show loader
    else Modal Embed
        Note over Parent: No action unless prerender
    end

    alt Prerender Flow
        Note over Parent: Set prerender=true in URL
        Parent->>Store: Set prerenderState="inProgress"
        Note over Store: Limited events allowed
        Parent->>Parent: Create hidden iframe
        Parent->>Parent: load booker(no slots)
        Note over Parent: Wait for connect() call
    end

    alt Modal CTA clicked
        Parent->>Parent: Create cal-modal-box
        Parent->>Parent: Create iframe (visibility: hidden)
        Parent->>Parent: Show loader
    end
    Note over Embed: background: transparent(stays transparent)
    Note over Embed: body tag set to visibility: hidden waiting to be shown
    Note over Embed: iframe webpage starts rendering

    Note over Store: Initialize EmbedStore state
    Store->>Store: Set NOT_INITIALIZED state
    Store->>Store: Initialize UI config & theme

    Note over Parent: Process URL params for prefill
    Parent->>Store: Set prefill data from URL
    Note over Store: Auto-populate form fields

    Embed->>Parent: __iframeReady event
    Note over Parent,Embed: Embed ready to receive messages
    Note over Store: Set state to INITIALIZED

    Store->>UI: Apply theme configuration
    Note over UI: DEPRECATED: styles prop
    Note over UI: Use cssVarsPerTheme instead
    Store->>UI: Apply cssVarsPerTheme

    Embed->>Parent: __dimensionChanged event
    Note over Parent: Calculate and adjust iframe dimensions
    Note over Store: Update parentInformedAboutContentHeight
    
    alt isBookerPage
        Note over Embed: Wait for booker ready state
    end

    Embed->>Parent: linkReady event
    Note over Parent: Changes loading state to done
    Note over Parent: Removes loader
    Note over Parent: Sets iframe visibility to visible

    Parent->>Embed: parentKnowsIframeReady event
    Note over Embed: Makes body visible
    Note over Store: Update UI configuration

    alt Prerendering Active
        Note over Store: Set prerenderState to completed
        Parent->>Store: connect() with new config
        Store->>Store: Reset parentInformedAboutContentHeight
        Store->>Parent: Update iframe with new params
        Note over Store: Remove prerender params
    end

    loop Dimension Monitoring
        Embed->>Embed: Monitor content size changes
        alt Dimensions Changed
            Embed->>Parent: __dimensionChanged event
            Parent->>Parent: Adjust iframe size to avoid scrollbar
        end
    end

    alt Route Changes
        UI->>Store: Update UI state
        Store->>Parent: __routeChanged event
        Parent->>Parent: Handle navigation
        Note over Store: Preserve prefill data
    end

Detailed State Management

EmbedStore States

• NOT_INITIALIZED: Initial state when iframe is created
• INITIALIZED: After __iframeReady event is processed
• prerenderState: Can be null | "inProgress" | "completed"

Visibility States

1. Initial Creation:

   • iframe.style.visibility = "hidden"
   • body.style.visibility = "hidden"

2. After __iframeReady:

   • iframe becomes visible (unless prerendering)

3. After parentKnowsIframeReady:

   • body becomes visible
   • Background remains transparent

Event Details

1. Initial Load

   • embed.js loads in parent page
   • For inline embeds: Creates elements immediately
   • For modal embeds: Waits for CTA click (unless prerendering)

2. iframe Creation

   • iframe is created with visibility: hidden
   • Loader is shown (default or skeleton)
   • EmbedStore initialized

3. __iframeReady Event

   • Fired by: Iframe
   • Indicates: Embed is ready to receive messages
   • Actions:
     • Sets iframeReady flag to true
     • Makes iframe visible (unless prerendering)
     • Processes queued iframe commands

4. __dimensionChanged Event

   • Fired by: Iframe
   • Purpose: Maintain proper iframe sizing
   • Triggers:
     • On initial load
     • When content size changes
     • After window load completes

5. linkReady Event

   • Fired by: Iframe
   • Indicates: iframe is fully ready for use
   • Requirements:
     • parentInformedAboutContentHeight must be true
     • For booker pages: booker must be in ready state
   • Actions:
     • Parent removes loader
     • Parent makes iframe visible

6. parentKnowsIframeReady Event

   • Fired by: Parent
   • Indicates: Parent acknowledges iframe readiness
   • Actions:
     • Makes body visible
     • For prerendering: marks prerenderState as "completed"

Prerendering Flow

The prerendering flow follows a special path:

1. Initial State:

   • prerenderState: null

2. During Prerender:

   • prerenderState: "inProgress"
   • Limited events allowed (only __iframeReady, __dimensionChanged)
   • iframe and body remain hidden

3. After Connect:

   • prerenderState: "completed"
   • Full event flow enabled
   • Visibility states updated

Command Queue System

The embed system implements a command queue to handle instructions before the iframe is ready:

1. Commands are queued if iframe isn't ready:

   if (!this.iframeReady) {
     this.iframeDoQueue.push(doInIframeArg);
     return;
   }
   

2. Queue is processed after __iframeReady event:

   • All queued commands are executed in order
   • New commands are executed immediately

Error Handling

Page Load Errors:

• System monitors CalComPageStatus
• On non-200 status: fires linkFailed event
• Includes error code and URL information