ncore-coding-style/AGENTS.md

1. Mimari ve Klasörleme (Index Pattern & Directory Structure)

• Klasörleme: Havada uçuşan bağımsız bileşen dosyaları (Örn: Header.tsx, Home.tsx) kullanılmaz. Her yeni özellik, sayfa veya bileşen kendi ismini taşıyan bir klasör içine açılır.
• Index Pattern: İlgili modülün asıl kod dosyası istisnasız index.tsx (veya index.ts) ismini alır.
• Sayfa İçi Alt Mimariler (Views Architecture): Büyük sayfalar (örneğin Home) alt bölümlere ayrılırken doğrudan aynı dizinde tutulmaz. Bunun yerine ilgili sayfanın içine bir views klasörü açılır (örn. src/pages/home/views) ve içindeki her alt parça (hero, about vs.) yine kendi klasörüne ve kendi index.tsx dosyasına sahip olur.

2. Stil Yönetimi (Style Isolation)

• Bir modüle/sayfaya ait stiller ASLA ana dosyaya veya global bir dosyaya yazılmaz. Doğrudan o modülün klasöründe stylesheet.ts isminde bir dosya açılır.
• StyleSheet.create Kullanımı: Stiller useStyles gibi ekstra bir hook ile değil, doğrudan React Native'in StyleSheet.create({ container: { ... } }) metodu kullanılarak oluşturulur ve export default stylesheet; olarak dışa aktarılır. Bileşen içinde import stylesheet from "./stylesheet"; şeklinde kullanılır.
• CSS-in-JS (webStyle): Platforma özgü (Web) spesifik özellikler ekleneceğinde (userSelect, backdropFilter gibi) kesinlikle webStyle({ ... }) yardımcı fonksiyonu kullanılır.

3. Tip (Type) ve TypeScript Standartları

• Tekil İsimlendirme: Bir modüle ait TypeScript tür dosyaları oluşturulurken çoğul (types.ts) yerine her zaman tekil olarak type.ts kullanılır.

• Type Export Syntax (as default): Tipleri dışarı varsayılan (default) olarak aktarırken export default TypeName; KULLANILMAZ. Bunun yerine "multiline" kuralına sadık kalınarak süslü parantezler içinde aktarılır:

  export type {
  TypeName as default
  };
  

4. Girintiler ve ESLint Multiline (Çok Satırlılık) Kuralları

