Kurs vibe coding z Claude Code · Moduł 14: Klon Pinteresta

Mapa skarbów w kolumnach: siatka masonry ze szkicu

10 min czytania
W tej lekcji12

Ahoj! W tej lokacji budujesz Treasure Map, klon Pinteresta, czyli serwisu, w którym ludzie przypinają inspirujące obrazki do tablic. Jeden obrazek z tytułem i autorem to pin. Kłopot zaczyna się na stronie głównej: zdjęcia mają różne wysokości, a zwykła siatka układa je w rzędy tak wysokie jak najwyższe zdjęcie, więc pod niższymi zostają dziury. Układ masonry (mur z cegieł) ma kolumny, a każdy kolejny pin trafia do tej, która jest w tej chwili najniższa. Jak kwatermistrz, który nową skrzynię stawia na najniższym stosie.

Czego się nauczysz

  • podać Claude szkic układu i sprawdzić, czy przeczytał go tak jak Ty;
  • przeczytać algorytm najniższej kolumny i rozpoznać stan ustawiany w trakcie renderu;
  • dobrać liczbę kolumn do szerokości okna bez błędu hydratacji;
  • zarezerwować miejsce na obrazek, zanim się pobierze, i dopilnować fokusu z klawiatury;
  • zamówić nieskończone przewijanie z wartownikiem, bez podwójnych żądań.

Nowy port: projekt treasure-map

Klon to osobna aplikacja, więc zakładasz ją poleceniem z lekcji 1_2, zmieniając tylko nazwę:

npx create-next-app@latest treasure-map --ts --eslint --tailwind --app --no-src-dir --no-cache-components --agents-md --no-agent-feedback --use-npm

Dalej znana pętla: sesja claude, CLAUDE.md z importem @AGENTS.md (lekcja 1_7), Vitest z poprawką @types/node z lekcji 4_1 i pierwszy commit. Do public/pins/ wrzuć kilkanaście zdjęć o szerokości 600 pikseli i różnych wysokościach, własnych albo kolorowych plansz z ffmpeg, jak w lekcji 12_1. Obrazy z projektu nie potrzebują wpisu remotePatterns z lekcji 3_1.

Szkic zamiast opisu

Układ kolumn łatwiej narysować niż opisać. Narysuj na kartce cztery kolumny prostokątów o różnej wysokości i zapisz zdjęcie jako szkice/masonry.png. Podasz je ścieżką do pliku, jak w lekcji 3_2. Szkic pokazuje wygląd, a nie zachowanie: liczba kolumn na telefonie i obsługa klawisza Tab muszą stać w tekście polecenia.

Polecenie dla Claude Code

Zmiana dotyka danych, funkcji, trzech komponentów i strony, więc zaczynasz od planu, jak w lekcji 1_6:

Polecenie dla Claude Code:

/plan Najpierw opisz, co widzisz na szkicu szkice/masonry.png.
Potem zaplanuj stronę główną Treasure Map: siatka masonry z pinów
z lib/pins.ts (obrazy z public/pins, każdy pin ma width, height
i dominantColor). Każdy pin trafia do najniższej kolumny; podział
licz w czystej funkcji lib/masonry.ts, nie w stanie. Kolumny: 2 na
telefonie, 3 od 768 px, 4 od 1024 px, bez błędu hydratacji. Miejsce
na obrazek zarezerwowane przed pobraniem, tło w kolorze dominującym.
Karta pinu: przycisk Zapisz w prawym górnym rogu, tytuł i autor na
dole, widoczne po najechaniu myszą i po fokusie z klawiatury.
Najpierw testy lib/masonry.ts. Gotowe, gdy npm run test -- --run,
npm run lint i npx tsc --noEmit przejdą bez błędów.

W planie przeczytaj opis szkicu i sprawdź, czy podział jest czystą funkcją i skąd Claude weźmie szerokość okna. Jeśli plan o tym milczy, popraw go przez Ctrl+G.

Co napisał Claude: dane pinu

Otwórz w Cursorze lib/types.ts. Pin ma tylko pola, których używa ta lekcja:

// lib/types.ts
export interface Pin {
  id: string;
  title: string;
  author: string;
  src: string;
  width: number;
  height: number;
  dominantColor: string; // "#rrggbb"
  tags: string[];
}

width i height to wymiary pliku w pikselach, a nie rozmiar na ekranie. dominantColor to kolor, którego na zdjęciu jest najwięcej, liczony raz, przy dodawaniu pliku. Tagi przydadzą się w lekcji 13_3.

Co napisał Claude: najniższa kolumna

