@asteroidcms/core-utils 0.1.7 → 0.1.8

package/dist/client.d.cts

@@ -294,4 +294,348 @@ declare function extractHeadingsFromElement(root: HTMLElement, options?: Extract
     scrollMarginTop?: number;
 }): ExtractedHeading[];
 
-export { AsteroidCMSProvider, type AsteroidCMSProviderProps, type ExtractHeadingsOptions, type ExtractedHeading, type HeadingLevel, RichTextContent, type UseCmsContentOptions, type UseCmsMutateOptions, extractHeadingsFromElement, extractHeadingsFromHtml, slugify, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+type SeoClientProps = {
+    title: string;
+    description: string;
+    url: string;
+    siteName?: string;
+    keywords?: string;
+    twitter?: string;
+    image?: string;
+    noindex?: boolean;
+};
+/** Theme colors used when generating dynamic OG images. */
+interface AsteroidOgImagePalette {
+    background: string;
+    foreground: string;
+    accent: string;
+    accentMuted?: string;
+    mutedText?: string;
+}
+interface AsteroidOgImageParams {
+    title: string;
+    subtitle?: string;
+    eyebrow?: string;
+    type?: "article" | "listing";
+}
+/** Site-level identity used to build the Organization/WebSite JSON-LD graph. */
+interface AsteroidOrganizationConfig {
+    logoUrl?: string;
+    contactEmail?: string;
+    contactPhone?: string;
+    address?: {
+        street?: string;
+        city?: string;
+        country?: string;
+    };
+    /** Generic list of profile URLs (LinkedIn, X, etc.). Maps to schema.org `sameAs`. */
+    socials?: string[];
+}
+/** Site-level SEO config passed into the headless Asteroid content components. */
+interface AsteroidSeoConfig {
+    siteName: string;
+    baseUrl: string;
+    twitter?: string;
+    defaultDescription?: string;
+    defaultKeywords?: string;
+    /** Path prefix for the article collection (e.g. `/blog`, `/news`, `/docs`). Default: `/blog` */
+    articlePath?: string;
+    /**
+     * Human label for the article collection, used in default titles/eyebrows
+     * (e.g. "Blog", "News", "Documentation"). Default: `"Articles"`.
+     */
+    contentLabel?: string;
+    /**
+     * Override how a raw page/article title becomes the final `<title>`.
+     * Default: `(title) => `${title} | ${siteName}``.
+     */
+    titleTemplate?: (title: string) => string;
+    ogImage?: {
+        palette: AsteroidOgImagePalette;
+        /** OG image API route path. Default: `/api/og` */
+        apiPath?: string;
+    };
+    /** Override dynamic OG image URL generation (e.g. custom CDN or renderer). */
+    getOgImageUrl?: (params: AsteroidOgImageParams) => string | undefined;
+    /** Site identity for the Organization/WebSite JSON-LD graph. */
+    organization?: AsteroidOrganizationConfig;
+    /** Extra schema.org @graph nodes (e.g. a ProfessionalService node). */
+    extraJsonLdNodes?: object[];
+    /** CMS base URL for resolving featured-image URLs. Required server-side for featured images. */
+    cmsUrl?: string;
+    /** URL to a PWA manifest.json. When set, a `<link rel="manifest">` is emitted. */
+    manifestUrl?: string;
+    /** Site-wide default robots policy. Per-page overrides are available on builder options. */
+    noindex?: boolean;
+}
+
+/** Render a JSON-LD <script>. Pass a built graph via `data`; renders nothing if absent. */
+declare function JsonLd({ data }: {
+    data?: object;
+}): react_jsx_runtime.JSX.Element | null;
+/**
+ * Imperatively sets document title, meta description, canonical URL and social
+ * tags. Works in plain React apps and Next.js client components. In a Next.js
+ * App Router app, prefer server `generateMetadata` from the `/next` entry.
+ */
+declare function Seo({ title, description, url, siteName, keywords, twitter, image, noindex, }: SeoClientProps): null;
+
+/** 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;
+
+/** Minimal article post shape shared across Asteroid CMS apps. */
+interface AsteroidArticlePost {
+    slug: string;
+    title: string;
+    description?: string;
+    featured_image?: string;
+    featured?: boolean;
+    published_date?: string | null;
+    category?: {
+        slug: string;
+        name: string;
+        description?: string;
+    };
+}
+interface AsteroidArticleCategoryGroup<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    categoryName: string;
+    categorySlug: string;
+    posts: TPost[];
+}
+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 AsteroidArticlesSearchParams {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: (event: React.FormEvent) => void;
+}
+interface AsteroidArticlesHeaderParams {
+    eyebrow: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    search: ReactNode;
+}
+interface AsteroidArticlesFeaturedCardParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    post: TPost;
+}
+interface AsteroidArticlesPostCardParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    post: TPost;
+    index: number;
+    group: AsteroidArticleCategoryGroup<TPost>;
+}
+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> {
+    group: AsteroidArticleCategoryGroup<TPost>;
+}
+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;
+    error?: unknown;
+}
+interface AsteroidArticlesContentParams {
+    featured: ReactNode;
+    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 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. */
+    seo?: AsteroidSeoConfig;
+    /** Mark this page as `noindex` for search engines. */
+    noindex?: boolean;
+    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. */
+    groupPostsByCategory?: (posts: TPost[]) => AsteroidArticleCategoryGroup<TPost>[];
+}
+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 };