@weasel-js/guides 1.7.0 → 1.7.2

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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';
+import { G as Guide, S as SpacingGap } from './types-DRSPiXfk.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;
@@ -204,8 +204,10 @@ 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.
+ * thin line, projecting the guide's world offset through the active view.
+ * A guide with a `span` draws as a segment over that span with a tick at each
+ * end; one without spans the full canvas. It also draws equal-spacing gaps
+ * (`SpacingGap`) as ticked segments labeled with their size.
  *
  * Guides are not scene objects; they live outside the scene and are managed
  * via `useGuides`. Pair with `guideSnapStrategy` (snap behavior) to keep
@@ -216,10 +218,24 @@ declare function useGuides(initial?: Guide[]): UseGuidesReturn;
 interface GuidesLayerOpts {
     /** Stable getter for the live guide list — typically `useGuides().getGuides`. */
     getGuides: () => readonly Guide[];
+    /** Stable getter for the equal-spacing gaps to draw — typically what an
+     *  alignment behavior's `setActiveGaps` last published. */
+    getGaps?: () => readonly SpacingGap[];
+    /** `'span'` (default) draws a guide that carries a `span` as a segment over
+     *  it; `'full'` draws every guide across the whole canvas. */
+    extent?: 'span' | 'full';
+    /** Length in CSS px of the tick across each end of a segment. 0 for none.
+     *  Default 6. */
+    ticks?: number;
+    /** Label each gap with its size: `true` (default) prints it rounded to a
+     *  whole world unit, a function formats it, `false` omits the label. */
+    gapLabels?: boolean | ((size: number) => string);
     /** Stroke width in CSS pixels. Default 1. */
     lineWidth?: number;
-    /** Stroke color. Default a subtle blue. */
+    /** Stroke color, and the gap labels' fill. Default a subtle blue. */
     color?: string;
+    /** Gap marker color. Default `color`. */
+    gapColor?: string;
     /** Optional dash pattern (CSS px). Currently unused — reserved for future
      *  parity with chrome that supports dashes. */
     dash?: number[];
@@ -229,8 +245,8 @@ interface GuidesLayerOpts {
     /** 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. */
+/** Build a `RenderLayer` that draws guide lines and spacing gaps in screen
+ *  space, projected from world coordinates via the active view. */
 declare function createGuidesLayer(opts: GuidesLayerOpts): RenderLayer<unknown>;
 
 /** Which feature of a box to test against candidates, per axis.
@@ -245,6 +261,17 @@ interface AlignMatchResult {
     activeX: Guide | null;
     activeY: Guide | null;
 }
+/** Which edges of a box move on one axis during a spacing match: `'both'`
+ *  for a translate, `'min'`/`'max'` for a resize dragging that edge. */
+type SpacingEdge = 'both' | 'min' | 'max';
+/** The correction an equal-spacing match asks for, and the gaps to draw. */
+interface SpacingMatchResult {
+    dx: number;
+    dy: number;
+    /** Every x gap equal to the one snapped to, the box's own included. */
+    gapsX: SpacingGap[];
+    gapsY: SpacingGap[];
+}
 /** 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> {
@@ -269,11 +296,20 @@ interface AlignmentBehaviorBase {
     tolerance?: number;
     /** Modifier key that bypasses snapping while held. */
     bypassKey?: keyof ModifierState;
+    /** Boxes to measure gaps between for equal-spacing snaps (`matchSpacing`):
+     *  the siblings' visual bounds, without the dragged ones. Omit to snap to
+     *  alignment lines only. On each axis the nearer of the two snaps wins.
+     *  Move and unrotated resize use it; insert does not. */
+    getSpacingTargets?: () => readonly Bounds[];
+    /** Publish the equal-gap markers. Called with the guides; cleared (`[]`) on
+     *  a miss and on onEnd. */
+    setActiveGaps?: (gaps: readonly SpacingGap[]) => void;
 }
 
 /** 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.
+ *  edges and the center. Overlapping offsets collapse to one candidate, whose
+ *  `span` covers every box that produced it.
  *  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[];
@@ -287,7 +323,9 @@ declare const MOVE_ANCHORS: {
  * 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.
+ * (feature, candidate) pair wins. A matched guide that carries a `span` comes
+ * back with it stretched to cover the snapped box, so the drawn segment runs
+ * from the aligned siblings to the box being dragged.
  *
  * `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
@@ -302,6 +340,35 @@ declare function matchAlignment(bounds: Bounds, candidates: readonly Guide[], wo
     y: readonly AlignAnchor[];
 }): AlignMatchResult;
 
+type Axis = 'x' | 'y';
+/**
+ * The visible gaps between neighboring boxes along `axis`: for `'x'`, each box
+ * and the nearest box to its right that shares some of its vertical range, as
+ * long as no third box stands in the strip between them. These are the gaps an
+ * equal-spacing snap can reproduce.
+ */
+declare function measureGaps(targets: readonly Bounds[], axis: Axis): SpacingGap[];
+/**
+ * Match a box against the gaps between `targets`, Figma's "equal spacing":
+ * on each axis, find where the box's gap to a neighbor equals a gap that
+ * already exists between two other boxes, or where it sits centered between
+ * its two neighbors. `moving` says which edges move on each axis — `'both'`
+ * for a translate, `'min'`/`'max'` for a resize dragging that edge, `null` to
+ * leave the axis alone. Default `'both'` on each axis.
+ *
+ * Targets should exclude the box itself. A reference gap the box now stands
+ * inside no longer counts. The returned gaps are every gap equal to the one
+ * snapped to, with the box at its snapped position — ready to draw with
+ * `createGuidesLayer`'s `getGaps`.
+ */
+declare function matchSpacing(bounds: Bounds, targets: readonly Bounds[], worldTolerance: {
+    x: number;
+    y: number;
+}, moving?: {
+    x: SpacingEdge | null;
+    y: SpacingEdge | null;
+}): SpacingMatchResult;
+
 /** Options for move and resize — adds the pose descriptor for non-rect poses. */
 interface AlignMoveArgs<TPose> extends AlignmentBehaviorBase {
     poseDescriptor?: PoseDescriptor<TPose>;
@@ -405,12 +472,39 @@ interface FreeformOptions<TPose> {
  */
 declare function freeform<TPose>(opts?: FreeformOptions<TPose>): LayoutStrategy<TPose>;
 
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * What a `tileGrid` does with a child past its `cols × rows` cells.
+ *
+ * - `'reject'` (default) — the grid holds `cols × rows` and refuses more, by
+ *   any route: a drop finds no free cell, and an insert or reparent that would
+ *   overfill it is reverted whole.
+ * - `'grow'` — the grid adds a line of cells whenever the last one fills
+ *   (a row, or a column for `flow: 'column'`) and the container grows by its
+ *   pitch to hold it, and gives the line back when children leave and it
+ *   empties. `rows` (or `cols`) is the minimum.
+ * - `'scroll'` — the container keeps its size, and the extra children take
+ *   cells past its last visible line, at the same pitch. `contentExtent`
+ *   reports the region they cover, for a host to scroll over.
+ */
+type TileGridOverflow = 'reject' | 'grow' | 'scroll';
 /** Options for `tileGrid`. */
 interface TileGridOptions<TPose> {
     cols: number;
     rows: number;
     /** Gap between cells, in world units. Default 0. */
     gap?: number;
+    /** The order cells fill in: along each row (`'row'`, the default) or down
+     *  each column (`'column'`). It is also the direction an overflowing grid
+     *  runs on in. */
+    flow?: 'row' | 'column';
+    /** What happens past `cols × rows` children. Default `'reject'`. */
+    overflow?: TileGridOverflow;
     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
@@ -418,12 +512,7 @@ interface TileGridOptions<TPose> {
      *  `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;
+    cellToPose?(cellRect: Rect, 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
@@ -434,13 +523,14 @@ interface TileGridOptions<TPose> {
     };
 }
 /**
- * Layout strategy that arranges children into a fixed grid of cells, one
- * child per cell, and the container holds at most `cols × rows` children.
+ * Layout strategy that arranges children into a grid of cells, one child per
+ * cell. What happens past `cols × rows` children is the `overflow` policy.
  *
  * 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.
+ * free one. A child that joins by an insert or a reparent is placed the same
+ * way, in the free cell nearest to where it was put.
  */
 declare function tileGrid<TPose>(opts: TileGridOptions<TPose>): LayoutStrategy<TPose>;
 
@@ -460,4 +550,4 @@ interface SnapPointOptions<TPose> {
  *  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 };
+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 SpacingEdge, SpacingGap, type SpacingMatchResult, type TileGridOptions, type TileGridOverflow, type UseGridCellHoverOptions, type UseGridCellHoverReturn, type UseGuidesReturn, alignInsertBehavior, alignMoveBehavior, alignResizeBehavior, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, deriveAlignmentGuides, freeform, gridSnapStrategy, guideSnapStrategy, matchAlignment, matchSpacing, measureGaps, nearest, nearestWithin, none, pointToGridCell, roundToCell, snapPoint, tileGrid, useGridCellHover, useGuides };