@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/dist/index.d.cts

@@ -14,6 +14,21 @@ interface HowToStep {
     name: string;
     text: string;
 }
+/**
+ * A real-world thing an article is about, emitted as schema.org `about`.
+ * `sameAs` should point at an authoritative identifier for the entity
+ * (Wikipedia, Wikidata, an official site) - that URL is what lets a consumer
+ * resolve "Pathfinder" the game system rather than guessing from the string.
+ */
+interface EntityReference {
+    name: string;
+    sameAs?: string;
+}
+/** An outbound source an article cites, emitted as schema.org `citation`. */
+interface CitationReference {
+    name: string;
+    url?: string;
+}
 interface Article {
     slug: string;
     title: string;
@@ -38,6 +53,18 @@ interface Article {
     toc?: TocItem[];
     faq?: FaqItem[];
     howTo?: HowToStep[];
+    /**
+     * A direct, self-contained answer to the article's core question, 40-60
+     * words. Rendered by `ArticleAnswer`, emitted as the Article schema's
+     * `abstract`, used as the `acceptedAnswer` when `articleType` is
+     * `'QAPage'`, and placed at the top of the article's markdown twin - the
+     * one passage most likely to be lifted verbatim by an answer engine.
+     */
+    answer?: string;
+    /** Entities this article is about. Emitted as schema.org `about`. */
+    about?: EntityReference[];
+    /** Outbound sources. Emitted as schema.org `citation`. */
+    citation?: CitationReference[];
     canonicalUrl?: string;
     articleType?: string;
     series?: string;
@@ -152,6 +179,13 @@ interface AuthorProfile {
     promise?: string;
     /** Structured long-form origin story - see `RichText`/`RichTextSection`. */
     originStory?: RichText;
+    /**
+     * Topics this author writes about, emitted as Person `knowsAbout`. Omit to
+     * derive it from the categories of their own published articles - unlike
+     * `credentials`/`proof`, subject matter is verifiable from the corpus
+     * itself, so it does belong in structured data.
+     */
+    knowsAbout?: string[];
     /** Who this author's content/work is for, e.g. "New game masters", "Streaming DMs". */
     servesWho?: string[];
     /** Core beliefs/approach statements. */
@@ -164,6 +198,27 @@ interface AuthorProfile {
     credentials?: string[];
     /** Concrete, sourceable proof points. */
     proof?: ProofItem[];
+    /**
+     * The one canonical URL identifying this person across every site they
+     * publish on. Used *only* to derive the Person `@id`, so the same author
+     * resolves to a single entity everywhere instead of one entity per site.
+     *
+     * Deliberately separate from `url`: that field also drives byline link
+     * targets, the author page's Open Graph URL, and its `CollectionPage` URL,
+     * so pointing it at another domain would send readers off-site and hand
+     * this site's author page a canonical belonging to a different one.
+     * `identityUrl` changes nothing a reader sees.
+     *
+     * Set the same value on every site. Falls back to `url`, then to this
+     * site's own author page.
+     */
+    identityUrl?: string;
+    /**
+     * Additional profile URLs identifying this same person elsewhere, merged
+     * into the Person schema's `sameAs` alongside the derived social links.
+     * List the author's pages on the other sites here.
+     */
+    sameAs?: string[];
     /** Primary call-to-action rendered on the author's page. */
     primaryCta?: {
         label: string;
@@ -338,6 +393,54 @@ interface BreadcrumbsConfig {
     /** Optional label overrides for built-in breadcrumb items. */
     labels?: BreadcrumbLabels;
 }
+/** Payload passed to `ArticlesConfig.onAiCrawl`. */
+interface AiCrawlEvent {
+    /** Article slug whose markdown twin was fetched. */
+    slug: string;
+    /** Matched crawler name (e.g. `'GPTBot'`), or `'unknown'` when the agent is not recognized. */
+    crawler: string;
+    /** Raw `User-Agent` header, or an empty string when absent. */
+    userAgent: string;
+}
+/**
+ * The publishing entity behind the site. Drives `OrganizationSchema`,
+ * `WebSiteSchema`, and the `publisher` reference on every article - so all
+ * three point at one `@id` instead of repeating an inline, unlinked
+ * `Organization` stub per page.
+ */
+interface OrganizationConfig {
+    /** schema.org type. Use `'Person'` for a personal brand. Default: `'Organization'`. */
+    type?: 'Organization' | 'Person';
+    /** Entity name. Falls back to `siteName`. */
+    name?: string;
+    /** Entity homepage. Falls back to `siteUrl`. */
+    url?: string;
+    /** Logo URL. Site-relative paths are resolved against `siteUrl`. */
+    logo?: string;
+    /** Entity description. Falls back to `ArticlesConfig.description`. */
+    description?: string;
+    /** Profile URLs that identify the same entity elsewhere (social, Crunchbase, Wikidata). */
+    sameAs?: string[];
+    /**
+     * The umbrella entity this site belongs to, for a network of sites run by
+     * one publisher. Emitted as `parentOrganization` - the link that lets
+     * authority earned by the network attach to each site in it, instead of
+     * each site standing alone.
+     */
+    parentOrganization?: {
+        name: string;
+        url: string;
+    };
+    /**
+     * Search URL template for the `WebSite` `SearchAction`, e.g.
+     * `'/search?q={search_term_string}'`. Omitted by default - the library's
+     * own search is client-side with no crawlable results URL, so declaring one
+     * that does not exist would be a false claim. Only set this if the app
+     * actually serves search results at that URL. Must contain the literal
+     * `{search_term_string}` placeholder.
+     */
+    searchUrlTemplate?: string;
+}
 /** Top-level configuration object. Pass one instance to every library component. */
 interface ArticlesConfig {
     /** Canonical base URL of the site, used in metadata and JSON-LD. Example: `'https://yoursite.com'` */
@@ -400,6 +503,94 @@ interface ArticlesConfig {
      * step rather than a build-time failure otherwise.
      */
     paths?: Record<string, PathDefinition>;
+    /**
+     * Template for the `<title>` tag on article, category, series, and author
+     * pages. Supports `{title}` and `{siteName}` placeholders.
+     * Default: `'{title} | {siteName}'`.
+     *
+     * Google truncates a result title around 60 characters, and a site name
+     * suffix spends that budget on every page. Set `'{title}'` to drop it when
+     * your titles are already long and your brand draws little search volume -
+     * the suffix is only earning its characters if people search for the brand.
+     */
+    titleTemplate?: string;
+    /**
+     * BCP 47 language tag for the site's content. Emitted as the Article
+     * schema's `inLanguage` and the RSS channel `<language>`. Default: `'en'`.
+     */
+    language?: string;
+    /**
+     * Set to `false` when articles sit behind a paywall or registration wall.
+     * Default: `true`, emitted as the Article schema's `isAccessibleForFree` -
+     * an explicit "this is readable" signal, since consumers that cannot tell
+     * tend to skip suspected-paywalled sources.
+     */
+    isAccessibleForFree?: boolean;
+    /**
+     * CSS selectors marking the parts of an article suitable for text-to-speech,
+     * emitted as the Article schema's `speakable`. Omitted by default - the
+     * correct selectors depend on the consuming app's own markup, and guessing
+     * them would point at elements that may not exist.
+     */
+    speakableSelectors?: string[];
+    /**
+     * Set to `true` to derive `FAQPage` entries from question-shaped `##`
+     * headings and the paragraph that follows each one. Default: `false` -
+     * turning prose into structured data without the author's intent can
+     * promote a rhetorical heading into a published Q&A pair, so this is
+     * opt-in. Explicit `faq` frontmatter always wins over derived entries.
+     */
+    deriveFaqFromHeadings?: boolean;
+    /**
+     * Shared entity vocabulary, keyed by an app-chosen slug. Article `about`
+     * entries may reference a key here instead of repeating a name/`sameAs`
+     * pair - the point of `about` is that a consumer can resolve one entity
+     * across a corpus, which free-text names spelled three different ways
+     * defeat. `validateArticles` warns on `about` keys with no registry entry.
+     */
+    entities?: Record<string, EntityReference>;
+    /**
+     * Where `lastmod` comes from when frontmatter omits it.
+     * - `'published'` (default): reuse the publish date, as before 1.3.0.
+     * - `'none'`: leave `lastmod` unset, so `dateModified` is omitted rather
+     *   than repeating a stale publish date.
+     * - `'fileMtime'`: read the article file's modification time. Accurate
+     *   locally; on a CI runner that clones fresh, every file's mtime is the
+     *   checkout time, which would report the whole corpus as updated today.
+     *   Only use it where the build preserves mtimes.
+     */
+    lastmodFallback?: 'published' | 'none' | 'fileMtime';
+    /**
+     * Called when an AI crawler fetches an article's markdown twin. The one
+     * choke point where those requests land, so it is the only place a site
+     * can measure whether any of its AI-readable content is being read, and
+     * by which bot. No PII: the payload carries the slug, the matched crawler
+     * name, and the raw user agent string only.
+     */
+    onAiCrawl?: (event: AiCrawlEvent) => void;
+    /**
+     * The publishing entity behind the site. Omit to keep the pre-1.3.0 inline
+     * `{'@type':'Organization', name: siteName}` publisher stub on articles.
+     * Set it to emit `OrganizationSchema`/`WebSiteSchema` in the root layout and
+     * have every article, author, and collection page reference the same `@id`.
+     */
+    organization?: OrganizationConfig;
+    /**
+     * Default `aiCrawl` value for articles whose frontmatter omits the key.
+     * Default: `false` (every article stays opted out unless it sets
+     * `aiCrawl: true`). Set to `true` on a site whose goal is being cited by
+     * answer engines to opt the whole corpus in at once; per-article
+     * `aiCrawl: false` still wins and keeps that article blocked.
+     */
+    aiCrawlDefault?: boolean;
+    /**
+     * Set to `false` to serve article markdown twins as the bare body, with no
+     * attribution header. Default: `true` - the twin is prefixed with the
+     * title, excerpt, canonical source URL, dates, author, and site name so a
+     * model reading `/articles/[slug].md` can attribute it. Only applies when
+     * a config is available (i.e. via `getArticleMarkdownResponse`).
+     */
+    markdownTwinHeader?: boolean;
     /**
      * Vendor-neutral event callback (Phase 27F). Fired by components/hooks at
      * meaningful reader-journey moments (see `ArticleEvent` in `events.ts`).
@@ -413,6 +604,19 @@ declare const DEFAULT_CATEGORIES_PAGE_SIZE = 8;
 declare const DEFAULT_LAYOUT: ArticlesSection[];
 declare function breadcrumbsAreEnabled(config: ArticlesConfig): boolean;
 declare function getBreadcrumbsConfig(config: ArticlesConfig): BreadcrumbsConfig;
+/** Stable `@id` for the site's publishing entity. */
+declare function getOrganizationId(config: Pick<ArticlesConfig, 'siteUrl'>): string;
+/** Stable `@id` for the site itself. */
+declare function getWebSiteId(config: Pick<ArticlesConfig, 'siteUrl'>): string;
+/** Stable `@id` for an author, so every article by them resolves to one Person. */
+declare function getPersonId(authorUrl: string): string;
+declare const DEFAULT_TITLE_TEMPLATE = "{title} | {siteName}";
+/**
+ * Applies `ArticlesConfig.titleTemplate` to a page title. Kept here rather
+ * than inlined at each call site so article, category, series, and author
+ * pages can never drift apart on how the site name is appended.
+ */
+declare function formatPageTitle(title: string, config: Pick<ArticlesConfig, 'siteName' | 'titleTemplate'>): string;
 
 declare function ArticlesPage({ config, initialArticles, initialCategories, page, totalPages, totalCount, }: Readonly<{
     config: ArticlesConfig;
@@ -612,6 +816,20 @@ declare function BreadcrumbSchema({ items }: Readonly<{
     items: BreadcrumbItem[];
 }>): react_jsx_runtime.JSX.Element;
 
+interface ArticleComment {
+    id: string;
+    articleSlug: string;
+    body: string;
+    isDeleted: boolean;
+    createdAt: string;
+    authorId: string;
+    authorName: string;
+    parentId: string | null;
+}
+interface ArticleCommentWithReplies extends ArticleComment {
+    replies: ArticleComment[];
+}
+
 type ArticleSEOProps = Readonly<{
     article: Article;
     articleUrl: string;
@@ -620,8 +838,15 @@ type ArticleSEOProps = Readonly<{
     showAuthor?: boolean;
     authors?: AuthorProfile[];
     config?: ArticlesConfig;
+    /**
+     * Top-level comments to emit as `commentCount`/`comment`. Real discussion
+     * is a quality signal that is otherwise invisible in structured data.
+     * Deleted comments are excluded, and only the author name, body, and
+     * timestamp are emitted - never the commenter's id.
+     */
+    comments?: readonly ArticleComment[];
 }>;
-declare function ArticleSEO({ article, articleUrl, siteName, siteLogo, showAuthor, authors, config, }: ArticleSEOProps): react_jsx_runtime.JSX.Element;
+declare function ArticleSEO({ article, articleUrl, siteName, siteLogo, showAuthor, authors, config, comments, }: ArticleSEOProps): react_jsx_runtime.JSX.Element;
 type FAQPageSchemaProps = Readonly<{
     items: ReadonlyArray<{
         question: string;
@@ -642,6 +867,30 @@ type CollectionPageSchemaProps = Readonly<{
     items?: CollectionPageItem[];
 }>;
 declare function CollectionPageSchema({ title, description, url, articleCount, items, }: CollectionPageSchemaProps): react_jsx_runtime.JSX.Element;
+type OrganizationSchemaProps = Readonly<{
+    config: ArticlesConfig;
+}>;
+/**
+ * Site-level publisher entity, rendered once in the root layout.
+ *
+ * Articles reference this by `@id` rather than repeating an inline
+ * `Organization` stub, so every page on the site resolves to one entity - the
+ * thing that lets a search or answer engine attribute a whole corpus to a
+ * single publisher instead of treating each page as an orphan.
+ * Returns `null` when `config.organization` is unset.
+ */
+declare function OrganizationSchema({ config }: OrganizationSchemaProps): react_jsx_runtime.JSX.Element | null;
+type WebSiteSchemaProps = Readonly<{
+    config: ArticlesConfig;
+}>;
+/**
+ * Site entity, rendered once in the root layout alongside `OrganizationSchema`.
+ * Emits a `SearchAction` only when `organization.searchUrlTemplate` is set -
+ * the library's own search is client-side with no crawlable results URL, so
+ * declaring one unconditionally would advertise an endpoint that does not exist.
+ * Returns `null` when `config.organization` is unset.
+ */
+declare function WebSiteSchema({ config }: WebSiteSchemaProps): react_jsx_runtime.JSX.Element | null;
 
 interface ArticleSocialShareProps {
     readonly title: string;
@@ -707,6 +956,22 @@ type ArticleTOCProps = Readonly<{
 }>;
 declare function ArticleTOC({ toc, className }: ArticleTOCProps): react_jsx_runtime.JSX.Element | null;
 
+type ArticleAnswerProps = Readonly<{
+    article: Pick<Article, 'answer'>;
+    /** Heading shown above the answer. Default: `'The short answer'`. */
+    label?: string;
+    className?: string;
+}>;
+/**
+ * Renders `article.answer` as a callout above the article body.
+ *
+ * The same text is emitted as the Article schema's `abstract` and placed at
+ * the top of the article's markdown twin, so the passage an answer engine is
+ * most likely to lift is also the one a reader sees first. Returns `null`
+ * when the article has no `answer`, so it is safe to render unconditionally.
+ */
+declare function ArticleAnswer({ article, label, className, }: ArticleAnswerProps): react_jsx_runtime.JSX.Element | null;
+
 declare function ScrollToTop(): react_jsx_runtime.JSX.Element | null;
 
 interface PaginationNavProps {
@@ -766,20 +1031,6 @@ interface CommentsSectionProps {
 }
 declare function CommentsSection({ articleSlug, config }: CommentsSectionProps): react_jsx_runtime.JSX.Element | null;
 
-interface ArticleComment {
-    id: string;
-    articleSlug: string;
-    body: string;
-    isDeleted: boolean;
-    createdAt: string;
-    authorId: string;
-    authorName: string;
-    parentId: string | null;
-}
-interface ArticleCommentWithReplies extends ArticleComment {
-    replies: ArticleComment[];
-}
-
 interface CommentThreadProps {
     readonly comments: ArticleCommentWithReplies[];
     readonly articleSlug: string;
@@ -815,4 +1066,4 @@ interface UseArticlesReturn {
 }
 declare function useArticles(initialArticles?: Article[], initialCategories?: CategoryInfo[]): UseArticlesReturn;
 
-export { type Article, ArticleBackLink, type ArticleBreadcrumbEntry, type ArticleBreadcrumbToken, ArticleCard, ArticleCategoryGrid, type ArticleComment, type ArticleCommentWithReplies, ArticleDetailHero, type ArticleEvent, type ArticleEventHandler, type ArticleEventName, ArticleNavigation, ArticleSEO, ArticleSearchBar, ArticleSocialShare, ArticleTOC, ArticleViewTracker, type ArticleViewedEvent, type ArticlesConfig, ArticlesHero, ArticlesPage, type ArticlesSection, type ArticlesTheme, AuthorArticlesPage, type AuthorBreadcrumbEntry, type AuthorBreadcrumbToken, AuthorCard, type AuthorClickedEvent, AuthorDetailHero, type AuthorPageSection, type AuthorProfile, type AuthorSocial, AuthorSocialLinks, Breadcrumb, type BreadcrumbItem, type BreadcrumbLabels, BreadcrumbSchema, type BreadcrumbsConfig, CategoryArticlesPage, type CategoryBreadcrumbEntry, type CategoryBreadcrumbToken, type CategoryDescription, type CategoryInfo, type CollectionPageItem, CollectionPageSchema, CommentForm, CommentItem, CommentThread, type CommentsConfig, CommentsSection, type CtaClickedEvent, CtaViewTracker, type CtaViewedEvent, type CustomBreadcrumbItem, DEFAULT_CATEGORIES_PAGE_SIZE, DEFAULT_LAYOUT, DEFAULT_PAGE_SIZE, FAQPageSchema, type FaqItem, FeaturedArticle, type HowToStep, LatestArticles, LatestArticlesSection, type LinkTargetStrategy, type ListingPagination, type ListingPaginationContext, type MdxComponents, type MeaningfulReadEvent, PaginationNav, type PathDefinition, type PathStepAdvancedEvent, type ProofItem, type RelatedArticleClickedEvent, RelatedArticlesSection, type RichText, type RichTextSection, ScrollToTop, SeriesArticlesPage, type SharedEvent, type TocItem, type UseArticlesReturn, breadcrumbsAreEnabled, getBreadcrumbsConfig, useArticles };
+export { type AiCrawlEvent, type Article, ArticleAnswer, ArticleBackLink, type ArticleBreadcrumbEntry, type ArticleBreadcrumbToken, ArticleCard, ArticleCategoryGrid, type ArticleComment, type ArticleCommentWithReplies, ArticleDetailHero, type ArticleEvent, type ArticleEventHandler, type ArticleEventName, ArticleNavigation, ArticleSEO, ArticleSearchBar, ArticleSocialShare, ArticleTOC, ArticleViewTracker, type ArticleViewedEvent, type ArticlesConfig, ArticlesHero, ArticlesPage, type ArticlesSection, type ArticlesTheme, AuthorArticlesPage, type AuthorBreadcrumbEntry, type AuthorBreadcrumbToken, AuthorCard, type AuthorClickedEvent, AuthorDetailHero, type AuthorPageSection, type AuthorProfile, type AuthorSocial, AuthorSocialLinks, Breadcrumb, type BreadcrumbItem, type BreadcrumbLabels, BreadcrumbSchema, type BreadcrumbsConfig, CategoryArticlesPage, type CategoryBreadcrumbEntry, type CategoryBreadcrumbToken, type CategoryDescription, type CategoryInfo, type CitationReference, type CollectionPageItem, CollectionPageSchema, CommentForm, CommentItem, CommentThread, type CommentsConfig, CommentsSection, type CtaClickedEvent, CtaViewTracker, type CtaViewedEvent, type CustomBreadcrumbItem, DEFAULT_CATEGORIES_PAGE_SIZE, DEFAULT_LAYOUT, DEFAULT_PAGE_SIZE, DEFAULT_TITLE_TEMPLATE, type EntityReference, FAQPageSchema, type FaqItem, FeaturedArticle, type HowToStep, LatestArticles, LatestArticlesSection, type LinkTargetStrategy, type ListingPagination, type ListingPaginationContext, type MdxComponents, type MeaningfulReadEvent, type OrganizationConfig, OrganizationSchema, PaginationNav, type PathDefinition, type PathStepAdvancedEvent, type ProofItem, type RelatedArticleClickedEvent, RelatedArticlesSection, type RichText, type RichTextSection, ScrollToTop, SeriesArticlesPage, type SharedEvent, type TocItem, type UseArticlesReturn, WebSiteSchema, breadcrumbsAreEnabled, formatPageTitle, getBreadcrumbsConfig, getOrganizationId, getPersonId, getWebSiteId, useArticles };