@roottale/cms-renderer-next 0.48.0 → 0.51.0

package/dist/server.d.ts

@@ -1,8 +1,9 @@
 import { ReactElement, ReactNode } from 'react';
 import { CmsPostContent, RootTaleTheme, CmsPostType } from '@roottale/cms-client/server';
 export { RootTaleTheme } from '@roottale/cms-client/server';
-import { Block, BindingResolver, RouteCollection } from '@roottale/cms-core';
 export { R as RootTaleCssVars, t as themeToCssVars } from './theme-css-vars-CD3jcEkp.js';
+import { Block, BindingResolver, RouteCollection } from '@roottale/cms-core';
+export { a as BlogCategory, B as BlogCategoryWithCount, c as collectCategories, b as collectCategoriesWithCounts, d as defaultCategoryHref, f as filterPostsByCategory } from './blog-filter-BKCGM0qd.js';
 import '@roottale/ui-react/theme';
 
 /**
@@ -189,319 +190,100 @@ declare function renderBoundBlocks(blocks: readonly Block[], opts?: {
     resolver?: BindingResolver;
 }): ReactElement[];
 
-/**
- * `RootTaleBlogList` 카테고리 필터 — 순수 헬퍼(서버 필터, client JS 불요).
- *
- * SSR-only 정책 유지: 필터는 `?category=<slug>` URL 파라미터로 동작하고(칩 =
- * 서버 렌더 `<a>` 링크), consumer 가 searchParams 의 category 를 `activeCategory`
- * 로 주입한다. hydration 없이 SEO 친화 + 공유 가능한 URL.
- */
-
-interface BlogCategory {
-    name: string;
-    slug: string;
-}
-interface BlogCategoryWithCount extends BlogCategory {
-    count: number;
-}
-/**
- * 글 목록에 등장하는 카테고리를 slug 기준 unique 로 수집. 서버가 보내는 정렬
- * (category → name asc)을 보존하기 위해 처음 등장 순서를 유지한다.
- */
-declare function collectCategories(posts: CmsPostContent[]): BlogCategory[];
-declare function collectCategoriesWithCounts(posts: CmsPostContent[]): BlogCategoryWithCount[];
-/** activeSlug 가 비면 전체 반환. 아니면 그 카테고리를 가진 글만. */
-declare function filterPostsByCategory(posts: CmsPostContent[], activeSlug: string | null | undefined): CmsPostContent[];
-/** 기본 카테고리 링크: 전체 → `/blog`, 특정 → `/blog/categories/<slug>`. */
-declare function defaultCategoryHref(slug: string | null): string;
-
-/**
- * `@roottale/cms-renderer-next/server` — RootTale CMS public-render React Server Components.
- *
- * Drop into any RSC-capable framework (Next.js App Router, Astro server islands,
- * React Router server). Single-line import, SSR-only, no `'use client'` boundary.
- *
- * ```tsx
- * import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
- *
- * export default function BlogPage() {
- *   return <RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} />;
- * }
- * ```
- *
- * Customer site MUST keep `apiKey` server-side. Browser bundle ships zero
- * RootTale credentials (ADR-0023 §5.1 #15).
- *
- * Design tokens auto-apply via the CSS import below. Customers can override
- * any class with their own CSS or Tailwind utilities — scoped selectors use
- * `:where()` to keep specificity at zero (ADR-0023 §5.1 #10).
- */
-
-/**
- * RootTaleBlogList/Post 가 받는 theme prop 의 평가 결과:
- *   - `RootTaleTheme` 객체 → 그대로 CSS 변수로 주입
- *   - `null`             → override 없음 (cms-public.css fallback 그대로)
- *   - `undefined`        → API key 로 자동 fetch (mysite.roottale.com 의 admin /design)
- */
 type RootTaleThemeInput = RootTaleTheme | null | undefined;
-/**
- * RootTale 디자인 토큰을 CSS 변수로 자식 트리에 주입한다. 외부 사이트가
- * 여러 RootTale 컴포넌트를 한 레이아웃에 묶을 때, 컴포넌트마다 같은 토큰을
- * fetch 하지 않도록 부모에서 한 번만 fetch 해서 전달하는 용도.
- *
- * ```tsx
- * const theme = await fetchTheme({ apiKey });
- * <RootTaleThemeProvider theme={theme}>
- *   <RootTaleBlogList apiKey={apiKey} theme={null} />
- *   <RootTaleBlogPost apiKey={apiKey} slugOrId="..." theme={null} />
- * </RootTaleThemeProvider>
- * ```
- *
- * 자식 RootTale 컴포넌트가 `theme={null}` 을 받으면 자체 주입을 건너뛰고
- * 부모의 변수를 그대로 상속. 자식이 `theme` 을 지정하면 자식 변수가 우선.
- */
 declare function RootTaleThemeProvider(props: {
-    theme: RootTaleTheme | null | undefined;
-    children: ReactNode;
+    readonly theme: RootTaleTheme | null | undefined;
+    readonly children: ReactNode;
 }): ReactElement;
