@astronox/core 0.2.0 → 0.2.2

package/src/patterns/Table/tableProgressiveController.ts

@@ -1,319 +1,707 @@
+import type {
+  TableProgressiveEntry,
+  TableProgressiveModel,
+} from '../../display/contracts';
+import { tableProgressiveBatchSize } from '../../display/tableProgressive';
+
 const initializedAttribute = 'data-table-progressive-initialized';
 
-type ProgressiveState = 'idle' | 'loading' | 'error' | 'complete';
+type PaginationState = 'idle' | 'loading' | 'error' | 'complete';
+type TableLoadingState =
+  | 'pending'
+  | 'ready'
+  | 'refreshing'
+  | 'appending'
+  | 'empty'
+  | 'error';
+type SortDirection = 'ascending' | 'descending';
+type SortType = 'number' | 'text';
+type SortValue = string | number | null;
 
 export type TableRowsAppendedDetail = {
   rows: readonly HTMLElement[];
 };
 
+export type TableProgressiveFilterState = {
+  search: string;
+  selections: Readonly<Record<string, string>>;
+};
+
+export type TableProgressiveSortState = {
+  id: string;
+  type: SortType;
+  direction: SortDirection;
+  tieBreaker?: string;
+} | null;
+
+export type TableProgressiveEntryUpdate = {
+  sortValues?: Readonly<Record<string, SortValue>>;
+  exclusion?: {
+    key: string;
+    excluded: boolean;
+  };
+};
+
+type IndexedEntry = TableProgressiveEntry & {
+  index: number;
+  exclusions: Set<string>;
+  normalizedSearch: readonly string[];
+  sortValues: Readonly<Record<string, SortValue>>;
+};
+
+type ProgressiveContext = {
+  destroy(): void;
+  progressive: true;
+  refresh(): void;
+  setFilters(state: TableProgressiveFilterState): void;
+  setSort(state: TableProgressiveSortState): void;
+  updateEntry(key: string, update: TableProgressiveEntryUpdate): void;
+};
+
+const contexts = new WeakMap<HTMLElement, ProgressiveContext>();
+
 export function initTableProgressive(root: HTMLElement): () => void {
   if (root.getAttribute(initializedAttribute) === 'true') {
     return () => undefined;
   }
 
-  const tableKey = root.dataset.tableKey;
+  const manifest = readManifest(root);
   const rowsRoot = root.querySelector<HTMLElement>('[data-table-rows]');
-  const pagination = root.querySelector<HTMLElement>('[data-table-pagination]');
-  const link = pagination?.querySelector<HTMLAnchorElement>(
-    '[data-table-pagination-link]',
+  const skeletonTemplate = root.querySelector<HTMLTemplateElement>(
+    ':scope > [data-table-skeleton-template]',
   );
+
+  if (!rowsRoot || !skeletonTemplate) {
+    return () => undefined;
+  }
+
+  if (!manifest) {
+    if (root.dataset.tablePreparation !== 'controlled') {
+      revealServerRows(root, rowsRoot);
+    }
+    return () => undefined;
+  }
+
+  const pagination = root.querySelector<HTMLElement>('[data-table-pagination]');
   const sentinel = pagination?.querySelector<HTMLElement>(
     '[data-table-pagination-sentinel]',
   );
   const status = pagination?.querySelector<HTMLElement>(
     '[data-table-pagination-status]',
   );
-  const skeletonTemplate = pagination?.querySelector<HTMLTemplateElement>(
-    '[data-table-skeleton-template]',
-  );
+  if (!pagination || !sentinel || !status) {
+    return () => undefined;
+  }
 
-  if (
-    !tableKey ||
-    !rowsRoot ||
-    !pagination ||
-    !link ||
-    !sentinel ||
-    !status ||
-    !skeletonTemplate ||
-    !('IntersectionObserver' in window)
-  ) {
+  const fallbackLink = pagination.querySelector<HTMLAnchorElement>(
+    '[data-table-pagination-link]',
+  );
+  if (!('IntersectionObserver' in window)) {
+    if (root.dataset.tablePreparation !== 'controlled') {
+      revealServerRows(root, rowsRoot);
+    }
+    showFallback(pagination, fallbackLink);
     return () => undefined;
   }
 
   root.setAttribute(initializedAttribute, 'true');
-  const activePagination = pagination;
-  const activeLink = link;
-  const activeStatus = status;
-  activePagination.setAttribute('data-table-progressive-enhanced', 'true');
-  activePagination.removeAttribute('data-surface');
-  setState(activePagination, activeStatus, 'idle');
-
-  const loadedUrls = new Set<string>();
+  pagination.hidden = false;
+  pagination.setAttribute('data-table-progressive-enhanced', 'true');
+  pagination.removeAttribute('data-surface');
+
+  const locale = document.documentElement.lang || undefined;
+  const normalize = (value: string): string =>
+    value
+      .normalize('NFD')
+      .replace(/\p{Diacritic}/gu, '')
+      .toLocaleLowerCase(locale);
+  const entries = manifest.entries.map(
+    (entry, index): IndexedEntry => ({
+      ...entry,
+      index,
+      exclusions: new Set(),
+      normalizedSearch: (entry.filters?.search ?? []).map(normalize),
+      sortValues: entry.sortValues ?? {},
+    }),
+  );
+  const entriesByKey = new Map(entries.map((entry) => [entry.key, entry]));
+  const rowsByKey = new Map<string, HTMLElement>();
+  const loadedSources = new Set<string>();
+  const batchSize = Math.max(
+    1,
+    Math.floor(manifest.batchSize ?? tableProgressiveBatchSize),
+  );
+  const initialOffset = Math.min(
+    Math.max(0, Math.floor(manifest.initialOffset ?? 0)),
+    entries.length,
+  );
+  const empty = root.querySelector<HTMLElement>('[data-table-filter-empty]');
+  const collator = new Intl.Collator(locale, {
+    numeric: true,
+    sensitivity: 'base',
+  });
+  let filterState: TableProgressiveFilterState = {
+    search: '',
+    selections: {},
+  };
+  let sortState: TableProgressiveSortState = null;
+  let results = entries;
+  let cursor = 0;
   let request: AbortController | null = null;
-  let skeletonRows: HTMLElement[] = [];
-  let batchedRows: HTMLElement[] = [];
+  let skeletonRows = getSkeletonRows(rowsRoot);
   let disposed = false;
-  let completed = false;
-  let loadAllRequested = false;
+  let generation = 0;
+  let prepared = false;
+
+  registerRows(getRows(rowsRoot));
 
   const observer = new IntersectionObserver(
-    (entries) => {
-      if (entries.some((entry) => entry.isIntersecting)) {
-        void loadNextPage();
+    (observedEntries) => {
+      if (observedEntries.some((entry) => entry.isIntersecting)) {
+        void renderNextBatch();
       }
     },
     { rootMargin: '600px 0px' },
   );
 
-  const removeSkeleton = (): void => {
+  function registerRows(rows: readonly HTMLElement[]): void {
+    for (const row of rows) {
+      const key = row.dataset.tableRowKey;
+      if (key) rowsByKey.set(key, row);
+    }
+  }
+
+  function removeSkeleton(): void {
     skeletonRows.forEach((row) => row.remove());
     skeletonRows = [];
-  };
-
-  const addSkeleton = (): void => {
-    if (skeletonRows.length > 0) return;
+  }
 
-    const templateRows = skeletonTemplate.content.querySelectorAll<HTMLElement>(
-      '[data-table-skeleton-row]',
-    );
+  function addSkeleton(count: number): void {
+    removeSkeleton();
+    const candidates = Array.from(
+      skeletonTemplate.content.querySelectorAll<HTMLElement>(
+        '[data-table-skeleton-row]',
+      ),
+    ).slice(0, count);
+    skeletonRows = candidates.map((row) => document.importNode(row, true));
+    insertBeforeEmpty(rowsRoot, empty, skeletonRows);
+  }
 
-    skeletonRows = Array.from(templateRows, (row) =>
-      document.importNode(row, true),
-    );
-    rowsRoot.append(...skeletonRows);
-  };
+  function detachRenderedRows(): HTMLElement[] {
+    const rendered = getRows(rowsRoot);
+    rendered.forEach((row) => row.remove());
+    return rendered;
+  }
 
-  const appendRows = (rows: readonly HTMLElement[]): void => {
+  function appendRows(rows: readonly HTMLElement[]): void {
     if (rows.length === 0) return;
-
-    const fragment = document.createDocumentFragment();
-    for (const row of rows) fragment.append(row);
-    rowsRoot.append(fragment);
+    for (const row of rows) row.hidden = false;
+    insertBeforeEmpty(rowsRoot, empty, rows);
     root.dispatchEvent(
       new CustomEvent<TableRowsAppendedDetail>('table:rows-appended', {
         bubbles: true,
         detail: { rows },
       }),
     );
-  };
-
-  const flushBatchedRows = (): void => {
-    if (batchedRows.length === 0) {
-      removeSkeleton();
-      return;
-    }
+  }
 
-    const rows = batchedRows;
-    batchedRows = [];
-    removeSkeleton();
-    appendRows(rows);
-  };
+  function updateEmptyState(): void {
+    if (empty) empty.hidden = results.length > 0;
+  }
 
-  const complete = (): void => {
-    completed = true;
-    flushBatchedRows();
-    loadAllRequested = false;
+  function updatePagination(): void {
     observer.disconnect();
-    activePagination.removeAttribute('data-surface');
-    activePagination.hidden = true;
-    setState(activePagination, activeStatus, 'complete');
-    root.removeAttribute('data-table-progressive-loading-all');
-    root.dispatchEvent(
-      new CustomEvent('table:progressive-complete', { bubbles: true }),
+    const complete = cursor >= results.length;
+    pagination.hidden = complete;
+    setPaginationState(pagination, status, complete ? 'complete' : 'idle');
+    if (!complete) observer.observe(sentinel);
+  }
+
+  function updateTableState(state: TableLoadingState): void {
+    root.dataset.tableLoadingState = state;
+    if (
+      state === 'pending' ||
+      state === 'refreshing' ||
+      state === 'appending'
+    ) {
+      root.setAttribute('aria-busy', 'true');
+    } else {
+      root.removeAttribute('aria-busy');
+    }
+  }
+
+  function applyQuery(): void {
+    const query = normalize(filterState.search.trim());
+    const selections = Object.entries(filterState.selections).filter(
+      ([, value]) => value.length > 0,
     );
-  };
 
-  const showFallback = (): void => {
-    activePagination.removeAttribute('data-table-progressive-enhanced');
-    activePagination.setAttribute('data-surface', '');
-  };
+    results = entries.filter((entry) => {
+      if (entry.exclusions.size > 0) return false;
+      if (
+        query.length > 0 &&
+        !entry.normalizedSearch.some((value) => value.includes(query))
+      ) {
+        return false;
+      }
+      return selections.every(([field, value]) =>
+        (entry.filters?.[field] ?? []).includes(value),
+      );
+    });
+
+    if (sortState) {
+      const state = sortState;
+      results = [...results].sort((left, right) => {
+        const comparison = compareValues(
+          left.sortValues[state.id],
+          right.sortValues[state.id],
+          state.type,
+          state.direction,
+          collator,
+        );
+        if (comparison !== 0) return comparison;
+
+        if (state.tieBreaker) {
+          const id = state.tieBreaker;
+          const tieComparison = compareValues(
+            left.sortValues[id],
+            right.sortValues[id],
+            inferSortType(left.sortValues[id], right.sortValues[id]),
+            'ascending',
+            collator,
+          );
+          if (tieComparison !== 0) return tieComparison;
+        }
+
+        return left.index - right.index;
+      });
+    }
+  }
 
-  async function loadNextPage(): Promise<void> {
-    if (request || disposed || completed) {
+  async function renderNextBatch(
+    loadingState: Extract<
+      TableLoadingState,
+      'pending' | 'refreshing' | 'appending'
+    > = 'appending',
+  ): Promise<void> {
+    if (request || disposed || cursor >= results.length) return;
+
+    const target = results.slice(cursor, cursor + batchSize);
+    if (target.length === 0) {
+      removeSkeleton();
+      updatePagination();
+      updateTableState(results.length === 0 ? 'empty' : 'ready');
       return;
     }
 
-    const nextUrl = new URL(activeLink.href, window.location.href);
-    if (nextUrl.origin !== window.location.origin) {
-      setState(activePagination, activeStatus, 'error');
-      showFallback();
+    const missing = target.filter((entry) => !rowsByKey.has(entry.key));
+    const activeGeneration = generation;
+
+    if (missing.length > 0) {
+      const activeRequest = new AbortController();
+      request = activeRequest;
+      setPaginationState(pagination, status, 'loading');
+      updateTableState(loadingState);
+      addSkeleton(target.length);
+
+      try {
+        await loadSources(missing, activeRequest.signal);
+      } catch (error) {
+        if (error instanceof DOMException && error.name === 'AbortError') return;
+        removeSkeleton();
+        setPaginationState(pagination, status, 'error');
+        updateTableState('error');
+        showFallback(pagination, fallbackLink);
+        observer.disconnect();
+        return;
+      } finally {
+        if (request === activeRequest) {
+          request = null;
+        }
+      }
+    }
+
+    if (disposed || activeGeneration !== generation) return;
+    const rows = target.map((entry) => rowsByKey.get(entry.key));
+    if (rows.some((row) => !row)) {
+      removeSkeleton();
+      setPaginationState(pagination, status, 'error');
+      updateTableState('error');
+      showFallback(pagination, fallbackLink);
       observer.disconnect();
       return;
     }
 
-    const requestKey = nextUrl.href;
-    if (loadedUrls.has(requestKey)) {
-      return;
+    removeSkeleton();
+    appendRows(rows as HTMLElement[]);
+    cursor += target.length;
+    updatePagination();
+    updateTableState('ready');
+  }
+
+  async function loadSources(
+    missingEntries: readonly IndexedEntry[],
+    signal: AbortSignal,
+  ): Promise<void> {
+    const sourceIds = new Set(
+      missingEntries.map((entry) => entry.source).filter(isString),
+    );
+    if (sourceIds.size === 0 || !manifest.sources) {
+      throw new Error('Missing progressive table row source');
     }
 
-    request = new AbortController();
-    setState(activePagination, activeStatus, 'loading');
-    root.setAttribute('aria-busy', 'true');
+    await Promise.all(
+      [...sourceIds].map(async (sourceId) => {
+        if (loadedSources.has(sourceId)) return;
+        const href = manifest.sources?.[sourceId];
+        if (!href) throw new Error(`Missing table source: ${sourceId}`);
+
+        const url = new URL(href, window.location.href);
+        if (url.origin !== window.location.origin) {
+          throw new Error('Table sources must use the current origin');
+        }
+        const response = await fetch(url, {
+          credentials: 'same-origin',
+          headers: { Accept: 'text/html' },
+          signal,
+        });
+        if (!response.ok) {
+          throw new Error(`Unable to load table source: ${response.status}`);
+        }
+
+        const documentNode = new DOMParser().parseFromString(
+          await response.text(),
+          'text/html',
+        );
+        const tableKey = root.dataset.tableKey;
+        const sourceTable = tableKey
+          ? Array.from(
+              documentNode.querySelectorAll<HTMLElement>('[data-table-key]'),
+            ).find((table) => table.dataset.tableKey === tableKey)
+          : null;
+        const sourceRowsRoot = sourceTable?.querySelector<HTMLElement>(
+          '[data-table-rows]',
+        );
+        const sourceRows = sourceRowsRoot ? getRows(sourceRowsRoot) : [];
+        if (sourceRows.length === 0) {
+          throw new Error(`Missing progressive table: ${tableKey ?? 'unknown'}`);
+        }
+
+        registerRows(sourceRows.map((row) => document.importNode(row, true)));
+        loadedSources.add(sourceId);
+      }),
+    );
+  }
 
-    let continueLoading = false;
+  function prepareWindow(
+    offset: number,
+    state: Extract<TableLoadingState, 'pending' | 'refreshing'>,
+  ): void {
+    generation += 1;
+    request?.abort();
+    request = null;
+    updateTableState(state);
+    addSkeleton(batchSize);
+    detachRenderedRows();
+    applyQuery();
+    cursor = Math.min(offset, results.length);
+    updateEmptyState();
+    if (results.length === 0) {
+      removeSkeleton();
+      updatePagination();
+      updateTableState('empty');
+      return;
+    }
+    void renderNextBatch(state);
+  }
 
-    try {
-      addSkeleton();
-      const response = await fetch(nextUrl, {
-        credentials: 'same-origin',
-        headers: { Accept: 'text/html' },
-        signal: request.signal,
-      });
+  function refresh(): void {
+    if (!prepared) {
+      prepared = true;
+      prepareWindow(initialOffset, 'pending');
+      return;
+    }
+    prepareWindow(0, 'refreshing');
+  }
 
-      if (!response.ok) {
-        throw new Error(`Unable to load table page: ${response.status}`);
+  const context: ProgressiveContext = {
+    destroy() {
+      disposed = true;
+      request?.abort();
+      observer.disconnect();
+      removeSkeleton();
+      pagination.hidden = !fallbackLink;
+      pagination.removeAttribute('data-table-progressive-enhanced');
+      pagination.removeAttribute('data-table-progressive-state');
+      if (!pagination.hidden) pagination.setAttribute('data-surface', '');
+      status.hidden = true;
+      status.textContent = '';
+      root.removeAttribute('aria-busy');
+      root.removeAttribute('data-table-loading-state');
+      root.removeAttribute(initializedAttribute);
+      contexts.delete(root);
+    },
+    progressive: true,
+    refresh,
+    setFilters(state) {
+      if (areFilterStatesEqual(filterState, state)) return;
+      filterState = state;
+      if (prepared) prepareWindow(0, 'refreshing');
+    },
+    setSort(state) {
+      if (areSortStatesEqual(sortState, state)) return;
+      sortState = state;
+      if (prepared) prepareWindow(0, 'refreshing');
+    },
+    updateEntry(key, update) {
+      const entry = entriesByKey.get(key);
+      if (!entry) return;
+      if (update.sortValues) {
+        entry.sortValues = { ...entry.sortValues, ...update.sortValues };
       }
-
-      const nextDocument = new DOMParser().parseFromString(
-        await response.text(),
-        'text/html',
-      );
-      const nextTable = Array.from(
-        nextDocument.querySelectorAll<HTMLElement>('[data-table-key]'),
-      ).find((table) => table.dataset.tableKey === tableKey);
-      const nextRowsRoot =
-        nextTable?.querySelector<HTMLElement>('[data-table-rows]');
-
-      if (!nextTable || !nextRowsRoot) {
-        throw new Error(`Missing paginated table: ${tableKey}`);
+      if (update.exclusion) {
+        if (update.exclusion.excluded) {
+          entry.exclusions.add(update.exclusion.key);
+        } else {
+          entry.exclusions.delete(update.exclusion.key);
+        }
       }
+    },
+  };
 
-      const nextRows = Array.from(
-        nextRowsRoot.querySelectorAll<HTMLElement>(':scope > [data-table-row]'),
-      );
-      if (nextRows.length === 0) {
-        throw new Error(`Missing paginated table rows: ${tableKey}`);
-      }
+  contexts.set(root, context);
+  if (root.dataset.tablePreparation !== 'controlled') refresh();
 
-      const nextPagination = nextTable.querySelector<HTMLElement>(
-        '[data-table-pagination]',
-      );
-      const nextLink = nextPagination?.querySelector<HTMLAnchorElement>(
-        '[data-table-pagination-link]',
-      );
+  return context.destroy;
+}
 
-      const importedRows = nextRows.map((row) =>
-        document.importNode(row, true),
-      );
-      if (loadAllRequested) {
-        batchedRows.push(...importedRows);
-      } else {
-        removeSkeleton();
-        appendRows(importedRows);
-      }
-      loadedUrls.add(requestKey);
+export function setTableProgressiveFilters(
+  root: HTMLElement,
+  state: TableProgressiveFilterState,
+): boolean {
+  const context = getProgressiveContext(root);
+  if (!context) return false;
+  context.setFilters(state);
+  return true;
+}
 
-      if (!nextPagination || !nextLink) {
-        complete();
-        return;
-      }
+export function setTableProgressiveSort(
+  root: HTMLElement,
+  state: TableProgressiveSortState,
+): boolean {
+  const context = getProgressiveContext(root);
+  if (!context) return false;
+  context.setSort(state);
+  return true;
+}
 
-      const nextHref = nextLink.getAttribute('href');
-      if (!nextHref) {
-        complete();
-        return;
-      }
+export function updateTableProgressiveEntry(
+  root: HTMLElement,
+  key: string,
+  update: TableProgressiveEntryUpdate,
+): boolean {
+  const context = getProgressiveContext(root);
+  if (!context) return false;
+  context.updateEntry(key, update);
+  return true;
+}
 
-      activeLink.href = nextHref;
-      copyDatasetValue(activePagination, nextPagination, 'tablePage');
-      copyDatasetValue(activePagination, nextPagination, 'tableTotalPages');
-      continueLoading = loadAllRequested;
-      if (!continueLoading) setState(activePagination, activeStatus, 'idle');
-    } catch (error) {
-      if (error instanceof DOMException && error.name === 'AbortError') {
-        return;
-      }
-      flushBatchedRows();
-      loadAllRequested = false;
-      root.removeAttribute('data-table-progressive-loading-all');
-      setState(activePagination, activeStatus, 'error');
-      showFallback();
-      observer.disconnect();
-    } finally {
-      request = null;
-      if (!loadAllRequested) root.removeAttribute('aria-busy');
-      if (continueLoading && !disposed) void loadNextPage();
-    }
+export function refreshTableProgressive(root: HTMLElement): boolean {
+  const context = getProgressiveContext(root);
+  if (!context) return false;
+  context.refresh();
+  return true;
+}
+
+export function hasTableProgressive(root: HTMLElement): boolean {
+  return getProgressiveContext(root)?.progressive === true;
+}
+
+export function resolveTablePreparation(root: HTMLElement): void {
+  const context = getProgressiveContext(root);
+  if (context) {
+    context.refresh();
+    return;
   }
 
-  const handleLoadAll = (): void => {
-    if (completed) return;
-    loadAllRequested = true;
-    root.setAttribute('data-table-progressive-loading-all', 'true');
-    void loadNextPage();
-  };
+  const rowsRoot = root.querySelector<HTMLElement>('[data-table-rows]');
+  if (rowsRoot) revealServerRows(root, rowsRoot);
+}
 
-  const handleClick = (event: MouseEvent): void => {
-    if (
-      event.defaultPrevented ||
-      event.button !== 0 ||
-      event.metaKey ||
-      event.ctrlKey ||
-      event.shiftKey ||
-      event.altKey
-    ) {
-      return;
-    }
+function getProgressiveContext(
+  root: HTMLElement,
+): ProgressiveContext | undefined {
+  const existing = contexts.get(root);
+  if (existing) return existing;
+  if (
+    !root.querySelector(':scope > [data-table-progressive-manifest]')
+  ) {
+    return undefined;
+  }
+  initTableProgressive(root);
+  return contexts.get(root);
+}
 
-    if (activePagination.dataset.tableProgressiveState === 'error') {
-      return;
-    }
+function readManifest(root: HTMLElement): TableProgressiveModel | null {
+  const node = root.querySelector<HTMLScriptElement>(
+    ':scope > [data-table-progressive-manifest]',
+  );
+  if (!node?.textContent) return null;
+
+  try {
+    const value: unknown = JSON.parse(node.textContent);
+    if (!isRecord(value) || !Array.isArray(value.entries)) return null;
+    const entries = value.entries.filter(isProgressiveEntry);
+    if (entries.length !== value.entries.length) return null;
+    return {
+      entries,
+      sources: isStringRecord(value.sources) ? value.sources : undefined,
+      batchSize: isFiniteNumber(value.batchSize) ? value.batchSize : undefined,
+      initialOffset: isFiniteNumber(value.initialOffset)
+        ? value.initialOffset
+        : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
 
-    event.preventDefault();
-    observer.observe(sentinel);
-    void loadNextPage();
-  };
+function getRows(root: ParentNode): HTMLElement[] {
+  return Array.from(
+    root.querySelectorAll<HTMLElement>(':scope > [data-table-row]'),
+  );
+}
 
-  activeLink.addEventListener('click', handleClick);
-  root.addEventListener('table:load-all', handleLoadAll);
-  observer.observe(sentinel);
+function getSkeletonRows(root: ParentNode): HTMLElement[] {
+  return Array.from(
+    root.querySelectorAll<HTMLElement>(
+      ':scope > [data-table-skeleton-row]',
+    ),
+  );
+}
 
-  return () => {
-    disposed = true;
-    request?.abort();
-    observer.disconnect();
-    activeLink.removeEventListener('click', handleClick);
-    root.removeEventListener('table:load-all', handleLoadAll);
-    flushBatchedRows();
-    activePagination.hidden = false;
-    activePagination.setAttribute('data-surface', '');
-    activePagination.removeAttribute('data-table-progressive-enhanced');
-    activePagination.removeAttribute('data-table-progressive-state');
-    activeStatus.hidden = true;
-    activeStatus.textContent = '';
-    root.removeAttribute('data-table-progressive-loading-all');
-    root.removeAttribute('aria-busy');
-    root.removeAttribute(initializedAttribute);
-  };
+function revealServerRows(root: HTMLElement, rowsRoot: HTMLElement): void {
+  getSkeletonRows(rowsRoot).forEach((row) => row.remove());
+  root.dataset.tableLoadingState = getRows(rowsRoot).some(
+    (row) => !row.hidden,
+  )
+    ? 'ready'
+    : 'empty';
+  root.removeAttribute('aria-busy');
 }
 
-function setState(
+function insertBeforeEmpty(
+  rowsRoot: HTMLElement,
+  empty: HTMLElement | null,
+  rows: readonly HTMLElement[],
+): void {
+  const fragment = document.createDocumentFragment();
+  rows.forEach((row) => fragment.append(row));
+  rowsRoot.insertBefore(fragment, empty);
+}
+
+function setPaginationState(
   pagination: HTMLElement,
   status: HTMLElement,
-  state: ProgressiveState,
+  state: PaginationState,
 ): void {
   pagination.dataset.tableProgressiveState = state;
   status.hidden = state !== 'loading' && state !== 'error';
-
-  if (state === 'loading') {
-    status.textContent = pagination.dataset.tableLoadingLabel ?? '';
-  } else if (state === 'error') {
-    status.textContent = pagination.dataset.tableErrorLabel ?? '';
-  } else {
-    status.textContent = '';
-  }
+  status.textContent =
+    state === 'loading'
+      ? (pagination.dataset.tableLoadingLabel ?? '')
+      : state === 'error'
+        ? (pagination.dataset.tableErrorLabel ?? '')
+        : '';
 }
 
-function copyDatasetValue(
-  target: HTMLElement,
-  source: HTMLElement,
-  key: 'tablePage' | 'tableTotalPages',
+function showFallback(
+  pagination: HTMLElement,
+  link: HTMLAnchorElement | null,
 ): void {
-  const value = source.dataset[key];
+  if (!link) return;
+  pagination.hidden = false;
+  pagination.removeAttribute('data-table-progressive-enhanced');
+  pagination.setAttribute('data-surface', '');
+}
 
-  if (value === undefined) {
-    delete target.dataset[key];
-  } else {
-    target.dataset[key] = value;
+function compareValues(
+  left: SortValue | undefined,
+  right: SortValue | undefined,
+  type: SortType,
+  direction: SortDirection,
+  collator: Intl.Collator,
+): number {
+  const leftMissing = left === null || left === undefined;
+  const rightMissing = right === null || right === undefined;
+  if (leftMissing || rightMissing) {
+    if (leftMissing && rightMissing) return 0;
+    return leftMissing ? 1 : -1;
   }
+
+  const comparison =
+    type === 'number'
+      ? Number(left) - Number(right)
+      : collator.compare(String(left), String(right));
+  return direction === 'ascending' ? comparison : -comparison;
+}
+
+function areFilterStatesEqual(
+  left: TableProgressiveFilterState,
+  right: TableProgressiveFilterState,
+): boolean {
+  if (left.search !== right.search) return false;
+  const leftEntries = Object.entries(left.selections);
+  const rightEntries = Object.entries(right.selections);
+  return (
+    leftEntries.length === rightEntries.length &&
+    leftEntries.every(([key, value]) => right.selections[key] === value)
+  );
+}
+
+function areSortStatesEqual(
+  left: TableProgressiveSortState,
+  right: TableProgressiveSortState,
+): boolean {
+  if (left === right) return true;
+  return Boolean(
+    left &&
+    right &&
+    left.id === right.id &&
+    left.type === right.type &&
+    left.direction === right.direction &&
+    left.tieBreaker === right.tieBreaker,
+  );
+}
+
+function inferSortType(
+  left: SortValue | undefined,
+  right: SortValue | undefined,
+): SortType {
+  return typeof left === 'number' || typeof right === 'number'
+    ? 'number'
+    : 'text';
+}
+
+function isProgressiveEntry(value: unknown): value is TableProgressiveEntry {
+  return isRecord(value) && typeof value.key === 'string';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isString(value: string | undefined): value is string {
+  return typeof value === 'string';
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    isRecord(value) &&
+    Object.values(value).every((entry) => typeof entry === 'string')
+  );
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
 }