@weasel-js/guides 1.13.0-rc.0 → 1.14.0

package/README.md

@@ -27,24 +27,24 @@ A grid you can see and snap to:
 
 ```tsx
 import { SceneCanvas } from '@weasel-js/core';
-import { createGridLayer, gridSnapSource } from '@weasel-js/guides';
+import { createGridPreset } from '@weasel-js/guides';
 
-const grid = createGridLayer({ spacing: 20, bounds: () => ({ x: 0, y: 0, width: 800, height: 600 }) });
-const snap = { sources: [gridSnapSource({ spacing: 20 })] };
+const grid = createGridPreset({ spacing: 20 });
 
-<SceneCanvas
-  /* … */
-  snap={snap}
-  layers={{ grid: { layer: grid } }}
-/>;
+<SceneCanvas /* … */ features={['draw', grid]} />;
 ```
 
-The grid source snaps every snapping gesture — move, resize, insert, the pen —
-and, being a fallback, gives way on any axis a real target in reach claims.
+The preset draws the grid in the `grid` slot and snaps every snapping gesture
+to it — move, resize, insert, the pen — and, being a fallback, its snap gives
+way on any axis a real target in reach claims. It takes every `createGridLayer`
+option, and `snap: false` to draw without snapping. The layer and the snap
+source it is built from, `createGridLayer` and `gridSnapSource`, go to
+`<SceneCanvas layers>` and `snap.sources` on their own where a canvas wants
+only one of them.
 
 | Area | Exports |
 |---|---|
-| Grid | `createGridLayer`, `createCellHighlightLayer`, `useGridCellHover`, `pointToGridCell`, `roundToCell` |
+| Grid | `createGridPreset`, `createGridLayer`, `createCellHighlightLayer`, `useGridCellHover`, `pointToGridCell`, `roundToCell` |
 | Guides | `useGuides`, `createGuidesLayer`, `deriveAlignmentGuides`, `matchSpacing`, `measureGaps`, `siblingBounds`, `worldBoundsOf`, `worldUnionOf` |
 | Snap sources | `gridSnapSource`, `guideSnapSource`, `alignmentSnapSource`, `spacingSnapSource`, for `<SceneCanvas snap={{ sources }}>` or a preset's `snapSources` |
 | Spacing hints | `createSpacingHintsPreset` (below), `distanceReadout`, `measureDistances` |

package/dist/index.d.ts

@@ -1,10 +1,94 @@
 import { RefObject } from 'react';
-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';
+import { UnitScope, Scene, NodeId, PlaneValue, PlaneUnits, PerAxis, ViewTransform, View, Dims, CommandStroke, RenderLayer, CommandFill, SnapSource, FeaturePreset, Bounds, PlaneMap, PoseDescriptor, SceneNode, SurfaceContribution, LayoutSnap, LayoutStrategy, LayoutContainer, Vec2, ContainerBounds, LayoutChild } from '@weasel-js/core';
+import { Affine, Rect as Rect$1 } from '@weasel-js/geom';
 
 /** Round `value` to the nearest multiple of `cellSize`. Returns 0 when the result would be -0. */
 declare function roundToCell(value: number, cellSize: number): number;
 
