@giancarlosgza/blog-layer 0.0.0-stage → 0.1.0

package/app/composables/useDateValue.ts

@@ -0,0 +1,27 @@
+import type { IFirestoreDateValue } from '#blog/shared/models/date'
+import { toDateMs } from '#blog/shared/utils/date'
+
+/** Normalize Date, Firestore Timestamp, serialized timestamps, and strings to milliseconds. */
+export function useDateValue() {
+  function normalizeDateValue(value?: IFirestoreDateValue): number {
+    return toDateMs(value) ?? 0
+  }
+
+  /** Format a Firestore-ish date value to a human-readable string. */
+  function formatDateValue(value?: IFirestoreDateValue, options?: Intl.DateTimeFormatOptions): string {
+    const ms = normalizeDateValue(value)
+    if (!ms)
+      return ''
+
+    return new Date(ms).toLocaleDateString('en-US', options ?? {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric'
+    })
+  }
+
+  return {
+    normalizeDateValue,
+    formatDateValue
+  }
+}

package/app/composables/usePaginatedPosts.ts

@@ -0,0 +1,57 @@
+import type { IPost } from '#blog/shared/models/post'
+import type { IPostListResponse } from '#blog/shared/types/api'
+
+/** Interfaces */
+type TPaginatedState<T extends IPostListResponse> = T & { page: number }
+
+/** Appends a page, skipping posts already listed (a publish between pages shifts the window). */
+export function appendPosts(current: IPost[], next: IPost[]): IPost[] {
+  const seen = new Set(current.map(post => post.id))
+  return [...current, ...next.filter(post => !seen.has(post.id))]
+}
+
+/**
+ * A "load more" post list (tag and author pages) over a cached endpoint taking `?page=N`.
+ * Page 1 renders on the server; each "load more" fetches the next page and appends it.
+ */
+export function usePaginatedPosts<T extends IPostListResponse>(key: string, url: string) {
+  const { state, data, pending, error, ready } = useCachedResource<TPaginatedState<T>>(
+    key,
+    async () => ({ ...(await $fetch<T>(url)), page: 1 })
+  )
+
+  /** State */
+  const isLoadingMore = ref(false)
+
+  /** Computed */
+  const posts = computed<IPost[]>(() => data.value?.posts ?? [])
+  const hasMore = computed(() => data.value?.hasMore ?? false)
+
+  /** Methods */
+  async function loadMore(): Promise<void> {
+    const current = state.value
+    if (!current || !current.hasMore || isLoadingMore.value)
+      return
+
+    isLoadingMore.value = true
+    try {
+      const page = current.page + 1
+      const next = await $fetch<T>(url, { query: { page } })
+      state.value = { ...current, ...next, posts: appendPosts(current.posts, next.posts), page }
+    } catch {
+      // Keeps the loaded pages; the button stays available to retry.
+    } finally {
+      isLoadingMore.value = false
+    }
+  }
+
+  return {
+    data,
+    posts,
+    hasMore,
+    pending: computed(() => pending.value || isLoadingMore.value),
+    error,
+    ready,
+    loadMore
+  }
+}

package/app/composables/usePostFeed.ts

