// === URLSearchParams の基本操作 ===
 
// 1. 生成方法
const params1 = new URLSearchParams('q=laptop&page=2');
const params2 = new URLSearchParams({ q: 'laptop', page: '2' });
const params3 = new URLSearchParams([['q', 'laptop'], ['page', '2']]);
const params4 = new URLSearchParams(window.location.search);
 
// 2. 値の取得
params1.get('q');        // 'laptop'
params1.get('page');     // '2'（常に string）
params1.get('missing');  // null
 
// 3. 値の設定
params1.set('sort', 'price');     // 追加（既存キーがあれば上書き）
params1.append('tag', 'sale');    // 追加（同じキーが複数存在可能）
params1.append('tag', 'new');
 
// 4. 値の削除
params1.delete('page');           // キーと値を削除
 
// 5. 存在確認
params1.has('q');                 // true
params1.has('page');              // false（削除済み）
 
// 6. イテレーション
for (const [key, value] of params1) {
  console.log(`${key}: ${value}`);
}
// q: laptop
// sort: price
// tag: sale
// tag: new
 
// 7. 配列値の取得
params1.getAll('tag');            // ['sale', 'new']
 
// 8. 文字列化
params1.toString();               // 'q=laptop&sort=price&tag=sale&tag=new'
 
// 9. ソート（キー順）
params1.sort();
params1.toString();               // 'q=laptop&sort=price&tag=new&tag=sale'
 
// 10. サイズ取得
params1.size;                     // 4（エントリ数）

// === URLSearchParams の実用的なヘルパー関数 ===
 
/**
 * 現在のURLのクエリパラメータを更新するヘルパー
 */
function updateSearchParams(
  updates: Record<string, string | string[] | null | undefined>
): string {
  const params = new URLSearchParams(window.location.search);
 
  for (const [key, value] of Object.entries(updates)) {
    if (value === null || value === undefined) {
      params.delete(key);
    } else if (Array.isArray(value)) {
      params.delete(key);
      value.forEach(v => params.append(key, v));
    } else {
      params.set(key, value);
    }
  }
 
  // デフォルト値のキーを除去してURLをクリーンに保つ
  return params.toString();
}
 
// 使用例
const newSearch = updateSearchParams({
  q: 'laptop',
  page: null,          // 削除
  tags: ['sale', 'new'] // 配列
});
// → 'q=laptop&tags=sale&tags=new'
 
/**
 * URLSearchParamsからオブジェクトに変換
 */
function searchParamsToObject(
  params: URLSearchParams
): Record<string, string | string[]> {
  const result: Record<string, string | string[]> = {};
 
  for (const key of new Set(params.keys())) {
    const values = params.getAll(key);
    result[key] = values.length === 1 ? values[0] : values;
  }
 
  return result;
}
 
// 使用例
const params = new URLSearchParams('q=laptop&tag=sale&tag=new&page=2');
const obj = searchParamsToObject(params);
// { q: 'laptop', tag: ['sale', 'new'], page: '2' }
 
/**
 * オブジェクトの差分をURLSearchParamsに適用
 */
function mergeSearchParams(
  base: URLSearchParams,
  updates: Record<string, string | null>
): URLSearchParams {
  const merged = new URLSearchParams(base.toString());
 
  for (const [key, value] of Object.entries(updates)) {
    if (value === null) {
      merged.delete(key);
    } else {
      merged.set(key, value);
    }
  }
 
  return merged;
}

// === エンコーディングの注意点 ===
 
// URLSearchParams は自動的にエンコード/デコードを行う
const params = new URLSearchParams();
params.set('q', '日本語 検索');
params.toString();  // 'q=%E6%97%A5%E6%9C%AC%E8%AA%9E+%E6%A4%9C%E7%B4%A2'
 
params.get('q');    // '日本語 検索'（自動デコード）
 
// 注意: + はスペースとして扱われる
const params2 = new URLSearchParams('q=hello+world');
params2.get('q');   // 'hello world'
 
// 注意: encodeURIComponent との違い
encodeURIComponent('hello world');  // 'hello%20world'（%20）
new URLSearchParams({ q: 'hello world' }).toString();  // 'q=hello+world'（+）
 
// 特殊文字のエンコーディング
const specialParams = new URLSearchParams();
specialParams.set('filter', 'price>100&stock>0');
specialParams.toString();  // 'filter=price%3E100%26stock%3E0'
// & や > が正しくエンコードされる

// === React Router v6 の useSearchParams ===
import { useSearchParams } from 'react-router-dom';
 
function ProductListPage() {
  // URLSearchParams のReactラッパー
  const [searchParams, setSearchParams] = useSearchParams();
 
  // 値の取得（常に string | null）
  const query = searchParams.get('q') ?? '';
  const page = Number(searchParams.get('page') ?? '1');
  const sort = searchParams.get('sort') ?? 'newest';
  const categories = searchParams.getAll('category');
 
  // 方法1: 関数型アップデート（推奨）
  function handleSortChange(newSort: string) {
    setSearchParams(prev => {
      const next = new URLSearchParams(prev);
      next.set('sort', newSort);
      next.delete('page'); // ソート変更時にページリセット
      return next;
    });
  }
 
  // 方法2: オブジェクト指定（全パラメータを置換）
  function handleReset() {
    setSearchParams({}); // 全パラメータをクリア
  }
 
  // 方法3: URLSearchParams を直接渡す
  function handleSearch(q: string) {
    const params = new URLSearchParams(searchParams);
    if (q) {
      params.set('q', q);
    } else {
      params.delete('q');
    }
    params.delete('page'); // 検索変更時にページリセット
    setSearchParams(params);
  }
 
  // 方法4: replace オプション（ブラウザ履歴に残さない）
  function handlePageChange(newPage: number) {
    setSearchParams(prev => {
      const next = new URLSearchParams(prev);
      next.set('page', String(newPage));
      return next;
    }, { replace: true }); // 履歴スタックに追加しない
  }
 
  return (
    <div>
      <SearchInput value={query} onSearch={handleSearch} />
      <SortSelect value={sort} onChange={handleSortChange} />
      <CategoryFilter selected={categories} onChange={handleCategoryChange} />
      <ProductGrid query={query} page={page} sort={sort} />
      <Pagination
        currentPage={page}
        onPageChange={handlePageChange}
      />
      <button onClick={handleReset}>Clear Filters</button>
    </div>
  );
}

