taffy-js 0.2.10 → 0.2.12

package/README.md

@@ -22,7 +22,7 @@ npm install taffy-js
 
 ## 🚀 Quick Start
 
-```javascript
+```typescript
 import {
   loadTaffy,
   TaffyTree,
@@ -32,52 +32,48 @@ import {
   AlignItems,
 } from "taffy-js";
 
-async function main() {
-  // Initialize WebAssembly module
-  await loadTaffy();
+// 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]),
+);
 
-  // Create a layout tree
-  const tree = new TaffyTree();
+// Compute layout
+tree.computeLayout(container, { width: 300, height: 200 });
 
-  // 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})`,
-  );
-}
+// Read computed layouts
+const containerLayout = tree.getLayout(container);
+const child1Layout = tree.getLayout(child1);
+const child2Layout = tree.getLayout(child2);
 
-main();
+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
@@ -86,272 +82,49 @@ main();
 
 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;
-}
-```
+[View Documentation](https://github.com/ByteLandTechnology/taffy-js/blob/main/docs/classes/TaffyTree.md)
 
 ### 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>;
-}
-```
+[View Documentation](https://github.com/ByteLandTechnology/taffy-js/blob/main/docs/classes/Style.md)
 
 ### 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;
-}
-```
+[View Documentation](https://github.com/ByteLandTechnology/taffy-js/blob/main/docs/classes/Layout.md)
 
 ### 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,
-}
-```
+[View Documentation](https://github.com/ByteLandTechnology/taffy-js/blob/main/docs/modules.md#enums)
 
 ### Types
 
-```typescript
-// Dimension values (CSS-like syntax)
-type Dimension = number | `${number}%` | "auto"; // e.g., 100, "50%", "auto"
-type LengthPercentage = number | `${number}%`; // e.g., 10, "25%"
-type LengthPercentageAuto = number | `${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;
-}
-
-// Available space for layout computation
-type AvailableSpace = number | "minContent" | "maxContent";
-
-// Measure function for custom content measurement
-type MeasureFunction = (
-  knownDimensions: Size<number | undefined>,
-  availableSpace: Size<AvailableSpace>,
-  node: bigint,
-  context: any,
-  style: Style,
-) => Size<number>;
-```
+[View Documentation](https://github.com/ByteLandTechnology/taffy-js/blob/main/docs/modules.md#type-aliases)
 
 ## 📐 Custom Text Measurement
 
 For text nodes or other content that needs dynamic measurement:
 
-```javascript
+```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: "maxContent" },
+  { 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);
+      const height = measureTextHeight(context.text, available.width as number);
       return { width, height };
     }
     return { width: 0, height: 0 };
@@ -363,13 +136,16 @@ tree.computeLayoutWithMeasure(
 
 Methods that can fail throw a `TaffyError` as a JavaScript exception. Use try-catch to handle errors:
 
-```javascript
+```typescript
 try {
+  const tree = new TaffyTree();
+  const style = new Style();
   const nodeId = tree.newLeaf(style);
   console.log("Created node:", nodeId);
-} catch (error) {
-  // error is a TaffyError instance
-  console.error("Error:", error.message);
+} catch (e) {
+  if (e instanceof TaffyError) {
+    console.error("Error:", e.message);
+  }
 }
 ```
 
@@ -386,7 +162,7 @@ Taffy-JS works in all modern browsers that support WebAssembly:
 
 ### Flexbox Row Layout
 
-```javascript
+```typescript
 const rowStyle = new Style();
 rowStyle.display = Display.Flex;
 rowStyle.flexDirection = FlexDirection.Row;
@@ -394,9 +170,46 @@ rowStyle.justifyContent = JustifyContent.SpaceBetween;
 rowStyle.gap = { width: 10, height: 0 };
 ```
 
+### CSS Grid Layout
+
+```typescript
+import { Style, Display, GridAutoFlow } from "taffy-js";
+
+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
 
-```javascript
+```typescript
 const absoluteStyle = new Style();
 absoluteStyle.position = Position.Absolute;
 absoluteStyle.inset = { left: 10, top: 10, right: "auto", bottom: "auto" };
@@ -405,7 +218,7 @@ absoluteStyle.size = { width: 100, height: 50 };
 
 ### Percentage Sizing
 
-```javascript
+```typescript
 const percentStyle = new Style();
 percentStyle.size = {
   width: "50%", // 50% of parent
@@ -413,6 +226,15 @@ percentStyle.size = {
 };
 ```
 
+### 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taffy-js",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "WebAssembly bindings for Taffy layout library",
   "keywords": [
     "layout",
@@ -41,10 +41,11 @@
   "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",
+    "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"
   },
@@ -77,4 +78,4 @@
     "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write",
     "*.rs": "cargo fmt --"
   }
-}
+}