ducjs 1.0.0

package/dist/legacy/v1/utils/math/random.d.ts

@@ -0,0 +1,4 @@
+export declare function randomSeed(): number;
+export declare const randomInteger: () => number;
+export declare const reseed: (seed: number) => void;
+export declare const randomId: () => string;

package/dist/legacy/v1/utils/math/random.js

@@ -0,0 +1,25 @@
+import { nanoid } from "nanoid";
+export function randomSeed() {
+    return Math.floor(Math.random() * Math.pow(2, 31));
+}
+class Random {
+    constructor(seed) {
+        this.seed = seed;
+    }
+    next() {
+        if (this.seed) {
+            return ((Math.pow(2, 31) - 1) & (this.seed = Math.imul(48271, this.seed))) / Math.pow(2, 31);
+        }
+        else {
+            return Math.random();
+        }
+    }
+}
+let random = new Random(Date.now());
+let testIdBase = 0;
+export const randomInteger = () => Math.floor(random.next() * Math.pow(2, 31));
+export const reseed = (seed) => {
+    random = new Random(seed);
+    testIdBase = 0;
+};
+export const randomId = () => nanoid();

package/dist/legacy/v1/utils/measurements.d.ts

@@ -0,0 +1,33 @@
+import { DucElement } from "ducjs/legacy/v1/types/elements";
+import { CombinedMeasure, ImperialMeasure, imperialMeasures, MetricMeasure, metricMeasures, ScaleFactors, SupportedMeasures } from "ducjs/legacy/v1/utils/scopes";
+export { imperialMeasures, metricMeasures, ScaleFactors };
+export type { CombinedMeasure, ImperialMeasure, MetricMeasure, SupportedMeasures };
+/**
+ * Gets translation factor between current scope and element scope
+ */
+export declare function getElementTranslationFactor(currentScope: CombinedMeasure, elementScope: CombinedMeasure): number;
+/**
+ * Gets the appropriate unit for the current zoom level
+ *
+ * @param zoom - Current zoom level
+ * @param mainMeasure - Main/base measurement unit
+ * @param scopeExpThreshold - Controls the sensitivity of precision scope changes
+ * @returns The most appropriate measurement unit for the current zoom
+ */
+export declare function getPrecisionScope(zoom: number, mainMeasure: SupportedMeasures, scopeExpThreshold: number): SupportedMeasures;
+export declare const coordinateToRealMeasure: (coordinate: number, currentScope: CombinedMeasure, elementScope: CombinedMeasure) => number;
+export declare const realMeasureToCoordinate: (realMeasure: number, gridUnit: number) => number;
+export declare function filterElementsByScope<T extends DucElement>(elements: readonly T[], currentScope: CombinedMeasure): T[];
+/**
+ * Calculates the approximate size of a single physical device pixel in millimeters.
+ *
+ * This calculation is based on the standard CSS definition of a reference pixel
+ * (1/96th of an inch) and the current devicePixelRatio of the window.
+ *
+ * It reflects the effective size of the smallest addressable pixel by the browser,
+ * considering screen density and browser/OS zoom levels.
+ *
+ * @returns {number} The approximate size of a physical pixel in millimeters.
+ * Returns NaN if window or window.devicePixelRatio is not available (e.g., in a Node.js environment).
+ */
+export declare const getPhysicalDevicePixelSizeInMm: () => number;

package/dist/legacy/v1/utils/measurements.js

