@giancarlosgza/blog-layer 0.0.0-stage → 0.1.0

package/shared/models/post.ts

@@ -0,0 +1,114 @@
+import type { IFirestoreDateValue } from './date'
+
+/**
+ * Editorial workflow state. `isPublished` stays the public-visibility flag (the blog and the
+ * rules read it): only a publish sets it true, so a live post can still be `review`/`changes`
+ * while its next revision is worked on. Legacy docs have no `status` (see resolvePostStatus).
+ */
+export type PostStatus = 'draft' | 'review' | 'changes' | 'scheduled' | 'published'
+
+/** Who performed a workflow step; `{ uid: 'system', name: 'Scheduler' }` for the scheduled publisher. */
+export interface IPostActor {
+  uid: string
+  name: string
+}
+
+/** The current review cycle, written only by the server routes. */
+export interface IPostReview {
+  /** 1 on the first submit, +1 on every resubmit after changes were requested. */
+  round: number
+  submittedAt: IFirestoreDateValue
+  submittedBy: IPostActor
+  /** Latest note in the thread: the submitter's note, then the reviewer's change request. */
+  note?: string
+  requestedAt?: IFirestoreDateValue
+  requestedBy?: IPostActor
+  reasons?: string[]
+  /** The author marked the change request as addressed. */
+  resolved?: boolean
+}
+
+/**
+ * `posts/{slug}` — post metadata. Document ID is the URL slug.
+ * `createdAt`/`updatedAt` are stored as Unix-ms numbers in the migrated data,
+ * but the type tolerates legacy Firestore Timestamp shapes too.
+ */
+export interface IPost {
+  id?: string
+  slug?: string
+  title: string
+  shortText?: string
+  isPublished: boolean
+  status?: PostStatus
+  /** When a `scheduled` post goes live (the scheduled Cloud Function publishes it). */
+  publishAt?: IFirestoreDateValue
+  review?: IPostReview
+  createdAt?: IFirestoreDateValue
+  updatedAt?: IFirestoreDateValue
+  authorName?: string
+  authorUuid?: string
+  /** Denormalized from the author doc so the public blog avoids a per-card author read. */
+  authorPhotoURL?: string
+  /** Denormalized author slug for linking to the author's public page. */
+  authorSlug?: string
+  /** Legacy field: author display name on older documents. */
+  author?: string
+  imageAlt?: string
+  imagePath?: string
+  imageURL?: string
+  /** Accent color for the post (used for the list icon and public theming). */
+  color?: string
+  tags?: string[]
+  /** Search/social title override; falls back to `title` (see resolvePostSeo). */
+  seoTitle?: string
+  /** Meta description override; falls back to `shortText`, then a body excerpt. */
+  seoDescription?: string
+  /** Social share image override; falls back to the cover, then the generated OG image. */
+  ogImageURL?: string
+  /** Absolute canonical URL override for republished content; defaults to the post URL. */
+  canonicalURL?: string
+  /** Hides the post from search engines and the sitemap while keeping it public. */
+  noindex?: boolean
+  /** Slug (document ID) of the `series/{slug}` this post belongs to. */
+  seriesSlug?: string
+  /** 1-based part number within the series. */
+  seriesOrder?: number
+  /** Shown in the blog home hero (published posts only). */
+  featured?: boolean
+  /** Hero order among featured posts, lower first; ties fall back to newest first. */
+  featuredOrder?: number
+}
+
+/**
+ * `postContents/{slug}` (published body) and `postDrafts/{slug}` (working body).
+ * `contents` is an HTML string.
+ */
+export interface IPostContent {
+  id?: string
+  contents: string
+  updatedAt?: IFirestoreDateValue
+}
+
+export type PostEventType
+  = | 'created'
+    | 'submitted'
+    | 'withdrawn'
+    | 'changes_requested'
+    | 'resolved'
+    | 'resubmitted'
+    | 'approved'
+    | 'scheduled'
+    | 'published'
+    | 'unpublished'
+
+/** `posts/{slug}/events/{autoId}` — workflow history, written by the server only. */
+export interface IPostEvent {
+  id?: string
+  type: PostEventType
+  from?: PostStatus
+  to?: PostStatus
+  note?: string
+  reasons?: string[]
+  actor: IPostActor
+  at: IFirestoreDateValue
+}

package/shared/models/series.ts

@@ -0,0 +1,14 @@
+import type { IFirestoreDateValue } from './date'
+
+/**
+ * `series/{slug}` — an ordered set of posts. The document ID is the URL slug.
+ * Posts join a series through `posts.seriesSlug` and are ordered by `posts.seriesOrder`.
+ */
+export interface ISeries {
+  id?: string
+  name: string
+  slug: string
+  description?: string
+  createdAt?: IFirestoreDateValue
+  updatedAt?: IFirestoreDateValue
+}

