@bygghammar/cms-platform 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.48.0
+
+- Public-site media runtime is package-owned: new `media/FocalImage` (focus-aware `<img>`, `MediaFocusProvider`, `useFocalStyle`, `useObjectPosition`), `media/MediaMetaProvider` (alt/OG metadata context) and `media/LazyVideo` (bandwidth- and mobile-safe autoplay video). Sites pass their own focus/meta query options and register nothing else.
+- New `media/use-media-upload`: `useMediaUploadWith(uploadBundle, existing)` runs the shared optimize → upload → cache-invalidate pipeline with progress; only the storage call stays site-local.
+- New `cms/page-draft-store`: `createPageDraftStore({ prefix, channel })` gives a site the localStorage + BroadcastChannel draft bridge the page builder and preview routes share.
+
 ## 0.47.0
 
 - Media server logic is package-owned: new `server/media-focus-core` (focus-point map, desktop/mobile upsert, clear), `server/media-meta-core` (localized alt/title/description/credit read and write) and `server/media-replace-core` (width-matched "replace everywhere" with audit trail).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": false,
@@ -170,7 +170,12 @@
     "./server/media-focus-core": "./src/server/media-focus-core.ts",
     "./server/media-meta-core": "./src/server/media-meta-core.ts",
     "./server/media-replace-core": "./src/server/media-replace-core.ts",
-    "./server/media-cleanup-host": "./src/server/media-cleanup-host.ts"
+    "./server/media-cleanup-host": "./src/server/media-cleanup-host.ts",
+    "./media/FocalImage": "./src/media/FocalImage.tsx",
+    "./media/MediaMetaProvider": "./src/media/MediaMetaProvider.tsx",
+    "./media/LazyVideo": "./src/media/LazyVideo.tsx",
+    "./media/use-media-upload": "./src/media/use-media-upload.ts",
+    "./cms/page-draft-store": "./src/cms/page-draft-store.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"
@@ -247,4 +252,4 @@
     "cms-platform-migrations": "scripts/sync-migrations.mjs",
     "create-cms-site": "./scripts/create-cms-site.mjs"
   }
-}
+}

package/src/cms/page-draft-store.ts

