@bygghammar/cms-platform 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to `@bygghammar/cms-platform`.
+
+The package follows semver with the pre-1.0 convention that a **minor** bump may
+contain breaking changes to shared views, adapters or cores; patch releases are
+always compatible. In addition, `PLATFORM_CONTRACT_VERSION` in
+`platform/contract` is bumped whenever a shared screen starts requiring schema
+or adapter capabilities an older site does not have. Sites assert that constant
+in a test and upgrade deliberately.
+
+## 0.23.0
+
+- Added `config/site-config`: the typed `SiteConfig` contract, `defineSiteConfig`
+  validation, feature flags, the overridable-key whitelist and
+  `resolveSiteConfig` (code defaults + database overrides).
+- Added `server/site-settings-core`: load/save/clear for the `site_settings`
+  key/value store, running as the caller so RLS applies.
+- Added `backoffice/SiteSettingsView`: shared site settings screen for name,
+  company details, module flags and brand tokens, with per-section reset back to
+  the code default.
+
+## 0.22.0
+
+- Added `docs/NEW-SITE.md`: the supported starter path for a new site (install,
+  contract assertion, migrations, theme, host registration, server cores,
+  backoffice routes, verification).
+- Added this changelog and a written compatibility policy.
+- Added the `cms-platform-migrations` bin, which copies missing canonical
+  migrations into a site's migration directory without overwriting or deleting
+  anything.
+- Removed five Voyara-specific content/data migrations from the canonical set
+  (SEO copy, a homepage block seed, a locale-domain update, a booking-link
+  rewrite and the content seed). Canonical migrations are schema only; site
+  content stays in the site's own migration directory. Existing sites keep
+  those files locally and remain compatible.
+- No runtime source changes; safe upgrade from 0.21.x.
+
+## 0.21.0
+
+- Added `server/forms-core`: host-agnostic forms server rules — effective
+  settings, recipient routing, notification templates, submitter detection,
+  field-removal safety, version snapshots, audit trail and the list/save/delete/
+  restore/purge/duplicate cores plus site defaults, usage and delivery logging.
+
+## 0.20.0
+
+- Added `server/media-usage-core` (usage scan, remote media import, reference
+  rewriting) and completed `server/media-cleanup-core`.
+
+## 0.19.0
+
+- Added `server/guards`, `server/redirects-core` and `server/page-seo-core`.
+
+## 0.18.0
+
+- Extracted `FormEditorView`, `FormsIndexView` and `RedirectsView`.
+
+## 0.17.0
+
+- Extracted the media library UI, including client-side optimisation and usage
+  inspection.
+
+## 0.15.0 – 0.16.0
+
+- Extracted `SectionFormView` and `PageEditorView`.
+
+## 0.14.0
+
+- Expanded the `PlatformData` host contract to every backoffice module and added
+  `assertPlatformData` / `REQUIRED_PLATFORM_DATA`.
+
+## 0.12.0 – 0.13.0
+
+- Extracted `ReviewImageUpload` and `PageSeoPanel`.
+
+## 0.5.0 – 0.11.0
+
+- Phase 1 and 2: pure forms/media/http/i18n helpers, backup core, trips and
+  navigation contracts, and the first host contract.
+- Phase 5 groundwork: canonical migrations shipped under `migrations/` with
+  `SCHEMA_MIGRATIONS` and `PLATFORM_CONTRACT_VERSION`.
+
+## 0.1.0
+
+- First release: blocks, block types, icons, i18n core, UI primitives and the
+  `theme.css` design-token contract.

package/README.md

@@ -18,6 +18,24 @@ future sites). **Code only** — no content, no data, no secrets, no theme.
   active-state helpers. Menu content and visual headers remain per-site.
 - `src/theme.css` — the design-token contract + neutral starter theme
 
