@asteroidcms/core-utils 0.1.8 → 0.2.1

package/dist/client.d.ts

@@ -383,117 +383,8 @@ declare function Seo({ title, description, url, siteName, keywords, twitter, ima
 /** schema.org Article subtypes; pick per content kind. */
 type ArticleJsonLdType = "Article" | "BlogPosting" | "NewsArticle" | "TechArticle" | (string & {});
 
-interface AsteroidArticlePagePost {
-    slug: string;
-    title: string;
-    description?: string;
-    content?: string;
-    featured_image?: string;
-    tags?: string;
-    published_date?: string | null;
-    category?: {
-        slug: string;
-        name: string;
-    };
-    author?: {
-        name: string;
-        bio?: string;
-    };
-}
-type AsteroidArticlePageUseArticleResult<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> = {
-    data?: TPost | null;
-    loading: boolean;
-    error?: unknown;
-};
-type AsteroidArticlePageUseArticle<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> = (slug: string) => AsteroidArticlePageUseArticleResult<TPost>;
-interface AsteroidArticlePageProps<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> {
-    /** Article post slug to fetch. */
-    slug: string;
-    /** Inject the app-specific CMS fetching hook. */
-    useArticle: AsteroidArticlePageUseArticle<TPost>;
-    /** Site SEO config - enables client-side meta tags in React and Next.js apps. */
-    seo?: AsteroidSeoConfig;
-    /** schema.org Article subtype for the built-in JSON-LD. Default: "Article". */
-    articleType?: ArticleJsonLdType;
-    /** Mark this page as `noindex` for search engines. */
-    noindex?: boolean;
-    /** "Back to article" link. */
-    backLink?: ReactNode;
-    /** Wrap the entire component output. */
-    renderRoot?: (params: {
-        children: ReactNode;
-    }) => ReactNode;
-    /** Loading skeleton placeholder. */
-    renderSkeleton?: () => ReactNode;
-    /** Error or not-found state. */
-    renderError?: (params: {
-        error?: unknown;
-        reason: "error" | "not-found";
-    }) => ReactNode;
-    /** Article post title / heading area. */
-    renderHeader?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Article post metadata line (date, author, reading time, category chip). */
-    renderMeta?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Article post description paragraph. */
-    renderDescription?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Featured / hero image. */
-    renderFeaturedImage?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Table of contents section. */
-    renderToc?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Main rich-text content body. */
-    renderContent?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Top advertisement slot. */
-    renderPreArticle?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Middle advertisement slot. */
-    renderMidArticle?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Bottom advertisement slot. */
-    renderPostArticle?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Tags section. */
-    renderTags?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Author details section. */
-    renderAuthorDetails?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Related / similar posts section. */
-    renderRelatedPosts?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Call-to-action section. */
-    renderCTA?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /** Override the built-in Article JSON-LD structured data. */
-    renderJsonLd?: (params: {
-        post: TPost;
-    }) => ReactNode;
-    /**
-     * Escape hatch - receive the full result and render everything yourself.
-     * When provided, structural render props above are ignored.
-     */
-    children?: (state: AsteroidArticlePageUseArticleResult<TPost>) => ReactNode;
-}
-declare function AsteroidArticlePage<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost>(props: AsteroidArticlePageProps<TPost>): string | number | boolean | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
-
+/** Resolves a CMS asset id (or passthrough URL) to an absolute media URL. */
+type ArticleImageResolver = (idOrUrl?: string) => string;
 /** Minimal article post shape shared across Asteroid CMS apps. */
 interface AsteroidArticlePost {
     slug: string;
@@ -513,18 +404,24 @@ interface AsteroidArticleCategoryGroup<TPost extends AsteroidArticlePost = Aster
     categorySlug: string;
     posts: TPost[];
 }
-interface AsteroidArticlesUsePostsResult<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+/** Runtime-agnostic computed state shared by client + server listing. */
+interface ArticlesViewState<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
     posts: TPost[];
-    featured?: TPost | null;
+    featured: TPost | null;
     rest: TPost[];
-    loading: boolean;
-    error?: unknown;
+    categoryGroups: AsteroidArticleCategoryGroup<TPost>[];
+    isEmpty: boolean;
+    isSearching: boolean;
+    /** The effective (already-debounced, for client) search query. */
+    searchQuery: string;
 }
-type AsteroidArticlesUsePosts<TPost extends AsteroidArticlePost = AsteroidArticlePost> = (searchQuery: string) => AsteroidArticlesUsePostsResult<TPost>;
+type AsteroidArticlesEmptyReason = "error" | "no-posts" | "no-results";
 interface AsteroidArticlesSearchParams {
     value: string;
     onChange: (value: string) => void;
-    onSubmit: (event: React.FormEvent) => void;
+    onSubmit: (event: {
+        preventDefault: () => void;
+    }) => void;
 }
 interface AsteroidArticlesHeaderParams {
     eyebrow: ReactNode;
@@ -534,16 +431,17 @@ interface AsteroidArticlesHeaderParams {
 }
 interface AsteroidArticlesFeaturedCardParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
     post: TPost;
+    cmsImage: ArticleImageResolver;
 }
 interface AsteroidArticlesPostCardParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
     post: TPost;
     index: number;
     group: AsteroidArticleCategoryGroup<TPost>;
+    cmsImage: ArticleImageResolver;
 }
 interface AsteroidArticlesPostGridParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
     posts: TPost[];
     group: AsteroidArticleCategoryGroup<TPost>;
