warp-grid/dist/index.d.ts

Create a complex grid, warped in 2D space and access data about its lines and cells

import { BoundingCurves } from 'coons-patch';
import { Curve } from 'coons-patch';
import { InterpolatePointOnCurve } from 'coons-patch';
import { InterpolatePointOnCurveFactory as InterpolatePointOnCurveFactory_2 } from '../..';
import { Point } from 'coons-patch';

/**
 * Defines bezier easing parameters for both axes of the grid.
 * All parameters must be in range [0,1].
 */
export declare interface BezierEasing {
    xAxis: BezierEasingParams;
    yAxis: BezierEasingParams;
}

/**
 * Control points array for a cubic Bezier curve.
 * All values must be in range [0,1].
 */
export declare type BezierEasingParams = [number, number, number, number];

export { BoundingCurves }

export declare enum CellBoundsOrder {
    TTB_LTR = "topToBottom-leftToRight",
    TTB_RTL = "topToBottom-rightToLeft",
    BTT_LTR = "bottomToTop-leftToRight",
    BTT_RTL = "bottomToTop-rightToLeft",
    LTR_TTB = "leftToRight-topToBottom",
    LTR_BTT = "leftToRight-bottomToTop",
    RTL_TTB = "rightToLeft-topToBottom",
    RTL_BTT = "rightToLeft-bottomToTop"
}

export { Curve }

/**
 * Configuration for retrieving cell bounds in the grid.
 */
export declare interface GetAllCellBoundsProps {
    /**
     * Returns bounds curves in sequential order when true.
     * @default false
     */
    makeBoundsCurvesSequential?: boolean;
    cellBoundsOrder?: CellBoundsOrder;
}

/**
 * Configuration for retrieving bounds of a specific cell.
 */
export declare interface GetCellBoundsConfig {
    cellBoundsOrder?: CellBoundsOrder;
}

/**
 * Parameters for retrieving a point within the grid space.
 * All coordinate values must be in range [0,1].
 */
export declare interface GetPointProps {
    u: number;
    v: number;
    uOpposite?: number;
    vOpposite?: number;
}

/**
 * Methods for interacting with and retrieving geometric data from the grid.
 */
export declare interface GridApi {
    /**
     * Returns a point at the specified grid coordinates. Results are memoized for
     * performance.
     * @param params The grid coordinates and options.
     * @returns The calculated grid point.
     * @throws ValidationError When coordinates are outside valid range.
     */
    getPoint: (params: GetPointProps) => Point;
    /**
     * Returns all points where grid lines intersect. Results are memoized for
     * performance.
     * @returns Array of intersection points.
     */
    getIntersections: () => Point[];
    /**
     * Returns horizontal grid lines organized in rows from top to bottom. Each
     * array element represents a row containing Bézier curves that form the
     * horizontal grid structure. Lines include top and bottom bounds. Results are
     * memoized for performance.
     */
    getLinesXAxis: () => Curve[][];
    /**
     * Returns vertical grid lines organized in rows from top to bottom. Each
     * array element represents a column containing Bézier curves that form the
     * vertical grid structure. Lines include left and right bounds. Results are
     * memoized for performance.
     */
    getLinesYAxis: () => Curve[][];
    /**
     * Returns all grid lines organized by axis. The returned object contains
     * arrays of Bézier curves representing horizontal lines (xAxis) and vertical
     * lines (yAxis). Results are memoized for performance.
     */
    getLines: () => LinesByAxis;
    /**
     * Returns the bounding curves for a specific cell. Results are memoized for
     * performance.
     * @param columnIdx Zero-based column index.
     * @param rowIdx Zero-based row index.
     * @param config Optional configuration.
     * @returns The cell's bounding curves.
     * @throws ValidationError When indices are out of bounds.
     */
    getCellBounds: (columnIdx: number, rowIdx: number, config?: GetCellBoundsConfig) => BoundingCurves;
    /**
     * Returns bounding curves for all cells in the grid. Results are memoized for
     * performance.
     * @param params Optional configuration.
     * @returns Array of cell bounds.
     */
    getAllCellBounds: (params?: GetAllCellBoundsProps) => BoundingCurves[];
}

/**
 * Configuration object defining the grid's structure and behavior.
 */
export declare interface GridDefinition {
    columns: StepDefinition;
    rows: StepDefinition;
    /**
     * Spacing between grid cells. Accepts pixels (number) or CSS units (string).
     * @default 0
     */
    gutter?: (number | string) | [number | string, number | string];
    /**
     * Strategy for interpolating points between grid lines.
     * @default 'linear'
     */
    interpolationStrategy?: InterpolationStrategy | InterpolatePointOnCurveFactory | [InterpolatePointOnCurveFactory, InterpolatePointOnCurveFactory];
    /**
     * Method for constructing lines between points.
     * @default 'bezier'
     */
    lineStrategy?: LineStrategy;
    /**
     * Curve interpolation precision.
     * @default 50
     */
    precision?: number;
    /**
     * Easing parameters for curve calculations.
     * @default [0, 0, 1, 1]
     */
    bezierEasing?: BezierEasing;
}

