npm - @ahrowe/ui - Versions diffs - 0.25.1 → 0.26.0 - Mend

@ahrowe/ui 0.25.1 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (82) hide show

package/docs/room-drawing-analysis.md DELETED Viewed

@@ -1,337 +0,0 @@
-# RoomViewer — Deep Analysis
-This document reverse-engineers every convention in the existing SVG room data so we can build a room-drawing tool that produces fully compatible output.
----
-## 1. The Data Model
-Each floor is an object `{ id: string, label: string, data: ReactElement }`.
-`data` is a JSX SVG element. The component renders it inside a `<div>` wrapper and queries the DOM after render to attach click handlers.
-```ts
-interface FloorData {
-  id: string;
-  label: string;      // shown as the floor heading
-  data: ReactElement; // the <svg> JSX element
-}
-```
-The array can hold 1..N floors. When length > 1 the component renders chevron navigation.
----
-## 2. SVG Coordinate System
-### ViewBox
-```
-viewBox="minX minY width height"
-```
-| Floor | viewBox | x-range | y-range |
-|-------|---------|---------|---------|
-| Ground (floor 1) | `0.9 0.9 165.1 103.8` | 0.9 → 166.0 | 0.9 → 104.7 |
-| Upper (floor 2) | `22 46 167 105` | 22 → 189 | 46 → 151 |
-**Key observation**: the viewBox does NOT need to start at origin. Floor 2 starts at `(22, 46)` because the actual room coordinates in that SVG happen to begin around those values. The SVG renderer maps the viewBox onto the container's display size automatically.
-The SVG itself has no `width` or `height` attributes — it fills whatever container it is placed in (the component styles it with CSS).
-### Y-axis direction
-SVG uses a **top-left origin** with Y increasing downward (opposite to Cartesian). This affects how you think about "up" and "down" in path commands: `V 1` is near the top edge, `V 103` is near the bottom.
-### Stroke width
-All paths are rendered with `stroke-width: 1px` (set in CSS, not SVG). This means wall thickness is purely visual — the coordinate defines the centre-line of the wall.
----
-## 3. Room Definition — Two Formats
-### Format A: Group with background path
-```xml
-<g id="roomKitchen">
-  <path id="path923" d="..." />       <!-- decorative outline segment(s) -->
-  <path id="path925" d="..." />       <!-- more outline -->
-  <path id="background" d="..." />    <!-- closed filled polygon -->
-</g>
-```
-- The `<g>` gets the `id="roomXxx"` that makes it interactive.
-- The `background` path is a **closed polygon** (`Z` at end) covering the room's entire floor area. CSS sets it `fill: transparent` by default and the highlight classes colour it.
-- The other paths are partial outlines (wall segments). They do **not** need to form a closed shape together — they are supplementary wall lines for visual completeness.
-- The group can also contain `<text>` for room label rendering (floor 2 only).
-### Format B: Bare path
-```xml
-<path id="roomToilet" d="..." />
-```
-- A single `<path>` element whose `id` starts with `room`.
-- The path itself is the room outline. It is typically **open** (no `Z`) — just the visible wall segments.
-- There is no separate background path. When highlighted, the path element itself gets both the `selected` (stroke colour) and `tint` (fill) classes directly.
-- This format has no text label support.
-### Comparison
-| | Format A (group) | Format B (bare path) |
-|--|--|--|
-| Hit area | `path[id="background"]` | the path element itself |
-| Outline | multiple partial paths | single path |
-| Text label | supported (`<text>` inside `<g>`) | not supported |
-| CSS tint target | `background` child | the path itself |
-| CSS stroke target | the `<g>` and its `path` children | the path itself |
----
-## 4. The `id="background"` Convention
-Inside a Format A group, the background path:
-- Must have `id="background"` (exact string, queried with `querySelector('[id="background"]')`).
-- Must be a **closed polygon** (path ends with `Z`) covering the whole room area.
-- Is the actual clickable surface when the group is a `<g>` — CSS sets `cursor: pointer` on it.
-- Gets the tint class on selection.
-- Multiple rooms can each have their own `id="background"` child (duplicate IDs in different subtrees — technically invalid HTML but SVG renders it fine and querySelector on a parent scoped to the group returns the right one).
----
-## 5. Path Anatomy — How Rooms Are Drawn
-SVG path `d` attributes use these commands in the sample data:
-| Command | Meaning |
-|---------|---------|
-| `M x,y` | Move to absolute point — starts a new sub-path |
-| `m dx,dy` | Move to relative point |
-| `H x` | Horizontal line to absolute x |
-| `h dx` | Horizontal line by relative dx |
-| `V y` | Vertical line to absolute y |
-| `v dy` | Vertical line by relative dy |
-| `L x,y` | Line to absolute point |
-| `l dx,dy` | Line to relative point |
-| `Z` | Close path (line back to start of sub-path) |
-All rooms in the sample data use **only axis-aligned segments** (H, V) with the exception of `L` / `l` for diagonal closes on the background polygons where the start and end points aren't perfectly aligned. In practice all rooms are **rectilinear polygons** (right-angle corners only).
-### Example: roomKitchen background (Format A)
-```
-m 70.283619,51.634041    →  start at (70.28, 51.63)
-h 95.082671              →  right to (165.37, 51.63)
-l 0.0972,52.109689       →  slightly right+down to (165.46, 103.74)  ← border-align correction
-H 69.930275              →  left to (69.93, 103.74)
-Z                         →  close back to (70.28, 51.63)
-```
-This is a near-perfect rectangle at x: 70–165, y: 52–104.
-The tiny `l 0.0972,52.11` instead of a pure `V` is because the border path itself has a slight diagonal — the background traces the outer border exactly.
-### Example: roomToilet (Format B, open path)
-```
-M 41.312537,31.672271    → start at (41.31, 31.67)
-V 27.96255               → up to (41.31, 27.96)    top-left corner
-H 1.5913974              → left to (1.59, 27.96)   top-right corner (at left wall)
-V 48.100984              → down to (1.59, 48.10)   bottom-right corner
-H 41.135885              → right to (41.14, 48.10)  bottom-left corner
-v -6.53616               → up to (41.14, 41.56)    partial right wall
-```
-No `Z` — the path is open. It draws three walls (top, left outer wall, bottom) and part of the right wall, leaving the door gap open. The room outline is **not** self-contained; it shares walls with the outer border and adjacent rooms.
-### Example: roomEntryHall (Format B, staircase shape)
-```
-M 47.848693,81.841692    → (47.85, 81.84)
-V 73.715669              → up to (47.85, 73.72)
-H 25.774869              → left to (25.77, 73.72)
-V 68.698633              → up to (25.77, 68.70)   ← step in wall
-H 1.6667594              → left to (1.67, 68.70)
-l -0.07538,35.045097     → down to (1.59, 103.75)  outer bottom-left
-H 48.201992              → right to (48.20, 103.75)
-v -9.094696              → up to (48.20, 94.65)
-```
-This L-shaped room has a **step** in its top-right corner at `(25.77, 73.72)→(25.77, 68.70)` — a 5-unit indentation where the wall jogs inward. This is the staircase landing or hallway notch.
-### The `nope` path
-```
-id="nope" — NOT prefixed with "room", therefore not interactive
-M 47.848693,73.715669
-H 25.774869
-V 57.331599              → up to y=57.33
-68.698633                → implicit V 68.70 (continuation) — BACK DOWN to y=68.70
-H 1.6667594              → left
-L 1.5913794,48.100984    → up
-H 47.848679              → right
-Z
-```
-This is the hallway/corridor space between Toilet, Office, and EntryHall. It is drawn but not selectable. The double V value (`V 57.33 68.70`) creates a zigzag that draws the staircase step outline that is shared with the EntryHall.
----
-## 6. Wall Sharing
-Rooms do **not** each define their complete closed boundary. They only draw the wall segments that are their "own" walls — the walls they share with other rooms or the outer border are not repeated.
-Examples from floor 1:
-- The left outer wall (`x ≈ 1.59`) is drawn by the `border` path, not by individual rooms.
-- The wall at `x ≈ 70` separating Toilet/Office/EntryHall from Kitchen/Livingroom is partially drawn by each room on that side.
-- The horizontal wall at `y ≈ 27.96` separating Toilet and Office is drawn by both their paths, but only the outer edge is stroked.
-This means the SVG viewer relies on **overlapping strokes** to form complete wall appearances — you don't get gaps because each side draws at least one stroke along the shared wall.
-**Implication for a drawing tool**: rooms should be stored as complete closed polygons internally, and at render time the tool can either:
-1. Render each room as a complete closed shape (simpler), or
-2. Compute shared edges and only render each wall segment once (more authentic to the existing format, matches the component's CSS expectations).
----
-## 7. The `<use>` Highlight Mechanism
-Every SVG must contain exactly one `<use id="use" href="">` element, placed **after** all room elements (so it renders on top in SVG painter's order):
-```xml
-<use id="use" href="" />
-```
-When a room is clicked, `onRoomClicked` does:
-```js
-use.setAttribute('href', `#${roomId}`);
-```
-This makes `<use>` render a visual copy of the selected room's element at the same position. Because `<use>` is last in the DOM, its copy renders on top of everything else.
-The `<use>` element inherits the CSS classes of the element it references (via SVG shadow DOM), so the green stroke/tint applied to the original group also shows on the `<use>` copy. The effect is a highlighted outline drawn over all other overlapping paths — this is why the selection visually "pops" even when rooms share wall lines.
-**Critical**: without `<use id="use">` in the SVG the component will throw when trying to `setAttribute` on `undefined`.
----
-## 8. CSS Highlight Classes
-The component applies classes from the CSS module to DOM elements directly via `classList`. Three classes are involved:
-### `.roomViewerSelected`
-Applied to: the room's top element (`<g>` or `<path>`)
-Effect:
-```css
-stroke: #18f810 !important;   /* green stroke on the group/path */
-path { stroke: #18f810 !important; fill: none !important; }
-path[id="background"] { stroke: none !important; fill: #20f81013 !important; }
-```
-### `.roomViewerTint`
-Applied to: the `path[id="background"]` child, or the room element itself if no background exists
-Effect:
-```css
-fill: #20f81013 !important;   /* translucent green fill */
-path { fill: #20f81013 !important; }
-text { stroke: none; fill: none; }  /* hide text when tinted */
-```
-### Deselection
-Both classes are removed from the previously selected room before applying to the new one. The `<use href>` is updated too.
-### Note on `.roomViewerActive`
-The CSS defines an `-active` class with identical styling to `-selected` but it is **never set by the component code**. It appears to be dead CSS, possibly from an older version.
----
-## 9. Non-Interactive Elements
-These elements appear in the SVG but are deliberately not rooms:
-| `id` | Role |
-|------|------|
-| `border` | outer building outline — pure decoration |
-| `layer1` | top-level `<g>` grouping all content |
-| `background` | fill area inside a Format A room — selectable but not a room itself |
-| `nope` | corridor/void area explicitly excluded from interaction |
-| `path923`, `path925`, etc. | decorative wall segments inside Format A groups |
-| `use` | the highlight overlay — must exist but is not a room |
-The selector `[id^="room"]` in both the JavaScript (`querySelectorAll`) and CSS (`*[id^="room"]`) correctly targets only room elements.
----
-## 10. Transform Attribute
-Floor 1's `roomLivingroom` has:
-```xml
-<g id="roomLivingroom" transform="translate(-0.41843424,-0.03740732)">
-```
-This tiny sub-pixel shift aligns the Livingroom paths with the outer border precisely (the border has very slight diagonal lines rather than perfect axis-aligned coordinates). The drawing tool should either:
-- Support a `transform` per room for micro-alignment corrections, or
-- Guarantee perfectly aligned coordinates so no correction is needed.
----
-## 11. Summary: What a Drawing Tool Needs to Produce
-To produce SVG data compatible with RoomViewer, every exported SVG must satisfy these rules:
-### Required structure
-```xml
-<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="minX minY width height">
-  <g id="layer1">
-    <!-- outer border (optional but conventional) -->
-    <path id="border" d="..." />
-    <!-- zero or more room elements -->
-    <g id="roomXxx">                      <!-- Format A -->
-      <path d="..." />                    <!-- wall segment(s) -->
-      <path id="background" d="..." />    <!-- closed polygon, must end with Z -->
-      <text ...>Label</text>              <!-- optional -->
-    </g>
-    <path id="roomYyy" d="..." />         <!-- Format B, for simple rooms -->
-  </g>
-  <use id="use" href="" />                <!-- REQUIRED, must be last -->
-</svg>
-```
-### Room ID convention
-- Must start with `room` (case-sensitive)
-- Remainder is the "pure room ID" — stored in state without the `room` prefix
-- Examples: `roomLivingroom`, `roomBath`, `roomBedroomOne`
-### Background path rules
-- Must be a **closed polygon** — path `d` must end with `Z`
-- Must have exactly `id="background"` (the querySelector targets this exact string)
-- Should cover the entire floor area of the room
-- For rectilinear rooms: trace all four (or more) corners and close
-### `<use>` element rules
-- Must have `id="use"`
-- Must be the last element in the SVG (so it renders on top)
-- `href=""` initially empty
-### Coordinate system for a drawing tool
-- Use a fixed grid (e.g. 200×150 units) as the design canvas
-- Store rooms as arrays of `{x, y}` corner points (all axis-aligned → only right-angle corners)
-- Generate path `d` for wall outlines: open path tracing the room's perimeter segments
-- Generate path `d` for background: closed polygon — `M x0,y0 H x1 V y1 H x0 Z` (for a rectangle)
-- viewBox should be computed from the bounding box of all content with a small margin
-- Keep coordinates as floating-point with 2–6 decimal places (the existing SVGs use 6)
-### Data format to emit
-```ts
-{
-  id: string,        // e.g. 'floorOne'
-  label: string,     // e.g. 'First floor'
-  data: ReactElement // the <svg> JSX
-}
-```
-The drawing tool should render rooms as JSX (using `React.createElement` or a JSX template string evaluated at export time).