@pg-labs-incubator/cobweb 0.0.0-stage → 0.0.2

package/target/tsc/shape/point.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Function mapping coordinates to a point.
+ *
+ * This is invoked once for each point of the {@link ./cubic#Cubic | curve},
+ * {@link ./rounded-polygon#PolygonFeature | feature} or
+ * {@link ./rounded-polygon#RoundedPolygon | polygon} being transformed.
+ *
+ * @param x - horizontal coordinate of point to map
+ * @param y - vertical coordinate of point to map
+ * @returns mapped point
+ */
+export type PointTransformer = (x: number, y: number) => Point;
+/**
+ * Immutable point, or vector, of the plane.
+ *
+ * This uses screen coordinates: `x` grows to the right and `y` grows downwards, hence positive
+ * rotations turn clockwise. Every operation returns a new point.
+ */
+export declare class Point {
+    /**
+     * Point at the origin, `(0, 0)`.
+     */
+    static readonly Zero: Point;
+    /**
+     * Horizontal coordinate, growing to the right.
+     */
+    readonly x: number;
+    /**
+     * Vertical coordinate, growing downwards.
+     */
+    readonly y: number;
+    /**
+     * Construct a new point.
+     *
+     * @param x - horizontal coordinate
+     * @param y - vertical coordinate
+     * @throws {@link Error} `x` or `y` is not finite
+     */
+    constructor(x: number, y: number);
+    /**
+     * Interpolate linearly between two points.
+     *
+     * @param start - point at progress `0`
+     * @param end - point at progress `1`
+     * @param progress - progress to interpolate at, extrapolating outside `[0, 1]`
+     * @returns interpolated point
+     * @throws {@link Error} interpolated point is not finite
+     */
+    static interpolate(start: Point, end: Point, progress: number): Point;
+    /**
+     * Subtract a vector from this vector.
+     *
+     * @param other - vector to subtract
+     * @returns difference of vectors
+     * @throws {@link Error} difference is not finite
+     */
+    minus(other: Point): Point;
+    /**
+     * Add a vector to this vector.
+     *
+     * @param other - vector to add
+     * @returns sum of vectors
+     * @throws {@link Error} sum is not finite
+     */
+    plus(other: Point): Point;
+    /**
+     * Multiply both coordinates by a factor.
+     *
+     * @param factor - factor to multiply by
+     * @returns scaled vector
+     * @throws {@link Error} scaled vector is not finite
+     */
+    times(factor: number): Point;
+    /**
+     * Divide both coordinates by a divisor.
+     *
+     * @param factor - divisor to divide by
+     * @returns scaled vector
+     * @throws {@link Error} scaled vector is not finite, for example after a division by `0`
+     */
+    div(factor: number): Point;
+    /**
+     * Compute squared length of this vector.
+     *
+     * @returns squared length
+     */
+    distanceSquared(): number;
+    /**
+     * Compute length of this vector.
+     *
+     * @returns length
+     */
+    distance(): number;
+    /**
+     * Compute dot product with another vector.
+     *
+     * @param other - vector to multiply with
+     * @returns dot product
+     */
+    dot(other: Point): number;
+    /**
+     * Compute unit vector of the same direction.
+     *
+     * @returns unit vector
+     * @throws {@link Error} this vector has no length
+     */
+    direction(): Point;
+    /**
+     * Turn this vector a quarter turn clockwise.
+     *
+     * @returns perpendicular vector of the same length
+     */
+    rotate90(): Point;
+    /**
+     * Compute cross product with another vector.
+     *
+     * @param other - vector to multiply with
+     * @returns cross product, positive if, and only if, `other` turns clockwise from this vector
+     */
+    cross(other: Point): number;
+    /**
+     * Rotate this point around a center.
+     *
+     * @param degrees - angle in degrees, where positive angles turn clockwise
+     * @param center - center to rotate around, or `undefined` to rotate around the origin
+     * @returns rotated point
+     */
+    rotate(degrees: number, center?: Point): Point;
+}
+/**
+ * Compute the unit vector of an angle.
+ *
+ * @param angle - angle in radians, clockwise from the positive `x` axis
+ * @returns unit vector
+ * @throws {@link Error} `angle` is not finite
+ */
+export declare function directionVector(angle: number): Point;
+/**
+ * Compute the unit vector of a vector.
+ *
+ * @param x - horizontal coordinate of vector
+ * @param y - vertical coordinate of vector
+ * @returns unit vector
+ * @throws {@link Error} vector has no length
+ */
+export declare function directionVector(x: number, y: number): Point;
+/**
+ * Compute the distance between two points.
+ *
+ * @param a - first point
+ * @param b - second point
+ * @returns distance between `a` and `b`
+ */
+export declare function distanceBetween(a: Point, b: Point): number;
+/**
+ * Test whether an outline turns clockwise.
+ *
+ * A clockwise outline is convex at the points where it turns clockwise.
+ *
+ * @param previous - point before `current`
+ * @param current - point at which outline turns
+ * @param next - point after `current`
+ * @returns `true` if, and only if, outline turns clockwise at `current`
+ */
+export declare function isConvex(previous: Point, current: Point, next: Point): boolean;

package/target/tsc/shape/rounded-polygon.d.ts

@@ -0,0 +1,289 @@
+import type { PointTransformer } from "./point";
+import { CornerRounding } from "./corner-rounding";
+import { Cubic } from "./cubic";
+import { Point } from "./point";
+/**
+ * Union of polygon feature kinds.
+ *
+ * | Kind     | Description                                           |
+ * | -------- | ----------------------------------------------------- |
+ * | `corner` | Rounded or sharp vertex, which morphs match by place. |
+ * | `edge`   | Straight segment between two corners.                 |
+ *
+ * @see {@link PolygonFeature.kind}
+ */
+export type PolygonFeatureKind = "corner" | "edge";
+/**
+ * {@link RoundedPolygon.fromVertices} options.
+ */
+export interface RoundedPolygonOptions {
+    /**
+     * Rounding of vertices without per-vertex rounding.
+     *
+     * @defaultValue {@link CornerRounding.Unrounded}
+     */
+    rounding?: CornerRounding | undefined;
+    /**
+     * Rounding of each vertex, in vertex order.
+     *
+     * Vertices without an entry are rounded with
+     * {@link RoundedPolygonOptions.rounding | `rounding`}.
+     */
+    perVertexRounding?: readonly CornerRounding[] | undefined;
+    /**
+     * Horizontal coordinate of the center.
+     *
+     * @defaultValue mean horizontal coordinate of vertices
+     */
+    centerX?: number | undefined;
+    /**
+     * Vertical coordinate of the center.
+     *
+     * @defaultValue mean vertical coordinate of vertices
+     */
+    centerY?: number | undefined;
+}
+/**
+ * Corner or edge of a {@link RoundedPolygon}.
+ *
+ * Morphs match the corners of two polygons by place and convexity, whereas edges only connect
+ * corners.
+ */
+export declare class PolygonFeature {
+    /**
+     * Contiguous curves of the feature.
+     */
+    readonly cubics: readonly Cubic[];
+    /**
+     * Kind of the feature.
+     */
+    readonly kind: PolygonFeatureKind;
+    /**
+     * Corner turns clockwise.
+     *
+     * This is always `true` for edges.
+     */
+    readonly convex: boolean;
+    /**
+     * Construct a new feature.
+     *
+     * @param cubics - contiguous curves of feature, in outline order
+     * @param kind - kind of feature
+     * @param convex - `false` if, and only if, corner turns counter-clockwise, which is ignored
+     * for edges
+     * @throws {@link Error} `cubics` is empty or not contiguous
+     */
+    constructor(cubics: readonly Cubic[], kind: PolygonFeatureKind, convex?: boolean);
+    /**
+     * Feature is an edge.
+     */
+    get isEdge(): boolean;
+    /**
+     * Feature is a corner.
+     */
+    get isCorner(): boolean;
+    /**
+     * Feature may be ignored by morphs.
+     *
+     * This is `true` if, and only if, the feature is an edge, which morphs may ignore when
+     * matching outlines.
+     */
+    get isIgnorableFeature(): boolean;
+    /**
+     * Feature is a corner turning clockwise.
+     */
+    get isConvexCorner(): boolean;
+    /**
+     * Feature is a corner turning counter-clockwise.
+     */
+    get isConcaveCorner(): boolean;
+    /**
+     * Transform the curves of the feature.
+     *
+     * @param transformer - function to transform each point of each curve with, in order
+     * @returns feature of same kind and convexity
+     * @throws {@link Error} a transformed coordinate is not finite, or the transformed curves are
+     * not contiguous
+     */
+    transformed(transformer: PointTransformer): PolygonFeature;
+    /**
+     * Reverse the direction of the feature.
+     *
+     * @returns feature of same kind running backwards, whose corner turns the other way
+     */
+    reversed(): PolygonFeature;
+    /**
+     * Test whether a value is an equal feature.
+     *
+     * @param other - value to compare with
+     * @returns `true` if, and only if, `other` is a feature of equal kind, convexity and curves
+     */
+    equals(other: unknown): boolean;
+}
+/**
+ * Polygon with rounded corners.
+ *
+ * This is an immutable, closed outline of {@link RoundedPolygon.features | features}: corners,
+ * rounded or sharp, alternating with the edges between them. Its
+ * {@link RoundedPolygon.cubics | curves} omit curves of zero length, and start in the middle of
+ * the first corner if it is rounded. Vertices listed clockwise make convex corners.
+ *
+ * ```ts
+ * // Rounded triangle within the unit square:
+ * const triangle = RoundedPolygon.fromVertices(
+ *     [0.5, 0, 1, 1, 0, 1],
+ *     { rounding: new CornerRounding(0.1, 0.4) }
+ * );
+ * ```
+ */
+export declare class RoundedPolygon {
+    /**
+     * Center of the polygon.
+     */
+    readonly center: Point;
+    /**
+     * Features of the polygon, in outline order.
+     */
+    readonly features: readonly PolygonFeature[];
+    /**
+     * Cubic Bezier curves of the outline.
+     *
+     * This is a closed outline, without curves of zero length.
+     */
+    readonly cubics: readonly Cubic[];
+    /**
+     * Construct a new polygon.
+     *
+     * @param features - features forming a closed outline
+     * @param center - center of polygon
+     * @throws {@link Error} there are fewer than two features, or they do not form a closed
+     * outline
+     */
+    private constructor();
+    /**
+     * Horizontal coordinate of the center.
+     */
+    get centerX(): number;
+    /**
+     * Vertical coordinate of the center.
+     */
+    get centerY(): number;
+    /**
+     * Create a polygon from its vertices.
+     *
+     * @param vertices - coordinates of at least three vertices, as `[x, y]` pairs in outline
+     * order
+     * @param options - roundings and center of polygon, if any
+     * @returns new polygon
+     * @throws {@link Error} there are fewer than three vertices, a coordinate is not finite, or
+     * the per-vertex roundings do not match the vertices
+     */
+    static fromVertices(vertices: readonly number[], options?: RoundedPolygonOptions): RoundedPolygon;
+    /**
+     * Create a polygon from its vertices.
+     *
+     * @param vertices - coordinates of at least three vertices, as `[x, y]` pairs in outline
+     * order
+     * @param rounding - rounding of vertices without per-vertex rounding, if any
+     * @param perVertexRounding - rounding of each vertex, if any
+     * @param centerX - horizontal coordinate of center, or `undefined` for the mean of the
+     * vertices
+     * @param centerY - vertical coordinate of center, or `undefined` for the mean of the
+     * vertices
+     * @returns new polygon
+     * @throws {@link Error} there are fewer than three vertices, a coordinate is not finite, or
+     * the per-vertex roundings do not match the vertices
+     */
+    static fromVertices(vertices: readonly number[], rounding?: CornerRounding, perVertexRounding?: readonly CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Create a polygon from its features.
+     *
+     * @param features - at least two features forming a closed outline
+     * @param centerX - horizontal coordinate of center, or `undefined` for the mean of the start
+     * anchors of all curves
+     * @param centerY - vertical coordinate of center, or `undefined` for the mean of the start
+     * anchors of all curves
+     * @returns new polygon
+     * @throws {@link Error} there are fewer than two features, they do not form a closed outline,
+     * or a coordinate of the center is not finite
+     */
+    static fromFeatures(features: readonly PolygonFeature[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Create a regular polygon.
+     *
+     * The first vertex lies at 3 o'clock from the center, and the others follow clockwise.
+     *
+     * @param numVertices - number of vertices, at least `3`
+     * @param radius - distance of vertices from center
+     * @param centerX - horizontal coordinate of center
+     * @param centerY - vertical coordinate of center
+     * @param rounding - rounding of vertices without per-vertex rounding
+     * @param perVertexRounding - rounding of each vertex, if any
+     * @returns new polygon
+     * @throws {@link Error} `numVertices` is not an integer of at least `3`, `radius` is not
+     * positive and finite, or the per-vertex roundings do not match the vertices
+     */
+    static fromNumVertices(numVertices: number, radius?: number, centerX?: number, centerY?: number, rounding?: CornerRounding, perVertexRounding?: readonly CornerRounding[]): RoundedPolygon;
+    /**
+     * Transform the features and the center of the polygon.
+     *
+     * @param transformer - function to transform each point of each feature with, in order, and
+     * then the center
+     * @returns transformed polygon
+     * @throws {@link Error} a transformed coordinate is not finite, or the transformed features do
+     * not form a closed outline
+     */
+    transformed(transformer: PointTransformer): RoundedPolygon;
+    /**
+     * Fit the polygon into the unit square.
+     *
+     * This scales and moves the polygon until the longer side of its
+     * {@link RoundedPolygon.calculateBounds | approximate bounds} spans `[0, 1]`, and centers the
+     * shorter side within `[0, 1]`.
+     *
+     * @returns polygon within the unit square
+     * @throws {@link Error} polygon has no extent
+     */
+    normalized(): RoundedPolygon;
+    /**
+     * Calculate the bounds of the outline.
+     *
+     * Approximate bounds contain the control points of the curves, and may thus exceed the
+     * outline.
+     *
+     * @param bounds - array to write `[left, top, right, bottom]` into, if any
+     * @param approximate - `true` if, and only if, bounds should be approximate
+     * @returns `bounds`, or a new array if `bounds` is `undefined`
+     * @throws {@link Error} `bounds` has fewer than four entries
+     */
+    calculateBounds(bounds?: number[], approximate?: boolean): number[];
+    /**
+     * Calculate bounds of the polygon in any rotation.
+     *
+     * This returns the bounds of a square around the center, reaching the farthest start anchor or
+     * midpoint of the curves of the outline. In other words, the bounds contain the polygon in any
+     * rotation around its center.
+     *
+     * @param bounds - array to write `[left, top, right, bottom]` into, if any
+     * @returns `bounds`, or a new array if `bounds` is `undefined`
+     * @throws {@link Error} `bounds` has fewer than four entries
+     */
+    calculateMaxBounds(bounds?: number[]): number[];
+    /**
+     * Test whether a value is an equal polygon.
+     *
+     * This does **not** compare centers.
+     *
+     * @param other - value to compare with
+     * @returns `true` if, and only if, `other` is a polygon whose features equal those of this
+     * polygon
+     */
+    equals(other: unknown): boolean;
+}
+/**
+ * Test whether a value is a rounded polygon.
+ *
+ * @param value - value to test
+ * @returns `true` if, and only if, `value` is a {@link RoundedPolygon}
+ */
+export declare function isRoundedPolygon(value: unknown): value is RoundedPolygon;

package/target/tsc/shape/shapes.d.ts

@@ -0,0 +1,76 @@
+import { CornerRounding } from "./corner-rounding";
+import { RoundedPolygon } from "./rounded-polygon";
+/**
+ * Factories of common polygons.
+ */
+export declare class Shapes {
+    /**
+     * Create a circle.
+     *
+     * This creates a regular polygon whose corners are rounded with the radius of the circle. In
+     * other words, the outline of the circle consists of `numVertices` circular arcs.
+     *
+     * @param numVertices - number of arcs, at least `3`
+     * @param radius - radius of circle
+     * @param centerX - horizontal coordinate of center
+     * @param centerY - vertical coordinate of center
+     * @returns new circle
+     * @throws {@link Error} `numVertices` is not an integer of at least `3`, or `radius` is not
+     * positive and finite
+     */
+    static circle(numVertices?: number, radius?: number, centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Create a rectangle.
+     *
+     * The vertices of the rectangle start at its bottom-right corner, and run clockwise.
+     *
+     * @param width - width of rectangle
+     * @param height - height of rectangle
+     * @param rounding - rounding of corners without per-vertex rounding
+     * @param perVertexRounding - rounding of bottom-right, bottom-left, top-left and top-right
+     * corners, respectively, if any
+     * @param centerX - horizontal coordinate of center
+     * @param centerY - vertical coordinate of center
+     * @returns new rectangle
+     * @throws {@link Error} `width` or `height` is not positive and finite, or the per-vertex
+     * roundings are not four
+     */
+    static rectangle(width?: number, height?: number, rounding?: CornerRounding, perVertexRounding?: readonly CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Create a star.
+     *
+     * Outer and inner vertices alternate, starting with an outer vertex at 3 o'clock from the
+     * center, and running clockwise.
+     *
+     * @param numVerticesPerRadius - number of outer vertices, at least `2`
+     * @param radius - distance of outer vertices from center
+     * @param innerRadius - distance of inner vertices from center, below `radius`
+     * @param rounding - rounding of outer vertices, and of inner vertices if `innerRounding` is
+     * `undefined`
+     * @param innerRounding - rounding of inner vertices, if any
+     * @param perVertexRounding - rounding of each vertex, replacing `rounding` and
+     * `innerRounding`, if any
+     * @param centerX - horizontal coordinate of center
+     * @param centerY - vertical coordinate of center
+     * @returns new star
+     * @throws {@link Error} `numVerticesPerRadius` is not an integer of at least `2`, a radius
+     * is not positive and finite, `innerRadius` is not below `radius`, or the per-vertex
+     * roundings do not match the vertices
+     */
+    static star(numVerticesPerRadius: number, radius?: number, innerRadius?: number, rounding?: CornerRounding, innerRounding?: CornerRounding, perVertexRounding?: readonly CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Create a pill.
+     *
+     * A pill is a rectangle whose shorter sides are semicircles.
+     *
+     * @param width - width of pill
+     * @param height - height of pill
+     * @param smoothing - smoothing of corners
+     * @param centerX - horizontal coordinate of center
+     * @param centerY - vertical coordinate of center
+     * @returns new pill
+     * @throws {@link Error} `width` or `height` is not positive and finite, or `smoothing` is
+     * outside `[0, 1]`
+     */
+    static pill(width?: number, height?: number, smoothing?: number, centerX?: number, centerY?: number): RoundedPolygon;
+}

package/target/tsc/spacing/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Spacing scale for layout.
+ *
+ * Cobweb exposes one spacing scale as numeric CSS pixel values, through {@link spacing}, and as
+ * `cw-Measurement-space<N>` design roles of the [`cw-Measurement`](./measurement.yaml) design
+ * attribute, both indexed by the same suffixes. A suffix is the spacing in hundredths of `8px`, so
+ * `100` is `8px` and `450` is `36px`. Import this module for numeric layout calculations, or use
+ * the design roles with `cw-var()` in stylesheets. Component-specific dimensions remain separate.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Spacing values, in CSS pixels, indexed by their {@link Spacing | suffix}.
+ */
+export declare const spacing: Readonly<Record<Spacing, number>>;
+/**
+ * Suffix of a spacing value, which is the spacing in hundredths of `8px`.
+ */
+export type Spacing = 0 | 25 | 50 | 75 | 100 | 125 | 150 | 175 | 200 | 250 | 300 | 400 | 450 | 500 | 600 | 700 | 800 | 900;

package/target/tsc/state/component.css.d.ts

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export {};