@@ -0,0 +1,139 @@
+import type { IPost } from '#blog/shared/models/post'
+import type { IFeaturedPostsResponse, IPostListResponse, ITagsResponse } from '#blog/shared/types/api'
+
+/** Interfaces */
+interface IPostFeedState extends IPostListResponse {
+  page: number
+}
+
+/**
+ * Home hero posts: the featured ones when any exist, else the latest post.
+ * `featured` comes from `/api/blog/featured` (already published-only, ordered and capped).
+ */
+export function homeHeroPosts(featured: IPost[], latest: IPost[]): IPost[] {
+  if (featured.length)
+    return featured
+  return latest.slice(0, 1)
+}
+
+/** `posts` without the ones already shown in the hero. */
+export function excludePosts(posts: IPost[], shown: IPost[]): IPost[] {
+  if (!shown.length)
+    return posts
+  const ids = new Set(shown.map(post => post.id))
+  return posts.filter(post => !ids.has(post.id))
+}
+
+/**
+ * Home post feed: published posts (newest first) with a `?tag=` synced filter,
+ * incremental "load more" pagination, the featured hero posts and the popularity-ordered tag list.
+ *
+ * Reads the cached `/api/blog/posts` (tag filtered server-side, so `?tag=` is a real server render)
+ * and `/api/blog/tags`. Feeds are kept per tag in one `post-feed` state: the server only fills the
+ * requested one, and switching back to a loaded tag on the client reuses it.
+ */
+export function usePostFeed() {
+  const route = useRoute()
+  const router = useRouter()
+
+  /** Tag filter */
+  const selectedTag = computed<string | null>({
+    get: () => route.query.tag?.toString() || null,
+    set: (value) => {
+      router.push({ query: { ...route.query, tag: value || undefined } })
+    }
+  })
+
+  /** Tags */
+  const { data: tagsData } = useCachedResource<ITagsResponse>('blog-tags', () => $fetch<ITagsResponse>('/api/blog/tags'))
+  const tags = computed(() => tagsData.value?.tags ?? [])
+
+  /** Featured (a failed read falls back to the latest post) */
+  const { data: featuredData, ready: featuredReady } = useCachedResource<IFeaturedPostsResponse>(
+    'blog-featured',
+    () => $fetch<IFeaturedPostsResponse>('/api/blog/featured')
+  )
+
+  /** Posts */
+  const feeds = useState<Record<string, IPostFeedState>>('post-feed', () => ({}))
+  const isLoadingMore = ref(false)
+  const error = ref<unknown>(null)
+  const feedKey = computed(() => (selectedTag.value ? `tag:${selectedTag.value}` : 'all'))
+  const feed = computed<IPostFeedState | undefined>(() => feeds.value[feedKey.value])
+
+  function fetchPage(tag: string | null, page: number): Promise<IPostListResponse> {
+    return $fetch<IPostListResponse>('/api/blog/posts', { query: { page, tag: tag || undefined } })
+  }
+
+  async function loadFeed(key: string, tag: string | null): Promise<void> {
+    try {
+      const response = await fetchPage(tag, 1)
+      feeds.value = { ...feeds.value, [key]: { ...response, page: 1 } }
+    } catch (loadError) {
+      error.value = loadError
+      feeds.value = { ...feeds.value, [key]: { posts: [], hasMore: false, page: 1 } }
+    }
+  }
+
+  let feedReady: Promise<unknown> = Promise.resolve()
+  if (import.meta.server) {
+    // useAsyncData blocks SSR until the fetch resolves, so the filled state is serialized.
+    feedReady = useAsyncData(`post-feed-${feedKey.value}`, async () => {
+      if (!feed.value)
+        await loadFeed(feedKey.value, selectedTag.value)
+      return true
+    })
+  } else {
+    watch(feedKey, (key) => {
+      if (!feeds.value[key])
+        loadFeed(key, selectedTag.value)
+    }, { immediate: true })
+  }
+
+  /** Computed */
+  const posts = computed<IPost[]>(() => feed.value?.posts ?? [])
+  const pending = computed(() => !feed.value || isLoadingMore.value)
+  const hasMore = computed(() => feed.value?.hasMore ?? false)
+  const heroPosts = computed<IPost[]>(() =>
+    selectedTag.value ? [] : homeHeroPosts(featuredData.value?.posts ?? [], posts.value)
+  )
+  const featuredPost = computed<IPost | null>(() => heroPosts.value[0] ?? null)
+  const secondaryFeaturedPosts = computed<IPost[]>(() => heroPosts.value.slice(1))
+  const gridPosts = computed(() => excludePosts(posts.value, heroPosts.value))
+
+  /** Methods */
+  async function loadMore(): Promise<void> {
+    const key = feedKey.value
+    const current = feeds.value[key]
+    if (!current || !current.hasMore || isLoadingMore.value)
+      return
+
+    isLoadingMore.value = true
+    try {
+      const page = current.page + 1
+      const response = await fetchPage(selectedTag.value, page)
+      feeds.value = {
+        ...feeds.value,
+        [key]: { posts: appendPosts(current.posts, response.posts), hasMore: response.hasMore, page }
+      }
+    } catch {
+      // Keeps the loaded pages; the button stays available to retry.
+    } finally {
+      isLoadingMore.value = false
+    }
+  }
+
+  return {
+    tags,
+    posts,
+    pending,
+    selectedTag,
+    hasMore,
+    featuredPost,
+    secondaryFeaturedPosts,
+    gridPosts,
+    loadMore,
+    error,
+    ready: Promise.all([feedReady, featuredReady])
+  }
+}

