@zag-js/signature-pad/dist/signature-pad.types.d.ts

Core logic for the signature-pad widget implemented as a state machine

import { Machine, EventObject, Service } from '@zag-js/core';
import { PropTypes, RequiredBy, DirectionProperty, CommonProperties } from '@zag-js/types';
import { StrokeOptions } from 'perfect-freehand';
export { StrokeOptions } from 'perfect-freehand';

interface Point {
    x: number;
    y: number;
    pressure: number;
}
interface DrawDetails {
    paths: string[];
}
interface DrawingOptions extends StrokeOptions {
    /**
     * The color of the stroke.
     * Note: Must be a valid CSS color string, not a css variable.
     */
    fill?: string | undefined;
}
type DataUrlType = "image/png" | "image/jpeg" | "image/svg+xml";
interface DrawEndDetails {
    paths: string[];
    getDataUrl: (type: DataUrlType, quality?: number) => Promise<string>;
}
interface DataUrlOptions {
    type: DataUrlType;
    quality?: number | undefined;
}
type ElementIds = Partial<{
    root: string;
    control: string;
    hiddenInput: string;
    label: string;
}>;
interface IntlTranslations {
    clearTrigger: string;
    control: string;
}

interface SignaturePadProps extends DirectionProperty, CommonProperties {
    /**
     * The ids of the signature pad elements. Useful for composition.
     */
    ids?: ElementIds | undefined;
    /**
     * The translations of the signature pad. Useful for internationalization.
     */
    translations?: IntlTranslations | undefined;
    /**
     * Callback when the signature pad is drawing.
     */
    onDraw?: ((details: DrawDetails) => void) | undefined;
    /**
     * Callback when the signature pad is done drawing.
     */
    onDrawEnd?: ((details: DrawEndDetails) => void) | undefined;
    /**
     * The drawing options.
     * @default '{ size: 2, simulatePressure: true }'
     */
    drawing?: DrawingOptions | undefined;
    /**
     * Whether the signature pad is disabled.
     */
    disabled?: boolean | undefined;
    /**
     * Whether the signature pad is required.
     */
    required?: boolean | undefined;
    /**
     * Whether the signature pad is read-only.
     */
    readOnly?: boolean | undefined;
    /**
     * The name of the signature pad. Useful for form submission.
     */
    name?: string | undefined;
    /**
     * The default paths of the signature pad.
     * Use when you don't need to control the paths of the signature pad.
     */
    defaultPaths?: string[] | undefined;
    /**
     * The controlled paths of the signature pad.
     */
    paths?: string[] | undefined;
}
type PropsWithDefault = "drawing" | "translations";
interface PrivateContext {
    /**
     * The layers of the signature pad. A layer is a snapshot of a single stroke interaction.
     */
    paths: string[];
    /**
     * The current layer points.
     */
    currentPoints: Point[];
    /**
     * The current stroke path
     */
    currentPath: string | null;
}
type ComputedContext = Readonly<{
    isInteractive: boolean;
    isEmpty: boolean;
}>;
interface SignaturePadSchema {
    state: "idle" | "drawing";
    props: RequiredBy<SignaturePadProps, PropsWithDefault>;
    context: PrivateContext;
    computed: ComputedContext;
    action: string;
    event: EventObject;
    effect: string;
    guard: string;
}
type SignaturePadService = Service<SignaturePadSchema>;
type SignaturePadMachine = Machine<SignaturePadSchema>;
interface SegmentPathProps {
    path: string;
}
interface HiddenInputProps {
    value: string;
}
interface SignaturePadApi<T extends PropTypes = PropTypes> {
    /**
     * Whether the signature pad is empty.
     */
    empty: boolean;
    /**
     * Whether the user is currently drawing.
     */
    drawing: boolean;
    /**
     * The current path being drawn.
     */
    currentPath: string | null;
    /**
     * The paths of the signature pad.
     */
    paths: string[];
    /**
     * Returns the data URL of the signature pad.
     */
    getDataUrl: (type: DataUrlType, quality?: number) => Promise<string>;
    /**
     * Clears the signature pad.
     */
    clear: VoidFunction;
    getLabelProps: () => T["element"];
    getRootProps: () => T["element"];
    getControlProps: () => T["element"];
    getSegmentProps: () => T["svg"];
    getSegmentPathProps: (props: SegmentPathProps) => T["path"];
    getHiddenInputProps: (props: HiddenInputProps) => T["input"];
    getGuideProps: () => T["element"];
    getClearTriggerProps: () => T["element"];
}

export type { DataUrlOptions, DataUrlType, DrawDetails, DrawEndDetails, DrawingOptions, ElementIds, HiddenInputProps, IntlTranslations, Point, SegmentPathProps, SignaturePadApi, SignaturePadMachine, SignaturePadProps, SignaturePadSchema, SignaturePadService };