@pantheon-systems/puck-css 0.4.0

package/dist/versioning/useVersions.d.ts

@@ -0,0 +1,81 @@
+/**
+ * useVersions Hook
+ *
+ * Provides document version history and comparison functionality.
+ */
+import type { DocumentVersion } from '@pantheon-systems/css-client';
+import type { P1Client } from '@pantheon-systems/css-client';
+import type { ComponentDiff } from '../core/types.js';
+export interface UseVersionsParams {
+    client: P1Client;
+    siteId: string;
+    branchId: string;
+    documentId: string | null;
+}
+export interface UseVersionsReturn {
+    /**
+     * List of versions for the current document.
+     */
+    versions: DocumentVersion[];
+    /**
+     * Loading state.
+     */
+    loading: boolean;
+    /**
+     * Error state.
+     */
+    error: Error | null;
+    /**
+     * Refresh the versions list.
+     */
+    refresh: () => Promise<void>;
+    /**
+     * Get the latest version.
+     */
+    latestVersion: DocumentVersion | null;
+    /**
+     * Compare two versions.
+     */
+    compareVersions: (beforeId: string, afterId: string) => Promise<ComponentDiff[]>;
+    /**
+     * Get version by ID.
+     */
+    getVersion: (versionId: string) => DocumentVersion | undefined;
+    /**
+     * Currently selected version for comparison.
+     */
+    selectedVersion: DocumentVersion | null;
+    /**
+     * Set selected version for comparison.
+     */
+    setSelectedVersion: (version: DocumentVersion | null) => void;
+    /**
+     * Comparison result.
+     */
+    comparisonDiffs: ComponentDiff[] | null;
+    /**
+     * Whether comparison is loading.
+     */
+    isComparing: boolean;
+}
+/**
+ * Hook for managing document versions and comparisons.
+ *
+ * @param params - Configuration for version management
+ * @returns Version state and operations
+ *
+ * @example
+ * ```tsx
+ * const { versions, compareVersions, latestVersion } = useVersions({
+ *   client,
+ *   siteId,
+ *   branchId,
+ *   documentId,
+ * });
+ *
+ * // Compare versions
+ * const diffs = await compareVersions(oldVersionId, newVersionId);
+ * ```
+ */
+export declare function useVersions({ client, siteId, branchId, documentId, }: UseVersionsParams): UseVersionsReturn;
+//# sourceMappingURL=useVersions.d.ts.map

package/dist/versioning/useVersions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVersions.d.ts","sourceRoot":"","sources":["../../src/versioning/useVersions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAY,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE5B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;OAEG;IACH,aAAa,EAAE,eAAe,GAAG,IAAI,CAAC;IAEtC;;OAEG;IACH,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAEjF;;OAEG;IACH,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,CAAC;IAE/D;;OAEG;IACH,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,KAAK,IAAI,CAAC;IAE9D;;OAEG;IACH,eAAe,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,MAAM,EACN,QAAQ,EACR,UAAU,GACX,EAAE,iBAAiB,GAAG,iBAAiB,CAkGvC"}

package/dist/versioning/useVersions.js

