@weasel-js/guides 1.7.0

package/dist/index.d.ts

@@ -0,0 +1,463 @@
+import { RefObject } from 'react';
+import { ViewTransform, UnitValue, UnitSystem, Stroke, RenderLayer, FillStyle, SnapStrategy, DebugSink, OriginProjection, ModifierState, Bounds, PoseDescriptor, InsertBehavior, MoveBehavior, BoundsConstraint, LayoutSnap, LayoutStrategy, Vec2 } from '@weasel-js/core';
+export { p as pointSnapToGrid } from './pointSnapToGrid-BaVEjV23.js';
+import { G as Guide } from './types-D2tTKEU0.js';
+
+/** Round `value` to the nearest multiple of `cellSize`. Returns 0 when the result would be -0. */
+declare function roundToCell(value: number, cellSize: number): number;
+
+/**
+ * Pointer-tracking glue that turns hover position into a grid cell, suitable
+ * for dropping straight into `createCellHighlightLayer({ getCell })`. Pairs
+ * with `gridSnapStrategy` / `createGridLayer` so the visual hover preview
+ * uses the exact same spacing as the snap behavior.
+ *
+ * Wires three things you'd otherwise glue by hand:
+ *   1. pointermove on a target element → client coords
+ *   2. client coords → world coords via your `ViewTransform`
+ *   3. world coords → integer `{col, row}` via `pointToGridCell`
+ *
+ * State updates only fire when the cell actually changes (not on every
+ * pointer tick). Pass `onChange` to trigger a canvas redraw on each transition.
+ */
+
+/** Options for `useGridCellHover`. */
+interface UseGridCellHoverOptions {
+    /** Element to attach pointer listeners to (typically the canvas). */
+    ref: RefObject<HTMLElement | null>;
+    /** Read the current view transform. Called on every pointermove so it can
+     *  reflect live pan/zoom without a re-binding step. */
+    view: () => ViewTransform;
+    /** Cell spacing in world units. Same value you pass to `createGridLayer`
+     *  and `createCellHighlightLayer`. */
+    spacing: UnitValue;
+    /** Required if `spacing` is tagged (e.g. `{ value: 1, unit: 'ft' }`). */
+    unitSystem?: UnitSystem;
+    /** Origin the cell grid is anchored to, in world units. Default `(0, 0)`. */
+    origin?: {
+        x: number;
+        y: number;
+    };
+    /** Fires when the hovered cell changes (including to/from `null`). Use it
+     *  to invalidate your layer renderer. */
+    onChange?: (cell: {
+        col: number;
+        row: number;
+    } | null) => void;
+    /** Disable the listeners without unmounting. Default `true`. */
+    enabled?: boolean;
+}
+/** Return shape of `useGridCellHover`. */
+interface UseGridCellHoverReturn {
+    /** Current hovered cell, or `null` when the pointer is outside the element. */
+    cell: {
+        col: number;
+        row: number;
+    } | null;
+    /** Stable callback that returns the current cell — drop straight into
+     *  `createCellHighlightLayer({ getCell })`. */
+    getCell: () => {
+        col: number;
+        row: number;
+    } | null;
+}
+/** Track which grid cell the pointer is over; pairs with `createCellHighlightLayer`. */
+declare function useGridCellHover(opts: UseGridCellHoverOptions): UseGridCellHoverReturn;
+
+/**
+ * Grid overlay — a reusable render layer that draws a world-space grid with
+ * optional finer subdivisions and accent lines every N cells.
+ *
+ * The layer renders in world space — the caller is expected to have applied
+ * any view transform to the canvas context already. To draw a highlighted
+ * cell (snap-target preview), stack `createCellHighlightLayer` alongside
+ * this one.
+ */
+
+/** Options for `createGridLayer`. */
+interface GridLayerOpts {
+    /**
+     * Distance between adjacent grid lines (also known as grid pitch),
+     * in world (base) units. Accepts a bare number or a tagged
+     * `{ value, unit }`. Tagged values require `unitSystem` to be supplied.
+     */
+    spacing: UnitValue;
+    /** Optional unit system for resolving tagged `spacing` values. */
+    unitSystem?: UnitSystem;
+    /** Bounds of the area to cover, in world units. */
+    bounds: () => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Lines every N cells get the accent style. 0/undef = no accent. */
+    accentEvery?: number;
+    /** Optional finer subdivisions per cell. e.g. 4 -> 4 sub-lines per cell. */
+    subdivisions?: number;
+    /** Per-band stroke styles. Each is a FillStyle+width (etc.) — see `Stroke`. */
+    style?: {
+        line?: Stroke;
+        accent?: Stroke;
+        sub?: Stroke;
+    };
+}
+/** Build a `RenderLayer` that draws a world-space grid with optional accent lines and subdivisions. */
+declare function createGridLayer(opts: GridLayerOpts): RenderLayer<unknown>;
+
+/**
+ * Cell highlight overlay — a thin render layer that fills a single grid cell
+ * (e.g. a snap-target preview). Stack it under or over `createGridLayer` in
+ * a layer sequence.
+ */
+
+/** Options for `createCellHighlightLayer`. */
+interface CellHighlightLayerOpts {
+    /** Cell size in world units (matches the grid's `spacing`). */
+    spacing: UnitValue;
+    /** Optional unit system for resolving tagged `spacing` values. */
+    unitSystem?: UnitSystem;
+    /** Origin the cell grid is anchored to, in world units. Defaults to (0,0). */
+    origin?: () => {
+        x: number;
+        y: number;
+    };
+    /** Cell to highlight, or `null` to skip drawing. */
+    getCell: () => {
+        col: number;
+        row: number;
+    } | null;
+    /** FillStyle strategy for the filled cell. Defaults to a soft green. */
+    fill?: FillStyle;
+}
+/** Build a `RenderLayer` that fills a single grid cell — typically a snap-target preview. */
+declare function createCellHighlightLayer(opts: CellHighlightLayerOpts): RenderLayer<unknown>;
+
+/** Snap-strategy that rounds the pose's origin to the nearest multiple of
+ *  `spacing` (resolved through `unitSystem`). For non-rect TPose pass an
+ *  `OriginProjection` so the strategy knows how to read/write the origin. */
+declare function gridSnapStrategy<TPose>(spacing: UnitValue, unitSystem?: UnitSystem): SnapStrategy<TPose>;
+/** As above, additionally reporting each candidate to a debug sink. */
+declare function gridSnapStrategy<TPose>(spacing: UnitValue, opts: {
+    unitSystem?: UnitSystem;
+    debug?: DebugSink;
+}): SnapStrategy<TPose>;
+/** As above, for a `TPose` that is not a rect: `origin` tells the strategy how
+ *  to read and write the pose's origin. */
+declare function gridSnapStrategy<TPose>(spacing: UnitValue, opts: {
+    unitSystem?: UnitSystem;
+    origin: OriginProjection<TPose>;
+    debug?: DebugSink;
+}): SnapStrategy<TPose>;
+/**
+ * Compute the integer cell `{col, row}` that contains `point`, given a grid
+ * `spacing` and optional `origin` and `unitSystem`. Pair with
+ * `createCellHighlightLayer` (its `getCell` callback) to draw a snap-target
+ * preview that uses the same spacing as `gridSnapStrategy` — so the visual
+ * and behavioral grids stay in lockstep:
+ *
+ *     const SPACING = 20;
+ *     const snap = gridSnapStrategy(SPACING);
+ *     // visual grid:
+ *     createGridLayer({ spacing: SPACING, bounds: () => ... });
+ *     // hover-preview overlay:
+ *     createCellHighlightLayer({
+ *       spacing: SPACING,
+ *       getCell: () => hoverPoint && pointToGridCell(hoverPoint, SPACING),
+ *     });
+ */
+declare function pointToGridCell(point: {
+    x: number;
+    y: number;
+}, spacing: UnitValue, unitSystem?: UnitSystem, origin?: {
+    x: number;
+    y: number;
+}): {
+    col: number;
+    row: number;
+};
+
+/** Return shape for `useGuides`. */
+interface UseGuidesReturn {
+    /** Live list (state). Re-renders when guides change. */
+    guides: Guide[];
+    /** Stable getter; reads the latest list without forcing a re-render.
+     *  Pass to `guideSnapStrategy` and `createGuidesLayer`. */
+    getGuides: () => Guide[];
+    /** Add a guide. If a guide with the same id already exists it is replaced. */
+    addGuide: (guide: Guide) => void;
+    /** Remove a guide by id. No-op when missing. */
+    removeGuide: (id: string) => void;
+    /** Drop all guides. */
+    clearGuides: () => void;
+}
+/**
+ * In-memory guide storage. Holds a list of horizontal/vertical world-space
+ * lines that callers can pass to `guideSnapStrategy` (snap behavior) and
+ * `createGuidesLayer` (render layer).
+ *
+ * v1 is intentionally minimal: no undo integration, no persistence, no
+ * batched mutation. Wrap calls in your own history-aware action if you
+ * want guide CRUD to be undoable.
+ */
+declare function useGuides(initial?: Guide[]): UseGuidesReturn;
+
+/**
+ * Guides overlay — a screen-space render layer that draws each guide as a
+ * thin line spanning the full canvas, projecting the guide's world offset
+ * through the active view.
+ *
+ * Guides are not scene objects; they live outside the scene and are managed
+ * via `useGuides`. Pair with `guideSnapStrategy` (snap behavior) to keep
+ * the visual guide and the snap target in lockstep.
+ */
+
+/** Options for `createGuidesLayer`. */
+interface GuidesLayerOpts {
+    /** Stable getter for the live guide list — typically `useGuides().getGuides`. */
+    getGuides: () => readonly Guide[];
+    /** Stroke width in CSS pixels. Default 1. */
+    lineWidth?: number;
+    /** Stroke color. Default a subtle blue. */
+    color?: string;
+    /** Optional dash pattern (CSS px). Currently unused — reserved for future
+     *  parity with chrome that supports dashes. */
+    dash?: number[];
+    /** Override the layer id. Useful if a consumer needs more than one
+     *  guides-layer (e.g. user-guides vs. system-guides). */
+    id?: string;
+    /** Override the layer label. */
+    label?: string;
+}
+/** Build a `RenderLayer` that draws guide lines across the full canvas in
+ *  screen space, projected from world offsets via the active view. */
+declare function createGuidesLayer(opts: GuidesLayerOpts): RenderLayer<unknown>;
+
+/** Which feature of a box to test against candidates, per axis.
+ *  'min' = left/top edge, 'center' = centerline, 'max' = right/bottom edge. */
+type AlignAnchor = 'min' | 'center' | 'max';
+/** The correction an alignment match asks for: the translation that lands the
+ *  dragged bounds on the matched guides, and the guides themselves so they can
+ *  be drawn. */
+interface AlignMatchResult {
+    dx: number;
+    dy: number;
+    activeX: Guide | null;
+    activeY: Guide | null;
+}
+/** Which candidate lines to derive from a set of poses — edges, centers, or
+ *  both, and whether the page box contributes its own. */
+interface DeriveAlignmentGuidesOptions<TPose = Bounds> {
+    /** Include the document/page box's edges + center as candidates. */
+    page?: Bounds;
+    /** Emit left/right (x) and top/bottom (y) edge guides. Default true. */
+    edges?: boolean;
+    /** Emit centerX (x) and centerY (y) guides. Default true. */
+    centers?: boolean;
+    /** How to read each target. Pass the same descriptor `alignMoveBehavior`
+     *  gets, or the two sides disagree. Default `AUTO_POSE_DESCRIPTOR`. */
+    poseDescriptor?: PoseDescriptor<TPose>;
+}
+/** Common options shared by the three alignment behavior factories. */
+interface AlignmentBehaviorBase {
+    /** Live candidate lines — consumer derives from current siblings + page. */
+    getCandidates: () => readonly Guide[];
+    /** Publish the currently-matched line(s). Called every onMove; cleared
+     *  (`[]`) on a miss and on onEnd. */
+    setActiveGuides: (guides: readonly Guide[]) => void;
+    /** Tolerance in screen px, read through the gesture's view. Default 6. */
+    tolerance?: number;
+    /** Modifier key that bypasses snapping while held. */
+    bypassKey?: keyof ModifierState;
+}
+
+/** Derive candidate alignment lines from a set of sibling poses plus an
+ *  optional page box. Each box contributes up to 3 guides per axis: the two
+ *  edges and the center. Overlapping offsets collapse to one candidate.
+ *  Poses go through the same descriptor `alignMoveBehavior` matches with, so
+ *  a rotated sibling advertises its ink edges rather than its stored box. */
+declare function deriveAlignmentGuides<TPose = Bounds>(targets: readonly TPose[], opts?: DeriveAlignmentGuidesOptions<TPose>): Guide[];
+
+/** Move/insert test all three features per axis. */
+declare const MOVE_ANCHORS: {
+    x: readonly AlignAnchor[];
+    y: readonly AlignAnchor[];
+};
+/**
+ * Match a moving box's selected edge/center features against candidate guide
+ * lines. Returns the per-axis snap delta and the matched candidate line(s).
+ * The two axes resolve independently; on each axis the closest in-tolerance
+ * (feature, candidate) pair wins.
+ *
+ * `worldTolerance` is per axis because a screen-pixel tolerance is not one
+ * world distance under non-uniform zoom — and each axis here is matched by a
+ * distance along that axis alone, so there is an exact answer rather than an
+ * approximation. Pass the same number twice for a world-space tolerance.
+ */
+declare function matchAlignment(bounds: Bounds, candidates: readonly Guide[], worldTolerance: {
+    x: number;
+    y: number;
+}, anchors: {
+    x: readonly AlignAnchor[];
+    y: readonly AlignAnchor[];
+}): AlignMatchResult;
+
+/** Options for move and resize — adds the pose descriptor for non-rect poses. */
+interface AlignMoveArgs<TPose> extends AlignmentBehaviorBase {
+    poseDescriptor?: PoseDescriptor<TPose>;
+}
+/** Move behavior: snap the dragged selection's union box (edges + center) to
+ *  candidates, shaping the proposed translate. The gesture applies the
+ *  transform uniformly to every dragged id, so the selection shifts together
+ *  and stays rigid. Single-select is the degenerate one-box union. Publishes
+ *  the matched line(s); clears on miss, end and cancel. */
+declare function alignMoveBehavior<TPose>(args: AlignMoveArgs<TPose>): MoveBehavior<TPose>;
+/** Insert behavior: snap the live `current` point to candidates (treating it
+ *  as a zero-size box). Publishes the matched line(s). */
+declare function alignInsertBehavior<TPose>(args: AlignmentBehaviorBase): InsertBehavior<TPose>;
+/** Resize constraint: snap the corner(s) the drag moves, as drawn, to
+ *  candidates; the pinned corner stays fixed. On an unrotated pose that is
+ *  the moving edge(s). On a rotated one the node's own axes set how the
+ *  corner can travel: a corner handle snaps each world axis, an edge handle
+ *  slides its edge until the nearer of its two corners meets a line.
+ *  `poseDescriptor` reads the origin pose's box and rotation, and must match
+ *  the resize action's. Publishes the matched line(s). */
+declare function alignResizeBehavior<TPose extends Bounds>(args: AlignMoveArgs<TPose>): BoundsConstraint<TPose>;
+
+/** Default snap tolerance (screen pixels). */
+declare const DEFAULT_GUIDE_TOLERANCE_PX = 6;
+/** Options for `guideSnapStrategy`. */
+interface GuideSnapOptions<TPose> {
+    /**
+     * Tolerance in screen pixels, divided by the gesture view's scale so the
+     * trigger zone stays the same on screen at every zoom. Defaults to
+     * `DEFAULT_GUIDE_TOLERANCE_PX`.
+     */
+    tolerance?: number;
+    /**
+     * Projection used when `TPose` doesn't expose `{x, y}` directly (Path,
+     * polygon, etc.) — same contract as `gridSnapStrategy`. Defaults to the
+     * rect-pose identity projection.
+     */
+    origin?: OriginProjection<TPose>;
+}
+/**
+ * Snap-strategy that snaps the pose's origin to the nearest guide line on
+ * each axis when within tolerance. Each axis is considered independently:
+ * a vertical guide (`axis: 'x'`) constrains X, a horizontal guide
+ * (`axis: 'y'`) constrains Y. When multiple guides are within range on the
+ * same axis, the closest wins.
+ *
+ * Pair with `useGuides` for storage and `createGuidesLayer` for rendering.
+ *
+ * **Composition:** combining with `gridSnapStrategy` is left to the
+ * consumer in v1 — typically by picking one based on a modifier key, or
+ * by stacking two move/resize/insert behaviors in priority order.
+ */
+declare function guideSnapStrategy<TPose extends {
+    x: number;
+    y: number;
+}>(getGuides: () => readonly Guide[], options?: Omit<GuideSnapOptions<TPose>, 'origin'>): SnapStrategy<TPose>;
+/** As above, for a `TPose` that is not a rect: `origin` tells the strategy how
+ *  to read and write the pose's origin. */
+declare function guideSnapStrategy<TPose>(getGuides: () => readonly Guide[], options: GuideSnapOptions<TPose> & {
+    origin: OriginProjection<TPose>;
+}): SnapStrategy<TPose>;
+
+/** Snap policy that never picks a target — every drop is rejected, which is
+ *  what a free-form container wants. */
+declare function none<TPose>(): LayoutSnap<TPose>;
+/** Snap policy that always picks the target closest to the pointer, however
+ *  far away it is. */
+declare function nearest<TPose>(): LayoutSnap<TPose>;
+/** Snap policy that picks the closest target, but only within `tolerance`
+ *  world units — beyond that the drop is rejected. */
+declare function nearestWithin<TPose>(opts: {
+    tolerance: number;
+}): LayoutSnap<TPose>;
+/**
+ * Region-aware snap. If the pointer falls inside any target's `hitBounds`,
+ * that target wins; otherwise falls back to nearest-origin. Useful for
+ * strategies whose targets are area-shaped (gutters, drop-zones, gridded
+ * cells) rather than point-shaped.
+ *
+ * Pointer-in-multiple-bounds order: first match in iteration order wins, so
+ * strategies should emit narrower/more-specific targets before broader ones
+ * (e.g. row-gutter before tray-corner).
+ */
+declare function containedThenNearest<TPose>(): LayoutSnap<TPose>;
+/**
+ * Backwards-compatible cell snap. Prefer `containedThenNearest` for new
+ * strategies; this variant remains for `tileGrid` and any caller that puts
+ * its cell rect in `meta.cellRect` rather than `hitBounds`.
+ */
+declare function cellAt<TPose>(): LayoutSnap<TPose>;
+
+/** Options for `freeform`. */
+interface FreeformOptions<TPose> {
+    snap?: LayoutSnap<TPose>;
+}
+/**
+ * Identity layout: each child stays where it's stored, no reflow, no drop
+ * targets. `snap` is accepted for API symmetry — overrides take effect only
+ * if a caller wires up an external drop-target source, since `getDropTargets`
+ * returns empty by default.
+ */
+declare function freeform<TPose>(opts?: FreeformOptions<TPose>): LayoutStrategy<TPose>;
+
+/** Options for `tileGrid`. */
+interface TileGridOptions<TPose> {
+    cols: number;
+    rows: number;
+    /** Gap between cells, in world units. Default 0. */
+    gap?: number;
+    snap?: LayoutSnap<TPose>;
+    /** Optional: map a cell rect + the dragged pose to the new pose. Default
+     *  writes `{ x, y, width, height }` into the dragged pose (assumes
+     *  `RectPose`). Override for point-only poses or other shapes. The
+     *  `dragged` argument is the pre-drop pose of the child being placed —
+     *  use it to preserve fields the cell rect doesn't carry (e.g. rotation,
+     *  domain metadata). */
+    cellToPose?(cellRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, dragged: TPose): TPose;
+    /** Optional: the point that decides which cell a child occupies — a child
+     *  occupies the cell containing it. Default reads `x`/`y` plus half of
+     *  `width`/`height` when the pose has them, which is the center of a
+     *  `RectPose` and the point itself for a point pose. */
+    centerOf?(pose: TPose): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Layout strategy that arranges children into a fixed grid of cells, one
+ * child per cell, and the container holds at most `cols × rows` children.
+ *
+ * A child occupies the cell its pose sits in (see `centerOf`). A drag from
+ * inside the container swaps with the child in the cell it lands on; a drop
+ * from outside is offered only the free cells, so it lands in the nearest
+ * free one and a full grid rejects it.
+ */
+declare function tileGrid<TPose>(opts: TileGridOptions<TPose>): LayoutStrategy<TPose>;
+
+/** Which points within a container a child can snap to. */
+type SnapPattern = 'corners' | 'edges' | 'center' | 'grid';
+/** Options for `snapPoint`. */
+interface SnapPointOptions<TPose> {
+    pattern: SnapPattern;
+    /** Spacing for the 'grid' pattern, in world units. Default 50. */
+    gridSpacing?: number;
+    /** Tolerance for the default snap policy (nearestWithin). Default Infinity. */
+    tolerance?: number;
+    snap?: LayoutSnap<TPose>;
+}
+/** Layout strategy that leaves children where they are but offers a fixed set
+ *  of points — corners, edge midpoints, center, or a grid — for a dragged
+ *  child to land on. */
+declare function snapPoint<TPose extends Vec2>(opts: SnapPointOptions<TPose>): LayoutStrategy<TPose>;
+
+export { type AlignAnchor, type AlignMatchResult, type AlignMoveArgs, type AlignmentBehaviorBase, type CellHighlightLayerOpts, DEFAULT_GUIDE_TOLERANCE_PX, type DeriveAlignmentGuidesOptions, type FreeformOptions, type GridLayerOpts, Guide, type GuideSnapOptions, type GuidesLayerOpts, MOVE_ANCHORS, type SnapPattern, type SnapPointOptions, type TileGridOptions, type UseGridCellHoverOptions, type UseGridCellHoverReturn, type UseGuidesReturn, alignInsertBehavior, alignMoveBehavior, alignResizeBehavior, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, deriveAlignmentGuides, freeform, gridSnapStrategy, guideSnapStrategy, matchAlignment, nearest, nearestWithin, none, pointToGridCell, roundToCell, snapPoint, tileGrid, useGridCellHover, useGuides };