@bug-on/m3-expressive 1.2.3 → 1.2.4

package/dist/md3-expressive-shapes-CPcfl_Hf.d.mts

@@ -0,0 +1,498 @@
+/**
+ * Corner rounding parameters for polygon vertices.
+ * Ported from androidx.graphics.shapes.CornerRounding.kt
+ *
+ * @see https://m3.material.io/styles/shape/corner-radius-scale
+ */
+/**
+ * Defines how a polygon corner is rounded.
+ *
+ * @example
+ * // Fully rounded corner with radius 16
+ * const rounding: CornerRounding = { radius: 16, smoothing: 0 };
+ *
+ * @example
+ * // Rounded corner with iOS-style squircle smoothing
+ * const smoothRounding: CornerRounding = { radius: 16, smoothing: 0.6 };
+ */
+interface CornerRounding {
+    /**
+     * The radius of the rounding. A value of 0 means no rounding (sharp corner).
+     * @default 0
+     */
+    readonly radius: number;
+    /**
+     * Smoothing factor in [0, 1]. Controls how the rounding curve transitions from
+     * the straight edge to the circular arc (squircle-like effect).
+     * 0 = pure circular arc, 1 = maximum smoothing.
+     * @default 0
+     */
+    readonly smoothing: number;
+}
+/**
+ * Creates a CornerRounding.
+ * @param radius - Rounding radius (default: 0)
+ * @param smoothing - Smoothing factor 0–1 (default: 0)
+ */
+declare function cornerRounding(radius?: number, smoothing?: number): CornerRounding;
+/** No rounding: straight/sharp corners. */
+declare const UNROUNDED: CornerRounding;
+
+/**
+ * Shared utility constants and functions for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Utils.kt
+ *
+ * @see https://m3.material.io/styles/shape/overview-principles
+ */
+/** Epsilon for floating-point distance comparisons */
+declare const DISTANCE_EPSILON = 0.0001;
+/** Epsilon for angle comparisons */
+declare const ANGLE_EPSILON = 0.0001;
+/** Pi as a float constant */
+declare const FLOAT_PI: number;
+/**
+ * Calculates the Euclidean distance between two coordinate offsets.
+ * @param dx - Difference in x coordinates
+ * @param dy - Difference in y coordinates
+ * @returns The distance
+ */
+declare function distance(dx: number, dy: number): number;
+/**
+ * Calculates the squared Euclidean distance (cheaper than distance).
+ * @param dx - Difference in x coordinates
+ * @param dy - Difference in y coordinates
+ * @returns The squared distance
+ */
+declare function distanceSquared(dx: number, dy: number): number;
+/**
+ * Converts polar coordinates to Cartesian (x, y).
+ * @param radius - The radial distance
+ * @param angle - The angle in radians
+ * @returns A tuple [x, y]
+ */
+declare function radialToCartesian(radius: number, angle: number): [number, number];
+/**
+ * Returns value modulo divisor, always positive.
+ * @param value - The value
+ * @param divisor - The divisor
+ * @returns Positive modulo result
+ */
+declare function positiveModulo(value: number, divisor: number): number;
+/**
+ * Linearly interpolates between start and stop.
+ * @param start - Start value (at fraction=0)
+ * @param stop - End value (at fraction=1)
+ * @param fraction - Interpolation factor [0,1]
+ * @returns Interpolated value
+ */
+declare function interpolate(start: number, stop: number, fraction: number): number;
+/**
+ * Returns the square of a value.
+ * @param value - The value to square
+ */
+declare function square(value: number): number;
+/**
+ * Returns a unit direction vector from (0,0) toward (dx, dy).
+ * @param dx - X component
+ * @param dy - Y component
+ * @returns [nx, ny] normalized direction
+ */
+declare function directionVector(dx: number, dy: number): [number, number];
+/**
+ * Checks if the turn from prev→curr→next is convex (clockwise in screen coords).
+ * @param prevX - Previous vertex x
+ * @param prevY - Previous vertex y
+ * @param currX - Current vertex x
+ * @param currY - Current vertex y
+ * @param nextX - Next vertex x
+ * @param nextY - Next vertex y
+ * @returns true if convex
+ */
+declare function convex(prevX: number, prevY: number, currX: number, currY: number, nextX: number, nextY: number): boolean;
+/**
+ * Type for a function that transforms a point (x, y) → (x', y').
+ */
+type PointTransformer = (x: number, y: number) => [number, number];
+
+/**
+ * Point type and operations for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Point.kt
+ *
+ * In Kotlin, Point is a type alias for FloatFloatPair. Here we use a plain object
+ * for zero-overhead structural typing in TypeScript.
+ */
+
+/** A 2D point or vector. */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Creates a new Point.
+ * @param x - X coordinate
+ * @param y - Y coordinate
+ */
+declare function point(x: number, y: number): Point;
+/**
+ * Returns the magnitude (distance from origin) of the point.
+ * @param p - The point
+ */
+declare function getDistance(p: Point): number;
+/**
+ * Returns the squared magnitude of the point (cheaper than getDistance).
+ * @param p - The point
+ */
+declare function getDistanceSquared(p: Point): number;
+/**
+ * Dot product of two points (treated as vectors).
+ * @param a - First point
+ * @param b - Second point
+ */
+declare function dotProduct(a: Point, b: Point): number;
+/**
+ * Rotates the point 90 degrees counter-clockwise.
+ * @param p - The point
+ * @returns New rotated point
+ */
+declare function rotate90(p: Point): Point;
+/**
+ * Returns the unit vector in the direction of the point from (0,0).
+ * @param p - The point
+ * @throws Error if the point is at the origin
+ */
+declare function getDirection(p: Point): Point;
+/**
+ * Checks if p0→p1→p2 turn is clockwise (positive cross product in screen coords).
+ * @param p0 - Previous point
+ * @param p1 - Current point
+ * @param p2 - Next point
+ */
+declare function clockwise(p0: Point, p1: Point, p2: Point): boolean;
+/** Point addition. */
+declare function addPoints(a: Point, b: Point): Point;
+/** Point subtraction. */
+declare function subtractPoints(a: Point, b: Point): Point;
+/** Scalar multiplication. */
+declare function scalePoint(p: Point, scalar: number): Point;
+/** Scalar division. */
+declare function dividePoint(p: Point, scalar: number): Point;
+/**
+ * Linearly interpolates between two points.
+ * @param start - Start point (at fraction=0)
+ * @param stop - End point (at fraction=1)
+ * @param fraction - Interpolation factor [0,1]
+ */
+declare function lerpPoint(start: Point, stop: Point, fraction: number): Point;
+/**
+ * Applies a PointTransformer to a point.
+ * @param p - The original point
+ * @param fn - The transform function
+ */
+declare function transformPoint(p: Point, fn: PointTransformer): Point;
+
+/**
+ * Cubic Bézier curve type for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Cubic.kt
+ *
+ * A cubic holds 8 floats: [anchor0X, anchor0Y, control0X, control0Y, control1X, control1Y, anchor1X, anchor1Y]
+ */
+
+/**
+ * A single cubic Bézier curve segment.
+ *
+ * The curve goes from anchor0 → (via control0, control1) → anchor1.
+ *
+ * @example
+ * const line = Cubic.straightLine(0, 0, 1, 0);
+ * const arc  = Cubic.circularArc(0, 0, 1, 0, 0, 1);
+ */
+declare class Cubic {
+    /** Internal storage: [a0x, a0y, c0x, c0y, c1x, c1y, a1x, a1y] */
+    readonly points: number[];
+    constructor(points: number[]);
+    /** First anchor point X */
+    get anchor0X(): number;
+    /** First anchor point Y */
+    get anchor0Y(): number;
+    /** First control point X */
+    get control0X(): number;
+    /** First control point Y */
+    get control0Y(): number;
+    /** Second control point X */
+    get control1X(): number;
+    /** Second control point Y */
+    get control1Y(): number;
+    /** Second anchor point X */
+    get anchor1X(): number;
+    /** Second anchor point Y */
+    get anchor1Y(): number;
+    /**
+     * Returns a point on the curve at parameter t (0=start, 1=end).
+     * Uses the standard cubic Bézier formula.
+     * @param t - Parameter in [0, 1]
+     */
+    pointOnCurve(t: number): Point;
+    /**
+     * Returns true if this curve has (near) zero length.
+     */
+    zeroLength(): boolean;
+    /**
+     * Splits this cubic at parameter t, returning two cubics.
+     * Uses De Casteljau's algorithm.
+     * @param t - Split parameter in [0, 1]
+     * @returns [left, right] pair
+     */
+    split(t: number): [Cubic, Cubic];
+    /**
+     * Returns a reversed copy of this cubic (anchor0 ↔ anchor1, controls swapped).
+     */
+    reverse(): Cubic;
+    /**
+     * Calculates the axis-aligned bounding box.
+     * @param approximate - If true, uses control point hull (faster). Default: false.
+     * @returns [minX, minY, maxX, maxY]
+     */
+    calculateBounds(approximate?: boolean): [number, number, number, number];
+    /**
+     * Interpolates between this cubic and another at fraction t.
+     * @param other - Target cubic
+     * @param t - Fraction [0, 1]
+     */
+    interpolateTo(other: Cubic, t: number): Cubic;
+    /**
+     * Applies a PointTransformer to all anchor and control points.
+     * @param fn - The transform function
+     */
+    transformed(fn: PointTransformer): Cubic;
+    toString(): string;
+    /**
+     * Creates a cubic representing a straight line.
+     * Control points lie at 1/3 and 2/3 of the line.
+     * @param x0 - Start anchor X
+     * @param y0 - Start anchor Y
+     * @param x1 - End anchor X
+     * @param y1 - End anchor Y
+     */
+    static straightLine(x0: number, y0: number, x1: number, y1: number): Cubic;
+    /**
+     * Creates a cubic approximating a circular arc.
+     * p0 and p1 must be equidistant from the center.
+     * For arcs > 180°, use multiple cubics.
+     *
+     * @param centerX - Arc center X
+     * @param centerY - Arc center Y
+     * @param x0 - Start point X (on circle)
+     * @param y0 - Start point Y (on circle)
+     * @param x1 - End point X (on circle)
+     * @param y1 - End point Y (on circle)
+     */
+    static circularArc(centerX: number, centerY: number, x0: number, y0: number, x1: number, y1: number): Cubic;
+    /**
+     * Creates a zero-length cubic at the given point.
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     */
+    static empty(x: number, y: number): Cubic;
+}
+/**
+ * A mutable version of Cubic used in performance-critical paths (Morph.forEachCubic).
+ * Reuses the same instance to avoid allocations.
+ */
+declare class MutableCubic extends Cubic {
+    constructor();
+    /**
+     * Mutably interpolates between c1 and c2 at the given progress.
+     * @param c1 - Start cubic
+     * @param c2 - End cubic
+     * @param progress - Interpolation factor [0, 1]
+     */
+    interpolate(c1: Cubic, c2: Cubic, progress: number): void;
+    /**
+     * Mutably applies a PointTransformer to all points.
+     * @param fn - The transform function
+     */
+    transform(fn: PointTransformer): void;
+}
+
+/**
+ * Feature types for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Features.kt
+ *
+ * Features describe the outline segments of a RoundedPolygon:
+ * - Corner: a (potentially rounded) vertex
+ * - Edge: a straight or curved segment between two corners
+ */
+
+/**
+ * A discriminated union representing one outline segment of a polygon.
+ *
+ * @example
+ * const corner: Feature = { type: "corner", cubics: [...], convex: true };
+ * const edge: Feature   = { type: "edge",   cubics: [...] };
+ */
+type Feature = CornerFeature | EdgeFeature;
+/** A (potentially rounded) corner vertex. */
+interface CornerFeature {
+    readonly type: "corner";
+    /**
+     * Cubic curves making up this corner.
+     * Unrounded corner = 1 zero-length cubic. Rounded = 1–3 cubics (flanking + arc + flanking).
+     */
+    readonly cubics: Cubic[];
+    /** True if this corner is convex (pointing outward). */
+    readonly convex: boolean;
+}
+/** A straight or curved edge segment between two corners. */
+interface EdgeFeature {
+    readonly type: "edge";
+    /** Cubic curves making up this edge (usually a single straight-line cubic). */
+    readonly cubics: Cubic[];
+}
+/**
+ * Creates a corner feature.
+ * @param cubics - Cubic curves defining the corner shape
+ * @param convex - Whether the corner is convex
+ */
+declare function cornerFeature(cubics: Cubic[], convex: boolean): CornerFeature;
+/**
+ * Creates an edge feature.
+ * @param cubics - Cubic curves defining the edge
+ */
+declare function edgeFeature(cubics: Cubic[]): EdgeFeature;
+/**
+ * Returns a transformed copy of a feature.
+ * @param feature - The feature to transform
+ * @param fn - Point transformer function
+ */
+declare function transformFeature(feature: Feature, fn: PointTransformer): Feature;
+
+/**
+ * RoundedPolygon — core shape class for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.RoundedPolygon.kt
+ *
+ * A RoundedPolygon is defined by a list of Feature (Corner + Edge) objects.
+ * Its geometry is stored as a flat list of Cubic Bézier curves that form
+ * a closed, contiguous outline.
+ */
+
+/**
+ * The core shape class. Represents a closed polygon outline as a list of Cubic
+ * Bézier curves, optionally rounded at the vertices.
+ *
+ * All shapes in MD3 Expressive are represented as RoundedPolygon instances.
+ *
+ * @example
+ * // Create a circle (8-vertex polygon, fully rounded)
+ * const circle = RoundedPolygon.circle();
+ *
+ * @example
+ * // Create a rounded rectangle
+ * const rect = RoundedPolygon.rectangle(2, 1, { radius: 0.25, smoothing: 0 });
+ */
+declare class RoundedPolygon {
+    /** Flat list of cubic Bézier curves forming the closed outline. */
+    readonly cubics: Cubic[];
+    /** Feature list (corners + edges). */
+    readonly features: Feature[];
+    /** Center point of the polygon. */
+    readonly center: Point;
+    /** @internal Use static factory methods instead */
+    private constructor();
+    get centerX(): number;
+    get centerY(): number;
+    /**
+     * Creates a polygon from a vertex count (regular polygon).
+     * @param numVertices - Number of vertices (≥ 3)
+     * @param radius - Circumradius (default: 1)
+     * @param centerX - Center X (default: 0)
+     * @param centerY - Center Y (default: 0)
+     * @param rounding - Corner rounding for all vertices
+     * @param perVertexRounding - Per-vertex rounding overrides
+     */
+    static fromNumVertices(numVertices: number, radius?: number, centerX?: number, centerY?: number, rounding?: CornerRounding, perVertexRounding?: CornerRounding[]): RoundedPolygon;
+    /**
+     * Creates a polygon from a flat vertex array [x0, y0, x1, y1, ...].
+     * @param vertices - Flat array of x,y pairs (length must be even and ≥ 6)
+     * @param rounding - Corner rounding for all vertices
+     * @param perVertexRounding - Per-vertex rounding overrides
+     * @param centerX - Center X (auto-calculated if not provided)
+     * @param centerY - Center Y (auto-calculated if not provided)
+     */
+    static fromVertices(vertices: number[], rounding?: CornerRounding, perVertexRounding?: CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Creates a polygon from a pre-built Feature list.
+     * @param features - Feature list (≥ 2 features)
+     * @param centerX - Center X (auto-calculated if NaN)
+     * @param centerY - Center Y (auto-calculated if NaN)
+     */
+    static fromFeatures(features: Feature[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Returns a new RoundedPolygon with all points transformed.
+     * @param fn - Transform function: (x, y) => [x', y']
+     */
+    transformed(fn: PointTransformer): RoundedPolygon;
+    /**
+     * Returns a normalized copy: scaled and centered to fit in [0,1] × [0,1].
+     * Maintains aspect ratio by using the larger dimension.
+     */
+    normalized(): RoundedPolygon;
+    /**
+     * Calculates the axis-aligned bounding box.
+     * @param approximate - If true, uses control point hull (faster). Default: true.
+     * @returns [minX, minY, maxX, maxY]
+     */
+    calculateBounds(approximate?: boolean): [number, number, number, number];
+    /**
+     * Calculates the maximum bounding square (useful for shapes that rotate).
+     * @returns [minX, minY, maxX, maxY] of the max-bounds square
+     */
+    calculateMaxBounds(): [number, number, number, number];
+}
+
+/**
+ * MD3 Expressive Shape Catalog — auto-generated from SVGs.
+ *
+ * Each shape is a pre-normalized RoundedPolygon (fits in [0,1]×[0,1], centered at (0.5, 0.5)).
+ * Regenerated via scratch/generate-shapes.ts.
+ */
+
+declare const MD3Shapes: {
+    readonly arch: RoundedPolygon;
+    readonly arrow: RoundedPolygon;
+    readonly boom: RoundedPolygon;
+    readonly bun: RoundedPolygon;
+    readonly burst: RoundedPolygon;
+    readonly circle: RoundedPolygon;
+    readonly clamshell: RoundedPolygon;
+    readonly diamond: RoundedPolygon;
+    readonly fan: RoundedPolygon;
+    readonly flower: RoundedPolygon;
+    readonly gem: RoundedPolygon;
+    readonly ghostish: RoundedPolygon;
+    readonly heart: RoundedPolygon;
+    readonly clover4Leaf: RoundedPolygon;
+    readonly clover8Leaf: RoundedPolygon;
+    readonly oval: RoundedPolygon;
+    readonly pentagon: RoundedPolygon;
+    readonly pill: RoundedPolygon;
+    readonly pixelCircle: RoundedPolygon;
+    readonly pixelTriangle: RoundedPolygon;
+    readonly puffyDiamond: RoundedPolygon;
+    readonly puffy: RoundedPolygon;
+    readonly semiCircle: RoundedPolygon;
+    readonly cookie12Sided: RoundedPolygon;
+    readonly cookie4Sided: RoundedPolygon;
+    readonly cookie6Sided: RoundedPolygon;
+    readonly cookie7Sided: RoundedPolygon;
+    readonly cookie9Sided: RoundedPolygon;
+    readonly slanted: RoundedPolygon;
+    readonly softBoom: RoundedPolygon;
+    readonly softBurst: RoundedPolygon;
+    readonly square: RoundedPolygon;
+    readonly sunny: RoundedPolygon;
+    readonly triangle: RoundedPolygon;
+    readonly verySunny: RoundedPolygon;
+};
+type MD3ShapeName = keyof typeof MD3Shapes;
+
+export { ANGLE_EPSILON as A, scalePoint as B, type CornerFeature as C, DISTANCE_EPSILON as D, type EdgeFeature as E, FLOAT_PI as F, square as G, subtractPoints as H, transformFeature as I, transformPoint as J, type MD3ShapeName as M, type Point as P, RoundedPolygon as R, UNROUNDED as U, type CornerRounding as a, Cubic as b, type Feature as c, MD3Shapes as d, MutableCubic as e, type PointTransformer as f, addPoints as g, clockwise as h, convex as i, cornerFeature as j, cornerRounding as k, directionVector as l, distance as m, distanceSquared as n, dividePoint as o, dotProduct as p, edgeFeature as q, getDirection as r, getDistance as s, getDistanceSquared as t, interpolate as u, lerpPoint as v, point as w, positiveModulo as x, radialToCartesian as y, rotate90 as z };