@fullstackdatasolutions/articles 0.1.0

package/README.md

@@ -0,0 +1,324 @@
+# @fullstackdatasolutions/articles
+
+A self-contained Next.js articles library providing components, server utilities, SEO helpers, and a comments system. Drop it into any Next.js + Tailwind CSS v4 app.
+
+---
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install @fullstackdatasolutions/articles
+# or
+pnpm add @fullstackdatasolutions/articles
+```
+
+### 2. Add the Tailwind source path
+
+In Tailwind CSS v4, you add a `@source` directive to your global CSS file — **not** a `tailwind.config.ts`. This tells Tailwind to scan the package's source files so all utility classes are generated.
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+
+@source "./node_modules/@fullstackdatasolutions/articles/src";
+```
+
+The package components use Tailwind semantic tokens (`bg-card`, `text-muted-foreground`, `border-border`, etc.) that shadcn/ui and v0-generated apps already define — so the styling integrates automatically with your existing theme.
+
+### 3. Add TypeScript path aliases
+
+If you're using TypeScript and want IDE autocomplete without a pre-built `dist/`, add these paths to `tsconfig.json`. This is **required in a monorepo** (where the package is a workspace dep) and optional when installed from npm (the published `dist/` files work without it).
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "@fullstackdatasolutions/articles": ["./node_modules/@fullstackdatasolutions/articles/src/index.ts"],
+      "@fullstackdatasolutions/articles/server": ["./node_modules/@fullstackdatasolutions/articles/src/server.ts"]
+    }
+  }
+}
+```
+
+### 4. Create your site config
+
+```ts
+// config/articles.ts
+import type { ArticlesConfig } from '@fullstackdatasolutions/articles'
+
+export const siteConfig: ArticlesConfig = {
+  siteUrl:  'https://yoursite.com',
+  siteName: 'Your Site',
+  pageSize: 6,
+}
+```
+
+### 5. Wire up the route files
+
+```tsx
+// app/articles/page.tsx
+import { ArticlesPage } from '@fullstackdatasolutions/articles'
+import { siteConfig } from '@/config/articles'
+export default function Page() {
+  return <ArticlesPage config={siteConfig} />
+}
+
+// app/articles/[slug]/page.tsx
+import { ArticlePage, generateArticleStaticParams, generateArticleMetadata } from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+export const generateStaticParams = () => generateArticleStaticParams()
+export const generateMetadata = ({ params }: { params: { slug: string } }) =>
+  generateArticleMetadata(params.slug, siteConfig)
+export default function Page({ params }: { params: { slug: string } }) {
+  return <ArticlePage slug={params.slug} config={siteConfig} />
+}
+
+// app/articles/category/[category]/page.tsx
+import { CategoryArticlesPage, generateCategoryStaticParams, generateCategoryMetadata } from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+export const generateStaticParams = () => generateCategoryStaticParams()
+export const generateMetadata = ({ params }: { params: { category: string } }) =>
+  generateCategoryMetadata(params.category, siteConfig)
+export default function Page({ params }: { params: { category: string } }) {
+  return <CategoryArticlesPage category={params.category} config={siteConfig} />
+}
+```
+
+### 6. Copy the API routes
+
+These cannot live inside the package — Next.js file-based routing requires them in your app. Copy these files from the reference implementation:
+
+```
+app/api/articles/route.ts
+app/api/articles/[slug]/comments/route.ts
+app/api/articles/[slug]/comments/[commentId]/route.ts
+```
+
+The route implementations import from `@fullstackdatasolutions/articles/server`. Do not put custom business logic in them; they should stay as thin wrappers.
+
+### 7. Add your content
+
+Create `public/articles/[slug]/article.md` for each article. Required frontmatter:
+
+```markdown
+---
+title: Your Article Title
+excerpt: A one-sentence summary shown in cards and meta descriptions.
+author: Jane Doe
+tags: [campaigns, strategy]
+---
+
+Article body in Markdown...
+```
+
+---
+
+## `ArticlesConfig` reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `siteUrl` | `string` | — | Canonical base URL. Used in metadata and JSON-LD. |
+| `siteName` | `string` | — | Site name in title tags and JSON-LD. |
+| `pageSize` | `number` | `6` | Articles per page / per "Load more" click. |
+| `categoriesPageSize` | `number` | `8` | Category cards before "Load more categories". |
+| `layout` | `ArticlesSection[]` | see below | Ordered sections to render. Omit a key to hide it. |
+| `theme` | `ArticlesTheme` | — | CSS custom-property overrides for colors and fonts. |
+| `categoryDescriptions` | `Record<string, string \| CategoryDescription>` | — | Short/long text per category slug. |
+| `comments` | `CommentsConfig` | — | Comments feature config. Omit to disable entirely. |
+
+**Default layout order:** `['hero', 'search', 'featured', 'latest', 'categories']`
+
+To add a newsletter section, pass `layout: ['hero','search','featured','latest','categories','newsletter']` — the library renders `null` for `'newsletter'` so you can append your own component after `<ArticlesPage />`.
+
+---
+
+## Theming
+
+All theme values are applied as CSS custom properties on a wrapper `<div>`. Components reference them through Tailwind so no extra CSS file is needed.
+
+```ts
+theme: {
+  fontFamily:      "'Inter', sans-serif",
+  headerColor:     '#111827',
+  textColor:       '#6b7280',
+  backgroundColor: '#ffffff',
+  linkColor:       '#4f46e5',
+  linkHoverColor:  '#4338ca',
+  borderRadius:    '0.5rem',
+}
+```
+
+All fields are optional. Omitted fields fall back to your Tailwind theme tokens.
+
+---
+
+## Comments setup
+
+### 1. Enable in config
+
+```ts
+export const siteConfig: ArticlesConfig = {
+  // ...
+  comments: {
+    enabled: true,
+    perArticleOverride: {
+      'sensitive-article': false,   // opt individual articles out
+    },
+  },
+}
+```
+
+### 2. Copy the comment API routes
+
+```
+app/api/articles/[slug]/comments/route.ts          ← GET list, POST new comment
+app/api/articles/[slug]/comments/[commentId]/route.ts  ← DELETE (soft)
+```
+
+### 3. Requirements
+
+- **NextAuth** session — users must be signed in to post. Unauthenticated visitors see a sign-in prompt.
+- **PostgreSQL** — comments are stored via Prisma. Run the migration from the reference app's `backend/` directory.
+
+---
+
+## SEO utilities
+
+```ts
+// app/articles/[slug]/page.tsx
+import { generateArticleMetadata } from '@fullstackdatasolutions/articles/server'
+export const generateMetadata = ({ params }) =>
+  generateArticleMetadata(params.slug, siteConfig)
+// Produces: title, description, full OpenGraph, Twitter Card, canonical URL
+
+// app/articles/category/[category]/page.tsx
+import { generateCategoryMetadata } from '@fullstackdatasolutions/articles/server'
+export const generateMetadata = ({ params }) =>
+  generateCategoryMetadata(params.category, siteConfig)
+
+// 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)
+}
+```
+
+JSON-LD structured data (`ArticleSchema`, `BreadcrumbSchema`, `CollectionPageSchema`) is rendered automatically inside the library components — no extra wiring required.
+
+---
+
+## Article frontmatter reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `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. |
+| `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. |
+
+---
+
+## Server utilities
+
+Import from `@fullstackdatasolutions/articles/server` — these use `fs`/`path` and must never be imported in client components.
+
+```ts
+import {
+  getAllArticles,
+  getArticleMetadata,
+  getArticlesByCategory,
+  getAllCategories,
+  getAvailableArticleSlugs,
+  getAdjacentArticles,
+  searchArticles,
+  categoryToSlug,
+  getArticleSitemapEntries,
+  generateArticleMetadata,
+  generateCategoryMetadata,
+} from '@fullstackdatasolutions/articles/server'
+```
+
+---
+
+## Using in a monorepo (workspace)
+
+If the package is a `workspace:*` dependency in a pnpm/npm monorepo, point TypeScript directly at the source so no build step is needed during local development:
+
+```json
+// tsconfig.json — consuming app
+{
+  "compilerOptions": {
+    "paths": {
+      "@fullstackdatasolutions/articles": ["../packages/articles/src/index.ts"],
+      "@fullstackdatasolutions/articles/server": ["../packages/articles/src/server.ts"]
+    }
+  }
+}
+```
+
+And point the Tailwind `@source` at the workspace path:
+
+```css
+/* app/globals.css */
+@source "../../packages/articles/src";
+```
+
+The relative path from your CSS file to `packages/articles/src` will vary by your monorepo layout.
+
+---
+
+## Adding to your app's `AGENTS.md`
+
+Paste this block into your app's `AGENTS.md` so AI assistants know how the library works:
+
+```markdown
+## Articles library
+
+This app uses `@fullstackdatasolutions/articles` for the articles section.
+
+### Key files
+- `config/articles.ts` — all library behaviour (layout, theme, page size, comments) is controlled here
+- `app/api/articles/` — thin API route wrappers; do not add business logic here
+- `public/articles/[slug]/article.md` — one directory per article
+
+### CSS (Tailwind v4)
+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, component classes (layout, images, line-clamp) will not render correctly.
+
+### Rules
+- Change `config/articles.ts` first; only edit library source if config cannot express the need.
+- When adding a new article: create `public/articles/[slug]/article.md` with title, excerpt, author, tags.
+- API routes are copied from the library — update the package version and re-copy if the library API changes.
+- Full library docs: `node_modules/@fullstackdatasolutions/articles/README.md`
+```
+
+---
+
+## Publishing
+
+The package publishes to npm automatically when you push a tag:
+
+```bash
+git tag articles-v0.2.0
+git push origin articles-v0.2.0
+```
+
+GitHub Actions runs typecheck → test → build → `npm publish --access public`. Requires an `NPM_TOKEN` secret in the repo settings.
+
+---
+
+## Upgrading
+
+Follow semver. Breaking changes (major) include a migration note in the changelog.
+
+- **Patch** — bug fixes only, safe to update
+- **Minor** — new config options or exports, backwards-compatible
+- **Major** — `ArticlesConfig` shape or component prop changes; check migration notes