Widget API Reference

The Widget API is the primary interface for programmatically controlling the BrowseAid Widget. It provides methods for tool management, event handling, and configuration.

Accessing the API

The API is available globally after the widget is initialized:

const api = window.BrowseAidWidget.api;

Tool Management Methods

enableTool(toolName, options?)

Enables a specific accessibility tool with optional configuration.

Parameters:

• toolName (string): Name of the tool to enable
• options (object, optional): Additional settings to apply

Returns: void

Throws: Error if tool is not found

Example:

// Enable dark mode
api.enableTool('dark-mode');

// Enable blue light filter with specific level
api.enableTool('blue-light-filter', {
  level: 'high'
});

// Enable reading mask with custom settings
api.enableTool('reading-mask', {
  windowHeight: 200,
  maskOpacity: 0.8
});

---

disableTool(toolName)

Disables a specific tool and resets it to default settings.

Parameters:

• toolName (string): Name of the tool to disable

Returns: void

Throws: Error if tool is not found

Example:

// Disable dark mode
api.disableTool('dark-mode');

// Disable contrast tool
api.disableTool('contrast');

---

toggleTool(toolName, options?)

Toggles a tool's enabled state. If disabled, enables it with optional settings. If enabled, disables it.

Parameters:

• toolName (string): Name of the tool to toggle
• options (object, optional): Settings to apply when enabling (ignored when disabling)

Returns: boolean - New enabled state

Throws: Error if tool is not found

Example:

// Simple toggle
const isEnabled = api.toggleTool('dark-mode');
console.log('Dark mode is now:', isEnabled ? 'enabled' : 'disabled');

// Toggle with options when enabling
api.toggleTool('blue-light-filter', {
  level: 'medium'
});

---

updateTool(toolName, settings)

Updates a tool with specific settings without changing its enabled state.

Parameters:

• toolName (string): Name of the tool to update
• settings (object): Complete settings object to apply

Returns: void

Throws: Error if tool is not found

Example:

// Update saturation tool
api.updateTool('saturation', {
  enabled: true,
  level: 150
});

// Update hide images tool
api.updateTool('hide-images', {
  enabled: true,
  showAltText: true,
  skipSmallImages: true
});

---

getToolState(toolName)

Retrieves the current state and settings of a specific tool.

Parameters:

• toolName (string): Name of the tool to query

Returns: object | null - Tool settings object or null if not found

Example:

// Get dark mode state
const darkModeState = api.getToolState('dark-mode');
console.log('Dark mode enabled:', darkModeState?.enabled);

// Get blue light filter settings
const filterState = api.getToolState('blue-light-filter');
console.log('Filter level:', filterState?.level);

---

resetAllTools()

Resets all tools to their default settings.

Parameters: None

Returns: void

Example:

// Reset everything
api.resetAllTools();

Widget Control Methods

showWidget()

Makes the widget interface visible.

Parameters: None

Returns: void

Example:

api.showWidget();

---

hideWidget()

Hides the widget interface.

Parameters: None

Returns: void

Example:

api.hideWidget();

---

toggleWidget()

Toggles the widget's visibility state.

Parameters: None

Returns: boolean - New visibility state

Example:

const isVisible = api.toggleWidget();
console.log('Widget is now:', isVisible ? 'visible' : 'hidden');

Language Methods

setLanguage(language)

Changes the widget's language.

Parameters:

• language (string): Language code (e.g., 'en', 'es', 'fr')

Returns: void

Example:

// Change to Spanish
api.setLanguage('es');

// Change to French
api.setLanguage('fr');

---

getLanguage()

Gets the current widget language.

Parameters: None

Returns: string - Current language code

Example:

const currentLang = api.getLanguage();
console.log('Current language:', currentLang);

Event Listener Methods

onToolChange(callback)

Registers a callback for tool state changes.

Parameters:

• callback (function): Function called when any tool changes state
  • toolName (string): Name of the changed tool
  • settings (object): New tool settings

Returns: function - Unsubscribe function

