@kyralabs/m3e-shapes 0.0.0-stage → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,437 @@
+/**
+ * CornerRounding defines the amount and quality around a given vertex of a shape. [radius] defines
+ * the radius of the circle which forms the basis of the rounding for the vertex. [smoothing]
+ * defines the amount by which the curve is extended from the circular arc around the corner to the
+ * edge between vertices.
+ *
+ * Each corner of a shape can be thought of as either:
+ * - unrounded (with a corner radius of 0 and no smoothing)
+ * - rounded with only a circular arc (with smoothing of 0). In this case, the rounding around
+ *   the corner follows an approximated circular arc between the edges to adjacent vertices.
+ * - rounded with three curves: There is an inner circular arc and two symmetric flanking curves.
+ *   The flanking curves determine the curvature from the inner curve to the edges, with a value of
+ *   0 (no smoothing) meaning that it is purely a circular curve and a value of 1 meaning that the
+ *   flanking curves are maximized between the inner curve and the edges.
+ *
+ * @param radius a value of 0 or greater, representing the radius of the circle which defines the
+ *   inner rounding arc of the corner. A value of 0 indicates that the corner is sharp, or
+ *   completely unrounded. A positive value is the requested size of the radius. Note that this
+ *   radius is an absolute size that should relate to the overall size of its shape.
+ * @param smoothing the amount by which the arc is "smoothed" by extending the curve from the inner
+ *   circular arc to the edge between vertices. A value of 0 (no smoothing) indicates that the
+ *   corner is rounded by only a circular arc; there are no flanking curves. A value of 1 indicates
+ *   that there is no circular arc in the center; the flanking curves on either side meet at the
+ *   middle.
+ */
+declare class CornerRounding {
+    /** [Unrounded] has a rounding radius of zero, producing a sharp corner at a vertex. */
+    static readonly Unrounded: CornerRounding;
+    readonly radius: number;
+    readonly smoothing: number;
+    /** Both values are Kotlin `Float`s (rounded to float32). */
+    constructor(radius?: number, smoothing?: number);
+}
+
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** Interface for a function that can transform (rotate/scale/translate/etc.) points. */
+type PointTransformer = (x: number, y: number) => readonly [number, number];
+
+/**
+ * This class holds the anchor and control point data for a single cubic Bézier curve, with anchor
+ * points ([anchor0X], [anchor0Y]) and ([anchor1X], [anchor1Y]) at either end and control points
+ * ([control0X], [control0Y]) and ([control1X], [control1Y]) determining the slope of the curve
+ * between the anchor points.
+ */
+declare class Cubic {
+    /** Kotlin `FloatArray`: values are stored as float32. */
+    readonly points: Float32Array;
+    constructor(points?: ArrayLike<number>);
+    /** Creates a Cubic from its eight coordinates (the top-level Kotlin `Cubic(...)` factory). */
+    static of(anchor0X: number, anchor0Y: number, control0X: number, control0Y: number, control1X: number, control1Y: number, anchor1X: number, anchor1Y: number): Cubic;
+    static fromPoints(anchor0: Point, control0: Point, control1: Point, anchor1: Point): Cubic;
+    get anchor0X(): number;
+    get anchor0Y(): number;
+    get control0X(): number;
+    get control0Y(): number;
+    get control1X(): number;
+    get control1Y(): number;
+    get anchor1X(): number;
+    get anchor1Y(): number;
+    pointOnCurve(t: number): Point;
+    zeroLength(): boolean;
+    /**
+     * Fills [bounds] with `[minX, minY, maxX, maxY]`. With [approximate], the bounding box of all
+     * anchors and controls; otherwise the exact extrema (solving the derivative quadratic).
+     */
+    calculateBounds(bounds?: number[], approximate?: boolean): void;
+    /** Returns two Cubics, created by splitting this curve at the given distance of [t]. */
+    split(t: number): [Cubic, Cubic];
+    /** Utility function to reverse the control/anchor points for this curve. */
+    reverse(): Cubic;
+    plus(o: Cubic): Cubic;
+    times(x: number): Cubic;
+    div(x: number): Cubic;
+    toString(): string;
+    equals(other: unknown): boolean;
+    /** Transforms the points in this [Cubic] with the given [PointTransformer]. */
+    transformed(f: PointTransformer): Cubic;
+    /** Generates a bezier curve that is a straight line between the given anchor points. */
+    static straightLine(x0: number, y0: number, x1: number, y1: number): Cubic;
+    /**
+     * Generates a bezier curve that approximates a circular arc, with p0 and p1 as the starting and
+     * ending anchor points. The curve generated is the smallest of the two possible arcs around the
+     * entire 360-degree circle. Arcs of greater than 180 degrees should use more than one arc
+     * together. Note that p0 and p1 should be equidistant from the center.
+     */
+    static circularArc(centerX: number, centerY: number, x0: number, y0: number, x1: number, y1: number): Cubic;
+}
+/** This is a Mutable version of [Cubic], used mostly for performance critical paths. */
+declare class MutableCubic extends Cubic {
+    private transformOnePoint;
+    transform(f: PointTransformer): void;
+    interpolate(c1: Cubic, c2: Cubic, progress: number): void;
+}
+
+/**
+ * This class holds information about a corner (rounded or not) or an edge of a given polygon. The
+ * features of a Polygon can be used to manipulate the shape with more context of what the shape
+ * actually is, rather than simply manipulating the raw curves and lines which describe it.
+ */
+declare abstract class Feature {
+    readonly cubics: readonly Cubic[];
+    constructor(cubics: readonly Cubic[]);
+    abstract transformed(f: PointTransformer): Feature;
+    abstract toString(): string;
+}
+/**
+ * Edges have only a list of the cubic curves which make up the edge. Edges lie between corners
+ * and have no vertex or concavity; the curves are simply straight lines (represented by Cubic
+ * curves).
+ */
+declare class Edge extends Feature {
+    transformed(f: PointTransformer): Edge;
+    toString(): string;
+}
+/**
+ * Corners contain the list of cubic curves which describe how the corner is rounded (or not),
+ * plus the vertex at the corner (which the cubics may or may not pass through, depending on
+ * whether the corner is rounded) and a flag indicating whether the corner is convex. A regular
+ * polygon has all convex corners, while a star polygon generally (but not necessarily) has both
+ * convex (outer) and concave (inner) corners.
+ */
+declare class Corner extends Feature {
+    readonly vertex: Point;
+    readonly roundedCenter: Point;
+    readonly convex: boolean;
+    constructor(cubics: readonly Cubic[], vertex: Point, roundedCenter: Point, convex?: boolean);
+    transformed(f: PointTransformer): Corner;
+    toString(): string;
+}
+
+/**
+ * The RoundedPolygon class allows simple construction of polygonal shapes with optional rounding
+ * at the vertices. Polygons can be constructed with either the number of vertices desired or an
+ * ordered list of vertices.
+ */
+declare class RoundedPolygon {
+    readonly features: readonly Feature[];
+    readonly cubics: readonly Cubic[];
+    readonly centerX: number;
+    readonly centerY: number;
+    constructor(features: readonly Feature[], centerX: number, centerY: number);
+    /** Transforms (scales/translates/etc.) this [RoundedPolygon] with the given [PointTransformer]. */
+    transformed(f: PointTransformer): RoundedPolygon;
+    /**
+     * Creates a new RoundedPolygon, moving and resizing this one, so it is completely inside the
+     * (0, 0) -> (1, 1) square, centered if there extra space in one direction
+     */
+    normalized(): RoundedPolygon;
+    toString(): string;
+    /**
+     * Like [calculateBounds], this function calculates the axis-aligned bounds of the object and
+     * returns that rectangle. But this function determines the max dimension of the shape (by
+     * calculating the distance from its center to the start and midpoint of each curve) and returns
+     * a square which can be used to hold the object in any rotation.
+     */
+    calculateMaxBounds(bounds?: number[]): number[];
+    /**
+     * Calculates the axis-aligned bounds of the object. With [approximate] (the default), uses the
+     * bounding box of every anchor and control point.
+     */
+    calculateBounds(bounds?: number[], approximate?: boolean): number[];
+    /** Copy constructor (Kotlin `RoundedPolygon(source)`). */
+    static copy(source: RoundedPolygon): RoundedPolygon;
+    /**
+     * Regular polygon of [numVertices] vertices around ([centerX], [centerY]) at [radius]
+     * (Kotlin `RoundedPolygon(numVertices, …)`).
+     */
+    static fromVertexCount(numVertices: number, options?: {
+        radius?: number;
+        centerX?: number;
+        centerY?: number;
+        rounding?: CornerRounding;
+        perVertexRounding?: readonly CornerRounding[] | null;
+    }): RoundedPolygon;
+    /**
+     * Polygon from an ordered list of `[x0, y0, x1, y1, …]` vertices (Kotlin
+     * `RoundedPolygon(vertices, …)`). Center defaults to the (1.0.1) estimate from the vertices.
+     */
+    static fromVertices(vertices: ArrayLike<number>, options?: {
+        rounding?: CornerRounding;
+        perVertexRounding?: readonly CornerRounding[] | null;
+        centerX?: number;
+        centerY?: number;
+    }): RoundedPolygon;
+}
+
+/**
+ * This class is used to animate between start and end polygons objects.
+ *
+ * Morphing between arbitrary objects can be problematic because it can be difficult to determine
+ * how the points of a given shape map to the points of some other shape. [Morph] simplifies the
+ * problem by only operating on [RoundedPolygon] objects, which are known to have similar,
+ * contiguous structures. For one thing, the shape of a polygon is contiguous from start to end
+ * (compared to an arbitrary Path object, which could have one or more `moveTo` operations in the
+ * shape). Also, all edges of a polygon shape are represented by [Cubic] objects, thus the start
+ * and end shapes use similar operations. Two Polygon shapes then only differ in the quantity and
+ * placement of their curves. The morph works by determining how to map the curves of the two
+ * shapes together (based on proximity and other information, such as distance to polygon
+ * vertices and concavity), and splitting curves when the shapes do not have the same number of
+ * curves or when the curve placement within the shapes is very different.
+ */
+declare class Morph {
+    private readonly start;
+    private readonly end;
+    /** The structure which holds the actual shape being morphed: matched start/end cubics. */
+    readonly morphMatch: readonly (readonly [Cubic, Cubic])[];
+    constructor(start: RoundedPolygon, end: RoundedPolygon);
+    /** Axis-aligned bounds covering both start and end shapes (and so the whole morph). */
+    calculateBounds(bounds?: number[], approximate?: boolean): number[];
+    /** A square that holds both shapes in any rotation (see RoundedPolygon.calculateMaxBounds). */
+    calculateMaxBounds(bounds?: number[]): number[];
+    /**
+     * Returns a representation of the morph object at a given [progress] value as a list of Cubics.
+     * Note that this function causes a new list to be created and populated, so there is some
+     * overhead.
+     */
+    asCubics(progress: number): Cubic[];
+    /**
+     * Calls [callback] for each of the cubics of the morph at [progress], reusing [mutableCubic]
+     * (no per-frame allocation).
+     */
+    forEachCubic(progress: number, callback: (cubic: MutableCubic) => void, mutableCubic?: MutableCubic): void;
+    /**
+     * Matches the cubics of two polygons: measures both outlines, maps their corners, cuts and
+     * shifts the end polygon, then walks both, cutting curves so every pair spans the same progress.
+     */
+    static match(p1: RoundedPolygon, p2: RoundedPolygon): [Cubic, Cubic][];
+}
+
+/**
+ * Creates a circular shape, approximating the rounding of the shape around the underlying polygon
+ * vertices.
+ */
+declare function circle(options?: {
+    numVertices?: number;
+    radius?: number;
+    centerX?: number;
+    centerY?: number;
+}): RoundedPolygon;
+/** Creates a rectangular shape with the given width/height around the given center. */
+declare function rectangle(options?: {
+    width?: number;
+    height?: number;
+    rounding?: CornerRounding;
+    perVertexRounding?: readonly CornerRounding[] | null;
+    centerX?: number;
+    centerY?: number;
+}): RoundedPolygon;
+/**
+ * Creates a star polygon, which is like a regular polygon except every other vertex is on either
+ * an inner or outer radius.
+ */
+declare function star(numVerticesPerRadius: number, options?: {
+    radius?: number;
+    innerRadius?: number;
+    rounding?: CornerRounding;
+    innerRounding?: CornerRounding | null;
+    perVertexRounding?: readonly CornerRounding[] | null;
+    centerX?: number;
+    centerY?: number;
+}): RoundedPolygon;
+/**
+ * A pill shape consists of a rectangle shape bounded by two semicircles at either of the long
+ * ends of the rectangle.
+ */
+declare function pill(options?: {
+    width?: number;
+    height?: number;
+    smoothing?: number;
+    centerX?: number;
+    centerY?: number;
+}): RoundedPolygon;
+/**
+ * A pillStar shape is like a [pill] except it has inner and outer radii along its pill-shaped
+ * outline, just like a [star] has inner and outer radii along its circular outline.
+ */
+declare function pillStar(options?: {
+    width?: number;
+    height?: number;
+    numVerticesPerRadius?: number;
+    innerRadiusRatio?: number;
+    rounding?: CornerRounding;
+    innerRounding?: CornerRounding | null;
+    perVertexRounding?: readonly CornerRounding[] | null;
+    vertexSpacing?: number;
+    startLocation?: number;
+    centerX?: number;
+    centerY?: number;
+}): RoundedPolygon;
+
+type PathCommand = readonly ['M', number, number] | readonly ['L', number, number] | readonly ['C', number, number, number, number, number, number] | readonly ['Z'];
+/** Compose `Path.translate(offset)`. */
+declare const translatePath: (path: readonly PathCommand[], dx: number, dy: number) => PathCommand[];
+/**
+ * Compose `Path.getBounds()`: `[left, top, right, bottom]` over every point, control points
+ * included (Skia's `SkPath::getBounds`). Empty paths give `[0, 0, 0, 0]`.
+ */
+declare function pathBounds(path: readonly PathCommand[]): [number, number, number, number];
+/**
+ * Serializes a path to an SVG `d` attribute with absolute commands. [fractionDigits] bounds the
+ * decimals per number (trailing zeros dropped).
+ */
+declare function toSvgPathData(path: readonly PathCommand[], fractionDigits?: number): string;
+
+/**
+ * `LoadingIndicatorDefaults.IndeterminateIndicatorPolygons`: the seven shapes the indeterminate
+ * indicator morphs between, in order.
+ */
+declare const indeterminateIndicatorPolygons: () => RoundedPolygon[];
+/**
+ * `LoadingIndicatorDefaults.DeterminateIndicatorPolygons`: a circle rotated by 360° / 20 (for a
+ * smoother morph into the soft burst, which is rotated by the same angle) and the soft burst.
+ */
+declare const determinateIndicatorPolygons: () => RoundedPolygon[];
+/**
+ * A morph between each consecutive pair of polygons (each normalized) and, when
+ * [circularSequence], a final morph from the last back to the first.
+ */
+declare function morphSequence(polygons: readonly RoundedPolygon[], circularSequence: boolean): Morph[];
+/**
+ * The scale factor that keeps every polygon inside its box while it rotates: the smallest
+ * bounds-to-max-bounds ratio (using the larger of the x and y ratios, for pill-like shapes).
+ */
+declare function calculateScaleFactor(polygons: readonly RoundedPolygon[]): number;
+/**
+ * Scales a normalized path by `size × scaleFactor` and centers it (by its control-point bounds)
+ * in a `width` x `height` box.
+ */
+declare function processPath(path: readonly PathCommand[], width: number, height: number, scaleFactor: number): PathCommand[];
+/** What the indicator draws in one frame: a morph at a progress, rotated about the center. */
+interface LoadingIndicatorFrame {
+    morphIndex: number;
+    morphProgress: number;
+    /** Degrees, clockwise. */
+    rotation: number;
+}
+/**
+ * The determinate draw step: picks the active morph for [progress] (coerced to 0..1), its local
+ * progress, and rotates counterclockwise by half a turn over the whole range.
+ */
+declare function determinateFrame(progress: number, morphCount: number): LoadingIndicatorFrame;
+/**
+ * A loading indicator's shapes, prepared once: the morph sequence and the scale factor
+ * (`calculateScaleFactor × activeIndicatorScale`, where the active indicator scale is the token
+ * ratio `ActiveSize / min(ContainerWidth, ContainerHeight)`).
+ */
+declare class LoadingIndicatorShapes {
+    readonly morphs: readonly Morph[];
+    readonly scaleFactor: number;
+    constructor(polygons: readonly RoundedPolygon[], circularSequence: boolean, activeIndicatorScale: number);
+    /** The processed path of morph [morphIndex] at [progress] in a [size]-sided square. */
+    path(morphIndex: number, progress: number, size: number): PathCommand[];
+    /** {@link path} as an SVG `d` attribute. */
+    pathData(morphIndex: number, progress: number, size: number): string;
+}
+/**
+ * {@link LoadingIndicatorShapes} for an indicator, built once per polygon list (null = the
+ * Compose defaults for the kind), kind and active indicator scale. Morph construction is the
+ * expensive part, so every indicator on a page shares it.
+ */
+declare function loadingIndicatorShapes(polygons: readonly RoundedPolygon[] | null, indeterminate: boolean, activeIndicatorScale: number): LoadingIndicatorShapes;
+
+/**
+ * The outline Compose's `RoundedPolygon.toShape(startAngle).createOutline(size, …)` produces: the
+ * path scaled to [width] x [height], then centered by its control-point bounds.
+ */
+declare function toShapeOutline(polygon: RoundedPolygon, width: number, height: number, startAngle?: number): PathCommand[];
+declare const builders: {
+    Circle: () => RoundedPolygon;
+    Square: () => RoundedPolygon;
+    Slanted: () => RoundedPolygon;
+    Arch: () => RoundedPolygon;
+    Fan: () => RoundedPolygon;
+    Arrow: () => RoundedPolygon;
+    SemiCircle: () => RoundedPolygon;
+    Oval: () => RoundedPolygon;
+    Pill: () => RoundedPolygon;
+    Triangle: () => RoundedPolygon;
+    Diamond: () => RoundedPolygon;
+    ClamShell: () => RoundedPolygon;
+    Pentagon: () => RoundedPolygon;
+    Gem: () => RoundedPolygon;
+    Sunny: () => RoundedPolygon;
+    VerySunny: () => RoundedPolygon;
+    Cookie4Sided: () => RoundedPolygon;
+    Cookie6Sided: () => RoundedPolygon;
+    Cookie7Sided: () => RoundedPolygon;
+    Cookie9Sided: () => RoundedPolygon;
+    Cookie12Sided: () => RoundedPolygon;
+    Ghostish: () => RoundedPolygon;
+    Clover4Leaf: () => RoundedPolygon;
+    Clover8Leaf: () => RoundedPolygon;
+    Burst: () => RoundedPolygon;
+    SoftBurst: () => RoundedPolygon;
+    Boom: () => RoundedPolygon;
+    SoftBoom: () => RoundedPolygon;
+    Flower: () => RoundedPolygon;
+    Puffy: () => RoundedPolygon;
+    PuffyDiamond: () => RoundedPolygon;
+    PixelCircle: () => RoundedPolygon;
+    PixelTriangle: () => RoundedPolygon;
+    Bun: () => RoundedPolygon;
+    Heart: () => RoundedPolygon;
+};
+type MaterialShapeName = keyof typeof builders;
+/** The 35 Material shape names, in MaterialShapes.kt order. */
+declare const materialShapeNames: MaterialShapeName[];
+/**
+ * A predefined Material shape as a normalized [RoundedPolygon] (fits the unit square), created on
+ * first use and cached, like the `MaterialShapes.<Name>` getters.
+ */
+declare function materialShape(name: MaterialShapeName): RoundedPolygon;
+
+interface PathOptions {
+    /**
+     * Angle in degrees the path starts drawing from. Note that, as in Compose, the path is rotated
+     * around the origin; the pivot only measures the angle of the first anchor.
+     */
+    startAngle?: number;
+    /** Draws the outline twice (for stroke animations). */
+    repeatPath?: boolean;
+    /** Closes the path. */
+    closePath?: boolean;
+}
+/** Path for a [RoundedPolygon]; the start angle is measured around its center. */
+declare function polygonToPath(polygon: RoundedPolygon, options?: PathOptions): PathCommand[];
+interface MorphPathOptions extends PathOptions {
+    rotationPivotX?: number;
+    rotationPivotY?: number;
+}
+/** Path for a [Morph] at [progress]; the start angle is measured around the rotation pivot. */
+declare function morphToPath(morph: Morph, progress: number, options?: MorphPathOptions): PathCommand[];
+
+export { Corner, CornerRounding, Cubic, Edge, Feature, type LoadingIndicatorFrame, LoadingIndicatorShapes, type MaterialShapeName, Morph, type MorphPathOptions, MutableCubic, type PathCommand, type PathOptions, type Point, type PointTransformer, RoundedPolygon, calculateScaleFactor, circle, determinateFrame, determinateIndicatorPolygons, indeterminateIndicatorPolygons, loadingIndicatorShapes, materialShape, materialShapeNames, morphSequence, morphToPath, pathBounds, pill, pillStar, polygonToPath, processPath, rectangle, star, toShapeOutline, toSvgPathData, translatePath };