morphico 0.2.0 → 0.4.0

package/dist/types/clip.d.ts

@@ -0,0 +1,57 @@
+import type { MorphOptions, MorphResult } from './morph.js';
+import type { IconSet } from './types.js';
+/** A length: a number = % (of the element's width for x and size, of its height for y), or `'40%'` / `'120px'`. */
+export type Length = number | string;
+/** Only a band along the shape's edge shows. */
+export interface ClipOutline {
+    /** Width of the band in px. */
+    width: number;
+    /** Where the band sits: inside the edge (default), on it (`'centre'`) or outside it. */
+    band?: 'inside' | 'centre' | 'outside';
+}
+/** What can change, in `clip()` and in every `to()` / `set()`. */
+export interface ClipChanges {
+    /** Centre of the shape, from the element's left edge (default 50 = the middle). */
+    x?: Length;
+    /** Centre of the shape, from the element's top edge (default 50 = the middle). */
+    y?: Length;
+    /** Side of the shape's square (default: the largest square that fits the element). */
+    size?: Length;
+    /** Turn in degrees, clockwise; absolute (`rotation: 360` ends one full turn from 0). */
+    rotation?: number;
+    /** Corners: 1 = the shape's own (default, the roundest) … 0 = sharp. */
+    roundness?: number;
+    /** `false` (default) = the whole shape shows; an outline = only a band along its edge (not animated). */
+    outline?: false | ClipOutline;
+    /** `true` = the other way round: the shape (or band) is a hole, the rest of the element shows (not animated). */
+    inverted?: boolean;
+}
+export interface ClipOptions extends ClipChanges, MorphOptions {
+    /** The shape set (default: the built-in shapes, based on Lucide). */
+    set?: IconSet;
+    /** The shape shown first (default `'circle'`). */
+    state?: string;
+}
+export interface ClipChangeOptions extends ClipChanges, MorphOptions {
+    /** Called when the change ends, with the same result the promise resolves to. */
+    onEnd?: (result: MorphResult) => void;
+}
+export interface Clip {
+    /** The shape shown, or being morphed to. */
+    readonly state: string;
+    /**
+     * Morphs to the shape `state` and animates the given changes along (move, resize, turn, roundness), or — called with
+     * only an object — animates those changes and keeps the shape. The promise resolves when it ends; an interrupted
+     * change resolves with `interrupted: true`. Without animation when the user prefers reduced motion.
+     */
+    to(state: string, options?: ClipChangeOptions): Promise<MorphResult>;
+    to(changes: ClipChangeOptions): Promise<MorphResult>;
+    /** Jumps (no animation), e.g. while a slider is dragged. Stops a running change (it resolves as interrupted). */
+    set(changes: ClipChanges & {
+        state?: string;
+    }): void;
+    /** Stops, removes the hidden <svg> and gives the element back its own clip-path / mask. */
+    destroy(): void;
+}
+/** Cuts `element` out by a morphing shape. */
+export declare const clip: (element: HTMLElement | SVGElement, options?: ClipOptions) => Clip;

package/dist/types/face.d.ts

@@ -0,0 +1,31 @@
+import type { MorphOptions, MorphResult } from './morph.js';
+import type { FaceExpression } from './sets/faces.js';
+export interface FaceOptions extends MorphOptions {
+    /** The expression shown first (default `'normal'`). */
+    state?: FaceExpression;
+    /** Color of the pupils (default `'white'`). Brows, eyes and mouth take the CSS `color`. */
+    pupilColor?: string;
+    /** Blink by itself every few seconds (default `true`). Off when the user prefers reduced motion. */
+    blink?: boolean;
+    /** CSS width and height of the face (default `'100%'`: it fills the element). */
+    size?: string;
+}
+export interface FaceChangeOptions extends MorphOptions {
+    /** Called when the morph ends, with the same result the promise resolves to. */
+    onEnd?: (result: MorphResult) => void;
+}
+export interface Face {
+    /** The expression shown, or being morphed to. */
+    readonly state: FaceExpression;
+    /**
+     * Morphs to another expression. The promise resolves when the morph ends; an interrupted morph resolves with
+     * `interrupted: true`. Without animation when the user prefers reduced motion.
+     */
+    to(state: FaceExpression, options?: FaceChangeOptions): Promise<MorphResult>;
+    /** Closes the eyes and opens them again, on top of the expression (none while asleep or with reduced motion). */
+    blink(): Promise<void>;
+    /** Stops everything and removes the face from the page. */
+    destroy(): void;
+}
+/** Adds a morphing face (an <svg>) to `element`. */
+export declare const face: (element: Element, options?: FaceOptions) => Face;

package/dist/types/index.d.ts

