simple-module-branding 0.0.24__tar.gz

simple_module_branding-0.0.24/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/
+.qa/

simple_module_branding-0.0.24/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: simple_module_branding
+Version: 0.0.24
+Summary: Customisable application branding (name, logo, favicon, primary colour) for simple_module apps
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: branding,simple-module,theming,white-label
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.24
+Requires-Dist: simple-module-db==0.0.24
+Requires-Dist: simple-module-file-storage==0.0.24
+Requires-Dist: simple-module-hosting==0.0.24
+Requires-Dist: simple-module-settings==0.0.24
+Description-Content-Type: text/markdown
+
+# simple_module_branding
+
+Customisable application branding for [simple_module_python](https://github.com/antosubash/simple_module_python) apps.
+
+An administrator can set the **application name**, **logo**, **favicon** and
+**primary brand colour** from the admin UI (`/branding`), and those values are
+applied everywhere the framework would otherwise show the default identity —
+the sidebar/header logo and name, the browser tab title, the favicon, and the
+primary accent colour.
+
+## Screenshots
+
+The admin page at `/branding`, and the same app rebranded as "Acme Analytics"
+(custom logo + name + primary colour) across the sidebar and dashboard:
+
+| Admin page | Branding applied | Across the app |
+|---|---|---|
+| ![Branding admin](../../docs/branding/screenshots/01-branding-admin-default.png) | ![Branding applied](../../docs/branding/screenshots/02-branding-admin-applied.png) | ![Branded dashboard](../../docs/branding/screenshots/03-branded-dashboard.png) |
+
+## Install
+
+The module ships with the default app. To add it to a custom host, declare it
+as a dependency and let entry-point discovery pick it up:
+
+```toml
+# host/pyproject.toml
+dependencies = ["simple_module_branding"]
+
+[tool.uv.sources]
+simple_module_branding = { workspace = true }
+```
+
+Then `uv sync --all-packages`. It requires the `Settings` and `FileStorage`
+modules to be installed too.
+
+## Usage
+
+1. Sign in as an admin and open **Branding** in the sidebar (or visit
+   `/branding`).
+2. Set the application name, pick a primary colour, and upload a logo and/or
+   favicon. Changes apply immediately across the app.
+
+Programmatically, the current branding is available on every page through the
+`branding` Inertia shared prop (`appName`, `primaryColor`, `logoUrl`,
+`faviconUrl`).
+
+## How it works
+
+- **Storage.** The four values are persisted via the `settings` module's store
+  (SYSTEM scope) — there is no branding database table. They hydrate into
+  `app.state.branding.settings` at boot and hot-swap on save.
+- **Images.** Logo and favicon uploads are stored through the `file_storage`
+  module (referenced by UUID) and served from its download endpoint.
+- **Delivery.** A registered Inertia shared-props provider injects a `branding`
+  block into every page's shared props (authenticated *and* guest), which the
+  frontend reads for the name, logo, favicon and colour.
+
+## Permissions
+
+- `branding.view` — view the branding admin page.
+- `branding.manage` — change branding (name, colour, logo, favicon).
+
+## Dependencies
+
+Depends on the `Settings` and `FileStorage` modules.
+
+## Notes
+
+- Branding is currently SYSTEM-scoped (one identity per deployment). The
+  settings store already supports tenant/user scope, leaving room for
+  per-tenant branding later.
+- The primary colour overrides the `--primary` / `--sidebar-primary` CSS
+  variables from a single hex; the full OKLCH colour scale is not regenerated.
+
+License: MIT

simple_module_branding-0.0.24/README.md

@@ -0,0 +1,75 @@
+# simple_module_branding
+
+Customisable application branding for [simple_module_python](https://github.com/antosubash/simple_module_python) apps.
+
+An administrator can set the **application name**, **logo**, **favicon** and
+**primary brand colour** from the admin UI (`/branding`), and those values are
+applied everywhere the framework would otherwise show the default identity —
+the sidebar/header logo and name, the browser tab title, the favicon, and the
+primary accent colour.
+
+## Screenshots
+
+The admin page at `/branding`, and the same app rebranded as "Acme Analytics"
+(custom logo + name + primary colour) across the sidebar and dashboard:
+
+| Admin page | Branding applied | Across the app |
+|---|---|---|
+| ![Branding admin](../../docs/branding/screenshots/01-branding-admin-default.png) | ![Branding applied](../../docs/branding/screenshots/02-branding-admin-applied.png) | ![Branded dashboard](../../docs/branding/screenshots/03-branded-dashboard.png) |
+
+## Install
+
+The module ships with the default app. To add it to a custom host, declare it
+as a dependency and let entry-point discovery pick it up:
+
+```toml
+# host/pyproject.toml
+dependencies = ["simple_module_branding"]
+
+[tool.uv.sources]
+simple_module_branding = { workspace = true }
+```
+
+Then `uv sync --all-packages`. It requires the `Settings` and `FileStorage`
+modules to be installed too.
+
+## Usage
+
+1. Sign in as an admin and open **Branding** in the sidebar (or visit
+   `/branding`).
+2. Set the application name, pick a primary colour, and upload a logo and/or
+   favicon. Changes apply immediately across the app.
+
+Programmatically, the current branding is available on every page through the
+`branding` Inertia shared prop (`appName`, `primaryColor`, `logoUrl`,
+`faviconUrl`).
+
+## How it works
+
+- **Storage.** The four values are persisted via the `settings` module's store
+  (SYSTEM scope) — there is no branding database table. They hydrate into
+  `app.state.branding.settings` at boot and hot-swap on save.
+- **Images.** Logo and favicon uploads are stored through the `file_storage`
+  module (referenced by UUID) and served from its download endpoint.
+- **Delivery.** A registered Inertia shared-props provider injects a `branding`
+  block into every page's shared props (authenticated *and* guest), which the
+  frontend reads for the name, logo, favicon and colour.
+
+## Permissions
+
+- `branding.view` — view the branding admin page.
+- `branding.manage` — change branding (name, colour, logo, favicon).
+
+## Dependencies
+
+Depends on the `Settings` and `FileStorage` modules.
+
+## Notes
+
+- Branding is currently SYSTEM-scoped (one identity per deployment). The
+  settings store already supports tenant/user scope, leaving room for
+  per-tenant branding later.
+- The primary colour overrides the `--primary` / `--sidebar-primary` CSS
+  variables from a single hex; the full OKLCH colour scale is not regenerated.
+
+License: MIT

simple_module_branding-0.0.24/branding/__init__.py

@@ -0,0 +1 @@
+"""Branding module."""

simple_module_branding-0.0.24/branding/constants.py

@@ -0,0 +1,65 @@
+"""Branding module constants."""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from file_storage.constants import PATH_FILE_DOWNLOAD, ROUTE_PREFIX_API
+
+PACKAGE: Final = "branding"
+
+# Modules this one depends on (kept as constants so the depends_on list doesn't
+# carry bare string literals — see scripts/check_hardcoded_strings.py).
+_MODULE_SETTINGS: Final = "Settings"
+_MODULE_FILE_STORAGE: Final = "FileStorage"
+
+# Inertia page identifier. The view endpoint renders this as a literal (so the
+# SM003/SM004 static-AST diagnostics can pair it with pages/Manage.tsx); a test
+# asserts the literal matches this constant.
+_PAGE_MANAGE: Final = "Branding/Manage"
+
+PERM_VIEW: Final = "branding.view"
+PERM_MANAGE: Final = "branding.manage"
+
+# A #rrggbb hex colour (single source of truth for both the settings and the
+# update-DTO validators).
+HEX_COLOR_RE: Final = re.compile(r"^#[0-9a-fA-F]{6}$")
+MAX_APP_NAME_LEN: Final = 60
+
+# Image upload guard-rails (enforced before handing the file to file_storage).
+MAX_IMAGE_BYTES: Final = 2 * 1024 * 1024  # 2 MB
+ALLOWED_IMAGE_TYPES: Final = frozenset(
+    {
+        "image/png",
+        "image/jpeg",
+        "image/svg+xml",
+        "image/webp",
+        "image/gif",
+        "image/x-icon",
+        "image/vnd.microsoft.icon",
+    }
+)
+
+# file_storage download URL, derived from file_storage's own route constants
+# (branding depends on FileStorage) so it tracks any route change. The
+# ``{file_id}`` placeholder is filled per stored-file id.
+FILE_DOWNLOAD_URL: Final = ROUTE_PREFIX_API + PATH_FILE_DOWNLOAD
+
+
+def clean_app_name(value: str) -> str:
+    """Normalise + validate an app name (shared by the settings + update DTO).
+
+    The name is surfaced in HTML titles and—critically—email ``Subject``
+    headers, so control characters (notably CR/LF) must be rejected: an
+    embedded newline would otherwise pass a bare ``strip()`` and then raise
+    when set as a header, breaking every transactional email.
+    """
+    cleaned = value.strip()
+    if not cleaned:
+        raise ValueError("app_name must not be blank")
+    if len(cleaned) > MAX_APP_NAME_LEN:
+        raise ValueError(f"app_name must be at most {MAX_APP_NAME_LEN} characters")
+    if any(ord(ch) < 0x20 for ch in cleaned):
+        raise ValueError("app_name must not contain control characters")
+    return cleaned

simple_module_branding-0.0.24/branding/contracts/__init__.py

@@ -0,0 +1,8 @@
+"""Branding contracts — public interface for other modules."""
+
+from branding.contracts.schemas import BrandingOut, BrandingUpdate
+
+__all__ = [
+    "BrandingOut",
+    "BrandingUpdate",
+]

simple_module_branding-0.0.24/branding/contracts/schemas.py

@@ -0,0 +1,43 @@
+"""SQLModel DTOs for the Branding module — the public surface."""
+
+from __future__ import annotations
+
+from pydantic import field_validator
+from sqlmodel import Field, SQLModel
+
+from branding.constants import HEX_COLOR_RE, MAX_APP_NAME_LEN, clean_app_name
+
+
+class BrandingOut(SQLModel):
+    """Current branding, with logo/favicon resolved to download URLs."""
+
+    app_name: str
+    primary_color: str = ""
+    logo_url: str | None = None
+    favicon_url: str | None = None
+
+
+class BrandingUpdate(SQLModel):
+    """Editable text fields. Logo/favicon are set via dedicated upload routes."""
+
+    app_name: str | None = Field(default=None, max_length=MAX_APP_NAME_LEN)
+    primary_color: str | None = Field(default=None)
+
+    @field_validator("app_name")
+    @classmethod
+    def _non_empty_name(cls, value: str | None) -> str | None:
+        # Validate here so bad input surfaces as a 422 rather than a 500 when
+        # BrandingSettings re-validates (blank, too long, or control chars —
+        # the last would otherwise break email Subject headers downstream).
+        if value is None:
+            return None
+        return clean_app_name(value)
+
+    @field_validator("primary_color")
+    @classmethod
+    def _valid_hex(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        if value != "" and not HEX_COLOR_RE.match(value):
+            raise ValueError("primary_color must be a #rrggbb hex string or empty")
+        return value.lower()

simple_module_branding-0.0.24/branding/deps.py

@@ -0,0 +1,21 @@
+"""FastAPI dependencies for the Branding module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from branding.service import BrandingService
+
+
+async def get_branding_service(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> BrandingService:
+    return BrandingService(request.app, db)
+
+
+BrandingServiceDep = Annotated[BrandingService, Depends(get_branding_service)]

simple_module_branding-0.0.24/branding/endpoints/api.py

@@ -0,0 +1,74 @@
+"""REST API endpoints for Branding (JSON). All writes require branding.manage."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile
+from file_storage.deps import get_file_storage_service
+from file_storage.service import FileStorageService
+from simple_module_hosting.permissions import RequiresPermission
+
+from branding import constants
+from branding.contracts.schemas import BrandingOut, BrandingUpdate
+from branding.deps import BrandingServiceDep
+
+router = APIRouter()
+
+_MANAGE = Depends(RequiresPermission(constants.PERM_MANAGE))
+
+
+def _validate_image(file: UploadFile) -> None:
+    if file.content_type not in constants.ALLOWED_IMAGE_TYPES:
+        raise HTTPException(
+            status_code=415,
+            detail=f"Unsupported image type {file.content_type!r}.",
+        )
+    if file.size is not None and file.size > constants.MAX_IMAGE_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Image exceeds {constants.MAX_IMAGE_BYTES} bytes.",
+        )
+
+
+@router.get("/", response_model=BrandingOut, dependencies=[_MANAGE])
+async def get_branding(service: BrandingServiceDep) -> BrandingOut:
+    return service.current()
+
+
+@router.put("/", response_model=BrandingOut, dependencies=[_MANAGE])
+async def update_branding(data: BrandingUpdate, service: BrandingServiceDep) -> BrandingOut:
+    changes = {k: v for k, v in data.model_dump(exclude_unset=True).items() if v is not None}
+    if not changes:
+        return service.current()
+    return await service.apply(changes)
+
+
+@router.post("/logo", response_model=BrandingOut, dependencies=[_MANAGE])
+async def upload_logo(
+    service: BrandingServiceDep,
+    file: UploadFile,
+    storage: FileStorageService = Depends(get_file_storage_service),
+) -> BrandingOut:
+    _validate_image(file)
+    stored = await storage.upload(file)
+    return await service.set_logo(str(stored.id))
+
+
+@router.post("/favicon", response_model=BrandingOut, dependencies=[_MANAGE])
+async def upload_favicon(
+    service: BrandingServiceDep,
+    file: UploadFile,
+    storage: FileStorageService = Depends(get_file_storage_service),
+) -> BrandingOut:
+    _validate_image(file)
+    stored = await storage.upload(file)
+    return await service.set_favicon(str(stored.id))
+
+
+@router.delete("/logo", response_model=BrandingOut, dependencies=[_MANAGE])
+async def clear_logo(service: BrandingServiceDep) -> BrandingOut:
+    return await service.clear_logo()
+
+
+@router.delete("/favicon", response_model=BrandingOut, dependencies=[_MANAGE])
+async def clear_favicon(service: BrandingServiceDep) -> BrandingOut:
+    return await service.clear_favicon()

simple_module_branding-0.0.24/branding/endpoints/views.py

@@ -0,0 +1,29 @@
+"""Inertia view endpoints for Branding."""
+
+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 branding import constants
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(constants.PERM_VIEW))],
+)
+async def manage(inertia: InertiaDep) -> InertiaResponse:
+    # Current branding is delivered through the shared ``branding`` prop
+    # (the branding shared-props provider), so no page props are needed.
+    # The page name is inlined as a literal (rather than constants._PAGE_MANAGE)
+    # so the SM003/SM004 diagnostics — which do static AST analysis and can't
+    # resolve attribute access — pair this call with pages/Manage.tsx. A unit
+    # test asserts the literal matches constants._PAGE_MANAGE.
+    return await inertia.render(
+        "Branding/Manage",
+    )

