PrimeVue DataTable Frozen Column 錯位之謎：兩層 Root Cause，與一個 ResizeObserver Directive 解法

updateStickyPosition() {
  if (this.columnProp('frozen')) {
    let align = this.columnProp('alignFrozen');
    if (align === 'right') {
      let pos = 0;
      let next = getNextElementSibling(this.$el, '[data-p-frozen-column="true"]');
      if (next) {
        pos = getOuterWidth(next) + parseFloat(next.style.right || 0);
      }
      this.styleObject.right = pos + 'px';
    } else {
      let pos = 0;
      let prev = getPreviousElementSibling(this.$el, '[data-p-frozen-column="true"]');
      if (prev) {
        // left = 前一個 frozen sibling 的「當下 DOM 寬度」+ 它的 inline left
        pos = getOuterWidth(prev) + parseFloat(prev.style.left || 0);
      }
      this.styleObject.left = pos + 'px';
    }
  }
}

<DataTable scrollable table-style="min-width: 60rem">
  <Column frozen field="name" style="width: 10rem; min-width: 10rem" />
  <Column frozen field="id" style="width: 7rem; min-width: 7rem" />
  <Column field="other" /> <!-- 非凍結欄可以流動 -->
</DataTable>

@for $i from 1 through 10 {
  .p-datatable-frozen-column:nth-child(#{$i}) {
    left: var(--frozen-left-#{$i}, 0px) !important;
  }
}

<Column
  v-for="(col, i) in columns"
  :frozen="col.frozen"
  :style="col.frozen ? { '--frozen-left': `${offsets[i] ?? 0}px` } : undefined"
/>

.p-datatable-frozen-column {
  left: var(--frozen-left, auto) !important;
}

/**
 * v-frozen-sync — 修正 PrimeVue DataTable frozen column 的定位失效問題。
 *
 * PrimeVue 對 frozen column 的 sticky offset 是在 cell mounted/updated 時各自量測、
 * 寫成 inline style 的固定 px 值：
 * 1. 純 layout 變化（scrollbar 出現/消失、容器寬度改變）不會觸發重算，offset 過期。
 * 2. 即使重算，讀的是前一個 sibling 尚未 patch 的舊 inline style，重算鏈可能中斷，
 *    造成部分 cell 永久停在錯誤位置（上游未修，見 primefaces/primevue#5331、#1473）。
 *
 * 此 directive 改由單一 ResizeObserver 集中計算所有 frozen column 的 offset，
 * 以 runtime 生成的 CSS 規則（!important）覆蓋 PrimeVue 的 inline style。
 *
 * 用法：<PrimeDataTable v-frozen-sync scrollable ...>
 *
 * 限制：
 * - 僅支援單層 header（column group / colspan 會使 nth-child 對應失準）。
 * - 方向判斷依賴 PrimeVue 在 frozen cell 上寫入單側 inline style 的行為
 *   （4.0.5 寫 left/right，新版改寫 inset-inline-*，兩者皆已相容）；升級 PrimeVue 後需重新驗證。
 * - 極端時序下（ResizeObserver callback 早於 PrimeVue 寫入 inline style）該輪會跳過寫入，
 *   待下次尺寸變化自動修正。
 */

interface FrozenSyncController {
  refresh: () => void
  destroy: () => void
}

const controllers = new WeakMap<HTMLElement, FrozenSyncController>()
let scopeSeq = 0

function frozenSide(headerCell: HTMLElement): 'left' | 'right' | null {
  const { left, right, insetInlineStart, insetInlineEnd } = headerCell.style
  if (right !== '' || insetInlineEnd !== '') {
    return 'right'
  }
  if (left !== '' || insetInlineStart !== '') {
    return 'left'
  }
  // PrimeVue 尚未寫入 inline style（cell 剛 mount、patch 未落地），方向未知
  return null
}

function buildRule(scopeId: string, columnIndex: number, side: 'left' | 'right', offset: number) {
  // 只用直接子層選擇器，避免影響巢狀（row expansion 內）的 DataTable
  const cellSelectors = [
    `> .p-datatable-thead > tr > th.p-datatable-frozen-column:nth-child(${columnIndex + 1})`,
    `> .p-datatable-tbody > tr > td.p-datatable-frozen-column:nth-child(${columnIndex + 1})`,
    `> .p-datatable-tfoot > tr > td.p-datatable-frozen-column:nth-child(${columnIndex + 1})`,
  ]
    .map(selector => `[data-frozen-sync="${scopeId}"] ${selector}`)
    .join(',')
  const oppositeSide = side === 'left' ? 'right' : 'left'
  return `${cellSelectors}{${side}:${offset}px !important;${oppositeSide}:auto !important}`
}

function attachFrozenSync(rootEl: HTMLElement): FrozenSyncController | undefined {
  const table = rootEl.querySelector<HTMLElement>('.p-datatable-table')
  if (!table) {
    return undefined
  }

  const scopeId = `fs-${++scopeSeq}`
  table.setAttribute('data-frozen-sync', scopeId)
  const styleEl = document.createElement('style')
  document.head.appendChild(styleEl)

  const headerCells = () => [
    ...table.querySelectorAll<HTMLElement>('.p-datatable-thead > tr:first-child > th'),
  ]
  const isFrozen = (cell: HTMLElement) => cell.dataset.pFrozenColumn === 'true'

  const update = () => {
    // 隱藏容器（display: none）下寬度全為 0，寫入只會產生 left:0 的垃圾規則；
    // 容器顯示時 ResizeObserver 會再次觸發，屆時再算
    if (table.getBoundingClientRect().width === 0) {
      return
    }

    const cells = headerCells()
    const sides = cells.map(cell => (isFrozen(cell) ? frozenSide(cell) : undefined))
    // 任一 frozen cell 方向未知（PrimeVue inline style 尚未寫入）就整批跳過，
    // 保留既有規則，等下一次 callback 再算
    if (sides.includes(null)) {
      return
    }

    const rules: string[] = []

    let offset = 0
    cells.forEach((cell, index) => {
      if (sides[index] === 'left') {
        rules.push(buildRule(scopeId, index, 'left', offset))
        offset += cell.getBoundingClientRect().width
      }
    })

    offset = 0
    for (let index = cells.length - 1; index >= 0; index--) {
      if (sides[index] === 'right') {
        rules.push(buildRule(scopeId, index, 'right', offset))
        offset += cells[index].getBoundingClientRect().width
      }
    }

    const css = rules.join('\n')
    if (styleEl.textContent !== css) {
      styleEl.textContent = css
    }
  }

  // directive lifecycle 沒有 active component instance，@vueuse 的 useResizeObserver
  // 依賴 getCurrentInstance 掛載清理，這裡必須直接使用原生 ResizeObserver
  const observer = new ResizeObserver(update)
  let observed: HTMLElement[] = []

  // observe() 會觸發 ResizeObserver 的 initial callback，等同重算一次
  const observe = () => {
    observer.disconnect()
    observed = [table, ...headerCells().filter(isFrozen)]
    observed.forEach(target => observer.observe(target))
  }
  observe()

  // 觀察目標沒變（一般 re-render）只重算 CSS；
  // 有變（欄位增減、th 重建）才重建觀察，避免每次 re-render 都 disconnect/re-observe
  const refresh = () => {
    const targets = [table, ...headerCells().filter(isFrozen)]
    const changed
      = targets.length !== observed.length || targets.some((target, index) => target !== observed[index])
    if (changed) {
      observer.disconnect()
      observed = targets
      targets.forEach(target => observer.observe(target))
      return
    }
    update()
  }

  return {
    refresh,
    destroy: () => {
      observer.disconnect()
      styleEl.remove()
      table.removeAttribute('data-frozen-sync')
    },
  }
}

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.directive<HTMLElement>('frozen-sync', {
    mounted(el) {
      const controller = attachFrozenSync(el)
      if (controller) {
        controllers.set(el, controller)
      }
    },
    updated(el) {
      const controller = controllers.get(el)
      // 首次 mounted 時 table 可能尚未渲染（如延遲載入），在 updated 補掛
      if (!controller) {
        const attached = attachFrozenSync(el)
        if (attached) {
          controllers.set(el, attached)
        }
        return
      }
      controller.refresh()
    },
    unmounted(el) {
      controllers.get(el)?.destroy()
      controllers.delete(el)
    },
  })
})

<DataTable v-frozen-sync :value="rows" scrollable scroll-height="flex">
  <Column field="name" header="Name" frozen />
  <Column field="balance" header="Balance" frozen align-frozen="right" />
  <Column field="company" header="Company" />
</DataTable>