İçeriğe geç
Reusable List

Referans / Mimari

Mimari

URL tabanlı durum yönetimi, server-side sonuçlar, odaklanmış client kontrolleri ve sayfaya özgü mantığı bir araya getiren liste sayfası mimarisi.

TL;DR

URL; arama, filtreler, sıralama, görünüm ve sayfalama için tek kaynaktır. Server Component'ler bu durumu ayrıştırır, sayfaya özgü sorgu servisini çağırır ve sonuçları render eder. Client Component'ler ise yalnızca URL'yi günceller veya geçici etkileşim durumlarını yönetir.

Her sayfa ve ona ait mock Route Handler aynı sorgu yapılandırmasını ve sorgu servisini kullanır. Seçim bilinçli bir istisnadır: paylaşılabilir liste durumunun değil, geçici UI durumunun bir parçası olduğu için client tarafında yerel kalır.

İstekten ekrana veri akışı

Bir örnek sayfa (page.tsx) liste durumunu URL'den alır ve sonuçları server tarafında render etmeden önce aşağıdaki ortak akıştan geçirir.

  1. URL Search Params

    Arama, filtreler, sıralama, görünüm ve sayfa bilgisi query string içinde tutulur.

  2. Ortak Sorgu Ayrıştırıcı

    parseListQuery(), ham parametreleri tipli ve varsayılan değerleri tanımlanmış tek bir sorgu nesnesine dönüştürür.

  3. Sayfaya Özgü Sorgu Servisi

    Her örneğin kendi query-service.ts dosyası kayıtları filtreler, sıralar ve sayfalara ayırır.

  4. Server'da Render Edilen Sonuçlar

    Server Component; kayıtları, sayfalama bağlantılarını ve etkin filtre bağlantılarını render eder.

Client etkileşim akışı

  1. Arama / Filtreler / Sıralama / Görünüm

    Sayfaya özgü araç çubuğu geçerli sorgu durumunu URL'den okur.

  2. useListQueryState

    Aynı ayrıştırıcı ve yapılandırmayı kullanarak bir sonraki query string'i oluşturur.

  3. Güncellenmiş URL

    Yeni URL'ye geçildiğinde server akışı güncel sorguyla yeniden çalışır.

Bu akış, diyagramın başındaki URL Search Params'ı günceller.

  • URL, listenin paylaşılabilir durumunun tek kaynağıdır.
  • Aynı sorgu yapılandırması sayfa, Route Handler ve client araç çubuğu tarafından ortak kullanılır.
  • Arama geçerli URL girdisini günceller; filtre, sıralama, görünüm ve sayfalama değişiklikleri ise tarayıcı geçmişine yeni bir giriş ekler.
  • Filtreleme her zaman sıralamadan önce, sıralama da sayfalamadan önce çalışır.

Server ve client sınırları

Liste sayfasının büyük bölümü server tarafında render edilir. Client Component'ler yalnızca kullanıcı etkileşiminin gerektiği noktalarda devreye girer.

Server tarafı

  • Arama parametrelerini ayrıştır
  • Mock veriyi sorgula
  • Geçersiz sayfaları yönlendir
  • Sonuçları render et
  • Sayfalama bağlantılarını render et
  • Etkin filtreleri kaldıran bağlantıları render et

Client tarafı

  • Arama alanındaki geçici değer
  • Filtre, sıralama ve görünüm kontrolleri
  • Seçim durumu
  • Toplu işlemlerin bekleme durumu
  • Hata sonrası kullanıcı etkileşimi

Client Component'ler yalnızca etkileşim sınırlarında kalır; liste verisi tarayıcı tarafından yeniden fetch edilmez.

Ortak çekirdek ve sayfaya özgü kod

Her örnek aynı ortak yapı taşlarını kullanır ve bunları kendi sayfaya özgü koduyla bir araya getirir. Ortak çekirdek hiçbir zaman çatallanmaz veya doğrudan değiştirilmez.

Ortak liste sayfası çekirdeği

src/features/list-page/
  • Sorgu ayrıştırma ve serileştirme
  • Arama ve filtre kontrolleri
  • Sıralama ve görünüm değiştirme
  • Sonuç düzeni
  • Sayfalama
  • Etkin filtreler
  • Seçim davranışları
  • Yüklenme, boş ve hata durumları

Sayfaya özgü yapı

src/features/issues-example/
  • Türler ve filtre seçenekleri
  • Mock kayıtlar
  • Sorgu servisi
  • Araç çubuğu düzeni
  • Liste satırları ve ızgara kartları
  • Durum ve sayfaya özgü sunum
  • Gerektiğinde toplu işlem davranışları

Sayfaya özgü özellikler ortak çekirdeği yalnızca dışa açtığı yapı taşları üzerinden kullanır; çekirdeği doğrudan değiştirmez.

Veri akışı

Bir sayfa isteği altı adımdan geçer. Ortadaki dört adım, sayfanın ve ilgili Route Handler'ın ortak kullandığı sorgu servisinde çalışır. Son adımda ise yalnızca sayfa, istenen sayfa ile geçerli sonuç sayfasını karşılaştırır ve gerekirse yönlendirme yapar.

  1. URL durumunu ayrıştır ve normalleştir
  2. Kayıtları ara ve filtrele
  3. Filtrelenmiş sonuçları sırala
  4. İstenen sayfayı geçerli aralığa sınırla
  5. Sıralanmış sonuçları sayfalara ayır ve geçerli sayfayı döndür
  6. Geçerli sayfayı istenen sayfayla karşılaştır, farklıysa yönlendir

Sayfa ve API aynı sorgu mantığını kullanır

Bir örnek sayfa ile ona ait mock Route Handler, aynı sorgu mantığının iki ayrı kopyası değildir. İkisi de aynı sorgu servisini kullanan iki farklı giriş noktasıdır.

page.tsx

Server Component

route.ts

Route Handler

query-service.ts

Mock veri kümesini filtreler, sıralar ve sayfalara ayırır.

Sayfa kendi Route Handler'ına fetch isteği atmaz. Her iki giriş noktası da aynı sorgu fonksiyonunu doğrudan kullanır.

Seçim bilinçli bir istisnadır

Sorunlar (Issues), satır seçimine sahip tek örnektir ve bu davranış bilinçli olarak URL tabanlı durum yönetiminin dışında tutulur.

  • Seçim, URL'de tutulmayan yerel bir client durumudur.
  • Arama, filtreler, sıralama veya sayfa değiştiğinde sıfırlanır; liste ve ızgara görünümü arasında geçiş yapmak seçimi sıfırlamaz.
  • Tümünü seç işlemi yalnızca o anda sayfada görünen sorunları kapsar.
  • Başarılı bir toplu durum güncellemesi, tüm veriyi yeniden fetch etmeden yerel olarak uygulanır; server tarafında kalıcı olarak saklanmaz.
  • Güncelleme başarısız olursa kullanıcı tekrar deneyebilsin diye mevcut seçim korunur.