URL как источник истины: типизированное управление стейтом с nuqs

// Чтение и запись параметра в URL точно так же просто, как useState:
const [query, setQuery] = useQueryState('q', queryParser);

import {
  parseAsInteger,
  parseAsString,
  parseAsStringEnum,
  parseAsBoolean,
  parseAsArrayOf,
  createParser,
} from 'nuqs';
import { z } from 'zod';

// Перечисление допустимых вариантов сортировки
export const SortOrderEnum = {
  POPULAR: 'popular',
  PRICE_ASC: 'price_asc',
  PRICE_DESC: 'price_desc',
  NEWEST: 'newest',
} as const;

export type SortOrder = (typeof SortOrderEnum)[keyof typeof SortOrderEnum];

// 1. Примитивные парсеры
export const pageParser = parseAsInteger.withDefault(1);
export const queryParser = parseAsString.withDefault('').withOptions({
  throttleMs: 300, // Дебаунс синхронизации с адресной строкой
  shallow: true,   // Без повторного запроса серверных компонентов Next.js
});
export const inStockOnlyParser = parseAsBoolean.withDefault(false);

// 2. Строгий Enum-парсер
export const sortOrderParser = parseAsStringEnum<SortOrder>(
  Object.values(SortOrderEnum)
).withDefault(SortOrderEnum.POPULAR);

// 3. Парсер массива строк (список категорий, разделенных запятой)
export const tagsParser = parseAsArrayOf(parseAsString, ',').withDefault([]);

// 4. Кастомный парсер на базе Zod-схемы (JSON в URL)
const PriceRangeSchema = z.object({
  min: z.number().nonnegative(),
  max: z.number().positive(),
});

export type PriceRange = z.infer<typeof PriceRangeSchema>;

export const priceRangeParser = createParser<PriceRange>({
  parse: (raw: string) => {
    try {
      const parsed = JSON.parse(raw);
      const validated = PriceRangeSchema.safeParse(parsed);
      return validated.success ? validated.data : null;
    } catch {
      return null;
    }
  },
  serialize: (value: PriceRange) => JSON.stringify(value),
}).withDefault({ min: 0, max: 10000 });

'use client';

import React from 'react';
import { useQueryState } from 'nuqs';
import { queryParser } from '@/lib/searchParams';

export function CatalogSearchInput() {
  const [query, setQuery] = useQueryState('q', queryParser);

  return (
    <div className="relative w-full max-w-md">
      <input
        type="search"
        id="catalog-search"
        value={query}
        placeholder="Поиск по курсам и навыкам..."
        onChange={(e) => setQuery(e.target.value)}
        className="w-full px-4 py-2 bg-bg-surface border border-border rounded-lg text-text-primary focus:outline-none focus:border-accent-cyan"
      />
      {query && (
        <button
          onClick={() => setQuery(null)} // Передача null удаляет параметр из URL!
          className="absolute right-3 top-2.5 text-xs text-text-muted hover:text-text-primary"
        >
          Очистить
        </button>
      )}
    </div>
  );
}

'use client';

import React from 'react';
import { useQueryStates } from 'nuqs';
import {
  pageParser,
  sortOrderParser,
  inStockOnlyParser,
  SortOrderEnum,
} from '@/lib/searchParams';

export function CatalogFiltersBar() {
  // Атомарное обновление нескольких параметров в одной транзакции URL
  const [filters, setFilters] = useQueryStates(
    {
      page: pageParser,
      sort: sortOrderParser,
      inStock: inStockOnlyParser,
    },
    {
      shallow: true,
      history: 'push', // Добавляет запись в историю при смене фильтра
    }
  );

  const handleSortChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
    // При смене сортировки синхронно сбрасываем страницу на 1
    void setFilters({
      sort: e.target.value as typeof filters.sort,
      page: 1,
    });
  };

  return (
    <div className="flex items-center gap-4 py-4 border-b border-border">
      <label className="flex items-center gap-2 text-sm text-text-muted">
        <span>Сортировка:</span>
        <select
          value={filters.sort}
          onChange={handleSortChange}
          className="bg-bg-surface border border-border rounded px-2 py-1 text-text-primary text-sm"
        >
          <option value={SortOrderEnum.POPULAR}>По популярности</option>
          <option value={SortOrderEnum.PRICE_ASC}>Сначала дешевле</option>
          <option value={SortOrderEnum.PRICE_DESC}>Сначала дороже</option>
          <option value={SortOrderEnum.NEWEST}>Сначала новые</option>
        </select>
      </label>

      <label className="flex items-center gap-2 text-sm text-text-muted cursor-pointer">
        <input
          type="checkbox"
          checked={filters.inStock}
          onChange={(e) => setFilters({ inStock: e.target.checked, page: 1 })}
          className="rounded border-border"
        />
        <span>Только в наличии</span>
      </label>

      <div className="ml-auto text-xs font-mono text-accent-cyan">
        Страница: {filters.page}
      </div>
    </div>
  );
}

import { createSearchParamsCache } from 'nuqs/server';
import {
  queryParser,
  pageParser,
  sortOrderParser,
  inStockOnlyParser,
} from '@/lib/searchParams';
import { CatalogSearchInput } from '@/components/CatalogSearchInput';
import { CatalogFiltersBar } from '@/components/CatalogFiltersBar';
import { ProductGrid } from '@/components/ProductGrid';
import { fetchProductsFromDb } from '@/lib/db/products';

// Инициализируем серверный кэш парсинга
const catalogSearchParamsCache = createSearchParamsCache({
  q: queryParser,
  page: pageParser,
  sort: sortOrderParser,
  inStock: inStockOnlyParser,
});

interface PageProps {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}

export default async function CatalogPage({ searchParams }: PageProps) {
  // Синхронный парсинг с гарантией типов на стороне Node.js/Edge
  const parsedParams = catalogSearchParamsCache.parse(await searchParams);

  // Прямой запрос к БД с валидными типами без инъекций и undefined
  const products = await fetchProductsFromDb({
    search: parsedParams.q,
    page: parsedParams.page,
    sortBy: parsedParams.sort,
    availableOnly: parsedParams.inStock,
  });

  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-2xl font-bold mb-6 font-sans">Каталог спецификаций</h1>
      
      {/* Клиентские контроллеры, синхронизирующиеся через URL */}
      <CatalogSearchInput />
      <CatalogFiltersBar />

      {/* Отрендеренная на сервере сетка товаров */}
      <ProductGrid initialProducts={products} />
    </div>
  );
}