HexGrid 3D

A reusable 3D hexagonal grid visualization component for displaying content in an immersive spherical layout.

Features

- 3D Hexagonal Grid Layout - Spherical projection with customizable curvature
- Interactive Camera Controls - Pan, zoom, inside/outside views with smooth transitions
- Image Texture Mapping - Automatic texture loading and caching
- Real-time Statistics - Live telemetry and performance metrics
- Narration System - Play-by-play commentary overlay
- Web Worker Rendering - High-performance offloaded calculations
- Multi-Input Support - Touch gestures, mouse, and keyboard controls
- Responsive Design - Adapts to mobile and desktop viewports
- Dynamic Theming - Accent color extraction from images
- Autoplay Mode - Queue-based content cycling
- Hardware Acceleration - Supports WebNN (NPU) and WebGPU for massive fluid/particle simulation

Installation

``bash
npm install @buley/hexgrid-3d
`

Usage

$3

`tsx
import { HexGrid, Photo } from "@buley/hexgrid-3d";

function MyComponent() {
const photos: Photo[] = [
{
id: "1",
url: "https://example.com/photo.jpg",
source: "example",
createdAt: new Date().toISOString(),
},
];

return (
photos={photos}
onHexClick={(photo) => console.log("Clicked:", photo)}
/>
);
}
`

$3

`tsx
import { HexGrid, Photo, uiStore } from "@buley/hexgrid-3d";
import { useRef, useState } from "react";

function AdvancedExample() {
const canvasRef = useRef(null);
const [modalOpen, setModalOpen] = useState(false);

return (



);
}
`

Components

$3

Main visualization component that renders a 3D hexagonal grid on a spherical surface.

Props:

| Prop | Type | Default | Description |
| ---------------------------- | ------------------------------------ | ------- | ---------------------------------------------- |
| photos | Photo[] | [] | Array of photos to display in the grid |
| onHexClick | (photo: Photo) => void | - | Callback when a hex tile is clicked |
| spacing | number | 1.0 | Grid spacing multiplier (affects tile density) |
| canvasRef | React.RefObject | - | Optional external canvas reference |
| onLeaderboardUpdate | (leaderboard: any) => void | - | Callback for leaderboard statistics updates |
| autoplayQueueLimit | number | - | Maximum items in autoplay queue |
| onAutoplayQueueLimitChange | (limit: number) => void | - | Callback when autoplay limit changes |
| modalOpen | boolean | false | Whether a modal is currently open |
| userId | string | - | Current user ID for personalization |
| username | string | - | Current username for display |

$3

Displays narration messages and real-time statistics in a dashboard-style overlay.

Props:

| Prop | Type | Description |
| -------------- | -------------------- | -------------------------------------- |
| messages | NarrationMessage[] | Array of narration messages to display |
| statsTracker | StatsTracker | Statistics tracker instance |
| isVisible | boolean | Whether overlay is visible |
| onClose | () => void | Callback when overlay is closed |

Types

$3

`typescript
interface Photo {
id: string;
url: string;
thumbnailUrl?: string;
title?: string;
description?: string;
source: string;
createdAt: string;
userId?: string;
username?: string;
videoUrl?: string;
platform?: string;
author?: string;
authorUrl?: string;
likes?: number;
views?: number;
comments?: number;
dominantColor?: string;
}
`

Stores

$3

Global UI state management for visualization components.

Methods:

- uiStore.toggleDebug() - Toggle debug panel
- uiStore.toggleStats() - Toggle statistics overlay
- uiStore.toggleCamera() - Toggle camera controls
- uiStore.toggleNarration() - Toggle narration overlay
- uiStore.set(state) - Update multiple state values
- uiStore.subscribe(callback) - Subscribe to state changes

State:

`typescript
interface UIState {
debugOpen: boolean;
showStats: boolean;
cameraOpen: boolean;
showNarration: boolean;
}
`

Camera Controls

$3

- Left Click + Drag - Rotate camera (yaw and pitch)
- Scroll - Zoom in/out
- Click on Hex - Select photo

$3

- Single Touch Drag - Rotate camera
- Pinch - Zoom in/out
- Tap on Hex - Select photo

$3

- D - Toggle debug panel
- Escape - Close debug panel

Performance

The component uses a Web Worker for heavy calculations to maintain 60fps rendering:

- Streaming Rendering - Progressively renders tiles
- Texture Caching - Reuses loaded images
- Adaptive Quality - Adjusts detail based on performance
- Low-Res Mode - Optional reduced quality for slower devices

Theming

The component integrates with your app's theme system and can extract accent colors from images:

`tsx
import { getAccentRgba, setCustomAccentColor } from "@/lib/theme-colors";

// Custom accent color from image
setCustomAccentColor("#ff00ff");
`

Dependencies

$3

- react ^18.0.0
- react-dom ^18.0.0
- next ^14.0.0
- three (Three.js for 3D calculations)

$3

- @/lib/stats-tracker - Statistics tracking
- @/lib/narration - Narration engine
- @/lib/logger - Logging utilities
- @/lib/theme-colors - Theme system integration
- @/lib/html-utils - HTML utilities

Development

$3

`bash
npm run build
`

$3

`bash
npm run dev
`

Architecture

`
hexgrid-3d/
├── src/
│ ├── components/ # React components
│ │ ├── HexGrid.tsx
│ │ └── NarrationOverlay.tsx
│ ├── stores/ # State management
│ │ └── uiStore.ts
│ ├── workers/ # Web Workers
│ │ └── hexgrid-worker.worker.ts
│ ├── types.ts # TypeScript definitions
│ └── index.ts # Main exports
├── public/ # Static assets
│ └── hexgrid-worker.js
├── examples/ # Usage examples
│ └── basic-usage.tsx
└── tests/ # Test suites
├── unit/
├── integration/
└── e2e/
`

Testing

$3

`bash
npm test
`

$3

`bash
npm run test:watch
`

$3

`bash
npm run test:coverage
`

$3

`bash
npm run test:e2e
``

License

Personal Use Only - See LICENSE file for full terms.

This software is provided for personal, non-commercial use only. Commercial use,
redistribution, and sublicensing are prohibited. All intellectual property
rights are reserved by the copyright holder.