ngx-radiant 21.0.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to Ngx Radiant are documented in this file.
+
+## 21.0.0 - 2026-06-28
+
+### Added
+
+- Initial public Angular 21+ standalone lightbox library release.
+- `NgxRadiantLightbox` component with controlled `open/openChange` and `index/indexChange` bindings.
+- `NgxRadiantDirective` trigger API for opening galleries or single images from any element.
+- Image, video, and iframe item support, including YouTube embed URLs.
+- Configurable iframe behavior:
+  - `iframeAspectRatio`, defaulting to `16 / 9`.
+  - `iframeAutoplay`, which appends `autoplay=1` without forcing muted mode.
+  - `iframeMuted`, which appends `mute=1&muted=1` only when explicitly enabled.
+  - `iframeAllowedOrigins` for optional iframe origin allowlisting.
+- Image zoom controls with zoom in/out/reset, optional zoom slider, and bounded drag/pan while zoomed.
+- Automatic hiding of counter and previous/next navigation for single-item overlays.
+- Captions, counters, thumbnails, backdrop close, keyboard navigation, and CSS custom properties for theming.
+- GitHub Pages demo covering component usage, directive usage, single-image usage, zoom, and iframe media.
+
+### Security
+
+- Iframe URLs are validated before being trusted as Angular resource URLs.
+- Unsupported iframe protocols and disallowed origins render `about:blank`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edward
+
+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

