mtrl 0.8.0-next.12 → 0.8.0-next.13

package/dist/components/progress/api.d.ts

@@ -27,8 +27,8 @@ interface CanvasComponent {
     hide?: () => void;
     show?: () => void;
     isVisible?: () => boolean;
-    startIndeterminateAnimation?: () => void;
-    stopIndeterminateAnimation?: () => void;
+    setIndeterminate?: (indeterminate: boolean) => void;
+    resize?: () => void;
 }
 /**
  * API configuration options for canvas-based progress component

package/dist/components/progress/constants.d.ts

@@ -1,143 +1,162 @@
-/**
- * Progress component variants
- */
 export declare const PROGRESS_VARIANTS: {
-    /** Standard horizontal progress bar */
     readonly LINEAR: "linear";
-    /** Circular spinner progress indicator */
     readonly CIRCULAR: "circular";
 };
-/**
- * Progress component shapes (linear only)
- */
 export declare const PROGRESS_SHAPES: {
-    /** Standard flat progress */
     readonly FLAT: "flat";
-    /** Wavy animated progress */
     readonly WAVY: "wavy";
 };
-/**
- * Progress component events
- */
 export declare const PROGRESS_EVENTS: {
-    /** Fired when progress value changes */
     readonly CHANGE: "change";
-    /** Fired when progress reaches 100% */
     readonly COMPLETE: "complete";
 };
-/**
- * Default configuration values
- */
 export declare const PROGRESS_DEFAULTS: {
-    /** Default progress variant */
     readonly VARIANT: "linear";
-    /** Initial progress value */
     readonly VALUE: 0;
-    /** Maximum progress value */
     readonly MAX: 100;
-    /** Buffer value for linear progress with buffer */
     readonly BUFFER: 0;
-    /** Default shape for linear indeterminate progress */
     readonly SHAPE: "flat";
-    /** Whether to show percentage label */
     readonly SHOW_LABEL: false;
-    /** Whether progress is indeterminate */
     readonly INDETERMINATE: false;
+    /** Accessible name when none is given */
+    readonly LABEL: "Loading";
 };
-/**
- * CSS classes for progress elements
- */
 export declare const PROGRESS_CLASSES: {
-    /** Container element class */
     readonly CONTAINER: "progress";
-    /** Linear variant class */
     readonly LINEAR: "progress--linear";
-    /** Circular variant class */
     readonly CIRCULAR: "progress--circular";
-    /** Track element (unfilled part) class */
     readonly TRACK: "progress__track";
-    /** Indicator element (filled part) class */
     readonly INDICATOR: "progress__indicator";
-    /** Buffer element class */
     readonly BUFFER: "progress__buffer";
-    /** Label element class */
     readonly LABEL: "progress__label";
-    /** Indeterminate state class */
     readonly INDETERMINATE: "progress--indeterminate";
-    /** Disabled state class */
     readonly DISABLED: "progress--disabled";
-    /** Test state class */
     readonly TEST: "progress--test";
     readonly TRANSITION: "progress--transition";
 };
 /**
- * Progress component measurements
+ * Colour roles (ProgressIndicatorTokens): the active indicator and the stop
+ * indicator take primary, the track secondary-container. A circular
+ * indeterminate indicator has no track.
  */