@@ -0,0 +1,65 @@
+import { calculateScope, getTranslationFactor, imperialMeasures, metricMeasures, ScaleFactors } from "ducjs/legacy/v1/utils/scopes";
+export { imperialMeasures, metricMeasures, ScaleFactors };
+/**
+ * Gets translation factor between current scope and element scope
+ */
+export function getElementTranslationFactor(currentScope, elementScope) {
+    return getTranslationFactor(elementScope, currentScope);
+}
+/**
+ * Gets the appropriate unit for the current zoom level
+ *
+ * @param zoom - Current zoom level
+ * @param mainMeasure - Main/base measurement unit
+ * @param scopeExpThreshold - Controls the sensitivity of precision scope changes
+ * @returns The most appropriate measurement unit for the current zoom
+ */
+export function getPrecisionScope(zoom, mainMeasure, scopeExpThreshold) {
+    return calculateScope(zoom, scopeExpThreshold, mainMeasure);
+}
+export const coordinateToRealMeasure = (coordinate, currentScope, elementScope) => {
+    const translationFactor = getElementTranslationFactor(currentScope, elementScope);
+    // 100 grid units is 1,00 real unit
+    return coordinate * translationFactor / 100;
+};
+export const realMeasureToCoordinate = (realMeasure, gridUnit) => {
+    // x grid units * 100 = 1,00 real unit
+    return realMeasure * 10 * gridUnit;
+};
+export function filterElementsByScope(elements, currentScope) {
+    return elements.filter((element) => element.scope === currentScope);
+}
+/**
+ * Calculates the approximate size of a single physical device pixel in millimeters.
+ *
+ * This calculation is based on the standard CSS definition of a reference pixel
+ * (1/96th of an inch) and the current devicePixelRatio of the window.
+ *
+ * It reflects the effective size of the smallest addressable pixel by the browser,
+ * considering screen density and browser/OS zoom levels.
+ *
+ * @returns {number} The approximate size of a physical pixel in millimeters.
+ * Returns NaN if window or window.devicePixelRatio is not available (e.g., in a Node.js environment).
+ */
+export const getPhysicalDevicePixelSizeInMm = () => {
+    // Check if running in a browser environment where window and devicePixelRatio are available
+    if (typeof window === 'undefined' || typeof window.devicePixelRatio === 'undefined') {
+        console.warn('window.devicePixelRatio is not available. This function should be run in a browser environment.');
+        return NaN; // Not applicable or calculable outside a browser context
+    }
+    // Standard conversion: 1 inch = 25.4 millimeters
+    const mmPerInch = 25.4;
+    // Standard CSS pixels per inch (W3C reference pixel definition)
+    const cssPixelsPerInch = 96;
+    // Calculate the conceptual size of one CSS pixel in millimeters.
+    // This is the physical size a CSS pixel would ideally occupy if devicePixelRatio were 1.
+    const cssPixelSizeInMm = mmPerInch / cssPixelsPerInch;
+    // Get the current device pixel ratio from the window.
+    // This value accounts for the screen's native density and any browser or OS zoom applied.
+    const currentDevicePixelRatio = window.devicePixelRatio;
+    // The size of a single physical pixel is the conceptual size of a CSS pixel
+    // divided by the devicePixelRatio. This is because devicePixelRatio indicates
+    // how many physical pixels are used to render one CSS pixel in each dimension.
+    const physicalPixelSizeInMm = cssPixelSizeInMm / currentDevicePixelRatio;
+    return physicalPixelSizeInMm;
+};

package/dist/legacy/v1/utils/normalize.d.ts

@@ -0,0 +1,14 @@
+import type { NormalizedZoomValue, ScopedValue } from "ducjs/legacy/v1/types";
+import { DucElement, FixedPoint } from "ducjs/legacy/v1/types/elements";
+export declare const getNormalizedZoom: (zoom: number) => NormalizedZoomValue;
+export declare const getNormalizedGridSize: (gridStep: number) => number;
+export declare const getNormalizedGridStep: (gridStep: number) => number;
+export declare const normalizeFixedPoint: <T extends FixedPoint | null>(fixedPoint: T) => T extends null ? null : FixedPoint;
+export declare const getNormalizedDimensions: (element: Pick<DucElement, "width" | "height" | "x" | "y">) => {
+    width: ScopedValue;
+    height: ScopedValue;
+    x: ScopedValue;
+    y: ScopedValue;
+};
+export declare const normalizeEOL: (str: string) => string;
+export declare const normalizeText: (text: string) => string;

