@ahmetilhn/hanui 2.0.0 → 2.0.2

package/build/index.d.ts

@@ -7,12 +7,14 @@ import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { JSX } from 'react';
+import { KeyboardEvent as KeyboardEvent_2 } from 'react';
 import { MemoExoticComponent } from 'react';
 import { NamedExoticComponent } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
 import { RefAttributes } from 'react';
+import { RefObject } from 'react';
 import { TableHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 
@@ -200,6 +202,16 @@ declare type BaseProps_4 = {
     previousLabel?: string;
     /** Verilmezse `labels.pagination.next`. */
     nextLabel?: string;
+    /**
+     * Sayfa değiştiğinde ekran okuyucuya duyurulacak metin
+     * ("3. sayfa · 1.248 sonuç").
+     *
+     * <p>Verilmediğinde duyuru YAPILMAZ. Görsel tarafta sayfa numarası
+     * `aria-current` ile zaten işaretli ama o yalnızca ODAK oraya geldiğinde
+     * okunuyor: bağlantıya basıp listenin başına dönen kullanıcı, kaçıncı
+     * sayfada olduğunu ve kaç sonuç kaldığını hiç duymuyordu.
+     */
+    formatAnnouncement?: (page: number, totalPages: number) => string;
     className?: string;
     testId?: string;
 };
@@ -1740,6 +1752,31 @@ declare type LinkProps = BaseProps_4 & {
     linkProps?: HanuiLinkExtraProps;
 };
 
+export declare type ListboxNavigation<T extends HTMLElement = HTMLElement> = {
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    /**
+     * Etkin seçeneği görünür alanda tutmak için LİSTEYE bağlanır.
+     *
+     * <p>Tip parametresi çağıran taraf için: `Select` bu referansı `<ul>`e
+     * veriyor ve panel açıldığında `focus()` çağırıyor. `HTMLElement`e sabitlense
+     * çağıran ikinci bir referans tutmak ve ikisini elle eşlemek zorunda kalırdı.
+     */
+    listRef: RefObject<T | null>;
+    handleKeyDown: (event: KeyboardEvent_2<HTMLElement>) => void;
+};
+
+export declare type ListboxNavigationOptions = {
+    /** Seçenek sayısı. Liste süzüldüğünde değişir. */
+    count: number;
+    isOpen: boolean;
+    /** Açılışta etkin olacak dizin — genellikle seçili olan. */
+    initialIndex?: number;
+    /** `Enter` / `Space` ile seçildiğinde. */
+    onSelect: (index: number) => void;
+    onClose: () => void;
+};
+
 /**
  * Aranan metin, hedefin içinde geçiyor mu?
  *
@@ -2092,10 +2129,34 @@ export declare const Popover: typeof Popover_2;
 declare const Popover_2: ({ trigger, children, label, side, align, isOpen: controlledOpen, onOpenChange, className, testId, }: Props_5) => JSX.Element | null;
 
 /** Tercih edilen kenar boyunca hizalama. */
-declare type PositionAlign = 'start' | 'center' | 'end';
+export declare type PositionAlign = 'start' | 'center' | 'end';
+
+export declare type PositioningOptions = {
+    side?: PositionSide;
+    align?: PositionAlign;
+    /** Tetikleyici ile yüzey arasındaki boşluk (px). */
+    offset?: number;
+    /** Görünüm alanının kenarından bırakılacak asgari pay (px). */
+    padding?: number;
+    /** Kapalıyken ölçüm yapılmaz ve dinleyici kurulmaz. */
+    isOpen: boolean;
+};
+
+export declare type PositioningState = {
+    /** Yüzeye uygulanacak stil — `position: fixed` + hesaplanmış koordinat. */
+    style: {
+        position: 'fixed';
+        top: number;
+        left: number;
+    };
+    /** ÇÖZÜLMÜŞ kenar: çarpışma yüzünden tercih edilenin karşıtı olabilir. */
+    side: PositionSide;
+    /** İlk ölçüm yapıldı mı. Yapılmadan çizilen yüzey sol üst köşede parlıyor. */
+    isPositioned: boolean;
+};
 
 /** Yüzeyin tercih ettiği kenar. Yer yoksa karşıtına düşer. */
-declare type PositionSide = 'top' | 'bottom' | 'left' | 'right';
+export declare type PositionSide = 'top' | 'bottom' | 'left' | 'right';
 
 /**
  * `showModal()` ÇAĞRILDIKTAN SONRA çağrılır. Odak bir metin alanına düştüyse
@@ -2542,6 +2603,20 @@ declare type Props_27 = {
     value: string;
     /** Para birimi simgesi ya da kodu. Verilmezse `labels.currency`. */
     currency?: string;
+    /**
+     * Değeri `Intl.NumberFormat` ile biçimlendirir.
+     *
+     * <p>`value` bu kipte de bir DİZE olarak kalıyor ve sayıya çevriliyor —
+     * bileşen hâlâ HESAP YAPMIYOR, yalnızca ayırıcıları ve para birimi
+     * konumunu yerel ayardan alıyor. Yerel ayar `labels.locale`den; verilmezse
+     * biçimlendirme YAPILMAZ ve değer olduğu gibi yazılır. Yanlış yerel ayarda
+     * biçimlendirilmiş bir tutar, biçimlendirilmemiş olandan kötü: "1,250" bir
+     * yerde bin iki yüz elli, başka bir yerde bir tam iki yüz elli.
+     *
+     * <p>Para birimi simgesinin ÖN/ARKA konumu da yerel ayara bağlı ve şu anda
+     * her zaman arkada — `Intl` açıldığında doğru konumu o veriyor.
+     */
+    isFormatted?: boolean;
     /** Üstü çizili liste fiyatı; indirim varsa verilir (biçimlenmiş). */
     listValue?: string;
     /** İndirim oranı (tam sayı yüzde). */
@@ -2770,6 +2845,16 @@ declare type Props_37 = {
     onChange?: (id: string) => void;
     /** Sekme çubuğunun erişilebilir adı. */
     ariaLabel?: string;
+    /**
+     * Ok tuşu yalnızca ODAĞI taşır; seçim `Enter`/`Space` ile yapılır.
+     *
+     * <p>Varsayılan OTOMATİK etkinleştirme (ok tuşu odakla birlikte seçimi de
+     * taşır) ve APG panel içeriği hazır olduğu sürece onu öneriyor. Ama panel
+     * PAHALIYSA — her sekme bir istek atıyorsa — otomatik etkinleştirme,
+     * kullanıcı beşinci sekmeye giderken dört istek atıyor. Manuel kipte
+     * kullanıcı hedefine varıp `Enter`a basıyor: tek istek.
+     */
+    isManualActivation?: boolean;
     className?: string;
     testId?: string;
 };
@@ -2915,6 +3000,16 @@ declare type Props_43 = {
     cancelLabel?: string;
     /** Verilmezse `labels.close`. */
     closeLabel?: string;
+    /**
+     * Onayın türü — ikon, ton ve onay düğmesinin varyantını birlikte belirler.
+     *
+     * <p>Ad `kind`ten `variant`a taşındı: aynı işi yapan üçüncü bir ad
+     * kütüphanede zaten `variant` olarak duruyordu (`Button`, `Badge`) ve
+     * tüketici her bileşende hangisinin geçerli olduğunu hatırlamak zorunda
+     * kalıyordu. Nöbetçi: `src/__tests__/api-consistency.test.ts`.
+     */
+    variant?: ConfirmKind;
+    /** @deprecated `variant` kullanın. Bir sonraki büyük sürümde kalkacak. */
     kind?: ConfirmKind;
     /** Ek bağlam: silinecek kaydın özeti, uyarı kutusu. */
     children?: ReactNode;
@@ -3752,9 +3847,10 @@ export declare const Tabs: typeof Tabs_2;
  *   <tr><td>`Tab`</td><td>çubuktan panele çıkar — çubuk TEK durak</td></tr>
  * </table>
  * Ok tuşu odakla birlikte seçimi de taşır (otomatik etkinleştirme). Panel
- * içeriği hazır ve ucuz olduğu sürece APG'nin önerdiği budur; pahalı panelli
- * bir kullanım manuel etkinleştirme ister ve o seçenek HENÜZ YOK. Nöbetçi:
- * `components/__tests__/keyboard.test.tsx`.
+ * içeriği hazır ve ucuz olduğu sürece APG'nin önerdiği budur; her sekmesi bir
+ * istek atan pahalı bir panelde `isManualActivation` verilir — orada otomatik
+ * etkinleştirme, kullanıcı beşinci sekmeye giderken dört istek atıyordu.
+ * Nöbetçi: `components/__tests__/keyboard.test.tsx`.
  */
 declare const Tabs_2: FC<Props_37>;
 
@@ -3802,8 +3898,33 @@ export declare const Textarea: typeof Textarea_2;
  *
  * <p>Yeniden boyutlandırma yalnızca <strong>dikey</strong>: yatayda büyütmek
  * alanı kapsayıcısının dışına taşırıp yerleşimi bozuyordu.
+ *
+ * <h3>Otomatik yükseklik neden CSS ile değil</h3>
+ * `field-sizing: content` bu işi tek satırda yapıyor ama bugün yalnızca
+ * Chromium'da var. Ölçüm yolu her yerde çalışıyor ve tarayıcı desteği
+ * geldiğinde tek dosyada değiştirilecek.
  */
 declare const Textarea_2: ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & {
+/**
+* Alan içeriğiyle birlikte BÜYÜR — kaydırma çubuğu yerine yükseklik.
+*
+* <p>Sabit yükseklikli bir alanda kullanıcı yazdığının tamamını göremiyor:
+* dört satırlık bir kutuya on satır yazan kişi, gönderdiğinde ne yazdığını
+* kontrol etmek için kutunun içinde kaydırmak zorunda kalıyordu. `maxRows`
+* ile tavan konur; ötesinde kaydırma geri döner (sayfa boyunca uzayan bir
+* alan, altındaki gönder düğmesini ekrandan çıkarıyordu).
+*/
+isAutoSize?: boolean;
+/** Otomatik büyümenin tavanı (satır). */
+maxRows?: number;
+/**
+* Kalan karakter sayacını gösterir. `maxLength` ile birlikte anlamlı.
+*
+* <p>Sayaç `aria-hidden`: aynı bilgi her tuşta duyurulsaydı yazma
+* kesintiye uğrardı. Sınıra YAKLAŞILDIĞINDA (son %10) sayaç uyarı tonuna
+* geçiyor — sınıra çarpıp yazamamak, yaklaştığını görmemekten kötü.
+*/
+hasCounter?: boolean;
 testId?: string;
 } & RefAttributes<HTMLTextAreaElement>>;
 
@@ -4149,6 +4270,90 @@ export declare const useHanui: () => HanuiContextValue;
  */
 export declare const useHanuiTheme: () => ThemeState;
 
+/**
+ * LISTBOX KLAVYE GEZİNMESİ — `Select` ve `Combobox`ın ortak modeli.
+ *
+ * <h3>Neden bir kanca</h3>
+ * İki bileşen aynı klavye modelini <strong>kopya kod</strong> olarak
+ * taşıyordu: `ArrowDown`/`ArrowUp` uçlarda dönme, `Home`/`End`, `Enter` ile
+ * seçme, `Escape` ile kapatma, `Tab` ile kapatıp gezinmeye devam etme ve
+ * etkin seçeneği görünür alanda tutma. Altı davranış, iki yerde. Kopya kod
+ * ayrışmaya açık ve ayrışma sessiz: bir bileşende `Home` çalışıp diğerinde
+ * çalışmadığında hiçbir test kırılmıyordu — ikisinin de kendi testi vardı ve
+ * ikisi de kendi davranışını doğruluyordu.
+ *
+ * <p>Kanca yalnızca <strong>gezinmeyi</strong> taşıyor. Açılma kararı (panel
+ * mi alt sayfa mı), filtreleme ve seçim sözleşmesi (`value`/`onChange`) hâlâ
+ * bileşenlerin: ikisi orada gerçekten farklı ve tek bir kancaya toplamak
+ * `Select`e hiç kullanmayacağı arama koduna taşıtırdı.
+ *
+ * <h3>Klavye</h3>
+ * <table>
+ *   <tr><td>`ArrowDown` / `ArrowUp`</td><td>etkin seçenek; uçlarda DÖNER</td></tr>
+ *   <tr><td>`Home` / `End`</td><td>ilk / son</td></tr>
+ *   <tr><td>`Enter` / `Space`</td><td>etkin seçeneği seçer</td></tr>
+ *   <tr><td>`Escape`</td><td>kapatır</td></tr>
+ *   <tr><td>`Tab`</td><td>kapatır, gezinme SÜRER (`preventDefault` yok)</td></tr>
+ * </table>
+ *
+ * <p>`Space` yalnızca `hasSpaceSelect` ile: `Combobox`ın arama kutusunda boşluk
+ * bir KARAKTER ve onu seçime çevirmek "fren balatası" yazmayı imkânsız
+ * kılıyordu.
+ */
+export declare const useListboxNavigation: <T extends HTMLElement = HTMLElement>({ count, isOpen, initialIndex, onSelect, onClose }: ListboxNavigationOptions, { hasSpaceSelect }?: {
+    hasSpaceSelect?: boolean | undefined;
+}) => ListboxNavigation<T>;
+
+/**
+ * ÇARPIŞMAYA DUYARLI KONUMLANDIRMA — `Tooltip`, `Popover`, `Menu` ve açılır
+ * listelerin ortak temeli.
+ *
+ * <h3>Neden var: `position: absolute` yetmiyordu</h3>
+ * `Tooltip` balonu tetikleyicinin içinde, `position: absolute` ile duruyordu.
+ * Üç somut sonucu vardı:
+ *
+ * <ul>
+ *   <li><b>Kırpılma.</b> `overflow: hidden` taşıyan her kapsayıcı (kart,
+ *       tablo kaydırma kutusu, `Panel`) balonu kesiyordu. Bir tablo hücresinde
+ *       ipucu görünmüyordu — hiç.</li>
+ *   <li><b>Taşma.</b> Ekranın sağ kenarındaki bir tetikleyicinin balonu
+ *       görünüm alanının dışına çıkıyor, yatay kaydırma açıyordu.</li>
+ *   <li><b>Yığılma bağlamı.</b> `transform` taşıyan bir ata (`Card` hover
+ *       animasyonu) yeni bir yığılma bağlamı açıyor ve `z-index` orada
+ *       hapsoluyordu; balon kendi kartının altında kalıyordu.</li>
+ * </ul>
+ *
+ * <p>Çözüm portal + `position: fixed`: yüzey gövdeye taşınır, koordinat
+ * görünüm alanına göre hesaplanır. Kırpılacak bir kapsayıcı ve yarışılacak bir
+ * yığılma bağlamı kalmaz.
+ *
+ * <h3>Neden yeni bir bağımlılık YOK</h3>
+ * `floating-ui` bu işi yapıyor ve iyi yapıyor; ama paketin tek çalışma zamanı
+ * bağımlılığının ikon seti olması bilinçli bir karar (bkz. README). Burada
+ * ihtiyaç duyulan şey o kütüphanenin küçük bir alt kümesi: bir kenar, bir
+ * hizalama ve karşıt kenara düşme. Ok konumlandırma, otomatik yerleşim
+ * (`autoPlacement`), sanal öğe ve middleware zinciri gerekmiyor — ve
+ * gerektiğinde eklenecek yer burası.
+ *
+ * <h3>CSS Anchor Positioning neden kullanılmıyor</h3>
+ * Denendi ve BUGÜN kullanılamıyor: `anchor-name` / `position-anchor` yalnızca
+ * Chromium'da var (Safari ve Firefox'ta bayrak arkasında bile değil). İki
+ * kod yolu tutmak — biri modern tarayıcıda, biri yedekte — konumlandırmayı iki
+ * kez yazmak ve ikisinin ayrışmasını beklemek demek. Ölçüm tabanlı yol her
+ * yerde çalışıyor; tarayıcı desteği geldiğinde geçiş TEK dosyada.
+ *
+ * <h3>Ölçüm ne zaman yenileniyor</h3>
+ * Açılışta, pencere yeniden boyutlandığında ve <em>herhangi bir atanın</em>
+ * kaydırılmasında. Sonuncusu için `capture: true` ile belge düzeyinde tek bir
+ * dinleyici: kaydırma olayı baloncuklanmıyor ve her ata için ayrı dinleyici
+ * kurmak, derin bir ağaçta onlarca dinleyici demekti.
+ */
+export declare const usePositioning: (anchorRef: {
+    current: HTMLElement | null;
+}, surfaceRef: {
+    current: HTMLElement | null;
+}, { side, align, offset, padding, isOpen }: PositioningOptions) => PositioningState;
+
 export declare const useScrollLock: (isLocked?: boolean) => void;
 
 /**
@@ -4178,4 +4383,57 @@ export declare const useScrollLock: (isLocked?: boolean) => void;
  */
 export declare const useSheetViewport: (isActive?: boolean) => void;
 
+/**
+ * SANALLAŞTIRMA — yalnızca görünen satırları çiz.
+ *
+ * <h3>Ölçülen sorun</h3>
+ * 1121 markalı bir `Combobox` listesinde DOM 1121 satır taşıyordu. Panel
+ * açılışı mobilde gözle görülür şekilde donuyor, her tuş vuruşunda liste
+ * yeniden çiziliyordu. Ekran okuyucu tarafında da bedeli var: 1121 öğelik bir
+ * `listbox`ta gezinmek pratikte imkânsız.
+ *
+ * <h3>Neden kütüphane içinde</h3>
+ * `react-window` / `@tanstack/virtual` bu işi yapıyor ve iyi yapıyor; ama
+ * paketin tek çalışma zamanı bağımlılığının ikon seti olması bilinçli bir
+ * karar. Burada gereken şey o kütüphanelerin küçük bir alt kümesi: SABİT
+ * yükseklikli satırlar, tek eksen, yatay yok, değişken yükseklik yok.
+ *
+ * <h3>SABİT satır yüksekliği — ve bu bir kısıt</h3>
+ * Değişken yükseklikli sanallaştırma her satırın ölçülmesini ve bir konum
+ * haritası tutulmasını gerektiriyor. Açılır liste satırları zaten sabit
+ * yükseklikte (`min-height` + tek satır metin); ikincil satır taşıyan
+ * seçeneklerde ölçü `rowHeight` ile verilir.
+ *
+ * <h3>`overscan` neden var</h3>
+ * Yalnızca görünen satırlar çizilseydi hızlı kaydırmada alt kenarda bir kare
+ * boyunca boşluk görünüyordu — tarayıcı kaydırma olayını boyamadan sonra
+ * veriyor. Görünür alanın üstüne ve altına birkaç satır fazladan çizilir.
+ *
+ * <h3>Klavye gezinmesiyle ilişkisi</h3>
+ * Etkin seçeneği görünür tutan `scrollIntoView`, o seçenek ÇİZİLMEMİŞSE
+ * çalışmaz. `scrollToIndex` bu yüzden var: klavyeyle listenin dibine giden
+ * kullanıcı için konum önce hesaplanır, satır sonra çizilir.
+ */
+export declare const useVirtualList: (count: number, { rowHeight, overscan, isEnabled }?: {
+    rowHeight?: number | undefined;
+    overscan?: number | undefined;
+    isEnabled?: boolean | undefined;
+}) => {
+    scrollRef: RefObject<HTMLElement | null>;
+    range: VirtualRange;
+    scrollToIndex: (index: number) => void;
+    measure: () => void;
+};
+
+export declare type VirtualRange = {
+    /** Çizilecek ilk öğenin dizini. */
+    start: number;
+    /** Çizilecek son öğenin dizini (dahil DEĞİL). */
+    end: number;
+    /** Listenin gerçek toplam yüksekliği — kaydırma çubuğu doğru boyda olmalı. */
+    totalHeight: number;
+    /** Görünen ilk öğenin üstünde bırakılacak boşluk. */
+    offset: number;
+};
+
 export { }