// === React Router: useSearchParams のデフォルト値パターン ===
 
// パターン1: インラインデフォルト値
function useProductFilters() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  return {
    query: searchParams.get('q') ?? '',
    page: Number(searchParams.get('page')) || 1,
    sort: searchParams.get('sort') ?? 'newest',
    category: searchParams.get('category') ?? 'all',
    perPage: Number(searchParams.get('per_page')) || 20,
  };
}
 
// パターン2: デフォルト値をuseSearchParamsに渡す
function ProductPage() {
  const [searchParams, setSearchParams] = useSearchParams({
    sort: 'newest',
    page: '1',
    per_page: '20',
  });
 
  // デフォルト値が設定された状態でスタート
  const sort = searchParams.get('sort')!; // non-null
  const page = Number(searchParams.get('page')!);
}
 
// パターン3: カスタムフックでラップ
interface ProductFilterState {
  query: string;
  page: number;
  sort: 'newest' | 'price-asc' | 'price-desc' | 'popular';
  category: string | null;
  tags: string[];
  priceMin: number | null;
  priceMax: number | null;
}
 
const DEFAULT_FILTERS: ProductFilterState = {
  query: '',
  page: 1,
  sort: 'newest',
  category: null,
  tags: [],
  priceMin: null,
  priceMax: null,
};
 
function useProductFiltersAdvanced() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const filters: ProductFilterState = {
    query: searchParams.get('q') ?? DEFAULT_FILTERS.query,
    page: Number(searchParams.get('page')) || DEFAULT_FILTERS.page,
    sort: (searchParams.get('sort') as ProductFilterState['sort'])
      ?? DEFAULT_FILTERS.sort,
    category: searchParams.get('category') ?? DEFAULT_FILTERS.category,
    tags: searchParams.getAll('tag'),
    priceMin: searchParams.has('price_min')
      ? Number(searchParams.get('price_min'))
      : null,
    priceMax: searchParams.has('price_max')
      ? Number(searchParams.get('price_max'))
      : null,
  };
 
  function setFilters(updates: Partial<ProductFilterState>) {
    setSearchParams(prev => {
      const params = new URLSearchParams(prev);
 
      // query
      if ('query' in updates) {
        if (updates.query) {
          params.set('q', updates.query);
        } else {
          params.delete('q');
        }
      }
 
      // page
      if ('page' in updates) {
        if (updates.page && updates.page > 1) {
          params.set('page', String(updates.page));
        } else {
          params.delete('page');
        }
      }
 
      // sort
      if ('sort' in updates) {
        if (updates.sort && updates.sort !== DEFAULT_FILTERS.sort) {
          params.set('sort', updates.sort);
        } else {
          params.delete('sort');
        }
      }
 
      // category
      if ('category' in updates) {
        if (updates.category) {
          params.set('category', updates.category);
        } else {
          params.delete('category');
        }
      }
 
      // tags（配列）
      if ('tags' in updates) {
        params.delete('tag');
        updates.tags?.forEach(tag => params.append('tag', tag));
      }
 
      // price range
      if ('priceMin' in updates) {
        if (updates.priceMin !== null && updates.priceMin !== undefined) {
          params.set('price_min', String(updates.priceMin));
        } else {
          params.delete('price_min');
        }
      }
 
      if ('priceMax' in updates) {
        if (updates.priceMax !== null && updates.priceMax !== undefined) {
          params.set('price_max', String(updates.priceMax));
        } else {
          params.delete('price_max');
        }
      }
 
      // フィルタ変更時にページをリセット
      if (!('page' in updates)) {
        params.delete('page');
      }
 
      return params;
    });
  }
 
  function resetFilters() {
    setSearchParams({});
  }
 
  const isFiltered = searchParams.toString() !== '';
 
  return { filters, setFilters, resetFilters, isFiltered };
}

// === Next.js App Router の useSearchParams ===
'use client';
import { useSearchParams, useRouter, usePathname } from 'next/navigation';
import { useCallback, useTransition } from 'react';
 
