Document Hyperview Behavior Implementation Details

[AtlantisPleb]

Hyperview Behavior Implementation Guide

This documents the correct way to implement Hyperview behaviors in the Onyx app, based on lessons learned during GitHub auth implementation.

Behavior Registration

Behaviors must be registered in an array format in app/hyperview/behaviors/index.ts:

export default [
  AddStyles,
  ...WebSocketBehaviors,  // Spread existing behavior arrays
  OpenUrlBehavior,        // Add new behaviors
];

❌ Don't use object format:

export default {
  'open-url': OpenUrlBehavior.callback,  // Wrong!
}

Behavior Definition

Each behavior should be defined as a HvBehavior object:

export const OpenUrlBehavior: HvBehavior = {
  action: 'open-url',
  callback: async (element, context) => {
    // Implementation
  }
};

Loading State Management

Use style.display instead of hidden attribute for visibility:

1. In HXML templates:

<style id="loading" display="none" />
<text id="loading-text" style="loading">Loading...</text>

2. In behavior code:

if (showDuringLoad) {
  const showElement = context.getElementByID(showDuringLoad);
  if (showElement) {
    showElement.style.display = 'flex';
  }
}

Common Issues & Solutions

1. Iterator Error: If you see "iterator method is not callable", check behavior registration format. Must be array, not object.

2. Loading State Stuck: Use style.display manipulation instead of hidden attribute.

3. Behavior Not Triggering:

   • Ensure behavior is registered in index.ts
   • Check XML has correct trigger and action attributes
   • Verify behavior name matches XML action

4. Multiple Behaviors: When adding multiple behaviors, spread them in the array:

export default [
  AddStyles,
  ...WebSocketBehaviors,
  ...NewBehaviors
];

Testing Behaviors

Add debug logging to track behavior execution:

callback: async (element, context) => {
  console.log('[BehaviorName] Triggered');
  console.log('[BehaviorName] Attributes:', {
    href: element.getAttribute('href'),
    // other relevant attrs
  });
  // Implementation
}

Example Implementation

See the GitHub auth implementation in:

• app/hyperview/behaviors/OpenUrl/index.ts
• templates/pages/auth/login.xml

For a complete working example of behavior implementation and usage.