@decocms/apps-blog 8.0.0 → 8.1.0-next.0

package/src/utils/blocksToSections.ts

@@ -0,0 +1,175 @@
+import type { Section } from "../types";
+
+/** Minimal Block type — matches the structure returned by the Spire API. */
+interface Block {
+  type?: string;
+  position?: number;
+  content?: Record<string, unknown>;
+  system_block_id?: string;
+  custom_block_id?: string;
+}
+
+const BASE = "blog/sections/blocks";
+
+function toSection(resolveType: string, props: Record<string, unknown>): Section {
+  return { __resolveType: resolveType, ...props } as Section;
+}
+
+/**
+ * Converts a Spire Block array into a Section[] using blog/sections/blocks
+ * components. Sections are sorted by block position before conversion.
+ * Supports an optional override map to remap block types to custom section
+ * renderers.
+ */
+export function blocksToSections(
+  blocks: Block[],
+  overrides: Record<string, { __resolveType?: string }> = {},
+): Section[] {
+  return [...blocks]
+    .sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+    .map((block) => blockToSection(block, overrides))
+    .filter((s): s is Section => s !== null);
+}
+
+function blockToSection(
+  block: Block,
+  overrides: Record<string, { __resolveType?: string }>,
+): Section | null {
+  const content = (block.content ?? {}) as Record<string, unknown>;
+
+  if ("type" in block && block.type) {
+    if (overrides[block.type]) {
+      return toSection(overrides[block.type]?.__resolveType ?? block.type, content);
+    }
+
+    switch (block.type) {
+      case "paragraph":
+        return toSection(`${BASE}/Paragraph.tsx`, {
+          html: content.html,
+          text: content.text,
+        });
+
+      case "heading":
+        return toSection(`${BASE}/Heading.tsx`, {
+          text: content.text,
+          level: content.level,
+        });
+
+      case "list":
+        return toSection(`${BASE}/List.tsx`, {
+          items: content.items,
+          style: content.style,
+        });
+
+      case "divider":
+        return toSection(`${BASE}/Divider.tsx`, {});
+
+      case "quote":
+        return toSection(`${BASE}/Quote.tsx`, {
+          quote: content.quote,
+          text: content.text,
+          attribution: content.attribution,
+          source: content.source,
+        });
+
+      case "callout":
+        return toSection(`${BASE}/Callout.tsx`, {
+          title: content.title,
+          body: content.body,
+          variant: content.variant,
+        });
+
+      case "checklist":
+        return toSection(`${BASE}/Checklist.tsx`, {
+          title: content.title,
+          items: content.items,
+        });
+
+      case "steps":
+        return toSection(`${BASE}/Steps.tsx`, {
+          title: content.title,
+          steps: content.steps,
+        });
+
+      case "stat":
+        return toSection(`${BASE}/Stat.tsx`, {
+          value: content.value,
+          label: content.label,
+          description: content.description,
+        });
+
+      case "stat-group":
+        return toSection(`${BASE}/StatGroup.tsx`, {
+          stats: content.stats,
+        });
+
+      case "card-group":
+        return toSection(`${BASE}/CardGroup.tsx`, {
+          cards: content.cards,
+        });
+
+      case "comparison":
+        return toSection(`${BASE}/Comparison.tsx`, {
+          left: content.left,
+          right: content.right,
+        });
+
+      case "table":
+        return toSection(`${BASE}/Table.tsx`, {
+          headers: content.headers,
+          rows: content.rows,
+        });
+
+      case "image":
+        return toSection(`${BASE}/BlockImage.tsx`, {
+          url: content.url,
+          mobileUrl: content.mobileUrl,
+          alt: content.alt,
+          caption: content.caption,
+          size: content.size,
+          // Upstream does not forward this, which leaves every block-pipeline
+          // image lazy-loaded and the prop reachable only on a hand-placed
+          // BlockImage section.
+          highPriority: content.highPriority,
+        });
+
+      case "video":
+        return toSection(`${BASE}/Video.tsx`, {
+          url: content.url,
+          caption: content.caption,
+        });
+
+      case "code":
+        return toSection(`${BASE}/Code.tsx`, {
+          code: content.code,
+          language: content.language,
+          filename: content.filename,
+        });
+
+      case "cta":
+        return toSection(`${BASE}/Cta.tsx`, {
+          text: content.text,
+          href: content.href,
+        });
+
+      default:
+        return null;
+    }
+  }
+
+  // System blocks (no explicit type) — render as paragraph if they have html/text
+  if ("system_block_id" in block) {
+    if (content.html) {
+      return toSection(`${BASE}/Paragraph.tsx`, {
+        html: content.html as string,
+      });
+    }
+    if (content.text) {
+      return toSection(`${BASE}/Paragraph.tsx`, {
+        text: content.text as string,
+      });
+    }
+  }
+
+  return null;
+}