+export declare const PROGRESS_COLORS: {
+    readonly INDICATOR: "sys-color-primary";
+    readonly TRACK: "sys-color-secondary-container";
+    readonly STOP: "sys-color-primary";
+    /** Not an M3 role: the buffer is this library's own extension */
+    readonly BUFFER: "sys-color-primary-container";
+};
 export declare const PROGRESS_MEASUREMENTS: {
     readonly LINEAR: {
-        readonly MIN_HEIGHT: 4;
+        /** Track and active indicator thickness (LinearProgressIndicatorTokens.Height) */
+        readonly HEIGHT: 4;
+        /** Space between the active indicator and the track (TrackActiveSpace) */
         readonly GAP: 4;
+        /** The dot that marks the end of the track (StopSize) */
         readonly STOP_INDICATOR: 4;
-        readonly HEIGHT: 4;
+        /** How far the stop indicator sits from the trailing edge, at most */
+        readonly STOP_TRAILING_SPACE: 6;
+        /** Container height of a wavy linear indicator (WaveHeight) */
+        readonly WAVE_HEIGHT: 10;
+        /** Inset from the edge of the element (m3.material.io: 4dp minimum) */
+        readonly EDGE_INSET: 4;
+        readonly MIN_HEIGHT: 4;
     };
     readonly CIRCULAR: {
-        readonly SIZE: 48;
-        readonly GAP: 8;
+        /** Flat container size (CircularProgressIndicatorTokens.Size) */
+        readonly SIZE: 40;
+        /** Wavy container size (CircularProgressIndicatorTokens.WaveSize) */
+        readonly WAVE_SIZE: 48;
+        /** Space between the active indicator and the track (TrackActiveSpace) */
+        readonly GAP: 4;
+        /** The guidelines' range for a circular indicator */
+        readonly MIN_SIZE: 24;
+        readonly MAX_SIZE: 240;
     };
     readonly COMMON: {
         readonly STROKE_WIDTH: 4;
     };
 };
-/**
- * Thickness presets for progress component
- * These are the standard thickness options following Material Design 3
- */
 export declare const PROGRESS_THICKNESS: {
-    /** Thin stroke width (4px) - default */
     readonly THIN: 4;
-    /** Thick stroke width (8px) */
     readonly THICK: 8;
 };
 /**
- * Wave animation parameters for progress components
+ * Wave geometry (LinearProgressIndicatorTokens, CircularProgressIndicatorTokens).
+ * Wavelengths and amplitudes are in dp at the default 4dp thickness and scale
+ * with the indicator's size.
  */
 export declare const PROGRESS_WAVE: {
-    /** Linear progress wave parameters */
     readonly LINEAR: {
-        /** Base amplitude of the wave in pixels */
-        readonly AMPLITUDE: 4;
-        /** Speed of wave animation in waves per second (Hz) */
-        readonly SPEED: 1;
-        /** Number of complete waves per 100 pixels */
-        readonly FREQUENCY: 2;
-        /** Number of complete waves per 100 pixels for indeterminate */
-        readonly INDETERMINATE_FREQUENCY: 4;
-        /** Amplitude for indeterminate animation */
-        readonly INDETERMINATE_AMPLITUDE: 2;
-        /** Wave shape power (lower = rounder peaks, higher = sharper) */
-        readonly POWER: 0.8;
-        /** Percentage at which wave amplitude reaches full strength from start */
-        readonly START_TRANSITION_END: 0;
-        /** Percentage at which wave amplitude begins to decrease near end */
-        readonly END_TRANSITION_START: 0.92;
+        /** ActiveWaveWavelength */
+        readonly WAVELENGTH: 40;
+        /** IndeterminateActiveWaveWavelength */
+        readonly INDETERMINATE_WAVELENGTH: 20;
+        /** ActiveWaveAmplitude */
+        readonly AMPLITUDE: 3;
+    };
+    readonly CIRCULAR: {
+        /** ActiveWaveWavelength */
+        readonly WAVELENGTH: 15;
+        /** ActiveWaveAmplitude */
+        readonly AMPLITUDE: 1.6;
+    };
+    /** The wave travels one wavelength per second (WavyProgressIndicatorDefaults) */
+    readonly SPEED: 1;
+    /**
+     * The wave flattens at both ends of the range
+     * (WavyProgressIndicatorDefaults.indicatorAmplitude)
+     */
+    readonly AMPLITUDE_START: 0.1;
+    readonly AMPLITUDE_END: 0.95;
+    /** How long the amplitude takes to appear or go (MotionTokens.DurationLong2) */
+    readonly AMPLITUDE_DURATION: 500;
+};
+/**
+ * Indeterminate motion (ProgressIndicator.kt)
+ */
+export declare const PROGRESS_MOTION: {
+    readonly LINEAR: {
+        /** LinearAnimationDuration */
+        readonly DURATION: 1750;
+        readonly FIRST_HEAD_DELAY: 0;
+        readonly FIRST_HEAD_DURATION: 1000;
+        readonly FIRST_TAIL_DELAY: 250;
+        readonly FIRST_TAIL_DURATION: 1000;
+        readonly SECOND_HEAD_DELAY: 650;
+        readonly SECOND_HEAD_DURATION: 850;
+        readonly SECOND_TAIL_DELAY: 900;
+        readonly SECOND_TAIL_DURATION: 850;
     };
-    /** Circular progress wave parameters */
     readonly CIRCULAR: {
-        /** Amplitude as percentage of radius (7 = 7%) */
-        readonly AMPLITUDE: 6;
-        /** Amplitude as percentage of radius for indeterminate (4 = 4%) */
-        readonly INDETERMINATE_AMPLITUDE: 4;
-        /** Speed of wave rotation in rotations per second (Hz), negative value means clockwise */
-        readonly SPEED: 1;
-        /** Number of complete waves around the circle */
-        readonly FREQUENCY: 10;
-        /** Number of complete waves for indeterminate animation */
-        readonly INDETERMINATE_FREQUENCY: 16;
-        /** Wave shape power (lower = rounder peaks, higher = sharper) */
-        readonly POWER: 0.8;
-        /** Percentage at which wave amplitude reaches full strength from start */
-        readonly START_TRANSITION_END: 0;
-        /** Percentage at which wave amplitude begins to decrease near end */
-        readonly END_TRANSITION_START: 0.92;
+        /** CircularAnimationProgressDuration */
+        readonly DURATION: 6000;
+        /** CircularAnimationAdditionalRotationDuration */
+        readonly ROTATION_DURATION: 300;
+        /** CircularAnimationAdditionalRotationDelay */
+        readonly ROTATION_DELAY: 1500;
+        /** CircularGlobalRotationDegreesTarget */
+        readonly GLOBAL_ROTATION: 1080;
+        /** CircularAdditionalRotationDegreesTarget */
+        readonly ADDITIONAL_ROTATION: 360;
+        /** CircularIndeterminateMinProgress */
+        readonly MIN_PROGRESS: 0.1;
+        /** CircularIndeterminateMaxProgress */
+        readonly MAX_PROGRESS: 0.87;
     };
+    /** How long a value change takes to animate (MotionTokens.DurationLong2) */
+    readonly VALUE_DURATION: 500;
+};
+/**
+ * Easing curves (MotionTokens), as cubic Bézier control points
+ */
+export declare const PROGRESS_EASING: {
+    /** EasingEmphasizedAccelerateCubicBezier */
+    readonly EMPHASIZED_ACCELERATE: readonly [0.3, 0, 0.8, 0.15];
+    /** EasingEmphasizedDecelerateCubicBezier */
+    readonly EMPHASIZED_DECELERATE: readonly [0.05, 0.7, 0.1, 1];
+    /** EasingStandardCubicBezier */
+    readonly STANDARD: readonly [0.2, 0, 0, 1];
+    /** EasingLinearCubicBezier */
+    readonly LINEAR: readonly [0, 0, 1, 1];
 };

