ducjs 1.0.0

package/dist/restore/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./restoreDataState";
+export * from "./restoreElements";
+export * from "./restoreStandards";

package/dist/restore/index.js

@@ -0,0 +1,3 @@
+export * from "./restoreDataState";
+export * from "./restoreElements";
+export * from "./restoreStandards";

package/dist/restore/restoreDataState.d.ts

@@ -0,0 +1,191 @@
+import { BLENDING } from "ducjs/flatbuffers/duc";
+import { Standard } from "ducjs/technical/standards";
+import type { Dictionary, DucExternalFiles, DucGlobalState, ImportedDataState, LibraryItems, PrecisionValue, Scope, VersionGraph } from "ducjs/types";
+import { DucLocalState } from "ducjs/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 "ducjs/types/elements";
+import { Percentage, Radian } from "ducjs/types/geometryTypes";
+import { ValueOf } from "ducjs/types/utility-types";
+import { VERSIONS } from "ducjs/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;