taffy-wasm 0.9.2 → 0.9.4

package/README.md

@@ -1,18 +1,18 @@
-# Taffy WebAssembly Bindings
+# Taffy-JS
 
-> **High-performance Flexbox and CSS Grid layout for JavaScript/TypeScript, powered by Rust and WebAssembly.**
+[![npm version](https://badge.fury.io/js/taffy-js.svg)](https://www.npmjs.com/package/taffy-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-![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.
+High-performance WebAssembly bindings for the [Taffy](https://github.com/DioxusLabs/taffy) layout engine, bringing CSS Flexbox and Grid layout algorithms to JavaScript 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**: WebAssembly-powered layout calculations
+- **📦 Complete CSS Support**: Full Flexbox and CSS Grid implementation
+- **🔧 Custom Measurement**: Support for custom text/content measurement callbacks
+- **📝 TypeScript Ready**: Complete type definitions included
+- **🌳 Tree-Based API**: Efficient tree structure for complex layouts
+- **💡 Familiar API**: CSS-like property names and values
 
 ## 📦 Installation
 
@@ -20,159 +20,434 @@
 npm install taffy-js
 ```
 
-> **Note**: This package relies on WebAssembly. Ensure your runtime (modern browser or Node.js) supports WASM.
-
-## 🚀 Usage
+## 🚀 Quick Start
 
-Here is a complete example showing how to create a layout tree, style nodes, and compute results.
-
-```typescript
-import init, {
-  new_leaf,
-  new_with_children,
-  compute_layout,
-  get_layout,
+```javascript
+import {
+  loadTaffy,
+  TaffyTree,
+  Style,
   Display,
   FlexDirection,
   AlignItems,
-  JustifyContent,
-  Style,
 } from "taffy-js";
 
-async function run() {
-  // 1. Initialize the 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,
+async function main() {
+  // Initialize WebAssembly module
+  await loadTaffy();
+
+  // Create a layout tree
+  const tree = new TaffyTree();
+
+  // Create container style
+  const containerStyle = new Style();
+  containerStyle.display = Display.Flex;
+  containerStyle.flexDirection = FlexDirection.Column;
+  containerStyle.alignItems = AlignItems.Center;
+  containerStyle.size = { width: { Length: 300 }, height: { Length: 200 } };
+  containerStyle.padding = {
+    left: { Length: 10 },
+    right: { Length: 10 },
+    top: { Length: 10 },
+    bottom: { Length: 10 },
   };
 
-  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
-  };
+  // Create child styles
+  const childStyle = new Style();
+  childStyle.flexGrow = 1;
+  childStyle.size = { width: { Percent: 100 }, height: "Auto" };
+
+  // Create nodes
+  const child1 = tree.newLeaf(childStyle);
+  const child2 = tree.newLeaf(childStyle);
+  const container = tree.newWithChildren(
+    containerStyle,
+    BigUint64Array.from([child1, child2]),
+  );
+
+  // Compute layout
+  tree.computeLayout(container, {
+    width: { Definite: 300 },
+    height: { Definite: 200 },
+  });
 
-  // 3. Create Tree Nodes
-  // Leaf nodes
-  const child1 = new_leaf(boxStyle);
-  const child2 = new_leaf(boxStyle);
+  // Read computed layouts
+  const containerLayout = tree.getLayout(container);
+  const child1Layout = tree.getLayout(child1);
+  const child2Layout = tree.getLayout(child2);
+
+  console.log(`Container: ${containerLayout.width}x${containerLayout.height}`);
+  console.log(
+    `Child 1: ${child1Layout.width}x${child1Layout.height} at (${child1Layout.x}, ${child1Layout.y})`,
+  );
+  console.log(
+    `Child 2: ${child2Layout.width}x${child2Layout.height} at (${child2Layout.x}, ${child2Layout.y})`,
+  );
+}
 
-  // Root node with children
-  const root = new_with_children(rootStyle, [child1, child2]);
+main();
+```
 
-  // 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,
-  });
+## 📖 API Reference
 
-  // 5. Retrieve Results
-  const rootLayout = get_layout(root);
-  const child1Layout = get_layout(child1);
-  const child2Layout = get_layout(child2);
+### TaffyTree
 
-  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 }
+The main class for managing layout trees.
+
+```typescript
+class TaffyTree {
+  // Construction
+  constructor();
+  static withCapacity(capacity: number): TaffyTree;
+
+  // Node Creation (throws TaffyError on failure)
+  newLeaf(style: Style): bigint;
+  newLeafWithContext(style: Style, context: any): bigint;
+  newWithChildren(style: Style, children: BigUint64Array): bigint;
+
+  // Tree Operations
+  clear(): void;
+  remove(node: bigint): bigint; // throws TaffyError
+  totalNodeCount(): number;
+
+  // Child Management (throws TaffyError on failure)
+  addChild(parent: bigint, child: bigint): void;
+  removeChild(parent: bigint, child: bigint): bigint;
+  setChildren(parent: bigint, children: BigUint64Array): void;
+  children(parent: bigint): BigUint64Array;
+  childCount(parent: bigint): number;
+  parent(child: bigint): bigint | undefined;
+
+  // Style Management (throws TaffyError on failure)
+  setStyle(node: bigint, style: Style): void;
+  getStyle(node: bigint): Style;
+
+  // Layout Computation (throws TaffyError on failure)
+  computeLayout(node: bigint, availableSpace: Size<AvailableSpace>): void;
+  computeLayoutWithMeasure(
+    node: bigint,
+    availableSpace: Size<AvailableSpace>,
+    measureFunc: MeasureFunction,
+  ): void;
+
+  // Layout Results (throws TaffyError on failure)
+  getLayout(node: bigint): Layout;
+  unroundedLayout(node: bigint): Layout;
+
+  // Dirty Tracking (throws TaffyError on failure)
+  markDirty(node: bigint): void;
+  dirty(node: bigint): boolean;
+
+  // Configuration
+  enableRounding(): void;
+  disableRounding(): void;
 }
+```
 
-run();
+### Style
+
+Configuration object for node layout properties.
+
+```typescript
+class Style {
+  constructor();
+
+  // Layout Mode
+  display: Display; // Block, Flex, Grid, None
+  position: Position; // Relative, Absolute
+
+  // Flexbox
+  flexDirection: FlexDirection; // Row, Column, RowReverse, ColumnReverse
+  flexWrap: FlexWrap; // NoWrap, Wrap, WrapReverse
+  flexGrow: number; // Growth factor (default: 0)
+  flexShrink: number; // Shrink factor (default: 1)
+  flexBasis: Dimension; // Initial size
+
+  // Alignment
+  alignItems: AlignItems | undefined;
+  alignSelf: AlignSelf | undefined;
+  alignContent: AlignContent | undefined;
+  justifyContent: JustifyContent | undefined;
+
+  // Sizing
+  size: Size<Dimension>; // Width and height
+  minSize: Size<Dimension>; // Minimum constraints
+  maxSize: Size<Dimension>; // Maximum constraints
+  aspectRatio: number | undefined; // Width/height ratio
+  boxSizing: BoxSizing; // BorderBox, ContentBox
+
+  // Spacing
+  margin: Rect<LengthPercentageAuto>;
+  padding: Rect<LengthPercentage>;
+  border: Rect<LengthPercentage>;
+  gap: Size<LengthPercentage>; // Row and column gap
+  inset: Rect<LengthPercentageAuto>; // For absolute positioning
+
+  // Overflow
+  overflow: Point<Overflow>;
+}
 ```
 
-## 📐 Architecture
+### Layout
+
+Read-only computed layout result.
+
+```typescript
+class Layout {
+  // Position (relative to parent)
+  readonly x: number;
+  readonly y: number;
+
+  // Size
+  readonly width: number;
+  readonly height: number;
+
+  // Content size (for scrollable content)
+  readonly contentWidth: number;
+  readonly contentHeight: number;
+
+  // Spacing
+  readonly paddingTop: number;
+  readonly paddingRight: number;
+  readonly paddingBottom: number;
+  readonly paddingLeft: number;
+
+  readonly borderTop: number;
+  readonly borderRight: number;
+  readonly borderBottom: number;
+  readonly borderLeft: number;
+
+  readonly marginTop: number;
+  readonly marginRight: number;
+  readonly marginBottom: number;
+  readonly marginLeft: number;
+
+  // Scrollbars
+  readonly scrollbarWidth: number;
+  readonly scrollbarHeight: number;
+
+  // Rendering order
+  readonly order: number;
+}
+```
+
+### Enums
+
+```typescript
+enum Display {
+  Block,
+  Flex,
+  Grid,
+  None,
+}
+enum Position {
+  Relative,
+  Absolute,
+}
+enum FlexDirection {
+  Row,
+  Column,
+  RowReverse,
+  ColumnReverse,
+}
+enum FlexWrap {
+  NoWrap,
+  Wrap,
+  WrapReverse,
+}
+enum AlignItems {
+  Start,
+  End,
+  FlexStart,
+  FlexEnd,
+  Center,
+  Baseline,
+  Stretch,
+}
+enum AlignSelf {
+  Auto,
+  Start,
+  End,
+  FlexStart,
+  FlexEnd,
+  Center,
+  Baseline,
+  Stretch,
+}
+enum AlignContent {
+  Start,
+  End,
+  FlexStart,
+  FlexEnd,
+  Center,
+  Stretch,
+  SpaceBetween,
+  SpaceAround,
+  SpaceEvenly,
+}
+enum JustifyContent {
+  Start,
+  End,
+  FlexStart,
+  FlexEnd,
+  Center,
+  Stretch,
+  SpaceBetween,
+  SpaceAround,
+  SpaceEvenly,
+}
+enum Overflow {
+  Visible,
+  Hidden,
+  Scroll,
+  Auto,
+}
+enum BoxSizing {
+  BorderBox,
+  ContentBox,
+}
+```
 
-`taffy-js` acts as a thin wrapper around the [Taffy](https://github.com/DioxusLabs/taffy) Rust crate.
+### Types
 
-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.
+```typescript
+// Dimension values
+type Dimension = { Length: number } | { Percent: number } | "Auto";
+type LengthPercentage = { Length: number } | { Percent: number };
+type LengthPercentageAuto = { Length: number } | { Percent: number } | "Auto";
+
+// Geometry
+interface Size<T> {
+  width: T;
+  height: T;
+}
+interface Rect<T> {
+  left: T;
+  right: T;
+  top: T;
+  bottom: T;
+}
+interface Point<T> {
+  x: T;
+  y: T;
+}
 
-## 📚 API Reference
+// Available space for layout computation
+type AvailableSpace = { Definite: number } | "MinContent" | "MaxContent";
+
+// Measure function for custom content measurement
+type MeasureFunction = (
+  knownDimensions: Size<number | null>,
+  availableSpace: Size<AvailableSpace>,
+  node: bigint,
+  context: any,
+  style: Style,
+) => Size<number>;
+```
 
-### Lifecycle
+## 📐 Custom Text Measurement
+
+For text nodes or other content that needs dynamic measurement:
+
+```javascript
+const textNode = tree.newLeafWithContext(textStyle, { text: "Hello, World!" });
+
+tree.computeLayoutWithMeasure(
+  rootNode,
+  { width: { Definite: 800 }, height: "MaxContent" },
+  (known, available, node, context, style) => {
+    if (context?.text) {
+      // Your text measurement logic here
+      const width = measureTextWidth(context.text);
+      const height = measureTextHeight(context.text, available.width);
+      return { width, height };
+    }
+    return { width: 0, height: 0 };
+  },
+);
+```
 
-| 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. |
+## 🔧 Error Handling
 
-### Node Management
+Methods that can fail throw a `TaffyError` as a JavaScript exception. Use try-catch to handle errors:
 
-| 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.    |
+```javascript
+try {
+  const nodeId = tree.newLeaf(style);
+  console.log("Created node:", nodeId);
+} catch (error) {
+  // error is a TaffyError instance
+  console.error("Error:", error.message);
+}
+```
 
-### Layout & Style
+## 🌐 Browser Support
 
-| 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). |
+Taffy-JS works in all modern browsers that support WebAssembly:
 
-### Type Definitions
+- Chrome 57+
+- Firefox 52+
+- Safari 11+
+- Edge 16+
 
-#### `Style`
+## 📚 Examples
 
-A comprehensive object mirroring CSS properties.
+### Flexbox Row Layout
 
-- **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.
+```javascript
+const rowStyle = new Style();
+rowStyle.display = Display.Flex;
+rowStyle.flexDirection = FlexDirection.Row;
+rowStyle.justifyContent = JustifyContent.SpaceBetween;
+rowStyle.gap = { width: { Length: 10 }, height: { Length: 0 } };
+```
 
-#### `AvailableSpace`
+### Absolute Positioning
+
+```javascript
+const absoluteStyle = new Style();
+absoluteStyle.position = Position.Absolute;
+absoluteStyle.inset = {
+  left: { Length: 10 },
+  top: { Length: 10 },
+  right: "Auto",
+  bottom: "Auto",
+};
+absoluteStyle.size = { width: { Length: 100 }, height: { Length: 50 } };
+```
 
-Used when triggering computation.
+### Percentage Sizing
 
-```typescript
-interface AvailableSpace {
-  width: number | null; // null = unlimited/content-based
-  height: number | null; // null = unlimited/content-based
-}
+```javascript
+const percentStyle = new Style();
+percentStyle.size = {
+  width: { Percent: 50 }, // 50% of parent
+  height: { Percent: 100 }, // 100% of parent
+};
 ```
 
-## 🛠 Building from Source
+## 🏗️ Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/user/taffy-js.git
+cd taffy-js
+
+# Install dependencies
+npm install
 
-If you want to contribute or build the WASM binary yourself:
+# Build the WebAssembly module
+npm run build
 
-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.
+# Run tests
+npm test
+```
 
 ## 📄 License
 
-MIT License © 2024 ByteLand Technology
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
 
-This project wraps [Taffy](https://github.com/DioxusLabs/taffy), which is also MIT licensed.
+- [Taffy](https://github.com/DioxusLabs/taffy) - The Rust layout engine this project wraps
+- [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) - Rust/WebAssembly interoperability

package/package.json

@@ -2,16 +2,14 @@
   "name": "taffy-wasm",
   "type": "module",
   "collaborators": [
-    "Alice Cecile <alice.i.cecile@gmail.com>",
-    "Johnathan Kelley <jkelleyrtp@gmail.com>",
-    "Nico Burns <nico@nicoburns.com>"
+    "ByteLandTechnology <github@byteland.app>"
   ],
   "description": "WebAssembly bindings for Taffy layout library",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DioxusLabs/taffy"
+    "url": "https://github.com/ByteLandTechnology/taffy-js"
   },
   "files": [
     "taffy_wasm_bg.wasm",