simple-module-news 0.0.2__py3-none-any.whl

news/components/ArticleRow.tsx

@@ -0,0 +1,78 @@
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { useState } from 'react';
+
+import type { ArticleRead } from '../utils/api';
+
+/** `2026-02-01T00:00:00` -> `2026-02-01`, which is what <input type=date> wants. */
+function toDateInput(iso: string | null): string {
+  return iso ? iso.slice(0, 10) : '';
+}
+
+export function ArticleRow({
+  article,
+  busy,
+  onSave,
+  onDetach,
+}: {
+  article: ArticleRead;
+  busy: boolean;
+  onSave: (id: number, category: string, publishedAt: string | null) => void;
+  onDetach: (id: number) => void;
+}) {
+  const [category, setCategory] = useState(article.category);
+  const [date, setDate] = useState(toDateInput(article.published_at));
+
+  const dirty = category !== article.category || date !== toDateInput(article.published_at);
+
+  return (
+    <tr className="border-b last:border-b-0">
+      <td className="py-2 pr-4">
+        <a href={`/pagebuilder/${article.page_id}`} className="font-medium hover:underline">
+          {article.title}
+        </a>
+        <div className="text-xs text-muted-foreground">{article.url}</div>
+      </td>
+      <td className="py-2 pr-4">
+        <Input
+          aria-label={`Category for ${article.title}`}
+          value={category}
+          disabled={busy}
+          onChange={(e) => setCategory(e.target.value)}
+          className="w-40"
+        />
+      </td>
+      <td className="py-2 pr-4">
+        <Input
+          type="date"
+          aria-label={`Date for ${article.title}`}
+          value={date}
+          disabled={busy}
+          onChange={(e) => setDate(e.target.value)}
+          className="w-40"
+        />
+      </td>
+      <td className="py-2 text-right whitespace-nowrap">
+        <Button
+          type="button"
+          size="sm"
+          // Enabled only when something changed, so the row never fires a
+          // no-op PUT that bumps updated_at for nothing.
+          disabled={busy || !dirty}
+          onClick={() => onSave(article.id, category, date ? `${date}T00:00:00Z` : null)}
+        >
+          Save
+        </Button>
+        <Button
+          type="button"
+          size="sm"
+          variant="ghost"
+          disabled={busy}
+          onClick={() => onDetach(article.id)}
+        >
+          Detach
+        </Button>
+      </td>
+    </tr>
+  );
+}

news/components/NewsFeed.tsx

@@ -0,0 +1,96 @@
+import type { ComponentConfig } from '@puckeditor/core';
+import {
+  type ArticleCardItem,
+  ArticleCardsGrid,
+} from '@simple-module-py/pagebuilder/pagebuilder/components/widgets/article-cards-render';
+import { useEffect, useState } from 'react';
+
+import { type ArticleRead, formatArticleDate, listArticles } from '../utils/api';
+
+export interface NewsFeedProps {
+  title: string;
+  category: string;
+  limit: number;
+  columns: '2' | '3' | '4';
+  viewAllLabel: string;
+  viewAllHref: string;
+}
+
+function toCard(article: ArticleRead): ArticleCardItem {
+  return {
+    imageUrl: article.cover_image_url,
+    imageAlt: '',
+    eyebrow: article.category,
+    date: formatArticleDate(article.published_at),
+    title: article.title,
+    body: article.excerpt,
+    // An article *is* a page, so this is the page's own public URL.
+    href: article.url,
+  };
+}
+
+export function NewsFeedRender({
+  title,
+  category,
+  limit,
+  columns,
+  viewAllLabel,
+  viewAllHref,
+}: NewsFeedProps) {
+  const [items, setItems] = useState<ArticleCardItem[] | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    listArticles({ limit, category, signal: controller.signal })
+      .then((response) => setItems(response.items.map(toCard)))
+      // An empty feed and a failed fetch look the same to a visitor on
+      // purpose: a broken API must not put an error box on a public page.
+      .catch(() => setItems([]));
+    return () => controller.abort();
+  }, [limit, category]);
+
+  // Render nothing at all until the first response, and nothing when there
+  // are no articles: a heading with an empty grid under it reads as a broken
+  // section. An empty fragment rather than null because Puck's render must
+  // return an Element.
+  if (items === null || items.length === 0) return <></>;
+
+  return (
+    <ArticleCardsGrid
+      title={title}
+      viewAllLabel={viewAllLabel}
+      viewAllHref={viewAllHref}
+      columns={columns}
+      items={items}
+    />
+  );
+}
+
+export const NewsFeedBlock: ComponentConfig<NewsFeedProps> = {
+  label: 'News feed (live articles)',
+  fields: {
+    title: { type: 'text', label: 'Heading' },
+    category: { type: 'text', label: 'Category filter (blank = all)' },
+    limit: { type: 'number', label: 'How many', min: 1, max: 12 },
+    columns: {
+      type: 'select',
+      label: 'Columns (desktop)',
+      options: [
+        { label: '2', value: '2' },
+        { label: '3', value: '3' },
+        { label: '4', value: '4' },
+      ],
+    },
+    viewAllLabel: { type: 'text', label: 'View-all link label' },
+    viewAllHref: { type: 'text', label: 'View-all link URL' },
+  },
+  defaultProps: {
+    title: 'Latest news',
+    category: '',
+    limit: 4,
+    columns: '4',
+    viewAllLabel: '',
+    viewAllHref: '',
+  },
+  render: NewsFeedRender,
+};