simple_module_branding-0.0.24/branding/locales/en.json

@@ -0,0 +1,23 @@
+{
+  "manage": {
+    "title": "Branding",
+    "description": "Customise your application's name, logo, favicon and primary colour.",
+    "app_name_label": "Application name",
+    "app_name_help": "Shown in the sidebar, the browser tab and on sign-in.",
+    "primary_color_label": "Primary colour",
+    "primary_color_help": "Accent colour used across buttons and highlights. Leave blank for the default.",
+    "logo_label": "Logo",
+    "logo_help": "Square PNG or SVG works best. Replaces the default badge in the sidebar.",
+    "favicon_label": "Favicon",
+    "favicon_help": "Small icon shown in the browser tab. PNG, SVG or ICO.",
+    "upload_button": "Upload",
+    "replace_button": "Replace",
+    "remove_button": "Remove",
+    "save_button": "Save changes",
+    "saving": "Saving…",
+    "preview_title": "Preview",
+    "saved_toast": "Branding updated",
+    "error_toast": "Could not update branding",
+    "upload_error_toast": "Could not upload image"
+  }
+}

simple_module_branding-0.0.24/branding/module.py

@@ -0,0 +1,77 @@
+"""Branding module definition.
+
+Lets an administrator customise the app name, logo, favicon and primary colour.
+Values persist in the shared settings store (no branding table) and reach every
+page through a registered Inertia shared-props provider.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from branding import constants
+
+
+class BrandingModule(ModuleBase):
+    meta = ModuleMeta(
+        name="Branding",
+        route_prefix="/api/branding",
+        view_prefix="/branding",
+        depends_on=[constants._MODULE_SETTINGS, constants._MODULE_FILE_STORAGE],
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from settings.registration import register_module_settings
+
+        from branding.services import BrandingServices
+        from branding.settings import BrandingSettings
+
+        register_module_settings(
+            app,
+            constants.PACKAGE,
+            BrandingSettings,
+            lambda s: BrandingServices(settings=s),
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            "Branding",
+            [constants.PERM_VIEW, constants.PERM_MANAGE],
+        )
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label="Branding",
+                url="/branding",
+                icon="palette",
+                order=115,
+                section=MenuSection.SIDEBAR,
+                group="Administration",
+                roles=["admin"],
+            )
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from branding.endpoints.api import router as api
+        from branding.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    async def on_startup(self, app: FastAPI) -> None:
+        from simple_module_hosting.shared_props import register_inertia_shared_provider
+
+        from branding.shared_props import branding_shared_props
+
+        register_inertia_shared_provider(app, branding_shared_props)
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {constants.PACKAGE: base}

simple_module_branding-0.0.24/branding/pages/Manage.tsx

@@ -0,0 +1,261 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@simple-module-py/ui/components/ui/card';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import type { SharedProps } from '@simple-module-py/ui/types';
+import { type ChangeEvent, useRef, useState } from 'react';
+import { toast } from 'sonner';
+
+const DEFAULT_SWATCH = '#10b981';
+type ImageKind = 'logo' | 'favicon';
+
+async function readError(res: Response): Promise<string> {
+  try {
+    const body = await res.json();
+    return typeof body?.detail === 'string' ? body.detail : res.statusText;
+  } catch {
+    return res.statusText;
+  }
+}
+
+function ImageField({
+  label,
+  help,
+  url,
+  onUpload,
+  onRemove,
+  disabled,
+}: {
+  label: string;
+  help: string;
+  url: string | null;
+  onUpload: (file: File) => void;
+  onRemove: () => void;
+  disabled: boolean;
+}) {
+  const { t } = useT();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <div className="space-y-2">
+      <Label>{label}</Label>
+      <div className="flex items-center gap-4">
+        <div className="flex h-16 w-16 items-center justify-center overflow-hidden rounded-lg border bg-muted">
+          {url ? (
+            <img src={url} alt={label} className="h-full w-full object-contain" />
+          ) : (
+            <span className="text-xs text-muted-foreground">—</span>
+          )}
+        </div>
+        <div className="flex gap-2">
+          <input
+            ref={inputRef}
+            type="file"
+            accept="image/*"
+            className="hidden"
+            onChange={(e: ChangeEvent<HTMLInputElement>) => {
+              const file = e.target.files?.[0];
+              if (file) onUpload(file);
+              e.target.value = '';
+            }}
+          />
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            disabled={disabled}
+            onClick={() => inputRef.current?.click()}
+          >
+            {url ? t(keys.branding.manage.replace_button) : t(keys.branding.manage.upload_button)}
+          </Button>
+          {url && (
+            <Button type="button" variant="ghost" size="sm" disabled={disabled} onClick={onRemove}>
+              {t(keys.branding.manage.remove_button)}
+            </Button>
+          )}
+        </div>
+      </div>
+      <p className="text-xs text-muted-foreground">{help}</p>
+    </div>
+  );
+}
+
+function Manage() {
+  const { t } = useT();
+  const { auth, branding } = usePage<{ props: SharedProps }>().props as unknown as SharedProps;
+  const canManage = auth?.permissions?.includes('branding.manage');
+
+  const [appName, setAppName] = useState(branding?.appName ?? '');
+  const [color, setColor] = useState(branding?.primaryColor ?? '');
+  const [busy, setBusy] = useState(false);
+
+  async function run(work: () => Promise<Response>, errorMsg: string) {
+    setBusy(true);
+    try {
+      const res = await work();
+      if (!res.ok) throw new Error(await readError(res));
+      toast.success(t(keys.branding.manage.saved_toast));
+      router.reload();
+    } catch (err) {
+      toast.error(`${errorMsg}: ${(err as Error).message}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const saveText = () =>
+    run(
+      () =>
+        fetch('/api/branding/', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ app_name: appName, primary_color: color }),
+        }),
+      t(keys.branding.manage.error_toast),
+    );
+
+  const uploadImage = (kind: ImageKind, file: File) => {
+    const form = new FormData();
+    form.append('file', file);
+    return run(
+      () => fetch(`/api/branding/${kind}`, { method: 'POST', body: form }),
+      t(keys.branding.manage.upload_error_toast),
+    );
+  };
+
+  const removeImage = (kind: ImageKind) =>
+    run(
+      () => fetch(`/api/branding/${kind}`, { method: 'DELETE' }),
+      t(keys.branding.manage.error_toast),
+    );
+
+  return (
+    <>
+      <Head title={t(keys.branding.manage.title)} />
+      <PageShell
+        title={t(keys.branding.manage.title)}
+        description={t(keys.branding.manage.description)}
+      >
+        <div className="grid gap-6 lg:grid-cols-3">
+          <Card className="lg:col-span-2">
+            <CardHeader>
+              <CardTitle>{t(keys.branding.manage.title)}</CardTitle>
+              <CardDescription>{t(keys.branding.manage.description)}</CardDescription>
+            </CardHeader>
+            <CardContent className="space-y-6">
+              <div className="space-y-2">
+                <Label htmlFor="app_name">{t(keys.branding.manage.app_name_label)}</Label>
+                <Input
+                  id="app_name"
+                  value={appName}
+                  maxLength={60}
+                  disabled={!canManage || busy}
+                  onChange={(e) => setAppName(e.target.value)}
+                />
+                <p className="text-xs text-muted-foreground">
+                  {t(keys.branding.manage.app_name_help)}
+                </p>
+              </div>
+
+              <div className="space-y-2">
+                <Label htmlFor="primary_color">{t(keys.branding.manage.primary_color_label)}</Label>
+                <div className="flex items-center gap-3">
+                  <input
+                    type="color"
+                    aria-label={t(keys.branding.manage.primary_color_label)}
+                    value={color || DEFAULT_SWATCH}
+                    disabled={!canManage || busy}
+                    onChange={(e) => setColor(e.target.value)}
+                    className="h-9 w-12 cursor-pointer rounded border bg-transparent"
+                  />
+                  <Input
+                    id="primary_color"
+                    value={color}
+                    placeholder={DEFAULT_SWATCH}
+                    disabled={!canManage || busy}
+                    onChange={(e) => setColor(e.target.value)}
+                    className="max-w-40 font-mono"
+                  />
+                  {color && (
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      disabled={busy}
+                      onClick={() => setColor('')}
+                    >
+                      {t(keys.branding.manage.remove_button)}
+                    </Button>
+                  )}
+                </div>
+                <p className="text-xs text-muted-foreground">
+                  {t(keys.branding.manage.primary_color_help)}
+                </p>
+              </div>
+
+              <ImageField
+                label={t(keys.branding.manage.logo_label)}
+                help={t(keys.branding.manage.logo_help)}
+                url={branding?.logoUrl ?? null}
+                onUpload={(file) => uploadImage('logo', file)}
+                onRemove={() => removeImage('logo')}
+                disabled={!canManage || busy}
+              />
+              <ImageField
+                label={t(keys.branding.manage.favicon_label)}
+                help={t(keys.branding.manage.favicon_help)}
+                url={branding?.faviconUrl ?? null}
+                onUpload={(file) => uploadImage('favicon', file)}
+                onRemove={() => removeImage('favicon')}
+                disabled={!canManage || busy}
+              />
+
+              <Button type="button" disabled={!canManage || busy} onClick={saveText}>
+                {busy ? t(keys.branding.manage.saving) : t(keys.branding.manage.save_button)}
+              </Button>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>{t(keys.branding.manage.preview_title)}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <div className="flex items-center gap-3 rounded-lg border p-4">
+                <div
+                  className="flex h-10 w-10 items-center justify-center overflow-hidden rounded-lg text-white"
+                  style={{ backgroundColor: color || DEFAULT_SWATCH }}
+                >
+                  {branding?.logoUrl ? (
+                    <img
+                      src={branding.logoUrl}
+                      alt={appName}
+                      className="h-full w-full object-contain"
+                    />
+                  ) : (
+                    <span className="font-bold">{(appName.trim()[0] ?? 'S').toUpperCase()}</span>
+                  )}
+                </div>
+                <span className="font-semibold">{appName || 'SimpleModule'}</span>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      </PageShell>
+    </>
+  );
+}
+
+Manage.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+
+export default Manage;

simple_module_branding-0.0.24/branding/service.py

@@ -0,0 +1,61 @@
+"""Branding service — reads current branding and applies admin changes.
+
+There is no branding DB table: values live in the shared settings store. Writes
+go through ``settings.reload.apply_changes_and_reload`` which validates against
+``BrandingSettings``, persists (SYSTEM scope), hot-swaps ``app.state.branding``
+and publishes ``SettingsReloaded``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from branding.constants import PACKAGE
+from branding.contracts.schemas import BrandingOut
+from branding.shared_props import file_url
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class BrandingService:
+    """Read/update the application's branding."""
+
+    def __init__(self, app: FastAPI, db: AsyncSession) -> None:
+        self.app = app
+        self.db = db
+
+    def current(self) -> BrandingOut:
+        settings = self.app.state.branding.settings
+        return BrandingOut(
+            app_name=settings.app_name,
+            primary_color=settings.primary_color,
+            logo_url=file_url(settings.logo_file_id),
+            favicon_url=file_url(settings.favicon_file_id),
+        )
+
+    async def apply(self, changes: dict[str, Any]) -> BrandingOut:
+        """Persist and hot-swap the given field changes, then return current."""
+        # Plugin→plugin imports (settings is a declared dependency); kept local
+        # so import order during discovery stays tolerant.
+        from settings.reload import apply_changes_and_reload
+        from settings.service import SettingService
+        from settings.store import SettingsStore
+
+        store = SettingsStore(SettingService(self.db))
+        bus = self.app.state.sm.event_bus
+        await apply_changes_and_reload(self.app, bus, store, package=PACKAGE, changes=changes)
+        return self.current()
+
+    async def set_logo(self, file_id: str) -> BrandingOut:
+        return await self.apply({"logo_file_id": file_id})
+
+    async def set_favicon(self, file_id: str) -> BrandingOut:
+        return await self.apply({"favicon_file_id": file_id})
+
+    async def clear_logo(self) -> BrandingOut:
+        return await self.apply({"logo_file_id": ""})
+
+    async def clear_favicon(self) -> BrandingOut:
+        return await self.apply({"favicon_file_id": ""})

