@objectifthunes/react-three-book 0.1.0 → 0.2.0

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/dist/index.d.ts

@@ -385,13 +385,16 @@ export declare interface BookState {
 }
 
 /**
- * Creates a 512×512 `THREE.CanvasTexture` suitable for use as a book page.
+ * Creates a `THREE.CanvasTexture` suitable for use as a book page.
+ *
+ * When `pageWidth` and `pageHeight` are given the canvas matches the page
+ * aspect ratio (256 px per world unit).  Otherwise defaults to 512×512.
  *
  * - Fills the background with `color`.
  * - If `image` is provided, draws it using `fitMode` and `fullBleed`.
  * - Otherwise, renders `label` as centred text (useful for debugging).
  */
-export declare function createPageTexture(color: string, label: string, image: HTMLImageElement | null, fitMode: ImageFitMode, fullBleed: boolean): THREE.Texture;
+export declare function createPageTexture(color: string, label: string, image: HTMLImageElement | null, fitMode: ImageFitMode, fullBleed: boolean, pageWidth?: number, pageHeight?: number): THREE.Texture;
 
 /**
  * Ported from Book.cs — Cylinder struct (lines ~3805-3902).
@@ -987,6 +990,9 @@ export declare class PaperUVMargin {
     clone(): PaperUVMargin;
 }
 
+/** Pixels per world unit — used to compute canvas size from page dimensions. */
+export declare const PX_PER_UNIT = 256;
+
 export declare class RendererFactory {
     private m_Root;
     private m_CreateMeshCollider;
@@ -1093,6 +1099,119 @@ export declare class StapleSetup {
     set quality(value: number);
 }
 
+export declare class TextBlock {
+    x: number;
+    y: number;
+    width: number;
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+    color: string;
+    lineHeight: number;
+    textAlign: 'left' | 'center' | 'right';
+    opacity: number;
+    shadowColor: string;
+    shadowBlur: number;
+    constructor(options?: TextBlockOptions);
+    private _font;
+    /**
+     * Word-wrap `text` into lines that fit within `width` pixels.
+     * Respects explicit newlines.
+     */
+    wrapLines(ctx: CanvasRenderingContext2D): string[];
+    /** Total rendered height in canvas pixels. */
+    measureHeight(ctx: CanvasRenderingContext2D): number;
+    /** Returns true if the point (px, py) is within the text bounding box. */
+    hitTest(ctx: CanvasRenderingContext2D, px: number, py: number): boolean;
+    private _maxLineWidth;
+    draw(ctx: CanvasRenderingContext2D): void;
+}
+
+/**
+ * A styled text block rendered onto a 2D canvas.
+ *
+ * Positions and dimensions are in canvas pixels.  Word-wrapping is handled
+ * manually via `ctx.measureText()` when `width` > 0.
+ */
+export declare interface TextBlockOptions {
+    /** Left edge of the text box in canvas pixels. */
+    x?: number;
+    /** Top edge of the text box in canvas pixels. */
+    y?: number;
+    /** Maximum width before wrapping.  0 = no wrapping (default 0). */
+    width?: number;
+    /** Text content. */
+    text?: string;
+    /** Font family (default 'Georgia'). */
+    fontFamily?: string;
+    /** Font size in canvas pixels (default 24). */
+    fontSize?: number;
+    /** Font weight (default 'normal'). */
+    fontWeight?: 'normal' | 'bold';
+    /** Font style (default 'normal'). */
+    fontStyle?: 'normal' | 'italic';
+    /** CSS fill colour (default '#222'). */
+    color?: string;
+    /** Line height multiplier (default 1.4). */
+    lineHeight?: number;
+    /** Text alignment within the box (default 'left'). */
+    textAlign?: 'left' | 'center' | 'right';
+    /** Opacity 0–1 (default 1). */
+    opacity?: number;
+    /** Optional text shadow colour for readability. */
+    shadowColor?: string;
+    /** Shadow blur radius in pixels (default 0). */
+    shadowBlur?: number;
+}
+
+export declare class TextOverlayContent implements IPageContent {
+    readonly canvas: HTMLCanvasElement;
+    readonly texts: TextBlock[];
+    private readonly ctx;
+    private readonly _texture;
+    private readonly _textureST;
+    private _source;
+    get texture(): THREE.Texture;
+    get textureST(): THREE.Vector4;
+    /** The base layer drawn beneath text blocks. */
+    get source(): HTMLCanvasElement | HTMLImageElement | null;
+    set source(v: HTMLCanvasElement | HTMLImageElement | null);
+    constructor(options?: TextOverlayContentOptions);
+    addText(options?: TextBlockOptions): TextBlock;
+    removeText(text: TextBlock): void;
+    /** Update a text block by index. Only provided fields are changed. */
+    updateText(index: number, options: Partial<TextBlockOptions>): void;
+    /**
+     * Re-composite the canvas: source layer + text blocks.
+     * Call every frame (or when content changes).
+     *
+     * @param root  Optional THREE.Object3D to traverse for texture sync
+     *              (same pattern as SpriteScene — needed because three-book
+     *              clones material textures).
+     */
+    update(root?: THREE.Object3D): void;
+    /**
+     * Traverse `root` and set `needsUpdate = true` on every material map whose
+     * source image is this overlay's canvas.
+     */
+    syncMaterials(root: THREE.Object3D): void;
+    isPointOverUI(_textureCoord: THREE.Vector2): boolean;
+    init(_bookContent: BookContent): void;
+    setActive(_active: boolean): void;
+    dispose(): void;
+}
+
+export declare interface TextOverlayContentOptions {
+    /** Canvas width in pixels (default 512). */
+    width?: number;
+    /** Canvas height in pixels (default 512). */
+    height?: number;
+    /** Source canvas or image to draw as the base layer. */
+    source?: HTMLCanvasElement | HTMLImageElement | null;
+}
+
 export declare class ThreeBook extends THREE.Group {
     private static s_Instances;
     static get instances(): ThreeBook[];
@@ -1263,4 +1382,15 @@ export declare interface UsePageTurningOptions {
 /** Returns the nearest ancestor Book instance. Throws outside a <Book> tree. */
 export declare function useRequiredBook(): ThreeBook;
 
+/**
+ * Creates and manages a TextOverlayContent instance with per-frame compositing.
+ *
+ * The returned overlay's canvas is re-composited every frame (source + text blocks).
+ * Material sync is performed automatically if inside a `<Book>` tree.
+ *
+ * @param options  Initial options (width, height, source).
+ * @returns The TextOverlayContent instance (stable ref).
+ */
+export declare function useTextOverlay(options?: TextOverlayContentOptions): TextOverlayContent;
+
 export { }