+type Point$1 = {
+    x: number;
+    y: number;
+};
+/** A container that declares its own unit scope, where a grid draws and
+ *  hit-tests that scope's lattice instead of its parent's. */
+interface GridRegion {
+    /** The container's outline in world units, as a closed polygon. */
+    outline: readonly Point$1[];
+    /** The scopes its lattice is read in, outermost first, rooted at the
+     *  grid's `scopes.root`, the container's own scope last. */
+    chain: readonly UnitScope[];
+    /** Scoped containers inside this one. */
+    regions?: readonly GridRegion[];
+    /** The container's frame, its own coordinates to world (`sceneBoxFrames`):
+     *  its lattice runs from the frame's origin along its axes, in its units,
+     *  as `gridSnapSource` snaps. Absent, the lattice is world-aligned and runs
+     *  through the grid's anchor. */
+    frame?: Affine;
+}
+/**
+ * Every container in `scene` declaring a unit scope, as `GridRegion`s nested
+ * the way the containers are, each in its box frame. `outlineOf` gives a
+ * node's world outline, or `null` to leave it, and every scope inside it,
+ * out; by default, a box pose's outline as it is drawn, and none for any
+ * other pose.
+ */
+declare function sceneGridRegions(scene: Scene<unknown, string, unknown>, root: UnitScope, outlineOf?: (id: NodeId) => readonly Point$1[] | null): GridRegion[];
+/** The innermost region holding `point`, or `null` outside them all. */
+declare function regionAt(regions: readonly GridRegion[] | undefined, point: Point$1): GridRegion | null;
+
+/** How a grid reads the unit scopes a scene's containers declare
+ *  (`GroupNode.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>;
+/**
+ * A grid's pitch in world units: read in `chain` (the root alone by default)
+ * when `scopes` is given, else against `unitSystem`. What every grid reader
+ * that takes both asks.
+ */
+declare function gridPitch(spacing: PlaneValue, unitSystem: PlaneUnits | undefined, scopes: GridScopes | undefined, chain?: readonly UnitScope[]): PerAxis<number>;
+
+/** A cell of a grid. `pitch` names the lattice it belongs to, in world units,
+ *  where a grid reads unit scopes; without it, the cell is the grid's own.
+ *  `frame` is that lattice's region's frame, the cell counted from its origin. */
+interface GridCell {
+    col: number;
+    row: number;
+    pitch?: PerAxis<number>;
+    frame?: Affine;
+}
+/** Where a grid reads unit scopes: `scopes`, and the containers declaring them. */
+interface GridScoping {
+    scopes: GridScopes;
+    regions?: readonly GridRegion[];
+}
+/**
+ * The integer cell `{col, row}` that contains `point`. Pair with
+ * `createCellHighlightLayer` (its `getCell` callback) to draw a snap-target
+ * preview that uses the same spacing as `gridSnapSource`. Given `scoped`,
+ * the cell is on the lattice of the innermost region holding `point`, and
+ * carries that lattice's `pitch`, and its `frame` where the region has one.
+ */
+declare function pointToGridCell(point: {
+    x: number;
+    y: number;
+}, spacing: PlaneValue, unitSystem?: PlaneUnits, origin?: {
+    x: number;
+    y: number;
+}, scoped?: GridScoping): GridCell;
+
 /**
  * Pointer-tracking glue that turns hover position into a grid cell, suitable
  * for dropping straight into `createCellHighlightLayer({ getCell })`.
@@ -30,32 +114,36 @@ interface UseGridCellHoverOptions {
         x: number;
         y: number;
     };
+    /** Read `spacing` in these scopes, as `createGridLayer` does: a cell inside
+     *  one of `regions` is on its scope's lattice and carries that `pitch`. */
+    scopes?: GridScopes;
+    /** The containers declaring scopes, read on every pointermove. */
+    regions?: () => readonly GridRegion[];
     /** 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;
+    onChange?: (cell: GridCell | 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;
+    cell: GridCell | null;
     /** Stable callback that returns the current cell — drop straight into
      *  `createCellHighlightLayer({ getCell })`. */
-    getCell: () => {
-        col: number;
-        row: number;
-    } | null;
+    getCell: () => GridCell | null;
 }
 /** Track which grid cell the pointer is over; pairs with `createCellHighlightLayer`. */
 declare function useGridCellHover(opts: UseGridCellHoverOptions): UseGridCellHoverReturn;
 
+/** An axis-aligned rectangle, in whatever coordinates a lattice is drawn in. */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
 /**
  * Grid overlay — a reusable render layer that draws a world-space grid with
  * optional finer subdivisions and accent lines every N cells.
@@ -77,18 +165,20 @@ interface GridLayerOpts {
     spacing: PlaneValue;
     /** Optional unit system for resolving tagged `spacing` values. */
     unitSystem?: PlaneUnits;