+## Starting a new site
+
+`docs/NEW-SITE.md` is the supported starter path: install, assert the contract,
+apply the canonical schema with `bunx cms-platform-migrations`, import
+`theme.css`, register host components / platform data / translations, wrap the
+server cores and mount the shared backoffice views.
+
+## Compatibility policy
+
+- `CHANGELOG.md` records every release; read it before upgrading.
+- Pre-1.0, a **minor** release may break shared views, adapters or cores; patch
+  releases are always compatible.
+- `PLATFORM_CONTRACT_VERSION` (`platform/contract`) is bumped when a shared
+  screen starts requiring schema or adapter capabilities an older site lacks.
+  Sites pin it in a test.
+- `migrations/` is schema only. Site content, SEO copy and seeds never belong
+  there.
+
 ## What must never live here
 
 - colours, fonts or spacing values used by a specific site (see `theme.css`)

package/docs/NEW-SITE.md

@@ -0,0 +1,103 @@
+# Starting a new site on @bygghammar/cms-platform
+
+This is the supported path from an empty TanStack Start project to a working
+CMS site. Every step is code or configuration in the new site; nothing here
+copies content, media or secrets between sites.
+
+## 0. Prerequisites
+
+- TanStack Start v1 (React 19, Vite 7), Tailwind v4, shadcn/ui.
+- A Supabase-compatible backend for the site (its own project/stack — never
+  shared with another site, never a production database during authoring).
+
+## 1. Install
+
+```bash
+bun add @bygghammar/cms-platform@<exact version>
+```
+
+Pin an exact version and commit the lockfile. Read `CHANGELOG.md` before every
+upgrade.
+
+## 2. Assert the contract
+
+```ts
+import {
+  PLATFORM_CONTRACT_VERSION,
+  SCHEMA_MIGRATIONS,
+  assertPlatformContract,
+  missingMigrations,
+} from "@bygghammar/cms-platform/platform/contract";
+```
+
+Add one test that pins the contract version the site was built against and one
+that asserts `missingMigrations(appliedFilenames)` is empty. See
+`tests/platform-contract.test.ts` in any existing site for the exact shape.
+
+## 3. Apply the canonical schema
+
+The package ships the canonical migrations under `migrations/`, oldest first.
+
+```bash
+bunx cms-platform-migrations ./supabase/migrations
+```
+
+The command copies any migration the target directory is missing and never
+overwrites or deletes a file, so it is safe to re-run after an upgrade. Apply
+the copied files with the site's normal migration tooling. Site-specific
+migrations live alongside them with later timestamps and must stay additive.
+
+## 4. Theme
+
+```css
+/* src/styles.css */
+@import "@bygghammar/cms-platform/theme.css";
+```
+
+Then override the design tokens for the new brand in the site's own layer.
+Never edit colours, fonts or spacing inside the package.
+
+## 5. Register the host
+
+Three registrations, all at startup:
+
+- **Host components** — `registerHostComponents()` from
+  `@bygghammar/cms-platform/host` for the site's link, image, video and rich
+  text primitives.
+- **Platform data adapter** — `registerHostPlatform({ data, site })` from
+  `@bygghammar/cms-platform/platform`. `data` implements every member in
+  `REQUIRED_PLATFORM_DATA` (pages, versions, global sections, media, SEO,
+  redirects, forms); `site` describes name, `backofficeBasePath` and locales.
+  Guard it with a test that calls `assertPlatformData`.
+- **Translations** — the site's own `sv`/`en` maps via the i18n register
+  module. Translation data is content and stays in the site.
+
+## 6. Server functions
+
+Wrap the shared server cores in the site's own `createServerFn` files:
+
+| Package core | Purpose |
+| --- | --- |
+| `server/guards` | `assertStaff`, `assertSuperadmin` |
+| `server/forms-core` | form definitions, versions, settings, delivery log |
+| `server/redirects-core` | path normalisation and redirect writes |
+| `server/page-seo-core` | slug conflicts and slug-change 301s |
+| `server/media-usage-core` | usage scan and remote import |
+| `server/media-cleanup-core` | duplicate/rename planning and apply |
+
+The site supplies clients, storage and page-key → path maps; the package owns
+the rules. Keep privileged clients inside handlers.
+
+## 7. Backoffice routes
+
+Each backoffice route is a thin adapter around the package view
+(`PageEditorView`, `MediaLibraryView`, `FormEditorView`, `FormsIndexView`,
+`RedirectsView`, `SectionFormView`, `PageSeoPanel`). Routes own the path and
+auth gate only.
+
+## 8. Verify
+
+1. Types pass.
+2. Full test suite passes, including the contract tests from step 2.
+3. `/` renders.
+4. The backoffice signs in, and one page, one form and one media asset save.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.21.0",
+  "version": "0.23.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,
@@ -10,7 +10,10 @@
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
+    "docs",
     "migrations",
