simple-module-branding 0.0.26__tar.gz → 0.0.28__tar.gz

{simple_module_branding-0.0.26 → simple_module_branding-0.0.28}/.gitignore

@@ -45,6 +45,7 @@ docs/.vitepress/dist/
 host/client_app/modules.manifest.json
 host/client_app/modules.generated.ts
 host/client_app/modules.generated.css
+host/client_app/modules.assets.json
 
 # Worktrees
 .worktrees/

simple_module_branding-0.0.28/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: simple_module_branding
+Version: 0.0.28
+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.28
+Requires-Dist: simple-module-db==0.0.28
+Requires-Dist: simple-module-file-storage==0.0.28
+Requires-Dist: simple-module-hosting==0.0.28
+Requires-Dist: simple-module-settings==0.0.28
+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** (plus an optional
+**dark-background variant**), **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`, `designPack`,
+`logoUrl`, `logoDarkUrl`, `faviconUrl`, `banner`, `footer`). `banner` and
+`footer` are `null` when unconfigured, which is what makes the frontend fall
+back to rendering nothing and to the framework footer respectively. For a dark
+surface use
+`darkSurfaceLogo(branding)` from `@simple-module-py/ui/lib/brand`, which applies
+the `logoDarkUrl → logoUrl` fallback in one place.
+
+## 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). Branding serves them back from its own
+  **anonymous** routes, `GET /api/branding/logo` and `GET /api/branding/favicon`
+  — `file_storage`'s download endpoint requires `file-storage.download`, which
+  no logged-out visitor has, and the sign-in page is exactly where the logo
+  must appear. Only the two ids currently held in branding settings are served,
+  so this is not a way to read arbitrary files. Uploading and clearing on those
+  same paths stay behind `branding.manage` (the exemption is GET-only).
+- **Caching.** The published URL carries `?v=<file id>`; a replaced image is a
+  new `file_storage` id, so the URL is content-addressed. Versioned requests
+  are served `public, max-age=31536000, immutable`; a request without a usable
+  version gets `public, max-age=3600` so it self-corrects, and a 404 is never
+  cached.
+- **Announcement banner.** A message plus a severity (`info` / `warning` /
+  `danger`) rendered above every shell — app, public and auth — because an
+  outage notice is most useful to people who cannot sign in. An empty message
+  hides it. Severity colours are semantic, not brand-tinted: a warning wearing
+  the deployment's accent colour stops reading as a warning.
+- **Presets.** One-click looks (`POST /api/branding/presets/{key}`), applied
+  through the ordinary update path so every validator still runs. A preset only
+  ever sets *appearance* (`PRESET_FIELDS` — primary colour, design pack); it
+  can never overwrite the app name, an uploaded logo or a live banner, and
+  `BrandingPreset` rejects any other field at construction.
+- **Configurable footer.** Tagline, copyright owner, caption, up to 6 columns
+  of 8 links, and up to 8 social links (`PUT /api/branding/footer`, whole-object
+  replace). Link URLs are restricted to http(s) or a single-leading-slash app
+  path — `javascript:` and `data:` are refused, and `//host` is treated as the
+  off-site absolute URL it is rather than a path. With nothing configured the
+  framework's built-in footer renders unchanged.
+- **Dark-background logo.** The sidebar and mobile bar sit on a near-black
+  surface in every theme, while the sign-in card and public page are light — so
+  a single logo cannot read on both. Uploading a *Logo (dark backgrounds)*
+  variant swaps it in on those surfaces only. It is optional: with none set the
+  shared prop reports `logoDarkUrl: null` and the frontend falls back to
+  `logoUrl`, so single-logo deployments look exactly as they did.
+- **Lifecycle.** Replacing or clearing an image deletes the file it stopped
+  referencing, so repeated logo tweaks don't leave orphans in `file_storage`.
+  Cleanup is best effort: the setting change has already been persisted, so a
+  storage fault is logged rather than failing an otherwise-successful rebrand.
+- **Upload validation.** PNG, JPEG, WEBP, GIF and ICO up to 2 MB. The declared
+  content-type is caller-controlled, so the first bytes are also checked
+  against each format's magic number — a payload renamed `logo.png` is
+  rejected. SVG is excluded on purpose: it is an XML document that can carry
+  `<script>`, so serving one from the app's origin would be stored XSS.
+- **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).
+
+The logo and favicon **GET** routes are anonymous by design (registered through
+the `register_public_routes` hook); everything else requires a permission.
+
+## 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.28/README.md

