Treyza SDK: Ürün Kartı Yuvası

Nerede bulunur: Tema Editörü → sol panel Bileşenler sekmesi → Yapay zekayla bileşen üret → Bileşen türü: Ürün kartı. Ayrıca sağ panel Ürün sekmesi → Ürün Kartı → Özel kartlar. Kimler için: Ürün listelerindeki kartın görünümünü beş yerleşik seçeneğin ötesinde değiştirmek isteyen mağazacılar ve onlara kart yazan tasarımcılar Kısaca: Ürün kartı bir yuva bileşenidir: vitrin, ürün verisini ve sepete ekle / favori / karşılaştır gibi eylemleri size hazır verir; siz yalnız kartın nasıl göründüğünü yazarsınız. Kart Bileşen Stüdyosunda üretilir, gerçek ürünlerinizle önizlenir, Yayınla dedikten sonra Ürün Kartı ayarlarından seçilir ve isterseniz toplulukla paylaşılır.

Yuva bileşeni ne demek?

Bir sayfa bloğu (kampanya şeridi, SSS…) sayfaya eklenir ve kendi başına durur. Ürün kartı ise vitrinin zaten çizdiği bir yuvayı doldurur: kategori sayfası, arama, öne çıkanlar ve ilgili ürünler listelerinde her ürün için aynı kart onlarca kez çizilir. Bu yüzden kart:

• veri çekmez — ürün, fiyat, görsel, rozet, stok, ön sipariş ve renk varyantları props ile gelir,
• eylemleri kendisi yazmaz — sepete ekle, favori, karşılaştır ve hızlı bakış host bileşenleri olarak hazır gelir,
• sunucuda çizilir — Google kartı ilk HTML'de görür, tarayıcıda hidrasyonla canlanır,
• bir hata verirse ziyaretçi boş kutu görmez; vitrin o kart için yerleşik Klasik karta geri düşer.

PRODUCT_CARD ilk yuvadır. İleride sepet çekmecesi gibi başka yuvalar aynı mekanizmayla eklenecektir.

Kart nereden başlar?

Stüdyoda Bileşen türü olarak Ürün kartı'nı seçince iki yol açılır:

1. Resmi şablondan başla — Klasik, Minimal, Overlay, Editöryal ve Kompakt kartlar açık kaynak şablon olarak listelenir. Birine tıklayınca kopyası sizin adınıza oluşturulur ve derlenir; sonra "başlığı büyüt", "fiyatı kırmızı yap" gibi isteklerle yapay zekaya değiştirtir ya da sağ paneldeki Kod sekmesinde doğrudan yazarsınız (yazdıkça önizleme güncellenir, aşağıda). Vitrindeki yerleşik beş kart da aynı şablonlardan beslenir; yani kopyanız birebir üretimdeki koddur.
2. Yapay zekayla üret — kartı düz Türkçe tarif edin. Yapay zeka ürün kartı sözleşmesini bilir; alan uydurmaz, veriyi props'tan okur ve host düğmelerini kullanır.

Her iki yolda da kart aynı hattan geçer: kod denetimi → derleme → doğrulama kapısı (indirimli, varyantlı, paket, tükenmiş, ön siparişli, görselsiz ve çok uzun adlı ürünlerle otomatik çizim).

Önizleme, yayın ve seçim

