URL como Fuente de la Verdad: Gestión de Estado Tipada con nuqs

// Lectura y escritura en la URL con la misma ergonomía que useState:
const [query, setQuery] = useQueryState('q', queryParser);

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

// Criterios de ordenación admisibles
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. Parsers escalares básicos
export const pageParser = parseAsInteger.withDefault(1);
export const queryParser = parseAsString.withDefault('').withOptions({
  throttleMs: 300, // Debounce en la escritura sobre la barra de direcciones
  shallow: true,   // Sin re-solicitar componentes de servidor de Next.js
});
export const inStockOnlyParser = parseAsBoolean.withDefault(false);

// 2. Parser estricto para enumeraciones
export const sortOrderParser = parseAsStringEnum<SortOrder>(
  Object.values(SortOrderEnum)
).withDefault(SortOrderEnum.POPULAR);

// 3. Parser de lista de cadenas separadas por coma (?tags=react,nextjs)
export const tagsParser = parseAsArrayOf(parseAsString, ',').withDefault([]);

// 4. Parser personalizado con validación de esquemas Zod (JSON en la 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="Buscar cursos y habilidades..."
        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)} // ¡Asignar null elimina el parámetro de la URL!
          className="absolute right-3 top-2.5 text-xs text-text-muted hover:text-text-primary"
        >
          Limpiar
        </button>
      )}
    </div>
  );
}

'use client';

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

export function CatalogFiltersBar() {
  // Actualización atómica de múltiples parámetros en una única transacción de URL
  const [filters, setFilters] = useQueryStates(
    {
      page: pageParser,
      sort: sortOrderParser,
      inStock: inStockOnlyParser,
    },
    {
      shallow: true,
      history: 'push', // Añade una entrada al historial del navegador al cambiar de filtro
    }
  );

  const handleSortChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
    // Al alterar el orden, se restablece sincrónicamente la página a 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>Ordenación:</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}>Más populares</option>
          <option value={SortOrderEnum.PRICE_ASC}>Precio: menor a mayor</option>
          <option value={SortOrderEnum.PRICE_DESC}>Precio: mayor a menor</option>
          <option value={SortOrderEnum.NEWEST}>Más recientes</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>Solo disponibles</span>
      </label>

      <div className="ml-auto text-xs font-mono text-accent-cyan">
        Página: {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';

// Inicialización de la caché de análisis en servidor
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) {
  // Análisis síncrono con tipado garantizado en Node.js/Edge
  const parsedParams = catalogSearchParamsCache.parse(await searchParams);

  // Consulta directa a la base de datos con tipos validados sin inyecciones ni 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">Catálogo de Especificaciones</h1>
      
      {/* Controladores de cliente sincronizados mediante la URL */}
      <CatalogSearchInput />
      <CatalogFiltersBar />

      {/* Malla de productos generada directamente en el servidor */}
      <ProductGrid initialProducts={products} />
    </div>
  );
}