@@ -0,0 +1,216 @@
+# ngx-radiant
+
+A modern Angular 21+ lightbox library for image galleries and media previews.
+
+## Demo
+
+```text
+https://edward124689.github.io/ngx-radiant/
+```
+
+## Install
+
+```bash
+npm install ngx-radiant
+```
+
+## Compatibility
+
+- Library version: `21.0.0`
+- Angular compatibility: `21+`
+
+## Component usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { NgxRadiantConfig, NgxRadiantItem, NgxRadiantLightbox } from 'ngx-radiant';
+
+@Component({
+  selector: 'app-gallery',
+  imports: [NgxRadiantLightbox],
+  template: `
+    <button type="button" (click)="isOpen.set(true)">Open gallery</button>
+
+    <ngx-radiant-lightbox
+      [items]="items"
+      [open]="isOpen()"
+      (openChange)="isOpen.set($event)"
+      [index]="activeIndex()"
+      (indexChange)="activeIndex.set($event)"
+      [config]="config"
+    />
+  `,
+})
+export class GalleryComponent {
+  readonly isOpen = signal(false);
+  readonly activeIndex = signal(0);
+  readonly config: NgxRadiantConfig = {
+    zoomStep: 0.5,
+    maxZoom: 8,
+    showZoomSlider: true,
+    showThumbnails: true,
+  };
+
+  readonly items: NgxRadiantItem[] = [
+    {
+      src: '/assets/gallery/aurora.jpg',
+      thumb: '/assets/gallery/aurora-thumb.jpg',
+      alt: 'Aurora over a mountain ridge',
+      caption: 'Aurora over a mountain ridge',
+    },
+  ];
+}
+```
+
+## Directive usage
+
+```ts
+import { Component } from '@angular/core';
+import { NgxRadiantDirective, NgxRadiantItem } from 'ngx-radiant';
+
+@Component({
+  selector: 'app-gallery',
+  imports: [NgxRadiantDirective],
+  template: `
+    <button type="button" [ngxRadiant]="items" [radiantIndex]="0">
+      Open gallery
+    </button>
+  `,
+})
+export class GalleryComponent {
+  readonly items: NgxRadiantItem[] = [
+    {
+      src: '/assets/gallery/aurora.jpg',
+      thumb: '/assets/gallery/aurora-thumb.jpg',
+      alt: 'Aurora over a mountain ridge',
+      caption: 'Aurora over a mountain ridge',
+    },
+  ];
+}
+```
+
+Images can zoom beyond the fitted viewport. When zoomed in, users can drag the image to inspect details.
+
+Single-image shorthand automatically hides the counter and previous/next controls:
+
+```html
+<button
+  type="button"
+  ngxRadiant="/assets/gallery/aurora.jpg"
+  radiantAlt="Aurora over a mountain ridge"
+  radiantCaption="Aurora over a mountain ridge"
+  [radiantConfig]="{ zoomStep: 0.5, maxZoom: 3 }"
+>
+  Open image
+</button>
+```
+
+Iframe / YouTube example:
+
+> Iframe sources must be application-controlled. Ngx Radiant only allows `http:`/`https:` iframe URLs by default. Use `iframeAllowedOrigins` when you want a stricter allowlist. Autoplay does not enable muted mode automatically; set `iframeMuted: true` only when you want muted autoplay params.
+
+```ts
+readonly mediaItems: NgxRadiantItem[] = [
+  {
+    src: 'https://www.youtube.com/embed/jYqX4YUzcKs',
+    type: 'iframe',
+    caption: 'YouTube embed',
+  },
+];
+```
+
+```html
+<button
+  type="button"
+  [ngxRadiant]="mediaItems"
+  [radiantConfig]="{ showCounter: false, showNavigation: false, zoomable: false }"
+>
+  Open YouTube
+</button>
+```
+
+## API
+
+### `NgxRadiantLightbox`
+
+| Input/output | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `NgxRadiantItem[]` | `[]` | Gallery items to display. |
+| `open` / `openChange` | `boolean` | `false` | Controls visibility. |
+| `index` / `indexChange` | `number` | `0` | Controls the selected item. |
+| `config` | `NgxRadiantConfig` | `null` | Shared config object for controls, zoom, and UI visibility. |
+| `ariaLabel` | `string` | `Image gallery lightbox` | Accessible dialog label. Overrides `config.ariaLabel`. |
+| `closeOnEscape` | `boolean` | `true` | Close the lightbox when Escape is pressed. Overrides `config.closeOnEscape`. |
+| `loop` | `boolean` | `true` | Wrap navigation at the first/last item. Overrides `config.loop`. |
+| `showThumbnails` | `boolean` | `true` | Render the thumbnail strip when possible. Overrides `config.showThumbnails`. |
+| `showCounter` | `boolean` | `true` | Render the counter when there is more than one item. Overrides `config.showCounter`. |
+| `showNavigation` | `boolean` | `true` | Render previous/next controls when there is more than one item. Overrides `config.showNavigation`. |
+| `zoomable` | `boolean` | `true` | Enable zoom controls for image items. Overrides `config.zoomable`. |
+| `initialZoom` | `number` | `1` | Initial image zoom level. Overrides `config.initialZoom`. |
+| `minZoom` | `number` | `1` | Minimum image zoom level. Overrides `config.minZoom`. |
+| `maxZoom` | `number` | `3` | Maximum image zoom level. Overrides `config.maxZoom`. |
+| `zoomStep` | `number` | `0.25` | Amount changed by each zoom in/out action. Overrides `config.zoomStep`. |
+| `showZoomSlider` | `boolean` | `false` | Render a range slider for direct zoom control. Overrides `config.showZoomSlider`. |
+| `iframeAspectRatio` | `string` | `'16 / 9'` | CSS aspect-ratio for iframe embeds. Overrides `config.iframeAspectRatio`. |
+| `iframeAutoplay` | `boolean` | `false` | Appends `autoplay=1` to iframe URLs. Overrides `config.iframeAutoplay`. |
+| `iframeMuted` | `boolean` | `false` | Appends `mute=1&muted=1` only when explicitly enabled. Overrides `config.iframeMuted`. |
+| `iframeAllowedOrigins` | `string[]` | `[]` | Optional iframe origin allowlist. Empty means any `http:`/`https:` origin is allowed; unsupported protocols render `about:blank`. |
+
+### `NgxRadiantDirective`
+
+| Input | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ngxRadiant` | `NgxRadiantItem \| NgxRadiantItem[] \| string` | `null` | Item, item list, or single image URL to open. |
+| `radiantItems` | `NgxRadiantItem[]` | `null` | Optional explicit gallery items. |
+| `radiantIndex` | `number` | `0` | Initial item index. |
+| `radiantAlt` | `string` | `undefined` | Alt text for string shorthand. |
+| `radiantCaption` | `string` | `undefined` | Caption for string shorthand. |
+| `radiantThumb` | `string` | `undefined` | Thumbnail for string shorthand. |
+| `radiantType` | `'image' \| 'video' \| 'iframe'` | `undefined` | Media type for string shorthand. |
+| `radiantAriaLabel` | `string` | `Image gallery lightbox` | Accessible dialog label. |
+| `radiantConfig` | `NgxRadiantConfig` | `null` | Shared config object passed to the created lightbox. |
+| `radiantCloseOnEscape` | `boolean` | `true` | Close the overlay when Escape is pressed. |
+| `radiantLoop` | `boolean` | `true` | Wrap navigation at the first/last item. |
+| `radiantShowThumbnails` | `boolean` | `true` | Render the thumbnail strip when possible. |
+
+### `NgxRadiantConfig`
+
+```ts
+interface NgxRadiantConfig {
+  ariaLabel?: string;
+  closeOnEscape?: boolean;
+  loop?: boolean;
+  showThumbnails?: boolean;
+  showCounter?: boolean;
+  showNavigation?: boolean;
+  zoomable?: boolean;
+  initialZoom?: number;
+  minZoom?: number;
+  maxZoom?: number;
+  zoomStep?: number;
+  showZoomSlider?: boolean;
+  iframeAspectRatio?: string;
+  iframeAutoplay?: boolean;
+  iframeMuted?: boolean;
+  iframeAllowedOrigins?: string[];
+}
+```
+
+### `NgxRadiantItem`
+
+```ts
+interface NgxRadiantItem {
+  src: string;
+  type?: 'image' | 'video' | 'iframe';
+  alt?: string;
+  caption?: string;
+  thumb?: string;
+}
+```
+
+## Commands
+
+```bash
+npm run build:lib
+npm test -- --watch=false
+```