news/constants.py

@@ -0,0 +1,40 @@
+"""News module constants.
+
+Kept out of the call sites so no module name, route or permission appears as a
+bare literal — see scripts/check_hardcoded_strings.py.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+PACKAGE: Final = "news"
+
+ROUTE_PREFIX_API: Final = "/api/news"
+VIEW_PREFIX: Final = "/news"
+# Trailing slash: the list route is registered at "/" under VIEW_PREFIX, so
+# linking to the bare prefix costs a 307 round trip on every navigation.
+MENU_URL: Final = f"{VIEW_PREFIX}/"
+MENU_GROUP: Final = "Content"
+MENU_ICON: Final = "newspaper"
+
+# Modules this one depends on.
+_MODULE_PAGEBUILDER: Final = "PageBuilder"
+
+# Inertia page identifier, rendered as a literal at the view so the SM003/SM004
+# static-AST diagnostics can pair it with pages/NewsList.tsx.
+_PAGE_LIST: Final = "News/NewsList"
+
+PERM_VIEW: Final = "news.view"
+PERM_EDIT: Final = "news.edit"
+
+# Anonymous reads: the feed block runs on public pages, so listing has to work
+# without a session. Writes stay behind news.edit.
+PUBLIC_READ_PREFIXES: Final = (
+    f"{ROUTE_PREFIX_API}/articles",
+    f"{ROUTE_PREFIX_API}/categories",
+)
+
+MAX_CATEGORY_LEN: Final = 80
+DEFAULT_LIMIT: Final = 20
+MAX_LIMIT: Final = 100

news/contracts/schemas.py

@@ -0,0 +1,56 @@
+"""DTOs for the News module — the public surface."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from news.constants import MAX_CATEGORY_LEN
+
+
+class ArticleRead(BaseModel):
+    """An article, flattened from its sidecar row plus the page it belongs to."""
+
+    id: int
+    page_id: int
+    slug: str
+    title: str
+    excerpt: str = ""
+    cover_image_url: str = ""
+    category: str = ""
+    published_at: datetime | None = None
+    url: str
+    """Where the article actually serves.
+
+    An article *is* a page, so this is the page's own public URL rather than a
+    route this module owns — duplicating the public viewer would mean
+    duplicating its ETag, cache, CSP, SEO and site-layout handling.
+    """
+
+
+class ArticleListResponse(BaseModel):
+    items: list[ArticleRead]
+    total: int
+
+
+class CategoryCount(BaseModel):
+    category: str
+    count: int
+
+
+class CategoryListResponse(BaseModel):
+    items: list[CategoryCount]
+
+
+class ArticleCreate(BaseModel):
+    """Attach article metadata to an existing page."""
+
+    page_id: int
+    category: str = Field(default="", max_length=MAX_CATEGORY_LEN)
+    published_at: datetime | None = None
+
+
+class ArticleUpdate(BaseModel):
+    category: str | None = Field(default=None, max_length=MAX_CATEGORY_LEN)
+    published_at: datetime | None = None

news/endpoints/api.py