function ProductFilters() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const pathname = usePathname();
  const [isPending, startTransition] = useTransition();
 
  // 値の取得
  const category = searchParams.get('category') ?? 'all';
  const sort = searchParams.get('sort') ?? 'newest';
  const page = Number(searchParams.get('page') ?? '1');
  const query = searchParams.get('q') ?? '';
 
  // URL更新ヘルパー（useCallback でメモ化）
  const updateParams = useCallback(
    (updates: Record<string, string | null>) => {
      const params = new URLSearchParams(searchParams.toString());
 
      for (const [key, value] of Object.entries(updates)) {
        if (value === null) {
          params.delete(key);
        } else {
          params.set(key, value);
        }
      }
 
      // フィルタ変更時はページをリセット
      if (!('page' in updates)) {
        params.delete('page');
      }
 
      // useTransition でUIのブロッキングを防ぐ
      startTransition(() => {
        router.push(`${pathname}?${params.toString()}`, {
          scroll: false, // スクロール位置を維持
        });
      });
    },
    [searchParams, router, pathname, startTransition]
  );
 
  return (
    <div className={isPending ? 'opacity-50' : ''}>
      {/* 検索入力 */}
      <SearchInput
        defaultValue={query}
        onSearch={(q) => updateParams({ q: q || null })}
      />
 
      {/* カテゴリ選択 */}
      <select
        value={category}
        onChange={(e) => updateParams({
          category: e.target.value === 'all' ? null : e.target.value,
        })}
      >
        <option value="all">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="books">Books</option>
        <option value="clothing">Clothing</option>
      </select>
 
      {/* ソート選択 */}
      <select
        value={sort}
        onChange={(e) => updateParams({ sort: e.target.value })}
      >
        <option value="newest">Newest</option>
        <option value="price-asc">Price: Low to High</option>
        <option value="price-desc">Price: High to Low</option>
        <option value="popular">Most Popular</option>
      </select>
 
      {/* ページネーション */}
      <Pagination
        currentPage={page}
        onPageChange={(p) => updateParams({ page: String(p) })}
      />
 
      {/* ペンディングインジケータ */}
      {isPending && <LoadingSpinner />}
    </div>
  );
}

// === Next.js: createQueryString ユーティリティ ===
'use client';
import { useSearchParams, useRouter, usePathname } from 'next/navigation';
 
/**
 * Next.js App Router 向け URL パラメータ管理フック
 */
function useURLParams() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const pathname = usePathname();
 
  /**
   * 新しいクエリ文字列を生成する（イミュータブル）
   */
  const createQueryString = useCallback(
    (params: Record<string, string | string[] | null>) => {
      const newParams = new URLSearchParams(searchParams.toString());
 
      for (const [key, value] of Object.entries(params)) {
        if (value === null) {
          newParams.delete(key);
        } else if (Array.isArray(value)) {
          newParams.delete(key);
          value.forEach(v => newParams.append(key, v));
        } else {
          newParams.set(key, value);
        }
      }
 
      return newParams.toString();
    },
    [searchParams]
  );
 
  /**
   * URLを更新（push）
   */
  const pushParams = useCallback(
    (params: Record<string, string | string[] | null>, options?: {
      scroll?: boolean;
      resetPage?: boolean;
    }) => {
      const updates = { ...params };
      if (options?.resetPage && !('page' in updates)) {
        updates.page = null;
      }
 
      const queryString = createQueryString(updates);
      const url = queryString ? `${pathname}?${queryString}` : pathname;
      router.push(url, { scroll: options?.scroll ?? false });
    },
    [createQueryString, pathname, router]
  );
 
  /**
   * URLを更新（replace - 履歴に残さない）
   */
  const replaceParams = useCallback(
    (params: Record<string, string | string[] | null>) => {
      const queryString = createQueryString(params);
      const url = queryString ? `${pathname}?${queryString}` : pathname;
      router.replace(url, { scroll: false });
    },
    [createQueryString, pathname, router]
  );
 
  /**
   * 全パラメータをクリア
   */
  const clearParams = useCallback(() => {
    router.push(pathname, { scroll: false });
  }, [pathname, router]);
 
  return {
    searchParams,
    createQueryString,
    pushParams,
    replaceParams,
    clearParams,
  };
}
 
// 使用例
function FilterComponent() {
  const { searchParams, pushParams, clearParams } = useURLParams();
 
  return (
    <div>
      <button onClick={() => pushParams(
        { category: 'electronics', sort: 'price-asc' },
        { resetPage: true }
      )}>
        Electronics (Cheapest)
      </button>
      <button onClick={() => clearParams()}>
        Clear All Filters
      </button>
    </div>
  );
}

// === Suspense boundary が必要な理由と対処法 ===
 
// NG: Suspense なしで useSearchParams を使うとビルドエラー
function Page() {
  return <ProductFilters />; // エラー: useSearchParams requires Suspense
}
 
// OK: Suspense で囲む
import { Suspense } from 'react';
 
function Page() {
  return (
    <Suspense fallback={<FiltersSkeleton />}>
      <ProductFilters />
    </Suspense>
  );
}
 
// OK: コンポーネントを分離するパターン
// app/products/page.tsx（Server Component）
export default function ProductsPage() {
  return (
    <div>
      <h1>Products</h1>
      <Suspense fallback={<div>Loading filters...</div>}>
        <ProductFilters />  {/* Client Component with useSearchParams */}
      </Suspense>
      <Suspense fallback={<ProductGridSkeleton />}>
        <ProductGrid />     {/* Server Component or Client Component */}
      </Suspense>
    </div>
  );
}
 
// ProductFilters.tsx（Client Component）
'use client';
import { useSearchParams } from 'next/navigation';
 
function ProductFilters() {
  const searchParams = useSearchParams();
  // ... フィルタのUI
}

# インストール
npm install nuqs
 
# Next.js App Router の場合: layout.tsx にプロバイダーを設定

// app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ja">
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  );
}
 
// Next.js Pages Router の場合
// pages/_app.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/pages';
 
export default function App({ Component, pageProps }) {
  return (
    <NuqsAdapter>
      <Component {...pageProps} />
    </NuqsAdapter>
  );
}
 
