ducjs/dist/restore/restoreDataState.d.ts

The duc 2D CAD file format is a cornerstone of our advanced design system, conceived to cater to professionals seeking precision and efficiency in their design work.

import { BLENDING } from "../flatbuffers/duc";
import { Standard } from "../technical/standards";
import type { Dictionary, DucExternalFiles, DucGlobalState, ImportedDataState, LibraryItems, PrecisionValue, Scope, VersionGraph } from "../types";
import { DucLocalState } from "../types";
import type { _DucStackBase, BezierMirroring, DucBlock, DucElement, DucGroup, DucHead, DucLayer, DucRegion, ElementBackground, ElementContentBase, ElementStroke, ExternalFileId, FillStyle, ImageStatus, LineHead, OrderedDucElement, StrokeCap, StrokeJoin, StrokePreference, StrokeSidePreference, StrokeStyle, TextAlign, VerticalAlign } from "../types/elements";
import { Percentage, Radian } from "../types/geometryTypes";
import { ValueOf } from "../types/utility-types";
import { VERSIONS } from "../utils/constants";
export type RestoredLocalState = Omit<DucLocalState, "offsetTop" | "offsetLeft" | "width" | "height">;
export type RestoredDataState = {
    thumbnail: Uint8Array | undefined;
    dictionary: Dictionary | undefined;
    elements: OrderedDucElement[];
    localState: RestoredLocalState;
    globalState: DucGlobalState;
    files: DucExternalFiles;
    blocks: DucBlock[];
    groups: DucGroup[];
    regions: DucRegion[];
    layers: DucLayer[];
    standards: Standard[];
    versionGraph: VersionGraph | undefined;
};
export interface ExportedLibraryData {
    type: string;
    version: typeof VERSIONS.excalidrawLibrary;
    source: string;
    libraryItems: LibraryItems;
}
export interface ImportedLibraryData extends Partial<ExportedLibraryData> {
    /** @deprecated v1 */
    library?: LibraryItems;
}
export type ElementsConfig = {
    syncInvalidIndices: (elements: readonly DucElement[], currentScope: Scope) => OrderedDucElement[];
    refreshDimensions?: boolean;
    repairBindings?: boolean;
    /**
     * Optional list of element ids that should bypass normal validation
     * during restore and be passed through as-is to `restoreElements`.
     */
    passThroughElementIds?: string[];
};
export declare const restore: (data: ImportedDataState | null, elementsConfig: ElementsConfig) => RestoredDataState;
export declare const restoreFiles: (importedFiles: unknown) => DucExternalFiles;
export declare const restoreDictionary: (importedDictionary: unknown) => Dictionary;
/**
 * Restores the groups array from imported data, ensuring each item
 * conforms to the DucGroup type.
 *
 * This function iterates through the raw input, filters out any invalid entries,
 * and constructs a new array of clean, validated DucGroup objects.
 *
 * @param groups - The raw, untrusted array of group-like objects.
 * @returns A validated array of DucGroup objects, or an empty array if the input is invalid.
 */
export declare const restoreGroups: (groups: unknown) => RestoredDataState["groups"];
/**
 * Restores the layers array from imported data, ensuring each item
 * conforms to the DucLayer type.
 *
 * This function deeply validates each layer, including its nested 'overrides'
 * for default stroke and background styles. It provides safe defaults for any
 * missing or invalid properties.
 *
 * @param layers - The raw, untrusted array of layer-like objects.
 * @param currentScope - The current drawing scope, required for restoring
 *   scope-dependent properties like stroke width.
 * @returns A validated array of DucLayer objects, or an empty array if the input is invalid.
 */
export declare const restoreLayers: (layers: unknown, currentScope: Scope) => RestoredDataState["layers"];
/**
 * Restores the regions array, ensuring correct structure and types.
 */
export declare const restoreRegions: (regions: unknown) => RestoredDataState["regions"];
/**
 * Restores the blocks array using a two-pass approach to resolve circular dependencies.
 *
 * Pass 1: Creates a "shallow" version of each block with all top-level properties
 * but an empty `elements` array. This provides a complete reference list of all blocks.
 *
 * Pass 2: Iterates over the shallow blocks, calling `restoreElements` for each one,
 * providing the complete block list from Pass 1 as the necessary context.
 */
export declare const restoreBlocks: (blocks: unknown, currentScope: Scope, elementsConfig: ElementsConfig) => RestoredDataState["blocks"];
/**
 * Restores the global state of the document from imported data.
 * It validates and provides defaults for missing or invalid properties.
 *
 * @param importedState - The partially imported global state data.
 * @returns A complete and valid DucGlobalState object.
 */
export declare const restoreGlobalState: (importedState?: Partial<DucGlobalState>) => DucGlobalState;
/**
 * Restores the user's local session state from imported data.
 * It requires the already-restored global state to correctly calculate dependent values
 * like zoom and scope.
 *
 * @param importedState - The partially imported local state data.
 * @param restoredGlobalState - The complete and valid global state for the document.
 * @returns A complete and valid DucLocalState object.
 */
export declare const restoreLocalState: (importedState: Partial<DucLocalState> | undefined, restoredGlobalState: RestoredDataState["globalState"], restoredStandards: RestoredDataState["standards"]) => DucLocalState;
export declare const restoreVersionGraph: (importedGraph: any) => RestoredDataState["versionGraph"];
/**
 * Restores common properties for elements leveraging _DucStackBase.
 */