• Genel Boşluk (Indentation): Her yerde istisnasız 4 boşluk (space) kullanılır. Tab tuşu kullanılmaz.
• Dosya Sonu ve Semicolon: Dosyaların sonunda her zaman boş bir satır bırakılır (eol-last). Satır sonlarında noktalı virgül (;) zorunludur (semi: always).
• Imports & Exports: İçe ve dışa aktarmalarda süslü parantez { açıldıktan sonra her bir eleman kesinlikle alt alta yeni satırlara yazılır.
• Object Properties & Destructuring: Obje tanımlarında ve özellikleri ayrıştırırken (destructuring) her özellik ayrı bir satırda yer almalıdır.

• Array & Hook Destructuring: Array elemanları da alt alta dizilir. Bu kural React Hook'ları için SIKI BİR ŞEKİLDE geçerlidir:

  const [
      status,
      setStatus
  ] = useState(false);
  

• JSX Attributes: Bileşenlere geçirilen property'ler (props) asla tek satıra sıkıştırılmaz, her biri ayrı bir satıra yazılır ve kapanış simgesi (>) hizalı şekilde yeni satıra atılır.

• Render Props / Callback Parametreleri: Fonksiyonel proplarda (icon={({ color, size }) => ...}) parametreler destructure ediliyorsa onlar da mutlaka alt alta (yeni satırda) yazılır.

5. İmza Kuralı: "Uzundan Kısaya" (Longest to Shortest) Sıralaması

• Kod içinde yazılan içe aktarmalar (imports), obje özellikleri, değişken tanımlamaları, argümanlar ve props'lar sıralanırken aksi bir iş mantığı gerekmedikçe her zaman karakter uzunluğu en uzun olandan en kısa olana (descending length order) doğru sıralanır.

6. Akış Kontrolü ve Fonksiyonellik (Fail Fast)

• Fail Fast (Hızlı Dönüş): Bir fonksiyondan olabildiğince erken çıkış yapmak (early return) esastır. Gereksiz yere else blokları uzatılmaz, iç içe (nested) if döngülerinden kaçınılır.
• if Kullanımı: if ifadesi ile açılış parantezi ( arasında asla boşluk bırakılmaz (if(kosul)).

• Süslü parantez { hemen aynı satırın sonunda, kendisinden önce sadece bir adet boşluk bırakılarak açılır.

  if(!condition) {
  return;
  }
  

• Export Default Bitişikliği: Dosya sonlarındaki export default ifadesinden önce boş bir satır (enter) KESİNLİKLE bırakılmaz. Hemen önceki fonksiyonun veya bloğun kapanışına (}) bitişik olarak yazılır.

7. Fonksiyonel Bileşenler ve Local Helpers

• Arrow Functions: React bileşenleri arrow function ile (const Home = () => { ... }) oluşturulur.
• Render Fonksiyonlarına Parçalama: İç içe çok uzun JSX ağaçları yazmak yerine; bileşen içerisinde const renderHero = () => { return <Hero/>; }; gibi küçük okuma fonksiyonları yazılıp ana return içinde çağrılır.
• Local Helper Modülleri: Sadece o dosya içinde kullanılacak küçük yardımcı bileşenlere en üstte Custom... ön eki verilir (Örn: CustomHomeIcon, CustomFooter) ve böylece ana yapı çok daha sadeleştirilir.

8. Tema (Theme) Yapısı, NCore Hook'ları ve Theme-First İlkesi

• Theme-First İlkesi: UI kodlanırken önce temaya (NCoreUIKitTheme) bakılır. Temada tanımlı bir renk, boşluk (space) veya radius varsa KESİNLİKLE temadan alınarak kullanılır. Sadece ve sadece temada o amaca uygun bir değer yoksa custom/hardcode (elle yazım) yapılabilir.
• colors Objeleri:
  • colors.system: Sistem overlay durumları (hover, pressed vb.) ve state (success, warning) arkaplanları.
  • colors.content: UI elementleri. Örn: colors.content.text.high, colors.content.icon.mid, colors.content.container.subtle veya colors.content.border.emphasized.
  • colors.project: Projeye özel isimlendirilmiş hex renkleri (Örn: colors.project.heroWhite, colors.project.menuTitle, colors.project.switcherGlassBackground).
• spaces (Boşluklar): spaces.spacingXs, spaces.spacingSm, spaces.spacingMd, spaces.spacingLg, spaces.spacingXl değerleri padding ve margin için kullanılır.
• radiuses (Köşe Yuvarlama): radiuses.full, radiuses.soft.md, radiuses.sharp.sm gibi yuvarlamalar kullanılır.
• configs: Global ayarlara erişim. (Örn: configs.headerSpace).
• Lokalizasyon: NCoreUIKitLocalize.useContext() çağrılarak elde edilen localize("key") fonksiyonu kullanılır. Stringler UI kısmına asla ham yazılmaz.

9. NCore Bileşen (Component) Listesi ve Amaçları

NCore bileşenleri ncore-ui-kit'ten import edilir ve projenin iskeletini oluşturur:

• PageContainer: Ana sayfa/görünüm kapsayıcısı. isScrollable, isCustomPadding, scrollViewStyle, scrollViewProps özelliklerini yöneterek tüm sayfayı sarmalar.
• MainHeader: Navbar/Header bileşeni. Stack navigator'u sarmalayarak (renderRight ile aksiyon butonu ekleyerek) global ve yapışkan (isWorkWithSticky) üst menüyü kurar.
• NCoreUIKitMenu: Menü ve drawer kontrolleri için mantık aracı. NCoreUIKitMenu.load({ ... }) ile başlatılır, NCoreUIKitMenu.open({ id: "main-menu" }) ile global state'den çağrılır.
• Text: Kütüphanenin standart tipografik kurallarını (örn: variant="heroTitle", variant="bodyMediumSize") okur ve metinleri customColor={colors.project.heroWhite} şeklinde boyar.
• HighlightButton: Üzerine gelindiğinde veya tıklandığında vurgu alan (Hover, pressed state) CTA (Call-to-Action) butonu. spreadBehaviour, customTextColor, isLoading özellikleri alır.
• Button: Normal eylem butonu. icon render prop'u ile fonksiyonel component olarak icon içeriği alabilir.
• ThemeSwitcher & LocaleSwitcher: Kütüphane içinden çağrılan hazır aydınlık/karanlık mod veya dil geçiş butonlarıdır.
• SiteLogo: Başlık veya menü için optimize edilmiş resimli logo gösterici.
• Seperator: Arayüzdeki elemanları ayırmak için kullanılan dikey veya yatay standart ayırıcı çizgidir.

10. Agent Geliştirme Süreci Kriterleri (Post-Process Rules)

Bu kurallar sadece Front-End projeleri için geçerlidir, Back-End bağımsız değerlendirilir.

• Lint ve Type-Check Zorunluluğu: Agent, front-end projesinde kod bazlı herhangi bir süreç/değişiklik işlemini bitirdikten hemen sonra OTO KONTROL amacıyla terminalde yarn lint ve yarn type-check komutlarını çalıştıracaktır.
• Hata Giderme (Fixing): Çalıştırılan bu komutlar sonucunda bir hata dönüyorsa, Agent işlemi tamamladığını bildirmeden önce bu hataları (kullanıcıya sormadan) çözmekle ve düzeltmekle yükümlüdür.