// React Router の場合
import { NuqsAdapter } from 'nuqs/adapters/react-router/v7';
 
// Remix の場合
import { NuqsAdapter } from 'nuqs/adapters/remix';

// === nuqs の基本: useQueryState ===
'use client';
import {
  useQueryState,
  parseAsInteger,
  parseAsBoolean,
  parseAsStringEnum,
  parseAsFloat,
  parseAsIsoDateTime,
  parseAsJson,
  parseAsArrayOf,
  parseAsString,
} from 'nuqs';
 
function ProductPage() {
  // 文字列パラメータ（デフォルトのパーサー）
  const [query, setQuery] = useQueryState('q', { defaultValue: '' });
  // URL: ?q=laptop → query = 'laptop'
  // URL: (なし)    → query = ''
 
  // 数値パラメータ
  const [page, setPage] = useQueryState(
    'page',
    parseAsInteger.withDefault(1)
  );
  // URL: ?page=3 → page = 3（number型）
  // URL: (なし)  → page = 1
 
  // 列挙型パラメータ
  const [sort, setSort] = useQueryState(
    'sort',
    parseAsStringEnum(['newest', 'price-asc', 'price-desc', 'popular'])
      .withDefault('newest')
  );
  // URL: ?sort=price-asc → sort = 'price-asc'
  // 不正な値は無視される
 
  // boolean パラメータ
  const [inStock, setInStock] = useQueryState(
    'in_stock',
    parseAsBoolean.withDefault(false)
  );
  // URL: ?in_stock=true → inStock = true
 
  // null 可能なパラメータ（withDefault なし）
  const [category, setCategory] = useQueryState('category');
  // URL: ?category=books → category = 'books'
  // URL: (なし)           → category = null
 
  return (
    <div>
      {/* 文字列入力 */}
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value || null)}
        placeholder="Search..."
      />
 
      {/* ソート選択 */}
      <select
        value={sort}
        onChange={(e) => setSort(e.target.value as typeof sort)}
      >
        <option value="newest">Newest</option>
        <option value="price-asc">Price: Low to High</option>
        <option value="price-desc">Price: High to Low</option>
        <option value="popular">Most Popular</option>
      </select>
 
      {/* ページネーション */}
      <button
        disabled={page <= 1}
        onClick={() => setPage(page - 1)}
      >
        Previous
      </button>
      <span>Page {page}</span>
      <button onClick={() => setPage(page + 1)}>
        Next
      </button>
 
      {/* 在庫フィルタ */}
      <label>
        <input
          type="checkbox"
          checked={inStock}
          onChange={(e) => setInStock(e.target.checked || null)}
        />
        In Stock Only
      </label>
 
      {/* カテゴリ（null 可能） */}
      <select
        value={category ?? ''}
        onChange={(e) => setCategory(e.target.value || null)}
      >
        <option value="">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="books">Books</option>
      </select>
    </div>
  );
}

// === nuqs の高度なパーサー ===
 
// 1. 浮動小数点数
const [price, setPrice] = useQueryState(
  'price',
  parseAsFloat.withDefault(0)
);
// URL: ?price=29.99 → price = 29.99
 
// 2. ISO日時
const [date, setDate] = useQueryState(
  'date',
  parseAsIsoDateTime.withDefault(new Date())
);
// URL: ?date=2024-03-15T10:30:00.000Z → Date オブジェクト
 
// 3. 配列（カンマ区切り）
const [tags, setTags] = useQueryState(
  'tags',
  parseAsArrayOf(parseAsString, ',').withDefault([])
);
// URL: ?tags=sale,new,popular → tags = ['sale', 'new', 'popular']
 
// 4. 数値配列
const [ids, setIds] = useQueryState(
  'ids',
  parseAsArrayOf(parseAsInteger, ',').withDefault([])
);
// URL: ?ids=1,2,3 → ids = [1, 2, 3]
 
// 5. JSON パラメータ（複雑なオブジェクト）
interface PriceRange {
  min: number;
  max: number;
}
 
const [priceRange, setPriceRange] = useQueryState<PriceRange>(
  'price_range',
  parseAsJson<PriceRange>().withDefault({ min: 0, max: 10000 })
);
// URL: ?price_range={"min":100,"max":500}
 
// 6. カスタムパーサー
import { createParser } from 'nuqs';
 
// カスタム: カンマ区切りの数値範囲
const parseAsRange = createParser({
  parse: (value: string) => {
    const [min, max] = value.split('-').map(Number);
    if (isNaN(min) || isNaN(max)) return null;
    return { min, max };
  },
  serialize: (value: { min: number; max: number }) =>
    `${value.min}-${value.max}`,
});
 
const [range, setRange] = useQueryState(
  'range',
  parseAsRange.withDefault({ min: 0, max: 100 })
);
// URL: ?range=10-50 → { min: 10, max: 50 }
 
// 7. カスタム: スラッグ化された文字列
const parseAsSlug = createParser({
  parse: (value: string) => value.replace(/-/g, ' '),
  serialize: (value: string) =>
    value.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''),
});
 
const [searchTerm, setSearchTerm] = useQueryState(
  'q',
  parseAsSlug.withDefault('')
);
// URL: ?q=red-shoes → searchTerm = 'red shoes'
// setSearchTerm('Blue Jacket') → URL: ?q=blue-jacket

// === useQueryStates: 複数パラメータを一度に管理 ===
import { useQueryStates, parseAsInteger, parseAsStringEnum } from 'nuqs';
 
