Expose usePhysics hook (#229)

* feat(physics): introduce usePhysics hook and enhance physics context documentation

- Added the `usePhysics` hook to provide access to physics state information, including whether physics is enabled and loaded, as well as any loading errors.
- Updated the physics context type definitions with detailed JSDoc comments for better clarity.
- Enhanced documentation for the `usePhysics` hook with usage examples and return value descriptions.
- Exported the `usePhysics` hook and its type from the physics context module.

* feat(physics): add usePhysics hook to access physics engine state

Author: marklundin

.changeset/open-berries-attend.md

@@ -0,0 +1,5 @@
+---
+"@playcanvas/react": minor
+---
+
+Exposes a new usePhysics hook to determine physics engine state

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

@@ -155,4 +155,70 @@ useFrame((dt) => {
 useAppEvent('update', (dt) => {
   // your frame logic
 });
-```
+```
+
+## usePhysics
+
+The `usePhysics` hook provides access to physics context information, allowing you to check the physics state and handle physics-related errors. This hook is particularly useful when working with physics-enabled applications.
+
+```jsx
+import { usePhysics } from '@playcanvas/react/hooks'
+
+const PhysicsStatus = () => {
+  const { isPhysicsEnabled, isPhysicsLoaded, physicsError } = usePhysics();
+
+  if (physicsError) {
+    return <div>Physics error: {physicsError.message}</div>;
+  }
+
+  if (!isPhysicsLoaded) {
+    return <div>Loading physics...</div>;
+  }
+
+  return <div>Physics is ready!</div>;
+};
+```
+
+### Return Value
+
+The hook returns an object with the following properties:
+
+- **`isPhysicsEnabled`**: `boolean` - Whether physics is enabled on the application
+- **`isPhysicsLoaded`**: `boolean` - Whether the physics library has been successfully loaded
+- **`physicsError`**: `Error | null` - The error that occurred when loading physics, if any
+
+### Usage with Physics Components
+
+This hook is commonly used alongside physics components like `RigidBody` and `Collision` to provide user feedback about physics state:
+
+```jsx
+import { usePhysics } from '@playcanvas/react/hooks'
+
+const PhysicsAwareComponent = () => {
+  const { isPhysicsEnabled, isPhysicsLoaded, physicsError } = usePhysics();
+
+  if (!isPhysicsEnabled) {
+    console.warn('Physics is not enabled on this application');
+    return null;
+  }
+
+  if (physicsError) {
+    console.error('Failed to load physics', physicsError);
+    return null;
+  }
+
+  if (!isPhysicsLoaded) {
+    console.log('Loading physics library...');
+    return null;
+  }
+
+  return (
+    <Entity>
+      <RigidBody type="dynamic" />
+      <Collision type="box" />
+    </Entity>
+  );
+};
+```
+
+**Note**: This hook requires the application to have physics enabled via the `usePhysics` prop on the `Application` component.

packages/lib/src/contexts/physics-context.tsx

@@ -1,9 +1,21 @@
 import React, { createContext, useContext, useEffect, useState } from 'react';
 import { AppBase } from 'playcanvas';
 
-interface PhysicsContextType {
+/**
+ * Physics context type containing physics state information.
+ */
+export interface PhysicsContextType {
+  /**
+   * Whether physics is enabled on the application.
+   */
   isPhysicsEnabled: boolean;
+  /**
+   * Whether the physics library has been successfully loaded.
+   */
   isPhysicsLoaded: boolean;
+  /**
+   * The error that occurred when loading physics, if any.
+   */
   physicsError: Error | null;
 }
 
@@ -16,6 +28,30 @@ const PhysicsContext = createContext<PhysicsContextType>({
 // Track how many Application instances are using physics
 let physicsInstanceCount = 0;
 
+/**
+ * Hook to access physics context information.
+ * 
+ * @returns Physics context containing physics state information
+ * 
+ * @example
+ * ```tsx
+ * import { usePhysics } from '@playcanvas/react/hooks';
+ * 
+ * const MyComponent = () => {
+ *   const { isPhysicsEnabled, isPhysicsLoaded, physicsError } = usePhysics();
+ * 
+ *   if (physicsError) {
+ *     return <div>Physics error: {physicsError.message}</div>;
+ *   }
+ * 
+ *   if (!isPhysicsLoaded) {
+ *     return <div>Loading physics...</div>;
+ *   }
+ * 
+ *   return <div>Physics is ready!</div>;
+ * };
+ * ```
+ */
 export const usePhysics = () => useContext(PhysicsContext);
 
 interface PhysicsProviderProps {

packages/lib/src/hooks/index.ts

@@ -7,4 +7,5 @@ export { useParent, ParentContext } from './use-parent.tsx';
 export { useMaterial } from './use-material.tsx'
 export { useAsset, useSplat, useTexture, useEnvAtlas, useModel, useFont } from './use-asset.ts';
 export { useFrame, useAppEvent } from './use-app-event.ts';
-export type { AssetResult } from './use-asset.ts';
+export type { AssetResult } from './use-asset.ts';
+export { usePhysics, type PhysicsContextType } from '../contexts/physics-context.tsx';