Add documentation catalog

Author: tomasf

Sources/Cadova/Cadova.docc/AlignmentAndStacking.md

@@ -0,0 +1,83 @@
+# Alignment and Stacking
+
+Position geometry relative to the origin and arrange shapes along an axis.
+
+## Overview
+
+In Cadova, alignment is a way to control how geometry is positioned relative to the coordinate system's origin. Since different shapes are defined differently, some centered, some corner-based, aligning them explicitly is often the easiest way to place them where you want.
+
+For example, a `Circle(radius: 10)` is centered at the origin by default, but a `Rectangle([20, 10])` extends from the origin toward the top right. Using alignment helps you standardize and simplify placement:
+
+```swift
+Rectangle([20, 10])
+    .aligned(at: .centerX, .bottom)
+```
+
+This centers the rectangle along the X-axis and aligns its bottom edge with Y = 0.
+
+## How `.aligned(at:)` works
+
+The `.aligned(at:)` method repositions geometry by translating it so that parts of its *bounding box* align to the coordinate system origin, based on the criteria you provide. The geometry isn't clipped, resized, or modified, just moved so it aligns as requested. You can align any geometry, including complex compositions, boolean operations, or custom components.
+
+You align along one or more axes:
+
+```swift
+Box([30, 40, 50])
+    .aligned(at: .centerX, .maxY, .bottom)
+```
+
+This centers the box in X, moves the back to Y = 0, and aligns the bottom of the Z axis to Z = 0. If you provide multiple alignments for the same axis, the last one wins.
+
+## Alignment Presets
+
+Cadova provides a set of readable alignment constants so you don't need to manually calculate anything. These include:
+
+- `.minX`, `.centerX`, `.maxX`, `.left`, `.right`
+- `.minY`, `.centerY`, `.maxY`
+- `.minZ`, `.centerZ`, `.maxZ`
+- `.top`, `.bottom` (Y axis in 2D, Z axis in 3D)
+- `.center` (all axes), `.centerXY`
+
+## Practical Examples
+
+### Center a rectangle
+
+```swift
+Rectangle([20, 10])
+    .aligned(at: .center)
+```
+
+### Align the bottom (min Y) of a circle to the origin
+
+```swift
+Circle(radius: 10)
+    .aligned(at: .bottom)
+```
+
+### Center a shape horizontally and align to the top
+
+```swift
+Rectangle([50, 20])
+    .aligned(at: .centerX, .top)
+```
+
+## Stack
+
+``Stack`` is a container that arranges its contents one after another along a given axis like `.x`, `.y`, or `.z`. It avoids overlap by using bounding boxes, and positions items relative to the origin using alignment on the *non-stacking* axes.
+
+### Basic Usage
+
+```swift
+Stack(.z, spacing: 2, alignment: .centerX) {
+    Cylinder(radius: 5, height: 1)
+    Box([10, 10, 3])
+}
+```
+
+This stacks a cylinder and a box vertically. Each item is spaced 2 mm apart, centered in X, and Y positioning is left unchanged.
+
+### Axis and Alignment
+
+- `axis` determines the direction of stacking.
+- `spacing` is `0` by default, meaning items touch edge-to-edge. Positive values add space between them.
+- `alignment` applies only to *non-stacking axes you explicitly specify*. Unspecified axes are left unchanged and the stacking axis is ignored. You can use `.center`, `.left`, `.bottom`, etc., just like with `.aligned(at:)`.

Sources/Cadova/Cadova.docc/Cadova.md

