İçeriğe geç
Reusable List

Referans / Yapı Taşları

Yapı Taşları

Şablonlar, bu yapı taşlarının dört farklı katmanda nasıl bir araya geldiğini gösterir. Bu sayfa ise tersinden bakar: src/features/list-page/ içindeki her ortak yapı taşını tek tek; ne render ettiğini, Server Component, Client Component veya client hook olup olmadığını ve hangi örneklerde kullanıldığını gösterir.

TL;DR

Ortak liste sayfası çekirdeği, tekrar eden davranışları kapsar: tipli URL ayrıştırma ve serileştirme, arama ve filtre kontrolleri, sıralama, görünüm değiştirme, sonuç düzenleri, sayfalama, etkin filtre bağlantıları, seçim davranışları ve sistem durumları.

Her özellik, kendine özgü kararları bu çekirdeğin dışında tutar: kayıt türleri, mock veriler, filtre seçenekleri, sorgu servisleri, araç çubuğu düzeni, satırlar, kartlar, durum gösterimleri ve toplu işlem davranışları. Yeni örnekler, ortak yapı taşlarının iç uygulamasını değiştirmeden onları kullanır.

Yapı ve Sonuçlar

Liste sayfasının temel düzenini oluşturan, kayıtları render eden ve metadata'yı biçimlendiren yapı taşları. Bunların hiçbiri kaydın kendi iş mantığını bilmek zorunda değildir.

  • ListPageShellShared Component

    Sayfa düzeyindeki temel düzeni sağlar: başlık ve açıklama alanı, sayfanın kendi araç çubuğu için bir alan, sonuçlar için children ve isteğe bağlı sayfalama alanı. Kendisi "use client" kullanmadığı için hem Server Component olan page.tsx'ten hem de Client Component olan error.tsx'ten render edilebilir.

    tüm örneklerin page.tsx, loading.tsx ve error.tsx dosyaları (Bileşenler, Sorunlar, Dağıtımlar, Paketler) tarafından kullanılır.

  • ResultsViewServer Component

    Bir veri kümesini liste veya ızgara görünümünde render eder. Öğe türünden bağımsızdır; her kaydın nasıl gösterileceğini renderListItem ve renderGridItem üzerinden ilgili sayfaya bırakır.

    Bileşenler, Dağıtımlar ve Paketler'in results bileşenleri. Sorunlar ise seçilebilir kendi tablosunu kullanır; aynı responsive kırılım noktalarını korumak için dışa aktarılan RESULTS_GRID_CLASS_NAME sabitinden yararlanır. tarafından kullanılır.

  • formatRelativeTimeUniversal

    Tarih içeren bir ISO değerini (ör. "2026-08-15") bugünün tarihiyle karşılaştırıp "3g önce" veya "bugün" gibi kısa ve dile duyarlı bir etikete dönüştürür.

    Bileşenler ve Sorunlar'ın liste satırı ve grid kartı bileşenleri tarafından kullanılır.

Önizleme: araç çubuğu, iki sonuç satırı ve sayfalama alanı içeren örnek bir liste sayfası.

Sorgu ve Navigasyon

URL search parametreleri ile tipli liste durumu arasındaki ortak sınır ve bu durumu URL'ye yazan client hook.

  • Query typesUniversal

    ViewMode, SortOption, FilterOption, FilterValues, ListQueryConfig ve ParsedListQuery tüm örneklerde URL durumunu aynı yapıyla tanımlar. Yeni bir örneğin yalnızca kendi sıralama ve filtre anahtarlarını sağlaması yeterlidir.

    tüm örneklerin config, sorgu servisi ve araç çubuğu tarafından kullanılır.

  • parseListQuery / buildListQueryStringUniversal

    parseListQuery, URLSearchParams değerlerini sayfanın ListQueryConfig'ine göre ParsedListQuery nesnesine dönüştürür. buildListQueryString ise bu işlemin tersini yapar. toSearchParams ve emptyFilterValues da Server Component searchParams değerleri ve boş filtre varsayımları için aynı yapıyı destekler.

    tüm örneklerin page.tsx, route.ts ve useListQueryState kullanımları; her zaman aynı config üzerinden tarafından kullanılır.

  • useListQueryStateClient Hook

    Geçerli URL'yi useSearchParams ile okur ve setSearch, setSort, setView, setSingleFilter ve toggleMultiFilter fonksiyonlarını sunar. Her biri buildListQueryString ile oluşturulan query string'i push veya replace eder. Sayfalama bağlantıları server tarafında render edildiği için sayfalama bilinçli olarak bu hook'un dışında tutulur.

    tüm örneklerin client araç çubuğu bileşenleri tarafından kullanılır.

