horeg-audio 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario (ryomario)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,13 +12,16 @@
 
 ## ✨ Fitur Utama
 
-- **Zero CSS Leakage**: Menggunakan native **Shadow DOM** (`mode: 'open'`) sehingga style pemutar musik 100% terisolasi dari stylesheet proyek induk (kompatibel dengan Tailwind, Bootstrap, mau pun framework apa pun).
-- **Sound Horeg Aesthetics**: Desain box speaker subwoofer panggung, grill tekstur radial, baut sudut industrial, dan tombol play dengan animasi neon pulse.
-- **Dynamic EQ / VU Visualizer**: Bar equalizer mini dinamis yang responsif saat audio diputar.
-- **Multi-Track Playlist & Rack Drawer**: Panel drawer geser bertema *rack mount audio* dengan antrean trek dan penanda lagu aktif.
-- **Micro Bundle**: Berukuran di bawah **10 KB** (gzip) dengan zero third-party runtime dependencies.
-- **Full Keyboard & ARIA a11y**: Navigasi ramah aksesibilitas (Space untuk toggle play, panah untuk seek dan volume).
-- **Universal Distribution**: Siap pakai via NPM (ESM, CJS, TypeScript `.d.ts`) maupun CDN tag `<script src="...">`.
+- **Zero CSS Leakage**: Menggunakan native **Shadow DOM** (`mode: 'open'`) sehingga style pemutar musik 100% terisolasi dari stylesheet proyek induk tanpa perlu file CSS terpisah (aman dipadukan dengan Tailwind, Bootstrap, Bulma, atau CSS global apa pun).
+- **Sound Horeg Aesthetics**: Desain box speaker subwoofer panggung, grill tekstur radial, baut sudut industrial, dan tombol play dengan animasi neon glow pulse.
+- **Real-time Scrubbing & Cursor Grab**: Geser timeline lagu secara instan dan *real-time* tanpa jeda animasi (`transition: none !important`), dengan respon kursor `cursor: grab` saat diarahkan dan `cursor: grabbing` saat menggeser track.
+- **6 Presets Tema (Dark & Light Mode)**: Pilihan tema gelap dan terang siap pakai yang otomatis menyesuaikan seluruh palet komponen internal (cabinet, surface, drawer, fader, dan soft elevation shadows).
+- **Dynamic EQ / VU Visualizer**: Bar equalizer mini dinamis multi-band yang responsif bergerak saat audio diputar.
+- **Multi-Track Playlist & Rack Drawer**: Panel drawer geser bertema *rack mount audio* dengan antrean trek, nomor urut, durasi, dan tombol hapus lagu.
+- **Dukungan File Lokal & Audio URL**: Tambahkan trek audio komputer (.mp3, .wav, .flac, .ogg, .m4a) secara instan via file dialog maupun drag-and-drop langsung ke player, serta form tambah audio streaming URL online.
+- **Zero Third-Party Dependencies**: Berbasis TypeScript / JavaScript murni tanpa ketergantungan library luar (*micro bundle* ~14 KB gzip).
+- **Full Keyboard & ARIA a11y**: Navigasi ramah aksesibilitas keyboard (`Space`, panah kiri/kanan untuk seek, panah atas/bawah untuk volume).
+- **Universal Distribution**: Siap pakai via NPM (ESM, CJS, TypeScript `.d.ts`), CDN browser tag `<script src="...">`, maupun native browser `<script type="module">`.
 
 ---
 
