@fullstackdatasolutions/articles 0.7.0 → 0.7.2

package/package.json

@@ -1,15 +1,33 @@
 {
   "name": "@fullstackdatasolutions/articles",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
   "license": "MIT",
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://buymeacoffee.com/andrewblase"
+  },
   "keywords": [
     "nextjs",
+    "next",
+    "nextjs-blog",
+    "nextjs-articles",
+    "next-app-router",
+    "react",
     "articles",
     "blog",
+    "blog-engine",
     "cms",
-    "react",
-    "markdown"
+    "markdown",
+    "mdx",
+    "rss",
+    "sitemap",
+    "seo",
+    "metadata",
+    "json-ld",
+    "tailwindcss",
+    "content",
+    "static-site"
   ],
   "type": "module",
   "exports": {
@@ -27,6 +45,7 @@
   "files": [
     "dist",
     "src",
+    "scripts",
     "README.md"
   ],
   "peerDependencies": {
@@ -57,24 +76,24 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.0.0",
-    "@testing-library/react": "^16.0.0",
-    "@testing-library/user-event": "^14.0.0",
-    "@types/hast": "^3.0.0",
-    "@types/jest": "^29.0.0",
-    "@types/node": "^20.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/hast": "^3.0.4",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.x",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
     "eslint": "^9.0.0",
-    "eslint-plugin-react": "^7.0.0",
+    "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.0.0",
     "globals": "^15.0.0",
-    "jest": "^29.0.0",
-    "jest-environment-jsdom": "^29.0.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
     "prettier": "^3.0.0",
-    "ts-jest": "^29.0.0",
+    "ts-jest": "^29.4.10",
     "tsup": "^8.3.5",
     "typescript": "^5.0.0"
   },
@@ -85,6 +104,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "postinstall": "node ./scripts/postinstall.cjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",

package/scripts/postinstall.cjs

@@ -0,0 +1,9 @@
+const message = [
+  '',
+  'Thanks for installing @fullstackdatasolutions/articles.',
+  'If this package saves you time, consider buying the developer a coffee:',
+  'https://buymeacoffee.com/andrewblase',
+  '',
+].join('\n')
+
+console.log(message)

package/src/ArticleSocialShare.tsx

@@ -75,15 +75,10 @@ export function ArticleSocialShare({ title, url, excerpt, shareMessage }: Articl
           <MessageCircle className="h-4 w-4" />
           Telegram
         </button>
-        <button
-          className={btnClass}
-          onClick={() => {
-            globalThis.location.href = shareLinks.email
-          }}
-        >
+        <a className={btnClass} href={shareLinks.email}>
           <Mail className="h-4 w-4" />
           Email
-        </button>
+        </a>
         <button className={btnClass} onClick={copyToClipboard}>
           {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
           {copied ? 'Copied!' : 'Copy Link'}

package/src/__tests__/ArticleSocialShare.test.tsx

@@ -32,7 +32,7 @@ describe('ArticleSocialShare', () => {
       expect(screen.getByText('Share this article')).toBeInTheDocument()
     })
 
-    it('renders all 8 share buttons', () => {
+    it('renders all share controls', () => {
       render(<ArticleSocialShare {...defaultProps} />)
       expect(screen.getByRole('button', { name: /linkedin/i })).toBeInTheDocument()
       expect(screen.getByRole('button', { name: /facebook/i })).toBeInTheDocument()
@@ -40,7 +40,7 @@ describe('ArticleSocialShare', () => {
       expect(screen.getByRole('button', { name: /reddit/i })).toBeInTheDocument()
       expect(screen.getByRole('button', { name: /whatsapp/i })).toBeInTheDocument()
       expect(screen.getByRole('button', { name: /telegram/i })).toBeInTheDocument()
-      expect(screen.getByRole('button', { name: /email/i })).toBeInTheDocument()
+      expect(screen.getByRole('link', { name: /email/i })).toBeInTheDocument()
       expect(screen.getByRole('button', { name: /copy link/i })).toBeInTheDocument()
     })
   })
@@ -149,19 +149,14 @@ describe('ArticleSocialShare', () => {
   })
 
   describe('Email button', () => {
-    it('clicking Email sets location.href to a mailto link', () => {
-      const originalLocation = globalThis.location
-      delete (globalThis as Record<string, unknown>).location
-      ;(globalThis as Record<string, unknown>).location = { href: '' }
-
+    it('renders Email as a mailto link', () => {
       render(<ArticleSocialShare {...defaultProps} />)
-      fireEvent.click(screen.getByRole('button', { name: /email/i }))
 
-      expect((globalThis.location as { href: string }).href).toContain('mailto:')
-      expect((globalThis.location as { href: string }).href).toContain(
-        encodeURIComponent(defaultProps.title)
+      const emailLink = screen.getByRole('link', { name: /email/i })
+      expect(emailLink).toHaveAttribute(
+        'href',
+        expect.stringContaining(`mailto:?subject=${encodeURIComponent(defaultProps.title)}`)
       )
-      ;(globalThis as Record<string, unknown>).location = originalLocation
     })
   })
 

package/src/__tests__/server-articles.test.ts

@@ -1,6 +1,16 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { getArticleMetadata, getAvailableArticleSlugs } from '../server-articles'
+import {
+  categoryToSlug,
+  getAdjacentArticles,
+  getAllArticles,
+  getAllCategories,
+  getArticleMetadata,
+  getArticlesByCategory,
+  getAvailableArticleSlugs,
+  sanitizeImagePath,
+  searchArticles,
+} from '../server-articles'
 
 jest.mock('react', () => ({ cache: (fn: Function) => fn }))
 jest.mock('node:fs')
@@ -28,6 +38,58 @@ function setupArticleMock(frontmatter: string, body = 'Article body content.'):
   ;(mockedFs.readdirSync as jest.Mock).mockReturnValue([])
 }
 
+interface MockArticle {
+  readonly slug: string
+  readonly frontmatter: string
+  readonly body?: string
+  readonly contentType?: 'md' | 'mdx'
+  readonly files?: readonly string[]
+}
+
+function setupArticleTreeMock(articles: readonly MockArticle[]): void {
+  const articleMap = new Map(articles.map((article) => [article.slug, article]))
+  const directoryChildren = new Map<string, Set<string>>()
+  const articleFilePaths = new Map<string, MockArticle>()
+
+  directoryChildren.set(articlesDirectory, new Set())
+
+  for (const article of articles) {
+    const segments = article.slug.split('/')
+    let currentDir = articlesDirectory
+    segments.forEach((segment, index) => {
+      if (!directoryChildren.has(currentDir)) directoryChildren.set(currentDir, new Set())
+      directoryChildren.get(currentDir)!.add(segment)
+      currentDir = path.join(currentDir, segment)
+      if (index < segments.length - 1 && !directoryChildren.has(currentDir)) {
+        directoryChildren.set(currentDir, new Set())
+      }
+    })
+
+    const extension = article.contentType === 'mdx' ? 'article.mdx' : 'article.md'
+    articleFilePaths.set(path.join(articlesDirectory, article.slug, extension), article)
+  }
+
+  mockedFs.existsSync.mockImplementation((target) => {
+    const targetPath = target.toString()
+    return targetPath === articlesDirectory || articleFilePaths.has(targetPath)
+  })
+
+  mockedFs.readFileSync.mockImplementation((target) => {
+    const article = articleFilePaths.get(target.toString())
+    if (!article) throw new Error(`Unexpected file read: ${target.toString()}`)
+    return `---\ntitle: ${article.slug}\nexcerpt: Excerpt for ${article.slug}\nauthor: Test Author\n${article.frontmatter}---\n\n${article.body ?? 'Article body content.'}`
+  })
+  ;(mockedFs.readdirSync as jest.Mock).mockImplementation((target: fs.PathLike) => {
+    const targetPath = target.toString()
+    const children = directoryChildren.get(targetPath)
+    if (!children) {
+      const slug = path.relative(articlesDirectory, targetPath)
+      return articleMap.get(slug)?.files ?? []
+    }
+    return Array.from(children).map(mockDirectory)
+  })
+}
+
 describe('getArticleMetadata - frontmatter parsing', () => {
   beforeEach(() => {
     jest.clearAllMocks()
@@ -130,4 +192,251 @@ describe('getAvailableArticleSlugs', () => {
 
     expect(getAvailableArticleSlugs()).toEqual(['game-system/article-name'])
   })
+
+  it('continues walking inside directories that are also articles', () => {
+    mockedFs.existsSync.mockImplementation((target) => {
+      const targetPath = target.toString()
+      return (
+        targetPath === articlesDirectory ||
+        targetPath === path.join(articlesDirectory, 'tov', 'article.md') ||
+        targetPath ===
+          path.join(articlesDirectory, 'tov', 'subdirectory', 'article-name', 'article.md')
+      )
+    })
+    ;(mockedFs.readdirSync as jest.Mock).mockImplementation((target: fs.PathLike) => {
+      const targetPath = target.toString()
+      if (targetPath === articlesDirectory) return [mockDirectory('tov')]
+      if (targetPath === path.join(articlesDirectory, 'tov')) {
+        return [mockDirectory('subdirectory')]
+      }
+      if (targetPath === path.join(articlesDirectory, 'tov', 'subdirectory')) {
+        return [mockDirectory('article-name')]
+      }
+      return []
+    })
+
+    expect(getAvailableArticleSlugs()).toEqual(['tov', 'tov/subdirectory/article-name'])
+  })
+
+  it('returns an empty list when the articles directory is missing', () => {
+    mockedFs.existsSync.mockReturnValue(false)
+
+    expect(getAvailableArticleSlugs()).toEqual([])
+  })
+})
+
+describe('article collection utilities', () => {
+  const originalEnv = process.env.NODE_ENV
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    Object.defineProperty(process.env, 'NODE_ENV', {
+      value: 'test',
+      configurable: true,
+    })
+  })
+
+  afterAll(() => {
+    Object.defineProperty(process.env, 'NODE_ENV', {
+      value: originalEnv,
+      configurable: true,
+    })
+  })
+
+  it('loads articles, resolves metadata defaults, filters future articles, and sorts by date', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'first',
+        frontmatter: 'date: 2025-01-02\ntags:\n  - Civic Tech\nfeaturedImage: hero.png\n',
+        files: ['hero.png'],
+      },
+      {
+        slug: 'second',
+        frontmatter: 'date: 2025-01-03\ntags:\n  - Campaigns\n',
+        files: ['cover.webp'],
+      },
+      {
+        slug: 'future',
+        frontmatter: 'date: 2999-01-01\ntags:\n  - Future\n',
+      },
+    ])
+
+    const articles = await getAllArticles()
+
+    expect(articles.map((article) => article.slug)).toEqual(['second', 'first'])
+    expect(articles[0]).toEqual(
+      expect.objectContaining({
+        title: 'second',
+        date: '2025-01-03',
+        author: 'Test Author',
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        featuredImage: '/articles/second/cover.webp',
+        contentType: 'md',
+        draft: false,
+      })
+    )
+    expect(articles[1].featuredImage).toBe('/articles/first/hero.png')
+  })
+
+  it('keeps draft articles outside production and filters them in production', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'draft',
+        frontmatter: 'date: 2025-01-01\ndraft: true\n',
+      },
+    ])
+
+    await expect(getAllArticles()).resolves.toHaveLength(1)
+
+    Object.defineProperty(process.env, 'NODE_ENV', {
+      value: 'production',
+      configurable: true,
+    })
+
+    await expect(getAllArticles()).resolves.toEqual([])
+  })
+
+  it('returns adjacent articles based on sorted article order', async () => {
+    setupArticleTreeMock([
+      { slug: 'oldest', frontmatter: 'date: 2025-01-01\n' },
+      { slug: 'middle', frontmatter: 'date: 2025-01-02\n' },
+      { slug: 'newest', frontmatter: 'date: 2025-01-03\n' },
+    ])
+
+    await expect(getAdjacentArticles('middle')).resolves.toEqual({
+      previous: expect.objectContaining({ slug: 'oldest' }),
+      next: expect.objectContaining({ slug: 'newest' }),
+    })
+    await expect(getAdjacentArticles('missing')).resolves.toEqual({ previous: null, next: null })
+  })
+
+  it('searches articles by title, excerpt, author, category, and tag', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'civic-article',
+        frontmatter: 'date: 2025-01-01\ntags:\n  - Civic Tech\n  - voting-tools\n',
+        body: 'Civic body',
+      },
+      {
+        slug: 'organizing-article',
+        frontmatter: 'date: 2025-01-02\ntags:\n  - Field Ops\n',
+        body: 'Organizing body',
+      },
+    ])
+
+    await expect(searchArticles('')).resolves.toHaveLength(2)
+    await expect(searchArticles('civic')).resolves.toEqual([
+      expect.objectContaining({ slug: 'civic-article' }),
+    ])
+    await expect(searchArticles('field ops')).resolves.toEqual([
+      expect.objectContaining({ slug: 'organizing-article' }),
+    ])
+    await expect(searchArticles('voting-tools')).resolves.toEqual([
+      expect.objectContaining({ slug: 'civic-article' }),
+    ])
+  })
+
+  it('groups categories and filters articles by category slug', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'one',
+        frontmatter: 'date: 2025-01-01\ntags:\n  - Civic Tech\n',
+        files: ['one.jpg'],
+      },
+      {
+        slug: 'two',
+        frontmatter: 'date: 2025-01-02\ntags:\n  - Civic Tech\n  - Field Ops\n',
+      },
+    ])
+
+    await expect(getAllCategories()).resolves.toEqual([
+      expect.objectContaining({ name: 'Civic Tech', slug: 'civic-tech', count: 2 }),
+      expect.objectContaining({ name: 'Field Ops', slug: 'field-ops', count: 1 }),
+    ])
+    await expect(getArticlesByCategory('field-ops')).resolves.toEqual([
+      expect.objectContaining({ slug: 'two' }),
+    ])
+  })
+})
+
+describe('getArticleMetadata - content handling', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('loads markdown articles with rendered html content and toc', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'markdown-article',
+        frontmatter:
+          'date: 2025-01-01\nlastmod: 2025-01-05\ntags:\n  - Civic Tech\nfeaturedImage: nested/hero.png\n',
+        body: '## Heading\n\nMarkdown body',
+      },
+    ])
+
+    const article = await getArticleMetadata('markdown-article')
+
+    expect(article).toEqual(
+      expect.objectContaining({
+        slug: 'markdown-article',
+        htmlContent: '<p>content</p>',
+        mdxSource: undefined,
+        date: '2025-01-01',
+        lastmod: '2025-01-05',
+        featuredImage: '/articles/markdown-article/nested/hero.png',
+        toc: [],
+      })
+    )
+  })
+
+  it('loads mdx articles as source instead of rendered html', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'mdx-article',
+        contentType: 'mdx',
+        frontmatter: 'date: 2025-01-01\n',
+        body: '<Component />',
+      },
+    ])
+
+    const article = await getArticleMetadata('mdx-article')
+
+    expect(article).toEqual(
+      expect.objectContaining({
+        slug: 'mdx-article',
+        contentType: 'mdx',
+        htmlContent: undefined,
+      })
+    )
+    expect(article?.mdxSource?.trim()).toBe('<Component />')
+  })
+
+  it('returns null when article file loading fails', async () => {
+    mockedFs.existsSync.mockReturnValue(true)
+    mockedFs.readFileSync.mockImplementation(() => {
+      throw new Error('read failed')
+    })
+
+    await expect(getArticleMetadata('broken')).resolves.toBeNull()
+  })
+})
+
+describe('article path helpers', () => {
+  it('sanitizes image paths and rejects unsafe values', () => {
+    expect(sanitizeImagePath('image.png', 'article')).toBe('/articles/article/image.png')
+    expect(sanitizeImagePath('nested/image.png', 'article')).toBe(
+      '/articles/article/nested/image.png'
+    )
+    expect(sanitizeImagePath('https://example.com/image.png', 'article')).toBe(
+      'https://example.com/image.png'
+    )
+    expect(sanitizeImagePath('../secret.png', 'article')).toBeNull()
+    expect(sanitizeImagePath('/secret.png', 'article')).toBeNull()
+    expect(sanitizeImagePath('bad image.png', 'article')).toBeNull()
+  })
+
+  it('creates normalized category slugs', () => {
+    expect(categoryToSlug('Civic Tech & Field Ops')).toBe('civic-tech--field-ops')
+  })
 })

package/src/server-articles.ts

@@ -83,9 +83,8 @@ function walkArticleDir(dir: string, baseSlug: string): string[] {
       const slug = baseSlug ? `${baseSlug}/${item.name}` : item.name
       if (findArticleFile(slug) !== null) {
         slugs.push(slug)
-      } else {
-        slugs.push(...walkArticleDir(path.join(dir, item.name), slug))
       }
+      slugs.push(...walkArticleDir(path.join(dir, item.name), slug))
     }
   } catch {
     // ignore unreadable directories