package/shared/models/settings.ts

@@ -0,0 +1,12 @@
+/**
+ * `settings/general` — site-wide branding and SEO metadata.
+ */
+export interface ISettings {
+  blogName: string
+  blogDescription?: string
+  blogKeywords?: string
+  blogURL?: string
+  logoURL?: string
+  primaryColor?: string
+  backgroundColor?: string
+}

package/shared/models/tag.ts

@@ -0,0 +1,15 @@
+import type { IFirestoreDateValue } from './date'
+
+/**
+ * `tags/{name}` — blog tag. The document ID is the display name (e.g. "CSS").
+ * Posts reference tags by this name (`posts.tags` is a string[] of names).
+ * `count` is the number of posts using the tag.
+ */
+export interface ITag {
+  id?: string
+  name: string
+  slug?: string
+  count?: number
+  createdAt?: IFirestoreDateValue
+  updatedAt?: IFirestoreDateValue
+}

package/shared/types/api.ts

@@ -0,0 +1,78 @@
+import type { IAuthor } from '../models/author'
+import type { IPost } from '../models/post'
+import type { ISeries } from '../models/series'
+import type { ISettings } from '../models/settings'
+import type { ITag } from '../models/tag'
+import type { IPostHeading } from '../utils/post-headings'
+
+/**
+ * Responses of the cached public read endpoints in `server/api`. Firestore Timestamps are
+ * serialized to Unix ms, so every payload is plain JSON.
+ */
+
+export interface ISettingsResponse {
+  settings: ISettings | null
+}
+
+export interface ITagsResponse {
+  tags: ITag[]
+}
+
+export interface IPostListResponse {
+  posts: IPost[]
+  hasMore: boolean
+}
+
+export interface IFeaturedPostsResponse {
+  /** Published `featured` posts for the home hero, `featuredOrder` first then newest (max 3). */
+  posts: IPost[]
+}
+
+export interface IPostSeriesPart {
+  slug: string
+  title: string
+  seriesOrder: number | null
+  isCurrent: boolean
+}
+
+/** The series a post belongs to, with its published parts in reading order. */
+export interface IPostSeries {
+  slug: string
+  name: string
+  description?: string
+  parts: IPostSeriesPart[]
+}
+
+export interface IPostPageResponse {
+  post: IPost
+  /** Body already sanitized and anchored on the server; rendered as-is. */
+  contents: string
+  headings: IPostHeading[]
+  readingTime: number
+  /** Plain-text excerpt of the raw body, the SEO description fallback. */
+  excerpt: string
+  author: IAuthor | null
+  related: IPost[]
+  older: IPost | null
+  newer: IPost | null
+  series: IPostSeries | null
+}
+
+export interface IAuthorPageResponse extends IPostListResponse {
+  author: IAuthor
+}
+
+export interface ITagPageResponse extends IPostListResponse {
+  tag: string
+}
+
+/** Series names by slug, for the series badge on post cards. */
+export interface ISeriesListResponse {
+  series: Array<Pick<ISeries, 'slug' | 'name'>>
+}
+
+export interface ISeriesPageResponse {
+  series: ISeries
+  /** Published parts in reading order. */
+  posts: IPost[]
+}

package/shared/utils/blog-path.ts

@@ -0,0 +1,23 @@
+/**
+ * Blog URL helpers. The blog mounts under `blog.basePath` (nuxt.config): `/` for a standalone blog,
+ * e.g. `/blog` when it is embedded in another site. Shared by pages, RSS, sitemap and SEO.
+ */
+
+/** `''` for the site root, otherwise `/segment(s)` with a leading and no trailing slash. */
+export function normalizeBasePath(base?: string | null): string {
+  const trimmed = (base ?? '').trim().replace(/^\/+|\/+$/g, '')
+  return trimmed ? `/${trimmed}` : ''
+}
+
+/** Blog-relative path → site path: (`/blog`, `/tags/css`) → `/blog/tags/css`; the root home is `/`. */
+export function joinBlogPath(base: string | null | undefined, path = '/'): string {
+  const relative = path.replace(/^\/+/, '')
+  return `${normalizeBasePath(base)}${relative ? `/${relative}` : ''}` || '/'
+}
+
+/** Absolute blog URL. The root home is the bare origin (`https://blog.example.com`, no trailing slash). */
+export function toBlogUrl(siteUrl: string, base: string | null | undefined, path = '/'): string {
+  const origin = siteUrl.replace(/\/+$/, '')
+  const sitePath = joinBlogPath(base, path)
+  return sitePath === '/' ? origin : `${origin}${sitePath}`
+}

