@fullstackdatasolutions/articles 0.6.0 → 0.7.0

package/README.md

@@ -23,12 +23,21 @@ In Tailwind CSS v4, you add a `@source` directive to your global CSS file — **
 ```css
 /* app/globals.css */
 @import "tailwindcss";
+@plugin "@tailwindcss/typography";
 
 @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.
 
+Install `@tailwindcss/typography` if not already present:
+
+```bash
+npm install @tailwindcss/typography
+# or
+pnpm add @tailwindcss/typography
+```
+
 ### 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).
@@ -191,6 +200,7 @@ Article directories can also be nested below grouping folders. For example, `pub
 | `hero` | `HeroConfig` | — | Hero section title and description. Omit to use built-in defaults. |
 | `comments` | `CommentsConfig` | — | Comments feature config. Omit to disable entirely. |
 | `showToc` | `boolean` | `true` | Show the table of contents on article detail pages. Set to `false` to hide on all articles. |
+| `showBackToArticles` | `boolean` | `true` | Show the back-navigation link on article detail pages. Set to `false` to hide `ArticleBackLink`. |
 | `description` | `string` | — | Short description used as the RSS feed channel description. Falls back to `siteName` if omitted. |
 
 **Default layout order:** `['hero', 'search', 'featured', 'latest', 'categories']`
@@ -327,6 +337,36 @@ import { ArticleTOC } from '@fullstackdatasolutions/articles/server'
 
 ---
 
+## ArticleBackLink
+
+`ArticleBackLink` renders a back-navigation link on article detail pages. Returns `null` when `config.showBackToArticles === false`, so it is safe to render unconditionally.
+
+```tsx
+import { ArticleBackLink } from '@fullstackdatasolutions/articles'
+
+<ArticleBackLink config={siteConfig} />
+
+// With custom props:
+<ArticleBackLink
+  config={siteConfig}
+  href="/blog"
+  label="Back to Blog"
+  className="custom-class"
+/>
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `config` | `ArticlesConfig` | yes | Site config. Must include `showBackToArticles?: boolean` from ArticlesConfig. |
+| `href` | `string` | no | Link destination. Defaults to `/articles`. |
+| `label` | `string` | no | Link text. Defaults to `Back to Articles`. |
+| `className` | `string` | no | Optional CSS class to override default styling. |
+
+- Returns `null` when `config.showBackToArticles === false`
+- Gate used in article detail pages: `config.showBackToArticles !== false`
+
+---
+
 ## ScrollToTop
 
 `ScrollToTop` is a fixed-position floating button in the bottom-right corner that appears when the user scrolls past 300px, and smooth-scrolls back to the top on click. Client component (`'use client'`). No props required - fully self-contained, safe to place anywhere in your layout.
@@ -574,6 +614,7 @@ And point the Tailwind `@source` at the workspace path:
 
 ```css
 /* app/globals.css */