Otwórz lib/masonry.ts. Cały algorytm to jedna pętla, która bierze piny po kolei i każdy dokłada do najniższej w tej chwili kolumny:

// lib/masonry.ts
export function distributePins<T extends Sized>(pins: readonly T[], columnCount: number): T[][] {
  const columns: T[][] = Array.from({ length: columnCount }, () => []);
  const heights: number[] = new Array(columnCount).fill(0);
  for (const pin of pins) {
    const shortest = heights.indexOf(Math.min(...heights));
    columns[shortest].push(pin);
    heights[shortest] += pin.height / pin.width; // wysokość przy szerokości kolumny równej 1
  }
  return columns;
}

Sized to typ z tego pliku: wszystko, co ma width i height. Math.min(...heights) znajduje najniższą wysokość, a indexOf numer jej kolumny; przy remisie wygrywa kolumna z lewej. Kolumny mają równą szerokość, więc ostatnia linia dodaje samą proporcję height / width: nie trzeba znać pikseli na ekranie. Funkcja nie zmienia tablicy wejściowej, tylko buduje nowe.

Z pięciu testów zapamiętaj jeden: "dopisanie pinów nie przesuwa wcześniejszych". Pętla idzie po pinach po kolei, więc przy dociąganiu kolejnych stron nic nie skacze pod oczami widza. Wynik u nas: Tests 5 passed (5).

Typowy błąd: stan ustawiany w trakcie renderu

Pierwsza wersja agenta, którą znajdziesz w wielu poradnikach, trzymała wysokości kolumn w stanie:

// components/MasonryGrid.tsx (wersja agenta)
const [columnHeights, setColumnHeights] = useState<number[]>(Array(columns).fill(0));
const distributePins = () => {
  // ... ta sama pętla co wyżej
  setColumnHeights(heights);
  return columnArrays;
};
const columnArrays = distributePins();

Render woła distributePins, ta ustawia stan nową tablicą, więc React renderuje komponent jeszcze raz, a ten znowu ustawia stan. U nas strona odpowiedziała kodem 500, a konsola pokazała Too many re-renders. React limits the number of renders to prevent an infinite loop. Stanu columnHeights nikt zresztą nie czytał. npm run lint złapał błąd przed przeglądarką: Cannot call setState during render (reguła react-hooks/set-state-in-render), a npx tsc --noEmit milczał. Lekarstwo podpowiada sam linter: dane wyliczane z propsów licz w trakcie renderu, bez stanu. Dlatego MasonryGrid ma jedną linię const columns = distributePins(pins, columnCount).

Co napisał Claude: liczba kolumn bez błędu hydratacji

Serwer renderuje HTML, zanim zobaczy go przeglądarka, więc nie zna szerokości okna. Agent lubi napisać typeof window === "undefined" ? 2 : .... U nas serwer wysłał "2", przeglądarka policzyła "4" i React zgłosił Hydration failed because the server rendered text didn't match the client. Hydratacja to moment, w którym React przejmuje HTML z serwera i podpina do niego zdarzenia. Otwórz lib/columns.ts:

// lib/columns.ts
export function useColumnCount(): number {
  return useSyncExternalStore(
    subscribe,
    () => columnsForWidth(window.innerWidth),
    () => 2, // serwer nie zna szerokości okna: renderuje 2 kolumny, przeglądarka poprawia po hydratacji
  );
}

useSyncExternalStore to hook Reacta do wartości, które zmieniają się poza Reactem. subscribe nasłuchuje zdarzenia resize okna, druga funkcja zamienia szerokość na 2, 3 albo 4 kolumny, a trzecia to wersja dla serwera. Według dokumentacji Reacta działa ona tylko na serwerze i podczas hydratacji, więc pierwszy render w przeglądarce zgadza się z HTML-em z serwera, a zaraz potem React renderuje jeszcze raz z prawdziwą szerokością. Ceną jest mignięcie dwóch kolumn na szerokim ekranie. React porównuje wyniki przez Object.is, więc ruch krawędzi okna w tym samym przedziale nie daje nowego renderu.

Co napisał Claude: karta pinu

Otwórz components/PinCard.tsx. Zdjęcie:

// components/PinCard.tsx
<figure className="group relative overflow-hidden rounded-2xl" style={{ backgroundColor: pin.dominantColor }}>
  <Image
    src={pin.src}
    alt={pin.title}
    width={pin.width}
    height={pin.height}
    sizes="(min-width: 1024px) 25vw, (min-width: 768px) 33vw, 50vw"
    loading={eager ? "eager" : "lazy"}
    className="h-auto w-full"
  />

