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

pagebuilder/endpoints/views.py

@@ -0,0 +1,228 @@
+"""Inertia view routes for the pagebuilder module.
+
+Admin views are mounted under the module's ``view_prefix`` (``/pagebuilder``).
+The public viewer is mounted at the host root via ``register_routes`` so the
+URL is ``/{public_route_prefix}/{slug}`` (default ``/p/{slug}``) rather than
+namespaced under the admin prefix.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+from inertia import InertiaResponse
+from simple_module_db import get_db
+from simple_module_hosting.inertia_deps import InertiaDep
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from pagebuilder.contracts.schemas import (
+    LayoutDetail,
+    LayoutRevisionListResponse,
+    LayoutRevisionRead,
+    MediaAssetListResponse,
+    PageDetail,
+    PageListResponse,
+    PageRead,
+    PageRevisionListResponse,
+    PageRevisionRead,
+)
+from pagebuilder.deps import get_media_service, get_settings
+from pagebuilder.layout_service import LayoutService, public_layout_props
+from pagebuilder.media_service import MediaService
+from pagebuilder.service import PagesService
+from pagebuilder.settings import PagebuilderSettings
+
+
+def _etag_for(
+    page_id: int,
+    updated_at: datetime | None,
+    layout_updated_at: datetime | None = None,
+) -> str:
+    """Stable, short ETag derived from page identity + last-modified time.
+
+    ``layout_updated_at`` participates so a site-wide header / footer
+    edit invalidates every page's cached chrome — without it, clients
+    keep serving stale layout from cache until the page itself changes.
+    """
+    stamp = updated_at.isoformat() if updated_at is not None else ""
+    layout_stamp = (
+        layout_updated_at.isoformat() if layout_updated_at is not None else ""
+    )
+    digest = hashlib.sha1(f"{page_id}:{stamp}:{layout_stamp}".encode()).hexdigest()[:16]
+    return f'W/"{digest}"'
+
+
+def _public_base_url(request: Request, settings: PagebuilderSettings) -> str:
+    """Resolve the public origin used to build absolute URLs.
+
+    Prefer the explicit setting (the deployment knows its public host)
+    and only fall back to the inbound request for local dev / scenarios
+    where the host header is trustworthy. Always returned without a
+    trailing slash so callers can concatenate path segments directly.
+    """
+    if settings.public_base_url:
+        return settings.public_base_url.rstrip("/")
+    return f"{request.url.scheme}://{request.url.netloc}".rstrip("/")
+
+
+def _absolute_page_url(
+    request: Request, settings: PagebuilderSettings, slug: str
+) -> str:
+    base = _public_base_url(request, settings)
+    prefix = settings.public_route_prefix.rstrip("/")
+    return f"{base}{prefix}/{slug}"
+
+
+router = APIRouter()
+public_router = APIRouter()
+
+_PAGE_LIST = "PageBuilder/PageList"
+_PAGE_EDITOR = "PageBuilder/PageEditor"
+_PAGE_PUBLIC = "PageBuilder/PublicPage"
+_PAGE_MEDIA = "PageBuilder/MediaLibrary"
+_PAGE_PENDING = "PageBuilder/PendingReview"
+_PAGE_LAYOUT_EDITOR = "PageBuilder/LayoutEditor"
+
+
+@router.get("/", response_model=None)
+async def admin_list(
+    inertia: InertiaDep,
+    db: AsyncSession = Depends(get_db),
+) -> InertiaResponse:
+    pages = await PagesService(db).list_pages()
+    payload = PageListResponse(items=[PageRead.model_validate(p) for p in pages])
+    return await inertia.render(_PAGE_LIST, {"pages": payload.model_dump(mode="json")})
+
+
+@router.get("/pending", response_model=None)
+async def admin_pending(
+    inertia: InertiaDep,
+    db: AsyncSession = Depends(get_db),
+) -> InertiaResponse:
+    """Approver queue view — pages awaiting review."""
+    pages = await PagesService(db).list_pending()
+    payload = PageListResponse(items=[PageRead.model_validate(p) for p in pages])
+    return await inertia.render(
+        _PAGE_PENDING, {"pages": payload.model_dump(mode="json")}
+    )
+
+
+@router.get("/new", response_model=None)
+async def admin_new(inertia: InertiaDep) -> InertiaResponse:
+    return await inertia.render(_PAGE_EDITOR, {"page": None, "revisions": []})
+
+
+@router.get("/{page_id}/edit", response_model=None)
+async def admin_edit(
+    page_id: int,
+    inertia: InertiaDep,
+    db: AsyncSession = Depends(get_db),
+) -> InertiaResponse:
+    service = PagesService(db)
+    page = await service.get_page(page_id)
+    revisions = await service.list_revisions(page_id)
+    revisions_payload = PageRevisionListResponse(
+        items=[PageRevisionRead.model_validate(r) for r in revisions]
+    )
+    return await inertia.render(
+        _PAGE_EDITOR,
+        {
+            "page": PageDetail.model_validate(page).model_dump(mode="json"),
+            "revisions": revisions_payload.model_dump(mode="json")["items"],
+        },
+    )
+
+
+@router.get("/layout", response_model=None)
+async def admin_layout(
+    inertia: InertiaDep,
+    db: AsyncSession = Depends(get_db),
+) -> InertiaResponse:
+    """Edit the site-wide header + footer."""
+    service = LayoutService(db)
+    layout = await service.get()
+    revisions = await service.list_revisions()
+    return await inertia.render(
+        _PAGE_LAYOUT_EDITOR,
+        {
+            "layout": LayoutDetail.model_validate(layout).model_dump(mode="json"),
+            "revisions": LayoutRevisionListResponse(
+                items=[LayoutRevisionRead.model_validate(r) for r in revisions]
+            ).model_dump(mode="json")["items"],
+        },
+    )
+
+
+@router.get("/media", response_model=None)
+async def admin_media(
+    inertia: InertiaDep,
+    media: MediaService = Depends(get_media_service),
+) -> InertiaResponse:
+    # Server-render the first page only; the React side handles further
+    # pagination + filtering via the JSON API. Folder list is loaded so
+    # the sidebar paints immediately on first navigation.
+    assets, next_cursor = await media.list_assets()
+    folders = await media.list_folders()
+    payload = MediaAssetListResponse(
+        items=[media.to_read(a) for a in assets],
+        next_cursor=next_cursor,
+        folders=folders,
+    )
+    return await inertia.render(
+        _PAGE_MEDIA,
+        {
+            "initial": payload.model_dump(mode="json"),
+        },
+    )
+
+
+@public_router.get("/{slug}", response_model=None)
+async def public_view(
+    slug: str,
+    request: Request,
+    inertia: InertiaDep,
+    db: AsyncSession = Depends(get_db),
+    settings: PagebuilderSettings = Depends(get_settings),
+) -> Response:
+    page = await PagesService(db).get_by_slug_published(slug)
+    if page is None or page.published_data is None:
+        raise HTTPException(status_code=404, detail="Page not found")
+
+    layout = await LayoutService(db).get()
+    etag = _etag_for(page.id or 0, page.updated_at, layout.updated_at)
+    cache_parts = [f"max-age={settings.public_cache_max_age}"]
+    if settings.public_cache_swr > 0:
+        cache_parts.append(f"stale-while-revalidate={settings.public_cache_swr}")
+    cache_control = "public, " + ", ".join(cache_parts)
+
+    def apply_headers(response: Response) -> Response:
+        response.headers["ETag"] = etag
+        response.headers["Cache-Control"] = cache_control
+        if settings.public_csp:
+            response.headers["Content-Security-Policy"] = settings.public_csp
+        return response
+
+    if request.headers.get("if-none-match") == etag:
+        return apply_headers(Response(status_code=304))
+
+    canonical = page.canonical_url or _absolute_page_url(request, settings, slug)
+    return apply_headers(
+        await inertia.render(
+            _PAGE_PUBLIC,
+            {
+                "title": page.title,
+                "data": page.published_data,
+                "meta_description": page.meta_description,
+                "og_image": page.og_image,
+                "canonical_url": canonical,
+                "og_url": canonical,
+                "index_in_search": page.index_in_search,
+                "json_ld": page.json_ld,
+                "site_name": settings.site_name,
+                "twitter_handle": settings.twitter_handle,
+                **public_layout_props(layout),
+            },
+        )
+    )

pagebuilder/fields/checkbox-field.tsx

@@ -0,0 +1,22 @@
+import type { CustomField } from "@puckeditor/core";
+
+export function createCheckboxField(label: string): CustomField<boolean> {
+	return {
+		type: "custom",
+		label,
+		render: ({ name, onChange, value, field }) => (
+			<div className="flex items-center gap-2 py-2">
+				<input
+					type="checkbox"
+					id={name}
+					checked={Boolean(value)}
+					onChange={(event) => onChange(event.target.checked)}
+					className="size-4 rounded border-gray-300"
+				/>
+				<label htmlFor={name} className="text-sm font-medium leading-none">
+					{field.label || label}
+				</label>
+			</div>
+		),
+	};
+}

pagebuilder/fields/file-picker/file-gallery.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import type { FileItem, FilePickerAdapter } from "./types";
+
+interface FileGalleryProps {
+	adapter: FilePickerAdapter;
+	open: boolean;
+	onClose: () => void;
+	/**
+	 * The picked file. `url` is first so URL-only consumers (Puck widgets, the
+	 * branding footer logos) keep working unchanged; `item` carries the full
+	 * record for callers that need the file id instead — see the ImagePicker's
+	 * `valueMode="id"`.
+	 */
+	onSelect: (url: string, item: FileItem) => void;
+}
+
+const PAGE_SIZE = 12;
+
+export function FileGallery({
+	adapter,
+	open,
+	onClose,
+	onSelect,
+}: FileGalleryProps) {
+	const [items, setItems] = useState<FileItem[]>([]);
+	const [totalCount, setTotalCount] = useState(0);
+	const [loading, setLoading] = useState(false);
+	const [page, setPage] = useState(0);
+
+	useEffect(() => {
+		if (!open) return;
+		setLoading(true);
+		adapter
+			.list({ skip: page * PAGE_SIZE, take: PAGE_SIZE })
+			.then((result) => {
+				setItems(result.items);
+				setTotalCount(result.totalCount);
+			})
+			.catch((err) => {
+				// Log instead of letting the rejection go unhandled. Keep whatever
+				// items are already displayed — wiping them on a failed page fetch
+				// would misread as "your uploads are gone".
+				console.error("[FileGallery] Failed to list files:", err);
+			})
+			.finally(() => setLoading(false));
+	}, [adapter, open, page]);
+
+	useEffect(() => {
+		if (!open) return;
+		const handleKeyDown = (e: KeyboardEvent) => {
+			if (e.key === "Escape") onClose();
+		};
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [open, onClose]);
+
+	if (!open) return null;
+
+	const hasMore = (page + 1) * PAGE_SIZE < totalCount;
+	const hasPrev = page > 0;
+
+	return createPortal(
+		<div
+			className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/50"
+			onClick={(e) => {
+				if (e.target === e.currentTarget) onClose();
+			}}
+		>
+			<div className="bg-white rounded-lg shadow-xl w-full max-w-3xl max-h-[80vh] flex flex-col m-4">
+				<div className="flex items-center justify-between px-4 py-3 border-b">
+					<h2 className="text-lg font-semibold">Select a file</h2>
+					<button
+						type="button"
+						onClick={onClose}
+						className="text-gray-500 hover:text-gray-700 text-xl leading-none"
+					>
+						&times;
+					</button>
+				</div>
+				<div className="flex-1 overflow-y-auto p-4">
+					{loading ? (
+						<div className="text-center py-8 text-gray-500">Loading...</div>
+					) : items.length === 0 ? (
+						<div className="text-center py-8 text-gray-500">
+							No files uploaded yet.
+						</div>
+					) : (
+						<div className="grid grid-cols-3 sm:grid-cols-4 gap-3">
+							{items.map((item) => (
+								<button
+									key={item.id}
+									type="button"
+									onClick={() => {
+										onSelect(item.url, item);
+										onClose();
+									}}
+									className="group relative aspect-square rounded-md overflow-hidden border hover:ring-2 hover:ring-blue-500 focus:ring-2 focus:ring-blue-500 outline-none"
+								>
+									{item.mimeType.startsWith("image/") ? (
+										<img
+											src={item.url}
+											alt=""
+											className="w-full h-full object-cover"
+										/>
+									) : (
+										<div className="w-full h-full flex items-center justify-center bg-gray-100 text-xs text-gray-500 p-2 text-center">
+											{item.mimeType}
+										</div>
+									)}
+									<div className="absolute inset-x-0 bottom-0 bg-black/60 text-white text-xs px-1 py-0.5 opacity-0 group-hover:opacity-100 transition-opacity truncate">
+										{formatFileSize(item.fileSize)}
+									</div>
+								</button>
+							))}
+						</div>
+					)}
+				</div>
+				<div className="flex items-center justify-between px-4 py-3 border-t">
+					<span className="text-sm text-gray-500">
+						{totalCount} file{totalCount !== 1 ? "s" : ""}
+					</span>
+					<div className="flex gap-2">
+						<button
+							type="button"
+							onClick={() => setPage((p) => p - 1)}
+							disabled={!hasPrev}
+							className="px-3 py-1 text-sm rounded border disabled:opacity-40 hover:bg-gray-50"
+						>
+							Prev
+						</button>
+						<button
+							type="button"
+							onClick={() => setPage((p) => p + 1)}
+							disabled={!hasMore}
+							className="px-3 py-1 text-sm rounded border disabled:opacity-40 hover:bg-gray-50"
+						>
+							Next
+						</button>
+					</div>
+				</div>
+			</div>
+		</div>,
+		document.body,
+	);
+}
+
+function formatFileSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

pagebuilder/fields/file-picker/image-picker-field.tsx

@@ -0,0 +1,214 @@
+import type { CustomField } from "@puckeditor/core";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { cn } from "../../utils/widgetUtils";
+import { FileGallery } from "./file-gallery";
+import type { FilePickerAdapter } from "./types";
+
+/**
+ * An image field backed by a media library.
+ *
+ * Generic over the prop type because widgets declare image props both as
+ * `string` and as `string | undefined` (an optional icon, say), and Puck's
+ * `CustomField` is invariant in its value — a single concrete type would fail
+ * to assign at one call site or the other.
+ */
+export function createImageField<T extends string | undefined = string>(
+	adapter: FilePickerAdapter,
+	label = "Image",
+): CustomField<T> {
+	return {
+		type: "custom",
+		label,
+		render: ({ value, onChange }) => (
+			<ImagePickerFieldRenderer
+				value={value ?? ""}
+				onChange={(next) => onChange(next as T)}
+				adapter={adapter}
+			/>
+		),
+	} as CustomField<T>;
+}
+
+interface ImagePickerFieldRendererProps {
+	value: string;
+	onChange: (value: string) => void;
+	adapter: FilePickerAdapter;
+	/**
+	 * What `value`/`onChange` carry.
+	 *
+	 * `"url"` (default) — a ready-to-render view URL, which is what Puck stores
+	 * verbatim in page content. `"id"` — the bare file id, for records that hold
+	 * a FK to the file (e.g. News.ImageId) and build the URL at render time.
+	 * Defaulting to `"url"` keeps every existing Puck widget untouched.
+	 */
+	valueMode?: "url" | "id";
+	/** Marks the hidden file input + drop zone, so hosts can target them in tests. */
+	testId?: string;
+	disabled?: boolean;
+}
+
+export function ImagePickerFieldRenderer({
+	value,
+	onChange,
+	adapter,
+	valueMode = "url",
+	testId,
+	disabled = false,
+}: ImagePickerFieldRendererProps) {
+	const [galleryOpen, setGalleryOpen] = useState(false);
+	const [uploading, setUploading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const [isDragOver, setIsDragOver] = useState(false);
+
+	// Any external or internal value change resolves a previous failure.
+	// biome-ignore lint/correctness/useExhaustiveDependencies(value): the effect intentionally keys on value changes without reading it
+	useEffect(() => {
+		setError(null);
+	}, [value]);
+	const fileInputRef = useRef<HTMLInputElement>(null);
+
+	const uploadFile = useCallback(
+		async (file: File) => {
+			setError(null);
+			setUploading(true);
+			try {
+				const result = await adapter.upload(file);
+				onChange(valueMode === "id" ? result.id : result.url);
+			} catch (err) {
+				console.error("[ImagePicker] Upload failed:", err);
+				setError("Upload failed. Please try again.");
+			} finally {
+				setUploading(false);
+				if (fileInputRef.current) fileInputRef.current.value = "";
+			}
+		},
+		[adapter, onChange, valueMode],
+	);
+
+	// In "id" mode `value` is a bare file id, so the preview has to resolve it
+	// through the adapter; in "url" mode it is already renderable.
+	const previewSrc = value
+		? valueMode === "id"
+			? adapter.getViewUrl(value)
+			: value
+		: null;
+
+	const handleUpload = useCallback(
+		(e: React.ChangeEvent<HTMLInputElement>) => {
+			const file = e.target.files?.[0];
+			if (!file) return;
+			void uploadFile(file);
+		},
+		[uploadFile],
+	);
+
+	const handleDrop = useCallback(
+		(e: React.DragEvent<HTMLDivElement>) => {
+			e.preventDefault();
+			setIsDragOver(false);
+			if (uploading) return;
+			const file = e.dataTransfer.files?.[0];
+			if (!file) return;
+			if (!file.type.startsWith("image/")) {
+				setError("Only image files can be dropped here.");
+				return;
+			}
+			void uploadFile(file);
+		},
+		[uploading, uploadFile],
+	);
+
+	const handleDragOver = useCallback((e: React.DragEvent<HTMLDivElement>) => {
+		e.preventDefault();
+		setIsDragOver(true);
+	}, []);
+
+	const handleDragLeave = useCallback(() => {
+		setIsDragOver(false);
+	}, []);
+
+	return (
+		<div className="space-y-2">
+			<div
+				data-testid={testId ? `${testId}-drop-zone` : "image-drop-zone"}
+				onDrop={handleDrop}
+				onDragOver={handleDragOver}
+				onDragLeave={handleDragLeave}
+				className={cn(
+					"w-full aspect-video rounded-md overflow-hidden",
+					isDragOver
+						? "border-2 border-blue-400 bg-blue-50"
+						: value
+							? "border bg-gray-50"
+							: "border-2 border-dashed border-gray-300",
+				)}
+			>
+				{previewSrc ? (
+					<img
+						src={previewSrc}
+						alt=""
+						className="w-full h-full object-contain"
+					/>
+				) : (
+					<div className="w-full h-full flex items-center justify-center text-sm text-gray-400">
+						No image selected — or drag an image here
+					</div>
+				)}
+			</div>
+			<div className="flex gap-2">
+				<button
+					type="button"
+					onClick={() => fileInputRef.current?.click()}
+					disabled={uploading || disabled}
+					className="flex-1 px-3 py-1.5 text-sm rounded border bg-white hover:bg-gray-50 disabled:opacity-50"
+				>
+					{uploading ? "Uploading..." : "Upload"}
+				</button>
+				<button
+					type="button"
+					onClick={() => setGalleryOpen(true)}
+					disabled={disabled}
+					className="flex-1 px-3 py-1.5 text-sm rounded border bg-white hover:bg-gray-50 disabled:opacity-50"
+				>
+					Browse
+				</button>
+				{value && (
+					<button
+						type="button"
+						onClick={() => {
+							setError(null);
+							onChange("");
+						}}
+						disabled={disabled}
+						className="px-3 py-1.5 text-sm rounded border bg-white hover:bg-gray-50 text-red-600 disabled:opacity-50"
+					>
+						Clear
+					</button>
+				)}
+			</div>
+			{error && (
+				<div role="alert" className="text-sm text-red-600">
+					{error}
+				</div>
+			)}
+			<input
+				ref={fileInputRef}
+				type="file"
+				accept="image/*"
+				onChange={handleUpload}
+				disabled={disabled}
+				data-testid={testId}
+				className="hidden"
+			/>
+			<FileGallery
+				adapter={adapter}
+				open={galleryOpen}
+				onClose={() => setGalleryOpen(false)}
+				onSelect={(url, item) => {
+					setError(null);
+					onChange(valueMode === "id" ? item.id : url);
+				}}
+			/>
+		</div>
+	);
+}

pagebuilder/fields/file-picker/index.ts

@@ -0,0 +1,6 @@
+export { FileGallery } from "./file-gallery";
+export {
+	createImageField,
+	ImagePickerFieldRenderer,
+} from "./image-picker-field";
+export type { FileItem, FilePickerAdapter } from "./types";

pagebuilder/fields/file-picker/types.ts

@@ -0,0 +1,15 @@
+export interface FileItem {
+	id: string;
+	mimeType: string;
+	fileSize: number;
+	url: string;
+}
+
+export interface FilePickerAdapter {
+	upload(file: File): Promise<FileItem>;
+	list(params: {
+		skip?: number;
+		take?: number;
+	}): Promise<{ items: FileItem[]; totalCount: number }>;
+	getViewUrl(id: string): string;
+}

pagebuilder/fields/index.ts

@@ -0,0 +1,9 @@
+// Custom Puck fields for this module.
+//
+// The image field is backed by the module's own media library, so authors
+// swap a picture by choosing a different upload rather than typing a path.
+export { createCheckboxField } from './checkbox-field';
+export { FileGallery } from './file-picker/file-gallery';
+export { createImageField, ImagePickerFieldRenderer } from './file-picker/image-picker-field';
+export type { FileItem, FilePickerAdapter } from './file-picker/types';
+export { mediaLibraryAdapter } from './media-adapter';

pagebuilder/fields/media-adapter.ts

@@ -0,0 +1,47 @@
+/**
+ * FilePickerAdapter backed by this module's own media library.
+ *
+ * The image fields in every widget go through this, so the pictures on a page
+ * are the ones an author uploaded to `/pagebuilder/media` — swapping one is
+ * picking a different upload, not editing a path by hand.
+ */
+
+import { deleteMedia, listMedia, type MediaAssetRead, uploadMedia } from '../utils/api';
+import type { FileItem, FilePickerAdapter } from './file-picker/types';
+
+function toFileItem(asset: MediaAssetRead): FileItem {
+  return {
+    id: String(asset.id),
+    mimeType: asset.content_type,
+    fileSize: asset.size_bytes,
+    url: asset.url,
+  };
+}
+
+export const mediaLibraryAdapter: FilePickerAdapter = {
+  async upload(file: File): Promise<FileItem> {
+    return toFileItem(await uploadMedia(file));
+  },
+
+  async list({ skip = 0, take = 24 } = {}) {
+    // The gallery jumps to arbitrary pages, so it uses the uploads endpoint's
+    // offset mode; that mode is also what makes the response carry `total`.
+    const response = await listMedia({ offset: skip, limit: take });
+    return {
+      items: response.items.map(toFileItem),
+      totalCount: response.total ?? response.items.length,
+    };
+  },
+
+  /**
+   * Only reachable in the picker's "id" mode, which this module never uses:
+   * assets carry a ready-to-render URL on the record, so fields store that
+   * directly. There is no id → URL endpoint to call here, and inventing a
+   * path from the numeric id would silently produce broken images.
+   */
+  getViewUrl(): string {
+    throw new Error(
+      'mediaLibraryAdapter stores URLs, not ids — use the picker in its default "url" mode.',
+    );
+  },
+};