/**
 * Merge GET /api/datatables/{key}/columns metadata with client-only column props
 * (valueMap, filterOptions, sortable, etc.). API order and defaultVisible win for base fields.
 *
 * @param {Array<Record<string, unknown>>} apiColumns
 * @param {Record<string, Record<string, unknown>>} [extrasByKey]
 * @returns {Array<Record<string, unknown>>}
 */
export function mergeDataTableColumns(apiColumns, extrasByKey = {}) {
  if (!Array.isArray(apiColumns)) {
    return [];
  }
  return apiColumns.map((c) => {
    const key = c.key;
    const extra =
      key != null && Object.prototype.hasOwnProperty.call(extrasByKey, key)
        ? extrasByKey[key]
        : {};
    return {
      ...c,
      ...extra,
      key,
      header: extra.header ?? c.header,
    };
  });
}