// パーサー定義を一箇所にまとめる
const productFiltersParsers = {
  q: parseAsString.withDefault(''),
  page: parseAsInteger.withDefault(1),
  per_page: parseAsInteger.withDefault(20),
  sort: parseAsStringEnum(['newest', 'price-asc', 'price-desc', 'popular'])
    .withDefault('newest'),
  category: parseAsString,
  tags: parseAsArrayOf(parseAsString, ',').withDefault([]),
  in_stock: parseAsBoolean.withDefault(false),
  price_min: parseAsInteger,
  price_max: parseAsInteger,
};
 
function ProductPage() {
  // 全パラメータを一括で管理
  const [filters, setFilters] = useQueryStates(productFiltersParsers);
 
  // filters の型は自動推論される:
  // {
  //   q: string;
  //   page: number;
  //   per_page: number;
  //   sort: 'newest' | 'price-asc' | 'price-desc' | 'popular';
  //   category: string | null;
  //   tags: string[];
  //   in_stock: boolean;
  //   price_min: number | null;
  //   price_max: number | null;
  // }
 
  // 一括更新（バッチ処理 → 1回のURL更新）
  function handleCategoryChange(category: string) {
    setFilters({
      category: category || null,
      page: 1,  // ページリセット
    });
  }
 
  // 全リセット
  function handleReset() {
    setFilters({
      q: '',
      page: 1,
      per_page: 20,
      sort: 'newest',
      category: null,
      tags: [],
      in_stock: false,
      price_min: null,
      price_max: null,
    });
  }
 
  // 条件付き更新
  function handlePriceRangeChange(min: number | null, max: number | null) {
    setFilters({
      price_min: min,
      price_max: max,
      page: 1,  // ページリセット
    });
  }
 
  return (
    <div>
      <p>
        {filters.q && `Search: "${filters.q}"`}
        {filters.category && ` | Category: ${filters.category}`}
        {filters.tags.length > 0 && ` | Tags: ${filters.tags.join(', ')}`}
      </p>
      {/* UI components */}
    </div>
  );
}

// === nuqs + TanStack Query: URL状態をデータフェッチに連動 ===
import { useQueryStates, parseAsInteger, parseAsString, parseAsStringEnum } from 'nuqs';
import { useQuery, keepPreviousData } from '@tanstack/react-query';
 
const searchParsers = {
  q: parseAsString.withDefault(''),
  page: parseAsInteger.withDefault(1),
  sort: parseAsStringEnum(['newest', 'price-asc', 'price-desc'])
    .withDefault('newest'),
  category: parseAsString,
};
 
function useProducts() {
  const [filters] = useQueryStates(searchParsers);
 
  return useQuery({
    // URL パラメータをそのまま queryKey に使用
    queryKey: ['products', filters],
    queryFn: () => api.products.list({
      q: filters.q || undefined,
      page: filters.page,
      sort: filters.sort,
      category: filters.category ?? undefined,
    }),
    // ページ切り替え時にチラつきを防止
    placeholderData: keepPreviousData,
    // URL パラメータが変わるたびに自動再フェッチ
    staleTime: 30_000,
  });
}
 
function ProductListPage() {
  const [filters, setFilters] = useQueryStates(searchParsers);
  const { data, isLoading, isFetching } = useProducts();
 
  return (
    <div>
      {/* フィルタUI */}
      <SearchInput
        value={filters.q}
        onChange={(q) => setFilters({ q: q || null, page: 1 })}
      />
 
      {/* ローディング状態 */}
      {isLoading && <ProductGridSkeleton />}
 
      {/* データ表示 */}
      {data && (
        <>
          <p>{data.meta.total} products found</p>
          {isFetching && <ProgressBar />}
          <ProductGrid products={data.items} />
          <Pagination
            currentPage={filters.page}
            totalPages={data.meta.totalPages}
            onPageChange={(page) => setFilters({ page })}
          />
        </>
      )}
    </div>
  );
}

// === nuqs: Server Component での searchParams キャッシュ ===
import { createSearchParamsCache } from 'nuqs/server';
import { parseAsInteger, parseAsString, parseAsStringEnum } from 'nuqs';
 
// Server 用のパーサーキャッシュを定義
const searchParamsCache = createSearchParamsCache({
  q: parseAsString.withDefault(''),
  page: parseAsInteger.withDefault(1),
  sort: parseAsStringEnum(['newest', 'price-asc', 'price-desc'])
    .withDefault('newest'),
  category: parseAsString,
});
 
// app/products/page.tsx（Server Component）
export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<Record<string, string | string[]>>;
}) {
  // 型安全に searchParams をパース
  const { q, page, sort, category } = await searchParamsCache.parse(
    await searchParams
  );
 
  // Server Component でデータフェッチ
  const products = await getProducts({
    query: q || undefined,
    page,
    sort,
    category: category ?? undefined,
  });
 
  return (
    <div>
      <h1>Products</h1>
      <Suspense fallback={<FiltersSkeleton />}>
        <ProductFilters />  {/* Client Component で nuqs を使用 */}
      </Suspense>
      <ProductGrid products={products.data} />
      <Pagination
        currentPage={page}
        totalPages={products.meta.totalPages}
      />
    </div>
  );
}

// === Next.js App Router: Server Component での searchParams ===
// app/products/page.tsx
 
interface SearchParams {
  q?: string;
  page?: string;
  sort?: string;
  category?: string;
  tags?: string | string[];
  price_min?: string;
  price_max?: string;
}
 
