@asteroidcms/core-utils 0.1.8 → 0.2.0

package/README.md

@@ -30,6 +30,17 @@ npm install @apollo/client-integration-nextjs # for nextjs (optional)
 
 ---
 
+## Entry points
+
+| Entry point                          | What it exports                                                                                                                                                                                                                                                                 |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@asteroidcms/core-utils`            | Core utilities: `fetchCmsContent`, `cmsMutate`, `buildCmsQuery`, `buildCmsMutation`, `cmsImage`, `parseRichText`, `getContentReadTime`, `extractHeadingsFromHtml`, `createApolloClient`, `AsteroidCMSProvider`.                                                                  |
+| `@asteroidcms/core-utils/client`     | Client components and hooks (browser / React): `AsteroidCMSProvider`, `useCmsContent`, `useCmsMutate`, `useCmsImage`, `RichTextContent`, `extractHeadingsFromElement`.                                                                                                          |
+| `@asteroidcms/core-utils/next`       | Next.js metadata helpers and SEO head component. Optional peer dep on `next`.                                                                                                                                                                                                   |
+| `@asteroidcms/core-utils/server`     | Server components: `AsteroidArticlesListingServer`, `AsteroidArticlePageServer`, `defineArticleSource`, `createCmsServerClient`, `generateListingMetadata`, `generateArticleMetadata`. Also exports `fetchArticles`, `fetchArticle`, `fetchRelatedArticles`, `buildSearchConditions`. Server-only -- the CMS API key never reaches the browser. |
+
+---
+
 ## Quick start
 
 Wrap your app once:
@@ -364,6 +375,8 @@ import { cmsImage } from "@asteroidcms/core-utils";
 cmsImage(id, { cmsUrl: "https://cms-api.example.com" });
 ```
 
+**Note:** Article render-prop callbacks (`renderPostCard` for listing, `renderRelatedPosts` for related posts, `renderContent`/`renderHeader` for article body) in both `AsteroidArticlesListing` (client) and `AsteroidArticlesListingServer` / `AsteroidArticlePageServer` (server) receive an injected `cmsImage(idOrUrl)` resolver. Prefer it over calling `useCmsImage()` directly so the same render function works in client and server components. A server equivalent for article listing and article page exists under `@asteroidcms/core-utils/server`.
+
 ---
 
 ## `getContentReadTime`