/**
 * Grid model containing boundary curves and layout information.
 */
export declare interface GridModel {
    boundingCurves: BoundingCurves;
    columns: Step[];
    rows: Step[];
    columnsNonGutter: Step[];
    rowsNonGutter: Step[];
}

/**
 * Interpolates a line in the U direction between two bounding curves.
 * @param boundingCurves The curves defining the grid space.
 * @param params Parameters for the interpolation.
 * @param interpolatePointOnCurveU Function to interpolate points along U axis.
 * @param interpolatePointOnCurveV Function to interpolate points along V axis.
 * @returns A curve representing the interpolated line.
 */
export declare type InterpolateLineU = (boundingCurves: BoundingCurves, params: InterpolationParamsU, interpolatePointOnCurveU: InterpolatePointOnCurve, interpolatePointOnCurveV: InterpolatePointOnCurve) => Curve;

/**
 * Interpolates a line in the V direction between two bounding curves.
 * @param boundingCurves The curves defining the grid space.
 * @param params Parameters for the interpolation.
 * @param interpolatePointOnCurveU Function to interpolate points along U axis.
 * @param interpolatePointOnCurveV Function to interpolate points along V axis.
 * @returns A curve representing the interpolated line.
 */
export declare type InterpolateLineV = (boundingCurves: BoundingCurves, params: InterpolationParamsV, interpolatePointOnCurveU: InterpolatePointOnCurve, interpolatePointOnCurveV: InterpolatePointOnCurve) => Curve;

export { InterpolatePointOnCurve }

export declare const interpolatePointOnCurveEvenlySpacedFactory: InterpolatePointOnCurveFactory_2;

/**
 * Creates a function that interpolates points along a curve based on the given
 * configuration.
 * @param {Object} config - The configuration object for the interpolation.
 * @param {number} config.precision - The precision level for the interpolation
 * calculations.
 * @param {BezierEasingParams} config.bezierEasing - The bezier curve parameters
 * for easing.
 * @returns {InterpolatePointOnCurve} A function that performs point
 * interpolation along the curve.
 */
export declare type InterpolatePointOnCurveFactory = (config: {
    precision: number;
    bezierEasing: BezierEasingParams;
}) => InterpolatePointOnCurve;

export declare const interpolatePointOnCurveLinearFactory: InterpolatePointOnCurveFactory_2;

/**
 * Parameters for interpolating a line in the U direction.
 */
export declare interface InterpolationParamsU extends ObjectWithStringKeys {
    uStart: number;
    uEnd: number;
    vStart: number;
    uOppositeStart: number;
    uOppositeEnd: number;
    vOppositeStart: number;
}

/**
 * Parameters for interpolating a line in the V direction.
 */
export declare interface InterpolationParamsV extends ObjectWithStringKeys {
    vStart: number;
    vEnd: number;
    uStart: number;
    vOppositeStart: number;
    vOppositeEnd: number;
    uOppositeStart: number;
}

export declare enum InterpolationStrategy {
    LINEAR = "linear",
    EVEN = "even"
}

/**
 * Collection of curves organized by axis.
 */
export declare interface LinesByAxis {
    xAxis: Curve[][];
    yAxis: Curve[][];
}

export declare enum LineStrategy {
    STRAIGHT_LINES = "straightLines",
    CURVES = "curves"
}

declare type ObjectWithStringKeys = Record<string, any>;

export { Point }

/**
 * Defines a single step in the grid's layout sequence.
 * Value must be positive.
 */
export declare interface Step {
    value: number | string;
    /**
     * Indicates a gutter space between cells when true.
     * @default false
     */
    isGutter?: boolean;
}

export declare type StepDefinition = number | UnprocessedStep[];

/**
 * Represents a raw step value before processing into a standardized Step
 * format. Can be a number, string, or an explicit Step object.
 */
export declare type UnprocessedStep = string | number | Step;

/**
 * Complete grid interface combining manipulation methods with model access.
 */
export declare interface WarpGrid extends GridApi {
    model: GridModel;
}

/**
 * Generates a warp grid based on the provided bounding curves and grid
 * definition.
 *
 * @param {BoundingCurves} boundingCurves - The curves that define the
 * boundaries of the grid.
 * @param {GridDefinition} gridDefinition - The definition of the grid, including
 * columns, rows, and gutter.
 * @returns {WarpGrid} The warp grid model and associated API functions.
 */
export declare const warpGrid: (boundingCurves: BoundingCurves, gridDefinition: GridDefinition) => WarpGrid;

export { }