startFocusManagement

Handles focus transfer from the SDK UI back to your application.

Overview

The startFocusManagement method is called when the user navigates away from the SDK UI and focus should return to your application. Your implementation should handle setting focus to the appropriate element in your UI to ensure a seamless navigation experience. It's important to note that it releases the focus management from the SDK, allowing your application to take control of focus transitions.

Breaking Change

startFocusManagement now receives a StartClientFocusManagementParams argument. Update your implementation to accept this parameter — implementations that omit it will receive undefined for the argument, which may cause runtime errors if your code destructures it.

Not the same as the event-instance method

This is the SDK → app direction — a callback you implement on your delegate. To hand focus the other way (app → SDK), call the event-instance method IMaestroEvent.startFocusManagement(). See the Focus Management guide for the full flow.

Method Signature

startFocusManagement(params: StartClientFocusManagementParams): Promise<void>

Parameters

Parameter	Type	Description
params	StartClientFocusManagementParams	Describes the focus handoff from the SDK to your application.

StartClientFocusManagementParams

Field	Type	Required	Description
fromTarget	'overlay' \| 'sidebar'	Yes	The SDK UI element that is releasing focus. Use this to decide which element in your app should receive focus.
keyPress	'up' \| 'down' \| 'left' \| 'right' \| 'enter' \| 'back'	No	The directional key that triggered the focus handoff, if applicable. Use this to replicate or redirect the navigation intent.

Return Value

A Promise that resolves when focus has been successfully set in your application.

Implementation Requirements

Your implementation of this method should:

1. Identify the appropriate UI element in your application to receive focus based on params.fromTarget.
2. Optionally use params.keyPress to handle the directional intent (e.g., continue scrolling in the same direction).
3. Set focus to that element using standard DOM methods (e.g., element.focus()).
4. Return a resolved promise.

Example

import { IMaestroEventDelegate, StartClientFocusManagementParams } from '@maestro_io/maestro-web-sdk';

class Delegate implements IMaestroEventDelegate {
  startFocusManagement(params: StartClientFocusManagementParams): Promise<void> {
    if (params.fromTarget === 'overlay') {
      // Return focus to the element that had it before the overlay appeared.
      this.lastFocusedBeforeOverlay?.focus();
    } else {
      // Return focus to the main navigation.
      document.getElementById('main-nav')?.focus();
    }
    return Promise.resolve();
  }
}

Notes

• Consider saving the last focused element in your application before focus is transferred to the SDK, so you can restore it when focus returns.
• The focus transition should be smooth and predictable for the user.
• Use params.fromTarget to distinguish between focus returning from the panel sidebar vs. the overlay.