-    /** Pre-built post cards - render as-is or wrap. */
     children: ReactNode;
 }
 interface AsteroidArticlesCategoryHeadingParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
@@ -551,10 +449,8 @@ interface AsteroidArticlesCategoryHeadingParams<TPost extends AsteroidArticlePos
 }
 interface AsteroidArticlesCategoryGroupParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
     group: AsteroidArticleCategoryGroup<TPost>;
-    /** Default heading + grid - use it, wrap it, or replace entirely. */
     defaultContent: ReactNode;
 }
-type AsteroidArticlesEmptyReason = "error" | "no-posts" | "no-results";
 interface AsteroidArticlesEmptyParams {
     reason: AsteroidArticlesEmptyReason;
     searchQuery?: string;
@@ -565,77 +461,145 @@ interface AsteroidArticlesContentParams {
     groups: ReactNode;
     noSearchResults: ReactNode;
 }
-interface AsteroidArticlesState<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
-    posts: TPost[];
-    featured: TPost | null | undefined;
-    rest: TPost[];
-    categoryGroups: AsteroidArticleCategoryGroup<TPost>[];
-    loading: boolean;
-    error: unknown;
-    hasError: boolean;
-    isEmpty: boolean;
-    isSearching: boolean;
-    searchQuery: string;
-    debouncedSearchQuery: string;
-    setSearchQuery: (value: string) => void;
+
+interface AsteroidArticlePagePost {
+    slug: string;
+    title: string;
+    description?: string;
+    content?: string;
+    featured_image?: string;
+    tags?: string;
+    published_date?: string | null;
+    category?: {
+        slug: string;
+        name: string;
+    };
+    author?: {
+        name: string;
+        bio?: string;
+    };
 }
-interface AsteroidArticlesProps<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
-    /** Inject app-specific CMS fetching. Receives the debounced search query. */
-    usePosts: AsteroidArticlesUsePosts<TPost>;
-    /** Limit listing to a single category slug. */
-    categorySlug?: string;
-    /** Limit listing to a single post slug. */
-    articleSlug?: string;
-    /** Debounce delay for search in ms. Default: 800 */
-    searchDebounceMs?: number;
-    /** Site SEO config - enables client-side meta tags in React and Next.js apps. */
+type Slot<TPost> = (params: {
+    post: TPost;
+    cmsImage: ArticleImageResolver;
+}) => ReactNode;
+interface ArticleBodyRenderProps<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> {
+    backLink?: ReactNode;
+    renderHeader?: Slot<TPost>;
+    renderMeta?: Slot<TPost>;
+    renderDescription?: Slot<TPost>;
+    renderFeaturedImage?: Slot<TPost>;
+    renderToc?: Slot<TPost>;
+    renderContent?: Slot<TPost>;
+    renderPreArticle?: Slot<TPost>;
+    renderMidArticle?: Slot<TPost>;
+    renderPostArticle?: Slot<TPost>;
+    renderTags?: Slot<TPost>;
+    renderAuthorDetails?: Slot<TPost>;
+    renderRelatedPosts?: (params: {
+        post: TPost;
+        relatedPosts: TPost[];
+        cmsImage: ArticleImageResolver;
+    }) => ReactNode;
+    renderCTA?: Slot<TPost>;
+}
+
+type AsteroidArticlePageUseArticleResult<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> = {
+    data?: TPost | null;
+    loading: boolean;
+    error?: unknown;
+};
+type AsteroidArticlePageUseArticle<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> = (slug: string) => AsteroidArticlePageUseArticleResult<TPost>;
+interface AsteroidArticlePageProps<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> extends ArticleBodyRenderProps<TPost> {
+    slug: string;
+    useArticle: AsteroidArticlePageUseArticle<TPost>;
     seo?: AsteroidSeoConfig;
-    /** Mark this page as `noindex` for search engines. */
+    articleType?: ArticleJsonLdType;
     noindex?: boolean;
+    relatedPosts?: TPost[];
+    renderRoot?: (params: {
+        children: ReactNode;
+    }) => ReactNode;
+    renderSkeleton?: () => ReactNode;
+    renderError?: (params: {
+        error?: unknown;
+        reason: "error" | "not-found";
+    }) => ReactNode;
+    renderJsonLd?: (params: {
+        post: TPost;
+    }) => ReactNode;
+    children?: (state: AsteroidArticlePageUseArticleResult<TPost>) => ReactNode;
+}
+declare function AsteroidArticlePage<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost>(props: AsteroidArticlePageProps<TPost>): react_jsx_runtime.JSX.Element;
+
+interface ArticlesListingRenderProps<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
     eyebrow?: ReactNode;
     title?: ReactNode;
     description?: ReactNode;
-    /** Wrap the entire component output. */
     renderRoot?: (params: {
         children: ReactNode;
     }) => ReactNode;
-    /** Replace the default header layout (eyebrow + title + description + search). */
     renderHeader?: (params: AsteroidArticlesHeaderParams) => ReactNode;
-    /** Replace the search control. */
-    renderSearch?: (params: AsteroidArticlesSearchParams) => ReactNode;
-    /** Featured hero card. Return `null` to suppress. Hidden while searching. */
     renderFeaturedCard?: (params: AsteroidArticlesFeaturedCardParams<TPost>) => ReactNode;
-    /** Individual post card inside a grid. */
     renderPostCard: (params: AsteroidArticlesPostCardParams<TPost>) => ReactNode;
-    /** Category section heading. */
     renderCategoryHeading?: (params: AsteroidArticlesCategoryHeadingParams<TPost>) => ReactNode;
-    /** Grid wrapper for post cards within a category. */
     renderPostGrid?: (params: AsteroidArticlesPostGridParams<TPost>) => ReactNode;
-    /**
-     * Full category section (heading + grid).
-     * Receives `defaultContent` so you can wrap rather than fully replace.
-     */
     renderCategoryGroup?: (params: AsteroidArticlesCategoryGroupParams<TPost>) => ReactNode;
-    /** Loading state. */
     renderSkeleton?: () => ReactNode;
-    /** Error, empty feed, or zero search results. Return `null` to suppress. */
     renderEmpty?: (params: AsteroidArticlesEmptyParams) => ReactNode;
-    /** Wrap featured card + category groups. */
     renderContent?: (params: AsteroidArticlesContentParams) => ReactNode;
-    /** Override the built-in CollectionPage JSON-LD structured data. */
-    renderJsonLd?: (params: AsteroidArticlesState<TPost>) => ReactNode;
-    /**
-     * Escape hatch - receive full computed state and render everything yourself.
-     * When provided, structural render props above are ignored (slot render props
-     * like `renderPostCard` are still used if you call them manually).
-     */
-    children?: (state: AsteroidArticlesState<TPost>) => ReactNode;
-    /** Custom category grouping. */
+}
+
+interface AsteroidArticlesUsePostsResult<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    posts: TPost[];
+    featured?: TPost | null;
+    rest?: TPost[];
+    loading: boolean;
+    error?: unknown;
+}
+type AsteroidArticlesUsePosts<TPost extends AsteroidArticlePost = AsteroidArticlePost> = (searchQuery: string) => AsteroidArticlesUsePostsResult<TPost>;
+interface AsteroidArticlesState<TPost extends AsteroidArticlePost = AsteroidArticlePost> extends ArticlesViewState<TPost> {
+    loading: boolean;
+    error: unknown;
+    hasError: boolean;
+    /** Raw, un-debounced input value. Bind your search box to this. */
+    inputValue: string;
+    setSearchQuery: (value: string) => void;
+}
+interface AsteroidArticlesProps<TPost extends AsteroidArticlePost = AsteroidArticlePost> extends ArticlesListingRenderProps<TPost> {
+    usePosts: AsteroidArticlesUsePosts<TPost>;
+    categorySlug?: string;
+    articleSlug?: string;
+    searchDebounceMs?: number;
+    seo?: AsteroidSeoConfig;
+    noindex?: boolean;
+    renderSearch?: (params: AsteroidArticlesSearchParams) => ReactNode;
+    renderJsonLd?: (state: AsteroidArticlesState<TPost>) => ReactNode;
     groupPostsByCategory?: (posts: TPost[]) => AsteroidArticleCategoryGroup<TPost>[];
+    children?: (state: AsteroidArticlesState<TPost>) => ReactNode;
 }