package/src/utils/constants.ts

@@ -0,0 +1 @@
+export const VALID_SORT_ORDERS = ["asc", "desc"];

package/src/utils/date.ts

@@ -0,0 +1,95 @@
+/** An ISO 8601 date or date-time carrying no timezone designator. */
+const ISO_WITHOUT_TIMEZONE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?)?$/;
+
+/**
+ * Parses a CMS-authored date or date-time into a timestamp.
+ *
+ * `BlogPost.date` may be a bare `YYYY-MM-DD` or a full ISO 8601 timestamp, and
+ * `scheduledDatetime` is a date-time that may or may not carry an offset.
+ *
+ * Anything without a timezone designator is pinned to UTC, so the result never
+ * depends on the machine timezone. That matters for both shapes: per spec a
+ * bare date is already UTC, but an offset-less datetime is parsed as *local*
+ * time, which would otherwise reorder posts near a day boundary from one
+ * server to the next — and, for a scheduled post, move its go-live instant.
+ *
+ * Unparseable values fall back to 0 instead of leaking NaN into a comparator
+ * (a NaN result is treated as 0, so the post would never move). Callers that
+ * compare against "now" must reject 0 explicitly rather than let it through as
+ * a very old date.
+ */
+export const dateToTime = (date: string) =>
+  new Date(
+    ISO_WITHOUT_TIMEZONE.test(date) ? `${date.includes("T") ? date : `${date}T00:00:00`}Z` : date,
+  ).getTime() || 0;
+
+/**
+ * An ISO 8601 date, optionally with a time and an offset. Anchored, grouped and
+ * deliberately narrow: `Date` accepts far more than this, and the extras are the
+ * problem — see `scheduledTime`.
+ */
+const STRICT_ISO =
+  /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(Z|[+-]\d{2}:\d{2})?$/;
+
+const lastDayOfMonth = (year: number, month: number) =>
+  new Date(Date.UTC(year, month, 0)).getUTCDate();
+
+/**
+ * Parses a scheduled go-live instant, or returns `null` if the value isn't one.
+ *
+ * Publishing needs a stricter parse than sorting does, because here a
+ * misreading doesn't reorder a list — it puts a post on the live site at the
+ * wrong moment. `Date` is lenient in two ways that both do exactly that:
+ *
+ * - It accepts non-ISO strings and parses them in *server-local* time, so
+ *   `"Sep 1 2026"` would go live at a different instant on every machine —
+ *   silently defeating the UTC pinning this module exists to guarantee. Worse,
+ *   it accepts strings that aren't dates in any useful sense: `"0"` is the year
+ *   2000, i.e. already live.
+ * - It rolls calendar overflow forward instead of rejecting it, so a typo'd
+ *   `"2026-02-31"` publishes on March 3rd.
+ *
+ * So the shape is matched against an anchored ISO pattern and the fields are
+ * range-checked before `Date` ever sees them. Anything else is `null`, and
+ * callers treat `null` as "not live" — a schedule we can't read is one we must
+ * not act on.
+ *
+ * A bare `YYYY-MM-DD` is accepted as midnight UTC: unlike the cases above it's
+ * an unambiguous ISO form, and rejecting it would strand a post forever over a
+ * missing time. `null` is used rather than 0 so that the Unix epoch stays a
+ * representable instant instead of being indistinguishable from a failure.
+ */
+export const scheduledTime = (value: string): number | null => {
+  const match = STRICT_ISO.exec(value);
+
+  if (!match) {
+    return null;
+  }
+
+  const [, ...groups] = match;
+  const [year, month, day] = groups.slice(0, 3).map(Number);
+  const [hour, minute, second] = groups.slice(3, 6).map((part) => Number(part ?? 0));
+
+  if (
+    month < 1 ||
+    month > 12 ||
+    day < 1 ||
+    day > lastDayOfMonth(year, month) ||
+    hour > 23 ||
+    minute > 59 ||
+    second > 59
+  ) {
+    return null;
+  }
+
+  // Only pin UTC when the value carries no designator of its own; `dateToTime`
+  // isn't reused here because its 0-on-failure fallback is precisely the
+  // ambiguity this function exists to remove.
+  const parsed = new Date(
+    groups[6] ? value : `${value.includes("T") ? value : `${value}T00:00:00`}Z`,
+  ).getTime();
+
+  // Still reachable despite the checks above — an out-of-range offset such as
+  // `+99:00` matches the pattern but is not a real instant.
+  return Number.isNaN(parsed) ? null : parsed;
+};

