@ahrowe/ui 0.35.0 → 0.36.0

package/dist/cjs-types/common/floorPlan/floorPlan.rooms.d.ts

@@ -0,0 +1,47 @@
+import { DerivedRoom, PlanDerivation, PlanFloor, PlanRoom } from './floorPlan.types.js';
+/** Relative weights of the three identity signals. */
+export declare const MATCH_WEIGHTS: {
+    /** Wall ids survive every geometry-only edit, so they carry the most weight. */
+    readonly boundary: 2;
+    /** Decides a split, where both children share half the old boundary. */
+    readonly anchor: 1;
+    /** Breaks a merge towards the larger of the two rooms. */
+    readonly area: 0.25;
+};
+/** Below this, a pair is not the same room at all. */
+export declare const MATCH_THRESHOLD = 0.15;
+/**
+ * Extracts faces and attaches stored room metadata to them.
+ *
+ * Pure: returns a new floor whose room match caches and anchors have been refreshed.
+ * It never creates or deletes a `PlanRoom`, so it is safe to call on every render.
+ * Minting rooms for newly enclosed faces is `commitDerivation`'s job, called once per
+ * committed edit.
+ */
+export declare function derivePlan(floor: PlanFloor): PlanDerivation;
+/** Test-only: makes the room sequence counter reproducible. */
+export declare function __resetRoomSeq(): void;
+export interface CommitDerivationOptions {
+    /** Names new rooms. Receives the 1-based index among rooms created in this call. */
+    nameFor?: (index: number, face: DerivedRoom) => string;
+}
+/**
+ * Mints a `PlanRoom` for every face that matched nothing.
+ *
+ * Separate from `derivePlan` so that derivation stays free of id minting and can run on
+ * every render without inflating the document. Call it once per committed edit.
+ */
+export declare function commitDerivation(floor: PlanFloor, options?: CommitDerivationOptions): {
+    floor: PlanFloor;
+    created: PlanRoom[];
+};
+/** Removes room metadata that matched no face. Never called automatically. */
+export declare function pruneUnmatchedRooms(floor: PlanFloor): {
+    floor: PlanFloor;
+    removed: string[];
+};
+/** Convenience: the derived room whose polygon contains `point`, if any. */
+export declare function roomAtPoint(derived: DerivedRoom[], point: {
+    x: number;
+    y: number;
+}): DerivedRoom | null;

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

@@ -0,0 +1,101 @@
+import { PlanFloor, PlanPoint } from './floorPlan.types.js';
+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/cjs-types/common/floorPlan/floorPlan.triangulate.d.ts

@@ -0,0 +1,11 @@
+import { PlanPoint } from './floorPlan.types.js';
+/**
+ * Triangulates a ring and its holes into index triples over the returned vertex list.
+ *
+ * The vertices come back as well as the indices because bridging a hole duplicates the
+ * two vertices it joins, so the caller cannot simply index into what it passed in.
+ */
+export declare function triangulate(outer: readonly PlanPoint[], holes?: readonly (readonly PlanPoint[])[]): {
+    vertices: PlanPoint[];
+    indices: number[];
+};

package/dist/cjs-types/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/cjs-types/common/floorPlan/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.js';
+export { DoorSwing, OpeningKind, PlanIssueKind, PlanUnitSystem, WallType } from './floorPlan.types.js';
+export { addFloor, duplicateFloor, emptyFloor, emptyFloorPlan, floorBelow, floorBounds, floorIndex, getFloor, MIN_FLOOR_HEIGHT, moveFloor, removeFloor, renameFloor, setFloor, setFloorHeight, updateFloor, } from './floorPlan.plan.js';
+export type { AddFloorOptions, EmptyFloorPlanOptions, PlanBounds } from './floorPlan.plan.js';
+export { MIN_OPENING_WIDTH, MIN_WALL_LENGTH } from './floorPlan.geometry.js';
+export { deriveFaces, nodeDegrees } from './floorPlan.faces.js';
+export { commitDerivation, derivePlan, pruneUnmatchedRooms, roomAtPoint } from './floorPlan.rooms.js';
+export type { CommitDerivationOptions } from './floorPlan.rooms.js';
+export { HIT_PX, HIT_PX_COARSE, hitTest, selectionsEqual, worldTolerances } from './floorPlan.hit.js';
+export type { HitTestOptions, HitTolerances } from './floorPlan.hit.js';
+export { DEFAULT_WALL_ATTRS, addOpening, addRect, addWall, cleanupPlan, detachWall, dissolveNode, mergeNodes, moveNode, removeOpening, removeWall, scalePlan, splitWall, transformPlan, updateOpening, validatePlan, wallLength, weldShortWalls, } from './floorPlan.graph.js';
+export type { DetachWallResult, DissolveNodeOptions, ResolveNodeResult, SplitWallResult, WallAttrs, } from './floorPlan.graph.js';
+export { DEFAULT_SNAP_OPTIONS, SnapKind, clientToWorld, resolveSnap, screenScale } from './floorPlan.snap.js';
+export type { SnapContext, SnapGuide, SnapOptions, SnapResult } from './floorPlan.snap.js';
+export { buildWallPaths, openingGeometry, wallCentrelineSpans } from './floorPlan.path.js';
+export type { BuildWallPathsOptions, WallCapLine, WallCapReason, WallPathGroup, WallPathResult, } from './floorPlan.path.js';
+export { PLAN_FORMAT_VERSION, planFromJson, planToJson } from './floorPlan.json.js';
+export type { PlanParseResult } from './floorPlan.json.js';
+export { buildPlanMesh } from './floorPlan.mesh.js';
+export type { BuildPlanMeshOptions, PlanMesh, PlanMeshGroup, PlanMeshPart } from './floorPlan.mesh.js';
+export { planFromLegacySvg } from './legacySvg.js';
+export type { LegacyImportOptions } from './legacySvg.js';

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

