simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/hooks/useAutosave.ts

@@ -0,0 +1,134 @@
+/** Dirty tracking, debounced autosave, and the unsaved-changes guard. */
+
+import type { Data } from '@puckeditor/core';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { savePage } from '../utils/api';
+import {
+  AUTOSAVE_DEBOUNCE_MS,
+  type EditorSnapshot,
+  type SaveState,
+  snapshotKey,
+} from '../utils/editorSnapshot';
+
+interface Params {
+  pageId: number | null;
+  busy: boolean;
+  data: Data;
+  snapshotPayload: EditorSnapshot;
+  initialSnapshot: EditorSnapshot;
+  writePayload: () => Record<string, unknown>;
+}
+
+export interface Autosave {
+  isDirty: boolean;
+  saveState: SaveState;
+  lastSavedAt: Date | null;
+  autosaveError: string | null;
+  markSaved: (payload: EditorSnapshot) => void;
+}
+
+export function useAutosave({
+  pageId,
+  busy,
+  data,
+  snapshotPayload,
+  initialSnapshot,
+  writePayload,
+}: Params): Autosave {
+  // Memoize the stringify — Puck ``data`` can be hundreds of KB on a
+  // populated page, and the component re-renders on every keystroke.
+  // Depending on the `snapshotPayload` object itself would defeat the memo —
+  // the caller rebuilds it every render. The fields listed are its full contents.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: listed fields are the object's full contents
+  const currentSnapshot = useMemo(
+    () => snapshotKey(snapshotPayload),
+    [
+      snapshotPayload.title,
+      snapshotPayload.slug,
+      snapshotPayload.metaDescription,
+      snapshotPayload.ogImage,
+      snapshotPayload.canonicalUrl,
+      snapshotPayload.indexInSearch,
+      snapshotPayload.jsonLdText,
+      snapshotPayload.data,
+    ],
+  );
+
+  // Intentionally mount-only. Inertia remounts the editor on a different page
+  // id, which is exactly when a fresh baseline is wanted; recomputing on prop
+  // identity would reset the dirty state mid-edit.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: mount-only baseline is deliberate
+  const baseline = useMemo(() => snapshotKey(initialSnapshot), []);
+
+  const [savedSnapshot, setSavedSnapshot] = useState<string>(baseline);
+  const [saveState, setSaveState] = useState<SaveState>('idle');
+  const [lastSavedAt, setLastSavedAt] = useState<Date | null>(null);
+  const [autosaveError, setAutosaveError] = useState<string | null>(null);
+
+  const isDirty = currentSnapshot !== savedSnapshot;
+
+  const markSaved = (payload: EditorSnapshot) => {
+    setSavedSnapshot(snapshotKey(payload));
+    setSaveState('idle');
+    setLastSavedAt(new Date());
+    setAutosaveError(null);
+  };
+
+  // Debounced autosave. If the user keeps editing while a save is in
+  // flight, ``saveState`` flips back to ``'idle'`` in the finally block,
+  // which re-runs this effect; ``isDirty`` is still true relative to the
+  // just-stored snapshot, so a fresh debounce window arms automatically
+  // — the trailing edit isn't lost.
+  //
+  // New (unsaved) pages opt out: the first save creates the row and
+  // redirects, which can't sensibly happen on a background timer.
+  const autosaveInFlight = useRef(false);
+  // `data` and `writePayload` are read inside the timeout, not at effect setup.
+  // Adding them would re-arm the debounce on every keystroke and the save would
+  // never fire; `currentSnapshot` already changes whenever they do.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: deps are read in the timeout, not at setup
+  useEffect(() => {
+    if (pageId === null) return;
+    if (!isDirty) return;
+    if (busy) return;
+    if (autosaveInFlight.current) return;
+    const handle = window.setTimeout(async () => {
+      autosaveInFlight.current = true;
+      const snapshotAtSave = currentSnapshot;
+      const payload = {
+        ...writePayload(),
+        draft_data: data as unknown as Record<string, unknown>,
+      };
+      setSaveState('saving');
+      try {
+        await savePage(pageId, payload);
+        setSavedSnapshot(snapshotAtSave);
+        setLastSavedAt(new Date());
+        setAutosaveError(null);
+        setSaveState('idle');
+      } catch (e) {
+        setAutosaveError(e instanceof Error ? e.message : 'Save failed');
+        setSaveState('error');
+      } finally {
+        autosaveInFlight.current = false;
+      }
+    }, AUTOSAVE_DEBOUNCE_MS);
+    return () => window.clearTimeout(handle);
+  }, [pageId, isDirty, busy, currentSnapshot, saveState]);
+
+  // beforeunload: only attached while dirty, so the browser confirm
+  // doesn't fire on a clean exit.
+  useEffect(() => {
+    if (!isDirty) return;
+    const handler = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      // Required by the spec; most browsers ignore the actual string.
+      event.returnValue = '';
+    };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [isDirty]);
+
+  return { isDirty, saveState, lastSavedAt, autosaveError, markSaved };
+}