package/src/utils/hardSanitize.ts

@@ -0,0 +1,106 @@
+/**
+ * Stricter, dependency-free HTML sanitizer for blocks that render CMS-provided
+ * markup in a table-like context (see Table.tsx). It is intentionally separate
+ * from the shared `sanitizeHtml` so hardening this path cannot regress the many
+ * other blocks that rely on the lighter sanitizer.
+ *
+ * On top of the shared sanitizer's guarantees it also:
+ *  - Removes dangerous elements together with their content (script, style,
+ *    iframe, object, embed, applet, form, svg, math, template, noscript, base,
+ *    link, meta, frame, frameset), plus any leftover open/close/self-closing tags
+ *  - Strips inline event-handler attributes (on*), srcdoc and inline style
+ *  - Neutralizes javascript:, data: and vbscript: protocols in url-bearing
+ *    attributes (href, src, action, formaction, xlink:href), decoding entities
+ *    and stripping whitespace/control chars first so obfuscated schemes are
+ *    caught, while harmless values like "data-*" or "javascriptX" are preserved
+ *
+ * Note: this is a pragmatic denylist — not a full HTML parser. Keep the content
+ * model simple (text + basic inline/formatting markup).
+ */
+const DANGEROUS_ELEMENTS = [
+  "script",
+  "style",
+  "iframe",
+  "object",
+  "embed",
+  "applet",
+  "form",
+  "svg",
+  "math",
+  "template",
+  "noscript",
+  "base",
+  "link",
+  "meta",
+  "frame",
+  "frameset",
+];
+
+const URL_ATTRS = "href|src|action|formaction|xlink:href";
+const DANGEROUS_PROTOCOLS = "javascript|data|vbscript";
+
+// Captures a url-bearing attribute and its value (double/single-quoted or bare).
+const URL_ATTR_RE = new RegExp(`\\b(${URL_ATTRS})\\s*=\\s*("[^"]*"|'[^']*'|[^\\s>]+)`, "gi");
+// A dangerous scheme must be a real scheme: name immediately followed by ":".
+const DANGEROUS_SCHEME_RE = new RegExp(`^(?:${DANGEROUS_PROTOCOLS}):`, "i");
+
+function toCodePoint(n: number): string {
+  return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : "";
+}
+
+/** Decode the HTML entities most commonly used to smuggle a scheme past a filter. */
+function decodeEntities(value: string): string {
+  return value
+    .replace(/&#x([0-9a-f]+);?/gi, (_, hex) => toCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);?/g, (_, dec) => toCodePoint(parseInt(dec, 10)))
+    .replace(/&colon;/gi, ":")
+    .replace(/&tab;/gi, "\t")
+    .replace(/&newline;/gi, "\n");
+}
+
+/**
+ * True when an attribute value resolves to a dangerous URL scheme. The value is
+ * decoded and stripped of whitespace/control chars first, since browsers ignore
+ * those within a scheme (e.g. `java\tscript:` and `&#106;avascript:`).
+ */
+function hasDangerousScheme(value: string): boolean {
+  const normalized = decodeEntities(value)
+    // Control chars are intentional: browsers strip C0 controls/whitespace from
+    // a URL scheme, so an attacker can hide one inside `javascript:`.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: see above
+    .replace(/[\s\u0000-\u001f]+/g, "")
+    .toLowerCase();
+  return DANGEROUS_SCHEME_RE.test(normalized);
+}
+
+export function hardSanitize(raw: string | null | undefined): string {
+  if (!raw) return "";
+
+  let html = raw;
+
+  for (const tag of DANGEROUS_ELEMENTS) {
+    // Remove the element with its content, then any stray open/close/self-closing tag.
+    html = html
+      .replace(new RegExp(`<${tag}\\b[\\s\\S]*?<\\/${tag}\\s*>`, "gi"), "")
+      .replace(new RegExp(`<\\/?${tag}\\b[^>]*>`, "gi"), "");
+  }
+
+  return (
+    html
+      // Inline event handlers (onclick, onerror, …)
+      .replace(/\s+on\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+      // srcdoc (smuggles an inline document into iframes) and inline styles
+      .replace(/\s+(srcdoc|style)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+      // Neutralize dangerous protocols in url-bearing attributes. One pass handles
+      // quoted and unquoted values identically: decode/normalize, then require a
+      // real dangerous scheme followed by ":" (so harmless "data-*"/"javascriptX"
+      // values are left intact).
+      .replace(URL_ATTR_RE, (match, attr, value) => {
+        const quote = value[0] === '"' || value[0] === "'" ? value[0] : "";
+        const inner = quote ? value.slice(1, -1) : value;
+        if (!hasDangerousScheme(inner)) return match;
+        const q = quote || '"';
+        return `${attr}=${q}#${q}`;
+      })
+  );
+}

package/src/utils/jsonLD.ts

@@ -0,0 +1,118 @@
+import type { Author, BlogPost, Category, Publisher } from "../types";
+
+const toAuthor = (author: Author) => {
+  const type = author.type ?? "Person";
+  return {
+    "@type": type,
+    name: author.name,
+    // url and image are valid on both Person and Organization
+    ...(author.url ? { url: author.url } : {}),
+    ...(author.avatar ? { image: author.avatar } : {}),
+    // jobTitle and worksFor are Person-only properties
+    ...(type === "Person" && author.jobTitle ? { jobTitle: author.jobTitle } : {}),
+    ...(type === "Person" && author.company
+      ? { worksFor: { "@type": "Organization" as const, name: author.company } }
+      : {}),
+  };
+};
+
+export const toOrganization = (publisher: Publisher) => ({
+  "@type": "Organization" as const,
+  name: publisher.name,
+  ...(publisher.url ? { url: publisher.url } : {}),
+  ...(publisher.logo ? { logo: { "@type": "ImageObject" as const, url: publisher.logo } } : {}),
+});
+
+/**
+ * Normalizes a page URL for SEO use (canonical and JSON-LD): strips the query
+ * string and hash, keeping only origin + pathname, and replaces the origin
+ * with the canonical base's when one is configured. Relative URLs are
+ * resolved against the canonical base; without a base, relative URLs are
+ * returned unchanged.
+ */
+export const withCanonicalBase = (url: string, canonicalBaseUrl?: string) => {
+  if (!canonicalBaseUrl) {
+    if (!URL.canParse(url)) {
+      return url;
+    }
+    const { origin, pathname } = new URL(url);
+    return origin + pathname;
+  }
+  const { pathname } = new URL(url, canonicalBaseUrl);
+  return new URL(pathname, canonicalBaseUrl).href;
+};
+
+/**
+ * Maps a BlogPost to a schema.org BlogPosting node, following
+ * https://developers.google.com/search/docs/appearance/structured-data/article
+ *
+ * The "@context" is intentionally omitted: the Seo component adds it when
+ * serializing the top-level JSON-LD object.
+ */
+export const toBlogPosting = (post: BlogPost, url?: string, publisher?: Publisher) => {
+  const image = post.seo?.image || post.image;
+  const categories = post.categories?.map((category) => category.name).filter(Boolean);
+
+  // AggregateRating requires ratingValue and ratingCount/reviewCount;
+  // InteractionCounter requires userInteractionCount. Posts may carry empty
+  // {"@type": ...} stubs, which are invalid in the Rich Results Test.
+  const aggregateRating =
+    post.aggregateRating?.ratingValue != null &&
+    (post.aggregateRating.ratingCount != null || post.aggregateRating.reviewCount != null)
+      ? post.aggregateRating
+      : undefined;
+  const interactionStatistic =
+    post.interactionStatistic?.userInteractionCount != null ? post.interactionStatistic : undefined;
+
+  return {
+    "@type": "BlogPosting" as const,
+    headline: post.title,
+    ...(post.excerpt ? { description: post.excerpt } : {}),
+    ...(image ? { image: [image] } : {}),
+    ...(post.date ? { datePublished: post.date } : {}),
+    ...(post.dateModified ? { dateModified: post.dateModified } : {}),
+    ...(post.authors?.length ? { author: post.authors.map(toAuthor) } : {}),
+    ...(publisher?.name ? { publisher: toOrganization(publisher) } : {}),
+    ...(categories?.length ? { articleSection: categories } : {}),
+    ...(post.readTime && post.readTime > 0 && Number.isFinite(post.readTime)
+      ? { timeRequired: `PT${post.readTime}M` }
+      : {}),
+    ...(url ? { url, mainEntityOfPage: { "@type": "WebPage" as const, "@id": url } } : {}),
+    ...(aggregateRating ? { aggregateRating } : {}),
+    ...(interactionStatistic ? { interactionStatistic } : {}),
+  };
+};
+
+const humanize = (slug: string) =>
+  decodeURIComponent(slug)
+    .replace(/[-_]+/g, " ")
+    .replace(/^./, (char) => char.toUpperCase());
+
+/**
+ * Builds a schema.org BreadcrumbList from the pathname of the given absolute
+ * URL. Intermediate segments resolve their names against the known categories
+ * (falling back to a humanized slug) and link to absolute URLs; the last item
+ * uses the real page name and omits "item", as allowed by Google.
+ */
+export const toBreadcrumbList = (
+  url: string,
+  { currentName, categories }: { currentName?: string; categories?: Category[] } = {},
+) => {
+  const { origin, pathname } = new URL(url);
+  const segments = pathname.split("/").filter(Boolean);
+
+  const nameOf = (segment: string) =>
+    categories?.find((category) => category.slug === segment)?.name ?? humanize(segment);
+
+  const itemListElement = segments.map((segment, index) => {
+    const isLast = index === segments.length - 1;
+    return {
+      "@type": "ListItem" as const,
+      position: index + 1,
+      name: isLast ? currentName || nameOf(segment) : nameOf(segment),
+      ...(isLast ? {} : { item: `${origin}/${segments.slice(0, index + 1).join("/")}` }),
+    };
+  });
+
+  return { "@type": "BreadcrumbList" as const, itemListElement };
+};

package/src/utils/sanitizeHtml.ts

@@ -0,0 +1,37 @@
+/**
+ * Lightweight allowlist-based HTML sanitizer that works in both server (SSR)
+ * and browser contexts without external dependencies.
+ *
+ * Strips the most dangerous XSS vectors from CMS-provided HTML:
+ *  - <script> and <style> blocks
+ *  - Inline event-handler attributes (on*)
+ *  - javascript: and data: protocol values in href/src/action attributes
+ */
+export function sanitizeHtml(raw: string | null | undefined): string {
+  if (!raw) return "";
+  return raw
+    .replace(/<script\b[\s\S]*?<\/script\s*>/gi, "")
+    .replace(/<style\b[\s\S]*?<\/style\s*>/gi, "")
+    .replace(/\s+on\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+    .replace(/\b(href|src|action)\s*=\s*"(?:javascript|data)[^"]*"/gi, '$1="#"')
+    .replace(/\b(href|src|action)\s*=\s*'(?:javascript|data)[^']*'/gi, "$1='#'");
+}
+
+/**
+ * Returns a safe href: allows http, https, mailto, tel, and hash-only links.
+ * Falls back to "#" for anything else (e.g. javascript: URIs).
+ */
+export function sanitizeHref(href: string | null | undefined): string {
+  if (!href) return "#";
+  const trimmed = href.trim();
+  if (
+    /^https?:\/\//i.test(trimmed) ||
+    /^mailto:/i.test(trimmed) ||
+    /^tel:/i.test(trimmed) ||
+    /^#/.test(trimmed) ||
+    /^\//.test(trimmed)
+  ) {
+    return trimmed;
+  }
+  return "#";
+}