@@ -0,0 +1,158 @@
+"""REST API for News.
+
+Reads are anonymous: the feed block runs on public pages, so a visitor with no
+session has to be able to list articles. Writes require ``news.edit``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from simple_module_db import get_db
+from simple_module_hosting.permissions import (
+    WILDCARD,
+    RequiresPermission,
+    resolve_permissions,
+)
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from news import service
+from news.constants import DEFAULT_LIMIT, MAX_LIMIT, PERM_EDIT
+from news.contracts.schemas import (
+    ArticleCreate,
+    ArticleListResponse,
+    ArticleRead,
+    ArticleUpdate,
+    CategoryListResponse,
+)
+
+router = APIRouter()
+
+require_edit = Depends(RequiresPermission(PERM_EDIT))
+
+
+def _may_see_drafts(request: Request) -> bool:
+    """Only an editor sees articles whose page is still a draft.
+
+    Everyone else gets the published site, which is what the public feed block
+    must show.
+
+    Reads ``request.state.resolved_permissions`` — where the hosting middleware
+    and ``RequiresPermission`` both put the resolved set — rather than a
+    ``permissions`` attribute on the user. ``UserContext`` has no such
+    attribute, so testing it always yielded an empty list and no editor ever
+    saw a draft.
+
+    The fallback mirrors ``RequiresPermission.__call__``: these listings are
+    registered as public routes, so on an anonymous-readable GET nothing has
+    populated ``resolved_permissions`` by the time we are asked. ``WILDCARD`` is
+    checked because an administrator resolves to it rather than to a literal
+    ``news.edit``.
+    """
+    resolved = getattr(request.state, "resolved_permissions", None)
+    if resolved is None:
+        user = getattr(request.state, "user", None)
+        if user is None:
+            return False
+        sm = getattr(getattr(request.app, "state", None), "sm", None)
+        registry = getattr(sm, "permissions", None) if sm is not None else None
+        resolved = resolve_permissions(
+            getattr(user, "roles", None) or [],
+            role_map=registry.role_map if registry is not None else None,
+        )
+    return WILDCARD in resolved or PERM_EDIT in resolved
+
+
+async def _read_one_by_page(db: AsyncSession, page_id: int) -> ArticleRead:
+    """Re-read through the listing join so every response has one shape.
+
+    Drafts are included: an editor has just written this row and must see it
+    back whatever state its page is in.
+    """
+    article = await service.get_read_by_page(db, page_id, include_drafts=True)
+    if article is None:
+        # The page is the only source of slug and title, so without it there is
+        # nothing to return.
+        raise HTTPException(status_code=404, detail="Article's page not found.")
+    return article
+
+
+@router.get("/articles", response_model=ArticleListResponse)
+async def list_articles(
+    request: Request,
+    limit: int = Query(DEFAULT_LIMIT, ge=1, le=MAX_LIMIT),
+    offset: int = Query(0, ge=0),
+    category: str | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+) -> ArticleListResponse:
+    items, total = await service.list_articles(
+        db,
+        limit=limit,
+        offset=offset,
+        category=category,
+        include_drafts=_may_see_drafts(request),
+    )
+    return ArticleListResponse(items=items, total=total)
+
+
+@router.get("/categories", response_model=CategoryListResponse)
+async def list_categories(
+    request: Request, db: AsyncSession = Depends(get_db)
+) -> CategoryListResponse:
+    items = await service.list_categories(db, include_drafts=_may_see_drafts(request))
+    return CategoryListResponse(items=items)
+
+
+@router.post(
+    "/articles",
+    response_model=ArticleRead,
+    status_code=201,
+    dependencies=[require_edit],
+)
+async def attach_article(
+    body: ArticleCreate, db: AsyncSession = Depends(get_db)
+) -> ArticleRead:
+    """Make an existing page an article."""
+    if not await service.page_exists(db, body.page_id):
+        raise HTTPException(status_code=404, detail=f"Page {body.page_id} does not exist.")
+    if await service.get_by_page(db, body.page_id) is not None:
+        raise HTTPException(
+            status_code=409, detail=f"Page {body.page_id} is already an article."
+        )
+    await service.create(
+        db, page_id=body.page_id, category=body.category, published_at=body.published_at
+    )
+    return await _read_one_by_page(db, body.page_id)
+
+
+@router.put(
+    "/articles/{article_id}", response_model=ArticleRead, dependencies=[require_edit]
+)
+async def update_article(
+    article_id: int, body: ArticleUpdate, db: AsyncSession = Depends(get_db)
+) -> ArticleRead:
+    article = await service.get(db, article_id)
+    if article is None:
+        raise HTTPException(status_code=404, detail="Article not found.")
+    # A partial update: an omitted `published_at` leaves the date alone, while
+    # an explicit null undates the article. Only `model_fields_set` can tell
+    # those apart, and the distinction is the endpoint's to make.
+    await service.update(
+        db,
+        article,
+        category=body.category,
+        published_at=(
+            body.published_at
+            if "published_at" in body.model_fields_set
+            else service.UNSET
+        ),
+    )
+    return await _read_one_by_page(db, article.page_id)
+
+
+@router.delete("/articles/{article_id}", status_code=204, dependencies=[require_edit])
+async def detach_article(article_id: int, db: AsyncSession = Depends(get_db)) -> None:
+    """Detach the metadata. The page, and its body, stays."""
+    article = await service.get(db, article_id)
+    if article is None:
+        raise HTTPException(status_code=404, detail="Article not found.")
+    await service.delete(db, article)

news/endpoints/views.py

@@ -0,0 +1,28 @@
+"""Inertia view endpoints for News."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from news import constants
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(constants.PERM_VIEW))],
+)
+async def article_list(inertia: InertiaDep) -> InertiaResponse:
+    # The list is fetched client-side from /api/news/articles so an inline edit
+    # can refresh one row without a full Inertia round trip.
+    #
+    # The page name comes from the constant, matching pagebuilder and this
+    # repo's check_hardcoded_strings. The framework's own modules inline the
+    # literal instead, for the SM003/SM004 static-AST pairing — the two
+    # conventions disagree, and an in-repo module follows the in-repo linter.
+    return await inertia.render(constants._PAGE_LIST)

