@roottale/cms-renderer-next 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @roottale/cms-renderer-next
 
+## 0.3.0
+
+### Minor Changes
+
+- 1e738fd: Add design token auto-application for external sites.
+
+  admin `mysite.roottale.com → 디자인` 에서 저장한 색·글꼴·둥글기를 외부 사이트의
+  RootTale 블로그 컴포넌트가 자동으로 가져와 적용한다.
+
+  **`@roottale/cms-client`** — 신규 `fetchTheme()` + `RootTaleTheme` 타입 export.
+  `GET /v1/cms/public/theme` 엔드포인트 호출 (Bearer rtlk*cust*\*).
+
+  **`@roottale/cms-renderer-next`** — `<RootTaleBlogList>` / `<RootTaleBlogPost>` 가
+  신규 `theme` prop 지원. 동시에 `<RootTaleThemeProvider>` 컴포넌트로 부모에서 1회
+  fetch 한 뒤 자식 컴포넌트가 변수를 상속하는 패턴도 지원.
+
+  ```tsx
+  // 자동 fetch (기본) — 별도 설정 없이 admin 토큰 적용
+  <RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} />
+
+  // 명시 override
+  <RootTaleBlogList
+    apiKey={process.env.ROOTTALE_API_KEY!}
+    theme={{ colors: { primary: "#0070f3" } }}
+  />
+
+  // 부모 1회 fetch → 자식들 상속 (다중 컴포넌트 페이지에서 호출 1회로 축소)
+  const theme = await fetchTheme({ apiKey });
+  <RootTaleThemeProvider theme={theme}>
+    <RootTaleBlogList apiKey={apiKey} theme={null} />
+    <RootTaleBlogPost apiKey={apiKey} slugOrId="..." theme={null} />
+  </RootTaleThemeProvider>
+  ```
+
+  **`@roottale/cms-renderer-astro`** — `renderBlogList` / `renderBlogPost` 에 동일
+  의미의 `theme` 옵션. style="..." 속성으로 CSS 변수 주입 (서버 측 escape 보강).
+
+  `theme` prop semantics:
+
+  - `undefined` → 자동 fetch
+  - `RootTaleTheme` → 호출자 override
+  - `null` → 자동 fetch 건너뜀 (부모 `RootTaleThemeProvider` 활용 시)
+
+  fetch 실패는 비치명적 — CSS fallback 으로 graceful degrade.
+
+### Patch Changes
+
+- Updated dependencies [a7444e2]
+- Updated dependencies [1e738fd]
+  - @roottale/cms-client@0.2.0
+
+## 0.2.1
+
+### Patch Changes
+
+- dist build 도입 — `.ts` 소스 직접 publish 폐기.
+
+  기존 (0.1.0/0.2.0): `exports` 가 `./src/server.ts` 가리킴 → 외부 Next.js
+  Turbopack/Webpack 이 npm 모듈에서 TS 자동 컴파일 안 해 build 실패 (customer
+  site 가 `transpilePackages` 명시해야 했음).
+
+  수정: `tsup` 으로 `dist/*.js` + `dist/*.d.ts` (ESM) 출력. `exports` 가 dist
+  가리킴. customer site 측 `transpilePackages` 불필요.
+
+  - `cms-client@0.1.1` — ESM `dist/server.js` + types
+  - `cms-core@0.2.1` — ESM `dist/index.js` + types
+  - `cms-renderer-next@0.2.1` — ESM `dist/{server,index}.js` + types + `dist/cms-public.css`
+    - `server.tsx` 의 `import "./styles/cms-public.css"` 제거 — customer 가
+      `@roottale/cms-renderer-next/styles` 로 명시 import (README 정합).
+  - `cms-renderer-astro@0.2.1` — ESM `dist/index.js` + types
+
+  후속 (customer site PR):
+
+  - roottale-web / kjmtax / theoneulsan 의 `next.config` 의 `transpilePackages`
+    에서 `@roottale/cms-*` 제거. `pnpm update @roottale/cms-client @roottale/cms-renderer-next` 로 patch 적용.
+
+- Updated dependencies
+  - @roottale/cms-core@0.2.1
+  - @roottale/cms-client@0.1.1
+
 ## 0.2.0
 
 ### Minor Changes
@@ -9,6 +89,7 @@
   ADR-0029 §0 amend (publish-only dormant) 는 design system 5 패키지 (tokens, ui-css, ui-react, ui-astro, ui-admin) 에 한정. cms-\* 는 별도 정책 — 실행 로직 + 5-20 외부 customer site 직접 의존 + schema 호환 + 보안 경계. Codex consult verdict (session `019e6703…`) 정합.
 
   변경:
+
   - 4 패키지 `private: true` 해제 + `publishConfig.access: "public"`
   - `@roottale/cms-renderer-next` 에서 `@roottale/tokens/tokens.css` import 제거 — 모든 `--rt-*` 변수에 static fallback 으로 self-contained. tokens dormant 와 무관하게 동작.
   - `RootTaleLeadForm` RSC 추가 — 외부 사이트 진단 폼 (`vertical`/`redirectUrl` props, medical 국외이전 동의 자동).