@@ -0,0 +1,121 @@
+/**
+ * Per-page draft store shared by every site.
+ *
+ * The page builder writes an unsaved snapshot to `localStorage` and broadcasts
+ * it so the preview route can render it live. Only the storage prefix and the
+ * broadcast channel name differ per site, so both are parameters.
+ */
+
+export type PageDraftSnapshot<TBlock = unknown> = {
+  blocks: TBlock[];
+  globals: Record<string, TBlock[]>;
+  locale?: string;
+  updatedAt: number;
+};
+
+export type PageDraftStoreOptions = {
+  /** localStorage key prefix, e.g. `"voyara:draft:"`. */
+  prefix: string;
+  /** BroadcastChannel name, e.g. `"voyara-page-draft"`. */
+  channel: string;
+};
+
+export type PageDraftStore<TBlock = unknown> = {
+  draftKey: (pageKey: string) => string;
+  writeDraft: (pageKey: string, snap: Omit<PageDraftSnapshot<TBlock>, "updatedAt">) => void;
+  readDraft: (pageKey: string) => PageDraftSnapshot<TBlock> | null;
+  clearDraft: (pageKey: string) => void;
+  subscribeDraft: (pageKey: string, cb: (snap: PageDraftSnapshot<TBlock>) => void) => () => void;
+};
+
+export function createPageDraftStore<TBlock = unknown>(
+  options: PageDraftStoreOptions,
+): PageDraftStore<TBlock> {
+  const draftKey = (pageKey: string) => `${options.prefix}${pageKey}`;
+
+  const openChannel = (): BroadcastChannel | null => {
+    if (typeof window === "undefined" || typeof BroadcastChannel === "undefined") return null;
+    try {
+      return new BroadcastChannel(options.channel);
+    } catch {
+      return null;
+    }
+  };
+
+  const isSnapshot = (value: unknown): value is PageDraftSnapshot<TBlock> =>
+    !!value && Array.isArray((value as PageDraftSnapshot<TBlock>).blocks);
+
+  return {
+    draftKey,
+
+    writeDraft(pageKey, snap) {
+      if (typeof window === "undefined") return;
+      const payload: PageDraftSnapshot<TBlock> = { ...snap, updatedAt: Date.now() };
+      try {
+        window.localStorage.setItem(draftKey(pageKey), JSON.stringify(payload));
+      } catch {
+        /* quota or disabled storage — preview falls back to published */
+      }
+      const bc = openChannel();
+      if (bc) {
+        try {
+          bc.postMessage({ pageKey, snapshot: payload });
+        } finally {
+          bc.close();
+        }
+      }
+    },
+
+    readDraft(pageKey) {
+      if (typeof window === "undefined") return null;
+      try {
+        const raw = window.localStorage.getItem(draftKey(pageKey));
+        if (!raw) return null;
+        const parsed = JSON.parse(raw) as unknown;
+        return isSnapshot(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+
+    clearDraft(pageKey) {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.removeItem(draftKey(pageKey));
+      } catch {
+        /* ignore */
+      }
+    },
+
+    subscribeDraft(pageKey, cb) {
+      if (typeof window === "undefined") return () => {};
+
+      const onStorage = (e: StorageEvent) => {
+        if (e.key !== draftKey(pageKey) || !e.newValue) return;
+        try {
+          const parsed = JSON.parse(e.newValue) as unknown;
+          if (isSnapshot(parsed)) cb(parsed);
+        } catch {
+          /* ignore */
+        }
+      };
+      window.addEventListener("storage", onStorage);
+
+      const bc = openChannel();
+      const onMsg = (ev: MessageEvent) => {
+        const d = ev.data as { pageKey?: string; snapshot?: unknown } | undefined;
+        if (!d || d.pageKey !== pageKey) return;
+        if (isSnapshot(d.snapshot)) cb(d.snapshot);
+      };
+      bc?.addEventListener("message", onMsg);
+
+      return () => {
+        window.removeEventListener("storage", onStorage);
+        if (bc) {
+          bc.removeEventListener("message", onMsg);
+          bc.close();
+        }
+      };
+    },
+  };
+}

package/src/media/FocalImage.tsx

@@ -0,0 +1,152 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type CSSProperties,
+  type ImgHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { useQuery } from "@tanstack/react-query";
+
+import {
+  focalCssVars,
+  focalToObjectPosition,
+  lookupEntry,
+  lookupFocal,
+  type FocusMap,
+} from "./focus";
+import { responsiveImage } from "./srcset";
+
+const FocusContext = createContext<FocusMap>({});
+
+/** Structural shape of a site's `queryOptions(...)` for its focus map. */
+export type FocusQueryOptions = {
+  queryKey: readonly unknown[];
+  queryFn: () => Promise<FocusMap>;
+  staleTime?: number;
+};
+
+/**
+ * Provides the site's saved focus points to every `FocalImage` below it.
+ * The query itself is site infrastructure and is passed in.
+ */
+export function MediaFocusProvider({
+  queryOptions,
+  children,
+}: {
+  queryOptions: FocusQueryOptions;
+  children: ReactNode;
+}) {
+  const { data } = useQuery({ ...queryOptions, placeholderData: {} as FocusMap });
+  return <FocusContext.Provider value={data ?? {}}>{children}</FocusContext.Provider>;
+}
+
+export function useFocusMap(): FocusMap {
+  return useContext(FocusContext);
+}
+
+/** `object-position` for a given image URL, honouring its saved focus point. */
+export function useObjectPosition(src: string | undefined): string {
+  const map = useFocusMap();
+  return focalToObjectPosition(lookupFocal(map, src));
+}
+
+/**
+ * Class + inline CSS vars that apply the desktop focus point and, when set,
+ * a separate mobile focus point (below 768px).
+ */
+export function useFocalStyle(src: string | undefined): {
+  className: string;
+  style: CSSProperties;
+} {
+  const map = useFocusMap();
+  return {
+    className: "focal-pos",
+    style: focalCssVars(lookupEntry(map, src)) as CSSProperties,
+  };
+}
+
+export type FocalImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> & {
+  src: string | undefined;
+  /** When set, builds a responsive srcSet from the media library variants. */
+  sizes?: string;
+  responsive?: boolean;
+};
+
+/**
+ * `<img>` that always crops around the image's editor-chosen focus point.
+ * Falls back to a centred crop when no focus point is stored.
+ *
+ * When the source is a responsive WebP variant with a `-fallback.png` sibling,
+ * renders a `<picture>` so browsers that do not support WebP (or need explicit
+ * alpha handling) still receive a transparent PNG.
+ */
+export function FocalImage({
+  src,
+  sizes,
+  responsive = true,
+  style,
+  onError,
+  ...rest
+}: FocalImageProps) {
+  const focal = useFocalStyle(src);
+  // Uploads of small source images skip the intermediate widths, so a candidate
+  // in the srcSet can be missing. If the browser picks one of those, fall back
+  // to the stored URL on its own — never leave a blank space on the page.
+  const [srcSetFailed, setSrcSetFailed] = useState(false);
+  useEffect(() => setSrcSetFailed(false), [src]);
+
+  const img = responsive && !srcSetFailed ? responsiveImage(src, sizes) : { src: src ?? "" };
+  const merged: CSSProperties = { ...focal.style, ...style };
+  const className = [focal.className, rest.className].filter(Boolean).join(" ");
+
+  // Only wrap in <picture> when a fallback PNG is advertised. The fallback URL
+  // is always derived, but it only exists for transparent uploads; using it for
+  // every image would cause unnecessary 404s on opaque assets.
+  const hasFallback =
+    "fallbackSrc" in img &&
+    img.fallbackSrc &&
+    // A missing fallback is indistinguishable from an opaque asset, so we only
+    // render the <source> when the primary URL is definitely a responsive WebP.
+    img.type === "image/webp" &&
+    img.srcSet;
+
+  if (hasFallback && "fallbackSrc" in img) {
+    // The <picture> is only a source selector: it must not take the layout or
+    // focus classes, or the inner <img> loses `object-position` and the crop
+    // ignores the editor-chosen focus point.
+    return (
+      <picture style={{ display: "contents" }}>
+        <source srcSet={img.srcSet} sizes={img.sizes} type="image/webp" />
+        <img
+          {...rest}
+          className={className}
+          src={img.fallbackSrc}
+          alt={rest.alt}
+          style={merged}
+          onError={(event) => {
+            if (!srcSetFailed) setSrcSetFailed(true);
+            onError?.(event);
+          }}
+        />
+      </picture>
+    );
+  }
+
+  return (
+    <img
+      {...rest}
+      className={className}
+      src={img.src}
+      srcSet={"srcSet" in img ? img.srcSet : undefined}
+      sizes={"sizes" in img ? img.sizes : undefined}
+      alt={rest.alt}
+      style={merged}
+      onError={(event) => {
+        if (!srcSetFailed) setSrcSetFailed(true);
+        onError?.(event);
+      }}
+    />
+  );
+}

package/src/media/LazyVideo.tsx

@@ -0,0 +1,202 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { useT } from "../i18n/context";
+import { resolveMediaSrc } from "./urls";
+
+/**
+ * Bandwidth-safe, mobile-safe <video> wrapper.
+ *
+ * Mobile browsers (iOS Safari in particular) only start an inline autoplaying
+ * video when `muted`, `playsinline` and `autoplay` are present as real
+ * attributes on the element that owns the media, and when at least one source
+ * is present when the element is parsed. Sources are therefore always
+ * rendered — the download itself stays cheap because `preload` is `none`
+ * until the element is near the viewport.
+ *
+ *  - the poster paints first (cheap image, correct visual design),
+ *  - `preload` is upgraded to the caller's hint once near the viewport,
+ *  - a timeout fallback guarantees the video is never left permanently
+ *    unloaded when IntersectionObserver never fires,
+ *  - `play()` is called explicitly and its promise is always caught: a refused
+ *    autoplay never crashes the page, it reveals an accessible tap-to-play
+ *    button over the poster,
+ *  - reduced motion keeps the poster and the tap-to-play button instead of
+ *    removing the media.
+ */
+export type LazyVideoProps = {
+  src?: string;
+  /** Optional alternative sources (e.g. WebM) tried before `src`. */
+  sources?: Array<{ src: string; type: string }>;
+  poster?: string;
+  className?: string;
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  controls?: boolean;
+  /** Preload hint used once the element is near the viewport. */
+  preload?: "none" | "metadata" | "auto";
+  ariaLabel?: string;
+  /** Localized accessible label for the tap-to-play fallback control. */
+  playLabel?: { sv: string } & Record<string, string>;
+};
+
+export function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * Order the sources so the broadly compatible MP4/H.264 rendition is always
+ * offered. Safari picks the first source it claims to support, and some iOS
+ * versions claim WebM support they cannot actually decode, so MP4 goes first.
+ */
+export function orderedSources(
+  rawSrc: string | undefined,
+  rawSources: Array<{ src: string; type: string }> | undefined,
+): Array<{ src: string; type: string }> {
+  const src = resolveMediaSrc(rawSrc);
+  const sources = rawSources?.map((s) => ({ ...s, src: resolveMediaSrc(s.src) }));
+  const list =
+    sources && sources.length ? [...sources] : src ? [{ src, type: guessType(src) }] : [];
+  const seen = new Set<string>();
+  const unique = list.filter((s) => {
+    if (!s.src || seen.has(s.src)) return false;
+    seen.add(s.src);
+    return true;
+  });
+  if (src && !seen.has(src)) unique.push({ src, type: guessType(src) });
+  const rank = (type: string) => (/mp4/i.test(type) ? 0 : /webm/i.test(type) ? 1 : 2);
+  return unique.sort((a, b) => rank(a.type) - rank(b.type));
+}
+
+function guessType(url: string): string {
+  const clean = url.split("?")[0]!.toLowerCase();
+  if (clean.endsWith(".webm")) return "video/webm";
+  if (clean.endsWith(".mov")) return "video/quicktime";
+  return "video/mp4";
+}
+
+export function LazyVideo({
+  src,
+  sources,
+  poster,
+  className,
+  autoPlay = true,
+  loop = true,
+  muted = true,
+  controls = false,
+  preload = "metadata",
+  ariaLabel,
+  playLabel,
+}: LazyVideoProps) {
+  const { t } = useT();
+  const ref = useRef<HTMLVideoElement>(null);
+  const [active, setActive] = useState(false);
+  const [reduced, setReduced] = useState(false);
+  const [blocked, setBlocked] = useState(false);
+
+  const list = orderedSources(src, sources);
+
+  useEffect(() => {
+    setReduced(prefersReducedMotion());
+  }, []);
+
+  useEffect(() => {
+    if (active) return;
+    const el = ref.current;
+    if (!el) return;
+    if (typeof IntersectionObserver === "undefined") {
+      setActive(true);
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) {
+          setActive(true);
+          io.disconnect();
+        }
+      },
+      { rootMargin: "200px" },
+    );
+    io.observe(el);
+    // Never leave the video permanently unloaded (mobile browsers can skip
+    // observer callbacks for elements inside transformed/animated ancestors).
+    const timer = setTimeout(() => setActive(true), 3000);
+    return () => {
+      io.disconnect();
+      clearTimeout(timer);
+    };
+  }, [active]);
+
+  // Explicit playback attempt: a refused promise must never propagate.
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !active) return;
+    if (!autoPlay || reduced) return;
+    let cancelled = false;
+    el.muted = muted;
+    const attempt = el.play();
+    if (attempt && typeof attempt.catch === "function") {
+      attempt
+        .then(() => {
+          if (!cancelled) setBlocked(false);
+        })
+        .catch(() => {
+          if (!cancelled) setBlocked(true);
+        });
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [active, autoPlay, muted, reduced]);
+
+  const play = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    setActive(true);
+    el.muted = muted;
+    const attempt = el.play();
+    if (attempt && typeof attempt.catch === "function") {
+      attempt.then(() => setBlocked(false)).catch(() => setBlocked(true));
+    }
+  }, [muted]);
+
+  const showPlayButton = !controls && (blocked || (reduced && autoPlay));
+
+  return (
+    <>
+      <video
+        ref={ref}
+        className={className}
+        poster={resolveMediaSrc(poster) || undefined}
+        preload={active ? preload : "none"}
+        autoPlay={autoPlay && !reduced}
+        loop={loop}
+        muted={muted}
+        controls={controls}
+        playsInline
+        aria-label={ariaLabel}
+      >
+        {list.map((s) => (
+          <source key={s.src} src={s.src} type={s.type} />
+        ))}
+      </video>
+      {showPlayButton ? (
+        <button
+          type="button"
+          onClick={play}
+          aria-label={t(
+            playLabel ?? { sv: ariaLabel ? `Spela upp ${ariaLabel}` : "Spela upp video" },
+          )}
+          className="absolute inset-0 z-10 grid place-items-center bg-transparent"
+        >
+          <span className="grid size-14 place-items-center rounded-full bg-white/85 text-black shadow-lg">
+            <svg viewBox="0 0 24 24" width="22" height="22" fill="currentColor" aria-hidden="true">
+              <path d="M8 5v14l11-7z" />
+            </svg>
+          </span>
+        </button>
+      ) : null}
+    </>
+  );
+}

