@giancarlosgza/blog-layer 0.0.0-stage → 0.1.0

package/app/components/blog/BlogPostCard.vue

@@ -0,0 +1,208 @@
+<script setup lang="ts">
+import type { IPost } from '#blog/shared/models/post'
+
+/** Interfaces */
+interface IProps {
+  post: IPost
+  featured?: boolean
+  badge?: string
+  badgeIcon?: string
+  showSeries?: boolean
+  isSkeleton?: boolean
+  headingTag?: 'h2' | 'h3'
+}
+
+/** Props */
+const {
+  post,
+  featured = false,
+  badge = '',
+  badgeIcon = '',
+  showSeries = true,
+  isSkeleton = false,
+  headingTag = 'h2'
+} = defineProps<IProps>()
+
+/** Constants */
+const MAX_TAGS = 2
+const MAX_FEATURED_TAGS = 3
+
+/** Composables */
+const { blogPath } = useBlogPath()
+const { formatDateValue, normalizeDateValue } = useDateValue()
+const brand = useAppConfig().blog
+const { seriesName } = useSeriesNames()
+const activePost = useState<string | null>('activePost', () => null)
+
+/** Computed */
+const slug = computed(() => post.slug || post.id || '')
+const authorName = computed(() => resolveAuthorName(post, brand.defaultAuthor))
+const authorInitial = computed(() => authorName.value.charAt(0).toUpperCase())
+const publishedLabel = computed(() => formatDateValue(post.createdAt))
+const publishedIso = computed(() => {
+  const published = normalizeDateValue(post.createdAt)
+  return published ? new Date(published).toISOString() : undefined
+})
+const series = computed(() => {
+  const name = showSeries ? seriesName(post.seriesSlug) : null
+  return name ? { name, to: blogPath(`/series/${post.seriesSlug}`) } : null
+})
+const badgeText = computed(() => badge || (featured ? 'Featured' : ''))
+const badgeIconCode = computed(() => (badge ? badgeIcon || undefined : '&#xf525;'))
+const displayedTags = computed(() => post.tags?.slice(0, featured ? MAX_FEATURED_TAGS : MAX_TAGS) ?? [])
+const isTransitionTarget = computed(() => activePost.value === slug.value)
+
+/** Methods */
+function markActive(): void {
+  activePost.value = slug.value
+}
+</script>
+
+<template>
+  <article
+    :aria-busy="isSkeleton || undefined"
+    :aria-label="isSkeleton ? 'Loading article' : undefined"
+  >
+    <UiCard
+      variant="pane"
+      class="card-post"
+      :class="{ 'wide-post': featured, 'card-post-skeleton': isSkeleton }"
+    >
+      <template #header>
+        <!-- Cover -->
+        <div class="card-post-cover">
+          <NuxtImg
+            v-if="!isSkeleton && post.imageURL"
+            :src="post.imageURL"
+            :alt="post.imageAlt || post.title"
+            :loading="featured ? 'eager' : 'lazy'"
+            width="1200"
+            height="630"
+            :sizes="featured ? 'sm:100vw md:50vw xl:640px' : 'sm:100vw md:50vw xl:400px'"
+            preset="cover"
+            class="img-fluid"
+            :class="{ 'vt-post-image': isTransitionTarget }"
+          />
+        </div>
+      </template>
+      <template #body>
+        <!-- Skeleton -->
+        <div
+          v-if="isSkeleton"
+          class="card-post-details"
+          aria-hidden="true"
+        >
+          <UiBaseSkeleton width="9rem" />
+          <UiBaseSkeleton
+            size="md"
+            width="85%"
+          />
+          <UiBaseSkeleton width="95%" />
+          <UiBaseSkeleton width="10rem" />
+        </div>
+
+        <!-- Details -->
+        <div
+          v-else
+          class="card-post-details"
+        >
+          <!-- Series, badge and date -->
+          <div class="card-post-meta">
+            <UiBadge
+              v-if="badgeText"
+              variant="tonal tonal-accent"
+              :text="badgeText"
+              :icon-code="badgeIconCode"
+            />
+            <NuxtLink
+              v-if="series"
+              :to="series.to"
+              class="card-post-chip badge badge-tonal tonal-secondary undecorated"
+              :title="`Part of the ${series.name} series`"
+            >
+              {{ series.name }}
+            </NuxtLink>
+            <time
+              v-if="publishedLabel"
+              :datetime="publishedIso"
+              class="caption text-muted"
+            >
+              {{ publishedLabel }}
+            </time>
+          </div>
+
+          <component
+            :is="headingTag"
+            class="card-post-title mb-0"
+            :class="featured ? 'display-3' : 'fs-xl fw-500 lh-base'"
+          >
+            <NuxtLink
+              :to="blogPath(`/${slug}`)"
+              class="card-post-link undecorated"
+              @pointerdown="markActive"
+            >
+              <span
+                class="d-block"
+                :class="{ 'vt-post-header': isTransitionTarget }"
+              >{{ post.title }}</span>
+            </NuxtLink>
+          </component>
+
+          <p
+            class="card-post-excerpt text-muted lh-md mb-0"
+            :class="featured ? 'body-1' : 'body-2'"
+          >
+            {{ post.shortText }}
+          </p>
+
+          <!-- Tags -->
+          <div class="card-post-tags">
+            <NuxtLink
+              v-for="tag in displayedTags"
+              :key="tag"
+              :to="blogPath(`/tags/${encodeURIComponent(tag)}`)"
+              class="card-post-chip badge badge-tonal tonal-secondary undecorated"
+            >
+              {{ tag }}
+            </NuxtLink>
+          </div>
+
+          <!-- Author (featured only) -->
+          <div
+            v-if="featured"
+            class="d-flex align-items-center gap-2"
+          >
+            <UiAvatar
+              v-if="post.authorPhotoURL"
+              :src="post.authorPhotoURL"
+              :alt="`${authorName} photo`"
+              size="sm"
+            />
+            <UiAvatar
+              v-else
+              :initials="authorInitial"
+              :alt="`${authorName} photo`"
+              size="sm"
+              color="secondary"
+              variant="tonal"
+              class="me-0"
+            />
+            <NuxtLink
+              v-if="post.authorSlug"
+              :to="blogPath(`/authors/${post.authorSlug}`)"
+              class="card-post-author caption text-muted fw-400 undecorated"
+            >
+              {{ authorName }}
+            </NuxtLink>
+            <span
+              v-else
+              class="caption text-muted fw-400"
+            >
+              {{ authorName }}
+            </span>
+          </div>
+        </div>
+      </template>
+    </UiCard>
+  </article>
+</template>

