simple-module-branding 0.0.24__py3-none-any.whl

branding/__init__.py

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

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

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",
+]

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()

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)]

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()

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",
+    )

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"
+  }
+}

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}

branding/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": {}
+}

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;

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": ""})

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

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()

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+branding/__init__.py,sha256=Oa-2vuIajUpsnnyueXSEHc9vcvd6_2nSMdlO7r53lRs,23
+branding/constants.py,sha256=-sTqm2wlKsxyZwjhIVqzWlnGeU06FAb2ExbC6iFZMbo,2358
+branding/deps.py,sha256=fOSykBZE9Oo5CxMUiJ-3XnX8znkc8Vkzq0H55W4rU9w,534
+branding/module.py,sha256=RPI7t7jYwVf6e7MMldPhwZYxd3iZa0SFvpipEhCEU9Y,2565
+branding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+branding/service.py,sha256=fCmCTrdmBtf8AOHBZi0itLuymBMKm3U8HNy5ac5Lzf0,2313
+branding/services.py,sha256=9vIoBm7XXajTKrKSbtzLFZUQd8GFSjbCy2a40SeiHow,483
+branding/settings.py,sha256=IFl0nQf-_otR1xTlSn6osZ-xGtfpJmrsKW4km0RPSSs,1520
+branding/shared_props.py,sha256=ams6xwtLuVHOFTTp479B0cZlsnPDxQg2z6pvLauA7qU,1477
+branding/contracts/__init__.py,sha256=t-odwPDL0_VvnvZeTE_-kf9r_DlkJ8ChLCgb0hgXaDA,189
+branding/contracts/schemas.py,sha256=du41MIj9PKRC7ik5gSH4AvALW1CcJBXIpDO4eLQlXJs,1490
+branding/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+branding/endpoints/api.py,sha256=HfWR3ntnx7T4s98QDUOr1K5j8l9FzuKBd-WuolP6tlk,2661
+branding/endpoints/views.py,sha256=TFYFKBB48DhQ5uajOV4WZm6-kitACq8_jbpAn44stc0,1026
+branding/locales/en.json,sha256=YefFECIyrc9ws9ug2Dvpj5CK1xoa9pjYrDA9M5RoPv4,966
+branding/pages/Manage.tsx,sha256=LWUnGaz7YAfos9O1k2VlObQKplmLQF-4ZUhruZ5uaJ8,9156
+branding/package.json,sha256=JL1APdonxmY0KeDEQToAiSVsLP3G1Ez3L1MI9tpapps,379
+simple_module_branding-0.0.24.dist-info/METADATA,sha256=x4yAeJM6mf0WpQsbmi88sTnmxFe_mYhBvr77JN1F1A0,3572
+simple_module_branding-0.0.24.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+simple_module_branding-0.0.24.dist-info/entry_points.txt,sha256=G-jt7Ul0Kc8Q3xE72Dts_LmwGG-s8MDQe3HEWoPysfk,58
+simple_module_branding-0.0.24.dist-info/RECORD,,

simple_module_branding-0.0.24.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_branding-0.0.24.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+branding = branding.module:BrandingModule