• Canlı önizleme sağ ortadaki panelde, mağazanızın gerçek ürünleriyle çizilir. Masaüstü/mobil geçişi kart ızgarasını daraltır.
• Kodu doğrudan düzenleme: sağ paneldeki Kod sekmesi ürün kartlarında yazılabilirdir. Yazmayı bıraktıktan yaklaşık bir saniye sonra kod sunucuda hızlı yoldan derlenir (kod denetimi + tarayıcı paketi + CSS; sürüm ve doğrulama kapısı çalışmaz) ve önizleme yeniden çizilir; üstteki şerit "Önizleme güncel · N ms" der. Hatalı kod önizlemeyi bozmaz: son çalışan hâl kalır, hata Türkçe olarak kodun altında listelenir. Kaydet (Ctrl+S) kodu kalıcı olarak yazar, kalıcı derlemeyi ve doğrulama kapısını başlatır; vitrin yine yalnız yayınlanan sürümü çizer. İncelemedeki ya da toplulukta yayındaki kartın kodu kilitlidir.
• Yapay zeka turundan sonra yeni kod kalıcı derleme bitmeden aynı hızlı yolla önizlenir; derleme bitince önizleme derlenmiş sürüme geçer.
• Kart derlenince üstte Yayınla düğmesi çıkar. Yayınlamak kartı toplulukla paylaşmaz; yalnız mağazanızda seçilebilir hâle getirir. Sonraki değişiklikler yeniden yayınlanana kadar vitrine gitmez; vitrin her zaman en son yayınlanan sürümü çizer.
• Mağaza kartı yap düğmesi, Ürün Kartı ayarındaki seçimi bu karta çevirir. Aynı işi sağ paneldeki Ürün → Ürün Kartı → Özel kartlar bölümünden de yapabilirsiniz; listede kendi yayınladığınız kartlar ve topluluktan kurduklarınız görünür.
• Blok bazında da seçilebilir: Ürün Listesi, Kürasyon Şeridi, Kargo Eşiği İlerlemesi (öneri destekli görünüm) ve Sonuç Yok Durumu (öneri ürünlü görünüm) bloklarının Kart tipi ayarında Mağaza ayarı seçeneği Ürün Kartı ayarını izler; özel kartlarınız yerleşik tiplerin altında listelenir. Sepet sayfasındaki öneri ürünleri her zaman mağaza kartını kullanır.
• Yayından kaldır düğmesi kartı mağazada seçilemez yapar; kod ve sürümler silinmez.
• Sürümler (Durum sekmesi): her başarılı derleme yeni bir sürümdür; mağazada yayındaki sürüm yayında, toplulukta onaylı olan onaylı rozetiyle işaretlenir. Bu sürüme dön kartı seçtiğiniz sürümün koduna ve paketine yeni bir sürüm numarasıyla döndürür; yayın değişmez, dönülen sürümü vitrine almak için Yayınla dersiniz. Şu anki, yayındaki ve onaylı sürüm silinemez; diğerlerini çöp simgesiyle silebilirsiniz.
• Yatay kartlar: export const treyza = { contract: 1, slot: "PRODUCT_CARD", wide: true } ilan eden kart (Kompakt şablon gibi) vitrin ızgarasında dar sütunla, geniş ekranda en çok dört sütunla çizilir; Özel kartlar listesinde "Yatay" rozeti görünür.
• Kartı Bileşenlerim sayfasında "Ürün kartı" rozetiyle görürsünüz.

Yayından kaldırılmış ya da silinmiş bir kart seçili kalırsa vitrin sessizce Klasik karta döner; Ürün Kartı ayarı ve blok ayarları bu durumu sarı bir uyarıyla gösterir.

Toplulukla paylaşma ve kurma

Kartı Durum sekmesinden Topluluğa gönder ile paylaşırsınız; Bileşeni Toplulukla Paylaşma sayfasındaki onay kapısı ve kilitler aynen geçerlidir. Başka bir mağazacı kartınızı Topluluk sekmesinde görüp Kur dediğinde kart o mağazanın Özel kartlar listesine düşer; kurulan kart her zaman onaylanan sürümde çizilir, siz sonradan değiştirseniz bile.

Kartın aldığı veri — ProductCardProps

Kart @treyza/sdk/slots/product-card girişinden tipleri alan tek argümanlı bir React bileşenidir:

"use client";
import type { ProductCardMeta, ProductCardProps } from "@treyza/sdk/slots/product-card";

export const treyza: ProductCardMeta = { contract: 1, slot: "PRODUCT_CARD" };

