WIP: Java bindings

bindings/java/.gitignore

@@ -0,0 +1,6 @@
+# Rust
+rust/target/
+
+# Gradle
+java/.gradle/
+java/build/

bindings/java/README.md

@@ -0,0 +1,109 @@
+# Taffy Java bindings
+
+JNI bindings to the [Taffy](../../README.md) layout engine.
+
+Status: **WIP / MVP**. The flex and block subsets of the API are wired up;
+CSS Grid, measure functions, node context, and `calc()` are not yet exposed.
+
+## Layout
+
+- `rust/` — a `cdylib` Rust crate (`taffy_java`) containing the JNI entry
+  points. It is **not** part of the main Taffy workspace so a normal
+  `cargo build` in the repo root does not require a JDK.
+- `java/` — a Gradle project that compiles to `taffy-java-<version>.jar`
+  and runs JUnit tests against the freshly built cdylib.
+
+## Requirements
+
+- Rust 1.71+ (matches Taffy's MSRV)
+- JDK 8+ for consumers, JDK 17+ to run Gradle
+- Gradle 8+ (tested with 9.4)
+
+## Building
+
+From `bindings/java/java/`:
+
+```sh
+gradle build       # compiles cargo + javac, packages jar
+gradle test        # runs JUnit tests against the local cdylib
+```
+
+`:cargoBuild` shells out to `cargo build --release` in `../rust` and wires
+the output directory into `java.library.path` for tests via the
+`taffy.native.dir` system property.
+
+## Using the library
+
+```java
+import com.dioxuslabs.taffy.*;
+
+try (TaffyTree tree = new TaffyTree()) {
+    long child = tree.newLeaf(Style.builder()
+            .size(Dimension.percent(0.5f), Dimension.AUTO));
+
+    long root = tree.newWithChildren(Style.builder()
+            .size(Dimension.length(100f), Dimension.length(100f))
+            .justifyContent(JustifyContent.CENTER),
+            child);
+
+    tree.computeLayout(root, 100f, 100f);
+
+    Layout rootLayout  = tree.layout(root);
+    Layout childLayout = tree.layout(child);
+}
+```
+
+Every `TaffyTree` owns a native handle and must be closed (try-with-resources
+is the idiomatic pattern). Nodes are plain `long` ids scoped to the tree
+that produced them.
+
+## Loading the native library
+
+`NativeLoader` looks for the cdylib in this order:
+
+1. `-Dtaffy.native.path=/abs/path/to/libtaffy_java.dylib` — explicit file
+2. `-Dtaffy.native.dir=/abs/path/to/dir` — directory; the name is derived from
+   `System.mapLibraryName("taffy_java")`
+3. `/native/<os>-<arch>/<mappedName>` on the classpath (for shipping a jar
+   with bundled binaries — not produced by the default build yet)
+4. `System.loadLibrary("taffy_java")` using `java.library.path`
+
+## Scope (MVP)
+
+Exposed today:
+
+- `TaffyTree`: create, drop, enable/disable rounding, `newLeaf`,
+  `newWithChildren`, `setStyle`, `addChild`, `removeChild`, `childCount`,
+  `markDirty`, `remove`, `computeLayout`, `layout`.
+- `Style`: `display`, `position`, `boxSizing`, `overflow`, `scrollbarWidth`,
+  `size` / `minSize` / `maxSize`, `margin`, `inset`, `padding`, `border`,
+  `gap`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`,
+  `justifyContent`, `alignContent`, `alignItems`, `alignSelf`, `aspectRatio`.
+- Value types: `Dimension`, `LengthPercentage`, `LengthPercentageAuto`,
+  `AvailableSpace`.
+- Enums: `Display`, `Position`, `BoxSizing`, `Overflow`, `FlexDirection`,
+  `FlexWrap`, `JustifyContent`, `AlignContent`, `AlignItems`, `AlignSelf`.
+
+Not yet exposed:
+
+- CSS Grid (`grid-template-rows`/`columns`, `grid-auto-*`, placement, gaps).
+- Block-specific properties (`text-align`, float/clear).
+- Measure functions / node context (needed for text nodes).
+- `calc()` values.
+- Detailed layout info (grid track info, etc.).
+- Packaged binaries per OS/arch in the published jar.
+
+## Design notes
+
+- **Handles.** The Java side stores opaque `long` pointers for the tree and
+  for transient native `Style` objects. All handles are owned — the JVM
+  frees them deterministically, not via finalization.
+- **Style materialization.** `Style` is a Java-side bag of optional fields.
+  When a node is created it spins up a fresh native `Style` via JNI setters
+  and discards it immediately after. This favors clarity over raw throughput;
+  if needed we can later add a batched/serialized path.
+- **Error reporting.** Taffy errors (`TaffyError`) are thrown as
+  `com.dioxuslabs.taffy.TaffyException` across the JNI boundary.
+- **Tagged value types.** `Dimension` and friends are encoded as a
+  `(tag, float)` pair instead of a subclass hierarchy; this keeps the JNI
+  ABI simple — every setter takes primitives only.

bindings/java/java/build.gradle.kts

@@ -0,0 +1,81 @@
+plugins {
+    `java-library`
+}
+
+group = "com.dioxuslabs"
+version = "0.1.0-SNAPSHOT"
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation(platform("org.junit:junit-bom:5.10.2"))
+    testImplementation("org.junit.jupiter:junit-jupiter")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+// ---- Rust build integration ------------------------------------------------
+
+val rustProjectDir = layout.projectDirectory.dir("../rust")
+val rustTargetDir  = rustProjectDir.dir("target/release")
+
+val libFileName: String = run {
+    val osName = System.getProperty("os.name").lowercase()
+    when {
+        osName.contains("mac") || osName.contains("darwin") -> "libtaffy_java.dylib"
+        osName.contains("windows") -> "taffy_java.dll"
+        else -> "libtaffy_java.so"
+    }
+}
+
+val cargoBuild by tasks.registering(Exec::class) {
+    group = "build"
+    description = "Compile the taffy_java Rust cdylib (release)."
+    workingDir = rustProjectDir.asFile
+    commandLine("cargo", "build", "--release")
+    inputs.dir(rustProjectDir.dir("src"))
+    inputs.file(rustProjectDir.file("Cargo.toml"))
+    outputs.file(rustTargetDir.file(libFileName))
+}
+
+tasks.named<Test>("test") {
+    dependsOn(cargoBuild)
+    useJUnitPlatform()
+    // Point NativeLoader at the freshly built cdylib.
+    systemProperty("taffy.native.dir", rustTargetDir.asFile.absolutePath)
+    // JDK 22+ emits a warning when System.load is called without explicit
+    // native-access enablement. Opt in here so tests run clean.
+    jvmArgs("--enable-native-access=ALL-UNNAMED")
+    testLogging {
+        events("passed", "failed", "skipped")
+        showStandardStreams = true
+    }
+}
+
+// ---- Examples --------------------------------------------------------------
+// Each file under src/examples/java/com/dioxuslabs/taffy/examples/<Name>.java
+// becomes a `./gradlew example<Name>` task, analogous to `cargo run --example`.
+
+val examples by sourceSets.creating {
+    java.srcDir("src/examples/java")
+    compileClasspath += sourceSets["main"].output
+    runtimeClasspath += sourceSets["main"].output
+}
+
+listOf("Basic", "FlexboxGap", "Nested", "Measure", "GridHolyGrail").forEach { name ->
+    tasks.register<JavaExec>("example$name") {
+        group = "examples"
+        description = "Run the $name example."
+        dependsOn(cargoBuild, tasks.named("examplesClasses"))
+        classpath = examples.runtimeClasspath
+        mainClass.set("com.dioxuslabs.taffy.examples.$name")
+        systemProperty("taffy.native.dir", rustTargetDir.asFile.absolutePath)
+        jvmArgs("--enable-native-access=ALL-UNNAMED")
+    }
+}

bindings/java/java/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists