@appaflytech/zeyrek-ai-mcp 0.0.28 → 0.0.31

package/dist/resources/guides/mobile-layout.md

@@ -0,0 +1,193 @@
+# Mobil mizanpaj — uygulamanın her yeri tek dil
+
+Bir mobil ekran kurmadan önce bunu okuyun. Buradaki kurallar zevk meselesi değildir, **ölçülür**:
+
+- **Doğru varsayılan.** Gateway iskeleti kendisi doğru kurar (`mobile_app_create`, `page_create`, yeni
+  düğümlerin boşluğu).
+- **Yazımda uyarı.** Yazım yanıtında sözleşme dışı durum `MOB-015…021` olarak gelir (`layoutWarnings`).
+- **Çizimde ölçüm.** `page_screenshot({ layoutReport: true })` sonucu sayıyla ölçer (`layoutSummary.alignment`).
+
+Temel mobil bilgi (flex-only yerleşim, tipli stil, gezinme, adımlar) için `platform_guide('mobile')`.
+Altın örnek: `ngapps://examples/mobile-form-screen`.
+
+## Sözleşme
+
+Birim dp. Ölçek **4 · 8 · 16 · 24 · 32**. `gap` jetonları `small` 8, `medium` 16, `large` 24.
+
+| # | Konu | Kural | Bulgu |
+|---|---|---|---|
+| S1 | Üst güvenli alan | Tek yerde. Kabuklu uygulamada kabukta (`safe-area` `edges: 'top'` içinde app-bar). Kabuksuz sayfada ilk öğe `safe-area` `top`. Sayfa kabuğun payını ikinci kez vermez | MOB-015 |
+| S2 | Alt güvenli alan | Formun gönder düğmesi akışta, formun sonunda durur. Ekrana sabit alt eylem gerekiyorsa `floating-container` (`respectSafeArea`) kullanılır, ayrıntısı §Bileşen dizgisi'nde. Akışın sonunda pay gerekiyorsa `safe-area` `bottom` (`all` değil) | — |
+| S3 | Kaydırma | Sayfa kökü kaydırır, `size: 'shrink'`. `scroll-view` yalnız gerekçeyle; iç içe dikey kaydırıcı yok | MOB-016 |
+| S4 | Ekran kenarı | Yatayda ve üstte **16**, tek yerde. Kabuklu sayfada slot'un margin'i verir. Kabuksuz sayfada yatayı kökün padding'i verir; üstteki 16, tepedeki `safe-area`'dan sonraki `gap`tir. Bileşenlere yazılmaz | ölçüm `gutter` |
+| S5 | Aralık | Kardeşler arası boşluk yalnız ebeveynin `gap`'i; çocuklar `marginType: 'none'`. Bölümler arası `large`, bölüm içi alanlar `medium`, satır içi öğeler `small` | MOB-019, MOB-021 |
+| S6 | Saydam sarmalayıcı | Yalnız davranış ekleyen kap (`tooltip`, zeminsiz grup kabı) içeriği içeri itmez: `paddingType: 'none'`, `marginType: 'none'`, `widthType: 'fill'` | MOB-019 |
+| S7 | Yüzey | Görünen grup (kart) iç boşluğu 16, yarıçap `lg`, 1 dp kenarlık ya da zemin (ikisi birden değil). Yüzeyin içeriği bilerek içeride durur | MOB-021 |
+| S8 | Genişlik | Tam genişlik öğesi (alan, birincil düğme, yüzey) `widthType: 'fill'`. Aynı sütundaki kardeşlerin sol ve sağ kenarı eşittir | MOB-019, MOB-020 |
+| S9 | Kap yönü | Dikey grup `direction: 'column'` + `horizontalAlign: 'stretch'`. **Yönü yazılmamış container/form satırdır.** Satır yalnız gerçekten yan yana dizilen öğeler için | MOB-020 |
+| S10 | Bileşen içi | Alan yüksekliği, iç boşluk, etiket aralığı ve yarıçap temadan (`--ng-form-*`) gelir; alanlara padding ya da yarıçap yazılmaz | — |
+| S11 | Yarıçap, renk, yazı | Yarıçap ölçek adıyla (`sm`, `md`, `lg`, `pill`), renk tanımlı jetonla, yazı boyu `text`'in `type` seviyesiyle (`h1`…`h4`, `p`, `small`, `label`). Ham px yok | MOB-021 |
+| S12 | App-bar | Ekranda tek app-bar, ilk çizilen öğe. Kabuk veriyorsa sayfa eklemez; başlık kabuğun app-bar'ına bağlanır | MOB-017 |
+| S13 | Boş kap | Çalışma anında boş kalan kap bırakılmaz (tepedeki `safe-area` payı hariç) | MOB-018 |
+
+## İskelet ağaçları
+
+Aşağıdaki iskeleti `mobile_app_create` ile mobil `page_create` kendisi kurar. Elle kuruyorsanız bu biçimi
+kullanın.
+
+**Kabuk (layout).** `shell_root` düz bir `container`'dır. Padding tipi yazılmazsa runtime ona 10 dp verir ve
+app-bar kenardan kopar.
+
+```
+container  shell_root   direction:column  gap:none  size:shrink  appearance.paddingType:none  heightType:fill
+├─ safe-area  edges:top
+│  └─ app-bar  (başlık, leading, menuTarget)
+├─ slot       appearance.marginType:custom  marginValues:{ top:16, right:16, bottom:0, left:16 }  heightType:fill
+└─ drawer     (çekmeceli kabukta)
+```
+
+**Kabuklu sayfa.** Pay ve kenar boşluğu kabuktan gelir.
+
+```
+container  page_container  direction:column  horizontalAlign:stretch  size:shrink  gap:medium  paddingType:none
+└─ … içerik
+```
+
+**Kabuksuz sayfa** (giriş, karşılama, izin). `isWrapper` yalnız margin'i sıfırlar, kökün padding'i çizilir.
+
+```
+container  page_container  direction:column  horizontalAlign:stretch  size:shrink  gap:medium
+           appearance.paddingType:custom  paddingValues:{ top:0, right:16, bottom:0, left:16 }
+├─ safe-area  edges:top     (boş: durum çubuğu payı + gap kadar üst boşluk)
+└─ … içerik
+```
+
+**Form ekranı.** Gönder düğmesi formun içinde, akışın sonundadır. Form doğrulaması yalnız bu yolda koşar.
+
+```
+page_container
+├─ text  type:h2  (başlık)
+└─ form  direction:column  horizontalAlign:stretch  gap:large  paddingType:none  marginType:none  widthType:fill
+   ├─ … bölümler
+   └─ button  type:submit  widthType:fill
+```
+
+## Bileşen dizgisi
+
+Bir ekran yukarıdan aşağıya şu sırayla kurulur: **başlık → bölümler → eylem.**
+
+- **Başlık:** `text` `type: 'h2'`, bölüm başlığı `type: 'h4'`. `typographyStyle.fontSize` yazılmaz.
+- **Bölüm iki türlüdür:**
+  - *Görünen grup (yüzey kabı):* `container` + `surfaceStyle` (zemin ya da kenarlık, `radius: 'lg'`) +
+    `paddingType: 'custom'` ve `paddingValue: 16`. İçeriği bilerek 16 içeride durur; kabın kendisi kardeşleriyle
+    hizalıdır.
+  - *Görünmeyen grup (saydam kap):* `container` `direction: 'column'`, `paddingType: 'none'`,
+    `marginType: 'none'`. İçerik kardeşleriyle aynı kenarda başlar.
+
+  Başlığı (`title`) olan ama zemini olmayan kap saydam kap gibi davranmalıdır. Varsayılan 10 dp padding'i
+  içeriği kaydırır (MOB-019). Ya yüzey verin ya da padding'i `none` yapın.
+- **`card` çocuk almaz.** Kart görünümlü alan grubu `container` + `surfaceStyle` ile kurulur.
+- **`tooltip`** dokunulan içeriği sarar ve saydamdır. Runtime ona varsayılan boşluk vermez; gateway yine de yeni
+  tooltip'e `paddingType: 'none'` ve `widthType: 'fill'` yazar. 2026-09-29'dan önce derlenmiş uygulamada
+  boşluksuz tooltip'in içeriği 14 dp içeri kayar ve 28 dp daralır; açık değer onu da korur.
+- **Satır (`direction: 'row'`)** yan yana dizilen öğeler içindir: arama kutusu + düğme, ikon + metin,
+  "Ekle / Sil" düğmeleri. Form alanlarını alt alta dizmek için satır kullanılmaz.
+- **Eylem:** birincil düğme tam genişlik (`widthType: 'fill'`). İkincil eylem `variant: 'text'` ya da
+  `'outline'`; metin görünümlü düğme içerik genişliğinde durabilir.
+- **Ekrana sabit eylem** (`floating-container`, `anchor: 'bottom-center'`, `fullWidth`, `respectSafeArea`) iki
+  şeye dikkat ister:
+  - *Yerleşim.* `fullWidth` ekran kenarına dayanır; S4 kenarı için içine `paddingType: 'custom'` +
+    `paddingValues` yatay 16 olan bir kap koyun, `floating-container`'ın kendisine `paddingType: 'none'`
+    yazın (yoksa akışta 20 dp boş şerit kalır). Sabit düğme uzun formun son alanını örter; akışın sonuna
+    düğme boyu kadar boşluk bırakın.
+  - *Gönderim.* Formun dışındaki `type: 'submit'` + `formId` düğmesi formun olayını tetikler ama **form
+    doğrulamasını koşmaz** (bilinen açık). Doğrulanan form için gönder düğmesi formun içinde kalmalı.
+
+## Boşluk
+
+Aralığın tek kaynağı ebeveynin `gap`'idir. Runtime'ın varsayılanları katmanlarda birikir: margin tipi
+yazılmamış her düğüm 4 dp, bırakılabilir düğüm ayrıca 10 dp padding alır. İki kat iç içe zeminsiz kap, içeriği
+28 dp kaydırır.
+
+- **Gateway yeni düğüme `marginType: 'none'` yazar** (`page_create`, `page_schema_patch`,
+  `page_schema_validate`) ve bunu `gatewayNormalized`'da söyler.
+  - Kardeşleri varsayılan margin'le duran eski bir kaba eklenen düğüme dokunulmaz; yeni düğüm eskilerden
+    4 dp kayardı. Kabı sözleşmeye taşımak için bütün çocuklarına `marginType: 'none'` yazın.
+  - `layout_schema_patch` ve `component_schema_patch` bu varsayılanı yazmaz. Kabukta ya da widget'ta eklenen
+    düğüme boşluğu siz yazın.
+- **Ritim:**
+  - bölümler arası `gap: 'large'` (24);
+  - bölüm içi alanlar `gap: 'medium'` (16);
+  - satır içi öğeler `gap: 'small'` (8).
+
+- **Özel değer** (`custom`) ve sayısal `gap` yalnız ölçekten seçilir: 0, 4, 8, 16, 24, 32 (MOB-021).
+
+## Genişlik ve hiza
+
+- **`horizontalAlign: 'stretch'`** olan sütun, çocuklarını `widthType` yazılmasa da tam genişlik gerer. Öteki
+  hizalarda tam genişlik öğesine `widthType: 'fill'` yazın. Aynı sütunda bir kısmı `fill`, bir kısmı değilse
+  sağ kenar hizadan kopar (MOB-020).
+- **Yönü yazılmamış `container` ve `form` satırdır.** Alanlar yan yana sıkışır; `direction: 'column'` yazın.
+  `safe-area` ve `scroll-view` sütun doğar.
+- **Ortalanmış ekran** (giriş, boş durum) için sütuna `horizontalAlign: 'center'` verin. Bu kapsamda kenar
+  eşitliği aranmaz.
+
+## Kenarlık, yarıçap, yazı
+
+- **Yüzey:** `surfaceStyle` ile verilir.
+  - zemin `background: 'var(--ng-…)'` (temada tanımlı jeton);
+  - kenarlık `borderTop…borderLeft` 1 dp, renk `border` jetonu;
+  - yarıçap `radius: 'lg'`.
+
+  Zemin ve kenarlığı birlikte kullanmayın; biri yeter.
+- **Yarıçap ölçeği:** kartlar `lg`, çip ve rozetler `pill`, alan ve düğmeler temadan. Ham `'10px'` yazılmaz.
+- **Yazı:** `text` `type` seviyesi.
+- **Tasarım sistemi çapında görünüm** (bütün kartlar, bütün düğmeler) temadan yönetilir. Ölçekler, adlı ön
+  ayarlar ve yeni düğümlerin başlangıç değerleri `platform_guide('theme')`'dadır. Aynı değer tek tek düğümlere
+  kopyalanmaz. Temanın eski `componentStyles` alanı emeklidir.
+
+## Kaydırma
+
+Sayfa kökü her zaman kaydırır: barındırıcı sayfayı bir kaydırıcı içinde çizer.
+
+`scroll-view` yalnız şu gerekçelerle eklenir:
+
+- `refreshable` (çekerek yenile);
+- `stickyHeader` ya da `states.isSticky` çocuk (yapışkan başlık);
+- `horizontal` (yatay şerit);
+- `heightType: 'fixed'` (sabit boylu iç liste).
+
+Gerekçesiz ya da iç içe dikey kaydırıcı jestleri çakıştırır (MOB-016). Kökün `size: 'grow'`'u çocukları ekran
+boyunca eşit böler ve kısa içerik üst üste biner. Yapışkan başlık ve ekrana sabit içerik için
+`platform_guide('mobile')` §Ekrana sabit içerik.
+
+## Doğrulama
+
+Bir ekranı bitirince iki çağrı yapın:
+
+1. **`page_schema_validate`** (kuru koşu): `layoutWarnings`'te MOB-015…021 bulgusu olmamalı.
+   - Yazım araçları (`page_schema_patch`, `layout_schema_patch`) yalnız o yazımın **getirdiği** bulguyu söyler.
+   - Sayfanın bütün durumunu kuru koşu verir.
+2. **`page_screenshot({ layoutReport: true })`:** `layoutSummary.alignment` şu değerleri vermeli.
+
+| Alan | Temiz değer | Anlamı |
+|---|---|---|
+| `gutter` | 16 | ekran kenarı boşluğu (sol = sağ) |
+| `leftEdges` | tek küme | aynı kapsamdaki geniş içeriğin sol kenarları |
+| `surfaces` | `[]` | iç hizası bozuk yüzey kabı yok |
+| `widthOutliers` | `[]` | sağ kenarı sapan geniş öğe yok (`insetLeft`/`insetRight` dp) |
+| `offScaleGaps` | `[]` | ardışık öğeler arası boşluk ölçekte |
+
+İki kaynak aynı şeyi söyler. MOB-019'un şemadan öngördüğü dp farkı, `leftEdges` kümeleri arasındaki farktır.
+
+## Bulgu → reçete
+
+| Kod | Ne diyor | Ne yapılır |
+|---|---|---|
+| MOB-015 | Üst pay eksik ya da çift | Kabuksuz sayfaya `safe-area` `top`. Kabuğu payı vermiyorsa kabukta app-bar'ı `safe-area` `top` içine alın. Kabuk veriyorsa sayfadaki `top`/`all` güvenli alanı kaldırın |
+| MOB-016 | Kaydırma tek yerde değil | Kök `size: 'shrink'`. Gerekçesiz `scroll-view`'ı kaldırın ya da gerekçesini verin. İç içe olanda içtekine `fixed` boy verin |
+| MOB-017 | İkinci ya da yanlış yerde app-bar | Kabuk veriyorsa sayfadakini silin, başlığı kabuğa bağlayın. Kabuksuzda app-bar'ı ilk sıraya (ya da tepedeki `safe-area`'nın içine) taşıyın |
+| MOB-018 | Boş kap | İçeriğini ekleyin ya da silin |
+| MOB-019 | Kenar kayması (dp) | Bulgunun hedefi içeriği iten kaptır. Görünen grup olacaksa yüzey verin, olmayacaksa `paddingType: 'none'` + `marginType: 'none'`. Hedef öğenin kendisiyse margin'ini kardeşleriyle aynı yapın |
+| MOB-020 | Genişlik tutarsız | Öğeye `widthType: 'fill'`. Yönü yazılmamış kaba `direction: 'column'` + `horizontalAlign: 'stretch'` |
+| MOB-021 | Ölçek dışı değer | Boşluğu ve sayısal gap'i 0/4/8/16/24/32'den, yarıçapı `sm`/`md`/`lg`/`pill`'den, yazı boyunu `text` `type`'tan seçin |