package/dist/components/progress/features/canvas.d.ts

@@ -1,7 +1,4 @@
 import { ProgressConfig, ProgressThickness } from "../types";
-/**
- * Canvas dimensions and drawing context
- */
 export interface CanvasContext {
     canvas: HTMLCanvasElement;
     ctx: CanvasRenderingContext2D;
@@ -9,21 +6,6 @@ export interface CanvasContext {
     height: number;
     pixelRatio: number;
 }
-/**
- * Component with canvas capabilities
- */
-interface CanvasComponent {
-    element: HTMLElement;
-    canvas: HTMLCanvasElement;
-    ctx: CanvasRenderingContext2D;
-    getClass: (name: string) => string;
-    draw: () => void;
-    resize: () => void;
-    [key: string]: unknown;
-}
-/**
- * Base component interface for withCanvas
- */
 interface BaseComponent {
     element: HTMLElement;
     getClass: (name: string) => string;
@@ -38,24 +20,31 @@ interface BaseComponent {
         indeterminate?: boolean;
         [key: string]: unknown;
     };
-    animationId?: number | null;
-    wavyAnimationId?: number | null;
-    valueAnimationId?: number | null;
-    animationTime?: number;
-    setIndeterminate?: (indeterminate: boolean) => void;
     [key: string]: unknown;
 }
+export interface CanvasComponent extends BaseComponent {
+    canvas: HTMLCanvasElement;
+    ctx?: CanvasRenderingContext2D;
+    draw: () => void;
+    resize: () => void;
+}
 /**
- * Gets the stroke width for a given thickness preset or custom value
+ * Resolves a thickness preset or a number of pixels
  */
 export declare const getStrokeWidth: (thickness?: ProgressThickness) => number;
 /**
- * Calculates wave amplitude based on stroke width
- * Uses thickness 4 as the baseline (where amplitude is perfect)
+ * How tall the wave is, in pixels. The linear wave keeps the token's
+ * relationship to the track (3dp of wave to a 4dp track, which is the 10dp
+ * container the tokens describe), so a thicker track waves proportionally;
+ * the circular wave scales with the indicator's size, as the guidelines ask.
  */
-export declare const getWaveAmplitude: (strokeWidth: number, baseAmplitude: number, maxAmplitude?: number) => number;
+export declare const getWaveAmplitude: (isCircular: boolean, strokeWidth: number, size: number) => number;
+/** The container size of a circular indicator: 40dp flat, 48dp wavy */
+export declare const getCircularSize: (config: ProgressConfig) => number;
+/** The height of a linear indicator: the track, plus the wave on both sides */
+export declare const getLinearHeight: (strokeWidth: number, isWavy: boolean) => number;
 /**
- * Adds canvas functionality to replace complex DOM structure
+ * Adds the canvas, the drawing routine and the animation loop
  */
 export declare const withCanvas: (config: ProgressConfig) => (component: BaseComponent) => CanvasComponent;
 export {};

package/dist/components/progress/features/circular.d.ts

@@ -1,9 +1,19 @@
-/**
- * Circular progress drawing functionality
- */
-import { ProgressConfig, ProgressShape } from "../types";
 import { CanvasContext } from "./canvas";
+import { ProgressColors } from "./colors";
+/** What a frame of the circular indicator needs */
+export interface CircularFrame {
+    /** Progress from 0 to 1; ignored when indeterminate */
+    progress: number;
+    indeterminate: boolean;
+    /** Arc thickness in pixels */
+    strokeWidth: number;
+    /** Milliseconds since the animation started */
+    time: number;
+    /** Wave height in pixels; 0 draws a flat arc */
+    waveAmplitude: number;
+    colors: ProgressColors;
+}
 /**
- * Draws circular progress on canvas
+ * Draws one frame of the circular indicator.
  */
-export declare const drawCircularProgress: (context: CanvasContext, config: ProgressConfig, value: number, max: number, isIndeterminate: boolean, animationTime?: number, currentShape?: ProgressShape) => void;
+export declare const drawCircularProgress: (context: CanvasContext, frame: CircularFrame) => void;

package/dist/components/progress/features/colors.d.ts

@@ -0,0 +1,16 @@
+export interface ProgressColors {
+    indicator: string;
+    track: string;
+    stop: string;
+    buffer: string;
+}
+/**
+ * Keeps the palette for one indicator, refreshed when the theme changes.
+ * @param onChange - called after the colours change, to redraw
+ * @returns the palette getter and a cleanup function
+ */
+export declare const createColors: (onChange: () => void) => {
+    get: () => ProgressColors;
+    refresh: () => void;
+    destroy: () => void;
+};

package/dist/components/progress/features/linear.d.ts

@@ -1,9 +1,25 @@
-/**
- * Linear progress drawing functionality
- */
-import { ProgressConfig, ProgressShape } from "../types";
 import { CanvasContext } from "./canvas";
+import { ProgressColors } from "./colors";
+/** What a frame of the linear indicator needs */
+export interface LinearFrame {
+    /** Progress from 0 to 1; ignored when indeterminate */
+    progress: number;
+    /** Buffer from 0 to 1, this library's own extension; 0 for none */
+    buffer: number;
+    indeterminate: boolean;
+    /** Track and indicator thickness in pixels */
+    strokeWidth: number;
+    /** Milliseconds since the animation started */
+    time: number;
+    /** Wave height in pixels; 0 draws a flat indicator */
+    waveAmplitude: number;
+    /** Right to left, in which case the indicator runs from the right */
+    rtl: boolean;
+    colors: ProgressColors;
+    /** Whether to mark the end of the track with a dot */
+    showStopIndicator: boolean;
+}
 /**
- * Draws linear progress on canvas with shape support
+ * Draws one frame of the linear indicator.
  */
-export declare const drawLinearProgress: (context: CanvasContext, config: ProgressConfig, value: number, max: number, buffer: number, isIndeterminate: boolean, animationTime?: number, showStopIndicator?: boolean, currentShape?: ProgressShape) => void;
+export declare const drawLinearProgress: (context: CanvasContext, frame: LinearFrame) => void;

package/dist/components/progress/features/motion.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A cubic Bézier easing, as CSS and Compose define it: the curve through
+ * (0,0), (x1,y1), (x2,y2), (1,1), solved for y at a given x.
+ */
+export declare const cubicBezier: (x1: number, y1: number, x2: number, y2: number) => ((t: number) => number);
+export declare const emphasizedAccelerate: (t: number) => number;
+export declare const emphasizedDecelerate: (t: number) => number;
+export declare const standardEasing: (t: number) => number;
+/** Where the two indeterminate bars are, as fractions of the track */
+export interface LinearIndeterminateFrame {
+    firstHead: number;
+    firstTail: number;
+    secondHead: number;
+    secondTail: number;
+}
+/**
+ * The linear indeterminate frame at `elapsed` milliseconds: two bars, each
+ * from its tail to its head, on the Compose keyframes over a 1750ms cycle.
+ */
+export declare const linearIndeterminateFrame: (elapsed: number) => LinearIndeterminateFrame;
+/** How far round the arc has turned, and how much of the circle it covers */
+export interface CircularIndeterminateFrame {
+    /** Rotation of the arc's start, in degrees clockwise from 3 o'clock */
+    rotation: number;
+    /** Length of the arc as a fraction of the circle */
+    sweep: number;
+}
+/**
+ * The circular indeterminate frame at `elapsed` milliseconds: a 1080 degree
+ * linear turn over the 6 second cycle, four 90 degree kicks on top of it, and
+ * an arc that grows to 87% by half way and shrinks back to 10%.
+ */
+export declare const circularIndeterminateFrame: (elapsed: number) => CircularIndeterminateFrame;
+/**
+ * How tall the wave is for a determinate value: flat at both ends of the
+ * range, full in between (WavyProgressIndicatorDefaults.indicatorAmplitude).
+ */
+export declare const waveAmplitudeTarget: (progress: number) => number;
+/**
+ * The wave's height part way through a change: standard easing on the way in,
+ * emphasized accelerate on the way out, over 500ms either way.
+ */
+export declare const waveAmplitudeAt: (from: number, target: number, elapsed: number) => number;

package/dist/components/progress/index.d.ts

@@ -1,2 +1,2 @@
 export { default } from "./progress";
-export { ProgressConfig, ProgressComponent, ProgressShape } from "./types";
+export type { ProgressConfig, ProgressComponent, ProgressShape } from "./types";

package/dist/components/progress/types.d.ts

@@ -74,6 +74,19 @@ export interface ProgressConfig {
      * @default false
      */
     indeterminate?: boolean;
+    /**
+     * Whether to mark the end of a linear determinate track with a 4dp dot.
+     * The dot is required unless the track has at least 3:1 contrast with
+     * everything around it (M3 progress indicator accessibility), so it is on
+     * by default.
+     * @default true
+     */
+    showStopIndicator?: boolean;
+    /**
+     * Accessible name: what is loading, such as "Loading news article"
+     * @default 'Loading'
+     */
+    ariaLabel?: string;
     /**
      * Custom label formatter function
      */
@@ -111,6 +124,10 @@ export interface ProgressComponent {
     track: SVGElement;
     /** The indicator element (filled part) - always an SVG element */
     indicator: SVGElement;
+    /** The canvas the indicator is drawn on */
+    canvas?: HTMLCanvasElement;
+    /** Re-measures the canvas and redraws; the component does this on resize */
+    resize?: () => void;
     /** The buffer element for linear variant (pre-loaded state) - always an SVG element */
     buffer?: SVGElement;
     /**