Önizleme: arama, sıralama ve sayfa parametrelerini içeren bir URL.

Arama, Filtreler, Sıralama ve Görünümler

Sayfaya özgü araç çubuklarında kullanılan etkileşimli kontroller. Her biri yalnızca kendi sorumlu olduğu sorgu durumu bölümünü okur ve günceller.

  • SearchFieldClient Component

    Arama simgesiyle birlikte debounce edilmiş bir metin alanı (varsayılan 300ms). Her tuş vuruşunda URL'yi güncellememek için geçici değeri kendi içinde tutar.

    tüm örneklerin araç çubuğu tarafından kullanılır.

  • SingleSelectFilterClient Component

    Tek bir değer seçilebilen ve radio group içeren dropdown filtre. Tetikleyici her zaman geçerli seçimi metin olarak gösterir.

    tüm örneklerin araç çubuğu tarafından kullanılır.

  • MultiSelectFilterClient Component

    Aynı anda birden fazla değer seçilebilen checkbox tabanlı popover filtre. Birden fazla değer seçildiğinde tetikleyicide "N seçildi" özeti gösterilir.

    Bileşenler'deki framework filtresi; şu anda tek kullanım alanı tarafından kullanılır.

  • SortMenuClient Component

    Sayfanın sıralama seçeneklerini gösteren dropdown. Sıralama anahtarından bağımsız çalışır ve aktif seçenek tetikleyicide her zaman metin olarak gösterilir.

    tüm örneklerin araç çubuğu tarafından kullanılır.

  • ViewSwitcherClient Component

    Liste ve ızgara görünümü arasında geçiş sağlayan iki seçenekli kontrol.

    tüm örneklerin araç çubuğu tarafından kullanılır.

Önizleme: arama alanı, etkin bir filtre, sıralama kontrolü ve liste/ızgara görünüm seçimi.

Sayfalama ve Etkin Filtreler

Sorgu durumunu gerçek bağlantılara dönüştüren server-rendered yapı taşları. Böylece hem sayfalama hem de filtre kaldırma işlemleri client JavaScript olmadan da çalışabilir.

  • PaginationControlsServer Component

    Numaralandırılmış sayfa bağlantıları, Önceki/Sonraki kontrolleri ve "84 içinden 1–20 gösteriliyor" gibi bir sonuç aralığı etiketi sunar. Her bağlantı sayfanın sağladığı buildHref ile oluşturulan gerçek bir Link'tir ve aktif sayfa aria-current="page" değerini korur.

    tüm örnek sayfalar tarafından kullanılır.

  • ActiveFiltersServer Component

    Sayfanın oluşturduğu ActiveFilterPill listesinden etkin her filtre için kaldırılabilir bir etiket ve "Tümünü temizle" bağlantısı render eder. Hiç filtre etkin değilse hiçbir şey göstermez.

    tüm örneklerin results bileşenleri tarafından kullanılır.

Önizleme: kaldırılabilir bir filtre etiketi ve numaralandırılmış sayfalama kontrolleri.

Seçim ve Toplu İşlemler

Yalnızca client tarafında tutulan seçim durumu ve bunu kullanan araç çubuğu. Bu durum bilinçli olarak paylaşılabilir URL durumunun dışında tutulur.

  • useSelectionClient Hook

    Kayıt id'sine göre yönetilen, yalnızca client tarafında yaşayan seçim durumu. selectedIds, selectedCount, isSelected, toggle, selectAll, removeMany ve clear fonksiyonlarını sunar. Sonuç kümesi değiştiğinde seçimi sıfırlamak için genellikle aktif sorgudan türetilen bir key ile yeniden mount edilir.

    Sorunlar; şu anda satır seçimi kullanan tek örnek tarafından kullanılır.

  • SelectionToolbarClient Component

    selectedCount sıfırdan büyük olduğunda görünür. Seçili kayıt sayısını, gerektiğinde "Bu sayfadaki N öğenin tümünü seç" işlemini ve sayfaya özgü toplu işlemler için bir actions alanını gösterir. Bir toplu işlem sürerken pending durumu seçim değişikliklerini devre dışı bırakır.

    Sorunlar tarafından kullanılır.

