Merge branch 'main' into perf/markdown-img-default-width

LadyBluenotes · web-flow · commit a11730e13b9b · 2026-07-02T10:00:50.000-07:00
diff --git a/src/components/BlogCard.tsx b/src/components/BlogCard.tsx
@@ -5,7 +5,7 @@ import {
   formatAuthors,
   formatPublishedDate,
   getBlogLibraries,
-} from '~/utils/blog'
+} from '~/utils/blog-format'
 import { getOptimizedImageUrl } from '~/utils/optimizedImage'
 
 export type BlogCardPost = {
diff --git a/src/components/LibraryLayout.tsx b/src/components/LibraryLayout.tsx
@@ -4,6 +4,7 @@ import { GithubIcon } from '~/components/icons/GithubIcon'
 import { DiscordIcon } from '~/components/icons/DiscordIcon'
 import { Link, useMatches, useParams } from '@tanstack/react-router'
 import { useLocalStorage } from '~/utils/useLocalStorage'
+import { useMediaQuery } from '~/utils/useMediaQuery'
 import { useClickOutside } from '~/hooks/useClickOutside'
 import { last } from '~/utils/utils'
 import type { ConfigSchema, MenuItem } from '~/utils/config'
@@ -424,26 +425,6 @@ function clampProgress(value: number) {
   return Math.min(Math.max(value, 0), 1)
 }
 
-function useMediaQuery(query: string) {
-  const [matches, setMatches] = React.useState(false)
-
-  React.useEffect(() => {
-    const mediaQueryList = window.matchMedia(query)
-    const updateMatches = () => {
-      setMatches(mediaQueryList.matches)
-    }
-
-    updateMatches()
-    mediaQueryList.addEventListener('change', updateMatches)
-
-    return () => {
-      mediaQueryList.removeEventListener('change', updateMatches)
-    }
-  }, [query])
-
-  return matches
-}
-
 function areDocsPartnerSlotsEqual(
   left: DocsPartnerScrollSlot | undefined,
   right: DocsPartnerScrollSlot | undefined,
@@ -903,6 +884,7 @@ export function LibraryLayout({
     surface: 'docs_rail',
   })
   const shouldShowDocsPartnerSlot = useMediaQuery('(max-width: 767.98px)')
+  const isDesktopViewport = useMediaQuery('(min-width: 768px)')
 
   const groupInitialOpenState = React.useMemo(() => {
     return visibleMenuConfig.reduce<Record<string, boolean>>(
@@ -1431,7 +1413,7 @@ export function LibraryLayout({
                   partners={activePartners}
                 />
                 <div className="hidden md:block border border-gray-500/20 rounded-l-lg overflow-hidden w-full">
-                  <RecentPostsWidget />
+                  <RecentPostsWidget enabled={isDesktopViewport} />
                 </div>
               </RightRail>
             )}
diff --git a/src/components/RecentPostsWidget.tsx b/src/components/RecentPostsWidget.tsx
@@ -1,10 +1,12 @@
 import { Link } from '@tanstack/react-router'
 import { useQuery } from '@tanstack/react-query'
 import { fetchRecentPosts, type RecentPost } from '~/utils/blog.functions'
-import { formatPublishedDate } from '~/utils/blog'
+import { formatPublishedDate } from '~/utils/blog-format'
 
 type RecentPostsWidgetProps = {
   posts?: ReadonlyArray<RecentPost>
+  /** Set to false to skip the client fetch when the widget is rendered but not visible (e.g. hidden below a CSS breakpoint). Ignored when `posts` is provided. */
+  enabled?: boolean
 }
 
 function RecentPostsList({ posts }: { posts: ReadonlyArray<RecentPost> }) {
@@ -63,11 +65,14 @@ function RecentPostsSkeleton() {
   )
 }
 
-export function RecentPostsWidget({ posts }: RecentPostsWidgetProps) {
+export function RecentPostsWidget({
+  posts,
+  enabled = true,
+}: RecentPostsWidgetProps) {
   const recentPostsQuery = useQuery({
     queryKey: ['recentPosts'],
     queryFn: () => fetchRecentPosts(),
-    enabled: posts === undefined,
+    enabled: posts === undefined && enabled,
     staleTime: 1000 * 60 * 5,
   })
 
diff --git a/src/components/home/HomeSocialProofSection.tsx b/src/components/home/HomeSocialProofSection.tsx
@@ -5,7 +5,7 @@ import { ArrowRight } from 'lucide-react'
 import { Card } from '~/components/Card'
 import { PartnersGrid } from '~/components/PartnersGrid'
 import { Button } from '~/ui'
-import { formatAuthors, formatPublishedDate } from '~/utils/blog'
+import { formatAuthors, formatPublishedDate } from '~/utils/blog-format'
 import type { RecentPost } from '~/utils/blog.functions'
 
 type HomeSocialProofSectionProps = {
diff --git a/src/components/stack/CategoryArticle.tsx b/src/components/stack/CategoryArticle.tsx
@@ -22,8 +22,9 @@ import {
 } from 'lucide-react'
 
 import { LibraryWordmark } from '~/components/LibraryWordmark'
-import type { LibrarySlim } from '~/libraries'
-import { formatPublishedDate, getPostsForLibrary } from '~/utils/blog'
+import type { LibraryId, LibrarySlim } from '~/libraries'
+import { formatPublishedDate } from '~/utils/blog-format'
+import type { RelatedPost as RelatedPostData } from '~/utils/blog.functions'
 import {
   categoryMeta,
   getCategoryLibraries,
@@ -44,10 +45,16 @@ const libraryLinkClassName =
 const staticPanelClassName =
   'rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-800 dark:bg-zinc-950'
 
-export function CategoryArticle({ slug }: { slug: CategorySlug }) {
+export function CategoryArticle({
+  slug,
+  relatedPosts: relatedPostsData,
+}: {
+  slug: CategorySlug
+  relatedPosts: Array<RelatedPostData>
+}) {
   const meta = categoryMeta[slug]
   const libraries = getCategoryLibraries(slug)
-  const relatedPosts = getRelatedPosts(libraries)
+  const relatedPosts = reconstructRelatedPosts(libraries, relatedPostsData)
 
   return (
     <div className="bg-white text-zinc-950 dark:bg-zinc-950 dark:text-zinc-50">
@@ -75,10 +82,23 @@ export function CategoryArticle({ slug }: { slug: CategorySlug }) {
   )
 }
 
-function getRelatedPosts(libraries: Array<LibrarySlim>) {
-  return libraries
-    .flatMap((lib) => getPostsForLibrary(lib.id).map((post) => ({ post, lib })))
-    .slice(0, 4)
+/**
+ * Reconstructs {post, lib} pairs from the server-provided, already-ordered
+ * and already-sliced related-posts data, using the in-memory `libraries`
+ * array (pure, client-safe) rather than sending non-serializable LibrarySlim
+ * objects (e.g. `handleRedirects`) over the server-fn RPC boundary.
+ */
+function reconstructRelatedPosts(
+  libraries: Array<LibrarySlim>,
+  data: Array<RelatedPostData>,
+): Array<RelatedPost> {
+  const libraryById = new Map<LibraryId, LibrarySlim>(
+    libraries.map((lib) => [lib.id, lib]),
+  )
+  return data.flatMap(({ libraryId, post }) => {
+    const lib = libraryById.get(libraryId)
+    return lib ? [{ post, lib }] : []
+  })
 }
 
 function Breadcrumb({ categoryName }: { categoryName: string }) {
diff --git a/src/routes/_library/$libraryId/$version.docs.blog.tsx b/src/routes/_library/$libraryId/$version.docs.blog.tsx
@@ -7,15 +7,18 @@ import { DocTitle } from '~/components/DocTitle'
 import { BlogCard } from '~/components/BlogCard'
 import { BlogAuthorFilter } from '~/components/BlogAuthorFilter'
 import { getLibrary, type LibraryId } from '~/libraries'
-import { getDistinctAuthors, getPostsForLibrary } from '~/utils/blog'
+import { fetchPostsForLibrary } from '~/utils/blog.functions'
+import { getDistinctAuthors } from '~/utils/blog-format'
 
 const searchSchema = v.object({
   author: v.fallback(v.optional(v.string()), undefined),
 })
 
 export const Route = createFileRoute('/_library/$libraryId/$version/docs/blog')(
   {
+    staleTime: Infinity,
     validateSearch: searchSchema,
+    loader: ({ params }) => fetchPostsForLibrary({ data: params.libraryId }),
     component: RouteComponent,
   },
 )
@@ -26,7 +29,7 @@ function RouteComponent() {
   const navigate = Route.useNavigate()
   const library = getLibrary(libraryId as LibraryId)
 
-  const posts = getPostsForLibrary(libraryId as LibraryId)
+  const posts = Route.useLoaderData()
   const authors = getDistinctAuthors(posts)
 
   const filteredPosts = author
diff --git a/src/routes/blog.$.tsx b/src/routes/blog.$.tsx
@@ -1,14 +1,15 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { seo } from '~/utils/seo'
 import { PostNotFound } from './blog'
-import { formatAuthors } from '~/utils/blog'
+import { formatAuthors } from '~/utils/blog-format'
 import * as React from 'react'
 import { MarkdownContent } from '~/components/markdown'
 import { Card } from '~/components/Card'
 import { LibrariesWidget } from '~/components/LibrariesWidget'
 import { partners } from '~/utils/partners'
 import { PartnersRail, RightRail } from '~/components/RightRail'
 import { RecentPostsWidget } from '~/components/RecentPostsWidget'
+import { useMediaQuery } from '~/utils/useMediaQuery'
 
 import { Toc } from '~/components/Toc'
 import { Breadcrumbs } from '~/components/Breadcrumbs'
@@ -76,6 +77,7 @@ function BlogPost() {
   const headings = markdown.headings
 
   const isTocVisible = headings.length > 1
+  const isDesktopViewport = useMediaQuery('(min-width: 768px)')
 
   const markdownContainerRef = React.useRef<HTMLDivElement>(null)
   const [activeHeadings, setActiveHeadings] = React.useState<Array<string>>([])
@@ -204,7 +206,7 @@ function BlogPost() {
               partners={activePartners}
             />
             <div className="hidden md:block border border-gray-500/20 rounded-l-lg overflow-hidden w-full">
-              <RecentPostsWidget />
+              <RecentPostsWidget enabled={isDesktopViewport} />
             </div>
             <Card>
               <LibrariesWidget />
diff --git a/src/routes/blog.index.tsx b/src/routes/blog.index.tsx
@@ -2,7 +2,8 @@ import { Link, createFileRoute } from '@tanstack/react-router'
 import * as v from 'valibot'
 import { BlogCard, type BlogCardPost } from '~/components/BlogCard'
 import { BlogAuthorFilter } from '~/components/BlogAuthorFilter'
-import { getDistinctAuthors, getPublishedPosts } from '~/utils/blog'
+import { getPublishedPosts } from '~/utils/blog'
+import { getDistinctAuthors } from '~/utils/blog-format'
 
 import { Footer } from '~/components/Footer'
 import { PostNotFound } from './blog'
diff --git a/src/routes/rss[.]xml.ts b/src/routes/rss[.]xml.ts
@@ -1,10 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { setResponseHeader } from '@tanstack/react-start/server'
-import {
-  getPublishedPosts,
-  formatAuthors,
-  publishedDateToUTCString,
-} from '~/utils/blog'
+import { getPublishedPosts } from '~/utils/blog'
+import { formatAuthors, publishedDateToUTCString } from '~/utils/blog-format'
 
 function escapeXml(unsafe: string): string {
   return unsafe
diff --git a/src/routes/stack.$category.tsx b/src/routes/stack.$category.tsx
@@ -4,20 +4,33 @@ import { CategoryArticle } from '~/components/stack/CategoryArticle'
 import {
   categoryMeta,
   categorySlugs,
+  getCategoryLibraries,
   type CategorySlug,
 } from '~/components/stack/stack-categories'
+import { fetchRelatedPostsForLibraries } from '~/utils/blog.functions'
 import { seo } from '~/utils/seo'
 
 function isCategorySlug(value: string): value is CategorySlug {
   return (categorySlugs as readonly string[]).includes(value)
 }
 
 export const Route = createFileRoute('/stack/$category')({
-  loader: ({ params }) => {
+  staleTime: Infinity,
+  loader: async ({ params }) => {
     if (!isCategorySlug(params.category)) {
       throw notFound()
     }
-    return { category: params.category, meta: categoryMeta[params.category] }
+
+    const libraries = getCategoryLibraries(params.category)
+    const relatedPosts = await fetchRelatedPostsForLibraries({
+      data: libraries.map((lib) => lib.id),
+    })
+
+    return {
+      category: params.category,
+      meta: categoryMeta[params.category],
+      relatedPosts,
+    }
   },
   head: ({ loaderData }) => ({
     meta: seo({
@@ -31,6 +44,6 @@ export const Route = createFileRoute('/stack/$category')({
 })
 
 function StackCategoryPage() {
-  const { category } = Route.useLoaderData()
-  return <CategoryArticle slug={category} />
+  const { category, relatedPosts } = Route.useLoaderData()
+  return <CategoryArticle slug={category} relatedPosts={relatedPosts} />
 }
diff --git a/src/utils/blog-format.ts b/src/utils/blog-format.ts
@@ -0,0 +1,70 @@
+import { findLibrary, type LibrarySlim } from '~/libraries'
+
+const listJoiner = new Intl.ListFormat('en-US', {
+  style: 'long',
+  type: 'conjunction',
+})
+
+export function formatAuthors(authors: Array<string>) {
+  if (!authors.length) {
+    return 'TanStack'
+  }
+
+  return listJoiner.format(authors)
+}
+
+function getUtcDateString(date = new Date()) {
+  return date.toISOString().slice(0, 10)
+}
+
+function parsePublishedDate(published: string) {
+  const [year, month, day] = published.split('-').map(Number)
+
+  return new Date(Date.UTC(year, month - 1, day, 12))
+}
+
+export function formatPublishedDate(published: string) {
+  return parsePublishedDate(published).toLocaleDateString('en-US', {
+    timeZone: 'UTC',
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  })
+}
+
+export function isPublishedDateReleased(published: string, now = new Date()) {
+  return published <= getUtcDateString(now)
+}
+
+export function publishedDateToUTCString(published: string) {
+  return parsePublishedDate(published).toUTCString()
+}
+
+function isLibrarySlim(
+  library: LibrarySlim | undefined,
+): library is LibrarySlim {
+  return library !== undefined
+}
+
+export function getBlogLibraries(library: string | undefined): LibrarySlim[] {
+  if (!library) {
+    return []
+  }
+
+  return library
+    .split(',')
+    .map((libraryId) => findLibrary(libraryId.trim()))
+    .filter(isLibrarySlim)
+}
+
+export function getDistinctAuthors(
+  posts: ReadonlyArray<{ authors: string[] }>,
+): string[] {
+  const authors = new Set<string>()
+  for (const post of posts) {
+    for (const author of post.authors) {
+      authors.add(author)
+    }
+  }
+  return [...authors].sort((a, b) => a.localeCompare(b))
+}
diff --git a/src/utils/blog.functions.ts b/src/utils/blog.functions.ts
diff --git a/src/utils/blog.ts b/src/utils/blog.ts
diff --git a/src/utils/useMediaQuery.ts b/src/utils/useMediaQuery.ts
