dees-wcctools/readme.hints.md

Project Hints and Findings

Properties Panel Element Detection Issue (Fixed)

Problem

The properties panel had timing issues detecting rendered elements because:

1. Elements are rendered asynchronously via lit's render() function in the dashboard component
2. The properties panel tried to find elements immediately without waiting for render completion
3. Element search only looked at direct children of the viewport, missing nested elements or those inside shadow DOM

Solution Implemented

1. Added a 100ms initial delay to allow render completion
2. Implemented recursive element search that:
   • Searches through nested children up to 5 levels deep
   • Checks both light DOM and shadow DOM for all elements
   • Handles complex DOM structures generically
   • Works with any wrapper elements, not specific to dees-demowrapper
3. Added retry mechanism with up to 5 attempts (200ms between retries)
4. Improved error messages to show retry count
5. Comprehensive error handling:
   • Errors in element search don't break the update cycle
   • Individual property errors don't prevent other properties from rendering
   • scheduleUpdate always completes even if createProperties fails
   • Clears warnings and property content appropriately on errors

Code Flow

1. Dashboard renders element demo into viewport using render(anonItem.demo(), viewport)
2. Properties panel waits 200ms for demo wrappers to run and set initial values
3. Searches recursively for the element instance
4. If not found, retries with delays to handle async rendering
5. Once found, extracts and displays element properties
6. Uses property binding (.value=) instead of attribute binding to prevent input events during initialization

Demo Tools

DeesDemoWrapper Component

A utility component for wrapping demo elements with post-render functionality.

Usage:

import * as demoTools from '@design.estate/dees-wcctools/demotools';

// In your demo function:
demo: () => html`
  <dees-demowrapper .runAfterRender=${(wrapper) => {
    // Use querySelector for specific elements
    const myElement = wrapper.querySelector('my-custom-element');
    myElement?.setAttribute('data-demo', 'true');
    
    // Access all children
    console.log('All children:', wrapper.children);
    
    // Use querySelectorAll for multiple elements
    wrapper.querySelectorAll('div').forEach(div => {
      console.log('Found div:', div);
    });
    
    // Full DOM API available
    const firstChild = wrapper.firstElementChild;
    const hasClass = wrapper.querySelector('.my-class');
  }}>
    <my-custom-element></my-custom-element>
    <div>Additional content</div>
  </dees-demowrapper>
`

Features:

• Wraps demo elements without affecting layout (uses display: contents)
• Provides the wrapper element itself with full DOM API access
• Use querySelector/querySelectorAll for powerful element selection
• Access children via wrapper.children property
• Supports async operations in runAfterRender callback
• Automatically handles timing to ensure elements are fully rendered