@@ -0,0 +1,38 @@
+# ``Cadova``
+
+A Swift DSL for creating precise, parametric 3D models for 3D printing.
+
+@Metadata {
+    @DisplayName("Cadova")
+}
+
+## Overview
+
+Cadova is a Swift library for constructing 3D models programmatically — with a focus on 3D printing. It builds on the ideas of OpenSCAD, but replaces its limited language with the power and elegance of Swift. Inspired by SwiftUI and designed for developers who want a better way to build models through code, Cadova is cross-platform and works on macOS, Linux, and Windows.
+
+![A 3D model created with Cadova](home-hero)
+
+## Topics
+
+### Essentials
+
+- <doc:GettingStarted>
+- <doc:WhatIsCadova>
+
+### Core Concepts
+
+- <doc:Geometry>
+- <doc:VectorsAndAngles>
+- <doc:AlignmentAndStacking>
+- <doc:Environment>
+- <doc:ModelAndProject>
+
+### Guides
+
+- <doc:WorkingWithParts>
+- <doc:Examples>
+
+### Under the Hood
+
+- <doc:Internals>
+- <doc:Troubleshooting>

Sources/Cadova/Cadova.docc/Environment.md

@@ -0,0 +1,98 @@
+# Environment
+
+Use environment values to control modeling behavior across geometry trees.
+
+## Overview
+
+Cadova's ``EnvironmentValues`` system provides a clean, declarative way to control modeling behavior across entire geometry trees, much like SwiftUI. This allows settings like resolution, tolerance, and material to apply consistently and implicitly, reducing the need for repetitive parameters in your modeling code. Environment values wrap around geometry and propagate through the tree unless explicitly overridden.
+
+Cadova has several built-in environment settings. For example, segmentation controls the number of straight segments used for curved surfaces like circles and curves. Other settings include the fill rule for polygons, the miter limit for offsets, and the maximum twist rate for sweeps, among others.
+
+## What Is the Environment For?
+
+The environment injects shared configuration into a subtree of your geometry. It flows down the tree — or rather *wraps around* the geometry it's attached to. Any geometry inside will receive those values, unless they're overridden further in.
+
+```swift
+Sphere(radius: 3)
+    .adding {
+        Cylinder(diameter: 2, height: 1)
+    }
+    .withSegmentation(minAngle: 1°, minSize: 0.5)
+    .adding {
+        Circle(radius: 2).revolved()
+    }
+```
+
+In this example, the segmentation settings apply to the sphere and the cylinder, but not the circle — because the `.withSegmentation(...)` is only applied to the subtree above it.
+
+This system makes it easy to apply shared settings without passing explicit parameters to every single node.
+
+## Reading Environment Values
+
+There are two primary ways to read values from the environment:
+
+### Using `.readingEnvironment(...)`
+
+This modifier reads a value from the environment and passes it into a closure:
+
+```swift
+Box(2)
+    .readingEnvironment(\.tolerance) { box, tolerance in
+        box.resized(x: 1 + tolerance)
+    }
+    // ...
+    .withTolerance(0.5)
+```
+
+Use this when you want to adjust an existing geometry based on the environment context.
+
+### Using the `@Environment` Property Wrapper
+
+If you're defining your own ``Shape2D`` or ``Shape3D``, you can use the `@Environment` property wrapper to access values directly:
+
+```swift
+struct MyShape: Shape3D {
+    @Environment(\.tolerance) var tolerance
+
+    var body: any Geometry3D {
+        Box(x: 10.0 + tolerance, y: 12.0 + tolerance, z: 4)
+    }
+}
+
+await Model("shape") {
+    MyShape()
+        .withTolerance(0.3)
+}
+```
+
+This works much like SwiftUI's `@Environment` and is ideal for defining reusable parametric shapes that adapt to configuration. You can also use it inside geometry builders:
+
+```swift
+Box(10)
+    .aligned(at: .centerXY)
+    .subtracting {
+        @Environment(\.tolerance) var tolerance
+        Cylinder(diameter: 5.0 + tolerance, height: 10)
+    }
+```
+
+## Custom Values
+
+You can define your own environment values. This is useful for advanced users and custom geometry behavior.
+
+```swift
+extension EnvironmentValues {
+    private static let key = Key("MyName.MyCustomValue")
+
+    var myCustomValue: Double? {
+        get { self[Self.key] as? Double }
+        set { self[Self.key] = newValue }
+    }
+}
+
+extension Geometry {
+    func withMyCustomValue(_ value: Double) -> D.Geometry {
+        withEnvironment { $0.myCustomValue = value }
+    }
+}
+```