Według dokumentacji next/image przeglądarka liczy z width i height proporcje i rezerwuje miejsce, zanim obrazek się pobierze. Do tego czasu widać prostokąt w kolorze dominującym, więc strona nie podskakuje. eager dostają piny z dwóch pierwszych rzędów. Agent często pisze tu priority, który dokumentacja Next.js 16 oznacza jako przestarzały na rzecz preload, a w większości przypadków radzi loading="eager" albo fetchPriority="high". preload nie pasuje też tam, gdzie największym elementem może być kilka różnych obrazków, jak w mozaice. Na zdjęciu leży nakładka:

// components/PinCard.tsx
<div className="absolute inset-0 flex flex-col justify-between bg-black/40 p-3 opacity-0 transition-opacity group-focus-within:opacity-100 group-hover:opacity-100">

Nakładkę pokazuje sam CSS: group-hover po najechaniu myszą i group-focus-within, gdy fokus jest na przycisku w środku. Stary kod robił to dwa razy naraz, stanem isHovered i klasą group-hover; jeden mechanizm wystarczy, a CSS nie renderuje komponentu przy każdym ruchu myszy. Przycisk Zapisz w prawym górnym rogu ma aria-label z tytułem, na przykład "Zapisz pin: Zatoka o świcie", bo trzydzieści sześć identycznych "Zapisz" brzmi w czytniku ekranu tak samo. Ma też obwódkę focus-visible, a tytuł i autor stoją na dole. Każda kolumna to lista ul, więc Tab idzie najpierw w dół pierwszej kolumny: taka jest cena masonry liczonego w JavaScripcie.

Nieskończone przewijanie: wartownik

Pierwsza strona ma dwanaście pinów, a kolejne mają dochodzić same, gdy widz zbliża się do końca. Drugie polecenie:

/plan Dodaj nieskończone przewijanie. Route Handler GET /api/pins?cursor=
zwraca 12 pinów i nextCursor (null na końcu). Komponent PinFeed
dociąga następną stronę, gdy element-wartownik pod siatką zbliża się
do ekranu: IntersectionObserver, element przez useRef. Bez podwójnych
żądań i bez starych wartości w domknięciu. Na końcu listy komunikat
zamiast wartownika. Na koniec lint, tsc i build.

Trasa w app/api/pins/route.ts czyta cursor z adresu i oddaje getPinPage(cursor). Kursor to tu numer pierwszego pinu następnej strony. Otwórz components/PinFeed.tsx i znajdź efekt, który pilnuje wartownika i dociąga kolejne strony:

// components/PinFeed.tsx
useEffect(() => {
  const sentinel = sentinelRef.current;
  if (!sentinel || cursor === null) return;
  let cancelled = false;
  const observer = new IntersectionObserver(
    (entries) => {
      if (!entries[0].isIntersecting) return;
      observer.disconnect(); // jedna strona na jedno wejście wartownika
      fetch(`/api/pins?cursor=${cursor}`)
        .then((res) => res.json() as Promise<PinPage>)
        .then((page) => {
          if (cancelled) return;
          setPins((prev) => [...prev, ...page.pins]);
          setCursor(page.nextCursor);
        });
    },
    { rootMargin: "0px 0px 600px 0px" },
  );
  observer.observe(sentinel);
  return () => {
    cancelled = true;
    observer.disconnect();
  };
}, [cursor]);

To skrót: prawdziwy plik sprawdza jeszcze res.ok i w .catch pokazuje komunikat o błędzie. Wartownik to pusty div pod siatką, a IntersectionObserver daje znać, gdy wchodzi on w pole widzenia. rootMargin według MDN poszerza obszar obserwacji, tu o 600 pikseli w dół, więc ładowanie rusza przed końcem listy. cursor stoi w zależnościach efektu, więc każda strona dostaje nowego obserwatora z aktualnym kursorem i nic nie czyta starej wartości. disconnect() po pierwszym trafieniu daje jedno żądanie na jedno wejście wartownika, a prev => ... dokleja piny do najświeższej listy. Gdy nextCursor to null, obserwatora nie ma, a zamiast wartownika stoi napis "To już wszystkie skarby na tej mapie."

