Chuci (楚辞)

A standalone multimedia swiper and viewer web components library extracted from Quyuan. Provides touch-enabled carousel and multimedia viewers without any framework dependencies.

Features

🚀 Framework-agnostic: Pure Web Components, works with any framework or vanilla JS
📱 Touch-enabled: Built on Swiper.js for smooth touch interactions
🎬 Multiple media types: Support for images, panoramas, videos, YouTube, 3D models, and Gaussian splats
🔧 Zero dependencies: All dependencies are bundled (no Lit dependency)
📦 Lightweight: Optimized bundle size with tree-shaking support
🛠️ TypeScript: Full TypeScript support with type definitions

Installation

npm install @c4h/chuci

Usage

Basic Swiper

<cc-swiper>
  <cc-swiper-slide 
    thumbnail-url="thumb1.jpg" 
    image-url="full1.jpg" 
    image-type="image"
    caption="First image">
  </cc-swiper-slide>
  <cc-swiper-slide 
    thumbnail-url="thumb2.jpg" 
    image-url="full2.jpg" 
    image-type="image"
    caption="Second image">
  </cc-swiper-slide>
</cc-swiper>

<script type="module">
  import '@c4h/chuci'
</script>

Programmatic Usage

import '@c4h/chuci';

// Get swiper element
const swiper = document.querySelector('cc-swiper');

// Open viewer programmatically
swiper.openViewer('path/to/image.jpg', 'image', 0);

// Listen to slide changes
swiper.addEventListener('slidechange', (e) => {
  console.log('Current slide:', e.detail.activeIndex);
});

With Thumbnails Gallery

<cc-swiper has-thumb>
  <cc-swiper-slide thumbnail-url="..." image-url="..." image-type="image"></cc-swiper-slide>
  <cc-swiper-slide thumbnail-url="..." image-url="..." image-type="image"></cc-swiper-slide>
</cc-swiper>

Autoplay

<cc-swiper autoplay>
  <!-- slides -->
</cc-swiper>

Supported Media Types

image: Regular images (jpg, png, gif, etc.)
panorama: 360° panoramic images
youtube: YouTube videos (provide YouTube URL)
video: HTML5 videos (mp4, webm, etc.)
3dmodel: 3D models (OBJ/MTL format)
gaussian: Gaussian splatting files (.splat, .ply)

Components

`<cc-swiper>`

Main carousel component.

Attributes:

has-thumb: Show thumbnail gallery
autoplay: Enable autoplay

Methods:

openViewer(imageUrl: string, imageType: string, slideIndex?: number): Programmatically open viewer

Events:

slidechange: Fired when slide changes

`<cc-swiper-slide>`

Individual slide component.

Attributes:

thumbnail-url: URL for thumbnail image
image-url: URL for full media
image-type: Media type (see supported types above)
caption: Optional caption text

Viewer Components

All viewer components inherit from CcViewerBase and support:

Methods:

open(url: string): Open viewer with media
close(): Close viewer

Properties:

showPrevButton: Show/hide previous button
showNextButton: Show/hide next button

Media-specific Examples

3D Model Viewer

<cc-swiper-slide 
  thumbnail-url="thumb.jpg"
  image-url="model.obj"
  image-type="3dmodel"
  material-url="model.mtl"
  debug-mode="true"
  camera-position="0,1,5"
  camera-target="0,0,0"
  show-texture="true">
</cc-swiper-slide>

Gaussian Splatting Viewer

<cc-swiper-slide
  thumbnail-url="thumb.jpg"
  image-url="scene.splat"
  image-type="gaussian"
  debug-mode="true"
  camera-position="0,0,10">
</cc-swiper-slide>

YouTube Video

<cc-swiper-slide
  thumbnail-url="thumb.jpg"
  image-url="https://www.youtube.com/watch?v=VIDEO_ID"
  image-type="youtube">
</cc-swiper-slide>

Styling

CSS Custom Properties:

cc-swiper {
  --cc-slider-theme-color: #007aff;
  --cc-slider-navigation-color: #007aff;
}

cc-viewer {
  --cc-viewer-z-index: 1000;
}

Browser Support

Works in all modern browsers that support Web Components:

Chrome/Edge 79+
Firefox 63+
Safari 12.1+

Development

# Install dependencies
pnpm install

# Start development server
pnpm run dev

# Run tests
pnpm test

# Build library
pnpm run build

License

MIT License - see LICENSE file for details.

Migration from Quyuan

If you're migrating from the original Quyuan implementation:

Change imports from quyuan to @c4h/chuci
Component names remain the same (cc-swiper, cc-swiper-slide, etc.)

3D model URLs no longer use pipe-separated format:

<!-- Old -->
<cc-swiper-slide image-url="model.obj|model.mtl" ...>

<!-- New -->
<cc-swiper-slide image-url="model.obj" material-url="model.mtl" ...>

Credits

Extracted from Quyuan by Code for History.

code4history/Chuci