package/app/composables/useSeriesNames.ts

@@ -0,0 +1,20 @@
+import type { ISeriesListResponse } from '#blog/shared/types/api'
+
+/**
+ * Series names by slug from the cached `/api/blog/series`, shared by every post card
+ * (`seriesSlug` is all a post stores). Unknown slugs resolve to `null`, hiding the badge.
+ */
+export function useSeriesNames() {
+  const { data } = useCachedResource<ISeriesListResponse['series']>(
+    'blog-series-names',
+    async () => (await $fetch<ISeriesListResponse>('/api/blog/series')).series
+  )
+
+  const names = computed(() => new Map((data.value ?? []).map(series => [series.slug, series.name])))
+
+  function seriesName(slug: string | null | undefined): string | null {
+    return slug ? names.value.get(slug) ?? null : null
+  }
+
+  return { seriesName }
+}

package/app/composables/useShikiHighlighter.ts

@@ -0,0 +1,108 @@
+import type { Highlighter, LanguageRegistration } from 'shiki'
+import bash from '@shikijs/langs/bash'
+import css from '@shikijs/langs/css'
+import html from '@shikijs/langs/html'
+import javascript from '@shikijs/langs/javascript'
+import json from '@shikijs/langs/json'
+import sass from '@shikijs/langs/sass'
+import scss from '@shikijs/langs/scss'
+import typescript from '@shikijs/langs/typescript'
+import xml from '@shikijs/langs/xml'
+import yaml from '@shikijs/langs/yaml'
+import githubDark from '@shikijs/themes/github-dark-default'
+import githubLight from '@shikijs/themes/github-light'
+import { createHighlighter } from 'shiki'
+
+// Global singleton instance
+let highlighterInstance: Highlighter | null = null
+let highlighterPromise: Promise<Highlighter> | null = null
+
+/** Theme ids loaded into the highlighter (mirrors the colorffy CSS dialog). */
+export const SHIKI_LIGHT_THEME = 'github-light'
+export const SHIKI_DARK_THEME = 'github-dark-default'
+
+/** Canonical language fallback when a code block has no (or an unknown) language. */
+export const SHIKI_DEFAULT_LANG = 'css'
+
+// Map of supported languages (web-focused set for the blog).
+const supportedLanguages: Record<string, LanguageRegistration | LanguageRegistration[]> = {
+  css,
+  scss,
+  sass,
+  html,
+  xml,
+  javascript,
+  typescript,
+  json,
+  bash,
+  yaml
+}
+
+/** Common aliases authors/editors may emit (`language-js`, ```ts, …) → canonical lang. */
+const languageAliases: Record<string, string> = {
+  js: 'javascript',
+  mjs: 'javascript',
+  cjs: 'javascript',
+  jsx: 'javascript',
+  ts: 'typescript',
+  tsx: 'typescript',
+  yml: 'yaml',
+  sh: 'bash',
+  shell: 'bash',
+  zsh: 'bash',
+  console: 'bash',
+  htm: 'html',
+  svg: 'xml'
+}
+
+const supportedLanguageSet = new Set(Object.keys(supportedLanguages))
+
+/**
+ * Normalize a detected language token to one the highlighter actually loaded.
+ * Unknown / empty languages fall back to {@link SHIKI_DEFAULT_LANG} so `codeToHtml`
+ * never throws on content that wasn't tagged in the editor.
+ */
+export function resolveShikiLang(lang?: string | null): string {
+  const normalized = (lang || '').trim().toLowerCase()
+  if (!normalized)
+    return SHIKI_DEFAULT_LANG
+
+  const canonical = languageAliases[normalized] ?? normalized
+  return supportedLanguageSet.has(canonical) ? canonical : SHIKI_DEFAULT_LANG
+}
+
+/**
+ * Shiki syntax highlighter singleton for blog code blocks.
+ * - Lazy-loads the highlighter on first access
+ * - Reuses a single instance across the app
+ * - Loads both the light and dark GitHub themes so blocks can re-theme on the fly
+ */
+export function useShikiHighlighter() {
+  /** Resolve (or create) the shared Shiki highlighter instance. */
+  const getHighlighter = async (): Promise<Highlighter> => {
+    if (highlighterInstance) {
+      return highlighterInstance
+    }
+
+    if (highlighterPromise) {
+      return highlighterPromise
+    }
+
+    const languageValues = Object.values(supportedLanguages).flat() as LanguageRegistration[]
+
+    highlighterPromise = createHighlighter({
+      themes: [githubLight, githubDark],
+      langs: languageValues
+    }).then((highlighter) => {
+      highlighterInstance = highlighter
+      highlighterPromise = null
+      return highlighter
+    })
+
+    return highlighterPromise
+  }
+
+  return {
+    getHighlighter
+  }
+}

