Özel öğeler ve SDK

Widget’ı kullanmanın üç düzeyi vardır; hepsi aynı yükleyiciye (widget.js 1.1.0) dayanır:

1. İşaretleme: <div data-mo-tool="kdv"> (Kurulum).
2. Özel öğeler: <mo-calculator tool="kdv">: framework’süz, öznitelik odaklı.
3. SDK paketi: tipler, loadWidget yükleyici yardımcısı ve React/Vue bileşenleri.

Özel öğeler

Yükleyici üç özel öğe tanımlar: <mo-calculator>, <mo-search> ve <mo-category>. Seçenekler, data- öneki olmadan aynı adlarla öznitelik olarak verilir; ön değerler için input-<alan-kebab> kullanılır.

<mo-calculator tool="kdv" locale="tr" theme="inherit" accent="0a7d5a" input-amount="1000" autorun></mo-calculator>
<mo-search target="event" category="tax"></mo-search>
<mo-category category="tax" density="compact"></mo-category>

<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

Öğe	Anahtar öznitelik	Ek öznitelikler
<mo-calculator>	tool (zorunlu)	view, autorun, inputs (JSON), input-<alan>
<mo-search>	(yok)	target, category
<mo-category>	category (zorunlu)	target

Hepsinde ortak: locale, theme, header, height, accent, radius, density, title, lazy. Değerler ve varsayılanlar data-* karşılıklarıyla aynıdır (Kurulum, Widget türleri). Geçersiz bir değer, her zamanki gibi İngilizce bir konsol uyarısı yazar.

Öznitelik değişince ne olur

• Canlı güncellenir (iframe yeniden yüklenmez): theme, header, density, radius, accent, view, height, title.
• Yeniden kurulur: tool, category, locale, target, autorun, inputs, lazy (ve <mo-search> için category).
• input-<alan> öznitelikleri öğe sayfaya bağlanırken okunur; sonradan değiştirilmeleri widget’a yansımaz. Çalışma anında değer vermek için setInputs kullanın ya da inputs özniteliğini (JSON) değiştirin; o yeniden kurar.

const calc = document.querySelector('mo-calculator');
calc.setAttribute('theme', 'dark');     // canlı
calc.setAttribute('accent', 'e11d48');  // canlı
calc.setAttribute('locale', 'en');      // iframe yeniden yüklenir

Olaylar ve programatik çağrılar

mo:* olayları öğeden kabarcıklanır; öğeye veya document’e dinleyici ekleyebilirsiniz:

calc.addEventListener('mo:result', (event) => console.log(event.detail.data.result));

Öğe, iç yapısını kendisi yönetir: mevcut içeriği, widget’ı taşıyan bir kapsayıcı <div data-mo-mounted> ile değiştirir ve öğe sayfadan çıkarılınca widget’ı kaldırır. update, setInputs, calculate gibi JavaScript API çağrılarına bu iç kapsayıcıyı verin:

const inner = calc.querySelector('[data-mo-mounted]');
await window.MiracOzdemirWidget.calculate(inner);
window.MiracOzdemirWidget.setInputs(inner, { amount: '2500' }, { autorun: true });

Olayların event.target değeri de bu iç kapsayıcıdır.

TypeScript tipleri

SDK, öğeler için HTMLElementTagNameMap tiplerini içerir. Bir kez içe aktarmanız yeterlidir:

import '@mirac-ozdemir/widget/elements';

const calc = document.querySelector('mo-calculator'); // tipli
// JSX (React): <mo-calculator tool="kdv" input-amount="100" />

React, özel DOM olaylarına prop olarak abone olmaz; React bileşenlerini (aşağıda) kullanın ya da bir ref ile mo:* dinleyicilerini kendiniz ekleyin.

SDK

@mirac-ozdemir/widget, yükleyicinin üzerinde ince bir katmandır: kendi davranışı yoktur; iframe’i ve postMessage protokolünü yükleyici yönetir, SDK yükleyiciyi bir kez yükler ve tipleri verir.

Henüz npm'de değil

Paket henüz npm’de yayınlanmadı (private). Şimdilik kaynak paket olarak (yerel yol veya git bağımlılığı) kullanılabilir; npm yayını gelecekte planlanıyor. Aşağıdaki import satırları paket kurulduğunda geçerlidir. Ham yükleyici (widget.js) ve özel öğeler SDK gerektirmez.

# SDK deposundaki `npm run build`'den sonra
npm install ../mirac-ozdemir-widget-sdk
# ya da git bağımlılığı
npm install git+ssh://[email protected]/<org>/mirac-ozdemir-widget-sdk.git

React (>=18) ve Vue (^3.3) isteğe bağlı peer bağımlılıklarıdır; yalnızca kullandığınızı kurun. Giriş noktaları: . (yükleyici yardımcıları ve tipler), ./react, ./vue, ./elements (yalnızca tipler).

loadWidget

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

const widget = await loadWidget();                      // window.MiracOzdemirWidget, tipli
const iframe = widget.mount(document.querySelector('#calc')!);

document.querySelector('#calc')!.addEventListener('mo:result', (event) => {
  console.log(event.detail.data.result, event.detail.meta.asOf); // tipli
});

Seçenek	Varsayılan	Anlamı
apiOrigin	https://api.mirac-ozdemir.com	Yükleyiciyi sunan origin.
version	'latest'	latest /widget.js yükler (1 saat önbellek); '1.1.0' değişmez /widget/v1.1.0.js’i; '1' /widget/v1.js’i.
integrity	yok	Betik etiketi için SRI değeri (sha384-…).
timeoutMs	15000	Bu süreden sonra Error ile reddeder.