Önizleme: "2 seçildi" bilgisinin ve sayfaya özgü toplu işlemin yer aldığı seçim araç çubuğu.

Yüklenme, Boş, Hata ve Demo Durumları

Bir listenin karşılaşabileceği temel durumlar için ortak sunum bileşenleri ve demo sırasında bu durumların istenerek tetiklenmesini sağlayan yardımcı yapılar.

  • ListSkeletonServer Component

    Sayfanın sağladığı gridTemplateColumns ve columnCount değerlerine göre şekillenen sabit yükseklikte placeholder satırlar. Böylece yüklenme durumu gerçek satır düzenine yakın kalır ve veri geldiğinde gereksiz yerleşim kayması oluşmaz.

    tüm örneklerin loading.tsx dosyaları tarafından kullanılır.

  • ListEmptyStateServer Component

    Simge, kısa başlık, açıklama ve isteğe bağlı bir işlem gösterir. Results bileşeni "hiç veri yok" ile "bu filtrelerle sonuç yok" durumları için farklı metinler sağlayabilir.

    tüm örneklerin results bileşenleri tarafından kullanılır.

  • ListErrorStateShared Component

    Boş durum bileşenine benzer bir yapı kullanır ancak hata görünümü için biçimlendirilmiştir ve zorunlu bir işlem içerir. Bu projede işlem her zaman useDemoErrorRecovery tarafından yönetilen tekrar deneme düğmesidir. Bileşenin kendisi "use client" kullanmaz.

    tüm örneklerin error.tsx dosyaları tarafından kullanılır.

  • useDemoErrorRecoveryClient Hook

    Tüm error.tsx dosyaları tarafından kullanılır. Simüle edilmiş hatalarda ?demoState=error parametresini URL'den kaldırır; gerçek bir hata durumunda ise sayfanın retry() fonksiyonunu çağırır.

    tüm örneklerin error.tsx dosyaları tarafından kullanılır.

  • DemoState helpersUniversal

    DemoState ve parseDemoState, örnek sayfaların ve mock Route Handler'ların desteklediği ?demoState= parametresini okur: default, loading, empty veya error. Böylece sistem durumları ek bir araca gerek kalmadan doğrudan URL üzerinden görüntülenebilir. simulateLatency ise Route Handler yanıtına yapay gecikme ekler.

    tüm /api/* rotaları ve örnek page.tsx dosyaları tarafından kullanılır.

Önizleme: yüklenme iskeleti, boş sonuç durumu ve tekrar deneme alanı.

Tek config, üç kullanım noktası

Kurgusal Snapshots örneğinde aynı ListQueryConfig; Server Component, Route Handler ve useListQueryState üzerinden Client Component tarafından parseListQuery'ye aktarılır. Böylece URL'nin nasıl yorumlanacağı konusunda üç farklı uygulama oluşmaz.

src/features/snapshots-example/query-config.ts üç farklı sınırda ortak kullanılıyor
// src/app/examples/snapshots/page.tsx (Server Component)
const searchParams = toSearchParams(await props.searchParams);
const query = parseListQuery<SnapshotSortKey, SnapshotFilterKey>(
  searchParams,
  SNAPSHOT_LIST_QUERY_CONFIG,
);

// src/app/api/snapshots/route.ts (Route Handler)
const searchParams = new URL(request.url).searchParams;
const query = parseListQuery<SnapshotSortKey, SnapshotFilterKey>(
  searchParams,
  SNAPSHOT_LIST_QUERY_CONFIG,
);

// src/features/snapshots-example/snapshots-toolbar.tsx (Client Component)
const { query, setSort } = useListQueryState<
  SnapshotSortKey,
  SnapshotFilterKey
>(SNAPSHOT_LIST_QUERY_CONFIG);

Sayfaya özgü neler kalır?

Liste satırları ve grid kartları gibi render bileşenleri, sorgu servisleri, mock veriler, filtre seçenekleri ve ortak kontrolleri bir araya getiren araç çubuğu her örneğin kendi feature klasöründe tutulur. Örneğin src/features/components-example/. Bunlar hiçbir zaman ortak src/features/list-page/ çekirdeğinin içine taşınmaz. Bu sayfa yapı taşlarını tek tek gösterir; bir sayfada nasıl bir araya geldiklerini görmek için Şablonlar bölümüne bakabilirsiniz.