@libs-ui/components-audio 0.2.190 → 0.2.191

package/README.md

@@ -1,109 +1,352 @@
-# Component Audio
+# Audio Component
+
+## Giới thiệu
+
+`audio` là một component mạnh mẽ dùng để phát âm thanh trong ứng dụng Angular. Component này cung cấp giao diện đơn giản để phát, tạm dừng và điều khiển các tệp âm thanh với nhiều tính năng.
 
 ## Tính năng
 
-- Control play/pause âm thanh
-- Control âm lượng với chức năng mute
+- Phát/tạm dừng âm thanh
+- Điều chỉnh âm lượng với chức năng tắt/bật tiếng
 - Hiển thị thời gian theo định dạng HH:MM:SS
-- Progress bar với chức năng seek
-- Khả năng download audio với permission control
-- Thiết kế responsive sử dụng Tailwind CSS
+- Thanh tiến độ với chức năng tua nhanh/tua lại
+- Tải xuống audio với kiểm soát quyền
+- Function Control API cho phép điều khiển từ bên ngoài
+- Thiết kế responsive
 - Source audio có thể cấu hình
 
 ## Cài đặt
 
+Để cài đặt component `audio`, sử dụng npm hoặc yarn:
+
 ```bash
 npm install @libs-ui/components-audio
 ```
 
-## Cách sử dụng cơ bản
+hoặc
 
-Import component vào module hoặc standalone component của bạn:
+```bash
+yarn add @libs-ui/components-audio
+```
+
+## Sử dụng
+
+### Import module
 
 ```typescript
 import { LibsUiComponentsAudioComponent } from '@libs-ui/components-audio';
 
+@NgModule({
+  declarations: [
+    AppComponent
+  ],
+  imports: [
+    BrowserModule,
+    LibsUiComponentsAudioComponent
+  ],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+Hoặc trong component standalone:
+
+```typescript
+import { Component } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { LibsUiComponentsAudioComponent } from '@libs-ui/components-audio';
+import { IAudioFunctionControlEvent } from '@libs-ui/components-audio';
+
 @Component({
-  selector: 'your-component',
+  selector: 'app-example',
   standalone: true,
-  imports: [LibsUiComponentsAudioComponent],
+  imports: [CommonModule, LibsUiComponentsAudioComponent],
   template: `
     <libs_ui-components-audio
-      fileAudio="https://example.com/audio.mp3"
+      [fileAudio]="audioSource"
       [checkPermissionDownloadAudio]="checkDownloadPermission"
-    />
+      (outFunctionsControl)="registerFunctions($event)">
+    </libs_ui-components-audio>
+    
+    <div class="controls">
+      <button (click)="playAudio()">Phát/Tạm dừng</button>
+      <button (click)="toggleMute()">Bật/Tắt tiếng</button>
+    </div>
   `
 })