@@ -0,0 +1,110 @@
+/**
+ * useVersions Hook
+ *
+ * Provides document version history and comparison functionality.
+ */
+import { useState, useCallback, useEffect } from 'react';
+import { diffPuckData } from './utils/diff.js';
+/**
+ * Hook for managing document versions and comparisons.
+ *
+ * @param params - Configuration for version management
+ * @returns Version state and operations
+ *
+ * @example
+ * ```tsx
+ * const { versions, compareVersions, latestVersion } = useVersions({
+ *   client,
+ *   siteId,
+ *   branchId,
+ *   documentId,
+ * });
+ *
+ * // Compare versions
+ * const diffs = await compareVersions(oldVersionId, newVersionId);
+ * ```
+ */
+export function useVersions({ client, siteId, branchId, documentId, }) {
+    const [versions, setVersions] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [selectedVersion, setSelectedVersion] = useState(null);
+    const [comparisonDiffs, setComparisonDiffs] = useState(null);
+    const [isComparing, setIsComparing] = useState(false);
+    // Fetch versions
+    const refresh = useCallback(async () => {
+        if (!documentId) {
+            setVersions([]);
+            return;
+        }
+        setLoading(true);
+        setError(null);
+        try {
+            const versionList = await client.versions.list(siteId, branchId, documentId);
+            // Sort by version number descending (newest first)
+            versionList.sort((a, b) => b.versionNumber - a.versionNumber);
+            setVersions(versionList);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, siteId, branchId, documentId]);
+    // Initial fetch when documentId changes
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    // Get latest version
+    const latestVersion = versions[0] ?? null;
+    // Get version by ID
+    const getVersion = useCallback((versionId) => {
+        return versions.find((v) => v.id === versionId);
+    }, [versions]);
+    // Compare two versions
+    const compareVersions = useCallback(async (beforeId, afterId) => {
+        setIsComparing(true);
+        setError(null);
+        try {
+            const beforeVersion = versions.find((v) => v.id === beforeId);
+            const afterVersion = versions.find((v) => v.id === afterId);
+            if (!beforeVersion || !afterVersion) {
+                throw new Error('Version not found');
+            }
+            const beforeData = beforeVersion.snapshot;
+            const afterData = afterVersion.snapshot;
+            const diffs = diffPuckData(beforeData, afterData);
+            setComparisonDiffs(diffs);
+            return diffs;
+        }
+        catch (err) {
+            const compareError = err instanceof Error ? err : new Error(String(err));
+            setError(compareError);
+            throw compareError;
+        }
+        finally {
+            setIsComparing(false);
+        }
+    }, [versions]);
+    // Clear comparison when selected version changes
+    useEffect(() => {
+        if (!selectedVersion) {
+            setComparisonDiffs(null);
+        }
+    }, [selectedVersion]);
+    return {
+        versions,
+        loading,
+        error,
+        refresh,
+        latestVersion,
+        compareVersions,
+        getVersion,
+        selectedVersion,
+        setSelectedVersion,
+        comparisonDiffs,
+        isComparing,
+    };
+}
+//# sourceMappingURL=useVersions.js.map

package/dist/versioning/useVersions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVersions.js","sourceRoot":"","sources":["../../src/versioning/useVersions.ts"],"names":[],"mappings":"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"}

package/dist/versioning/utils/branchDiff.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Branch Diff Utility
+ *
+ * Bridges merge preview API data with existing Puck diff utilities
+ * for branch-level comparison. Provides document-level and aggregate
+ * merge comparison capabilities.
+ */
+import type { PuckData } from '@pantheon-systems/css-client';
+import type { ComponentDiffWithPosition } from '../../core/types.js';
+/**
+ * Comparison result for a single document between source and target branches.
+ */
+export interface BranchDocumentComparison {
+    /** Document identifier. */
+    documentId: string;
+    /** Document path (e.g., '/pages/home'). */
+    documentPath: string;
+    /** Whether the snapshots were detected as PuckData. */
+    isPuckData: boolean;
+    /** Component-level diffs with position information. */
+    diffs: ComponentDiffWithPosition[];
+    /** Aggregated change counts for this document. */
+    counts: {
+        added: number;
+        removed: number;
+        modified: number;
+        unchanged: number;
+    };
+}
+/**
+ * Aggregated comparison result across all documents in a branch merge.
+ */
+export interface BranchMergeComparison {
+    /** Per-document comparison results. */
+    documents: BranchDocumentComparison[];
+    /** Aggregated change counts across all documents. */
+    totalCounts: {
+        added: number;
+        removed: number;
+        modified: number;
+        unchanged: number;
+    };
+    /** Total number of documents compared. */
+    documentCount: number;
+    /** Number of documents that have at least one non-unchanged diff. */
+    changedDocumentCount: number;
+}
+/**
+ * Input summary for a document to be diffed between branches.
+ */
+export interface DocumentDiffSummary {
+    /** Document identifier. */
+    documentId: string;
+    /** Document path (e.g., '/pages/home'). */
+    documentPath: string;
+    /** Snapshot from the source branch (may be PuckData or regular JSON). */
+    sourceSnapshot: unknown;
+    /** Snapshot from the target branch (may be PuckData or regular JSON). */
+    targetSnapshot: unknown;
+}
+/** Empty PuckData used as a stand-in for null snapshots. */
+export declare const EMPTY_PUCK_DATA: PuckData;
+/**
+ * Detects whether the given value is a PuckData structure.
+ *
+ * A value is considered PuckData when it is a non-null object with a
+ * `content` property that is an array and a `root` property that is
+ * an object.
+ *
+ * @param data - The value to inspect.
+ * @returns `true` if the value matches the PuckData shape.
+ *
+ * @example
+ * ```typescript
+ * if (isPuckData(snapshot)) {
+ *   const diffs = diffPuckDataWithPositions(before, snapshot);
+ * }
+ * ```
+ */
+export declare function isPuckData(data: unknown): boolean;
+/**
+ * Creates a comparison for a single document between source and target
+ * branch snapshots.
+ *
+ * Behaviour varies depending on the snapshot values:
+ *
+ * - **Both PuckData** -- uses `diffPuckDataWithPositions` to compute
+ *   component-level diffs (target as baseline, source as changed state).
+ * - **Source has data, target is null** -- produces synthetic diffs
+ *   where all source components are marked as `added` (new document).
+ * - **Target has data, source is null** -- produces synthetic diffs
+ *   where all target components are marked as `removed` (deleted document).
+ * - **Neither is PuckData / both null** -- returns empty diffs with
+ *   `isPuckData: false`.
+ *
+ * @param documentId   - Unique identifier of the document.
+ * @param documentPath - Path of the document (e.g., '/pages/home').
+ * @param sourceSnapshot - Snapshot from the source branch (or null).
+ * @param targetSnapshot - Snapshot from the target branch (or null).
+ * @returns A {@link BranchDocumentComparison} describing the differences.
+ *
+ * @example
+ * ```typescript
+ * const comparison = createBranchDocumentComparison(
+ *   'doc-1',
+ *   '/pages/home',
+ *   sourceBranchSnapshot,
+ *   targetBranchSnapshot
+ * );
+ * console.log(comparison.counts); // { added: 0, removed: 1, modified: 2, unchanged: 5 }
+ * ```
+ */
+export declare function createBranchDocumentComparison(documentId: string, documentPath: string, sourceSnapshot: unknown, targetSnapshot: unknown): BranchDocumentComparison;
+/**
+ * Creates an aggregated comparison across multiple documents for a
+ * branch merge operation.
+ *
+ * Calls {@link createBranchDocumentComparison} for each document and
+ * aggregates the resulting counts. A document is considered "changed"
+ * when it contains at least one diff whose type is **not** `unchanged`.
+ *
+ * @param documents - Array of document diff summaries to compare.
+ * @returns A {@link BranchMergeComparison} with per-document results
+ *          and aggregate statistics.
+ *
+ * @example
+ * ```typescript
+ * const merge = createBranchMergeComparison([
+ *   { documentId: 'doc-1', documentPath: '/home', sourceSnapshot, targetSnapshot },
+ *   { documentId: 'doc-2', documentPath: '/about', sourceSnapshot: null, targetSnapshot },
+ * ]);
+ * console.log(merge.changedDocumentCount); // number of docs with changes
+ * ```
+ */
+export declare function createBranchMergeComparison(documents: DocumentDiffSummary[]): BranchMergeComparison;
+//# sourceMappingURL=branchDiff.d.ts.map

package/dist/versioning/utils/branchDiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchDiff.d.ts","sourceRoot":"","sources":["../../../src/versioning/utils/branchDiff.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAOrE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IAErB,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAC;IAEpB,uDAAuD;IACvD,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAEnC,kDAAkD;IAClD,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,SAAS,EAAE,wBAAwB,EAAE,CAAC;IAEtC,qDAAqD;IACrD,WAAW,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAEF,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IAEtB,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IAErB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;IAExB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;CACzB;AAMD,4DAA4D;AAC5D,eAAO,MAAM,eAAe,EAAE,QAA+C,CAAC;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAQjD;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,OAAO,EACvB,cAAc,EAAE,OAAO,GACtB,wBAAwB,CAmC1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,mBAAmB,EAAE,GAC/B,qBAAqB,CAoCvB"}

package/dist/versioning/utils/branchDiff.js

@@ -0,0 +1,172 @@
+/**
+ * Branch Diff Utility
+ *
+ * Bridges merge preview API data with existing Puck diff utilities
+ * for branch-level comparison. Provides document-level and aggregate
+ * merge comparison capabilities.
+ */
+import { diffPuckDataWithPositions } from './diff.js';
+// =============================================================================
+// Utilities
+// =============================================================================
+/** Empty PuckData used as a stand-in for null snapshots. */
+export const EMPTY_PUCK_DATA = { content: [], root: { props: {} } };
+/**
+ * Detects whether the given value is a PuckData structure.
+ *
+ * A value is considered PuckData when it is a non-null object with a
+ * `content` property that is an array and a `root` property that is
+ * an object.
+ *
+ * @param data - The value to inspect.
+ * @returns `true` if the value matches the PuckData shape.
+ *
+ * @example
+ * ```typescript
+ * if (isPuckData(snapshot)) {
+ *   const diffs = diffPuckDataWithPositions(before, snapshot);
+ * }
+ * ```
+ */
+export function isPuckData(data) {
+    if (data === null || data === undefined || typeof data !== 'object') {
+        return false;
+    }
+    const obj = data;
+    return Array.isArray(obj.content) && obj.root !== null && typeof obj.root === 'object';
+}
+/**
+ * Counts diffs by type, producing an object with `added`, `removed`,
+ * `modified`, and `unchanged` tallies.
+ */
+function countDiffs(diffs) {
+    const counts = { added: 0, removed: 0, modified: 0, unchanged: 0 };
+    for (const diff of diffs) {
+        if (diff.type === 'added') {
+            counts.added++;
+        }
+        else if (diff.type === 'removed') {
+            counts.removed++;
+        }
+        else if (diff.type === 'modified') {
+            counts.modified++;
+        }
+        else if (diff.type === 'unchanged') {
+            counts.unchanged++;
+        }
+        // 'reordered' diffs are intentionally not counted in the four standard
+        // buckets; they are tracked via the reordered flag on modified diffs.
+    }
+    return counts;
+}
+/**
+ * Creates a comparison for a single document between source and target
+ * branch snapshots.
+ *
+ * Behaviour varies depending on the snapshot values:
+ *
+ * - **Both PuckData** -- uses `diffPuckDataWithPositions` to compute
+ *   component-level diffs (target as baseline, source as changed state).
+ * - **Source has data, target is null** -- produces synthetic diffs
+ *   where all source components are marked as `added` (new document).
+ * - **Target has data, source is null** -- produces synthetic diffs
+ *   where all target components are marked as `removed` (deleted document).
+ * - **Neither is PuckData / both null** -- returns empty diffs with
+ *   `isPuckData: false`.
+ *
+ * @param documentId   - Unique identifier of the document.
+ * @param documentPath - Path of the document (e.g., '/pages/home').
+ * @param sourceSnapshot - Snapshot from the source branch (or null).
+ * @param targetSnapshot - Snapshot from the target branch (or null).
+ * @returns A {@link BranchDocumentComparison} describing the differences.
+ *
+ * @example
+ * ```typescript
+ * const comparison = createBranchDocumentComparison(
+ *   'doc-1',
+ *   '/pages/home',
+ *   sourceBranchSnapshot,
+ *   targetBranchSnapshot
+ * );
+ * console.log(comparison.counts); // { added: 0, removed: 1, modified: 2, unchanged: 5 }
+ * ```
+ */
+export function createBranchDocumentComparison(documentId, documentPath, sourceSnapshot, targetSnapshot) {
+    const sourceIsPuck = isPuckData(sourceSnapshot);
+    const targetIsPuck = isPuckData(targetSnapshot);
+    // Neither side is PuckData (or both are null) -- nothing we can diff.
+    if (!sourceIsPuck && !targetIsPuck) {
+        return {
+            documentId,
+            documentPath,
+            isPuckData: false,
+            diffs: [],
+            counts: { added: 0, removed: 0, modified: 0, unchanged: 0 },
+        };
+    }
+    // The diff compares before (old) → after (new).
+    // Target is the baseline (main), source is the changed state (feature branch).
+    // So before = target, after = source.
+    const before = targetIsPuck
+        ? targetSnapshot
+        : EMPTY_PUCK_DATA;
+    const after = sourceIsPuck
+        ? sourceSnapshot
+        : EMPTY_PUCK_DATA;
+    const diffs = diffPuckDataWithPositions(before, after);
+    const counts = countDiffs(diffs);
+    return {
+        documentId,
+        documentPath,
+        isPuckData: true,
+        diffs,
+        counts,
+    };
+}
+/**
+ * Creates an aggregated comparison across multiple documents for a
+ * branch merge operation.
+ *
+ * Calls {@link createBranchDocumentComparison} for each document and
+ * aggregates the resulting counts. A document is considered "changed"
+ * when it contains at least one diff whose type is **not** `unchanged`.
+ *
+ * @param documents - Array of document diff summaries to compare.
+ * @returns A {@link BranchMergeComparison} with per-document results
+ *          and aggregate statistics.
+ *
+ * @example
+ * ```typescript
+ * const merge = createBranchMergeComparison([
+ *   { documentId: 'doc-1', documentPath: '/home', sourceSnapshot, targetSnapshot },
+ *   { documentId: 'doc-2', documentPath: '/about', sourceSnapshot: null, targetSnapshot },
+ * ]);
+ * console.log(merge.changedDocumentCount); // number of docs with changes
+ * ```
+ */
+export function createBranchMergeComparison(documents) {
+    const totalCounts = { added: 0, removed: 0, modified: 0, unchanged: 0 };
+    const comparisons = [];
+    let changedDocumentCount = 0;
+    for (const doc of documents) {
+        const comparison = createBranchDocumentComparison(doc.documentId, doc.documentPath, doc.sourceSnapshot, doc.targetSnapshot);
+        comparisons.push(comparison);
+        // Aggregate counts.
+        totalCounts.added += comparison.counts.added;
+        totalCounts.removed += comparison.counts.removed;
+        totalCounts.modified += comparison.counts.modified;
+        totalCounts.unchanged += comparison.counts.unchanged;
+        // A document is "changed" if it has any diff that is not 'unchanged'.
+        const hasChanges = comparison.diffs.some((diff) => diff.type !== 'unchanged');
+        if (hasChanges) {
+            changedDocumentCount++;
+        }
+    }
+    return {
+        documents: comparisons,
+        totalCounts,
+        documentCount: documents.length,
+        changedDocumentCount,
+    };
+}
+//# sourceMappingURL=branchDiff.js.map

package/dist/versioning/utils/branchDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchDiff.js","sourceRoot":"","sources":["../../../src/versioning/utils/branchDiff.ts"],"names":[],"mappings":"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"}

package/dist/versioning/utils/diff.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Diff Utility
+ *
+ * Functions for comparing Puck data structures to identify changes.
+ */
+import type { PuckData } from '@pantheon-systems/css-client';
+import type { ComponentDiff, ComponentDiffWithPosition, PropDiff } from '../../core/types.js';
+/**
+ * Compares two Puck data structures and returns a list of component differences.
+ *
+ * @param before - The original Puck data
+ * @param after - The modified Puck data
+ * @returns Array of component differences
+ *
+ * @example
+ * ```typescript
+ * const diffs = diffPuckData(oldData, newData);
+ * for (const diff of diffs) {
+ *   if (diff.type === 'added') {
+ *     console.log(`Added: ${diff.componentType}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function diffPuckData(before: PuckData, after: PuckData): ComponentDiff[];
+/**
+ * Filters diffs to only include changes (excludes unchanged components).
+ */
+export declare function getChangedComponents(diffs: ComponentDiff[]): ComponentDiff[];
+/**
+ * Counts the number of changes by type.
+ */
+export declare function countChanges(diffs: ComponentDiff[]): {
+    added: number;
+    removed: number;
+    modified: number;
+    unchanged: number;
+};
+/**
+ * Checks if the root props have changed between two Puck data objects.
+ */
+export declare function hasRootChanged(before: PuckData, after: PuckData): boolean;
+/**
+ * Compares two Puck data structures with position tracking and reorder detection.
+ *
+ * @param before - The original Puck data
+ * @param after - The modified Puck data
+ * @returns Array of component differences with position info
+ */
+export declare function diffPuckDataWithPositions(before: PuckData, after: PuckData): ComponentDiffWithPosition[];
+/**
+ * Compares two prop objects and returns detailed prop-level differences.
+ *
+ * @param before - Props before change
+ * @param after - Props after change
+ * @returns Array of prop differences
+ */
+export declare function diffProps(before: Record<string, unknown>, after: Record<string, unknown>): PropDiff[];
+/**
+ * Filters diffs to only include reordered components.
+ */
+export declare function getReorderedComponents(diffs: ComponentDiffWithPosition[]): ComponentDiffWithPosition[];
+//# sourceMappingURL=diff.d.ts.map

package/dist/versioning/utils/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/versioning/utils/diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAqB,MAAM,8BAA8B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,yBAAyB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AA8D9F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,aAAa,EAAE,CAwD/E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAE5E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAQA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEzE;AAgCD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,QAAQ,GACd,yBAAyB,EAAE,CAkF7B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,QAAQ,EAAE,CAyCZ;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,yBAAyB,EAAE,GACjC,yBAAyB,EAAE,CAI7B"}