@buildcores/render-client 1.0.0

package/README.md

@@ -0,0 +1,341 @@
+# @buildcores/render-client
+
+A React component library for interactive 360-degree PC build rendering with drag-to-scrub functionality. Create immersive 3D visualizations of computer builds that users can rotate and explore.
+
+<img src="./render-preview.png" alt="BuildRender Component" width="400">
+
+_Interactive 3D PC build that users can rotate by dragging_
+
+## 🚀 Installation
+
+```bash
+npm install @buildcores/render-client
+```
+
+## 📖 Quick Start
+
+```tsx
+import React from "react";
+import { BuildRender, getAvailableParts } from "@buildcores/render-client";
+
+function App() {
+  const parts = {
+    parts: {
+      CPU: ["7xjqsomhr"], // AMD Ryzen 7 9800X3D
+      GPU: ["z7pyphm9k"], // ASUS GeForce RTX 5080 ASTRAL
+      RAM: ["dpl1iyvb5"], // PNY DDR5
+      Motherboard: ["iwin2u9vx"], // Asus ROG STRIX X870E-E GAMING WIFI
+      PSU: ["m4kilv190"], // LIAN LI 1300W
+      Storage: ["0bkvs17po"], // SAMSUNG 990 EVO
+      PCCase: ["qq9jamk7c"], // MONTECH KING 95 PRO
+      CPUCooler: ["62d8zelr5"], // ARCTIC LIQUID FREEZER 360
+    },
+  };
+
+  return (
+    <div>
+      <BuildRender
+        parts={parts}
+        size={500}
+        mouseSensitivity={0.01}
+        touchSensitivity={0.01}
+      />
+    </div>
+  );
+}
+```
+
+## 🔧 API Reference
+
+### `BuildRender` Component
+
+The main React component for rendering interactive 3D PC builds.
+
+#### Props
+
+| Prop               | Type                 | Required | Default | Description                              |
+| ------------------ | -------------------- | -------- | ------- | ---------------------------------------- |
+| `parts`            | `RenderBuildRequest` | ✅       | -       | PC parts configuration object            |
+| `size`             | `number`             | ✅       | -       | Video size in pixels (square dimensions) |
+| `mouseSensitivity` | `number`             | ❌       | `0.01`  | Mouse drag sensitivity (0.001-0.1)       |
+| `touchSensitivity` | `number`             | ❌       | `0.01`  | Touch drag sensitivity (0.001-0.1)       |
+
+#### Parts Configuration
+
+The `parts` prop uses the `RenderBuildRequest` interface:
+
+```tsx
+interface RenderBuildRequest {
+  parts: {
+    [K in PartCategory]?: string[];
+  };
+}
+
+// Available part categories
+enum PartCategory {
+  CPU = "CPU",
+  GPU = "GPU",
+  RAM = "RAM",
+  Motherboard = "Motherboard",
+  PSU = "PSU",
+  Storage = "Storage",
+  PCCase = "PCCase",
+  CPUCooler = "CPUCooler",
+}
+```
+
+**Current Limitation**: Each category array must contain exactly one part ID. Multiple parts per category will be supported in future versions.
+
+#### Examples
+
+**Complete Build (All Components)**
+
+```tsx
+const completeBuild = {
+  parts: {
+    CPU: ["7xjqsomhr"], // AMD Ryzen 7 9800X3D
+    GPU: ["z7pyphm9k"], // ASUS GeForce RTX 5080 ASTRAL
+    RAM: ["dpl1iyvb5"], // PNY DDR5
+    Motherboard: ["iwin2u9vx"], // Asus ROG STRIX X870E-E GAMING WIFI
+    PSU: ["m4kilv190"], // LIAN LI 1300W
+    Storage: ["0bkvs17po"], // SAMSUNG 990 EVO
+    PCCase: ["qq9jamk7c"], // MONTECH KING 95 PRO
+    CPUCooler: ["62d8zelr5"], // ARCTIC LIQUID FREEZER 360
+  },
+};
+
+<BuildRender parts={completeBuild} size={500} />;
+```
+
+**Case Only (Minimal)**
+
+```tsx
+const caseOnly = {
+  parts: {
+    PCCase: ["qq9jamk7c"], // MONTECH KING 95 PRO
+  },
+};
+
+<BuildRender parts={caseOnly} size={500} />;
+```
+
+### `getAvailableParts()` Function
+
+Fetches all available PC parts from the BuildCores API.
+
+```tsx
+function getAvailableParts(): Promise<AvailablePartsResponse>;
+```
+
+#### Return Type
+
+```tsx
+interface PartDetails {
+  id: string; // Unique part identifier
+  name: string; // Human-readable part name
+  image: string; // URL to part image
+}
+
+type AvailablePartsResponse = {
+  [K in PartCategory]: PartDetails[];
+};
+```
+
+#### Example Response
+
+```json
+{
+  "CPU": [
+    {
+      "id": "7xjqsomhr",
+      "name": "AMD Ryzen 7 9800X3D",
+      "image": "https://example.com/cpu1.jpg"
+    },
+    {
+      "id": "x2thvstj3",
+      "name": "AMD Ryzen 7 9700X",
+      "image": "https://example.com/cpu2.jpg"
+    }
+  ],
+  "GPU": [
+    {
+      "id": "z7pyphm9k",
+      "name": "ASUS GeForce RTX 5080 ASTRAL",
+      "image": "https://example.com/gpu1.jpg"
+    },
+    {
+      "id": "4a0mjb360",
+      "name": "PNY GeForce RTX 5060 Ti 16GB",
+      "image": "https://example.com/gpu2.jpg"
+    }
+  ],
+  "RAM": [
+    {
+      "id": "dpl1iyvb5",
+      "name": "PNY DDR5",
+      "image": "https://example.com/ram1.jpg"
+    }
+  ],
+  "Motherboard": [
+    {
+      "id": "iwin2u9vx",
+      "name": "Asus ROG STRIX X870E-E GAMING WIFI",
+      "image": "https://example.com/mb1.jpg"
+    }
+  ],
+  "PSU": [
+    {
+      "id": "m4kilv190",
+      "name": "LIAN LI 1300W",
+      "image": "https://example.com/psu1.jpg"
+    }
+  ],
+  "Storage": [
+    {
+      "id": "0bkvs17po",
+      "name": "SAMSUNG 990 EVO",
+      "image": "https://example.com/storage1.jpg"
+    }
+  ],
+  "PCCase": [
+    {
+      "id": "qq9jamk7c",
+      "name": "MONTECH KING 95 PRO",
+      "image": "https://example.com/case1.jpg"
+    }
+  ],
+  "CPUCooler": [
+    {
+      "id": "62d8zelr5",
+      "name": "ARCTIC LIQUID FREEZER 360",
+      "image": "https://example.com/cooler1.jpg"
+    }
+  ]
+}
+```
+
+#### Usage Example
+
+```tsx
+import { useState, useEffect } from "react";
+import {
+  BuildRender,
+  getAvailableParts,
+  type AvailablePartsResponse,
+} from "@buildcores/render-client";
+
+function PCBuildConfigurator() {
+  const [availableParts, setAvailableParts] = useState<AvailablePartsResponse>(
+    {} as AvailablePartsResponse
+  );
+  const [selectedParts, setSelectedParts] = useState<Record<string, string>>(
+    {}
+  );
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    const fetchParts = async () => {
+      try {
+        const parts = await getAvailableParts();
+        setAvailableParts(parts);
+
+        // Set default selections (first part of each category)
+        const defaults: Record<string, string> = {};
+        Object.entries(parts).forEach(([category, partList]) => {
+          if (partList.length > 0) {
+            defaults[category] = partList[0].id;
+          }
+        });
+        setSelectedParts(defaults);
+      } catch (error) {
+        console.error("Failed to fetch available parts:", error);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchParts();
+  }, []);
+
+  if (isLoading) return <div>Loading parts...</div>;
+
+  // Build the parts object for BuildRender
+  const buildParts = {
+    parts: Object.fromEntries(
+      Object.entries(selectedParts).map(([category, partId]) => [
+        category,
+        [partId], // Wrap in array as required
+      ])
+    ),
+  };
+
+  return (
+    <div>
+      <BuildRender parts={buildParts} size={500} />
+
+      {/* Part selection UI */}
+      {Object.entries(availableParts).map(([category, parts]) => (
+        <div key={category}>
+          <h3>{category}</h3>
+          <select
+            value={selectedParts[category] || ""}
+            onChange={(e) =>
+              setSelectedParts((prev) => ({
+                ...prev,
+                [category]: e.target.value,
+              }))
+            }
+          >
+            {parts.map((part) => (
+              <option key={part.id} value={part.id}>
+                {part.name}
+              </option>
+            ))}
+          </select>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## ✨ Features
+
+- **🎮 Interactive Controls**: Drag with mouse or touch to rotate the 3D model
+- **📱 Mobile Support**: Optimized touch controls for mobile devices
+- **⚡ Real-time Rendering**: Dynamic video generation based on part selection
+- **💡 User Guidance**: Animated hints showing users they can interact
+- **📏 Responsive**: Adapts to any size you specify
+- **🔒 TypeScript**: Full TypeScript support with comprehensive types
+
+## 🔧 Configuration
+
+### Sensitivity Settings
+
+Fine-tune the drag sensitivity for different use cases:
+
+```tsx
+<BuildRender parts={parts} size={500} mouseSensitivity={0.003} />
+<BuildRender parts={parts} size={500} mouseSensitivity={0.01} />
+<BuildRender parts={parts} size={500} mouseSensitivity={0.02} />
+```
+
+### Size Configuration
+
+Set the display size based on your layout needs:
+
+```tsx
+<BuildRender parts={parts} size={500} />
+```
+
+## 📝 License
+
+ISC
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome! Please ensure TypeScript types are properly maintained.
+
+---
+
+Built with ❤️ for the PC building community

package/dist/BuildRender.d.ts

@@ -0,0 +1,2 @@
+import { BuildRenderProps } from "./types";
+export declare const BuildRender: React.FC<BuildRenderProps>;

package/dist/api.d.ts

@@ -0,0 +1,37 @@
+import { RenderBuildRequest, AvailablePartsResponse } from "./types";
+declare const API_BASE_URL = "https://squid-app-7aeyk.ondigitalocean.app";
+export declare const API_ENDPOINTS: {
+    readonly RENDER_BUILD_EXPERIMENTAL: "/render-build-experimental";
+    readonly AVAILABLE_PARTS: "/available-parts";
+};
+export interface RenderBuildResponse {
+    /**
+     * The rendered MP4 video as a Blob
+     */
+    video: Blob;
+    /**
+     * Optional metadata about the render
+     */
+    metadata?: {
+        duration?: number;
+        size?: number;
+        format?: string;
+    };
+}
+export interface RenderAPIService {
+    /**
+     * Submit a render build request
+     * @param parts - The parts configuration for the build
+     * @returns Promise with the rendered MP4 video
+     */
+    renderBuildExperimental(parts: RenderBuildRequest): Promise<RenderBuildResponse>;
+    /**
+     * Get available parts for building
+     * @returns Promise with available parts by category
+     */
+    getAvailableParts(): Promise<AvailablePartsResponse>;
+}
+export declare const buildApiUrl: (endpoint: string) => string;
+export declare const renderBuildExperimental: (request: RenderBuildRequest) => Promise<RenderBuildResponse>;
+export declare const getAvailableParts: () => Promise<AvailablePartsResponse>;
+export { API_BASE_URL };

package/dist/components/DragIcon.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+interface DragIconProps {
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const DragIcon: React.FC<DragIconProps>;
+export {};

package/dist/components/InstructionTooltip.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+interface InstructionTooltipProps {
+    isVisible: boolean;
+    progressValue: number;
+    instructionIcon?: string;
+}
+export declare const InstructionTooltip: React.FC<InstructionTooltipProps>;
+export {};

package/dist/components/LoadingErrorOverlay.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+interface LoadingErrorOverlayProps {
+    isVisible: boolean;
+    renderError?: string;
+    size: number;
+}
+export declare const LoadingErrorOverlay: React.FC<LoadingErrorOverlayProps>;
+export {};

package/dist/hooks/useBuildRender.d.ts

@@ -0,0 +1,12 @@
+import { RenderBuildRequest } from "../types";
+/**
+ * Compares two RenderBuildRequest objects for equality by checking if the same IDs
+ * are present in each category array, regardless of order.
+ */
+export declare const arePartsEqual: (parts1: RenderBuildRequest, parts2: RenderBuildRequest) => boolean;
+export interface UseBuildRenderReturn {
+    videoSrc: string | null;
+    isRenderingBuild: boolean;
+    renderError: string | null;
+}
+export declare const useBuildRender: (parts: RenderBuildRequest, onLoadStart?: () => void) => UseBuildRenderReturn;

package/dist/hooks/useProgressOneSecond.d.ts

@@ -0,0 +1,4 @@
+export declare function useBouncePatternProgress(enabled?: boolean): {
+    value: number;
+    isBouncing: boolean;
+};

package/dist/hooks/useVideoScrubbing.d.ts

@@ -0,0 +1,15 @@
+import { type RefObject } from "react";
+export declare const calculateCircularTime: (startTime: number, deltaX: number, sensitivity: number, duration: number) => number;
+interface UseVideoScrubbingOptions {
+    mouseSensitivity?: number;
+    touchSensitivity?: number;
+    progressSensitivity?: number;
+    useProgressScrubbing?: boolean;
+}
+export declare const useVideoScrubbing: (videoRef: RefObject<HTMLVideoElement | null>, options?: UseVideoScrubbingOptions) => {
+    isDragging: boolean;
+    handleMouseDown: (e: React.MouseEvent) => void;
+    handleTouchStart: (e: React.TouchEvent) => void;
+    hasDragged: import("react").MutableRefObject<boolean>;
+};
+export {};