@ahrowe/ui 0.25.2 → 0.27.0

package/docs/FloorPlan.md

@@ -0,0 +1,252 @@
+# FloorPlan
+
+**When to use:** The shared data model behind `RoomDrawer` and `RoomViewer`. Reach for it directly when you need to build, inspect, validate or persist a floor plan in code rather than by drawing one — seeding a plan from a database, computing room areas, or generating a layout programmatically.
+
+**Keywords:** blueprint, cad, grundriss, apartment, building, storey, partition, area calculation, planar graph, half-edge, extrusion
+
+**Import:** `import { emptyFloorPlan, addWall, derivePlan } from '@ahrowe/ui'`
+**Types:** `import type { FloorPlan, PlanFloor, PlanNode, PlanWall, PlanOpening, PlanRoom, DerivedRoom, PlanPoint, PlanView, PlanSelection } from '@ahrowe/ui'`
+
+`PlanPoint`, `PlanView` and `PlanSelection` are the ones that also appear in `RoomDrawer` and `RoomViewer` props. Every exported function's own option and result types come with it — `WallAttrs`, `SplitWallResult`, `WallPathResult` and the rest.
+
+## The model in one paragraph
+
+A plan is a **planar wall graph**. `PlanNode`s are junctions, `PlanWall`s are the edges between them, and a wall is **shared**: where two rooms meet there is one wall, not one per room. Rooms are not stored as shapes at all — they are the enclosed faces the walls happen to form, recomputed by `derivePlan`, with a `PlanRoom` carrying only the name and colour. A `PlanOpening` (door, window, archway, gap) belongs to a **wall**, so a door between two rooms is cut once and both rooms open through it.
+
+**Every length is in millimetres.** Coordinates, wall thickness, storey height, opening offsets and widths. There is deliberately no per-plan scale factor: it would have to be threaded through every function, and one missed call site is a silent 1000x error. `unitSystem` affects display formatting only and is never read by geometry.
+
+```tsx
+import { emptyFloorPlan, addRect, addOpening, derivePlan, OpeningKind } from '@ahrowe/ui';
+
+const plan = emptyFloorPlan({ floorLabel: 'Ground floor' });
+let floor = plan.floors[0];
+
+// Two rooms flush against each other. The shared edge becomes ONE wall.
+floor = addRect(floor, { x: 0, y: 0 }, { x: 3000, y: 3000 }).floor;
+floor = addRect(floor, { x: 3000, y: 0 }, { x: 7000, y: 3000 }).floor;
+Object.keys(floor.walls).length; // 7, not 8
+
+// Rooms are derived, not drawn.
+const { rooms } = derivePlan(floor);
+rooms.length;            // 2
+rooms[0].area;           // mm², holes already subtracted
+rooms[0].outer;          // the polygon, for rendering
+```
+
+## Enums
+
+- `WallType`: `Exterior` | `Interior` | `Partition` | `Virtual` (a room divider with no physical wall: it still closes a face, but extrudes to nothing in 3D)
+- `OpeningKind`: `Door` | `Window` | `Archway` | `Gap`
+- `DoorSwing`: `None` | `StartLeft` | `StartRight` | `EndLeft` | `EndRight` | `Double` | `Sliding`
+- `PlanUnitSystem`: `Metric` | `Imperial` (display only)
+- `PlanIssueKind`: what `validatePlan` reports
+
+## Building a plan
+
+Every operation is pure and returns `PlanEdit<T>` = `{ floor, result, issues }`, so results drop straight into React state.
+
+| Function | Purpose |
+|----------|---------|
+| `addWall(floor, a, b, attrs?, tol?)` | Adds a wall, **splitting anything it crosses** so the graph stays planar |
+| `addRect(floor, corner, opposite, attrs?, tol?)` | Four walls at once, welding onto anything already there |
+| `splitWall(floor, wallId, at)` | Cuts a wall at a point or 0..1 parameter; redistributes its openings |
+| `mergeNodes(floor, keepId, removeId)` | Welds two nodes, deduplicating the walls that collapse together |
+| `dissolveNode(floor, nodeId)` | Rejoins two collinear same-construction walls; the inverse of `splitWall` |
+| `detachWall(floor, wallId, delta)` | Pulls a wall off its shared corners and moves it by `delta`, bridging each old corner to the new one |
+| `weldShortWalls(floor)` | Collapses every wall shorter than `MIN_WALL_LENGTH` by merging its two ends, so a squashed wall never leaves two corners stacked on one point |
+| `removeWall(floor, wallId, opts?)` | Removes a wall, its openings, and any node left orphaned |
+| `moveNode` / `transformPlan` / `scalePlan` | Move one node, translate everything, or rescale everything |
+| `addOpening` / `updateOpening` / `removeOpening` | Openings, clamped to fit their wall |
+| `validatePlan(floor)` | Every way the graph currently breaks the planar invariant |
+| `cleanupPlan(floor)` | Removes what can safely be removed. Idempotent |
+
+**`addWall` is the one that matters.** It resolves each endpoint (reusing a nearby node, splitting a wall it lands on, or creating one), then splits every wall it crosses and cuts itself at every node it passes through. That is what makes a second rectangle drawn flush against the first share the existing edge instead of laying a duplicate on top of it.
+
+```tsx
+// Drawing across an existing wall splits both, leaving four walls and a new junction.
+floor = addWall(floor, { x: 0, y: 0 }, { x: 4000, y: 0 }).floor;
+floor = addWall(floor, { x: 2000, y: -2000 }, { x: 2000, y: 2000 }).floor;
+Object.keys(floor.walls).length; // 4
+validatePlan(floor);             // []
+```
+
+**Tolerances.** `addWall`'s `tol` is the welding distance in millimetres. Pass the value a user's pointer tolerance works out to in world units (see `resolveSnap` below); the default is exact-match only.
+
+## Deriving rooms
+
+```tsx
+const { floor: refreshed, rooms, issues } = derivePlan(floor);
+```
+
+`derivePlan` extracts the faces and attaches stored metadata. It is pure and **never creates or deletes a `PlanRoom`**, so it is safe to call on every render. Memoise it on `plan.revision`, which every mutation bumps.
+
+`commitDerivation(floor)` mints a `PlanRoom` for each face that matched nothing — call it once per committed edit, not per render.
+
+Each `DerivedRoom` carries the face (`outer`, `holes`, `area`, `perimeter`, `wallIds`), the matched `meta`, and an `anchor` guaranteed to be **inside** the polygon (an area centroid can fall outside a concave room, so it is computed, not averaged).
+
+### How a room keeps its name
+
+Identity is primarily the **set of boundary wall ids**, with the anchor point as a secondary signal and area as a tie-break. That ordering is what makes it robust:
+
+- **Reshape or drag the whole plan** — the wall set is unchanged, so it matches regardless of where the anchors ended up.
+- **Split a room** — both children share half the old boundary, so the **anchor decides**: the child containing it keeps the name, the other becomes a new room. Predictable beats plausible.
+- **Merge two rooms** — one wins on area (the larger), and **the loser is kept, not deleted**. It is reported as `PlanIssueKind.UnmatchedRoom`, and re-adding the wall restores it to the right child by itself. Call `pruneUnmatchedRooms` only when you actually want them gone.
+
+Set `anchorPinned` on a `PlanRoom` to stop `derivePlan` moving its label.
+
+### Free-standing walls
+
+A wall with a loose end does not create a room and does not break the one it sits in. The face walk goes out along it and straight back, so the room's fill, area and hit-testing are unaffected. Two consequences: the face polygon contains a zero-width slit (so it is not a *simple* polygon — run `stripSpurs` before triangulating a floor slab), and that wall's id appears **twice** in `wallIds`.
+
+## Rendering walls
+
+`buildWallPaths(floor)` returns `{ groups, caps }` for a two-pass stroke. Both passes stroke the **same** path data: the outline pass at `thickness`, the fill pass at `thickness - 2 * outlineWidth`. The visible wall outline is not drawn at all, it is what is left of the first pass after the second covers its middle.
+
+```tsx
+const { groups, caps } = buildWallPaths(floor);
+const ow = 1 * pxToWorld; // outline width, screen-constant
+
+<g fill="none" strokeLinecap="butt" strokeLinejoin="miter" strokeMiterlimit={4}>
+  {groups.map((g) => <path key={g.thickness} d={g.d} strokeWidth={g.thickness} stroke="var(--border-color)" />)}
+</g>
+<g fill="none" strokeLinecap="butt" strokeLinejoin="miter" strokeMiterlimit={4}>
+  {groups.map((g) => g.thickness - 2 * ow > 0 && (
+    <path key={g.thickness} d={g.d} strokeWidth={g.thickness - 2 * ow} stroke="var(--background-accent)" />
+  ))}
+</g>
+<g stroke="var(--border-color)" strokeWidth={ow}>
+  {caps.map((c, i) => <line key={i} x1={c.a.x} y1={c.a.y} x2={c.b.x} y2={c.b.y} />)}
+</g>
+```
+
+Rules that make this work:
+
+- **Every outline path before every fill path.** One `<g>` each, never interleaved pairs.
+- **`caps` must be drawn.** Nothing is ever drawn across a butt end, because both passes stop at the same coordinate, so opening jambs, free wall ends and thickness changes need explicit lines. Each cap says which (`reason: 'jamb' | 'freeEnd' | 'thicknessStep'`).
+- **`outlineWidth` is screen-constant**, so recompute `thickness - 2 * ow` on zoom. The path data itself never changes. Skip the fill pass entirely when it would go non-positive (zoomed far out, walls become solid lines, which is correct at that scale).
+
+- **`strokeLinejoin` and `strokeMiterlimit` must be set**, and set the same on both passes. Corners are filled by the join, not by extra geometry.
+
+Walls are emitted as chains through corners so `stroke-linejoin: miter` fills them. Where a chain has to stop, at a junction or a thickness change, most corners still need nothing: both walls' bands start at the node, so across a gap of up to 180 degrees they already reach each other. The exception is a gap **wider** than 180 degrees, which happens when every wall at a node points into the same half-plane; there the two faces diverge and leave a wedge bitten out of the node, and a small hinged subpath is emitted to mitre it. At most one gap at a node can be reflex, so there is never more than one. Different thicknesses become separate groups, since one path can carry only one stroke width.
+
+`buildWallPaths(floor, { wallIds })` builds the same paths for a subset of walls, taking node degrees from the whole floor so chains break and corners fill exactly where they do in the full drawing. That is what lets a room's boundary be highlighted by painting over the walls it is bounded by, openings and all.
+
+`wallCentrelineSpans(floor, wall)` gives the stretches that are actually wall, in millimetres from node `a`, with openings removed and overlaps merged. `openingGeometry(floor, opening)` gives the centre, direction, normal and endpoints for drawing a door leaf, swing arc or window symbol.
+
+## Addressing a plan
+
+`getFloor(plan, floorId?)` reads one floor, defaulting to the lowest. `updateFloor(plan, floorId, edit)` applies a floor-level edit and bumps `revision` for you; `setFloor` replaces one outright. `floorBounds(floor)` gives the bounding box, padded by half the thickest wall so the outer face of every wall is inside it, which is what a fit-to-view needs. `renameFloor`, `wallLength`, `floorIndex` and `DEFAULT_WALL_ATTRS` round out the small helpers.
+
+## Floors
+
+`FloorPlan.floors` is a stack of storeys, **bottom first**: index 0 is the lowest, and `elevation` rises with the index.
+
+```ts
+import { addFloor, duplicateFloor, removeFloor, moveFloor, setFloorHeight, floorBelow } from '@ahrowe/ui';
+
+const { plan: two, floor } = addFloor(plan);            // empty storey on top
+const { plan: three } = duplicateFloor(two, floor.id);  // copy of it, above it
+const below = floorBelow(three, floor.id);              // what an underlay traces
+```
+
+Every one of these re-stacks the elevations behind you, so each storey sits on the one below: insert a floor and the ones above it rise, remove one and they drop, raise a storey's height with `setFloorHeight` and everything over it lifts, and the building's own ground level stays where it was. This is also why a storey's height is not set with a plain `setFloor`, which would leave the floors above buried in it or floating over it — neither of which a 2D plan would show. Without that, a gap or an overlap only turns up in 3D, long after the edit that caused it.
+
+`duplicateFloor` regenerates **every** id and rewires every reference — walls to the copy's nodes, openings to its walls, rooms to its wall ids — so the two storeys share nothing and an edit to one cannot reach into the other. A room's `wallIds` in particular must point at the copy's own walls, or the first `derivePlan` would strand every room in it.
+
+`setFloorHeight` clamps to `MIN_FLOOR_HEIGHT` (500mm), low enough for a crawl space and high enough to stop a zero-height storey. `removeFloor` refuses to remove the last storey: a plan with nowhere to draw would need a special case in every consumer.
+
+## Saving and loading
+
+JSON is the interchange format. `planToJson` writes it; `planFromJson` reads it back, and does so defensively, because a file off a disk is untrusted and whatever comes out is rendered immediately.
+
+```ts
+import { planToJson, planFromJson } from '@ahrowe/ui';
+
+const text = planToJson(plan);                  // indented; pass { pretty: false } for one line
+const { plan: loaded, issues } = planFromJson(text);
+if (!loaded) console.error(issues);             // unreadable
+else if (issues.length) console.warn(issues);   // loaded, but repaired
+```
+
+`planFromJson` rebuilds the plan field by field rather than casting the parsed object, so no unchecked field reaches a renderer. It repairs wherever the repair is unambiguous — a numeric string becomes a number, an unknown enum value falls back, a wall with missing corners or an opening with no wall is dropped — and returns a `null` plan only when the text is not JSON, is not an object, has no `floors`, or carries a `version` other than `PLAN_FORMAT_VERSION`. A room whose walls have gone is kept rather than dropped: re-adding the wall re-matches it by name.
+
+`revision` is bumped on load, since `derivePlan` memoises on it and the repaired plan is not the one the file described.
+
+## Snapping and pointer input
+
+```tsx
+const world = clientToWorld(e.clientX, e.clientY, svg.getBoundingClientRect(), view);
+const snap = resolveSnap(world, { floor, pxToWorld: 1 / view.zoom, origin, options });
+```
+
+`clientToWorld` **only converts** — snapping is `resolveSnap`'s job alone, which is what makes "hold Alt to disable snapping" possible at all.
+
+Every tolerance in `SnapOptions` is in **screen pixels**, converted through `pxToWorld` at the point of use. A fixed world-unit tolerance covers less and less of the screen as you zoom in until it stops working.
+
+`resolveSnap` runs in two stages, because half of these are constraints rather than points. A hard snap (`Node`, `Intersection`, `Wall`) fixes both degrees of freedom, so the first match wins. A constraint (`Angle`, `Extension`, `Alignment`) removes only one: two of them intersect, one is projected onto and then slid **along** to the nearest grid position. That last detail is what lets angle lock and grid snap coexist — you get exactly 45° at a round length, rather than a point that is neither.
+
+Pass `options.enabled: []` to disable snapping entirely.
+
+## Validation
+
+```tsx
+const issues = validatePlan(floor); // O(walls²) — development and tests, not per keystroke
+```
+
+The invariant that matters: **no two walls may cross without a node at the intersection, and no node may sit on a wall's interior without that wall being split there.** Break either and the face walk silently merges two rooms into one figure-eight face with no error anywhere, which is why `UnsplitCrossing` and `UnsplitNodeOnWall` exist as explicit issue kinds. Everything built through `addWall` maintains this automatically.
+
+## Importing older plans
+
+```tsx
+import { planFromLegacySvg } from '@ahrowe/ui';
+
+// The old canvas was unitless; pick the factor that makes it millimetres.
+// A 400-unit-wide export meant to be a 12m house wants scale: 30.
+const plan = planFromLegacySvg(svgText, { scale: 30 });
+```
+
+Feeding every legacy polygon edge through `addWall` is what collapses the old duplicated walls: the second room's copy of a shared edge resolves to the same two nodes and is recognised as already walled. Room names carry across, and doors are recovered where the old swing-arc path is recognisable; anything that is not is skipped rather than guessed at.
+
+## Ready for 3D
+
+`buildPlanMesh(floor, options?)` turns a storey into triangles: wall solids with their openings cut out, and a slab under each room.
+
+```ts
+import { buildPlanMesh } from '@ahrowe/ui';
+
+const mesh = buildPlanMesh(plan.floors[0]);
+// { positions: Float32Array, normals: Float32Array, indices: Uint32Array, groups }
+
+// three.js, for example — no adapter needed
+const g = new THREE.BufferGeometry();
+g.setAttribute('position', new THREE.BufferAttribute(mesh.positions, 3));
+g.setAttribute('normal', new THREE.BufferAttribute(mesh.normals, 3));
+g.setIndex(new THREE.BufferAttribute(mesh.indices, 1));
+```
+
+There is no renderer and no dependency: plain arrays are what every engine takes, so this feeds three.js, Babylon, a glTF writer or your own rasteriser without the package having an opinion. Call it per storey and concatenate for a whole building; each floor already knows its own `elevation`.
+
+**Axes.** Plan x becomes world x, plan y becomes world **z**, and world y is up. A plan is drawn in SVG's y-down space, so that mapping is a handedness flip — faces are wound here to suit, rather than inheriting the 2D rings' winding.
+
+**Openings are cut by splitting the wall, not by subtracting solids.** Every opening is an axis-aligned rectangle in its wall's own plane, so the wall falls into at most three prisms: under the sill, over the head, and the full-height stretches between openings. Exact, and no CSG library. A window leaves its upstand and lintel behind, which is what `sill` and `head` are carried for.
+
+**Storeys stack wall to wall.** `elevation` is the *finished floor level*, so a slab hangs below it and the walls start at the slab's underside — they clothe the floor plate the way a facade does, rather than stopping at it. A wall stays exactly `floor.height` tall, one storey's walls end precisely where the next storey's begin, and the slab sits inside them instead of showing as a band between the storeys. Build the walls from the level itself and their top face ends up coplanar with the slab above, which z-fights.
+
+A wall also drops a millimetre past the slab rather than landing flush on its underside. That is not arbitrary: a wall overlaps the slab it stands over, because the slab reaches the wall centrelines and the wall straddles them, so sharing a plane would leave two downward faces fighting for the same pixels and speckle the whole underside of the building. Wall heights and floor-to-floor spacing are unaffected.
+
+`groups` marks which triangles are wall and which are floor, so the two can take different materials in one draw.
+
+| Option | Default | |
+|---|---|---|
+| `wallHeight` | the floor's `height` | For walls with no `height` of their own |
+| `includeFloorSlab` | `true` | Lay a slab under each room |
+| `slabThickness` | `200` | Millimetres, hanging below floor level |
+| `applyElevation` | `true` | Lift by the floor's own elevation, so storeys stack |
+
+**Corners are mitred.** Two walls meeting at a corner both stop at the shared node, so left square they leave a gap of half a thickness on the outside of the turn — a notch cut through the full height of the wall. Their footprints are extended to where their edges actually cross instead, which is the same join the 2D renderer makes.
+
+An end stays square where there is no single corner to mitre to: a junction of three or more walls, a change of thickness across the node, an angle acute enough to send the mitre running away, and the reveals of an opening, which are square faces in their own right. Walls overlap slightly at those joints, which is invisible on an opaque solid but would show in a cutaway or through glass, and would double-count in a volume taken straight off the triangles.
+
+These are the fields that do nothing in 2D, and that is expected rather than a gap: a plan is a horizontal cut, so a window 900mm up the wall and a door at floor level are the same hole seen from above. `sill` is the height of an opening's bottom above the floor and `head` the height of its top; the drawer edits `sill` in its selection bar so the value is captured while the plan is being drawn, rather than having to be filled in for every opening afterwards.
+
+One thing to know when you build one: `PlanFace.outer` is positively wound under the shoelace formula, which in SVG's y-down space reads as **visually clockwise**. Anything assuming counter-clockwise (slab normals, most triangulators) must flip it, and should run `stripSpurs` first so a free-standing wall's zero-width slit does not produce degenerate triangles.