+@plugin "@tailwindcss/typography";
 @source "../../packages/articles/src";
 ```
 
@@ -599,9 +640,11 @@ This app uses `@fullstackdatasolutions/articles` for the articles section.
 
 ### CSS (Tailwind v4)
 The package ships its source TypeScript files so Tailwind can scan them.
-`app/globals.css` contains:
+`app/globals.css` must contain:
+  @plugin "@tailwindcss/typography";
   @source "./node_modules/@fullstackdatasolutions/articles/src";
-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.
+If the `@source` 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.
+The `@plugin "@tailwindcss/typography"` line is required for article body prose styling. Install with `pnpm add @tailwindcss/typography`.
 
 ### Components
 - `ArticleTOC` — server component imported from `@fullstackdatasolutions/articles/server`; renders `article.toc[]` as a nav block. Controlled by `siteConfig.showToc` (defaults `true`). Returns `null` when empty.

package/dist/index.cjs

@@ -69,6 +69,7 @@ var __async = (__this, __arguments, generator) => {
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  ArticleBackLink: () => ArticleBackLink,
   ArticleCard: () => ArticleCard,
   ArticleCategoryGrid: () => ArticleCategoryGrid,
   ArticleDetailHero: () => ArticleDetailHero,
@@ -1088,18 +1089,42 @@ function ArticleNavigation({ previous, next, basePath }) {
   ] }) });
 }
 
-// src/ArticleTOC.tsx
+// src/ArticleBackLink.tsx
+var import_link8 = __toESM(require("next/link"), 1);
+var import_lucide_react8 = require("lucide-react");
 var import_jsx_runtime14 = require("react/jsx-runtime");
+function ArticleBackLink({
+  config,
+  href = "/articles",
+  label = "Back to Articles",
+  className
+}) {
+  if (config.showBackToArticles === false) return null;
+  return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(
+    import_link8.default,
+    {
+      href,
+      className: className != null ? className : "inline-flex items-center gap-2 mb-6 -ml-3 px-3 py-2 rounded-md text-sm font-medium text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(import_lucide_react8.ArrowLeft, { className: "h-4 w-4" }),
+        label
+      ]
+    }
+  );
+}
+
+// src/ArticleTOC.tsx
+var import_jsx_runtime15 = require("react/jsx-runtime");
 function ArticleTOC({ toc, className }) {
   if (!toc.length) return null;
-  return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(
+  return /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)(
     "nav",
     {
       "aria-label": "Table of contents",
       className: `mb-8 rounded-lg border border-border bg-muted/40 px-6 py-4 ${className != null ? className : ""}`,
       children: [
-        /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("p", { className: "mb-3 text-sm font-semibold uppercase tracking-wide text-muted-foreground", children: "On this page" }),
-        /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("ul", { className: "space-y-1 text-sm", children: toc.map((item) => /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("li", { style: { paddingLeft: `${Math.max(0, item.depth - 2) * 1}rem` }, children: /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+        /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("p", { className: "mb-3 text-sm font-semibold uppercase tracking-wide text-muted-foreground", children: "On this page" }),
+        /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("ul", { className: "space-y-1 text-sm", children: toc.map((item) => /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("li", { style: { paddingLeft: `${Math.max(0, item.depth - 2) * 1}rem` }, children: /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
           "a",
           {
             href: `#${item.id}`,