simple_module_branding-0.0.24/branding/services.py

@@ -0,0 +1,20 @@
+"""Module-scoped state container.
+
+Stored as ``app.state.branding`` by
+:meth:`BrandingModule.register_settings` (via ``register_module_settings``).
+``settings`` is hot-swapped by ``settings.reload.apply_changes_and_reload`` when
+an admin saves changes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from branding.settings import BrandingSettings
+
+
+@dataclass
+class BrandingServices:
+    """Branding module singletons."""
+
+    settings: BrandingSettings

simple_module_branding-0.0.24/branding/settings.py

@@ -0,0 +1,42 @@
+"""Branding module settings — DB-backed via ``register_module_settings``.
+
+The four values an administrator can customise (app name, logo, favicon,
+primary colour) are stored in the shared settings store at SYSTEM scope,
+hydrated into ``app.state.branding.settings`` at boot, and hot-swapped on save
+through ``settings.reload.apply_changes_and_reload``.
+
+Logo/favicon are stored as ``file_storage`` UUIDs (empty string = unset); the
+frontend derives a download URL from the id.
+"""
+
+from __future__ import annotations
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from branding.constants import HEX_COLOR_RE, clean_app_name
+
+DEFAULT_APP_NAME = "SimpleModule"
+
+
+class BrandingSettings(BaseSettings):
+    """Customisable application identity."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    app_name: str = DEFAULT_APP_NAME
+    primary_color: str = ""  # "" = use the theme default; otherwise "#rrggbb"
+    logo_file_id: str = ""  # file_storage UUID, "" = no custom logo
+    favicon_file_id: str = ""  # file_storage UUID, "" = no custom favicon
+
+    @field_validator("app_name")
+    @classmethod
+    def _non_empty_name(cls, value: str) -> str:
+        return clean_app_name(value)
+
+    @field_validator("primary_color")
+    @classmethod
+    def _valid_hex(cls, value: str) -> str:
+        if value and not HEX_COLOR_RE.match(value):
+            raise ValueError("primary_color must be a #rrggbb hex string or empty")
+        return value.lower()

