|
|
@@ -1,15 +1,14 @@
|
|
|
-# NCore UI Kit & Global Coding Style Guidelines
|
|
|
-*Bu doküman, projedeki kodlama alışkanlıkları ve mimari standartların tam bir dökümüdür. Sistem tarafından otomatik analiz edilerek çıkartılmıştır.*
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
## 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.
|
|
|
-- **Stil İzolasyonu (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 ve orada barındırılı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. Tip (Type) ve TypeScript Standartları
|
|
|
+## 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:
|
|
|
```typescript
|
|
|
@@ -18,12 +17,12 @@ export type {
|
|
|
};
|
|
|
```
|
|
|
|
|
|
-## 3. Girintiler ve ESLint Multiline (Çok Satırlılık) Kuralları
|
|
|
+## 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 de SIKI BİR ŞEKİLDE geçerlidir:
|
|
|
+- **Array & Hook Destructuring:** Array elemanları da alt alta dizilir. Bu kural React Hook'ları için SIKI BİR ŞEKİLDE geçerlidir:
|
|
|
```typescript
|
|
|
const [
|
|
|
status,
|
|
|
@@ -33,12 +32,12 @@ export type {
|
|
|
- **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.
|
|
|
|
|
|
-## 4. İmza Kuralı: "Uzundan Kısaya" (Longest to Shortest) Sıralaması
|
|
|
+## 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.
|
|
|
|
|
|
-## 5. Akış Kontrolü ve Fonksiyonellik (Fail Fast)
|
|
|
+## 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)`).
|
|
|
+- **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.
|
|
|
```typescript
|
|
|
if(!condition) {
|
|
|
@@ -47,13 +46,35 @@ if(!condition) {
|
|
|
```
|
|
|
- **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.
|
|
|
|
|
|
-## 6. Fonksiyonel Bileşenler ve Local Helpers
|
|
|
+## 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.
|
|
|
|
|
|
-## 7. NCore UI Kit Zorunlulukları
|
|
|
-- Tasarımsal ölçüler ve renkler elle (hardcode) YAZILMAZ.
|
|
|
-- Her zaman `NCoreUIKitTheme.useContext()` kullanılarak `spaces`, `colors`, `radiuses` ve `configs` (örn: `configs.headerSpace`) objeleri çağrılır ve değerler buradan alınır.
|
|
|
-- Metinler (string) UI kısmına asla ham haliyle yazılmaz. `NCoreUIKitLocalize.useContext()` çağrılarak elde edilen `localize("key")` fonksiyonu ile kullanılır.
|
|
|
-- CSS-in-JS yazılırken, sadece Web ortamına özel (cross-platform olmayan) stiller uygulanacağı zaman mutlaka kütüphanenin sağladığı `webStyle` fonksiyonu kullanılır.
|
|
|
+## 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.
|
