modern-cms 1.0.0

package/template/apps/web/lib/useEntranceAnimation.ts

@@ -0,0 +1,245 @@
+"use client";
+
+import { useLayoutEffect, type RefObject } from "react";
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import type { NodeStyle } from "@pgcms/shared";
+
+let pluginRegistered = false;
+
+// One-shot reveal tweens — element starts at these values and animates to its natural
+// (pre-tween) state. Used for onLoad/onScroll.
+const FROM_VARS: Record<string, gsap.TweenVars> = {
+  fadeIn: { opacity: 0 },
+  slideUp: { opacity: 0, y: 40 },
+  slideDown: { opacity: 0, y: -40 },
+  slideLeft: { opacity: 0, x: 40 },
+  slideRight: { opacity: 0, x: -40 },
+  zoomIn: { opacity: 0, scale: 0.92 },
+  scrollReveal: { opacity: 0, y: 24 },
+  rotateIn: { opacity: 0, rotation: -12 },
+  pulse: { opacity: 0, scale: 0.9 },
+  blurIn: { opacity: 0, filter: "blur(14px)" },
+  flipIn: { opacity: 0, rotationX: -65, transformOrigin: "50% 0%" },
+  bounceIn: { opacity: 0, scale: 0.5, y: -40 },
+};
+
+// Effects whose motion only reads right with a specific ease — used as the default
+// when the user hasn't picked one explicitly.
+const EFFECT_DEFAULT_EASE: Record<string, string> = {
+  bounceIn: "bounce.out",
+  flipIn: "back.out(1.4)",
+};
+
+// Toggle tweens — element starts at its natural state and animates *to* these values;
+// used for onHover/onFocus (which reverse back out) and onClick (which restarts).
+const INTERACTIVE_VARS: Record<string, gsap.TweenVars> = {
+  fadeIn: { opacity: 0.55 },
+  slideUp: { y: -6 },
+  slideDown: { y: 6 },
+  slideLeft: { x: -6 },
+  slideRight: { x: 6 },
+  zoomIn: { scale: 1.05 },
+  scrollReveal: { y: -4 },
+  rotateIn: { rotation: -4 },
+  pulse: { scale: 1.08 },
+  blurIn: { opacity: 0.7, filter: "blur(2px)" },
+  flipIn: { rotationX: 8, transformOrigin: "50% 0%" },
+  bounceIn: { scale: 1.06 },
+};
+
+const INTERACTIVE_TRIGGERS = new Set(["onHover", "onFocus", "onClick"]);
+
+/** Universal animation for any rendered node — driven entirely by NodeStyle fields set
+ * from the Inspector, so no per-component-type wiring is needed. Applied only on the
+ * public renderer (see Renderer.tsx); the builder canvas renders nodes in their settled
+ * final state so editing stays stable. */
+export function useEntranceAnimation(ref: RefObject<HTMLElement | null>, style: NodeStyle) {
+  const {
+    animationType,
+    animationTrigger,
+    animationDuration,
+    animationDelay,
+    animationEasing,
+    animationLoop,
+    animationStagger,
+  } = style;
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || !animationType || animationType === "none") return;
+
+    if (!pluginRegistered) {
+      gsap.registerPlugin(ScrollTrigger);
+      pluginRegistered = true;
+    }
+
+    const trigger = animationTrigger ?? (animationType === "scrollReveal" ? "onScroll" : "onLoad");
+    const duration = animationDuration ?? 0.8;
+    const delay = animationDelay ?? 0;
+    const ease = animationEasing || EFFECT_DEFAULT_EASE[animationType] || "power2.out";
+
+    if (INTERACTIVE_TRIGGERS.has(trigger)) {
+      // A paused toggle tween never renders anything until played, so — unlike the
+      // one-shot "from" tweens below — React Strict Mode's dev-only double-invoke of
+      // this effect can't leave it in a half-animated state; plain kill() is enough.
+      const toVars = INTERACTIVE_VARS[animationType] ?? INTERACTIVE_VARS.fadeIn;
+      // onClick is a self-contained "tap" gesture — play forward then automatically back
+      // out, rather than needing a second click to undo it like hover/focus's reverse().
+      const tween = gsap.to(el, {
+        ...toVars,
+        duration,
+        ease,
+        paused: true,
+        ...(trigger === "onClick" ? { repeat: 1, yoyo: true } : {}),
+      });
+
+      let removeListeners = () => {};
+      if (trigger === "onHover") {
+        const enter = () => tween.play();
+        const leave = () => tween.reverse();
+        el.addEventListener("mouseenter", enter);
+        el.addEventListener("mouseleave", leave);
+        removeListeners = () => {
+          el.removeEventListener("mouseenter", enter);
+          el.removeEventListener("mouseleave", leave);
+        };
+      } else if (trigger === "onFocus") {
+        // focusin/focusout bubble from whichever focusable descendant (button, link,
+        // input) actually receives focus — the section itself doesn't need a tabindex.
+        const focusIn = () => tween.play();
+        const focusOut = () => tween.reverse();
+        el.addEventListener("focusin", focusIn);
+        el.addEventListener("focusout", focusOut);
+        removeListeners = () => {
+          el.removeEventListener("focusin", focusIn);
+          el.removeEventListener("focusout", focusOut);
+        };
+      } else {
+        const onClick = () => tween.restart();
+        el.addEventListener("click", onClick);
+        removeListeners = () => el.removeEventListener("click", onClick);
+      }
+
+      return () => {
+        removeListeners();
+        tween.kill();
+      };
+    }
+
+    // React 18 Strict Mode double-invokes effects on mount (create, cleanup, create
+    // again) purely as a dev-mode sanity check. `tween.kill()` alone doesn't undo the
+    // inline styles gsap.from() already applied, so the second invocation's "from" call
+    // would capture the barely-animated first tween's paused values as its target and
+    // visibly never move. `gsap.context().revert()` undoes those inline styles too, so
+    // the second invocation starts from the element's true original state.
+    const ctx = gsap.context(() => {
+      const fromVars = FROM_VARS[animationType] ?? FROM_VARS.fadeIn;
+      // With a stagger, reveal the section's inner items one after another instead of
+      // the whole block at once. The DOM depth of "the items" varies per component
+      // (cards in a grid, paragraphs in prose, buttons in a row), so find the densest
+      // shallow group: the element with the most direct children near the top.
+      const targets = animationStagger ? findStaggerTargets(el) : el;
+      gsap.from(targets, {
+        ...fromVars,
+        duration,
+        delay,
+        ease,
+        stagger: animationStagger || 0,
+        repeat: animationLoop ? -1 : 0,
+        yoyo: animationLoop || undefined,
+        scrollTrigger: trigger === "onScroll" ? { trigger: el, start: "top 85%", once: true } : undefined,
+      });
+    });
+
+    return () => ctx.revert();
+  }, [
+    ref,
+    animationType,
+    animationTrigger,
+    animationDuration,
+    animationDelay,
+    animationEasing,
+    animationLoop,
+    animationStagger,
+  ]);
+}
+
+/** The stagger targets for a section: walk a few levels down and pick the element
+ * holding the most direct children — for a CardGrid that's the grid (cards), for
+ * prose it's the paragraph list, for a CTA it's the flex column (heading/sub/button).
+ * Falls back to the section itself when nothing groups. */
+function findStaggerTargets(el: HTMLElement): HTMLElement | Element[] {
+  let best: Element | null = null;
+  let bestCount = 1;
+  const queue: { node: Element; depth: number }[] = [{ node: el, depth: 0 }];
+  while (queue.length) {
+    const { node, depth } = queue.shift()!;
+    if (node.children.length > bestCount) {
+      best = node;
+      bestCount = node.children.length;
+    }
+    if (depth < 4) {
+      for (const child of Array.from(node.children)) queue.push({ node: child, depth: depth + 1 });
+    }
+  }
+  return best ? Array.from(best.children) : el;
+}
+
+/** Always-on pointer/scroll effects, independent of the entrance animation:
+ * `parallaxSpeed` scrubs the section vertically against the scroll, and
+ * `hoverEffect: "tilt"` makes it follow the pointer in 3D. (The other hover effects —
+ * lift/glow/scale — are pure CSS classes applied by Renderer; only tilt needs JS.) */
+export function useModernEffects(ref: RefObject<HTMLElement | null>, style: NodeStyle) {
+  const { parallaxSpeed, hoverEffect } = style;
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (!parallaxSpeed && hoverEffect !== "tilt") return;
+
+    if (!pluginRegistered) {
+      gsap.registerPlugin(ScrollTrigger);
+      pluginRegistered = true;
+    }
+
+    const ctx = gsap.context(() => {
+      if (parallaxSpeed) {
+        gsap.to(el, {
+          y: parallaxSpeed * 120,
+          ease: "none",
+          scrollTrigger: { trigger: el, start: "top bottom", end: "bottom top", scrub: true },
+        });
+      }
+    });
+
+    let removeTilt = () => {};
+    if (hoverEffect === "tilt") {
+      const rotX = gsap.quickTo(el, "rotationX", { duration: 0.4, ease: "power2.out" });
+      const rotY = gsap.quickTo(el, "rotationY", { duration: 0.4, ease: "power2.out" });
+      gsap.set(el, { transformPerspective: 900 });
+      const onMove = (e: PointerEvent) => {
+        const rect = el.getBoundingClientRect();
+        const px = (e.clientX - rect.left) / rect.width - 0.5;
+        const py = (e.clientY - rect.top) / rect.height - 0.5;
+        rotY(px * 10);
+        rotX(py * -10);
+      };
+      const onLeave = () => {
+        rotX(0);
+        rotY(0);
+      };
+      el.addEventListener("pointermove", onMove);
+      el.addEventListener("pointerleave", onLeave);
+      removeTilt = () => {
+        el.removeEventListener("pointermove", onMove);
+        el.removeEventListener("pointerleave", onLeave);
+      };
+    }
+
+    return () => {
+      removeTilt();
+      ctx.revert();
+    };
+  }, [ref, parallaxSpeed, hoverEffect]);
+}

