@thisiscrowd/crowdbox 1.0.0

package/types/index.d.ts

@@ -0,0 +1,239 @@
+// ─── Crowdbox — TypeScript definitions ─────────────────────────────────
+
+export interface GalleryItem {
+  /** URL of the media. */
+  src: string;
+  /** Explicit media type. Auto-detected if omitted. */
+  type?: 'image' | 'video' | 'youtube' | 'vimeo' | 'iframe';
+  /** Thumbnail URL (falls back to src for images). */
+  thumb?: string;
+  /** Caption HTML string. */
+  caption?: string;
+  /** Alt text for images. */
+  alt?: string;
+  /** Poster image for video. */
+  poster?: string;
+  /** Override download URL. */
+  download?: string;
+  /** Custom filename for downloads. */
+  downloadName?: string;
+  /** URL used by the Share plugin. */
+  shareUrl?: string;
+  /** Start time in seconds (YouTube). */
+  start?: number;
+  /** Autoplay the media when opened. */
+  autoplay?: boolean;
+  /** Loop video. */
+  loop?: boolean;
+  /** Start muted. */
+  muted?: boolean;
+  /** For iframes: explicit width. */
+  iframeWidth?: string;
+  /** For iframes: explicit height. */
+  iframeHeight?: string;
+  /** Multiple sources for HTML5 video. */
+  sources?: Array<{ src: string; type?: string }>;
+}
+
+export interface I18nStrings {
+  close?: string;
+  prev?: string;
+  next?: string;
+  zoomIn?: string;
+  zoomOut?: string;
+  fullscreen?: string;
+  download?: string;
+  share?: string;
+  autoplayStart?: string;
+  autoplayStop?: string;
+  /** Template: "{current} of {total}" */
+  counter?: string;
+}
+
+export interface CrowdboxOptions {
+  /** CSS selector for trigger elements. Default: '[data-lgx]' */
+  selector?: string;
+  /** Loop gallery navigation. Default: true */
+  loop?: boolean;
+  /** Enable keyboard navigation. Default: true */
+  keyboard?: boolean;
+  /** Enable touch swipe. Default: true */
+  touch?: boolean;
+  /** Enable mouse drag. Default: true */
+  drag?: boolean;
+  /** Enable zoom controls. Default: true */
+  zoom?: boolean;
+  /** Show thumbnail strip. Default: true */
+  thumbnails?: boolean;
+  /** Show captions. Default: true */
+  captions?: boolean;
+  /** Show slide counter. Default: true */
+  counter?: boolean;
+  /** Show fullscreen button. Default: true */
+  fullscreen?: boolean;
+  /** Show download button. Default: false */
+  download?: boolean;
+  /** Show share button. Default: false */
+  share?: boolean;
+  /** Close when clicking the backdrop. Default: true */
+  closeOnBackdrop?: boolean;
+  /** Close on Escape key. Default: true */
+  closeOnEscape?: boolean;
+  /** Open/close animation duration in ms. Default: 300 */
+  animationDuration?: number;
+  /** Slide transition duration in ms. Default: 250 */
+  slideAnimationDuration?: number;
+  /** Zoom step per click. Default: 0.5 */
+  zoomStep?: number;
+  /** Maximum zoom level. Default: 4 */
+  zoomMax?: number;
+  /** Minimum zoom level. Default: 1 */
+  zoomMin?: number;
+  /** Lazy-load images. Default: true */
+  lazyLoad?: boolean;
+  /** Number of slides to preload ahead/behind. Default: 1 */
+  preload?: number;
+  /** Autoplay slideshow. Default: false */
+  autoplay?: boolean;
+  /** Autoplay interval in ms. Default: 4000 */
+  autoplayInterval?: number;
+  /** Localization strings. */
+  i18n?: I18nStrings;
+}
+
+export type LightboxGalleryOptions = CrowdboxOptions;
+
+export type GalleryEventMap = {
+  open:            { index: number; item: GalleryItem };
+  close:           void;
+  slide:           { index: number; item: GalleryItem };
+  zoom:            { zoom: number };
+  download:        { item: GalleryItem };
+  share:           { item: GalleryItem; method: 'native' | 'clipboard' };
+  'autoplay:start': void;
+  'autoplay:stop':  void;
+};
+
+export declare class EventEmitter {
+  on<K extends keyof GalleryEventMap>(event: K, listener: (data: GalleryEventMap[K]) => void): this;
+  once<K extends keyof GalleryEventMap>(event: K, listener: (data: GalleryEventMap[K]) => void): this;
+  off<K extends keyof GalleryEventMap>(event: K, listener: (data: GalleryEventMap[K]) => void): this;
+  emit<K extends keyof GalleryEventMap>(event: K, data?: GalleryEventMap[K]): boolean;
+  removeAllListeners(event?: string): this;
+}
+
+export declare class Crowdbox extends EventEmitter {
+  readonly opts: Required<CrowdboxOptions>;
+
+  constructor(options?: CrowdboxOptions);
+
+  /** Open the gallery with an array of items, starting at startIndex. */
+  open(items: GalleryItem | GalleryItem[], startIndex?: number): this;
+
+  /** Close the gallery. */
+  close(): this;
+
+  /** Go to the next item. */
+  next(): this;
+
+  /** Go to the previous item. */
+  prev(): this;
+
+  /** Jump to a specific index. */
+  goTo(index: number): this;
+
+  /** Zoom in by one step. */
+  zoomIn(): this;
+
+  /** Zoom out by one step. */
+  zoomOut(): this;
+
+  /** Reset zoom to 1×. */
+  resetZoom(): this;
+
+  /** Start the autoplay slideshow. */
+  startAutoplay(): this;
+
+  /** Stop the autoplay slideshow. */
+  stopAutoplay(): this;
+
+  /** Toggle the autoplay slideshow. */
+  toggleAutoplay(): this;
+
+  /** Remove all event listeners and DOM. */
+  destroy(): void;
+}
+
+export declare class LightboxGallery extends Crowdbox {}
+
+// ─── Media Adapters ───────────────────────────────────────────────────────────
+
+export interface MediaAdapter {
+  type: string;
+  canHandle(item: GalleryItem): boolean;
+  render(item: GalleryItem): HTMLElement;
+  getThumbnail(item: GalleryItem): string | null;
+}
+
+export declare const ImageAdapter:   MediaAdapter;
+export declare const VideoAdapter:   MediaAdapter;
+export declare const YouTubeAdapter: MediaAdapter;
+export declare const VimeoAdapter:   MediaAdapter;
+export declare const IframeAdapter:  MediaAdapter;
+
+// ─── Plugins ──────────────────────────────────────────────────────────────────
+
+export interface GalleryPlugin {
+  pluginName: string;
+  init?(gallery: Crowdbox): void;
+  afterOpen?(): void;
+  beforeClose?(): void;
+  afterClose?(): void;
+  afterBuildDOM?(): void;
+  buildToolbar?(toolbar: HTMLElement): void;
+  afterSlide?(index: number, item: GalleryItem): void;
+  updateUI?(): void;
+  afterZoom?(zoom: number): void;
+  toggleFullscreen?(): void;
+  destroy?(): void;
+}
+
+export declare class ZoomPlugin       implements GalleryPlugin { static pluginName: 'zoom'; }
+export declare class ThumbsPlugin     implements GalleryPlugin { static pluginName: 'thumbnails'; }
+export declare class FullscreenPlugin implements GalleryPlugin { static pluginName: 'fullscreen'; }
+export declare class DownloadPlugin   implements GalleryPlugin { static pluginName: 'download'; }
+export declare class SharePlugin      implements GalleryPlugin { static pluginName: 'share'; }
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+export declare const Registry: {
+  registerAdapter(type: string, adapter: MediaAdapter): void;
+  getAdapter(type: string): MediaAdapter | null;
+  registerPlugin(name: string, plugin: GalleryPlugin): void;
+  getPlugin(name: string): GalleryPlugin | null;
+  getPlugins(): GalleryPlugin[];
+};
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+export declare function createGallery(options?: CrowdboxOptions): Crowdbox;
+
+export default Crowdbox;
+
+// ─── React types (optional peer dep) ─────────────────────────────────────────
+
+export interface LightboxProps extends CrowdboxOptions {
+  items: GalleryItem[];
+  open: boolean;
+  startIndex?: number;
+  onClose: () => void;
+  className?: string;
+}
+
+export interface GalleryGridProps {
+  items: GalleryItem[];
+  columns?: number;
+  gap?: number;
+  lightboxOptions?: CrowdboxOptions;
+  className?: string;
+}