@@ -1114,8 +1139,8 @@ function ArticleTOC({ toc, className }) {
 
 // src/ScrollToTop.tsx
 var import_react5 = require("react");
-var import_lucide_react8 = require("lucide-react");
-var import_jsx_runtime15 = require("react/jsx-runtime");
+var import_lucide_react9 = require("lucide-react");
+var import_jsx_runtime16 = require("react/jsx-runtime");
 function ScrollToTop() {
   const [visible, setVisible] = (0, import_react5.useState)(false);
   (0, import_react5.useEffect)(() => {
@@ -1124,13 +1149,13 @@ function ScrollToTop() {
     return () => globalThis.removeEventListener("scroll", onScroll);
   }, []);
   if (!visible) return null;
-  return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
     "button",
     {
       "aria-label": "Scroll to top",
       onClick: () => globalThis.scrollTo({ top: 0, behavior: "smooth" }),
       className: "fixed bottom-8 right-8 z-50 rounded-full bg-primary p-2 shadow-md text-primary-foreground hover:bg-primary/90 transition-colors",
-      children: /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(import_lucide_react8.ArrowUp, { className: "h-5 w-5" })
+      children: /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(import_lucide_react9.ArrowUp, { className: "h-5 w-5" })
     }
   );
 }
@@ -1141,7 +1166,7 @@ var import_react9 = require("react");
 
 // src/CommentForm.tsx
 var import_react6 = require("react");
-var import_jsx_runtime16 = require("react/jsx-runtime");
+var import_jsx_runtime17 = require("react/jsx-runtime");
 var MAX_LENGTH = 2e3;
 var WARN_THRESHOLD = 1800;
 function submitLabel(submitting, parentId) {
@@ -1180,8 +1205,8 @@ function CommentForm({ articleSlug, parentId, onSuccess, onCancel }) {
       }
     });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime16.jsxs)("form", { onSubmit: handleSubmit, className: "space-y-2", children: [
-    /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)("form", { onSubmit: handleSubmit, className: "space-y-2", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
       "textarea",
       {
         value: body,
@@ -1194,13 +1219,13 @@ function CommentForm({ articleSlug, parentId, onSuccess, onCancel }) {
         "aria-label": parentId ? "Reply text" : "Comment text"
       }
     ),
-    remaining <= MAX_LENGTH - WARN_THRESHOLD && /* @__PURE__ */ (0, import_jsx_runtime16.jsxs)("p", { className: `text-xs ${remaining < 0 ? "text-destructive" : "text-muted-foreground"}`, children: [
+    remaining <= MAX_LENGTH - WARN_THRESHOLD && /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)("p", { className: `text-xs ${remaining < 0 ? "text-destructive" : "text-muted-foreground"}`, children: [
       remaining,
       " characters remaining"
     ] }),
-    error && /* @__PURE__ */ (0, import_jsx_runtime16.jsx)("p", { className: "text-xs text-destructive", children: error }),
-    /* @__PURE__ */ (0, import_jsx_runtime16.jsxs)("div", { className: "flex gap-2", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
+    error && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("p", { className: "text-xs text-destructive", children: error }),
+    /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)("div", { className: "flex gap-2", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
         "button",
         {
           type: "submit",
@@ -1209,7 +1234,7 @@ function CommentForm({ articleSlug, parentId, onSuccess, onCancel }) {
           children: submitLabel(submitting, parentId)
         }
       ),
-      onCancel && /* @__PURE__ */ (0, import_jsx_runtime16.jsx)(
+      onCancel && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
         "button",
         {
           type: "button",
@@ -1224,7 +1249,7 @@ function CommentForm({ articleSlug, parentId, onSuccess, onCancel }) {
 
 // src/CommentItem.tsx
 var import_react7 = require("react");
-var import_jsx_runtime17 = require("react/jsx-runtime");
+var import_jsx_runtime18 = require("react/jsx-runtime");
 function relativeTime(iso) {
   const diff = Date.now() - new Date(iso).getTime();
   const minutes = Math.floor(diff / 6e4);
@@ -1262,15 +1287,15 @@ function CommentItem({
       }
     });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)("div", { className: `${isReply ? "ml-8 border-l-2 border-border pl-4" : ""}`, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("div", { className: "rounded-lg bg-muted/40 p-3 space-y-1", children: comment.isDeleted ? /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("p", { className: "text-sm italic text-muted-foreground", children: "Comment removed" }) : /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)(import_jsx_runtime17.Fragment, { children: [
-      /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)("div", { className: "flex items-center justify-between gap-2", children: [
-        /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("span", { className: "text-sm font-medium text-foreground", children: comment.authorName }),
-        /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("span", { className: "text-xs text-muted-foreground", children: relativeTime(comment.createdAt) })
+  return /* @__PURE__ */ (0, import_jsx_runtime18.jsxs)("div", { className: `${isReply ? "ml-8 border-l-2 border-border pl-4" : ""}`, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("div", { className: "rounded-lg bg-muted/40 p-3 space-y-1", children: comment.isDeleted ? /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("p", { className: "text-sm italic text-muted-foreground", children: "Comment removed" }) : /* @__PURE__ */ (0, import_jsx_runtime18.jsxs)(import_jsx_runtime18.Fragment, { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime18.jsxs)("div", { className: "flex items-center justify-between gap-2", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("span", { className: "text-sm font-medium text-foreground", children: comment.authorName }),
+        /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("span", { className: "text-xs text-muted-foreground", children: relativeTime(comment.createdAt) })
       ] }),
-      /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("p", { className: "text-sm text-foreground whitespace-pre-wrap break-words", children: comment.body }),
-      /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)("div", { className: "flex gap-3 pt-1", children: [
-        canReply && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
+      /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("p", { className: "text-sm text-foreground whitespace-pre-wrap break-words", children: comment.body }),
+      /* @__PURE__ */ (0, import_jsx_runtime18.jsxs)("div", { className: "flex gap-3 pt-1", children: [
+        canReply && /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
           "button",
           {
             onClick: () => setShowReplyForm((v) => !v),
@@ -1278,7 +1303,7 @@ function CommentItem({
             children: showReplyForm ? "Cancel" : "Reply"
           }
         ),
-        canDelete && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
+        canDelete && /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
           "button",
           {
             onClick: handleDelete,
@@ -1289,7 +1314,7 @@ function CommentItem({
         )
       ] })
     ] }) }),
-    showReplyForm && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("div", { className: "mt-2 ml-2", children: /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
+    showReplyForm && /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("div", { className: "mt-2 ml-2", children: /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
       CommentForm,
       {
         articleSlug,
@@ -1301,7 +1326,7 @@ function CommentItem({
         onCancel: () => setShowReplyForm(false)
       }
     ) }),
-    replies.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("div", { className: "mt-2 space-y-2", children: replies.map((reply) => /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
+    replies.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("div", { className: "mt-2 space-y-2", children: replies.map((reply) => /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
       CommentItem,
       {
         comment: __spreadProps(__spreadValues({}, reply), { replies: [] }),
@@ -1316,7 +1341,7 @@ function CommentItem({
 }
 
 // src/CommentThread.tsx
-var import_jsx_runtime18 = require("react/jsx-runtime");
+var import_jsx_runtime19 = require("react/jsx-runtime");
 function CommentThread({
   comments,
   articleSlug,
@@ -1324,9 +1349,9 @@ function CommentThread({
   onRefresh
 }) {
   if (comments.length === 0) {
-    return /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("p", { className: "text-sm text-muted-foreground text-center py-6", children: "No comments yet. Be the first to share your thoughts." });
+    return /* @__PURE__ */ (0, import_jsx_runtime19.jsx)("p", { className: "text-sm text-muted-foreground text-center py-6", children: "No comments yet. Be the first to share your thoughts." });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("div", { className: "space-y-4", children: comments.map((comment) => /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime19.jsx)("div", { className: "space-y-4", children: comments.map((comment) => /* @__PURE__ */ (0, import_jsx_runtime19.jsx)(
     CommentItem,
     {
       comment,
@@ -1339,7 +1364,7 @@ function CommentThread({
 }
 
 // src/CommentsSection.tsx
-var import_jsx_runtime19 = require("react/jsx-runtime");
+var import_jsx_runtime20 = require("react/jsx-runtime");
 function CommentsSection({ articleSlug, config }) {
   var _a, _b, _c, _d, _e, _f;
   const { data: session, status } = (0, import_react8.useSession)();
@@ -1371,10 +1396,10 @@ function CommentsSection({ articleSlug, config }) {
   if (!enabled) return null;
   const count = comments.length;
   const label = count === 1 ? "1 comment" : `${count} comments`;
-  return /* @__PURE__ */ (0, import_jsx_runtime19.jsxs)("section", { "aria-label": "Comments", className: "mt-12 pt-8 border-t border-border space-y-6", children: [
-    /* @__PURE__ */ (0, import_jsx_runtime19.jsx)("h2", { className: "text-xl font-semibold text-foreground", children: loading ? "Comments" : label }),
-    status === "authenticated" ? /* @__PURE__ */ (0, import_jsx_runtime19.jsx)(CommentForm, { articleSlug, onSuccess: fetchComments }) : /* @__PURE__ */ (0, import_jsx_runtime19.jsxs)("p", { className: "text-sm text-muted-foreground", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime19.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime20.jsxs)("section", { "aria-label": "Comments", className: "mt-12 pt-8 border-t border-border space-y-6", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime20.jsx)("h2", { className: "text-xl font-semibold text-foreground", children: loading ? "Comments" : label }),
+    status === "authenticated" ? /* @__PURE__ */ (0, import_jsx_runtime20.jsx)(CommentForm, { articleSlug, onSuccess: fetchComments }) : /* @__PURE__ */ (0, import_jsx_runtime20.jsxs)("p", { className: "text-sm text-muted-foreground", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime20.jsx)(
         "button",
         {
           onClick: () => (0, import_react8.signIn)(),
@@ -1385,8 +1410,8 @@ function CommentsSection({ articleSlug, config }) {
       " ",
       "to join the discussion."
     ] }),
-    fetchError && /* @__PURE__ */ (0, import_jsx_runtime19.jsx)("p", { className: "text-sm text-destructive", children: fetchError }),
-    loading ? /* @__PURE__ */ (0, import_jsx_runtime19.jsx)("p", { className: "text-sm text-muted-foreground", children: "Loading comments\u2026" }) : /* @__PURE__ */ (0, import_jsx_runtime19.jsx)(
+    fetchError && /* @__PURE__ */ (0, import_jsx_runtime20.jsx)("p", { className: "text-sm text-destructive", children: fetchError }),
+    loading ? /* @__PURE__ */ (0, import_jsx_runtime20.jsx)("p", { className: "text-sm text-muted-foreground", children: "Loading comments\u2026" }) : /* @__PURE__ */ (0, import_jsx_runtime20.jsx)(
       CommentThread,
       {
         comments,
@@ -1399,6 +1424,7 @@ function CommentsSection({ articleSlug, config }) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ArticleBackLink,
   ArticleCard,
   ArticleCategoryGrid,
   ArticleDetailHero,