package/template/apps/web/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/template/apps/web/next.config.mjs

@@ -0,0 +1,32 @@
+const API_URL = process.env.API_URL ?? "http://localhost:4000";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ["@pgcms/shared"],
+  output: "standalone",
+  images: {
+    remotePatterns: [
+      { protocol: "http", hostname: "localhost" },
+      { protocol: "https", hostname: "**" },
+    ],
+  },
+  // Proxy API calls through the Next.js origin so the auth cookie set by the
+  // Express API is treated as first-party by the browser (same-origin as the web app).
+  async rewrites() {
+    return {
+      // Route handlers in app/api (e.g. /api/revalidate) match before afterFiles rewrites.
+      afterFiles: [{ source: "/api/:path*", destination: `${API_URL}/api/:path*` }],
+    };
+  },
+  // @pgcms/shared uses NodeNext-style ".js" specifiers in its own source (required
+  // for tsx/Node ESM resolution in apps/api). Webpack doesn't know those map to
+  // sibling ".ts" files, so teach it to.
+  webpack(config) {
+    config.resolve.extensionAlias = {
+      ".js": [".js", ".ts", ".tsx"],
+    };
+    return config;
+  },
+};
+
+export default nextConfig;

package/template/apps/web/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pgcms/web",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --webpack -p 3000",
+    "build": "next build",
+    "start": "next start -p 3000",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.1.0",
+    "@dnd-kit/sortable": "^8.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@pgcms/shared": "*",
+    "@tiptap/extension-color": "^2.27.2",
+    "@tiptap/extension-link": "^2.8.0",
+    "@tiptap/extension-text-align": "^2.27.2",
+    "@tiptap/extension-text-style": "^2.27.2",
+    "@tiptap/extension-underline": "^2.27.2",
+    "@tiptap/react": "^2.8.0",
+    "@tiptap/starter-kit": "^2.8.0",
+    "clsx": "^2.1.1",
+    "gsap": "^3.15.0",
+    "isomorphic-dompurify": "^3.18.0",
+    "lucide-react": "^1.23.0",
+    "nanoid": "^5.0.7",
+    "next": "^16.2.10",
+    "react": "^19.2.7",
+    "react-colorful": "^5.6.1",
+    "react-dom": "^19.2.7",
+    "three": "^0.185.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.185.0",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^10.6.0",
+    "eslint-config-next": "^16.2.10",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^3.4.13",
+    "typescript": "^5.9.3"
+  }
+}