@@ -30,17 +33,25 @@ Gunakan **pnpm** (atau package manager pilihan Anda):
 pnpm add horeg-audio
 ```
 
+Atau menggunakan npm / yarn:
+
+```bash
+npm install horeg-audio
+# atau
+yarn add horeg-audio
+```
+
 ---
 
 ## 🚀 Cara Penggunaan
 
-### 1. Modern Frameworks & Bundlers (ESM / TypeScript)
+### 1. Modern Frameworks & Bundlers (ESM / TypeScript / Vite / Next.js)
 
 ```typescript
 import { HoregAudio } from 'horeg-audio';
 
 const player = new HoregAudio({
-  container: '#music-player',
+  container: '#music-player', // Selektor string atau HTMLElement
   playlist: [
     {
       id: 1,
@@ -59,55 +70,172 @@ const player = new HoregAudio({
     }
   ],
   theme: {
-    variant: 'horeg-classic',
-    primaryGlowColor: '#f59e0b'
+    variant: 'horeg-classic'
   },
+  autoplay: false,
+  volume: 0.8,
+  loop: 'all',
   onPlay: (track) => console.log('Playing:', track.title),
-  onPause: () => console.log('Paused')
+  onPause: () => console.log('Paused'),
+  onTrackChange: (track, index) => console.log(`Track #${index + 1}: ${track.title}`)
 });
 ```
 
+---
+
 ### 2. Browser Langsung via CDN (IIFE / Global Script)
 
+Anda dapat langsung menggunakan `horeg-audio` pada file HTML biasa **tanpa bundler atau build step** (*zero-config*). 
+
+> [!NOTE]
+> **Tidak membutuhkan link stylesheet/CSS terpisah!** Seluruh style visual, ikon SVG, dan animasi dirangkum mandiri di dalam Shadow DOM internal pemutar.
+
+#### Opsi A: Tag `<script>` Tradisional (Global `window.HoregAudio`)
+
+Saat file script dimuat, class `HoregAudio` otomatis didaftarkan ke objek `window`:
+
 ```html
-<!-- Container di HTML -->
-<div id="player-container"></div>
+<!DOCTYPE html>
+<html lang="id">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Horeg Audio Player</title>
+  <style>
+    body {
+      background-color: #0b0c10;
+      color: #f4f4f5;
+      font-family: sans-serif;
+      padding: 40px 16px;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+    }
+  </style>
+</head>
+<body>
+
+  <!-- 1. Elemen mount player -->
+  <div id="player-mount" style="max-width: 520px; width: 100%;"></div>
+
+  <!-- 2. Muat Script Bundle IIFE (Pilih salah satu CDN atau file lokal) -->
+  <!-- Via jsDelivr CDN: -->
+  <script src="https://cdn.jsdelivr.net/npm/horeg-audio/dist/horeg-audio.global.js"></script>
+  <!-- Atau via unpkg CDN: -->
+  <!-- <script src="https://unpkg.com/horeg-audio/dist/horeg-audio.global.js"></script> -->
+  <!-- Atau dari folder lokal repository: -->
+  <!-- <script src="./dist/horeg-audio.global.js"></script> -->
+
+  <!-- 3. Inisialisasi Player -->
+  <script>
+    document.addEventListener('DOMContentLoaded', function () {
+      // Inisialisasi HoregAudio global
+      const player = new HoregAudio({
+        container: '#player-mount', // Selektor CSS string atau elemen DOM langsung
+        playlist: [
+          {
+            id: 1,
+            title: 'Bass Horeg Jedag-Jedug Extreme',
+            artist: 'DJ Riswanda Karnaval',
+            album: 'Festival Sound Jatim 2026',
+            src: 'https://cdn.example.com/audio/horeg-bass.mp3',
+            coverArt: 'https://cdn.example.com/images/cover.jpg',
+            duration: 215
+          },
+          {
+            id: 2,
+            title: 'Karnaval Audio Rig Battle',
+            artist: 'Brewog Audio Master',
+            src: 'https://cdn.example.com/audio/karnaval.mp3'
+          }
+        ],
+        theme: {
+          variant: 'horeg-classic' // 'horeg-classic' | 'horeg-nightclub' | 'horeg-stealth' | 'horeg-light' | 'horeg-light-clean' | 'horeg-light-minimal'
+        },
+        volume: 0.85,
+        autoplay: false,
+        loop: 'all',
+        onPlay: function (track) {
+          console.log('Sedang memutar:', track.title);
+        },
+        onTimeUpdate: function (currentTime, duration) {
+          // Detik realtime
+        }
+      });
+
+      // Kontrol pemutar secara dinamis via JavaScript:
+      // player.play();
+      // player.pause();
+      // player.setTheme({ variant: 'horeg-light' });
+
+      // Mengakses daftar preset tema bawaan dari properti statis:
+      console.log('Preset yang tersedia:', HoregAudio.THEME_PRESETS);
+    });
+  </script>
+</body>
+</html>
+```
+
+#### Opsi B: Menggunakan Native Browser ES Module (`<script type="module">`)
+
+Untuk browser modern, Anda juga dapat mengimpor langsung versi ESM via CDN tanpa proses bundling:
+
+```html
+<div id="player-mount"></div>
+
+<script type="module">
+  import HoregAudio, { THEME_PRESETS } from 'https://cdn.jsdelivr.net/npm/horeg-audio/dist/horeg-audio.js';
 
-<!-- Load Script -->
-<script src="https://cdn.jsdelivr.net/npm/horeg-audio/dist/horeg-audio.global.js"></script>
-<script>
   const player = new HoregAudio({
-    container: '#player-container',
+    container: '#player-mount',
     playlist: [
       {
-        title: 'Karnaval Audio Battle',
-        artist: 'Horeg Team',
+        title: 'Karnaval Sound Horeg',
+        artist: 'Audio Crew',
         src: 'https://example.com/audio.mp3'
       }
-    ]
+    ],
+    theme: {
+      variant: 'horeg-light'
+    }
   });
 </script>
 ```
 
 ---
 
-## 🎨 Tema Preset (Sound Horeg Edition)
+## 🎨 Tema Preset (Dark & Light Edition)
 
-| Preset Variant | Deskripsi | Warna Utama |
-|---|---|---|
-| `horeg-classic` | Hitam matte khas box speaker + aksen amber neon karnaval | `#f59e0b` |
-| `horeg-nightclub` | Cyberpunk night vibe dengan aksen neon cyan & strobe magenta | `#06b6d4` & `#ec4899` |
-| `horeg-stealth` | Monokrom taktis metalik dan aksen perak | `#94a3b8` |
+Tersedia 6 varian tema siap pakai yang secara otomatis mengonfigurasi seluruh aspek visual player:
 
-Contoh kustomisasi tema dinamis:
+| Preset Variant | Mode | Deskripsi | Warna Glow / Aksen | Background / Teks |
+|---|---|---|---|---|
+| `horeg-classic` | Dark | Hitam matte box subwoofer + aksen amber neon karnaval | `#f59e0b` & `#ef4444` | `#121214` / `#f4f4f5` |
+| `horeg-nightclub` | Dark | Cyberpunk club vibe dengan aksen neon cyan & strobe pink | `#06b6d4` & `#ec4899` | `#0b0c10` / `#f8fafc` |
+| `horeg-stealth` | Dark | Monokrom taktis metalik dan aksen perak industrial | `#94a3b8` & `#e2e8f0` | `#0f1115` / `#e2e8f0` |
+| `horeg-light` | Light | Horeg Daylight Rig putih bersih dengan aksen amber & red punch | `#d97706` & `#dc2626` | `#ffffff` / `#0f172a` |
+| `horeg-light-clean` | Light | Studio white modern dengan aksen neon sky blue & pink | `#0284c7` & `#db2777` | `#ffffff` / `#0f172a` |
+| `horeg-light-minimal` | Light | Minimalist industrial slate dengan aksen royal cobalt | `#475569` & `#2563eb` | `#f8fafc` / `#1e293b` |
+
+### Mengubah Tema Secara Dinamis (`player.setTheme`)
+
+Saat `setTheme({ variant })` dipanggil, seluruh atribut warna preset baru langsung diterapkan secara utuh:
 
 ```typescript
+// Beralih ke tema Light Mode
+player.setTheme({
+  variant: 'horeg-light'
+});
+
+// Beralih ke tema Nightclub dengan kustomisasi warna aksen khusus
 player.setTheme({
   variant: 'horeg-nightclub',
-  primaryGlowColor: '#06b6d4',
-  accentColor: '#ec4899',
+  primaryGlowColor: '#00f2fe',
   borderRadius: '16px'
 });
+
+// Melihat konfigurasi tema yang sedang aktif
+console.log(player.getTheme());
 ```
 
 ---
@@ -118,14 +246,14 @@ player.setTheme({
 
 ```typescript
 interface HoregPlayerOptions {
-  container: string | HTMLElement;  // Target selector atau elemen DOM
-  playlist: Track[];                // Daftar lagu
+  container: string | HTMLElement;  // Target CSS selektor atau elemen DOM
+  playlist: Track[];                // Daftar lagu awal
   initialIndex?: number;            // Indeks lagu awal (default: 0)
-  autoplay?: boolean;               // Otomatis memutar lagu
+  autoplay?: boolean;               // Otomatis memutar saat dimuat (default: false)
   loop?: 'none' | 'all' | 'one';    // Mode perulangan (default: 'all')
   shuffle?: boolean;                // Acak urutan lagu (default: false)
   volume?: number;                  // Level volume 0.0 - 1.0 (default: 0.8)
-  theme?: HoregTheme;               // Konfigurasi tema
+  theme?: HoregTheme;               // Konfigurasi tema awal
   onPlay?: (track: Track) => void;
   onPause?: () => void;
   onTrackChange?: (track: Track, index: number) => void;
@@ -136,25 +264,31 @@ interface HoregPlayerOptions {
 }
 ```
 
-### Metode Publik
+### Metode Publik (`player.*`)
 
-- `player.play(): Promise<void>` - Memutar lagu.
-- `player.pause(): void` - Menjeda audio.
-- `player.toggle(): void` - Toggle play/pause.
+- `player.play(): Promise<void>` - Memutar lagu aktif.
+- `player.pause(): void` - Menjeda pemutaran.
+- `player.toggle(): void` - Toggle play / pause.
 - `player.next(): void` - Berpindah ke lagu berikutnya.
 - `player.prev(): void` - Kembali ke awal lagu atau lagu sebelumnya.
-- `player.seek(seconds: number): void` - Lompat ke detik tertentu.
+- `player.seek(seconds: number): void` - Lompat ke detik pemutaran tertentu secara instan.
 - `player.setVolume(level: number): void` - Mengatur volume (`0.0` sampai `1.0`).
-- `player.loadTrack(indexOrTrack: number | Track): void` - Memuat trek tertentu.
-- `player.addTrack(track: Track, autoPlay?: boolean): number` - Menambahkan lagu ke playlist.
+- `player.loadTrack(indexOrTrack: number | Track, autoPlay?: boolean): void` - Memuat trek tertentu.
+- `player.addTrack(track: Track, autoPlay?: boolean): number` - Menambahkan satu lagu ke playlist.
 - `player.addTracks(tracks: Track[], autoPlay?: boolean): void` - Menambahkan kumpulan lagu ke playlist.
-- `player.addTrackFromFile(file: File, autoPlay?: boolean): Promise<Track>` - Menambahkan lagu dari file lokal komputer (otomatis ekstrak nama dan durasi).
+- `player.addTrackFromFile(file: File, autoPlay?: boolean): Promise<Track>` - Menambahkan lagu dari file lokal komputer (otomatis ekstrak nama file dan durasi).
 - `player.addTrackFromFiles(files: FileList | File[], autoPlay?: boolean): Promise<Track[]>` - Menambahkan banyak file audio lokal sekaligus.
-- `player.addTrackFromUrl(url: string, meta?: Partial<Track>, autoPlay?: boolean): Promise<Track>` - Menambahkan lagu dari URL online/streaming.
+- `player.addTrackFromUrl(url: string, meta?: Partial<Track>, autoPlay?: boolean): Promise<Track>` - Menambahkan lagu dari tautan audio streaming URL.
 - `player.removeTrack(index: number): void` - Menghapus lagu dari playlist berdasarkan indeks.
-- `player.getPlaylist(): Track[]` - Mengambil daftar lagu saat ini.
-- `player.setTheme(themeConfig: Partial<HoregTheme>): void` - Mengganti tema secara realtime.
-- `player.destroy(): void` - Membersihkan event listeners, audio stream, dan DOM Shadow Root.
+- `player.getPlaylist(): Track[]` - Mengambil daftar seluruh lagu di playlist saat ini.
+- `player.setTheme(themeConfig: Partial<HoregTheme>): void` - Mengganti tema atau properti warna secara realtime.
+- `player.getTheme(): HoregTheme` - Mengambil konfigurasi tema yang sedang diterapkan.
+- `player.destroy(): void` - Membersihkan seluruh audio stream, event listener global, dan menghapus DOM Shadow Root.
+
+### Properti & Fungsi Statis (`HoregAudio.*`)
+
+- `HoregAudio.THEME_PRESETS` - Objek kamus preset tema bawaan (`Record<ThemeVariant, Partial<HoregTheme>>`).
+- `HoregAudio.generateStyles(theme?)` - Fungsi generator string CSS Shadow DOM terenkapsulasi.
 
 ---
 
@@ -186,5 +320,7 @@ pnpm run build
 
 ## 📄 Lisensi
 
-MIT License © 2026.
+Didistribusikan di bawah Lisensi MIT. Lihat berkas [`LICENSE`](LICENSE) untuk informasi lebih lanjut.
+
+Copyright © 2026 Mario ([@ryomario](https://github.com/ryomario)).