3RD_PARTY_REFACTOR_COMPLETE.md

3rd Party Card Refactoring - Complete Implementation

Overview

Comprehensive refactoring of the 3rd party card mechanism to ensure ALL cards work properly as a true wrapper, whether they have native editors or are YAML-based.

Changes Implemented

1. ✅ Removed External Card from Regular Module Selector

File: src/modules/module-registry.ts

• Removed UltraExternalCardModule registration (line 67)
• Removed import statement (line 23)
• External cards now ONLY available through 3rd Party tab

Result: No more confusing "External Card" option in regular modules

2. ✅ Robust getStubConfig Handling

File: src/editor/tabs/layout-tab.ts (lines 11577-11686)

Replaced blacklist approach with universal try-catch solution:

private async _getDefaultCardConfig(cardType: string, fullCardType: string): Promise<any> {
  // Try to get stub config safely
  try {
    const stubConfig = await this._tryGetStubConfig(cardType);
    if (stubConfig) {
      return stubConfig;
    }
  } catch (error) {
    console.log(`[UC] Could not get stub config for ${cardType}, using fallback:`, error);
  }

  // Always fall back to minimal config
  return { type: fullCardType };
}

private async _tryGetStubConfig(cardType: string): Promise<any | null> {
  // Wrap in Promise with timeout to handle ALL edge cases
  return Promise.race([
    this._callGetStubConfig(cardElement, cardType),
    new Promise<null>((_, reject) =>
      setTimeout(() => reject(new Error('getStubConfig timeout')), 1000)
    )
  ]).catch(error => {
    console.warn(`[UC] getStubConfig failed for ${cardType}:`, error);
    return null;
  });
}

Key Features:

• No more blacklist maintenance
• 1-second timeout prevents hanging
• Temporary hass object prevents "undefined" errors
• Works for ALL cards automatically

3. ✅ Improved Editor Detection

Files:

• src/modules/external-card-module.ts (lines 88-96)
• src/services/uc-external-cards-service.ts (lines 203-215)

Added robust native editor detection:

hasNativeEditor(cardType: string): boolean {
  if (!cardType) return false;

  const editorType = `${cardType}-editor`;
  const editorElement = customElements.get(editorType);

  // Check if editor exists and is not HTMLUnknownElement
  return editorElement !== undefined &&
         !(editorElement.prototype instanceof HTMLUnknownElement);
}

4. ✅ Smart Tab Selection

File: src/editor/tabs/layout-tab.ts

When Opening Module Settings (lines 2458-2484):

// For external cards, check if they have a native editor
if (module?.type === 'external_card') {
  const hasEditor = /* check for native editor */;
  // If no native editor, switch to YAML tab
  this._activeModuleTab = hasEditor ? 'general' : 'yaml';
}

When Adding New Card (lines 11790-11805):

// Check if the card has a native editor
const hasEditor = /* check for native editor */;
// If no native editor, switch to YAML tab
this._activeModuleTab = hasEditor ? 'general' : 'yaml';

5. ✅ Conditional General Tab Rendering

File: src/modules/external-card-module.ts (lines 304-318)

renderGeneralTab(...): TemplateResult | null {
  // Check if this card has a native editor
  if (!this.hasNativeEditor(module.card_type)) {
    // No native editor - user should use YAML tab
    return null;
  }
  // ... render native editor
}

File: src/editor/tabs/layout-tab.ts (lines 6324-6334)

General tab button only shown for external cards with native editors.

How It Works Now

Cards with Native Editors (e.g., Mushroom, Button Card)

1. User clicks card in 3rd Party tab
2. Card is added to builder
3. Module settings open with General tab active
4. Native editor is displayed
5. YAML tab also available as alternative
6. Logic and Design tabs work normally

YAML-Only Cards

1. User clicks card in 3rd Party tab
2. Card is added to builder
3. Module settings open with YAML tab active
4. General tab is hidden (no button shown)
5. User configures via YAML
6. Logic and Design tabs work normally

Universal Features

• ✅ No more blacklists to maintain
• ✅ All cards work automatically
• ✅ 1-second timeout prevents hanging
• ✅ Proper error handling with fallbacks
• ✅ Cards act naturally (true wrapper)
• ✅ Ultra Card features (Logic/Design) work for all

Technical Benefits

1. Future-Proof: New cards work automatically without code changes
2. Maintainable: No hardcoded lists or special cases
3. Robust: Handles all error scenarios gracefully
4. User-Friendly: Appropriate UI shown based on card capabilities
5. Performance: Caches editors to prevent recreation

Testing Checklist

Cards with Native Editors

• ✅ Mushroom Cards → General tab with native editor
• ✅ Button Card → General tab with native editor
• ✅ Mini Graph Card → General tab with native editor

YAML-Only Cards

• ✅ Cards without editors → YAML tab only
• ✅ Custom cards → Appropriate tab based on editor availability

Error Scenarios

• ✅ Broken getStubConfig → Uses fallback config
• ✅ Timeout getStubConfig → Uses fallback config
• ✅ Cards accessing hass.states → Temporary hass prevents errors

Build Status

✅ TypeScript: No errors
✅ Webpack: Success (10862ms)
✅ Distribution: Updated (3.8MB)
✅ All modules compiled successfully

Migration Notes

For users with existing Ultra Cards:

• External card modules in layouts continue to work
• No breaking changes
• Improved stability and compatibility

Version

• Ultra Card Version: 2.0-beta21
• Refactoring: Complete 3rd Party Card System
• Status: ✅ Complete and Tested
• Date: October 18, 2025

Summary

The 3rd party card system has been completely refactored to act as a true wrapper:

1. ALL cards supported - No exceptions or blacklists
2. Smart UI - Shows native editor OR YAML based on card capabilities
3. Natural behavior - Cards work exactly as on regular dashboards
4. Ultra features - Logic and Design tabs enhance any card
5. Future-proof - New cards work automatically

The implementation is now robust, maintainable, and provides the best possible user experience for integrating any 3rd party Home Assistant card into Ultra Card layouts.