package/dist/legacy/v1/utils/normalize.js

@@ -0,0 +1,49 @@
+import { MAX_ZOOM, MIN_ZOOM } from "ducjs/legacy/v1/utils/constants";
+import { clamp } from "ducjs/legacy/v1/utils/math";
+export const getNormalizedZoom = (zoom) => {
+    return clamp(zoom, MIN_ZOOM, MAX_ZOOM);
+};
+export const getNormalizedGridSize = (gridStep) => {
+    return clamp(Math.round(gridStep), 1, 100);
+};
+export const getNormalizedGridStep = (gridStep) => {
+    return clamp(Math.round(gridStep), 1, 100);
+};
+export const normalizeFixedPoint = (fixedPoint) => {
+    // Do not allow a precise 0.5 for fixed point ratio
+    // to avoid jumping arrow heading due to floating point imprecision
+    if (fixedPoint && (fixedPoint.x === 0.5 || fixedPoint.y === 0.5)) {
+        return {
+            x: fixedPoint.x === 0.5 ? 0.5001 : fixedPoint.x,
+            y: fixedPoint.y === 0.5 ? 0.5001 : fixedPoint.y,
+        };
+    }
+    return fixedPoint;
+};
+export const getNormalizedDimensions = (element) => {
+    const ret = {
+        width: element.width.scoped,
+        height: element.height.scoped,
+        x: element.x.scoped,
+        y: element.y.scoped,
+    };
+    if (element.width.scoped < 0) {
+        const nextWidth = Math.abs(element.width.scoped);
+        ret.width = nextWidth;
+        ret.x = element.x.scoped - nextWidth;
+    }
+    if (element.height.scoped < 0) {
+        const nextHeight = Math.abs(element.height.scoped);
+        ret.height = nextHeight;
+        ret.y = element.y.scoped - nextHeight;
+    }
+    return ret;
+};
+export const normalizeEOL = (str) => {
+    return str.replace(/\r?\n|\r/g, "\n");
+};
+export const normalizeText = (text) => {
+    return (normalizeEOL(text)
+        // replace tabs with spaces so they render and measure correctly
+        .replace(/\t/g, "        "));
+};

package/dist/legacy/v1/utils/restore.d.ts