export declare const restoreDucStackProperties: (stack: any) => Omit<_DucStackBase, "id">;
export declare const isValidAppStateScopeValue: (value: string | undefined) => Scope;
export declare const isValidAppStateScopeExponentThresholdValue: (value: number | undefined, defaultValue: number) => number;
export declare const isValidPrecisionScopeValue: (zoom: number, mainScope: Scope, scopeExponentThreshold: number) => Scope;
/**
 * Converts a plain number or legacy value to a PrecisionValue object
 * @param value - The value to convert (can be a raw number or legacy value)
 * @param elementScope - The scope to use for the precision value
 * @returns A properly formatted PrecisionValue object
 */
export declare const restorePrecisionValue: (value: number | PrecisionValue | undefined, elementScope: Scope, currentScope: Scope, defaultValue?: number, fromScoped?: boolean) => PrecisionValue;
export declare const isValidFillStyleValue: (value: FillStyle | undefined) => FillStyle;
export declare const isValidStrokePreferenceValue: (value: StrokePreference | undefined) => StrokePreference;
export declare const isValidVerticalAlignValue: (value: VerticalAlign | undefined) => VerticalAlign;
export declare const isValidTextAlignValue: (value: TextAlign | undefined) => TextAlign;
export declare const isValidScopeValue: (value: string | undefined, localState?: Readonly<Partial<DucLocalState>> | null, mainScope?: Scope) => Scope;
export declare const isValidImageStatusValue: (value: ImageStatus | undefined) => ImageStatus;
export declare const isValidDucHead: (value: DucHead | null | undefined, blocks: RestoredDataState["blocks"], elementScope: Scope, currentScope: Scope) => DucHead | null;
export declare const isValidLineHeadValue: (value: LineHead | null | undefined) => LineHead | null;
export declare const isValidZoomStepValue: (value: number | undefined) => number;
export declare const isValidImageScaleValue: (value: [number, number] | undefined) => [number, number];
export declare const isValidBezierMirroringValue: (value: BezierMirroring | undefined) => BezierMirroring | undefined;
export declare const isValidStrokeSidePreferenceValue: (value: StrokeSidePreference | undefined) => StrokeSidePreference;
export declare const isValidStrokeCapValue: (value: StrokeCap | undefined) => StrokeCap;
export declare const isValidStrokeJoinValue: (value: StrokeJoin | undefined) => StrokeJoin;
export declare const isValidStrokeDashValue: (value: number[] | undefined) => number[];
export declare const isValidStrokeMiterLimitValue: (value: number | undefined) => number;
export declare const isValidBlendingValue: (value: ValueOf<typeof BLENDING> | undefined) => ValueOf<typeof BLENDING> | undefined;
export declare const validateElementContent: ({ content, defaultContent, }: {
    content: Partial<ElementContentBase> | undefined;
    defaultContent: ElementContentBase;
}) => ElementContentBase;
export declare const validateStrokeStyle: (style: Partial<StrokeStyle> | undefined) => StrokeStyle;
export declare const validateStroke: (stroke: ElementStroke | undefined, elementScope: Scope, currentScope: Scope) => ElementStroke;
export declare const validateBackground: (bg: ElementBackground | undefined) => ElementBackground;
export declare const isValidFinitePositiveByteValue: (value: number | undefined, defaultValue: number) => number;
export declare const isValidPolygonSides: (sides: any) => number;
export declare const isValidRadianValue: (value: number | Radian | undefined, defaultValue: Radian) => Radian;
/**
 * Validates a Percentage value.
 * Returns a clamped value within the <0,1> range or a provided default.
 */
export declare const isValidPercentageValue: (value: number | Percentage | undefined, defaultValue: Percentage, allowNegative?: boolean) => Percentage;
export declare const isValidBoolean: (value: any, defaultValue?: boolean) => boolean;
/**
 * Ensures the supplied easing function is valid. Falls back to the default easing otherwise.
 */
export declare const isValidFunction: <T extends Function>(value: unknown, defaultFn: T) => T;
export declare const isValidColor: (value: any, defaultValue?: string) => string;
/**
 * Validates a string value.
 * Returns the string if valid, otherwise returns the provided defaultValue or an empty string.
 */
export declare const isValidString: (value: any, defaultValue?: string) => string;
export declare const isValidExternalFileId: (value: any, defaultValue?: ExternalFileId) => ExternalFileId;
/**
 * Validates a value to ensure it is or can be converted to a non-empty Uint8Array.
 *
 * This function handles three types of input:
 * 1. An existing `Uint8Array`.
 * 2. A Base64-encoded string.
 * 3. A full Data URL string (e.g., "data:image/png;base64,...").
 *
 * @param value The unknown value to validate.
 * @returns A valid, non-empty `Uint8Array` if the conversion is successful, otherwise `undefined`.
 */
export declare const isValidUint8Array: (value: unknown) => Uint8Array | undefined;
/**
 * Validates a Standard id.
 * Returns the id if valid and present in standards, otherwise returns the default DUC standard id.
 */
export declare const isValidStandardId: (id: any, standards: Standard[], defaultId?: string) => string;
/**
 * Validates a block id.
 * Returns the id if present in restored blocks, otherwise returns null.
 */
export declare const isValidBlockId: (blockId: any, blocks: RestoredDataState["blocks"]) => string | null;
/**
 * A generic helper to validate an enum value from a lookup object.
 * @param value The value to check.
 * @param enumObject The object containing valid enum values (e.g., VIEWPORT_SHADE_PLOT).
 * @param defaultValue The value to return if the input is invalid.
 */
export declare const isValidEnumValue: <T>(value: any, enumObject: object, defaultValue: T) => T;