+
 type RootTaleBlogListProps = {
     apiKey: string;
     baseUrl?: string;
     limit?: number;
-    /** Filter by post type (`post` or `page`). Default = `post` only (blog list 의도). */
+    /** Filter by post type (`post` or `page`). Default = `post` only. */
     type?: CmsPostType;
-    /**
-     * Build a customer-side URL for a single post. Defaults to `/blog/${slug}`,
-     * 또는 `collections` 를 주면 글의 섹션 basePath 기준(`/notice/${slug}` 등).
-     */
     postHref?: (post: CmsPostContent) => string;
-    /** Rendered when the tenant has no published posts yet. */
     emptyMessage?: string;
-    /**
-     * 단일 섹션(stream)으로 스코프 (ADR-0060). `collections` 와 함께 줘야 동작한다.
-     * 예: `collection="notice"` → 공지 섹션 글만 렌더. **미지정 = 전체** 글(레거시
-     * 단일 블로그). 이 prop 없이 다중 스트림 사이트에서 쓰면 공지·블로그가 한 목록에
-     * 섞여 나오므로(`/blog` 에 공지가 새어 들어옴), 섹션을 나눈 사이트는 각 목록
-     * 페이지에서 반드시 `collection` 으로 스코프해야 한다.
-     *
-     * **서버 필터** (`blog-list-collection-scope.md` §2②) — `collections` 와 함께
-     * 주면 api-core `collection_key=` 파라미터로 fetch 단계에서부터 그 섹션 글만
-     * 가져온다(limit 이 스트림 밖 글에 낭비되지 않음). `postsForCollection` 클라이언트
-     * 필터는 방어선으로 남아 있다 — 판정 시맨틱은 두 층 모두 `resolvePostCollection`
-     * 동일 정의.
-     */
     collection?: string;
-    /**
-     * 섹션 정의 (ADR-0060). `collection` 스코프와 collection-aware `postHref`(글을
-     * 소속 섹션 basePath 로 라우팅) 해석에 쓰인다. admin 에서 동적으로 받으려면
-     * `fetchCollections()` 결과를 넘긴다(`collections.md` 참고).
-     */
     collections?: readonly RouteCollection[];
     /**
-     * **네거티브** 스코프 — `collections` 와 함께 주면 어느 스트림에도 안 속한
-     * ("미소속") 글만 렌더한다(`postsNotInAnyCollection`, `blog-list-collection-scope.md`
-     * §2①). `collection`(포지티브) 과 배타적이며 **동시 지정은 throw**. `collections`
-     * 없이 `excludeCollections` 만 주는 것도 **throw**(조용한 no-op 금지, fail-closed).
-     *
-     * **적용 조건 한정** — `/blog` 가 *선언 컬렉션이 아닌*(미소속 글이 `/blog` 를 받는)
-     * 사이트에서만 쓴다. **`blog` 자체가 선언 컬렉션인 사이트(예: kjmtax — 글의
-     * `collectionKey === "blog"`) 는 반대로 포지티브 `collection="blog"` 가 정경로다.**
-     * 그런 사이트에 `excludeCollections` 를 적용하면 블로그 글까지 전부 "소속 글"로
-     * 걸려 제외되므로 목록이 비게 된다 — 동시 지정 throw 로는 이 오적용을 못 잡는다.
+     * `collection`과 배타적이다. `collections` 없이 지정해도 예외를 던진다.
      */
     excludeCollections?: boolean;
-    /**
-     * 카테고리 필터 칩을 목록 위에 렌더. SSR-only — 칩은 `<a>` 링크이고
-     * `?category=<slug>` URL 파라미터로 동작한다(client JS 불요). consumer 는
-     * searchParams 의 category 를 `activeCategory` 로 주입.
-     */
     showCategoryFilter?: boolean;
-    /** 현재 선택 카테고리 slug. 미지정/빈 값 = 전체. searchParams 에서 주입. */
     activeCategory?: string;
-    /**
-     * 카테고리 칩 링크 URL 빌더. `null` = "전체" 칩. 기본 `defaultCategoryHref`
-     * (전체 → `/blog`, 특정 → `/blog/categories/<slug>` — 사이트에 해당 라우트
-     * 필요, starter `blog/categories/[slug]` 참조). 쿼리 필터(`?category=<slug>`)
-     * 방식을 쓰려면 override.
-     */
     categoryHref?: (slug: string | null) => string;
-    /** "전체" 칩 라벨. 기본 "전체". */
     allCategoriesLabel?: string;
-    /**
-     * 작가 slug 로 글을 필터 — 작가 아카이브(/blog/author/{slug}) 페이지용. 지정 시
-     * 그 작가의 발행 글(post)만 fetch 한다. `fetchAuthors` 로 작가 메타(이름·소개)를
-     * 따로 가져와 페이지 헤더에 쓴다.
-     */
     author?: string;
-    /**
-     * RootTale 디자인 토큰. 생략 시 admin /design 에서 저장한 값을 자동 fetch.
-     * `null` 을 명시하면 자동 fetch 도 건너뛰고 CSS fallback 사용 (부모
-     * `<RootTaleThemeProvider>` 가 변수를 이미 설정한 경우 유용).
-     */
     theme?: RootTaleThemeInput;
-    /**
-     * ADR-0052 A안 (W4-6 PR C1) — 언어판 필터(`fetchPosts` 의 `locale` 그대로 전달).
-     * 미지정 시 서버가 사이트 기본 locale 반환(하위호환). cms-i18n 기본 문자열
-     * (`emptyMessage`/`allCategoriesLabel` 미지정 시)의 locale 해석에도 쓰인다.
-     */
     locale?: string;
 };
 declare function RootTaleBlogList(props: RootTaleBlogListProps): Promise<ReactElement>;