@@ -1,11 +1,17 @@
+export { clip } from './clip.js';
 export { easings } from './engine.js';
+export { face } from './face.js';
 export { icon } from './icon.js';
 export { iconSets } from './iconSets.js';
+export { faceExpressionNames } from './sets/faces.js';
 export { text } from './text.js';
+export type { Clip, ClipChangeOptions, ClipChanges, ClipOptions, ClipOutline, Length } from './clip.js';
 export type { Easing } from './engine.js';
+export type { Face, FaceChangeOptions, FaceOptions } from './face.js';
 export type { ChangeOptions, Icon, IconOptions } from './icon.js';
 export type { IconSetName } from './iconSets.js';
 export type { EasingName, MorphOptions, MorphResult } from './morph.js';
+export type { FaceExpression } from './sets/faces.js';
 export type { StyleOptions } from './svg.js';
 export type { SetOptions, Text, TextOptions, TextResult } from './text.js';
 export type { IconSet, TextLayout } from './types.js';

package/dist/types/morph.d.ts

@@ -1,6 +1,6 @@
 import { easings } from './engine.js';
 import type { Easing } from './engine.js';
-import type { IconSet } from './types.js';
+import type { IconSet, PathNumbers } from './types.js';
 export type EasingName = keyof typeof easings;
 export interface MorphOptions {
     /** Length of a morph in milliseconds (default 400). */
@@ -16,7 +16,11 @@ export interface MorphResult {
 }
 /** The empty state: nothing is drawn. Shapes grow out of it and shrink into it while fading. */
 export declare const EMPTY_STATE = " ";
+export declare const DEFAULT_DURATION = 400;
+export declare const shapesOf: (iconSet: IconSet) => Record<string, PathNumbers>;
 export declare const hasState: (iconSet: IconSet, state: string) => boolean;
+export declare const prefersReducedMotion: () => boolean;
+export declare const clampToUnit: (value: number) => number;
 export interface MorphingPath {
     /** The state shown, or being morphed to. */
     readonly state: string;

package/dist/types/sets/faces.d.ts

@@ -0,0 +1,25 @@
+import type { Point } from '../types.js';
+export declare const OUTLINE_POINTS = 24;
+export declare const PIECE_NAMES: readonly ['leftBrow', 'rightBrow', 'leftEye', 'rightEye', 'leftPupil', 'rightPupil', 'mouth'];
+type PieceName = typeof PIECE_NAMES[number];
+/** One expression: the outline points of every piece. */
+export type FacePieces = Record<PieceName, Point[]>;
+export declare const faceExpressionNames: readonly ['normal', 'smiling', 'pleading', 'wonder', 'focused', 'fright', 'angry', 'asleep', 'sad', 'surprised', 'laughing', 'tired', 'wink-left', 'wink-right', 'suspicious', 'confused', 'smug', 'irritated', 'bored', 'curious', 'empathetic', 'guilty', 'worried', 'disappointed', 'ashamed', 'embarrassed', 'yearning', 'triumphant', 'proud', 'excited', 'scornful', 'disgusted'];
+export type FaceExpression = typeof faceExpressionNames[number];
+/** Every expression's pieces, built on first use (nothing runs at import). */
+export declare const faceExpressionPieces: () => Record<FaceExpression, FacePieces>;
+export declare const interpolateFace: (from: FacePieces, to: FacePieces, progress: number) => FacePieces;
+/** The face with its eyes partly closed: openness 1 = as drawn, 0 = shut to a flat slit (pupils gone). */
+export declare const blinked: (face: FacePieces, openness: number) => FacePieces;
+/** A smooth closed curve through the points: each handle points along the neighbours' chord and is a third of its own
+ * segment long (no loops where points sit close together, as at a band's round end). Empty for a hidden piece. */
+export declare const smoothClosedPath: (points: Point[]) => string;
+export interface FacePaths {
+    /** Brows, eyes and mouth (one colour). */
+    features: string;
+    /** Both eyes, to clip the pupils with. */
+    eyes: string;
+    pupils: string;
+}
+export declare const facePaths: (face: FacePieces) => FacePaths;
+export {};

package/dist/types/sets/shapes.d.ts

@@ -0,0 +1,5 @@
+import type { IconSet, Stroke } from '../types.js';
+/** The shapes as Lucide draws them (Lucide coordinates); the set's states are made from these. */
+export declare const lucideShapeOutlines: Record<string, Stroke[]>;
+/** The shape set of clip(): states `circle`, `ellipse`, `heart` … `puzzle` (see `lucideShapeOutlines`). */
+export declare const clipShapes: IconSet;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "morphico",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Morphing line-art icons: smooth SVG path transitions between digits and other states. No dependencies.",
   "license": "MIT AND ISC",
   "author": "Raycho Ivanov",