+declare function useAsteroidArticlesState<TPost extends AsteroidArticlePost = AsteroidArticlePost>(props: Pick<AsteroidArticlesProps<TPost>, "usePosts" | "categorySlug" | "articleSlug" | "searchDebounceMs" | "groupPostsByCategory">): AsteroidArticlesState<TPost>;
+declare function AsteroidArticlesListing<TPost extends AsteroidArticlePost = AsteroidArticlePost>(props: AsteroidArticlesProps<TPost>): react_jsx_runtime.JSX.Element;
+
 declare function defaultGetCategoryName(post: Pick<AsteroidArticlePost, "category">): string | undefined;
 declare function defaultGroupPostsByCategory<TPost extends AsteroidArticlePost = AsteroidArticlePost>(posts: TPost[]): AsteroidArticleCategoryGroup<TPost>[];
-declare function useAsteroidArticlesState<TPost extends AsteroidArticlePost = AsteroidArticlePost>({ usePosts, categorySlug, articleSlug, searchDebounceMs, groupPostsByCategory, }: Pick<AsteroidArticlesProps<TPost>, "usePosts" | "categorySlug" | "articleSlug" | "searchDebounceMs" | "groupPostsByCategory">): AsteroidArticlesState<TPost>;
-declare function AsteroidArticlesListing<TPost extends AsteroidArticlePost = AsteroidArticlePost>(props: AsteroidArticlesProps<TPost>): string | number | boolean | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
 
