mtrl 0.8.0-next.10 → 0.8.0-next.11

package/dist/components/index.d.ts

@@ -27,6 +27,7 @@ export { default as createMenu } from "./menu";
 export { default as createNavigation } from "./navigation";
 export { default as createNavigationSystem } from "./navigation/system";
 export { default as createProgress } from "./progress";
+export { default as createLoadingIndicator } from "./loading-indicator";
 export { default as createRadios } from "./radios";
 export { default as createSearch } from "./search";
 export { default as createSelect } from "./select";
@@ -62,6 +63,7 @@ export type { ExtendedFabConfig, ExtendedFabComponent, } from "./extended-fab/ty
 export type { IconButtonConfig, IconButtonComponent, } from "./icon-button/types";
 export type { ListConfig, ListComponent, SelectEvent as ListSelectEvent, LoadEvent, } from "./list/types";
 export type { MenuConfig, MenuComponent, MenuItem } from "./menu/types";
+export type { LoadingIndicatorConfig, LoadingIndicatorComponent, } from "./loading-indicator/types";
 export type { ProgressConfig, ProgressComponent, ProgressShape, } from "./progress/types";
 export type { RadiosConfig, RadiosComponent, RadioOptionConfig, } from "./radios/types";
 export type { SearchConfig, SearchComponent } from "./search/types";

package/dist/components/loading-indicator/api.d.ts