@@ -0,0 +1,126 @@
+# 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** (plus an optional
+**dark-background variant**), **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`, `designPack`,
+`logoUrl`, `logoDarkUrl`, `faviconUrl`, `banner`, `footer`). `banner` and
+`footer` are `null` when unconfigured, which is what makes the frontend fall
+back to rendering nothing and to the framework footer respectively. For a dark
+surface use
+`darkSurfaceLogo(branding)` from `@simple-module-py/ui/lib/brand`, which applies
+the `logoDarkUrl → logoUrl` fallback in one place.
+
+## 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). Branding serves them back from its own
+  **anonymous** routes, `GET /api/branding/logo` and `GET /api/branding/favicon`
+  — `file_storage`'s download endpoint requires `file-storage.download`, which
+  no logged-out visitor has, and the sign-in page is exactly where the logo
+  must appear. Only the two ids currently held in branding settings are served,
+  so this is not a way to read arbitrary files. Uploading and clearing on those
+  same paths stay behind `branding.manage` (the exemption is GET-only).
+- **Caching.** The published URL carries `?v=<file id>`; a replaced image is a
+  new `file_storage` id, so the URL is content-addressed. Versioned requests
+  are served `public, max-age=31536000, immutable`; a request without a usable
+  version gets `public, max-age=3600` so it self-corrects, and a 404 is never
+  cached.
+- **Announcement banner.** A message plus a severity (`info` / `warning` /
+  `danger`) rendered above every shell — app, public and auth — because an
+  outage notice is most useful to people who cannot sign in. An empty message
+  hides it. Severity colours are semantic, not brand-tinted: a warning wearing
+  the deployment's accent colour stops reading as a warning.
+- **Presets.** One-click looks (`POST /api/branding/presets/{key}`), applied
+  through the ordinary update path so every validator still runs. A preset only
+  ever sets *appearance* (`PRESET_FIELDS` — primary colour, design pack); it
+  can never overwrite the app name, an uploaded logo or a live banner, and
+  `BrandingPreset` rejects any other field at construction.
+- **Configurable footer.** Tagline, copyright owner, caption, up to 6 columns
+  of 8 links, and up to 8 social links (`PUT /api/branding/footer`, whole-object
+  replace). Link URLs are restricted to http(s) or a single-leading-slash app
+  path — `javascript:` and `data:` are refused, and `//host` is treated as the
+  off-site absolute URL it is rather than a path. With nothing configured the
+  framework's built-in footer renders unchanged.
+- **Dark-background logo.** The sidebar and mobile bar sit on a near-black
+  surface in every theme, while the sign-in card and public page are light — so
+  a single logo cannot read on both. Uploading a *Logo (dark backgrounds)*
+  variant swaps it in on those surfaces only. It is optional: with none set the
+  shared prop reports `logoDarkUrl: null` and the frontend falls back to
+  `logoUrl`, so single-logo deployments look exactly as they did.
+- **Lifecycle.** Replacing or clearing an image deletes the file it stopped
+  referencing, so repeated logo tweaks don't leave orphans in `file_storage`.
+  Cleanup is best effort: the setting change has already been persisted, so a
+  storage fault is logged rather than failing an otherwise-successful rebrand.
+- **Upload validation.** PNG, JPEG, WEBP, GIF and ICO up to 2 MB. The declared
+  content-type is caller-controlled, so the first bytes are also checked
+  against each format's magic number — a payload renamed `logo.png` is
+  rejected. SVG is excluded on purpose: it is an XML document that can carry
+  `<script>`, so serving one from the app's origin would be stored XSS.
+- **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).
+
+The logo and favicon **GET** routes are anonymous by design (registered through
+the `register_public_routes` hook); everything else requires a permission.
+
+## 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.28/branding/components/BannerField.tsx