Przegląd kapitana

  1. Stan w renderze. Wyszukaj w projekcie (Cmd+Shift+F) setColumn. Stan ustawiany w ciele komponentu zgłasza npm run lint; nigdy nie wyłączaj tej reguły komentarzem.
  2. Hydratacja. Wyszukaj typeof window, potem otwórz stronę w szerokim oknie: konsola ma być pusta. U nas Chrome pokazał 4 kolumny przy 1280 pikselach, 3 przy 800 i 2 przy 700, bez przeładowania.
  3. Klawiatura. Wejdź na stronę i naciśnij Tab. U nas fokus trafił na "Zapisz pin: Zatoka o świcie", nakładka się pokazała, a przycisk dostał obwódkę.
  4. Jedno żądanie na stronę. W zakładce Network przewiń do końca. U nas 36 pinów przyszło w dwóch żądaniach (cursor=12 i cursor=24), bez powtórek, choć w trybie deweloperskim React uruchamia efekty dwa razy. Typowy błąd agenta to setPins([...pins, ...nowe]) w efekcie z pustą tablicą zależności: domknięcie widzi wciąż pierwszą stronę, a flaga ładowania w stanie nie zatrzymuje drugiego wywołania. Objaw: te same piny dwa razy i ostrzeżenie o powtórzonych kluczach.

Następny krok

Gdy przegląd przejdzie, poproś o commit "Siatka masonry z nieskończonym przewijaniem". Potem mały krok: "Gdy pobranie strony się nie uda, pokaż przycisk Spróbuj ponownie". W następnej lekcji przycisk Zapisz dostanie skrzynie. W edytorze poniżej czeka podział na kolumny w miniaturze: dokładaj piny po jednym, zmieniaj liczbę kolumn i patrz, która jest najniższa.

Zapamiętaj: dobry kwatermistrz stawia każdą skrzynię na najniższym stosie i liczy stosy z listy ładunku, zamiast co chwilę przepisywać księgę w trakcie liczenia.

Kod do tej lekcji: App.tsx
// Masonry w miniaturze: dokładaj piny po jednym i patrz, która kolumna jest najniższa
import { useState } from 'react';

interface Pin {
  id: string;
  title: string;
  width: number;
  height: number;
  dominantColor: string;
}

const PINS: Pin[] = [
  { id: 'p1', title: 'Zatoka o świcie', width: 600, height: 400, dominantColor: '#289888' },
  { id: 'p2', title: 'Zachód nad portem', width: 600, height: 900, dominantColor: '#f8a858' },
  { id: 'p3', title: 'Dżungla na wyspie', width: 600, height: 750, dominantColor: '#284858' },
  { id: 'p4', title: 'Piasek pod palmą', width: 600, height: 600, dominantColor: '#e8c868' },
  { id: 'p5', title: 'Głębia oceanu', width: 600, height: 1050, dominantColor: '#487898' },
  { id: 'p6', title: 'Rafa koralowa', width: 600, height: 500, dominantColor: '#e86868' },
  { id: 'p7', title: 'Laguna', width: 600, height: 800, dominantColor: '#a8c808' },
  { id: 'p8', title: 'Złoto w skrzyni', width: 600, height: 450, dominantColor: '#f88808' },
  { id: 'p9', title: 'Nocna wachta', width: 600, height: 1200, dominantColor: '#080858' },
  { id: 'p10', title: 'Stara mapa', width: 600, height: 700, dominantColor: '#986848' },
  { id: 'p11', title: 'Pokład z drewna', width: 600, height: 950, dominantColor: '#785838' },
  { id: 'p12', title: 'Bandera w porcie', width: 600, height: 550, dominantColor: '#d8a898' },
];

// Czysta funkcja z lekcji: kolumny i ich wysokości liczone w trakcie renderu, bez stanu
function distributePins(pins: readonly Pin[], columnCount: number) {
  const columns: Pin[][] = Array.from({ length: columnCount }, () => []);
  const heights: number[] = new Array(columnCount).fill(0);
  for (const pin of pins) {
    const shortest = heights.indexOf(Math.min(...heights));
    columns[shortest].push(pin);
    heights[shortest] += pin.height / pin.width; // wysokość przy szerokości kolumny równej 1
  }
  return { columns, heights };
}

