ng-images-preview 1.0.3 → 2.0.1

package/README.md

@@ -28,12 +28,16 @@ Check out the component in action: **[https://lanxuexing.github.io/ng-images-pre
 - 🎨 **Vanilla CSS**: Zero dependencies, fully customizable via CSS variables.
 - 🖼️ **Multi-Image Gallery**: Navigate through a list of images with arrows or swipe gestures.
 - 📱 **Mobile Ready**: Swipe to navigate, double-tap to zoom, pinch-to-zoom gestures.
+- 👆 **Pull-to-Close**: Drag down to close the preview (like native apps).
+- 🎞️ **Thumbnail Strip**: Quick preview and navigation with an auto-scrolling strip.
+- 🧩 **Toolbar Extensions**: Inject custom buttons (like Download) into the toolbar.
+- 🤝 **Hybrid Support**: Fully compatible with both Standalone and NgModule-based apps.
 - ⌨️ **Keyboard Support**: Arrow keys to navigate, ESC to close.
 - 🔍 **Zoom & Pan**: Smooth zooming and panning interactions.
 - 🔄 **Rotate & Flip**: Built-in toolbar for image manipulation.
-- 🧩 **Custom Template**: Complete control over the preview UI via `ng-template`.
+- 🎨 **Custom Template**: Complete control over the preview UI via `ng-template`.
 - ♿ **Accessible**: ARIA labels and focus management.
-- ⚡ **Performance**: Smart image preloading for smoother gallery navigation.
+- ⚡ **Performance**: Smart image preloading and buffering for smoother navigation.
 - 🌏 **SSR Safe**: Fully compatible with Angular Universal/SSR.
 - 🌗 **Dark Mode Ready**: Inherits system preferences or app styles seamlessly.
 
@@ -70,10 +74,9 @@ import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
 export class AppModule { }
 ```
 
-### 1. Import Directive
-
-Register `ImagesPreviewDirective` in your standalone component or module.
+Register the library in your standalone component or module.
 
+#### Standalone (Recommended)
 ```typescript
 import { ImagesPreviewDirective } from 'ng-images-preview';
 
@@ -84,6 +87,16 @@ import { ImagesPreviewDirective } from 'ng-images-preview';
 export class MyComponent {}
 ```
 
+#### NgModule (Legacy Support)
+```typescript
+import { NgImagesPreviewModule } from 'ng-images-preview';
+
+@NgModule({
+  imports: [NgImagesPreviewModule, ...]
+})
+export class AppModule {}
+```
+
 ### 2. Basic Usage
 
 **Option A: Zero Config** (Auto-detects source)
@@ -101,12 +114,33 @@ export class MyComponent {}
 ```
 
 **Option C: Gallery Mode**
-Pass a list of images to `previewImages` to enable gallery navigation (arrows, swipe).
+Pass a list of images to `previewImages` to enable gallery navigation and the automatic **Thumbnail Strip**.
 ```html
 <img 
   src="item1.jpg" 
   [ngImagesPreview]="'item1-highres.jpg'"
-  [previewImages]="['item1-highres.jpg', 'item2-highres.jpg', 'item3-highres.jpg']">
+  [previewImages]="['item1.jpg', 'item2.jpg', 'item3.jpg']">
+```
+
+**Option D: Toolbar Extensions**
+Add custom buttons (like Download) using an `ng-template`.
+```html
+<ng-template #myExtraButtons>
+  <button class="toolbar-btn" (click)="download()">
+    <svg>...</svg>
+  </button>
+</ng-template>
+
+<img src="pic.jpg" ngImagesPreview [toolbarExtensions]="myExtraButtons">
+```
+
+**Option E: Performance (Srcsets)**
+Support responsive images for faster loading on mobile.
+```html
+<img 
+  src="thumb.jpg" 
+  ngImagesPreview 
+  [previewSrcsets]="['image-400w.jpg 400w, image-800w.jpg 800w']">
 ```
 
 ### 3. Custom Template
@@ -134,6 +168,10 @@ Take full control of the UI by providing a template.
 | `ngImagesPreview` | `string` | `''` | High-res URL. If empty, tries to read `src` from host or child `img`. |
 | `previewImages` | `string[]` | `[]` | List of image URLs for gallery navigation. |
 | `previewTemplate` | `TemplateRef` | `undefined` | Custom template to render instead of the default viewer. |
+| `previewSrcsets` | `string[]` | `[]` | List of `srcset` strings for gallery navigation. |
+| `showThumbnails` | `boolean` | `true` | Whether to show the thumbnail strip. |
+| `showToolbar` | `boolean` | `true` | Whether to show the top toolbar. |
+| `toolbarExtensions`| `TemplateRef` | `undefined` | Custom template for toolbar buttons. |
 
 ### Component Inputs (`ImagesPreviewComponent`)
 
@@ -145,6 +183,10 @@ If you use the component directly:
 | `images` | `string[]` | `[]` | List of images for gallery. |
 | `initialIndex` | `number` | `0` | Initial image index in gallery. |
 | `customTemplate` | `TemplateRef` | `undefined` | Custom template for the overlay content. |
+| `srcsets` | `string[]` | `[]` | List of `srcset` strings for images. |
+| `showThumbnails` | `boolean` | `true` | Whether to show the thumbnail strip. |
+| `showToolbar` | `boolean` | `true` | Whether to show the top toolbar. |
+| `toolbarExtensions`| `TemplateRef` | `undefined` | Custom template for toolbar buttons. |
 
 ### Template Context (for Custom Templates)
 
@@ -160,6 +202,8 @@ When using `previewTemplate`, you get access to:
 | `flipV` | `boolean` | Vertical flip state. |
 | `isLoading` | `boolean` | True if image is loading. |
 | `hasError` | `boolean` | True if image failed to load. |
+| `currentIndex` | `number` | Current index in gallery (0-based). |
+| `total` | `number` | Total number of images in gallery. |
 
 #### `actions`
 | Method | Description |
@@ -174,6 +218,36 @@ When using `previewTemplate`, you get access to:
 | `close()` | Close the preview. |
 | `next()` | Go to next image (if gallery). |
 | `prev()` | Go to previous image (if gallery). |
+| `jumpTo(index)` | Jump to a specific index in gallery. |
+
+### CSS Variables (Theming)
+
+You can customize the look and feel by overriding these CSS variables in your `styles.css` or component styles:
+
+```css
+:root {
+  /* Overlay */
+  --ng-img-background: rgba(0, 0, 0, 0.95);
+  --ng-img-text-color: rgba(255, 255, 255, 0.8);
+  --ng-img-z-index: 50;
+  
+  /* Toolbar */
+  --ng-img-toolbar-bg: rgba(255, 255, 255, 0.1);
+  --ng-img-toolbar-hover: rgba(255, 255, 255, 0.2);
+  --ng-img-gap: 16px;
+  
+  /* Thumbnails */
+  --ng-img-thumb-strip-bg: rgba(0, 0, 0, 0.4);
+  --ng-img-thumb-width: 60px;
+  --ng-img-thumb-height: 40px;
+  --ng-img-thumb-gap: 8px;
+  --ng-img-thumb-border-radius: 6px;
+  --ng-img-thumb-active-border: white;
+  
+  /* Misc */
+  --ng-img-item-bg: rgba(0, 0, 0, 0.3);
+}
+```