+    "scripts",
     "src"
   ],
   "repository": {
@@ -109,7 +112,10 @@
     "./server/page-seo-core": "./src/server/page-seo-core.ts",
     "./server/media-cleanup-core": "./src/server/media-cleanup-core.ts",
     "./server/media-usage-core": "./src/server/media-usage-core.ts",
-    "./server/forms-core": "./src/server/forms-core.ts"
+    "./server/forms-core": "./src/server/forms-core.ts",
+    "./config/site-config": "./src/config/site-config.ts",
+    "./server/site-settings-core": "./src/server/site-settings-core.ts",
+    "./backoffice/SiteSettingsView": "./src/backoffice/SiteSettingsView.tsx"
   },
   "dependencies": {
     "fflate": "^0.8.3"
@@ -181,5 +187,8 @@
     "@tiptap/extension-table": {
       "optional": true
     }
+  },
+  "bin": {
+    "cms-platform-migrations": "scripts/sync-migrations.mjs"
   }
-}
+}

package/scripts/sync-migrations.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Copy canonical platform migrations into a site's migration directory.
+ *
+ * Additive only: a file that already exists in the target is left untouched and
+ * nothing is ever deleted or overwritten, so this is safe to re-run after an
+ * upgrade.
+ *
+ * Usage: cms-platform-migrations [targetDir] [--check]
+ *   targetDir defaults to ./supabase/migrations
+ *   --check exits non-zero when files are missing instead of copying them
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = resolve(here, "..", "migrations");
+
+const args = process.argv.slice(2);
+const checkOnly = args.includes("--check");
+const target = resolve(args.find((a) => !a.startsWith("--")) ?? "supabase/migrations");
+
+if (!existsSync(source)) {
+  console.error(`No migrations directory in the package at ${source}`);
+  process.exit(1);
+}
+
+const canonical = readdirSync(source)
+  .filter((f) => f.endsWith(".sql"))
+  .sort();
+
+const present = new Set(existsSync(target) ? readdirSync(target) : []);
+const missing = canonical.filter((f) => !present.has(f));
+
+if (missing.length === 0) {
+  console.log(`Up to date: ${canonical.length} canonical migrations already present.`);
+  process.exit(0);
+}
+
+if (checkOnly) {
+  console.error(`Missing ${missing.length} canonical migrations:`);
+  for (const f of missing) console.error(`  ${f}`);
+  process.exit(1);
+}
+
+mkdirSync(target, { recursive: true });
+for (const f of missing) copyFileSync(join(source, f), join(target, f));
+console.log(`Copied ${missing.length} migration(s) into ${target}. Apply them with your migration tooling.`);

package/src/backoffice/SiteSettingsView.tsx

