@bygghammar/cms-platform 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -9,6 +9,17 @@ always compatible. In addition, `PLATFORM_CONTRACT_VERSION` in
 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "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,
@@ -112,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"

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>
+  );
+}

package/src/config/site-config.ts

@@ -0,0 +1,239 @@
+/**
+ * Site configuration contract (Phase 1 of the stand-alone CMS work).
+ *
+ * A site describes itself once, in code, with `defineSiteConfig`. A subset of
+ * those values may be overridden at runtime from the `site_settings` table so
+ * non-developers can change them in the backoffice. Shared platform code reads
+ * the resolved config instead of hardcoding a site name, locale set, backoffice
+ * path or feature set.
+ */
+
+/** Feature modules a site can switch on. Unknown flags are ignored. */
+export type SiteFeatureFlags = {
+  /** Trips / departures module (`/kontoret/trips`). */
+  trips: boolean;
+  /** Courses module (`/kontoret/kurser`). */
+  courses: boolean;
+  /** Reviews module (`/kontoret/recensioner`). */
+  reviews: boolean;
+  /** Transactional email + provider settings screens. */
+  email: boolean;
+  /** Head/body code injection and analytics pixels. */
+  tracking: boolean;
+  /** Backup & restore tooling (superadmin only). */
+  backup: boolean;
+  /** Custom domain management screen. */
+  domains: boolean;
+  /** Public forms module. */
+  forms: boolean;
+};
+
+export const DEFAULT_FEATURE_FLAGS: SiteFeatureFlags = {
+  trips: false,
+  courses: false,
+  reviews: false,
+  email: true,
+  tracking: true,
+  backup: true,
+  domains: false,
+  forms: true,
+};
+
+/** Official company / contact details. Locale-neutral by design. */
+export type SiteCompany = {
+  legalName: string;
+  locationName: string;
+  street: string;
+  postCode: string;
+  city: string;
+  country: string;
+  orgNumber: string;
+  email: string;
+  phone: string;
+};
+
+export const EMPTY_COMPANY: SiteCompany = {
+  legalName: "",
+  locationName: "",
+  street: "",
+  postCode: "",
+  city: "",
+  country: "",
+  orgNumber: "",
+  email: "",
+  phone: "",
+};
+
+/** Brand design tokens. Values are CSS colors written into the theme contract. */
+export type SiteBrandTokens = Record<string, string>;
+
+/** Serializable per-site extras. Kept primitive so the config can cross RPC. */
+export type SiteExtra = Record<string, string | number | boolean | null>;
+
+export type SiteConfigInput = {
+  /** Machine key, e.g. "voyara". Lowercase, no spaces. */
+  key: string;
+  /** Display name used in the backoffice and default SEO titles. */
+  name: string;
+  /** Canonical public origin, without a trailing slash. */
+  origin: string;
+  /** Locales the public site serves, most important first. */
+  locales: readonly string[];
+  /** Locale used when nothing else matches. Must be in `locales`. */
+  defaultLocale: string;
+  /** Path the backoffice is mounted at, e.g. "/kontoret". */
+  backofficePath?: string;
+  /** UI language of the backoffice itself. */
+  backofficeLocale?: string;
+  company?: Partial<SiteCompany>;
+  brand?: SiteBrandTokens;
+  features?: Partial<SiteFeatureFlags>;
+  /** Optional free-form per-site extras shared code never reads. */
+  extra?: SiteExtra;
+};
+
+export type SiteConfig = {
+  key: string;
+  name: string;
+  origin: string;
+  locales: readonly string[];
+  defaultLocale: string;
+  backofficePath: string;
+  backofficeLocale: string;
+  company: SiteCompany;
+  brand: SiteBrandTokens;
+  features: SiteFeatureFlags;
+  extra: SiteExtra;
+};
+
+function fail(message: string): never {
+  throw new Error(`@bygghammar/cms-platform: invalid site config — ${message}`);
+}
+
+/** Validate and normalize a site config. Throws on anything unusable. */
+export function defineSiteConfig(input: SiteConfigInput): SiteConfig {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(input.key)) fail(`key "${input.key}" must be kebab-case`);
+  if (!input.name.trim()) fail("name is required");
+  if (!/^https?:\/\/[^/]+$/.test(input.origin)) {
+    fail(`origin "${input.origin}" must be an absolute URL without a path`);
+  }
+  if (!input.locales.length) fail("at least one locale is required");
+  if (!input.locales.includes(input.defaultLocale)) {
+    fail(`defaultLocale "${input.defaultLocale}" is not listed in locales`);
+  }
+  const backofficePath = input.backofficePath ?? "/kontoret";
+  if (!backofficePath.startsWith("/") || backofficePath.endsWith("/")) {
+    fail(`backofficePath "${backofficePath}" must start with "/" and not end with one`);
+  }
+  return {
+    key: input.key,
+    name: input.name.trim(),
+    origin: input.origin.replace(/\/$/, ""),
+    locales: [...input.locales],
+    defaultLocale: input.defaultLocale,
+    backofficePath,
+    backofficeLocale: input.backofficeLocale ?? "en",
+    company: { ...EMPTY_COMPANY, ...(input.company ?? {}) },
+    brand: { ...(input.brand ?? {}) },
+    features: { ...DEFAULT_FEATURE_FLAGS, ...(input.features ?? {}) },
+    extra: { ...(input.extra ?? {}) },
+  };
+}
+
+/**
+ * Keys the backoffice may override from the database. Everything else is
+ * code-only on purpose: routing, locale set and origin must be deployable and
+ * reviewable, not editable at runtime.
+ */
+export const OVERRIDABLE_SETTING_KEYS = [
+  "name",
+  "company",
+  "brand",
+  "features",
+] as const satisfies readonly (keyof SiteConfig)[];
+
+export type OverridableSettingKey = (typeof OVERRIDABLE_SETTING_KEYS)[number];
+
+/** Stored override rows, keyed by `OverridableSettingKey`. */
+export type SiteSettingOverrides = Partial<{
+  name: string;
+  company: Partial<SiteCompany>;
+  brand: SiteBrandTokens;
+  features: Partial<SiteFeatureFlags>;
+}>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Narrow an untrusted settings payload to the overridable subset. */
+export function parseSiteSettingOverrides(raw: unknown): SiteSettingOverrides {
+  if (!isRecord(raw)) return {};
+  const out: SiteSettingOverrides = {};
+  if (typeof raw["name"] === "string" && raw["name"].trim()) out.name = raw["name"].trim();
+  if (isRecord(raw["company"])) {
+    const company: Partial<SiteCompany> = {};
+    for (const key of Object.keys(EMPTY_COMPANY) as (keyof SiteCompany)[]) {
+      const value = (raw["company"] as Record<string, unknown>)[key];
+      if (typeof value === "string") company[key] = value;
+    }
+    out.company = company;
+  }
+  if (isRecord(raw["brand"])) {
+    const brand: SiteBrandTokens = {};
+    for (const [key, value] of Object.entries(raw["brand"])) {
+      if (typeof value === "string") brand[key] = value;
+    }
+    out.brand = brand;
+  }
+  if (isRecord(raw["features"])) {
+    const features: Partial<SiteFeatureFlags> = {};
+    for (const key of Object.keys(DEFAULT_FEATURE_FLAGS) as (keyof SiteFeatureFlags)[]) {
+      const value = (raw["features"] as Record<string, unknown>)[key];
+      if (typeof value === "boolean") features[key] = value;
+    }
+    out.features = features;
+  }
+  return out;
+}
+
+/** Layer database overrides over the code config. Code stays the fallback. */
+export function resolveSiteConfig(base: SiteConfig, overrides: unknown): SiteConfig {
+  const parsed = parseSiteSettingOverrides(overrides);
+  return {
+    ...base,
+    name: parsed.name ?? base.name,
+    company: { ...base.company, ...(parsed.company ?? {}) },
+    brand: { ...base.brand, ...(parsed.brand ?? {}) },
+    features: { ...base.features, ...(parsed.features ?? {}) },
+  };
+}
+
+/** True when a feature module is enabled for the resolved config. */
+export function isFeatureEnabled(config: SiteConfig, flag: keyof SiteFeatureFlags): boolean {
+  return config.features[flag] === true;
+}
+
+/** Build a backoffice URL from the configured mount path. */
+export function backofficeUrl(config: SiteConfig, subpath = ""): string {
+  if (!subpath) return config.backofficePath;
+  return `${config.backofficePath}/${subpath.replace(/^\//, "")}`;
+}
+
+let active: SiteConfig | null = null;
+
+/** Register the resolved site config once at startup. */
+export function registerSiteConfig(config: SiteConfig): SiteConfig {
+  active = config;
+  return config;
+}
+
+/** Read the registered site config. Throws when a site forgot to register. */
+export function siteConfig(): SiteConfig {
+  if (!active) {
+    throw new Error(
+      "@bygghammar/cms-platform: no site config registered. Call registerSiteConfig(defineSiteConfig({...})) during startup.",
+    );
+  }
+  return active;
+}