@@ -17,6 +98,7 @@
   - `cms-renderer-astro` 도 동등 surface 유지를 위해 동시 publish
 
   후속:
+
   - ADR 신규 — cms-\* publish 정책 (별 PR)
   - Astro 측 LeadForm 컴포넌트 (현재 `@roottale/ui-astro` 위치, `cms-renderer-astro` 로 이동 검토)
 

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server.d.ts

@@ -0,0 +1,228 @@
+import { ReactElement, ReactNode } from 'react';
+import { CmsPostContent, CmsPostType, RootTaleTheme } from '@roottale/cms-client/server';
+export { RootTaleTheme } from '@roottale/cms-client/server';
+import { Block } from '@roottale/cms-core';
+
+/**
+ * `<RootTalePostCard>` — server-only summary card for a single CmsPostContent.
+ *
+ * Building block for `<RootTaleBlogList>` (and customer-side custom grids).
+ * Pure SSR — anchor + title + meta + excerpt. Featured image is left out for
+ * now: `CmsPostContent` only carries `featuredMediaId`, not a public URL.
+ * Media URL resolution belongs in a separate slice once `cms-client` exposes
+ * it (ADR-0034 §4 media followup — CF Images variants).
+ */
+
+interface RootTalePostCardProps {
+    post: CmsPostContent;
+    /** Customer-side URL builder. Defaults to `/blog/${slug}`. */
+    href?: (post: CmsPostContent) => string;
+}
+declare function RootTalePostCard(props: RootTalePostCardProps): ReactElement;
+
+/**
+ * `@roottale/cms-renderer/toc` — Tiptap doc → TOC entries + heading id injection.
+ *
+ * Server-only utility. Walks a Tiptap JSON doc, extracts H2/H3 headings, and
+ * derives stable kebab-case ids (Korean-safe). The companion `attachHeadingIds`
+ * mutates a shallow clone of the doc so renderers can emit `<h2 id="...">`
+ * anchors that match what `<RootTaleTableOfContents>` links to.
+ *
+ * Internal ancestor: `roottale-internal/packages/cms-renderer/src/toc.ts`
+ * (HTML-string based, vendored snapshot). Ported to Tiptap-JSON because the
+ * platform renderer no longer round-trips through HTML before render.
+ */
+interface TocEntry {
+    level: 2 | 3;
+    text: string;
+    id: string;
+}
+declare function headingToId(text: string): string;
+declare function extractToc(doc: Record<string, unknown>): TocEntry[];
+/**
+ * Returns a shallow-cloned Tiptap doc where each H2/H3 carries the matching
+ * `attrs.id` from `entries` (same order as `extractToc` returns). Existing
+ * `id` attrs are overwritten so renderer + TOC always agree on anchors.
+ */
+declare function attachHeadingIds(doc: Record<string, unknown>, entries: TocEntry[]): Record<string, unknown>;
+
+/**
+ * `<RootTaleTableOfContents>` — server-only anchor list for blog posts.
+ *
+ * Pure SSR. Renders `<nav>` + ordered anchors that link to `#<id>` slots
+ * emitted by `attachHeadingIds`. No scroll-spy here — that requires an
+ * `IntersectionObserver` which only exists in the browser; a client-island
+ * variant can layer on top later without changing the data contract.
+ *
+ * Internal ancestor: `roottale-internal/packages/cms-renderer/src/TableOfContents.tsx`
+ * (had `'use client'` + IntersectionObserver). Stripped to server-safe form per
+ * the platform renderer contract (no `'use client'` boundary — ADR-0023 §5.3).
+ */
+
+interface RootTaleTableOfContentsProps {
+    entries: TocEntry[];
+    title?: string;
+}
+declare function RootTaleTableOfContents(props: RootTaleTableOfContentsProps): ReactElement | null;
+
+/**
+ * `<RootTaleFloatingCta>` — fixed-position call-to-action stack.
+ *
+ * Server-only (anchors only, no state). External targets (`kakao` / `custom`)
+ * open in a new tab with `rel="noopener noreferrer"`; tel/contact stay in the
+ * same tab so iOS/Android can trigger the dialer / mailto handler.
+ *
+ * Internal ancestor: `roottale-internal/packages/cms-renderer/src/FloatingCta.tsx`.
+ */
+
+type CtaButtonType = "phone" | "contact" | "kakao" | "custom";
+interface CtaButton {
+    type: CtaButtonType;
+    label: string;
+    href: string;
+    /** Optional override icon (emoji or short text). */
+    icon?: string;
+}
+type FloatingCtaPosition = "bottom-right" | "bottom-left" | "bottom-center";
+interface RootTaleFloatingCtaProps {
+    buttons: CtaButton[];
+    position?: FloatingCtaPosition;
+}
+declare function RootTaleFloatingCta(props: RootTaleFloatingCtaProps): ReactElement | null;
+
+/**
+ * `@roottale/cms-renderer-next` — RootTaleLeadForm RSC.
+ *
+ * 외부 고객 사이트(roottale.com, 고객사 외주)의 진단 신청 폼. HTML form POST →
+ * tenant-api `/v1/public/inquiries`. cross-origin POST 는 CORS 불필요 (HTML form
+ * submission). PII 는 server 측에서 암호화 후 `inquiries` insert, 302 redirect.
+ *
+ * vertical prop:
+ * - 미지정 = "분야 선택" select 노출 (consulting/medical/tax/legal)
+ * - 지정   = hidden input + 표시 라벨 + vertical 별 추가 필드
+ *   (medical = 국외이전 동의 — ADR-0018)
+ *
+ * redirectPath prop:
+ * - 외부 사이트가 폼 제출 후 돌아갈 path (API 가 allowlist 검증, ?ok=1 / ?err=*)
+ *
+ * 0 JS RSC. customer-facing className 전체 `.rt-cms-*` prefix, scoped via
+ * `[data-roottale-cms]` (cms-public.css). customer override 자유.
+ */
+
+type LeadFormVertical = "consulting" | "medical" | "tax" | "legal";
+interface RootTaleLeadFormProps {
+    /** lead intake endpoint. 예: `https://api.roottale.com/v1/public/inquiries` */
+    action: string;
+    /**
+     * vertical 고정. 미지정 시 select 노출.
+     * `medical` 일 때 국외이전 동의 체크박스 추가 (ADR-0018).
+     */
+    vertical?: LeadFormVertical;
+    /**
+     * 폼 제출 후 API가 돌려보낼 절대 URL.
+     * tenant-api `LEAD_INTAKE_ALLOWED_ORIGINS` allowlist 검증. fail = fallback.
+     * 미지정 시 tenant-api env의 LEAD_INTAKE_REDIRECT_BASE 사용.
+     */
+    redirectUrl?: string;
+    heading?: string;
+    description?: string;
+    submitLabel?: string;
+    /** 추가 클래스 (customer 디자인 hook). */
+    className?: string;
+}
+declare function RootTaleLeadForm(props: RootTaleLeadFormProps): ReactElement;
+
+/**
+ * 단일 block 을 ReactElement 로 변환. `block-to-html.ts` 와 동일 분기.
+ */
+declare function renderBlock(block: Block, key?: number): ReactElement;
+/** Block tree 전체를 React element 배열로 직렬화. */
+declare function renderBlocks(blocks: readonly Block[]): ReactElement[];
+
+/**
+ * `@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;
+}): ReactElement;
+type RootTaleBlogListProps = {
+    apiKey: string;
+    baseUrl?: string;
+    limit?: number;
+    /** Filter by post type (`post` or `page`). Default = `post` only (blog list 의도). */
+    type?: CmsPostType;
+    /** Build a customer-side URL for a single post. Defaults to `/blog/${slug}`. */
+    postHref?: (post: CmsPostContent) => string;
+    /** Rendered when the tenant has no published posts yet. */
+    emptyMessage?: string;
+    /**
+     * RootTale 디자인 토큰. 생략 시 admin /design 에서 저장한 값을 자동 fetch.
+     * `null` 을 명시하면 자동 fetch 도 건너뛰고 CSS fallback 사용 (부모
+     * `<RootTaleThemeProvider>` 가 변수를 이미 설정한 경우 유용).
+     */
+    theme?: RootTaleThemeInput;
+};
+declare function RootTaleBlogList(props: RootTaleBlogListProps): Promise<ReactElement>;
+type RootTaleBlogPostProps = {
+    apiKey: string;
+    slugOrId: string;
+    baseUrl?: string;
+    /** Rendered when the slug is not found or not published. */
+    notFoundElement?: ReactElement;
+    /**
+     * When true, prepends an auto-derived `<RootTaleTableOfContents>` before
+     * the article body (H2/H3 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;
+    /** See `RootTaleBlogListProps['theme']`. */
+    theme?: RootTaleThemeInput;
+};
+declare function RootTaleBlogPost(props: RootTaleBlogPostProps): Promise<ReactElement>;
+
+export { type CtaButton, type CtaButtonType, type FloatingCtaPosition, type LeadFormVertical, RootTaleBlogList, type RootTaleBlogListProps, RootTaleBlogPost, type RootTaleBlogPostProps, RootTaleFloatingCta, type RootTaleFloatingCtaProps, RootTaleLeadForm, type RootTaleLeadFormProps, RootTalePostCard, type RootTalePostCardProps, RootTaleTableOfContents, type RootTaleTableOfContentsProps, type RootTaleThemeInput, RootTaleThemeProvider, type TocEntry, attachHeadingIds, extractToc, headingToId, renderBlock, renderBlocks };