@@ -0,0 +1,258 @@
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+import { Save, RotateCcw } from "lucide-react";
+
+import {
+  DEFAULT_FEATURE_FLAGS,
+  EMPTY_COMPANY,
+  type SiteConfig,
+  type SiteFeatureFlags,
+  type SiteSettingOverrides,
+} from "../config/site-config";
+
+export type SiteSettingsDeps = {
+  /** Code config with any stored overrides already applied. */
+  config: SiteConfig;
+  /** Raw stored overrides, used to show what differs from code. */
+  overrides: SiteSettingOverrides;
+  saveSettings: (input: { data: SiteSettingOverrides }) => Promise<unknown>;
+  clearSetting: (input: { data: { key: string } }) => Promise<unknown>;
+  refresh: () => Promise<unknown> | void;
+};
+
+const FEATURE_LABELS: Record<keyof SiteFeatureFlags, string> = {
+  trips: "Trips & departures",
+  courses: "Courses",
+  reviews: "Reviews",
+  email: "Transactional email",
+  tracking: "Code & tracking",
+  backup: "Backup & restore",
+  domains: "Custom domains",
+  forms: "Forms",
+};
+
+const COMPANY_LABELS: Record<keyof typeof EMPTY_COMPANY, string> = {
+  legalName: "Legal name",
+  locationName: "Location name",
+  street: "Street",
+  postCode: "Post code",
+  city: "City",
+  country: "Country",
+  orgNumber: "Org. number",
+  email: "Email",
+  phone: "Phone",
+};
+
+const inputClass =
+  "w-full border border-ink/15 bg-white px-3 py-2 text-sm text-ink focus:border-sea focus:outline-none";
+const labelClass = "block text-xs uppercase tracking-wider text-ink/60 mb-1";
+const cardClass = "border border-ink/10 bg-white p-6";
+
+/**
+ * Host-agnostic site settings screen. Code config is always the baseline; this
+ * screen writes only the overridable subset into the database.
+ */
+export function SiteSettingsView({ deps }: { deps: SiteSettingsDeps }) {
+  const { config, overrides, saveSettings, clearSetting, refresh } = deps;
+  const [name, setName] = useState(config.name);
+  const [company, setCompany] = useState({ ...EMPTY_COMPANY, ...config.company });
+  const [features, setFeatures] = useState<SiteFeatureFlags>({ ...config.features });
+  const [brand, setBrand] = useState<Record<string, string>>({ ...config.brand });
+  const [busy, setBusy] = useState<string | null>(null);
+
+  useEffect(() => {
+    setName(config.name);
+    setCompany({ ...EMPTY_COMPANY, ...config.company });
+    setFeatures({ ...config.features });
+    setBrand({ ...config.brand });
+  }, [config]);
+
+  const save = async (key: string, patch: SiteSettingOverrides) => {
+    setBusy(key);
+    try {
+      await saveSettings({ data: patch });
+      toast.success("Saved");
+      await refresh();
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Failed to save");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const reset = async (key: string) => {
+    setBusy(key);
+    try {
+      await clearSetting({ data: { key } });
+      toast.success("Reset to the value defined in code");
+      await refresh();
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Failed to reset");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const overridden = (key: keyof SiteSettingOverrides) => overrides[key] !== undefined;
+
+  return (
+    <div className="p-8 md:p-12 w-full">
+      <h1 className="font-serif text-3xl md:text-4xl text-ink">Site settings</h1>
+      <p className="mt-3 max-w-2xl text-sm text-ink/60">
+        These values come from the site configuration in code. Anything you change here is stored as
+        an override in the database and can be reset back to the code default.
+      </p>
+
+      <dl className="mt-8 grid gap-4 md:grid-cols-4">
+        {[
+          ["Site key", config.key],
+          ["Public origin", config.origin],
+          ["Locales", config.locales.join(", ")],
+          ["Backoffice", `${config.backofficePath} (${config.backofficeLocale})`],
+        ].map(([label, value]) => (
+          <div key={label} className="border border-ink/10 bg-white p-4">
+            <dt className="text-xs uppercase tracking-wider text-ink/50">{label}</dt>
+            <dd className="mt-1 text-sm text-ink">{value}</dd>
+          </div>
+        ))}
+      </dl>
+
+      <section className={`mt-8 ${cardClass}`}>
+        <SectionHeader
+          title="Site name"
+          overridden={overridden("name")}
+          onReset={() => reset("name")}
+          busy={busy === "name"}
+        />
+        <div className="mt-4 grid gap-3 md:grid-cols-[1fr_auto] md:items-end">
+          <label className="block">
+            <span className={labelClass}>Name</span>
+            <input className={inputClass} value={name} onChange={(e) => setName(e.target.value)} />
+          </label>
+          <SaveButton busy={busy === "name"} onClick={() => save("name", { name })} />
+        </div>
+      </section>
+
+      <section className={`mt-6 ${cardClass}`}>
+        <SectionHeader
+          title="Company & contact details"
+          overridden={overridden("company")}
+          onReset={() => reset("company")}
+          busy={busy === "company"}
+        />
+        <div className="mt-4 grid gap-3 md:grid-cols-3">
+          {(Object.keys(COMPANY_LABELS) as (keyof typeof EMPTY_COMPANY)[]).map((key) => (
+            <label key={key} className="block">
+              <span className={labelClass}>{COMPANY_LABELS[key]}</span>
+              <input
+                className={inputClass}
+                value={company[key] ?? ""}
+                onChange={(e) => setCompany({ ...company, [key]: e.target.value })}
+              />
+            </label>
+          ))}
+        </div>
+        <div className="mt-4">
+          <SaveButton busy={busy === "company"} onClick={() => save("company", { company })} />
+        </div>
+      </section>
+
+      <section className={`mt-6 ${cardClass}`}>
+        <SectionHeader
+          title="Modules"
+          overridden={overridden("features")}
+          onReset={() => reset("features")}
+          busy={busy === "features"}
+        />
+        <div className="mt-4 grid gap-3 md:grid-cols-2">
+          {(Object.keys(DEFAULT_FEATURE_FLAGS) as (keyof SiteFeatureFlags)[]).map((flag) => (
+            <label key={flag} className="flex items-center gap-3 text-sm text-ink">
+              <input
+                type="checkbox"
+                checked={features[flag]}
+                onChange={(e) => setFeatures({ ...features, [flag]: e.target.checked })}
+              />
+              {FEATURE_LABELS[flag]}
+            </label>
+          ))}
+        </div>
+        <div className="mt-4">
+          <SaveButton busy={busy === "features"} onClick={() => save("features", { features })} />
+        </div>
+      </section>
+
+      {Object.keys(brand).length > 0 && (
+        <section className={`mt-6 ${cardClass}`}>
+          <SectionHeader
+            title="Brand tokens"
+            overridden={overridden("brand")}
+            onReset={() => reset("brand")}
+            busy={busy === "brand"}
+          />
+          <div className="mt-4 grid gap-3 md:grid-cols-3">
+            {Object.keys(brand).map((token) => (
+              <label key={token} className="block">
+                <span className={labelClass}>{token}</span>
+                <div className="flex items-center gap-2">
+                  <span
+                    className="size-8 shrink-0 border border-ink/15"
+                    style={{ background: brand[token] }}
+                  />
+                  <input
+                    className={inputClass}
+                    value={brand[token] ?? ""}
+                    onChange={(e) => setBrand({ ...brand, [token]: e.target.value })}
+                  />
+                </div>
+              </label>
+            ))}
+          </div>
+          <div className="mt-4">
+            <SaveButton busy={busy === "brand"} onClick={() => save("brand", { brand })} />
+          </div>
+        </section>
+      )}
+    </div>
+  );
+}
+
+function SectionHeader({
+  title,
+  overridden,
+  onReset,
+  busy,
+}: {
+  title: string;
+  overridden: boolean;
+  onReset: () => void;
+  busy: boolean;
+}) {
+  return (
+    <div className="flex items-center justify-between gap-4">
+      <h2 className="font-serif text-xl text-ink">{title}</h2>
+      {overridden && (
+        <button
+          type="button"
+          onClick={onReset}
+          disabled={busy}
+          className="inline-flex items-center gap-2 border border-ink/15 px-3 py-1.5 text-xs uppercase tracking-wider text-ink/70 hover:border-sea disabled:opacity-50"
+        >
+          <RotateCcw className="size-3.5" /> Reset to code default
+        </button>
+      )}
+    </div>
+  );
+}
+
+function SaveButton({ busy, onClick }: { busy: boolean; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={busy}
+      className="inline-flex items-center gap-2 bg-ink px-4 py-2 text-xs uppercase tracking-wider text-white hover:bg-sea disabled:opacity-50"
+    >
+      <Save className="size-4" /> {busy ? "Saving…" : "Save"}
+    </button>
+  );
+}