+    /** Read `spacing` in these scopes, in place of `unitSystem`: the root's
+     *  system outside every region, and each region's own scope inside it. */
+    scopes?: GridScopes;
+    /** The containers drawing their own scope's lattice, read every paint,
+     *  each cut out of the lattice around it and drawn in its own `frame`.
+     *  Read only with `scopes`; `sceneGridRegions` builds them from a scene. */
+    regions?: () => readonly GridRegion[];
     /**
      * The area to cover, in world units, read every paint with that paint's
      * view and canvas size. Lines start at its own `x`/`y`. Omitted, the grid
      * covers whatever the canvas shows, with its lines on world multiples of
      * `spacing` so they stay put as the view pans.
      */
-    bounds?: (view: View, dims: Dims) => {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
+    bounds?: (view: View, dims: Dims) => Rect;
     /** 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. */
@@ -120,50 +210,57 @@ interface CellHighlightLayerOpts {
         x: number;
         y: number;
     };
-    /** Cell to highlight, or `null` to skip drawing. */
-    getCell: () => {
-        col: number;
-        row: number;
-    } | null;
+    /** Cell to highlight, or `null` to skip drawing. A cell carrying its
+     *  lattice's `pitch` (`useGridCellHover` with `scopes`) is drawn at it,
+     *  and one carrying a `frame` is drawn in it, from its origin. */
+    getCell: () => GridCell | null;
     /** Fill for the highlighted cell. Defaults to a soft green. */
     fill?: CommandFill;
 }
 /** Build a `RenderLayer` that fills a single grid cell — typically a snap-target preview. */
 declare function createCellHighlightLayer(opts: CellHighlightLayerOpts): RenderLayer<unknown>;
 
