@canvus/core 0.1.0

package/dist/layout.js

@@ -0,0 +1,278 @@
+// ─────────────────────────────────────────────────────────────
+// canvus/src/layout.ts
+// Layout Introspection Engine — Detects CSS layout modes and
+// extracts structural metadata from live Shadow DOM elements.
+//
+// All functions read from `getComputedStyle()` and do not
+// mutate the DOM. Results are used by the overlay renderer to
+// draw layout-aware visual badges, direction arrows, and grid
+// track lines.
+// ─────────────────────────────────────────────────────────────
+// ── Detection Functions ─────────────────────────────────────
+/**
+ * Detects the CSS layout mode and properties of an element.
+ *
+ * Reads `getComputedStyle()` to extract the resolved display
+ * mode, flex direction, gap, alignment, and grid template values.
+ *
+ * @param element - The DOM element to inspect.
+ * @returns Complete `LayoutInfo` descriptor.
+ */
+export function detectLayout(element) {
+    const cs = getComputedStyle(element);
+    const display = cs.display;
+    // Resolve display to our LayoutMode enum.
+    const mode = resolveLayoutMode(display);
+    // Flex properties.
+    const isFlex = mode === "flex" || mode === "inline-flex";
+    const direction = isFlex
+        ? cs.flexDirection
+        : null;
+    const wrap = isFlex
+        ? cs.flexWrap
+        : null;
+    // Gap (works for flex and grid).
+    const rowGap = parseFloat(cs.rowGap) || 0;
+    const columnGap = parseFloat(cs.columnGap) || 0;
+    // Alignment.
+    const alignItems = cs.alignItems;
+    const justifyContent = cs.justifyContent;
+    // Grid properties.
+    const isGrid = mode === "grid" || mode === "inline-grid";
+    const gridTemplateColumns = isGrid ? cs.gridTemplateColumns : null;
+    const gridTemplateRows = isGrid ? cs.gridTemplateRows : null;
+    const gridAutoFlow = isGrid ? cs.gridAutoFlow : null;
+    return {
+        mode,
+        direction,
+        wrap,
+        gap: { row: rowGap, column: columnGap },
+        alignItems,
+        justifyContent,
+        gridTemplateColumns,
+        gridTemplateRows,
+        gridAutoFlow,
+    };
+}
+/**
+ * Returns the primary flow axis for a layout container.
+ *
+ * - Flex row → "x" (horizontal)
+ * - Flex column → "y" (vertical)
+ * - Grid row (default auto-flow) → "x"
+ * - Block → "y" (vertical stacking)
+ *
+ * @param info - The layout info to inspect.
+ * @returns "x" for horizontal flow, "y" for vertical flow.
+ */
+export function getFlowAxis(info) {
+    if (info.mode === "flex" || info.mode === "inline-flex") {
+        return info.direction === "column" || info.direction === "column-reverse"
+            ? "y"
+            : "x";
+    }
+    if (info.mode === "grid" || info.mode === "inline-grid") {
+        return info.gridAutoFlow?.includes("column") ? "x" : "y";
+    }
+    // Block, inline: vertical stacking.
+    return "y";
+}
+/**
+ * Returns the flow direction sign for a layout container.
+ *
+ * `1` for normal direction, `-1` for reverse.
+ * Useful for computing insertion positions.
+ */
+export function getFlowSign(info) {
+    if (info.direction === "row-reverse" || info.direction === "column-reverse") {
+        return -1;
+    }
+    return 1;
+}
+/**
+ * Detects the position and size of each child element's slot
+ * within a container, measured relative to the container's
+ * padding box.
+ *
+ * This uses `getBoundingClientRect()` for accuracy, then
+ * converts to container-relative coordinates.
+ *
+ * @param container - The parent DOM element.
+ * @returns Array of `ChildSlot` objects, one per child element.
+ */
+export function detectChildSlots(container) {
+    const slots = [];
+    const containerRect = container.getBoundingClientRect();
+    const cs = getComputedStyle(container);
+    const padLeft = parseFloat(cs.paddingLeft) || 0;
+    const padTop = parseFloat(cs.paddingTop) || 0;
+    const children = container.children;
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childRect = child.getBoundingClientRect();
+        slots.push({
+            index: i,
+            rect: {
+                x: childRect.left - containerRect.left - padLeft,
+                y: childRect.top - containerRect.top - padTop,
+                width: childRect.width,
+                height: childRect.height,
+            },
+        });
+    }
+    return slots;
+}
+/**
+ * Parses grid track values from a resolved `grid-template-columns`
+ * or `grid-template-rows` string into an array of `GridTrack` objects.
+ *
+ * The browser resolves templates like `1fr 2fr 100px` into
+ * computed pixel values like `200px 400px 100px`. This function
+ * parses those resolved values, accounting for the layout gap between tracks.
+ *
+ * @param templateValue - The resolved CSS grid template string
+ *                         (e.g. "200px 400px 100px").
+ * @param gap           - The layout gap in pixels between tracks.
+ * @returns Array of grid tracks with start offsets and sizes.
+ */
+export function parseGridTracks(templateValue, gap = 0) {
+    const tracks = [];
+    // The resolved value is space-separated pixel values like "200px 400px 100px".
+    // Filter out named grid lines (e.g. "[start]") which appear in brackets.
+    const parts = templateValue
+        .replace(/\[.*?\]/g, "") // Remove grid line names.
+        .trim()
+        .split(/\s+/)
+        .filter(p => p.length > 0);
+    let offset = 0;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const size = parseFloat(part) || 0;
+        if (i > 0) {
+            offset += gap;
+        }
+        tracks.push({ start: offset, size });
+        offset += size;
+    }
+    return tracks;
+}
+/**
+ * Maps a padding-box relative coordinate (x, y) to the grid cell indices (1-indexed).
+ *
+ * @param x - X coordinate relative to container padding edge.
+ * @param y - Y coordinate relative to container padding edge.
+ * @param columns - Parsed column tracks.
+ * @param rows - Parsed row tracks.
+ * @param colGap - Column gap.
+ * @param rowGap - Row gap.
+ * @returns { col: number, row: number } (1-indexed, matching CSS grid-column-start/grid-row-start).
+ */
+export function getGridCellAt(x, y, columns, rows, colGap, rowGap) {
+    // Find column index (1-indexed)
+    let col = 1;
+    for (let i = 0; i < columns.length; i++) {
+        const c = columns[i];
+        const colEnd = c.start + c.size + colGap / 2;
+        if (x <= colEnd) {
+            col = i + 1;
+            break;
+        }
+        col = i + 1;
+    }
+    // Find row index (1-indexed)
+    let row = 1;
+    for (let i = 0; i < rows.length; i++) {
+        const r = rows[i];
+        const rowEnd = r.start + r.size + rowGap / 2;
+        if (y <= rowEnd) {
+            row = i + 1;
+            break;
+        }
+        row = i + 1;
+    }
+    return { col, row };
+}
+/**
+ * Computes the canvas-space bounding rect of a grid area span.
+ *
+ * @param containerRect - The parent container's canvas-space bounding box.
+ * @param padLeft - Container padding-left.
+ * @param padTop - Container padding-top.
+ * @param colStart - 1-based column start index.
+ * @param rowStart - 1-based row start index.
+ * @param colSpan - Column span.
+ * @param rowSpan - Row span.
+ * @param columns - Parsed column tracks.
+ * @param rows - Parsed row tracks.
+ * @returns The bounding Rect in canvas-space.
+ */
+export function getGridAreaRect(containerRect, padLeft, padTop, colStart, rowStart, colSpan, rowSpan, columns, rows) {
+    const colIdx = Math.max(1, Math.min(colStart, columns.length)) - 1;
+    const rowIdx = Math.max(1, Math.min(rowStart, rows.length)) - 1;
+    const startCol = columns[colIdx] ?? { start: 0, size: 0 };
+    const startRow = rows[rowIdx] ?? { start: 0, size: 0 };
+    const endColIdx = Math.max(1, Math.min(colStart + colSpan - 1, columns.length)) - 1;
+    const endRowIdx = Math.max(1, Math.min(rowStart + rowSpan - 1, rows.length)) - 1;
+    const endCol = columns[endColIdx] ?? startCol;
+    const endRow = rows[endRowIdx] ?? startRow;
+    const x = containerRect.x + padLeft + startCol.start;
+    const y = containerRect.y + padTop + startRow.start;
+    const width = (endCol.start + endCol.size) - startCol.start;
+    const height = (endRow.start + endRow.size) - startRow.start;
+    return { x, y, width, height };
+}
+/**
+ * Returns a short, human-readable label for a layout mode.
+ * Used for layout badge overlays.
+ *
+ * @param info - The layout info to label.
+ * @returns A concise string like "FLEX →", "FLEX ↓", "GRID", "BLOCK".
+ */
+export function getLayoutLabel(info) {
+    switch (info.mode) {
+        case "flex":
+        case "inline-flex": {
+            const arrow = info.direction === "column"
+                ? "↓"
+                : info.direction === "column-reverse"
+                    ? "↑"
+                    : info.direction === "row-reverse"
+                        ? "←"
+                        : "→";
+            return `FLEX ${arrow}`;
+        }
+        case "grid":
+        case "inline-grid":
+            return "GRID";
+        case "inline":
+            return "INLINE";
+        case "block":
+            return "BLOCK";
+        default:
+            return "NONE";
+    }
+}
+// ── Private Helpers ─────────────────────────────────────────
+/**
+ * Maps a CSS `display` value to our `LayoutMode` enum.
+ * Handles compound values like "inline-flex", "inline-grid".
+ */
+function resolveLayoutMode(display) {
+    // Normalize: CSS can return compound values like "inline flex" or "block grid".
+    const d = display.toLowerCase().trim();
+    if (d.includes("inline-flex") || d.includes("inline flex"))
+        return "inline-flex";
+    if (d.includes("inline-grid") || d.includes("inline grid"))
+        return "inline-grid";
+    if (d.includes("flex"))
+        return "flex";
+    if (d.includes("grid"))
+        return "grid";
+    if (d === "inline" || d === "inline-block" || d.includes("inline"))
+        return "inline";
+    if (d === "none")
+        return "none";
+    // Everything else (block, table, list-item, etc.) → block.
+    return "block";
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"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"}