@@ -0,0 +1,27 @@
+import { scalePlan } from './floorPlan.graph.js';
+import { FloorPlan } from './floorPlan.types.js';
+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/cjs-types/common/hooks/useAnchorTracking.d.ts

@@ -0,0 +1,40 @@
+import { RefObject } from 'react';
+export interface UseAnchorTrackingArgs {
+    isOpen: boolean;
+    /** The element the popup is anchored to. Its scrollable ancestors are what get tracked. */
+    triggerRef: RefObject<HTMLElement | null>;
+    /**
+     * Every element the positioning maths needs. Tracking starts only once all of them, plus the
+     * trigger, are mounted. Read fresh on each setup, so an inline array literal is fine.
+     */
+    elementRefs: RefObject<HTMLElement | null>[];
+    /**
+     * Positions the popup. Called once on setup and then on every scroll, resize and tracked size
+     * change. Reads the caller's own refs for everything beyond the two arguments.
+     */
+    update: (trigger: HTMLElement, ancestors: HTMLElement[]) => void;
+    /**
+     * Elements whose own size changes must re-run `update`: a popup whose content changes size
+     * while open (a filtered list shrinking, an async list loading in) otherwise keeps coordinates
+     * computed for its old height and ends up detached from the trigger. Re-read on every update,
+     * since a panel can mount a commit later than the element it hangs off.
+     */
+    resizeRefs?: RefObject<HTMLElement | null>[];
+    /** Hands the popup's elements back as they were found. Runs when tracking stops. */
+    teardown?: () => void;
+    /** Values that must restart tracking, and so re-run `update`, when they change. */
+    deps?: readonly unknown[];
+}
+/**
+ * The lifecycle half of anchoring a portaled, `position: fixed` popup to a trigger: waits for the
+ * elements to mount, resolves the trigger's scrolling ancestors once, and re-runs the caller's
+ * positioning on every scroll, viewport resize and tracked size change until it closes.
+ *
+ * Callers supply only the geometry (`update`) and the inline styles to clear again (`teardown`);
+ * `usePopoverPosition` is built on this.
+ *
+ * Position is deliberately written straight to the DOM by the caller rather than through React
+ * state: going through setState -> re-render -> commit adds a round-trip that lags behind the
+ * browser's own scroll painting by at least a frame.
+ */
+export declare function useAnchorTracking({ isOpen, triggerRef, elementRefs, update, resizeRefs, teardown, deps, }: UseAnchorTrackingArgs): void;

package/dist/cjs-types/common/hooks/useCoarsePointer.d.ts

@@ -0,0 +1,3 @@
+/** `true` when the primary pointing device is coarse (touch). */
+export declare function useCoarsePointer(): boolean;
+export default useCoarsePointer;

package/dist/cjs-types/common/hooks/useFocusBoundary.d.ts

