Add default chunk shape calculation for v3 arrays

Co-authored-by: brokkoli71 <44113112+brokkoli71@users.noreply.github.com>

Author: Copilot

src/main/java/dev/zarr/zarrjava/v3/ArrayMetadataBuilder.java

@@ -161,13 +161,48 @@ public ArrayMetadata build() throws ZarrException {
         if (dataType == null) {
             throw new ZarrException("Data type needs to be provided. Please call `.withDataType`.");
         }
+        
+        // If chunk grid is not specified, calculate default chunks
         if (chunkGrid == null) {
-            throw new ZarrException("Chunk grid needs to be provided. Please call `.withChunkShape`.");
+            int[] defaultChunks = calculateDefaultChunks(shape);
+            chunkGrid = new RegularChunkGrid(new RegularChunkGrid.Configuration(defaultChunks));
         }
+        
         return new ArrayMetadata(shape, dataType, chunkGrid, chunkKeyEncoding, fillValue, codecs,
                 dimensionNames,
                 attributes,
                 storageTransformers
         );
     }
+    
+    /**
+     * Calculate default chunk shape when not specified.
+     * This implements JZarr's ArrayParams.build() logic, targeting chunks of approximately 512 elements.
+     * 
+     * The algorithm divides each dimension by 512 to determine the number of ~512-sized chunks,
+     * then calculates chunk sizes that will cover the dimension. Note that the total coverage
+     * may slightly exceed the dimension size (e.g., for shape=1024, chunks=342 results in 
+     * 3 chunks covering 1026 elements). This is intentional and matches JZarr behavior - 
+     * Zarr handles out-of-bounds gracefully, and the goal is approximate chunk sizes rather 
+     * than perfect tiling.
+     */
+    private int[] calculateDefaultChunks(long[] shape) {
+        int[] chunks = new int[shape.length];
+        for (int i = 0; i < shape.length; i++) {
+            long shapeDim = shape[i];
+            int numChunks = (int) (shapeDim / 512);
+            if (numChunks > 0) {
+                int chunkDim = (int) (shapeDim / (numChunks + 1));
+                if (shapeDim % chunkDim == 0) {
+                    chunks[i] = chunkDim;
+                } else {
+                    chunks[i] = chunkDim + 1;
+                }
+            } else {
+                // If dimension is smaller than 512, use the full dimension
+                chunks[i] = (int) shapeDim;
+            }
+        }
+        return chunks;
+    }
 }

src/test/java/dev/zarr/zarrjava/ZarrV3Test.java

@@ -773,4 +773,51 @@ public void testUnalignedArrayAccess(int arrayShape, int chunkShape, int accessS
             Assertions.assertArrayEquals(expectedData, (int[]) result.get1DJavaArray(ucar.ma2.DataType.UINT));
         }
     }
-}
+
+    @Test
+    public void testDefaultChunkShape() throws IOException, ZarrException {
+        // Test with a small array (< 512 elements per dimension)
+        Array smallArray = Array.create(
+                new FilesystemStore(TESTOUTPUT).resolve("v3_default_chunks_small"),
+                Array.metadataBuilder()
+                        .withShape(100, 50)
+                        .withDataType(DataType.UINT8)
+                        .build()
+        );
+        Assertions.assertEquals(2, smallArray.metadata().chunkShape().length);
+        // Both dimensions < 512, so chunks should equal shape
+        Assertions.assertEquals(100, smallArray.metadata().chunkShape()[0]);
+        Assertions.assertEquals(50, smallArray.metadata().chunkShape()[1]);
+
+        // Test with a larger array (> 512 elements per dimension)
+        Array largeArray = Array.create(
+                new FilesystemStore(TESTOUTPUT).resolve("v3_default_chunks_large"),
+                Array.metadataBuilder()
+                        .withShape(2000, 1500)
+                        .withDataType(DataType.UINT8)
+                        .build()
+        );
+        Assertions.assertEquals(2, largeArray.metadata().chunkShape().length);
+        // Chunks should be calculated based on division by 512
+        Assertions.assertTrue(largeArray.metadata().chunkShape()[0] > 0);
+        Assertions.assertTrue(largeArray.metadata().chunkShape()[0] < 2000);
+        Assertions.assertTrue(largeArray.metadata().chunkShape()[1] > 0);
+        Assertions.assertTrue(largeArray.metadata().chunkShape()[1] < 1500);
+
+        // Test with mixed dimensions
+        Array mixedArray = Array.create(
+                new FilesystemStore(TESTOUTPUT).resolve("v3_default_chunks_mixed"),
+                Array.metadataBuilder()
+                        .withShape(1024, 100, 2048)
+                        .withDataType(DataType.UINT8)
+                        .build()
+        );
+        Assertions.assertEquals(3, mixedArray.metadata().chunkShape().length);
+        // Verify chunks are reasonable
+        Assertions.assertTrue(mixedArray.metadata().chunkShape()[0] > 0);
+        Assertions.assertTrue(mixedArray.metadata().chunkShape()[0] <= 1024);
+        Assertions.assertEquals(100, mixedArray.metadata().chunkShape()[1]);  // < 512, should equal shape
+        Assertions.assertTrue(mixedArray.metadata().chunkShape()[2] > 0);
+        Assertions.assertTrue(mixedArray.metadata().chunkShape()[2] <= 2048);
+    }
+}