@ahrowe/ui 0.25.2 → 0.26.0

package/dist/types/package/common/floorPlan/floorPlan.snap.d.ts

@@ -0,0 +1,101 @@
+import { PlanFloor, PlanPoint } from './floorPlan.types';
+export declare enum SnapKind {
+    None = "none",
+    Node = "node",
+    /** A point projected onto a wall's centreline. */
+    Wall = "wall",
+    /** The crossing of two walls, or of a wall with the active angle ray. */
+    Intersection = "intersection",
+    /** On the infinite line continuing an existing wall. */
+    Extension = "extension",
+    /** Shares an x or y coordinate with an existing node. */
+    Alignment = "alignment",
+    /** On a ray at a multiple of `angleStepDeg` from `origin`. */
+    Angle = "angle",
+    Grid = "grid"
+}
+export interface SnapGuide {
+    kind: SnapKind;
+    a: PlanPoint;
+    b: PlanPoint;
+    /** Render as an unbounded construction line rather than a segment. */
+    infinite?: boolean;
+}
+export interface SnapOptions {
+    /** Which snaps are active. Pass `[]` (Alt held) to disable snapping entirely. */
+    enabled: SnapKind[];
+    /** Millimetres. 0 disables grid snap. */
+    gridSize: number;
+    /** Degrees. 45 gives 0/45/90. 0 disables angle lock. */
+    angleStepDeg: number;
+    toleranceScreenPx: number;
+    /** Nodes are the most valuable snap, so they get a little more room. */
+    nodeToleranceScreenPx?: number;
+}
+export declare const DEFAULT_SNAP_OPTIONS: SnapOptions;
+export interface SnapContext {
+    floor: PlanFloor;
+    /** World units per screen pixel at the current zoom. See `screenScale`. */
+    pxToWorld: number;
+    /** The anchored point. Required for angle lock; also enables the length readout. */
+    origin?: PlanPoint;
+    /**
+     * A direction in radians that angle lock measures from, in ADDITION to the world axes.
+     *
+     * Pass the direction of the wall being continued and the lock offers perpendicular and
+     * parallel to that wall, not just to the world. Without it, angle lock is only useful
+     * on a building that happens to be aligned to the page.
+     */
+    referenceAngle?: number;
+    excludeWallIds?: ReadonlySet<string>;
+    excludeNodeIds?: ReadonlySet<string>;
+    options?: Partial<SnapOptions>;
+}
+export interface SnapResult {
+    point: PlanPoint;
+    kind: SnapKind;
+    nodeId?: string;
+    wallId?: string;
+    /** Parameter along `wallId`, for `SnapKind.Wall`. */
+    t?: number;
+    /** Everything an overlay needs to draw to explain the snap. */
+    guides: SnapGuide[];
+    /** Radians from `origin` to `point`, when an origin was given. */
+    angle?: number;
+    /** Distance from `origin` to `point`, when an origin was given. */
+    distance?: number;
+    /**
+     * Set when angle lock produced the result, saying what it locked against: the world
+     * axes, or the reference direction that was passed in.
+     */
+    angleRelativeTo?: 'world' | 'reference';
+}
+/** World units per screen pixel, from the element's current transform. */
+export declare function screenScale(svg: SVGSVGElement): number;
+/**
+ * Client (screen) coordinates to world coordinates. Pure conversion, no snapping.
+ *
+ * Uses `getBoundingClientRect` arithmetic against an explicit viewport rather than
+ * `getScreenCTM`, which returns `null` in jsdom and so makes anything built on it
+ * untestable.
+ */
+export declare function clientToWorld(clientX: number, clientY: number, rect: {
+    left: number;
+    top: number;
+}, view: {
+    x: number;
+    y: number;
+    zoom: number;
+}): PlanPoint;
+/**
+ * Resolves a raw pointer position to the point the user meant.
+ *
+ * Two stages, because half of these snaps are constraints rather than points. A hard
+ * snap (node, intersection, wall) fixes both degrees of freedom, so the first match
+ * wins. A constraint (angle lock, extension, alignment) removes only one, so a flat
+ * "first match wins" list would kick the point off the angle ray the moment an
+ * alignment also matched. Two constraints intersect; one constraint is projected onto
+ * and then slid ALONG to the nearest grid position, which is what lets angle lock and
+ * grid coexist instead of fighting.
+ */
+export declare function resolveSnap(raw: PlanPoint, ctx: SnapContext): SnapResult;

