Grid & Alignment

Grid Configuration

interface GridConfig {
    enabled: boolean;
    size: number;          // grid cell size in world units (default: 20)
    snapEnabled: boolean;
    snapThreshold: number; // snap distance in pixels (default: 5)
    visible: boolean;
}

createDefaultGridConfig

function createDefaultGridConfig(): GridConfig;
// Returns: { enabled: false, size: 20, snapEnabled: false, snapThreshold: 5, visible: false }

Grid Snapping

snapToGrid

Snaps a point to the nearest grid intersection. Returns the point unchanged if snapping is disabled.

function snapToGrid(point: Point, config: GridConfig): Point;

import { snapToGrid, createDefaultGridConfig } from '@hfu.digital/boardkit-core';

const config = { ...createDefaultGridConfig(), enabled: true, snapEnabled: true, size: 20 };
const snapped = snapToGrid({ x: 33, y: 47 }, config);
// { x: 40, y: 40 }

snapRectToGrid

Snaps a rectangle's top-left corner to the grid.

function snapRectToGrid(rect: Rect, config: GridConfig): Rect;

Alignment Guides

Alignment guides appear when moving elements to help align them with other elements on the canvas.

AlignmentGuide

interface AlignmentGuide {
    type: 'vertical' | 'horizontal';
    position: number;  // x for vertical, y for horizontal
    start: number;     // start of the guide line
    end: number;       // end of the guide line
}

findAlignmentGuides

Finds alignment guides for a moving element against all other elements. Checks edge-to-edge, edge-to-center, and center-to-center alignment.

function findAlignmentGuides(
    movingBounds: Rect,
    otherElements: Rect[],
    threshold?: number,   // default: 5
): AlignmentGuide[];

snapToAlignment

Snaps a moving element to the nearest alignment guide and returns the position delta to apply.

function snapToAlignment(
    movingBounds: Rect,
    otherElements: Rect[],
    threshold?: number,
): { dx: number; dy: number; guides: AlignmentGuide[] };

import { snapToAlignment } from '@hfu.digital/boardkit-core';

const { dx, dy, guides } = snapToAlignment(
    movingElementBounds,
    otherElementBounds,
    5,
);

// Apply the snap offset
const snappedX = movingElementBounds.x + dx;
const snappedY = movingElementBounds.y + dy;

// Render the active guides on the interactive canvas layer
for (const guide of guides) {
    // Draw guide line...
}

The alignment system checks 9 combinations per axis for each pair of elements:

Left ↔ Left, Left ↔ Right, Left ↔ Center
Right ↔ Left, Right ↔ Right, Right ↔ Center
Center ↔ Left, Center ↔ Right, Center ↔ Center

(And the same for top/bottom/center on the horizontal axis.)

Grid & Alignment

On this page