pagebuilder/hooks/useEditorForm.ts

@@ -0,0 +1,193 @@
+/** Field state for the page editor, plus the derived write payload. */
+
+import type { Data } from '@puckeditor/core';
+import { useState } from 'react';
+
+import { emptyData } from '../components/puckConfig';
+import type { PageDetail } from '../utils/api';
+import type { EditorSnapshot } from '../utils/editorSnapshot';
+import { slugify } from '../utils/slugify';
+
+export interface EditorForm {
+  pageId: number | null;
+  setPageId: (id: number | null) => void;
+  title: string;
+  setTitle: (v: string) => void;
+  slug: string;
+  setSlug: (v: string) => void;
+  slugTouched: boolean;
+  setSlugTouched: (v: boolean) => void;
+  effectiveSlug: string;
+  metaDescription: string;
+  setMetaDescription: (v: string) => void;
+  ogImage: string;
+  setOgImage: (v: string) => void;
+  canonicalUrl: string;
+  setCanonicalUrl: (v: string) => void;
+  indexInSearch: boolean;
+  setIndexInSearch: (v: boolean) => void;
+  jsonLdText: string;
+  jsonLdError: string | null;
+  handleJsonLdChange: (v: string) => void;
+  status: PageDetail['status'];
+  setStatus: (v: PageDetail['status']) => void;
+  publishAt: string | null;
+  setPublishAt: (v: string | null) => void;
+  unpublishAt: string | null;
+  setUnpublishAt: (v: string | null) => void;
+  data: Data;
+  setData: (v: Data) => void;
+  writePayload: () => Record<string, unknown>;
+  snapshotPayload: EditorSnapshot;
+  applyRestored: (restored: PageDetail) => EditorSnapshot;
+}
+
+export function useEditorForm(page: PageDetail | null): EditorForm {
+  const [pageId, setPageId] = useState<number | null>(page?.id ?? null);
+  const [title, setTitle] = useState(page?.title ?? 'Untitled page');
+  const [slug, setSlug] = useState(page?.slug ?? '');
+  const [slugTouched, setSlugTouched] = useState(Boolean(page?.slug));
+  const [metaDescription, setMetaDescription] = useState(page?.meta_description ?? '');
+  const [ogImage, setOgImage] = useState(page?.og_image ?? '');
+  const [canonicalUrl, setCanonicalUrl] = useState(page?.canonical_url ?? '');
+  const [indexInSearch, setIndexInSearch] = useState<boolean>(page?.index_in_search ?? true);
+  const [jsonLdText, setJsonLdText] = useState<string>(
+    page?.json_ld ? JSON.stringify(page.json_ld, null, 2) : '',
+  );
+  const [jsonLdError, setJsonLdError] = useState<string | null>(null);
+  const [status, setStatus] = useState<PageDetail['status']>(page?.status ?? 'draft');
+  // ISO 8601 strings (with offset). The native ``datetime-local`` input
+  // emits *naive* values like ``"2026-05-19T09:30"`` so we adapt at the
+  // boundary in toLocalInput/fromLocalInput rather than carrying two
+  // representations through component state.
+  const [publishAt, setPublishAt] = useState<string | null>(page?.publish_at ?? null);
+  const [unpublishAt, setUnpublishAt] = useState<string | null>(page?.unpublish_at ?? null);
+  const [data, setData] = useState<Data>(
+    (page?.draft_data as unknown as Data) || (emptyData as unknown as Data),
+  );
+
+  const effectiveSlug = slugTouched ? slug : slugify(title);
+
+  const handleJsonLdChange = (value: string) => {
+    setJsonLdText(value);
+    const trimmed = value.trim();
+    if (!trimmed) {
+      setJsonLdError(null);
+      return;
+    }
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        setJsonLdError('JSON-LD must be a JSON object.');
+      } else {
+        setJsonLdError(null);
+      }
+    } catch (err) {
+      setJsonLdError(err instanceof Error ? err.message : 'Invalid JSON.');
+    }
+  };
+
+  // ``json_ld`` is omitted from the payload when the editor textarea is
+  // unparseable so a malformed draft doesn't silently overwrite a good
+  // saved value. The ``jsonLdError`` state surfaces the parse error inline.
+  const parseJsonLd = (): Record<string, unknown> | null | undefined => {
+    const trimmed = jsonLdText.trim();
+    if (!trimmed) return null;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return undefined;
+      }
+      return parsed as Record<string, unknown>;
+    } catch {
+      return undefined;
+    }
+  };
+
+  const writePayload = () => {
+    const parsedLd = parseJsonLd();
+    return {
+      title,
+      slug: effectiveSlug || slugify(title) || 'untitled',
+      meta_description: metaDescription.trim() ? metaDescription.trim() : null,
+      og_image: ogImage.trim() ? ogImage.trim() : null,
+      canonical_url: canonicalUrl.trim() ? canonicalUrl.trim() : null,
+      index_in_search: indexInSearch,
+      // Only include json_ld in the payload when we have a valid parse;
+      // ``undefined`` (parse error) is dropped so the server retains the
+      // previously saved value.
+      ...(parsedLd === undefined ? {} : { json_ld: parsedLd }),
+    };
+  };
+
+  const snapshotPayload: EditorSnapshot = {
+    title,
+    slug: effectiveSlug,
+    metaDescription,
+    ogImage,
+    canonicalUrl,
+    indexInSearch,
+    jsonLdText,
+    data,
+  };
+
+  /** Push a restored revision into the form; returns its snapshot. */
+  const applyRestored = (restored: PageDetail): EditorSnapshot => {
+    const restoredData = restored.draft_data as unknown as Data;
+    const restoredCanonical = restored.canonical_url ?? '';
+    const restoredIndex = restored.index_in_search ?? true;
+    const restoredJsonLd = restored.json_ld ? JSON.stringify(restored.json_ld, null, 2) : '';
+    setTitle(restored.title);
+    setMetaDescription(restored.meta_description ?? '');
+    setOgImage(restored.og_image ?? '');
+    setCanonicalUrl(restoredCanonical);
+    setIndexInSearch(restoredIndex);
+    setJsonLdText(restoredJsonLd);
+    setJsonLdError(null);
+    setData(restoredData);
+    return {
+      title: restored.title,
+      slug: restored.slug,
+      metaDescription: restored.meta_description ?? '',
+      ogImage: restored.og_image ?? '',
+      canonicalUrl: restoredCanonical,
+      indexInSearch: restoredIndex,
+      jsonLdText: restoredJsonLd,
+      data: restoredData,
+    };
+  };
+
+  return {
+    pageId,
+    setPageId,
+    title,
+    setTitle,
+    slug,
+    setSlug,
+    slugTouched,
+    setSlugTouched,
+    effectiveSlug,
+    metaDescription,
+    setMetaDescription,
+    ogImage,
+    setOgImage,
+    canonicalUrl,
+    setCanonicalUrl,
+    indexInSearch,
+    setIndexInSearch,
+    jsonLdText,
+    jsonLdError,
+    handleJsonLdChange,
+    status,
+    setStatus,
+    publishAt,
+    setPublishAt,
+    unpublishAt,
+    setUnpublishAt,
+    data,
+    setData,
+    writePayload,
+    snapshotPayload,
+    applyRestored,
+  };
+}

