taffy-js 0.1.2 → 0.2.0

package/README.md

@@ -1,18 +1,19 @@
-# Taffy WebAssembly Bindings
+# Taffy-JS: WebAssembly Bindings for Taffy Layout Engine
 
 > **High-performance Flexbox and CSS Grid layout for JavaScript/TypeScript, powered by Rust and WebAssembly.**
 
 ![License](https://img.shields.io/npm/l/taffy-js?style=flat-square) ![Version](https://img.shields.io/npm/v/taffy-js?style=flat-square) ![WASM](https://img.shields.io/badge/platform-wasm-blueviolet?style=flat-square)
 
-**Taffy** is a generic, high-performance UI layout library written in Rust. This package (`taffy-js`) provides WebAssembly bindings, allowing you to use Taffy's standards-compliant Flexbox and Grid algorithms directly in your web or Node.js applications with near-native performance.
+**Taffy** is a high-performance UI layout library written in Rust. This package (`taffy-js`) provides WebAssembly bindings, enabling JavaScript/TypeScript applications to use standards-compliant Flexbox, CSS Grid, and Block layout algorithms with near-native performance.
 
 ## ✨ Features
 
-- **🚀 High Performance**: Leverages the speed of Rust and WebAssembly for complex layout computations.
-- **📦 Tiny Footprint**: Highly optimized WASM binary size.
-- **🎨 Modern Layouts**: Full support for **Flexbox** and **CSS Grid** specifications.
-- **🛠 Framework Agnostic**: Use it with React, Vue, Svelte, vanilla JS, or even in Node.js for server-side layout calculation.
-- **🔒 Type-Safe**: Fully typed API with TypeScript definitions included.
+- 🚀 **High Performance** – Rust + WebAssembly for complex layout computations
+- 📦 **Tiny Footprint** – Optimized WASM binary size
+- 🎨 **Modern Layouts** – Full Flexbox, CSS Grid, and Block layout support
+- 🛠 **Framework Agnostic** – Works with React, Vue, Svelte, vanilla JS, Node.js
+- 🔒 **Type-Safe** – Full TypeScript definitions included
+- 📐 **Custom Measurement** – Support for text measurement via callback functions
 
 ## 📦 Installation
 
@@ -20,156 +21,463 @@
 npm install taffy-js
 ```
 
-> **Note**: This package relies on WebAssembly. Ensure your runtime (modern browser or Node.js) supports WASM.
+> **Note**: Requires a runtime that supports WebAssembly (all modern browsers and Node.js 12+).
 
-## 🚀 Usage
-
-Here is a complete example showing how to create a layout tree, style nodes, and compute results.
+## 🚀 Quick Start
 
 ```typescript
 import init, {
-  new_leaf,
-  new_with_children,
-  compute_layout,
-  get_layout,
+  TaffyTree,
+  Style,
   Display,
   FlexDirection,
   AlignItems,
   JustifyContent,
-  Style,
 } from "taffy-js";
 
-async function run() {
-  // 1. Initialize the WASM module
+async function main() {
+  // 1. Initialize WASM module
   await init();
 
-  // 2. Define Styles
-  // Styles match CSS properties. You can mix specific units like Pixels, Percent, or Auto.
-  const boxStyle: Style = {
-    display: Display.Flex,
-    width: { value: 100, unit: "Pixels" },
-    height: { value: 100, unit: "Pixels" },
-    justify_content: JustifyContent.Center,
-    align_items: AlignItems.Center,
-  };
-
-  const rootStyle: Style = {
-    display: Display.Flex,
-    // layout 500x500 container
-    width: { value: 500, unit: "Pixels" },
-    height: { value: 500, unit: "Pixels" },
-    flex_direction: FlexDirection.Row,
-    justify_content: JustifyContent.SpaceAround,
-    align_items: AlignItems.Center,
-    gap: {
-      width: { value: 20, unit: "Pixels" },
-      height: { value: 0, unit: "Pixels" },
-    }, // Example of potential gap usage if supported
-  };
-
-  // 3. Create Tree Nodes
-  // Leaf nodes
-  const child1 = new_leaf(boxStyle);
-  const child2 = new_leaf(boxStyle);
-
-  // Root node with children
-  const root = new_with_children(rootStyle, [child1, child2]);
-
-  // 4. Compute Layout
-  // You can pass available space constraints (width/height).
-  // Passing values corresponds to "Definite" size, null corresponds to "MaxContent/Available".
-  compute_layout(root, {
-    width: 500,
-    height: 500,
-  });
+  // 2. Create tree and styles
+  const tree = new TaffyTree();
 
-  // 5. Retrieve Results
-  const rootLayout = get_layout(root);
-  const child1Layout = get_layout(child1);
-  const child2Layout = get_layout(child2);
+  const rootStyle = new Style();
+  rootStyle.display = Display.Flex;
+  rootStyle.flex_direction = FlexDirection.Row;
+  rootStyle.justify_content = JustifyContent.SpaceAround;
+  rootStyle.align_items = AlignItems.Center;
+  rootStyle.size = { width: { Length: 500 }, height: { Length: 400 } };
+
+  const childStyle = new Style();
+  childStyle.size = { width: { Length: 100 }, height: { Length: 100 } };
+
+  // 3. Build the tree
+  const child1 = tree.newLeaf(childStyle);
+  const child2 = tree.newLeaf(childStyle);
+  const root = tree.newWithChildren(rootStyle, [child1, child2]);
+
+  // 4. Compute layout
+  tree.computeLayout(root, {
+    width: { Definite: 500 },
+    height: { Definite: 400 },
+  });
 
-  console.log("Root:", rootLayout); // { x: 0, y: 0, width: 500, height: 500 }
-  console.log("Child 1:", child1Layout); // { x: ..., y: ..., width: 100, height: 100 }
-  console.log("Child 2:", child2Layout); // { x: ..., y: ..., width: 100, height: 100 }
+  // 5. Read results
+  console.log("Root:", tree.getLayout(root));
+  console.log("Child 1:", tree.getLayout(child1));
+  console.log("Child 2:", tree.getLayout(child2));
 }
 
-run();
+main();
 ```
 
 ## 📐 Architecture
 
-`taffy-js` acts as a thin wrapper around the [Taffy](https://github.com/DioxusLabs/taffy) Rust crate.
+The library is organized into four main components:
 
-1.  **Node Tree**: You build a flat tree of nodes in the WASM memory space using integer IDs (`u32`).
-2.  **Style Transfer**: Styles are serialized from JS objects to Rust structs via `serde-wasm-bindgen`.
-3.  **Computation**: Rust runs the layout algorithms (Flexbox/Grid).
-4.  **Readout**: You query the final computed geometry (x, y, width, height) back to JS.
+| Component     | Description                                                                           |
+| :------------ | :------------------------------------------------------------------------------------ |
+| **Enums**     | CSS layout enum types (Display, Position, FlexDirection, FlexWrap, AlignItems, etc.)  |
+| **DTOs**      | Data Transfer Objects for JS ↔ Rust serialization (JsDimension, JsSize, JsRect, etc.) |
+| **Style**     | Node style configuration with getter/setter methods for all CSS layout properties     |
+| **TaffyTree** | Layout tree manager for node creation, tree manipulation, and layout computation      |
+
+### How It Works
+
+1. **Create Tree** – Instantiate a `TaffyTree` to manage layout nodes
+2. **Define Styles** – Create `Style` objects and set CSS layout properties
+3. **Build Nodes** – Use `newLeaf()` or `newWithChildren()` to create nodes
+4. **Compute Layout** – Call `computeLayout()` on the root node
+5. **Read Results** – Use `getLayout()` to retrieve computed positions and sizes
+
+---
 
 ## 📚 API Reference
 
-### Lifecycle
+### TaffyTree Class
+
+The main entry point for layout computation.
+
+#### Constructors
+
+| Method                      | Description                                              |
+| :-------------------------- | :------------------------------------------------------- |
+| `new TaffyTree()`           | Creates a new empty layout tree                          |
+| `TaffyTree.withCapacity(n)` | Creates a tree with pre-allocated capacity for `n` nodes |
+
+#### Configuration
+
+| Method              | Description                                              |
+| :------------------ | :------------------------------------------------------- |
+| `enableRounding()`  | Enables rounding layout values to whole pixels (default) |
+| `disableRounding()` | Disables rounding for sub-pixel precision                |
+
+#### Node Creation
+
+| Method               | Signature                                     | Description                               |
+| :------------------- | :-------------------------------------------- | :---------------------------------------- |
+| `newLeaf`            | `(style: Style) → number`                     | Creates a leaf node (no children)         |
+| `newLeafWithContext` | `(style: Style, context: any) → number`       | Creates a leaf with attached context data |
+| `newWithChildren`    | `(style: Style, children: number[]) → number` | Creates a container node with children    |
+
+#### Style Management
+
+| Method     | Signature                             | Description                          |
+| :--------- | :------------------------------------ | :----------------------------------- |
+| `setStyle` | `(node: number, style: Style) → void` | Updates a node's style (marks dirty) |
+| `getStyle` | `(node: number) → Style`              | Returns a copy of the node's style   |
+
+#### Tree Operations
+
+| Method                | Signature                         | Description                    |
+| :-------------------- | :-------------------------------- | :----------------------------- |
+| `addChild`            | `(parent, child) → void`          | Appends a child to a parent    |
+| `removeChild`         | `(parent, child) → number`        | Removes and returns the child  |
+| `removeChildAtIndex`  | `(parent, index) → number`        | Removes child at index         |
+| `insertChildAtIndex`  | `(parent, index, child) → void`   | Inserts child at index         |
+| `replaceChildAtIndex` | `(parent, index, child) → number` | Replaces and returns old child |
+| `setChildren`         | `(parent, children[]) → void`     | Replaces all children          |
+| `remove`              | `(node) → number`                 | Removes node from tree         |
+| `clear`               | `() → void`                       | Removes all nodes              |
+
+#### Tree Queries
+
+| Method            | Signature                  | Description                 |
+| :---------------- | :------------------------- | :-------------------------- |
+| `parent`          | `(child) → number \| null` | Returns parent node ID      |
+| `children`        | `(parent) → number[]`      | Returns array of child IDs  |
+| `childCount`      | `(parent) → number`        | Returns number of children  |
+| `getChildAtIndex` | `(parent, index) → number` | Returns child at index      |
+| `totalNodeCount`  | `() → number`              | Returns total nodes in tree |
+
+#### Dirty Tracking
+
+| Method      | Signature          | Description                    |
+| :---------- | :----------------- | :----------------------------- |
+| `markDirty` | `(node) → void`    | Marks node for re-layout       |
+| `dirty`     | `(node) → boolean` | Checks if node needs re-layout |
+
+#### Layout Computation
+
+| Method                     | Signature                                  | Description                           |
+| :------------------------- | :----------------------------------------- | :------------------------------------ |
+| `computeLayout`            | `(node, availableSpace) → void`            | Computes layout for subtree           |
+| `computeLayoutWithMeasure` | `(node, availableSpace, measureFn) → void` | Computes with custom measure function |
+
+#### Layout Results
+
+| Method            | Signature         | Description                           |
+| :---------------- | :---------------- | :------------------------------------ |
+| `getLayout`       | `(node) → Layout` | Returns computed layout (rounded)     |
+| `unroundedLayout` | `(node) → Layout` | Returns layout with fractional values |
+
+#### Node Context
+
+| Method           | Signature                | Description             |
+| :--------------- | :----------------------- | :---------------------- |
+| `setNodeContext` | `(node, context) → void` | Attaches data to node   |
+| `getNodeContext` | `(node) → any`           | Retrieves attached data |
 
-| Function | Description                                                                     |
-| :------- | :------------------------------------------------------------------------------ |
-| `init()` | Initializes the WASM module. Must be awaited before calling any other function. |
-| `free()` | (Optional) Manually free memory if required by your specific WASM loader setup. |
+#### Debug
 
-### Node Management
+| Method            | Description                      |
+| :---------------- | :------------------------------- |
+| `printTree(node)` | Prints tree structure to console |
 
-| Function            | Signature                                      | Description                             |
-| :------------------ | :--------------------------------------------- | :-------------------------------------- |
-| `new_leaf`          | `(style: Style) -> number`                     | Creates a leaf node (no children).      |
-| `new_with_children` | `(style: Style, children: number[]) -> number` | Creates a node containing child nodes.  |
-| `add_child`         | `(parent: number, child: number) -> void`      | Appends a child to a parent.            |
-| `remove_child`      | `(parent: number, child: number) -> void`      | Removes a specific child from a parent. |
-| `set_children`      | `(parent: number, children: number[]) -> void` | Replaces all children of a node.        |
-| `remove_node`       | `(node: number) -> void`                       | Deletes a node and frees its memory.    |
+---
 
-### Layout & Style
+### Style Class
 
-| Function         | Signature                                       | Description                                                                 |
-| :--------------- | :---------------------------------------------- | :-------------------------------------------------------------------------- |
-| `set_style`      | `(node: number, style: Style) -> void`          | Updates the style properties of a node.                                     |
-| `compute_layout` | `(root: number, space: AvailableSpace) -> void` | Triggers the layout calculation algorithm.                                  |
-| `get_layout`     | `(node: number) -> Layout`                      | Returns `{x, y, width, height}` for a node.                                 |
-| `mark_dirty`     | `(node: number) -> void`                        | Manually validates a node (usually handled automatically by style setters). |
+Configuration object for CSS layout properties.
+
+```typescript
+const style = new Style();
+```
+
+#### Layout Mode
+
+| Property   | Type       | Description                               |
+| :--------- | :--------- | :---------------------------------------- |
+| `display`  | `Display`  | Layout algorithm: Block, Flex, Grid, None |
+| `position` | `Position` | Positioning: Relative, Absolute           |
+
+#### Flexbox Properties
+
+| Property         | Type            | Description                                       |
+| :--------------- | :-------------- | :------------------------------------------------ |
+| `flex_direction` | `FlexDirection` | Main axis: Row, Column, RowReverse, ColumnReverse |
+| `flex_wrap`      | `FlexWrap`      | Wrap behavior: NoWrap, Wrap, WrapReverse          |
+| `flex_grow`      | `number`        | Grow factor (default: 0)                          |
+| `flex_shrink`    | `number`        | Shrink factor (default: 1)                        |
+| `flex_basis`     | `Dimension`     | Initial size before grow/shrink                   |
+
+#### Alignment
+
+| Property          | Type              | Description                        |
+| :---------------- | :---------------- | :--------------------------------- |
+| `align_items`     | `AlignItems?`     | Cross-axis alignment for children  |
+| `align_self`      | `AlignSelf?`      | Cross-axis alignment for this item |
+| `align_content`   | `AlignContent?`   | Multi-line cross-axis alignment    |
+| `justify_content` | `JustifyContent?` | Main-axis alignment                |
+
+#### Sizing
+
+| Property       | Type                | Description              |
+| :------------- | :------------------ | :----------------------- |
+| `size`         | `{ width, height }` | Element dimensions       |
+| `min_size`     | `{ width, height }` | Minimum size constraints |
+| `max_size`     | `{ width, height }` | Maximum size constraints |
+| `aspect_ratio` | `number?`           | Width-to-height ratio    |
+
+#### Spacing
+
+| Property  | Type                           | Description                           |
+| :-------- | :----------------------------- | :------------------------------------ |
+| `margin`  | `{ left, right, top, bottom }` | Outer spacing (supports Auto)         |
+| `padding` | `{ left, right, top, bottom }` | Inner spacing                         |
+| `border`  | `{ left, right, top, bottom }` | Border width                          |
+| `gap`     | `{ width, height }`            | Gap between children (column/row gap) |
+| `inset`   | `{ left, right, top, bottom }` | Absolute positioning offsets          |
+
+#### Overflow
+
+| Property   | Type       | Description                |
+| :--------- | :--------- | :------------------------- |
+| `overflow` | `{ x, y }` | Overflow behavior per axis |
+
+---
 
 ### Type Definitions
 
-#### `Style`
+#### Dimension (JsDimension)
+
+Values for size properties:
+
+```typescript
+// Fixed pixel value
+{
+  Length: 100;
+}
+
+// Percentage of parent
+{
+  Percent: 0.5;
+} // 50%
+
+// Automatic sizing
+("Auto");
+```
+
+#### LengthPercentage (JsLengthPercentage)
+
+For properties that don't support Auto (padding, border):
+
+```typescript
+{
+  Length: 10;
+}
+{
+  Percent: 0.1;
+}
+```
+
+#### LengthPercentageAuto (JsLengthPercentageAuto)
 
-A comprehensive object mirroring CSS properties.
+For properties that support Auto (margin, inset):
 
-- **Display**: `Display.Flex`, `Display.Grid`, `Display.None`
-- **Dimensions**: `{ value: number, unit: "Pixels" | "Percent" | "Auto" }`
-- **Flexbox**: `flex_direction`, `justify_content`, `align_items`, `flex_wrap`, etc.
-- **Grid**: `grid_template_rows`, `grid_template_columns`, etc.
+```typescript
+{
+  Length: 10;
+}
+{
+  Percent: 0.1;
+}
+("Auto");
+```
+
+#### AvailableSpace (JsAvailableSize)
+
+Constraints for layout computation:
+
+```typescript
+{
+  width: { Definite: 800 },   // Fixed width
+  height: { Definite: 600 }   // Fixed height
+}
+
+{
+  width: "MaxContent",        // Intrinsic max width
+  height: "MinContent"        // Intrinsic min height
+}
+```
 
-#### `AvailableSpace`
+#### Layout Result
 
-Used when triggering computation.
+Returned by `getLayout()`:
 
 ```typescript
-interface AvailableSpace {
-  width: number | null; // null = unlimited/content-based
-  height: number | null; // null = unlimited/content-based
+{
+  order: number,
+  size: { width: number, height: number },
+  location: { x: number, y: number },
+  padding: { left, right, top, bottom },
+  border: { left, right, top, bottom },
+  scrollbar_size: { width, height },
+  content_size: { width, height }
 }
 ```
 
+---
+
+### Enums
+
+#### Display
+
+```typescript
+Display.Block; // Block layout (default)
+Display.Flex; // Flexbox container
+Display.Grid; // CSS Grid container
+Display.None; // Hidden, takes no space
+```
+
+#### Position
+
+```typescript
+Position.Relative; // Normal document flow (default)
+Position.Absolute; // Removed from flow, positioned via inset
+```
+
+#### FlexDirection
+
+```typescript
+FlexDirection.Row; // Horizontal, left to right
+FlexDirection.Column; // Vertical, top to bottom
+FlexDirection.RowReverse; // Horizontal, right to left
+FlexDirection.ColumnReverse; // Vertical, bottom to top
+```
+
+#### FlexWrap
+
+```typescript
+FlexWrap.NoWrap; // Single line (default)
+FlexWrap.Wrap; // Wrap to multiple lines
+FlexWrap.WrapReverse; // Wrap in reverse order
+```
+
+#### AlignItems / AlignSelf
+
+```typescript
+AlignItems.Start; // Align to start
+AlignItems.End; // Align to end
+AlignItems.FlexStart; // Align to flex start
+AlignItems.FlexEnd; // Align to flex end
+AlignItems.Center; // Center alignment
+AlignItems.Baseline; // Baseline alignment
+AlignItems.Stretch; // Stretch to fill
+
+AlignSelf.Auto; // Inherit from parent (AlignSelf only)
+```
+
+#### AlignContent
+
+```typescript
+AlignContent.Start;
+AlignContent.End;
+AlignContent.FlexStart;
+AlignContent.FlexEnd;
+AlignContent.Center;
+AlignContent.Stretch;
+AlignContent.SpaceBetween;
+AlignContent.SpaceAround;
+AlignContent.SpaceEvenly;
+```
+
+#### JustifyContent
+
+```typescript
+JustifyContent.Start;
+JustifyContent.End;
+JustifyContent.FlexStart;
+JustifyContent.FlexEnd;
+JustifyContent.Center;
+JustifyContent.Stretch;
+JustifyContent.SpaceBetween;
+JustifyContent.SpaceAround;
+JustifyContent.SpaceEvenly;
+```
+
+#### Overflow
+
+```typescript
+Overflow.Visible; // Content not clipped
+Overflow.Hidden; // Content clipped
+Overflow.Scroll; // Always show scrollbars
+Overflow.Auto; // Show scrollbars when needed
+```
+
+---
+
+## 📏 Custom Measurement
+
+For nodes with intrinsic sizes (like text), use `computeLayoutWithMeasure`:
+
+```typescript
+tree.computeLayoutWithMeasure(
+  root,
+  { width: { Definite: 800 }, height: { Definite: 600 } },
+  (knownDimensions, availableSpace, context) => {
+    // knownDimensions: { width: number | null, height: number | null }
+    // availableSpace: { width: AvailableSpace, height: AvailableSpace }
+    // context: The value attached via setNodeContext/newLeafWithContext
+
+    // Return the measured size
+    return { width: 100, height: 20 };
+  },
+);
+```
+
+**Example with text measurement:**
+
+```typescript
+// Create a text node with context
+const textNode = tree.newLeafWithContext(style, { text: "Hello World" });
+
+// Measure function
+tree.computeLayoutWithMeasure(root, availableSpace, (known, available, ctx) => {
+  if (ctx?.text) {
+    // Use your text measurement library here
+    const measured = measureText(ctx.text, available.width);
+    return { width: measured.width, height: measured.height };
+  }
+  return { width: 0, height: 0 };
+});
+```
+
+---
+
 ## 🛠 Building from Source
 
-If you want to contribute or build the WASM binary yourself:
-
-1.  **Prerequisites**: Install Rust and `wasm-pack`.
-    ```bash
-    curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
-    ```
-2.  **Build**:
-    ```bash
-    npm install
-    npm run build
-    ```
-    The artifacts will be generated in the `pkg/` directory.
+1. **Prerequisites**: Install Rust and `wasm-pack`
+
+   ```bash
+   curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+   ```
+
+2. **Build**
+
+   ```bash
+   npm install
+   npm run build
+   ```
+
+3. **Build with debug features**
+
+   ```bash
+   wasm-pack build --features console_error_panic_hook
+   ```
+
+---
 
 ## 📄 License
 

package/package.json

@@ -1,24 +1,58 @@
 {
   "name": "taffy-js",
-  "type": "module",
-  "collaborators": [
-    "ByteLandTechnology <github@byteland.app>"
-  ],
+  "version": "0.2.0",
   "description": "WebAssembly bindings for Taffy layout library",
-  "version": "0.1.2",
-  "license": "MIT",
+  "keywords": [
+    "layout",
+    "flexbox",
+    "css-grid",
+    "grid",
+    "ui",
+    "wasm",
+    "webassembly"
+  ],
+  "homepage": "https://github.com/ByteLandTechnology/taffy-js#readme",
+  "bugs": {
+    "url": "https://github.com/ByteLandTechnology/taffy-js/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ByteLandTechnology/taffy-js"
+    "url": "git+https://github.com/ByteLandTechnology/taffy-js.git"
   },
+  "license": "MIT",
+  "author": "ByteLandTechnology <github@byteland.app>",
+  "type": "module",
+  "main": "pkg/taffy_js.js",
+  "types": "pkg/taffy_js.d.ts",
   "files": [
-    "taffy_js_bg.wasm",
-    "taffy_js.js",
-    "taffy_js.d.ts"
+    "pkg"
   ],
-  "main": "taffy_js.js",
-  "types": "taffy_js.d.ts",
-  "sideEffects": [
-    "./snippets/*"
-  ]
-}
+  "scripts": {
+    "build": "wasm-pack build --release --target web",
+    "build:dev": "wasm-pack build --dev --target web",
+    "test": "wasm-pack test --node",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "wasm-pack": "^0.13.1"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "overrides": {
+    "axios": "^1.7.9"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write"
+  }
+}