API Publik dan Tipings TypeScript

Waves dimuat sebagai modul UMD. Wrapper-nya memilih define untuk AMD, module.exports untuk CommonJS, dan window.Waves untuk browser, sehingga kode aplikasi selalu memanggil satu objek yang sama src/js/waves.js:10-32¹. Objek itu membawa lima entry point publik. Empat di antaranya adalah kontrak utama, sedangkan yang kelima, Waves.displayEffect, hanya fallback deprecated yang meneruskan panggilan ke Waves.init src/js/waves.js:594-597².

Sisi TypeScript diumumkan lewat field types pada package.json, yang menunjuk berkas src/typings/waves.d.ts package.json:8³. Berkas itu mendeklarasikan tipe ElementSelector dan empat fungsi, tanpa displayEffect src/typings/waves.d.ts:1-9⁴.

Lima entry point

Alur pemanggilan dari kode aplikasi

Kode aplikasi hanya menyentuh objek Waves. Semua pekerjaan riil terjadi di getWavesElements, Effect, dan listener yang dipasang pada document.body src/js/waves.js:467-487⁵.

sequenceDiagram
    participant App as "kode aplikasi"
    participant W as "objek Waves"
    participant GE as "getWavesElements"
    participant Body as "document.body"
    participant Eff as "Effect"
    App->>W: "Waves.attach('.flat-buttons', ['waves-button'])"
    W->>GE: "elements dinormalisasi"
    GE-->>W: "kumpulan DOM node"
    W->>W: "tambah kelas waves-effect"
    App->>W: "Waves.init({ duration: 500 })"
    W->>Eff: "set Effect.duration dan Effect.delay"
    W->>Body: "addEventListener mousedown dan touchstart"
    App->>W: "Waves.ripple('.box', { wait: null })"
    W->>Eff: "Effect.show(mousedown, element)"
    W->>Eff: "setTimeout hideRipple"
    App->>W: "Waves.calm('.box')"
    W->>Eff: "Effect.hide(mouseup, element)"
%% fig: Alur pemanggilan lima entry point publik
%% desc: Kode aplikasi memanggil Waves, yang menormalkan elemen dan menyerahkan pembuatan serta penghapusan ripple ke objek Effect.

Normalisasi argumen elements

getWavesElements menerima empat bentuk masukan: string selector yang dijalankan lewat $$ (yaitu document.querySelectorAll), koleksi ber-length seperti Array, HTMLCollection, NodeList, atau Object, satu DOM node yang dibungkus menjadi array, dan nilai lain yang jatuh ke array kosong src/js/waves.js:59-71⁹.

graph LR
    S["string selector"] --> GE["getWavesElements"]
    C["Array / HTMLCollection / NodeList / Object"] --> GE
    N["satu DOM node"] --> GE
    GE --> Q["$$(nodes)"]
    GE --> P["nodes apa adanya"]
    GE --> A["[nodes]"]
    GE --> E["[]"]
    style GE fill:#f59e0b,color:#000
    style Q fill:#2d7d46,color:#fff
    style P fill:#2d7d46,color:#fff
    style A fill:#2d7d46,color:#fff
    style E fill:#dc2626,color:#fff
%% fig: Cabang normalisasi elemen
%% desc: getWavesElements memetakan tiap bentuk masukan ke koleksi node, dan masukan yang tidak dikenali berakhir sebagai array kosong.

Typings menyederhanakan kontrak itu menjadi string | HTMLElement | HTMLElement[] src/typings/waves.d.ts:1-9⁴. Koleksi NodeList dan HTMLCollection tetap bekerja saat runtime, tetapi tidak tercantum di tipe.

Waves.init

Waves.init menerima config opsional. duration hanya disalin bila properti itu benar-benar ada pada objek ('duration' in options), dan delay mengikuti pola yang sama, sehingga { delay: 0 } tetap dihormati src/js/waves.js:472-478¹⁰.

Nilai awal itu adalah properti literal pada objek Effect src/js/waves.js:102-108¹¹. Contoh konfigurasi di dokumentasi resmi memakai duration: 500 dan delay: 200 docs/_pages/api.html:16-30¹².