pagebuilder/hooks/useMediaUploads.ts

@@ -0,0 +1,96 @@
+/** Upload queue orchestration for the media library. */
+
+import { router } from '@inertiajs/react';
+import { useCallback, useState } from 'react';
+
+import type { UploadItem } from '../components/media/types';
+import { type MediaAssetRead, uploadMedia } from '../utils/api';
+import { uploadKey } from '../utils/mediaFormat';
+
+interface Params {
+  /** Folder new uploads are filed into; blank means Unfiled. */
+  uploadFolder: string;
+  /** Called once per successful upload so the page can splice it into view. */
+  onUploaded: (asset: MediaAssetRead) => void;
+  setMessage: (message: string | null) => void;
+}
+
+export interface MediaUploads {
+  uploads: UploadItem[];
+  startUploads: (files: File[]) => void;
+  dismissUpload: (id: string) => void;
+}
+
+export function useMediaUploads({ uploadFolder, onUploaded, setMessage }: Params): MediaUploads {
+  const [uploads, setUploads] = useState<UploadItem[]>([]);
+
+  const startUploads = useCallback(
+    (files: File[]) => {
+      if (files.length === 0) return;
+      const folderForBatch = uploadFolder.trim();
+      const items: UploadItem[] = files.map((file) => ({
+        id: uploadKey(file),
+        file,
+        status: 'pending',
+        loaded: 0,
+        total: file.size,
+        error: null,
+      }));
+      setUploads((prev) => [...prev, ...items]);
+      setMessage(null);
+
+      // Upload sequentially to avoid swamping the server with a 50-file
+      // drop; the per-file progress bar is what makes this feel fast.
+      void (async () => {
+        let succeeded = 0;
+        for (const item of items) {
+          setUploads((prev) =>
+            prev.map((u) => (u.id === item.id ? { ...u, status: 'uploading' } : u)),
+          );
+          try {
+            const asset = await uploadMedia(item.file, {
+              folder: folderForBatch || null,
+              onProgress: (loaded, total) => {
+                setUploads((prev) =>
+                  prev.map((u) =>
+                    u.id === item.id ? { ...u, loaded, total: total || u.total } : u,
+                  ),
+                );
+              },
+            });
+            setUploads((prev) =>
+              prev.map((u) => (u.id === item.id ? { ...u, status: 'done', loaded: u.total } : u)),
+            );
+            onUploaded(asset);
+            succeeded += 1;
+          } catch (e) {
+            setUploads((prev) =>
+              prev.map((u) =>
+                u.id === item.id
+                  ? {
+                      ...u,
+                      status: 'error',
+                      error: e instanceof Error ? e.message : 'Upload failed',
+                    }
+                  : u,
+              ),
+            );
+          }
+        }
+        if (succeeded > 0) {
+          setMessage(`Uploaded ${succeeded} file${succeeded === 1 ? '' : 's'}.`);
+          // Best-effort: also re-sync via Inertia so the SSR props
+          // reflect the new state on next reload.
+          router.reload({ only: ['initial'] });
+        }
+      })();
+    },
+    [uploadFolder, onUploaded, setMessage],
+  );
+
+  const dismissUpload = (id: string) => {
+    setUploads((prev) => prev.filter((u) => u.id !== id));
+  };
+
+  return { uploads, startUploads, dismissUpload };
+}