@@ -475,6 +488,160 @@ const client = createApolloClient({
 
 ---
 
+## `@asteroidcms/core-utils/server`
+
+Server-only entry. Guarded by `server-only` so it fails loudly if imported in a client module.
+
+See [docs/web-sdk-react/13-server-article-components.md](./docs/web-sdk-react/13-server-article-components.md) for the full guide.
+
+### `createCmsServerClient` + `defineArticleSource`
+
+Define a source once in a server-only module and import it from any route that needs it.
+
+```ts
+// cms/articleSource.ts
+import { createCmsServerClient, defineArticleSource } from "@asteroidcms/core-utils/server";
+import type { AsteroidSeoConfig } from "@asteroidcms/core-utils";
+
+const cmsClient = createCmsServerClient({
+  cmsUrl: process.env.CMS_API_BASE_URL!,
+  apiKey: process.env.CMS_API_KEY!, // server-only, NOT NEXT_PUBLIC
+  revalidate: 300,
+});
+
+const articleSeo: AsteroidSeoConfig = {
+  siteName: "Acme",
+  baseUrl: "https://acme.example",
+  cmsUrl: process.env.CMS_API_BASE_URL!,
+  defaultDescription: "News and updates.",
+  articlePath: "/news",
+  contentLabel: "News",
+};
+
+export const articleSource = defineArticleSource({
+  client: cmsClient,
+  schemaSlug: "news",
+  listSelect: ["slug", "title", "description", "featured_image", "published_date",
+    { field: "category", single: true, select: ["slug", "name"] }],
+  detailSelect: ["slug", "title", "description", "content", "tags", "featured_image", "published_date",
+    { field: "category", single: true, select: ["slug", "name"] },
+    { field: "author", single: true, select: ["name"] }],
+  seo: articleSeo,
+  relatedLimit: 3,
+});
+```
+
+`createCmsServerClient` memoizes per request via React `cache` when available (React Server Components / React 19 / Next.js bundled React). On React 18 stable without `cache` it degrades to no per-request dedup but remains correct.
+
+`defineArticleSource` required fields: `client`, `schemaSlug`, `listSelect`, `detailSelect`, `seo`. Optional: `searchFields`, `articleType`, `status`, `relatedLimit`, `groupPostsByCategory`.
+
+### `AsteroidArticlesListingServer`
+
+Read `searchParams` in the page and pass the query as `searchQuery`.
+
+```tsx
+// app/news/page.tsx
+import { AsteroidArticlesListingServer, generateListingMetadata } from "@asteroidcms/core-utils/server";
+import { articleSource } from "@/cms/articleSource";
+
+export const generateMetadata = () => generateListingMetadata(articleSource);
+
+export default async function NewsPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ q?: string }>;
+}) {
+  const { q } = await searchParams;
+  return (
+    <AsteroidArticlesListingServer
+      source={articleSource}
+      searchQuery={q}
+      renderPostCard={({ post, cmsImage }) => (
+        <a href={`/news/${post.slug}`}>
+          <h2>{post.title}</h2>
+        </a>
+      )}
+    />
+  );
+}
+```
+
+Required prop: `renderPostCard` receives `{ post, cmsImage }`. Optional: `renderFeaturedCard`, `renderEmpty`, `renderSearch`, `categorySlug`, `searchParamKey`, `searchBoxProps`, and more.
+
+### `AsteroidArticlePageServer`
+
+```tsx
+// app/news/[slug]/page.tsx
+import { AsteroidArticlePageServer, generateArticleMetadata } from "@asteroidcms/core-utils/server";
+import { articleSource } from "@/cms/articleSource";
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  return generateArticleMetadata(articleSource, params);
+}
+
+export default async function ArticlePage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  return (
+    <AsteroidArticlePageServer
+      source={articleSource}
+      slug={slug}
+      renderHeader={({ post }) => <h1>{post.title}</h1>}
+      renderContent={({ post }) => (
+        <div dangerouslySetInnerHTML={{ __html: post.content ?? "" }} />
+      )}
+      renderRelatedPosts={({ relatedPosts, cmsImage }) => (
+        <ul>
+          {relatedPosts.map((related) => (
+            <li key={related.slug}>
+              <a href={`/news/${related.slug}`}>{related.title}</a>
+            </li>
+          ))}
+        </ul>
+      )}
+      renderError={({ reason }) =>
+        reason === "not-found" ? <p>Not found.</p> : <p>Error loading post.</p>
+      }
+    />
+  );
+}
+```
+
+Render-prop slots: `renderHeader`, `renderContent`, `renderRelatedPosts` (receives `{ post, relatedPosts, cmsImage }`), `renderError`. Every render prop receives an injected `cmsImage(idOrUrl)` resolver -- do not call `useCmsImage()` inside render props.
+
+### Metadata helpers
+
+```ts
+import { generateListingMetadata, generateArticleMetadata } from "@asteroidcms/core-utils/server";
+
+// Listing page -- positional args: source first
+export const generateMetadata = () => generateListingMetadata(articleSource);
+
+// Category page
+export async function generateMetadata({ params }) {
+  const { category } = await params;
+  return generateListingMetadata(articleSource, { categorySlug: category });
+}
+
+// Article page -- positional args: source first, then params or slug
+export async function generateMetadata({ params }) {
+  return generateArticleMetadata(articleSource, params);
+}
+```
+
+### Low-level fetch helpers
+
+`fetchArticles`, `fetchArticle`, `fetchRelatedArticles`, and `buildSearchConditions` are also exported for custom fetch logic outside the ready-made server components.
+
+---
+
 ## Development
 
 ```bash

package/dist/client.cjs

@@ -9,6 +9,7 @@ var error = require('@apollo/client/link/error');
 var jsxRuntime = require('react/jsx-runtime');
 var reactDom = require('react-dom');
 var hljs = require('highlight.js/lib/common');
+var navigation = require('next/navigation');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -1923,93 +1924,88 @@ function buildCollectionJsonLd(props) {
     inLanguage: "en-US"
   };
 }
+function renderArticleBody(args) {
+  const { post, cmsImage: cmsImage2, relatedPosts, seoNode, jsonLdNode, renderProps: r } = args;
+  const slot = { post, cmsImage: cmsImage2 };
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    seoNode,
+    jsonLdNode,
+    r.backLink,
+    r.renderPreArticle?.(slot),
+    r.renderHeader?.(slot),
+    r.renderMeta?.(slot),
+    r.renderDescription?.(slot),
+    r.renderFeaturedImage?.(slot),
+    r.renderToc?.(slot),
+    r.renderContent?.(slot),
+    r.renderMidArticle?.(slot),
+    r.renderTags?.(slot),
+    r.renderAuthorDetails?.(slot),
+    r.renderRelatedPosts?.({ post, relatedPosts, cmsImage: cmsImage2 }),
+    r.renderCTA?.(slot),
+    r.renderPostArticle?.(slot)
+  ] });
+}
 function AsteroidArticlePage(props) {
   const {
     slug,
     useArticle,
     seo,
     articleType,
-    backLink,
+    noindex,
+    relatedPosts = [],
     renderRoot,
     renderSkeleton,
     renderError,
-    renderHeader,
-    renderMeta,
-    renderDescription,
-    renderFeaturedImage,
-    renderToc,
-    renderContent,
-    renderPreArticle,
-    renderMidArticle,
-    renderPostArticle,
-    renderTags,
-    renderAuthorDetails,
-    renderRelatedPosts,
-    renderCTA,
     renderJsonLd,
-    noindex,
-    children
+    children,
+    ...bodyRenderProps
   } = props;
   const { data: article, loading, error } = useArticle(slug);
   const cmsConfig = react.useContext(AsteroidCMSContext);
+  const cmsImage2 = useCmsImage();
   const seoConfig = seo && !seo.cmsUrl && cmsConfig?.cmsUrl ? { ...seo, cmsUrl: cmsConfig.cmsUrl } : seo;
-  if (children) {
-    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children({ data: article, loading, error }) });
-  }
+  if (children) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children({ data: article, loading, error }) });
   if (loading) {
     const body2 = renderSkeleton?.() ?? null;
-    return renderRoot ? renderRoot({ children: body2 }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body2 });
+    return renderRoot ? /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderRoot({ children: body2 }) }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body2 });
   }
   if (!article || error) {
     const body2 = renderError?.({ error, reason: error ? "error" : "not-found" }) ?? null;
-    return renderRoot ? renderRoot({ children: body2 }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body2 });
+    return renderRoot ? /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderRoot({ children: body2 }) }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body2 });
   }
-  const seoValues = seoConfig && article ? buildArticleSeoValues(article, seoConfig, slug, { noindex }) : null;
-  const body = /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-    seoValues ? /* @__PURE__ */ jsxRuntime.jsx(Seo, { ...seoValuesToClientProps(seoValues) }) : null,
-    seoConfig && article ? renderJsonLd?.({ post: article }) ?? /* @__PURE__ */ jsxRuntime.jsx(
-      JsonLd,
-      {
-        data: buildArticleJsonLd({
-          title: article.title,
-          description: article.description || seoConfig.defaultDescription || "",
-          url: `${(seoConfig.baseUrl || "").replace(/\/$/, "")}${seoConfig.articlePath ?? "/blog"}/${slug}`,
-          siteName: seoConfig.siteName,
-          siteUrl: (seoConfig.baseUrl || "").replace(/\/$/, ""),
-          articleType,
-          image: seoValues?.image,
-          authorName: article.author?.name,
-          publishedTime: article.published_date || void 0,
-          tags: article.tags?.split(",").map((t) => t.trim()).filter(Boolean),
-          category: article.category?.name
-        })
-      }
-    ) : null,
-    backLink,
-    renderPreArticle?.({ post: article }),
-    renderHeader?.({ post: article }),
-    renderMeta?.({ post: article }),
-    renderDescription?.({ post: article }),
-    renderFeaturedImage?.({ post: article }),
-    renderToc?.({ post: article }),
-    renderContent?.({ post: article }),
-    renderMidArticle?.({ post: article }),
-    renderTags?.({ post: article }),
-    renderAuthorDetails?.({ post: article }),
-    renderRelatedPosts?.({ post: article }),
-    renderCTA?.({ post: article }),
-    renderPostArticle?.({ post: article })
-  ] });
-  return renderRoot ? renderRoot({ children: body }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body });
-}
-function useDebouncedValue(value, delay) {
-  const [debouncedValue, setDebouncedValue] = react.useState(value);
-  react.useEffect(() => {
-    const timer = setTimeout(() => setDebouncedValue(value), delay);
-    return () => clearTimeout(timer);
-  }, [value, delay]);
-  return debouncedValue;
+  const seoValues = seoConfig ? buildArticleSeoValues(article, seoConfig, slug, { noindex }) : null;
+  const seoNode = seoValues ? /* @__PURE__ */ jsxRuntime.jsx(Seo, { ...seoValuesToClientProps(seoValues) }) : null;
+  const jsonLdNode = seoConfig ? renderJsonLd?.({ post: article }) ?? /* @__PURE__ */ jsxRuntime.jsx(
+    JsonLd,
+    {
+      data: buildArticleJsonLd({
+        title: article.title,
+        description: article.description || seoConfig.defaultDescription || "",
+        url: `${(seoConfig.baseUrl || "").replace(/\/$/, "")}${seoConfig.articlePath ?? "/blog"}/${slug}`,
+        siteName: seoConfig.siteName,
+        siteUrl: (seoConfig.baseUrl || "").replace(/\/$/, ""),
+        articleType,
+        image: seoValues?.image,
+        authorName: article.author?.name,
+        publishedTime: article.published_date || void 0,
+        tags: article.tags?.split(",").map((t) => t.trim()).filter(Boolean),
+        category: article.category?.name
+      })
+    }
+  ) : null;
+  const body = renderArticleBody({
+    post: article,
+    cmsImage: cmsImage2,
+    relatedPosts,
+    seoNode,
+    jsonLdNode,
+    renderProps: bodyRenderProps
+  });
+  return renderRoot ? /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderRoot({ children: body }) }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body });
 }
+
+// src/components/articles/articles.state.ts
 function defaultGetCategoryName(post) {
   return post.category?.name?.trim() || void 0;
 }
@@ -2027,10 +2023,7 @@ function defaultGroupPostsByCategory(posts) {
   }
   return Array.from(groups.values());
 }
-function applyPostFilters(posts, {
-  categorySlug,
-  articleSlug
-}) {
+function applyPostFilters(posts, { categorySlug, articleSlug }) {
   let filtered = posts;
   if (categorySlug) {
     filtered = filtered.filter((post) => post.category?.slug === categorySlug);
@@ -2045,65 +2038,42 @@ function splitFeaturedAndRest(posts) {
   const rest = featured ? posts.filter((post) => post.slug !== featured.slug) : [...posts];
   return { featured, rest };
 }
-function useAsteroidArticlesState({
-  usePosts,
-  categorySlug,
-  articleSlug,
-  searchDebounceMs = 800,
-  groupPostsByCategory = defaultGroupPostsByCategory
-}) {
-  const [searchQuery, setSearchQuery] = react.useState("");
-  const debouncedSearchQuery = useDebouncedValue(searchQuery, searchDebounceMs);
-  const { posts: rawPosts, loading, error } = usePosts(debouncedSearchQuery);
-  const posts = react.useMemo(
-    () => applyPostFilters(rawPosts, { categorySlug, articleSlug }),
-    [rawPosts, categorySlug, articleSlug]
-  );
-  const { featured, rest } = react.useMemo(
-    () => splitFeaturedAndRest(posts),
-    [posts]
-  );
-  const isSearching = debouncedSearchQuery.trim().length > 0;
-  const categoryGroups = react.useMemo(() => {
-    if (isSearching) {
-      if (posts.length === 0) return [];
-      return [
-        {
-          categoryName: `Search results for "${debouncedSearchQuery.trim()}"`,
-          categorySlug: "search-results",
-          posts
-        }
-      ];
+function buildArticlesViewState(rawPosts, options) {
+  const {
+    categorySlug,
+    articleSlug,
+    searchQuery = "",
+    groupPostsByCategory = defaultGroupPostsByCategory
+  } = options;
+  const posts = applyPostFilters(rawPosts, { categorySlug, articleSlug });
+  const { featured, rest } = splitFeaturedAndRest(posts);
+  const trimmedQuery = searchQuery.trim();
+  const isSearching = trimmedQuery.length > 0;
+  const categoryGroups = isSearching ? posts.length === 0 ? [] : [
+    {
+      categoryName: `Search results for "${trimmedQuery}"`,
+      categorySlug: "search-results",
+      posts
     }
-    return groupPostsByCategory(rest);
-  }, [isSearching, posts, debouncedSearchQuery, rest, groupPostsByCategory]);
-  const hasError = Boolean(error);
-  const isEmpty = !featured && rest.length === 0;
+  ] : groupPostsByCategory(rest);
   return {
     posts,
     featured,
     rest,
     categoryGroups,
-    loading,
-    error,
-    hasError,
-    isEmpty,
+    isEmpty: !featured && rest.length === 0,
     isSearching,
-    searchQuery,
-    debouncedSearchQuery,
-    setSearchQuery
+    searchQuery: trimmedQuery
   };
 }
-function AsteroidArticlesListing(props) {
+function renderArticlesListingBody(args) {
+  const { state, loading, hasError, error, cmsImage: cmsImage2, searchNode, seoNode, jsonLdNode, renderProps } = args;
   const {
     eyebrow,
     title,
     description,
-    seo,
-    categorySlug,
     renderRoot,
     renderHeader,
-    renderSearch,
     renderFeaturedCard,
     renderPostCard,
     renderCategoryHeading,
@@ -2111,73 +2081,27 @@ function AsteroidArticlesListing(props) {
     renderCategoryGroup,
     renderSkeleton,
     renderEmpty,
-    renderContent,
-    renderJsonLd,
-    noindex,
-    children
-  } = props;
-  const state = useAsteroidArticlesState(props);
-  const categoryName = categorySlug ? state.posts[0]?.category?.name?.trim() : void 0;
-  if (children) {
-    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children(state) });
-  }
-  const seoNode = seo ? /* @__PURE__ */ jsxRuntime.jsx(
-    Seo,
-    {
-      ...seoValuesToClientProps(
-        buildArticleListingSeoValues(seo, {
-          categoryName,
-          categorySlug,
-          noindex
-        })
-      )
-    }
-  ) : null;
-  const jsonLdNode = seo ? renderJsonLd?.(state) ?? /* @__PURE__ */ jsxRuntime.jsx(
-    JsonLd,
-    {
-      data: buildCollectionJsonLd({
-        name: categoryName || `${seo.siteName} ${seo.contentLabel ?? "Articles"}`,
-        description: seo.defaultDescription || "",
-        url: `${(seo.baseUrl || "").replace(/\/$/, "")}${seo.articlePath ?? "/blog"}${categorySlug ? `/category/${categorySlug}` : ""}`,
-        siteUrl: (seo.baseUrl || "").replace(/\/$/, "")
-      })
-    }
-  ) : null;
-  const handleSearchSubmit = (event) => {
-    event.preventDefault();
-  };
-  const searchNode = renderSearch ? renderSearch({
-    value: state.searchQuery,
-    onChange: state.setSearchQuery,
-    onSubmit: handleSearchSubmit
-  }) : null;
+    renderContent
+  } = renderProps;
   const headerNode = renderHeader ? renderHeader({ eyebrow, title, description, search: searchNode }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
     eyebrow,
     title,
     description,
     searchNode
   ] });
-  const featuredNode = state.featured && !state.isSearching && renderFeaturedCard ? renderFeaturedCard({ post: state.featured }) : null;
-  const noSearchResultsNode = state.isSearching && !state.loading && state.posts.length === 0 ? renderEmpty?.({
-    reason: "no-results",
-    searchQuery: state.debouncedSearchQuery.trim()
-  }) ?? null : null;
+  const featuredNode = state.featured && !state.isSearching && renderFeaturedCard ? renderFeaturedCard({ post: state.featured, cmsImage: cmsImage2 }) : null;
+  const noSearchResultsNode = state.isSearching && !loading && state.posts.length === 0 ? renderEmpty?.({ reason: "no-results", searchQuery: state.searchQuery }) ?? null : null;
   const groupsNode = noSearchResultsNode ? null : state.categoryGroups.map((group) => {
-    const postCards = group.posts.map((post, index) => /* @__PURE__ */ jsxRuntime.jsx(react.Fragment, { children: renderPostCard({ post, index, group }) }, post.slug ?? index));
+    const postCards = group.posts.map((post, index) => /* @__PURE__ */ jsxRuntime.jsx(react.Fragment, { children: renderPostCard({ post, index, group, cmsImage: cmsImage2 }) }, post.slug ?? index));
     const gridNode = renderPostGrid ? renderPostGrid({ posts: group.posts, group, children: postCards }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: postCards });
     const headingNode = renderCategoryHeading ? renderCategoryHeading({ group }) : group.categoryName;
     const defaultContent = /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
       headingNode,
       gridNode
     ] });
-    return renderCategoryGroup ? renderCategoryGroup({ group, defaultContent }) : defaultContent;
+    return /* @__PURE__ */ jsxRuntime.jsx(react.Fragment, { children: renderCategoryGroup ? renderCategoryGroup({ group, defaultContent }) : defaultContent }, group.categorySlug);
   });
-  const contentNode = !state.loading && !state.hasError && (state.featured || state.rest.length > 0) ? renderContent ? renderContent({
-    featured: featuredNode,
-    groups: groupsNode,
-    noSearchResults: noSearchResultsNode
-  }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+  const contentNode = !loading && !hasError && (state.featured || state.rest.length > 0) ? renderContent ? renderContent({ featured: featuredNode, groups: groupsNode, noSearchResults: noSearchResultsNode }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
     featuredNode,
     noSearchResultsNode,
     groupsNode
@@ -2186,17 +2110,129 @@ function AsteroidArticlesListing(props) {
     seoNode,
     jsonLdNode,
     headerNode,
-    state.loading ? renderSkeleton?.() : null,
-    !state.loading && (state.hasError || state.isEmpty) ? renderEmpty?.({
-      reason: state.hasError ? "error" : "no-posts",
-      searchQuery: state.debouncedSearchQuery.trim(),
-      error: state.error
+    loading ? renderSkeleton?.() : null,
+    !loading && (hasError || state.isEmpty) ? renderEmpty?.({
+      reason: hasError ? "error" : state.isSearching ? "no-results" : "no-posts",
+      searchQuery: state.searchQuery,
+      error
     }) : null,
     contentNode
   ] });
   return renderRoot ? renderRoot({ children: body }) : /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: body });
 }
+function useDebouncedValue(value, delay) {
+  const [debounced, setDebounced] = react.useState(value);
+  react.useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+function useAsteroidArticlesState(props) {
+  const { usePosts, categorySlug, articleSlug, searchDebounceMs = 800, groupPostsByCategory } = props;
+  const [inputValue, setSearchQuery] = react.useState("");
+  const debouncedSearchQuery = useDebouncedValue(inputValue, searchDebounceMs);
+  const { posts: rawPosts, loading, error } = usePosts(debouncedSearchQuery);
+  const view = react.useMemo(
+    () => buildArticlesViewState(rawPosts, {
+      categorySlug,
+      articleSlug,
+      searchQuery: debouncedSearchQuery,
+      groupPostsByCategory
+    }),
+    [rawPosts, categorySlug, articleSlug, debouncedSearchQuery, groupPostsByCategory]
+  );
+  return {
+    ...view,
+    loading,
+    error,
+    hasError: Boolean(error),
+    inputValue,
+    setSearchQuery
+  };
+}
+function AsteroidArticlesListing(props) {
+  const { seo, categorySlug, noindex, renderSearch, renderJsonLd, children, ...renderProps } = props;
+  const state = useAsteroidArticlesState(props);
+  const cmsImage2 = useCmsImage();
+  if (children) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children(state) });
+  const categoryName = categorySlug ? state.posts[0]?.category?.name?.trim() : void 0;
+  const seoNode = seo ? /* @__PURE__ */ jsxRuntime.jsx(
+    Seo,
+    {
+      ...seoValuesToClientProps(
+        buildArticleListingSeoValues(seo, { categoryName, categorySlug, noindex })
+      )
+    }
+  ) : null;
+  const jsonLdNode = seo ? renderJsonLd?.(state) ?? /* @__PURE__ */ jsxRuntime.jsx(
+    JsonLd,
+    {
+      data: buildCollectionJsonLd({
+        name: categoryName || `${seo.siteName} ${seo.contentLabel ?? "Articles"}`,
+        description: seo.defaultDescription || "",
+        url: `${(seo.baseUrl || "").replace(/\/$/, "")}${seo.articlePath ?? "/blog"}${categorySlug ? `/category/${categorySlug}` : ""}`,
+        siteUrl: (seo.baseUrl || "").replace(/\/$/, "")
+      })
+    }
+  ) : null;
+  const searchNode = renderSearch ? renderSearch({
+    value: state.inputValue,
+    onChange: state.setSearchQuery,
+    onSubmit: (event) => event.preventDefault()
+  }) : null;
+  return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderArticlesListingBody({
+    state,
+    loading: state.loading,
+    hasError: state.hasError,
+    error: state.error,
+    cmsImage: cmsImage2,
+    searchNode,
+    seoNode,
+    jsonLdNode,
+    renderProps
+  }) });
+}
+function ArticleSearchBox({
+  paramKey = "q",
+  placeholder = "Search articles...",
+  debounceMs = 500,
+  className,
+  render
+}) {
+  const router = navigation.useRouter();
+  const pathname = navigation.usePathname();
+  const searchParams = navigation.useSearchParams();
+  const initial = searchParams.get(paramKey) ?? "";
+  const [value, setValue] = react.useState(initial);
+  const searchParamsRef = react.useRef(searchParams);
+  searchParamsRef.current = searchParams;
+  react.useEffect(() => {
+    const timer = setTimeout(() => {
+      const params = new URLSearchParams(Array.from(searchParamsRef.current.entries()));
+      const trimmed = value.trim();
+      if (trimmed) params.set(paramKey, trimmed);
+      else params.delete(paramKey);
+      const query = params.toString();
+      router.replace(query ? `${pathname}?${query}` : pathname, { scroll: false });
+    }, debounceMs);
+    return () => clearTimeout(timer);
+  }, [value, debounceMs, paramKey, pathname]);
+  const onSubmit = (event) => event.preventDefault();
+  if (render) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: render({ value, onChange: setValue, onSubmit }) });
+  return /* @__PURE__ */ jsxRuntime.jsx("form", { onSubmit, className, children: /* @__PURE__ */ jsxRuntime.jsx(
+    "input",
+    {
+      type: "search",
+      value,
+      placeholder,
+      "aria-label": placeholder,
+      onChange: (event) => setValue(event.target.value)
+    }
+  ) });
+}
 
+exports.ArticleSearchBox = ArticleSearchBox;
 exports.AsteroidArticlePage = AsteroidArticlePage;
 exports.AsteroidArticlesListing = AsteroidArticlesListing;
 exports.AsteroidCMSProvider = AsteroidCMSProvider;