@poe2-toolkit/tree-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Rajtmajer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @poe2-toolkit/tree-react
+
+[![npm](https://img.shields.io/npm/v/@poe2-toolkit/tree-react.svg)](https://www.npmjs.com/package/@poe2-toolkit/tree-react)
+[![types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6.svg)](src/index.ts)
+[![React 18+](https://img.shields.io/badge/react-18%2B-61dafb.svg)](https://react.dev)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+React renderer for the Path of Exile 2 passive tree. It's a thin view layer on
+top of [`@poe2-toolkit/tree-core`](../poe2-tree-core): the core works out where
+everything goes, and this package draws it and runs the canvas, panning,
+zooming, hovering, and clicking.
+
+It does no geometry of its own. Positions, sizes, rotations, the hub layout, and
+hit-testing all come from the core. If you ever catch this package computing a
+coordinate, that's a bug.
+
+The geometry lives in a framework-agnostic core, so the same `Scene` can just as
+easily be drawn from Vue, Svelte, or anything else. React is what this project
+happens to use.
+
+> **Live demo:** see this renderer in a real app at
+> [poe.rajtik.com/tree](https://poe.rajtik.com/tree).
+
+## Who does what
+
+| Concern | Owner |
+|---|---|
+| node positions, sizes, hub geometry, arcs, hit-test math | core |
+| canvas, device-pixel sizing, draw loop, layer order | this package |
+| pan, zoom, wheel, fullscreen, pointer hover and click | this package |
+| loading atlas bitmaps, colors, tooltips, surrounding UI | you |
+
+## Install
+
+```sh
+npm install @poe2-toolkit/tree-react @poe2-toolkit/tree-core
+```
+
+React 18 or newer is a peer dependency.
+
+## Usage
+
+The tree data comes from GGG's official skill-tree export. Run it through the
+core's GGG adapter to get a `TreeData`, build a `Scene` from it, and hand that to
+`TreeView`.
+
+```tsx
+import { buildScene } from '@poe2-toolkit/tree-core';
+import { normalizeGggTree } from '@poe2-toolkit/tree-core/ggg';
+import { TreeView } from '@poe2-toolkit/tree-react';
+
+// Normalize GGG's data.json into the engine's TreeData (once per tree).
+const data = normalizeGggTree(rawGggExport, '0_5');
+
+// Build a render-ready scene for the current build (rebuild it on edits).
+const scene = buildScene(data, { allocation });
+
+// Draw it. `resources` (atlas bitmaps + manifest) is optional; leave it out
+// and you get the vector debug render.
+<TreeView
+  scene={scene}
+  resources={{ manifest, atlases }}
+  activeClassId={allocation.classId}
+  activeAscendancy={allocation.ascendId}
+  onNodeClick={(skill) => toggle(skill)}
+/>;
+```
+
+The pattern is state in, intent out. The `scene` already holds everything
+visual, so the component just reports what the user did (`onNodeClick`,
+`onNodeHover`, and the rest) and never touches the build itself.
+
+## Graphics
+
+`TreeView` doesn't load any images. You give it a `RenderResources`:
+
+```ts
+interface RenderResources {
+  manifest: SpriteManifest;                     // sprite key -> native atlas rect
+  atlases: Record<string, CanvasImageSource>;   // atlas id -> bitmap
+}
+```
+
+To draw a node, the renderer turns it into a sprite key with the helpers in
+[`spriteKeys`](src/spriteKeys.ts) (`iconKeyFor`, `frameKeyFor`, `effectKeyFor`,
+and friends), looks that key up in your `manifest`, and blits the rect from the
+matching atlas. The keys follow GGG's atlas naming, so pointing the renderer at a
+different atlas set comes down to swapping that one file. Leave `resources` out
+and you get a plain vector render of discs and rails, which is handy for
+debugging without art.
+
+The hub artwork (class portrait and ornate ring) comes in through the optional
+`centreSprites` prop. Skip it and the hub falls back to a vector placeholder.
+
+## Component props
+
+```tsx
+<TreeView
+  scene={scene}                 // required: core.buildScene output
+  resources={resources}         // atlas bitmaps + manifest (omit for vector)
+  activeClassId={classId}       // rotates the active ring onto the class
+  activeAscendancy={ascId}      // relocates that ascendancy disc into the hub
+  centreSprites={centreSprites} // optional portrait + ring artwork
+  preview={preview}             // hover highlight: pending add (gold) / remove (red)
+  focus={worldRect}             // pass a fresh rect to pan + zoom-fit to it
+  wheelZoom                     // turn on wheel zoom (off by default)
+  controls={controlsRef}        // imperative zoomIn() / zoomOut()
+  onNodeClick={(skill, screen) => …}
+  onNodeDoubleClick={(skill) => …}
+  onNodeHover={(skill, screen) => …}
+  onInteractStart={() => …}     // a press started on the canvas (e.g. close popovers)
+/>
+```
+
+Exported types: `TreeViewProps`, `TreeViewControls`, `AllocationPreview`,
+`CentreSprite`, `RenderResources`.
+
+For external +/- buttons, reach for the imperative handle on `controls`:
+
+```tsx
+const controls = useRef<TreeViewControls>(null);
+// …
+<button onClick={() => controls.current?.zoomIn()}>+</button>
+```
+
+## Non-goals
+
+This package won't:
+
+- compute or adjust any position, size, rotation, or hub placement;
+- carry magic numbers for node, icon, or effect sizing;
+- lock itself to one data source (it only knows `Scene` and `SpriteManifest`);
+- claim to be the only frontend. A Vue, Svelte, or Livewire renderer on the same
+  contract is every bit as valid.
+
+## Local development
+
+In-repo, this package finds `@poe2-toolkit/tree-core` two ways:
+
+- typecheck and build read it through a `tsconfig` `paths` entry that points at
+  the sibling source, so there's no build or link step;
+- `npm install` links the sibling through the `file:../poe2-tree-core`
+  dependency.
+
+When you split this out into its own repo, change two things: drop the `paths`
+block in `tsconfig.json`, and swap the `@poe2-toolkit/tree-core` dependency from
+`file:../poe2-tree-core` to a published version like `^0.1.0`.
+
+```sh
+npm install
+npm run typecheck
+npm run build
+```
+
+## Attributions and legal
+
+This is an unofficial, fan-made project, **not** affiliated with, endorsed by, or
+sponsored by Grinding Gear Games. "Path of Exile 2" is a trademark of Grinding
+Gear Games, and all game content, data, and art are their property. This package
+ships code only and stores nothing derived from the game. Thank you to Grinding
+Gear Games for making Path of Exile 2. See the repository [NOTICE](../../NOTICE.md).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/TreeView.d.ts

@@ -0,0 +1,101 @@
+import type { Scene, WorldRect } from '@poe2-toolkit/tree-core';
+import type { CSSProperties, Ref } from 'react';
+import type { RenderResources } from './resources.js';
+export interface TreeViewProps {
+    /** Computed geometry from `@poe2-toolkit/tree-core`'s `buildScene`. */
+    scene: Scene;
+    /** Atlas bitmaps + manifest. Omit for the vector debug render (no GGG art). */
+    resources?: RenderResources;
+    /** Active class id — rotates the active ring onto that class. */
+    activeClassId?: number;
+    /** Active ascendancy id — its disc is relocated into the hub. */
+    activeAscendancy?: string;
+    /**
+     * Optional centre artwork. Each sprite is a URL + source sub-rect, drawn at
+     * the hub sized to the matching core radius:
+     *  - `portrait` -> `ring.artRadius` (the inner class illustration)
+     *  - `ringStatic` -> `ring.frameRadius` (the ornate ring)
+     *  - `ringActive` -> `ring.activeRadius`, rotated by the active class's
+     *    `ringRotation` (the gold band pointing at the class)
+     * When absent, the vector hub stand-in is drawn instead.
+     */
+    centreSprites?: {
+        portrait?: CentreSprite;
+        ringStatic?: CentreSprite;
+        ringActive?: CentreSprite;
+    };
+    /** Single-click intent out: the skill id and the node's centre in canvas px. */
+    onNodeClick?: (skill: number, screen: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Double-click intent out (skill id). */
+    onNodeDoubleClick?: (skill: number) => void;
+    /** Fires when a press starts on the canvas (pan/empty click) — e.g. to dismiss popovers. */
+    onInteractStart?: () => void;
+    /**
+     * Hover feedback out: the skill id (or null when leaving all nodes) and, when
+     * hovering a node, its centre in canvas pixels — so callers can anchor UI
+     * (e.g. an attribute picker) to the node.
+     */
+    onNodeHover?: (skill: number | null, screen?: {
+        x: number;
+        y: number;
+    }) => void;
+    /**
+     * Hover preview to highlight: the nodes/edges that a click would allocate
+     * (`add`) or remove (`remove`). Drawn on top of the base render.
+     */
+    preview?: AllocationPreview | null;
+    /** Imperative zoom controls, for external +/- buttons. */
+    controls?: Ref<TreeViewControls>;
+    /**
+     * Enable mouse-wheel zoom. Off by default so the page can scroll over an
+     * embedded canvas; turn on in fullscreen, where there's nothing to scroll.
+     */
+    wheelZoom?: boolean;
+    /**
+     * World rect to frame (pan + zoom to fit). Whenever the object reference
+     * changes the view re-frames it — pass a fresh object to trigger, `null` to
+     * keep the current/default view (the hub).
+     */
+    focus?: WorldRect | null;
+    /**
+     * Skill ids to emphasise with a standing teal ring (e.g. name-search hits).
+     * Unlike `onNodeHover`, this is a persistent set drawn until it changes.
+     */
+    highlight?: Set<number> | null;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Imperative handle exposed via `controls` for external zoom buttons. */
+export interface TreeViewControls {
+    zoomIn: () => void;
+    zoomOut: () => void;
+}
+/** Hover preview of a pending allocate/remove: node ids + edge keys to glow. */
+export interface AllocationPreview {
+    kind: 'add' | 'remove';
+    nodes: Set<number>;
+    /** Edge keys as `min-max` of the two node ids. */
+    edges: Set<string>;
+}
+/** A sprite to draw at the hub: source image URL + the sub-rect to crop. */
+export interface CentreSprite {
+    url: string;
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+}
+/**
+ * Thin canvas view over a core `Scene`. It owns nothing geometric — pan, zoom,
+ * device-pixel sizing, the draw loop, and hover hit-testing only. Positions,
+ * sizes, projection and hit-testing all come from `@poe2-toolkit/tree-core`.
+ *
+ * Without `resources` it renders a vector debug view (nodes as discs, edges as
+ * lines/arcs, the hub opening as a ring) — enough to see the geometry before any
+ * GGG atlas art exists.
+ */
+export declare function TreeView({ scene, resources, activeClassId, activeAscendancy, centreSprites, onNodeClick, onNodeDoubleClick, onInteractStart, onNodeHover, preview, controls, wheelZoom, focus, highlight, className, style, }: TreeViewProps): React.JSX.Element;
+//# sourceMappingURL=TreeView.d.ts.map

package/dist/TreeView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeView.d.ts","sourceRoot":"","sources":["../src/TreeView.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,KAAK,EAAqC,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAG7G,OAAO,KAAK,EAAE,aAAa,EAAoE,GAAG,EAAE,MAAM,OAAO,CAAC;AAClH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,EAAE,KAAK,CAAC;IACb,+EAA+E;IAC/E,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE;QACd,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,UAAU,CAAC,EAAE,YAAY,CAAC;QAC1B,UAAU,CAAC,EAAE,YAAY,CAAC;KAC3B,CAAC;IACF,gFAAgF;IAChF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,4FAA4F;IAC5F,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IACvB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AA0ED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,OAAO,EACP,QAAQ,EACR,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS,EACT,KAAK,GACN,EAAE,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAkWnC"}