pagebuilder/hooks/usePageRevisions.ts

@@ -0,0 +1,59 @@
+/** Revision compare and restore actions for the page editor. */
+
+import { useState } from 'react';
+
+import { diffRevisions, type RevisionDiff, restoreRevision } from '../utils/api';
+import type { EditorSnapshot } from '../utils/editorSnapshot';
+import type { EditorForm } from './useEditorForm';
+
+interface Params {
+  form: EditorForm;
+  setBusy: (v: boolean) => void;
+  setMessage: (v: string | null) => void;
+  markSaved: (payload: EditorSnapshot) => void;
+}
+
+export interface PageRevisions {
+  activeDiff: RevisionDiff | null;
+  diffError: string | null;
+  handleCompare: (beforeId: number, afterId: number) => Promise<void>;
+  handleRestore: (revisionId: number) => Promise<void>;
+}
+
+export function usePageRevisions({ form, setBusy, setMessage, markSaved }: Params): PageRevisions {
+  const [activeDiff, setActiveDiff] = useState<RevisionDiff | null>(null);
+  const [diffError, setDiffError] = useState<string | null>(null);
+
+  const handleCompare = async (beforeId: number, afterId: number) => {
+    if (form.pageId === null) return;
+    if (activeDiff?.after_id === afterId && activeDiff?.before_id === beforeId) {
+      setActiveDiff(null);
+      return;
+    }
+    setDiffError(null);
+    try {
+      const diff = await diffRevisions(form.pageId, beforeId, afterId);
+      setActiveDiff(diff);
+    } catch (e) {
+      setDiffError(e instanceof Error ? e.message : 'Could not load diff');
+    }
+  };
+
+  const handleRestore = async (revisionId: number) => {
+    if (form.pageId === null) return;
+    if (!confirm('Replace the current draft with this revision?')) return;
+    setBusy(true);
+    setMessage(null);
+    try {
+      const restored = await restoreRevision(form.pageId, revisionId);
+      markSaved(form.applyRestored(restored));
+      setMessage('Revision restored to draft.');
+    } catch (e) {
+      setMessage(e instanceof Error ? e.message : 'Restore failed');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return { activeDiff, diffError, handleCompare, handleRestore };
+}

pagebuilder/hooks/usePageSchedule.ts

@@ -0,0 +1,72 @@
+/** Scheduled publish / unpublish actions for the page editor. */
+
+import { useState } from 'react';
+
+import { schedulePage } from '../utils/api';
+import { fromLocalInput } from '../utils/datetime';
+import type { EditorForm } from './useEditorForm';
+
+interface Params {
+  form: EditorForm;
+  setBusy: (v: boolean) => void;
+  setMessage: (v: string | null) => void;
+}
+
+export interface PageSchedule {
+  scheduleError: string | null;
+  handleSaveSchedule: () => Promise<void>;
+  handleClearSchedule: () => Promise<void>;
+}
+
+export function usePageSchedule({ form, setBusy, setMessage }: Params): PageSchedule {
+  const [scheduleError, setScheduleError] = useState<string | null>(null);
+
+  const handleSaveSchedule = async () => {
+    if (form.pageId === null) {
+      setScheduleError('Save a draft first.');
+      return;
+    }
+    setScheduleError(null);
+    const publish = fromLocalInput(form.publishAt);
+    const unpublish = fromLocalInput(form.unpublishAt);
+    if (publish && unpublish && publish >= unpublish) {
+      setScheduleError('Unpublish time must be after publish time.');
+      return;
+    }
+    setBusy(true);
+    try {
+      const updated = await schedulePage(form.pageId, {
+        publish_at: publish,
+        unpublish_at: unpublish,
+      });
+      form.setPublishAt(updated.publish_at);
+      form.setUnpublishAt(updated.unpublish_at);
+      setMessage('Schedule saved.');
+    } catch (e) {
+      setScheduleError(e instanceof Error ? e.message : 'Could not save schedule');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const handleClearSchedule = async () => {
+    if (form.pageId === null) return;
+    setBusy(true);
+    setScheduleError(null);
+    try {
+      const updated = await schedulePage(form.pageId, {
+        publish_at: null,
+        unpublish_at: null,
+      });
+      form.setPublishAt(updated.publish_at);
+      form.setUnpublishAt(updated.unpublish_at);
+      setMessage('Schedule cleared.');
+    } catch (e) {
+      setScheduleError(e instanceof Error ? e.message : 'Could not clear schedule');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return { scheduleError, handleSaveSchedule, handleClearSchedule };
+}