@objectifthunes/react-three-book 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,214 @@
+# @objectifthunes/react-three-book
+
+A procedural, interactive 3D book for [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) — drag pages to turn them, apply textures to every surface, and drop `<Book>` into your R3F scene like any other component.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ObjectifThunes/react-three-book/main/docs/images/default.png" width="49%" alt="Closed book" />
+  <img src="https://raw.githubusercontent.com/ObjectifThunes/react-three-book/main/docs/images/open-half.png" width="49%" alt="Book opened halfway" />
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ObjectifThunes/react-three-book/main/docs/images/page-curl.png" width="49%" alt="Page mid-curl" />
+  <img src="https://raw.githubusercontent.com/ObjectifThunes/react-three-book/main/docs/images/demo-ui.png" width="49%" alt="Demo app with tweakable controls" />
+</p>
+
+## Features
+
+- **`<Book>` R3F component** — handles init / update / dispose automatically; rebuilds cleanly via React's `key` prop.
+- **`<BookInteraction>`** — declarative pointer-drag wiring for interactive page turning; auto-discovers the book from context.
+- **Hooks** — `useBookControls`, `useAutoTurn`, `useBookState`, `useBookContent`, `usePageTurning`.
+- **BookContext** — child components access the book instance without prop-drilling.
+- **Per-surface textures** — assign a `THREE.Texture` (or `null`) to each cover side and page side independently.
+- **Configurable geometry** — page/cover width, height, thickness, stiffness, color.
+- **Texture utilities** — `createPageTexture`, `drawImageWithFit`, `loadImage` included.
+
+## Installation
+
+```bash
+npm install @objectifthunes/react-three-book three @react-three/fiber react react-dom
+```
+
+```bash
+pnpm add @objectifthunes/react-three-book three @react-three/fiber react react-dom
+```
+
+Peer dependencies: `three >= 0.150.0`, `react >= 18.0.0`, `@react-three/fiber >= 8.0.0`.
+
+## Quick Start
+
+```tsx
+import { Canvas } from '@react-three/fiber';
+import { OrbitControls } from '@react-three/drei';
+import * as THREE from 'three';
+import {
+  Book,
+  BookContent,
+  BookDirection,
+  BookInteraction,
+  StapleBookBinding,
+  useBookContent,
+} from '@objectifthunes/react-three-book';
+
+function Scene() {
+  const orbitRef = useRef(null);
+
+  const content = useBookContent(() => {
+    const c = new BookContent();
+    c.direction = BookDirection.LeftToRight;
+    c.covers.push(frontOuterTex, frontInnerTex, backInnerTex, backOuterTex);
+    c.pages.push(page1Tex, page2Tex, page3Tex, page4Tex);
+    return c;
+  }, []);
+
+  return (
+    <>
+      <OrbitControls ref={orbitRef} />
+      <Book
+        content={content}
+        binding={new StapleBookBinding()}
+        castShadows
+        alignToGround
+        pagePaperSetup={{ width: 2, height: 3, thickness: 0.02, stiffness: 0.2, color: new THREE.Color(1, 1, 1), material: null }}
+        coverPaperSetup={{ width: 2.1, height: 3.1, thickness: 0.04, stiffness: 0.5, color: new THREE.Color(1, 1, 1), material: null }}
+      >
+        <BookInteraction orbitControlsRef={orbitRef} />
+      </Book>
+    </>
+  );
+}
+
+export default function App() {
+  return (
+    <Canvas shadows camera={{ position: [0, 2, 5], fov: 45 }}>
+      <Scene />
+    </Canvas>
+  );
+}
+```
+
+## Triggering a Rebuild
+
+Change the `key` prop — React unmounts and remounts `<Book>`, which runs a clean dispose → init cycle:
+
+```tsx
+<Book key={buildKey} content={content} binding={binding} ... />
+```
+
+## Imperative Access
+
+Forward a ref to get the underlying `ThreeBook` instance:
+
+```tsx
+const bookRef = useRef<ThreeBook>(null);
+<Book ref={bookRef} ... />
+
+bookRef.current?.setOpenProgress(0.5);
+```
+
+## Hooks
+
+### `useBookControls(bookRef?)`
+
+```tsx
+const { setOpenProgress, setOpenProgressByIndex, stopTurning } = useBookControls();
+```
+
+### `useAutoTurn(bookRef?)`
+
+```tsx
+const { turnNext, turnPrev, turnAll, startAutoTurning, cancelPendingAutoTurns } = useAutoTurn();
+
+turnNext();
+turnPrev();
+turnAll(AutoTurnDirection.Next);
+startAutoTurning(AutoTurnDirection.Next, settings, 5, 0.3);
+```
+
+### `useBookState(bookRef?)`
+
+Reactive snapshot updated every frame — triggers re-renders only when something actually changes:
+
+```tsx
+const { isTurning, isIdle, isAutoTurning, paperCount } = useBookState();
+```
+
+### `useBookContent(factory, deps)`
+
+Creates a `BookContent` and disposes its `THREE.Texture`s automatically when `deps` change or the component unmounts:
+
+```tsx
+const content = useBookContent(() => {
+  const c = new BookContent();
+  c.covers.push(myTexture);
+  c.pages.push(pageA, pageB);
+  return c;
+}, [rebuildKey]);
+```
+
+## Context
+
+Any component rendered inside `<Book>` can access the instance without a ref:
+
+```tsx
+function PageButtons() {
+  const { turnNext, turnPrev } = useAutoTurn();
+  return (
+    <>
+      <button onClick={turnPrev}>◀</button>
+      <button onClick={turnNext}>▶</button>
+    </>
+  );
+}
+
+<Book ...>
+  <BookInteraction />
+  <PageButtons />
+</Book>
+```
+
+## Texture Utilities
+
+```tsx
+import { createPageTexture, drawImageWithFit, loadImage } from '@objectifthunes/react-three-book';
+
+const tex = createPageTexture('#ff0000', 'Cover', myImage, 'cover', true);
+
+const result = await loadImage(file); // { image, objectUrl } | null
+```
+
+## Content Model
+
+**Covers** — 4 entries, one per surface:
+
+| Index | Surface |
+|-------|---------|
+| 0 | Front outer |
+| 1 | Front inner |
+| 2 | Back inner |
+| 3 | Back outer |
+
+**Pages** — ordered list of page-side textures. Each entry can be a `THREE.Texture`, an `IPageContent` implementation, or `null` (renders the base paper color).
+
+## Auto Turn
+
+```tsx
+import { AutoTurnDirection, AutoTurnMode, AutoTurnSettings } from '@objectifthunes/react-three-book';
+
+const { startAutoTurning } = useAutoTurn();
+
+const settings = new AutoTurnSettings();
+settings.mode = AutoTurnMode.Edge;
+startAutoTurning(AutoTurnDirection.Next, settings, 3);
+```
+
+## API Surface
+
+| Category | Exports |
+|----------|---------|
+| Components | `Book`, `BookInteraction` |
+| Context | `BookContext`, `useBook`, `useRequiredBook` |
+| Hooks | `useBookRef`, `useBookContent`, `useBookControls`, `useAutoTurn`, `useBookState`, `usePageTurning` |
+| Texture utils | `createPageTexture`, `drawImageWithFit`, `loadImage` |
+| Core | `ThreeBook`, `BookContent`, `BookDirection`, `Paper`, `PaperSetup` |
+| Binding | `BookBinding`, `StapleBookBinding`, `StapleBookBound`, `StapleSetup` |
+| Content | `IPageContent`, `PageContent`, `SpritePageContent2` |
+| Auto turn | `AutoTurnDirection`, `AutoTurnMode`, `AutoTurnSettings`, `AutoTurnSetting` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectifthunes/react-three-book",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,7 +10,7 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": ["dist", "README.md"],
   "scripts": {
     "build": "vite build",
     "typecheck": "tsc --noEmit",