@quicktvui/web-renderer 1.0.0

package/src/components/QtFastListView.js

@@ -0,0 +1,1920 @@
+// QtFastListView - A data-driven list component
+// Children act as templates, data is bound via ${prop} syntax
+import { QtBaseComponent } from './QtBaseComponent'
+import { registerComponent } from '../core/componentRegistry'
+import { applyDomOnlyTemplateRootDefaults, renderQtFlexViewInPlace } from './QtFlexView'
+import {
+  bindTemplateDataToNode,
+  extractTemplateValue,
+  replaceTemplatePlaceholders,
+  syncDomAutoWidthIn,
+} from '../core/templateBinding'
+import {
+  registerFastListInstance,
+  unregisterFastListInstance,
+  getFadeConfig,
+} from '../modules/FastListModule'
+
+export class QtFastListView extends QtBaseComponent {
+  constructor(context, id, pId) {
+    super(context, id, pId)
+    this.tagName = 'FastListView'
+    this.dom = document.createElement('div')
+    this.dom.setAttribute('data-component-name', 'FastListView')
+    this._listData = []
+    this._templateChildren = [] // Regular templates (cloned for each data item)
+    this._singletonTemplates = [] // Singleton templates (used once, not cloned)
+    this._horizontal = false // Default: vertical layout
+    this._spanCount = 0 // Default: list layout (0 = list, > 0 = grid)
+    this._fadeConfig = getFadeConfig() // Initialize fade config
+    this._focusedIndex = -1
+    this._itemContainer = document.createElement('div')
+    this._itemContainer.className = 'fast-list-item-container'
+    this._itemContainer.style.cssText =
+      'display: flex; flex-direction: column; align-content: flex-start;'
+    this.dom.appendChild(this._itemContainer)
+    this.dom.style.cssText = 'overflow: auto; display: block;'
+    // 添加实例引用，用于焦点导航
+    this.dom.__fastListViewInstance = this
+    this._itemContainer.__fastListViewInstance = this
+    this._templateCaptured = false
+
+    registerComponent(id, this)
+
+    // Register this instance for fade config updates
+    registerFastListInstance(this)
+
+    // Set up MutationObserver to watch for children added to DOM
+    this._observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (mutation.type === 'childList') {
+          mutation.addedNodes.forEach((node) => {
+            if (node !== this._itemContainer && node.nodeType === Node.ELEMENT_NODE) {
+              this._processTemplateNode(node)
+            }
+          })
+        }
+      })
+    })
+    this._observer.observe(this.dom, { childList: true, subtree: false })
+  }
+
+  /**
+   * Update fade configuration (called by FastListModule)
+   * @param {{enabled: boolean, duration: number}} config
+   */
+  updateFadeConfig(config) {
+    this._fadeConfig = { ...config }
+  }
+
+  defaultStyle() {
+    return {
+      display: 'block',
+      overflow: 'auto',
+      boxSizing: 'border-box',
+    }
+  }
+
+  _processTemplateNode(node) {
+    if (!node || node === this._itemContainer) return
+    if (node.nodeType !== Node.ELEMENT_NODE) return
+
+    const parseType = (element) => {
+      const raw = element.getAttribute('data-template-type') ?? element.getAttribute('type')
+      if (raw === null || raw === undefined || raw === '') return null
+      return isNaN(Number(raw)) ? raw : Number(raw)
+    }
+    const registerTemplate = (element, singleton = false) => {
+      const type = parseType(element)
+      if (singleton) {
+        if (!this._singletonTemplates.some((t) => t.dom === element)) {
+          this._singletonTemplates.push({
+            dom: element,
+            tagName: element.tagName,
+            component: null,
+            type,
+          })
+          element.setAttribute('data-singleton', 'true')
+        }
+        element.style.display = 'none'
+        return
+      }
+      if (!this._templateChildren.some((t) => t.dom === element)) {
+        this._templateChildren.push({
+          dom: element,
+          tagName: element.tagName,
+          component: null,
+          type,
+        })
+        element.setAttribute('data-template', 'true')
+        if (type !== null) {
+          element.setAttribute('data-template-type', String(type))
+        }
+      }
+      element.style.display = 'none'
+    }
+
+    const hasSingleton = node.hasAttribute && node.hasAttribute('singleton')
+    const type = parseType(node)
+
+    if (!hasSingleton && type === null && node.querySelectorAll) {
+      const nestedTemplates = Array.from(
+        node.querySelectorAll('[type], [data-template-type], [singleton]')
+      )
+      if (nestedTemplates.length > 0) {
+        node.style.display = 'none'
+        nestedTemplates.forEach((element) => {
+          registerTemplate(element, element.hasAttribute('singleton'))
+        })
+        return
+      }
+    }
+
+    if (hasSingleton) {
+      registerTemplate(node, true)
+      return
+    }
+
+    registerTemplate(node)
+  }
+
+  // Handle property updates
+  updateProperty(key, value) {
+    switch (key) {
+      case 'horizontal':
+        this._horizontal = value === true || value === 'true' || value === ''
+        if (this._horizontal) {
+          this.dom.setAttribute('horizontal', '')
+        } else {
+          this.dom.removeAttribute('horizontal')
+        }
+        this._updateLayoutDirection()
+        break
+      case 'spanCount':
+      case 'span-count':
+        this._spanCount = value > 0 ? value : 0
+        if (this._spanCount > 0) {
+          this.dom.setAttribute('span-count', String(this._spanCount))
+        } else {
+          this.dom.removeAttribute('span-count')
+        }
+        this._updateLayoutDirection()
+        break
+      case 'listData':
+      case 'list-data':
+        this.setListData(value)
+        break
+      case 'list':
+        if (Array.isArray(value)) {
+          this.setListData(value)
+        } else if (typeof value === 'string' && value.startsWith('${')) {
+          // Template variable - store for later resolution
+          this.dom.setAttribute('list', value)
+          this._pendingListValue = value
+        } else {
+          this.setListData(value)
+        }
+        break
+      default:
+        if (typeof value === 'string' && value.startsWith('${')) {
+          this.dom.setAttribute(key, value)
+        }
+        super.updateProperty(key, value)
+    }
+  }
+
+  // Update layout direction based on horizontal and spanCount properties
+  _updateLayoutDirection() {
+    if (this._spanCount > 0) {
+      // Grid layout: use CSS Grid
+      this._itemContainer.style.display = 'grid'
+      this._itemContainer.style.gridTemplateColumns = `repeat(${this._spanCount}, 1fr)`
+      this._itemContainer.style.flexDirection = ''
+      this._itemContainer.style.flexWrap = ''
+      this._itemContainer.style.overflowX = 'hidden'
+      this._itemContainer.style.overflowY = 'auto'
+    } else if (this._horizontal) {
+      // Horizontal list: row layout, no wrap
+      this._itemContainer.style.display = 'flex'
+      this._itemContainer.style.flexDirection = 'row'
+      this._itemContainer.style.flexWrap = 'nowrap'
+      this._itemContainer.style.gridTemplateColumns = ''
+      this._itemContainer.style.overflowX = 'auto'
+      this._itemContainer.style.overflowY = 'hidden'
+    } else {
+      // Vertical list: column layout
+      this._itemContainer.style.display = 'flex'
+      this._itemContainer.style.flexDirection = 'column'
+      this._itemContainer.style.flexWrap = 'nowrap'
+      this._itemContainer.style.gridTemplateColumns = ''
+      this._itemContainer.style.overflowX = 'hidden'
+      this._itemContainer.style.overflowY = 'auto'
+    }
+  }
+
+  // Helper: check if a view is singleton
+  _isSingleton(view) {
+    if (view.props && view.props.singleton) return true
+    if (view.dom && view.dom.hasAttribute && view.dom.hasAttribute('singleton')) return true
+    return false
+  }
+
+  // Override insertChild to capture template children
+  insertChild(view, index) {
+    if (view && view.dom) {
+      // Check if this view's parent is NOT this FastListView (meaning it should be nested)
+      // This happens when a child view has a pId that matches one of our templates
+      if (view.pId && view.pId !== this.id) {
+        const parentTemplate =
+          this._singletonTemplates.find((t) => t.component && t.component.id === view.pId) ||
+          this._templateChildren.find((t) => t.component && t.component.id === view.pId)
+        if (parentTemplate) {
+          if (parentTemplate.component && parentTemplate.component.insertChild) {
+            parentTemplate.component.insertChild(view, index)
+          }
+          return
+        }
+      }
+
+      // Check if this is a singleton template
+      if (this._isSingleton(view)) {
+        if (!this._singletonTemplates.some((t) => t.dom === view.dom)) {
+          // Extract type from the view's props or dom (same logic as regular templates)
+          let type = null
+          if (view.props && view.props.type !== undefined) {
+            type = view.props.type
+          } else if (view.dom.hasAttribute('type')) {
+            const typeAttr = view.dom.getAttribute('type')
+            type =
+              typeAttr !== null ? (isNaN(Number(typeAttr)) ? typeAttr : Number(typeAttr)) : null
+          }
+
+          this._singletonTemplates.push({
+            dom: view.dom,
+            tagName: view.tagName,
+            id: view.id,
+            component: view,
+            type: type,
+          })
+          view.dom.setAttribute('data-singleton', 'true')
+        }
+        view.dom.style.display = 'none'
+        // Don't add to templateChildren, and don't return
+        // Let it continue so child elements can be mounted properly
+      } else {
+        // Regular template (not singleton)
+        if (!this._templateChildren.some((t) => t.dom === view.dom)) {
+          // Extract type from the view's props or dom
+          let type = null
+          if (view.props && view.props.type !== undefined) {
+            type = view.props.type
+          } else if (view.dom.hasAttribute('type')) {
+            const typeAttr = view.dom.getAttribute('type')
+            type =
+              typeAttr !== null ? (isNaN(Number(typeAttr)) ? typeAttr : Number(typeAttr)) : null
+          }
+
+          const templateWrapper = {
+            dom: view.dom,
+            tagName: view.tagName,
+            id: view.id,
+            component: view,
+            type: type,
+          }
+          this._templateChildren.push(templateWrapper)
+          view.dom.setAttribute('data-template', 'true')
+        }
+        view.dom.style.display = 'none'
+      }
+      if (!this.dom.contains(view.dom)) {
+        if (this._itemContainer && this.dom.contains(this._itemContainer)) {
+          this.dom.insertBefore(view.dom, this._itemContainer)
+        } else {
+          this.dom.appendChild(view.dom)
+        }
+      }
+
+      if (this._listData.length > 0 && !this._rerenderScheduled) {
+        this._rerenderScheduled = true
+        requestAnimationFrame(() => {
+          this._rerenderScheduled = false
+          this._renderItems()
+        })
+      }
+    }
+  }
+
+  // Override beforeChildMount - called before a child is mounted
+  async beforeChildMount(child, childPosition) {
+    if (child && child.dom) {
+      // Check if this child's parent is NOT this FastListView
+      if (child.pId && child.pId !== this.id) {
+        const parentTemplate =
+          this._singletonTemplates.find((t) => t.component && t.component.id === child.pId) ||
+          this._templateChildren.find((t) => t.component && t.component.id === child.pId)
+        if (parentTemplate) {
+          if (parentTemplate.component && parentTemplate.component.beforeChildMount) {
+            await parentTemplate.component.beforeChildMount(child, childPosition)
+          }
+          await super.beforeChildMount(child, childPosition)
+          return
+        }
+      }
+
+      // Check if this is a singleton template
+      if (this._isSingleton(child)) {
+        if (!this._singletonTemplates.some((t) => t.dom === child.dom)) {
+          // Extract type from the child's props or dom (same logic as regular templates)
+          let type = null
+          if (child.props && child.props.type !== undefined) {
+            type = child.props.type
+          } else if (child.dom.hasAttribute('type')) {
+            const typeAttr = child.dom.getAttribute('type')
+            type =
+              typeAttr !== null ? (isNaN(Number(typeAttr)) ? typeAttr : Number(typeAttr)) : null
+          }
+
+          this._singletonTemplates.push({
+            dom: child.dom,
+            tagName: child.tagName,
+            id: child.id,
+            component: child,
+            type: type,
+          })
+          child.dom.setAttribute('data-singleton', 'true')
+        }
+        child.dom.style.display = 'none'
+        // Don't return - let child elements continue to be mounted
+      } else {
+        // Regular template (not singleton)
+        if (!this._templateChildren.some((t) => t.dom === child.dom)) {
+          // Extract type from the child's props or dom
+          let type = null
+          if (child.props && child.props.type !== undefined) {
+            type = child.props.type
+          } else if (child.dom.hasAttribute('type')) {
+            const typeAttr = child.dom.getAttribute('type')
+            type =
+              typeAttr !== null ? (isNaN(Number(typeAttr)) ? typeAttr : Number(typeAttr)) : null
+          }
+
+          const templateWrapper = {
+            dom: child.dom,
+            tagName: child.tagName,
+            id: child.id,
+            component: child,
+            type: type,
+          }
+          this._templateChildren.push(templateWrapper)
+          child.dom.setAttribute('data-template', 'true')
+        }
+        child.dom.style.display = 'none'
+      }
+      if (!this.dom.contains(child.dom)) {
+        if (this._itemContainer && this.dom.contains(this._itemContainer)) {
+          this.dom.insertBefore(child.dom, this._itemContainer)
+        } else {
+          this.dom.appendChild(child.dom)
+        }
+      }
+    }
+    await super.beforeChildMount(child, childPosition)
+  }
+
+  // Capture templates from DOM children
+  _captureTemplatesFromDOM() {
+    this._templateCaptured = true
+  }
+
+  // Set list data and render items
+  setListData(data) {
+    // Handle wrapped params - sometimes data comes as [dataArray]
+    if (Array.isArray(data) && data.length === 1 && Array.isArray(data[0])) {
+      data = data[0]
+    }
+
+    if (!Array.isArray(data)) {
+      return
+    }
+    this._listData = data
+
+    // Wait for templates to be ready, then render
+    const tryRender = (attempts = 0) => {
+      if (
+        this._templateChildren.length > 0 ||
+        this._singletonTemplates.length > 0 ||
+        attempts >= 10
+      ) {
+        this._renderItems()
+      } else {
+        setTimeout(() => tryRender(attempts + 1), 50)
+      }
+    }
+    setTimeout(() => tryRender(), 0)
+  }
+
+  // Render items based on current data
+  _renderItems() {
+    this._itemContainer.innerHTML = ''
+
+    // Hide regular templates (they will be cloned)
+    this._templateChildren.forEach((t) => {
+      if (t.dom) {
+        t.dom.style.display = 'none'
+      }
+    })
+
+    const renderedSingletonTypes = new Set()
+
+    // Process singleton templates - show directly, no cloning
+    // Match by type instead of index
+    this._singletonTemplates.forEach((template) => {
+      if (template.dom) {
+        // Find matching data by type
+        let matchingData = null
+        if (template.type !== null && template.type !== undefined) {
+          // Find data with matching type
+          matchingData = this._listData.find((item) => item.type === template.type)
+        }
+
+        // If no matching data found, hide this template (don't render it)
+        if (!matchingData) {
+          template.dom.style.display = 'none'
+          return
+        }
+
+        // Show the singleton
+        template.dom.style.display = ''
+
+        if (matchingData.type !== null && matchingData.type !== undefined) {
+          renderedSingletonTypes.add(matchingData.type)
+        } else if (template.type !== null && template.type !== undefined) {
+          renderedSingletonTypes.add(template.type)
+        }
+
+        // Apply style from matching data if available
+        if (matchingData.style) {
+          this._applyStyleToElement(template.dom, matchingData.style)
+        }
+
+        // Move to item container
+        this._itemContainer.appendChild(template.dom)
+      }
+    })
+
+    if (this._listData.length === 0) {
+      return
+    }
+
+    // Create items for each data entry (for regular templates)
+    this._listData.forEach((itemData, index) => {
+      if (renderedSingletonTypes.has(itemData.type)) return
+      const itemElement = this._createItemFromData(itemData, index)
+      if (itemElement) {
+        this._itemContainer.appendChild(itemElement)
+      }
+    })
+
+    // Initialize showOnState visibility for dynamically created elements
+    requestAnimationFrame(() => {
+      const focusManager = global.__TV_FOCUS_MANAGER__
+      if (focusManager && focusManager.initShowOnStateForElement) {
+        focusManager.initShowOnStateForElement(this._itemContainer)
+      }
+    })
+  }
+
+  // Helper: apply style object to element
+  _applyStyleToElement(element, styleObj) {
+    if (!styleObj || typeof styleObj !== 'object') return
+    Object.keys(styleObj).forEach((key) => {
+      let value = styleObj[key]
+      if (typeof value === 'number') {
+        const needsPx = [
+          'width',
+          'height',
+          'minWidth',
+          'minHeight',
+          'maxWidth',
+          'maxHeight',
+          'padding',
+          'paddingTop',
+          'paddingRight',
+          'paddingBottom',
+          'paddingLeft',
+          'margin',
+          'marginTop',
+          'marginRight',
+          'marginBottom',
+          'marginLeft',
+          'top',
+          'left',
+          'right',
+          'bottom',
+          'borderRadius',
+          'borderWidth',
+        ].includes(key)
+        if (needsPx) value = value + 'px'
+      }
+      element.style[key] = value
+    })
+  }
+
+  // Create an item element by cloning template and binding data
+  _createItemFromData(itemData, index) {
+    const item = document.createElement('div')
+    item.setAttribute('data-index', index)
+    item.setAttribute('data-position', index)
+
+    // Get the item's type
+    const itemType = itemData.type !== undefined ? itemData.type : null
+
+    // Find matching template by type
+    let matchingTemplate = this._templateChildren.find((t) => t.type === itemType)
+
+    const sharedTemplates = window.__QT_SHARED_TEMPLATES__
+    const sharedByType =
+      sharedTemplates && itemType !== null && itemType !== undefined
+        ? sharedTemplates.get(itemType)
+        : null
+
+    if (!matchingTemplate && sharedByType && sharedByType.dom) {
+      matchingTemplate = sharedByType
+    }
+
+    // If no matching template found, try to use template without type (default template)
+    if (!matchingTemplate) {
+      matchingTemplate = this._templateChildren.find((t) => t.type === null)
+    }
+
+    if (!matchingTemplate && sharedTemplates && sharedTemplates.size > 0) {
+      const firstShared = sharedTemplates.values().next().value
+      if (firstShared && firstShared.dom) {
+        matchingTemplate = firstShared
+      }
+    }
+
+    // If still no template, use the first template
+    if (!matchingTemplate && this._templateChildren.length > 0) {
+      matchingTemplate = this._templateChildren[0]
+    }
+
+    // Clone the matching template and bind data
+    if (matchingTemplate && matchingTemplate.dom) {
+      const clonedNode = matchingTemplate.dom.cloneNode(true)
+      clonedNode.removeAttribute('data-template')
+
+      // Reset position for display
+      clonedNode.style.position = 'relative'
+      clonedNode.style.left = 'auto'
+      clonedNode.style.top = 'auto'
+      clonedNode.style.display = ''
+
+      // Process component-level props if available
+      // console.log(
+      //   '[QtFastListView] matchingTemplate:',
+      //   matchingTemplate.tagName,
+      //   'has component:',
+      //   !!matchingTemplate.component,
+      //   'has props:',
+      //   !!matchingTemplate.component?.props
+      // )
+      if (matchingTemplate.component && matchingTemplate.component.props) {
+        // console.log('[QtFastListView] props keys:', Object.keys(matchingTemplate.component.props))
+        this._bindComponentPropsToNode(clonedNode, matchingTemplate.component.props, itemData, {
+          itemList: this._listData,
+        })
+      }
+
+      // Bind data to the cloned node, pass list data as additional scope
+      this._bindDataToNode(clonedNode, itemData, { itemList: this._listData })
+
+      item.appendChild(clonedNode)
+
+      // Process child list data after DOM is attached
+      requestAnimationFrame(() => {
+        this._processChildListData(item)
+        syncDomAutoWidthIn(item)
+      })
+    }
+
+    // If no templates, create a simple item
+    if (this._templateChildren.length === 0) {
+      const textContent = itemData.text || itemData.title || itemData.name || `Item ${index}`
+      const textSpan = document.createElement('span')
+      textSpan.textContent = textContent
+      textSpan.style.cssText =
+        'color: white; font-size: 14px; padding: 5px; background: #333; margin: 5px; border-radius: 4px;'
+      item.appendChild(textSpan)
+    }
+
+    // Handle decoration (positioning)
+    if (itemData.decoration) {
+      const dec = itemData.decoration
+      if (dec.top !== undefined) item.style.marginTop = dec.top + 'px'
+      if (dec.left !== undefined) item.style.marginLeft = dec.left + 'px'
+      if (dec.right !== undefined) item.style.marginRight = dec.right + 'px'
+      if (dec.bottom !== undefined) item.style.marginBottom = dec.bottom + 'px'
+    }
+
+    item._itemData = itemData
+    item._itemPosition = index
+
+    item.addEventListener('click', (evt) => {
+      const nested = this._findNestedItemMeta(evt?.target, item)
+      if (
+        nested &&
+        nested.itemData !== itemData &&
+        itemData &&
+        typeof itemData === 'object' &&
+        Array.isArray(itemData.itemList)
+      ) {
+        this._dispatchItemClick(nested.position, nested.itemData, index)
+        return
+      }
+      this._dispatchItemClick(index, itemData)
+    })
+
+    // Apply fade-in animation if enabled
+    if (this._fadeConfig.enabled) {
+      item.style.opacity = '0'
+      item.style.transition = `opacity ${this._fadeConfig.duration}ms ease-in-out`
+      // Trigger animation after element is in DOM
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          item.style.opacity = '1'
+        })
+      })
+    }
+
+    return item
+  }
+
+  // Bind component-level props to a cloned node (handles flexStyle etc.)
+  _bindComponentPropsToNode(node, props, data, additionalScope = {}) {
+    if (!props || !data) return
+
+    const combinedData = { ...additionalScope, ...data }
+
+    Object.keys(props).forEach((key) => {
+      const value = props[key]
+
+      if (typeof value === 'string' && value.startsWith('${') && value.endsWith('}')) {
+        let resolvedValue = extractTemplateValue(value, combinedData)
+        const keyLower = key.toLowerCase()
+
+        // Handle list/listData specially - try item data first, then additional scope
+        if (keyLower === 'list' || keyLower === 'listdata') {
+          console.log(
+            '[QtFastListView] Processing list prop, value:',
+            value,
+            'resolvedValue from itemData:',
+            resolvedValue
+          )
+          if (resolvedValue === undefined || !Array.isArray(resolvedValue)) {
+            resolvedValue = extractTemplateValue(value, combinedData)
+            console.log('[QtFastListView] resolvedValue from combinedData:', resolvedValue)
+          }
+          if (Array.isArray(resolvedValue)) {
+            // Find the component registered for this node and call setListData directly
+            const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+            console.log(
+              '[QtFastListView] Looking for component, registry size:',
+              componentRegistry?.size
+            )
+            if (componentRegistry) {
+              const component = componentRegistry.get(node)
+              console.log('[QtFastListView] Found component by node:', component?.constructor?.name)
+              if (component && typeof component.setListData === 'function') {
+                console.log(
+                  '[QtFastListView] Calling setListData on component with',
+                  resolvedValue.length,
+                  'items'
+                )
+                component.setListData(resolvedValue)
+              } else {
+                // Fallback: store on node for later lookup
+                node._qtListData = resolvedValue
+                console.log('[QtFastListView] Set node._qtListData as fallback')
+              }
+            } else {
+              node._qtListData = resolvedValue
+            }
+          }
+          return // Don't process further
+        }
+
+        // Handle flexStyle specially
+        if (
+          (keyLower === 'flexstyle' || keyLower === 'flexstyletemplate') &&
+          resolvedValue &&
+          typeof resolvedValue === 'object'
+        ) {
+          const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+          const component = componentRegistry ? componentRegistry.get(node) : null
+          if (component && typeof component.updateProperty === 'function') {
+            component.updateProperty(key, resolvedValue)
+          } else {
+            this._applyFlexStyleToElement(node, resolvedValue)
+          }
+        }
+
+        // Handle textSize and fontSize specially
+        if ((keyLower === 'textsize' || keyLower === 'fontsize') && resolvedValue !== undefined) {
+          const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+          const component = componentRegistry ? componentRegistry.get(node) : null
+          if (component && typeof component.updateProperty === 'function') {
+            component.updateProperty(key, resolvedValue)
+          } else {
+            const fontSize =
+              typeof resolvedValue === 'number' ? resolvedValue + 'px' : resolvedValue
+            node.style.fontSize = fontSize
+          }
+        }
+
+        // Handle src attribute
+        if (keyLower === 'src') {
+          if (resolvedValue && typeof resolvedValue === 'object') {
+            if (resolvedValue.url !== undefined) {
+              resolvedValue = resolvedValue.url
+            } else if (resolvedValue.uri !== undefined) {
+              resolvedValue = resolvedValue.uri
+            } else if (resolvedValue.src !== undefined) {
+              resolvedValue = resolvedValue.src
+            }
+          }
+          const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+          const component = componentRegistry ? componentRegistry.get(node) : null
+          if (component && typeof component.updateProperty === 'function') {
+            component.updateProperty(key, resolvedValue)
+          } else if (node.tagName === 'IMG' && typeof resolvedValue === 'string') {
+            node.src = resolvedValue
+          }
+        }
+      }
+    })
+  }
+
+  // Bind data to a node: replace ${prop} in text and attributes
+  _bindDataToNode(node, data, additionalScope = {}) {
+    bindTemplateDataToNode(node, data, {
+      scope: additionalScope,
+      onListData: (element, listValue) => {
+        element._qtListData = listValue
+        element.setAttribute('data-has-list', 'true')
+      },
+    })
+  }
+
+  // Replace ${prop} placeholders with actual values
+  _replacePlaceholders(str, data) {
+    return replaceTemplatePlaceholders(str, data)
+  }
+
+  // Process child components that have list data
+  _processChildListData(container) {
+    // Find child nodes with _qtListData property
+    const processNode = (element) => {
+      // console.log(
+      //   '[QtFastListView] _processChildListData checking element:',
+      //   element.tagName,
+      //   'has _qtListData:',
+      //   !!element._qtListData
+      // )
+      if (element._qtListData) {
+        // Find the component for this element
+        const componentRegistry = window.__HIPPY_COMPONENT_REGISTRY__
+        // console.log(
+        //   '[QtFastListView] Found _qtListData:',
+        //   element._qtListData.length,
+        //   'items, componentRegistry size:',
+        //   componentRegistry?.size
+        // )
+        if (componentRegistry) {
+          const component = componentRegistry.get(element)
+          // console.log('[QtFastListView] Found component:', component?.constructor?.name)
+          if (component && typeof component.setListData === 'function') {
+            component.setListData(element._qtListData)
+          } else {
+            // DOM-only fallback: when templates are cloned as DOM, nested components are not instantiated.
+            // Handle tv-flex/FastFlexView by rendering in-place from its hidden templates.
+            const componentName = element.getAttribute?.('data-component-name')
+            const hasListTemplates = !!element.querySelector?.(
+              '[type], [data-template-type], [data-template], [data-singleton]'
+            )
+            if (componentName === 'QtFlexView') {
+              renderQtFlexViewInPlace(element, element._qtListData)
+            } else if (
+              componentName === 'FastListView' ||
+              componentName === 'ListView' ||
+              (element.hasAttribute?.('data-has-list') && hasListTemplates)
+            ) {
+              renderQtFastListViewInPlace(element, element._qtListData)
+            }
+          }
+        }
+        delete element._qtListData
+      }
+      // Recursively process children
+      if (element.children) {
+        Array.from(element.children).forEach((child) => processNode(child))
+      }
+    }
+    processNode(container)
+  }
+
+  // Dispatch item click event
+  _findNestedItemMeta(target, stopElement) {
+    let el = target
+    if (el && el.nodeType === Node.TEXT_NODE) {
+      el = el.parentElement
+    }
+    while (el && el !== stopElement) {
+      if (el._itemData !== undefined && el._itemPosition !== undefined) {
+        return {
+          position: el._itemPosition,
+          itemData: el._itemData,
+        }
+      }
+      el = el.parentElement
+    }
+    return null
+  }
+
+  _dispatchItemClick(position, itemData, parentPosition) {
+    const payload = {
+      position: position,
+      index: position,
+      item: itemData,
+    }
+    if (parentPosition !== undefined && parentPosition !== null) {
+      payload.parentPosition = parentPosition
+    }
+    this.dispatchEvent('onItemclick', payload)
+  }
+
+  _dispatchItemFocused(position, itemData, hasFocus) {
+    const payload = {
+      position: position,
+      index: position,
+      item: itemData,
+      hasFocus: !!hasFocus,
+      isFocused: !!hasFocus,
+    }
+    this.dispatchEvent('onItemfocused', payload)
+  }
+
+  notifyItemFocusChanged(currentElement, hasFocus) {
+    if (!currentElement || !this._itemContainer) return
+    const items = this._itemContainer.children
+    const itemCount = items.length
+    if (itemCount === 0) return
+
+    let currentIndex = -1
+    let parentItem = null
+    for (let i = 0; i < itemCount; i++) {
+      if (items[i] === currentElement || items[i].contains(currentElement)) {
+        currentIndex = i
+        parentItem = items[i]
+        break
+      }
+    }
+    if (currentIndex === -1) return
+
+    const itemData = this._listData[currentIndex]
+
+    // Check if focus is on a nested item (waterfall -> section -> item)
+    if (
+      parentItem &&
+      itemData &&
+      typeof itemData === 'object' &&
+      Array.isArray(itemData.itemList)
+    ) {
+      const nested = this._findNestedItemMeta(currentElement, parentItem)
+      if (nested && nested.itemData) {
+        // Dispatch focus event for nested item with parent position
+        const payload = {
+          position: nested.position,
+          index: nested.position,
+          item: nested.itemData,
+          hasFocus: !!hasFocus,
+          isFocused: !!hasFocus,
+          parentPosition: currentIndex,
+        }
+        this.dispatchEvent('onItemfocused', payload)
+        return
+      }
+    }
+
+    if (hasFocus) {
+      if (this._focusedIndex === currentIndex) return
+      this._focusedIndex = currentIndex
+    } else {
+      if (this._focusedIndex !== currentIndex) return
+      this._focusedIndex = -1
+    }
+
+    this._dispatchItemFocused(currentIndex, itemData, hasFocus)
+  }
+
+  // Add more items to the list
+  addListData(data) {
+    if (!Array.isArray(data)) return
+    const startIndex = this._listData.length
+    this._listData = this._listData.concat(data)
+    data.forEach((itemData, i) => {
+      const index = startIndex + i
+      const itemElement = this._createItemFromData(itemData, index)
+      if (itemElement) {
+        this._itemContainer.appendChild(itemElement)
+      }
+    })
+  }
+
+  // Update a single item
+  updateItem(position, data) {
+    if (position < 0 || position >= this._listData.length) return
+    this._listData[position] = { ...this._listData[position], ...data }
+
+    const existingItem = this._itemContainer.children[position]
+    if (existingItem) {
+      const newItem = this._createItemFromData(this._listData[position], position)
+      this._itemContainer.replaceChild(newItem, existingItem)
+    }
+  }
+
+  // Delete items
+  deleteItem(position, count = 1) {
+    this._listData.splice(position, count)
+    for (let i = 0; i < count; i++) {
+      const item = this._itemContainer.children[position]
+      if (item) {
+        this._itemContainer.removeChild(item)
+      }
+    }
+    Array.from(this._itemContainer.children).forEach((item, idx) => {
+      item.setAttribute('data-index', idx)
+      item.setAttribute('data-position', idx)
+      item._itemPosition = idx
+    })
+  }
+
+  // Clear all data
+  clearData() {
+    this._listData = []
+    this._itemContainer.innerHTML = ''
+  }
+
+  // Scroll to position
+  scrollToPosition(position, offset) {
+    const item = this._itemContainer.children[position]
+    if (item) {
+      item.scrollIntoView({ behavior: 'smooth', block: 'start' })
+    }
+  }
+
+  // Request focus on item
+  requestChildFocus(position) {
+    const item = this._itemContainer.children[position]
+    if (item) {
+      item.focus()
+    }
+  }
+
+  // Set span count for grid layout
+  setSpanCount(count) {
+    if (count > 0) {
+      this._itemContainer.style.setProperty('--span-count', count)
+    }
+  }
+
+  // Cleanup when component is destroyed
+  destroy() {
+    // Unregister from FastListModule updates
+    unregisterFastListInstance(this)
+    // Call parent destroy if exists
+    if (super.destroy) {
+      super.destroy()
+    }
+  }
+
+  /**
+   * 处理焦点导航 - 根据布局类型计算下一个焦点元素
+   * @param {HTMLElement} currentElement 当前焦点元素
+   * @param {string} direction 方向: 'up' | 'down' | 'left' | 'right'
+   * @returns {HTMLElement|null} 下一个焦点元素，如果没有则返回 null
+   */
+  handleFocusNavigation(currentElement, direction) {
+    console.log('[QtFastListView] handleFocusNavigation called:', { direction, currentElement })
+
+    const items = this._itemContainer.children
+    const itemCount = items.length
+    console.log('[QtFastListView] items:', { itemCount })
+
+    if (itemCount === 0) return null
+
+    // 找到当前焦点元素所在的 item
+    let currentItem = null
+    let currentIndex = -1
+    for (let i = 0; i < itemCount; i++) {
+      if (items[i] === currentElement || items[i].contains(currentElement)) {
+        currentItem = items[i]
+        currentIndex = i
+        break
+      }
+    }
+
+    console.log('[QtFastListView] currentIndex:', currentIndex)
+
+    if (currentIndex === -1) return null
+
+    // 尝试在当前 item 内部进行焦点导航
+    const internalNext = this._handleInternalNavigation(currentItem, currentElement, direction)
+    console.log('[QtFastListView] internalNext:', !!internalNext)
+
+    if (internalNext) {
+      return internalNext
+    }
+
+    // 内部导航失败，检查是否在数据边界
+    // 在第一个 item 且向上/左移动，滚动到头部
+    if (currentIndex === 0 && (direction === 'up' || direction === 'left')) {
+      console.log('[QtFastListView] 在第一个 item，滚动到头部')
+      this._scrollToBoundary(direction, currentElement)
+    }
+    // 在最后一个 item 且向下/右移动，滚动到尾部
+    else if (currentIndex === itemCount - 1 && (direction === 'down' || direction === 'right')) {
+      console.log('[QtFastListView] 在最后一个 item，滚动到尾部')
+      this._scrollToBoundary(direction, currentElement)
+    }
+
+    // 尝试导航到其他 item
+    let nextElement = null
+    let nextIndex = -1
+
+    // 默认使用空间距离导航，支持瀑布流和复杂布局
+    const result = this._handleSpatialNavigation(currentElement, direction, items, itemCount)
+    if (result.element) {
+      nextElement = result.element
+      nextIndex = result.index
+    } else {
+      // 空间导航没找到时，作为后备回退到网格/列表基础逻辑
+      if (this._spanCount > 0) {
+        const fallback = this._handleGridNavigation(currentIndex, direction, items, itemCount)
+        nextElement = fallback.element
+        nextIndex = fallback.index
+      } else {
+        const fallback = this._handleListNavigation(currentIndex, direction, items, itemCount)
+        nextElement = fallback.element
+        nextIndex = fallback.index
+      }
+    }
+
+    console.log('[QtFastListView] navigation result:', { nextIndex, hasElement: !!nextElement })
+
+    return nextElement
+  }
+
+  updateBlockFocusDirections(currentElement) {
+    if (!currentElement || !this._itemContainer) return
+
+    if (
+      currentElement.hasAttribute &&
+      (currentElement.hasAttribute('blockFocusDirections') ||
+        currentElement.hasAttribute('blockfocusdirections'))
+    ) {
+      return
+    }
+
+    const items = this._itemContainer.children
+    const itemCount = items.length
+    if (itemCount === 0) return
+
+    let currentIndex = -1
+    for (let i = 0; i < itemCount; i++) {
+      if (items[i] === currentElement || items[i].contains(currentElement)) {
+        currentIndex = i
+        break
+      }
+    }
+    if (currentIndex === -1) return
+
+    // 默认不应该阻止焦点移出列表，这会导致无法导航到 Tabs 等外部组件
+    // 只有在组件自身设置了 blockFocusDirections 时才生效
+    // const blocked = []
+    // if (this._horizontal) {
+    //   if (currentIndex === 0) blocked.push('left')
+    //   if (currentIndex === itemCount - 1) blocked.push('right')
+    // } else {
+    //   if (currentIndex === 0) blocked.push('up')
+    //   if (currentIndex === itemCount - 1) blocked.push('down')
+    // }
+
+    // if (blocked.length > 0) {
+    //   currentElement.setAttribute('blockfocusdirections', JSON.stringify(blocked))
+    // } else {
+    //   currentElement.removeAttribute('blockfocusdirections')
+    //   currentElement.removeAttribute('blockFocusDirections')
+    // }
+  }
+
+  /**
+   * 滚动到列表边界（头部或尾部）
+   * @param {string} direction - 'left', 'right', 'up', 'down'
+   * @param {HTMLElement} currentElement - 当前焦点的元素
+   */
+  _scrollToBoundary(direction, currentElement) {
+    if (!this.dom) return
+
+    // 为了实现嵌套列表（如 Waterfall -> Section -> Item）的精确边界滚动
+    // 我们需要判断当前元素是否“真的”在这个方向的逻辑边缘上
+    // 如果它不是在边缘，说明只是局部移动被拦截，不应该触发整个外层列表的回滚
+
+    // 获取当前列表所有直接的项
+    const items = this._itemContainer ? Array.from(this._itemContainer.children) : []
+    if (items.length === 0 || !currentElement) return
+
+    // 找到当前焦点元素所属的顶层项 (item)
+    let currentItem = null
+    let currentIndex = -1
+    for (let i = 0; i < items.length; i++) {
+      if (items[i] === currentElement || items[i].contains(currentElement)) {
+        currentItem = items[i]
+        currentIndex = i
+        break
+      }
+    }
+
+    if (currentIndex === -1) return
+
+    // 获取所有可见项的坐标，用于判断是否是第一行/最后一行
+    const itemRects = items
+      .map((item) => ({
+        el: item,
+        rect: item.getBoundingClientRect(),
+      }))
+      .filter((info) => info.rect.width > 0 && info.rect.height > 0)
+
+    if (itemRects.length === 0) return
+
+    const currentRect = currentItem.getBoundingClientRect()
+
+    // 判断是否处于该方向的“最前排”
+    let isAtBoundary = false
+    const tolerance = 20 // 20px的行高容差
+
+    if (this._horizontal) {
+      if (direction === 'left') {
+        // 判断是否是最左边的一列（没有比它明显更靠左的元素）
+        const minLeft = Math.min(...itemRects.map((i) => i.rect.left))
+        isAtBoundary = currentRect.left <= minLeft + tolerance
+        if (isAtBoundary) {
+          // 这里必须直接设置 scrollTop/scrollLeft 为 0，而不是调用 scrollTo，
+          // 因为 scrollTo 可能受到 CSS scroll-behavior 或其他库的干扰，导致滚动不到位。
+          // 对于“回滚到边缘”的操作，直接重置是最稳妥的。
+          this.dom.scrollLeft = 0
+        }
+      } else if (direction === 'right') {
+        // 判断是否是最右边的一列
+        const maxRight = Math.max(...itemRects.map((i) => i.rect.right))
+        isAtBoundary = currentRect.right >= maxRight - tolerance
+        if (isAtBoundary) {
+          this.dom.scrollLeft = this.dom.scrollWidth
+        }
+      }
+    } else {
+      if (direction === 'up') {
+        // 判断是否是最高的一行（第一行）
+        const minTop = Math.min(...itemRects.map((i) => i.rect.top))
+        isAtBoundary = currentRect.top <= minTop + tolerance
+        if (isAtBoundary) {
+          // console.log(`[QtFastListView] Scroll to top triggered for ${this.dom.id}`);
+          this.dom.scrollTop = 0
+          // 如果外层还有滚动容器（比如页面本身的 body），也尝试重置一下，防止因为局部滚动导致的视差
+          if (this.dom.parentElement && this.dom.parentElement.scrollTop > 0) {
+            this.dom.parentElement.scrollTop = 0
+          }
+        }
+      } else if (direction === 'down') {
+        // 判断是否是最底的一行（最后一行）
+        const maxBottom = Math.max(...itemRects.map((i) => i.rect.bottom))
+        isAtBoundary = currentRect.bottom >= maxBottom - tolerance
+        if (isAtBoundary) {
+          this.dom.scrollTop = this.dom.scrollHeight
+        }
+      }
+    }
+  }
+
+  /**
+   * 处理 item 内部的焦点导航
+   * 当 item 内部有多个可聚焦元素时，先在内部导航
+   */
+  _handleInternalNavigation(item, currentElement, direction) {
+    // 查找 item 内所有可聚焦元素
+    const focusables = item.querySelectorAll('[focusable="true"]')
+    if (focusables.length <= 1) {
+      return null // 只有一个或没有可聚焦元素，无法内部导航
+    }
+
+    // 找到当前焦点在可聚焦元素列表中的位置
+    let currentFocusIndex = -1
+    for (let i = 0; i < focusables.length; i++) {
+      if (focusables[i] === currentElement || focusables[i].contains(currentElement)) {
+        currentFocusIndex = i
+        break
+      }
+    }
+
+    if (currentFocusIndex === -1) {
+      return null
+    }
+
+    // 根据方向计算下一个焦点
+    // 获取可聚焦元素的布局信息
+    const focusableRects = Array.from(focusables).map((el) => ({
+      el,
+      rect: el.getBoundingClientRect(),
+    }))
+
+    const currentRect = focusableRects[currentFocusIndex].rect
+    let nextElement = null
+    let minDistance = Infinity
+
+    focusableRects.forEach((item, index) => {
+      if (index === currentFocusIndex) return
+
+      const rect = item.rect
+      let distance = Infinity
+      let isValidDirection = false
+
+      switch (direction) {
+        case 'up':
+          // 目标元素在当前元素上方
+          if (rect.bottom <= currentRect.top) {
+            distance = Math.abs(rect.left - currentRect.left) + (currentRect.top - rect.bottom)
+            isValidDirection = true
+          }
+          break
+        case 'down':
+          // 目标元素在当前元素下方
+          if (rect.top >= currentRect.bottom) {
+            distance = Math.abs(rect.left - currentRect.left) + (rect.top - currentRect.bottom)
+            isValidDirection = true
+          }
+          break
+        case 'left':
+          // 目标元素在当前元素左边
+          if (rect.right <= currentRect.left) {
+            distance = Math.abs(rect.top - currentRect.top) + (currentRect.left - rect.right)
+            isValidDirection = true
+          }
+          break
+        case 'right':
+          // 目标元素在当前元素右边
+          if (rect.left >= currentRect.right) {
+            distance = Math.abs(rect.top - currentRect.top) + (rect.left - currentRect.right)
+            isValidDirection = true
+          }
+          break
+      }
+
+      if (isValidDirection && distance < minDistance) {
+        minDistance = distance
+        nextElement = item.el
+      }
+    })
+
+    return nextElement
+  }
+
+  /**
+   * 获取 item 内实际可聚焦的元素
+   * @param {HTMLElement} item - 目标 item
+   * @param {string} direction - 导航方向 ('up'|'down'|'left'|'right')，用于选择最近的焦点
+   */
+  _getFocusableInItem(item, direction = null) {
+    // 如果 item 本身可聚焦
+    if (item.getAttribute('focusable') === 'true') {
+      return item
+    }
+
+    // 查找子元素中的所有可聚焦元素
+    const focusables = item.querySelectorAll('[focusable="true"]')
+    if (focusables.length === 0) {
+      // 没有找到可聚焦元素，返回 item 本身
+      return item
+    }
+
+    if (focusables.length === 1 || !direction) {
+      // 只有一个可聚焦元素，或没有方向信息，直接返回第一个
+      return focusables[0]
+    }
+
+    // 有多个可聚焦元素，根据方向选择最近的
+    // 获取所有可聚焦元素的位置信息
+    const focusableRects = Array.from(focusables).map((el) => ({
+      el,
+      rect: el.getBoundingClientRect(),
+    }))
+
+    // 根据方向选择最佳元素
+    // up: 选择最下方的元素（从下面进入）
+    // down: 选择最上方的元素（从上面进入）
+    // left: 选择最右边的元素（从右边进入）
+    // right: 选择最左边的元素（从左边进入）
+    let bestElement = focusableRects[0].el
+    let bestValue = null
+
+    focusableRects.forEach((item) => {
+      const rect = item.rect
+      let value
+
+      switch (direction) {
+        case 'up':
+          // 从下往上导航，选择最下方的元素
+          value = rect.bottom
+          if (bestValue === null || value > bestValue) {
+            bestValue = value
+            bestElement = item.el
+          }
+          break
+        case 'down':
+          // 从上往下导航，选择最上方的元素
+          value = rect.top
+          if (bestValue === null || value < bestValue) {
+            bestValue = value
+            bestElement = item.el
+          }
+          break
+        case 'left':
+          // 从右往左导航，选择最右边的元素
+          value = rect.right
+          if (bestValue === null || value > bestValue) {
+            bestValue = value
+            bestElement = item.el
+          }
+          break
+        case 'right':
+          // 从左往右导航，选择最左边的元素
+          value = rect.left
+          if (bestValue === null || value < bestValue) {
+            bestValue = value
+            bestElement = item.el
+          }
+          break
+      }
+    })
+
+    return bestElement
+  }
+
+  /**
+   * 基于空间距离的焦点导航（适用于瀑布流或不规则布局）
+   */
+  _handleSpatialNavigation(currentElement, direction, items, itemCount) {
+    if (!currentElement) return { element: null, index: -1 }
+
+    const currentRect = currentElement.getBoundingClientRect()
+    // 计算中心点坐标（相对于视口）
+    const currentCenter = {
+      x: currentRect.left + currentRect.width / 2,
+      y: currentRect.top + currentRect.height / 2,
+    }
+
+    console.log(
+      `[QtFastListView] SpatialNav start - Current Focus Center: (${currentCenter.x}, ${currentCenter.y}), direction: ${direction}`
+    )
+
+    let bestElement = null
+    let bestIndex = -1
+    let bestDistance = Infinity
+    const crossWeight = 0.5 // 侧向距离权重
+
+    // 获取所有项的实际位置（处理绝对定位和相对定位）
+    for (let i = 0; i < itemCount; i++) {
+      const item = items[i]
+      // 跳过不可见的项
+      if (item.style.display === 'none') continue
+
+      const focusable = this._getFocusableInItem(item, direction)
+      if (!focusable || focusable === currentElement) continue
+
+      // 如果整个 item 都不可聚焦（如瀑布流的空标题），跳过
+      if (focusable === item && item.getAttribute('focusable') !== 'true') continue
+
+      // 必须使用 getBoundingClientRect 获取真实视口坐标，因为 waterfall 的子项可能是绝对定位的
+      const rect = focusable.getBoundingClientRect()
+      // 跳过尺寸为 0 的不可见元素
+      if (rect.width === 0 && rect.height === 0) continue
+
+      const center = {
+        x: rect.left + rect.width / 2,
+        y: rect.top + rect.height / 2,
+      }
+
+      const dx = center.x - currentCenter.x
+      const dy = center.y - currentCenter.y
+
+      let isInDirection = false
+      let primaryDistance = 0
+      let crossDistance = 0
+
+      switch (direction) {
+        case 'up':
+          isInDirection = dy < -5 // 减小容差，更精确匹配
+          primaryDistance = Math.abs(dy)
+          crossDistance = Math.abs(dx)
+          break
+        case 'down':
+          isInDirection = dy > 5
+          primaryDistance = Math.abs(dy)
+          crossDistance = Math.abs(dx)
+          break
+        case 'left':
+          isInDirection = dx < -5
+          primaryDistance = Math.abs(dx)
+          crossDistance = Math.abs(dy)
+          break
+        case 'right':
+          isInDirection = dx > 5
+          primaryDistance = Math.abs(dx)
+          crossDistance = Math.abs(dy)
+          break
+      }
+
+      if (isInDirection) {
+        // 主方向距离 + 侧向距离加权
+        // 对于左右移动，如果 y 轴差异很大（不在同一行），应大大增加距离惩罚
+        if ((direction === 'left' || direction === 'right') && Math.abs(dy) > rect.height / 2) {
+          crossDistance *= 5 // 如果不在同一行，极大地降低其被选中的概率
+        }
+
+        // 对于上下移动，如果 x 轴差异很大（不在同一列），应大大增加距离惩罚
+        if ((direction === 'up' || direction === 'down') && Math.abs(dx) > rect.width / 2) {
+          crossDistance *= 5
+        }
+
+        const distance = primaryDistance + crossDistance * crossWeight
+
+        console.log(
+          `[QtFastListView] SpatialNav candidate - Index: ${i}, Center: (${center.x}, ${center.y}), dx: ${dx}, dy: ${dy}, distance: ${distance}`
+        )
+
+        if (distance < bestDistance) {
+          bestDistance = distance
+          bestElement = focusable
+          bestIndex = i
+        }
+      }
+    }
+
+    if (bestElement) {
+      console.log(
+        `[QtFastListView] SpatialNav success - Best Index: ${bestIndex}, distance: ${bestDistance}`
+      )
+    } else {
+      console.log(
+        `[QtFastListView] SpatialNav failed - No candidate found for direction ${direction}`
+      )
+    }
+
+    return { element: bestElement, index: bestIndex }
+  }
+
+  /**
+   * 网格布局的焦点导航
+   * @returns { element: HTMLElement|null, index: number }
+   */
+  _handleGridNavigation(currentIndex, direction, items, itemCount) {
+    const spanCount = this._spanCount
+    let currentRow = Math.floor(currentIndex / spanCount)
+    let currentCol = currentIndex % spanCount
+
+    let nextIndex = currentIndex
+
+    while (true) {
+      switch (direction) {
+        case 'up':
+          if (currentRow > 0) {
+            nextIndex -= spanCount
+            currentRow--
+          } else {
+            nextIndex = -1
+          }
+          break
+        case 'down':
+          nextIndex += spanCount
+          currentRow++
+          if (nextIndex >= itemCount) {
+            nextIndex = -1
+          }
+          break
+        case 'left':
+          if (currentCol > 0) {
+            nextIndex -= 1
+            currentCol--
+          } else {
+            nextIndex = -1
+          }
+          break
+        case 'right':
+          if (currentCol < spanCount - 1 && nextIndex + 1 < itemCount) {
+            nextIndex += 1
+            currentCol++
+          } else {
+            nextIndex = -1
+          }
+          break
+      }
+
+      if (nextIndex >= 0 && nextIndex < itemCount) {
+        const focusable = this._getFocusableInItem(items[nextIndex], direction)
+        if (
+          focusable !== items[nextIndex] ||
+          items[nextIndex].getAttribute('focusable') === 'true'
+        ) {
+          return { element: focusable, index: nextIndex }
+        }
+        // 如果当前项不可聚焦，继续在同方向上查找
+        continue
+      }
+
+      break
+    }
+
+    return { element: null, index: -1 }
+  }
+
+  /**
+   * 列表布局的焦点导航
+   * @returns { element: HTMLElement|null, index: number }
+   */
+  _handleListNavigation(currentIndex, direction, items, itemCount) {
+    let nextIndex = currentIndex
+
+    while (true) {
+      if (this._horizontal) {
+        // 水平列表
+        switch (direction) {
+          case 'left':
+            if (nextIndex > 0) {
+              nextIndex -= 1
+            } else {
+              nextIndex = -1
+            }
+            break
+          case 'right':
+            if (nextIndex < itemCount - 1) {
+              nextIndex += 1
+            } else {
+              nextIndex = -1
+            }
+            break
+          default:
+            nextIndex = -1
+            break
+        }
+      } else {
+        // 垂直列表
+        switch (direction) {
+          case 'up':
+            if (nextIndex > 0) {
+              nextIndex -= 1
+            } else {
+              nextIndex = -1
+            }
+            break
+          case 'down':
+            if (nextIndex < itemCount - 1) {
+              nextIndex += 1
+            } else {
+              nextIndex = -1
+            }
+            break
+          default:
+            nextIndex = -1
+            break
+        }
+      }
+
+      if (nextIndex >= 0 && nextIndex < itemCount) {
+        const focusable = this._getFocusableInItem(items[nextIndex], direction)
+        if (
+          focusable !== items[nextIndex] ||
+          items[nextIndex].getAttribute('focusable') === 'true'
+        ) {
+          return { element: focusable, index: nextIndex }
+        }
+        // 如果当前项不可聚焦，继续在同方向上查找
+        continue
+      }
+
+      break
+    }
+
+    return { element: null, index: -1 }
+  }
+
+  // Extract the actual value from a ${prop} placeholder
+  _extractValue(placeholder, data) {
+    return extractTemplateValue(placeholder, data)
+  }
+
+  // Apply flexStyle object to a DOM element
+  _applyFlexStyleToElement(element, styleObj) {
+    if (!styleObj || typeof styleObj !== 'object') return
+
+    Object.keys(styleObj).forEach((key) => {
+      let value = styleObj[key]
+
+      if (typeof value === 'number') {
+        const needsPx = [
+          'width',
+          'height',
+          'minWidth',
+          'minHeight',
+          'maxWidth',
+          'maxHeight',
+          'padding',
+          'paddingTop',
+          'paddingRight',
+          'paddingBottom',
+          'paddingLeft',
+          'margin',
+          'marginTop',
+          'marginRight',
+          'marginBottom',
+          'marginLeft',
+          'top',
+          'left',
+          'right',
+          'bottom',
+          'borderRadius',
+          'borderWidth',
+          'fontSize',
+          'lineHeight',
+          'letterSpacing',
+          'gap',
+          'rowGap',
+          'columnGap',
+        ].includes(key)
+
+        if (needsPx) {
+          value = value + 'px'
+        }
+      }
+
+      try {
+        element.style[key] = value
+      } catch (e) {
+        try {
+          const cssKey = key.replace(/([A-Z])/g, '-$1').toLowerCase()
+          element.style.setProperty(cssKey, value)
+        } catch (err) {
+          // Ignore style errors
+        }
+      }
+    })
+  }
+
+  // Override updateChildzIndex to safely handle null children
+  updateChildzIndex() {
+    if (!this.dom) return
+    const uiManager = this.context.getModuleByName('UIManagerModule')
+    this.dom.childNodes.forEach((item) => {
+      const childDom = uiManager.findViewById(item.id)
+      if (!childDom) return
+
+      if (this.exitChildrenStackContext && childDom.props?.style?.zIndex !== undefined) {
+        childDom.updateSelfStackContext()
+      }
+      if (!this.exitChildrenStackContext && childDom.updatedZIndex) {
+        childDom.updateSelfStackContext(false)
+      }
+    })
+  }
+}
+
+function parseDomTemplateType(element) {
+  if (!element || element.nodeType !== Node.ELEMENT_NODE) return null
+  const raw = element.getAttribute('data-template-type') ?? element.getAttribute('type')
+  if (raw === null || raw === undefined || raw === '') return null
+  return isNaN(Number(raw)) ? raw : Number(raw)
+}
+
+function collectDomTemplates(rootElement, itemContainer) {
+  const templates = []
+  const directChildren = Array.from(rootElement.children || []).filter(
+    (child) => child !== itemContainer
+  )
+
+  directChildren.forEach((element) => {
+    const ownType = parseDomTemplateType(element)
+    const isSingleton =
+      element.hasAttribute?.('singleton') || element.hasAttribute?.('data-singleton')
+
+    if (ownType !== null || isSingleton) {
+      element.setAttribute(isSingleton ? 'data-singleton' : 'data-template', 'true')
+      if (ownType !== null) {
+        element.setAttribute('data-template-type', String(ownType))
+      }
+      element.style.display = 'none'
+      templates.push({ dom: element, type: ownType, singleton: isSingleton })
+      return
+    }
+
+    const nestedTemplates = element.querySelectorAll
+      ? Array.from(
+          element.querySelectorAll('[type], [data-template-type], [singleton], [data-singleton]')
+        )
+      : []
+
+    if (nestedTemplates.length > 0) {
+      element.style.display = 'none'
+      nestedTemplates.forEach((nested) => {
+        const nestedType = parseDomTemplateType(nested)
+        const nestedSingleton =
+          nested.hasAttribute?.('singleton') || nested.hasAttribute?.('data-singleton')
+        nested.setAttribute(nestedSingleton ? 'data-singleton' : 'data-template', 'true')
+        if (nestedType !== null) {
+          nested.setAttribute('data-template-type', String(nestedType))
+        }
+        nested.style.display = 'none'
+        templates.push({ dom: nested, type: nestedType, singleton: nestedSingleton })
+      })
+      return
+    }
+
+    element.setAttribute('data-template', 'true')
+    element.style.display = 'none'
+    templates.push({ dom: element, type: null, singleton: false })
+  })
+
+  return templates
+}
+
+function configureDomListItemContainer(rootElement, itemContainer) {
+  const isHorizontal =
+    rootElement.hasAttribute('horizontal') || rootElement.getAttribute('horizontal') === ''
+
+  const spanCountValue =
+    rootElement.getAttribute('spanCount') || rootElement.getAttribute('span-count') || '0'
+  const spanCount = Number(spanCountValue) || 0
+
+  if (spanCount > 0) {
+    itemContainer.style.display = 'grid'
+    itemContainer.style.gridTemplateColumns = `repeat(${spanCount}, 1fr)`
+    itemContainer.style.flexDirection = ''
+    itemContainer.style.flexWrap = ''
+    itemContainer.style.overflowX = 'hidden'
+    itemContainer.style.overflowY = 'auto'
+    return
+  }
+
+  itemContainer.style.display = 'flex'
+  itemContainer.style.gridTemplateColumns = ''
+
+  if (isHorizontal) {
+    itemContainer.style.flexDirection = 'row'
+    itemContainer.style.flexWrap = 'nowrap'
+    itemContainer.style.overflowX = 'auto'
+    itemContainer.style.overflowY = 'hidden'
+    return
+  }
+
+  itemContainer.style.flexDirection = 'column'
+  itemContainer.style.flexWrap = 'nowrap'
+  itemContainer.style.overflowX = 'hidden'
+  itemContainer.style.overflowY = 'auto'
+}
+
+function bindDomOnlyListNode(node, itemData, listData) {
+  bindTemplateDataToNode(node, itemData, {
+    scope: { itemList: listData },
+    onListData: (element, value) => {
+      element._qtListData = value
+      element.setAttribute('data-has-list', 'true')
+    },
+  })
+}
+
+export function renderQtFastListViewInPlace(rootElement, listData) {
+  if (!rootElement) return
+  if (Array.isArray(listData) && listData.length === 1 && Array.isArray(listData[0])) {
+    listData = listData[0]
+  }
+  if (!Array.isArray(listData)) return
+  if (rootElement.style.display === 'none') {
+    rootElement.style.display = ''
+  }
+
+  let itemContainer = Array.from(rootElement.children || []).find(
+    (child) => child.classList && child.classList.contains('fast-list-item-container')
+  )
+
+  if (!itemContainer) {
+    itemContainer = document.createElement('div')
+    itemContainer.className = 'fast-list-item-container'
+    rootElement.appendChild(itemContainer)
+  }
+
+  configureDomListItemContainer(rootElement, itemContainer)
+
+  const templates = collectDomTemplates(rootElement, itemContainer)
+  const sharedTemplates = window.__QT_SHARED_TEMPLATES__
+  itemContainer.innerHTML = ''
+
+  if (listData.length === 0) {
+    return
+  }
+
+  const renderedSingletonTypes = new Set()
+  const singletonTemplates = templates.filter((template) => template.singleton)
+  const regularTemplates = templates.filter((template) => !template.singleton)
+
+  singletonTemplates.forEach((template) => {
+    let matchingData = null
+    if (template.type !== null && template.type !== undefined) {
+      matchingData = listData.find((item) => item?.type === template.type) || null
+    } else {
+      matchingData = listData[0] || null
+    }
+    if (!matchingData) {
+      template.dom.style.display = 'none'
+      return
+    }
+    template.dom.style.display = ''
+    bindDomOnlyListNode(template.dom, matchingData, listData)
+    applyDomOnlyTemplateRootDefaults(template.dom)
+    itemContainer.appendChild(template.dom)
+    if (matchingData.type !== null && matchingData.type !== undefined) {
+      renderedSingletonTypes.add(matchingData.type)
+    }
+  })
+
+  const renderTemplates = regularTemplates.length > 0 ? regularTemplates : templates
+  listData.forEach((itemData, index) => {
+    if (renderedSingletonTypes.has(itemData?.type)) {
+      return
+    }
+
+    let matchingTemplate = renderTemplates.find((template) => template.type === itemData?.type)
+    if (
+      !matchingTemplate &&
+      sharedTemplates &&
+      itemData?.type !== null &&
+      itemData?.type !== undefined
+    ) {
+      const sharedByType = sharedTemplates.get(itemData.type)
+      if (sharedByType?.dom) {
+        matchingTemplate = sharedByType
+      }
+    }
+    if (!matchingTemplate) {
+      matchingTemplate = renderTemplates.find((template) => template.type === null)
+    }
+    if (!matchingTemplate) {
+      if (sharedTemplates && sharedTemplates.size > 0) {
+        const firstShared = sharedTemplates.values().next().value
+        if (firstShared?.dom) {
+          matchingTemplate = firstShared
+        }
+      }
+    }
+    if (!matchingTemplate) {
+      matchingTemplate = renderTemplates[0]
+    }
+    if (!matchingTemplate?.dom) {
+      return
+    }
+
+    const itemWrapper = document.createElement('div')
+    itemWrapper.setAttribute('data-index', index)
+    itemWrapper.setAttribute('data-position', index)
+    itemWrapper._itemData = itemData
+    itemWrapper._itemPosition = index
+
+    if (itemData && itemData.decoration && typeof itemData.decoration === 'object') {
+      const decoration = itemData.decoration
+      if (decoration.top !== undefined) itemWrapper.style.marginTop = decoration.top + 'px'
+      if (decoration.left !== undefined) itemWrapper.style.marginLeft = decoration.left + 'px'
+      if (decoration.right !== undefined) itemWrapper.style.marginRight = decoration.right + 'px'
+      if (decoration.bottom !== undefined) itemWrapper.style.marginBottom = decoration.bottom + 'px'
+    }
+
+    const clonedNode = matchingTemplate.dom.cloneNode(true)
+    clonedNode.removeAttribute('data-template')
+    clonedNode.removeAttribute('data-singleton')
+    clonedNode.style.display = ''
+    clonedNode.style.position = 'relative'
+
+    bindDomOnlyListNode(clonedNode, itemData, listData)
+    applyDomOnlyTemplateRootDefaults(clonedNode)
+
+    itemWrapper.appendChild(clonedNode)
+    itemContainer.appendChild(itemWrapper)
+  })
+
+  requestAnimationFrame(() => syncDomAutoWidthIn(itemContainer))
+}