Genarrative/apps/ai-game-creator-shell/src/features/template-library/templateLibraryGrid.ts

/**
 * 模板库卡片网格的布局计算（纯函数）。
 *
 * 页面用 `react-window` 的 `FixedSizeGrid` 做虚拟滚动：只渲染可视区域的行，
 * 因此这里负责把「容器宽度 + 条目数」换算成列数、列宽、行高与行数，
 * 保证卡片尺寸、封面比例与行高完全确定（虚拟列表要求固定行高）。
 */

import type { GameTemplateEntry } from './templateLibraryModel';

/** 卡片最小宽度（与 CSS 里旧的 `minmax(250px,1fr)` 口径一致）。 */
export const TEMPLATE_CARD_MIN_WIDTH = 250;
/** 卡片之间的水平/垂直间隙。 */
export const TEMPLATE_CARD_GAP = 14;
/** 封面宽高比：16:9。 */
export const TEMPLATE_CARD_COVER_RATIO = 9 / 16;
/** 卡片封面以下的文字与按钮区固定高度。 */
export const TEMPLATE_CARD_TEXT_HEIGHT = 150;
/** 额外预渲染的行数，减小快速滚动时的白屏。 */
export const TEMPLATE_GRID_OVERSCAN_ROWS = 2;

export type TemplateGridLayout = {
  columnCount: number;
  /** FixedSizeGrid 的列宽（含卡片右侧间隙）。 */
  columnWidth: number;
  /** FixedSizeGrid 的行高（含卡片下方间隙）。 */
  rowHeight: number;
  rowCount: number;
};

export function computeTemplateGridColumns(containerWidth: number): number {
  if (!Number.isFinite(containerWidth) || containerWidth <= 0) {
    return 1;
  }
  const columns = Math.floor(
    (containerWidth + TEMPLATE_CARD_GAP) /
      (TEMPLATE_CARD_MIN_WIDTH + TEMPLATE_CARD_GAP),
  );
  return Math.max(1, columns);
}

export function computeTemplateRowHeight(columnWidth: number): number {
  const cardWidth = Math.max(
    TEMPLATE_CARD_MIN_WIDTH,
    Math.round(columnWidth) - TEMPLATE_CARD_GAP,
  );
  return (
    Math.ceil(cardWidth * TEMPLATE_CARD_COVER_RATIO) +
    TEMPLATE_CARD_TEXT_HEIGHT +
    TEMPLATE_CARD_GAP
  );
}

export function computeTemplateGridLayout({
  containerWidth,
  itemCount,
}: {
  containerWidth: number;
  itemCount: number;
}): TemplateGridLayout {
  const columnCount = computeTemplateGridColumns(containerWidth);
  const columnWidth = Math.max(1, Math.floor(containerWidth / columnCount));
  return {
    columnCount,
    columnWidth,
    rowHeight: computeTemplateRowHeight(columnWidth),
    rowCount: Math.max(0, Math.ceil(Math.max(0, itemCount) / columnCount)),
  };
}

/** 按行切分，行尾补 `null` 占位，保证虚拟列表的列索引与条目一一对应。 */
export function buildTemplateRows(
  templates: readonly GameTemplateEntry[],
  columnCount: number,
): Array<Array<GameTemplateEntry | null>> {
  if (columnCount <= 0) {
    return [];
  }
  const rows: Array<Array<GameTemplateEntry | null>> = [];
  for (let index = 0; index < templates.length; index += columnCount) {
    const row: Array<GameTemplateEntry | null> = [];
    for (let column = 0; column < columnCount; column += 1) {
      row.push(templates[index + column] ?? null);
    }
    rows.push(row);
  }
  return rows;
}

/** 虚拟列表的稳定 key：行内槽位固定，避免筛选后复用错卡片。 */
export function templateGridItemKey(
  rowIndex: number,
  columnIndex: number,
): string {
  return `template-cell-${rowIndex}-${columnIndex}`;
}