@dsaplatform/content-sdk 1.1.0 → 1.3.0

package/README.md

@@ -111,6 +111,78 @@ function BlogPost({ slug }: { slug: string }) {
 }
 ```
 
+## Theming & Styling
+
+### Light / Dark theme (works out of the box)
+
+The SDK ships built-in prose styles for headings, paragraphs, lists, blockquotes, tables, and links inside the article body. These are scoped via `[data-dsa-article-body]` and injected once via `<style>` — they work even when Tailwind Preflight resets all margins.
+
+```tsx
+<ArticlePage article={article} theme="light" />
+<ArticlePage article={article} theme="dark" />
+```
+
+Override any value with CSS variables on a parent element:
+
+```css
+:root {
+  --dsa-text: #0f172a;
+  --dsa-content-text: #334155;
+  --dsa-h2-text: #0f172a;
+  --dsa-h3-text: #1e293b;
+  --dsa-link: #2563eb;
+  --dsa-link-hover: #1d4ed8;
+  --dsa-toc-bg: #f8fafc;
+  --dsa-card-border: #e2e8f0;
+  --dsa-badge-bg: #eff6ff;
+  --dsa-badge-text: #2563eb;
+  --dsa-badge-alt-bg: #f0fdf4;
+  --dsa-badge-alt-text: #16a34a;
+  --dsa-divider: #e2e8f0;
+  --dsa-blockquote-border: #cbd5e1;
+  --dsa-blockquote-text: #475569;
+  --dsa-pre-bg: #f1f5f9;
+  --dsa-table-border: #e2e8f0;
+  --dsa-table-header-bg: #f8fafc;
+}
+```
+
+To disable the built-in prose styles (e.g. if you use `@tailwindcss/typography`):
+
+```tsx
+<ArticlePage article={article} disableProseStyles />
+```
+
+### Inherit theme (full control)
+
+`theme="inherit"` removes **all** inline styles and injected `<style>` tags. The SDK renders only semantic HTML with stable CSS classes and `data-*` attributes.
+
+```tsx
+<ArticlePage
+  article={article}
+  theme="inherit"
+  className="max-w-3xl mx-auto font-sans"
+  contentClassName="prose dark:prose-invert"
+/>
+```
+
+> **Tailwind + Preflight note:** In `inherit` mode, paragraph margins, heading sizes, and list styles are all reset to zero by Preflight. You must provide your own prose styles — for example via `@tailwindcss/typography` (`prose` class) or custom CSS targeting the stable selectors below.
+
+### Stable CSS selectors
+
+Always present regardless of theme:
+
+| Element | CSS class | Data attribute |
+|---------|-----------|----------------|
+| Root | your `className` | `data-dsa-theme="light\|dark\|inherit"` |
+| Article body | `dsa-article-body` + `contentClassName` | `data-dsa-article-body` |
+| TOC nav | `dsa-toc` | `data-dsa-toc` |
+| Meta row | `dsa-meta` | `data-dsa-meta` |
+| H1 | `dsa-h1` | — |
+| Badge | `dsa-badge` | — |
+| Featured image | `dsa-featured-image` | — |
+| Divider | `dsa-divider` | — |
+
 ## Components
 
 | Component | Description |

package/dist/headless.d.mts

@@ -0,0 +1,101 @@
+/**
+ * Full article response from Content Engine
+ */
+interface Article {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    content_html: string;
+    content_json: any | null;
+    h1: string | null;
+    meta_title: string | null;
+    meta_description: string | null;
+    canonical_url?: string | null;
+    target_keyword: string | null;
+    secondary_keywords: string[];
+    headings: ArticleHeading[];
+    faq: FaqItem[];
+    internal_links: InternalLink[];
+    schema_json: any | null;
+    featured_image_url: string | null;
+    featured_image_alt: string | null;
+    publish_status: string;
+    published_at: string | null;
+    updated_at?: string | null;
+    word_count: number | null;
+    reading_time_minutes: number | null;
+    seo_score: number | null;
+    pillar_name?: string;
+    cluster_name?: string;
+    content_type?: string;
+}
+/**
+ * Article heading (from H1-H6 tags)
+ */
+interface ArticleHeading {
+    level: number;
+    text: string;
+    id: string;
+}
+/**
+ * FAQ item
+ */
+interface FaqItem {
+    question: string;
+    answer: string;
+}
+/**
+ * Internal link reference
+ */
+interface InternalLink {
+    slug: string;
+    anchor_text: string;
+}
+
+/**
+ * Headless utilities — data transformers with zero UI / zero inline styles.
+ * Use these to build your own components with shadcn/Tailwind/custom CSS.
+ *
+ * ```ts
+ * import { buildTocData, buildFaqSchema, normalizeArticle } from '@dsaplatform/content-sdk/headless';
+ * ```
+ */
+
+/** TOC entry with indentation level for rendering */
+interface TocEntry {
+    id: string;
+    text: string;
+    level: number;
+    /** Depth relative to minimum heading level (0-based) */
+    depth: number;
+}
+/**
+ * Build TOC data from article headings.
+ * Normalizes depth so the shallowest heading is depth=0.
+ */
+declare function buildTocData(headings: ArticleHeading[]): TocEntry[];
+/**
+ * Build Schema.org FAQPage JSON-LD object from FAQ items.
+ * Returns the object (not stringified) — you inject it into <script type="application/ld+json">.
+ */
+declare function buildFaqSchema(items: FaqItem[]): Record<string, any> | null;
+/**
+ * Build Schema.org Article JSON-LD object.
+ */
+declare function buildArticleSchema(article: Article, siteUrl?: string): Record<string, any>;
+/**
+ * Normalize an article response — ensures all array fields are arrays, never null.
+ */
+declare function normalizeArticle(article: Article): Article;
+/**
+ * Extract plain text from content_html (strip tags).
+ * Useful for excerpts, search indexing, reading time calculation.
+ */
+declare function htmlToPlainText(html: string): string;
+/**
+ * Calculate reading time from HTML content.
+ */
+declare function calculateReadingTime(html: string, wordsPerMinute?: number): number;
+
+export { type Article, type ArticleHeading, type FaqItem, type TocEntry, buildArticleSchema, buildFaqSchema, buildTocData, calculateReadingTime, htmlToPlainText, normalizeArticle };

package/dist/headless.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Full article response from Content Engine
+ */
+interface Article {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    content_html: string;
+    content_json: any | null;
+    h1: string | null;
+    meta_title: string | null;
+    meta_description: string | null;
+    canonical_url?: string | null;
+    target_keyword: string | null;
+    secondary_keywords: string[];
+    headings: ArticleHeading[];
+    faq: FaqItem[];
+    internal_links: InternalLink[];
+    schema_json: any | null;
+    featured_image_url: string | null;
+    featured_image_alt: string | null;
+    publish_status: string;
+    published_at: string | null;
+    updated_at?: string | null;
+    word_count: number | null;
+    reading_time_minutes: number | null;
+    seo_score: number | null;
+    pillar_name?: string;
+    cluster_name?: string;
+    content_type?: string;
+}
+/**
+ * Article heading (from H1-H6 tags)
+ */
+interface ArticleHeading {
+    level: number;
+    text: string;
+    id: string;
+}
+/**
+ * FAQ item
+ */
+interface FaqItem {
+    question: string;
+    answer: string;
+}
+/**
+ * Internal link reference
+ */
+interface InternalLink {
+    slug: string;
+    anchor_text: string;
+}
+
+/**
+ * Headless utilities — data transformers with zero UI / zero inline styles.
+ * Use these to build your own components with shadcn/Tailwind/custom CSS.
+ *
+ * ```ts
+ * import { buildTocData, buildFaqSchema, normalizeArticle } from '@dsaplatform/content-sdk/headless';
+ * ```
+ */
+
+/** TOC entry with indentation level for rendering */
+interface TocEntry {
+    id: string;
+    text: string;
+    level: number;
+    /** Depth relative to minimum heading level (0-based) */
+    depth: number;
+}
+/**
+ * Build TOC data from article headings.
+ * Normalizes depth so the shallowest heading is depth=0.
+ */
+declare function buildTocData(headings: ArticleHeading[]): TocEntry[];
+/**
+ * Build Schema.org FAQPage JSON-LD object from FAQ items.
+ * Returns the object (not stringified) — you inject it into <script type="application/ld+json">.
+ */
+declare function buildFaqSchema(items: FaqItem[]): Record<string, any> | null;
+/**
+ * Build Schema.org Article JSON-LD object.
+ */
+declare function buildArticleSchema(article: Article, siteUrl?: string): Record<string, any>;
+/**
+ * Normalize an article response — ensures all array fields are arrays, never null.
+ */
+declare function normalizeArticle(article: Article): Article;
+/**
+ * Extract plain text from content_html (strip tags).
+ * Useful for excerpts, search indexing, reading time calculation.
+ */
+declare function htmlToPlainText(html: string): string;
+/**
+ * Calculate reading time from HTML content.
+ */
+declare function calculateReadingTime(html: string, wordsPerMinute?: number): number;
+
+export { type Article, type ArticleHeading, type FaqItem, type TocEntry, buildArticleSchema, buildFaqSchema, buildTocData, calculateReadingTime, htmlToPlainText, normalizeArticle };

package/dist/headless.js

@@ -0,0 +1,2 @@
+"use strict";var i=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var u=(e,t)=>{for(var n in t)i(e,n,{get:t[n],enumerable:!0})},c=(e,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of a(t))!l.call(e,r)&&r!==n&&i(e,r,{get:()=>t[r],enumerable:!(o=d(t,r))||o.enumerable});return e};var p=e=>c(i({},"__esModule",{value:!0}),e);var f={};u(f,{buildArticleSchema:()=>_,buildFaqSchema:()=>g,buildTocData:()=>m,calculateReadingTime:()=>h,htmlToPlainText:()=>s,normalizeArticle:()=>y});module.exports=p(f);function m(e){if(!e||e.length===0)return[];let t=Math.min(...e.map(n=>n.level));return e.map(n=>({id:n.id,text:n.text,level:n.level,depth:n.level-t}))}function g(e){return!e||e.length===0?null:{"@context":"https://schema.org","@type":"FAQPage",mainEntity:e.map(t=>({"@type":"Question",name:t.question,acceptedAnswer:{"@type":"Answer",text:t.answer}}))}}function _(e,t){if(e.schema_json&&Object.keys(e.schema_json).length>0)return e.schema_json;let n=t?`${t.replace(/\/+$/,"")}/blog/${e.slug}`:void 0;return{"@context":"https://schema.org","@type":"Article",headline:e.meta_title||e.title,description:e.meta_description||e.excerpt||"",datePublished:e.published_at||void 0,dateModified:e.updated_at||e.published_at||void 0,...e.featured_image_url?{image:e.featured_image_url}:{},...n?{url:n}:{},...e.target_keyword?{keywords:[e.target_keyword,...e.secondary_keywords||[]].join(", ")}:{}}}function y(e){return{...e,headings:e.headings??[],faq:e.faq??[],internal_links:e.internal_links??[],secondary_keywords:e.secondary_keywords??[],schema_json:e.schema_json??null,content_json:e.content_json??null}}function s(e){return e.replace(/<[^>]+>/g,"").replace(/\s+/g," ").trim()}function h(e,t=200){let o=s(e).split(/\s+/).filter(Boolean).length;return Math.max(1,Math.ceil(o/t))}0&&(module.exports={buildArticleSchema,buildFaqSchema,buildTocData,calculateReadingTime,htmlToPlainText,normalizeArticle});
+//# sourceMappingURL=headless.js.map

package/dist/headless.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/headless.ts"],"sourcesContent":["/**\n * Headless utilities — data transformers with zero UI / zero inline styles.\n * Use these to build your own components with shadcn/Tailwind/custom CSS.\n *\n * ```ts\n * import { buildTocData, buildFaqSchema, normalizeArticle } from '@dsaplatform/content-sdk/headless';\n * ```\n */\nimport type { Article, ArticleHeading, FaqItem } from './types';\n\nexport type { Article, ArticleHeading, FaqItem };\n\n/** TOC entry with indentation level for rendering */\nexport interface TocEntry {\n  id: string;\n  text: string;\n  level: number;\n  /** Depth relative to minimum heading level (0-based) */\n  depth: number;\n}\n\n/**\n * Build TOC data from article headings.\n * Normalizes depth so the shallowest heading is depth=0.\n */\nexport function buildTocData(headings: ArticleHeading[]): TocEntry[] {\n  if (!headings || headings.length === 0) return [];\n  const minLevel = Math.min(...headings.map((h) => h.level));\n  return headings.map((h) => ({\n    id: h.id,\n    text: h.text,\n    level: h.level,\n    depth: h.level - minLevel,\n  }));\n}\n\n/**\n * Build Schema.org FAQPage JSON-LD object from FAQ items.\n * Returns the object (not stringified) — you inject it into <script type=\"application/ld+json\">.\n */\nexport function buildFaqSchema(items: FaqItem[]): Record<string, any> | null {\n  if (!items || items.length === 0) return null;\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'FAQPage',\n    mainEntity: items.map((item) => ({\n      '@type': 'Question',\n      name: item.question,\n      acceptedAnswer: { '@type': 'Answer', text: item.answer },\n    })),\n  };\n}\n\n/**\n * Build Schema.org Article JSON-LD object.\n */\nexport function buildArticleSchema(\n  article: Article,\n  siteUrl?: string,\n): Record<string, any> {\n  if (article.schema_json && Object.keys(article.schema_json).length > 0) {\n    return article.schema_json;\n  }\n  const url = siteUrl\n    ? `${siteUrl.replace(/\\/+$/, '')}/blog/${article.slug}`\n    : undefined;\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'Article',\n    headline: article.meta_title || article.title,\n    description: article.meta_description || article.excerpt || '',\n    datePublished: article.published_at || undefined,\n    dateModified: article.updated_at || article.published_at || undefined,\n    ...(article.featured_image_url ? { image: article.featured_image_url } : {}),\n    ...(url ? { url } : {}),\n    ...(article.target_keyword\n      ? { keywords: [article.target_keyword, ...(article.secondary_keywords || [])].join(', ') }\n      : {}),\n  };\n}\n\n/**\n * Normalize an article response — ensures all array fields are arrays, never null.\n */\nexport function normalizeArticle(article: Article): Article {\n  return {\n    ...article,\n    headings: article.headings ?? [],\n    faq: article.faq ?? [],\n    internal_links: article.internal_links ?? [],\n    secondary_keywords: article.secondary_keywords ?? [],\n    schema_json: article.schema_json ?? null,\n    content_json: article.content_json ?? null,\n  };\n}\n\n/**\n * Extract plain text from content_html (strip tags).\n * Useful for excerpts, search indexing, reading time calculation.\n */\nexport function htmlToPlainText(html: string): string {\n  return html.replace(/<[^>]+>/g, '').replace(/\\s+/g, ' ').trim();\n}\n\n/**\n * Calculate reading time from HTML content.\n */\nexport function calculateReadingTime(html: string, wordsPerMinute = 200): number {\n  const text = htmlToPlainText(html);\n  const words = text.split(/\\s+/).filter(Boolean).length;\n  return Math.max(1, Math.ceil(words / wordsPerMinute));\n}\n"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,wBAAAE,EAAA,mBAAAC,EAAA,iBAAAC,EAAA,yBAAAC,EAAA,oBAAAC,EAAA,qBAAAC,IAAA,eAAAC,EAAAR,GAyBO,SAASI,EAAaK,EAAwC,CACnE,GAAI,CAACA,GAAYA,EAAS,SAAW,EAAG,MAAO,CAAC,EAChD,IAAMC,EAAW,KAAK,IAAI,GAAGD,EAAS,IAAKE,GAAMA,EAAE,KAAK,CAAC,EACzD,OAAOF,EAAS,IAAKE,IAAO,CAC1B,GAAIA,EAAE,GACN,KAAMA,EAAE,KACR,MAAOA,EAAE,MACT,MAAOA,EAAE,MAAQD,CACnB,EAAE,CACJ,CAMO,SAASP,EAAeS,EAA8C,CAC3E,MAAI,CAACA,GAASA,EAAM,SAAW,EAAU,KAClC,CACL,WAAY,qBACZ,QAAS,UACT,WAAYA,EAAM,IAAKC,IAAU,CAC/B,QAAS,WACT,KAAMA,EAAK,SACX,eAAgB,CAAE,QAAS,SAAU,KAAMA,EAAK,MAAO,CACzD,EAAE,CACJ,CACF,CAKO,SAASX,EACdY,EACAC,EACqB,CACrB,GAAID,EAAQ,aAAe,OAAO,KAAKA,EAAQ,WAAW,EAAE,OAAS,EACnE,OAAOA,EAAQ,YAEjB,IAAME,EAAMD,EACR,GAAGA,EAAQ,QAAQ,OAAQ,EAAE,CAAC,SAASD,EAAQ,IAAI,GACnD,OACJ,MAAO,CACL,WAAY,qBACZ,QAAS,UACT,SAAUA,EAAQ,YAAcA,EAAQ,MACxC,YAAaA,EAAQ,kBAAoBA,EAAQ,SAAW,GAC5D,cAAeA,EAAQ,cAAgB,OACvC,aAAcA,EAAQ,YAAcA,EAAQ,cAAgB,OAC5D,GAAIA,EAAQ,mBAAqB,CAAE,MAAOA,EAAQ,kBAAmB,EAAI,CAAC,EAC1E,GAAIE,EAAM,CAAE,IAAAA,CAAI,EAAI,CAAC,EACrB,GAAIF,EAAQ,eACR,CAAE,SAAU,CAACA,EAAQ,eAAgB,GAAIA,EAAQ,oBAAsB,CAAC,CAAE,EAAE,KAAK,IAAI,CAAE,EACvF,CAAC,CACP,CACF,CAKO,SAASP,EAAiBO,EAA2B,CAC1D,MAAO,CACL,GAAGA,EACH,SAAUA,EAAQ,UAAY,CAAC,EAC/B,IAAKA,EAAQ,KAAO,CAAC,EACrB,eAAgBA,EAAQ,gBAAkB,CAAC,EAC3C,mBAAoBA,EAAQ,oBAAsB,CAAC,EACnD,YAAaA,EAAQ,aAAe,KACpC,aAAcA,EAAQ,cAAgB,IACxC,CACF,CAMO,SAASR,EAAgBW,EAAsB,CACpD,OAAOA,EAAK,QAAQ,WAAY,EAAE,EAAE,QAAQ,OAAQ,GAAG,EAAE,KAAK,CAChE,CAKO,SAASZ,EAAqBY,EAAcC,EAAiB,IAAa,CAE/E,IAAMC,EADOb,EAAgBW,CAAI,EACd,MAAM,KAAK,EAAE,OAAO,OAAO,EAAE,OAChD,OAAO,KAAK,IAAI,EAAG,KAAK,KAAKE,EAAQD,CAAc,CAAC,CACtD","names":["headless_exports","__export","buildArticleSchema","buildFaqSchema","buildTocData","calculateReadingTime","htmlToPlainText","normalizeArticle","__toCommonJS","headings","minLevel","h","items","item","article","siteUrl","url","html","wordsPerMinute","words"]}

package/dist/headless.mjs

@@ -0,0 +1,2 @@
+function i(e){if(!e||e.length===0)return[];let n=Math.min(...e.map(t=>t.level));return e.map(t=>({id:t.id,text:t.text,level:t.level,depth:t.level-n}))}function s(e){return!e||e.length===0?null:{"@context":"https://schema.org","@type":"FAQPage",mainEntity:e.map(n=>({"@type":"Question",name:n.question,acceptedAnswer:{"@type":"Answer",text:n.answer}}))}}function d(e,n){if(e.schema_json&&Object.keys(e.schema_json).length>0)return e.schema_json;let t=n?`${n.replace(/\/+$/,"")}/blog/${e.slug}`:void 0;return{"@context":"https://schema.org","@type":"Article",headline:e.meta_title||e.title,description:e.meta_description||e.excerpt||"",datePublished:e.published_at||void 0,dateModified:e.updated_at||e.published_at||void 0,...e.featured_image_url?{image:e.featured_image_url}:{},...t?{url:t}:{},...e.target_keyword?{keywords:[e.target_keyword,...e.secondary_keywords||[]].join(", ")}:{}}}function a(e){return{...e,headings:e.headings??[],faq:e.faq??[],internal_links:e.internal_links??[],secondary_keywords:e.secondary_keywords??[],schema_json:e.schema_json??null,content_json:e.content_json??null}}function o(e){return e.replace(/<[^>]+>/g,"").replace(/\s+/g," ").trim()}function l(e,n=200){let r=o(e).split(/\s+/).filter(Boolean).length;return Math.max(1,Math.ceil(r/n))}export{d as buildArticleSchema,s as buildFaqSchema,i as buildTocData,l as calculateReadingTime,o as htmlToPlainText,a as normalizeArticle};
+//# sourceMappingURL=headless.mjs.map

package/dist/headless.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/headless.ts"],"sourcesContent":["/**\n * Headless utilities — data transformers with zero UI / zero inline styles.\n * Use these to build your own components with shadcn/Tailwind/custom CSS.\n *\n * ```ts\n * import { buildTocData, buildFaqSchema, normalizeArticle } from '@dsaplatform/content-sdk/headless';\n * ```\n */\nimport type { Article, ArticleHeading, FaqItem } from './types';\n\nexport type { Article, ArticleHeading, FaqItem };\n\n/** TOC entry with indentation level for rendering */\nexport interface TocEntry {\n  id: string;\n  text: string;\n  level: number;\n  /** Depth relative to minimum heading level (0-based) */\n  depth: number;\n}\n\n/**\n * Build TOC data from article headings.\n * Normalizes depth so the shallowest heading is depth=0.\n */\nexport function buildTocData(headings: ArticleHeading[]): TocEntry[] {\n  if (!headings || headings.length === 0) return [];\n  const minLevel = Math.min(...headings.map((h) => h.level));\n  return headings.map((h) => ({\n    id: h.id,\n    text: h.text,\n    level: h.level,\n    depth: h.level - minLevel,\n  }));\n}\n\n/**\n * Build Schema.org FAQPage JSON-LD object from FAQ items.\n * Returns the object (not stringified) — you inject it into <script type=\"application/ld+json\">.\n */\nexport function buildFaqSchema(items: FaqItem[]): Record<string, any> | null {\n  if (!items || items.length === 0) return null;\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'FAQPage',\n    mainEntity: items.map((item) => ({\n      '@type': 'Question',\n      name: item.question,\n      acceptedAnswer: { '@type': 'Answer', text: item.answer },\n    })),\n  };\n}\n\n/**\n * Build Schema.org Article JSON-LD object.\n */\nexport function buildArticleSchema(\n  article: Article,\n  siteUrl?: string,\n): Record<string, any> {\n  if (article.schema_json && Object.keys(article.schema_json).length > 0) {\n    return article.schema_json;\n  }\n  const url = siteUrl\n    ? `${siteUrl.replace(/\\/+$/, '')}/blog/${article.slug}`\n    : undefined;\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'Article',\n    headline: article.meta_title || article.title,\n    description: article.meta_description || article.excerpt || '',\n    datePublished: article.published_at || undefined,\n    dateModified: article.updated_at || article.published_at || undefined,\n    ...(article.featured_image_url ? { image: article.featured_image_url } : {}),\n    ...(url ? { url } : {}),\n    ...(article.target_keyword\n      ? { keywords: [article.target_keyword, ...(article.secondary_keywords || [])].join(', ') }\n      : {}),\n  };\n}\n\n/**\n * Normalize an article response — ensures all array fields are arrays, never null.\n */\nexport function normalizeArticle(article: Article): Article {\n  return {\n    ...article,\n    headings: article.headings ?? [],\n    faq: article.faq ?? [],\n    internal_links: article.internal_links ?? [],\n    secondary_keywords: article.secondary_keywords ?? [],\n    schema_json: article.schema_json ?? null,\n    content_json: article.content_json ?? null,\n  };\n}\n\n/**\n * Extract plain text from content_html (strip tags).\n * Useful for excerpts, search indexing, reading time calculation.\n */\nexport function htmlToPlainText(html: string): string {\n  return html.replace(/<[^>]+>/g, '').replace(/\\s+/g, ' ').trim();\n}\n\n/**\n * Calculate reading time from HTML content.\n */\nexport function calculateReadingTime(html: string, wordsPerMinute = 200): number {\n  const text = htmlToPlainText(html);\n  const words = text.split(/\\s+/).filter(Boolean).length;\n  return Math.max(1, Math.ceil(words / wordsPerMinute));\n}\n"],"mappings":"AAyBO,SAASA,EAAaC,EAAwC,CACnE,GAAI,CAACA,GAAYA,EAAS,SAAW,EAAG,MAAO,CAAC,EAChD,IAAMC,EAAW,KAAK,IAAI,GAAGD,EAAS,IAAKE,GAAMA,EAAE,KAAK,CAAC,EACzD,OAAOF,EAAS,IAAKE,IAAO,CAC1B,GAAIA,EAAE,GACN,KAAMA,EAAE,KACR,MAAOA,EAAE,MACT,MAAOA,EAAE,MAAQD,CACnB,EAAE,CACJ,CAMO,SAASE,EAAeC,EAA8C,CAC3E,MAAI,CAACA,GAASA,EAAM,SAAW,EAAU,KAClC,CACL,WAAY,qBACZ,QAAS,UACT,WAAYA,EAAM,IAAKC,IAAU,CAC/B,QAAS,WACT,KAAMA,EAAK,SACX,eAAgB,CAAE,QAAS,SAAU,KAAMA,EAAK,MAAO,CACzD,EAAE,CACJ,CACF,CAKO,SAASC,EACdC,EACAC,EACqB,CACrB,GAAID,EAAQ,aAAe,OAAO,KAAKA,EAAQ,WAAW,EAAE,OAAS,EACnE,OAAOA,EAAQ,YAEjB,IAAME,EAAMD,EACR,GAAGA,EAAQ,QAAQ,OAAQ,EAAE,CAAC,SAASD,EAAQ,IAAI,GACnD,OACJ,MAAO,CACL,WAAY,qBACZ,QAAS,UACT,SAAUA,EAAQ,YAAcA,EAAQ,MACxC,YAAaA,EAAQ,kBAAoBA,EAAQ,SAAW,GAC5D,cAAeA,EAAQ,cAAgB,OACvC,aAAcA,EAAQ,YAAcA,EAAQ,cAAgB,OAC5D,GAAIA,EAAQ,mBAAqB,CAAE,MAAOA,EAAQ,kBAAmB,EAAI,CAAC,EAC1E,GAAIE,EAAM,CAAE,IAAAA,CAAI,EAAI,CAAC,EACrB,GAAIF,EAAQ,eACR,CAAE,SAAU,CAACA,EAAQ,eAAgB,GAAIA,EAAQ,oBAAsB,CAAC,CAAE,EAAE,KAAK,IAAI,CAAE,EACvF,CAAC,CACP,CACF,CAKO,SAASG,EAAiBH,EAA2B,CAC1D,MAAO,CACL,GAAGA,EACH,SAAUA,EAAQ,UAAY,CAAC,EAC/B,IAAKA,EAAQ,KAAO,CAAC,EACrB,eAAgBA,EAAQ,gBAAkB,CAAC,EAC3C,mBAAoBA,EAAQ,oBAAsB,CAAC,EACnD,YAAaA,EAAQ,aAAe,KACpC,aAAcA,EAAQ,cAAgB,IACxC,CACF,CAMO,SAASI,EAAgBC,EAAsB,CACpD,OAAOA,EAAK,QAAQ,WAAY,EAAE,EAAE,QAAQ,OAAQ,GAAG,EAAE,KAAK,CAChE,CAKO,SAASC,EAAqBD,EAAcE,EAAiB,IAAa,CAE/E,IAAMC,EADOJ,EAAgBC,CAAI,EACd,MAAM,KAAK,EAAE,OAAO,OAAO,EAAE,OAChD,OAAO,KAAK,IAAI,EAAG,KAAK,KAAKG,EAAQD,CAAc,CAAC,CACtD","names":["buildTocData","headings","minLevel","h","buildFaqSchema","items","item","buildArticleSchema","article","siteUrl","url","normalizeArticle","htmlToPlainText","html","calculateReadingTime","wordsPerMinute","words"]}

package/dist/index.d.mts

@@ -272,17 +272,22 @@ interface ArticleFeedProps {
     showMeta?: boolean;
     onArticleClick?: (slug: string) => void;
     className?: string;
+    /** "light" | "dark" | "inherit" — sets CSS variable defaults. Use "inherit" to control via your own CSS vars. */
+    theme?: 'light' | 'dark' | 'inherit';
     renderArticle?: (article: ArticleListItem) => React.ReactNode;
 }
 /**
  * Renders a grid or list of article cards.
+ * Supports theme="light" | "dark" | "inherit" via CSS variables.
  *
- * ```tsx
- * <ArticleFeed articles={articles} layout="grid" columns={3} onArticleClick={(slug) => router.push(`/blog/${slug}`)} />
- * ```
+ * CSS variables (override in your own CSS for full control):
+ *   --dsa-text, --dsa-text-muted, --dsa-text-faint,
+ *   --dsa-card-bg, --dsa-card-border,
+ *   --dsa-badge-bg, --dsa-badge-text, --dsa-hover-shadow
  */
-declare function ArticleFeed({ articles, layout, columns, showExcerpt, showImage, showMeta, onArticleClick, className, renderArticle, }: ArticleFeedProps): react_jsx_runtime.JSX.Element;
+declare function ArticleFeed({ articles, layout, columns, showExcerpt, showImage, showMeta, onArticleClick, className, theme, renderArticle, }: ArticleFeedProps): react_jsx_runtime.JSX.Element;
 
+type ArticleTheme = 'light' | 'dark' | 'inherit';
 interface ArticlePageProps {
     article: Article;
     showFaq?: boolean;
@@ -292,6 +297,22 @@ interface ArticlePageProps {
     relatedArticles?: ArticleListItem[];
     onRelatedClick?: (slug: string) => void;
     className?: string;
+    /** Extra class(es) on the `<div>` that wraps `content_html`. */
+    contentClassName?: string;
+    /**
+     * `"light"` / `"dark"` — SDK applies inline styles + CSS vars + built-in prose rules.
+     * `"inherit"` — SDK applies NO inline styles; only CSS classes and
+     *  `data-*` attributes are rendered so the host site has full control.
+     *
+     * In all modes the content body div has:
+     * - `className="dsa-article-body"`
+     * - `data-dsa-article-body`
+     *
+     * @default "light"
+     */
+    theme?: ArticleTheme;
+    /** Disable built-in prose styles injected via `<style>`. Works only in light/dark themes. */
+    disableProseStyles?: boolean;
     components?: {
         H1?: React.ComponentType<{
             children: React.ReactNode;
@@ -305,13 +326,32 @@ interface ArticlePageProps {
     };
 }
 /**
- * Renders a full article page with optional TOC, FAQ, and related articles.
+ * Full article page with optional TOC, FAQ, related articles, and JSON-LD.
+ *
+ * **light / dark** — SDK applies inline styles with `--dsa-*` CSS variable
+ * overrides, plus built-in prose rules for the article body.
+ *
+ * **inherit** — SDK renders only semantic HTML with stable CSS classes
+ * and `data-*` attributes. No inline styles, no injected `<style>`.
+ *
+ * ### Stable CSS selectors (always present)
+ *
+ * | Element | Class | Data attribute |
+ * |---------|-------|----------------|
+ * | Root    | `className` prop | `data-dsa-theme` |
+ * | Body    | `dsa-article-body` + `contentClassName` | `data-dsa-article-body` |
+ * | TOC     | `dsa-toc` | `data-dsa-toc` |
+ * | Meta    | `dsa-meta` | `data-dsa-meta` |
  *
  * ```tsx