-export class YourComponent {
+export class ExampleComponent {
+  audioSource = 'path/to/audio/file.mp3';
+  functionControls: IAudioFunctionControlEvent | null = null;
+
   checkDownloadPermission(): Promise<boolean> {
-    // Your logic to determine if download is allowed
+    // Kiểm tra quyền download
     return Promise.resolve(true);
   }
+  
+  registerFunctions(event: IAudioFunctionControlEvent) {
+    this.functionControls = event;
+  }
+  
+  playAudio() {
+    if (this.functionControls) {
+      this.functionControls.playPause();
+    }
+  }
+  
+  toggleMute() {
+    if (this.functionControls) {
+      this.functionControls.toggleMute();
+    }
+  }
 }
 ```
 
-## Inputs
+## API Reference
 
-| Input | Type | Required | Description |
-|-------|------|----------|-------------|
-| `fileAudio` | `string` | Yes | URL của file audio cần phát |
-| `checkPermissionDownloadAudio` | `() => Promise<boolean>` | Yes | Function trả về promise với kết quả boolean cho biết nếu được phép download |
+### Inputs
 
-## UI Features
+| Input                          | Type                | Description                                          |
+|--------------------------------|---------------------|------------------------------------------------------|
+| fileAudio                      | string              | URL của file audio cần phát                          |
+| checkPermissionDownloadAudio   | () => Promise<boolean> | Function trả về promise với kết quả boolean cho biết nếu được phép download |
 
-### Audio Controls
-- Button play/pause
-- Hiển thị current time và duration (định dạng HH:MM:SS)
-- Progress bar với chức năng seek
+### Outputs
 
-### Volume Controls
-- Button mute/unmute
-- Volume slider (hiển thị khi hover)
+| Output              | Type                        | Description                                      |
+|---------------------|----------------------------|--------------------------------------------------|
+| outFunctionsControl | IAudioFunctionControlEvent | Event chứa các hàm điều khiển của audio component |
+| outVolumeControl    | number                     | Phát ra giá trị âm lượng hiện tại (0-100)        |
+| outTimeUpdate       | { currentTime: string, duration: string } | Phát ra thông tin thời gian hiện tại và tổng thời gian |
+| outEnded            | void                       | Phát ra khi audio kết thúc phát                  |
+| outMute             | boolean                    | Phát ra trạng thái tắt/bật tiếng                |
+| outPlay             | boolean                    | Phát ra trạng thái phát/tạm dừng                |
 
-### Download
-- Button download cần kiểm tra permission
+### Methods (Available through outFunctionsControl)
 
-## CSS Classes
+| Method            | Parameters    | Return Type | Description                                         |
+|-------------------|---------------|-------------|-----------------------------------------------------|
+| playPause         | event?: Event | void        | Bắt đầu/tạm dừng phát audio                        |
+| toggleMute        | event?: Event | void        | Bật/tắt âm thanh                                    |
+| setVolume         | value: number | void        | Điều chỉnh âm lượng (từ 0 đến 100)                   |
+| seekTo            | value: number | void        | Di chuyển đến vị trí cụ thể trong audio (0-100)     |
+| download          | event?: Event | void        | Tải xuống file audio                                |
+| isPlaying         | -             | boolean     | Kiểm tra trạng thái đang phát audio                 |
+| isMuted           | -             | boolean     | Kiểm tra trạng thái tắt tiếng                       |
 
-Component sử dụng các class của Tailwind và các custom icon classes:
+## Interfaces
 
-- `.libs-ui-disable` - Áp dụng cho player bị disabled
-- `.pointer-events-none` - Áp dụng khi player bị disabled
-- `.libs-ui-font-h5r` - Áp dụng cho time display
-- `.libs-ui-icon-play-solid` - Icon play
-- `.libs-ui-icon-pause-solid` - Icon pause
-- `.libs-ui-icon-speaker-on-solid` - Icon speaker (volume on)
-- `.libs-ui-icon-speaker-off-solid` - Icon speaker (volume off/mute)
-- `.libs-ui-icon-download-solid` - Icon download
+```typescript
+// Audio Function Control Event
+interface IAudioFunctionControlEvent {
+  playPause: (event?: Event) => void;
+  toggleMute: (event?: Event) => void;
+  setVolume: (value: number) => void;
+  seekTo: (value: number) => void;
+  download: (event?: Event) => void;
+  isPlaying: () => boolean;
+  isMuted: () => boolean;
+}
+```
 
-## Dependencies
+## Styling Volume Slider
 
-- Angular 16+
-- RxJS
-- @libs-ui/components-inputs-range-slider
+Để tạo hiệu ứng thanh trượt âm lượng có màu nền thay đổi theo giá trị, bạn có thể sử dụng CSS variables:
 
-## Example Implementation
+```css
+/* Định nghĩa thanh trượt âm lượng */
+input[type="range"].volume-slider {
+  background: linear-gradient(to right, #3b82f6 var(--volume-percent, 50%), #e5e7eb var(--volume-percent, 50%));
+}
+
+/* Track styling cho WebKit browsers */
+input[type="range"].volume-slider::-webkit-slider-runnable-track {
+  background: linear-gradient(to right, #3b82f6 var(--volume-percent, 50%), #e5e7eb var(--volume-percent, 50%));
+}
+
+/* Track styling cho Firefox */
+input[type="range"].volume-slider::-moz-range-track {
+  background: linear-gradient(to right, #3b82f6 var(--volume-percent, 50%), #e5e7eb var(--volume-percent, 50%));
+}
+```
+
+Và trong template:
+
+```html
+<input type="range"
+  min="0"
+  max="100"
+  [value]="volumePercent()"
+  (input)="changeVolume($event)"
+  class="volume-slider"
+  [style.--volume-percent.%]="volumePercent()">
+```
+
+## Ví dụ
+
+### Sử dụng Function Control
 
 ```typescript
+import { Component, signal, computed } from '@angular/core';
+import { IAudioFunctionControlEvent } from '@libs-ui/components-audio';
+
 @Component({
-  selector: 'app-audio-player',
-  standalone: true,
-  imports: [LibsUiComponentsAudioComponent],
+  selector: 'app-example',
   template: `
     <libs_ui-components-audio
-      fileAudio="https://example.com/audio.mp3"
+      [fileAudio]="audioSource()"
       [checkPermissionDownloadAudio]="checkDownloadPermission"
-    />
+      (outFunctionsControl)="registerFunctions($event)">
+    </libs_ui-components-audio>
+    
+    <div class="audio-controls">
+      <button (click)="playPauseAudio()">{{ isPlaying() ? 'Tạm dừng' : 'Phát' }}</button>
+      <button (click)="toggleMuteAudio()">{{ isMuted() ? 'Bật tiếng' : 'Tắt tiếng' }}</button>
+      <div class="volume-control">
+        <span>Âm lượng:</span>
+        <input type="range" 
+          min="0" 
+          max="100" 
+          [value]="volumePercent()" 
+          (input)="changeVolume($event)"
+          class="volume-slider"
+          [style.--volume-percent.%]="volumePercent()">
+        <span>{{ volumePercent() }}%</span>
+      </div>
+      <div class="progress-control">
+        <span>Tiến độ:</span>
+        <input type="range" 
+          min="0" 
+          max="100" 
+          [value]="progress()" 
+          (input)="changeProgress($event)">
+        <span>{{ progress() }}%</span>
+      </div>
+      <button (click)="downloadAudio()">Tải xuống</button>
+    </div>
   `
 })
-export class AudioPlayerComponent {
-  checkDownloadPermission(): Promise<boolean> {
-    // Example implementation - can be replaced with actual permission logic
-    return new Promise(resolve => {
-      // Check user permissions, authentication, or any other business logic
-      const isAllowed = true;
-      resolve(isAllowed);
-    });
+export class ExampleComponent {
+  audioSource = signal('path/to/audio.mp3');
+  functionControls: IAudioFunctionControlEvent | null = null;
+  isPlaying = signal(false);
+  isMuted = signal(false);
+  volume = signal(80);
+  progress = signal(0);
+  
+  // Computed properties
+  volumePercent = computed(() => Math.round(this.volume()));
+
+  checkDownloadPermission = (): Promise<boolean> => {
+    return Promise.resolve(true);
+  }
+
+  registerFunctions(event: IAudioFunctionControlEvent) {
+    this.functionControls = event;
+    
+    // Initialize state
+    if (this.functionControls) {
+      this.isPlaying.set(this.functionControls.isPlaying());
+      this.isMuted.set(this.functionControls.isMuted());
+    }
+  }
+
+  playPauseAudio() {
+    if (this.functionControls) {
+      this.functionControls.playPause();
+      this.isPlaying.set(this.functionControls.isPlaying());
+    }
+  }
+
+  toggleMuteAudio() {
+    if (this.functionControls) {
+      this.functionControls.toggleMute();
+      this.isMuted.set(this.functionControls.isMuted());
+    }
+  }
+
+  changeVolume(event: Event) {
+    if (this.functionControls && event.target) {
+      const value = parseInt((event.target as HTMLInputElement).value);
+      this.volume.set(value);
+      this.functionControls.setVolume(value / 100); // Convert to 0-1 range
+    }
+  }
+
+  changeProgress(event: Event) {
+    if (this.functionControls && event.target) {
+      const value = parseInt((event.target as HTMLInputElement).value);
+      this.progress.set(value);
+      this.functionControls.seekTo(value);
+    }
+  }
+
+  downloadAudio() {
+    if (this.functionControls) {
+      this.functionControls.download();
+    }
   }
 }
 ```
+
+### Sử dụng Events
+
+Sử dụng các events để phản ứng với thay đổi từ audio player:
+
+```typescript
+import { Component, signal } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <libs_ui-components-audio
+      [fileAudio]="audioSource()"
+      [checkPermissionDownloadAudio]="checkPermission"
+      (outTimeUpdate)="handleTimeUpdate($event)"
+      (outVolumeControl)="handleVolumeChange($event)" 
+      (outPlay)="handlePlayChange($event)"
+      (outMute)="handleMuteChange($event)"
+      (outEnded)="handleEnded()">
+    </libs_ui-components-audio>
+    
+    <div class="audio-info">
+      <p>Trạng thái: {{ isPlaying() ? 'Đang phát' : 'Tạm dừng' }}</p>
+      <p>Thời gian hiện tại: {{ currentTime() }}</p>
+      <p>Tổng thời gian: {{ duration() }}</p>
+      <p>Âm lượng: {{ volumeLevel() }}%</p>
+    </div>
+  `
+})
+export class ExampleComponent {
+  audioSource = signal('path/to/audio.mp3');
+  isPlaying = signal(false);
+  isMuted = signal(false);
+  currentTime = signal('00:00:00');
+  duration = signal('00:00:00');
+  volumeLevel = signal(100);
+  
+  checkPermission = (): Promise<boolean> => {
+    return Promise.resolve(true);
+  }
+  
+  handleTimeUpdate(timeInfo: { currentTime: string, duration: string }) {
+    this.currentTime.set(timeInfo.currentTime);
+    this.duration.set(timeInfo.duration);
+  }
+  
+  handleVolumeChange(volume: number) {
+    this.volumeLevel.set(volume);
+  }
+  
+  handlePlayChange(isPlaying: boolean) {
+    this.isPlaying.set(isPlaying);
+  }
+  
+  handleMuteChange(isMuted: boolean) {
+    this.isMuted.set(isMuted);
+  }
+  
+  handleEnded() {
+    this.isPlaying.set(false);
+  }
+}
+```

package/audio.component.d.ts

@@ -1,4 +1,5 @@
 import { AfterViewInit, ElementRef, OnDestroy } from '@angular/core';
+import { IAudioFunctionControlEvent } from './interfaces/function-control-event.interface';
 import * as i0 from "@angular/core";
 export declare class LibsUiComponentsAudioComponent implements AfterViewInit, OnDestroy {
     protected audioRatioValue: import("@angular/core").WritableSignal<number>;
@@ -15,19 +16,29 @@ export declare class LibsUiComponentsAudioComponent implements AfterViewInit, On
     readonly checkPermissionDownloadAudio: import("@angular/core").InputSignal<() => Promise<boolean>>;
     readonly audioRef: import("@angular/core").Signal<ElementRef<any>>;
     readonly volumeControlRef: import("@angular/core").Signal<ElementRef<any>>;
+    readonly outFunctionsControl: import("@angular/core").OutputEmitterRef<IAudioFunctionControlEvent>;
+    readonly outVolumeControl: import("@angular/core").OutputEmitterRef<number>;
+    readonly outTimeUpdate: import("@angular/core").OutputEmitterRef<{
+        currentTime: string;
+        duration: string;
+    }>;
+    readonly outEnded: import("@angular/core").OutputEmitterRef<void>;
+    readonly outMute: import("@angular/core").OutputEmitterRef<boolean>;
+    readonly outPlay: import("@angular/core").OutputEmitterRef<boolean>;
+    constructor();
     ngAfterViewInit(): void;
     private initObservable;
     protected handlerKeyPressAudio(): Promise<void>;
-    protected handlerAudioMuteMuted(event: Event): Promise<void>;
-    protected handlerAudioPausePlay(event: Event): Promise<void>;
+    protected handlerAudioMuteMuted(event?: Event): Promise<void>;
+    protected handlerAudioPausePlay(event?: Event): Promise<void>;
     protected handlerLoadedData(event: Event): Promise<void>;
-    protected handlerTimeUpdate(event: Event): Promise<void>;
+    protected handlerTimeUpdate(event?: Event): Promise<void>;
     private toHHMMSS;
     protected handlerChangeAudio(value: number): Promise<void>;
     protected handlerChangeVolume(value: number): Promise<void>;
     protected handlerEnded(event: Event): Promise<void>;
-    protected handlerDownload(e: Event): Promise<void>;
+    protected handlerDownload(e?: Event): Promise<void>;
     ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<LibsUiComponentsAudioComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiComponentsAudioComponent, "libs_ui-components-audio", never, { "fileAudio": { "alias": "fileAudio"; "required": true; "isSignal": true; }; "checkPermissionDownloadAudio": { "alias": "checkPermissionDownloadAudio"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiComponentsAudioComponent, "libs_ui-components-audio", never, { "fileAudio": { "alias": "fileAudio"; "required": true; "isSignal": true; }; "checkPermissionDownloadAudio": { "alias": "checkPermissionDownloadAudio"; "required": true; "isSignal": true; }; }, { "outFunctionsControl": "outFunctionsControl"; "outVolumeControl": "outVolumeControl"; "outTimeUpdate": "outTimeUpdate"; "outEnded": "outEnded"; "outMute": "outMute"; "outPlay": "outPlay"; }, never, never, true, never>;
 }

package/demo/audio-demo.component.d.ts

@@ -0,0 +1,112 @@
+import { LibsUiComponentsAudioComponent } from '../audio.component';
+import { IAudioFunctionControlEvent } from '../interfaces/function-control-event.interface';
+import * as i0 from "@angular/core";
+export declare class LibsUiComponentsAudioDemoComponent {
+    audioPlayer: LibsUiComponentsAudioComponent;
+    isPlaying: import("@angular/core").WritableSignal<boolean>;
+    isMuted: import("@angular/core").WritableSignal<boolean>;
+    volume: import("@angular/core").WritableSignal<number>;
+    currentTime: import("@angular/core").WritableSignal<string>;
+    duration: import("@angular/core").WritableSignal<string>;
+    progress: import("@angular/core").WritableSignal<number>;
+    volumePercent: import("@angular/core").Signal<number>;
+    selectedAudio: import("@angular/core").WritableSignal<number>;
+    currentAudioSource: import("@angular/core").WritableSignal<string>;
+    functionControls: IAudioFunctionControlEvent | null;
+    audioSamples: import("@angular/core").WritableSignal<{
+        id: number;
+        name: string;
+        src: string;
+        duration: string;
+    }[]>;
+    inputsDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        type: string;
+        default: string;
+        description: string;
+    }[]>;
+    outputsDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        type: string;
+        description: string;
+    }[]>;
+    interfacesDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        description: string;
+        properties: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+    }[]>;
+    methodsDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        params: string;
+        returnType: string;
+        description: string;
+    }[]>;
+    features: import("@angular/core").WritableSignal<{
+        id: number;
+        icon: string;
+        title: string;
+        description: string;
+    }[]>;
+    codeExamples: import("@angular/core").WritableSignal<{
+        id: number;
+        title: string;
+        code: string;
+    }[]>;
+    playAudio(): void;
+    toggleMute(): void;
+    changeVolume(event: Event): void;
+    downloadAudio(): void;
+    /**
+     * Format thời gian từ giây sang chuỗi HH:MM:SS
+     */
+    formatTime(timeInSeconds: number): string;
+    /**
+     * Sao chép text vào clipboard
+     */
+    copyToClipboard(text: string): void;
+    /**
+     * Đăng ký các function control từ component
+     */
+    registerFunctions(event: IAudioFunctionControlEvent): void;
+    /**
+     * Xử lý sự kiện thay đổi thời gian
+     */
+    handleTimeUpdate(timeInfo: {
+        currentTime: string;
+        duration: string;
+    }): void;
+    /**
+     * Xử lý sự kiện thay đổi âm lượng
+     */
+    handleVolumeChange(volume: number): void;
+    /**
+     * Xử lý sự kiện thay đổi trạng thái phát
+     */
+    handlePlayChange(isPlaying: boolean): void;
+    /**
+     * Xử lý sự kiện thay đổi trạng thái tắt tiếng
+     */
+    handleMuteChange(isMuted: boolean): void;
+    /**
+     * Xử lý sự kiện kết thúc phát
+     */
+    handleEnded(): void;
+    /**
+     * Chọn mẫu âm thanh
+     */
+    selectAudio(id: number): void;
+    /**
+     * Kiểm tra quyền tải xuống
+     */
+    checkDownloadPermission: () => Promise<boolean>;
+    /**
+     * Thay đổi vị trí phát bằng cách click trực tiếp vào thanh tiến độ
+     */
+    seekAudioByClick(event: MouseEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LibsUiComponentsAudioDemoComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiComponentsAudioDemoComponent, "lib-audio-demo", never, {}, {}, never, never, true, never>;
+}