houseplan-card/docs/STAIRS.md

Stairs

Stairs are plan-level navigation objects. They show the physical place and direction of an ascent on one space and can link that space to one other House Plan space. The link is deliberately one-way: adding or editing a stair never creates or changes anything on the target floor.

User contract

The Plan editor has one Stairs group with Straight and Spiral tools. Stairs are drawn like decor shapes (#676): press on the plan, drag and release. The dominant drag axis is the rise axis, the ascent points from the press to the release ("draw from the bottom up"), the sizes are the drawn extents (never below one 30 cm tread) and the angle is 0°, 90°, 180° or 270°; equal extents prefer the horizontal. A spiral stair takes the square of the drag, anchored at the press. A drag shorter than one grid cell is a click and places the default size (240 × 100 cm straight, R 90 cm spiral) at the press. The new stair stays selected and the tool remains armed; Esc during the drag discards the draft.

The selected stair shows the same frame as furniture in the decor editor, painted above wall bodies: a dashed outline, four corner and four side handles (a spiral stair has four handles on its axis tangents), a stem with the rotation handle above the local top side. Handle hit areas are finger-sized on screen at every zoom. The cursor over a handle follows the handle's world direction — ew/ns when it moves along an axis, a diagonal arrow otherwise — and the rotation handle shows the circular cursor. Drag the body to move, a handle to resize about the opposite side or corner (sizes stop at 30 cm and a pointer dragged past the anchor never mirrors the stair; Shift keeps the proportions), and the upper handle to rotate. Resizing never changes the angle. Rotation is continuous; holding Shift snaps to the nearest multiple of 45 degrees. Esc cancels an active transform or clears the selection; Delete/Backspace removes the selected stair; the ordinary Plan Undo/Redo history covers create, edit, move, resize, rotate and delete. The click a browser synthesizes after a gesture never reaches the plan tool: it places no copy under Stairs and keeps the selection under Select. Under any other plan tool the frame is not rendered at all.

Double click opens properties. A straight stair stores positive length and width; a spiral stair stores a positive radius. The fields accept 30–10000 cm (inches when Home Assistant is imperial); a field left untouched keeps the stored number bit for bit, and saving without changes writes nothing. The dialog also selects the rise direction, rotation and an optional target space. A target cannot be the current space. A missing, self or deleted target leaves the stair visible and editable but shows a repair warning and makes View activation a no-op.

In View, hovering a stair with a mouse shows the card tooltip "Go to floor