rpc to handle post message: focus

[marclundgren]

Description

This PR adds cross-iframe RPC (Remote Procedure Call) functionality to enable parent applications to programmatically focus WebChat elements when
WebChat is embedded in an iframe. This addresses the common use case where WebChat runs inside an iframe and the parent application needs to control
focus behavior but cannot directly access DOM elements due to security restrictions.

The implementation provides a secure postMessage-based communication system that allows external applications to trigger WebChat's existing focus
management system across iframe boundaries.

Design

The solution follows WebChat's existing architectural patterns:

1. PostMessageListener Component: A new React component that listens for postMessage events from parent windows
2. Hook Integration: Leverages the existing useFocus() hook internally for proper focus management
3. Security First: Only accepts messages from parent windows with basic validation
4. Backwards Compatible: Does not modify existing APIs or behavior

The design uses WebChat's established patterns:

• Component-based architecture following existing WebChat components
• Hook-based functionality using the existing useFocus() hook
• Context-aware implementation that works within the Composer system

Specific Changes

• Added PostMessageListener.tsx: New component that handles cross-iframe focus commands

  • Listens for WEBCHAT_FOCUS message type
  • Supports all existing focus targets: 'sendBox', 'sendBoxWithoutKeyboard', 'main'
  • Includes error handling and basic security validation

• Updated Composer.tsx: Integrated PostMessageListener into the main component tree

  • Added import and component instantiation
  • Maintains existing component hierarchy and context

• Added comprehensive sample: samples/04.api/o.iframe-rpc-focus/

  • Complete working demonstration with parent application and WebChat iframe
  • Includes both CDN-based fallback implementation and development version usage
  • Documentation covers security considerations and implementation details

• Updated samples documentation: Added new sample to samples/README.md

API Usage

// From parent application
const iframe = document.getElementById('webchat-iframe');
iframe.contentWindow.postMessage({
  type: 'WEBCHAT_FOCUS',
  target: 'sendBox'  // or 'sendBoxWithoutKeyboard' or 'main'
}, '*');

Included Demo

Testing

• New unit test file
• New demo to test this concept (see screen recording)

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)

The key points covered:

• Clear problem statement: Cross-iframe focus control limitation
• Solution description: PostMessage-based RPC system
• Design rationale: Follows existing WebChat patterns
• Specific implementation details: Files changed and their purposes
• Working demo: Complete sample with documentation
• Security considerations: Basic validation and parent-only message acceptance

[OEvgeny]

It'd be great to have tests as well. Also need @compulim to weigh on design.

[marclundgren]

It'd be great to have tests as well. Also need @compulim to weigh on design.

Good idea. I added a new test file