package/src/media/MediaMetaProvider.tsx

@@ -0,0 +1,33 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+
+import { lookupMediaMeta, type MediaMeta, type MediaMetaMap } from "./media-meta";
+
+const MediaMetaContext = createContext<MediaMetaMap>({});
+
+/** Structural shape of a site's `queryOptions(...)` for its media metadata. */
+export type MediaMetaQueryOptions = {
+  queryKey: readonly unknown[];
+  queryFn: () => Promise<MediaMetaMap>;
+  staleTime?: number;
+};
+
+export function MediaMetaProvider({
+  queryOptions,
+  children,
+}: {
+  queryOptions: MediaMetaQueryOptions;
+  children: ReactNode;
+}) {
+  const { data } = useQuery({ ...queryOptions, placeholderData: {} as MediaMetaMap });
+  return <MediaMetaContext.Provider value={data ?? {}}>{children}</MediaMetaContext.Provider>;
+}
+
+export function useMediaMetaMap(): MediaMetaMap {
+  return useContext(MediaMetaContext);
+}
+
+/** Saved metadata (alt / OG title / description / credit) for one image URL. */
+export function useMediaMeta(src: string | undefined): MediaMeta {
+  return lookupMediaMeta(useMediaMetaMap(), src);
+}

package/src/media/use-media-upload.ts