export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<SearchParams>;
}) {
  const params = await searchParams;
 
  // パラメータのパースとバリデーション
  const page = Math.max(1, Number(params.page ?? '1'));
  const sort = validateSort(params.sort ?? 'newest');
  const category = params.category ?? null;
  const tags = Array.isArray(params.tags)
    ? params.tags
    : params.tags
      ? [params.tags]
      : [];
  const priceMin = params.price_min ? Number(params.price_min) : undefined;
  const priceMax = params.price_max ? Number(params.price_max) : undefined;
 
  // サーバーサイドでデータフェッチ
  const products = await getProducts({
    query: params.q,
    page,
    sort,
    category,
    tags,
    priceMin,
    priceMax,
  });
 
  return (
    <div>
      {/* SEO: 動的メタデータ */}
      <h1>
        {category ? `${category} Products` : 'All Products'}
        {params.q && ` - "${params.q}"`}
      </h1>
 
      {/* Client Component: フィルタUI */}
      <Suspense fallback={<FiltersSkeleton />}>
        <ProductFilters />
      </Suspense>
 
      {/* Server Component: 結果表示 */}
      <p>{products.meta.total} products found</p>
      <ProductGrid products={products.data} />
 
      {/* Server Component: ページネーション（リンクベース） */}
      <ServerPagination
        currentPage={page}
        totalPages={products.meta.totalPages}
        searchParams={params}
      />
    </div>
  );
}
 
// バリデーション関数
function validateSort(sort: string): string {
  const validSorts = ['newest', 'oldest', 'price-asc', 'price-desc', 'popular'];
  return validSorts.includes(sort) ? sort : 'newest';
}

// === Server Component: リンクベースのページネーション ===
import Link from 'next/link';
 
interface ServerPaginationProps {
  currentPage: number;
  totalPages: number;
  searchParams: Record<string, string | string[] | undefined>;
}
 
function ServerPagination({
  currentPage,
  totalPages,
  searchParams,
}: ServerPaginationProps) {
  function createPageURL(page: number): string {
    const params = new URLSearchParams();
 
    for (const [key, value] of Object.entries(searchParams)) {
      if (key === 'page') continue; // page は別途設定
      if (value === undefined) continue;
 
      if (Array.isArray(value)) {
        value.forEach(v => params.append(key, v));
      } else {
        params.set(key, value);
      }
    }
 
    if (page > 1) {
      params.set('page', String(page));
    }
 
    const queryString = params.toString();
    return queryString ? `?${queryString}` : '';
  }
 
  // ページ番号のリストを生成
  const pages = generatePageNumbers(currentPage, totalPages);
 
  return (
    <nav aria-label="Pagination">
      {/* 前のページ */}
      {currentPage > 1 ? (
        <Link href={createPageURL(currentPage - 1)}>
          Previous
        </Link>
      ) : (
        <span aria-disabled="true">Previous</span>
      )}
 
      {/* ページ番号 */}
      {pages.map((page, index) => (
        page === '...' ? (
          <span key={`ellipsis-${index}`}>...</span>
        ) : (
          <Link
            key={page}
            href={createPageURL(Number(page))}
            aria-current={Number(page) === currentPage ? 'page' : undefined}
            className={Number(page) === currentPage ? 'active' : ''}
          >
            {page}
          </Link>
        )
      ))}
 
      {/* 次のページ */}
      {currentPage < totalPages ? (
        <Link href={createPageURL(currentPage + 1)}>
          Next
        </Link>
      ) : (
        <span aria-disabled="true">Next</span>
      )}
    </nav>
  );
}
 
// ページ番号生成ロジック
function generatePageNumbers(
  current: number,
  total: number
): (string | number)[] {
  if (total <= 7) {
    return Array.from({ length: total }, (_, i) => i + 1);
  }
 
  if (current <= 3) {
    return [1, 2, 3, 4, '...', total];
  }
 
  if (current >= total - 2) {
    return [1, '...', total - 3, total - 2, total - 1, total];
  }
 
  return [1, '...', current - 1, current, current + 1, '...', total];
}

// === 動的メタデータの生成 ===
// app/products/page.tsx
 
import { Metadata } from 'next';
 
interface Props {
  searchParams: Promise<{
    q?: string;
    category?: string;
    page?: string;
  }>;
}
 
export async function generateMetadata({
  searchParams,
}: Props): Promise<Metadata> {
  const params = await searchParams;
 
  let title = 'Products';
  let description = 'Browse our product catalog';
 
  if (params.q) {
    title = `Search: "${params.q}" - Products`;
    description = `Search results for "${params.q}"`;
  }
 
  if (params.category) {
    title = `${params.category} - Products`;
    description = `Browse ${params.category} products`;
  }
 
  const page = Number(params.page ?? '1');
  if (page > 1) {
    title += ` (Page ${page})`;
  }
 
  return {
    title,
    description,
    // canonical URL でページネーションの重複を防ぐ
    alternates: {
      canonical: params.q
        ? `/products?q=${encodeURIComponent(params.q)}`
        : params.category
          ? `/products?category=${params.category}`
          : '/products',
    },
    // 検索結果ページはインデックスしない
    robots: params.q ? { index: false } : undefined,
  };
}

// === Streaming SSR パターン ===
// app/products/page.tsx
 
import { Suspense } from 'react';
 