@@ -0,0 +1,197 @@
+import type { BinaryFiles, LibraryItem, LibraryItems, LibraryItems_anyVersion, PrecisionValue, RendererState, Scope } from "ducjs/legacy/v1/types";
+import { DucState } from "ducjs/legacy/v1/types";
+import type { BezierMirroring, DucBlock, DucElement, DucFreeDrawEasing, DucGroup, DucPoint, ElementSubset, FillStyle, ImageStatus, LineHead, OrderedDucElement, StrokeCap, StrokeJoin, StrokePreference, StrokeSidePreference, TextAlign, VerticalAlign } from "ducjs/legacy/v1/types/elements";
+import { Percentage, Radian } from "ducjs/legacy/v1/types/geometryTypes";
+import type { ValueOf } from "ducjs/legacy/v1/types/utility-types";
+import { BLENDING, VERSIONS } from "ducjs/legacy/v1/utils/constants";
+import { SupportedMeasures } from "ducjs/legacy/v1/utils/measurements";
+import { DesignStandard } from "ducjs/legacy/v1/utils/standards";
+type RestoredDucState = Omit<DucState, "offsetTop" | "offsetLeft" | "width" | "height">;
+export interface ExportedDataState {
+    type: string;
+    version: number;
+    source: string;
+    elements: readonly DucElement[];
+    appState: DucState;
+    files: BinaryFiles | undefined;
+}
+export interface ImportedDataState {
+    type?: string;
+    version?: number;
+    source?: string;
+    elements?: readonly DucElement[] | null;
+    appState?: Readonly<Partial<DucState>> | null;
+    scrollToContent?: boolean;
+    libraryItems?: LibraryItems_anyVersion;
+    files?: BinaryFiles;
+    rendererState?: RendererState;
+    blocks?: readonly DucBlock[];
+    groups?: readonly DucGroup[];
+}
+export interface ImportedExtendedDataState<TExtendedAppState = any> {
+    type?: string;
+    version?: number;
+    source?: string;
+    elements?: readonly DucElement[] | null;
+    appState?: Readonly<Partial<TExtendedAppState>> | null;
+    scrollToContent?: boolean;
+    libraryItems?: LibraryItems_anyVersion;
+    files?: BinaryFiles;
+    rendererState?: RendererState;
+    blocks?: readonly DucBlock[];
+    groups?: readonly DucGroup[];
+}
+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 RestoredDataState = {
+    elements: OrderedDucElement[];
+    appState: RestoredDucState;
+    files: BinaryFiles;
+    rendererState: RendererState | null;
+    blocks: DucBlock[];
+    groups: DucGroup[];
+};
+export type RestoredExtendedDataState<TExtendedAppState = any> = {
+    elements: OrderedDucElement[];
+    appState: TExtendedAppState;
+    files: BinaryFiles;
+    rendererState: RendererState | null;
+    blocks: DucBlock[];
+    groups: DucGroup[];
+};
+export type ExtendedAppStateRestorer<TExtendedAppState> = (extendedAppState: Partial<TExtendedAppState> | null | undefined, localExtendedAppState: Partial<TExtendedAppState> | null | undefined, restoredDucState: RestoredDucState) => TExtendedAppState;
+export type ElementsConfig = {
+    syncInvalidIndices: (elements: readonly DucElement[], currentScope: Scope) => OrderedDucElement[];
+    refreshDimensions?: boolean;
+    repairBindings?: boolean;
+    appState?: Readonly<Partial<DucState>> | null;
+};
+export declare const AllowedDucActiveTools: Record<DucState["activeTool"]["type"], boolean>;
+export declare const isValidElementScopeValue: (value: string | undefined, appState?: Readonly<Partial<DucState>> | null) => SupportedMeasures;
+export declare const isValidAppStateScopeValue: (value: string | undefined) => SupportedMeasures;
+export declare const isValidAppStateScopeExponentThresholdValue: (value: number | undefined, defaultValue: number) => number;
+export declare const isValidPrecisionScopeValue: (zoom: number, mainScope: SupportedMeasures, scopeExponentThreshold: number) => SupportedMeasures;
+/**
+ * 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: SupportedMeasures, currentScope: SupportedMeasures, defaultValue?: number, fromScoped?: boolean) => PrecisionValue;
+/**
+ * Restores a point that might have legacy format (x,y as numbers)
+ * @param point - The point to restore
+ * @param elementScope - The scope to use for the precision values
+ * @returns A properly formatted DucPoint
+ */
+export declare const restorePoint: (point: Partial<DucPoint> | {
+    x: number | PrecisionValue;
+    y: number | PrecisionValue;
+    isCurve?: boolean;
+    mirroring?: BezierMirroring;
+    handleIn?: {
+        x: number | PrecisionValue;
+        y: number | PrecisionValue;
+    };
+    handleOut?: {
+        x: number | PrecisionValue;
+        y: number | PrecisionValue;
+    };
+    borderRadius?: number | PrecisionValue;
+} | undefined, elementScope: SupportedMeasures, currentScope: SupportedMeasures) => DucPoint | null;
+/**
+ * Assigns z-index values to elements based on their position in the array.
+ * This recreates the original visual stacking that was implied by array order
+ * before explicit z-index support was added.
+ */
+export declare const migrateArrayOrderToZIndex: (elements: DucElement[]) => DucElement[];
+export declare const restoreElements: (elements: ImportedDataState["elements"], currentScope: Scope, 
+/** NOTE doesn't serve for reconciliation */
+localElements: readonly DucElement[] | null | undefined, opts?: {
+    refreshDimensions?: boolean;
+    repairBindings?: boolean;
+    appState?: Readonly<Partial<DucState>> | null;
+    syncInvalidIndices?: (elements: readonly DucElement[], currentScope: Scope) => OrderedDucElement[];
+}) => OrderedDucElement[];
+export declare const restoreDucState: (ducState: ImportedDataState["appState"], localDucState: Partial<DucState> | null | undefined) => RestoredDucState;
+/**
+ * Creates an extended AppState restorer function that can be provided as a prop.
+ * This handles restoration of extended AppState that wraps around DucState.
+ *
+ * @param restoreExtendedProps - Function to restore extended properties beyond DucState
+ * @returns A function that can restore the full extended AppState
+ */
+export declare const createExtendedAppStateRestorer: <TExtendedAppState extends Record<string, any>>(restoreExtendedProps: (extendedAppState: Partial<TExtendedAppState> | null | undefined, localExtendedAppState: Partial<TExtendedAppState> | null | undefined, restoredDucState: RestoredDucState) => Omit<TExtendedAppState, keyof DucState>) => ExtendedAppStateRestorer<TExtendedAppState>;
+export declare const noopExtendedAppStateRestorer: ExtendedAppStateRestorer<DucState>;
+/**
+ * Extended restore function that supports restoring extended AppState.
+ * This allows users of the library to provide their own AppState restoration logic.
+ */
+export declare function restore<TExtendedAppState>(data: Pick<ImportedExtendedDataState<TExtendedAppState>, "appState" | "elements" | "files" | "rendererState" | "blocks" | "groups"> | null, 
+/**
+ * Local extended AppState for fallback values.
+ * Supply `null` if you can't get access to it.
+ */
+localExtendedAppState: Partial<TExtendedAppState> | null | undefined, localElements: readonly DucElement[] | null | undefined, 
+/**
+ * Extended AppState restorer function that handles the extended properties.
+ * This should be created using `createExtendedAppStateRestorer`.
+ */
+extendedAppStateRestorer: ExtendedAppStateRestorer<TExtendedAppState>, elementsConfig?: ElementsConfig): RestoredExtendedDataState<TExtendedAppState>;
+export declare const restoreLibraryItems: (libraryItems: ImportedDataState["libraryItems"], defaultStatus: LibraryItem["status"], currentScope: Scope) => LibraryItem[];
+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, appState?: Readonly<Partial<DucState>> | null) => SupportedMeasures;
+export declare const isValidImageStatusValue: (value: ImageStatus | undefined) => ImageStatus;
+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 isValidSubsetValue: (value: ElementSubset | null | undefined) => ElementSubset | null;
+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 isValidFinitePositiveByteValue: (value: number | undefined, defaultValue: number) => number;
+/**
+ * Validates and returns a DesignStandard value, or the default if invalid.
+ */
+export declare const isValidStandard: (value: any) => DesignStandard;
+export declare const isValidPolygonSides: (sides: any) => number;
+/**
+ * Restores the groups array for AppState, ensuring correct structure and types.
+ */
+export declare const restoreGroups: (groups: any, currentScope: Scope) => DucGroup[];
+/**
+ * Restores common properties for elements leveraging _DucStackBase.
+ */
+export declare const restoreDucStackProperties: (stack: any, currentScope: SupportedMeasures) => Omit<DucGroup, "id" | "type">;
+/**
+ * Restores the blocks array, ensuring correct structure and types.
+ */
+export declare const restoreBlocks: (blocks: any, currentScope: SupportedMeasures) => DucBlock[];
+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;
+/**
+ * Ensures the supplied easing function is valid. Falls back to the default easing otherwise.
+ */
+export declare const isValidFreeDrawEasingValue: (value: DucFreeDrawEasing | undefined) => DucFreeDrawEasing;
+export declare const isValidBoolean: (value: any, defaultValue?: boolean) => boolean;
+export declare const isValidColor: (value: any, defaultValue?: string) => string;
+export {};