@c4h/chuci 0.2.4 → 0.2.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Code for History
+Copyright (c) 2024-2026 Code for History
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.ja.md

@@ -1,5 +1,10 @@
 # Chuci (楚辞)
 
+[![CI](https://github.com/code4history/Chuci/actions/workflows/ci.yml/badge.svg)](https://github.com/code4history/Chuci/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/@c4h%2Fchuci.svg)](https://www.npmjs.com/package/@c4h/chuci)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
 [Quyuan](https://github.com/code4history/Quyuan)から抽出されたスタンドアロンのマルチメディアスワイパーとビューアWebコンポーネントライブラリです。フレームワークに依存せず、タッチ対応のカルーセルとマルチメディアビューアを提供します。
 
 ## 特徴
@@ -11,12 +16,39 @@
 - 📦 **軽量**: tree-shakingサポートによる最適化されたバンドルサイズ
 - 🛠️ **TypeScript**: 型定義付きの完全なTypeScriptサポート
 
+## 要件
+
+- **Node.js**: 20以降
+- **パッケージマネージャー**: pnpm 9.0.0以降（推奨）
+- **ブラウザ**: Web Componentsをサポートするモダンブラウザ
+  - Chrome/Edge 79+
+  - Firefox 63+
+  - Safari 12.1+
+
 ## インストール
 
+### pnpmを使用（推奨）
+
+```bash
+pnpm add @c4h/chuci
+```
+
+### npmを使用
+
 ```bash
 npm install @c4h/chuci
 ```
 
+### CDN（ブラウザ）
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@c4h/chuci@latest/dist/chuci.umd.js"></script>
+<script>
+  // コンポーネントはグローバルにChuciとして利用可能
+  // HTMLで直接カスタム要素を使用できます
+</script>
+```
+
 ## 使用方法
 
 ### 基本的なスワイパー
@@ -42,6 +74,23 @@ npm install @c4h/chuci
 </script>
 ```
 
+### プログラムによる使用
+
+```javascript
+import '@c4h/chuci';
+
+// スワイパー要素を取得
+const swiper = document.querySelector('cc-swiper');
+
+// プログラムでビューアを開く
+swiper.openViewer('path/to/image.jpg', 'image', 0);
+
+// スライド変更イベントをリッスン
+swiper.addEventListener('slidechange', (e) => {
+  console.log('現在のスライド:', e.detail.activeIndex);
+});
+```
+
 ### サムネイルギャラリー付き
 
 ```html
@@ -78,24 +127,89 @@ npm install @c4h/chuci
 - `has-thumb`: サムネイルギャラリーを表示
 - `autoplay`: 自動再生を有効化
 
+**メソッド:**
+- `openViewer(imageUrl: string, imageType: string, slideIndex?: number)`: プログラムでビューアを開く
+  - `imageUrl`: 表示するメディアのURL
+  - `imageType`: メディアのタイプ（上記のサポートされるタイプを参照）
+  - `slideIndex`: オプションのスライドインデックス（デフォルト: 0）
+
+**イベント:**
+- `slidechange`: スライドが変更されたときに発火
+  - `detail.activeIndex`: 現在のアクティブなスライドインデックス
+
+**プロパティ:**
+- `slider`: 基盤となるSwiperインスタンスへのアクセス
+
 ### `<cc-swiper-slide>`
 
 個別のスライドコンポーネント。
 
 **属性:**
-- `thumbnail-url`: サムネイル画像のURL
-- `image-url`: フルメディアのURL
-- `image-type`: メディアタイプ（上記のサポートされるタイプを参照）
+- `thumbnail-url`: サムネイル画像のURL（必須）
+- `image-url`: フルメディアのURL（必須）
+- `image-type`: メディアタイプ（上記のサポートされるタイプを参照）（必須）
 - `caption`: オプションのキャプションテキスト
 
-### ビューア固有の属性
+**3DモデルとGaussianスプラット用の属性:**
+- `material-url`: 3Dモデル用のマテリアルファイルURL（OBJ/MTL）
+- `debug-mode`: デバッグ情報の表示を有効化（`"true"` または `"false"`）
+- `camera-position`: 初期カメラ位置を `"x,y,z"` 形式で指定（例: `"0,1,5"`）
+- `camera-target`: カメラターゲット位置を `"x,y,z"` 形式で指定（例: `"0,0,0"`）
+- `show-texture`: 3Dモデルのテクスチャの表示/非表示（`"true"` または `"false"`）
+- `fit-to-container`: モデルをコンテナサイズに合わせる（`"true"` または `"false"`）
+
+### ビューアコンポーネント
+
+すべてのビューアコンポーネントは`CcViewerBase`を継承し、以下をサポートします:
+
+**メソッド:**
+- `open(url: string)`: メディアURLでビューアを開く
+- `close()`: ビューアを閉じる
+
+**プロパティ:**
+- `showPrevButton` (boolean): 前へナビゲーションボタンの表示/非表示
+- `showNextButton` (boolean): 次へナビゲーションボタンの表示/非表示
 
-3DモデルとGaussianスプラット用:
-- `fit-to-container`: モデルをコンテナサイズに合わせる
-- `debug-mode`: デバッグ情報を表示
-- `camera-position`: 初期カメラ位置を設定（例: "0,0,5"）
-- `camera-target`: カメラターゲットを設定（例: "0,0,0"）
-- `show-texture`: テクスチャの表示/非表示（3Dモデル用）
+**イベント:**
+- `close`: ビューアが閉じられたときに発火
+- `navigate-prev`: 前へボタンがクリックされたときに発火
+- `navigate-next`: 次へボタンがクリックされたときに発火
+
+### メディア固有の例
+
+#### 3Dモデルビューア
+```html
+<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スプラッティングビューア
+```html
+<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動画
+```html
+<cc-swiper-slide
+  thumbnail-url="thumb.jpg"
+  image-url="https://www.youtube.com/watch?v=VIDEO_ID"
+  image-type="youtube">
+</cc-swiper-slide>
+```
 
 ## スタイリング
 
@@ -107,17 +221,20 @@ cc-swiper {
   --cc-slider-navigation-color: #007aff;
 }
 
-cc-viewer {
+cc-viewer-base,
+cc-viewer-image,
+cc-viewer-panorama,
+cc-viewer-youtube,
+cc-viewer-video,
+cc-viewer-3dmodel,
+cc-viewer-gaussian {
   --cc-viewer-z-index: 1000;
 }
 ```
 
 ## ブラウザサポート
 
-Web Componentsをサポートするすべてのモダンブラウザで動作:
-- Chrome/Edge 79+
-- Firefox 63+
-- Safari 12.1+
+ブラウザ互換性の詳細については、[要件](#要件)セクションを参照してください。
 
 ## 開発
 
@@ -137,7 +254,26 @@ pnpm run build
 
 ## ライセンス
 
-MIT License - 詳細はLICENSEファイルを参照してください。
+MIT License
+
+Copyright (c) 2024-2026 Code for History
+
+詳細は[LICENSE](LICENSE)ファイルを参照してください。
+
+## Quyuanからの移行
+
+元のQuyuan実装から移行する場合:
+
+1. インポートを`quyuan`から`@c4h/chuci`に変更
+2. コンポーネント名は同じまま（`cc-swiper`、`cc-swiper-slide`など）
+3. 3DモデルのURLはパイプ区切り形式を使用しなくなりました:
+   ```html
+   <!-- 旧 -->
+   <cc-swiper-slide image-url="model.obj|model.mtl" ...>
+   
+   <!-- 新 -->
+   <cc-swiper-slide image-url="model.obj" material-url="model.mtl" ...>
+   ```
 
 ## クレジット
 

package/README.md

@@ -15,12 +15,39 @@ A standalone multimedia swiper and viewer web components library extracted from
 - 📦 **Lightweight**: Optimized bundle size with tree-shaking support
 - 🛠️ **TypeScript**: Full TypeScript support with type definitions
 
+## Requirements
+
+- **Node.js**: 20 or higher
+- **Package Manager**: pnpm 9.0.0 or higher (recommended)
+- **Browser**: Any modern browser supporting Web Components
+  - Chrome/Edge 79+
+  - Firefox 63+
+  - Safari 12.1+
+
 ## Installation
 
+### Using pnpm (recommended)
+
+```bash
+pnpm add @c4h/chuci
+```
+
+### Using npm
+
 ```bash
 npm install @c4h/chuci
 ```
 
+### CDN (Browser)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@c4h/chuci@latest/dist/chuci.umd.js"></script>
+<script>
+  // Components are available globally as Chuci
+  // Use custom elements directly in HTML
+</script>
+```
+
 ## Usage
 
 ### Basic Swiper
@@ -101,31 +128,51 @@ Main carousel component.
 
 **Methods:**
 - `openViewer(imageUrl: string, imageType: string, slideIndex?: number)`: Programmatically open viewer
+  - `imageUrl`: URL of the media to display
+  - `imageType`: Type of media (see supported types above)
+  - `slideIndex`: Optional slide index (default: 0)
 
 **Events:**
 - `slidechange`: Fired when slide changes
+  - `detail.activeIndex`: Current active slide index
+
+**Properties:**
+- `slider`: Access to underlying Swiper instance
 
 ### `<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)
+- `thumbnail-url`: URL for thumbnail image (required)
+- `image-url`: URL for full media (required)
+- `image-type`: Media type (see supported types above) (required)
 - `caption`: Optional caption text
 
+**3D Model & Gaussian Splatting Attributes:**
+- `material-url`: Material file URL for 3D models (OBJ/MTL)
+- `debug-mode`: Enable debug information display (`"true"` or `"false"`)
+- `camera-position`: Initial camera position as `"x,y,z"` (e.g., `"0,1,5"`)
+- `camera-target`: Camera target position as `"x,y,z"` (e.g., `"0,0,0"`)
+- `show-texture`: Show/hide texture for 3D models (`"true"` or `"false"`)
+- `fit-to-container`: Fit model to container size (`"true"` or `"false"`)
+
 ### Viewer Components
 
 All viewer components inherit from `CcViewerBase` and support:
 
 **Methods:**
-- `open(url: string)`: Open viewer with media
+- `open(url: string)`: Open viewer with media URL
 - `close()`: Close viewer
 
 **Properties:**
-- `showPrevButton`: Show/hide previous button
-- `showNextButton`: Show/hide next button
+- `showPrevButton` (boolean): Show/hide previous navigation button
+- `showNextButton` (boolean): Show/hide next navigation button
+
+**Events:**
+- `close`: Fired when viewer is closed
+- `navigate-prev`: Fired when previous button is clicked
+- `navigate-next`: Fired when next button is clicked
 
 ### Media-specific Examples
 
@@ -173,17 +220,20 @@ cc-swiper {
   --cc-slider-navigation-color: #007aff;
 }
 
-cc-viewer {
+cc-viewer-base,
+cc-viewer-image,
+cc-viewer-panorama,
+cc-viewer-youtube,
+cc-viewer-video,
+cc-viewer-3dmodel,
+cc-viewer-gaussian {
   --cc-viewer-z-index: 1000;
 }
 ```
 
 ## Browser Support
 
-Works in all modern browsers that support Web Components:
-- Chrome/Edge 79+
-- Firefox 63+
-- Safari 12.1+
+See [Requirements](#requirements) section for browser compatibility details.
 
 ## Development
 
@@ -203,7 +253,11 @@ pnpm run build
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT License
+
+Copyright (c) 2024-2026 Code for History
+
+See [LICENSE](LICENSE) file for details.
 
 ## Migration from Quyuan
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4h/chuci",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Standalone multimedia swiper and viewer web components",
   "type": "module",
   "private": false,