chaingrow-blog 0.2.2 → 0.7.0

package/dist/blog-cards-D1j7ZqHK.d.ts

@@ -0,0 +1,123 @@
+import { B as Blog, F as FaqItem, a as Block, E as EmbeddedMedia } from './types-DvkCm1rh.js';
+
+/**
+ * Consumer-supplied extras for BlogPosting. Everything is optional — the
+ * SDK doesn't know the customer's base URL, organisation name, or author
+ * identity, so it just omits what it isn't told. Schema.org treats
+ * `author`, `publisher`, and `url` as recommended but not required.
+ */
+type BlogJsonLdOptions = {
+    /** Absolute URL of the blog page (e.g. `https://example.com/blog/my-post`). */
+    url?: string;
+    author?: {
+        name: string;
+        type?: 'Person' | 'Organization';
+        url?: string;
+    };
+    publisher?: {
+        name: string;
+        logo?: string;
+    };
+};
+/**
+ * Build a Schema.org `BlogPosting` JSON-LD object from a chaingrow Blog.
+ * Fields that aren't present on the Blog (description, og_image, …) are
+ * omitted entirely so the resulting JSON has no `undefined` junk.
+ */
+declare function buildBlogPostingSchema(blog: Blog, opts?: BlogJsonLdOptions): Record<string, unknown>;
+/**
+ * Build a Schema.org `FAQPage` JSON-LD object from chaingrow's `{question, answer}[]`
+ * pairs. Returns `null` for empty input so callers can skip it with a single
+ * `if (faqSchema) items.push(faqSchema)` / `filter(Boolean)`.
+ */
+declare function buildFAQPageSchema(faq: FaqItem[] | null | undefined): Record<string, unknown> | null;
+/**
+ * Combines BlogPosting + FAQPage + any LLM-generated `structured_data.jsonLd`
+ * extras into a flat array ready for `@graph`. Tolerant of missing/malformed
+ * `structured_data` — if the backend ever sends something unexpected we just
+ * skip it rather than crashing the consumer's page.
+ */
+declare function buildBlogJsonLd(blog: Blog, opts?: BlogJsonLdOptions): Record<string, unknown>[];
+/** Schema-org context string — exposed so `<JsonLdGraph>` and any
+ *  bring-your-own renderer use the same value. */
+declare const SCHEMA_ORG_CONTEXT: "https://schema.org";
+
+/**
+ * Compute the block-index insertion point for each media item when
+ * distributing `mediaCount` attachments across `blockCount` blocks.
+ *
+ * Formula: media `i` goes at insertion index `floor(i * blockCount / mediaCount)`.
+ * An insertion index of `0` means "before block 0" (top of body); `blockCount`
+ * means "after the last block".
+ *
+ * Examples (blockCount = 10):
+ *   mediaCount = 1  →  [0]           (single media at top)
+ *   mediaCount = 2  →  [0, 5]        (top + middle)
+ *   mediaCount = 3  →  [0, 3, 6]     (top, 1/3, 2/3)
+ *   mediaCount = 4  →  [0, 2, 5, 7]  (every quarter)
+ *
+ * When `blockCount` is 0 every media falls at position 0 and stacks at the
+ * top. When two media round to the same position they both land there and
+ * render consecutively; this is deterministic but not always visually ideal
+ * for very small `blockCount / mediaCount` ratios — assume content has
+ * enough blocks to spread across.
+ */
+declare function distributeMediaPositions(blockCount: number, mediaCount: number): number[];
+/** One interleaved slot in a blog's body — either a block or a media item. */
+type InterleavedSlot = {
+    kind: 'block';
+    block: Block;
+    index: number;
+} | {
+    kind: 'media';
+    media: EmbeddedMedia;
+    index: number;
+};
+/**
+ * Walk `blocks` once, splicing in `media` at the positions returned by
+ * `distributeMediaPositions`. Returns a flat array of typed slots that
+ * `<BlogRenderer>` can map over directly. Exposed so consumers who need a
+ * custom layout (e.g. wrapping each section in a `<section>`) can use the
+ * same placement logic without re-implementing it.
+ */
+declare function interleaveMedia(blocks: Block[], media: EmbeddedMedia[] | undefined): InterleavedSlot[];
+
+type BlogCard = {
+    id: string;
+    href: string;
+    title: string;
+    description: string | null;
+    og_image: string | null;
+    published_at: string | null;
+    language?: string;
+};
+type ToBlogCardOptions = {
+    /** URL prefix for the generated `href`. Defaults to `/blog`. */
+    pathPrefix?: string;
+    /**
+     * Full control over the generated `href` — takes precedence over
+     * `pathPrefix`. Use this when the route depends on more than a static
+     * prefix, e.g. locale-prefixed routes:
+     *
+     * ```ts
+     * hrefFor: (blog) =>
+     *   blog.language === 'de' ? `/blog/${blog.slug}` : `/${blog.language}/blog/${blog.slug}`
+     * ```
+     */
+    hrefFor?: (blog: Blog) => string;
+};
+/**
+ * Project a chaingrow `Blog` into the small `BlogCard` shape used by
+ * `<BlogIndex>` and `mergeBlogs`. Hybrid integrators can map their own
+ * legacy posts into the same shape (`extra` prop on `<BlogIndex>`) and
+ * the two sources render through the same Card slot.
+ */
+declare function toBlogCard(blog: Blog, opts?: ToBlogCardOptions): BlogCard;
+/**
+ * Merge a list of chaingrow cards with extra (legacy) cards and return a
+ * single list sorted newest-first by `published_at`. Cards without a
+ * `published_at` sort to the end.
+ */
+declare function mergeBlogs(chaingrow: BlogCard[], extra?: BlogCard[]): BlogCard[];
+
+export { type BlogCard as B, type InterleavedSlot as I, SCHEMA_ORG_CONTEXT as S, type ToBlogCardOptions as T, type BlogJsonLdOptions as a, buildBlogJsonLd as b, buildBlogPostingSchema as c, buildFAQPageSchema as d, distributeMediaPositions as e, interleaveMedia as i, mergeBlogs as m, toBlogCard as t };

