@clikvn/showroom-visualizer 0.3.0-dev-07 → 0.3.0-dev-08

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clikvn/showroom-visualizer",
   "description": "Showroom Visualizer",
-  "version": "0.3.0-dev-07",
+  "version": "0.3.0-dev-08",
   "author": "Clik JSC",
   "license": "ISC",
   "type": "module",

package/Planning/README-middleware.md

@@ -1,582 +0,0 @@
-# Middleware Implementation - Tracking Only
-
-## Overview
-
-The showroom-visualizer library now supports **tracking middleware** that fires on all user interactions, regardless of whether external listeners are configured.
-
-**Key Design**: Middleware is for **tracking only** - it does NOT block or cancel actions.
-
-## Quick Start
-
-```typescript
-import ShowroomVisualizer from '@clikvn/showroom-visualizer';
-
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-
-  // Add tracking middleware
-  middleware: (event) => {
-    console.log('Action:', event.actionName);
-    console.log('Payload:', event.payload);
-    console.log('Timestamp:', event.timestamp);
-    console.log('Tour:', event.metadata?.tourCode);
-  },
-});
-```
-
-## Event Structure
-
-Each middleware call receives an `ActionEvent`:
-
-```typescript
-interface ActionEvent {
-  // Action name (e.g., 'onPinActionClicked', 'onSceneChanged')
-  actionName: string;
-
-  // Action data (button key, scene info, scenario code, etc.)
-  payload: any;
-
-  // ISO timestamp when action occurred
-  timestamp: string;
-
-  // Optional context
-  metadata?: {
-    tourCode?: string;
-    sceneCode?: string;
-  };
-}
-```
-
-## Tracked Actions
-
-The middleware system tracks **13 distinct action types** across the application:
-
-### 1. Pin Action Buttons (UI Layer)
-
-**Component**: `src/components/SkinLayer/PinActionButtons/index.tsx`
-**Action Name**: `onPinActionClicked`
-**Payload**: Button key string
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onPinActionClicked') {
-    console.log('Button clicked:', event.payload);
-    // Possible values: 'MAP', 'SOUND', 'FULLSCREEN', 'SEARCH', etc.
-  }
-};
-```
-
-### 2. Scene Navigation (UI Layer)
-
-**Component**: `src/components/SkinLayer/SceneCategories/index.tsx`
-**Action Name**: `onSceneChanged`
-**Payload**: `{ scene: SceneType, category: CategoryDataType }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onSceneChanged') {
-    const { scene, category } = event.payload;
-    console.log('Navigating to:', scene.name, 'in category:', category.name);
-  }
-};
-```
-
-### 3. Scenario Playback (UI Layer)
-
-**Component**: `src/components/SkinLayer/TourScenarios/index.tsx`
-**Action Name**: `onStartScenario`
-**Payload**: Scenario code (string)
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onStartScenario') {
-    console.log('Starting scenario:', event.payload);
-  }
-};
-```
-
-### 4. POI Click (Krpano Layer)
-
-**Hook**: `src/hooks/Visualizer/useTourVisualizer.ts`
-**Action Name**: `onPoiClicked`
-**Payload**: POI data object
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onPoiClicked') {
-    console.log('POI clicked:', event.payload);
-    // Payload contains: { code, type, sceneCode, ...poi properties }
-  }
-};
-```
-
-### 5. Moving POI Click (Krpano Layer)
-
-**Hook**: `src/hooks/Visualizer/useTourVisualizer.ts`
-**Action Name**: `onMovingPoiClick`
-**Payload**: `{ sceneCode: string, floorPlanCode?: string }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onMovingPoiClick') {
-    console.log('Moving POI clicked:', event.payload.sceneCode);
-  }
-};
-```
-
-### 6. Texture POI Click (Krpano Layer)
-
-**Hook**: `src/hooks/Visualizer/useTourVisualizer.ts`
-**Action Name**: `onTexturePoiClick`
-**Payload**: `{ poiCode: string, textureIndex: number }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onTexturePoiClick') {
-    console.log(
-      'Texture POI clicked:',
-      event.payload.poiCode,
-      'index:',
-      event.payload.textureIndex
-    );
-  }
-};
-```
-
-### 7. Background Sound Toggle (Krpano Layer)
-
-**Hook**: `src/hooks/Visualizer/useTourVisualizer.ts`
-**Action Name**: `onBackgroundSoundToggle`
-**Payload**: `{ playing: boolean }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onBackgroundSoundToggle') {
-    console.log(
-      'Background sound:',
-      event.payload.playing ? 'playing' : 'paused'
-    );
-  }
-};
-```
-
-### 8. Function Button Open (Krpano Layer)
-
-**Hook**: `src/hooks/Visualizer/useTourVisualizer.ts`
-**Action Name**: `onFunctionButtonOpen`
-**Payload**: `{ buttonCode: string }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onFunctionButtonOpen') {
-    console.log('Function button opened:', event.payload.buttonCode);
-  }
-};
-```
-
-### 9. Minimap Toggle (Krpano Layer)
-
-**Hook**: `src/hooks/Visualizer/useTourVisualizer.ts`
-**Action Name**: `onMinimapToggle`
-**Payload**: `{ fullscreen: boolean }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onMinimapToggle') {
-    console.log('Minimap fullscreen:', event.payload.fullscreen);
-  }
-};
-```
-
-### 10. Hotspot View More (UI Layer)
-
-**Component**: `src/components/SkinLayer/HotspotOverview/index.tsx`
-**Action Name**: `onHotspotViewMore`
-**Payload**: `{ poiCode: string, poiType: string }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onHotspotViewMore') {
-    console.log(
-      'View more clicked:',
-      event.payload.poiCode,
-      'type:',
-      event.payload.poiType
-    );
-  }
-};
-```
-
-### 11. Gallery Item Click (UI Layer)
-
-**Component**: `src/components/SkinLayer/HotspotOverview/index.tsx`
-**Action Name**: `onGalleryItemClick`
-**Payload**: `{ id: number, poiCode: string }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onGalleryItemClick') {
-    console.log('Gallery item clicked:', event.payload.id);
-  }
-};
-```
-
-### 12. Texture Selected (UI Layer)
-
-**Component**: `src/components/SkinLayer/HotspotOverview/index.tsx`
-**Action Name**: `onTextureSelected`
-**Payload**: `{ index: number, poiCode: string }`
-
-```typescript
-middleware: (event) => {
-  if (event.actionName === 'onTextureSelected') {
-    console.log(
-      'Texture selected:',
-      event.payload.index,
-      'for POI:',
-      event.payload.poiCode
-    );
-  }
-};
-```
-
-## Summary of All Tracked Actions
-
-| #   | Action Name               | Layer  | Component/Hook    | Payload                         |
-| --- | ------------------------- | ------ | ----------------- | ------------------------------- |
-| 1   | `onPinActionClicked`      | UI     | PinActionButtons  | `string` (button key)           |
-| 2   | `onSceneChanged`          | UI     | SceneCategories   | `{ scene, category }`           |
-| 3   | `onStartScenario`         | UI     | TourScenarios     | `string` (scenario code)        |
-| 4   | `onPoiClicked`            | Krpano | useTourVisualizer | POI object                      |
-| 5   | `onMovingPoiClick`        | Krpano | useTourVisualizer | `{ sceneCode, floorPlanCode? }` |
-| 6   | `onTexturePoiClick`       | Krpano | useTourVisualizer | `{ poiCode, textureIndex }`     |
-| 7   | `onBackgroundSoundToggle` | Krpano | useTourVisualizer | `{ playing }`                   |
-| 8   | `onFunctionButtonOpen`    | Krpano | useTourVisualizer | `{ buttonCode }`                |
-| 9   | `onMinimapToggle`         | Krpano | useTourVisualizer | `{ fullscreen }`                |
-| 10  | `onHotspotViewMore`       | UI     | HotspotOverview   | `{ poiCode, poiType }`          |
-| 11  | `onGalleryItemClick`      | UI     | HotspotOverview   | `{ id, poiCode }`               |
-| 12  | `onTextureSelected`       | UI     | HotspotOverview   | `{ index, poiCode }`            |
-
-## Usage Examples
-
-### Example 1: Google Analytics Tracking
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: (event) => {
-    gtag('event', event.actionName, {
-      event_category: 'showroom',
-      event_label: event.metadata?.tourCode,
-      value: JSON.stringify(event.payload),
-    });
-  },
-});
-```
-
-### Example 2: Custom Analytics Service
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: async (event) => {
-    await fetch('https://analytics.example.com/track', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        action: event.actionName,
-        data: event.payload,
-        timestamp: event.timestamp,
-        session: getSessionId(),
-        user: getUserId(),
-      }),
-    });
-  },
-});
-```
-
-### Example 3: Console Logging (Development)
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: (event) => {
-    console.group(`[${event.timestamp}] ${event.actionName}`);
-    console.log('Payload:', event.payload);
-    console.log('Tour:', event.metadata?.tourCode);
-    console.groupEnd();
-  },
-});
-```
-
-### Example 4: Multiple Tracking Services
-
-```typescript
-const trackToMultipleServices = async (event) => {
-  // Track to Google Analytics
-  gtag('event', event.actionName, { ...event.payload });
-
-  // Track to Mixpanel
-  mixpanel.track(event.actionName, event.payload);
-
-  // Track to custom backend
-  await logToBackend(event);
-};
-
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: trackToMultipleServices,
-});
-```
-
-### Example 5: Conditional Tracking
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: (event) => {
-    // Only track certain actions
-    const importantActions = [
-      'onPinActionClicked',
-      'onSceneChanged',
-      'onStartScenario',
-    ];
-
-    if (importantActions.includes(event.actionName)) {
-      analytics.track(event.actionName, event.payload);
-    }
-  },
-});
-```
-
-## Middleware Behavior
-
-### ✅ Always Fires
-
-Middleware executes even if no listeners are configured:
-
-```typescript
-// Middleware fires for all actions!
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: (event) => console.log(event.actionName),
-  // No listeners configured - middleware still works!
-});
-```
-
-### ✅ Non-Blocking
-
-Middleware does NOT block actions - it's for tracking only:
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: (event) => {
-    console.log('Tracking:', event.actionName);
-    // No return value needed - actions always proceed
-  },
-});
-```
-
-### ✅ Error Handling
-
-Middleware errors are caught and logged, but don't break the app:
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: (event) => {
-    // If this throws an error, it's caught and logged
-    // The action still proceeds normally
-    throw new Error('Oops!');
-  },
-});
-```
-
-### ✅ Async Support
-
-Middleware can be synchronous or asynchronous:
-
-```typescript
-// Sync middleware
-middleware: (event) => {
-  localStorage.setItem('lastAction', event.actionName);
-};
-
-// Async middleware (fire and forget)
-middleware: async (event) => {
-  await fetch('/track', { method: 'POST', body: JSON.stringify(event) });
-};
-```
-
-## TypeScript Types
-
-```typescript
-import { ActionMiddleware, ActionEvent } from '@clikvn/showroom-visualizer';
-
-// Define your middleware with types
-const myMiddleware: ActionMiddleware = (event: ActionEvent) => {
-  console.log(event.actionName, event.payload);
-};
-
-// Use in initialization
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-  middleware: myMiddleware,
-});
-```
-
-## Performance
-
-- **Zero overhead** when middleware not configured
-- **~1-2ms** per action when middleware configured
-- **Non-blocking** - uses fire-and-forget pattern
-- **Async-safe** - errors don't block the UI
-
-## Comparison with Listeners
-
-### Middleware
-
-- **Purpose**: Tracking/analytics
-- **Fires**: Always (even without listeners)
-- **Blocks actions**: No
-- **Use case**: Send data to external services
-
-### Listeners
-
-- **Purpose**: Custom app logic
-- **Fires**: Only if configured
-- **Blocks actions**: No (callbacks)
-- **Use case**: Communication between lib and app
-
-### Both Can Be Used Together
-
-```typescript
-ShowroomVisualizer.initVisualizer({
-  apiHost: 'https://api.clik.vn',
-  config: { tourCode: 'TOUR_123' },
-
-  // Middleware for tracking
-  middleware: (event) => {
-    analytics.track(event.actionName, event.payload);
-  },
-
-  // Listeners for custom logic
-  listeners: {
-    onPinActionClicked: (key) => {
-      if (key === 'FULLSCREEN') {
-        updateUIState({ fullscreen: true });
-      }
-    },
-    onSceneChanged: (scene) => {
-      updateBreadcrumbs(scene.name);
-    },
-  },
-});
-```
-
-## Components with Middleware
-
-Currently, middleware tracking is implemented across **5 locations**:
-
-### UI Layer Components (4 components)
-
-1. **PinActionButtons** (`src/components/SkinLayer/PinActionButtons/index.tsx`)
-   - `onPinActionClicked` - All action button clicks
-
-2. **SceneCategories** (`src/components/SkinLayer/SceneCategories/index.tsx`)
-   - `onSceneChanged` - Scene navigation
-
-3. **TourScenarios** (`src/components/SkinLayer/TourScenarios/index.tsx`)
-   - `onStartScenario` - Scenario playback
-
-4. **HotspotOverview** (`src/components/SkinLayer/HotspotOverview/index.tsx`)
-   - `onHotspotViewMore` - View more button clicks
-   - `onGalleryItemClick` - Gallery item clicks
-   - `onTextureSelected` - Texture selection
-
-### Krpano/POI Layer (1 hook)
-
-5. **useTourVisualizer** (`src/hooks/Visualizer/useTourVisualizer.ts`)
-   - `onPoiClicked` - POI clicks
-   - `onMovingPoiClick` - Moving POI clicks
-   - `onTexturePoiClick` - Texture POI clicks
-   - `onBackgroundSoundToggle` - Background sound control
-   - `onFunctionButtonOpen` - Function button opens
-   - `onMinimapToggle` - Minimap fullscreen toggle
-
-**Total**: 12 tracked actions across 5 locations
-
-## Architecture
-
-The middleware system tracks **UI layer and POI interactions only**:
-
-- **UI Components** use the `useActionMiddleware` hook to get the `trackAction` function
-- **useTourVisualizer hook** tracks POI clicks from the Krpano layer
-- **Tour Model** does not have tracking - keeping it focused on core tour logic
-- **Single source of truth** - all tracking logic exists only in `useActionMiddleware.ts`
-
-This ensures clean separation between business logic (Tour model) and tracking concerns (UI layer).
-
-## Adding Middleware to Custom Components
-
-If you're extending the library, add middleware to your components:
-
-```typescript
-import { useActionMiddleware } from '../../../hooks/useActionMiddleware';
-
-const MyComponent = () => {
-  const { trackAction } = useActionMiddleware();
-
-  const handleClick = () => {
-    // Track the action
-    trackAction('myCustomAction', { some: 'data' });
-
-    // Continue with your logic
-    doSomething();
-  };
-
-  return <button onClick={handleClick}>Click Me</button>;
-};
-```
-
-## FAQ
-
-**Q: Does middleware affect performance?**
-A: Minimal impact (~1-2ms per action). Uses fire-and-forget pattern.
-
-**Q: Can middleware cancel actions?**
-A: No. Middleware is tracking-only and cannot block actions.
-
-**Q: Do I need to configure listeners for middleware to work?**
-A: No. Middleware works independently of listeners.
-
-**Q: Can I use async operations in middleware?**
-A: Yes. Middleware supports both sync and async functions.
-
-**Q: What happens if middleware throws an error?**
-A: Errors are caught and logged. The action proceeds normally.
-
-**Q: Can I track actions from Krpano/POI layer?**
-A: Not directly. Use listeners for those events. Middleware tracks component-level actions.
-
-## Summary
-
-✅ **Tracking-only** - Does not block actions
-✅ **Always fires** - Even without listeners configured
-✅ **Error-safe** - Errors don't break the app
-✅ **Type-safe** - Full TypeScript support
-✅ **Async-ready** - Supports async operations
-✅ **Production-ready** - Tested and optimized
-
-For analytics, logging, and tracking needs - middleware is the perfect solution! 🎉

package/Planning/README.md

@@ -1,67 +0,0 @@
-# Planning Documentation
-
-This folder contains planning documents and specifications for features in the showroom-visualizer library.
-
-## Current Documentation
-
-### [README-middleware.md](./README-middleware.md)
-
-Complete documentation for the **Middleware/Analytics Tracking System**:
-
-- Overview and quick start guide
-- Event structure and types
-- All 12 tracked actions with examples
-- Usage examples (Google Analytics, custom services, conditional tracking)
-- Middleware behavior and error handling
-- TypeScript types and performance notes
-- Component architecture and integration
-
-## Documentation Structure
-
-Each feature should have its own markdown file following this structure:
-
-```markdown
-# Feature Name
-
-## Overview
-
-Brief description of the feature and its purpose
-
-## Quick Start
-
-Basic usage example
-
-## API Reference
-
-Detailed API documentation with types and examples
-
-## Architecture
-
-How the feature is implemented internally
-
-## Usage Examples
-
-Multiple real-world usage scenarios
-
-## FAQ
-
-Common questions and answers
-```
-
-## Adding New Features
-
-When planning a new feature:
-
-1. Create a new markdown file: `feature-name.md`
-2. Use the template structure above
-3. Include TypeScript examples
-4. Document all public APIs
-5. Add integration examples
-6. Link from the main README.md
-
-## Maintenance
-
-- Keep documentation up-to-date with code changes
-- Remove outdated planning documents after implementation
-- Archive old versions if needed for reference
-- Update this README when adding new features