package/src/server/site-settings-core.ts

@@ -0,0 +1,66 @@
+/**
+ * Host-agnostic core for the `site_settings` key/value store.
+ *
+ * Rows are `{ key, value jsonb }` where `key` is one of
+ * `OVERRIDABLE_SETTING_KEYS`. Reads use whatever client the host passes
+ * (publishable client for the public site, authenticated client in the
+ * backoffice); writes always run as the signed-in staff user so RLS applies.
+ */
+
+import {
+  OVERRIDABLE_SETTING_KEYS,
+  parseSiteSettingOverrides,
+  type OverridableSettingKey,
+  type SiteSettingOverrides,
+} from "../config/site-config";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Client = {
+  from: (table: string) => any;
+};
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export const SITE_SETTINGS_TABLE = "site_settings";
+
+/** Load every stored override, narrowed to the overridable subset. */
+export async function loadSiteSettingsCore(client: Client): Promise<SiteSettingOverrides> {
+  const { data, error } = await client.from(SITE_SETTINGS_TABLE).select("key, value");
+  if (error) throw new Error(error.message);
+  const raw: Record<string, unknown> = {};
+  for (const row of (data ?? []) as Array<{ key: string; value: unknown }>) {
+    if ((OVERRIDABLE_SETTING_KEYS as readonly string[]).includes(row.key)) raw[row.key] = row.value;
+  }
+  return parseSiteSettingOverrides(raw);
+}
+
+/**
+ * Upsert the provided override keys. Keys absent from `patch` are untouched, so
+ * a screen can save one section without clobbering another.
+ */
+export async function saveSiteSettingsCore(
+  client: Client,
+  patch: SiteSettingOverrides,
+  actorId?: string | null,
+): Promise<SiteSettingOverrides> {
+  const clean = parseSiteSettingOverrides(patch);
+  const rows = (Object.keys(clean) as OverridableSettingKey[]).map((key) => ({
+    key,
+    value: clean[key] as unknown,
+    updated_by: actorId ?? null,
+    updated_at: new Date().toISOString(),
+  }));
+  if (rows.length) {
+    const { error } = await client.from(SITE_SETTINGS_TABLE).upsert(rows, { onConflict: "key" });
+    if (error) throw new Error(error.message);
+  }
+  return loadSiteSettingsCore(client);
+}
+
+/** Remove one override so the code default takes over again. */
+export async function clearSiteSettingCore(
+  client: Client,
+  key: OverridableSettingKey,
+): Promise<void> {
+  const { error } = await client.from(SITE_SETTINGS_TABLE).delete().eq("key", key);
+  if (error) throw new Error(error.message);
+}