@@ -0,0 +1,90 @@
+import { useCallback, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+import { optimizeForUpload } from "./optimize";
+import { pickVideoPoster } from "./pick-video-poster";
+import { cleanFileName, splitExt, uniqueFileName } from "./filename";
+
+export type UploadProgress = { label: string; percent: number } | null;
+
+/** One file in a site's media library, as far as uploading is concerned. */
+export type UploadExistingItem = { name: string };
+
+/** The site's server call that stores an already-optimized bundle. */
+export type UploadBundleFn = (input: {
+  data: {
+    files: Array<{ name: string; contentType: string; bytes: number[] }>;
+  };
+}) => Promise<{ urls: string[] }>;
+
+/**
+ * Shared browser-side media upload (optimize → storage → cache invalidate)
+ * with a coarse percentage so callers can render a progress bar.
+ *
+ * The storage call itself is site infrastructure and is injected.
+ */
+export function useMediaUploadWith(
+  uploadBundle: UploadBundleFn,
+  existing: UploadExistingItem[] = [],
+) {
+  const queryClient = useQueryClient();
+  const [progress, setProgress] = useState<UploadProgress>(null);
+  const [uploading, setUploading] = useState(false);
+
+  const upload = useCallback(
+    async (files: FileList | File[] | null): Promise<string[]> => {
+      const arr = files ? Array.from(files as ArrayLike<File>) : [];
+      if (!arr.length) return [];
+      setUploading(true);
+      const urls: string[] = [];
+      const taken = new Set<string>(
+        existing.flatMap((i) => {
+          const { base } = splitExt(i.name);
+          return [i.name, base, base.replace(/-(?:480|768|1200|1920)$/, "")];
+        }),
+      );
+      try {
+        for (let idx = 0; idx < arr.length; idx++) {
+          const file = arr[idx]!;
+          const step = (frac: number, label: string) =>
+            setProgress({
+              label: `${label} ${idx + 1}/${arr.length}: ${file.name}`,
+              percent: Math.round(((idx + frac) / arr.length) * 100),
+            });
+
+          // Videos: let the editor pick the poster frame before we transcode.
+          const posterTime = file.type.startsWith("video/") ? await pickVideoPoster(file) : null;
+
+          step(0.05, "Optimizing");
+          const { base } = splitExt(cleanFileName(file.name));
+          const baseSlug = uniqueFileName(base, taken);
+          taken.add(baseSlug);
+          const bundle = await optimizeForUpload(file, baseSlug, {
+            posterTime: posterTime ?? undefined,
+          });
+
+          step(0.4, "Uploading");
+          const all = [bundle.primary, ...bundle.extras];
+          const payload = await Promise.all(
+            all.map(async (part) => ({
+              name: part.name,
+              contentType: part.contentType,
+              bytes: Array.from(new Uint8Array(await part.blob.arrayBuffer())),
+            })),
+          );
+          const { urls: uploaded } = await uploadBundle({ data: { files: payload } });
+          urls.push(uploaded[0]!);
+          step(1, "Uploading");
+        }
+        await queryClient.invalidateQueries({ queryKey: ["media-library"] });
+        return urls;
+      } finally {
+        setUploading(false);
+        setProgress(null);
+      }
+    },
+    [existing, queryClient, uploadBundle],
+  );
+
+  return { upload, uploading, progress };
+}