@fullstackdatasolutions/articles 0.2.1 → 0.4.2

package/README.md

@@ -171,6 +171,79 @@ 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.
+
+```tsx
+import { ArticleDetailHero } from '@fullstackdatasolutions/articles'
+
+<ArticleDetailHero
+  article={article}
+  categoryBasePath="/articles/category"
+/>
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `article` | `Article` | yes | Article object returned by `getArticleMetadata` |
+| `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.
+
+---
+
+## 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`.
+
+---
+
 ## Comments setup
 
 ### 1. Enable in config
@@ -203,6 +276,8 @@ app/api/articles/[slug]/comments/[commentId]/route.ts  ← DELETE (soft)
 
 ## SEO utilities
 
+### Article and category metadata
+
 ```ts
 // app/articles/[slug]/page.tsx
 import { generateArticleMetadata } from '@fullstackdatasolutions/articles/server'
@@ -214,15 +289,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.
 
 ---
@@ -234,7 +325,7 @@ JSON-LD structured data (`ArticleSchema`, `BreadcrumbSchema`, `CollectionPageSch
 | `title` | `string` | yes | Article title |
 | `excerpt` | `string` | yes | One-sentence summary for cards and meta |
 | `author` | `string` | no | Defaults to `'Andrew Blase'` |
-| `tags` | `string[]` | no | Used as categories. First tag = primary category. |
+| `tags` | `string[]` | no | Used as categories. First tag = primary category. ArticleDetailHero displays at most 4 category tags; articles with more than 4 show only the first 4 in the hero. |
 | `date` | `YYYY-MM-DD` | no | Omit to publish immediately. Future dates hide until that date. |
 | `featuredImage` | `string` | no | Filename relative to the article directory. Auto-detected if omitted. |
 
@@ -307,7 +398,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, 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.