@bygghammar/cms-platform 0.43.1 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.44.0
+
+- New `backoffice/routes/media-forms`: package-owned `MediaRoute`,
+  `FormsIndexRoute`, `FormEditorRoute`, `FormSubmissionsRoute` and
+  `FormDeliveriesRoute`, plus `validateSubmissionSearch`.
+- Host contract gains optional `media` and `forms` adapter groups
+  (`requireHostGroup`) and `backofficePaths()` now also derives `media`,
+  `formSubmissions` and `formDeliveries`.
+
 ## 0.42.0
 
 - Backoffice host registry gains email-settings, locale-domain, shared-content,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.43.1",
+  "version": "0.44.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,
@@ -158,6 +158,7 @@
     "./backoffice/shell": "./src/backoffice/shell/index.ts",
     "./backoffice/routes": "./src/backoffice/routes/index.tsx",
     "./backoffice/routes/host": "./src/backoffice/routes/host.ts",
+    "./backoffice/routes/media-forms": "./src/backoffice/routes/media-forms.tsx",
     "./backoffice/inspectors": "./src/backoffice/inspectors/index.tsx"
   },
   "dependencies": {

package/src/backoffice/routes/host.ts

@@ -122,8 +122,67 @@ export type BackofficeHost = {
     /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
     buildBrowserMediaArchive: (args: any) => Promise<any>;
   };
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  /** Media library adapters: query options, server calls and site components. */
+  media?: {
+    /** TanStack Query options for the media library listing. */
+    libraryQueryOptions: any;
+    fns: {
+      deleteMedia: HostServerFn;
+      listTrash: HostServerFn;
+      restoreMedia: HostServerFn;
+      purgeMedia: HostServerFn;
+      emptyTrash: HostServerFn;
+      uploadMediaBundle: HostServerFn;
+      listMediaUsage: HostServerFn;
+      importUrlToMedia: HostServerFn;
+    };
+    components: {
+      FocalImage: any;
+      FocusPicker: any;
+      MediaMetaDialog: any;
+      MediaReplaceDialog: any;
+    };
+    /** Hook returning the site's media metadata map (alt/caption/credits). */
+    useMetaMap: () => any;
+    /** Superadmin maintenance tools rendered next to Upload. */
+    maintenanceTools?: (args: { onDone: () => Promise<void> }) => ReactNode;
+  };
+  /** Forms module adapters: server calls plus the editor panels. */
+  forms?: {
+    fns: {
+      createFormFromType: HostServerFn;
+      deleteForm: HostServerFn;
+      duplicateForm: HostServerFn;
+      getFormUsage: HostServerFn;
+      listDeletedForms: HostServerFn;
+      purgeForm: HostServerFn;
+      restoreForm: HostServerFn;
+      saveForm: HostServerFn;
+      syncSubmissionsToSheet: HostServerFn;
+      testWebhook: HostServerFn;
+      listSubmissions: HostServerFn;
+      setSubmissionStatus: HostServerFn;
+      pushSubmissionsToSheet: HostServerFn;
+      resendDelivery: HostServerFn;
+      listPartials: HostServerFn;
+      deletePartials: HostServerFn;
+      listDeliveryAttempts: HostServerFn;
+      retryDeliveryAttempts: HostServerFn;
+      resolveDeliveryAttempts: HostServerFn;
+    };
+    components: {
+      FieldEditor: any;
+      FormPreview: any;
+      TestDeliveryPanel: any;
+      VersionHistory: any;
+      ActivityLog: any;
+    };
+  };
+  /* eslint-enable @typescript-eslint/no-explicit-any */
 };
 
+
 let current: BackofficeHost | null = null;
 
 /** Registers the host adapters. Call once, from a module the routes import. */
@@ -164,5 +223,21 @@ export function backofficePaths(host: BackofficeHost = backofficeHost()) {
     backup: `${base}/admin/backup`,
     sections: `${base}/sections`,
     globalSections: `${base}/global-sections`,
+    media: `${base}/media`,
+    formSubmissions: `${base}/forms/submissions`,
+    formDeliveries: `${base}/forms/deliveries`,
   };
 }
+
+/** Reads a required optional host group, failing loudly when it is missing. */
+export function requireHostGroup<K extends "media" | "forms">(
+  key: K,
+): NonNullable<BackofficeHost[K]> {
+  const group = backofficeHost()[key];
+  if (!group) {
+    throw new Error(
+      `Backoffice host is missing the "${key}" adapters — add them to registerBackofficeHost().`,
+    );
+  }
+  return group as NonNullable<BackofficeHost[K]>;
+}

package/src/backoffice/routes/index.tsx