@@ -0,0 +1,20 @@
+import { RefObject } from 'react';
+/** Tabbable descendants of `root`, in DOM order. */
+export declare function tabbablesIn(root: ParentNode | null): HTMLElement[];
+export interface UseFocusBoundaryArgs {
+    /** The trigger element focus returns to on Escape / Shift+Tab out of the content's top. */
+    triggerRef: RefObject<HTMLElement | null>;
+    /** The portaled content root — tabbables inside it define the Tab boundary. */
+    contentRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Focus helpers for content portaled to the end of the DOM (e.g. via BodyEnd), where Tab can't
+ * reach it in visual document order on its own. Used by Popover and by Menu, which both need to
+ * hand focus back to the trigger on Escape / Shift+Tab out of the top, and continue focus
+ * naturally past the trigger when Tab exits the bottom.
+ */
+export declare function useFocusBoundary({ triggerRef, contentRef }: UseFocusBoundaryArgs): {
+    firstTriggerFocusable: () => HTMLElement | null;
+    restoreFocusToTrigger: () => void;
+    focusAfterTrigger: () => void;
+};

package/dist/cjs-types/common/hooks/useMediaQuery.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `true` while `query` matches, kept current so a resize or an input-mode change re-renders.
+ *
+ * `useSyncExternalStore` rather than `useState` + `useEffect`: callers pick *markup* with this,
+ * so hydration has to start from the server's answer. Reading `matchMedia` in a `useState`
+ * initialiser makes the client's first render disagree with the server's HTML.
+ */
+export declare function useMediaQuery(query: string): boolean;
+export default useMediaQuery;

package/dist/cjs-types/common/hooks/useOverlay.d.ts

@@ -0,0 +1,26 @@
+import { RefObject } from 'react';
+export interface UseOverlayArgs {
+    /** Whether the overlay is currently visible. Everything below is set up while this is true. */
+    isActive: boolean;
+    /** The overlay panel. Focus is trapped inside it and Escape is scoped to it. */
+    containerRef: RefObject<HTMLElement | null>;
+    /** Called when Escape is pressed while this is the topmost overlay. Omit to not handle Escape. */
+    onEscape?: () => void;
+    /** Keep Tab inside the panel and restore focus to the previously focused element on close. */
+    trapFocus?: boolean;
+    /** Prevent the page behind the overlay from scrolling. */
+    lockScroll?: boolean;
+}
+/**
+ * The three behaviours every blocking overlay needs: Escape to dismiss, a focus trap, and a
+ * scroll lock on the page behind it.
+ *
+ * They share one module-level stack because they share one question: overlays nest (a
+ * ConfirmModal opened from inside a Modal), every instance listens on `document`, and only the
+ * innermost one may react. Without the stack, Escape would close every open layer at once and
+ * the outer trap would yank focus out of the inner panel on the next Tab.
+ *
+ * The scroll lock is reference-counted for the same reason: the page stays locked until the last
+ * overlay closes, and the body's original inline styles are restored rather than cleared.
+ */
+export declare function useOverlay({ isActive, containerRef, onEscape, trapFocus, lockScroll }: UseOverlayArgs): void;

package/dist/cjs-types/common/hooks/useScrollEdges.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from 'react';
+export interface ScrollEdges {
+    /** Content is scrolled out of view past the element's top (or left) edge. */
+    hasStart: boolean;
+    /** Content continues past the element's bottom (or right) edge. */
+    hasEnd: boolean;
+}
+export interface ScrollEdgesOptions {
+    /** Which axis to measure. Default `'vertical'`. */
+    axis?: 'vertical' | 'horizontal';
+    /** Measure at all. Default `true`; pass `false` while the element is hidden. */
+    isEnabled?: boolean;
+}
+/**
+ * Reports which edges of a scroll container currently hide content, so a caller can mark the
+ * boundary, most often by fading it: see `styles/scrollFade.module.pcss`.
+ */
+export declare function useScrollEdges(ref: RefObject<HTMLElement | null>, options?: ScrollEdgesOptions): ScrollEdges;

package/dist/cjs-types/common/hooks/useSheet.d.ts

@@ -0,0 +1,19 @@
+import { CSSProperties } from 'react';
+import { Presentation } from '../configProvider/presentation.types.js';
+export interface Sheet {
+    /** Whether the popup should render as a bottom sheet instead of anchored to its trigger. */
+    isSheet: boolean;
+    /**
+     * Inline style for the sheet root: keeps it above an open on-screen keyboard, and hands the CSS
+     * the height actually left on screen as `--sheet-available-height`.
+     */
+    sheetStyle: CSSProperties | undefined;
+}
+/**
+ * Resolves whether a popup presents as a bottom sheet.
+ *
+ * `Auto` asks for a coarse pointer *and* a small screen: pointer alone turns a touchscreen laptop
+ * into a phone, and width alone turns a narrow desktop window into one.
+ */
+export declare function useSheet(presentation?: Presentation): Sheet;
+export default useSheet;