@fullstackdatasolutions/articles 0.10.0 → 0.12.0

package/src/__tests__/renderMdx.test.tsx

@@ -334,4 +334,82 @@ describe('renderMdxSource', () => {
       expect(capturedComponents).toBeUndefined()
     })
   })
+
+  describe('custom MDX components', () => {
+    it('renders a registered custom component with its MDX props', async () => {
+      type LeadMagnetCTAProps = Readonly<{
+        system: string
+        segment: string
+      }>
+      const LeadMagnetCTA = ({ system, segment }: LeadMagnetCTAProps) =>
+        React.createElement('div', { 'data-testid': 'lead-magnet' }, `${system}:${segment}`)
+
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const CustomCTA = components?.LeadMagnetCTA as React.ComponentType<LeadMagnetCTAProps>
+          return React.createElement(CustomCTA, { system: 'DND', segment: 'new-players' })
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const source = 'Article intro.\n\n<LeadMagnetCTA system="DND" segment="new-players" />'
+      const el = await renderMdxSource(source, undefined, {
+        siteUrl: 'https://example.com',
+        siteName: 'Example',
+        mdxComponents: { LeadMagnetCTA },
+      })
+      const { getByTestId } = render(el as React.ReactElement)
+
+      expect(getByTestId('lead-magnet')).toHaveTextContent('DND:new-players')
+      expect(mockEvaluate).toHaveBeenCalledWith(source, expect.any(Object))
+    })
+
+    it('merges registered custom components with the relative image override', async () => {
+      type LeadMagnetCTAProps = Readonly<{ label: string }>
+      const LeadMagnetCTA = ({ label }: LeadMagnetCTAProps) =>
+        React.createElement('div', { 'data-testid': 'lead-magnet' }, label)
+
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const CustomCTA = components?.LeadMagnetCTA as React.ComponentType<LeadMagnetCTAProps>
+          const Img = components?.img as React.ComponentType<
+            React.ImgHTMLAttributes<HTMLImageElement>
+          >
+          return React.createElement(
+            'div',
+            null,
+            React.createElement(CustomCTA, { label: 'Download now' }),
+            React.createElement(Img, { src: 'photo.png', alt: 'Article image' })
+          )
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource(
+        '<LeadMagnetCTA label="Download now" />\n\n![Article image](photo.png)',
+        '/articles/my-article',
+        {
+          siteUrl: 'https://example.com',
+          siteName: 'Example',
+          mdxComponents: { LeadMagnetCTA },
+        }
+      )
+      const { container, getByTestId } = render(el as React.ReactElement)
+
+      expect(getByTestId('lead-magnet')).toHaveTextContent('Download now')
+      expect(container.querySelector('img')?.getAttribute('src')).toBe(
+        '/articles/my-article/photo.png'
+      )
+    })
+  })
 })

package/src/__tests__/useArticles.test.ts

@@ -190,6 +190,34 @@ describe('useArticles', () => {
     })
   })
 
+  describe('with server-seeded initial data', () => {
+    it('starts populated and not loading, and skips the mount fetch', () => {
+      ;(globalThis.fetch as jest.Mock).mockReturnValue(new Promise(() => {}))
+      const mockCategories = [
+        { name: 'Campaigns', slug: 'campaigns', count: 2, featuredImage: '/x.jpg' },
+      ]
+
+      const { result } = renderHook(() => useArticles(mockArticles, mockCategories))
+
+      expect(result.current.loading).toBe(false)
+      expect(result.current.articles).toHaveLength(3)
+      expect(result.current.categories).toEqual(mockCategories)
+      expect(globalThis.fetch).not.toHaveBeenCalled()
+    })
+
+    it('still fetches when a search is performed after seeding', async () => {
+      ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: async () => ({ articles: [mockArticles[0]] }),
+      })
+
+      const { result } = renderHook(() => useArticles(mockArticles, []))
+      act(() => result.current.handleSearch(''))
+
+      await waitFor(() => expect(globalThis.fetch).toHaveBeenCalledWith('/api/articles'))
+    })
+  })
+
   it('refetches all articles when handleSearch is called with empty string', async () => {
     ;(globalThis.fetch as jest.Mock).mockResolvedValue({
       ok: true,

package/src/articlesConfig.ts

@@ -1,3 +1,4 @@
+import type { ComponentType } from 'react'
 import type { AuthorProfile } from './articleTypes'
 
 /** Keys for each renderable section of the articles listing page. */
@@ -72,6 +73,9 @@ export interface HeroConfig {
 /** Controls how article body links set target/rel attributes. */
 export type LinkTargetStrategy = 'external-new-tab' | 'all-new-tab' | 'same-tab'
 
+/** React components that article MDX bodies can reference by JSX tag name. */
+export type MdxComponents = Record<string, ComponentType<never>>
+
 export type ArticleBreadcrumbToken =
   | 'home'
   | 'articles'
@@ -160,6 +164,8 @@ export interface ArticlesConfig {
   breadcrumbs?: false | BreadcrumbsConfig
   /** Article body link target behavior. Default: `'external-new-tab'`. */
   linkTargetStrategy?: LinkTargetStrategy
+  /** Extra components exposed to article MDX bodies by JSX tag name. */
+  mdxComponents?: MdxComponents
 }
 
 export const DEFAULT_PAGE_SIZE = 6

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
   CategoryDescription,
   CommentsConfig,
   LinkTargetStrategy,
+  MdxComponents,
   BreadcrumbsConfig,
   BreadcrumbLabels,
   ArticleBreadcrumbToken,

package/src/renderMdx.tsx

@@ -45,6 +45,10 @@ export async function renderMdxSource(source: string, basePath?: string, config?
   })
 
   const Content = mdxModule.default as MdxContent
-  const components = basePath ? { img: makeImgComponent(basePath) } : undefined
+  const internalComponents = basePath ? { img: makeImgComponent(basePath) } : undefined
+  const components =
+    internalComponents || config?.mdxComponents
+      ? { ...internalComponents, ...config?.mdxComponents }
+      : undefined
   return <Content components={components as Record<string, ComponentType<unknown>>} />
 }

package/src/useArticles.ts

@@ -12,12 +12,15 @@ export interface UseArticlesReturn {
   handleSearch: (query: string) => void
 }
 
-export function useArticles(): UseArticlesReturn {
+export function useArticles(
+  initialArticles?: Article[],
+  initialCategories?: CategoryInfo[]
+): UseArticlesReturn {
   const [searchQuery, setSearchQuery] = useState('')
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const [articles, setArticles] = useState<Article[]>([])
-  const [categories, setCategories] = useState<CategoryInfo[]>([])
-  const [loading, setLoading] = useState(true)
+  const [articles, setArticles] = useState<Article[]>(initialArticles ?? [])
+  const [categories, setCategories] = useState<CategoryInfo[]>(initialCategories ?? [])
+  const [loading, setLoading] = useState(initialArticles === undefined)
   const [error, setError] = useState<string | null>(null)
 
   const fetchArticles = useCallback(async (query: string) => {
@@ -66,7 +69,9 @@ export function useArticles(): UseArticlesReturn {
   }, [])
 
   useEffect(() => {
-    fetchArticles('')
+    if (initialArticles === undefined) fetchArticles('')
+    // Seeded data came from the server render; skip the redundant client fetch on mount.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [fetchArticles])
 
   const handleSearch = useCallback(