package/dist/types/package/common/floorPlan/floorPlan.types.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Floor plan model: a planar wall graph whose rooms are derived, not stored.
+ *
+ * Nodes and walls are first-class and shared, so the wall between two rooms is one
+ * wall. An opening therefore cuts it exactly once, which is what the previous
+ * room-polygon model could not express.
+ *
+ * GEOMETRY INVARIANT: every coordinate, length, thickness, offset and height in this
+ * module is in MILLIMETRES. There is deliberately no per-plan scale factor: one would
+ * have to be threaded through every geometry function, and a single missed call site
+ * is a silent 1000x error that no type can catch. `unitSystem` below drives display
+ * formatting only and is never read by geometry.
+ */
+/** A point in plan space, in millimetres. y increases downwards, as in SVG. */
+export interface PlanPoint {
+    x: number;
+    y: number;
+}
+export declare enum PlanUnitSystem {
+    /** Display as m / cm / mm. */
+    Metric = "metric",
+    /** Display as feet and inches. Storage stays millimetres. */
+    Imperial = "imperial"
+}
+export declare enum WallType {
+    /** Load-bearing envelope wall. */
+    Exterior = "exterior",
+    /** Load-bearing interior wall. */
+    Interior = "interior",
+    /** Non-load-bearing partition. */
+    Partition = "partition",
+    /**
+     * A room boundary with no physical wall, for dividing open-plan space. It still
+     * closes a face, so it produces two rooms, but renders as a thin dashed line and
+     * extrudes to nothing in 3D.
+     */
+    Virtual = "virtual"
+}
+export declare enum OpeningKind {
+    /** A real door leaf, with a swing and a threshold. */
+    Door = "door",
+    /** Glazed opening with a sill above floor level. */
+    Window = "window",
+    /** Structural opening with a head but no leaf. */
+    Archway = "archway",
+    /**
+     * A plain hole in the wall with no jamb detailing. Distinct from "no wall at all":
+     * a Gap is a marked span of a wall that exists, which is what lets a gap-style
+     * rendering stay unambiguous.
+     */
+    Gap = "gap"
+}
+export declare enum DoorSwing {
+    None = "none",
+    /** Hinged at the opening's start, opening towards the wall's left normal. */
+    StartLeft = "startLeft",
+    StartRight = "startRight",
+    EndLeft = "endLeft",
+    EndRight = "endRight",
+    /** Two leaves, hinged at both ends. */
+    Double = "double",
+    Sliding = "sliding"
+}
+/** A graph vertex. Structurally assignable to `PlanPoint`. */
+export interface PlanNode {
+    id: string;
+    x: number;
+    y: number;
+}
+/**
+ * An undirected edge between two nodes. `a` and `b` define the wall's own direction,
+ * which is what opening offsets and door swings are measured against.
+ *
+ * The wall is centred on the segment a..b, extending `thickness / 2` to each side.
+ * There is no eccentric offset in this version.
+ */
+export interface PlanWall {
+    id: string;
+    a: string;
+    b: string;
+    /** Millimetres. Must be greater than 0. */
+    thickness: number;
+    /** Millimetres above this wall's base. Omit to inherit `PlanFloor.height`. */
+    height?: number;
+    /** Millimetres above the floor's finished level. Defaults to 0. */
+    baseHeight?: number;
+    type: WallType;
+}
+/**
+ * An opening cut into exactly one wall. Because a shared wall is one wall, an opening
+ * between two rooms exists exactly once and needs no de-duplication anywhere.
+ */
+export interface PlanOpening {
+    id: string;
+    wallId: string;
+    kind: OpeningKind;
+    /**
+     * Distance in millimetres from the wall's node `a` to the opening's CENTRE, measured
+     * along the centreline.
+     *
+     * Deliberately absolute rather than a 0..1 parameter: with a parameter, stretching a
+     * wall by dragging one of its nodes would rescale every door on it. Absolute offsets
+     * are clamped instead when a wall shortens.
+     */
+    offset: number;
+    /** Millimetres, along the wall. */
+    width: number;
+    /**
+     * Height of the opening's BOTTOM above the floor, in millimetres: 0 for a door, around
+     * 900 for a window. Nothing in the 2D plan reads it, since a plan is a horizontal cut
+     * and every opening looks the same from above. It is here so the same plan can drive a
+     * 3D view later without the heights having to be invented or asked for again.
+     */
+    sill: number;
+    /** Height of the opening's TOP above the floor, in millimetres. Typically 2100. */
+    head: number;
+    /** Only meaningful for `OpeningKind.Door`. */
+    swing?: DoorSwing;
+}
+/**
+ * Room METADATA. This is not a geometric object: the polygon comes from face
+ * extraction. The trailing `wallIds` / `area` fields are a match cache maintained by
+ * `derivePlan`, and are the reason a room's name survives edits.
+ */
+export interface PlanRoom {
+    id: string;
+    name: string;
+    /** Any CSS colour. Omit to use the theme default. */
+    colour?: string;
+    /** Free-form usage tag ("kitchen", "bath"), for later fixture and 3D defaults. */
+    usage?: string;
+    /**
+     * A point that lay inside the room's polygon when it was last written. Used as the
+     * label position and as the secondary identity signal during matching.
+     */
+    anchor: PlanPoint;
+    /** Set once the user drags the label; `derivePlan` then stops moving it. */
+    anchorPinned: boolean;
+    /** Monotonic creation counter, used as a deterministic tie-break when matching. */
+    seq: number;
+    /** Match cache: the wall ids on this room's boundary at the last successful match. */
+    wallIds: string[];
+    /** Match cache: area in mm² at the last successful match. */
+    area: number;
+}
+export interface PlanFloor {
+    id: string;
+    label: string;
+    /** Finished floor level of this storey, millimetres above datum. */
+    elevation: number;
+    /** Default storey height in millimetres, used when a wall omits its own `height`. */
+    height: number;
+    /**
+     * Keyed by id for O(1) lookup. Ids must not be numeric strings ('n_12', never '12'),
+     * so that JavaScript preserves insertion order and iteration stays reproducible.
+     */
+    nodes: Record<string, PlanNode>;
+    walls: Record<string, PlanWall>;
+    openings: Record<string, PlanOpening>;
+    rooms: Record<string, PlanRoom>;
+}
+export interface FloorPlan {
+    id: string;
+    name?: string;
+    /** Schema version, for future migrations. */
+    version: 1;
+    /** Display formatting only. Never read by geometry. */
+    unitSystem: PlanUnitSystem;
+    floors: PlanFloor[];
+    /**
+     * Bumped by every mutating operation. Use it as the memo key for `derivePlan`, so a
+     * gesture that does not actually change the graph does not trigger a re-derive.
+     */
+    revision: number;
+}
+/**
+ * A raw face from the planar walk, before room metadata is attached.
+ *
+ * WINDING: `outer` is positively wound under the shoelace formula, which in SVG's
+ * y-down space means it reads as visually CLOCKWISE. Anything downstream that assumes
+ * counter-clockwise (extruded slab normals, most triangulators) must flip it.
+ */
+export interface PlanFace {
+    /**
+     * Derived from the boundary itself, so it is stable across derives for as long as
+     * the geometry is unchanged. Safe to use as a React key.
+     */
+    id: string;
+    /** Outer ring, closed implicitly: the first vertex is not repeated at the end. */
+    outer: PlanPoint[];
+    /** Inner rings from nested components, wound opposite to `outer`. */
+    holes: PlanPoint[][];
+    /** mm², always positive, with holes already subtracted. */
+    area: number;
+    /** mm, outer ring only. */
+    perimeter: number;
+    /**
+     * Wall ids on the boundary, in traversal order. A dangling wall inside this face
+     * appears TWICE, once per direction, so consumers needing unique ids must dedupe.
+     */
+    wallIds: string[];
+    nodeIds: string[];
+}
+/** A face with its matched metadata. This is what the components render. */
+export interface DerivedRoom extends PlanFace {
+    /** `null` when no `PlanRoom` matched this face during this derive. */
+    roomId: string | null;
+    meta: PlanRoom | null;
+    /** Guaranteed inside `outer` and outside every hole. The label position. */
+    anchor: PlanPoint;
+}
+export declare enum PlanIssueKind {
+    ZeroLengthWall = "zeroLengthWall",
+    SelfLoopWall = "selfLoopWall",
+    DuplicateWall = "duplicateWall",
+    CoincidentNodes = "coincidentNodes",
+    /** Two walls cross with no node at the intersection. Corrupts face extraction. */
+    UnsplitCrossing = "unsplitCrossing",
+    /** A node sits on a wall's interior but that wall was never split there. */
+    UnsplitNodeOnWall = "unsplitNodeOnWall",
+    /** Two walls leave a node in the same direction, tying the angular sort. */
+    OverlappingWalls = "overlappingWalls",
+    OrphanNode = "orphanNode",
+    DanglingOpening = "danglingOpening",
+    /** A `PlanRoom` matched no face this derive. It is kept, never deleted. */
+    UnmatchedRoom = "unmatchedRoom",
+    /** An opening was moved or dropped because its wall no longer has room for it. */
+    OpeningDropped = "openingDropped"
+}
+export interface PlanIssue {
+    kind: PlanIssueKind;
+    message: string;
+    nodeIds?: string[];
+    wallIds?: string[];
+    roomIds?: string[];
+    openingIds?: string[];
+}
+export interface PlanDerivation {
+    /** The floor with room match caches and anchors refreshed. Pure: a new object. */
+    floor: PlanFloor;
+    rooms: DerivedRoom[];
+    issues: PlanIssue[];
+}
+/** The uniform result of every graph mutation. All of them are pure. */
+export interface PlanEdit<T = void> {
+    floor: PlanFloor;
+    result: T;
+    issues: PlanIssue[];
+}
+/**
+ * The viewport: which world point sits at the canvas's top-left corner, and how many
+ * screen pixels one world millimetre occupies.
+ *
+ * A 6m plan filling a 600px canvas is `zoom: 0.1`. Note this is a transform on a group,
+ * not an SVG `viewBox`: handles, labels and hit tolerances are then sized in screen
+ * pixels and stay constant as you zoom, instead of scaling with the drawing.
+ */
+export interface PlanView {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/** What is currently selected or hovered. */
+export type PlanSelection = {
+    type: 'room';
+    id: string;
+} | {
+    type: 'wall';
+    id: string;
+} | {
+    type: 'opening';
+    id: string;
+} | {
+    type: 'node';
+    id: string;
+};

package/dist/types/package/common/floorPlan/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public surface of the floor plan model.
+ *
+ * Explicit named exports, NOT `export *`: `scripts/gen-barrel.ts` forwards this folder
+ * straight into `package/index.ts`, so anything listed here becomes part of the
+ * published `@ahrowe/ui` API. Internal primitives (`cross`, `lerp`, the dart graph)
+ * stay unexported and are imported by path within this module.
+ */
+export type { DerivedRoom, FloorPlan, PlanDerivation, PlanEdit, PlanFace, PlanFloor, PlanIssue, PlanNode, PlanOpening, PlanPoint, PlanRoom, PlanSelection, PlanView, PlanWall, } from './floorPlan.types';
+export { DoorSwing, OpeningKind, PlanIssueKind, PlanUnitSystem, WallType } from './floorPlan.types';
+export { addFloor, duplicateFloor, emptyFloor, emptyFloorPlan, floorBelow, floorBounds, floorIndex, getFloor, MIN_FLOOR_HEIGHT, moveFloor, removeFloor, renameFloor, setFloor, setFloorHeight, updateFloor, } from './floorPlan.plan';
+export type { AddFloorOptions, EmptyFloorPlanOptions, PlanBounds } from './floorPlan.plan';
+export { MIN_OPENING_WIDTH, MIN_WALL_LENGTH } from './floorPlan.geometry';
+export { deriveFaces, nodeDegrees } from './floorPlan.faces';
+export { commitDerivation, derivePlan, pruneUnmatchedRooms, roomAtPoint } from './floorPlan.rooms';
+export type { CommitDerivationOptions } from './floorPlan.rooms';
+export { HIT_PX, HIT_PX_COARSE, hitTest, selectionsEqual, worldTolerances } from './floorPlan.hit';
+export type { HitTestOptions, HitTolerances } from './floorPlan.hit';
+export { DEFAULT_WALL_ATTRS, addOpening, addRect, addWall, cleanupPlan, dissolveNode, mergeNodes, moveNode, removeOpening, removeWall, scalePlan, splitWall, transformPlan, updateOpening, validatePlan, wallLength, } from './floorPlan.graph';
+export type { DissolveNodeOptions, ResolveNodeResult, SplitWallResult, WallAttrs, } from './floorPlan.graph';
+export { DEFAULT_SNAP_OPTIONS, SnapKind, clientToWorld, resolveSnap, screenScale } from './floorPlan.snap';
+export type { SnapContext, SnapGuide, SnapOptions, SnapResult } from './floorPlan.snap';
+export { buildWallPaths, openingGeometry, wallCentrelineSpans } from './floorPlan.path';
+export type { BuildWallPathsOptions, WallCapLine, WallCapReason, WallPathGroup, WallPathResult, } from './floorPlan.path';
+export { PLAN_FORMAT_VERSION, planFromJson, planToJson } from './floorPlan.json';
+export type { PlanParseResult } from './floorPlan.json';
+export { planFromLegacySvg } from './legacySvg';
+export type { LegacyImportOptions } from './legacySvg';

package/dist/types/package/common/floorPlan/legacySvg.d.ts

@@ -0,0 +1,27 @@
+import { scalePlan } from './floorPlan.graph';
+import { FloorPlan } from './floorPlan.types';
+export interface LegacyImportOptions {
+    /**
+     * Multiplies every imported coordinate, converting the old unitless canvas into the
+     * module's millimetre invariant.
+     *
+     * There is no correct automatic value: the old format records no scale at all. The
+     * default of 1 keeps the numbers as they were, which makes a typical 400x300 export
+     * a 40cm plan. A 400-unit-wide export meant to be a 12m house wants `scale: 30`.
+     */
+    scale?: number;
+    /** Wall thickness for imported walls, in millimetres after scaling. */
+    thickness?: number;
+    /** Tolerance for welding coincident endpoints, in millimetres after scaling. */
+    weldTolerance?: number;
+    label?: string;
+}
+/**
+ * Parses a legacy exported SVG into a single-floor `FloorPlan`.
+ *
+ * Rooms keep their names. Doors are recovered where the old swing-arc path is
+ * recognisable, as `OpeningKind.Door`. Windows and archways did not exist in that
+ * format, so nothing is lost by not looking for them.
+ */
+export declare function planFromLegacySvg(svg: string, options?: LegacyImportOptions): FloorPlan;
+export { scalePlan };

package/dist/types/package/common/planCanvas/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './planCanvas';
+export * from './planCanvas.types';

package/dist/types/package/common/planCanvas/planCanvas.d.ts

@@ -0,0 +1,7 @@
+import { PlanCanvasProps } from './planCanvas.types';
+/**
+ * The ref lands on the `<svg>` itself, which is what a consumer wants for measuring or
+ * screenshotting. Both the drawer and the viewer expose it as `getSvgElement()`.
+ */
+declare const PlanCanvas: import('react').ForwardRefExoticComponent<PlanCanvasProps & import('react').RefAttributes<SVGSVGElement>>;
+export default PlanCanvas;

package/dist/types/package/common/planCanvas/planCanvas.types.d.ts

@@ -0,0 +1,62 @@
+import { CSSProperties, ReactNode } from 'react';
+import { DerivedRoom, PlanFloor, PlanRoom, PlanSelection, PlanView } from '../floorPlan';
+import { SlotClassNames, SlotStyles } from '../types/slots.types';
+export type PlanCanvasSlots = 'canvas' | 'grid' | 'underlay' | 'rooms' | 'roomFill' | 'roomLabel' | 'walls' | 'wallBody' | 'openings' | 'opening' | 'overlay';
+export interface PlanCanvasProps {
+    floor: PlanFloor;
+    /**
+     * A floor traced faintly behind this one, normally the storey below, so walls can be
+     * lined up between storeys. Drawn as wall centrelines only: it is a reference, not a
+     * second plan, and it takes no pointer events.
+     */
+    underlay?: PlanFloor | null;
+    /**
+     * Derived rooms, passed in rather than computed here so the parent controls
+     * memoisation and both components share one derivation per render.
+     */
+    rooms: DerivedRoom[];
+    view: PlanView;
+    /** Everything currently selected. A single selection is a one-element array. */
+    selection?: readonly PlanSelection[];
+    hovered?: PlanSelection | null;
+    /** Makes room fills focusable, clickable and screen-reader labelled. */
+    interactiveRooms?: boolean;
+    interactiveOpenings?: boolean;
+    showGrid?: boolean;
+    /** Grid spacing in millimetres. */
+    gridSize?: number;
+    showRoomLabels?: boolean;
+    /** Door leaves, swing arcs and window panes. `false` leaves plain gaps. */
+    showOpeningSymbols?: boolean;
+    getRoomColor?: (room: PlanRoom, area: number) => string | undefined;
+    renderRoomLabel?: (room: PlanRoom | null, context: {
+        area: number;
+        faceId: string;
+    }) => ReactNode;
+    /** Accessible name for a room. */
+    getRoomLabel?: (room: PlanRoom | null, context: {
+        area: number;
+    }) => string;
+    formatArea?: (areaMm2: number) => string;
+    onRoomActivate?: (roomId: string) => void;
+    onOpeningActivate?: (openingId: string) => void;
+    onBackgroundActivate?: () => void;
+    onHoverChange?: (target: PlanSelection | null) => void;
+    /**
+     * Extra SVG drawn above everything, in SCREEN space: handles, previews, badges.
+     * The drawer supplies its editing chrome through this.
+     */
+    overlay?: ReactNode;
+    /** Extra SVG drawn in WORLD space, below the screen-space overlay. */
+    worldOverlay?: ReactNode;
+    /** Width and height of the canvas in CSS pixels, measured by the parent. */
+    size: {
+        width: number;
+        height: number;
+    };
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<PlanCanvasSlots>;
+    styles?: SlotStyles<PlanCanvasSlots>;
+}

package/dist/types/package/common/roomDrawer/roomDrawer.d.ts

@@ -1,3 +1,3 @@
-import { ReactElement } from 'react';
-import { RoomDrawerProps } from './roomDrawer.types';
-export default function RoomDrawer({ className }: RoomDrawerProps): ReactElement;
+import { RoomDrawerHandle, RoomDrawerProps } from './roomDrawer.types';
+declare const RoomDrawer: import('react').ForwardRefExoticComponent<RoomDrawerProps & import('react').RefAttributes<RoomDrawerHandle>>;
+export default RoomDrawer;