package/app/composables/useSiteSchemaLd.ts

@@ -0,0 +1,44 @@
+/**
+ * Injects the site-wide `Organization` and `WebSite` JSON-LD into every page.
+ *
+ * Both nodes carry a stable `@id` so per-page structured data (`BlogPosting`,
+ * breadcrumbs, etc.) can reference them via `publisher`/`@id` instead of
+ * redefining them. No `SearchAction`: the blog has no search. Call once, in `app.vue`.
+ */
+export function useSiteSchemaLd() {
+  const siteUrl = useSiteUrl()
+  const brand = useAppConfig().blog
+  const organizationId = `${siteUrl}/#organization`
+  const websiteId = `${siteUrl}/#website`
+
+  const organizationLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    '@id': organizationId,
+    'name': brand.organization.name || brand.name,
+    'url': brand.organization.url || siteUrl,
+    'logo': {
+      '@type': 'ImageObject',
+      'url': `${siteUrl}/pwa-512x512.png`,
+      'width': 512,
+      'height': 512
+    },
+    ...(brand.organization.sameAs.length ? { sameAs: brand.organization.sameAs } : {})
+  }
+
+  const websiteLd = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    '@id': websiteId,
+    'name': brand.name,
+    'url': siteUrl,
+    'publisher': { '@id': organizationId }
+  }
+
+  useHead({
+    script: [
+      { type: 'application/ld+json', innerHTML: JSON.stringify(organizationLd) },
+      { type: 'application/ld+json', innerHTML: JSON.stringify(websiteLd) }
+    ]
+  })
+}

package/app/composables/useSiteUrl.ts

@@ -0,0 +1,4 @@
+/** Returns the resolved canonical site URL from Nuxt Site Config. */
+export function useSiteUrl(): string {
+  return useSiteConfig().url
+}

package/app/utils/widget-props.ts