package/app/components/blog/BlogPostContent.vue

@@ -0,0 +1,111 @@
+<script setup lang="ts">
+import type { App } from 'vue'
+import { createApp } from 'vue'
+import WidgetError from '#blog/app/widgets/WidgetError.vue'
+import BlogCodeBlock from './BlogCodeBlock.vue'
+
+/* eslint-disable vue/one-component-per-file -- createApp() hydration, not extra SFCs */
+
+/** Props */
+const props = defineProps<{ html: string }>()
+
+const bodyHtml = computed(() => decorateBlogLinks(props.html))
+const root = useTemplateRef<HTMLElement>('root')
+const nuxtApp = useNuxtApp()
+const widgets = useBlogWidgets()
+
+let mountedApps: App[] = []
+
+function teardown() {
+  for (const app of mountedApps) {
+    try {
+      app.unmount()
+    } catch {
+      // ignore unmount errors
+    }
+  }
+  mountedApps = []
+}
+
+/** Mounts an app on `host` with the Nuxt context */
+function mountInContext(app: App, host: HTMLElement) {
+  Object.assign(app._context, nuxtApp.vueApp._context)
+  app.mount(host)
+  mountedApps.push(app)
+}
+
+/** Language hint from `language-xxx` / `lang-xxx` classes */
+function detectLang(pre: HTMLElement, code: HTMLElement | null): string | null {
+  const classes = `${code?.className || ''} ${pre.className || ''}`
+  return classes.match(/(?:language|lang)-([\w#+-]+)/i)?.[1] ?? null
+}
+
+/** Upgrades `<pre><code>` blocks into Shiki code blocks */
+function hydrateCodeBlocks() {
+  if (!root.value)
+    return
+
+  const blocks = root.value.querySelectorAll<HTMLElement>('pre')
+  blocks.forEach((pre) => {
+    // Widgets render their own code
+    if (pre.closest('[data-blog-widget]'))
+      return
+
+    const code = pre.querySelector<HTMLElement>(':scope > code')
+    const source = (code ?? pre).textContent ?? ''
+    if (!source.trim())
+      return
+
+    const host = document.createElement('div')
+    host.className = 'blog-code-host'
+    pre.replaceWith(host)
+
+    mountInContext(createApp(BlogCodeBlock, { code: source, lang: detectLang(pre, code) }), host)
+  })
+}
+
+function hydrateWidgets() {
+  if (!root.value)
+    return
+
+  const placeholders = root.value.querySelectorAll<HTMLElement>('[data-blog-widget]')
+  placeholders.forEach((el) => {
+    const key = el.dataset.blogWidget || ''
+    const widget = Object.hasOwn(widgets, key) ? widgets[key] : undefined
+
+    let app: App
+    if (!widget) {
+      app = createApp(WidgetError, { reason: `Unknown widget “${key}”` })
+    } else {
+      const { props: widgetProps } = coerceProps(safeParseProps(el.dataset.props), widget.descriptor)
+      if (widget.descriptor.minHeight)
+        el.style.minHeight = `${widget.descriptor.minHeight}px`
+      app = createApp(widget.component, widgetProps)
+    }
+
+    el.innerHTML = ''
+    mountInContext(app, el)
+  })
+}
+
+function hydrate() {
+  teardown()
+  hydrateCodeBlocks()
+  hydrateWidgets()
+}
+
+onMounted(hydrate)
+onBeforeUnmount(teardown)
+watch(() => props.html, async () => {
+  await nextTick()
+  hydrate()
+})
+</script>
+
+<template>
+  <div
+    ref="root"
+    class="blog-prose"
+    v-html="bodyHtml"
+  />
+</template>

package/app/components/blog/BlogPostList.vue

@@ -0,0 +1,143 @@
+<script setup lang="ts">
+import type { IPost } from '#blog/shared/models/post'
+import { NuxtLink } from '#components'
+
+/** Interfaces */
+interface IProps {
+  posts: IPost[] | null | undefined
+  pending?: boolean
+  paginated?: boolean
+  hasMore?: boolean
+  nextHref?: string
+  emptyTitle?: string
+  emptySubtitle?: string
+  headingTag?: 'h2' | 'h3'
+}
+
+/** Props */
+const {
+  posts,
+  pending = false,
+  paginated = false,
+  hasMore = false,
+  nextHref = undefined,
+  emptyTitle = 'No articles found',
+  emptySubtitle = 'Check back soon for new articles.',
+  headingTag = 'h2'
+} = defineProps<IProps>()
+
+/** Emit */
+const emit = defineEmits<{ loadMore: [] }>()
+
+/** Composables */
+const { blogPath } = useBlogPath()
+
+/** Constants */
+const SKELETON_COUNT = 6
+
+/** Computed */
+const hasPosts = computed(() => Boolean(posts?.length))
+const isLoading = computed(() => pending && !hasPosts.value)
+const skeletonPost: IPost = { title: '', isPublished: true }
+
+/** Methods */
+function freezeCardGeometry(el: Element): void {
+  const card = el as HTMLElement
+  card.style.left = `${card.offsetLeft}px`
+  card.style.top = `${card.offsetTop}px`
+  card.style.width = `${card.offsetWidth}px`
+  card.style.height = `${card.offsetHeight}px`
+}
+function handleLoadMore(event: MouseEvent): void {
+  if (nextHref && (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey))
+    return
+  event.preventDefault()
+  if (pending || !hasMore)
+    return
+  emit('loadMore')
+}
+</script>
+
+<template>
+  <div>
+    <!-- Skeletons -->
+    <div
+      v-if="isLoading"
+      class="blog-post-skeleton-grid d-grid grid-repeat-cols-1 grid-repeat-cols-md-2 grid-repeat-cols-xl-3 gap-5"
+      role="status"
+      aria-label="Loading articles"
+    >
+      <BlogPostCard
+        v-for="indexSkeleton in SKELETON_COUNT"
+        :key="`skeleton-${indexSkeleton}`"
+        :post="skeletonPost"
+        is-skeleton
+      />
+    </div>
+
+    <!-- Grid -->
+    <TransitionGroup
+      v-else-if="hasPosts"
+      tag="div"
+      name="post-card"
+      class="blog-post-grid d-grid grid-repeat-cols-1 grid-repeat-cols-md-2 grid-repeat-cols-xl-3 gap-inline-8 gap-block-10"
+      @before-leave="freezeCardGeometry"
+    >
+      <BlogPostCard
+        v-for="post in posts"
+        :key="post.id"
+        :post="post"
+        :heading-tag="headingTag"
+      />
+    </TransitionGroup>
+
+    <!-- Empty state -->
+    <UiEmpty
+      v-else
+      :title="emptyTitle"
+      :subtitle="emptySubtitle"
+      custom-class="my-5 my-md-8"
+    >
+      <template #action>
+        <slot name="empty-action">
+          <UiButtonGroup class="justify-content-center">
+            <UiButton
+              :as="NuxtLink"
+              :to="blogPath()"
+              variant="tonal"
+              color="primary"
+              text="Back to home"
+              class="btn-cta"
+            >
+              <template #icon>
+                <UiIconMaterial icon-code="&#xe5c4;" />
+              </template>
+            </UiButton>
+          </UiButtonGroup>
+        </slot>
+      </template>
+    </UiEmpty>
+
+    <!-- Load more -->
+    <UiButtonGroup
+      v-if="paginated && hasPosts"
+      class="justify-content-center mt-5"
+    >
+      <UiButton
+        variant="tonal"
+        color="neutral"
+        class="btn-cta hover-rotate"
+        :href="hasMore ? nextHref : undefined"
+        :rel="hasMore && nextHref ? 'next' : undefined"
+        :text="hasMore ? 'Load more articles' : 'No more articles'"
+        :disabled="!hasMore"
+        :loading="pending"
+        @click="handleLoadMore"
+      >
+        <template #icon>
+          <UiIconMaterial :icon-code="hasMore ? '&#xe863;' : '&#xea76;'" />
+        </template>
+      </UiButton>
+    </UiButtonGroup>
+  </div>
+</template>

package/app/components/layout/HubHeader.vue

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+import type { IBreadcrumbItem } from '@colorffy/ui'
+import { NuxtLink } from '#components'
+
+/** Interfaces */
+interface IProps {
+  title?: string
+  titleId?: string
+  description?: string
+  breadcrumbs?: IBreadcrumbItem[]
+}
+
+/** Props */
+const {
+  title = '',
+  titleId = undefined,
+  description = '',
+  breadcrumbs = []
+} = defineProps<IProps>()
+
+/** Composables */
+const siteUrl = useSiteUrl()
+</script>
+
+<template>
+  <div>
+    <UiBreadcrumb
+      v-if="breadcrumbs.length"
+      :as="NuxtLink"
+      :base-url="siteUrl"
+      separator-icon="&#xe5cc;"
+      :items="breadcrumbs"
+      class="mb-4"
+    />
+
+    <header class="facet-hub-header">
+      <div>
+        <h1
+          :id="titleId"
+          class="facet-hub-title display-1"
+        >
+          <slot name="title">
+            {{ title }}
+          </slot>
+        </h1>
+        <slot />
+      </div>
+      <div
+        v-if="description || $slots.meta"
+        class="facet-hub-meta"
+      >
+        <p
+          v-if="description"
+          class="subtitle-1 lh-md text-muted mb-0"
+        >
+          {{ description }}
+        </p>
+        <slot name="meta" />
+      </div>
+    </header>
+  </div>
+</template>

package/app/composables/useBlogBrand.ts

@@ -0,0 +1,13 @@
+/**
+ * Blog identity: the static `app.config.ts` brand plus the admin-editable name and
+ * description from `settings/general`, which win when set.
+ */
+export function useBlogBrand() {
+  const brand = useAppConfig().blog
+  const { settings } = useBlogSettings()
+
+  const blogName = computed(() => settings.value?.blogName?.trim() || brand.shortName)
+  const blogDescription = computed(() => settings.value?.blogDescription?.trim() || brand.description)
+
+  return { brand, blogName, blogDescription }
+}

package/app/composables/useBlogPath.ts

@@ -0,0 +1,13 @@
+/**
+ * Builds blog links under `blog.basePath`: `blogPath('/tags/css')` for router links and
+ * `blogUrl('/tags/css')` for absolute URLs (canonicals, share links, JSON-LD).
+ */
+export function useBlogPath() {
+  const basePath = useRuntimeConfig().public.blog.basePath
+  const siteUrl = useSiteUrl()
+
+  const blogPath = (path = '/') => joinBlogPath(basePath, path)
+  const blogUrl = (path = '/') => toBlogUrl(siteUrl, basePath, path)
+
+  return { basePath, blogPath, blogUrl }
+}

package/app/composables/useBlogPost.ts

@@ -0,0 +1,12 @@
+import type { IPostPageResponse } from '#blog/shared/types/api'
+
+/**
+ * A published post with its sanitized body, TOC, author, related and sibling posts from the
+ * cached `/api/blog/posts/[slug]`. Pages remount per slug, so the key is fixed for the instance.
+ */
+export function useBlogPost(slug: string) {
+  return useCachedResource<IPostPageResponse>(
+    `blog-post-${slug}`,
+    () => $fetch<IPostPageResponse>(`/api/blog/posts/${encodeURIComponent(slug)}`)
+  )
+}

package/app/composables/useBlogSettings.ts

@@ -0,0 +1,15 @@
+import type { ISettings } from '#blog/shared/models/settings'
+import type { ISettingsResponse } from '#blog/shared/types/api'
+
+/**
+ * Site-wide `settings/general` (branding + SEO defaults) from the cached `/api/blog/settings`.
+ * One `blog-settings` state shared by the layout, navbar, footer and pages.
+ */
+export function useBlogSettings() {
+  const { data, pending, error } = useCachedResource<ISettings | null>(
+    'blog-settings',
+    async () => (await $fetch<ISettingsResponse>('/api/blog/settings')).settings
+  )
+
+  return { settings: data, pending, error }
+}

package/app/composables/useBlogWidgets.ts

@@ -0,0 +1,18 @@
+import type { Component } from 'vue'
+import type { WidgetDescriptor } from '#blog/shared/widgets/types'
+
+/** An embeddable post widget: its schema (for props coercion) and the component that renders it. */
+export interface IBlogWidget {
+  descriptor: WidgetDescriptor
+  component: Component
+}
+
+export type BlogWidgetMap = Record<string, IBlogWidget>
+
+/**
+ * Widgets the site registers by providing `$blogWidgets` from a plugin (see `plugins/blog-widgets.ts`).
+ * Without one, every `[data-blog-widget]` placeholder renders the "unavailable" fallback.
+ */
+export function useBlogWidgets(): BlogWidgetMap {
+  return (useNuxtApp().$blogWidgets as BlogWidgetMap | undefined) ?? {}
+}

package/app/composables/useCachedResource.ts

@@ -0,0 +1,72 @@
+/** Interfaces */
+interface IResourceError {
+  statusCode?: number
+  message?: string
+}
+
+/**
+ * One read from the cached `server/api` endpoints, held in `useState` (colorffy's
+ * `useChangelogs` pattern) instead of VueFire or `useFetch`:
+ * - VueFire kept SSR state in one object shared by every anonymous request, so keys from other
+ *   pages (`author-for-card-*`, `posts-home`, …) leaked into every payload.
+ * - Post pages are swr-cached, where Nuxt drops the `useFetch` payload (`payload.data`) and only
+ *   `useState` survives, so SSR-rendered data hydrates without a blank flash or mismatch.
+ *
+ * `ready` resolves once the state is filled: pages await it before throwing 404s and before
+ * `defineOgImage`/SEO that read the data synchronously. `state` is `null` after a failed read,
+ * which a later client navigation retries (never during hydration, to reuse the SSR result).
+ */
+// Client-only: several components can share one key, so a navigation starts one request per key.
+const inflightLoads = new Map<string, Promise<void>>()
+
+export function useCachedResource<T>(key: string, fetcher: () => Promise<T>) {
+  const nuxtApp = useNuxtApp()
+  const state = useState<T | null | undefined>(key, () => undefined)
+  const error = ref<IResourceError | null>(null)
+
+  async function load(): Promise<void> {
+    try {
+      state.value = await fetcher()
+    } catch (loadError) {
+      state.value = null
+      error.value = loadError as IResourceError
+    }
+  }
+
+  let ready: Promise<unknown> = Promise.resolve()
+  if (import.meta.server) {
+    // useAsyncData blocks SSR until the fetch resolves, so the filled state is serialized.
+    ready = useAsyncData(key, async () => {
+      if (state.value === undefined)
+        await load()
+      return true
+    })
+  } else if (state.value === undefined || (state.value === null && !nuxtApp.isHydrating)) {
+    let pending = inflightLoads.get(key)
+    if (!pending) {
+      pending = load().finally(() => inflightLoads.delete(key))
+      inflightLoads.set(key, pending)
+    }
+    ready = pending
+  }
+
+  return {
+    state,
+    data: computed<T | null>(() => state.value ?? null),
+    pending: computed<boolean>(() => state.value === undefined),
+    error,
+    ready
+  }
+}
+
+/**
+ * Maps a failed read to the page error: missing data is a 404, an upstream failure a 503.
+ * Fatal, so a client-side navigation also swaps to the error page instead of keeping the old one.
+ */
+export function resourceError(error: IResourceError | null, statusMessage: string) {
+  const statusCode = error?.statusCode
+  if (!error || statusCode === 404 || statusCode === 400)
+    return createError({ statusCode: 404, statusMessage, fatal: true })
+
+  return createError({ statusCode: statusCode && statusCode >= 500 ? statusCode : 503, statusMessage: 'Temporarily unavailable', fatal: true })
+}