rankrunners-cms 0.0.19 → 0.0.21

package/src/api/client/posts.ts

@@ -0,0 +1,50 @@
+import { CMS_BASE_URL, SITE_ID } from "../constants";
+import { fetchAs } from "../../libs/validator";
+import {
+  PublicPostSeoDetailsSchema,
+  PublicSeoDetailsSchema,
+  type PublicPostDTO,
+  type PublicPostSeoDetailsDTO,
+} from "../types/public";
+
+/**
+ * Get a list of published blog posts for the current site.
+ * Optionally filter by a post category name.
+ */
+export const getPublicPosts = async (
+  category?: string,
+): Promise<PublicPostDTO[]> => {
+  const url = new URL(`${CMS_BASE_URL}/public/seo/${SITE_ID}`);
+  if (category) {
+    url.searchParams.set("category", category);
+  }
+
+  const response = await fetchAs(PublicSeoDetailsSchema, url.toString());
+  return response.posts;
+};
+
+/**
+ * Get a single blog post's full SEO details by its slug.
+ */
+export const getPublicPostBySlug = async (
+  slug: string,
+): Promise<PublicPostSeoDetailsDTO> => {
+  const response = await fetchAs(
+    PublicPostSeoDetailsSchema,
+    `${CMS_BASE_URL}/public/seo/${SITE_ID}/posts/${encodeURIComponent(slug)}`,
+  );
+  return response;
+};
+
+/**
+ * Get a single blog post's full SEO details by its ID (or slug).
+ */
+export const getPublicPostById = async (
+  postId: string,
+): Promise<PublicPostSeoDetailsDTO> => {
+  const response = await fetchAs(
+    PublicPostSeoDetailsSchema,
+    `${CMS_BASE_URL}/public/sites/${SITE_ID}/posts/${encodeURIComponent(postId)}`,
+  );
+  return response;
+};

package/src/api/types/public.ts

@@ -1,31 +1,146 @@
-import { object, string, array, optional, type InferOutput } from "valibot";
+import {
+  object,
+  string,
+  array,
+  optional,
+  nullable,
+  boolean,
+  type InferOutput,
+} from "valibot";
 import { IdSchema } from "../types/common";
 