package/dist/matrix.d.ts

@@ -0,0 +1,168 @@
+import type { Rect, Vec2, ViewportMatrix } from "./types.js";
+/**
+ * Projects a raw screen-space pointer coordinate (e.g. `MouseEvent.clientX/Y`)
+ * into the infinite canvas coordinate space, accounting for:
+ *   1. The canvas element's own position within the page (`canvasRect`).
+ *   2. The current pan offset (`viewport.offsetX/Y`).
+ *   3. The current zoom scale (`viewport.scale`).
+ *
+ * Derivation:
+ *   screenX = canvasX * scale + offsetX + canvasRect.x
+ *   ⟹ canvasX = (clientX - canvasRect.x - offsetX) / scale
+ *
+ * @param clientX - `MouseEvent.clientX` (viewport-relative screen pixel).
+ * @param clientY - `MouseEvent.clientY` (viewport-relative screen pixel).
+ * @param viewport - Current affine viewport transform state.
+ * @param canvasRect - Bounding rect of the `<canvas>` element on screen.
+ * @returns The corresponding point in canvas (world) space.
+ */
+export declare function screenToCanvas(clientX: number, clientY: number, viewport: Readonly<ViewportMatrix>, canvasRect: Readonly<Rect>): Vec2;
+/**
+ * Projects a canvas-space coordinate back to absolute screen pixels,
+ * the algebraic inverse of `screenToCanvas`.
+ *
+ * Derivation:
+ *   screenX = canvasX * scale + offsetX + canvasRect.x
+ *
+ * @param canvasX - X position in canvas (world) space.
+ * @param canvasY - Y position in canvas (world) space.
+ * @param viewport - Current affine viewport transform state.
+ * @param canvasRect - Bounding rect of the `<canvas>` element on screen.
+ * @returns The corresponding point in screen (client) space.
+ */
+export declare function canvasToScreen(canvasX: number, canvasY: number, viewport: Readonly<ViewportMatrix>, canvasRect: Readonly<Rect>): Vec2;
+/**
+ * Computes a new `ViewportMatrix` after applying a zoom delta
+ * anchored precisely at the cursor's current screen position.
+ *
+ * The key invariant: the canvas-space point directly beneath the
+ * cursor must map to the *exact same screen pixel* before and
+ * after the zoom. This prevents the jarring "zoom drift" that
+ * occurs with naïve center-point scaling.
+ *
+ * ### Mathematical derivation
+ *
+ * Let `(cx, cy)` be the cursor in screen-space relative to the
+ * canvas element origin:
+ *   cx = clientX - canvasRect.x
+ *   cy = clientY - canvasRect.y
+ *
+ * Before zoom, the canvas-space point under the cursor is:
+ *   worldX = (cx - offsetX) / oldScale
+ *   worldY = (cy - offsetY) / oldScale
+ *
+ * After zoom with `newScale`, we require the same world point to
+ * project back to `(cx, cy)`:
+ *   cx = worldX * newScale + newOffsetX
+ *   cy = worldY * newScale + newOffsetY
+ *
+ * Solving for the new offsets:
+ *   newOffsetX = cx - worldX * newScale
+ *              = cx - ((cx - offsetX) / oldScale) * newScale
+ *              = cx * (1 - newScale / oldScale) + offsetX * (newScale / oldScale)
+ *
+ * Equivalently (and more numerically stable):
+ *   newOffsetX = cx - (cx - offsetX) * (newScale / oldScale)
+ *
+ * @param clientX     - `MouseEvent.clientX` at the zoom gesture origin.
+ * @param clientY     - `MouseEvent.clientY` at the zoom gesture origin.
+ * @param scaleDelta  - Multiplicative scale factor to apply (e.g. 1.1 for zoom-in).
+ * @param viewport    - The current viewport transform state before zooming.
+ * @param canvasRect  - Bounding rect of the `<canvas>` element on screen.
+ * @returns A new `ViewportMatrix` with the anchored zoom applied.
+ */
+export declare function calculateZoomAnchor(clientX: number, clientY: number, scaleDelta: number, viewport: Readonly<ViewportMatrix>, canvasRect: Readonly<Rect>): ViewportMatrix;
+/**
+ * Convenience wrapper that converts a `WheelEvent.deltaY` value
+ * into a multiplicative scale factor and delegates to
+ * `calculateZoomAnchor`.
+ *
+ * Scroll-up (negative deltaY) zooms in, scroll-down zooms out.
+ * The sensitivity constant (0.001) yields a smooth, non-jarring
+ * zoom curve across trackpad and discrete-notch scroll wheels.
+ *
+ * @param clientX    - `MouseEvent.clientX` at the wheel event.
+ * @param clientY    - `MouseEvent.clientY` at the wheel event.
+ * @param deltaY     - `WheelEvent.deltaY` (positive = scroll down = zoom out).
+ * @param viewport   - Current viewport state.
+ * @param canvasRect - Canvas element bounding rect.
+ * @returns A new `ViewportMatrix` with the wheel-zoom applied.
+ */
+export declare function applyWheelZoom(clientX: number, clientY: number, deltaY: number, viewport: Readonly<ViewportMatrix>, canvasRect: Readonly<Rect>, isPinch?: boolean): ViewportMatrix;
+/**
+ * Applies a screen-space pan delta to the viewport offset.
+ * Typically driven by pointer-move events while spacebar is held
+ * or middle-mouse is pressed.
+ *
+ * @param dx - Horizontal screen-pixel delta (`e.movementX`).
+ * @param dy - Vertical screen-pixel delta (`e.movementY`).
+ * @param viewport - Current viewport state.
+ * @returns A new `ViewportMatrix` with the pan offset applied.
+ */
+export declare function applyPan(dx: number, dy: number, viewport: Readonly<ViewportMatrix>): ViewportMatrix;
+/**
+ * Axis-Aligned Bounding Box (AABB) point-inclusion test.
+ *
+ * Returns `true` if the point `(x, y)` lies within (or exactly on
+ * the boundary of) the rectangle described by `bounds`.
+ *
+ * Both coordinates and bounds should be in the same space
+ * (typically canvas-space after `screenToCanvas` conversion).
+ *
+ * @param x - Point X coordinate.
+ * @param y - Point Y coordinate.
+ * @param bounds - The axis-aligned bounding rectangle to test against.
+ * @returns Whether the point is inside or on the edge of `bounds`.
+ */
+export declare function isPointInElement(x: number, y: number, bounds: Readonly<Rect>): boolean;
+/**
+ * Determines which `WebHTMLNode` (if any) is hit by a canvas-space
+ * point, respecting z-order (last in the array = topmost).
+ *
+ * @param x - Canvas-space X coordinate.
+ * @param y - Canvas-space Y coordinate.
+ * @param elements - Array of elements with `id` and bounding `Rect`.
+ * @returns The `id` of the topmost hit element, or `null` if none.
+ */
+export declare function hitTestElements(x: number, y: number, elements: ReadonlyArray<Readonly<{
+    id: string;
+    currentRect: Rect | null;
+}>>): string | null;
+/**
+ * Computes the screen-space positions of all 8 resize anchor
+ * handles for a given element bounding box.
+ *
+ * Returns an object keyed by anchor direction with the
+ * corresponding screen-space `Vec2` position of each handle center.
+ *
+ * @param bounds    - The element's bounding rect in canvas-space.
+ * @param viewport  - Current viewport transform.
+ * @param canvasRect - Canvas element bounding rect on screen.
+ * @returns Record mapping each anchor to its screen-space center point.
+ */
+export declare function getAnchorPositions(bounds: Readonly<Rect>, viewport: Readonly<ViewportMatrix>, canvasRect: Readonly<Rect>): Record<"nw" | "n" | "ne" | "e" | "se" | "s" | "sw" | "w", Vec2>;
+/** Clamps a scale value to the allowed zoom range. */
+export declare function clampScale(s: number): number;
+/**
+ * Linearly interpolates between two values.
+ * Useful for animated viewport transitions.
+ *
+ * @param a - Start value.
+ * @param b - End value.
+ * @param t - Interpolation factor in [0, 1].
+ */
+export declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Linearly interpolates between two `ViewportMatrix` states.
+ * Useful for smooth animated zoom/pan transitions.
+ *
+ * @param from - Starting viewport.
+ * @param to   - Target viewport.
+ * @param t    - Interpolation factor in [0, 1].
+ */
+export declare function lerpViewport(from: Readonly<ViewportMatrix>, to: Readonly<ViewportMatrix>, t: number): ViewportMatrix;
+/**
+ * Checks if two axis-aligned bounding rectangles intersect.
+ */
+export declare function rectsIntersect(r1: Readonly<Rect>, r2: Readonly<Rect>): boolean;
+//# sourceMappingURL=matrix.d.ts.map

package/dist/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../src/matrix.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAK7D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,GACzB,IAAI,CAKN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,GACzB,IAAI,CAKN;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,GACzB,cAAc,CAmBhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,EAC1B,OAAO,GAAE,OAAe,GACvB,cAAc,CAWhB;AAID;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,GACjC,cAAc,CAMhB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,GACrB,OAAO,CAOT;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC,GAC1E,MAAM,GAAG,IAAI,CASf;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EACtB,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,GACzB,MAAM,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,EAAE,IAAI,CAAC,CAsBjE;AAID,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,EAC9B,EAAE,EAAE,QAAQ,CAAC,cAAc,CAAC,EAC5B,CAAC,EAAE,MAAM,GACR,cAAc,CAMhB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAO9E"}