@@ -0,0 +1,75 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@simple-module-py/ui/components/ui/select';
+
+/** Mirrors `BANNER_SEVERITIES` in `branding/constants.py`. */
+export const BANNER_SEVERITIES = ['info', 'warning', 'danger'] as const;
+export type BannerSeverity = (typeof BANNER_SEVERITIES)[number];
+
+/** Matches `MAX_BANNER_MESSAGE_LEN`, so the server never has to reject length. */
+export const MAX_BANNER_MESSAGE = 500;
+
+interface BannerFieldProps {
+  message: string;
+  severity: BannerSeverity;
+  onMessageChange: (next: string) => void;
+  onSeverityChange: (next: BannerSeverity) => void;
+  disabled: boolean;
+}
+
+/** Site-wide announcement bar: message + severity. Empty message hides it. */
+export function BannerField({
+  message,
+  severity,
+  onMessageChange,
+  onSeverityChange,
+  disabled,
+}: BannerFieldProps) {
+  const { t } = useT();
+  const severityLabels: Record<BannerSeverity, string> = {
+    info: t(keys.branding.manage.banner_severity_info),
+    warning: t(keys.branding.manage.banner_severity_warning),
+    danger: t(keys.branding.manage.banner_severity_danger),
+  };
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="banner_message">{t(keys.branding.manage.banner_label)}</Label>
+      <div className="flex flex-wrap items-center gap-3">
+        <Input
+          id="banner_message"
+          value={message}
+          maxLength={MAX_BANNER_MESSAGE}
+          disabled={disabled}
+          placeholder={t(keys.branding.manage.banner_placeholder)}
+          onChange={(e) => onMessageChange(e.target.value)}
+          className="min-w-60 flex-1"
+        />
+        <Select
+          value={severity}
+          disabled={disabled}
+          onValueChange={(next) => onSeverityChange(next as BannerSeverity)}
+        >
+          <SelectTrigger id="banner_severity" className="w-40" aria-label="Banner severity">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {BANNER_SEVERITIES.map((value) => (
+              <SelectItem key={value} value={value}>
+                {severityLabels[value]}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+      <p className="text-xs text-muted-foreground">{t(keys.branding.manage.banner_help)}</p>
+    </div>
+  );
+}

simple_module_branding-0.0.28/branding/components/FooterCard.tsx

@@ -0,0 +1,76 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@simple-module-py/ui/components/ui/card';
+import type { FooterShared } from '@simple-module-py/ui/types';
+import { useState } from 'react';
+import { EMPTY_FOOTER, type FooterDraft, FooterEditor } from './FooterEditor';
+import { newRowId, stripIds } from './LinkRows';
+
+/** Payload shape of `PUT /api/branding/footer` (snake_case, like the DTO). */
+export interface FooterPayload {
+  tagline: string;
+  copyright_owner: string;
+  note: string;
+  columns: { title: string; links: { label: string; href: string }[] }[];
+  social_links: { label: string; href: string }[];
+}
+
+interface FooterCardProps {
+  /** Current server-side footer, or null when none is configured. */
+  initial: FooterShared | null;
+  disabled: boolean;
+  busy: boolean;
+  onSave: (payload: FooterPayload) => void;
+}
+
+/** Rows get a client-only id so React keys stay stable across add/remove. */
+function toDraft(footer: FooterShared | null): FooterDraft {
+  if (!footer) return EMPTY_FOOTER;
+  return {
+    tagline: footer.tagline,
+    copyrightOwner: footer.copyrightOwner,
+    note: footer.note,
+    columns: footer.columns.map((c) => ({
+      id: newRowId(),
+      title: c.title,
+      links: c.links.map((l) => ({ id: newRowId(), ...l })),
+    })),
+    socialLinks: footer.socialLinks.map((l) => ({ id: newRowId(), ...l })),
+  };
+}
+
+/**
+ * The footer section of the branding page — its own card, its own draft state
+ * and its own save, because a footer edit replaces the whole structure and is
+ * independent of the identity fields above it.
+ */
+export function FooterCard({ initial, disabled, busy, onSave }: FooterCardProps) {
+  const { t } = useT();
+  const [draft, setDraft] = useState<FooterDraft>(() => toDraft(initial));
+
+  const save = () =>
+    onSave({
+      tagline: draft.tagline,
+      copyright_owner: draft.copyrightOwner,
+      note: draft.note,
+      columns: stripIds(draft.columns).map((c) => ({
+        title: c.title,
+        links: stripIds(c.links),
+      })),
+      social_links: stripIds(draft.socialLinks),
+    });
+
+  return (
+    <Card className="lg:col-span-2">
+      <CardHeader>
+        <CardTitle>{t(keys.branding.manage.footer_title)}</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <FooterEditor value={draft} onChange={setDraft} disabled={disabled} />
+        <Button type="button" disabled={disabled} onClick={save}>
+          {busy ? t(keys.branding.manage.saving) : t(keys.branding.manage.footer_save_button)}
+        </Button>
+      </CardContent>
+    </Card>
+  );
+}

simple_module_branding-0.0.28/branding/components/FooterEditor.tsx

@@ -0,0 +1,139 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { type EditableLink, LinkRows, newRowId } from './LinkRows';
+
+/** Mirror the server limits in `branding/footer.py`. */
+export const MAX_COLUMNS = 6;
+export const MAX_LINKS_PER_COLUMN = 8;
+export const MAX_SOCIAL_LINKS = 8;
+
+export interface EditableColumn {
+  /** Client-only key; see LinkRows. Stripped before sending. */
+  id: string;
+  title: string;
+  links: EditableLink[];
+}
+
+export interface FooterDraft {
+  tagline: string;
+  copyrightOwner: string;
+  note: string;
+  columns: EditableColumn[];
+  socialLinks: EditableLink[];
+}
+
+export const EMPTY_FOOTER: FooterDraft = {
+  tagline: '',
+  copyrightOwner: '',
+  note: '',
+  columns: [],
+  socialLinks: [],
+};
+
+interface FooterEditorProps {
+  value: FooterDraft;
+  onChange: (next: FooterDraft) => void;
+  disabled: boolean;
+}
+
+/** Multi-column footer builder: brand text, link columns and a social row. */
+export function FooterEditor({ value, onChange, disabled }: FooterEditorProps) {
+  const { t } = useT();
+  const patch = (next: Partial<FooterDraft>) => onChange({ ...value, ...next });
+
+  const updateColumn = (id: string, next: Partial<EditableColumn>) =>
+    patch({ columns: value.columns.map((c) => (c.id === id ? { ...c, ...next } : c)) });
+
+  return (
+    <div className="space-y-4">
+      <div className="grid gap-3 sm:grid-cols-3">
+        <div className="space-y-1.5">
+          <Label htmlFor="footer_tagline">{t(keys.branding.manage.footer_tagline_label)}</Label>
+          <Input
+            id="footer_tagline"
+            value={value.tagline}
+            disabled={disabled}
+            onChange={(e) => patch({ tagline: e.target.value })}
+          />
+        </div>
+        <div className="space-y-1.5">
+          <Label htmlFor="footer_copyright">{t(keys.branding.manage.footer_copyright_label)}</Label>
+          <Input
+            id="footer_copyright"
+            value={value.copyrightOwner}
+            disabled={disabled}
+            onChange={(e) => patch({ copyrightOwner: e.target.value })}
+          />
+        </div>
+        <div className="space-y-1.5">
+          <Label htmlFor="footer_note">{t(keys.branding.manage.footer_note_label)}</Label>
+          <Input
+            id="footer_note"
+            value={value.note}
+            disabled={disabled}
+            onChange={(e) => patch({ note: e.target.value })}
+          />
+        </div>
+      </div>
+
+      <div className="space-y-3">
+        {value.columns.map((column, index) => (
+          <div key={column.id} className="space-y-2 rounded-lg border p-3">
+            <div className="flex items-center gap-2">
+              <Input
+                value={column.title}
+                disabled={disabled}
+                placeholder={t(keys.branding.manage.footer_column_title)}
+                onChange={(e) => updateColumn(column.id, { title: e.target.value })}
+                className="w-56 font-medium"
+              />
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                disabled={disabled}
+                aria-label={`${t(keys.branding.manage.footer_remove_column)}: ${column.title || index + 1}`}
+                onClick={() => patch({ columns: value.columns.filter((c) => c.id !== column.id) })}
+              >
+                {t(keys.branding.manage.footer_remove_column)}
+              </Button>
+            </div>
+            <LinkRows
+              links={column.links}
+              max={MAX_LINKS_PER_COLUMN}
+              disabled={disabled}
+              onChange={(links) => updateColumn(column.id, { links })}
+            />
+          </div>
+        ))}
+        {value.columns.length < MAX_COLUMNS && (
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            disabled={disabled}
+            onClick={() =>
+              patch({ columns: [...value.columns, { id: newRowId(), title: '', links: [] }] })
+            }
+          >
+            {t(keys.branding.manage.footer_add_column)}
+          </Button>
+        )}
+      </div>
+
+      <div className="space-y-2">
+        <Label>{t(keys.branding.manage.footer_social_label)}</Label>
+        <LinkRows
+          links={value.socialLinks}
+          max={MAX_SOCIAL_LINKS}
+          disabled={disabled}
+          onChange={(socialLinks) => patch({ socialLinks })}
+        />
+      </div>
+
+      <p className="text-xs text-muted-foreground">{t(keys.branding.manage.footer_help)}</p>
+    </div>
+  );
+}

simple_module_branding-0.0.28/branding/components/ImageField.tsx

@@ -0,0 +1,81 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { type ChangeEvent, useRef } from 'react';
+
+/**
+ * Mirrors the server allow-list in `branding/images.py`. SVG is absent on
+ * purpose — it is an XML document that can carry <script>, so the server
+ * rejects it; offering it in the picker would only produce a 415.
+ */
+export const ACCEPTED_IMAGE_TYPES = 'image/png,image/jpeg,image/webp,image/gif,image/x-icon';
+
+interface ImageFieldProps {
+  label: string;
+  help: string;
+  url: string | null;
+  onUpload: (file: File) => void;
+  onRemove: () => void;
+  disabled: boolean;
+  /** Preview swatch background — dark for logos meant for dark surfaces. */
+  previewClassName?: string;
+}
+
+/** One upload/replace/remove slot with a thumbnail, for a single branding image. */
+export function ImageField({
+  label,
+  help,
+  url,
+  onUpload,
+  onRemove,
+  disabled,
+  previewClassName = 'bg-muted',
+}: ImageFieldProps) {
+  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 ${previewClassName}`}
+        >
+          {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={ACCEPTED_IMAGE_TYPES}
+            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>
+  );
+}