@fullstackdatasolutions/articles 0.1.0 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+Built by [Full Stack Data Solutions](https://fullstackdatasolutions.com).
+
 ---
 
 ## Quick start
@@ -127,6 +129,7 @@ Article body in Markdown...
 | `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. |
+| `hero` | `HeroConfig` | — | Hero section title and description. Omit to use built-in defaults. |
 | `comments` | `CommentsConfig` | — | Comments feature config. Omit to disable entirely. |
 
 **Default layout order:** `['hero', 'search', 'featured', 'latest', 'categories']`
@@ -155,6 +158,19 @@ All fields are optional. Omitted fields fall back to your Tailwind theme tokens.
 
 ---
 
+## Hero section
+
+Customize the hero heading by passing `title` and `description` to `HeroConfig`. Omit the `hero` field entirely to use built-in defaults.
+
+```ts
+hero: {
+  title: 'My App Articles',
+  description: 'Insights and updates from our team.',
+}
+```
+
+---
+
 ## Comments setup
 
 ### 1. Enable in config
@@ -291,12 +307,13 @@ 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, component classes (layout, images, line-clamp) will not render correctly.
+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.
 
 ### 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.
+- `hero.title` and `hero.description` in `ArticlesConfig` control the hero heading — pass them to customize per app.
 - Full library docs: `node_modules/@fullstackdatasolutions/articles/README.md`
 ```
 
@@ -307,8 +324,8 @@ If this line is missing, component classes (layout, images, line-clamp) will not
 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
+git tag articles-v0.2.1
+git push origin articles-v0.2.1
 ```
 
 GitHub Actions runs typecheck → test → build → `npm publish --access public`. Requires an `NPM_TOKEN` secret in the repo settings.

package/dist/index.cjs

@@ -102,8 +102,7 @@ function ArticleCategoryGrid({ categories, pageSize = 8 }) {
   (0, import_react.useEffect)(() => {
     setVisibleCount(pageSize);
   }, [categories, pageSize]);
-  if (categories.length === 0)
-    return null;
+  if (categories.length === 0) return null;
   const visible = categories.slice(0, visibleCount);
   const hasMore = visibleCount < categories.length;
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("section", { className: "py-16 bg-background", children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8", children: [
@@ -111,26 +110,37 @@ function ArticleCategoryGrid({ categories, pageSize = 8 }) {
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h2", { className: "text-3xl font-bold text-foreground mb-4", children: "Browse by Category" }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "text-lg text-muted-foreground", children: "Explore our articles by topic to find the insights most relevant to your interests." })
     ] }),
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "grid grid-cols-2 sm:grid-cols-4 gap-6", children: visible.map((cat) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_link.default, { href: `/articles/category/${cat.slug}`, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "group overflow-hidden rounded-xl border border-border shadow-sm hover:shadow-lg transition-all duration-300 cursor-pointer bg-card", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "relative h-52 overflow-hidden", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-        import_image.default,
-        {
-          src: cat.featuredImage,
-          alt: cat.name,
-          fill: true,
-          sizes: "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw",
-          className: "object-cover group-hover:scale-105 transition-transform duration-300"
-        }
-      ) }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "p-4 text-center", children: [
-        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h3", { className: "font-semibold text-foreground text-base", children: cat.name }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { className: "text-sm text-muted-foreground mt-1", children: [
-          cat.count,
-          " ",
-          cat.count === 1 ? "article" : "articles"
-        ] })
-      ] })
-    ] }) }, cat.slug)) }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        className: "sm:grid-cols-4",
+        style: {
+          display: "grid",
+          gridTemplateColumns: "repeat(1, minmax(0, 1fr))",
+          gap: "1.5rem"
+        },
+        children: visible.map((cat) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_link.default, { href: `/articles/category/${cat.slug}`, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "group overflow-hidden rounded-xl border border-border shadow-sm hover:shadow-lg transition-all duration-300 cursor-pointer bg-card", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "overflow-hidden", style: { position: "relative", height: "13rem" }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            import_image.default,
+            {
+              src: cat.featuredImage,
+              alt: cat.name,
+              fill: true,
+              sizes: "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw",
+              className: "object-cover group-hover:scale-105 transition-transform duration-300"
+            }
+          ) }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "p-4 text-center", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h3", { className: "font-semibold text-foreground text-base", children: cat.name }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { className: "text-sm text-muted-foreground mt-1", children: [
+              cat.count,
+              " ",
+              cat.count === 1 ? "article" : "articles"
+            ] })
+          ] })
+        ] }) }, cat.slug))
+      }
+    ),
     hasMore && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "mt-10 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       "button",
       {
@@ -248,10 +258,15 @@ function ArticleSearchBar({
 // src/ArticlesHero.tsx
 var import_link2 = __toESM(require("next/link"), 1);
 var import_jsx_runtime4 = require("react/jsx-runtime");
-function ArticlesHero() {
+var DEFAULT_TITLE = "Vox Populus Insights";
+var DEFAULT_DESCRIPTION = "Expert analysis, campaign strategies, and voter engagement insights from the frontlines of democracy.";
+function ArticlesHero({
+  title = DEFAULT_TITLE,
+  description = DEFAULT_DESCRIPTION
+}) {
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("section", { className: "bg-linear-to-r from-gray-50 to-gray-100 py-16 md:py-24", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { className: "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "max-w-3xl mx-auto text-center", children: [
-    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("h1", { className: "text-4xl md:text-5xl font-bold text-foreground mb-6", children: "Vox Populus Insights" }),
-    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { className: "text-xl text-muted-foreground mb-8", children: "Expert analysis, campaign strategies, and voter engagement insights from the frontlines of democracy." }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("h1", { className: "text-4xl md:text-5xl font-bold text-foreground mb-6", children: title }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { className: "text-xl text-muted-foreground mb-8", children: description }),
     /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "flex flex-col sm:flex-row gap-4 justify-center", children: [
       /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
         import_link2.default,
@@ -475,8 +490,7 @@ function useArticles() {
       setLoading(true);
       const url = query ? `/api/articles?q=${encodeURIComponent(query)}` : "/api/articles";
       const response = yield fetch(url);
-      if (!response.ok)
-        throw new Error("Failed to fetch articles");
+      if (!response.ok) throw new Error("Failed to fetch articles");
       const data = yield response.json();
       setArticles(data.articles);
       if (!(query == null ? void 0 : query.trim())) {
@@ -512,8 +526,7 @@ function useArticles() {
   const handleSearch = (0, import_react3.useCallback)(
     (query) => {
       setSearchQuery(query);
-      if (debounceRef.current)
-        clearTimeout(debounceRef.current);
+      if (debounceRef.current) clearTimeout(debounceRef.current);
       if (query === "") {
         fetchArticles("");
       } else if (query.length >= 3) {
@@ -524,8 +537,7 @@ function useArticles() {
   );
   (0, import_react3.useEffect)(
     () => () => {
-      if (debounceRef.current)
-        clearTimeout(debounceRef.current);
+      if (debounceRef.current) clearTimeout(debounceRef.current);
     },
     []
   );
@@ -535,36 +547,24 @@ function useArticles() {
 // src/ArticlesPage.tsx
 var import_jsx_runtime9 = require("react/jsx-runtime");
 function buildThemeVars(theme) {
-  if (!theme)
-    return {};
+  if (!theme) return {};
   const vars = {};
-  if (theme.fontFamily)
-    vars["--articles-font-family"] = theme.fontFamily;
-  if (theme.headerColor)
-    vars["--articles-header-color"] = theme.headerColor;
-  if (theme.textColor)
-    vars["--articles-text-color"] = theme.textColor;
-  if (theme.backgroundColor)
-    vars["--articles-bg-color"] = theme.backgroundColor;
-  if (theme.linkColor)
-    vars["--articles-link-color"] = theme.linkColor;
-  if (theme.linkHoverColor)
-    vars["--articles-link-hover-color"] = theme.linkHoverColor;
-  if (theme.linkTextDecoration)
-    vars["--articles-link-decoration"] = theme.linkTextDecoration;
-  if (theme.headerFontWeight)
-    vars["--articles-header-font-weight"] = String(theme.headerFontWeight);
-  if (theme.headerFontSize)
-    vars["--articles-header-font-size"] = theme.headerFontSize;
-  if (theme.bodyFontSize)
-    vars["--articles-body-font-size"] = theme.bodyFontSize;
-  if (theme.lineHeight)
-    vars["--articles-line-height"] = theme.lineHeight;
-  if (theme.borderRadius)
-    vars["--articles-border-radius"] = theme.borderRadius;
+  if (theme.fontFamily) vars["--articles-font-family"] = theme.fontFamily;
+  if (theme.headerColor) vars["--articles-header-color"] = theme.headerColor;
+  if (theme.textColor) vars["--articles-text-color"] = theme.textColor;
+  if (theme.backgroundColor) vars["--articles-bg-color"] = theme.backgroundColor;
+  if (theme.linkColor) vars["--articles-link-color"] = theme.linkColor;
+  if (theme.linkHoverColor) vars["--articles-link-hover-color"] = theme.linkHoverColor;
+  if (theme.linkTextDecoration) vars["--articles-link-decoration"] = theme.linkTextDecoration;
+  if (theme.headerFontWeight) vars["--articles-header-font-weight"] = String(theme.headerFontWeight);
+  if (theme.headerFontSize) vars["--articles-header-font-size"] = theme.headerFontSize;
+  if (theme.bodyFontSize) vars["--articles-body-font-size"] = theme.bodyFontSize;
+  if (theme.lineHeight) vars["--articles-line-height"] = theme.lineHeight;
+  if (theme.borderRadius) vars["--articles-border-radius"] = theme.borderRadius;
   return vars;
 }
-function renderSection(section, ctx) {
+function renderSection(section, ctx, config) {
+  var _a, _b;
   const {
     articles,
     displayedArticles,
@@ -578,7 +578,14 @@ function renderSection(section, ctx) {
   } = ctx;
   switch (section) {
     case "hero":
-      return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(ArticlesHero, {}, "hero");
+      return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+        ArticlesHero,
+        {
+          title: (_a = config.hero) == null ? void 0 : _a.title,
+          description: (_b = config.hero) == null ? void 0 : _b.description
+        },
+        "hero"
+      );
     case "search":
       return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
         ArticleSearchBar,
@@ -633,6 +640,7 @@ function renderSection(section, ctx) {
         },
         "categories"
       );
+    // 'newsletter' is intentionally omitted — inject it via the layout prop in the consuming app
     default:
       return null;
   }
@@ -649,7 +657,7 @@ function ArticlesPage({ config }) {
   const displayedArticles = state.searchQuery ? state.articles : articlesWithoutFeatured;
   const ctx = __spreadProps(__spreadValues({}, state), { displayedArticles, pageSize, categoriesPageSize });
   return /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("div", { style: themeVars, children: [
-    layout.map((section) => renderSection(section, ctx)),
+    layout.map((section) => renderSection(section, ctx, config)),
     state.articles.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
       CollectionPageSchema,
       {
@@ -669,16 +677,13 @@ var import_jsx_runtime10 = require("react/jsx-runtime");
 function getCategoryDescription(config, slug, categoryName) {
   var _a;
   const raw = (_a = config.categoryDescriptions) == null ? void 0 : _a[slug];
-  if (!raw)
-    return { short: `Browse all articles in ${categoryName}.` };
-  if (typeof raw === "string")
-    return { short: raw };
+  if (!raw) return { short: `Browse all articles in ${categoryName}.` };
+  if (typeof raw === "string") return { short: raw };
   return raw;
 }
 function CategoryArticlesPage({ category, articles, config }) {
   var _a;
-  if (articles.length === 0)
-    return null;
+  if (articles.length === 0) return null;
   const categoryName = articles[0].category;
   const heroImage = articles[0].featuredImage;
   const description = getCategoryDescription(config, category, categoryName);
@@ -739,8 +744,7 @@ var import_jsx_runtime11 = require("react/jsx-runtime");
 var MAX_LENGTH = 2e3;
 var WARN_THRESHOLD = 1800;
 function submitLabel(submitting, parentId) {
-  if (submitting)
-    return "Posting\u2026";
+  if (submitting) return "Posting\u2026";
   return parentId ? "Reply" : "Post comment";
 }
 function CommentForm({ articleSlug, parentId, onSuccess, onCancel }) {
@@ -752,8 +756,7 @@ function CommentForm({ articleSlug, parentId, onSuccess, onCancel }) {
     return __async(this, null, function* () {
       var _a;
       e.preventDefault();
-      if (!body.trim() || submitting)
-        return;
+      if (!body.trim() || submitting) return;
       setSubmitting(true);
       setError(null);
       try {
@@ -824,19 +827,14 @@ var import_jsx_runtime12 = require("react/jsx-runtime");
 function relativeTime(iso) {
   const diff = Date.now() - new Date(iso).getTime();
   const minutes = Math.floor(diff / 6e4);
-  if (minutes < 1)
-    return "just now";
-  if (minutes < 60)
-    return `${minutes}m ago`;
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
   const hours = Math.floor(minutes / 60);
-  if (hours < 24)
-    return `${hours}h ago`;
+  if (hours < 24) return `${hours}h ago`;
   const days = Math.floor(hours / 24);
-  if (days < 30)
-    return `${days}d ago`;
+  if (days < 30) return `${days}d ago`;
   const months = Math.floor(days / 30);
-  if (months < 12)
-    return `${months}mo ago`;
+  if (months < 12) return `${months}mo ago`;
   return `${Math.floor(months / 12)}y ago`;
 }
 function CommentItem({
@@ -853,8 +851,7 @@ function CommentItem({
   const canDelete = !!currentUserId && currentUserId === comment.authorId && !comment.isDeleted;
   function handleDelete() {
     return __async(this, null, function* () {
-      if (deleting)
-        return;
+      if (deleting) return;
       setDeleting(true);
       try {
         yield fetch(`/api/articles/${articleSlug}/comments/${comment.id}`, { method: "DELETE" });
@@ -956,8 +953,7 @@ function CommentsSection({ articleSlug, config }) {
     setFetchError(null);
     try {
       const res = yield fetch(`/api/articles/${articleSlug}/comments`);
-      if (!res.ok)
-        throw new Error("Failed to load comments");
+      if (!res.ok) throw new Error("Failed to load comments");
       const data = yield res.json();
       setComments(data.comments);
     } catch (e) {
@@ -971,8 +967,7 @@ function CommentsSection({ articleSlug, config }) {
       fetchComments().catch(() => void 0);
     }
   }, [fetchComments, enabled]);
-  if (!enabled)
-    return null;
+  if (!enabled) return null;
   const count = comments.length;
   const label = count === 1 ? "1 comment" : `${count} comments`;
   return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("section", { "aria-label": "Comments", className: "mt-12 pt-8 border-t border-border space-y-6", children: [