package/template/apps/web/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/template/apps/web/proxy.ts

@@ -0,0 +1,23 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+const COOKIE_NAME = process.env.COOKIE_NAME ?? "pgcms_token";
+
+// This only gates the UX (redirect to /admin/login when no session cookie is present).
+// The Express API independently verifies the JWT and enforces roles on every request -
+// that's the real security boundary, not this proxy.
+export function proxy(req: NextRequest) {
+  const { pathname } = req.nextUrl;
+  if (pathname === "/admin/login") return NextResponse.next();
+
+  const token = req.cookies.get(COOKIE_NAME);
+  if (!token) {
+    const loginUrl = new URL("/admin/login", req.url);
+    loginUrl.searchParams.set("next", pathname);
+    return NextResponse.redirect(loginUrl);
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/admin/:path*"],
+};

package/template/apps/web/tailwind.config.ts

@@ -0,0 +1,24 @@
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}", "./lib/**/*.{ts,tsx}"],
+  theme: {
+    extend: {
+      colors: {
+        theme: {
+          primary: "var(--theme-primary)",
+          secondary: "var(--theme-secondary)",
+          bg: "var(--theme-bg)",
+          text: "var(--theme-text)",
+        },
+      },
+      fontFamily: {
+        heading: "var(--theme-heading-font)",
+        body: "var(--theme-body-font)",
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

package/template/apps/web/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/template/docker-compose.yml

@@ -0,0 +1,60 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-pgcms}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-pgcms_dev_password}
+      POSTGRES_DB: ${POSTGRES_DB:-pgcms}
+    ports:
+      # Host port 5433 collides with another project's Postgres container on this
+      # machine (postgres_db_dev) — 5434 avoids it. Container-internal port stays 5432.
+      - "5434:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-pgcms}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  minio:
+    image: minio/minio:latest
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${S3_ACCESS_KEY_ID:-pgcms_minio}
+      MINIO_ROOT_PASSWORD: ${S3_SECRET_ACCESS_KEY:-pgcms_minio_secret}
+    ports:
+      # Host ports 9000/9001 collide with another project's MinIO container on this
+      # machine (minio_dev) — 9010/9011 avoid it. Container-internal ports are unchanged.
+      - "9010:9000"
+      - "9011:9001"
+    volumes:
+      - minio-data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  minio-init:
+    image: minio/mc:latest
+    depends_on:
+      minio:
+        condition: service_healthy
+    environment:
+      S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-pgcms_minio}
+      S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-pgcms_minio_secret}
+      S3_BUCKET: ${S3_BUCKET:-pgcms-media}
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 $$S3_ACCESS_KEY_ID $$S3_SECRET_ACCESS_KEY &&
+      (mc mb local/$$S3_BUCKET || true) &&
+      mc anonymous set download local/$$S3_BUCKET &&
+      echo 'MinIO bucket ready'
+      "
+
+volumes:
+  postgres-data:
+  minio-data:

package/template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pg-cms",
+  "private": true,
+  "engines": {
+    "node": "^24.0.0",
+    "npm": "^11.0.0"
+  },
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
+  "scripts": {
+    "dev": "concurrently -n api,web -c blue,green \"npm run dev -w apps/api\" \"npm run dev -w apps/web\"",
+    "dev:api": "npm run dev -w apps/api",
+    "dev:web": "npm run dev -w apps/web",
+    "build": "npm run build -w packages/shared && npm run build -w apps/api && npm run build -w apps/web",
+    "test": "npm run test -w packages/shared",
+    "docker:up": "docker compose up -d",
+    "docker:down": "docker compose down",
+    "db:migrate": "npm run db:migrate -w apps/api",
+    "db:seed": "npm run db:seed -w apps/api"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "concurrently": "^9.1.0",
+    "typescript": "^5.9.3"
+  }
+}

package/template/packages/shared/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pgcms/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "npm run typecheck",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "nanoid": "^5.0.7",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
+  }
+}