package/dist/blog-cards-DPfcmUUD.d.cts

@@ -0,0 +1,123 @@
+import { B as Blog, F as FaqItem, a as Block, E as EmbeddedMedia } from './types-DvkCm1rh.cjs';
+
+/**
+ * Consumer-supplied extras for BlogPosting. Everything is optional — the
+ * SDK doesn't know the customer's base URL, organisation name, or author
+ * identity, so it just omits what it isn't told. Schema.org treats
+ * `author`, `publisher`, and `url` as recommended but not required.
+ */
+type BlogJsonLdOptions = {
+    /** Absolute URL of the blog page (e.g. `https://example.com/blog/my-post`). */
+    url?: string;
+    author?: {
+        name: string;
+        type?: 'Person' | 'Organization';
+        url?: string;
+    };
+    publisher?: {
+        name: string;
+        logo?: string;
+    };
+};
+/**
+ * Build a Schema.org `BlogPosting` JSON-LD object from a chaingrow Blog.
+ * Fields that aren't present on the Blog (description, og_image, …) are
+ * omitted entirely so the resulting JSON has no `undefined` junk.
+ */
+declare function buildBlogPostingSchema(blog: Blog, opts?: BlogJsonLdOptions): Record<string, unknown>;
+/**
+ * Build a Schema.org `FAQPage` JSON-LD object from chaingrow's `{question, answer}[]`
+ * pairs. Returns `null` for empty input so callers can skip it with a single
+ * `if (faqSchema) items.push(faqSchema)` / `filter(Boolean)`.
+ */
+declare function buildFAQPageSchema(faq: FaqItem[] | null | undefined): Record<string, unknown> | null;
+/**
+ * Combines BlogPosting + FAQPage + any LLM-generated `structured_data.jsonLd`
+ * extras into a flat array ready for `@graph`. Tolerant of missing/malformed
+ * `structured_data` — if the backend ever sends something unexpected we just
+ * skip it rather than crashing the consumer's page.
+ */
+declare function buildBlogJsonLd(blog: Blog, opts?: BlogJsonLdOptions): Record<string, unknown>[];
+/** Schema-org context string — exposed so `<JsonLdGraph>` and any
+ *  bring-your-own renderer use the same value. */
+declare const SCHEMA_ORG_CONTEXT: "https://schema.org";
+
+/**
+ * Compute the block-index insertion point for each media item when
+ * distributing `mediaCount` attachments across `blockCount` blocks.
+ *
+ * Formula: media `i` goes at insertion index `floor(i * blockCount / mediaCount)`.
+ * An insertion index of `0` means "before block 0" (top of body); `blockCount`
+ * means "after the last block".
+ *
+ * Examples (blockCount = 10):
+ *   mediaCount = 1  →  [0]           (single media at top)
+ *   mediaCount = 2  →  [0, 5]        (top + middle)
+ *   mediaCount = 3  →  [0, 3, 6]     (top, 1/3, 2/3)
+ *   mediaCount = 4  →  [0, 2, 5, 7]  (every quarter)
+ *
+ * When `blockCount` is 0 every media falls at position 0 and stacks at the
+ * top. When two media round to the same position they both land there and
+ * render consecutively; this is deterministic but not always visually ideal
+ * for very small `blockCount / mediaCount` ratios — assume content has
+ * enough blocks to spread across.
+ */
+declare function distributeMediaPositions(blockCount: number, mediaCount: number): number[];
+/** One interleaved slot in a blog's body — either a block or a media item. */
+type InterleavedSlot = {
+    kind: 'block';
+    block: Block;
+    index: number;
+} | {
+    kind: 'media';
+    media: EmbeddedMedia;
+    index: number;
+};
+/**
+ * Walk `blocks` once, splicing in `media` at the positions returned by
+ * `distributeMediaPositions`. Returns a flat array of typed slots that
+ * `<BlogRenderer>` can map over directly. Exposed so consumers who need a
+ * custom layout (e.g. wrapping each section in a `<section>`) can use the
+ * same placement logic without re-implementing it.
+ */
+declare function interleaveMedia(blocks: Block[], media: EmbeddedMedia[] | undefined): InterleavedSlot[];
+
+type BlogCard = {
+    id: string;
+    href: string;
+    title: string;
+    description: string | null;
+    og_image: string | null;
+    published_at: string | null;
+    language?: string;
+};
+type ToBlogCardOptions = {
+    /** URL prefix for the generated `href`. Defaults to `/blog`. */
+    pathPrefix?: string;
+    /**
+     * Full control over the generated `href` — takes precedence over
+     * `pathPrefix`. Use this when the route depends on more than a static
+     * prefix, e.g. locale-prefixed routes:
+     *
+     * ```ts
+     * hrefFor: (blog) =>
+     *   blog.language === 'de' ? `/blog/${blog.slug}` : `/${blog.language}/blog/${blog.slug}`
+     * ```
+     */
+    hrefFor?: (blog: Blog) => string;
+};
+/**
+ * Project a chaingrow `Blog` into the small `BlogCard` shape used by
+ * `<BlogIndex>` and `mergeBlogs`. Hybrid integrators can map their own
+ * legacy posts into the same shape (`extra` prop on `<BlogIndex>`) and
+ * the two sources render through the same Card slot.
+ */
+declare function toBlogCard(blog: Blog, opts?: ToBlogCardOptions): BlogCard;
+/**
+ * Merge a list of chaingrow cards with extra (legacy) cards and return a
+ * single list sorted newest-first by `published_at`. Cards without a
+ * `published_at` sort to the end.
+ */
+declare function mergeBlogs(chaingrow: BlogCard[], extra?: BlogCard[]): BlogCard[];
+
+export { type BlogCard as B, type InterleavedSlot as I, SCHEMA_ORG_CONTEXT as S, type ToBlogCardOptions as T, type BlogJsonLdOptions as a, buildBlogJsonLd as b, buildBlogPostingSchema as c, buildFAQPageSchema as d, distributeMediaPositions as e, interleaveMedia as i, mergeBlogs as m, toBlogCard as t };

