qirra

Qirra

Qirra is a modular, extensible file preview utility. It detects file types and loads the appropriate viewer/player for text, images, audio, video, or unsupported files. Optional encryption check is included. Qirra is designed for clarity, usability, and easy integration into modern web projects.

Features

• Automatic File Type Detection: Uses MIME type and file extension.
• Modular Renderer: Loads the correct viewer/player for each file type.
• Inline or Modal Preview: Can render previews inside a specified container or as a modal overlay.
• Extensible Players: Easily add support for new file types by creating new player modules.
• Optional Encryption Check: Detects and handles encrypted files.
• Modern UI: Clean, accessible, and responsive design.
• Loading Feedback: Shows a loading spinner/message during preview load.
• Graceful Fallback: Handles unsupported file types with a clear message.
• Robust Error Handling: All preview operations are wrapped in try/catch; errors show a styled message and a retry button for user feedback.

File Structure

qirra/
│
├── index.js                # Main controller (entry point)
├── qirra.css               # Default styles for modals/previews
├── fileType.js             # Handles file type detection (MIME/ext)
├── renderer.js             # Loads the correct player/viewer based on file type
├── encryptionCheck.js      # Checks if a file is encrypted (optional)
│
└── players/                # Contains viewers/players for different file types
    ├── textViewer.js       # Renders text files
    ├── imageViewer.js      # Renders image files
    ├── audioPlayer.js      # Plays audio files (MP3, WAV, etc.)
    ├── videoPlayer.js      # Plays video files (MP4, WebM, etc.)
    └── unsupported.js      # Handles unsupported file types

Usage

• Install Qirra
  Copy the qirra folder into your project or install via your preferred package manager (if published).

• Import and use Qirra

  import { previewFile } from './qirra/index.js';
  // Inline preview:
  previewFile('path/to/file.ext', { container: document.getElementById('preview-area'), modal: false });
  // Modal preview:
  previewFile('path/to/file.ext', { modal: true });
  

• Include CSS

  <link rel="stylesheet" href="./qirra/qirra.css">
  

• Demo Page

  • See demo.html for a modern, interactive example.
  • Buttons are dynamically generated for each sample file.
  • Previews are rendered inline or in a modal with loading feedback and error handling.

Example

import { previewFile } from './qirra/index.js';

// Inline preview
previewFile('examples/example.txt', { container: document.getElementById('preview-area') });

// Modal preview
previewFile('examples/image.jpg', { modal: true });

Improvements in v1.0.0

• Cleaned up codebase: removed unused imports, comments, and console logs.
• Consistent naming conventions and file structure.
• All modules export/import correctly.
• Robust error handling and user feedback.
• Finalized and scoped CSS for both inline and modal previews.
• Thoroughly tested demo page for all file types and preview modes.
• Ready for integration and production use.

Limitations

• Browser Support: Relies on browser support for media formats (e.g., not all browsers support all audio/video codecs).
• File Size: Large files may load slowly or fail to preview, especially in browsers with memory limits.
• Security: Previews are limited by browser sandboxing; encrypted files require custom logic.
• No Server-Side Processing: All previews are client-side; cannot preview files requiring server-side parsing.
• Limited Format Support: Only file types with a corresponding player module are supported out-of-the-box.
• No Drag-and-Drop: Current demo does not support drag-and-drop file preview (can be added).

How to Extend

• Add a new player module:
  Create players/myTypeViewer.js for your new file type.

• Update renderer.js:
  Add logic to detect and load your new player based on file type.

• Style as needed:
  Update qirra.css for new preview styles.

Making Qirra Even Better

• Add drag-and-drop and file input support.
• Improve accessibility (keyboard, ARIA).
• Add support for more file types (PDF, Markdown, Office docs, etc.).
• Provide theme customization.
• Add localization support.
• Integrate with cloud storage/file pickers.
• Add file metadata/info panel.
• Support for previewing remote URLs.
• Add automated tests for previewFile and renderer.

Credits

• Inspired by modular previewers and modern UI/UX best practices.
• Demo uses sample files from W3Schools.

Qirra aims to be the best, most extensible, and user-friendly file preview utility for web projects. Contributions and suggestions are welcome!