-export { type AsteroidArticleCategoryGroup, AsteroidArticlePage, type AsteroidArticlePagePost, type AsteroidArticlePageProps, type AsteroidArticlePageUseArticle, type AsteroidArticlePageUseArticleResult, type AsteroidArticlePost, AsteroidArticlesListing, type AsteroidArticlesProps, type AsteroidArticlesState, type AsteroidArticlesUsePosts, type AsteroidArticlesUsePostsResult, AsteroidCMSProvider, type AsteroidCMSProviderProps, type ExtractHeadingsOptions, type ExtractedHeading, type HeadingLevel, JsonLd, RichTextContent, Seo, type UseCmsContentOptions, type UseCmsMutateOptions, defaultGetCategoryName, defaultGroupPostsByCategory, extractHeadingsFromElement, extractHeadingsFromHtml, slugify, useAsteroidArticlesState, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+interface ArticleSearchBoxProps {
+    /** URL query param the search writes to. Default: "q". */
+    paramKey?: string;
+    placeholder?: string;
+    /** Debounce before navigating. Default: 500ms. */
+    debounceMs?: number;
+    className?: string;
+    /** Override the default input UI. */
+    render?: (params: {
+        value: string;
+        onChange: (value: string) => void;
+        onSubmit: (event: {
+            preventDefault: () => void;
+        }) => void;
+    }) => ReactNode;
+}
+declare function ArticleSearchBox({ paramKey, placeholder, debounceMs, className, render, }: ArticleSearchBoxProps): react_jsx_runtime.JSX.Element;
+
+export { type ArticleBodyRenderProps, type ArticleImageResolver, ArticleSearchBox, type ArticleSearchBoxProps, type AsteroidArticleCategoryGroup, AsteroidArticlePage, type AsteroidArticlePagePost, type AsteroidArticlePageProps, type AsteroidArticlePageUseArticle, type AsteroidArticlePageUseArticleResult, type AsteroidArticlePost, type AsteroidArticlesCategoryGroupParams, type AsteroidArticlesCategoryHeadingParams, type AsteroidArticlesContentParams, type AsteroidArticlesEmptyParams, type AsteroidArticlesEmptyReason, type AsteroidArticlesFeaturedCardParams, type AsteroidArticlesHeaderParams, AsteroidArticlesListing, type AsteroidArticlesPostCardParams, type AsteroidArticlesPostGridParams, type AsteroidArticlesProps, type AsteroidArticlesSearchParams, type AsteroidArticlesState, type AsteroidArticlesUsePosts, type AsteroidArticlesUsePostsResult, AsteroidCMSProvider, type AsteroidCMSProviderProps, type ExtractHeadingsOptions, type ExtractedHeading, type HeadingLevel, JsonLd, RichTextContent, Seo, type UseCmsContentOptions, type UseCmsMutateOptions, defaultGetCategoryName, defaultGroupPostsByCategory, extractHeadingsFromElement, extractHeadingsFromHtml, slugify, useAsteroidArticlesState, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };