leafthrough 0.1.3 → 0.1.5

package/README.md

@@ -2,10 +2,12 @@
 
 A 3D magazine you can flip through. Pages are printed paper: they bend, roll, catch the
 light and cast shadows. Built on three.js, written in TypeScript, with bindings for React,
-Vue, Svelte, and a Web Component for everything else (Angular, Solid, Lit, plain HTML).
+Vue, Svelte, and a Web Component for everything else (Angular, Solid, Lit, plain HTML). It
+can also be [one object in your own three.js scene](#in-your-own-threejs-scene).
 
 **[Live demo](https://dmtrbrl.github.io/leafthrough/)**, with one page per binding and a dev panel
-for every option, method and event.
+for every option, method and event, and
+[a three.js scene](https://dmtrbrl.github.io/leafthrough/three.html) with the magazine in it.
 
 - **Two layouts.** `spread` is an open magazine with sheets turning over the spine.
   `single` shows one page at a time, and read pages roll up behind the magazine. `auto`
@@ -136,6 +138,76 @@ error trackers listen. To register the element under another tag, call
 
 **Solid**: `<leaf-through prop:pages={pages()} on:pagechange={(e) => setPage(e.detail.page)} />`.
 
+## In your own three.js scene
+
+`LeafThroughObject` is the magazine as a `THREE.Group`, for a scene you already have. It
+draws with your renderer and takes pointer input through your camera, so it turns wherever
+it lies, however it's moved, turned or scaled. Every option, method, property and event of
+`LeafThrough` works the same, apart from those about its own canvas and DOM: the options
+`bleed`, `maxPixelRatio`, `plain`, `label` and `formatPageLabel`, and the properties
+`plain` and `element`.
+
+```ts
+import { LeafThroughObject } from 'leafthrough'
+
+const magazine = new LeafThroughObject({ renderer, camera }, { pages, layout: 'spread' })
+magazine.rotation.x = -Math.PI / 2   // lay it on the table
+magazine.scale.setScalar(0.21)        // a page 21 cm wide, in a scene measured in metres
+scene.add(magazine)
+
+renderer.setAnimationLoop((now) => {
+  magazine.tick(now)   // advance the pages, then draw as usual
+  renderer.render(scene, camera)
+})
+```
+
+- **Units.** A page is 1 wide and `pageAspect` tall. The spine runs up the y axis at
+  x = 0 and the pages lie on the z = 0 plane, facing +z. A spread closed on its front
+  cover shows it at x 0 to 1, and closed on its back cover at x -1 to 0.
+  `magazine.bounds.pages` is the pages at rest, the rectangle to frame with your camera;
+  `magazine.bounds.reach` is everything a turning page sweeps through.
+- **Input.** The magazine listens for pointer events on `renderer.domElement` (or the
+  `domElement` you pass, which must show exactly the camera's view). It takes presses in
+  its hit area: the pages in `spread` (only the cover's side while closed), and in
+  `single` a box round the page with a strip left of the spine for turning back. It
+  doesn't look at your scene, so objects in front of the magazine don't block it.
+  `magazine.covers(clientX, clientY)` tells you whether it takes a press there; check that
+  in your own handlers to leave such presses alone. Hide the magazine (`visible = false`,
+  on it or a parent) and it takes none. With `interaction.keyboard: true` the keys work
+  while that element has focus; a canvas only takes focus with a `tabIndex`, so give it
+  one or use `'global'`. Drags scale with the magazine's size on screen, so they feel the
+  same near or far. For touch drags, give the element `touch-action: pan-y pinch-zoom`
+  (or `none`), so the browser doesn't take them for scrolling.
+- **Light.** The paper is a `MeshStandardMaterial`, lit by your scene's lights,
+  environment, fog and tone mapping. Of the `lighting` options, `shadows` makes the
+  sheets cast and receive shadows when your renderer draws them, and `sun.position`
+  should point towards your shadow-casting directional light, in the magazine's own
+  frame (only the direction counts). It places the shadow a turning sheet casts right by
+  the spine, where the shadow map can't.
+- **Rendering on demand.** If you only draw when something changes, listen for `change`:
+  it fires when input, loading or a method call needs a frame. Then keep drawing while
+  `tick()` returns true.
+- **Accessibility is yours.** With no DOM of its own, it has no live region, no page
+  descriptions and no plain view: pages' `alt` and `text` aren't read. Describe the pages
+  in your own page, and announce `pagechange` if readers should hear it.
+
+```ts
+magazine.tick(now)                       // advance; true while the pages still move
+magazine.covers(e.clientX, e.clientY)    // whether the magazine takes a press there
+magazine.bounds                          // { pages, reach }, in the magazine's own units
+magazine.camera = otherCamera            // cast input from another camera
+magazine.enabled = false                 // cancel active gestures and stop taking pointer/key input
+magazine.addEventListener('change', () => requestRender())
+magazine.addEventListener('pagechange', (e) => e.detail)   // also ready, pageload, error
+magazine.dispose()                       // free everything and leave the scene
+```
+
+The [three.js demo](https://dmtrbrl.github.io/leafthrough/three.html) takes a magazine
+out of a portrait paperboard mailer on a table; its source is
+[`demo/main-three.ts`](https://github.com/dmtrbrl/leafthrough/blob/main/demo/main-three.ts),
+with the native three.js mailer geometry in
+[`demo/envelope.ts`](https://github.com/dmtrbrl/leafthrough/blob/main/demo/envelope.ts).
+
 ## Sizing
 
 The magazine fills the element you give it and keeps its proportions, centred.
@@ -188,6 +260,7 @@ The magazine fills the element you give it and keeps its proportions, centred.
 | `backColor`               | `#fcfcf9`                   | Unprinted paper: the blank back of single-layout pages, and transparent parts of page images.                |
 | `wrinkles`                | `1`                         | Waviness of resting sheets; `0` lays them flat.                                                              |
 | `bulge`                   | `1`                         | How much pages rise off the spine.                                                                           |
+| `cutout`                  | `false`                     | Cuts each sheet to the shape of its front page: transparent areas are no paper at all, shadow included.      |
 
 **`lighting`**: `ambient: { sky, ground, intensity }`, `sun: { color, intensity, position }`,
 `shadows` (default `true`), `shadowMapSize` (default `2048`), and `floorShadow`. That last
@@ -264,7 +337,8 @@ pages: [
   readers get both, and changing them doesn't reload anything.
 - **Transparent artwork.** PNG and WebP alpha is composited onto the paper: transparent
   areas are unprinted paper in `paper.backColor`, including when the reverse side shows
-  through.
+  through. With `paper.cutout`, they're cut away instead, so a sheet can be any shape: its
+  front page's outline (draw the back page as its mirror image).
 - **Cross-origin URLs.** URLs on another origin need CORS headers, because the images are
   uploaded to WebGL.
 - **Textures.** A three.js `Texture` you pass in is never disposed, but the magazine sets its
@@ -292,7 +366,8 @@ off screen or the tab is hidden.
 The 3D canvas is hidden from screen readers, so give pages an `alt` and their `text` (see
 [Pages](#pages)). The magazine keeps the visible pages' descriptions and text in the page,
 visually hidden, where screen readers can read them; each page is a `figure` named by
-`formatPageLabel`.
+`formatPageLabel`. `LeafThroughObject` has no DOM, so none of this comes with it (see
+[In your own three.js scene](#in-your-own-threejs-scene)).
 
 **Plain view.** `plain: true` shows the pages as flat images, with the same layouts,
 navigation, keyboard and events, and no 3D. Clicking the right half turns forward, the left
@@ -303,7 +378,7 @@ magazine also switches to it by itself when the browser can't run WebGL.
 
 ```bash
 npm install
-npm run dev          # demo playground: a page per binding, each with the dev panel
+npm run dev          # demo playground: a page per binding, each with the dev panel, and a three.js scene
 npm run typecheck
 npm test             # browser tests in headless Chromium (first run: npx playwright install chromium)
 npm run build        # dist/: ESM bundles + type declarations
@@ -329,7 +404,12 @@ How it works:
 - `textures.ts` loads, prioritises and unloads page textures.
 - `src/paper` holds the shared paper material and the procedural grain.
 - `LeafThrough.ts` handles the DOM, sizing, loading, layout switching, keyboard and
-  events.
+  events. `LeafThroughObject.ts` does the same inside someone else's scene, without the DOM.
+- Engines take input through `EngineInput` (`engine.ts`): an element to listen on, a ray
+  for a point on screen, and whether a press lands on the pages. They meet the ray with
+  their own floor plane, so the same code serves the magazine's own camera and any scene's.
+- `navigation.ts` maps pages to engine positions, riffles an animated `goTo()` and binds
+  the keyboard, for both.
 
 ## Credits
 
@@ -338,4 +418,4 @@ The page deformation and interaction model are reverse-engineered from the magaz
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/dmtrbrl/leafthrough/blob/main/LICENSE)

package/dist/LeafThrough.d.ts

@@ -36,9 +36,7 @@ export declare class LeafThrough extends EventTarget {
     private readonly content;
     private readonly renderer;
     private frameRequest;
-    private readonly blank;
-    private readonly backBlank;
-    private pattern;
+    private readonly paper;
     private loader;
     private view;
     private spreadMedia;
@@ -52,7 +50,7 @@ export declare class LeafThrough extends EventTarget {
     private visible;
     private needsRender;
     private running;
-    private riffle;
+    private readonly riffle;
     private lastPagesKey;
     private ready;
     private disposed;
@@ -93,10 +91,8 @@ export declare class LeafThrough extends EventTarget {
     private remount;
     private createPlain;
     private createScene;
-    private patternFor;
     private layoutBox;
     private pagesKey;
-    private preloadRadius;
     private loadPages;
     private inView;
     private followReader;
@@ -104,7 +100,6 @@ export declare class LeafThrough extends EventTarget {
     private pageLoaded;
     private fail;
     private pageToPosition;
-    private positionToPage;
     private pagesAt;
     private detail;
     private lastDetailKey;
@@ -112,8 +107,6 @@ export declare class LeafThrough extends EventTarget {
     private syncContent;
     private applyLabel;
     private bindKeyboard;
-    private stopRiffle;
-    private stepRiffle;
     private syncLoop;
     private setLoop;
     private placeHitArea;

package/dist/LeafThroughObject.d.ts

@@ -0,0 +1,152 @@
+import * as THREE from 'three';
+import { type Rect } from './framing.js';
+import type { GoToOptions } from './LeafThrough.js';
+import { type LeafThroughOptions, type Layout, type PageChangeDetail } from './options.js';
+/**
+ * The magazine's options, less those about its own canvas and DOM. Of `lighting`, only
+ * `shadows` (whether sheets cast and receive them) and `sun.position` apply: the lights are
+ * your scene's. Point `sun.position` towards your shadow-casting directional light, in the
+ * magazine's own frame; it places the shadow a turning sheet casts right by the spine.
+ */
+export type LeafThroughObjectOptions = Omit<LeafThroughOptions, 'bleed' | 'maxPixelRatio' | 'plain' | 'label' | 'formatPageLabel'>;
+/** What the magazine draws with, from your scene. */
+export interface LeafThroughObjectContext {
+    /** The renderer drawing your scene. Pages load into it. */
+    renderer: THREE.WebGLRenderer;
+    /** The camera your scene is drawn with. Pointer input is cast from it; change it later through `camera`. */
+    camera: THREE.Camera;
+    /**
+     * Takes pointer input, and keys with `interaction.keyboard: true` while it has focus. It must
+     * show the camera's whole view. Default `renderer.domElement`.
+     */
+    domElement?: HTMLElement;
+}
+export interface LeafThroughObjectEventMap extends THREE.Object3DEventMap {
+    pagechange: {
+        detail: PageChangeDetail;
+    };
+    ready: {};
+    pageload: {
+        detail: {
+            page: number;
+        };
+    };
+    error: {
+        detail: {
+            error: unknown;
+            page?: number;
+        };
+    };
+    /** Something changed between frames: draw one, and keep drawing while `tick()` returns true. */
+    change: {};
+}
+/** Where the magazine lies in its own units. */
+export interface LeafThroughBounds {
+    /** The pages at rest: what to frame. */
+    pages: Rect;
+    /** Everything a turning page can sweep through. */
+    reach: Rect;
+}
+/**
+ * A 3D magazine to add to your own three.js scene. It draws nothing itself: call `tick()`
+ * every frame you render, and render again whenever it fires `change`.
+ *
+ * In its own units a page is 1 wide and `pageAspect` tall, the spine runs up the y axis at
+ * x = 0, and the pages lie on the z = 0 plane facing +z. Move, turn and scale it like any
+ * object. Pointer input is cast through `camera` onto the pages, wherever they are.
+ *
+ * ```ts
+ * const magazine = new LeafThroughObject({ renderer, camera }, { pages, layout: 'spread' })
+ * scene.add(magazine)
+ * renderer.setAnimationLoop((now) => {
+ *   magazine.tick(now)
+ *   renderer.render(scene, camera)
+ * })
+ * ```
+ */
+export declare class LeafThroughObject extends THREE.Group<LeafThroughObjectEventMap> {
+    /** The camera your scene is drawn with; pointer input is cast from it. */
+    camera: THREE.Camera;
+    readonly domElement: HTMLElement;
+    private inputEnabled;
+    /**
+     * Whether it takes pointer and key input. Turn it off while it's tucked away or moving,
+     * and on again; the pages stay as they are. Turning it off lets go of a page being held.
+     * Default `true`.
+     */
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    private readonly renderer;
+    private options;
+    private readonly paper;
+    private loader;
+    private view;
+    private spreadMedia;
+    private readonly motionMedia;
+    private readonly abort;
+    private readonly riffle;
+    private readonly metrics;
+    private readonly ray;
+    private readonly point;
+    private readonly ends;
+    private needsRender;
+    private lastPagesKey;
+    private lastDetailKey;
+    private inView;
+    private ready;
+    private readyFired;
+    private disposed;
+    constructor({ renderer, camera, domElement }: LeafThroughObjectContext, options: LeafThroughObjectOptions);
+    /** First visible page, 0-based. */
+    get page(): number;
+    get pageCount(): number;
+    get layout(): Layout;
+    get visiblePages(): number[];
+    /** True while a page is being dragged or is completing its turn. */
+    get turning(): boolean;
+    /**
+     * Where the magazine lies in its own units: frame `pages` with your camera. Changes with
+     * the layout, which `'auto'` can switch as the window resizes.
+     */
+    get bounds(): LeafThroughBounds;
+    /** Turns to the next page. Returns false at the end. */
+    next(): boolean;
+    /** Turns to the previous page. Returns false at the start. */
+    prev(): boolean;
+    /** Shows `page` (0-based), jumping there or turning the pages one by one. */
+    goTo(page: number, { animate }?: GoToOptions): void;
+    /** Loads the pages that failed again. Also happens by itself when the browser comes back online. */
+    retry(): void;
+    /** Changes some options and keeps the rest. Structural changes rebuild the pages and keep the current page. */
+    update(options: Partial<LeafThroughObjectOptions>): void;
+    /** Replaces every option at once: anything left out goes back to its default. */
+    setOptions(options: LeafThroughObjectOptions): void;
+    /**
+     * Whether a press at this point on screen lands on the magazine, which then takes it. Check
+     * it in your own pointer handlers to leave such presses alone. False while it's hidden or
+     * not `enabled`.
+     */
+    covers(clientX: number, clientY: number): boolean;
+    /**
+     * Advances the pages to `now` (a `requestAnimationFrame` timestamp). Call it every frame
+     * before rendering. Returns true while the pages are moving and need another frame.
+     */
+    tick(now?: number): boolean;
+    /** Frees the pages, textures and listeners, and takes the magazine out of its parent. */
+    dispose(): void;
+    private applyOptions;
+    private pickLayout;
+    private watchSpreadQuery;
+    private remount;
+    private readonly axis;
+    private pageAxis;
+    private dragWidth;
+    private shown;
+    private requestFrame;
+    private pagesKey;
+    private loadPages;
+    private followReader;
+    private fail;
+    private detail;
+    private emitPageChange;
+}