-/**
- * The integer cell `{col, row}` that contains `point`. Pair with
- * `createCellHighlightLayer` (its `getCell` callback) to draw a snap-target
- * preview that uses the same spacing as `gridSnapSource`.
- */
-declare function pointToGridCell(point: {
-    x: number;
-    y: number;
-}, spacing: PlaneValue, unitSystem?: PlaneUnits, origin?: {
+type Point = {
     x: number;
     y: number;
-}): {
-    col: number;
-    row: number;
 };
+/** Options for `gridSnapSource`. */
+interface GridSnapSourceOptions {
+    /** The grid's pitch, or one per axis, in `unitSystem`'s units. */
+    spacing: PlaneValue;
+    /** 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. When that
+     *  scope is one container's, the lattice runs in its frame
+     *  (`SnapCollect.frameOf`): from its corner, turned as it is. */
+    scopes?: GridScopes;
+}
+/**
+ * A grid as snap targets: for each origin or pointer probe, the grid line on
+ * either side of it on each axis. Its reach is unlimited and it is a
+ * fallback, so it holds every axis no target claims and never displaces one.
+ * Its lines are the camera's, carried into the plane a gesture runs in.
+ */
+declare function gridSnapSource(opts: GridSnapSourceOptions): SnapSource;
 
-/** How a grid reads the unit scopes a scene's containers declare
- *  (`GroupNode.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;
+/** Options for `createGridPreset`: the grid's, and how it snaps. */
+interface GridPresetOptions extends GridLayerOpts {
+    /** Preset id. Default `'grid'`. */
+    id?: string;
+    /** Snap gestures to the grid's lines, on its `spacing`, `unitSystem` and
+     *  `scopes`; `origin` is where the snap lattice starts. `false` draws the
+     *  grid without snapping to it. Default on, from `(0, 0)`. */
+    snap?: false | Pick<GridSnapSourceOptions, 'origin'>;
 }
 /**
- * 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.
+ * A grid as one `<SceneCanvas features>` preset: the lattice drawn in the
+ * grid slot, and the snap source that pulls gestures onto it.
  */
-declare function scopedGridPitch(spacing: PlaneValue, scopes: GridScopes, chain: readonly UnitScope[]): PerAxis<number>;
+declare function createGridPreset(opts: GridPresetOptions): FeaturePreset;
 
 /**
  * Guide — a horizontal or vertical world-space line used as a snap target
@@ -361,31 +458,6 @@ declare function worldUnionOf(scene: Scene<unknown, string, unknown>, ids: Itera
  */
 declare function siblingBounds(scene: Scene<unknown, string, unknown>, ids: readonly NodeId[], opts?: SceneBoundsOptions): Bounds[];
 
-type Point = {
-    x: number;
-    y: number;
-};
-/** Options for `gridSnapSource`. */
-interface GridSnapSourceOptions {
-    /** The grid's pitch, or one per axis, in `unitSystem`'s units. */
-    spacing: PlaneValue;
-    /** 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
- * either side of it on each axis. Its reach is unlimited and it is a
- * fallback, so it holds every axis no target claims and never displaces one.
- * Its lines are the camera's, carried into the plane a gesture runs in.
- */
-declare function gridSnapSource(opts: GridSnapSourceOptions): SnapSource;
-
 /**
  * Ruler guides as snap targets: each guide within reach of an origin or
  * pointer probe is a line it may land on. Reads `getGuides` every frame, so
@@ -613,7 +685,7 @@ interface TileGridOptions<TPose> {
      *  writes `{ x, y, width, height }` into the dragged pose (assumes
      *  `RectPose`). `dragged` is the pre-drop pose of the child being placed —
      *  use it to preserve fields the cell rect doesn't carry (e.g. rotation). */
-    cellToPose?(cellRect: Rect, dragged: TPose): TPose;
+    cellToPose?(cellRect: Rect$1, 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
@@ -749,7 +821,7 @@ interface PackOptions<TPose> {
     /** Which index a drag means. Default `nearest()`. */
     snap?: LayoutSnap<TPose>;
     /** A child's box. Default reads `x`, `y`, `width`, and `height` off the pose. */
-    rectOf?(pose: TPose): Rect;
+    rectOf?(pose: TPose): Rect$1;
     /** `pose` with its box's top-left at `at`. Default writes `x` and `y`. */
     moveTo?(pose: TPose, at: {
         x: number;
@@ -778,7 +850,7 @@ interface QuadtreeOptions<TPose> {
     sizeOf?(pose: TPose): number;
     /** The pose a child takes in a cell. Default centers the child's own size
      *  in the cell and keeps every other field. */
-    cellToPose?(cell: Rect, pose: TPose): TPose;
+    cellToPose?(cell: Rect$1, pose: TPose): TPose;
     /** The point that decides which cell a child sits in. Default is the
      *  center of a `RectPose`, and the point itself for a point pose. */
     centerOf?(pose: TPose): {
@@ -791,7 +863,7 @@ interface QuadtreeCell {
     id: string;
     /** How many times the container was quartered to reach the cell. */
     depth: number;
-    rect: Rect;
+    rect: Rect$1;
 }
 /** A `quadtree` layout, which also reports the cells it has given out. */
 interface QuadtreeStrategy<TPose> extends LayoutStrategy<TPose> {
@@ -841,4 +913,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 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 };
+export { type AlignmentSnapSourceOptions, type Arrangement, type CellHighlightLayerOpts, type DeriveAlignmentGuidesOptions, type DistanceReadout, type DistanceReadoutContribution, type DistanceReadoutOptions, type FreeformOptions, type GridCell, type GridLayerOpts, type GridPresetOptions, type GridRegion, type GridScopes, type GridScoping, 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, createGridPreset, createGuidesLayer, createSpacingHintsPreset, deriveAlignmentGuides, distanceReadout, freeform, gridPitch, gridSlots, gridSnapSource, guideSnapSource, matchSpacing, measureDistances, measureGaps, nearest, nearestWithin, none, pack, perContainer, pointToGridCell, quadtree, regionAt, ringSlots, roundToCell, rowSlots, sceneGridRegions, scopedGridPitch, sequenceLayout, siblingBounds, slots, snapPoint, spacingSnapSource, tileGrid, useGridCellHover, useGuides, worldBoundsOf, worldUnionOf };