export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<Record<string, string>>;
}) {
  const params = await searchParams;
 
  return (
    <div>
      <h1>Products</h1>
 
      {/* フィルタUI: すぐに表示（Client Component） */}
      <Suspense fallback={<FiltersSkeleton />}>
        <ProductFilters />
      </Suspense>
 
      {/* 検索結果: データフェッチを待ってストリーミング */}
      <Suspense fallback={<ProductGridSkeleton count={20} />}>
        <ProductResults searchParams={params} />
      </Suspense>
 
      {/* サイドバー: 独立してストリーミング */}
      <Suspense fallback={<SidebarSkeleton />}>
        <CategorySidebar />
      </Suspense>
    </div>
  );
}
 
// データフェッチを含む Server Component
async function ProductResults({
  searchParams,
}: {
  searchParams: Record<string, string>;
}) {
  // このデータフェッチが完了するまでフォールバックが表示される
  const products = await getProducts({
    query: searchParams.q,
    page: Number(searchParams.page ?? '1'),
    sort: searchParams.sort ?? 'newest',
    category: searchParams.category,
  });
 
  return (
    <>
      <p>{products.meta.total} products found</p>
      <ProductGrid products={products.data} />
      <ServerPagination
        currentPage={Number(searchParams.page ?? '1')}
        totalPages={products.meta.totalPages}
        searchParams={searchParams}
      />
    </>
  );
}

// === デバウンス: 検索入力のURL同期 ===
'use client';
import { useState, useEffect, useCallback } from 'react';
import { useRouter, usePathname, useSearchParams } from 'next/navigation';
 
/**
 * デバウンスフック
 */
function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);
 
  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);
 
  return debouncedValue;
}
 
/**
 * デバウンス付き検索入力コンポーネント
 */
function DebouncedSearchInput() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const pathname = usePathname();
 
  // ローカル状態（即座に更新）
  const [inputValue, setInputValue] = useState(
    searchParams.get('q') ?? ''
  );
 
  // デバウンスされた値（300ms後に確定）
  const debouncedQuery = useDebounce(inputValue, 300);
 
  // デバウンスされた値が変更されたらURLを更新
  useEffect(() => {
    const params = new URLSearchParams(searchParams.toString());
 
    if (debouncedQuery) {
      params.set('q', debouncedQuery);
    } else {
      params.delete('q');
    }
    params.delete('page'); // 検索変更時にページリセット
 
    const queryString = params.toString();
    const url = queryString ? `${pathname}?${queryString}` : pathname;
 
    // replace: 入力中の履歴を残さない
    router.replace(url, { scroll: false });
  }, [debouncedQuery, pathname, router, searchParams]);
 
  // URLが外部から変更された場合（ブラウザバック等）に同期
  useEffect(() => {
    const urlQuery = searchParams.get('q') ?? '';
    if (urlQuery !== inputValue) {
      setInputValue(urlQuery);
    }
  }, [searchParams]); // eslint-disable-line react-hooks/exhaustive-deps
 
  return (
    <input
      type="search"
      value={inputValue}
      onChange={(e) => setInputValue(e.target.value)}
      placeholder="Search products..."
    />
  );
}

// === nuqs でのデバウンス ===
import { useQueryState } from 'nuqs';
 
function SearchWithNuqs() {
  const [query, setQuery] = useQueryState('q', {
    defaultValue: '',
    // nuqs v2+ では shallow オプションで制御
    shallow: true, // サーバーへのリクエストを防ぐ
    throttleMs: 300, // URL更新をスロットル
    history: 'replace', // 入力中は履歴を汚さない
  });
 
  return (
    <input
      type="search"
      value={query}
      onChange={(e) => setQuery(e.target.value || null)}
      placeholder="Search..."
    />
  );
}

// === URL状態のバリデーション ===
import { z } from 'zod';
 
// Zod スキーマでURL状態を定義
const searchParamsSchema = z.object({
  q: z.string().max(200).optional().default(''),
  page: z.coerce.number().int().positive().optional().default(1),
  per_page: z.coerce.number().int().min(10).max(100).optional().default(20),
  sort: z.enum(['newest', 'oldest', 'price-asc', 'price-desc', 'popular'])
    .optional().default('newest'),
  category: z.string().max(50).optional(),
  tags: z.string().transform(s => s ? s.split(',') : []).optional().default(''),
  price_min: z.coerce.number().nonnegative().optional(),
  price_max: z.coerce.number().nonnegative().optional(),
}).refine(
  (data) => {
    if (data.price_min !== undefined && data.price_max !== undefined) {
      return data.price_min <= data.price_max;
    }
    return true;
  },
  { message: 'price_min must be less than or equal to price_max' }
);
 
type ValidatedSearchParams = z.infer<typeof searchParamsSchema>;
 
// Server Component でのバリデーション
export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<Record<string, string>>;
}) {
  const rawParams = await searchParams;
 
  // バリデーションとデフォルト値の適用
  const result = searchParamsSchema.safeParse(rawParams);
 
  if (!result.success) {
    // 不正なパラメータの場合はデフォルト値にリダイレクト
    redirect('/products');
  }
 
  const validParams = result.data;
 
  // ... データフェッチ
}
 
// カスタムフックでのバリデーション（Client Component）
function useValidatedSearchParams() {
  const searchParams = useSearchParams();
 
  const rawParams = Object.fromEntries(searchParams.entries());
  const result = searchParamsSchema.safeParse(rawParams);
 
  if (!result.success) {
    // デフォルト値を返す
    return searchParamsSchema.parse({});
  }
 
  return result.data;
}

// === XSS 対策: URL状態のサニタイズ ===
 
/**
 * URL パラメータのサニタイズ
 * XSSやインジェクション攻撃を防ぐ
 */