Example:

// Listen for tool changes
const unsubscribe = api.onToolChange((toolName, settings) => {
  console.log(`Tool ${toolName} changed:`, settings);

  if (toolName === 'dark-mode' && settings.enabled) {
    console.log('Dark mode was enabled!');
  }
});

// Later, unsubscribe
unsubscribe();

---

onVisibilityChange(callback)

Registers a callback for widget visibility changes.

Parameters:

• callback (function): Function called when widget visibility changes
  • isVisible (boolean): New visibility state

Returns: function - Unsubscribe function

Example:

const unsubscribe = api.onVisibilityChange((isVisible) => {
  console.log('Widget is now:', isVisible ? 'visible' : 'hidden');
});

---

onLanguageChange(callback)

Registers a callback for language changes.

Parameters:

• callback (function): Function called when language changes
  • newLanguage (string): New language code

Returns: function - Unsubscribe function

Example:

const unsubscribe = api.onLanguageChange((newLanguage) => {
  console.log('Language changed to:', newLanguage);

  // Update your app's language
  myApp.setLanguage(newLanguage);
});

---

onInit(callback)

Registers a callback for widget initialization.

Parameters:

• callback (function): Function called when widget initializes
  • isInitialized (boolean): Initialization state

Returns: function - Unsubscribe function

Example:

const unsubscribe = api.onInit((isInitialized) => {
  if (isInitialized) {
    console.log('Widget is ready!');

    // Safe to use other API methods now
    api.enableTool('dark-mode');
  }
});

Complete Example

Here's a comprehensive example showing various API usage patterns:

// Wait for widget to initialize
api.onInit((isInitialized) => {
  if (!isInitialized) return;

  console.log('BrowseAid Widget initialized!');

  // Set up event listeners
  const toolChangeUnsubscribe = api.onToolChange((toolName, settings) => {
    console.log(`${toolName} updated:`, settings);

    // Send analytics event
    analytics.track('accessibility_tool_changed', {
      tool: toolName,
      enabled: settings.enabled
    });
  });

  // Language change listener
  const langChangeUnsubscribe = api.onLanguageChange((newLanguage) => {
    console.log(`Language changed to: ${newLanguage}`);
    document.documentElement.lang = newLanguage;
  });

  // Enable tools based on user preferences
  const userPrefs = getUserPreferences();

  if (userPrefs.darkMode) {
    api.enableTool('dark-mode');
  }

  if (userPrefs.highContrast) {
    api.enableTool('contrast', { level: 1.4 });
  }

  if (userPrefs.language !== 'en') {
    api.setLanguage(userPrefs.language);
  }

  // Set up keyboard shortcuts
  document.addEventListener('keydown', (event) => {
    // Ctrl+Alt+D to toggle dark mode
    if (event.ctrlKey && event.altKey && event.key === 'd') {
      event.preventDefault();
      api.toggleTool('dark-mode');
    }

    // Ctrl+Alt+W to toggle widget
    if (event.ctrlKey && event.altKey && event.key === 'w') {
      event.preventDefault();
      api.toggleWidget();
    }
  });

  // Clean up on page unload
  window.addEventListener('beforeunload', () => {
    toolChangeUnsubscribe();
    langChangeUnsubscribe();
  });
});

Error Handling Best Practices

Always wrap API calls in try-catch blocks for robust error handling:

function safeEnableTool(toolName, options = {}) {
  try {
    api.enableTool(toolName, options);
    return true;
  } catch (error) {
    console.error(`Failed to enable ${toolName}:`, error.message);

    // Show user-friendly message
    showNotification(`Accessibility tool "${toolName}" is not available.`);
    return false;
  }
}

function safeBatchUpdate(tools) {
  const results = {};

  for (const [toolName, settings] of Object.entries(tools)) {
    try {
      api.updateTool(toolName, settings);
      results[toolName] = { success: true };
    } catch (error) {
      results[toolName] = {
        success: false,
        error: error.message
      };
    }
  }

  return results;
}