+
 type RootTaleBlogCategoriesProps = {
     apiKey: string;
     baseUrl?: string;
     limit?: number;
-    /** Build a customer-side URL for a category. Defaults to `/blog/categories/<slug>`. */
     categoryHref?: (slug: string) => string;
-    /** Rendered when no categories are attached to published posts yet. */
     emptyMessage?: string;
-    /**
-     * 단일 섹션으로 스코프 (ADR-0060). `collections` 와 함께 줘야 동작. 그 섹션의
-     * `categories`(주제 allowlist) 안에서, 그 섹션에 귀속된 글의 카테고리만 집계한다.
-     * 미지정 = 전체 글의 카테고리.
-     */
     collection?: string;
-    /** 섹션 정의 (ADR-0060). `collection` 스코프에 필요. */
     collections?: readonly RouteCollection[];
-    /** See `RootTaleBlogListProps['theme']`. */
-    theme?: RootTaleThemeInput;
-    /** See `RootTaleBlogListProps['locale']`. */
+    theme?: RootTaleTheme | null | undefined;
     locale?: string;
 };
 declare function RootTaleBlogCategories(props: RootTaleBlogCategoriesProps): Promise<ReactElement>;
+
 type RootTaleBlogPostProps = {
     apiKey: string;
     slugOrId: string;
     baseUrl?: string;
-    /** Rendered when the slug is not found or not published. */
     notFoundElement?: ReactElement;
-    /**
-     * 글 제목 `<h1>` 표시 여부. 페이지가 제목을 직접 출력할 때는 false.
-     * 요약·발행일·작성자 등 나머지 헤더 정보는 그대로 유지한다.
-     */
     showTitle?: boolean;
-    /**
-     * When true, prepends an auto-derived `<RootTaleTableOfContents>` before
-     * the article body (H2-H4 headings only). Default: false — keep markup
-     * stable for customers who already control their own layout.
-     */
     showTableOfContents?: boolean;
-    /** Title shown above the TOC (only when `showTableOfContents`). */
     tableOfContentsTitle?: string;
-    /**
-     * 글 하단에 같은 카테고리 최근 글을 N개 노출 (0 = off, 기본 0 — 기존 마크업 보존).
-     * 현재 글에 카테고리가 없거나 후보가 없으면 렌더되지 않는다.
-     */
     relatedPostsCount?: number;
-    /** 관련 글 섹션 제목. 기본 "관련 글". */
     relatedPostsTitle?: string;
-    /** 관련 글 링크 빌더 — 미지정 시 collections 라우팅 또는 `/blog/{slug}`. */
     postHref?: (post: CmsPostContent) => string;
-    /** 다중 스트림 라우팅(ADR-0060) — 관련 글 링크 해석에 사용. */
     collections?: readonly RouteCollection[];
-    /**
-     * W5-2 — 양식(필드 그룹) 스칼라 값을 연관 박스 아래 정보 패널로 렌더.
-     * 라벨·타입은 서버 동봉 `fieldsMeta` 를 사용 — 렌더러는 vertical 지식 없음.
-     * relationship 계열은 연관 박스가 담당하므로 제외. 표시할 값이 하나도 없으면
-     * 패널 자체 미렌더(빈 껍데기 금지). 기본 false — 기존 소비자 마크업 불변.
-     */
     showFieldFacts?: boolean;
-    /** See `RootTaleBlogListProps['theme']`. */
     theme?: RootTaleThemeInput;
-    /** See `RootTaleBlogListProps['locale']`. `fetchPost`/관련 글 fetch 양쪽에 적용. */
     locale?: string;
-    /**
-     * 작가 페이지 링크 빌더 — `post.authorSlug` 가 있을 때 헤더 메타·저자 카드의
-     * 작성자 이름을 `<a>` 로 감싸는 데 사용. 기본 `/blog/author/{slug}`.
-     */
     authorHref?: (slug: string) => string;
-    /**
-     * 시각 브레드크럼 + `BreadcrumbList` JSON-LD (avcd 구조). 기본 off — 기존
-     * 마크업 보존 관례(다른 opt-in prop 과 동일). `siteUrl` 이 있으면 JSON-LD 도
-     * 함께 emit, 없으면 시각 브레드크럼만 렌더.
-     */
     breadcrumb?: BlogPostBreadcrumbOptions;
 };