news/models.py

@@ -0,0 +1,70 @@
+"""SQLModel table for the news module.
+
+An article *is* a pagebuilder page — title, slug, body, approval workflow,
+revisions and SEO all live there, and it serves at ``/p/{slug}`` with the
+existing ETag, cache and CSP handling. This table adds only what a page has no
+concept of: the category it belongs to and the date it should be listed under.
+
+Keeping it a sidecar is what lets pagebuilder stay a generic CMS that knows
+nothing about news. The cost is that every listing is a join, and that
+``page_id`` carries no database foreign key — see the field for why.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import Column, DateTime, Integer
+from sqlmodel import Field
+
+Base = create_module_base("news")
+
+PAGE_TABLE = "pagebuilder_pages"
+
+
+class NewsArticle(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Article metadata attached to a pagebuilder page."""
+
+    __tablename__ = "news_articles"
+
+    id: int | None = Field(default=None, primary_key=True)
+
+    page_id: int = Field(
+        sa_column=Column(Integer, nullable=False, unique=True, index=True)
+    )
+    """The pagebuilder page holding the body, slug and workflow.
+
+    Deliberately *not* a database foreign key. ``create_module_base`` gives
+    every module its own ``MetaData``, so a cross-module ``ForeignKey`` cannot
+    resolve its target table and SQLAlchemy raises ``NoReferencedTableError``
+    when the mapper configures. The framework offers no cross-module FK and
+    pagebuilder publishes no page-deleted event, so there is nothing to hang a
+    cascade on either.
+
+    Two things make that safe. Every listing inner-joins the page, so an article
+    whose page was deleted stops appearing immediately rather than surfacing a
+    broken link. And an orphan is removed rather than left invisible — by the
+    ``PageDeleted`` subscription first, and by the startup sweep
+    (``service.reconcile_orphans``) when that event is missed.
+
+    The sweep is not belt-and-braces. An invisible orphan does not stay
+    invisible: SQLite reuses a deleted row's id, so the row re-attaches to
+    whatever page is created next and lists one article's category and date
+    against another article's page.
+    """
+
+    category: str = Field(default="", max_length=80, index=True)
+    """Free-text grouping. Empty means uncategorised, which still lists."""
+
+    published_at: datetime | None = Field(
+        default=None,
+        sa_column=Column(DateTime(timezone=True), nullable=True, index=True),
+    )
+    """The article's display date.
+
+    Deliberately not ``Page.publish_at``, which is the single-shot scheduling
+    field and is cleared on every flip — it would be empty for every article
+    published immediately.
+    """

news/module.py