@@ -0,0 +1,14 @@
+import { BaseComponent, LoadingIndicatorComponent, LoadingIndicatorConfig } from './types';
+interface ApiOptions {
+    config: LoadingIndicatorConfig;
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+/**
+ * Adds the public API and runs the animation
+ * @param {ApiOptions} options - API configuration
+ * @returns {Function} Higher-order function that adds API methods
+ */
+export declare const withAPI: ({ config, lifecycle }: ApiOptions) => (component: BaseComponent) => LoadingIndicatorComponent;
+export {};

package/dist/components/loading-indicator/config.d.ts

@@ -0,0 +1,44 @@
+import { LoadingIndicatorConfig } from './types';
+/**
+ * Default configuration for the loading indicator
+ */
+export declare const defaultConfig: Partial<LoadingIndicatorConfig>;
+/**
+ * Creates the base configuration
+ * @param {LoadingIndicatorConfig} config - User provided configuration
+ * @returns {LoadingIndicatorConfig} Complete configuration with defaults applied
+ */
+export declare const createBaseConfig: (config?: LoadingIndicatorConfig) => LoadingIndicatorConfig;
+/** Keeps a size within the 24–240 the guidelines allow */
+export declare const clampSize: (size: number | undefined) => number;
+/** A value within 0–1, or null for indeterminate */
+export declare const clampValue: (value: number | null | undefined) => number | null;
+/**
+ * Element configuration: a progressbar, as the M3 accessibility guidance
+ * asks, named after what is loading
+ * @param {LoadingIndicatorConfig} config - Configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export declare const getElementConfig: (config: LoadingIndicatorConfig) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    id: string;
+    name: string;
+    title: string;
+    tabIndex: number;
+    style: string | Partial<CSSStyleDeclaration>;
+    data: Record<string, string>;
+    role: string;
+    ariaLabel: string;
+    ariaDescribedBy: string;
+    ariaLabelledBy: string;
+    ariaHidden: boolean;
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};
+export default defaultConfig;

package/dist/components/loading-indicator/constants.d.ts

@@ -0,0 +1,60 @@
+import type { MaterialShapeName } from '../../core/shapes';
+/**
+ * Loading indicator measurements and timing (Compose Material 3
+ * LoadingIndicatorTokens.kt and LoadingIndicator.kt)
+ * @category Components
+ */
+export declare const LOADING_INDICATOR_DEFAULTS: {
+    /** Container width and height */
+    readonly SIZE: 48;
+    /** The active indicator's diameter within a 48dp container */
+    readonly INDICATOR_SIZE: 38;
+    /** Smallest size the guidelines allow */
+    readonly MIN_SIZE: 24;
+    /** Largest size the guidelines allow */
+    readonly MAX_SIZE: 240;
+    /** Milliseconds between two shape morphs */
+    readonly MORPH_INTERVAL: 650;
+    /** Milliseconds for one full turn of the slow global rotation */
+    readonly ROTATION_DURATION: 4666;
+    /** Degrees each morph turns the shape */
+    readonly MORPH_ROTATION: 90;
+    /** Accessible name when none is given */
+    readonly LABEL: "Loading";
+    /** Outline samples per shape */
+    readonly SAMPLES: 360;
+};
+/**
+ * The morph spring (Compose: `spring(dampingRatio = 0.6f, stiffness = 200f,
+ * visibilityThreshold = 0.1f)`)
+ * @category Components
+ */
+export declare const LOADING_INDICATOR_SPRING: {
+    readonly DAMPING: 0.6;
+    readonly STIFFNESS: 200;
+    readonly THRESHOLD: 0.1;
+};
+/**
+ * The shapes the indeterminate indicator morphs through, in order
+ * (LoadingIndicatorDefaults.IndeterminateIndicatorPolygons)
+ * @category Components
+ */
+export declare const LOADING_INDICATOR_SHAPES: readonly MaterialShapeName[];
+/**
+ * The shapes the determinate indicator morphs between as the value grows
+ * (LoadingIndicatorDefaults.DeterminateIndicatorPolygons)
+ * @category Components
+ */
+export declare const LOADING_INDICATOR_DETERMINATE_SHAPES: readonly MaterialShapeName[];
+/**
+ * CSS class names used by the loading indicator, without the prefix
+ * @category Components
+ */
+export declare const LOADING_INDICATOR_CLASSES: {
+    readonly ROOT: "loading-indicator";
+    /** Drawn on a primary-container circle */
+    readonly CONTAINED: "loading-indicator--contained";
+    /** Shows a value rather than looping */
+    readonly DETERMINATE: "loading-indicator--determinate";
+    readonly CANVAS: "loading-indicator__canvas";
+};

package/dist/components/loading-indicator/features/motion.d.ts

@@ -0,0 +1,22 @@
+/** Seconds from the start of a morph to its end */
+export declare const MORPH_SETTLE_SECONDS: number;
+/** Morph progress at `elapsed` milliseconds into an interval */
+export declare const morphProgress: (elapsed: number) => number;
+/** The indeterminate frame at `elapsed` milliseconds since the animation started */
+export declare const indeterminateFrame: (elapsed: number, shapeCount: number) => {
+    index: number;
+    progress: number;
+    rotation: number;
+};
+/** The still frame reduced motion shows: the shape for this interval, unrotated */
+export declare const reducedMotionFrame: (elapsed: number, shapeCount: number) => {
+    index: number;
+    progress: number;
+    rotation: number;
+};
+/** The determinate frame for a value from 0 to 1 */
+export declare const determinateFrame: (value: number) => {
+    index: number;
+    progress: number;
+    rotation: number;
+};

package/dist/components/loading-indicator/features/renderer.d.ts

@@ -0,0 +1,29 @@
+import { RadialProfile, MaterialShapeName } from '../../../core/shapes';
+import { BaseComponent, LoadingIndicatorConfig } from '../types';
+/** A frame: which morph, how far along it, and the rotation in degrees */
+export interface Frame {
+    /** Index of the shape the morph starts from */
+    index: number;
+    /** 0 at the shape, 1 at the next; may overshoot */
+    progress: number;
+    /** Clockwise rotation in degrees */
+    rotation: number;
+}
+export interface Renderer {
+    /** Draws one frame with the given shape sequence */
+    draw: (shapes: readonly RadialProfile[], frame: Frame) => void;
+    /** Resizes the canvas to the element's size */
+    resize: (size: number) => void;
+    /** Re-reads the indicator colour from the element's computed style */
+    refreshColor: () => void;
+    /** The last frame drawn, redrawn on resize and theme change */
+    redraw: () => void;
+    /** Profiles for a shape sequence, cached per name */
+    profiles: (names: readonly MaterialShapeName[]) => RadialProfile[];
+}
+/**
+ * Adds the canvas and the drawing routine
+ * @param {LoadingIndicatorConfig} config - Component configuration
+ * @returns {Function} Higher-order function that adds the renderer
+ */
+export declare const withRenderer: (config: LoadingIndicatorConfig) => (component: BaseComponent) => BaseComponent;

package/dist/components/loading-indicator/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './loading-indicator';
+export type { LoadingIndicatorConfig, LoadingIndicatorComponent } from './types';
+export { LOADING_INDICATOR_SHAPES, LOADING_INDICATOR_DEFAULTS } from './constants';

package/dist/components/loading-indicator/loading-indicator.d.ts

@@ -0,0 +1,9 @@
+import { LoadingIndicatorConfig, LoadingIndicatorComponent } from './types';
+/**
+ * Creates a loading indicator: the Material 3 expressive shape morph for
+ * waits under about five seconds. It animates from creation.
+ * @param {LoadingIndicatorConfig} config - Loading indicator configuration
+ * @returns {LoadingIndicatorComponent} Loading indicator component instance
+ */
+declare const createLoadingIndicator: (config?: LoadingIndicatorConfig) => LoadingIndicatorComponent;
+export default createLoadingIndicator;

package/dist/components/loading-indicator/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration options for the loading indicator
+ * @interface LoadingIndicatorConfig
+ */
+export interface LoadingIndicatorConfig {
+    /** Width and height in pixels, 24 to 240 (default 48) */
+    size?: number;
+    /**
+     * Draws the indicator on a primary-container circle, for use over other
+     * content; the indicator then takes on-primary-container
+     */
+    contained?: boolean;
+    /**
+     * A value from 0 to 1 makes the indicator determinate: the shape morphs
+     * with the value instead of looping. Leave unset for indeterminate.
+     */
+    value?: number | null;
+    /** Accessible name: what is loading (default "Loading") */
+    ariaLabel?: string;
+    /** Additional CSS classes */
+    class?: string;
+    /** Component prefix for CSS classes */
+    prefix?: string;
+    /** Component name for CSS classes */
+    componentName?: string;
+}
+/**
+ * Loading indicator public API
+ * @interface LoadingIndicatorComponent
+ */
+export interface LoadingIndicatorComponent {
+    /** The root element */
+    element: HTMLElement;
+    /** The canvas the shapes are drawn on */
+    canvas: HTMLCanvasElement;
+    /** Sets a value from 0 to 1 (determinate) or null (indeterminate) */
+    setValue: (value: number | null) => LoadingIndicatorComponent;
+    /** The current value, or null when indeterminate */
+    getValue: () => number | null;
+    /** Sets the size in pixels, clamped to 24–240 */
+    setSize: (size: number) => LoadingIndicatorComponent;
+    /** The size in pixels */
+    getSize: () => number;
+    /** Sets the accessible name */
+    setLabel: (label: string) => LoadingIndicatorComponent;
+    /** Runs the indeterminate animation (it runs from creation) */
+    start: () => LoadingIndicatorComponent;
+    /** Freezes the indicator on its current frame */
+    stop: () => LoadingIndicatorComponent;
+    /** Whether the animation is running */
+    isRunning: () => boolean;
+    /** Stops the animation and removes the element */
+    destroy: () => void;
+}
+/**
+ * The component as it passes through the enhancers
+ */
+export interface BaseComponent {
+    element: HTMLElement;
+    getClass?: (name: string) => string;
+    lifecycle?: {
+        destroy?: () => void;
+    };
+    [key: string]: any;
+}

package/dist/core/shapes/cubic.d.ts

@@ -0,0 +1,30 @@
+/** A cubic Bézier: anchor 0, control 0, control 1, anchor 1 */
+export type Cubic = readonly [number, number, number, number, number, number, number, number];
+/** A 2D point */
+export type Point = readonly [number, number];
+/** Below this distance two points are the same point */
+export declare const DISTANCE_EPSILON = 0.0001;
+export declare const lerp: (start: number, stop: number, fraction: number) => number;
+export declare const distance: (x: number, y: number) => number;
+/** Unit vector in the direction of (x, y) */
+export declare const direction: (x: number, y: number) => Point;
+export declare const rotate90: ([x, y]: Point) => Point;
+export declare const dot: (a: Point, b: Point) => number;
+/** A straight segment expressed as a cubic */
+export declare const straightLine: (x0: number, y0: number, x1: number, y1: number) => Cubic;
+/**
+ * A circular arc from (x0, y0) to (x1, y1) around (centerX, centerY),
+ * approximated by one cubic; the arc must be under 180 degrees.
+ */
+export declare const circularArc: (centerX: number, centerY: number, x0: number, y0: number, x1: number, y1: number) => Cubic;
+export declare const pointOnCurve: (c: Cubic, t: number) => Point;
+export declare const reverseCubic: (c: Cubic) => Cubic;
+export declare const zeroLength: (c: Cubic) => boolean;
+export type PointTransformer = (x: number, y: number) => Point;
+export declare const transformCubic: (c: Cubic, f: PointTransformer) => Cubic;
+/**
+ * The bounding box of a cubic as [left, top, right, bottom]. The approximate
+ * box is the hull of anchors and controls, which is what the library uses to
+ * normalise shapes.
+ */
+export declare const cubicBounds: (c: Cubic) => [number, number, number, number];

package/dist/core/shapes/index.d.ts

@@ -0,0 +1,6 @@
+export type { Cubic, Point, PointTransformer } from './cubic';
+export { straightLine, circularArc, pointOnCurve, cubicBounds } from './cubic';
+export type { CornerRounding, RoundedPolygon } from './polygon';
+export { UNROUNDED, roundedPolygon, regularPolygon, circle, star, transformPolygon, rotatePolygon, scalePolygon, polygonBounds, polygonMaxRadius, normalizePolygon, } from './polygon';
+export type { MaterialShapeName, RadialProfile } from './material';
+export { materialShape, radialProfile } from './material';

package/dist/core/shapes/material.d.ts

@@ -0,0 +1,21 @@
+import { RoundedPolygon, polygonMaxRadius } from './polygon';
+/** Names of the Material shapes available here */
+export type MaterialShapeName = 'circle' | 'oval' | 'pill' | 'pentagon' | 'sunny' | 'cookie4' | 'cookie9' | 'softBurst';
+/** A Material shape, normalised into the unit square */
+export declare const materialShape: (name: MaterialShapeName) => RoundedPolygon;
+/** A shape's outline as radii at evenly spaced angles around its centre */
+export interface RadialProfile {
+    /** Radius at angle i * 2π / radii.length, clockwise from the positive x axis on a y-down canvas */
+    radii: Float32Array;
+    centerX: number;
+    centerY: number;
+    /** The largest radius, for fitting the shape into a circle */
+    maxRadius: number;
+}
+/**
+ * Samples the outline at `samples` angles. The shape must be star-shaped
+ * around its bounds centre, which every Material shape is: each ray from the
+ * centre crosses the outline once.
+ */
+export declare const radialProfile: (polygon: RoundedPolygon, samples?: number, stepsPerCubic?: number) => RadialProfile;
+export { polygonMaxRadius };

package/dist/core/shapes/polygon.d.ts

@@ -0,0 +1,35 @@
+import { Cubic, PointTransformer } from './cubic';
+/** How a vertex is rounded: the radius, and how much the curve is smoothed into the sides (0–1) */
+export interface CornerRounding {
+    radius: number;
+    smoothing?: number;
+}
+export declare const UNROUNDED: CornerRounding;
+/** A closed shape made of contiguous cubics */
+export interface RoundedPolygon {
+    cubics: Cubic[];
+    centerX: number;
+    centerY: number;
+}
+/**
+ * Builds a rounded polygon from a flat list of vertex coordinates
+ * [x0, y0, x1, y1, ...], a rounding for every vertex or one per vertex, and
+ * an optional centre (the vertices' centroid by default).
+ */
+export declare const roundedPolygon: (vertices: number[], rounding?: CornerRounding, perVertexRounding?: CornerRounding[], centerX?: number, centerY?: number) => RoundedPolygon;
+/** A regular polygon, first vertex at angle 0 */
+export declare const regularPolygon: (numVertices: number, radius?: number, centerX?: number, centerY?: number, rounding?: CornerRounding, perVertexRounding?: CornerRounding[]) => RoundedPolygon;
+/** A circle approximated by a fully rounded polygon */
+export declare const circle: (numVertices?: number, radius?: number, centerX?: number, centerY?: number) => RoundedPolygon;
+/** A star with `numVerticesPerRadius` outer and inner vertices, outer first at angle 0 */
+export declare const star: (numVerticesPerRadius: number, radius?: number, innerRadius?: number, rounding?: CornerRounding, innerRounding?: CornerRounding, perVertexRounding?: CornerRounding[], centerX?: number, centerY?: number) => RoundedPolygon;
+export declare const transformPolygon: (polygon: RoundedPolygon, f: PointTransformer) => RoundedPolygon;
+/** Rotation about the origin, in degrees, positive clockwise on a y-down canvas */
+export declare const rotatePolygon: (polygon: RoundedPolygon, degrees: number) => RoundedPolygon;
+export declare const scalePolygon: (polygon: RoundedPolygon, sx: number, sy?: number) => RoundedPolygon;
+/** Bounding box [left, top, right, bottom] from the hull of anchors and controls */
+export declare const polygonBounds: (polygon: RoundedPolygon) => [number, number, number, number];
+/** The farthest any anchor or curve midpoint gets from the centre */
+export declare const polygonMaxRadius: (polygon: RoundedPolygon) => number;
+/** Fits the shape into the unit square, centred, keeping its aspect ratio */
+export declare const normalizePolygon: (polygon: RoundedPolygon) => RoundedPolygon;