simple_module_branding-0.0.24/branding/shared_props.py

@@ -0,0 +1,44 @@
+"""Branding shared-props provider.
+
+Registered on ``app.state.inertia_shared_providers`` so every Inertia page
+(authenticated *and* guest) receives a ``branding`` block in its shared props.
+The frontend uses it for the app name, logo, favicon and primary colour.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from branding.constants import FILE_DOWNLOAD_URL
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from branding.settings import BrandingSettings
+
+
+def file_url(file_id: str) -> str | None:
+    """Build the file_storage download URL for a stored file id (or None)."""
+    return FILE_DOWNLOAD_URL.format(file_id=file_id) if file_id else None
+
+
+def branding_payload(settings: BrandingSettings) -> dict:
+    """The camelCase branding block shared with the frontend."""
+    return {
+        "appName": settings.app_name,
+        "primaryColor": settings.primary_color or None,
+        "logoUrl": file_url(settings.logo_file_id),
+        "faviconUrl": file_url(settings.favicon_file_id),
+    }
+
+
+def branding_shared_props(request: Request) -> dict:
+    """Provider: emit ``{"branding": {...}}`` from the live module settings.
+
+    Defensive — returns ``{}`` if the branding state isn't mounted yet, so a
+    half-booted app never errors a page render.
+    """
+    services = getattr(request.app.state, "branding", None)
+    if services is None:
+        return {}
+    return {"branding": branding_payload(services.settings)}

simple_module_branding-0.0.24/package.json

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

simple_module_branding-0.0.24/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "simple_module_branding"
+version = "0.0.24"
+description = "Customisable application branding (name, logo, favicon, primary colour) for simple_module apps"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "branding", "theming", "white-label"]
+requires-python = ">=3.12"
+dependencies = [
+    "simple_module_core==0.0.24",
+    "simple_module_db==0.0.24",
+    "simple_module_hosting==0.0.24",
+    "simple_module_settings==0.0.24",
+    "simple_module_file_storage==0.0.24",
+]
+
+[project.urls]
+Repository = "https://github.com/antosubash/simple_module_python"
+
+[project.entry-points.simple_module]
+branding = "branding.module:BrandingModule"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["branding"]
+
+# Ship the module-root package.json inside the wheel so the host can
+# discover JS deps via importlib.resources after a pip install.
+[tool.hatch.build.targets.wheel.force-include]
+"package.json" = "branding/package.json"
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_db = { workspace = true }
+simple_module_hosting = { workspace = true }
+simple_module_settings = { workspace = true }
+simple_module_file_storage = { workspace = true }

simple_module_branding-0.0.24/tests/test_branding.py

@@ -0,0 +1,203 @@
+"""Tests for the Branding module."""
+
+from __future__ import annotations
+
+import uuid
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from branding.settings import BrandingSettings
+from branding.shared_props import branding_payload, branding_shared_props
+
+# ── Unit: settings validation ──────────────────────────────────────────
+
+
+def test_settings_defaults() -> None:
+    s = BrandingSettings()
+    assert s.app_name == "SimpleModule"
+    assert s.primary_color == ""
+    assert s.logo_file_id == ""
+    assert s.favicon_file_id == ""
+
+
+def test_settings_app_name_trimmed_and_required() -> None:
+    assert BrandingSettings(app_name="  Acme  ").app_name == "Acme"
+    with pytest.raises(ValueError):
+        BrandingSettings(app_name="   ")
+    with pytest.raises(ValueError):
+        BrandingSettings(app_name="x" * 61)
+
+
+def test_settings_app_name_rejects_control_chars() -> None:
+    # A CR/LF in the name would break email Subject headers downstream — it must
+    # be rejected at the source rather than passing a bare strip().
+    for bad in ("Acme\nCorp", "Acme\rCorp", "Acme\tInc"):
+        with pytest.raises(ValueError):
+            BrandingSettings(app_name=bad)
+
+
+def test_settings_primary_color_validation() -> None:
+    assert BrandingSettings(primary_color="#1A7DD1").primary_color == "#1a7dd1"
+    assert BrandingSettings(primary_color="").primary_color == ""
+    with pytest.raises(ValueError):
+        BrandingSettings(primary_color="red")
+    with pytest.raises(ValueError):
+        BrandingSettings(primary_color="#fff")
+
+
+# ── Unit: shared-props payload + provider ──────────────────────────────
+
+
+def test_branding_payload_unset() -> None:
+    payload = branding_payload(BrandingSettings())
+    assert payload == {
+        "appName": "SimpleModule",
+        "primaryColor": None,
+        "logoUrl": None,
+        "faviconUrl": None,
+    }
+
+
+def test_branding_payload_set() -> None:
+    s = BrandingSettings(
+        app_name="Acme",
+        primary_color="#ff0000",
+        logo_file_id="abc-123",
+        favicon_file_id="def-456",
+    )
+    payload = branding_payload(s)
+    assert payload["appName"] == "Acme"
+    assert payload["primaryColor"] == "#ff0000"
+    assert payload["logoUrl"] == "/api/file-storage/files/abc-123/download"
+    assert payload["faviconUrl"] == "/api/file-storage/files/def-456/download"
+
+
+def test_provider_returns_empty_when_state_absent() -> None:
+    request = SimpleNamespace(app=SimpleNamespace(state=SimpleNamespace()))
+    assert branding_shared_props(request) == {}  # type: ignore[arg-type]
+
+
+def test_provider_emits_branding_block() -> None:
+    state = SimpleNamespace(branding=SimpleNamespace(settings=BrandingSettings(app_name="Acme")))
+    request = SimpleNamespace(app=SimpleNamespace(state=state))
+    out = branding_shared_props(request)  # type: ignore[arg-type]
+    assert out["branding"]["appName"] == "Acme"
+
+
+# ── Integration: API + persistence + hot-swap ──────────────────────────
+
+
+async def test_get_branding_returns_defaults(authenticated_client: httpx.AsyncClient) -> None:
+    resp = await authenticated_client.get("/api/branding/")
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["app_name"] == "SimpleModule"
+    assert body["logo_url"] is None
+
+
+async def test_update_persists_and_hot_swaps(app, authenticated_client: httpx.AsyncClient) -> None:
+    resp = await authenticated_client.put(
+        "/api/branding/",
+        json={"app_name": "Acme Corp", "primary_color": "#1A7DD1"},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["app_name"] == "Acme Corp"
+    assert body["primary_color"] == "#1a7dd1"
+
+    # Hot-swapped on app.state so the shared-props provider sees it immediately.
+    settings = app.state.branding.settings
+    assert settings.app_name == "Acme Corp"
+    assert branding_payload(settings)["appName"] == "Acme Corp"
+
+    # Persisted: a fresh GET reflects the change.
+    again = await authenticated_client.get("/api/branding/")
+    assert again.json()["app_name"] == "Acme Corp"
+
+
+async def test_root_template_reflects_branding(
+    app, authenticated_client: httpx.AsyncClient
+) -> None:
+    """The pre-hydration HTML shell carries the branded title + theme-color."""
+    # Default name before any change.
+    default_page = await authenticated_client.get("/branding/", follow_redirects=False)
+    assert default_page.status_code == 200, default_page.text
+    assert "<title>SimpleModule</title>" in default_page.text
+
+    await authenticated_client.put(
+        "/api/branding/",
+        json={"app_name": "Acme Corp", "primary_color": "#1A7DD1"},
+    )
+    page = await authenticated_client.get("/branding/", follow_redirects=False)
+    assert "<title>Acme Corp</title>" in page.text
+    assert '<meta name="theme-color" content="#1a7dd1" />' in page.text
+
+
+async def test_update_rejects_bad_hex(authenticated_client: httpx.AsyncClient) -> None:
+    resp = await authenticated_client.put("/api/branding/", json={"primary_color": "nope"})
+    assert resp.status_code == 422
+
+
+async def test_update_rejects_blank_app_name(authenticated_client: httpx.AsyncClient) -> None:
+    # A whitespace-only name must be a clean 422, not a 500 from BrandingSettings.
+    resp = await authenticated_client.put("/api/branding/", json={"app_name": "   "})
+    assert resp.status_code == 422
+
+
+async def test_update_rejects_control_char_app_name(
+    authenticated_client: httpx.AsyncClient,
+) -> None:
+    # A newline must be a clean 422 — otherwise it would later break email
+    # Subject headers (it now flows into invite/verify/reset subjects).
+    resp = await authenticated_client.put("/api/branding/", json={"app_name": "Acme\nCorp"})
+    assert resp.status_code == 422
+
+
+async def test_logo_upload_rejects_non_image(authenticated_client: httpx.AsyncClient) -> None:
+    resp = await authenticated_client.post(
+        "/api/branding/logo",
+        files={"file": ("notes.txt", b"hello", "text/plain")},
+    )
+    assert resp.status_code == 415
+
+
+async def test_logo_upload_sets_logo_url(
+    app, authenticated_client: httpx.AsyncClient, monkeypatch
+) -> None:
+    fake_id = uuid.uuid4()
+
+    async def fake_upload(self, upload):
+        return SimpleNamespace(id=fake_id)
+
+    monkeypatch.setattr("file_storage.service.FileStorageService.upload", fake_upload, raising=True)
+
+    resp = await authenticated_client.post(
+        "/api/branding/logo",
+        files={"file": ("logo.png", b"\x89PNG\r\n", "image/png")},
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["logo_url"] == f"/api/file-storage/files/{fake_id}/download"
+    assert app.state.branding.settings.logo_file_id == str(fake_id)
+
+    # Clearing removes it.
+    cleared = await authenticated_client.delete("/api/branding/logo")
+    assert cleared.status_code == 200
+    assert cleared.json()["logo_url"] is None
+
+
+async def test_manage_view_requires_auth(client: httpx.AsyncClient) -> None:
+    resp = await client.get("/branding", follow_redirects=False)
+    assert resp.status_code in (302, 401, 403)
+
+
+def test_page_constant_matches_view_literal() -> None:
+    # Guards against the inlined render literal drifting from the constant
+    # (the literal is required inline for SM003/SM004 static AST pairing).
+    import inspect
+
+    from branding import constants
+    from branding.endpoints import views
+
+    assert constants._PAGE_MANAGE == "Branding/Manage"
+    assert f'"{constants._PAGE_MANAGE}"' in inspect.getsource(views.manage)

simple_module_branding-0.0.24/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@simple-module-py/tsconfig/base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./branding/*"],
+      "@simple-module-py/ui/*": ["../../packages/ui/src/*"]
+    }
+  },
+  "include": ["branding/**/*.ts", "branding/**/*.tsx"]
+}