@@ -0,0 +1,66 @@
+import type { WidgetDescriptor } from '#blog/shared/widgets/types'
+
+/** Safely parse a widget's `data-props` JSON into a plain object. Never throws. */
+export function safeParseProps(raw: string | null | undefined): Record<string, unknown> {
+  if (!raw)
+    return {}
+
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+function clamp(value: number, min?: number, max?: number): number {
+  let result = value
+  if (typeof min === 'number')
+    result = Math.max(min, result)
+  if (typeof max === 'number')
+    result = Math.min(max, result)
+  return result
+}
+
+/**
+ * Coerce raw (untrusted) props against a widget descriptor's schema.
+ * Always returns a fully-populated, type-correct props object: invalid or missing
+ * values fall back to the schema default, numbers are clamped, enums validated.
+ */
+export function coerceProps(
+  raw: Record<string, unknown>,
+  descriptor: WidgetDescriptor
+): { props: Record<string, unknown> } {
+  const props: Record<string, unknown> = {}
+
+  for (const [key, schema] of Object.entries(descriptor.props)) {
+    const value = raw[key]
+
+    switch (schema.type) {
+      case 'number': {
+        const num = typeof value === 'number' ? value : Number(value)
+        props[key] = Number.isFinite(num) ? clamp(num, schema.min, schema.max) : schema.default
+        break
+      }
+      case 'boolean': {
+        props[key] = typeof value === 'boolean' ? value : Boolean(schema.default)
+        break
+      }
+      case 'enum': {
+        const allowed = (schema.options ?? []).map(option => option.value)
+        props[key] = typeof value === 'string' && allowed.includes(value) ? value : schema.default
+        break
+      }
+      case 'color':
+      case 'string':
+      default: {
+        props[key] = typeof value === 'string' && value.trim() ? value : schema.default
+        break
+      }
+    }
+  }
+
+  return { props }
+}

package/app/widgets/WidgetError.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+defineProps<{ reason?: string }>()
+</script>
+
+<template>
+  <div class="widget-error" role="alert">
+    <UiIconMaterial icon-code="&#xe40a;" />
+    <span>
+      <strong>Interactive widget unavailable</strong>
+      <template v-if="reason"> — {{ reason }}</template>
+    </span>
+  </div>
+</template>

package/blog-module.ts

@@ -0,0 +1,71 @@
+import type { NuxtPage } from 'nuxt/schema'
+import { addServerHandler, createResolver, defineNuxtModule, extendPages } from 'nuxt/kit'
+import { joinBlogPath, normalizeBasePath } from './shared/utils/blog-path'
+
+export interface BlogModuleOptions {
+  /** Where the blog mounts: `/` for a standalone blog, e.g. `/blog` inside another site. Build time. */
+  basePath: string
+  /** Layout for the blog pages; defaults to the site's `default` layout. */
+  layout?: string
+}
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig {
+    blog?: Partial<BlogModuleOptions>
+  }
+  interface NuxtOptions {
+    blog: BlogModuleOptions
+  }
+}
+
+/**
+ * Mounts the blog under `blog.basePath`: its pages (named `blog`, `blog-post`, `blog-archive`,
+ * `blog-tag`, `blog-author`, `blog-series`), the RSS feed at `<basePath>/rss.xml` and the SWR
+ * route rules. The API always lives under `/api/blog/*`. Exposes the normalized base path as
+ * `runtimeConfig.public.blog.basePath` for links, canonicals, RSS and the sitemap.
+ */
+export default defineNuxtModule<BlogModuleOptions>({
+  meta: { name: 'blog', configKey: 'blog' },
+  defaults: { basePath: '/' },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+    const basePath = normalizeBasePath(options.basePath)
+    const path = (relative: string) => joinBlogPath(basePath, relative)
+
+    nuxt.options.runtimeConfig.public.blog = { basePath: basePath || '/' }
+
+    extendPages((pages) => {
+      const page = (name: string, routePath: string, file: string): NuxtPage => ({
+        name,
+        path: routePath,
+        file: resolve(`./app/blog-pages/${file}.vue`),
+        ...(options.layout ? { meta: { layout: options.layout } } : {})
+      })
+
+      pages.push(
+        page('blog', path('/'), 'home'),
+        page('blog-archive', path('/page/:page'), 'archive'),
+        page('blog-tag', path('/tags/:tag'), 'tag'),
+        page('blog-author', path('/authors/:slug'), 'author'),
+        page('blog-series', path('/series/:slug'), 'series'),
+        page('blog-post', path('/:slug'), 'post')
+      )
+    })
+
+    addServerHandler({ route: path('/rss.xml'), handler: resolve('./server/handlers/rss.xml.ts') })
+
+    // Firestore-backed pages are cached like the /api data they render (5 min). Posts are cached
+    // at the API layer only: Nitro resolves route-level cache per handler, and the catch-all
+    // renderer matches any single-segment rule, which would swr-cache every rendered page.
+    // Rules the site defines for the same paths win.
+    const swr = { swr: 300 }
+    nuxt.options.routeRules = {
+      [path('/')]: swr,
+      [path('/page/**')]: swr,
+      [path('/authors/**')]: swr,
+      [path('/tags/**')]: swr,
+      [path('/series/**')]: swr,
+      ...nuxt.options.routeRules
+    }
+  }
+})

