Adds SplatViewer progress bar (#154)

* Initial onProgress implementation

* Refactor useAsset hook to support options for props and progress callback

- Updated useAsset to accept an options object, allowing for additional properties and a subscribe callback for loading progress.
- Adjusted fetchAsset calls to utilize the new options structure.
- Updated related hooks (useSplat, useTexture, useEnvAtlas, useModel) to align with the new useAsset signature.
- Enhanced documentation to reflect changes in API and usage.

* Enhance useAsset hook and documentation for improved asset loading

- Refactored useAsset to accept an options object, allowing for additional properties and a subscribe callback for loading progress.
- Updated related hooks (useSplat, useTexture, useEnvAtlas, useModel) to align with the new useAsset signature.
- Added documentation for the new loading progress feature and updated API references accordingly.
- Introduced a new index page for hooks documentation.

* Add Progress component and update context for asset loading progress

- Introduced a new Progress component to visually indicate asset loading progress.
- Enhanced AssetViewerContext to include asset and error states, along with a subscribeToProgress method for tracking loading progress.
- Updated SplatViewer and related components to integrate the new Progress component.
- Added a useSubscribe hook for managing subscription to progress updates.
- Updated documentation to reflect the addition of the Progress component.

* Comment out unused useFrame hook in Progress component

* Refactor useAsset hook and update related hooks for improved prop handling

- Changed useAsset to accept props directly instead of an options object, simplifying the API.
- Updated useSplat, useTexture, useEnvAtlas, and useModel hooks to align with the new useAsset signature.
- Enhanced documentation to reflect changes in parameter types and usage.
- Updated fetchAsset utility to support new prop structure and progress callback.

* Update useModel documentation to reflect removal of subscribe callback

- Adjusted the documentation for the useModel hook to clarify that the subscribe callback has been removed from the props parameter.
- Ensured consistency with the updated useAsset hook signature.

* Refactor Progress component and update asset viewer context

- Refactored the Progress component to improve its functionality and styling, allowing for customizable visibility and width transitions.
- Updated the AssetViewerContext to streamline the subscription method for asset progress updates.
- Enhanced the SplatViewer component to utilize the new Progress component and handle asset progress callbacks.
- Adjusted documentation to reflect changes in the Progress component and its integration within the viewer.

* Enhance Progress component and SplatViewer asset progress handling

- Added a timeout reference in the Progress component to manage visibility more effectively after progress completion.
- Updated the cleanup function in the Progress component to clear the timeout if it exists, preventing potential memory leaks.
- Modified the SplatViewer component to include the 'notify' function in the dependency array of the asset progress callback, ensuring proper updates during re-renders.

* Update packages/docs/content/docs/api/hooks/index.mdx

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: marklundin

packages/blocks/src/index.ts

@@ -1,42 +1,3 @@
-
 // Splat Viewer
 import * as Viewer from "./splat-viewer"
 export { Viewer };
-
-// export const MUPS = {
-//   hello: () => console.log("hello from MUPS"),
-//   // HelpButton,
-// };
-// import { HelpButton } from './splat-viewer/help-button';
-
-// Controls: SplatViewer.Controls,
-// FullScreenButton: SplatViewer.FullScreenButton,
-// DownloadButton: SplatViewer.DownloadButton,
-// MenuButton: SplatViewer.MenuButton,
-// CameraModeToggle: SplatViewer.CameraModeToggle,
-// Splat: SplatViewer.Splat,
-// etc...
-
-// import { FullScreenButton } from "./splat-viewer/full-screen-button"
-// import { DownloadButton } from "./splat-viewer/download-button"
-// import { MenuButton } from "./splat-viewer/menu-button"
-// import { Controls } from "./splat-viewer/controls"
-// import { CameraModeToggle } from "./splat-viewer/camera-mode-toggle"
-// import { HelpButton } from "./splat-viewer/help-button"
-// import { SplatViewer } from "./splat-viewer/splat-viewer"
-
-// Export namespace for MDX
-// const Viewer = {
-//   Splat: SplatViewer,
-//   FullScreenButton,
-//   DownloadButton,
-//   MenuButton,
-//   Controls,
-//   CameraModeToggle,
-//   HelpButton,
-// };
-
-// console.log('[DEBUG] Exporting Viewer keys:', Object.keys(Viewer));
-
-// export { Viewer };
-

packages/blocks/src/splat-viewer/hooks/use-subscribe.ts

@@ -0,0 +1,25 @@
+import { useCallback, useRef } from 'react';
+
+/**
+ * A hook for subscribing to a value.
+ * @example
+ * const { subscribe, notify } = useSubscribe<number>();
+ * subscribe((value) => console.log(value));
+ * notify(1);
+ * 
+ * @returns A tuple of `subscribe` and `notify` functions.
+ */
+export function useSubscribe<T>() {
+  const subscribers = useRef(new Set<(value: T) => void>());
+
+  const subscribe = useCallback((fn: (value: T) => void) => {
+    subscribers.current.add(fn);
+    return () => subscribers.current.delete(fn);
+  }, []);
+
+  const notify = useCallback((value: T) => {
+    subscribers.current.forEach((fn) => fn(value));
+  }, []);
+
+  return { subscribe, notify };
+} 

packages/blocks/src/splat-viewer/index.ts

@@ -5,6 +5,7 @@ import { Controls } from "./controls"
 import { CameraModeToggle } from "./camera-mode-toggle"
 import { HelpButton } from "./help-button"
 import { SplatViewer } from "./splat-viewer"
+import { Progress } from "./progress-indicator"
 
 export {
   FullScreenButton,
@@ -14,4 +15,5 @@ export {
   CameraModeToggle,
   HelpButton,
   SplatViewer as Splat,
+  Progress,
 };

packages/blocks/src/splat-viewer/progress-indicator.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useAssetViewer } from "./splat-viewer-context";
+import { cn } from "@lib/utils";
+
+type ProgressProps = {
+  variant?: "top" | "bottom";
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+export function Progress({ variant = "top", className, style }: ProgressProps) {
+  const { subscribe } = useAssetViewer();
+  const ref = useRef<HTMLDivElement>(null);
+  const [visible, setVisible] = useState(true);
+  const timeoutRef = useRef<number>(null);
+
+  useEffect(() => {
+    const unsubscribe = subscribe((progress) => {
+      if (!ref.current) return;
+      ref.current.style.width = `${progress * 100}%`;
+
+      if (progress >= 1) {
+        timeoutRef.current = setTimeout(() => setVisible(false), 500);
+      } else {
+        setVisible(true);
+      }
+    });
+
+    return () => {
+      unsubscribe();
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, [subscribe]);
+
+  if (!visible) return null;
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "absolute left-0 w-full h-1 bg-accent transition-[width] duration-300 will-change-[width]",
+        variant === "top" && "top-0",
+        variant === "bottom" && "bottom-0",
+        className
+      )}
+      style={{ width: "0%", ...style }}
+    />
+  );
+}

packages/blocks/src/splat-viewer/splat-viewer-context.tsx

@@ -2,9 +2,9 @@
 
 import { createContext, useCallback, useEffect, useState, useContext, ReactNode, useRef } from "react";
 import { CameraMode } from "./splat-viewer";
+import { useSubscribe } from "./hooks/use-subscribe";
 
 type AssetViewerContextValue = {
-
   /**
    * Whether the viewer is in fullscreen mode.
    */
@@ -60,6 +60,11 @@ type AssetViewerContextValue = {
    * Toggles the auto rotate.
    */
   setAutoRotate: (autoRotate: boolean) => void;
+
+  /**
+   * Subscribes to the asset progress.
+   */
+  subscribe: (fn: (progress: number) => void) => () => void;
 };
 
 export const AssetViewerContext = createContext<AssetViewerContextValue | undefined>(undefined);
@@ -88,14 +93,17 @@ export function AssetViewerProvider({
   mode,
   setMode,
   src,
+  subscribe,
 }: {
   children: React.ReactNode;
   autoPlay?: boolean;
   targetRef: React.RefObject<HTMLElement>;
   src: string;
   mode: CameraMode;
   setMode: (mode: CameraMode) => void;
+  subscribe: (fn: (progress: number) => void) => () => void;
 }) {
+  
   const [isFullscreen, setIsFullscreen] = useState(false);
   const [overlay, setOverlay] = useState<"help" | "settings" | null>(null);
   const [autoRotate, setAutoRotate] = useState(false);
@@ -196,7 +204,8 @@ export function AssetViewerProvider({
         setOverlay,
         triggerDownload,
         autoRotate,
-        setAutoRotate
+        setAutoRotate,
+        subscribe
       }}
     >
       <TimelineProvider autoPlay={autoPlay}>
@@ -234,26 +243,21 @@ export function TimelineProvider({
   const [isPlaying, setIsPlaying] = useState(autoPlay);
   const timeRef = useRef(time);
   const rafIdRef = useRef<number | null>(null);
-  const subscribers = useRef(new Set<(v: number) => void>());
+  const { subscribe, notify } = useSubscribe<number>();
 
   const setTime = useCallback((value: number) => {
     timeRef.current = value;
-    subscribers.current.forEach((fn) => fn(value));
-  }, []);
+    notify(value);
+  }, [notify]);
 
   const getTime = useCallback(() => timeRef.current, []);
 
-  const subscribe = useCallback((fn: (v: number) => void) => {
-    subscribers.current.add(fn);
-    return () => subscribers.current.delete(fn);
-  }, []);
-
   // Example: when time is changed and user commits it
   const onCommit = useCallback((value: number) => {
     timeRef.current = value;
     setTime(value);
     _setTime(value);
-  }, []);
+  }, [setTime]);
 
   const lastTimestampRef = useRef<number | null>(null);
 

packages/blocks/src/splat-viewer/splat-viewer.tsx

@@ -12,6 +12,7 @@ import { SmartCamera } from "./smart-camera"
 import { HelpDialog } from "./help-dialog"
 import { FILLMODE_NONE } from "playcanvas"
 import { RESOLUTION_AUTO } from "playcanvas"
+import { useSubscribe } from "./hooks/use-subscribe"
 export type CameraMode = 'orbit' |  'fly';
 
 type CameraControlsProps = {
@@ -38,6 +39,7 @@ type SplatViewerComponentProps = CameraControlsProps & {
      * The url of an image to display whilst the asset is loading.
      */
     src: string,
+
     /**
      * The track to use for the animation 
      */
@@ -53,6 +55,11 @@ type SplatViewerComponentProps = CameraControlsProps & {
      * A callback function for when the type of camera changes
      */
     onTypeChange?: (type: 'orbit' | 'fly') => void,
+
+    /**
+     * A callback function for when the asset progress changes
+     */
+    onAssetProgress?: (progress: number) => void,
 }
 
 type PosterComponentProps = {
@@ -75,11 +82,11 @@ export type SplatViewerProps = SplatViewerComponentProps & PosterComponentProps
     children?: React.ReactNode,
 }
 
-function SplatComponent({ 
-    src
+function SplatComponent({
+    src,
+    onAssetProgress
 }: SplatViewerComponentProps) {
-
-    const { asset, error } = useSplat(src)
+    const { asset, error, subscribe } = useSplat(src);
     const { isInteracting } = useAssetViewer();
     const { isPlaying } = useTimeline();
     const app = useApp();
@@ -89,6 +96,10 @@ function SplatComponent({
         return () => asset?.unload();
     }, [asset]);
 
+    useEffect(() => {
+        return subscribe(({ progress }) => onAssetProgress?.(progress));
+    }, [subscribe, onAssetProgress]);
+
     // Hide the cursor when the timeline is playing and the user is not interacting
     useEffect(() => {
         if (app.graphicsDevice.canvas) {
@@ -129,10 +140,12 @@ export function SplatViewer( {
     defaultMode = 'orbit',
     onTypeChange,
     className, 
-    children, 
-    ...props 
+    children
 } : SplatViewerProps) {
 
+    const { subscribe, notify } = useSubscribe<number>();
+    const onAssetProgress = useCallback((progress: number) => notify(progress), [src, notify]);
+
     const isControlled = !mode;
     const containerRef = useRef<HTMLDivElement>(null!);
     const [uncontrolledMode, setUncontrolledMode] = useState<CameraMode>(
@@ -156,13 +169,14 @@ export function SplatViewer( {
                 src={src}
                 mode={currentMode}
                 setMode={setCameraMode}
+                subscribe={subscribe}
             >
                 <Suspense fallback={<PosterComponent poster={poster} />} >
                     <Application fillMode={FILLMODE_NONE} resolutionMode={RESOLUTION_AUTO} autoRender={false}>
-                        <SplatComponent src={src} {...props} />
+                        <SplatComponent src={src} onAssetProgress={onAssetProgress} />
                     </Application>
                     <TooltipProvider>
-                        {children}
+                        { children }
                     </TooltipProvider>
                 </Suspense>
                 <HelpDialog />

packages/docs/content/blocks/index.mdx

@@ -26,7 +26,9 @@ export const splatVersion = registry.items.find(item => item.name === 'splat-vie
     High-level 3D primitives for React — minimal setup and beautiful by default.
 </div>
 
-PlayCanvas Blocks are high-level component primitives for React. Clean, simple, and beautiful by default, they're designed to drop into your project and get to work. Built around **@playcanvas/react** and **@shadcn/ui** they're composable, themeable and ready to use out of the box.
+PlayCanvas Blocks are high-level component primitives for React. Clean, simple, and beautiful by default, they're designed to drop into your project and get to work. 
+
+Built on **@playcanvas/react** and compatible with **@shadcn/ui** they're composable, themeable and ready to use out of the box.
 
 <div className='flex flex-row gap-2 mt-4 items-center'>
     <a className="flex items-center -ml-2 flex-row gap-2 bg-muted rounded-full p-2 px-4 max-w-fit" href="blocks/installation">
@@ -42,10 +44,12 @@ PlayCanvas Blocks are high-level component primitives for React. Clean, simple,
 </div>
 
 <div className='relative mb-4 lg:mb-12'>
-    <Viewer.Splat src={splatUrl} className="aspect-4:1 mt-8 lg:my-8 -mx-4 lg:-mx-6 bg-gray-200 lg:rounded-lg shadow-xl cursor-grab active:cursor-grabbing" />
+    <Viewer.Splat src={splatUrl} className="aspect-4:1 mt-8 lg:my-8 -mx-4 lg:-mx-6 bg-gray-200 md:rounded-lg shadow-xl cursor-grab active:cursor-grabbing" >
+        <Viewer.Progress className="bg-[#e0004d]" />
+    </Viewer.Splat>
     <div className='lg:absolute bottom-0 right-0 w-full py-2 lg:py-8 lg:text-background text-xs italic text-center pointer-events-none'>
         <span className="pointer-events-auto">
-            Rendered with the <code>Viewer.Splat</code> component — a React block for Gaussian splats.{" "}
+            Rendered with the <code>Splat</code> block — a React component for Gaussian splats.{" "}
             <a className="underline text-bold" href="/blocks/splat-viewer">Learn more →</a>
         </span>
     </div>
@@ -87,7 +91,7 @@ PlayCanvas Blocks are high-level component primitives for React. Clean, simple,
 
 ## How it works?
 
-Built on @playcanvas/react and the PlayCanvas engine, Blocks abstract the underlying engine to provide a high-level component API that's easy to use and understand. Internally, each block maps to a PlayCanvas entity and component hierarchy, giving you full control with a familiar dev experience.
+Built on **@playcanvas/react** and the PlayCanvas engine, Blocks abstract the underlying engine to provide a high-level component API that's easy to use and understand. Internally, each block maps to a PlayCanvas entity and component hierarchy, giving you full control with a familiar dev experience.
 
 ## Featured blocks
 

packages/docs/content/blocks/splat-viewer.mdx

@@ -17,6 +17,7 @@ Supports compressed gaussian splats.
 <div className="lg:outline lg:p-28 -mx-4 lg:-mx-6 mt-12 mb-0 rounded-t-lg bg-linear-to-br from-indigo-500 to-purple-600 relative">
   <OpenInV0Button url={`https://${process.env.VERCEL_URL}/r/splat-viewer.json`} className="absolute top-4 right-4" />
   <Viewer.Splat src={splatUrl} className="aspect-2.39:1 bg-purple-200 rounded-t-lg lg:rounded-lg shadow-xl cursor-grab active:cursor-grabbing" >
+      <Viewer.Progress className="bg-[#8a01ff]" />
       <Viewer.Controls autoHide >
         <div className="flex gap-1 flex-grow">
             <Viewer.FullScreenButton />
@@ -39,6 +40,7 @@ Supports compressed gaussian splats.
             export function SplatViewerDemo() {
               return (
                 <Viewer.Splat src={splatUrl} autoPlay >
+                  <Viewer.Progress />
                   <Viewer.Controls >
                     <div className="flex gap-2 flex-grow">
                         <Viewer.FullScreenButton />
@@ -146,6 +148,7 @@ export default () => (
       <Viewer.DownloadButton />
       <Viewer.CameraModeToggle />
       <Viewer.MenuButton />
+      <Viewer.Progress />
     </Viewer.Controls>
   </Viewer.Viewer>
 )

packages/docs/content/docs/api/hooks/index.mdx

@@ -12,7 +12,7 @@ openGraph:
 
 # Hooks
 
-The are a a number of important hooks that are useful when working with `@playcanvas/react`. These can often be useful when creating custom components, hooks or utilities.
+There are a number of important hooks that are useful when working with `@playcanvas/react`. These can often be useful when creating custom components, hooks or utilities.
 
 ## useApp