@buildcores/render-client 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+import * as React$1 from 'react';
+import React__default, { RefObject } from 'react';
+
+interface BuildRenderProps {
+    /**
+     * Parts configuration for the build render.
+     *
+     * This object defines which PC components should be included in the 3D render.
+     * Each part category contains an array with a single part ID that will be rendered.
+     *
+     * **Current Limitation**: Only 1 part per category is supported. Arrays must contain
+     * exactly one part ID per category. Future versions will support multiple parts per category.
+     *
+     * @example
+     * ```tsx
+     * 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
+     *   }
+     * };
+     *
+     * <BuildRender parts={parts} size={300} />
+     * ```
+     *
+     * @example Minimal build (only required components)
+     * ```tsx
+     * const parts = {
+     *   parts: {
+     *     CPU: ["7xjqsomhr"],              // Single CPU required
+     *     Motherboard: ["iwin2u9vx"],      // Single motherboard required
+     *     PCCase: ["qq9jamk7c"],           // Single case required
+     *   }
+     * };
+     * ```
+     *
+     * Note: Part IDs must correspond to valid components in the BuildCores database.
+     * Use the available parts API to get valid part IDs for each category.
+     */
+    parts: RenderBuildRequest;
+    /**
+     * Video size in pixels (width and height will be the same).
+     *
+     * This determines the resolution of the rendered 3D video. Higher values
+     * provide better quality but may impact performance.
+     *
+     * @example
+     * ```tsx
+     * <BuildRender parts={parts} size={300} />  // 300x300px
+     * <BuildRender parts={parts} size={500} />  // 500x500px
+     * <BuildRender parts={parts} size={800} />  // 800x800px - high quality
+     * ```
+     *
+     * Recommended sizes:
+     * - 300px: Good for thumbnails or small previews
+     * - 500px: Standard size for most use cases
+     * - 800px+: High quality for detailed viewing
+     */
+    size: number;
+    /**
+     * Optional mouse sensitivity for dragging (default: 0.005).
+     *
+     * Controls how responsive the 3D model rotation is to mouse movements.
+     * Lower values make rotation slower and more precise, higher values make it faster.
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   parts={parts}
+     *   size={300}
+     *   mouseSensitivity={0.003}  // Slower, more precise
+     * />
+     *
+     * <BuildRender
+     *   parts={parts}
+     *   size={300}
+     *   mouseSensitivity={0.01}   // Faster rotation
+     * />
+     * ```
+     *
+     * @default 0.005
+     */
+    mouseSensitivity?: number;
+    /**
+     * Optional touch sensitivity for dragging (default: 0.01).
+     *
+     * Controls how responsive the 3D model rotation is to touch gestures on mobile devices.
+     * Generally set higher than mouseSensitivity for better touch experience.
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   parts={parts}
+     *   size={300}
+     *   touchSensitivity={0.008}  // Slower touch rotation
+     * />
+     *
+     * <BuildRender
+     *   parts={parts}
+     *   size={300}
+     *   touchSensitivity={0.015}  // Faster touch rotation
+     * />
+     * ```
+     *
+     * @default 0.01
+     */
+    touchSensitivity?: number;
+}
+/**
+ * Enum defining all available PC part categories that can be rendered.
+ *
+ * Each category represents a different type of computer component that can be
+ * included in the 3D build visualization.
+ *
+ * @example
+ * ```tsx
+ * // All available categories
+ * const categories = [
+ *   PartCategory.CPU,        // "CPU"
+ *   PartCategory.GPU,        // "GPU"
+ *   PartCategory.RAM,        // "RAM"
+ *   PartCategory.Motherboard,// "Motherboard"
+ *   PartCategory.PSU,        // "PSU"
+ *   PartCategory.Storage,    // "Storage"
+ *   PartCategory.PCCase,     // "PCCase"
+ *   PartCategory.CPUCooler,  // "CPUCooler"
+ * ];
+ * ```
+ */
+declare enum PartCategory {
+    /** Central Processing Unit - The main processor */
+    CPU = "CPU",
+    /** Graphics Processing Unit - Video card for rendering */
+    GPU = "GPU",
+    /** Random Access Memory - System memory modules */
+    RAM = "RAM",
+    /** Main circuit board that connects all components */
+    Motherboard = "Motherboard",
+    /** Power Supply Unit - Provides power to all components */
+    PSU = "PSU",
+    /** Storage devices like SSDs, HDDs, NVMe drives */
+    Storage = "Storage",
+    /** PC Case - The enclosure that houses all components */
+    PCCase = "PCCase",
+    /** CPU Cooler - Air or liquid cooling for the processor */
+    CPUCooler = "CPUCooler"
+}
+/**
+ * Request structure for rendering a PC build.
+ *
+ * This interface defines the parts configuration that will be sent to the
+ * rendering service to generate a 3D visualization of a PC build.
+ *
+ * **Current Limitation**: Only one part per category is supported. Each category
+ * array must contain exactly one part ID. Future versions will support multiple
+ * parts per category for comparison views.
+ *
+ * @example Basic build configuration
+ * ```tsx
+ * const buildRequest: RenderBuildRequest = {
+ *   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
+ *   }
+ * };
+ * ```
+ *
+ * @example Minimal build (only required components)
+ * ```tsx
+ * const minimalBuild: RenderBuildRequest = {
+ *   parts: {
+ *     CPU: ["7xjqsomhr"],              // Single CPU
+ *     Motherboard: ["iwin2u9vx"],      // Single motherboard
+ *     PCCase: ["qq9jamk7c"],           // Single case
+ *   }
+ * };
+ * ```
+ *
+ * @example Gaming build configuration
+ * ```tsx
+ * const gamingBuild: RenderBuildRequest = {
+ *   parts: {
+ *     CPU: ["x2thvstj3"],              // AMD Ryzen 7 9700X
+ *     GPU: ["4a0mjb360"],              // PNY GeForce RTX 5060 Ti 16GB
+ *     RAM: ["46rwpop35"],              // G.SKILL NEO RGB DDR5
+ *     Motherboard: ["xy81tonxw"],      // Asus ROG STRIX B850-A GAMING WIFI
+ *     PSU: ["v0qv6k9dp"],              // MSI 850W
+ *     Storage: ["0bs8cxv4c"],          // CORSAIR T500
+ *     PCCase: ["kb76dp9aw"],           // LIAN LI O11 VISION
+ *     CPUCooler: ["0vajcxkzq"],        // BE QUIET PURE ROCK 2 AIR
+ *   }
+ * };
+ * ```
+ */
+interface RenderBuildRequest {
+    /**
+     * Object mapping part categories to arrays of part IDs.
+     *
+     * **Current Requirements**:
+     * - Keys are part categories (CPU, GPU, RAM, etc.)
+     * - Values are arrays containing exactly one part ID string
+     * - All categories are optional - include only the parts you want to render
+     * - Part IDs must be valid identifiers from the BuildCores parts database
+     *
+     * **Future Enhancement**: Multiple parts per category will be supported for comparison views.
+     *
+     * @see PartCategory for all available categories
+     * @see AvailablePartsResponse for getting valid part IDs
+     */
+    parts: {
+        [K in PartCategory]?: string[];
+    };
+}
+/**
+ * Response structure containing all available parts for each category.
+ *
+ * This type represents the response from the available parts API endpoint,
+ * providing arrays of valid part IDs for each component category.
+ *
+ * @example Using available parts response
+ * ```tsx
+ * const availableParts: AvailablePartsResponse = {
+ *   CPU: [
+ *     { id: "7xjqsomhr", name: "AMD Ryzen 7 9800X3D", image: "https://..." },
+ *     { id: "x2thvstj3", name: "AMD Ryzen 7 9700X", image: "https://..." },
+ *   ],
+ *   GPU: [
+ *     { id: "z7pyphm9k", name: "ASUS GeForce RTX 5080 ASTRAL", image: "https://..." },
+ *     { id: "4a0mjb360", name: "PNY GeForce RTX 5060 Ti 16GB", image: "https://..." },
+ *   ],
+ *   // ... all other categories
+ * };
+ *
+ * // Select one part per category for current build request
+ * const buildRequest: RenderBuildRequest = {
+ *   parts: {
+ *     CPU: [availableParts.CPU[0].id],     // Select first available CPU ID
+ *     GPU: [availableParts.GPU[1].id],     // Select second available GPU ID
+ *     RAM: [availableParts.RAM[0].id],     // Select first available RAM ID
+ *   }
+ * };
+ * ```
+ *
+ * @example Dynamic part selection
+ * ```tsx
+ * // Function to create build with user-selected parts
+ * const createBuild = (selectedPartIds: Record<string, string>) => {
+ *   const buildRequest: RenderBuildRequest = {
+ *     parts: {
+ *       CPU: [selectedPartIds.cpu],          // Single selected CPU ID
+ *       GPU: [selectedPartIds.gpu],          // Single selected GPU ID
+ *       RAM: [selectedPartIds.ram],          // Single selected RAM ID
+ *       // ... other single selections
+ *     }
+ *   };
+ *   return buildRequest;
+ * };
+ * ```
+ */
+/**
+ * Individual part information with details
+ */
+interface PartDetails {
+    /** Unique part identifier */
+    id: string;
+    /** Human-readable part name */
+    name: string;
+    /** URL to part image */
+    image: string;
+}
+type AvailablePartsResponse = {
+    [K in PartCategory]: PartDetails[];
+};
+
+declare const BuildRender: React.FC<BuildRenderProps>;
+
+declare const calculateCircularTime: (startTime: number, deltaX: number, sensitivity: number, duration: number) => number;
+interface UseVideoScrubbingOptions {
+    mouseSensitivity?: number;
+    touchSensitivity?: number;
+    progressSensitivity?: number;
+    useProgressScrubbing?: boolean;
+}
+declare const useVideoScrubbing: (videoRef: RefObject<HTMLVideoElement | null>, options?: UseVideoScrubbingOptions) => {
+    isDragging: boolean;
+    handleMouseDown: (e: React.MouseEvent) => void;
+    handleTouchStart: (e: React.TouchEvent) => void;
+    hasDragged: React$1.MutableRefObject<boolean>;
+};
+
+declare function useBouncePatternProgress(enabled?: boolean): {
+    value: number;
+    isBouncing: boolean;
+};
+
+/**
+ * Compares two RenderBuildRequest objects for equality by checking if the same IDs
+ * are present in each category array, regardless of order.
+ */
+declare const arePartsEqual: (parts1: RenderBuildRequest, parts2: RenderBuildRequest) => boolean;
+interface UseBuildRenderReturn {
+    videoSrc: string | null;
+    isRenderingBuild: boolean;
+    renderError: string | null;
+}
+declare const useBuildRender: (parts: RenderBuildRequest, onLoadStart?: () => void) => UseBuildRenderReturn;
+
+interface DragIconProps {
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare const DragIcon: React__default.FC<DragIconProps>;
+
+interface LoadingErrorOverlayProps {
+    isVisible: boolean;
+    renderError?: string;
+    size: number;
+}
+declare const LoadingErrorOverlay: React__default.FC<LoadingErrorOverlayProps>;
+
+interface InstructionTooltipProps {
+    isVisible: boolean;
+    progressValue: number;
+    instructionIcon?: string;
+}
+declare const InstructionTooltip: React__default.FC<InstructionTooltipProps>;
+
+declare const API_BASE_URL = "https://squid-app-7aeyk.ondigitalocean.app";
+declare const API_ENDPOINTS: {
+    readonly RENDER_BUILD_EXPERIMENTAL: "/render-build-experimental";
+    readonly AVAILABLE_PARTS: "/available-parts";
+};
+interface RenderBuildResponse {
+    /**
+     * The rendered MP4 video as a Blob
+     */
+    video: Blob;
+    /**
+     * Optional metadata about the render
+     */
+    metadata?: {
+        duration?: number;
+        size?: number;
+        format?: string;
+    };
+}
+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>;
+}
+declare const buildApiUrl: (endpoint: string) => string;
+declare const renderBuildExperimental: (request: RenderBuildRequest) => Promise<RenderBuildResponse>;
+declare const getAvailableParts: () => Promise<AvailablePartsResponse>;
+
+export { API_BASE_URL, API_ENDPOINTS, BuildRender, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, calculateCircularTime, getAvailableParts, renderBuildExperimental, useBouncePatternProgress, useBuildRender, useVideoScrubbing };
+export type { AvailablePartsResponse, BuildRenderProps, PartDetails, RenderAPIService, RenderBuildRequest, RenderBuildResponse, UseBuildRenderReturn };