@sarmal/react/dist/index.d.cts

React components and hooks for @sarmal/core animated curves

import { BaseSarmalOptions, SarmalInstance, BaseDotMatrixOptions, DotMatrixRuntimeRenderOptions, BaseMorphOptions, CurveDef, SarmalOptions, CanvasInit, SVGSarmalOptions, BaseInit, DotMatrixSarmalOptions, DotMatrixInit } from '@sarmal/core';
export { CanvasInit, DotMatrixInit } from '@sarmal/core';
import * as react from 'react';
import { CSSProperties } from 'react';
import * as react_jsx_runtime from 'react/jsx-runtime';

/** Options forwarded to morphTo when the curve prop changes. */
type MorphOptions = Omit<BaseMorphOptions, "curve">;
/** Props shared by `<Sarmal>` and `<SarmalSVG>`. */
interface BaseSarmalProps extends BaseSarmalOptions {
    className?: string;
    style?: CSSProperties;
    onReady?: (instance: SarmalInstance) => void;
}
/** Props for `<Sarmal>`. Extends {@link BaseSarmalProps} with canvas buffer sizing. */
interface SarmalProps extends BaseSarmalProps {
    /** changing after mount recreates the instance and resets the trail */
    width?: number;
    /** changing after mount recreates the instance and resets the trail */
    height?: number;
}
/** Props for `<SarmalSVG>`. SVG scales naturally via CSS so no `width`/`height` sizing props are needed. */
type SarmalSVGProps = BaseSarmalProps;
/** Props for `<SarmalDotMatrix>`. */
interface SarmalDotMatrixProps extends BaseDotMatrixOptions {
    className?: string;
    style?: CSSProperties;
    onReady?: (instance: SarmalInstance<DotMatrixRuntimeRenderOptions>) => void;
    /** Canvas buffer width in pixels. @init */
    width?: number;
    /** Canvas buffer height in pixels. @init */
    height?: number;
}

declare function useSarmal(curve: CurveDef, options?: Partial<SarmalOptions>, init?: CanvasInit, morphOptions?: MorphOptions): {
    canvasRef: React.RefObject<HTMLCanvasElement | null>;
    instance: React.RefObject<SarmalInstance | null>;
};

declare const Sarmal: react.MemoExoticComponent<({ curve, className, style, trailColor, morphDuration, morphStrategy, morphEasing, morphAlign, onReady, skeletonColor, headColor, trailStyle, width, height, headRadius, trailLength, trailWidth, autoStart, initialPhase, pauseOnHidden, }: SarmalProps) => react_jsx_runtime.JSX.Element>;

/**
 * React hook for creating and managing a Sarmal SVG instance.
 * Mirrors the lifecycle of {@link useSarmal}
 *  but calls {@link createSarmalSVG} and returns an SVG ref instead of a canvas ref.
 * SVG elements scale with CSS, so width/height are not needed.
 * The renderer sets `viewBox="0 0 100 100"` on the root `<svg>`.
 *
 * @param curve The curve definition to render. Morphs on reference change.
 * @param options Runtime visual options (trailColor, headColor, etc.) which can be updated with setRenderOptions
 * @param init Initial options. Changing any of these destroys and recreates the instance
 * @param morphOptions Options forwarded to morphTo when the curve changes
 * @returns An object with `svgRef` (attach to an `<svg>` element) and `instance` (the live SarmalInstance)
 */
declare function useSarmalSVG(curve: CurveDef, options?: Partial<SVGSarmalOptions>, init?: BaseInit, morphOptions?: MorphOptions): {
    svgRef: React.RefObject<SVGSVGElement | null>;
    instance: React.RefObject<SarmalInstance | null>;
};

declare const SarmalSVG: react.MemoExoticComponent<({ curve, className, style, trailColor, morphDuration, morphStrategy, morphEasing, morphAlign, onReady, skeletonColor, headColor, trailStyle, headRadius, trailLength, trailWidth, autoStart, initialPhase, pauseOnHidden, }: SarmalSVGProps) => react_jsx_runtime.JSX.Element>;

/**
 * React hook for creating and managing a Sarmal dot matrix instance.
 * Mirrors the lifecycle of `useSarmal` but calls {@link createSarmalDotMatrix}.
 *
 * @param curve The curve definition to render. Morphs on reference change.
 * @param options Runtime visual options forwarded at creation.
 * @param init Initialization options. Changing any of these destroys and recreates the instance.
 * @param morphOptions Options forwarded to morphTo when the curve changes.
 */
declare function useSarmalDotMatrix(curve: CurveDef, options?: Partial<DotMatrixSarmalOptions>, init?: DotMatrixInit, morphOptions?: MorphOptions): {
    canvasRef: react.RefObject<HTMLCanvasElement | null>;
    instance: react.RefObject<SarmalInstance<DotMatrixRuntimeRenderOptions> | null>;
};

declare const SarmalDotMatrix: react.MemoExoticComponent<({ curve, className, style, trailColor, trailStyle, skeletonColor, gridColor, morphDuration, morphStrategy, morphEasing, morphAlign, onReady, cols, rows, roundness, trailLength, width, height, autoStart, initialPhase, pauseOnHidden, }: SarmalDotMatrixProps) => react_jsx_runtime.JSX.Element>;

export { type BaseSarmalProps, Sarmal, SarmalDotMatrix, type SarmalDotMatrixProps, type SarmalProps, SarmalSVG, type SarmalSVGProps, useSarmal, useSarmalDotMatrix, useSarmalSVG };