- * <ArticlePage article={article} showTableOfContents showFaq />
+ * // Works out of the box
+ * <ArticlePage article={article} />
+ *
+ * // Inherit — host site provides all styles
+ * <ArticlePage article={article} theme="inherit" contentClassName="prose dark:prose-invert" />
  * ```
  */
-declare function ArticlePage({ article, showFaq, showTableOfContents, showMeta, showRelated, relatedArticles, onRelatedClick, className, components, }: ArticlePageProps): react_jsx_runtime.JSX.Element;
+declare function ArticlePage({ article, showFaq, showTableOfContents, showMeta, showRelated, relatedArticles, onRelatedClick, className, contentClassName, theme, disableProseStyles, components, }: ArticlePageProps): react_jsx_runtime.JSX.Element;
 
 interface FaqBlockProps {
     items: FaqItem[];
@@ -319,15 +359,14 @@ interface FaqBlockProps {
     defaultOpen?: boolean;
     className?: string;
     title?: string;
+    /** "light" | "dark" | "inherit" */
+    theme?: 'light' | 'dark' | 'inherit';
 }
 /**
- * FAQ block with optional collapse behavior and Schema.org FAQPage markup.
- *
- * ```tsx
- * <FaqBlock items={article.faq} collapsible />
- * ```
+ * FAQ block with Schema.org FAQPage markup.
+ * Supports theme="light" | "dark" | "inherit" via CSS variables.
  */
-declare function FaqBlock({ items, collapsible, defaultOpen, className, title, }: FaqBlockProps): react_jsx_runtime.JSX.Element | null;
+declare function FaqBlock({ items, collapsible, defaultOpen, className, title, theme, }: FaqBlockProps): react_jsx_runtime.JSX.Element | null;
 
 interface RelatedArticlesProps {
     articles: ArticleListItem[];
@@ -335,15 +374,14 @@ interface RelatedArticlesProps {
     limit?: number;
     onArticleClick?: (slug: string) => void;
     className?: string;
+    /** "light" | "dark" | "inherit" */
+    theme?: 'light' | 'dark' | 'inherit';
 }
 /**
  * Related articles widget.
- *
- * ```tsx
- * <RelatedArticles articles={related} onArticleClick={(slug) => router.push(`/blog/${slug}`)} />
- * ```
+ * Supports theme="light" | "dark" | "inherit" via CSS variables.
  */
-declare function RelatedArticles({ articles, title, limit, onArticleClick, className, }: RelatedArticlesProps): react_jsx_runtime.JSX.Element | null;
+declare function RelatedArticles({ articles, title, limit, onArticleClick, className, theme, }: RelatedArticlesProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Generate Next.js App Router Metadata object from an Article.
@@ -372,4 +410,4 @@ declare function SeoMetaBridge({ article, siteUrl, }: {
     siteUrl?: string;
 }): react_jsx_runtime.JSX.Element;
 
-export { type Article, ArticleFeed, type ArticleFeedProps, type ArticleFilters, type ArticleHeading, type ArticleListItem, ArticlePage, type ArticlePageProps, type Category, type ClusterInfo, ContentClient, type DsaContentConfig, DsaContentProvider, type DsaContentProviderProps, FaqBlock, type FaqBlockProps, type FaqItem, type InternalLink, type PaginatedResponse, RelatedArticles, type RelatedArticlesProps, SeoMetaBridge, type SitemapEntry, type UseArticleListState, type UseArticleState, type UseArticlesState, type UseCategoriesState, generateArticleMetadata, useArticle, useArticles, useCategories, useDsaContent, useRelatedArticles };
+export { type Article, ArticleFeed, type ArticleFeedProps, type ArticleFilters, type ArticleHeading, type ArticleListItem, ArticlePage, type ArticlePageProps, type ArticleTheme, type Category, type ClusterInfo, ContentClient, type DsaContentConfig, DsaContentProvider, type DsaContentProviderProps, FaqBlock, type FaqBlockProps, type FaqItem, type InternalLink, type PaginatedResponse, RelatedArticles, type RelatedArticlesProps, SeoMetaBridge, type SitemapEntry, type UseArticleListState, type UseArticleState, type UseArticlesState, type UseCategoriesState, generateArticleMetadata, useArticle, useArticles, useCategories, useDsaContent, useRelatedArticles };

package/dist/index.d.ts

@@ -272,17 +272,22 @@ interface ArticleFeedProps {
     showMeta?: boolean;
     onArticleClick?: (slug: string) => void;
     className?: string;
+    /** "light" | "dark" | "inherit" — sets CSS variable defaults. Use "inherit" to control via your own CSS vars. */
+    theme?: 'light' | 'dark' | 'inherit';
     renderArticle?: (article: ArticleListItem) => React.ReactNode;
 }
 /**
  * Renders a grid or list of article cards.
+ * Supports theme="light" | "dark" | "inherit" via CSS variables.
  *
- * ```tsx
- * <ArticleFeed articles={articles} layout="grid" columns={3} onArticleClick={(slug) => router.push(`/blog/${slug}`)} />
- * ```
+ * CSS variables (override in your own CSS for full control):
+ *   --dsa-text, --dsa-text-muted, --dsa-text-faint,
+ *   --dsa-card-bg, --dsa-card-border,
+ *   --dsa-badge-bg, --dsa-badge-text, --dsa-hover-shadow
  */
-declare function ArticleFeed({ articles, layout, columns, showExcerpt, showImage, showMeta, onArticleClick, className, renderArticle, }: ArticleFeedProps): react_jsx_runtime.JSX.Element;
+declare function ArticleFeed({ articles, layout, columns, showExcerpt, showImage, showMeta, onArticleClick, className, theme, renderArticle, }: ArticleFeedProps): react_jsx_runtime.JSX.Element;
 
+type ArticleTheme = 'light' | 'dark' | 'inherit';
 interface ArticlePageProps {
     article: Article;
     showFaq?: boolean;
@@ -292,6 +297,22 @@ interface ArticlePageProps {
     relatedArticles?: ArticleListItem[];
     onRelatedClick?: (slug: string) => void;
     className?: string;
+    /** Extra class(es) on the `<div>` that wraps `content_html`. */
+    contentClassName?: string;
+    /**
+     * `"light"` / `"dark"` — SDK applies inline styles + CSS vars + built-in prose rules.
+     * `"inherit"` — SDK applies NO inline styles; only CSS classes and
+     *  `data-*` attributes are rendered so the host site has full control.
+     *
+     * In all modes the content body div has:
+     * - `className="dsa-article-body"`
+     * - `data-dsa-article-body`
+     *
+     * @default "light"
+     */
+    theme?: ArticleTheme;
+    /** Disable built-in prose styles injected via `<style>`. Works only in light/dark themes. */
+    disableProseStyles?: boolean;
     components?: {
         H1?: React.ComponentType<{
             children: React.ReactNode;
@@ -305,13 +326,32 @@ interface ArticlePageProps {
     };
 }
 /**
- * Renders a full article page with optional TOC, FAQ, and related articles.
+ * Full article page with optional TOC, FAQ, related articles, and JSON-LD.
+ *
+ * **light / dark** — SDK applies inline styles with `--dsa-*` CSS variable
+ * overrides, plus built-in prose rules for the article body.
+ *
+ * **inherit** — SDK renders only semantic HTML with stable CSS classes
+ * and `data-*` attributes. No inline styles, no injected `<style>`.
+ *
+ * ### Stable CSS selectors (always present)
+ *
+ * | Element | Class | Data attribute |
+ * |---------|-------|----------------|
+ * | Root    | `className` prop | `data-dsa-theme` |
+ * | Body    | `dsa-article-body` + `contentClassName` | `data-dsa-article-body` |
+ * | TOC     | `dsa-toc` | `data-dsa-toc` |
+ * | Meta    | `dsa-meta` | `data-dsa-meta` |
  *
  * ```tsx