-/** `RootTaleBlogPostProps['breadcrumb']` — 상세는 필드별 JSDoc 참조. */
 interface BlogPostBreadcrumbOptions {
-    /** JSON-LD 절대 URL 조립용. 없으면 시각 브레드크럼만(JSON-LD 미emit). */
     siteUrl?: string;
-    /** 기본 "홈". */
     homeLabel?: string;
-    /** 기본 "/". */
     homeHref?: string;
-    /** 기본 "블로그". */
     listLabel?: string;
-    /**
-     * 기본 "/blog". `collections` 가 있으면 글의 소속 섹션 basePath 로 자동 해석을
-     * 시도(공지→/notice 등) — `RootTaleBlogPostProps['collections']` 필요.
-     */
     listHref?: string;
-    /**
-     * 카테고리 세그먼트 포함 여부. 기본 true — 글의 첫 category term 을 쓴다.
-     * 카테고리가 없으면 있어도 자동 생략.
-     */
     showCategory?: boolean;
-    /** 카테고리 링크 빌더. 기본 `defaultCategoryHref`(= `/blog/categories/{slug}`). */
     categoryHref?: (slug: string) => string;
 }
+
 declare function RootTaleBlogPost(props: RootTaleBlogPostProps): Promise<ReactElement>;
+
 declare function RootTaleFaqJsonLd({ doc, }: {
-    doc: unknown;
+    readonly doc: unknown;
 }): ReactElement | null;
+
 type RootTalePageProps = {
     apiKey: string;
-    /** Page slug (kebab-case) or UUIDv7 id. */
     slugOrId: string;
     baseUrl?: string;
-    /** Rendered when the slug is not found or not published. */
     notFoundElement?: ReactElement;
-    /**
-     * Render the page title as `<h1>`. Default true — set false when the
-     * customer layout already owns the heading.
-     */
     showTitle?: boolean;
-    /** See `RootTaleBlogListProps['theme']`. */
     theme?: RootTaleThemeInput;
-    /** See `RootTaleBlogListProps['locale']`. */
     locale?: string;
 };
-/**
- * 고정 페이지(posts type='page') 렌더러 — RootTaleBlogPost 의 경량판.
- * 날짜·작성자·author card·blog settings 등 블로그 chrome 없이
- * 제목 + 본문만 그린다. 회사 소개·서비스·이용약관 류의 페이지 용도.
- *
- * ```tsx
- * // app/[slug]/page.tsx
- * export default async function CmsPage({ params }) {
- *   const { slug } = await params;
- *   return <RootTalePage apiKey={process.env.ROOTTALE_API_KEY!} slugOrId={slug} />;
- * }
- * ```
- */
 declare function RootTalePage(props: RootTalePageProps): Promise<ReactElement>;
