@weasel-js/core 0.5.0

package/dist/types-BjUi2vA-.d.ts

@@ -0,0 +1,355 @@
+import { Op } from '@weasel-js/history';
+import { S as SnapTarget, M as MoveAdapter, I as InsertAdapter } from './types-B_-khFM0.js';
+
+/** Snapshot of modifier-key state at gesture dispatch. */
+interface ModifierState {
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    ctrl: boolean;
+}
+/** Pointer position in both world and client coords. */
+interface PointerState {
+    worldX: number;
+    worldY: number;
+    clientX: number;
+    clientY: number;
+}
+/**
+ * Per-gesture context passed to behaviors. `current` is the running pose
+ * map; behaviors mutate proposed poses by returning new TPose values from
+ * onMove. `scratch` is per-gesture key/value storage that resets at the
+ * next gesture start.
+ */
+interface GestureContext<TPose, TNode extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    draggedIds: string[];
+    origin: Map<string, TPose>;
+    current: Map<string, TPose>;
+    snap: SnapTarget<TPose> | null;
+    modifiers: ModifierState;
+    pointer: PointerState;
+    adapter: MoveAdapter<TNode, TPose>;
+    /**
+     * Per-gesture mutable store. Keys should be namespaced by behavior name to avoid
+     * collisions: `'behaviorName'` for a single value, `'behaviorName.field'` for
+     * sub-keys. Two behaviors sharing a key will silently clobber each other.
+     */
+    scratch: Record<string, unknown>;
+}
+/** Pluggable per-gesture snap rule; receives the proposed pose and returns a snapped pose or `null` to skip. */
+interface SnapStrategy<TPose> {
+    snap(pose: TPose, ctx: GestureContext<TPose, {
+        id: string;
+    }>): TPose | null;
+}
+/**
+ * Generalized base behavior. Each hook defines an alias that pins the
+ * proposed-pose shape (TProposed) and the onMove return shape (TMoveResult).
+ * onEnd is uniform: first non-undefined return wins (Op[] = commit those,
+ * null = abort, undefined = defer).
+ *
+ * `defaultTransient`: when at least one behavior in a gesture sets this true
+ * AND the hook's `options.transient` is not explicitly set, the gesture
+ * commits its ops via `adapter.applyOps(ops)` (no history entry). When
+ * `options.transient` is set explicitly, that value wins.
+ */
+interface ActionBehavior<TPose, TProposed, TMoveResult> {
+    defaultTransient?: boolean;
+    onStart?(ctx: GestureContext<TPose>): void;
+    onMove?(ctx: GestureContext<TPose>, proposed: TProposed): TMoveResult | void;
+    onEnd?(ctx: GestureContext<TPose>): Op[] | null | void;
+}
+/**
+ * Uniform group transform proposed by a gesture and shaped by behaviors.
+ * Applied identically to every dragged id so a multi-select gesture cannot
+ * drift apart (the historical bug: snap shifted only the primary, secondaries
+ * kept the raw cursor delta).
+ *
+ * v1 of the migration: only `'translate'` is wired end-to-end. `'scale'` and
+ * `'rotate'` exist for forward compatibility — `useResize` already remaps
+ * each leaf via `geom.remapBounds`, and `useRotate` is single-id-pivot-bound,
+ * so neither suffers the multi-select drift `'translate'` did. Migrate those
+ * gestures to emit `GroupTransform` in a follow-up.
+ */
+type GroupTransform = {
+    kind: 'translate';
+    dx: number;
+    dy: number;
+} | {
+    kind: 'scale';
+    pivot: {
+        x: number;
+        y: number;
+    };
+    sx: number;
+    sy: number;
+} | {
+    kind: 'rotate';
+    pivot: {
+        x: number;
+        y: number;
+    };
+    angle: number;
+};
+/**
+ * Per-frame result a `MoveBehavior.onMove` can return.
+ *
+ * `transform` is the new uniform-group-transform channel: the gesture applies
+ * it to every dragged id, eliminating multi-select drift.
+ *
+ * `pose` is the legacy channel: a primary-id-only override. The hook routes
+ * it through a back-compat shim that derives a `translate` transform from
+ * the pose diff against `origin.get(primaryId)`. Prefer `transform` in new
+ * behaviors; `pose` will be removed after one release cycle.
+ *
+ * `snap` announces a visual snap target; unchanged from the legacy contract.
+ */
+interface BehaviorResult<TPose> {
+    /** Replace the proposed transform. Applied uniformly to every id. */
+    transform?: GroupTransform;
+    /** @deprecated Return `transform` instead. Legacy primary-only pose override; supported via internal shim. */
+    pose?: TPose;
+    snap?: SnapTarget<TPose> | null;
+}
+/** @deprecated Renamed to `BehaviorResult`. Kept as an alias for one release cycle. */
+type BehaviorMoveResult<TPose> = BehaviorResult<TPose>;
+/** A behavior plugged into `useMove` — shapes the proposed transform during a drag.
+ *  Behaviors receive a `GroupTransform` (currently always `'translate'` for
+ *  `useMove`) and return a `BehaviorResult` shaping it (or, legacy, an
+ *  override pose run through the back-compat shim). */
+type MoveBehavior<TPose> = ActionBehavior<TPose, GroupTransform, BehaviorResult<TPose>>;
+/** Which corner/edge of the rect stays fixed during a resize. */
+type ResizeAnchor = {
+    x: 'min' | 'max' | 'free';
+    y: 'min' | 'max' | 'free';
+};
+/** Minimum rect-shaped pose required by the resize machinery. */
+interface ResizePose {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Per-frame proposed resize: pose plus the anchor pinning the opposite corner. */
+interface ResizeProposed<TPose extends ResizePose> {
+    pose: TPose;
+    anchor: ResizeAnchor;
+}
+/** Per-frame result a `BoundsConstraint.onMove` can return to override the proposed pose. */
+interface ResizeMoveResult<TPose extends ResizePose> {
+    pose?: TPose;
+}
+/** A bounds-frame constraint plugged into `useResize` / `resizeAction`.
+ *  Reads/writes `{x,y,width,height}` and can override the proposed pose
+ *  on each frame (e.g. lock-aspect, clamp-min-size, snap-to-grid). */
+type BoundsConstraint<TPose extends ResizePose> = ActionBehavior<TPose, ResizeProposed<TPose>, ResizeMoveResult<TPose>>;
+/** Live overlay state exposed by `useResize` for rendering the in-flight resize ghost. */
+interface ResizeOverlay<TPose> {
+    id: string;
+    currentPose: TPose;
+    targetPose: TPose;
+    anchor: ResizeAnchor;
+    /** Per-leaf scaled poses when the gesture is resizing a group.
+     *  Keys are the expanded leaf ids (from `expandIds`); values are the
+     *  per-leaf poses produced by scaling each leaf's origin pose against
+     *  the group's origin/proposed union rects. Absent for single-leaf
+     *  resizes. */
+    leafPoses?: Map<string, TPose>;
+}
+/** ResizePose extended with a rotation angle (radians). Pivot is the AABB
+ *  center of the unrotated `{x, y, width, height}`. */
+interface RotatedPose extends ResizePose {
+    rotation: number;
+}
+/** Per-frame proposed rotation: pose plus the candidate angle in radians. */
+interface RotateProposed<TPose> {
+    pose: TPose;
+    /** Proposed rotation angle (radians). */
+    rotation: number;
+}
+/** Per-frame result a `RotateBehavior.onMove` can return to override the proposed pose. */
+interface RotateMoveResult<TPose> {
+    pose?: TPose;
+}
+/** A behavior plugged into `useRotate`. */
+type RotateBehavior<TPose> = ActionBehavior<TPose, RotateProposed<TPose>, RotateMoveResult<TPose>>;
+/** Live overlay state exposed by `useRotate` for rendering the in-flight rotation ghost. */
+interface RotateOverlay<TPose> {
+    id: string;
+    currentPose: TPose;
+    targetPose: TPose;
+    /** Origin pose at gesture start. */
+    originPose: TPose;
+}
+/** A single world-space point. Insert tracks two of these (start + current);
+ *  bounds and pose are derived per-frame. */
+interface InsertPoint {
+    x: number;
+    y: number;
+}
+/** Per-frame proposed insert: the two world points plus their derived bounds and pose. */
+interface InsertProposed<TPose> {
+    start: InsertPoint;
+    current: InsertPoint;
+    bounds: ResizePose;
+    pose: TPose;
+}
+/** Per-frame result an `InsertBehavior.onMove` can return to override the start/current points. */
+interface InsertMoveResult {
+    /** Override the start point (e.g. snap-to-grid on the anchor). */
+    start?: InsertPoint;
+    /** Override the current point (e.g. snap the live edge). */
+    current?: InsertPoint;
+}
+/** Behaviors operate over the two world points; bounds and pose are derived
+ *  by the hook from the (possibly modified) points each frame. */
+type InsertBehavior<TPose> = ActionBehavior<TPose, InsertProposed<TPose>, InsertMoveResult>;
+/** Live overlay state exposed by `useInsert` for rendering the in-flight insert preview. */
+interface InsertOverlay<TPose> {
+    start: InsertPoint;
+    current: InsertPoint;
+    /** Axis-aligned bounding rect derived from `start`/`current`. */
+    bounds: ResizePose;
+    /** TPose constructed from `bounds` via the hook's `posefromBounds`. */
+    pose: TPose;
+}
+/** Pose carried through area-select gestures: the world point under the
+ *  cursor at gesture start, plus the shift-key state at start. */
+interface AreaSelectPose {
+    worldX: number;
+    worldY: number;
+    shiftHeld: boolean;
+}
+/** Per-frame proposed area-select state: start point, current point, and shift policy. */
+interface AreaSelectProposed {
+    start: {
+        worldX: number;
+        worldY: number;
+    };
+    current: {
+        worldX: number;
+        worldY: number;
+    };
+    shiftHeld: boolean;
+}
+/** onMove for area-select doesn't shape ops; behaviors only need to react in
+ *  onEnd. We return void from onMove. */
+type AreaSelectMoveResult = void;
+/** A behavior plugged into `useAreaSelect`. */
+type AreaSelectBehavior = ActionBehavior<AreaSelectPose, AreaSelectProposed, AreaSelectMoveResult>;
+/** Live overlay state exposed by `useAreaSelect` for rendering the marquee. */
+interface AreaSelectOverlay {
+    start: {
+        worldX: number;
+        worldY: number;
+    };
+    current: {
+        worldX: number;
+        worldY: number;
+    };
+    shiftHeld: boolean;
+}
+/** Pose carried through lasso-select gestures: the world point under the
+ *  cursor at gesture start, plus the shift-key state at start. */
+interface LassoSelectPose {
+    worldX: number;
+    worldY: number;
+    shiftHeld: boolean;
+}
+/** Per-frame proposed lasso state: full vertex history + shift policy. */
+interface LassoSelectProposed {
+    vertices: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    shiftHeld: boolean;
+}
+/** onMove for lasso-select doesn't shape ops; behaviors only need to react
+ *  in onEnd. We return void from onMove. */
+type LassoSelectMoveResult = void;
+/** A behavior plugged into `useLassoSelect`. */
+type LassoSelectBehavior = ActionBehavior<LassoSelectPose, LassoSelectProposed, LassoSelectMoveResult>;
+/** Live overlay state exposed by `useLassoSelect` for rendering the
+ *  in-progress polyline + dashed close-line. */
+interface LassoSelectOverlay {
+    vertices: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    current: {
+        worldX: number;
+        worldY: number;
+    };
+    shiftHeld: boolean;
+}
+/** Frames a point-snap behavior can return for the hook to back-solve. */
+type PointSnapFrame = 'dragged-corner' | 'fixed-corner' | 'center' | 'origin';
+/** Per-frame world-space context handed to `PointSnapBehavior.onMove`.
+ *  `draggedCorner` and `fixedCorner` are `null` for edge drags
+ *  (`anchor.x === 'free'` or `anchor.y === 'free'`). `center` and
+ *  `origin` are always present. */
+interface PointSnapContext<TPose extends ResizePose> {
+    draggedCorner: {
+        worldX: number;
+        worldY: number;
+    } | null;
+    fixedCorner: {
+        worldX: number;
+        worldY: number;
+    } | null;
+    center: {
+        worldX: number;
+        worldY: number;
+    };
+    origin: {
+        worldX: number;
+        worldY: number;
+    };
+    rotation: number;
+    anchor: ResizeAnchor;
+    proposed: TPose;
+    modifiers: ModifierState;
+}
+/** Per-frame snap result. A behavior returns at most one. */
+interface PointSnapResult {
+    frame: PointSnapFrame;
+    worldX: number;
+    worldY: number;
+}
+/** A point-snap behavior plugged into `useResize`'s `pointSnapBehaviors`. */
+interface PointSnapBehavior<TPose extends ResizePose> {
+    id?: string;
+    onMove(ctx: PointSnapContext<TPose>): PointSnapResult | null | undefined;
+}
+/** Pose carried through clone gestures: ids being cloned plus the pointer/offset state. */
+interface ClonePose {
+    ids: string[];
+    offset: {
+        dx: number;
+        dy: number;
+    };
+    worldX: number;
+    worldY: number;
+}
+/** Layer category a clone targets — kit-level placeholder; consumers may narrow. */
+type CloneLayer = 'structures' | 'zones' | 'plantings';
+/** A behavior plugged into `useClone`; gates on modifier state and emits ops at gesture end. */
+interface CloneBehavior {
+    id: string;
+    /** Default true. */
+    defaultTransient?: boolean;
+    /** Decides whether this gesture should activate at start. */
+    activates: (modifiers: ModifierState) => boolean;
+    /** On end, returns ops to commit (or [] for no-op). */
+    onEnd: (pose: ClonePose, ctx: {
+        adapter: InsertAdapter<{
+            id: string;
+        }>;
+    }) => Op[];
+}
+
+export type { ActionBehavior as A, BoundsConstraint as B, CloneBehavior as C, ResizeMoveResult as D, ResizeOverlay as E, ResizeProposed as F, GestureContext as G, RotateMoveResult as H, InsertBehavior as I, RotateOverlay as J, RotateProposed as K, LassoSelectBehavior as L, ModifierState as M, PointSnapBehavior as P, ResizePose as R, SnapStrategy as S, MoveBehavior as a, RotatedPose as b, ResizeAnchor as c, PointSnapFrame as d, RotateBehavior as e, AreaSelectBehavior as f, AreaSelectMoveResult as g, AreaSelectOverlay as h, AreaSelectPose as i, AreaSelectProposed as j, BehaviorMoveResult as k, BehaviorResult as l, CloneLayer as m, ClonePose as n, GroupTransform as o, InsertMoveResult as p, InsertOverlay as q, InsertPoint as r, InsertProposed as s, LassoSelectMoveResult as t, LassoSelectOverlay as u, LassoSelectPose as v, LassoSelectProposed as w, PointSnapContext as x, PointSnapResult as y, PointerState as z };