package/dist/chunk-4EKET2DQ.js

@@ -0,0 +1,34 @@
+// src/blog-cards.ts
+var normalizePathPrefix = (s) => {
+  let p = s.trim();
+  if (!p.startsWith("/")) p = "/" + p;
+  while (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+  return p;
+};
+function toBlogCard(blog, opts = {}) {
+  const prefix = normalizePathPrefix(opts.pathPrefix ?? "/blog");
+  return {
+    id: blog.id,
+    href: opts.hrefFor ? opts.hrefFor(blog) : `${prefix}/${blog.slug}`,
+    title: blog.title,
+    description: blog.description,
+    og_image: blog.og_image,
+    published_at: blog.published_at,
+    language: blog.language
+  };
+}
+function mergeBlogs(chaingrow, extra = []) {
+  const combined = [...chaingrow, ...extra];
+  combined.sort((a, b) => {
+    const ta = a.published_at ? Date.parse(a.published_at) : 0;
+    const tb = b.published_at ? Date.parse(b.published_at) : 0;
+    return tb - ta;
+  });
+  return combined;
+}
+
+export {
+  toBlogCard,
+  mergeBlogs
+};
+//# sourceMappingURL=chunk-4EKET2DQ.js.map

package/dist/chunk-4EKET2DQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/blog-cards.ts"],"sourcesContent":["import type { Blog } from './types';\n\nexport type BlogCard = {\n  id: string;\n  href: string;\n  title: string;\n  description: string | null;\n  og_image: string | null;\n  published_at: string | null;\n  language?: string;\n};\n\nexport type ToBlogCardOptions = {\n  /** URL prefix for the generated `href`. Defaults to `/blog`. */\n  pathPrefix?: string;\n  /**\n   * Full control over the generated `href` — takes precedence over\n   * `pathPrefix`. Use this when the route depends on more than a static\n   * prefix, e.g. locale-prefixed routes:\n   *\n   * ```ts\n   * hrefFor: (blog) =>\n   *   blog.language === 'de' ? `/blog/${blog.slug}` : `/${blog.language}/blog/${blog.slug}`\n   * ```\n   */\n  hrefFor?: (blog: Blog) => string;\n};\n\nconst normalizePathPrefix = (s: string): string => {\n  let p = s.trim();\n  if (!p.startsWith('/')) p = '/' + p;\n  while (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);\n  return p;\n};\n\n/**\n * Project a chaingrow `Blog` into the small `BlogCard` shape used by\n * `<BlogIndex>` and `mergeBlogs`. Hybrid integrators can map their own\n * legacy posts into the same shape (`extra` prop on `<BlogIndex>`) and\n * the two sources render through the same Card slot.\n */\nexport function toBlogCard(blog: Blog, opts: ToBlogCardOptions = {}): BlogCard {\n  const prefix = normalizePathPrefix(opts.pathPrefix ?? '/blog');\n  return {\n    id: blog.id,\n    href: opts.hrefFor ? opts.hrefFor(blog) : `${prefix}/${blog.slug}`,\n    title: blog.title,\n    description: blog.description,\n    og_image: blog.og_image,\n    published_at: blog.published_at,\n    language: blog.language,\n  };\n}\n\n/**\n * Merge a list of chaingrow cards with extra (legacy) cards and return a\n * single list sorted newest-first by `published_at`. Cards without a\n * `published_at` sort to the end.\n */\nexport function mergeBlogs(\n  chaingrow: BlogCard[],\n  extra: BlogCard[] = [],\n): BlogCard[] {\n  const combined = [...chaingrow, ...extra];\n  combined.sort((a, b) => {\n    const ta = a.published_at ? Date.parse(a.published_at) : 0;\n    const tb = b.published_at ? Date.parse(b.published_at) : 0;\n    return tb - ta;\n  });\n  return combined;\n}\n"],"mappings":";AA4BA,IAAM,sBAAsB,CAAC,MAAsB;AACjD,MAAI,IAAI,EAAE,KAAK;AACf,MAAI,CAAC,EAAE,WAAW,GAAG,EAAG,KAAI,MAAM;AAClC,SAAO,EAAE,SAAS,KAAK,EAAE,SAAS,GAAG,EAAG,KAAI,EAAE,MAAM,GAAG,EAAE;AACzD,SAAO;AACT;AAQO,SAAS,WAAW,MAAY,OAA0B,CAAC,GAAa;AAC7E,QAAM,SAAS,oBAAoB,KAAK,cAAc,OAAO;AAC7D,SAAO;AAAA,IACL,IAAI,KAAK;AAAA,IACT,MAAM,KAAK,UAAU,KAAK,QAAQ,IAAI,IAAI,GAAG,MAAM,IAAI,KAAK,IAAI;AAAA,IAChE,OAAO,KAAK;AAAA,IACZ,aAAa,KAAK;AAAA,IAClB,UAAU,KAAK;AAAA,IACf,cAAc,KAAK;AAAA,IACnB,UAAU,KAAK;AAAA,EACjB;AACF;AAOO,SAAS,WACd,WACA,QAAoB,CAAC,GACT;AACZ,QAAM,WAAW,CAAC,GAAG,WAAW,GAAG,KAAK;AACxC,WAAS,KAAK,CAAC,GAAG,MAAM;AACtB,UAAM,KAAK,EAAE,eAAe,KAAK,MAAM,EAAE,YAAY,IAAI;AACzD,UAAM,KAAK,EAAE,eAAe,KAAK,MAAM,EAAE,YAAY,IAAI;AACzD,WAAO,KAAK;AAAA,EACd,CAAC;AACD,SAAO;AACT;","names":[]}