@@ -0,0 +1,130 @@
+"""News — articles backed by page-builder pages.
+
+An article *is* a page: the body, slug, approval workflow, revisions and public
+URL all belong to ``pagebuilder``. This module adds only the metadata a page
+has no concept of — category and display date — plus the listing API and the
+feed block that renders it.
+
+There is therefore no public route here. An article serves at ``/p/{slug}``
+with the existing ETag, cache, CSP, SEO and site-layout handling; a second
+viewer would mean duplicating all of it.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+
+from fastapi import APIRouter, FastAPI
+from pagebuilder.contracts.events import PageDeleted
+from simple_module_core import ModuleBase, ModuleMeta
+from simple_module_core.events import EventBus
+from simple_module_core.menu import MenuItem, MenuRegistry
+from simple_module_core.permissions import PermissionRegistry
+from simple_module_core.public_routes import PublicRouteRegistry
+
+from news import constants
+
+logger = logging.getLogger(__name__)
+
+_VERSION = importlib.metadata.version("simple_module_news")
+
+
+class NewsModule(ModuleBase):
+    meta = ModuleMeta(
+        name="News",
+        route_prefix=constants.ROUTE_PREFIX_API,
+        view_prefix=constants.VIEW_PREFIX,
+        depends_on=[constants._MODULE_PAGEBUILDER],
+        version=_VERSION,
+        # The framework API version (1.0.0) is decoupled from the framework
+        # package version (0.0.x) — this range is correct as written.
+        requires_framework=">=1.0,<2.0",
+    )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from news.endpoints.api import router as api
+        from news.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            NewsModule.meta.name, [constants.PERM_VIEW, constants.PERM_EDIT]
+        )
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        # Roles stay empty: filtering is a plain intersection with no admin
+        # bypass, so a non-empty list hides the entry from everyone outside it.
+        registry.add(
+            MenuItem(
+                label="News",
+                url=constants.MENU_URL,
+                icon=constants.MENU_ICON,
+                group=constants.MENU_GROUP,
+            )
+        )
+
+    def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) -> None:
+        """Drop an article when its page is deleted.
+
+        This is not tidiness. There is no cross-module foreign key to cascade
+        from, and a leftover row does not merely dangle: SQLite reuses the
+        deleted page's id, so the article silently re-attaches to whatever page
+        is created next and the listing shows one article's title under
+        another's metadata.
+
+        This is the fast path, not a guarantee — the bus logs a handler failure
+        rather than raising it, and pagebuilder has already committed the page
+        deletion by the time we run. ``on_startup``'s sweep is what makes the
+        outcome eventual rather than merely likely.
+        """
+        if app is None:
+            return
+
+        async def _drop_article(event: PageDeleted) -> None:
+            from news import service
+
+            # Outside a request, so `get_db` is not managing this session and
+            # the commit is ours to make.
+            async with app.state.sm.db.session_factory() as db:
+                article = await service.get_by_page(db, event.page_id)
+                if article is not None:
+                    await service.delete(db, article)
+                    await db.commit()
+
+        bus.subscribe(PageDeleted, _drop_article)
+
+    async def on_startup(self, app: FastAPI) -> None:
+        """Sweep away articles whose page no longer exists.
+
+        Closes the window the ``PageDeleted`` subscription cannot: if that
+        handler ever fails, the row survives with nothing to retry it, and the
+        only trace is a log line. A restart is a cheap, natural boundary at
+        which to reconcile, and the sweep costs one indexed anti-join over a
+        table holding one row per article.
+
+        A non-zero count means an event was lost, so it is logged at warning —
+        the repair should be visible, not silent.
+        """
+        from news import service
+
+        async with app.state.sm.db.session_factory() as db:
+            dropped = await service.reconcile_orphans(db)
+            await db.commit()
+        if dropped:
+            logger.warning(
+                "Dropped %d orphaned news article(s) whose page no longer exists; "
+                "a PageDeleted event was missed.",
+                dropped,
+            )
+
+    def register_public_routes(self, registry: PublicRouteRegistry) -> None:
+        """Let the feed block list articles for an anonymous visitor.
+
+        Reads only, and by exact prefix: the same paths carry POST/PUT/DELETE,
+        which must stay behind ``news.edit``.
+        """
+        for prefix in constants.PUBLIC_READ_PREFIXES:
+            registry.add_prefix(prefix, methods={"GET"})

news/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/news",
+  "version": "0.0.2",
+  "private": true,
+  "description": "Frontend assets for the News 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": {}
+}

news/pages/.gitkeep

@@ -0,0 +1 @@
+# Keep this directory; TSX pages go here (e.g. Browse.tsx, Detail.tsx).