package/nuxt.config.ts

@@ -0,0 +1,80 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import blogModule from './blog-module'
+
+const layerDir = dirname(fileURLToPath(import.meta.url))
+
+/** Blog layer: pages under `blog.basePath`, `/api/blog/*`, RSS, sitemap and SEO */
+export default defineNuxtConfig({
+  compatibilityDate: '2026-01-01',
+
+  alias: {
+    '#blog': layerDir
+  },
+
+  // Pages come from blog-module, no pages/ dir
+  pages: true,
+
+  blog: {
+    basePath: '/'
+  },
+
+  nitro: {
+    // fs cache breaks on Windows with ?query keys
+    devStorage: {
+      cache: { driver: 'memory' }
+    }
+  },
+
+  runtimeConfig: {
+    siteUrl: '',
+
+    public: {
+      blog: {
+        basePath: '/'
+      }
+    }
+  },
+
+  css: [join(layerDir, 'app/assets/scss/main.scss')],
+
+  modules: [
+    blogModule,
+    '@colorffy/ui/nuxt',
+    'nuxt-og-image',
+    '@nuxt/image',
+    '@nuxtjs/color-mode',
+    '@nuxtjs/sitemap',
+    '@vueuse/nuxt'
+  ],
+
+  // SEO
+  sitemap: {
+    sources: ['/api/blog/_sitemap-urls']
+  },
+
+  // Color mode (`.dark-mode` class)
+  colorMode: {
+    preference: 'system',
+    classSuffix: '-mode'
+  },
+
+  // Image
+  image: {
+    provider: 'ipx',
+    presets: {
+      logo: {
+        modifiers: {
+          format: 'webp',
+          quality: 50
+        }
+      },
+      cover: {
+        modifiers: {
+          format: 'webp',
+          quality: 70
+        }
+      }
+    }
+  }
+})

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@giancarlosgza/blog-layer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Nuxt layer that adds a Firestore-backed blog to a site under a configurable base path: pages, cached API, RSS, sitemap and SEO",
+  "author": "Giancarlos Garza <giancarlosgza@gmail.com> (https://github.com/giancarlosgza)",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "bin": {
+    "blog-layer-subset-icons": "./scripts/subset-icons.mjs"
+  },
+  "files": [
+    "app",
+    "blog-module.ts",
+    "nuxt.config.ts",
+    "scripts",
+    "server",
+    "shared",
+    "!server/tsconfig.json"
+  ],
+  "peerDependencies": {
+    "nuxt": "^4.5.0",
+    "vue": "^3.5.0",
+    "vue-router": "^5.0.0"
+  },
+  "dependencies": {
+    "@colorffy/css": "3.0.0",
+    "@colorffy/ui": "3.0.0",
+    "@material-symbols/font-700": "0.47.6",
+    "@nuxt/image": "2.1.0",
+    "@nuxtjs/color-mode": "4.0.1",
+    "@nuxtjs/sitemap": "8.6.1",
+    "@shikijs/langs": "4.5.0",
+    "@shikijs/themes": "4.5.0",
+    "@takumi-rs/core": "2.14.0",
+    "@types/sanitize-html": "2.16.2",
+    "@vueuse/components": "14.4.0",
+    "@vueuse/core": "14.4.0",
+    "@vueuse/nuxt": "14.4.0",
+    "firebase-admin": "13.10.0",
+    "floating-vue": "5.4.0",
+    "nuxt-og-image": "6.10.3",
+    "sanitize-html": "2.18.0",
+    "sass": "1.105.1",
+    "shiki": "4.5.0",
+    "subset-font": "2.9.0"
+  }
 }