taffy-layout 0.1.0

package/README.md

@@ -0,0 +1,262 @@
+# Taffy Layout
+
+[![npm version](https://badge.fury.io/js/taffy-layout.svg)](https://www.npmjs.com/package/taffy-layout)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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**: 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
+
+```bash
+npm install taffy-layout
+```
+
+## 🚀 Quick Start
+
+```typescript
+import {
+  loadTaffy,
+  TaffyTree,
+  Style,
+  Display,
+  FlexDirection,
+  AlignItems,
+} from "taffy-layout";
+
+// 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: 300, height: 200 };
+containerStyle.padding = { left: 10, right: 10, top: 10, bottom: 10 };
+
+// Create child styles
+const childStyle = new Style();
+childStyle.flexGrow = 1;
+childStyle.size = { width: "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: 300, height: 200 });
+
+// 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})`,
+);
+```
+
+## 📖 API Reference
+
+### TaffyTree
+
+The main class for managing layout trees.
+
+[View Documentation](./docs/classes/TaffyTree.md)
+
+### Style
+
+Configuration object for node layout properties.
+
+[View Documentation](./docs/classes/Style.md)
+
+### Layout
+
+Read-only computed layout result.
+
+[View Documentation](./docs/classes/Layout.md)
+
+### Enums
+
+[View Documentation](./docs/index.md#enumerations)
+
+### Types
+
+[View Documentation](./docs/index.md#type-aliases)
+
+## 📐 Custom Text Measurement
+
+For text nodes or other content that needs dynamic measurement:
+
+```typescript
+const tree = new TaffyTree();
+const textStyle = new Style();
+const rootNode = tree.newLeaf(new Style());
+const measureTextWidth = (text: string) => text.length * 8;
+const measureTextHeight = (text: string, width: number) => 20;
+
+const textNode = tree.newLeafWithContext(textStyle, { text: "Hello, World!" });
+
+tree.computeLayoutWithMeasure(
+  rootNode,
+  { width: 800, height: "max-content" },
+  (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 as number);
+      return { width, height };
+    }
+    return { width: 0, height: 0 };
+  },
+);
+```
+
+## 🔧 Error Handling
+
+Methods that can fail throw a `TaffyError` as a JavaScript exception. Use try-catch to handle errors:
+
+```typescript
+try {
+  const tree = new TaffyTree();
+  const style = new Style();
+  const nodeId = tree.newLeaf(style);
+  console.log("Created node:", nodeId);
+} catch (e) {
+  if (e instanceof TaffyError) {
+    console.error("Error:", e.message);
+  }
+}
+```
+
+## 🌐 Browser Support
+
+Taffy Layout works in all modern browsers that support WebAssembly:
+
+- Chrome 57+
+- Firefox 52+
+- Safari 11+
+- Edge 16+
+
+## 📚 Examples
+
+### Flexbox Row Layout
+
+```typescript
+const rowStyle = new Style();
+rowStyle.display = Display.Flex;
+rowStyle.flexDirection = FlexDirection.Row;
+rowStyle.justifyContent = JustifyContent.SpaceBetween;
+rowStyle.gap = { width: 10, height: 0 };
+```
+
+### CSS Grid Layout
+
+```typescript
+import { Style, Display, GridAutoFlow } from "taffy-layout";
+
+const gridStyle = new Style();
+gridStyle.display = Display.Grid;
+gridStyle.gridAutoFlow = GridAutoFlow.Row;
+gridStyle.gap = { width: 10, height: 10 };
+
+// Grid item placement
+const itemStyle = new Style();
+itemStyle.gridRow = { start: 1, end: 3 }; // Spans 2 rows
+itemStyle.gridColumn = { start: 1, end: { span: 2 } }; // Spans 2 columns
+```
+
+### Grid Template Areas
+
+```typescript
+const gridStyle = new Style();
+gridStyle.display = Display.Grid;
+gridStyle.gridTemplateAreas = [
+  { name: "header", rowStart: 1, rowEnd: 2, columnStart: 1, columnEnd: 4 },
+  { name: "sidebar", rowStart: 2, rowEnd: 4, columnStart: 1, columnEnd: 2 },
+  { name: "main", rowStart: 2, rowEnd: 4, columnStart: 2, columnEnd: 4 },
+  { name: "footer", rowStart: 4, rowEnd: 5, columnStart: 1, columnEnd: 4 },
+];
+
+// Named grid lines
+gridStyle.gridTemplateRowNames = [
+  ["header-start"],
+  ["header-end", "content-start"],
+  ["content-end", "footer-start"],
+  ["footer-end"],
+];
+```
+
+### Absolute Positioning
+
+```typescript
+const absoluteStyle = new Style();
+absoluteStyle.position = Position.Absolute;
+absoluteStyle.inset = { left: 10, top: 10, right: "auto", bottom: "auto" };
+absoluteStyle.size = { width: 100, height: 50 };
+```
+
+### Percentage Sizing
+
+```typescript
+const percentStyle = new Style();
+percentStyle.size = {
+  width: "50%", // 50% of parent
+  height: "100%", // 100% of parent
+};
+```
+
+### Block Layout with Replaced Elements
+
+```typescript
+const imgStyle = new Style();
+imgStyle.itemIsReplaced = true;
+imgStyle.aspectRatio = 16 / 9; // 16:9 aspect ratio
+imgStyle.size = { width: "100%", height: "auto" };
+```
+
+## 🏗️ Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/ByteLandTechnology/taffy-layout.git
+cd taffy-layout
+
+# Install dependencies
+npm install
+
+# Build the WebAssembly module
+npm run build
+
+# Run tests
+npm test
+```
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- [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/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Taffy Layout: TypeScript wrapper for Taffy WASM bindings
+ *
+ * This module provides the `loadTaffy` function for initializing the WASM module
+ * and re-exports all types and functions from the underlying WASM bindings.
+ *
+ * @example
+ * ```typescript
+ * import { loadTaffy, TaffyTree, Style, Display } from 'taffy-layout';
+ *
+ * await loadTaffy();
+ *
+ * const tree = new TaffyTree();
+ * const style = new Style();
+ * style.display = Display.Flex;
+ * const node = tree.newLeaf(style);
+ * ```
+ */
+export * from "../pkg/taffy_wasm.js";
+export type { InitOutput } from "../pkg/taffy_wasm.js";
+import type { InitOutput } from "../pkg/taffy_wasm.js";
+/**
+ * Universal initialization function for Taffy WASM module.
+ *
+ * Automatically detects the environment (Web or Node.js) and loads the WASM accordingly.
+ * - In a **Web environment**, it uses `fetch` to load the WASM file.
+ * - In a **Node.js environment**, it uses `fs` to read the WASM file.
+ *
+ * @returns - A promise that resolves to the WASM module exports.
+ *
+ * @example
+ * ```typescript
+ * import { loadTaffy } from 'taffy-layout';
+ * await loadTaffy();
+ * ```
+ */
+export declare function loadTaffy(): Promise<InitOutput>;
+export default loadTaffy;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,cAAc,sBAAsB,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAavD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,CAkBrD;AAGD,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,66 @@
+/**
+ * Taffy Layout: TypeScript wrapper for Taffy WASM bindings
+ *
+ * This module provides the `loadTaffy` function for initializing the WASM module
+ * and re-exports all types and functions from the underlying WASM bindings.
+ *
+ * @example
+ * ```typescript
+ * import { loadTaffy, TaffyTree, Style, Display } from 'taffy-layout';
+ *
+ * await loadTaffy();
+ *
+ * const tree = new TaffyTree();
+ * const style = new Style();
+ * style.display = Display.Flex;
+ * const node = tree.newLeaf(style);
+ * ```
+ */
+// Re-export everything from the WASM module
+export * from "../pkg/taffy_wasm.js";
+// Import the init functions for the loader
+import init, { initSync } from "../pkg/taffy_wasm.js";
+/**
+ * Detects if running in a Node.js environment
+ */
+function isNode() {
+    return (typeof process !== "undefined" &&
+        process.versions != null &&
+        process.versions.node != null);
+}
+/**
+ * Universal initialization function for Taffy WASM module.
+ *
+ * Automatically detects the environment (Web or Node.js) and loads the WASM accordingly.
+ * - In a **Web environment**, it uses `fetch` to load the WASM file.
+ * - In a **Node.js environment**, it uses `fs` to read the WASM file.
+ *
+ * @returns - A promise that resolves to the WASM module exports.
+ *
+ * @example
+ * ```typescript
+ * import { loadTaffy } from 'taffy-layout';
+ * await loadTaffy();
+ * ```
+ */
+export async function loadTaffy() {
+    if (isNode()) {
+        // Node.js environment - use fs to read the WASM file
+        const fs = await import("fs");
+        const url = await import("url");
+        const path = await import("path");
+        // Resolve WASM path relative to this module
+        const __filename = url.fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const wasmPath = path.join(__dirname, "..", "pkg", "taffy_wasm_bg.wasm");
+        const wasmBuffer = fs.readFileSync(wasmPath);
+        return initSync({ module: wasmBuffer });
+    }
+    else {
+        // Web environment - use fetch via the default init function
+        return await init();
+    }
+}
+// Default export for convenience
+export default loadTaffy;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,4CAA4C;AAC5C,cAAc,sBAAsB,CAAC;AAGrC,2CAA2C;AAC3C,OAAO,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGtD;;GAEG;AACH,SAAS,MAAM;IACb,OAAO,CACL,OAAO,OAAO,KAAK,WAAW;QAC9B,OAAO,CAAC,QAAQ,IAAI,IAAI;QACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,MAAM,EAAE,EAAE,CAAC;QACb,qDAAqD;QACrD,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QAElC,4CAA4C;QAC5C,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC;QAEzE,MAAM,UAAU,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,OAAO,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,4DAA4D;QAC5D,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;AACH,CAAC;AAED,iCAAiC;AACjC,eAAe,SAAS,CAAC"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "taffy-layout",
+  "version": "0.1.0",
+  "description": "WebAssembly bindings for Taffy layout library",
+  "keywords": [
+    "layout",
+    "flexbox",
+    "css-grid",
+    "grid",
+    "ui",
+    "wasm",
+    "webassembly"
+  ],
+  "homepage": "https://github.com/ByteLandTechnology/taffy-layout#readme",
+  "bugs": {
+    "url": "https://github.com/ByteLandTechnology/taffy-layout/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ByteLandTechnology/taffy-layout.git"
+  },
+  "license": "MIT",
+  "author": "ByteLandTechnology <github@byteland.app>",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./wasm": {
+      "types": "./pkg/taffy_wasm.d.ts",
+      "import": "./pkg/taffy_wasm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "pkg"
+  ],
+  "scripts": {
+    "build": "npm run build:wasm && npm run build:ts && npm run docs",
+    "build:wasm": "wasm-pack build --release --target web && rm -f pkg/.gitignore && npm run patch-dts",
+    "build:ts": "tsc && npm run generate:examples",
+    "build:dev": "wasm-pack build --dev --target web && npm run patch-dts && npm run build:ts",
+    "docs": "typedoc && prettier --write docs",
+    "patch-dts": "npx tsx scripts/patch-dts.ts",
+    "generate:examples": "npx tsx scripts/generate-example-tests.ts",
+    "test": "vitest run",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
+    "@types/node": "^22.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "tsx": "^4.0.0",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.16",
+    "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",
+    "*.rs": "cargo fmt --"
+  }
+}