export default function BenimKartim({ product, view, settings, state, actions, labels, ui, format, priority }: ProductCardProps) {
    const { Link, Media, AddToCartButton, CompareToggle, FavoriteToggle, ColorSwatches, CardBadgeLayer } = ui;
    return (
        <div className="group relative flex flex-col overflow-hidden rounded-xl border bg-card">
            <Link href={view.url}>
                <Media>
                    <CardBadgeLayer
                        discountLabel={view.discountLabel}
                        outOfStockLabel={view.isOutOfStock ? labels.outOfStock : null}
                        preOrderLabel={product.isPreOrder && !view.isOutOfStock ? labels.preOrder : null}
                        badges={product.badges}
                    />
                </Media>
            </Link>
            <FavoriteToggle className="absolute right-2.5 top-2.5" />
            <div className="flex flex-col gap-1.5 p-3">
                <Link href={view.url} className="line-clamp-2 text-sm font-medium">{product.name}</Link>
                <span className="text-base font-bold">{view.priceLabel}</span>
                {view.listPriceLabel && <span className="text-xs line-through text-muted-foreground">{view.listPriceLabel}</span>}
                <AddToCartButton className="w-full" />
                <CompareToggle className="w-full" />
            </div>
        </div>
    );
}

Host bileşenleri — ui.*

Sınırlar

• İzinli import'lar: @treyza/sdk/slots/product-card, @treyza/sdk/ui, @treyza/sdk/primitives, @treyza/sdk/lib/utils, react, @tabler/icons-react (ikonlar tek tek adıyla), clsx, tailwind-merge.
• Yasak: @treyza/sdk/data (kart veri çekmez), fetch ve her türlü ağ erişimi, window / document / localStorage / location, eval, dangerouslySetInnerHTML, dinamik import(), constructor / __proto__ / prototype erişimi. Kod denetimi bunları derlemeden önce reddeder ve nedenini Türkçe söyler.
• configSchema kullanılmaz; kartın ayarları mağazanın Ürün Kartı ayarlarından gelir.
• Sabit renk yerine tema jetonlarını kullanın (bg-card, text-foreground, text-muted-foreground, bg-primary…); kart mağazanın renk ve köşe yuvarlaklığı ayarlarına böyle uyar.
• Kart sunucuda çizildiği için ilk çizimde tarih, rastgele değer ve DOM erişimi kullanmayın.
• Üzerine gelince açılan katmanlar mobilde yoktur: masaüstü katmanını hidden md:block, mobil düğmeleri md:hidden içinde ayrı çizin.
• Her kartta bir CompareToggle ve bir FavoriteToggle bulunmalı; kapalıyken kendileri gizlenir.

Sık sorulanlar

Kartımı değiştirdim, vitrinde görünmüyor. Kart yeniden derlenmiş olabilir ama yayınlanmamıştır; üst şeritteki Yayınla düğmesine basın. Vitrin en son yayınlanan sürümü çizer. Kod sekmesinde yazdıklarınız ise önce Kaydet ile kalıcı olur; kaydedilmemiş kod yalnız stüdyo önizlemesinde görünür.

Kod sekmesinde yazdım, önizleme neden güncellenmedi? Kodun altındaki hata listesine bakın: kod denetiminden geçmeyen ya da derlenemeyen kod önizlemeyi değiştirmez, son çalışan hâl kalır. Hata çözülünce önizleme kendiliğinden yenilenir.

Resmi şablonlar değişir mi? Hayır; Klasik…Kompakt şablonlar paketten okunur ve her zaman kopyalanır. Kopyanızı ne kadar değiştirirseniz değiştirin şablon aynı kalır, yeni kopya yine özgün koddan açılır.

Kart tek bir üründe hata verirse ne olur? Yalnız o ürün için yerleşik Klasik kart çizilir, listenin kalanı etkilenmez; hata mağaza günlüğüne düşer.

Topluluktan kurduğum kart güncellenir mi? Hayır; kurulan kart yazarının onaylanan sürümünde kalır. Yeni sürüm için yazarın yeniden göndermesi ve onay alması gerekir.