function sanitizeSearchParam(value: string): string {
  // HTMLタグを除去
  const sanitized = value.replace(/<[^>]*>/g, '');
 
  // 制御文字を除去
  const cleaned = sanitized.replace(/[\x00-\x1F\x7F]/g, '');
 
  // 最大長を制限
  return cleaned.slice(0, 500);
}
 
/**
 * URL パラメータを安全に表示する
 */
function SafeSearchDisplay({ query }: { query: string }) {
  // React はデフォルトでXSSを防ぐが、追加の保護として
  const safeQuery = sanitizeSearchParam(query);
 
  return (
    <h2>
      Search results for: <span className="highlight">{safeQuery}</span>
    </h2>
  );
}
 
// 危険: URLパラメータを直接 dangerouslySetInnerHTML に使わない
// NG:
function DangerousComponent() {
  const searchParams = useSearchParams();
  const q = searchParams.get('q') ?? '';
 
  // 絶対にやってはいけない!
  // return <div dangerouslySetInnerHTML={{ __html: q }} />;
 
  // OK: React のテキストノードとして表示
  return <div>{q}</div>;
}

// === History API: push vs replace の使い分け ===
 
/**
 * push（履歴に追加）を使うべき場面:
 * - フィルタの変更
 * - カテゴリの変更
 * - ソートの変更
 * - 検索の確定（デバウンス後）
 * → ブラウザバックで前のフィルタ状態に戻れる
 */
function handleFilterChange(newCategory: string) {
  // React Router
  setSearchParams(prev => {
    const next = new URLSearchParams(prev);
    next.set('category', newCategory);
    return next;
  }); // デフォルトは push
 
  // Next.js
  router.push(`${pathname}?category=${newCategory}`);
}
 
/**
 * replace（履歴を置換）を使うべき場面:
 * - 検索入力中のリアルタイム更新（デバウンス中）
 * - ページネーションの連続クリック
 * - 並び替えの頻繁な切り替え
 * - 初期パラメータの正規化
 * → ブラウザバックで大量の中間状態に戻らない
 */
function handleSearchInput(query: string) {
  // React Router
  setSearchParams(prev => {
    const next = new URLSearchParams(prev);
    if (query) next.set('q', query);
    else next.delete('q');
    return next;
  }, { replace: true }); // 履歴を置換
 
  // Next.js
  router.replace(`${pathname}?q=${encodeURIComponent(query)}`);
}
 
/**
 * popstate イベント: ブラウザバック/フォワードの検知
 */
useEffect(() => {
  function handlePopState(event: PopStateEvent) {
    // ブラウザの戻る/進むが押されたときの処理
    // React Router や Next.js は自動的にこれを処理するが、
    // カスタムロジックが必要な場合に使用
    console.log('Navigation via browser back/forward');
    console.log('New URL:', window.location.href);
  }
 
  window.addEventListener('popstate', handlePopState);
  return () => window.removeEventListener('popstate', handlePopState);
}, []);

// === 配列パラメータの方式比較 ===
 
// 方式1: 同一キー反復（Web標準 / URLSearchParams 準拠）
// URL: ?tag=sale&tag=new&tag=popular
// 取得: searchParams.getAll('tag') → ['sale', 'new', 'popular']
// 利点: Web標準に準拠、URLSearchParams で自然に扱える
// 欠点: URLが長くなりやすい
 
// 方式2: カンマ区切り
// URL: ?tags=sale,new,popular
// 取得: searchParams.get('tags')?.split(',') ?? []
// 利点: URLがコンパクト
// 欠点: 値にカンマが含まれる場合にエスケープが必要
 
// 方式3: ブラケット表記（PHP/Ruby on Rails スタイル）
// URL: ?tags[]=sale&tags[]=new&tags[]=popular
// 取得: 手動パースが必要
// 利点: バックエンドフレームワークとの互換性
// 欠点: URLSearchParams で直接扱えない
 
// 方式4: JSON エンコード
// URL: ?tags=["sale","new","popular"]
// 取得: JSON.parse(searchParams.get('tags') ?? '[]')
// 利点: 複雑な構造も表現可能
// 欠点: URLが読みにくい、エンコードで長くなる
 
// 推奨: 方式1 または 方式2
// 簡単な配列 → 方式2（カンマ区切り）
// URLSearchParams との互換性重視 → 方式1（同一キー反復）
 
// 実装例: カンマ区切り方式のヘルパー
function useArrayParam(key: string): [string[], (values: string[]) => void] {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const values = searchParams.get(key)?.split(',').filter(Boolean) ?? [];
 
  const setValues = useCallback((newValues: string[]) => {
    setSearchParams(prev => {
      const params = new URLSearchParams(prev);
      if (newValues.length > 0) {
        params.set(key, newValues.join(','));
      } else {
        params.delete(key);
      }
      params.delete('page'); // ページリセット
      return params;
    });
  }, [key, setSearchParams]);
 
  return [values, setValues];
}
 
// 使用例
function TagFilter() {
  const [selectedTags, setSelectedTags] = useArrayParam('tags');
 
  const allTags = ['sale', 'new', 'popular', 'limited', 'exclusive'];
 
  function toggleTag(tag: string) {
    if (selectedTags.includes(tag)) {
      setSelectedTags(selectedTags.filter(t => t !== tag));
    } else {
      setSelectedTags([...selectedTags, tag]);
    }
  }
 
  return (
    <div>
      {allTags.map(tag => (
        <button
          key={tag}
          onClick={() => toggleTag(tag)}
          className={selectedTags.includes(tag) ? 'active' : ''}
        >
          {tag}
        </button>
      ))}
    </div>
  );
}