@ahrowe/ui 0.25.1 → 0.26.0

package/docs/FloorPlan.md

@@ -0,0 +1,214 @@
+# 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` |
+| `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
+
+The model carries everything an extrusion needs and nothing it would have to invent: `PlanWall.thickness` / `height` / `baseHeight`, `PlanOpening.sill` / `head`, `PlanFloor.elevation` / `height`, and derived floor polygons. No 3D renderer ships today.
+
+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.

package/docs/Modal.md

@@ -52,7 +52,7 @@ const [isOpen, setIsOpen] = useState(false);
 | `closeOnEscape` | `boolean` | Close on Escape while this is the topmost modal. Default `true` |
 | `presentation` | `Presentation` | Present as a bottom sheet, always (`Sheet`) or only on a small touch screen (`Auto`). `Default`, or omitting it, is the centred dialog |
 
-**Bottom sheet:** `presentation={Presentation.Sheet}` pins the dialog to the bottom of the screen instead of centring it — full width up to 560px, rounded on its top corners only, sliding up rather than scaling in, and lifted above an open on-screen keyboard. Nothing else changes: the header stays fixed and the body scrolls, which is what a sheet needs anyway, and the backdrop, focus trap, scroll lock and Escape all behave exactly as they do centred. `Presentation.Auto` applies it only when the pointer is coarse *and* the screen is under 768px wide.
+**Bottom sheet:** `presentation={Presentation.Sheet}` pins the dialog to the bottom of the screen instead of centring it — full width up to 560px, rounded on its top corners only, sliding up rather than scaling in, and lifted above an open on-screen keyboard, shrinking to fit the space that leaves rather than running off the top of the screen. Nothing else changes: the header stays fixed and the body scrolls, which is what a sheet needs anyway, and the backdrop, focus trap, scroll lock and Escape all behave exactly as they do centred. `Presentation.Auto` applies it only when the pointer is coarse *and* the screen is under 768px wide.
 
 `Presentation.Default` means "wherever the component normally puts it", which for a Modal is centred rather than anchored to anything — so an app-wide `<ConfigProvider presentation={Presentation.Default}>` switches sheets off everywhere, this included.
 
@@ -64,7 +64,7 @@ import { Modal, Presentation } from '@ahrowe/ui';
 </Modal>
 ```
 
-A sheet-presented Modal takes 90% of the screen height rather than the 70% a menu-sized sheet uses, since it carries forms and detail views. Override either with the `--sheet-max-height` and `--sheet-safe-padding` custom properties, per instance via `style` or theme-wide via `ThemeProvider`.
+A sheet-presented Modal takes 90% of the screen height rather than the 70% a menu-sized sheet uses, since it carries forms and detail views. Override either with the `--sheet-max-height` and `--sheet-safe-padding` custom properties, per instance via `style` or theme-wide via `ThemeProvider`. `--sheet-max-height` is a ceiling, not a height: whatever it's set to, a sheet never grows past the area actually visible, which is measured live and so accounts for an open keyboard that no viewport unit can see.
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Modal: { presentation: Presentation.Auto } }}` — which also covers `DatePicker`, `TimeInput` and `KlipyPicker` when they open in a Modal via their own `isModal`. `presentation={Presentation.Auto}` on the provider itself sets every sheet-capable component at once. See [ConfigProvider.md](ConfigProvider.md).
 

package/docs/Popover.md

@@ -61,7 +61,7 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 
 **Slots:** `root` `trigger` `floating` `panel` `arrow` `backdrop` (`backdrop` only exists while presenting as a sheet)
 
-**Bottom sheet:** `presentation={Presentation.Sheet}` drops the anchoring and the arrow, and pins the panel to the bottom of the screen instead — full width up to 560px, behind a backdrop, scrolling internally past 70% of the viewport height, lifted above an open on-screen keyboard. Scrolling on the page behind it is locked while it's open, and tapping the backdrop closes it without pressing whatever sits behind it (`closeOnOutsideClick={false}` leaves the backdrop inert but still blocking). `Presentation.Auto` applies that only when the pointer is coarse *and* the screen is under 768px wide.
+**Bottom sheet:** `presentation={Presentation.Sheet}` drops the anchoring and the arrow, and pins the panel to the bottom of the screen instead — full width up to 560px, behind a backdrop, scrolling internally past 70% of the viewport height, lifted above an open on-screen keyboard, and shrunk to fit the space that leaves rather than running off the top of the screen. Scrolling on the page behind it is locked while it's open, and tapping the backdrop closes it without pressing whatever sits behind it (`closeOnOutsideClick={false}` leaves the backdrop inert but still blocking). `Presentation.Auto` applies that only when the pointer is coarse *and* the screen is under 768px wide.
 
 Only a `Click` trigger presents as a sheet. `Hover` and `Focus` open something small next to whatever caused them, which is the opposite of a screen-owning sheet, so they stay anchored regardless of `presentation`.