@sjolystinnovation/app-kit 0.13.0 → 0.14.0

package/README.md

@@ -28,7 +28,7 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui`, `markdown` and `session/react` are styled with Tailwind CSS.
+The components in `@sjolystinnovation/app-kit/ui`, `markdown`, `branding` and `session/react` are styled with Tailwind CSS.
 Import the package's stylesheet after Tailwind:
 
 ```css
@@ -460,6 +460,69 @@ export async function GET(_request: Request, { params }: { params: Promise<{ loc
 It is a route rather than the `opengraph-image` file convention, since a page's own `openGraph`
 block replaces that image.
 
+### `@sjolystinnovation/app-kit/branding`
+
+The logo and favicon an admin uploads, as the API's `/branding` endpoint returns them.
+
+`BrandingProvider` holds them for the components below it. It takes the branding the server
+rendered with, loads it on mount when there is none, and loads it again every five minutes, so an
+open tab picks up a change. A failed load keeps what it has. `useBranding()` gives `branding`,
+`logoUrl` as a `data:` URL or null, and `refresh()`.
+
+```tsx
+"use client";
+import { BrandingProvider, useBranding } from "@sjolystinnovation/app-kit/branding";
+
+<BrandingProvider load={BrandingService.get} initial={initialBranding}>{children}</BrandingProvider>;
+
+const { logoUrl } = useBranding();
+<img src={logoUrl ?? "/logo.png"} alt="" />;
+```
+
+`BrandingManager` is the admin form for uploading or removing them. It needs a `BrandingProvider`
+above it, and refreshes it after a save.
+
+```tsx
+<BrandingManager save={form => BrandingService.update(form)} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `save` | `(form: FormData) => Promise<unknown>` | Sends `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw to show the error's message. |
+| `strings` | `TextOverrides<BrandingManagerStrings>` | The form's text. |
+
+`toDataUrl(data, contentType)` turns base64 bytes into a `data:` URL.
+
+### `@sjolystinnovation/app-kit/branding/server`
+
+`brandingIcon({ load, fallbackPath, fallbackType })` is the response for an `app/icon.ts` route:
+the favicon set in admin settings when it is a PNG, JPEG, WebP, GIF or ICO, or the bundled file
+otherwise, since an SVG or HTML upload could run script on the site's origin. Both carry `nosniff`
+and a sandbox CSP, which a CSP header from the app's `next.config` replaces. When the branding cannot be
+loaded it answers 503 with `no-store`, since a browser would cache the bundled icon in place of the
+one set in settings.
+
+```ts
+// src/app/icon.ts
+import { join } from "node:path";
+import { brandingIcon } from "@sjolystinnovation/app-kit/branding/server";
+
+export const dynamic = "force-dynamic";
+
+export default function Icon() {
+  return brandingIcon({
+    load: () => publicGet<Branding>("/branding", { tags: ["branding"] }),
+    fallbackPath: join(process.cwd(), "public", "icon.png"),
+    fallbackType: "image/png",
+  });
+}
+```
+
+The route needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment. Tag the
+fetch and revalidate the tag after a save, so a new icon shows at once. `iconVersion(data)` is a
+short digest of the icon bytes, for a manifest icon URL such as `/icon?v=<digest>`, since Android
+refreshes a home screen icon only when the manifest changes.
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",
@@ -29,6 +29,8 @@
     "./markdown": "./src/markdown/index.ts",
     "./seo": "./src/seo/index.ts",
     "./seo/og": "./src/seo/og/index.tsx",
+    "./branding": "./src/branding/index.ts",
+    "./branding/server": "./src/branding/server.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [

package/src/branding/BrandingManager.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { ArrowUpTrayIcon, TrashIcon } from "@heroicons/react/24/outline";
+import { useEffect, useRef, useState } from "react";
+import { toast } from "../toast";
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { useBranding } from "./BrandingProvider";
+import { toDataUrl } from "./types";
+
+export interface BrandingManagerStrings {
+  title: string;
+  logo: string;
+  logoHint: string;
+  icon: string;
+  iconHint: string;
+  none: string;
+  choose: string;
+  remove: string;
+  save: string;
+  saving: string;
+  saved: string;
+  saveFailed: string;
+}
+
+export const defaultBrandingManagerStrings: BrandingManagerStrings = {
+  title: "Branding",
+  logo: "Logo",
+  logoHint: "Shown in the navbar and footer. PNG/SVG, max 2 MB.",
+  icon: "Icon (favicon)",
+  iconHint: "Browser tab icon. Square PNG/ICO, max 2 MB.",
+  none: "none",
+  choose: "Choose",
+  remove: "Remove",
+  save: "Save branding",
+  saving: "Saving…",
+  saved: "Branding saved",
+  saveFailed: "Failed to save branding",
+};
+
+export interface BrandingManagerProps {
+  /**
+   * Sends the form: `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw
+   * to show the error's message, such as one from `formatApiError`.
+   */
+  save: (form: FormData) => Promise<unknown>;
+  strings?: TextOverrides<BrandingManagerStrings> | undefined;
+}
+
+/** A preview is an object URL for the chosen file or a data URL of a raster image. Anything else shows none. */
+const PREVIEW_URL = /^(blob:|data:image\/(png|jpeg|webp|gif|x-icon|vnd\.microsoft\.icon);base64,)/i;
+const previewUrl = (url: string | null): string | null => (url !== null && PREVIEW_URL.test(url) ? url : null);
+
+interface SlotProps {
+  label: string;
+  hint: string;
+  currentUrl: string | null;
+  file: File | null;
+  onPick: (file: File | null) => void;
+  onClear: () => void;
+  text: BrandingManagerStrings;
+}
+
+function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [objectUrl, setObjectUrl] = useState<string | null>(null);
+
+  // An object URL is an outside resource with a lifetime, which is what an effect is for. Creating
+  // it during render instead leaks the second URL that StrictMode builds when it renders twice.
+  /* eslint-disable react-hooks/set-state-in-effect */
+  useEffect(() => {
+    if (!file) {
+      setObjectUrl(null);
+      return;
+    }
+    const url = URL.createObjectURL(file);
+    setObjectUrl(url);
+    return () => URL.revokeObjectURL(url);
+  }, [file]);
+  /* eslint-enable react-hooks/set-state-in-effect */
+
+  const preview = previewUrl(objectUrl ?? currentUrl);
+  return (
+    <div>
+      <label className="block text-sm font-medium text-gray-700 mb-1">{label}</label>
+      <div className="flex items-center gap-3">
+        <div className="h-14 w-14 rounded-lg border border-gray-200 bg-gray-50 flex items-center justify-center overflow-hidden">
+          {preview ? (
+            <img src={preview} alt={label} className="max-h-full max-w-full object-contain" />
+          ) : (
+            <span className="text-xs text-gray-400">{text.none}</span>
+          )}
+        </div>
+        <input
+          ref={inputRef}
+          type="file"
+          accept="image/*"
+          aria-label={label}
+          className="hidden"
+          onChange={e => onPick(e.target.files?.[0] ?? null)}
+        />
+        <button
+          type="button"
+          onClick={() => inputRef.current?.click()}
+          className="inline-flex items-center gap-1.5 rounded-lg bg-gray-100 text-gray-700 font-medium px-3 py-2 text-sm hover:bg-gray-200"
+        >
+          <ArrowUpTrayIcon className="h-4 w-4" /> {text.choose}
+        </button>
+        {(currentUrl || file) && (
+          <button type="button" onClick={onClear} className="p-2 rounded-lg text-red-500 hover:bg-red-50" title={text.remove} aria-label={`${text.remove} ${label}`}>
+            <TrashIcon className="h-4 w-4" />
+          </button>
+        )}
+      </div>
+      <p className="mt-1 text-xs text-gray-500">{hint}</p>
+    </div>
+  );
+}
+
+/** The admin form for uploading or removing the logo and the favicon. Needs a `BrandingProvider` above it. */
+export function BrandingManager({ save, strings }: BrandingManagerProps) {
+  const text = withDefaults(defaultBrandingManagerStrings, strings);
+  const { branding, refresh } = useBranding();
+  const [logo, setLogo] = useState<File | null>(null);
+  const [icon, setIcon] = useState<File | null>(null);
+  const [removeLogo, setRemoveLogo] = useState(false);
+  const [removeIcon, setRemoveIcon] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  const currentLogo = removeLogo ? null : toDataUrl(branding.logoData, branding.logoContentType);
+  const currentIcon = removeIcon ? null : toDataUrl(branding.iconData, branding.iconContentType);
+
+  const submit = async () => {
+    setSaving(true);
+    try {
+      const form = new FormData();
+      if (logo) form.append("logo", logo);
+      if (icon) form.append("icon", icon);
+      if (removeLogo) form.append("removeLogo", "true");
+      if (removeIcon) form.append("removeIcon", "true");
+      await save(form);
+      setLogo(null);
+      setIcon(null);
+      setRemoveLogo(false);
+      setRemoveIcon(false);
+      refresh();
+      toast.success(text.saved);
+    } catch (err) {
+      toast.error(err instanceof Error && err.message ? err.message : text.saveFailed);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md space-y-5 border-t border-gray-200 pt-6">
+      <h2 className="font-bold text-gray-900">{text.title}</h2>
+      <Slot
+        label={text.logo}
+        hint={text.logoHint}
+        currentUrl={currentLogo}
+        file={logo}
+        onPick={f => { setLogo(f); setRemoveLogo(false); }}
+        onClear={() => { setLogo(null); setRemoveLogo(true); }}
+        text={text}
+      />
+      <Slot
+        label={text.icon}
+        hint={text.iconHint}
+        currentUrl={currentIcon}
+        file={icon}
+        onPick={f => { setIcon(f); setRemoveIcon(false); }}
+        onClear={() => { setIcon(null); setRemoveIcon(true); }}
+        text={text}
+      />
+      <button
+        type="button"
+        onClick={submit}
+        disabled={saving || (!logo && !icon && !removeLogo && !removeIcon)}
+        className="rounded-button bg-button-primary-bg text-button-primary-text font-semibold px-5 py-2.5 hover:brightness-95 disabled:opacity-60 transition"
+      >
+        {saving ? text.saving : text.save}
+      </button>
+    </div>
+  );
+}

package/src/branding/BrandingProvider.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { toDataUrl, type Branding } from "./types";
+
+export interface BrandingContextValue {
+  branding: Branding;
+  /** The logo as a `data:` URL, or null when none is set. */
+  logoUrl: string | null;
+  /** Loads the branding again, such as after saving it. */
+  refresh: () => void;
+}
+
+const BrandingContext = createContext<BrandingContextValue>({ branding: {}, logoUrl: null, refresh: () => {} });
+
+/** The branding from the nearest `BrandingProvider`. Empty outside one. */
+export const useBranding = () => useContext(BrandingContext);
+
+/** How often the provider loads the branding again, so an open tab picks up a change. */
+export const BRANDING_REFRESH_MS = 5 * 60 * 1000;
+
+export interface BrandingProviderProps {
+  children: ReactNode;
+  /** Loads the branding, such as a GET of `/branding`. A failure keeps the branding it has. */
+  load: () => Promise<Branding>;
+  /** The branding the server rendered with. Without it, the provider loads it on mount. */
+  initial?: Branding | undefined;
+}
+
+/** Holds the logo and favicon for the components below it, and loads them again every five minutes. */
+export function BrandingProvider({ children, load, initial }: BrandingProviderProps) {
+  const [branding, setBranding] = useState<Branding>(initial ?? {});
+  // The latest load, so an inline function does not restart the refresh timer on every render.
+  const loadRef = useRef(load);
+  useEffect(() => {
+    loadRef.current = load;
+  }, [load]);
+  const hasInitial = initial !== undefined;
+
+  const refresh = useCallback(() => {
+    loadRef.current().then(setBranding).catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    if (!hasInitial) refresh();
+    const id = setInterval(refresh, BRANDING_REFRESH_MS);
+    return () => clearInterval(id);
+  }, [refresh, hasInitial]);
+
+  const logoUrl = toDataUrl(branding.logoData, branding.logoContentType);
+
+  return <BrandingContext.Provider value={{ branding, logoUrl, refresh }}>{children}</BrandingContext.Provider>;
+}

package/src/branding/index.ts

@@ -0,0 +1,14 @@
+export {
+  BrandingManager,
+  defaultBrandingManagerStrings,
+  type BrandingManagerProps,
+  type BrandingManagerStrings,
+} from "./BrandingManager";
+export {
+  BRANDING_REFRESH_MS,
+  BrandingProvider,
+  useBranding,
+  type BrandingContextValue,
+  type BrandingProviderProps,
+} from "./BrandingProvider";
+export { toDataUrl, type Branding } from "./types";

package/src/branding/server.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import type { Branding } from "./types";
+
+export interface BrandingIconOptions {
+  /** Loads the branding, such as a cached GET of `/branding`. Throws when the API cannot be reached. */
+  load: () => Promise<Branding | null | undefined>;
+  /** The bundled icon for when none is set, such as `public/icon.png`. */
+  fallbackPath: string;
+  /** Its content type, such as `image/png` or `image/svg+xml`. */
+  fallbackType: string;
+}
+
+/**
+ * The response for an `app/icon.ts` route: the favicon set in admin settings when it is a PNG,
+ * JPEG, WebP, GIF or ICO, or the bundled one otherwise. Both carry `nosniff`, and a sandbox CSP
+ * that a CSP header from the app's `next.config` replaces.
+ * When the branding cannot be loaded it answers 503 with `no-store`, not the
+ * bundled icon, since a browser would cache that in place of the one set in settings. The route
+ * needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment.
+ */
+export async function brandingIcon({ load, fallbackPath, fallbackType }: BrandingIconOptions): Promise<Response> {
+  let branding: Branding | null | undefined;
+  try {
+    branding = await load();
+  } catch {
+    return new Response(null, { status: 503, headers: { "Cache-Control": "no-store" } });
+  }
+
+  const type = branding?.iconContentType?.trim().toLowerCase();
+  if (branding?.iconData && type && RASTER_TYPES.has(type)) {
+    return new Response(new Uint8Array(Buffer.from(branding.iconData, "base64")), {
+      headers: { "Content-Type": type, ...HARDENING },
+    });
+  }
+
+  return new Response(new Uint8Array(await readFile(fallbackPath)), { headers: { "Content-Type": fallbackType, ...HARDENING } });
+}
+
+/**
+ * The uploaded types the icon route serves. An SVG or HTML upload could carry script and would run
+ * on the site's origin, so anything else gives the bundled icon instead.
+ */
+const RASTER_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif", "image/x-icon", "image/vnd.microsoft.icon"]);
+
+/** Keeps a browser from sniffing the bytes as another type, and from running anything in them where the app sets no CSP. */
+const HARDENING = { "X-Content-Type-Options": "nosniff", "Content-Security-Policy": "default-src 'none'; sandbox" };
+
+/**
+ * A short digest of icon bytes, for a URL that changes when the icon does, such as
+ * `/icon?v=<digest>` in the web app manifest. Android refreshes a home screen icon only when the
+ * manifest changes.
+ */
+export const iconVersion = (data: string | Buffer): string => createHash("sha256").update(data).digest("hex").slice(0, 12);

package/src/branding/types.ts

@@ -0,0 +1,13 @@
+/** The logo and favicon set in admin settings, as the API's `/branding` endpoint returns them. */
+export interface Branding {
+  /** Base64 image bytes. */
+  logoData?: string | null | undefined;
+  logoContentType?: string | null | undefined;
+  /** Base64 image bytes. */
+  iconData?: string | null | undefined;
+  iconContentType?: string | null | undefined;
+}
+
+/** A `data:` URL for base64 image bytes, or null when either part is missing. */
+export const toDataUrl = (data?: string | null, contentType?: string | null): string | null =>
+  data && contentType ? `data:${contentType};base64,${data}` : null;