-export const PublicPageSeoDetailsSchema = object({
-  id: optional(IdSchema), // ok
-  siteId: optional(string()), // ok
-  title: optional(string()), // ok
-  slug: optional(string()), // ok
-  content: optional(string()), // ok
-  metaTitle: string(), // ok
-  metaDescription: string(), // ok
-  seoKeywords: array(string()), // ok
-  openGraphTitle: optional(string()), // ok
-  openGraphDescription: optional(string()), // ok
-  openGraphImage: optional(string()), // ok
-  googleAnalyticsId: optional(string()), // ok
-  googleTagManagerId: optional(string()), // ok
-  metaPixelId: optional(string()), // ok
-  universalPixelId: optional(string()), // ok
-  universalPixelAdvertiserId: optional(string()), // ok
+// --- Media Schema (for hero images) ---
+
+export const PublicMediaSchema = object({
+  id: string(),
+  name: string(),
+  altText: string(),
+  seoKeywords: array(string()),
+  url: string(),
+});
+
+export type PublicMediaDTO = InferOutput<typeof PublicMediaSchema>;
+
+// --- Shared SEO fields (reused across page & post SEO DTOs) ---
+
+const SeoTrackingFields = {
+  googleAnalyticsId: optional(string()),
+  googleTagManagerId: optional(string()),
+  metaPixelId: optional(string()),
+  universalPixelId: optional(string()),
+  universalPixelAdvertiserId: optional(string()),
   googleSiteVerificationId: optional(string()),
   callrailScript: optional(string()),
-  twitterCardType: optional(string()),
+} as const;
+
+const SeoOpenGraphFields = {
+  openGraphTitle: optional(string()),
+  openGraphDescription: optional(string()),
+  openGraphImage: optional(string()),
+} as const;
+
+const SeoMetaFields = {
+  metaTitle: string(),
+  metaDescription: string(),
+  seoKeywords: array(string()),
+  ...SeoOpenGraphFields,
+  ...SeoTrackingFields,
+} as const;
+
+const SeoScriptFields = {
   headerScripts: string(),
   footerScripts: string(),
   structuredData: string(),
+} as const;
+
+/**
+ * All common SEO detail fields shared between pages and posts.
+ */
+const CommonSeoDetailFields = {
+  ...SeoMetaFields,
+  ...SeoScriptFields,
+} as const;
+
+// --- Post Schemas ---
+
+export const PublicPostSchema = object({
+  id: IdSchema,
+  title: string(),
+  slug: string(),
+  author: nullable(string()),
+  publishedAt: nullable(string()),
+  shortContent: string(),
+  heroImage: nullable(PublicMediaSchema),
+});
+
+export type PublicPostDTO = InferOutput<typeof PublicPostSchema>;
+
+export const PublicPostSeoDetailsSchema = object({
+  id: IdSchema,
+  siteId: string(),
+  title: string(),
+  slug: string(),
+  content: string(),
+  publishedAt: nullable(string()),
+  author: nullable(string()),
+  heroImage: nullable(PublicMediaSchema),
+  ...CommonSeoDetailFields,
+  twitterCardType: string(),
+});
+
+export type PublicPostSeoDetailsDTO = InferOutput<
+  typeof PublicPostSeoDetailsSchema
+>;
+
+// --- Page Schema ---
+
+export const PublicPageSchema = object({
+  id: IdSchema,
+  title: string(),
+  slug: string(),
+});
+
+export type PublicPageDTO = InferOutput<typeof PublicPageSchema>;
+
+// --- SEO Details Schema (includes pages + posts) ---
+
+export const PublicSeoDetailsSchema = object({
+  siteTitle: string(),
+  siteDescription: string(),
+  siteKeywords: string(),
+  robotsTxt: string(),
+  ...SeoTrackingFields,
+  ...SeoOpenGraphFields,
+  twitterCardType: string(),
+  headerScripts: string(),
+  footerScripts: string(),
+  enableRobotsTxt: boolean(),
+  enableOpenGraph: boolean(),
+  enableTwitterCards: boolean(),
+  pages: array(PublicPageSchema),
+  posts: array(PublicPostSchema),
+});
+
+export type PublicSeoDetailsDTO = InferOutput<typeof PublicSeoDetailsSchema>;
+
+// --- Page SEO Details Schema ---
+
+export const PublicPageSeoDetailsSchema = object({
+  id: optional(IdSchema),
+  siteId: optional(string()),
+  title: optional(string()),
+  slug: optional(string()),
+  content: optional(string()),
+  ...CommonSeoDetailFields,
+  twitterCardType: optional(string()),
 });
 
 export type PublicPageSeoDetailsDTO = InferOutput<
   typeof PublicPageSeoDetailsSchema
 >;
+
+/**
+ * Union type of any entity that carries the common SEO detail fields.
+ * Useful for building meta/scripts generically from either a page or post response.
+ */
+export type AnySeoDetails = PublicPageSeoDetailsDTO | PublicPostSeoDetailsDTO;

package/src/tanstack/components/NotFound.tsx

@@ -0,0 +1,79 @@
+import { Link } from '@tanstack/react-router'
+
+export const NotFound = () => (
+  <div
+    style={{
+      minHeight: '100vh',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      backgroundColor: '#f3f4f6',
+    }}
+  >
+    <div
+      style={{
+        textAlign: 'center',
+        paddingLeft: '1.5rem',
+        paddingRight: '1.5rem',
+        paddingTop: '3rem',
+        paddingBottom: '3rem',
+      }}
+    >
+      <h1
+        style={{
+          fontSize: '8rem',
+          lineHeight: '1',
+          fontWeight: 'bold',
+          color: '#1f2937',
+          margin: 0,
+        }}
+      >
+        404
+      </h1>
+      <h2
+        style={{
+          marginTop: '1rem',
+          fontSize: '1.875rem',
+          lineHeight: '2.25rem',
+          fontWeight: '600',
+          color: '#374151',
+        }}
+      >
+        Page Not Found
+      </h2>
+      <p
+        style={{
+          marginTop: '1rem',
+          fontSize: '1.125rem',
+          lineHeight: '1.75rem',
+          color: '#4b5563',
+          maxWidth: '28rem',
+          marginLeft: 'auto',
+          marginRight: 'auto',
+        }}
+      >
+        Sorry, the page you're looking for doesn't exist or has been moved.
+      </p>
+      <div style={{ marginTop: '2rem' }}>
+        <Link
+          to={'/' as '.'}
+          style={{
+            display: 'inline-block',
+            paddingLeft: '1.5rem',
+            paddingRight: '1.5rem',
+            paddingTop: '0.75rem',
+            paddingBottom: '0.75rem',
+            backgroundColor: '#2563eb',
+            color: '#ffffff',
+            fontWeight: '500',
+            borderRadius: '0.5rem',
+            textDecoration: 'none',
+            transition: 'background-color 0.2s',
+          }}
+        >
+          Go to Home
+        </Link>
+      </div>
+    </div>
+  </div>
+)

package/src/tanstack/index.ts

@@ -1,3 +1,4 @@
-export * from "./seo/index";
-export * from "./editor/index";
-export * from "./hooks";
+export * from './seo/index'
+export * from './editor/index'
+export * from './hooks'
+export * from './withCMS'

package/src/tanstack/seo/head.ts

@@ -1,4 +1,5 @@
 import { getPublicPageSEODetails } from "../../api/client/public";
+import { getPublicPostBySlug } from "../../api/client/posts";
 import type { RouteHead } from "./types";
 import { SITE_ID } from "../../api/constants";
 import type { RouteOptions } from "@tanstack/router-core";
@@ -12,19 +13,27 @@ import {
   parseAndAppendScripts,
 } from "../../libs/parser/parseScripts";
 import { extractPathname } from "./extractors";
+import type { AnySeoDetails } from "../../api/types/public";
+import type { CMSBlogConfig } from "./types";
 
-export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
-  const { match } = ctx;
-  const pathname = extractPathname(match);
-  const seoDetails = await getPublicPageSEODetails(SITE_ID, pathname);
-  const meta: DetailedHTMLProps<
-    MetaHTMLAttributes<HTMLMetaElement>,
-    HTMLMetaElement
-  >[] = [{ charSet: "utf-8" }];
-
-  if (!seoDetails) {
-    return { meta };
-  }
+// ---------------------------------------------------------------------------
+// Generic SEO builders (work for both page and post SEO details)
+// ---------------------------------------------------------------------------
+
+type MetaTag = DetailedHTMLProps<
+  MetaHTMLAttributes<HTMLMetaElement>,
+  HTMLMetaElement
+>;
+type ScriptTag = DetailedHTMLProps<
+  ScriptHTMLAttributes<HTMLScriptElement>,
+  HTMLScriptElement
+>;
+
+/**
+ * Build `<meta>` tags from any SEO details object (page or post).
+ */
+export function buildSeoMeta(seoDetails: AnySeoDetails): MetaTag[] {
+  const meta: MetaTag[] = [];
 
   if (seoDetails.metaTitle && seoDetails.metaTitle.length > 0) {
     meta.push({ title: seoDetails.metaTitle });
@@ -34,12 +43,10 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     meta.push({ name: "description", content: seoDetails.metaDescription });
   }
 
-  // SEO Keywords
   if (seoDetails.seoKeywords && seoDetails.seoKeywords.length > 0) {
     meta.push({ name: "keywords", content: seoDetails.seoKeywords.join(", ") });
   }
 
-  // Google Site Verification
   if (seoDetails.googleSiteVerificationId) {
     meta.push({
       name: "google-site-verification",
@@ -47,7 +54,7 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     });
   }
 
-  // Open Graph tags
+  // Open Graph
   if (seoDetails.openGraphTitle && seoDetails.openGraphTitle.length > 0) {
     meta.push({ property: "og:title", content: seoDetails.openGraphTitle });
   }
@@ -64,9 +71,10 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     meta.push({ property: "og:image", content: seoDetails.openGraphImage });
   }
 
-  meta.push({ property: "og:type", content: "website" });
+  const isPost = "author" in seoDetails;
+  meta.push({ property: "og:type", content: isPost ? "article" : "website" });
 
-  // Twitter Card tags
+  // Twitter Card
   if (seoDetails.twitterCardType && seoDetails.twitterCardType.length > 0) {
     meta.push({ name: "twitter:card", content: seoDetails.twitterCardType });
     if (seoDetails.openGraphTitle && seoDetails.openGraphTitle.length > 0) {
@@ -86,11 +94,15 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
     }
   }
 
-  // Build scripts array for head
-  const scripts: DetailedHTMLProps<
-    ScriptHTMLAttributes<HTMLScriptElement>,
-    HTMLScriptElement
-  >[] = [];
+  return meta;
+}
+
+/**
+ * Build `<script>` tags (structured data, pixels, analytics, custom header
+ * scripts) from any SEO details object (page or post).
+ */
+export function buildSeoScripts(seoDetails: AnySeoDetails): ScriptTag[] {
+  const scripts: ScriptTag[] = [];
 
   // Structured Data (JSON-LD)
   if (seoDetails.structuredData) {
@@ -181,11 +193,78 @@ export const seoHead: RouteHead<RouteOptions<any, any>> = async (ctx) => {
   // Custom header scripts
   parseAndAppendScripts(scripts, seoDetails.headerScripts);
 
-  return {
-    meta,
-    scripts: dedupeScripts(scripts),
+  return scripts;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve SEO details for a pathname, considering blog routes
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a pathname and optional blog configs, fetch the appropriate SEO details.
+ *
+ * - If the pathname matches `{prefix}/{slug}`, fetch the post by slug.
+ * - If the pathname matches `{prefix}` exactly, return page SEO (the list page
+ *   itself is a CMS page; the blog posts are loaded separately in the loader).
+ * - Otherwise fall back to normal page SEO lookup.
+ */
+async function resolveSeoDetails(
+  pathname: string,
+  blogs?: CMSBlogConfig[],
+): Promise<AnySeoDetails | null> {
+  if (blogs) {
+    for (const blog of blogs) {
+      const prefix = blog.prefix.replace(/^\/+|\/+$/g, "");
+
+      // Detail page: {prefix}/{slug}
+      if (pathname.startsWith(`${prefix}/`)) {
+        const slug = pathname.slice(prefix.length + 1);
+        if (slug.length > 0) {
+          try {
+            return await getPublicPostBySlug(slug);
+          } catch {
+            return null;
+          }
+        }
+      }
+    }
+  }
+
+  // Default: fetch page SEO details
+  return getPublicPageSEODetails(SITE_ID, pathname);
+}
+
+// ---------------------------------------------------------------------------
+// seoHead — now blog-aware
+// ---------------------------------------------------------------------------
+
+export const createSeoHead = (
+  blogs?: CMSBlogConfig[],
+): RouteHead<RouteOptions<any, any>> =>
+  async (ctx) => {
+    const { match } = ctx;
+    const pathname = extractPathname(match);
+
+    const meta: MetaTag[] = [{ charSet: "utf-8" }];
+
+    const seoDetails = await resolveSeoDetails(pathname, blogs);
+
+    if (!seoDetails) {
+      return { meta };
+    }
+
+    return {
+      meta: [...meta, ...buildSeoMeta(seoDetails)],
+      scripts: dedupeScripts(buildSeoScripts(seoDetails)),
+    };
   };
-};
+
+/** Default seoHead (no blog config — backwards-compatible). */
+export const seoHead: RouteHead<RouteOptions<any, any>> = createSeoHead();
+
+// ---------------------------------------------------------------------------
+// headWithSEO
+// ---------------------------------------------------------------------------
 
 const toArray = <T>(v?: T | T[]): T[] => {
   if (v === undefined || v === null) return [];
@@ -195,10 +274,12 @@ const toArray = <T>(v?: T | T[]): T[] => {
 export const headWithSEO =
   <T extends RouteOptions<any, any>>(
     originalHead: RouteHead<T>,
+    blogs?: CMSBlogConfig[],
   ): RouteHead<T> =>
   async (...params) => {
+    const seoHeadFn = blogs ? createSeoHead(blogs) : seoHead;
     const ourHeadResult = await originalHead(...params);
-    const seoHeadResult = await seoHead(...params);
+    const seoHeadResult = await seoHeadFn(...params);
 
     return {
       meta: [

package/src/tanstack/seo/scripts.ts

@@ -1,5 +1,6 @@
 import { getPublicPageSEODetails } from "../../api/client/public";
-import type { RouteScripts } from "./types";
+import { getPublicPostBySlug } from "../../api/client/posts";
+import type { RouteScripts, CMSBlogConfig } from "./types";
 import { SITE_ID } from "../../api/constants";
 import {
   dedupeScripts,
@@ -8,27 +9,60 @@ import {
 import type { RouteOptions } from "@tanstack/router-core";
 import { extractPathname } from "./extractors";
 import type { DetailedHTMLProps, ScriptHTMLAttributes } from "react";
+import type { AnySeoDetails } from "../../api/types/public";
 
-export const seoScripts: RouteScripts<RouteOptions<any, any>> = async (ctx) => {
-  const { match } = ctx;
-  const pathname = extractPathname(match);
-  const seoDetails = await getPublicPageSEODetails(SITE_ID, pathname);
+/**
+ * Resolve footer-level SEO details, taking blog routes into account.
+ */
+async function resolveFooterSeoDetails(
+  pathname: string,
+  blogs?: CMSBlogConfig[],
+): Promise<AnySeoDetails | null> {
+  if (blogs) {
+    for (const blog of blogs) {
+      const prefix = blog.prefix.replace(/^\/+|\/+$/g, "");
+      if (pathname.startsWith(`${prefix}/`)) {
+        const slug = pathname.slice(prefix.length + 1);
+        if (slug.length > 0) {
+          try {
+            return await getPublicPostBySlug(slug);
+          } catch {
+            return null;
+          }
+        }
+      }
+    }
+  }
+  return getPublicPageSEODetails(SITE_ID, pathname);
+}
 
-  const scripts: DetailedHTMLProps<
-    ScriptHTMLAttributes<HTMLScriptElement>,
-    HTMLScriptElement
-  >[] = [];
+export const createSeoScripts = (
+  blogs?: CMSBlogConfig[],
+): RouteScripts<RouteOptions<any, any>> =>
+  async (ctx) => {
+    const { match } = ctx;
+    const pathname = extractPathname(match);
+    const seoDetails = await resolveFooterSeoDetails(pathname, blogs);
 
-  if (!seoDetails) {
-    return scripts;
-  }
+    const scripts: DetailedHTMLProps<
+      ScriptHTMLAttributes<HTMLScriptElement>,
+      HTMLScriptElement
+    >[] = [];
 
-  if (seoDetails.callrailScript) {
-    scripts.push({
-      src: seoDetails.callrailScript,
-    });
-  }
+    if (!seoDetails) {
+      return scripts;
+    }
+
+    if (seoDetails.callrailScript) {
+      scripts.push({
+        src: seoDetails.callrailScript,
+      });
+    }
+
+    parseAndAppendScripts(scripts, seoDetails.footerScripts);
+    return dedupeScripts(scripts);
+  };
 
-  parseAndAppendScripts(scripts, seoDetails.footerScripts);
-  return dedupeScripts(scripts);
-};
+/** Default seoScripts (no blog config — backwards-compatible). */
+export const seoScripts: RouteScripts<RouteOptions<any, any>> =
+  createSeoScripts();

package/src/tanstack/seo/types.ts

@@ -1,4 +1,9 @@
 import type { RouteOptions } from "@tanstack/router-core";
+import type React from "react";
+import type {
+  PublicPostDTO,
+  PublicPostSeoDetailsDTO,
+} from "../../api/types/public";
 
 export type RouteHead<T extends RouteOptions<any, any>> = NonNullable<
   T["head"]
@@ -7,3 +12,30 @@ export type RouteHead<T extends RouteOptions<any, any>> = NonNullable<
 export type RouteScripts<T extends RouteOptions<any, any>> = NonNullable<
   T["scripts"]
 >;
+
+/**
+ * Configuration for a single blog section served by the CMS catch-all route.
+ *
+ * - `prefix`  – URL prefix without leading/trailing slashes (e.g. `"blog"`).
+ *               `/{prefix}` renders the list page, `/{prefix}/{slug}` the detail.
+ * - `category` – Optional post category name used to filter posts from the API.
+ *                When `undefined`/`null`, all posts are returned.
+ * - `listComponent` – React component rendered at `/{prefix}` receiving the
+ *                      filtered post list.
+ * - `detailComponent` – React component rendered at `/{prefix}/{slug}` receiving
+ *                        the full post SEO details.
+ */
+export interface CMSBlogConfig {
+  prefix: string;
+  category?: string | null;
+  listComponent: (posts: PublicPostDTO[]) => React.ReactNode;
+  detailComponent: (post: PublicPostSeoDetailsDTO) => React.ReactNode;
+}
+
+/**
+ * Optional CMS-specific configuration that can be passed to `withCMS` and
+ * `headWithSEO` / `createSeoHead`.
+ */
+export interface CMSConfig {
+  blogs?: CMSBlogConfig[];
+}