window.MiracOzdemirWidget zaten varsa hemen çözülür; eşzamanlı çağrılar tek bir betiği paylaşır (ve sayfada aynı adres için zaten bir <script> varsa onu bekler); <script async crossorigin="anonymous"> ekler; yükleme hatasında, zaman aşımında ya da global tanımlanmazsa Error ile reddeder. Başarısız bir yükleme unutulur, yani yeniden çağırmak yeniden dener. DOM yoksa (SSR) açık bir hatayla reddeder ve window’a hiç dokunmaz.

Manifest ve SRI

import { fetchManifest, loadPinnedWidget } from '@mirac-ozdemir/widget';

const widget = await loadPinnedWidget();    // manifestteki en yeni sürüm, integrity ile
const manifest = await fetchManifest();     // { latest, protocol, versions: [{ version, url, integrity, features }] }

loadPinnedWidget, protocol değeri 1 olmayan bir manifesti reddeder. Sabitlemenin bedeli: sabit yükleyici değişmez, SDK’yı veya manifesti yenileyene kadar düzeltme almazsınız. Ayrıntı: Sürüm politikası.

Tipli olaylar

Ana giriş noktası, HTMLElementEventMap’i genişletir; addEventListener('mo:result', …) ve diğerleri tipli gelir. detail tipleri dışa aktarılır:

import type { ReadyDetail, InputDetail, ResultDetail, ErrorDetail, SelectDetail, WidgetError, CalculationResult } from '@mirac-ozdemir/widget';

el.addEventListener('mo:error', (event) => {
  const { error, requestId } = event.detail; // ErrorDetail
  console.warn(error.code, error.fields, requestId);
});

Diğer tipler: MiracOzdemirWidgetApi, WidgetOptions, WidgetPatch, WidgetConfig, WidgetInstance, WidgetManifest. calculate() bir Error değil, WidgetError nesnesiyle ({ code, message, fields? }) reddeder.

React

import { useRef } from 'react';
import { Calculator, WidgetSearch, WidgetCategory, useWidget } from '@mirac-ozdemir/widget/react';

function Vat() {
  const ref = useRef<HTMLDivElement>(null);
  const { ready, calculate, setInputs, reset, getResult } = useWidget(ref);

  return (
    <>
      <Calculator
        ref={ref}
        tool="kdv"
        locale="tr"
        theme="inherit"
        accent="0a7d5a"
        inputs={{ amount: '1000' }}
        autorun
        onResult={({ data }) => console.log(data.result)}
        onError={({ error }) => console.warn(error.code, error.fields)}
      />
      <button disabled={!ready} onClick={() => calculate().then((r) => console.log(r.data))}>Hesapla</button>
    </>
  );
}

<WidgetSearch target="event" category="tax" onSelect={({ kind, key, url }) => router.push(url)} />
<WidgetCategory category="tax" />

• Prop’lar: tool (WidgetCategory için category), locale, theme, header, height, accent, radius, density, view, autorun, inputs, title, lazy, className, style, ref; ayrıca loader (LoadWidgetOptions) ve onLoadError. Olaylar: hesaplayıcıda onReady, onInput, onResult, onError; arama/kategoride onReady, onSelect, onError.
• Canlı prop’lar (theme, header, density, radius, accent, view, height, title) mount edilmiş widget’ta update çağırır; tool, locale, category ve target widget’ı yeniden kurar. Değişen inputs, setInputs ile gönderilir.
• Bileşenler data-* öznitelikli boş bir div çizer ve render sırasında window okumaz; yani SSR güvenlidir. Next.js App Router’da bir istemci bileşeninde kullanın ('use client').
• useWidget(ref).ready, mo:ready olayını izler. calculate() bir WidgetError nesnesiyle reddeder; widget mount edilmeden önce NOT_MOUNTED döner.
• onLoadError verilmezse, başarısız betik yüklemesi console.error ile yazılır.

Vue 3

<script setup lang="ts">
import { ref } from 'vue';
import { Calculator, type CalculatorExposed } from '@mirac-ozdemir/widget/vue';

const calc = ref<CalculatorExposed | null>(null);
</script>

<template>
  <Calculator
    ref="calc"
    tool="kdv"
    locale="tr"
    :inputs="{ amount: '1000' }"
    autorun
    @result="(d) => console.log(d.data.result)"
    @error="(d) => console.warn(d.error.code)"
  />
  <button @click="calc?.calculate()">Hesapla</button>
</template>

Calculator, WidgetSearch ve WidgetCategory React bileşenleriyle aynı prop’ları alır (ref/style hariç; class düşer) ve ready, resize, input, result, error (hesaplayıcı), ready, resize, select, error (arama/kategori) ve loadError olaylarını yayar. Calculator calculate, setInputs, reset, getResult yöntemlerini dışa açar. Nuxt’ta <ClientOnly> içinde kullanın.

Uyumluluk

SDK, yükleyici 1.1.0 ve mesaj protokolü 1 için yazılmıştır. Geriye dönük uyumlu yükleyici sürümleri çalışmaya devam eder; protokol 2’ye sahip bir /widget/v2.js, SDK’nın yeni bir ana sürümünü gerektirir. Yükleyicinin bilmediği seçenekler yok sayılır.