Sources/Cadova/Cadova.docc/Examples.md

@@ -0,0 +1,132 @@
+# Examples
+
+A collection of example models demonstrating Cadova's features.
+
+## Chamfer
+
+![A chamfered shape created from two circles](example-chamfer)
+
+```swift
+await Model("chamfer") {
+    Circle(diameter: 12)
+        .clonedAt(x: 8)
+        .rounded(insideRadius: 2)
+        .extruded(height: 7, topEdge: .chamfer(depth: 2))
+}
+```
+
+## Colors and materials
+
+![Three shapes with different colors and materials](example-colors-materials)
+
+```swift
+await Model("stack-materials") {
+    Stack(.x, spacing: 2, alignment: .center, .bottom) {
+        Sphere(diameter: 10)
+            .colored(.darkOrange)
+        Cylinder(diameter: 8, height: 12)
+            .withMaterial(.glossyPlastic(.mediumSeaGreen))
+        Box(x: 12, y: 8, z: 15)
+            .withMaterial(.steel)
+    }
+}
+```
+
+## Swept text
+
+![Text swept along a bezier curve](example-swept-text)
+
+```swift
+await Model("swept-text") {
+    Text("Cadova")
+        .withFont("Futura", style: "Condensed Medium", size: 10)
+        .wrappedAroundCircle(spanning: 230°..<310°)
+        .aligned(at: .centerX, .bottom)
+        .swept(along: BezierPath {
+            curve(
+                controlX: 20, controlY: 10, controlZ: 3,
+                endX: 20, endY: 30, endZ: 12
+            )
+        })
+}
+```
+
+## Loft
+
+![A lofted shape transitioning between profiles](example-loft)
+
+```swift
+await Model("loft") {
+    Loft(interpolation: .easeInOut) {
+        layer(z: 0) {
+            Ring(outerDiameter: 20, innerDiameter: 12)
+        }
+        layer(z: 30) {
+            Rectangle(x: 25, y: 6)
+                .aligned(at: .center)
+                .cloned { $0.rotated(90°) }
+                .subtracting {
+                    RegularPolygon(sideCount: 8, circumradius: 2)
+                }
+        }
+        layer(z: 35) {
+            Ring(outerDiameter: 12, innerDiameter: 10)
+        }
+    }
+}
+```
+
+## Circular overhang
+
+![Overhang-safe circles for FDM printing](example-circular-overhang)
+
+```swift
+await Model("circular-overhang") {
+    Stack(.x, spacing: 5) {
+        Box(20)
+            .aligned(at: .centerXY)
+            .subtracting {
+                Cylinder(diameter: 10, height: 20)
+                    .overhangSafe(.teardrop)
+            }
+            .rotated(x: -90°)
+
+        Circle(diameter: 20)
+            .overhangSafe(.bridge)
+            .extruded(height: 20)
+            .rotated(x: -90°)
+    }
+    .aligned(at: .minZ)
+}
+```
+
+Using `overhangSafe(_:)` makes a circle or cylinder extend its shape to work better with FDM 3D printing. The shapes are extended in the right direction automatically, using the geometry's world transform, pointing downward for additive geometry and upward for subtractive geometry (holes).
+
+## Table
+
+![A table with lofted legs](example-table)
+
+```swift
+await Model("table") {
+    let height = 7.0
+    let footDiameter = 2.0
+    let footHeight = 2.0
+    let legDiameter = 1.0
+    let topThickness = 1.0
+    let size = Vector2D(5, 7)
+
+    Loft(interpolation: .smootherstep) {
+        layer(z: 0) { Circle(diameter: footDiameter) }
+        layer(z: footHeight) { Circle(diameter: legDiameter) }
+        layer(z: height) { Circle(diameter: legDiameter) }
+    }
+    .translated(size / 2, z: 0)
+    .symmetry(over: .xy)
+    .sliced(atZ: height - 1e-6) { base, slice in
+        base
+        slice.extruded(height: topThickness)
+            .convexHull()
+            .translated(z: height)
+    }
+}
+```