@weasel-js/guides 1.11.0 → 1.11.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { RefObject } from 'react';
-import { ViewTransform, PlaneValue, PlaneUnits, View, Dims, CommandStroke, RenderLayer, CommandFill, Bounds, PlaneMap, PoseDescriptor, Scene, NodeId, SnapSource, SurfaceContribution, FeaturePreset, LayoutSnap, LayoutStrategy, LayoutContainer, Vec2, ContainerBounds, LayoutChild } from '@weasel-js/core';
+import { ViewTransform, PlaneValue, PlaneUnits, View, Dims, CommandStroke, RenderLayer, CommandFill, UnitScope, PerAxis, Bounds, PlaneMap, PoseDescriptor, Scene, NodeId, SnapSource, SceneNode, SurfaceContribution, FeaturePreset, LayoutSnap, LayoutStrategy, LayoutContainer, Vec2, ContainerBounds, LayoutChild } from '@weasel-js/core';
 import { Rect } from '@weasel-js/geom';
 
 /** Round `value` to the nearest multiple of `cellSize`. Returns 0 when the result would be -0. */
@@ -147,6 +147,24 @@ declare function pointToGridCell(point: {
     row: number;
 };
 
+/** How a grid reads the unit scopes a scene's containers declare
+ *  (`ContainerNode.units`). */
+interface GridScopes {
+    /** The scene's outermost scope, as `sceneUnitScopes` is handed it. The grid's
+     *  `spacing` is read in its system, in place of `unitSystem`. */
+    root: UnitScope;
+    /** The pitch inside a container's scope, written in that scope's units.
+     *  Default: the grid's `spacing`, read there, so a bare 10 is ten of its
+     *  base units. */
+    spacing?: (scope: UnitScope) => PlaneValue;
+}
+/**
+ * A grid's pitch on each axis, in world units, where `chain` (outermost
+ * first, rooted at `scopes.root`) encloses it: `spacing` in the root, and
+ * `scopes.spacing` of the innermost scope inside a container's.
+ */
+declare function scopedGridPitch(spacing: PlaneValue, scopes: GridScopes, chain: readonly UnitScope[]): PerAxis<number>;
+
 /**
  * Guide — a horizontal or vertical world-space line used as a snap target
  * and an optional rendered overlay.
@@ -354,6 +372,11 @@ interface GridSnapSourceOptions {
     /** A point the lattice passes through. Default `(0, 0)`. */
     origin?: Point;
     unitSystem?: PlaneUnits;
+    /** Read the unit scope the subject sits in: a node inside a millimeter
+     *  sub-assembly snaps on that scope's pitch. The subject's scope is the one
+     *  all its nodes share; for a gesture with none, the scope of the
+     *  container it draws into (`SnapCollect.parent`), else the root. */
+    scopes?: GridScopes;
 }
 /**
  * A grid as snap targets: for each origin or pointer probe, the grid line on
@@ -370,6 +393,9 @@ declare function gridSnapSource(opts: GridSnapSourceOptions): SnapSource;
  */
 declare function guideSnapSource(getGuides: () => readonly Guide[]): SnapSource;
 