- * <ArticlePage article={article} showTableOfContents showFaq />
+ * // Works out of the box
+ * <ArticlePage article={article} />
+ *
+ * // Inherit — host site provides all styles
+ * <ArticlePage article={article} theme="inherit" contentClassName="prose dark:prose-invert" />
  * ```
  */
-declare function ArticlePage({ article, showFaq, showTableOfContents, showMeta, showRelated, relatedArticles, onRelatedClick, className, components, }: ArticlePageProps): react_jsx_runtime.JSX.Element;
+declare function ArticlePage({ article, showFaq, showTableOfContents, showMeta, showRelated, relatedArticles, onRelatedClick, className, contentClassName, theme, disableProseStyles, components, }: ArticlePageProps): react_jsx_runtime.JSX.Element;
 
 interface FaqBlockProps {
     items: FaqItem[];
@@ -319,15 +359,14 @@ interface FaqBlockProps {
     defaultOpen?: boolean;
     className?: string;
     title?: string;
+    /** "light" | "dark" | "inherit" */
+    theme?: 'light' | 'dark' | 'inherit';
 }
 /**
- * FAQ block with optional collapse behavior and Schema.org FAQPage markup.
- *
- * ```tsx
- * <FaqBlock items={article.faq} collapsible />
- * ```
+ * FAQ block with Schema.org FAQPage markup.
+ * Supports theme="light" | "dark" | "inherit" via CSS variables.
  */
-declare function FaqBlock({ items, collapsible, defaultOpen, className, title, }: FaqBlockProps): react_jsx_runtime.JSX.Element | null;
+declare function FaqBlock({ items, collapsible, defaultOpen, className, title, theme, }: FaqBlockProps): react_jsx_runtime.JSX.Element | null;
 
 interface RelatedArticlesProps {
     articles: ArticleListItem[];
@@ -335,15 +374,14 @@ interface RelatedArticlesProps {
     limit?: number;
     onArticleClick?: (slug: string) => void;
     className?: string;
+    /** "light" | "dark" | "inherit" */
+    theme?: 'light' | 'dark' | 'inherit';
 }
 /**
  * Related articles widget.
- *
- * ```tsx
- * <RelatedArticles articles={related} onArticleClick={(slug) => router.push(`/blog/${slug}`)} />
- * ```
+ * Supports theme="light" | "dark" | "inherit" via CSS variables.
  */
-declare function RelatedArticles({ articles, title, limit, onArticleClick, className, }: RelatedArticlesProps): react_jsx_runtime.JSX.Element | null;
+declare function RelatedArticles({ articles, title, limit, onArticleClick, className, theme, }: RelatedArticlesProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Generate Next.js App Router Metadata object from an Article.
@@ -372,4 +410,4 @@ declare function SeoMetaBridge({ article, siteUrl, }: {
     siteUrl?: string;
 }): react_jsx_runtime.JSX.Element;
 
-export { type Article, ArticleFeed, type ArticleFeedProps, type ArticleFilters, type ArticleHeading, type ArticleListItem, ArticlePage, type ArticlePageProps, type Category, type ClusterInfo, ContentClient, type DsaContentConfig, DsaContentProvider, type DsaContentProviderProps, FaqBlock, type FaqBlockProps, type FaqItem, type InternalLink, type PaginatedResponse, RelatedArticles, type RelatedArticlesProps, SeoMetaBridge, type SitemapEntry, type UseArticleListState, type UseArticleState, type UseArticlesState, type UseCategoriesState, generateArticleMetadata, useArticle, useArticles, useCategories, useDsaContent, useRelatedArticles };
+export { type Article, ArticleFeed, type ArticleFeedProps, type ArticleFilters, type ArticleHeading, type ArticleListItem, ArticlePage, type ArticlePageProps, type ArticleTheme, type Category, type ClusterInfo, ContentClient, type DsaContentConfig, DsaContentProvider, type DsaContentProviderProps, FaqBlock, type FaqBlockProps, type FaqItem, type InternalLink, type PaginatedResponse, RelatedArticles, type RelatedArticlesProps, SeoMetaBridge, type SitemapEntry, type UseArticleListState, type UseArticleState, type UseArticlesState, type UseCategoriesState, generateArticleMetadata, useArticle, useArticles, useCategories, useDsaContent, useRelatedArticles };