@bygghammar/cms-platform 0.3.0 → 0.4.0

package/src/media/review-image.ts

@@ -0,0 +1,107 @@
+/**
+ * Client-side preparation of review (testimonial) images.
+ *
+ * Uploaded review images keep their original aspect ratio (no crop at upload
+ * time — cropping happens at display time around the editor-chosen focus point)
+ * and are re-encoded to WebP at the four standard responsive widths so review
+ * cards stay fast. The server re-validates every produced variant
+ * (see `review-image.server.ts`) — this step is an optimisation, not a trust boundary.
+ *
+ * Browser-only (uses Canvas). Do NOT import from server code.
+ */
+
+import { RESPONSIVE_WIDTHS } from "./srcset";
+
+export const REVIEW_ASPECT = 16 / 10;
+/** Safety ceiling for the stored image height (very tall panoramas). */
+export const MAX_STORED_HEIGHT = 2400;
+export const REVIEW_QUALITY = 0.8;
+/** Hard client-side guard before we even decode the file. */
+export const MAX_SOURCE_BYTES = 15 * 1024 * 1024;
+export const ACCEPTED_SOURCE_TYPES = /^image\/(jpeg|jpg|png|webp|avif|gif|bmp|tiff?)$/i;
+
+export type PreparedVariant = {
+  width: number;
+  height: number;
+  /** Base64 (no data: prefix) WebP payload. */
+  data: string;
+};
+
+export type PreparedReviewImage = {
+  slug: string;
+  variants: PreparedVariant[];
+  sourceBytes: number;
+  optimizedBytes: number;
+};
+
+export function reviewImageSlug(fileName: string): string {
+  const dot = fileName.lastIndexOf(".");
+  const base = dot > 0 ? fileName.slice(0, dot) : fileName;
+  const cleaned = base
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  // Keep the uploaded filename — no timestamps (SEO-friendly URLs).
+  return cleaned || "review-image";
+}
+
+export async function prepareReviewImage(file: File): Promise<PreparedReviewImage> {
+  if (!ACCEPTED_SOURCE_TYPES.test(file.type)) {
+    throw new Error("Unsupported image type. Use JPEG, PNG, WebP, AVIF or GIF.");
+  }
+  if (file.size > MAX_SOURCE_BYTES) {
+    throw new Error("Image is too large (max 15 MB).");
+  }
+
+  const bmp = await createImageBitmap(file);
+  try {
+    if (bmp.width < 320 || bmp.height < 200) {
+      throw new Error("Image is too small — use at least 320×200 px.");
+    }
+    const variants: PreparedVariant[] = [];
+    let optimizedBytes = 0;
+    for (const targetW of RESPONSIVE_WIDTHS) {
+      const width = Math.min(targetW, Math.max(320, bmp.width));
+      let height = Math.max(1, Math.round((width * bmp.height) / bmp.width));
+      if (height > MAX_STORED_HEIGHT) height = MAX_STORED_HEIGHT;
+      const blob = await encodeCoverWebp(bmp, width, height);
+      optimizedBytes += blob.size;
+      variants.push({ width: targetW, height, data: await blobToBase64(blob) });
+    }
+    return { slug: "", variants, sourceBytes: file.size, optimizedBytes };
+  } finally {
+    bmp.close?.();
+  }
+}
+
+async function encodeCoverWebp(bmp: ImageBitmap, w: number, h: number): Promise<Blob> {
+  const canvas = document.createElement("canvas");
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Canvas is unavailable in this browser.");
+  // Scale to fill; with an aspect-preserving target this is a plain resize.
+  const scale = Math.max(w / bmp.width, h / bmp.height);
+  const dw = bmp.width * scale;
+  const dh = bmp.height * scale;
+  ctx.imageSmoothingQuality = "high";
+  ctx.drawImage(bmp, (w - dw) / 2, (h - dh) / 2, dw, dh);
+  const blob = await new Promise<Blob | null>((resolve) =>
+    canvas.toBlob((b) => resolve(b), "image/webp", REVIEW_QUALITY),
+  );
+  if (!blob) throw new Error("Could not encode the image.");
+  return blob;
+}
+
+async function blobToBase64(blob: Blob): Promise<string> {
+  const buf = new Uint8Array(await blob.arrayBuffer());
+  let binary = "";
+  const chunk = 0x8000;
+  for (let i = 0; i < buf.length; i += chunk) {
+    binary += String.fromCharCode(...buf.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}

package/src/media/srcset.ts

@@ -0,0 +1,78 @@
+/**
+ * Responsive image helpers. Works with files produced by `optimizeForUpload`,
+ * which uploads a base slug plus WebP variants: `-480`, `-768`, `-1200`, `-1920`
+ * and (for assets uploaded after the HiDPI change) `-2560`. Transparent uploads
+ * also produce a single `-fallback.png` for older browsers.
+ *
+ * Given the largest variant URL (`…-1920.webp`), derives sibling URLs and returns
+ * a ready-to-use `srcSet`/`sizes` pair plus a PNG fallback when one exists. For
+ * any other URL shape, returns the original `src` so legacy assets keep working
+ * with no responsive scaling.
+ */
+
+import { resolveMediaSrc } from "./urls";
+
+export const RESPONSIVE_WIDTHS = [480, 768, 1200, 1920, 2560] as const;
+export type ResponsiveWidth = (typeof RESPONSIVE_WIDTHS)[number];
+
+const VARIANT_RE = /-(480|768|1200|1920|2560)\.webp(\?.*)?$/i;
+
+export type ResponsiveImage = {
+  src: string;
+  srcSet?: string;
+  sizes?: string;
+  /** MIME type of the responsive srcSet (`image/webp`). */
+  type?: string;
+  /** PNG fallback URL for browsers that do not support WebP or need alpha. */
+  fallbackSrc?: string;
+};
+
+/**
+ * Build a responsive srcSet from any variant URL (…-1920.webp / -1200 / -768 / -480).
+ * Returns just `{ src }` if the URL is not a known responsive variant.
+ */
+export function responsiveImage(input: string | undefined, sizes?: string): ResponsiveImage {
+  if (!input) return { src: "" };
+  const url = resolveMediaSrc(input);
+  const m = url.match(VARIANT_RE);
+  if (!m) return { src: url };
+
+  const currentWidth = Number(m[1]);
+  const query = m[2] ?? "";
+  const base = url.slice(0, url.length - m[0].length); // strip `-<w>.webp[?…]`
+  // Legacy assets only have variants up to 1920; only advertise 2560 when the
+  // URL we were handed already points at a 2560 primary (i.e. a newer upload).
+  const maxWidth = currentWidth >= 2560 ? 2560 : 1920;
+  const widths = RESPONSIVE_WIDTHS.filter((w) => w <= maxWidth);
+  const parts = widths.map((w) => `${base}-${w}.webp${query} ${w}w`);
+  return {
+    // The URL we were handed is the one that is actually stored, so it is the
+    // only safe plain `src`: small uploads skip the intermediate widths and a
+    // derived `-1920.webp` may never have been written.
+    src: url,
+    srcSet: parts.join(", "),
+    sizes: sizes ?? "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 1200px",
+    type: "image/webp",
+    fallbackSrc: `${base}-fallback.png${query}`,
+  };
+}
+
+/** All sibling variant paths for a given primary path (for deletion cascades). */
+export function variantSiblings(primaryPath: string): string[] {
+  const m = primaryPath.match(VARIANT_RE);
+  if (!m) return [];
+  const base = primaryPath.slice(0, primaryPath.length - m[0].length);
+  return RESPONSIVE_WIDTHS.filter((w) => w !== Number(m[1])).map((w) => `${base}-${w}.webp`);
+}
+
+/** True when `path` is a smaller variant of a primary (used to hide from library). */
+export function isSecondaryVariant(path: string): boolean {
+  const m = path.match(VARIANT_RE);
+  if (!m) return false;
+  const w = Number(m[1]);
+  if (w === 2560) return false;
+  if (w !== 1920) return true;
+  // A `-1920` file is primary for legacy assets but secondary when a `-2560`
+  // sibling exists; the library filters that case via `hasLargerSibling`.
+  return false;
+}

package/src/media/storage.ts

@@ -0,0 +1,139 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+
+import { isInternalMediaPath } from "./internal-paths";
+import { mediaBucket } from "./urls";
+
+export type StorageProvider = "supabase";
+
+export type StorageFileInfo = {
+  name: string;
+  size: number;
+  contentType: string | null;
+  updatedAt: string | null;
+};
+
+export type UploadOptions = {
+  upsert?: boolean;
+};
+
+export interface MediaStorage {
+  readonly provider: StorageProvider;
+  upload(
+    path: string,
+    data: Uint8Array,
+    contentType: string,
+    options?: UploadOptions,
+  ): Promise<void>;
+  download(path: string): Promise<Uint8Array>;
+  remove(paths: string[]): Promise<void>;
+  move(source: string, destination: string): Promise<void>;
+  list(): Promise<StorageFileInfo[]>;
+  publicUrl(filePath: string): string;
+}
+
+/**
+ * Return the media storage client.
+ *
+ * Pass the authenticated client from the request context so RLS applies.
+ */
+export function getMediaStorage(supabaseClient?: SupabaseClient): MediaStorage {
+  return new SupabaseStorage(supabaseClient);
+}
+
+class SupabaseStorage implements MediaStorage {
+  readonly provider = "supabase" as const;
+
+  constructor(private readonly client: SupabaseClient | undefined) {}
+
+  private bucket() {
+    if (!this.client) throw new Error("Supabase storage requires an authenticated client");
+    return this.client.storage.from(mediaBucket());
+  }
+
+  async upload(
+    filePath: string,
+    data: Uint8Array,
+    contentType: string,
+    options?: UploadOptions,
+  ): Promise<void> {
+    const blob = new Blob([data as unknown as BlobPart], { type: contentType });
+    const { error } = await this.bucket().upload(filePath, blob, {
+      contentType,
+      upsert: options?.upsert ?? false,
+    });
+    if (error) throw new Error(error.message);
+  }
+
+  async download(filePath: string): Promise<Uint8Array> {
+    const { data, error } = await this.bucket().download(filePath);
+    if (!error) return new Uint8Array(await data.arrayBuffer());
+
+    // The media bucket is deliberately public. Large authenticated Storage
+    // downloads can occasionally fail in browsers even while the CDN object
+    // is healthy, so retry through the public object URL before aborting the
+    // complete archive.
+    const publicUrl = this.publicUrl(filePath);
+    try {
+      const response = await fetch(publicUrl, { cache: "no-store" });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return new Uint8Array(await response.arrayBuffer());
+    } catch (fallbackError) {
+      throw new Error(
+        `${error.message}; public media fallback failed: ${
+          fallbackError instanceof Error ? fallbackError.message : String(fallbackError)
+        }`,
+      );
+    }
+  }
+
+  async remove(paths: string[]): Promise<void> {
+    if (!paths.length) return;
+    const { error } = await this.bucket().remove(paths);
+    if (error) throw new Error(error.message);
+  }
+
+  async move(source: string, destination: string): Promise<void> {
+    const { error } = await this.bucket().move(source, destination);
+    if (error) throw new Error(error.message);
+  }
+
+  /** Recursively list every object in the bucket, paginating through folders. */
+  async list(): Promise<StorageFileInfo[]> {
+    const out: StorageFileInfo[] = [];
+    const walk = async (prefix: string): Promise<void> => {
+      const PAGE = 1000;
+      for (let offset = 0; ; offset += PAGE) {
+        const { data, error } = await this.bucket().list(prefix, {
+          limit: PAGE,
+          offset,
+          sortBy: { column: "name", order: "asc" },
+        });
+        if (error) throw new Error(error.message);
+        const entries = data ?? [];
+        for (const f of entries as any[]) {
+          const name = prefix ? `${prefix}/${f.name}` : (f.name as string);
+          if (isInternalMediaPath(name)) continue;
+          // Supabase returns folders as rows without an id/metadata.
+          if (!f.id && !f.metadata) {
+            await walk(name);
+            continue;
+          }
+          out.push({
+            name,
+            size: f.metadata?.size ?? 0,
+            contentType: f.metadata?.mimetype ?? null,
+            updatedAt: f.updated_at ?? f.created_at ?? null,
+          });
+        }
+        if (entries.length < PAGE) break;
+      }
+    };
+    await walk("");
+    return out;
+  }
+
+  publicUrl(filePath: string): string {
+    const { data } = this.bucket().getPublicUrl(filePath);
+    return data.publicUrl ?? "";
+  }
+}

package/src/media/urls.ts

@@ -0,0 +1,55 @@
+/**
+ * Public URLs for files stored in a site's media library.
+ *
+ * The URL shape is platform behaviour and identical on every site; only the
+ * origins differ, so each site configures them once at startup instead of the
+ * package reading any site's environment variables.
+ */
+
+export type MediaUrlConfig = {
+  /** Supabase project URL, when media is served from Supabase Storage. */
+  supabaseUrl?: string | undefined;
+  /** Explicit public origin, used by self-hosted installs. */
+  mediaPublicUrl?: string | undefined;
+  /** Storage bucket holding the media library. */
+  bucket?: string;
+};
+
+let config: Required<Pick<MediaUrlConfig, "bucket">> & MediaUrlConfig = { bucket: "media" };
+
+/** Register the origins this install serves media from. */
+export function configureMediaUrls(next: MediaUrlConfig): void {
+  config = {
+    ...config,
+    ...next,
+    mediaPublicUrl: next.mediaPublicUrl?.replace(/\/$/, "") ?? config.mediaPublicUrl,
+    bucket: next.bucket ?? config.bucket,
+  };
+}
+
+export function mediaBucket(): string {
+  return config.bucket;
+}
+
+export function mediaUrl(path: string): string {
+  const clean = path.replace(/^\/+/, "");
+  if (config.mediaPublicUrl) return `${config.mediaPublicUrl}/${clean}`;
+  if (config.supabaseUrl) {
+    return `${config.supabaseUrl}/storage/v1/object/public/${config.bucket}/${clean}`;
+  }
+  // Self-hosted default: same-origin, served by the /media/* route.
+  return `/media/${clean}`;
+}
+
+/**
+ * Resolve any stored media reference to a URL that works on this install.
+ *
+ * Content written while media was served from the app's own origin still holds
+ * `/media/<file>` paths, so rewrite that legacy shape. Absolute URLs, data URIs
+ * and non-media paths are returned untouched.
+ */
+export function resolveMediaSrc<T extends string | undefined>(src: T): T {
+  if (!src) return src;
+  if (!src.startsWith("/media/")) return src;
+  return mediaUrl(src.slice("/media/".length)) as T;
+}

package/src/media/usage-types.ts

@@ -0,0 +1,24 @@
+export type MediaUsage = {
+  entity: "section" | "page" | "global_section" | "page_seo" | "block_template";
+  entityKey: string;
+  label: string;
+  editPath: string;
+  publicPath?: string;
+  jsonPath: string;
+};
+
+export type MediaUsageReport = {
+  byPath: Record<string, MediaUsage[]>;
+  external: Array<{ url: string; usages: MediaUsage[] }>;
+};
+
+export type MediaImportResult =
+  | {
+      path: string;
+      url: string;
+      skipped?: false;
+      error?: never;
+      rewritten?: number;
+      deduped?: boolean;
+    }
+  | { path: ""; url: ""; skipped: true; error: string; rewritten?: never; deduped?: never };

package/src/platform/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Host platform contract.
+ *
+ * Blocks and inspectors already reach the host through `../host`. Backoffice
+ * *screens* additionally need data: pages, forms, media, SEO and audit access.
+ * Those calls are per-site (each site owns its own database, server functions
+ * and auth), while the screens themselves are identical everywhere — so the
+ * package declares the contract here and each site registers an adapter at
+ * startup.
+ *
+ * Adapters return plain data. No Supabase client, request or response object
+ * ever crosses this boundary, which keeps the package usable by a site that is
+ * not backed by Supabase at all.
+ */
+
+import type { Json } from "../i18n/json";
+
+export type PageSummary = {
+  key: string;
+  title: string;
+  updatedAt: string | null;
+  published: boolean;
+};
+
+export type PageDraft = {
+  key: string;
+  versionNo: number;
+  blocks: Json;
+};
+
+export type MediaEntry = {
+  path: string;
+  url: string;
+  size: number;
+  contentType: string | null;
+  updatedAt: string | null;
+};
+
+/** Data access the shared backoffice screens need from the host site. */
+export type PlatformData = {
+  pages: {
+    list: () => Promise<PageSummary[]>;
+    loadDraft: (key: string) => Promise<PageDraft | null>;
+    saveDraft: (input: PageDraft) => Promise<{ versionNo: number }>;
+    publish: (key: string, versionNo: number) => Promise<void>;
+  };
+  media: {
+    list: () => Promise<MediaEntry[]>;
+    remove: (paths: string[]) => Promise<void>;
+  };
+  audit?: {
+    log: (event: { action: string; target: string; detail?: Json }) => Promise<void>;
+  };
+};
+
+/** Non-data facts about the host install that shared screens display. */
+export type PlatformSite = {
+  /** Human name shown in the backoffice chrome. */
+  name: string;
+  /** Backoffice base path, e.g. `/kontoret`. */
+  backofficeBasePath: string;
+  /** Public site origin, used for preview links. */
+  publicOrigin?: string;
+};
+
+export type HostPlatform = {
+  site: PlatformSite;
+  data: PlatformData;
+};
+
+let platform: HostPlatform | null = null;
+
+/** Register the host adapter. Call once during site startup. */
+export function registerHostPlatform(next: HostPlatform): HostPlatform {
+  platform = next;
+  return next;
+}
+
+export function getHostPlatform(): HostPlatform {
+  if (!platform) {
+    throw new Error(
+      "@bygghammar/cms-platform: no host platform registered. Call registerHostPlatform() during site startup.",
+    );
+  }
+  return platform;
+}
+
+export function hasHostPlatform(): boolean {
+  return platform !== null;
+}

package/src/trips/index.ts

@@ -58,6 +58,33 @@ export function defineTripTerminology(terminology: TripTerminology): TripTermino
   return terminology;
 }
 
+/** Neutral fallback used until a site registers its own wording. */
+export const DEFAULT_TRIP_TERMINOLOGY: TripTerminology = {
+  singular: "Trip",
+  plural: "Trips",
+  number: "Trip number",
+  dates: "Trip dates",
+  location: "Route",
+  accommodation: "Accommodation",
+  description:
+    "This is the single source of truth for trips and departures across the whole site.",
+};
+
+let terminology: TripTerminology = DEFAULT_TRIP_TERMINOLOGY;
+
+/**
+ * Register the site's trip wording so shared platform screens can label
+ * trip-related fields without hardcoding any site's vocabulary.
+ */
+export function registerTripTerminology(value: TripTerminology): TripTerminology {
+  terminology = value;
+  return value;
+}
+
+export function getTripTerminology(): TripTerminology {
+  return terminology;
+}
+
 export function tripNumber(item: Pick<TripItem, "tripNo" | "courseNo">): Partial<LocalizedString> {
   return item.tripNo ?? item.courseNo ?? {};
 }