+/** Which nodes may be targets; one that fails offers no lines or gaps. */
+type TargetFilter = (node: SceneNode<unknown, string, unknown>) => boolean;
+
 /** Options for `alignmentSnapSource`. */
 interface AlignmentSnapSourceOptions {
     /** A page box whose edges and center are lines too, in the camera's world. */
@@ -377,6 +403,8 @@ interface AlignmentSnapSourceOptions {
     /** The lines to align to, in place of the edges and centers of the
      *  subject's siblings (of the scene's top-level nodes, for a point gesture). */
     getCandidates?: () => readonly Guide[];
+    /** Which nodes offer lines. Narrows the default siblings; not `getCandidates`. */
+    filter?: TargetFilter;
     /** The color of the lines it marks. Default: the readout layer's. */
     color?: string;
     /** Overrides the canvas's reach for these targets, in screen px. */
@@ -395,6 +423,8 @@ declare function alignmentSnapSource(opts?: AlignmentSnapSourceOptions): SnapSou
 interface SpacingSnapSourceOptions {
     /** The boxes to measure gaps between, in place of the subject's siblings. */
     getTargets?: () => readonly Bounds[];
+    /** Which nodes offer gaps. Narrows the default siblings; not `getTargets`. */
+    filter?: TargetFilter;
     /** The color of the gaps it marks. Default: the readout layer's. */
     color?: string;
     /** Overrides the canvas's reach for these targets, in screen px. */
@@ -466,6 +496,8 @@ interface SpacingHintsOptions {
     align?: boolean;
     /** Snap distance in screen px. Default the canvas's reach. */
     tolerance?: number;
+    /** Which nodes the snap sources take as siblings to line up or space against. */
+    filter?: TargetFilter;
     /** The Alt-hover distance readout, configured, or `false` for none. Default
      *  on, with the preset's `color`. */
     readout?: false | Omit<DistanceReadoutOptions, 'color'>;
@@ -809,4 +841,4 @@ interface Sequencer<TPose> {
  */
 declare function sequenceLayout<TPose>(seq: Sequencer<TPose>): LayoutStrategy<TPose>;
 
-export { type AlignmentSnapSourceOptions, type Arrangement, type CellHighlightLayerOpts, type DeriveAlignmentGuidesOptions, type DistanceReadout, type DistanceReadoutContribution, type DistanceReadoutOptions, type FreeformOptions, type GridLayerOpts, type GridSlotsOptions, type GridSnapSourceOptions, type Guide, type GuidesLayerOpts, type PackOptions, type PackOverflow, type PerContainerOptions, type PerContainerStrategy, type QuadtreeCell, type QuadtreeOptions, type QuadtreeStrategy, type RingSlotsOptions, type RowSlotsOptions, type SceneBoundsOptions, type Sequencer, type Slot, type SlotsOptions, type SnapPattern, type SnapPointOptions, type SpacingEdge, type SpacingGap, type SpacingHintsOptions, type SpacingMatchResult, type SpacingSnapSourceOptions, type TileGridOptions, type TileGridOverflow, type UseGridCellHoverOptions, type UseGridCellHoverReturn, type UseGuidesReturn, alignmentSnapSource, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, createSpacingHintsPreset, deriveAlignmentGuides, distanceReadout, freeform, gridSlots, gridSnapSource, guideSnapSource, matchSpacing, measureDistances, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, ringSlots, roundToCell, rowSlots, sequenceLayout, siblingBounds, slots, snapPoint, spacingSnapSource, tileGrid, useGridCellHover, useGuides, worldBoundsOf, worldUnionOf };
+export { type AlignmentSnapSourceOptions, type Arrangement, type CellHighlightLayerOpts, type DeriveAlignmentGuidesOptions, type DistanceReadout, type DistanceReadoutContribution, type DistanceReadoutOptions, type FreeformOptions, type GridLayerOpts, type GridScopes, type GridSlotsOptions, type GridSnapSourceOptions, type Guide, type GuidesLayerOpts, type PackOptions, type PackOverflow, type PerContainerOptions, type PerContainerStrategy, type QuadtreeCell, type QuadtreeOptions, type QuadtreeStrategy, type RingSlotsOptions, type RowSlotsOptions, type SceneBoundsOptions, type Sequencer, type Slot, type SlotsOptions, type SnapPattern, type SnapPointOptions, type SpacingEdge, type SpacingGap, type SpacingHintsOptions, type SpacingMatchResult, type SpacingSnapSourceOptions, type TargetFilter, type TileGridOptions, type TileGridOverflow, type UseGridCellHoverOptions, type UseGridCellHoverReturn, type UseGuidesReturn, alignmentSnapSource, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, createSpacingHintsPreset, deriveAlignmentGuides, distanceReadout, freeform, gridSlots, gridSnapSource, guideSnapSource, matchSpacing, measureDistances, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, ringSlots, roundToCell, rowSlots, scopedGridPitch, sequenceLayout, siblingBounds, slots, snapPoint, spacingSnapSource, tileGrid, useGridCellHover, useGuides, worldBoundsOf, worldUnionOf };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
-import { resolveAxes, useLatest, viewportWorldRect, pxExtent, tickedSegment, measuredSegmentCommands, AUTO_POSE_DESCRIPTOR, visualBoundsViaDescriptor, rectFromPlane, scenePoseFrame, unionAABB, createTransformOp, screenToWorld, nodeGates, resolveStrokeWidth } from '@weasel-js/core';
+import { resolveAxes, useLatest, viewportWorldRect, pxExtent, tickedSegment, measuredSegmentCommands, AUTO_POSE_DESCRIPTOR, visualBoundsViaDescriptor, rectFromPlane, scenePoseFrame, unionAABB, createTransformOp, sceneSharedUnitScopes, asNodeId, sceneUnitScopes, screenToWorld, nodeGates, resolveStrokeWidth, resolveScoped } from '@weasel-js/core';
 import { PATH_M, PATH_L } from '@weasel-js/geom';
 
 // src/grid/roundToCell.ts
@@ -159,6 +159,23 @@ function createCellHighlightLayer(opts) {
     }
   };
 }
+function span(v, chain) {
+  const zero = typeof v === "number" ? 0 : { ...v, value: 0 };
+  return resolveScoped(v, chain) - resolveScoped(zero, chain);
+}
+function scopedGridPitch(spacing, scopes, chain) {
+  const inner = chain.length > 1 ? chain[chain.length - 1] : null;
+  const v = inner && scopes.spacing ? scopes.spacing(inner) : spacing;
+  const on = (axis) => {
+    const a = typeof v === "object" && "x" in v ? v[axis] : v;
+    try {
+      return span(a, chain);
+    } catch (e) {
+      throw new Error(`${axis} axis: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  };
+  return { x: on("x"), y: on("y") };
+}
 function useGuides(initial = []) {
   const [guides, setGuides] = useState(initial);
   const ref = useLatest(guides);
@@ -208,16 +225,16 @@ function createGuidesLayer(opts) {
       const sy = (y) => (y - view.y) * view.scale.y;
       const out = [];
       for (const g of guides) {
-        const span = spanned ? g.span : void 0;
+        const span2 = spanned ? g.span : void 0;
         if (g.axis === "x") {
           const x = sx(g.offset);
           if (x < -lineWidth || x > dims.width + lineWidth) continue;
-          const path = span ? tickedSegment(x, sy(span.min), x, sy(span.max), ticks) : tickedSegment(x, 0, x, dims.height, 0);
+          const path = span2 ? tickedSegment(x, sy(span2.min), x, sy(span2.max), ticks) : tickedSegment(x, 0, x, dims.height, 0);
           out.push({ kind: "path", path, stroke });
         } else {
           const y = sy(g.offset);
           if (y < -lineWidth || y > dims.height + lineWidth) continue;
-          const path = span ? tickedSegment(sx(span.min), y, sx(span.max), y, ticks) : tickedSegment(0, y, dims.width, y, 0);
+          const path = span2 ? tickedSegment(sx(span2.min), y, sx(span2.max), y, ticks) : tickedSegment(0, y, dims.width, y, 0);
           out.push({ kind: "path", path, stroke });
         }
       }
@@ -284,9 +301,9 @@ function gapBetween(a, b, axis) {
   if (shared === null) return null;
   return { axis, min: hi(a, axis), max: lo(b, axis), at: (shared[0] + shared[1]) / 2 };
 }
-function hitsStrip(g, b, span) {
+function hitsStrip(g, b, span2) {
   const c = cross(g.axis);
-  return lo(b, g.axis) < g.max - EPS2 && hi(b, g.axis) > g.min + EPS2 && lo(b, c) < span[1] - EPS2 && hi(b, c) > span[0] + EPS2;
+  return lo(b, g.axis) < g.max - EPS2 && hi(b, g.axis) > g.min + EPS2 && lo(b, c) < span2[1] - EPS2 && hi(b, c) > span2[0] + EPS2;
 }
 function measureGaps(targets, axis) {
   return measureGapSpans(targets, axis).map((m) => m.gap);
@@ -302,9 +319,9 @@ function measureGapSpans(targets, axis) {
     }
     if (next === null) continue;
     const gap = gapBetween(a, next, axis);
-    const span = overlap(a, next, cross(axis));
-    if (targets.some((t) => t !== a && t !== next && hitsStrip(gap, t, span))) continue;
-    out.push({ gap, span });
+    const span2 = overlap(a, next, cross(axis));
+    if (targets.some((t) => t !== a && t !== next && hitsStrip(gap, t, span2))) continue;
+    out.push({ gap, span: span2 });
   }
   return out.sort((p, q) => p.gap.min - q.gap.min || p.gap.at - q.gap.at);
 }
@@ -448,9 +465,16 @@ function landedShift(q, delta) {
 
 // src/sources/grid.ts
 function gridSnapSource(opts) {
-  const pitch = resolveAxes(opts.spacing, opts.unitSystem);
+  const { scopes } = opts;
+  const rootPitch = scopes ? scopedGridPitch(opts.spacing, scopes, [scopes.root]) : resolveAxes(opts.spacing, opts.unitSystem);
+  const pitchFor = (q) => {
+    if (!scopes || !q.scene) return rootPitch;
+    if (q.ids?.length) return scopedGridPitch(opts.spacing, scopes, sceneSharedUnitScopes(q.scene, q.ids.map(asNodeId), scopes.root));
+    if (q.parent === void 0) return rootPitch;
+    return scopedGridPitch(opts.spacing, scopes, sceneUnitScopes(q.scene, asNodeId(q.parent), scopes.root, { inclusive: true }));
+  };
   const o = opts.origin ?? { x: 0, y: 0 };
-  const lines = (v, axis, plane) => {
+  const lines = (v, axis, pitch, plane) => {
     const s = plane ? plane.scale[axis] : 1;
     const near = roundToGridOn(v - o[axis] * s, axis, pitch[axis], plane) + o[axis] * s;
     const step = pitch[axis] * s;
@@ -462,9 +486,10 @@ function gridSnapSource(opts) {
     reachPx: Infinity,
     roles: ["origin", "pointer"],
     *collect(q) {
+      const pitch = pitchFor(q);
       for (const p of q.probes) {
         for (const axis of ["x", "y"]) {
-          for (const at of lines(p.at[axis], axis, q.plane ?? null)) yield { probe: p.id, locus: axisLine(axis, at, p.at) };
+          for (const at of lines(p.at[axis], axis, pitch, q.plane ?? null)) yield { probe: p.id, locus: axisLine(axis, at, p.at) };
         }
       }
     }
@@ -496,16 +521,23 @@ function stretchSpan(g, min, max) {
   if (g === null || g.span === void 0) return g;
   return { ...g, span: { min: Math.min(g.span.min, min), max: Math.max(g.span.max, max) } };
 }
-function targetIds(scene, exclude) {
-  if (exclude.length > 0) return siblingIds(scene, exclude);
+function visibleRoots(scene) {
   const gates = nodeGates(scene);
   return scene.roots.filter((id) => !gates.hidden(id));
 }
-function targetBoxes(q, scene) {
+function targetIds(scene, exclude, filter) {
+  const ids = exclude.length > 0 ? siblingIds(scene, exclude) : visibleRoots(scene);
+  if (!filter) return ids;
+  return ids.filter((id) => {
+    const node = scene.get(id);
+    return node !== void 0 && filter(node);
+  });
+}
+function targetBoxes(q, scene, filter) {
   const drawn = q.drawnBox;
-  return drawn ? targetIds(scene, q.exclude).flatMap((id) => drawn(id) ?? []) : [];
+  return drawn ? targetIds(scene, q.exclude, filter).flatMap((id) => drawn(id) ?? []) : [];
 }
-function cachedPerScene(derive) {
+function cachedPerScene(derive, filter) {
   let key = null;
   let value = null;
   return (q) => {
@@ -514,7 +546,7 @@ function cachedPerScene(derive) {
     const version = scene.getVersion();
     const exclude = q.exclude.join("\n");
     if (key === null || key.scene !== scene || key.version !== version || key.exclude !== exclude) {
-      value = derive(targetBoxes(q, scene));
+      value = derive(targetBoxes(q, scene, filter));
       key = { scene, version, exclude };
     }
     return value;
@@ -538,13 +570,13 @@ function* inReach(lines, v, reach) {
 }
 var cross2 = (a) => a === "x" ? "y" : "x";
 function lineMark(g, extent, color) {
-  const span = stretchSpan(g, extent[0], extent[1])?.span ?? { min: extent[0], max: extent[1] };
-  const ends = g.axis === "x" ? { from: { x: g.offset, y: span.min }, to: { x: g.offset, y: span.max } } : { from: { x: span.min, y: g.offset }, to: { x: span.max, y: g.offset } };
+  const span2 = stretchSpan(g, extent[0], extent[1])?.span ?? { min: extent[0], max: extent[1] };
+  const ends = g.axis === "x" ? { from: { x: g.offset, y: span2.min }, to: { x: g.offset, y: span2.max } } : { from: { x: span2.min, y: g.offset }, to: { x: span2.max, y: g.offset } };
   return { kind: "line", ...ends, ...color === void 0 ? {} : { color } };
 }
 function alignmentSnapSource(opts = {}) {
   const page = () => (typeof opts.page === "function" ? opts.page() : opts.page) ?? void 0;
-  const fromScene = cachedPerScene((boxes) => indexLines(deriveAlignmentGuides(boxes)));
+  const fromScene = cachedPerScene((boxes) => indexLines(deriveAlignmentGuides(boxes)), opts.filter);
   const linesFor = (q) => {
     const pageBox = page();
     const own = opts.getCandidates ? indexLines(opts.getCandidates()) : fromScene(q);
@@ -591,7 +623,7 @@ function gapMark(g, color) {
   return { kind: "gap", ...ends, value: g.max - g.min, ...color === void 0 ? {} : { color } };
 }
 function spacingSnapSource(opts = {}) {
-  const fromScene = cachedPerScene(measureAll);
+  const fromScene = cachedPerScene(measureAll, opts.filter);
   return {
     id: "spacing",
     ...opts.reachPx === void 0 ? {} : { reachPx: opts.reachPx },
@@ -656,8 +688,8 @@ function measureAxis(from, to, axis, out) {
     push(min, max, at2);
     if (!shares) {
       const edge = before ? lo2(to, axis) : hi2(to, axis);
-      const span = at2 < lo2(to, c) ? { min: at2, max: lo2(to, c) } : { min: hi2(to, c), max: at2 };
-      out.leaders.push({ id: `distance:${axis}`, axis, offset: edge, span });
+      const span2 = at2 < lo2(to, c) ? { min: at2, max: lo2(to, c) } : { min: hi2(to, c), max: at2 };
+      out.leaders.push({ id: `distance:${axis}`, axis, offset: edge, span: span2 });
     }
     return;
   }
@@ -756,7 +788,11 @@ function distanceReadout(opts = {}) {
 function createSpacingHintsPreset(opts = {}) {
   const id = opts.id ?? "spacingHints";
   const color = opts.color === void 0 ? {} : { color: opts.color };
-  const own = { ...color, ...opts.tolerance === void 0 ? {} : { reachPx: opts.tolerance } };
+  const own = {
+    ...color,
+    ...opts.filter === void 0 ? {} : { filter: opts.filter },
+    ...opts.tolerance === void 0 ? {} : { reachPx: opts.tolerance }
+  };
   const snapSources = [
     ...opts.spacing ?? true ? [spacingSnapSource(own)] : [],
     ...opts.align ?? false ? [alignmentSnapSource(own)] : []
@@ -1538,6 +1574,6 @@ function ringSlots(opts = {}) {
   };
 }
 
-export { alignmentSnapSource, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, createSpacingHintsPreset, deriveAlignmentGuides, distanceReadout, freeform, gridSlots, gridSnapSource, guideSnapSource, matchSpacing, measureDistances, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, ringSlots, roundToCell, rowSlots, sequenceLayout, siblingBounds, slots, snapPoint, spacingSnapSource, tileGrid, useGridCellHover, useGuides, worldBoundsOf, worldUnionOf };
+export { alignmentSnapSource, cellAt, containedThenNearest, createCellHighlightLayer, createGridLayer, createGuidesLayer, createSpacingHintsPreset, deriveAlignmentGuides, distanceReadout, freeform, gridSlots, gridSnapSource, guideSnapSource, matchSpacing, measureDistances, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, ringSlots, roundToCell, rowSlots, scopedGridPitch, sequenceLayout, siblingBounds, slots, snapPoint, spacingSnapSource, tileGrid, useGridCellHover, useGuides, worldBoundsOf, worldUnionOf };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map