package/shared/utils/blog.ts

@@ -0,0 +1,45 @@
+import type { IPost } from '../models/post'
+
+/** Convert an arbitrary string to a URL-safe slug. */
+export function toSlug(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** Resolve the best available author display name for a post (prefers new fields, then legacy, then `fallback`). */
+export function resolveAuthorName(post: Pick<IPost, 'authorName' | 'author'>, fallback = ''): string {
+  return post.authorName || post.author || fallback
+}
+
+/** Add the `.text-link` class to every prose `<a>` (merges existing classes; idempotent). */
+export function decorateBlogLinks(html: string): string {
+  if (!html)
+    return ''
+
+  return html.replace(/<a\b([^>]*)>/gi, (tag, attrs: string) => {
+    if (/\bclass\s*=\s*(["'])[^"']*\btext-link\b[^"']*\1/i.test(attrs))
+      return tag
+
+    if (/\bclass\s*=\s*["']/i.test(attrs))
+      return `<a${attrs.replace(/(\bclass\s*=\s*(["']))(.*?)(\2)/i, '$1$3 text-link$4')}>`
+
+    return `<a class="text-link"${attrs}>`
+  })
+}
+
+/** Strip HTML tags and collapse whitespace to build a plain-text excerpt. */
+export function htmlToExcerpt(html: string, maxLength = 160): string {
+  const text = (html || '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  if (text.length <= maxLength)
+    return text
+
+  return `${text.slice(0, maxLength - 1).trimEnd()}…`
+}

package/shared/utils/date.ts

@@ -0,0 +1,26 @@
+import type { IFirestoreDateValue } from '../models/date'
+
+/** Below this, a number is Unix seconds rather than milliseconds. */
+const MIN_SECONDS_TIMESTAMP = 10_000_000_000
+
+/** Firestore-ish date value (Date, Timestamp, `{ seconds }`, seconds/ms number, ISO string) → Unix ms, or `null`. */
+export function toDateMs(value: IFirestoreDateValue): number | null {
+  if (value == null || value === '')
+    return null
+
+  let ms: number
+  if (value instanceof Date)
+    ms = value.getTime()
+  else if (typeof value === 'number')
+    ms = value < MIN_SECONDS_TIMESTAMP ? value * 1000 : value
+  else if (typeof value === 'string')
+    ms = Date.parse(value)
+  else if ('toDate' in value && typeof value.toDate === 'function')
+    ms = value.toDate().getTime()
+  else if ('seconds' in value && typeof value.seconds === 'number')
+    ms = value.seconds * 1000
+  else
+    return null
+
+  return Number.isFinite(ms) && ms > 0 ? ms : null
+}

package/shared/utils/post-headings.ts

@@ -0,0 +1,134 @@
+import { toSlug } from './blog'
+
+export interface IPostHeading {
+  id: string
+  text: string
+  level: 2 | 3
+}
+
+export interface IPostHeadingsResult {
+  html: string
+  headings: IPostHeading[]
+}
+
+const WORDS_PER_MINUTE = 225
+const FALLBACK_HEADING_ID = 'section'
+const TAG_REGEX = /<(\/?)([a-z][\w-]*)\b([^>]*)>/gi
+const ID_ATTR_REGEX = /(?:^|\s)id\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i
+const SKIP_ATTR_REGEX = /\bdata-blog-widget\b/i
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: '\'',
+  nbsp: ' '
+}
+
+function decodeEntities(value: string): string {
+  return value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, code: string) => {
+    if (code[0] === '#') {
+      const point = code[1]?.toLowerCase() === 'x'
+        ? Number.parseInt(code.slice(2), 16)
+        : Number.parseInt(code.slice(1), 10)
+      return Number.isFinite(point) && point > 0 && point <= 0x10FFFF ? String.fromCodePoint(point) : entity
+    }
+
+    return NAMED_ENTITIES[code.toLowerCase()] ?? entity
+  })
+}
+
+function htmlToText(html: string): string {
+  return decodeEntities(html.replace(/<[^>]+>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function readIdAttr(attrs: string): string | null {
+  const match = attrs.match(ID_ATTR_REGEX)
+  if (!match)
+    return null
+
+  return match[1] ?? match[2] ?? match[3] ?? null
+}
+
+function uniqueId(base: string, used: Set<string>): string {
+  let candidate = base
+  let suffix = 2
+  while (used.has(candidate)) {
+    candidate = `${base}-${suffix}`
+    suffix++
+  }
+  used.add(candidate)
+  return candidate
+}
+
+/**
+ * Gives every top-level h2/h3 a stable, unique slug id and returns the TOC.
+ * String-based so SSR and client produce identical markup. Existing ids are kept,
+ * headings inside `<pre>` or widget placeholders are skipped (they are replaced on hydration).
+ */
+export function addHeadingAnchors(html: string): IPostHeadingsResult {
+  if (!html)
+    return { html: '', headings: [] }
+
+  const used = new Set<string>()
+  for (const match of html.matchAll(/<[a-z][\w-]*\b[^>]*>/gi)) {
+    const id = readIdAttr(match[0].slice(1))
+    if (id)
+      used.add(id)
+  }
+
+  const lowerHtml = html.toLowerCase()
+  const headings: IPostHeading[] = []
+  // Tracks the element whose subtree is skipped; depth counts nested tags of the same name
+  let skip: { tag: string, depth: number } | null = null
+
+  const output = html.replace(TAG_REGEX, (tag, closing: string, rawName: string, attrs: string, offset: number) => {
+    const name = rawName.toLowerCase()
+    const isSelfClosing = /\/\s*$/.test(attrs)
+
+    if (skip) {
+      if (name === skip.tag && !isSelfClosing) {
+        skip.depth += closing ? -1 : 1
+        if (skip.depth === 0)
+          skip = null
+      }
+      return tag
+    }
+
+    if (closing || isSelfClosing)
+      return tag
+
+    if (name === 'pre' || SKIP_ATTR_REGEX.test(attrs)) {
+      skip = { tag: name, depth: 1 }
+      return tag
+    }
+
+    if (name !== 'h2' && name !== 'h3')
+      return tag
+
+    const innerStart = offset + tag.length
+    const closeIndex = lowerHtml.indexOf(`</${name}`, innerStart)
+    const text = htmlToText(html.slice(innerStart, closeIndex === -1 ? undefined : closeIndex))
+    const level = name === 'h2' ? 2 : 3
+    const existingId = readIdAttr(attrs)
+
+    if (existingId) {
+      headings.push({ id: existingId, text, level })
+      return tag
+    }
+
+    const id = uniqueId(toSlug(text) || FALLBACK_HEADING_ID, used)
+    headings.push({ id, text, level })
+    return `<${rawName} id="${id}"${attrs}>`
+  })
+
+  return { html: output, headings }
+}
+
+/** Estimated reading time in minutes (225 wpm, at least 1). */
+export function estimateReadingTime(html: string): number {
+  const words = htmlToText(html || '').split(' ').filter(Boolean).length
+  return Math.max(1, Math.round(words / WORDS_PER_MINUTE))
+}

package/shared/utils/post-seo.ts

@@ -0,0 +1,58 @@
+import type { IPost } from '../models/post'
+import { toBlogUrl } from './blog-path'
+
+/**
+ * Per-post SEO resolution shared by blog-admin (editor previews) and the public blog
+ * (post page meta). DUPLICATED byte-identically into blog/shared/utils/post-seo.ts so the
+ * editor preview always matches what the blog outputs.
+ */
+
+/** Constants */
+export const SEO_TITLE_MAX = 60
+export const SEO_DESCRIPTION_MAX = 160
+
+/** Interfaces */
+export type IPostSeoSource = Pick<IPost, 'slug' | 'id' | 'title' | 'shortText' | 'imageURL' | 'imageAlt' | 'seoTitle' | 'seoDescription' | 'ogImageURL' | 'canonicalURL' | 'noindex'>
+
+export interface IPostSeoOptions {
+  /** Public site origin, e.g. https://blog.colorffy.com */
+  siteUrl: string
+  /** Where the blog mounts on that site (`blog.basePath`); defaults to the root. */
+  basePath?: string
+  /** Plain-text excerpt of the body, used when neither seoDescription nor shortText is set. */
+  bodyExcerpt?: string
+  /** Generated OG image URL, used when the post has no custom social image or cover. */
+  generatedImage?: string | null
+}
+
+export interface IResolvedPostSeo {
+  title: string
+  description: string
+  image: string | null
+  imageAlt: string
+  canonical: string
+  robots: 'index,follow' | 'noindex,follow'
+  noindex: boolean
+}
+
+/** Helpers */
+function clean(value: string | null | undefined): string {
+  return (value ?? '').replace(/\s+/g, ' ').trim()
+}
+
+export function resolvePostSeo(post: IPostSeoSource, options: IPostSeoOptions): IResolvedPostSeo {
+  const slug = clean(post.slug) || clean(post.id)
+  const title = clean(post.seoTitle) || clean(post.title) || 'Article'
+  const noindex = post.noindex === true
+
+  return {
+    title,
+    description: clean(post.seoDescription) || clean(post.shortText) || clean(options.bodyExcerpt),
+    // Custom social image beats the cover; the generated card is only a fallback.
+    image: clean(post.ogImageURL) || clean(post.imageURL) || clean(options.generatedImage) || null,
+    imageAlt: clean(post.imageAlt) || clean(post.title),
+    canonical: clean(post.canonicalURL) || toBlogUrl(options.siteUrl, options.basePath, `/${slug}`),
+    robots: noindex ? 'noindex,follow' : 'index,follow',
+    noindex
+  }
+}

package/shared/utils/sanitize.ts

@@ -0,0 +1,80 @@
+import sanitizeHtml from 'sanitize-html'
+
+/**
+ * Server-side clean for post bodies shown with `v-html` (the post API only; the client
+ * never imports it). Same allowlist as blog-admin's
+ * `server/utils/sanitizePostHtml.ts` (the publish-time pass), so published markup survives untouched:
+ * code blocks keep `language-xxx`, widget placeholders keep `data-blog-widget` + `data-props`,
+ * external links get `rel="noopener nofollow"` + `target="_blank"` and images `img-fluid`.
+ * Only addition: `id` on h2/h3, so heading ids already in the stored markup are kept for the TOC.
+ */
+export function sanitizeBlogHtml(html: string): string {
+  if (!html)
+    return ''
+
+  return sanitizeHtml(html, {
+    allowedTags: [
+      'p',
+      'br',
+      'hr',
+      'div',
+      'span',
+      'h1',
+      'h2',
+      'h3',
+      'h4',
+      'h5',
+      'h6',
+      'strong',
+      'b',
+      'em',
+      'i',
+      's',
+      'u',
+      'code',
+      'pre',
+      'blockquote',
+      'ul',
+      'ol',
+      'li',
+      'a',
+      'img',
+      'figure',
+      'figcaption',
+      'table',
+      'thead',
+      'tbody',
+      'tr',
+      'th',
+      'td'
+    ],
+    allowedAttributes: {
+      '*': ['class'],
+      'a': ['href', 'name', 'target', 'rel'],
+      'img': ['src', 'alt', 'title', 'width', 'height'],
+      'div': ['data-blog-widget', 'data-props'],
+      'h2': ['id'],
+      'h3': ['id'],
+      'td': ['colspan', 'rowspan'],
+      'th': ['colspan', 'rowspan']
+    },
+    allowedSchemes: ['http', 'https', 'mailto'],
+    transformTags: {
+      a: (tagName, attribs) => {
+        const href = attribs.href ?? ''
+        if (/^https?:\/\//i.test(href)) {
+          attribs.rel = 'noopener nofollow'
+          attribs.target = '_blank'
+        }
+        return { tagName, attribs }
+      },
+      img: (tagName, attribs) => {
+        const classes = (attribs.class ?? '').split(/\s+/).filter(Boolean)
+        if (!classes.includes('img-fluid'))
+          classes.push('img-fluid')
+        attribs.class = classes.join(' ')
+        return { tagName, attribs }
+      }
+    }
+  })
+}

package/shared/widgets/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Interactive blog widget contract.
+ *
+ * This file is the single source of truth for widget metadata and is DUPLICATED
+ * byte-identically into blog-admin/shared/widgets/ (two independent repos). Keep it
+ * free of Vue/runtime imports so both the public renderer and the admin editor can
+ * consume it. The public site maps each `key` to an actual Vue component separately
+ * (app/widgets/component-map.ts).
+ */
+export type WidgetPropType = 'string' | 'number' | 'boolean' | 'color' | 'enum'
+
+export interface WidgetPropOption {
+  value: string
+  label: string
+}
+
+export interface WidgetPropSchema {
+  type: WidgetPropType
+  label: string
+  default: string | number | boolean
+  required?: boolean
+  help?: string
+  /** enum only */
+  options?: WidgetPropOption[]
+  /** number only */
+  min?: number
+  max?: number
+  step?: number
+}
+
+export interface WidgetDescriptor {
+  /** Stored verbatim in the `data-blog-widget` attribute. */
+  key: string
+  name: string
+  description: string
+  /** Material Symbols HTML entity code point, e.g. `` (optional). */
+  icon?: string
+  /** px reserved by the placeholder before hydration, to avoid layout shift. */
+  minHeight?: number
+  props: Record<string, WidgetPropSchema>
+}