export default function App() {
  const [placed, setPlaced] = useState(3);
  const [columnCount, setColumnCount] = useState(3);

  const { columns, heights } = distributePins(PINS.slice(0, placed), columnCount);
  const next = PINS[placed];
  const shortest = heights.indexOf(Math.min(...heights));
  const lastId = PINS[placed - 1]?.id;

  return (
    <div className="min-h-screen bg-amber-50 p-4 text-zinc-900">
      <h1 className="text-xl font-bold">Mapa skarbów w kolumnach</h1>
      <div className="my-3 flex flex-wrap items-center gap-2">
        <button
          type="button"
          onClick={() => setPlaced((n) => Math.min(n + 1, PINS.length))}
          disabled={!next}
          className="rounded-full bg-red-600 px-4 py-2 font-semibold text-white disabled:bg-zinc-400"
        >
          Dołóż pin
        </button>
        <button type="button" onClick={() => setPlaced(0)} className="rounded-full bg-zinc-200 px-4 py-2">
          Od nowa
        </button>
        <label className="flex items-center gap-2">
          Kolumny:
          <select value={columnCount} onChange={(e) => setColumnCount(Number(e.target.value))} className="rounded border border-zinc-300 px-2 py-1">
            <option value={2}>2 (telefon)</option>
            <option value={3}>3 (od 768 px)</option>
            <option value={4}>4 (od 1024 px)</option>
          </select>
        </label>
      </div>
      <p role="status" className="mb-3 text-sm">
        {next
          ? 'Następny pin "' + next.title + '" (proporcja ' + (next.height / next.width).toFixed(2) + ') trafi do kolumny ' + (shortest + 1) + '.'
          : 'Wszystkie piny są już na mapie.'}
      </p>
      <div className="flex items-start gap-3">
        {columns.map((column, c) => (
          <div key={c} className="min-w-0 flex-1">
            <p className={c === shortest ? 'mb-1 text-xs font-bold text-red-700' : 'mb-1 text-xs text-zinc-500'}>
              Kolumna {c + 1}: {heights[c].toFixed(2)}
              {c === shortest && next ? ' (najniższa)' : ''}
            </p>
            <ul className="flex flex-col gap-2">
              {column.map((pin) => (
                <li
                  key={pin.id}
                  style={{ aspectRatio: pin.width + ' / ' + pin.height, backgroundColor: pin.dominantColor }}
                  className={pin.id === lastId ? 'flex items-end rounded-xl p-2 ring-4 ring-red-600' : 'flex items-end rounded-xl p-2'}
                >
                  <span className="rounded bg-black/50 px-1 text-xs text-white">{pin.title}</span>
                </li>
              ))}
            </ul>
          </div>
        ))}
      </div>
      <p className="mt-4 text-sm text-zinc-600">
        Zmień liczbę kolumn: podział liczy się od nowa z tej samej listy, bo to wynik funkcji, a nie stan.
      </p>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Podajesz Claude szkic szkice/masonry.png. Czego szkic nie powie, więc musi to stać w tekście polecenia?

  2. 2. Czym układ masonry różni się od zwykłej siatki z rzędami?

To 2 z 8 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż linię z distributePins, która znajduje numer najniższej kolumny:

  • Układanie w pionie

    Ułóż linie pętli, która rozdziela piny na kolumny:

  • Edytor kodu

    Stwórz masonry layout dla pinów

  • Układanie w poziomie

    Ułóż linię z MasonryGrid, która liczy kolumny w trakcie renderu, bez stanu:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować wywołanie z useColumnCount:

  • Edytor kodu

    Zbuduj kartę pina z hover effects

  • Układanie w pionie

    Uporządkuj, co dzieje się w PinFeed, gdy widz zbliża się do końca listy:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować linię, która każe obserwatorowi pilnować wartownika:

  • Układanie w poziomie

    Ułóż linię, która dokleja nowe piny do najświeższej listy, a nie do starej wartości z domknięcia:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować obliczenie najniższej wysokości kolumn:

  • Układanie w pionie

    Uporządkuj warstwy PinCard od spodu (tło) do wierzchu:

  1. PytanieQuiz: Szkic jako wejście
  2. PytanieQuiz: Układ masonry
  3. PytanieQuiz: Pola width i height pinu
  4. Ułóż w kolejnościSortowanie: Numer najniższej kolumny
  5. Ułóż w kolejnościSortowanie: Pętla distributePins
  6. Zadanie z kodemPraktyka: Masonry grid
  7. PytanieQuiz: Proporcja zamiast pikseli
  8. PytanieQuiz: Nakładka karty pinu
  9. Ułóż w kolejnościSortowanie: Podział liczony w renderze
  10. Kliknij w kolejnościBudowanie: Liczba kolumn bez błędu hydratacji
  11. Zadanie z kodemPraktyka: Pin card
  12. PytanieQuiz: Wartownik nieskończonego przewijania
  13. Ułóż w kolejnościSortowanie: Dociąganie strony pinów
  14. Kliknij w kolejnościBudowanie: observer.observe(sentinel)
  15. PytanieQuiz: Stan ustawiany w trakcie renderu
  16. Ułóż w kolejnościSortowanie: Doklejanie pinów do najświeższej listy
  17. PytanieQuiz: Kolor dominujący przed pobraniem
  18. Kliknij w kolejnościBudowanie: Math.min dla kolumn
  19. Ułóż w kolejnościSortowanie: Warstwy karty pinu

Przydatne artykuły