@@ -46,6 +46,7 @@ import { VersionView } from "../VersionView";
 import { backofficeHost, backofficePaths } from "./host";
 
 export * from "./host";
+export * from "./media-forms";
 
 /** Audit trail screen. */
 export function AuditRoute() {

package/src/backoffice/routes/media-forms.tsx

@@ -0,0 +1,360 @@
+/**
+ * Package-owned media library and forms routes.
+ *
+ * Each component reads the media/forms adapters from the backoffice host
+ * registry, wires the queries and renders the shared view, so a site route file
+ * stays a two-line `createFileRoute(...)({ component: XRoute })`.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { Link, useNavigate, useParams, useSearch } from "@tanstack/react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useServerFn } from "@tanstack/react-start";
+import { useMemo, useState } from "react";
+
+import { MediaLibraryView, type MediaLibraryDeps } from "../MediaLibraryView";
+import { FormsIndexView } from "../FormsIndexView";
+import { FormEditorView } from "../FormEditorView";
+import { FormSubmissionsView, SUBMISSIONS_PAGE_SIZE } from "../FormSubmissionsView";
+import { FormDeliveriesView, type DeliveryChannel } from "../FormDeliveriesView";
+import { backofficeHost, backofficePaths, requireHostGroup } from "./host";
+
+/** Router-agnostic link that forwards loose `to`/`params`/`search` values. */
+function HostLink({
+  to,
+  params,
+  search,
+  className,
+  onClick,
+  children,
+}: {
+  to: string;
+  params?: unknown;
+  search?: unknown;
+  className?: string;
+  onClick?: () => void;
+  children?: React.ReactNode;
+}) {
+  return (
+    <Link
+      to={to as any}
+      params={params as any}
+      search={search as any}
+      className={className}
+      onClick={onClick}
+    >
+      {children}
+    </Link>
+  );
+}
+
+/** Media library screen (library, trash, usage and maintenance tools). */
+export function MediaRoute() {
+  const media = requireHostGroup("media");
+  const { fns: adminFns } = backofficeHost();
+  const queryClient = useQueryClient();
+
+  const { data: items = [], isLoading } = useQuery(media.libraryQueryOptions);
+
+  const del = useServerFn(media.fns.deleteMedia);
+  const fetchUsage = useServerFn(media.fns.listMediaUsage);
+  const runImport = useServerFn(media.fns.importUrlToMedia);
+  const uploadBundle = useServerFn(media.fns.uploadMediaBundle);
+  const fetchTrash = useServerFn(media.fns.listTrash);
+  const fetchRoles = useServerFn(adminFns.getMyRoles);
+  const restore = useServerFn(media.fns.restoreMedia);
+  const purge = useServerFn(media.fns.purgeMedia);
+  const empty = useServerFn(media.fns.emptyTrash);
+
+  const usageQ = useQuery({ queryKey: ["media-usage"], queryFn: () => fetchUsage() });
+  const trashQ = useQuery({ queryKey: ["media-trash"], queryFn: () => fetchTrash() });
+  const rolesQ = useQuery({ queryKey: ["admin", "my-roles"], queryFn: () => fetchRoles() });
+
+  const metaMap = media.useMetaMap();
+
+  const refreshAll = async () => {
+    await Promise.all([
+      queryClient.invalidateQueries({ queryKey: ["media-library"] }),
+      queryClient.invalidateQueries({ queryKey: ["media-trash"] }),
+      queryClient.invalidateQueries({ queryKey: ["media-usage"] }),
+    ]);
+  };
+
+  const deps = useMemo<MediaLibraryDeps>(
+    () => ({
+      items: (items ?? []) as MediaLibraryDeps["items"],
+      isLoading,
+      trash: (trashQ.data ?? []) as MediaLibraryDeps["trash"],
+      trashLoading: trashQ.isLoading,
+      usage: usageQ.data as MediaLibraryDeps["usage"],
+      isSuperadmin: ((rolesQ.data ?? []) as string[]).includes("superadmin"),
+      metaMap,
+      deleteMedia: (input) => del(input as never),
+      restoreMedia: (input) => restore(input as never),
+      purgeMedia: (input) => purge(input as never),
+      emptyTrash: () => empty() as Promise<{ purged: number }>,
+      uploadMediaBundle: (input) => uploadBundle(input as never),
+      importUrlToMedia: (input) => runImport(input as never),
+      refreshAll,
+      invalidateLibrary: () => queryClient.invalidateQueries({ queryKey: ["media-library"] }),
+      FocalImageComponent: media.components.FocalImage,
+      MediaMetaDialogComponent: media.components.MediaMetaDialog,
+      FocusPickerComponent: media.components.FocusPicker,
+      MediaReplaceDialogComponent: media.components.MediaReplaceDialog,
+      maintenanceTools: media.maintenanceTools,
+      LinkComponent: HostLink as MediaLibraryDeps["LinkComponent"],
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [items, isLoading, trashQ.data, trashQ.isLoading, usageQ.data, rolesQ.data, metaMap],
+  );
+
+  return <MediaLibraryView deps={deps} />;
+}
+
+/** Forms index: list, create, duplicate, delete and the trash bin. */
+export function FormsIndexRoute() {
+  const forms = requireHostGroup("forms");
+  const { fns } = backofficeHost();
+  const qc = useQueryClient();
+
+  const list = useServerFn(fns.listForms);
+  const create = useServerFn(forms.fns.createFormFromType);
+  const remove = useServerFn(forms.fns.deleteForm);
+  const copy = useServerFn(forms.fns.duplicateForm);
+  const usage = useServerFn(forms.fns.getFormUsage);
+  const listBin = useServerFn(forms.fns.listDeletedForms);
+  const restore = useServerFn(forms.fns.restoreForm);
+  const purge = useServerFn(forms.fns.purgeForm);
+
+  const { data: rows, isLoading } = useQuery({
+    queryKey: ["backoffice-forms"],
+    queryFn: () => list(),
+  });
+  const { data: bin } = useQuery({ queryKey: ["backoffice-forms-bin"], queryFn: () => listBin() });
+
+  const refresh = async () => {
+    await qc.invalidateQueries({ queryKey: ["backoffice-forms"] });
+    await qc.invalidateQueries({ queryKey: ["backoffice-forms-bin"] });
+  };
+
+  return (
+    <FormsIndexView
+      deps={{
+        forms: (rows ?? []) as never,
+        isLoading,
+        bin: bin as never,
+        createForm: (input) => create(input as never),
+        duplicateForm: (input) => copy(input as never),
+        deleteForm: (input) => remove(input as never),
+        restoreForm: (input) => restore(input as never),
+        purgeForm: (input) => purge(input as never),
+        getFormUsage: (input) => usage(input as never),
+        refresh,
+        LinkComponent: HostLink as never,
+      }}
+    />
+  );
+}
+
+/** Form editor for a single form key. */
+export function FormEditorRoute() {
+  const forms = requireHostGroup("forms");
+  const { fns } = backofficeHost();
+  const params = useParams({ strict: false }) as { key?: string };
+  const key = params.key ?? "";
+
+  const list = useServerFn(fns.listForms);
+  const save = useServerFn(forms.fns.saveForm);
+  const sync = useServerFn(forms.fns.syncSubmissionsToSheet);
+  const dup = useServerFn(forms.fns.duplicateForm);
+  const pingWebhook = useServerFn(forms.fns.testWebhook);
+  const loadDefaults = useServerFn(fns.getFormDefaults);
+
+  const { data: rows, isLoading } = useQuery({
+    queryKey: ["backoffice-forms"],
+    queryFn: () => list(),
+  });
+  const { data: defaults } = useQuery({
+    queryKey: ["form-defaults"],
+    queryFn: () => loadDefaults(),
+  });
+  const form = useMemo(
+    () => ((rows ?? []) as { key: string }[]).find((f) => f.key === key),
+    [rows, key],
+  );
+
+  const C = forms.components;
+  return (
+    <FormEditorView
+      deps={{
+        form: form as never,
+        defaults: defaults as never,
+        isLoading,
+        saveForm: (input) => save(input as never),
+        duplicateForm: (input) => dup(input as never),
+        syncSubmissions: (input) => sync(input as never),
+        testWebhook: (input) => pingWebhook(input as never),
+        LinkComponent: HostLink as never,
+        FieldEditorComponent: C.FieldEditor,
+        FormPreviewComponent: C.FormPreview,
+        TestDeliveryPanelComponent: C.TestDeliveryPanel,
+        VersionHistoryComponent: C.VersionHistory,
+        ActivityLogComponent: C.ActivityLog,
+      }}
+    />
+  );
+}
+
+type SubmissionSearch = {
+  form?: string;
+  status?: string;
+  locale?: string;
+  q?: string;
+  from?: string;
+  to?: string;
+  page?: number;
+};
+
+/** Validator a site route reuses for the submissions screen search params. */
+export function validateSubmissionSearch(search: Record<string, unknown>): SubmissionSearch {
+  const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
+  return {
+    form: str(search.form),
+    status: str(search.status),
+    locale: str(search.locale),
+    q: str(search.q),
+    from: str(search.from),
+    to: str(search.to),
+    page: typeof search.page === "number" ? search.page : undefined,
+  };
+}
+
+/** Submission inbox with filters, paging, exports and delivery retries. */
+export function FormSubmissionsRoute() {
+  const forms = requireHostGroup("forms");
+  const host = backofficeHost();
+  const paths = backofficePaths(host);
+  const search = useSearch({ strict: false }) as SubmissionSearch;
+  const navigate = useNavigate();
+  const qc = useQueryClient();
+
+  const listF = useServerFn(host.fns.listForms);
+  const listS = useServerFn(forms.fns.listSubmissions);
+  const setStatus = useServerFn(forms.fns.setSubmissionStatus);
+  const push = useServerFn(forms.fns.pushSubmissionsToSheet);
+  const resend = useServerFn(forms.fns.resendDelivery);
+  const partials = useServerFn(forms.fns.listPartials);
+  const removePartials = useServerFn(forms.fns.deletePartials);
+
+  const page = search.page ?? 0;
+  const go = (next: SubmissionSearch) => navigate({ search: next as never });
+
+  const { data: rows } = useQuery({ queryKey: ["backoffice-forms"], queryFn: () => listF() });
+  const { data, isLoading, isFetching } = useQuery({
+    queryKey: ["form-submissions", search],
+    queryFn: () =>
+      listS({
+        data: {
+          formKey: search.form,
+          status: search.status,
+          locale: search.locale,
+          search: search.q,
+          from: search.from,
+          to: search.to,
+          page,
+          pageSize: SUBMISSIONS_PAGE_SIZE,
+          sort: "newest",
+        },
+      }),
+  });
+
+  return (
+    <FormSubmissionsView
+      deps={{
+        filters: search as never,
+        setFilters: (patch) => go({ ...search, ...(patch as SubmissionSearch), page: 0 }),
+        clearFilters: () => go({}),
+        goToPage: (next) => go({ ...search, page: next }),
+        data: data as never,
+        isLoading,
+        isFetching,
+        forms: ((rows ?? []) as { key: string; name: unknown; fields: unknown }[]).map((f) => ({
+          key: f.key,
+          name: f.name,
+          fields: f.fields,
+        })) as never,
+        locales: host.locales as never,
+        refresh: () => qc.invalidateQueries({ queryKey: ["form-submissions"] }),
+        setStatus: (input) => setStatus(input as never),
+        pushToSheet: (input) => push(input as never),
+        resendDelivery: (input) => resend(input as never),
+        listPartials: (input) => partials(input as never),
+        deletePartials: (input) => removePartials(input as never),
+        BackLink: ({ className, children }) => (
+          <HostLink to={paths.forms} className={className}>
+            {children}
+          </HostLink>
+        ),
+      }}
+    />
+  );
+}
+
+/** Delivery attempt dashboard (retry / resolve failed notifications). */
+export function FormDeliveriesRoute() {
+  const forms = requireHostGroup("forms");
+  const host = backofficeHost();
+  const paths = backofficePaths(host);
+
+  const list = useServerFn(forms.fns.listDeliveryAttempts);
+  const formsFn = useServerFn(host.fns.listForms);
+  const retry = useServerFn(forms.fns.retryDeliveryAttempts);
+  const resolve = useServerFn(forms.fns.resolveDeliveryAttempts);
+
+  const [filters, setFiltersState] = useState<{
+    formKey: string;
+    channel: "" | DeliveryChannel;
+    state: "open" | "resolved" | "all";
+  }>({ formKey: "", channel: "", state: "open" });
+
+  const { data: formList } = useQuery({
+    queryKey: ["backoffice-forms"],
+    queryFn: () => formsFn(),
+  });
+  const { data, isLoading, refetch } = useQuery({
+    queryKey: ["form-deliveries", filters],
+    queryFn: () =>
+      list({
+        data: {
+          formKey: filters.formKey || undefined,
+          channel: filters.channel || undefined,
+          state: filters.state,
+          limit: 100,
+        },
+      }),
+  });
+
+  return (
+    <FormDeliveriesView
+      deps={{
+        data: data as never,
+        isLoading,
+        forms: ((formList ?? []) as { key: string; name: unknown }[]).map((f) => ({
+          key: f.key,
+          name: f.name,
+        })) as never,
+        filters,
+        setFilters: (patch) => setFiltersState((prev) => ({ ...prev, ...patch })),
+        refetch: () => refetch(),
+        retryAttempts: (input) => retry(input as never),
+        resolveAttempts: (input) => resolve(input as never),
+        BackLink: ({ className, children }) => (
+          <HostLink to={paths.forms} className={className}>
+            {children}
+          </HostLink>
+        ),
+      }}
+    />
+  );
+}