simple-module-pagebuilder 0.0.1__tar.gz

simple_module_pagebuilder-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+*.db
+*.sqlite3
+.env
+
+*/static/dist/

simple_module_pagebuilder-0.0.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: simple_module_pagebuilder
+Version: 0.0.1
+Summary: Drag-and-drop visual page builder for simple_module apps
+Project-URL: Repository, https://github.com/antosubash/simple_module_python_modules
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: cms,pagebuilder,puck,simple-module
+Requires-Python: >=3.12
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: simple-module-core<0.1,>=0.0.25
+Requires-Dist: simple-module-db<0.1,>=0.0.25
+Requires-Dist: simple-module-hosting<0.1,>=0.0.25
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: sqlmodel>=0.0.21
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: simple-module-test<0.1,>=0.0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# simple_module_pagebuilder
+
+Drag-and-drop visual page builder for [simple_module](https://github.com/antosubash/simple_module_python)
+apps. Pages are composed from a reusable block library using
+[Puck](https://puckeditor.com) and stored as JSON; published pages are served
+at `/p/{slug}`.
+
+## Features
+
+- **Visual editor** — Puck-based drag-and-drop with a block library (heading,
+  text, image, button, columns, spacer) and a media picker.
+- **Site layout** — a shared header/footer layout, edited the same way, wrapped
+  around every public page.
+- **Media library** — uploads with magic-byte content sniffing, folder
+  organisation, and server-generated WebP thumbnails.
+- **Revisions** — every status transition snapshots the page, with a diff view
+  and restore-as-draft.
+- **Approval workflow** — edit → submit for review → approve / reject, gated by
+  three separate permissions.
+- **Scheduled publishing** — set `publish_at` / `unpublish_at`; a background
+  poller flips status at the due time.
+- **SEO** — per-page meta description, canonical URL, OG image, JSON-LD, plus
+  `/sitemap.xml` and `/robots.txt`.
+
+## Installation
+
+```bash
+uv add simple_module_pagebuilder
+```
+
+Then add it to your host's `pyproject.toml` dependencies. The module is
+discovered at boot through the `simple_module` entry point — no registration
+code required.
+
+Its frontend ships inside the wheel. Pull its JS dependencies into your host's
+client app and regenerate the page manifest with:
+
+```bash
+smpy host sync-js-deps --host-client-app=host/client_app
+smpy host gen-pages --host-dir=host/client_app
+```
+
+## Usage
+
+Once installed and migrated, sign in and open `/pagebuilder`:
+
+1. **Create a page** — `/pagebuilder/new`. Give it a title; the slug is derived
+   from it and stays editable.
+2. **Compose it** — drag blocks from the Puck sidebar. Images come from the
+   media library, which uploads and thumbnails them for you.
+3. **Publish it** — publish directly with `pagebuilder.publish`, or submit for
+   review if your role only carries `pagebuilder.edit`. Reviewers work through
+   `/pagebuilder/pending`.
+4. **Schedule it** — set `publish_at` / `unpublish_at` instead of publishing
+   now, and the poller flips the status at the due time.
+5. **View it** — the page is live at `/p/{slug}`, wrapped in the site layout
+   from `/pagebuilder/layout`.
+
+Every transition writes a revision, so `/pagebuilder/{id}/edit` can compare any
+two revisions and restore either one as a draft.
+
+## Migrations
+
+This module ships **no** migrations — that is the framework convention. Its
+SQLModel tables are picked up by your host's `build_module_metadata()`, so
+after installing it run:
+
+```bash
+make migration msg="add pagebuilder"
+make migrate
+```
+
+Add `branch_labels = ("pagebuilder",)` to that first generated revision so the
+module can later be removed on its own with
+`alembic downgrade pagebuilder@base`.
+
+## Permissions
+
+| Permission | Grants |
+|---|---|
+| `pagebuilder.edit` | Draft, save, submit for review, restore a revision |
+| `pagebuilder.publish` | Publish and unpublish directly |
+| `pagebuilder.approve` | Approve or reject a submitted page |
+
+`DEFAULT_ROLE_MAP` in `pagebuilder.permissions` suggests three roles —
+`pagebuilder_editor`, `pagebuilder_publisher`, `pagebuilder_approver` —
+cumulatively mapped to those permissions.
+
+## Settings
+
+All settings use the `SM_PAGEBUILDER_` env prefix.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `public_route_prefix` | `/p` | Where published pages are served |
+| `requires_auth` | `true` | Gate the admin surface behind authentication |
+| `csrf_protect` | `true` | Require a CSRF token on mutating admin requests |
+| `media_root` | `var/pagebuilder/media` | Upload storage directory |
+| `media_url_prefix` | `/media/pagebuilder` | Public URL prefix for uploads |
+| `media_max_bytes` | `10485760` | Per-upload size ceiling |
+| `media_thumbnail_widths` | `320,640,1280,1920` | Widths generated as WebP |
+| `media_webp_quality` | `82` | WebP encoder quality |
+| `public_csp` | see `settings.py` | CSP header on public pages |
+| `public_cache_max_age` | `60` | `max-age` on public pages |
+| `public_base_url` | `None` | Absolute base for canonical URLs and the sitemap |
+| `site_name` | `None` | OpenGraph site name |
+| `sitemap_enabled` | `true` | Serve `/sitemap.xml` |
+| `robots_enabled` | `true` | Serve `/robots.txt` |
+| `scheduler_enabled` | `true` | Run the scheduled publish/unpublish poller |
+| `scheduler_interval_seconds` | `30` | Poll interval |
+
+## Routes
+
+**Admin views** (under `/pagebuilder`): `/`, `/new`, `/{page_id}/edit`,
+`/pending`, `/layout`, `/media`.
+
+**Admin API** (under `/api/pagebuilder`): pages CRUD, workflow transitions,
+revisions and diffs, layout and its revisions, uploads.
+
+**Public**: `/p/{slug}`, `/sitemap.xml`, `/robots.txt`.
+
+## Contracts
+
+DTOs other modules may depend on are exported from `pagebuilder.contracts`.
+Everything else in the package is internal and may change without a major
+version bump.
+
+## Licence
+
+MIT

simple_module_pagebuilder-0.0.1/README.md

@@ -0,0 +1,130 @@
+# simple_module_pagebuilder
+
+Drag-and-drop visual page builder for [simple_module](https://github.com/antosubash/simple_module_python)
+apps. Pages are composed from a reusable block library using
+[Puck](https://puckeditor.com) and stored as JSON; published pages are served
+at `/p/{slug}`.
+
+## Features
+
+- **Visual editor** — Puck-based drag-and-drop with a block library (heading,
+  text, image, button, columns, spacer) and a media picker.
+- **Site layout** — a shared header/footer layout, edited the same way, wrapped
+  around every public page.
+- **Media library** — uploads with magic-byte content sniffing, folder
+  organisation, and server-generated WebP thumbnails.
+- **Revisions** — every status transition snapshots the page, with a diff view
+  and restore-as-draft.
+- **Approval workflow** — edit → submit for review → approve / reject, gated by
+  three separate permissions.
+- **Scheduled publishing** — set `publish_at` / `unpublish_at`; a background
+  poller flips status at the due time.
+- **SEO** — per-page meta description, canonical URL, OG image, JSON-LD, plus
+  `/sitemap.xml` and `/robots.txt`.
+
+## Installation
+
+```bash
+uv add simple_module_pagebuilder
+```
+
+Then add it to your host's `pyproject.toml` dependencies. The module is
+discovered at boot through the `simple_module` entry point — no registration
+code required.
+
+Its frontend ships inside the wheel. Pull its JS dependencies into your host's
+client app and regenerate the page manifest with:
+
+```bash
+smpy host sync-js-deps --host-client-app=host/client_app
+smpy host gen-pages --host-dir=host/client_app
+```
+
+## Usage
+
+Once installed and migrated, sign in and open `/pagebuilder`:
+
+1. **Create a page** — `/pagebuilder/new`. Give it a title; the slug is derived
+   from it and stays editable.
+2. **Compose it** — drag blocks from the Puck sidebar. Images come from the
+   media library, which uploads and thumbnails them for you.
+3. **Publish it** — publish directly with `pagebuilder.publish`, or submit for
+   review if your role only carries `pagebuilder.edit`. Reviewers work through
+   `/pagebuilder/pending`.
+4. **Schedule it** — set `publish_at` / `unpublish_at` instead of publishing
+   now, and the poller flips the status at the due time.
+5. **View it** — the page is live at `/p/{slug}`, wrapped in the site layout
+   from `/pagebuilder/layout`.
+
+Every transition writes a revision, so `/pagebuilder/{id}/edit` can compare any
+two revisions and restore either one as a draft.
+
+## Migrations
+
+This module ships **no** migrations — that is the framework convention. Its
+SQLModel tables are picked up by your host's `build_module_metadata()`, so
+after installing it run:
+
+```bash
+make migration msg="add pagebuilder"
+make migrate
+```
+
+Add `branch_labels = ("pagebuilder",)` to that first generated revision so the
+module can later be removed on its own with
+`alembic downgrade pagebuilder@base`.
+
+## Permissions
+
+| Permission | Grants |
+|---|---|
+| `pagebuilder.edit` | Draft, save, submit for review, restore a revision |
+| `pagebuilder.publish` | Publish and unpublish directly |
+| `pagebuilder.approve` | Approve or reject a submitted page |
+
+`DEFAULT_ROLE_MAP` in `pagebuilder.permissions` suggests three roles —
+`pagebuilder_editor`, `pagebuilder_publisher`, `pagebuilder_approver` —
+cumulatively mapped to those permissions.
+
+## Settings
+
+All settings use the `SM_PAGEBUILDER_` env prefix.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `public_route_prefix` | `/p` | Where published pages are served |
+| `requires_auth` | `true` | Gate the admin surface behind authentication |
+| `csrf_protect` | `true` | Require a CSRF token on mutating admin requests |
+| `media_root` | `var/pagebuilder/media` | Upload storage directory |
+| `media_url_prefix` | `/media/pagebuilder` | Public URL prefix for uploads |
+| `media_max_bytes` | `10485760` | Per-upload size ceiling |
+| `media_thumbnail_widths` | `320,640,1280,1920` | Widths generated as WebP |
+| `media_webp_quality` | `82` | WebP encoder quality |
+| `public_csp` | see `settings.py` | CSP header on public pages |
+| `public_cache_max_age` | `60` | `max-age` on public pages |
+| `public_base_url` | `None` | Absolute base for canonical URLs and the sitemap |
+| `site_name` | `None` | OpenGraph site name |
+| `sitemap_enabled` | `true` | Serve `/sitemap.xml` |
+| `robots_enabled` | `true` | Serve `/robots.txt` |
+| `scheduler_enabled` | `true` | Run the scheduled publish/unpublish poller |
+| `scheduler_interval_seconds` | `30` | Poll interval |
+
+## Routes
+
+**Admin views** (under `/pagebuilder`): `/`, `/new`, `/{page_id}/edit`,
+`/pending`, `/layout`, `/media`.
+
+**Admin API** (under `/api/pagebuilder`): pages CRUD, workflow transitions,
+revisions and diffs, layout and its revisions, uploads.
+
+**Public**: `/p/{slug}`, `/sitemap.xml`, `/robots.txt`.
+
+## Contracts
+
+DTOs other modules may depend on are exported from `pagebuilder.contracts`.
+Everything else in the package is internal and may change without a major
+version bump.
+
+## Licence
+
+MIT

simple_module_pagebuilder-0.0.1/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@simple-module-py/pagebuilder",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Frontend assets for the PageBuilder module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {
+    "@puckeditor/core": "^0.22.4"
+  }
+}

simple_module_pagebuilder-0.0.1/pagebuilder/components/DiffSummary.tsx

@@ -0,0 +1,107 @@
+import type React from 'react';
+import type { RevisionDiff } from '../utils/api';
+
+interface Props {
+  diff: RevisionDiff;
+}
+
+function renderValue(value: unknown): string {
+  if (value === null || value === undefined) return '∅';
+  if (typeof value === 'string') return value || '""';
+  return JSON.stringify(value);
+}
+
+/**
+ * Compact, scannable diff: metadata table (only changed fields) plus
+ * three lists of blocks (added / removed / changed). Designed to fit
+ * inside the editor's history panel without a separate page.
+ */
+export function DiffSummary({ diff }: Props): React.JSX.Element {
+  const { metadata, blocks } = diff;
+  const metaKeys = Object.keys(metadata);
+  const totalChanges =
+    metaKeys.length + blocks.added.length + blocks.removed.length + blocks.changed.length;
+
+  if (totalChanges === 0) {
+    return (
+      <div
+        className="mt-3 rounded border border-gray-200 bg-white p-3 text-xs text-gray-500"
+        data-testid="diff-summary"
+      >
+        No changes between these revisions.
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="mt-3 rounded border border-gray-200 bg-white p-3 text-xs space-y-2"
+      data-testid="diff-summary"
+    >
+      {metaKeys.length > 0 && (
+        <div>
+          <div className="font-semibold text-gray-700">Metadata</div>
+          <ul className="ml-3 list-disc">
+            {metaKeys.map((key) => (
+              <li key={key}>
+                <span className="font-mono">{key}</span>:{' '}
+                <span className="text-red-600 line-through">
+                  {renderValue(metadata[key].before)}
+                </span>{' '}
+                → <span className="text-green-700">{renderValue(metadata[key].after)}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {blocks.added.length > 0 && (
+        <div>
+          <div className="font-semibold text-green-700">Added ({blocks.added.length})</div>
+          <ul className="ml-3 list-disc">
+            {blocks.added.map((b) => (
+              <li key={b.id}>
+                <span className="font-mono">{b.type ?? '?'}</span>{' '}
+                <span className="text-gray-500">({b.id})</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {blocks.removed.length > 0 && (
+        <div>
+          <div className="font-semibold text-red-700">Removed ({blocks.removed.length})</div>
+          <ul className="ml-3 list-disc">
+            {blocks.removed.map((b) => (
+              <li key={b.id}>
+                <span className="font-mono">{b.type ?? '?'}</span>{' '}
+                <span className="text-gray-500">({b.id})</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {blocks.changed.length > 0 && (
+        <div>
+          <div className="font-semibold text-amber-700">Changed ({blocks.changed.length})</div>
+          <ul className="ml-3 list-disc">
+            {blocks.changed.map((b) => (
+              <li key={b.id}>
+                <span className="font-mono">{b.type ?? '?'}</span>{' '}
+                <span className="text-gray-500">({b.id})</span>
+                {b.type_before && (
+                  <span className="text-gray-500">
+                    {' '}
+                    — was <span className="font-mono">{b.type_before}</span>
+                  </span>
+                )}
+                {b.fields.length > 0 && (
+                  <span className="text-gray-700">: {b.fields.join(', ')}</span>
+                )}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}

simple_module_pagebuilder-0.0.1/pagebuilder/components/ScheduledBadge.tsx

@@ -0,0 +1,34 @@
+import type { PageStatus } from '../utils/api';
+
+interface Props {
+  status: PageStatus;
+  publishAt: string | null;
+  unpublishAt: string | null;
+}
+
+/**
+ * Inline pill rendered next to ``StatusBadge`` when a page has a
+ * pending scheduler-driven flip. Drafts surface the upcoming publish
+ * time; published pages surface the upcoming unpublish time. Pages
+ * with no schedule for their current state render nothing — so callers
+ * can drop this in unconditionally.
+ */
+export function ScheduledBadge({ status, publishAt, unpublishAt }: Props) {
+  const target =
+    status === 'draft' && publishAt
+      ? { kind: 'publish' as const, at: publishAt }
+      : status === 'published' && unpublishAt
+        ? { kind: 'unpublish' as const, at: unpublishAt }
+        : null;
+  if (!target) return null;
+  const label = target.kind === 'publish' ? 'Scheduled to publish' : 'Scheduled to unpublish';
+  return (
+    <span
+      className="ml-2 inline-block text-xs font-medium px-2 py-1 rounded bg-blue-100 text-blue-800"
+      title={new Date(target.at).toLocaleString()}
+      data-testid="scheduled-badge"
+    >
+      {label} {new Date(target.at).toLocaleString()}
+    </span>
+  );
+}

simple_module_pagebuilder-0.0.1/pagebuilder/components/StatusBadge.tsx

@@ -0,0 +1,21 @@
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+
+import type { PageStatus } from '../utils/api';
+
+// The e2e suite asserts on this text verbatim — getByText('published',
+// { exact: true }) — so these labels stay lowercase and unabbreviated.
+const LABELS: Record<PageStatus, string> = {
+  published: 'published',
+  submitted_for_review: 'pending review',
+  draft: 'draft',
+};
+
+const VARIANTS: Record<PageStatus, 'default' | 'secondary' | 'outline'> = {
+  published: 'default',
+  submitted_for_review: 'secondary',
+  draft: 'outline',
+};
+
+export function StatusBadge({ status }: { status: PageStatus }) {
+  return <Badge variant={VARIANTS[status]}>{LABELS[status]}</Badge>;
+}

simple_module_pagebuilder-0.0.1/pagebuilder/components/blockRegistry.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  type AnyBlock,
+  declareBuiltInBlocks,
+  registeredBlocks,
+  registerPuckBlocks,
+  registryVersion,
+  resetBlockRegistry,
+} from './blockRegistry';
+
+const stub = { render: () => null } as unknown as AnyBlock;
+
+describe('block registry', () => {
+  beforeEach(() => {
+    declareBuiltInBlocks(['Heading', 'Text']);
+    resetBlockRegistry();
+  });
+
+  it('collects a registration', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(registeredBlocks().flatMap((r) => Object.keys(r.blocks))).toContain('Widget');
+  });
+
+  it('bumps the version on each registration', () => {
+    const before = registryVersion();
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(registryVersion()).toBeGreaterThan(before);
+  });
+
+  it('refuses to shadow a block pagebuilder already ships', () => {
+    // Block names are the `type` stored in page content, so a duplicate would
+    // make two blocks each render the other's saved data.
+    expect(() => registerPuckBlocks({ blocks: { Heading: stub } })).toThrow(/Heading/);
+  });
+
+  it('refuses to register the same name twice', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(() => registerPuckBlocks({ blocks: { Widget: stub } })).toThrow(/Widget/);
+  });
+
+  it('keeps the built-ins reserved across a reset', () => {
+    resetBlockRegistry();
+    expect(() => registerPuckBlocks({ blocks: { Text: stub } })).toThrow(/Text/);
+  });
+
+  it('carries the category through', () => {
+    registerPuckBlocks({ blocks: { Widget: stub }, category: { key: 'feeds', title: 'Feeds' } });
+    expect(registeredBlocks()[0].category).toEqual({ key: 'feeds', title: 'Feeds' });
+  });
+
+  it('defaults to page-only, not layout', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(registeredBlocks()[0].layout).toBeUndefined();
+  });
+});

simple_module_pagebuilder-0.0.1/pagebuilder/components/blockRegistry.ts

@@ -0,0 +1,80 @@
+/**
+ * Lets another module contribute Puck blocks without pagebuilder importing it.
+ *
+ * The framework's registries — menu, permissions, public routes, design packs —
+ * are all backend. This is the frontend equivalent, and the reason it exists is
+ * dependency direction: the news module knows about pagebuilder, so pagebuilder
+ * must not know about news.
+ *
+ * Registration is a side effect of importing a module's `puck-blocks.ts`. The
+ * host imports them all eagerly at app start (see `host/client_app/blocks.ts`),
+ * which is what guarantees the registry is populated before the first render.
+ */
+
+import type { ComponentConfig } from '@puckeditor/core';
+
+// Puck's ComponentConfig is invariant in its props, so a registry that holds
+// configs for unrelated prop shapes cannot be typed precisely. The runtime
+// shape is what matters here; each module keeps its own widget types honest.
+// biome-ignore lint/suspicious/noExplicitAny: a heterogeneous registry has no single prop type
+export type AnyBlock = ComponentConfig<any>;
+
+export interface BlockRegistration {
+  /** Block name → config. The name is the `type` stored in page content. */
+  blocks: Record<string, AnyBlock>;
+  /** Palette group. Blocks with no category land in Puck's "Other". */
+  category?: { key: string; title: string };
+  /** Also offer these in the site-layout palette. Default false. */
+  layout?: boolean;
+}
+
+let registrations: BlockRegistration[] = [];
+let takenNames = new Set<string>();
+let builtIns: readonly string[] = [];
+let version = 0;
+
+/**
+ * Declare the names pagebuilder itself ships, so a module cannot shadow one.
+ *
+ * Called once by puckConfig at import time rather than hardcoded here, which
+ * would be a second list to keep in sync.
+ */
+export function declareBuiltInBlocks(names: readonly string[]): void {
+  builtIns = names;
+  for (const name of names) takenNames.add(name);
+}
+
+export function registerPuckBlocks(registration: BlockRegistration): void {
+  for (const name of Object.keys(registration.blocks)) {
+    if (takenNames.has(name)) {
+      throw new Error(
+        `Puck block "${name}" is already registered. Block names are the \`type\` ` +
+          'stored in page content, so two blocks sharing one would each render ' +
+          "the other's saved data.",
+      );
+    }
+    takenNames.add(name);
+  }
+  registrations = [...registrations, registration];
+  version += 1;
+}
+
+export function registeredBlocks(): readonly BlockRegistration[] {
+  return registrations;
+}
+
+/**
+ * Bumped on every registration. The config builders memoise on this rather
+ * than caching unconditionally, so a registration that lands after the first
+ * read is not silently dropped.
+ */
+export function registryVersion(): number {
+  return version;
+}
+
+/** Test-only: drop every registration, keeping the declared built-ins. */
+export function resetBlockRegistry(): void {
+  registrations = [];
+  takenNames = new Set(builtIns);
+  version += 1;
+}