Widget türleri

Widget artık yalnızca hesaplayıcı değildir. Aynı yükleyici (widget.js) üç tür widget kurar:

Tür	İşaretleme	Embed sayfası	Ne gösterir
Hesaplayıcı	data-mo-tool="kdv" veya <mo-calculator tool="kdv">	/{dil}/embed/{key}	Bir aracın formu ve sonuç paneli.
Arama	data-mo-search veya <mo-search>	/{dil}/embed/kit/search	Araçları arayan bir kutu.
Kategori	data-mo-category="tax" veya <mo-category category="tax">	/{dil}/embed/kit/category/{key}	Bir kategorideki araçların listesi.

Üç türde de ortak seçenekler geçerlidir: data-locale, data-theme, data-header, data-height, data-accent, data-radius, data-density, data-title, data-lazy (Kurulum). Hesaplayıcıya özgü seçenekler (data-view, data-autorun, data-input-*, data-inputs) arama ve kategori widget’larında yoktur.

Not

kit, araç anahtarı olarak ayrılmıştır; bu adlı bir araç olmaz.

Arama kutusu

<div data-mo-search data-locale="tr" data-target="event" data-category="tax"></div>
<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

Öznitelik	Değerler	Varsayılan	Açıklama
data-mo-search	(değer yok)	zorunlu	Kapsayıcıyı arama widget’ı yapar.
data-target	_blank, event	_blank	Bir sonuç seçilince ne olacağı (aşağıya bakın).
data-category	kategori anahtarı (^[a-z0-9]+(-[a-z0-9]+)*$, 2–64)	yok	Aramayı bir kategoriye sınırlar.

Kategori listesi

<div data-mo-category="tax" data-locale="tr" data-density="compact"></div>
<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

Öznitelik	Değerler	Varsayılan	Açıklama
data-mo-category	kategori anahtarı	zorunlu	Listelenecek kategori. Anahtarlar araç kataloğunda görünür.
data-target	_blank, event	_blank	Bir araç seçilince ne olacağı.

Geçersiz bir anahtar veya değer, hesaplayıcıdaki gibi İngilizce bir console.warn yazar ve kapsayıcı atlanır.

target: seçim davranışı

Değer	Davranış
_blank (varsayılan)	Seçilen aracın (veya kategorinin) sayfası yeni sekmede açılır.
event	Hiçbir şey açılmaz; widget yalnızca mo:select olayı gönderir. Yönlendirmeyi siz yaparsınız (kendi yönlendiricinizle, bir modalla, hesaplayıcıyı aynı sayfada açarak vb.).

`_top` yoktur

target yalnızca _blank ve event değerlerini kabul eder. Yükleyicinin iframe sandbox’ı üst pencereyi yönlendirmeyi (top navigation) engeller; aynı sekmede gezinmek istiyorsanız event kullanın ve event.detail.url ile kendiniz yönlendirin.

mo:select olayı

Arama ve kategori widget’larında bir araç ya da kategori seçildiğinde kapsayıcıdan kabarcıklanan bir CustomEvent gelir:

interface SelectDetail {
  id: string;                       // yükleyicinin atadığı örnek kimliği
  kind: 'tool' | 'category';
  key: string;                      // seçilenin anahtarı
  title: string;
  url: string;                      // seçilenin tam sayfa adresi
}

target="event" iken widget yalnızca bu olayı gönderir ve gezinmeyi size bırakır. Bu widget’larda ayrıca mo:ready (tool alanı null), mo:resize ve mo:error gelir; mo:input ve mo:result gelmez. Ayrıntılar: Olaylar.

Örnek: seçilen aracı aynı sayfada hesaplayıcı olarak aç

<div id="arama" data-mo-search data-target="event" data-locale="tr"></div>
<div id="hesap"></div>
<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

<script>
  document.getElementById('arama').addEventListener('mo:select', (event) => {
    const { kind, key } = event.detail;
    if (kind !== 'tool') return;

    const host = document.getElementById('hesap');
    window.MiracOzdemirWidget.unmount(host);
    host.setAttribute('data-mo-tool', key);
    host.setAttribute('data-locale', 'tr');
    window.MiracOzdemirWidget.mount(host);
  });
</script>

mo:select ancak arama widget’ı kurulup kullanıcı bir seçim yaptıktan sonra geldiği için bu noktada window.MiracOzdemirWidget tanımlıdır. Hesaplayıcı kapsayıcısı bir kez kurulduktan sonra aracı değiştirmek için unmount + mount yerine update(host, { tool: key }) de kullanılabilir.

Örnek: React’te yönlendirici ile

import { WidgetSearch } from '@mirac-ozdemir/widget/react';

export function Search() {
  return <WidgetSearch target="event" category="tax" onSelect={({ kind, key }) => kind === 'tool' && navigate(`/hesapla/${key}`)} />;
}

(SDK henüz npm’de değil; bkz. Özel öğeler ve SDK. Ham yükleyiciyle aynısı addEventListener('mo:select', …) ile yapılır.)

Yalnızca sonuç görünümü

data-view="result" hesaplayıcının girdi formunu gizler ve yalnızca sonuç panelini gösterir. Tek başına bir sonuç kartı, bir bordro özeti veya haber yazısı içinde “güncel KDV tutarı” gibi önceden hesaplanmış bir çıktı için kullanışlıdır. Sonuç görünümü ön değer gerektirir ve autorun’u içerir (ayrıca data-autorun vermeniz gerekmez):

<div
  data-mo-tool="kdv"
  data-view="result"
  data-input-amount="1000"
  data-input-mode="exclusive"
  data-input-vat-rate-option="standard"
  data-header="false"
></div>
<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

Düz iframe karşılığı: /{dil}/embed/{key}?view=result&i.amount=1000&…. view canlı değiştirilebilir (update(el, { view: 'full' })), böylece kullanıcıya “değerleri düzenle” düğmesi sunabilirsiniz.

Özel öğe

<mo-calculator tool="kdv" view="result" input-amount="1000" input-mode="exclusive" header="false"></mo-calculator>

Düz iframe

<iframe
  src="https://mirac-ozdemir.com/tr/embed/kdv?view=result&i.amount=1000&i.mode=exclusive&header=0"
  title="KDV sonucu"
  width="100%"
  height="320"
  style="border:0;display:block"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
></iframe>

Görünümü özelleştirme

Her tür aynı görünüm seçeneklerini kabul eder: data-accent (6 onaltılık hane), data-radius (none, sm, md, lg), data-density (comfortable, compact), data-theme (inherit dahil). Bunlar update ile canlı değiştirilir; target, category ve locale ise iframe’i yeniden yükler. Seçenekleri deneyerek görmek için yapılandırıcıda Widget türü listesinden bir tür seçin.