Saat dipanggil, Waves.init mengambil document.body, lalu mendaftarkan mousedown pada body; bila isTouchAvailable bernilai benar, ia juga mendaftarkan touchstart, touchcancel, dan touchend src/js/waves.js:467-487⁵. Nilai isTouchAvailable dihitung sekali dari 'ontouchstart' in window src/js/waves.js:36-38¹³. Karena listener menempel di body, Waves.init cukup dipanggil sekali; perjalanan event setelah itu dibahas di Alur Efek Klik dari Event ke Elemen.

Waves.attach

Waves.attach menormalkan elements, merapikan argumen kelas, lalu menempelkan kelas waves-effect pada setiap elemen src/js/waves.js:495-521⁶. Argumen classes boleh berupa array; array itu di-join(' '), dan kelas gabungan diberi awalan satu spasi sebelum ditempel ke className. Elemen yang className-nya sudah memuat waves-effect dilewati, jadi pemanggilan berulang tidak menggandakan kelas. Untuk input dan img, TagWrapper[tagName] dijalankan lebih dulu dan element diganti element.parentElement; rinciannya ada di Pembungkusan Elemen input dan img.

Typings menandai classes sebagai opsional bertipe string | string[] src/typings/waves.d.ts:1-9⁴, sejalan dengan contoh Waves.attach('button', 'waves-light') dan Waves.attach('.box', null) docs/_pages/api.html:44-51¹⁴.

Waves.ripple

Waves.ripple menyiapkan options.wait = options.wait || 0 dan options.position = options.position || null, lalu mengirim objek mousedown sintetis { type: 'mousedown', button: 1 } ke Effect.show untuk setiap elemen src/js/waves.js:527-574⁷. Tanpa position, titik pusat dihitung dari element.clientWidth / 2 dan element.clientHeight / 2; dengan position, koordinatnya relatif terhadap elemen. Dokumentasi resmi mencatat default wait: 0 dengan keterangan null = infinite docs/_pages/api.html:64-70¹⁵, dan menegaskan elemen wajib sudah memiliki .waves-effect docs/_pages/api.html:56-62¹⁶.

Penutupan ripple dijaga oleh kondisi if (options.wait >= 0 && options.wait !== null). Nilai wait: null melewati kondisi itu, sehingga Effect.hide tidak pernah dijadwalkan. Urutan Effect.show lalu Effect.hide selengkapnya dibahas di Siklus Hidup Ripple, sedangkan perilaku pada perangkat sentuh ada di Penanganan Perangkat Touch.

Waves.calm

Waves.calm menormalkan elements lalu memanggil Effect.hide(mouseup, elements[i]) dengan objek mouseup sintetis untuk setiap elemen src/js/waves.js:579-589⁸. Effect.hide sendiri mengiterasi getElementsByClassName('waves-rippling') dan mencabut listener touchend, touchcancel, mouseup, serta mouseleave dari elemen tersebut src/js/waves.js:183-199¹⁷. Pasangan ripple dan calm biasanya dipakai untuk efek hover, seperti contoh mouseenter/mouseleave di dokumentasi docs/_pages/api.html:97-104¹⁸.

Waves.displayEffect

Waves.displayEffect adalah fallback deprecated. Fungsi itu menulis pesan Waves.displayEffect() has been deprecated and will be removed in future version. Please use Waves.init() to initialize Waves effect lewat console.error, lalu memanggil Waves.init(options) src/js/waves.js:594-597². Pemakai baru sebaiknya langsung memanggil Waves.init.

Tipings TypeScript dan selisihnya dengan runtime

Semua deklarasi memakai bentuk export function tanpa default export, dan ElementSelector didefinisikan sekali di baris pertama src/typings/waves.d.ts:1-9⁴.

⚠️ Pola resmi Waves.ripple('.box', { wait: null }) docs/_pages/api.html:97-104¹⁸ tidak lolos pemeriksaan tipe wait?: number src/typings/waves.d.ts:1-9⁴. Bila strictNullChecks aktif, TypeScript menandai argumen null sebagai tidak sesuai tipe. Hal yang sama berlaku untuk Waves.attach yang menerima NodeList saat runtime tetapi tidak di tipe mana pun. Perlebar tipe di proyek pemanggil, atau lewati argumen lewat variabel bertipe lebih longgar.