@fullstackdatasolutions/articles 0.3.0 → 0.4.3

package/README.md

@@ -62,8 +62,11 @@ export const siteConfig: ArticlesConfig = {
 
 ```tsx
 // app/articles/page.tsx
+import type { Metadata } from 'next'
 import { ArticlesPage } from '@fullstackdatasolutions/articles'
+import { generateArticlesIndexMetadata } from '@fullstackdatasolutions/articles/server'
 import { siteConfig } from '@/config/articles'
+export const metadata: Metadata = generateArticlesIndexMetadata(siteConfig)
 export default function Page() {
   return <ArticlesPage config={siteConfig} />
 }
@@ -173,7 +176,7 @@ hero: {
 
 ## ArticleDetailHero
 
-`ArticleDetailHero` renders the article's featured image full-width behind the title, category tags, and metadata (date, read time, author). Use it in your `app/articles/[slug]/page.tsx` instead of building a custom hero.
+`ArticleDetailHero` renders the article's featured image full-width behind the title, category tags, and metadata (date, read time, author). When you render `ArticleDetailHero` exactly as shown below the hero image and linked categories appear automatically—no additional styling or extra `<Link>` wiring is required in the consuming app. Just pass the article payload and `categoryBasePath` (defaults to `/articles/category`) so the tags render as links.
 
 ```tsx
 import { ArticleDetailHero } from '@fullstackdatasolutions/articles'
@@ -187,10 +190,61 @@ import { ArticleDetailHero } from '@fullstackdatasolutions/articles'
 | Prop | Type | Required | Description |
 |---|---|---|---|
 | `article` | `Article` | yes | Article object returned by `getArticleMetadata` |
-| `categoryBasePath` | `string` | no | Base path for category links (e.g. `"/articles/category"`). Omit to render categories as plain text. |
+| `categoryBasePath` | `string` | no | Base path for category links. Defaults to `"/articles/category"`. Pass `""` to render categories as plain text. |
+| `showDate` | `boolean` | no | Show the article date. Defaults to `false` (hidden). |
 
 - Category tags are capped at 4. When an article has more than 4 categories, only the first 4 are shown.
+- The date field is hidden by default. Pass `showDate={true}` to display it.
 - All layout styles are inline so the component renders correctly regardless of whether `@source` is configured for the package.
+ - Hero image / categories behave automatically once you use this component; apps do not need to reimplement the hero section for those features.
+
+---
+
+## ArticleSocialShare
+
+`ArticleSocialShare` renders a row of sharing buttons (LinkedIn, Facebook, Twitter, Reddit, WhatsApp, Telegram, Email, Copy Link). Use it below the article body in your `app/articles/[slug]/page.tsx`.
+
+```tsx
+import { ArticleSocialShare } from '@fullstackdatasolutions/articles'
+
+<ArticleSocialShare
+  title={article.title}
+  url={articleUrl}
+  excerpt={article.excerpt}
+  shareMessage="Optional footer note shown below the buttons."
+/>
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | yes | Article title - used in share text |
+| `url` | `string` | yes | Canonical URL to share |
+| `excerpt` | `string` | no | Used as email body pre-fill |
+| `shareMessage` | `string` | no | Optional paragraph rendered below the share buttons |
+
+---
+
+## ArticleNavigation
+
+`ArticleNavigation` renders previous/next article links at the bottom of an article. Returns `null` when both `previous` and `next` are absent (no output, no wrapper element). Use `getAdjacentArticles` from the server entry to fetch the data.
+
+```tsx
+import { ArticleNavigation } from '@fullstackdatasolutions/articles'
+import { getAdjacentArticles } from '@fullstackdatasolutions/articles/server'
+
+const { previous, next } = await getAdjacentArticles(slug)
+
+<ArticleNavigation previous={previous} next={next} basePath="/articles" />
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `previous` | `{ slug: string; title: string } \| null` | yes | Previous article, or `null` |
+| `next` | `{ slug: string; title: string } \| null` | yes | Next article, or `null` |
+| `basePath` | `string` | yes | Route prefix (e.g. `"/articles"`) prepended to each slug |
+
+- Titles longer than 60 characters are truncated with an ellipsis.
+- No output is rendered when both `previous` and `next` are `null`.
 
 ---
 
@@ -226,6 +280,21 @@ app/api/articles/[slug]/comments/[commentId]/route.ts  ← DELETE (soft)
 
 ## SEO utilities
 
+### Articles index metadata
+
+```ts
+// app/articles/page.tsx
+import type { Metadata } from 'next'
+import { generateArticlesIndexMetadata } from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+export const metadata: Metadata = generateArticlesIndexMetadata(siteConfig)
+// Produces: title, description, full OpenGraph (type: 'website'), Twitter Card,
+// canonical URL (/articles), and robots directives.
+// Description falls back to config.hero?.description when set.
+```
+
+### Article and category metadata
+
 ```ts
 // app/articles/[slug]/page.tsx
 import { generateArticleMetadata } from '@fullstackdatasolutions/articles/server'
@@ -237,15 +306,31 @@ export const generateMetadata = ({ params }) =>
 import { generateCategoryMetadata } from '@fullstackdatasolutions/articles/server'
 export const generateMetadata = ({ params }) =>
   generateCategoryMetadata(params.category, siteConfig)
+```
+
+### Sitemaps
 
+Use `getArticleSitemapEntries` to generate article and category sitemap entries. Pass your `ArticlesConfig` object (preferred) or a plain URL string.
+
+```ts
 // app/sitemap.ts
 import { getArticleSitemapEntries } from '@fullstackdatasolutions/articles/server'
-export default async function sitemap() {
-  return getArticleSitemapEntries('https://yoursite.com')
-  // Returns both article entries (priority 0.8) and category entries (priority 0.7)
+import { siteConfig } from '@/config/articles'
+import type { MetadataRoute } from 'next'
+
+const staticPages: MetadataRoute.Sitemap = [
+  { url: 'https://yoursite.com', changeFrequency: 'weekly', priority: 1.0 },
+  { url: 'https://yoursite.com/about', changeFrequency: 'monthly', priority: 0.8 },
+]
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const articleEntries = await getArticleSitemapEntries(siteConfig)
+  return [...staticPages, ...articleEntries]
 }
 ```
 
+Returns article entries (priority 0.8, changeFrequency 'weekly') and category entries (priority 0.7, changeFrequency 'weekly'). Alternative: pass a plain URL string instead of `siteConfig`: `getArticleSitemapEntries('https://yoursite.com')`.
+
 JSON-LD structured data (`ArticleSchema`, `BreadcrumbSchema`, `CollectionPageSchema`) is rendered automatically inside the library components — no extra wiring required.
 
 ---
@@ -278,6 +363,7 @@ import {
   searchArticles,
   categoryToSlug,
   getArticleSitemapEntries,
+  generateArticlesIndexMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
 } from '@fullstackdatasolutions/articles/server'
@@ -330,7 +416,10 @@ This app uses `@fullstackdatasolutions/articles` for the articles section.
 The package ships its source TypeScript files so Tailwind can scan them.
 `app/globals.css` contains:
   @source "./node_modules/@fullstackdatasolutions/articles/src";
-If this line is missing, most component classes will not render correctly. Note: `ArticleCategoryGrid` image containers use inline styles for critical layout so images remain visible, but all other styling still requires this line.
+If this line is missing, most component classes will not render correctly. Note: `ArticleCategoryGrid` images, `CategoryArticlesPage` hero, and `ArticleDetailHero` image use inline styles for critical layout so they render correctly without this line. All other styling still requires it.
+
+### Server utilities
+For sitemaps and metadata: `import { getArticleSitemapEntries, generateArticlesIndexMetadata, generateArticleMetadata, generateCategoryMetadata } from '@fullstackdatasolutions/articles/server'`. See README for usage examples.
 
 ### Rules
 - Change `config/articles.ts` first; only edit library source if config cannot express the need.