@pantheon-systems/puck-css 0.4.2 → 0.4.4

package/dist/editor/P1PuckProvider.js

@@ -15,6 +15,8 @@ import { useDocuments } from './useDocuments.js';
 import { resolveFeatureConfig } from '../core/featureConfig.js';
 import { resolveActivePlugins, composeProviders } from './composePlugins.js';
 import { DEFAULT_CSS_FEATURE_PLUGINS } from './defaultPlugins.js';
+import { createPuckPermissions } from '../features/content-type-templates/permissions/createPuckPermissions.js';
+import { useTemplateList } from '../features/content-type-templates/hooks/useTemplateList.js';
 /**
  * Provider component for P1 Puck integration.
  *
@@ -63,7 +65,10 @@ agentModeEnabled = false, agentId, agentTrigger: _agentTrigger,
 // Phase 9: Callbacks
 onPresenceChange, onAgentConflict: _onAgentConflict, 
 // Plugin system props (B.4)
-featurePlugins, featureConfig, children, }) {
+featurePlugins, featureConfig, 
+// Content Type Templates (PROPOSAL-010)
+// Consumers should resolve the role via useResolveContentRole and pass it here.
+userRole = 'editor', children, }) {
     // Access notification context
     const notificationContext = useNotifications();
     // Persist selected branch in sessionStorage so it survives provider remounts
@@ -120,6 +125,8 @@ featurePlugins, featureConfig, children, }) {
     // Document state
     const [currentDocument, setCurrentDocument] = useState(null);
     const [currentData, setCurrentData] = useState(null);
+    // Template state (PROPOSAL-010)
+    const [currentTemplate, setCurrentTemplate] = useState(null);
     // Save state
     const [saveStatus, setSaveStatus] = useState('idle');
     const [lastSaved, setLastSaved] = useState(null);
@@ -129,9 +136,10 @@ featurePlugins, featureConfig, children, }) {
     const currentDocumentRef = useRef(null);
     const initializedRef = useRef(false);
     // Track the latest Puck action metadata for inclusion in sync payloads.
-    // Set by handleAction (Puck's onAction callback), consumed by saveData
-    // when sending changes via realtime, then cleared.
-    const lastActionRef = useRef(null);
+    // Buffered actions captured by handleAction (Puck's onAction callback)
+    // Array accumulates all structural actions during an edit session.
+    // Forwarded to backend on save for version history, then cleared.
+    const pendingActionsRef = useRef([]);
     // Tracks the document path that the current data in state belongs to.
     // Set alongside every setCurrentData call to record the data's origin.
     // Checked before every write (realtime or REST) to prevent cross-document
@@ -208,6 +216,9 @@ featurePlugins, featureConfig, children, }) {
         actorType: 'user',
         enabled: enableRealtime && !!wsBaseUrl,
         initialData: currentData,
+        onServerReload: () => {
+            notificationContext.addInfo('Document is being refreshed by the server. Reconnecting...');
+        },
         // WebSocket presence callbacks - receive instant presence updates
         onPresenceUpdate: (actors) => {
             // Mark WebSocket presence as active (first update received)
@@ -222,13 +233,7 @@ featurePlugins, featureConfig, children, }) {
             setWsPresenceActors((prev) => prev.map((a) => (a.actorId === actorId ? { ...a, focusRegions } : a)));
         },
         onRemoteUpdate: (data) => {
-            const componentCount = data.content?.length ?? 0;
-            const zoneCount = data.zones ? Object.keys(data.zones).length : 0;
-            console.log('[P1PuckProvider] onRemoteUpdate received:', `components=${componentCount}, zones=${zoneCount},`, `pendingRemoteUpdates=${pendingRemoteUpdatesRef.current},`, `viewingVersion=${viewingVersionRef.current !== null}`);
-            // Don't apply remote updates while viewing a historical version
-            // The user is viewing read-only historical data and shouldn't see live changes
             if (viewingVersionRef.current !== null) {
-                console.log('[P1PuckProvider] onRemoteUpdate SKIPPED: viewing historical version');
                 return;
             }
             // Reject empty data that would overwrite real editor content.
@@ -239,7 +244,6 @@ featurePlugins, featureConfig, children, }) {
             if (data.content.length === 0 &&
                 (!rootProps || Object.keys(rootProps).length === 0) &&
                 !data.zones) {
-                console.log('[P1PuckProvider] onRemoteUpdate SKIPPED: empty data rejected');
                 return;
             }
             // Store the latest data - will be used when debounce fires
@@ -260,8 +264,6 @@ featurePlugins, featureConfig, children, }) {
                 }
                 const dataToSync = pendingRemoteDataRef.current;
                 if (dataToSync) {
-                    const syncComponentCount = dataToSync.content?.length ?? 0;
-                    console.log('[P1PuckProvider] onRemoteUpdate APPLYING:', `components=${syncComponentCount},`, `pendingRemoteUpdates will be=${pendingRemoteUpdatesRef.current + 1}`);
                     // Increment counter to skip the onChange echo(es) that will fire
                     // when Puck processes the setCurrentData call below.
                     // The content-based guards in puckDataToYMap and RealtimeClient
@@ -342,7 +344,6 @@ featurePlugins, featureConfig, children, }) {
             const dataOriginPath = currentDataDocumentPathRef.current;
             if (dataOriginPath !== currentPath)
                 return;
-            console.log('[P1PuckProvider] PuckDataCapture catch-up: sending missed data,', `components=${currentData.content?.length ?? 0}`);
             realtimeRef.current.applyLocalChange(currentData);
             lastSentDataRef.current = dataJson;
         }, 800);
@@ -369,17 +370,31 @@ featurePlugins, featureConfig, children, }) {
     const userClient = useMemo(() => client.withPrincipal({ id: userId, type: 'user' }), [client, userId]);
     // Document list for current branch
     const { documents: branchDocuments, loading: documentsLoading, create: createDocumentRaw, remove: removeDocumentRaw, } = useDocuments({ client: userClient, siteId, branchId });
+    // Template list for current branch
+    const { templates: branchTemplates, loading: templatesLoading, error: templatesError, refresh: refreshTemplates, } = useTemplateList(userClient, siteId, branchId);
     // Stable document create/delete callbacks
     const branchIdRef = useRef(branchId);
     branchIdRef.current = branchId;
     const createDocumentRawRef = useRef(createDocumentRaw);
     createDocumentRawRef.current = createDocumentRaw;
-    const stableCreateDocument = useCallback(async (path) => {
+    const stableCreateDocument = useCallback(async (path, template) => {
         if (!branchIdRef.current) {
             throw new Error('Cannot create document: no branch selected');
         }
-        await createDocumentRawRef.current(path);
-    }, []);
+        if (template) {
+            // Fetch the full template — the list endpoint may omit the components array
+            const fullTemplate = await userClient.templates.get(siteId, branchIdRef.current, template.id);
+            const { scaffoldFromTemplate } = await import('../features/content-type-templates/editor/useTemplateScaffold.js');
+            const initialData = scaffoldFromTemplate(fullTemplate);
+            await createDocumentRawRef.current(path, initialData, {
+                templateId: fullTemplate.id,
+                templateVersion: fullTemplate.version,
+            });
+        }
+        else {
+            await createDocumentRawRef.current(path);
+        }
+    }, [userClient, siteId]);
     const removeDocumentRawRef = useRef(removeDocumentRaw);
     removeDocumentRawRef.current = removeDocumentRaw;
     const stableDeleteDocument = useCallback(async (documentId, _path) => {
@@ -394,33 +409,29 @@ featurePlugins, featureConfig, children, }) {
             setBranchesLoading(true);
             const branchList = await userClient.branches.list(siteId);
             setBranches(branchList);
-            // Update current branch from current branchId state
-            setBranchId((currentBranchId) => {
-                let effectiveBranchId = currentBranchId;
-                // If no branchId set, try persisted branch, then default to main
-                if (!effectiveBranchId) {
-                    const persisted = getPersistedBranchId();
-                    if (persisted && branchList.some((b) => b.id === persisted)) {
-                        effectiveBranchId = persisted;
-                    }
+            let effectiveBranchId = branchIdRef.current;
+            // If no branchId set, try persisted branch, then default to main
+            if (!effectiveBranchId) {
+                const persisted = getPersistedBranchId();
+                if (persisted && branchList.some((b) => b.id === persisted)) {
+                    effectiveBranchId = persisted;
                 }
-                // Validate that the branch exists in the list; fall back to main if not
-                if (effectiveBranchId && !branchList.some((b) => b.id === effectiveBranchId)) {
-                    const mainBranch = branchList.find((b) => b.isMain);
-                    effectiveBranchId = mainBranch?.id ?? effectiveBranchId;
-                }
-                // Default to main if still empty
-                if (!effectiveBranchId) {
-                    const mainBranch = branchList.find((b) => b.isMain);
-                    if (mainBranch) {
-                        effectiveBranchId = mainBranch.id;
-                    }
+            }
+            // Validate that the branch exists in the list; fall back to main if not
+            if (effectiveBranchId && !branchList.some((b) => b.id === effectiveBranchId)) {
+                const mainBranch = branchList.find((b) => b.isMain);
+                effectiveBranchId = mainBranch?.id ?? effectiveBranchId;
+            }
+            // Default to main if still empty
+            if (!effectiveBranchId) {
+                const mainBranch = branchList.find((b) => b.isMain);
+                if (mainBranch) {
+                    effectiveBranchId = mainBranch.id;
                 }
-                persistBranchId(effectiveBranchId);
-                const current = branchList.find((b) => b.id === effectiveBranchId);
-                setCurrentBranch(current ?? null);
-                return effectiveBranchId;
-            });
+            }
+            persistBranchId(effectiveBranchId);
+            setBranchId(effectiveBranchId);
+            setCurrentBranch(branchList.find((b) => b.id === effectiveBranchId) ?? null);
         }
         catch (error) {
             console.error('Failed to load branches:', error);
@@ -468,11 +479,16 @@ featurePlugins, featureConfig, children, }) {
         setSaveError(null);
         try {
             await withRetry(async () => {
+                const actionsToSend = pendingActionsRef.current.length > 0
+                    ? [...pendingActionsRef.current]
+                    : undefined;
                 await userClient.versions.create(siteId, {
                     documentId: doc.id,
                     branchId,
                     snapshot: dataToSave,
+                    puckActions: actionsToSend,
                 });
+                pendingActionsRef.current = [];
             }, { maxAttempts: maxRetries });
             // Note: We intentionally do NOT call setCurrentData(dataToSave) here.
             // The data is already in Puck's internal state (it came from Puck's onChange).
@@ -517,30 +533,34 @@ featurePlugins, featureConfig, children, }) {
     // This captures the action type and relevant metadata fields so they
     // can be included in the sync payload for backend version storage.
     const handleAction = useCallback((action) => {
-        const actionMetadata = {};
+        const puckAction = {
+            type: action.type || 'unknown',
+        };
         if (action.componentType)
-            actionMetadata.componentType = action.componentType;
+            puckAction.componentType = action.componentType;
         if (action.componentId)
-            actionMetadata.componentId = action.componentId;
+            puckAction.componentId = action.componentId;
         if (action.zone)
-            actionMetadata.zone = action.zone;
+            puckAction.zone = action.zone;
         if (action.sourceIndex !== undefined)
-            actionMetadata.sourceIndex = action.sourceIndex;
+            puckAction.sourceIndex = action.sourceIndex;
         if (action.destinationIndex !== undefined)
-            actionMetadata.destinationIndex = action.destinationIndex;
-        lastActionRef.current = {
-            actionType: action.type || 'unknown',
-            actionMetadata,
-        };
+            puckAction.destinationIndex = action.destinationIndex;
+        if (action.sourceZone)
+            puckAction.sourceZone = action.sourceZone;
+        if (action.destinationZone)
+            puckAction.destinationZone = action.destinationZone;
+        const buffer = pendingActionsRef.current;
+        buffer.push(puckAction);
+        if (buffer.length > 1000) {
+            pendingActionsRef.current = buffer.slice(-500);
+        }
     }, []);
     // Public save function (triggers debounce)
     // Also resumes auto-save if paused, per user requirement
     // Sends changes via WebSocket when realtime is enabled (but not for remote updates)
     const saveData = useCallback((data) => {
-        const componentCount = data.content?.length ?? 0;
-        // Suppress the onChange echo from PuckDataSynchronizer after loadDocument.
         if (suppressNextSaveRef.current) {
-            console.log(`[P1PuckProvider] saveData SKIPPED: suppressNextSave (components=${componentCount})`);
             suppressNextSaveRef.current = false;
             return;
         }
@@ -551,14 +571,10 @@ featurePlugins, featureConfig, children, }) {
         // getHasUnsavedChanges() will incorrectly report unsaved changes.
         if (enableRealtime && realtime.connected) {
             if (pendingRemoteUpdatesRef.current > 0) {
-                // Counter indicates this onChange is from a remote update or data load
-                console.log(`[P1PuckProvider] saveData SKIPPED: pendingRemoteUpdates=${pendingRemoteUpdatesRef.current} (components=${componentCount})`);
                 pendingRemoteUpdatesRef.current -= 1;
                 return;
             }
             else if (viewingVersionRef.current !== null) {
-                // User is viewing historical version - don't broadcast or save
-                console.log(`[P1PuckProvider] saveData SKIPPED: viewing historical version (components=${componentCount})`);
                 return;
             }
             else {
@@ -569,24 +585,29 @@ featurePlugins, featureConfig, children, }) {
                 // into state after currentDocument has been updated to X.
                 const dataOriginPath = currentDataDocumentPathRef.current;
                 if (dataOriginPath !== currentPath) {
-                    console.warn('[P1PuckProvider] saveData SKIPPED: data origin mismatch.', 'dataOrigin:', dataOriginPath, 'currentDoc:', currentPath, `components=${componentCount}`);
+                    console.warn('[P1PuckProvider] saveData SKIPPED: data origin mismatch.', 'dataOrigin:', dataOriginPath, 'currentDoc:', currentPath);
                     return;
                 }
                 // Connection identity guard: verify the realtime connection is
                 // bound to the same document we're currently editing.
                 const connectedPath = realtime.connectedDocumentPath;
                 if (currentPath !== connectedPath) {
-                    console.warn('[P1PuckProvider] saveData SKIPPED: connection identity mismatch.', 'currentDoc:', currentPath, 'connectedDoc:', connectedPath, `components=${componentCount}`);
+                    console.warn('[P1PuckProvider] saveData SKIPPED: connection identity mismatch.', 'currentDoc:', currentPath, 'connectedDoc:', connectedPath);
                     return;
                 }
                 // Local user edit — send via WebSocket (DO handles persistence)
                 // Echo prevention is handled at lower layers:
                 // - puckDataToYMap no-ops when Y.Doc already has identical data
                 // - RealtimeClient.lastSentSnapshot drops sends matching last sent/received
-                console.log(`[P1PuckProvider] saveData SENDING via realtime: components=${componentCount}, path=${currentPath}`);
-                realtime.applyLocalChange(data);
+                const actions = pendingActionsRef.current;
+                if (actions.length > 0) {
+                    realtime.applyLocalChange(data, actions);
+                }
+                else {
+                    realtime.applyLocalChange(data);
+                }
                 trackSentData(data);
-                lastActionRef.current = null;
+                pendingActionsRef.current = [];
                 // Data sent via WebSocket — DO handles persistence.
                 // Update save status directly (skip debouncedSave/performSave chain).
                 setSaveStatus('saved');
@@ -594,8 +615,6 @@ featurePlugins, featureConfig, children, }) {
                 return;
             }
         }
-        // Non-realtime path: mark data as pending and trigger debounced REST save
-        console.log(`[P1PuckProvider] saveData via REST (debounced): components=${componentCount}, realtimeEnabled=${enableRealtime}, connected=${realtime.connected}`);
         pendingDataRef.current = data;
         if (debouncedSave.isPaused()) {
             debouncedSave.resume();
@@ -658,6 +677,23 @@ featurePlugins, featureConfig, children, }) {
             currentDataDocumentPathRef.current = null;
             setCurrentData(null);
             setCurrentDocument(doc);
+            // Fetch template if document is bound to one (PROPOSAL-010)
+            if (doc.templateId) {
+                try {
+                    if (!userClient.templates) {
+                        throw new Error('Templates endpoint not available on client');
+                    }
+                    const template = await userClient.templates.get(siteId, branchId, doc.templateId);
+                    setCurrentTemplate(template);
+                }
+                catch (templateError) {
+                    console.warn('[P1PuckProvider] Failed to fetch template:', templateError);
+                    setCurrentTemplate(null);
+                }
+            }
+            else {
+                setCurrentTemplate(null);
+            }
             // Get latest version
             const version = await userClient.versions.getLatest(siteId, branchId, doc.id);
             const puckData = version.snapshot;
@@ -805,6 +841,56 @@ featurePlugins, featureConfig, children, }) {
     // Computed property for whether viewing historical version
     const isViewingHistoricalVersion = viewingVersion !== null;
     // =========================================================================
+    // Content Type Templates: Permission Resolution (PROPOSAL-010)
+    // =========================================================================
+    // Resolve template: either from document binding or registry path
+    const resolvedTemplate = useMemo(() => {
+        if (currentTemplate)
+            return currentTemplate;
+        const path = currentDocument?.path;
+        if (!path)
+            return null;
+        const match = path.match(/^_registry\/templates\/(.+)$/);
+        if (!match)
+            return null;
+        return branchTemplates.find((t) => t.name === match[1]) ?? null;
+    }, [currentTemplate, currentDocument?.path, branchTemplates]);
+    // Create Puck permissions resolver based on current template and user role
+    const resolvePermissions = useMemo(() => createPuckPermissions(resolvedTemplate, userRole, isViewingHistoricalVersion), [resolvedTemplate, userRole, isViewingHistoricalVersion]);
+    // Show notification when template list fails to load
+    useEffect(() => {
+        if (templatesError && showErrorNotifications && notificationContext?.addError) {
+            notificationContext.addError(`Failed to load templates: ${templatesError.message}`, () => void refreshTemplates());
+        }
+    }, [templatesError]);
+    // =========================================================================
+    // Content Type Templates: Re-fetch template on tab focus (CUJ-15a)
+    // =========================================================================
+    useEffect(() => {
+        if (typeof document === 'undefined')
+            return;
+        const handler = async () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            const doc = currentDocumentRef.current;
+            if (!doc?.templateId || !userClient.templates)
+                return;
+            try {
+                const freshTemplate = await userClient.templates.get(siteId, branchId, doc.templateId);
+                setCurrentTemplate((prev) => {
+                    if (prev && prev.version === freshTemplate.version)
+                        return prev;
+                    return freshTemplate;
+                });
+            }
+            catch {
+                // Silently ignore — stale template is better than no template
+            }
+        };
+        document.addEventListener('visibilitychange', handler);
+        return () => document.removeEventListener('visibilitychange', handler);
+    }, [siteId, userClient]);
+    // =========================================================================
     // Phase 9: Presence & Agent Mode State
     // =========================================================================
     // Presence state (when presenceEnabled)
@@ -1254,6 +1340,10 @@ featurePlugins, featureConfig, children, }) {
     const switchBranchRef = useRef(switchBranch);
     switchBranchRef.current = switchBranch;
     const stableSwitchBranch = useCallback((newBranchId) => switchBranchRef.current(newBranchId), []);
+    // Get pending actions for forwarding to backend
+    const getPendingActions = useCallback(() => {
+        return [...pendingActionsRef.current]; // Return copy to prevent external mutation
+    }, []);
     const loadDocumentRef = useRef(loadDocument);
     loadDocumentRef.current = loadDocument;
     const stableLoadDocument = useCallback((path) => loadDocumentRef.current(path), []);
@@ -1388,6 +1478,8 @@ featurePlugins, featureConfig, children, }) {
         sendFocusRegions: realtime.sendFocusRegions,
         // Puck action metadata capture - pass as onAction to <Puck>
         handleAction,
+        // Get pending actions for backend forwarding (PROPOSAL-010)
+        getPendingActions,
         // Phase 9: Presence & Agent values
         // Use getter to avoid context recreation on every focus-region update.
         // Expose humanPresenceCount/hasActiveHumans/hasActiveAgents directly so every
@@ -1406,6 +1498,14 @@ featurePlugins, featureConfig, children, }) {
         // Internal: realtime data capture for catch-up (sends missed keystrokes)
         _realtimeDataCaptureRef: enableRealtime ? realtimeDataCaptureRef : null,
         _onRealtimeDataCapture: enableRealtime ? handleRealtimeDataCapture : null,
+        // Content Type Templates (PROPOSAL-010)
+        userRole,
+        templates: branchTemplates,
+        templatesLoading,
+        templatesError,
+        refreshTemplates,
+        currentTemplate,
+        resolvePermissions,
     }), [
         userClient,
         notificationContext,
@@ -1451,6 +1551,7 @@ featurePlugins, featureConfig, children, }) {
         remoteSyncKey,
         realtime.sendFocusRegions,
         handleAction,
+        getPendingActions,
         handleRealtimeDataCapture,
         // Phase 9 dependencies (full presenceState excluded — accessed via getter/ref,
         // but humanPresenceCount/hasActiveHumans/hasActiveAgents are direct values so every
@@ -1465,6 +1566,14 @@ featurePlugins, featureConfig, children, }) {
         dismissConflict,
         enableRealtime,
         resolvedFeatureConfig,
+        // Content Type Templates
+        userRole,
+        branchTemplates,
+        templatesLoading,
+        templatesError,
+        refreshTemplates,
+        currentTemplate,
+        resolvePermissions,
     ]);
     // Wrap with PresenceContext.Provider when presence is enabled
     const wrappedChildren = presenceContextValue ? (_jsx(PresenceContext.Provider, { value: presenceContextValue, children: children })) : (children);