-/**
- * Minimal Tiptap doc renderer. Walks the Tiptap doc tree and emits semantic
- * HTML. This is intentionally tiny — richer extensions (image asset URL
- * resolution, TableOfContents, FloatingCta) belong in followup §5.7 #5.
- *
- * Browser-side sanitization is unnecessary here because output is rendered
- * server-side from data the customer-trusted API returned. If the customer
- * site federates with untrusted authors later, layer a sanitizer in front
- * of this component.
- */
-declare function RenderTiptap({ doc, fields, apiKey, baseUrl, }: {
-    doc: Record<string, unknown>;
-    /**
-     * ADR-0041 D3 — 공개 API `post.fields` (포맷된 커스텀 필드 값). 전달 시
-     * 블록 바인딩(`roottale/field`)을 필드 값으로 치환 — 값 없으면 본문이
-     * fallback 으로 그대로 렌더. astro `renderTiptapDoc(doc, { fields })` 동등.
-     */
-    fields?: Record<string, unknown> | null;
-    /** Enables cms-bound section nodes (`blog-list`, `lead-form`, `contact`). */
-    apiKey?: string;
-    /** Optional RootTale API base URL for cms-bound section fetches. */
-    baseUrl?: string;
-}): ReactElement;
 
-export { type BlogCategory, type BlogCategoryWithCount, type BlogPostBreadcrumbOptions, type CtaButton, type CtaButtonType, type FloatingCtaPosition, type LeadFormVertical, RenderTiptap, RootTaleBlogCategories, type RootTaleBlogCategoriesProps, RootTaleBlogList, type RootTaleBlogListProps, RootTaleBlogPost, type RootTaleBlogPostProps, RootTaleFaqJsonLd, RootTaleFloatingCta, type RootTaleFloatingCtaProps, RootTaleLeadForm, type RootTaleLeadFormProps, RootTalePage, type RootTalePageProps, RootTalePostCard, type RootTalePostCardProps, RootTaleTableOfContents, type RootTaleTableOfContentsProps, type RootTaleThemeInput, RootTaleThemeProvider, type TocEntry, attachHeadingIds, collectCategories, collectCategoriesWithCounts, defaultCategoryHref, extractToc, filterPostsByCategory, headingToId, renderBlock, renderBlocks, renderBoundBlocks };
+type RenderTiptapProps = {
+    readonly doc: Record<string, unknown>;
+    readonly fields?: Record<string, unknown> | null;
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+};
+declare function RenderTiptap({ doc, fields, apiKey, baseUrl, }: RenderTiptapProps): ReactElement;
+
+export { type BlogPostBreadcrumbOptions, type CtaButton, type CtaButtonType, type FloatingCtaPosition, type LeadFormVertical, RenderTiptap, RootTaleBlogCategories, type RootTaleBlogCategoriesProps, RootTaleBlogList, type RootTaleBlogListProps, RootTaleBlogPost, type RootTaleBlogPostProps, RootTaleFaqJsonLd, RootTaleFloatingCta, type RootTaleFloatingCtaProps, RootTaleLeadForm, type RootTaleLeadFormProps, RootTalePage, type RootTalePageProps, RootTalePostCard, type RootTalePostCardProps, RootTaleTableOfContents, type RootTaleTableOfContentsProps, type RootTaleThemeInput, RootTaleThemeProvider, type TocEntry, attachHeadingIds, extractToc, headingToId, renderBlock, renderBlocks, renderBoundBlocks };

package/dist/server.js

@@ -17,15 +17,17 @@ import {
   renderBlocks,
   renderBoundBlocks,
   themeToCssVars
-} from "./chunk-LIBSVC4M.js";
+} from "./chunk-2QU4JU46.js";
+import "./chunk-VG6UUF4D.js";
+import "./chunk-QYNEOFL7.js";
 import "./chunk-U5AKACPN.js";
 import "./chunk-LEHHSI6G.js";
-import "./chunk-6MFHA555.js";
-import "./chunk-FZK3EXYZ.js";
+import "./chunk-27RT6B3O.js";
+import "./chunk-YLSQAT6B.js";
+import "./chunk-4RQ3SEDL.js";
 import "./chunk-K62RR4UQ.js";
 import "./chunk-H46JUIHZ.js";
 import "./chunk-ZL2NA3QT.js";
-import "./chunk-VG6UUF4D.js";
 import {
   collectCategories,
   collectCategoriesWithCounts,
@@ -33,8 +35,6 @@ import {
   filterPostsByCategory
 } from "./chunk-U2IM6OCQ.js";
 import "./chunk-UM37DOIK.js";
-import "./chunk-OMXEU4LS.js";
-import "./chunk-YLSQAT6B.js";
 export {
   RenderTiptap,
   RootTaleBlogCategories,