@roottale/cms-core 0.53.0 → 0.55.0

package/dist/index.d.ts

@@ -83,7 +83,8 @@ declare function bindingSrcValue(value: unknown): string | undefined;
  *
  * 설계(codex consult `019ef577` 반영):
  * - **활성화 = `collections.length > 0`.** 빈 배열·미전달 = 레거시 단일 /blog.
- * - `RouteCollection` 은 **라우팅 최소셋**만(key/basePath/categories/feed/archives).
+ * - `RouteCollection` 은 **라우팅 최소셋**만(key/basePath/categories/feed/archives와
+ *   경로 정책) 가진다.
  *   label/layout/icon 등 표시·작성 메타는 templates `CollectionSchema` 에 둔다.
  */
 /** 콘텐츠 스트림 1개 — sitemap/feed/아카이브 파생의 라우팅 단위. */
@@ -118,6 +119,20 @@ interface RouteCollection {
      * — 소속과 상세 URL 존재 여부는 별개(M4 원칙 연장).
      */
     readonly detail?: boolean;
+    /**
+     * 글 상세 주소 형식. `flat`(기본) = `${basePath}/{postSlug}`,
+     * `category` = `${basePath}/{categorySlug}/{postSlug}`.
+     * category 모드는 URL을 하나로 결정해야 하므로 `categoryCardinality: "exactly-one"`
+     * 과 함께 쓴다.
+     */
+    readonly detailPath?: "flat" | "category";
+    /**
+     * 카테고리 허브 주소 형식. `namespaced`(기본) =
+     * `${basePath}/categories/{slug}`, `direct` = `${basePath}/{slug}`.
+     */
+    readonly categoryPath?: "namespaced" | "direct";
+    /** 글에 허용하는 category term 개수. 기본 `multiple`(기존 동작). */
+    readonly categoryCardinality?: "multiple" | "exactly-one";
 }
 /** resolve 입력 — 글의 구조적 최소 형태(cms-client `CmsPostContent` 와 구조 호환). */
 interface RoutablePost {
@@ -149,6 +164,14 @@ declare function resolvePostCollection(post: RoutablePost, collections: readonly
  * (주소 없는 유형)이면 null. slug 는 percent-encoding (한글 slug 안전).
  */
 declare function resolvePostUrl(siteUrl: string, post: RoutablePost, collections: readonly RouteCollection[]): string | null;
+/**
+ * category 기반 상세 주소에 사용할 단일 category slug. collection 에 연결된
+ * category만 세고 정확히 1개일 때만 반환한다. 0개·2개 이상이면 정규 URL을
+ * 임의 선택하지 않고 null 로 닫는다.
+ */
+declare function resolvePostCategorySlug(post: RoutablePost, collection: RouteCollection): string | null;
+/** 카테고리 허브 경로. archives 가 꺼졌거나 주소가 없으면 null. */
+declare function resolveCategoryPath(collection: RouteCollection, categorySlug: string): string | null;
 /**
  * 글의 *경로*(siteUrl 없는 basePath-상대) — 예: "/blog/hello". 소속 스트림이
  * 없거나, `detail: false`(목록 전용 유형) 이거나, `basePath` 가 빈 문자열
@@ -178,6 +201,38 @@ declare function postsNotInAnyCollection<T extends RoutablePost>(posts: readonly
  */
 declare function validateCollections(collections: readonly RouteCollection[]): string[];
 
+/**
+ * 콘텐츠 모델의 계층형 분류 주소 계산기.
+ *
+ * FAQ·도움말·문서처럼 하나의 모델이 여러 단계 분류 허브를 가지는 경우에 쓴다.
+ * 저장소나 프레임워크를 모르며, 공개 API와 ROOT-ADMIN이 같은 계산을 재사용한다.
+ */
+interface CategoryTreePresentation {
+    readonly basePath: string;
+    readonly categoryDepth: number;
+}
+interface CategoryTreeTerm {
+    readonly id: string;
+    readonly slug: string;
+    readonly parentId?: string | null;
+}
+interface CategoryTreeEntry {
+    readonly slug: string;
+    readonly terms: ReadonlyArray<{
+        readonly id: string;
+        readonly taxonomy: string;
+    }>;
+}
+/**
+ * 선택한 말단 분류부터 루트까지의 사슬을 루트→말단 순서로 돌려준다.
+ * 끊긴 부모·순환·중복 id·깊이 불일치·말단이 아닌 선택은 null로 닫는다.
+ */
+declare function resolveCategoryTreeChain(presentation: CategoryTreePresentation, leafId: string, terms: readonly CategoryTreeTerm[]): CategoryTreeTerm[] | null;
+/** 루트부터 선택 분류까지 모든 허브 주소. */
+declare function resolveCategoryTreeHubPaths(presentation: CategoryTreePresentation, termId: string, terms: readonly CategoryTreeTerm[]): string[] | null;
+/** 계층형 분류 모델 항목의 정규 상세 주소. */
+declare function resolveCategoryTreeEntryPath(presentation: CategoryTreePresentation, entry: CategoryTreeEntry, terms: readonly CategoryTreeTerm[]): string | null;
+
 interface ClientHydrationSpec {
     hydration?: "visible" | "idle" | "load" | "media" | "only";
     module?: string;
@@ -270,6 +325,15 @@ declare const IMAGE_ALT_MAX_LENGTH = 160;
  */
 declare function normalizeImageAlt(value: unknown): string;
 
+/** ChatGPT HTML의 style 블록에서 실행·외부 로드 위험만 제거한다. */
+declare function sanitizeImportedCss(css: string, allowedAssetUrls?: readonly string[]): string;
+/** class·id·안전한 inline style을 보존하는 원문 디자인 전용 HTML 경계. */
+declare function sanitizeImportedHtml(html: string, allowedAssetUrls?: readonly string[]): string;
+/** 구 버전 저장값도 현재의 html/body 가상 루트 계약으로 올린다. */
+declare function ensureImportedHtmlDocumentRoots(html: string, allowedAssetUrls?: readonly string[]): string;
+/** 저장된 안전 CSS가 같은 importedHtml 블록 밖으로 새지 않도록 범위를 고정한다. */
+declare function scopeImportedCss(css: string, scope: string, allowedAssetUrls?: readonly string[]): string;
+
 interface PreviewTokenPayload {
     postId: string;
     expiresAt: Date;
@@ -284,6 +348,8 @@ declare function verifyPreviewToken(secret: string, token: string): PreviewToken
  * Phase 1 acceptance: `<script>alert(1)</script>` 등 인라인 벡터가 inert.
  */
 declare function sanitizeHtml(html: string): string;
+/** 공개 렌더링 원장인 HTML에서 검사·검색용 텍스트를 서버에서도 동일하게 파생한다. */
+declare function htmlToPlainText(html: string): string;
 /**
  * 표준 CSP 헤더 값 (Phase 1 acceptance test #7 정합).
  * Astro middleware / Next.js header config 에서 사용.
@@ -305,4 +371,4 @@ declare function injectStableIdsTree(blocks: readonly (Omit<Block, "_id"> & {
     _id?: string;
 })[]): Block[];
 
-export { BLOCK_NAME_PATTERN, type BindingResolver, type Block, type BlockBinding, type BlockDefinition, type BlockRegistry, type ClientHydrationSpec, type EmbedProvider, FIELD_BINDING_SOURCE, FIELD_BINDING_SOURCE_ALIAS, type FaqEntry, IMAGE_ALT_MAX_LENGTH, type NormalizedEmbed, PHASE_1_CORE_BLOCKS, PHASE_1_CSP, type Phase1CoreBlockName, type PreviewTokenPayload, type RoutablePost, type RouteCollection, applyBlockBindings, bindingSrcValue, bindingTextValue, blockSchema, boundFieldValue, chainResolvers, createFieldBindingResolver, ensureStableIds, extractFaqEntries, faqPageJsonLd, injectStableIdsTree, isAllowedEmbedSrc, isAllowedMapEmbedSrc, isInCollectionMode, isValidBlock, issuePreviewToken, normalizeEmbed, normalizeImageAlt, parseBlock, postsForCollection, postsInAnyCollection, postsNotInAnyCollection, resolvePostCollection, resolvePostPath, resolvePostUrl, sanitizeHtml, serializeBlock, validateCollections, verifyPreviewToken };
+export { BLOCK_NAME_PATTERN, type BindingResolver, type Block, type BlockBinding, type BlockDefinition, type BlockRegistry, type CategoryTreeEntry, type CategoryTreePresentation, type CategoryTreeTerm, type ClientHydrationSpec, type EmbedProvider, FIELD_BINDING_SOURCE, FIELD_BINDING_SOURCE_ALIAS, type FaqEntry, IMAGE_ALT_MAX_LENGTH, type NormalizedEmbed, PHASE_1_CORE_BLOCKS, PHASE_1_CSP, type Phase1CoreBlockName, type PreviewTokenPayload, type RoutablePost, type RouteCollection, applyBlockBindings, bindingSrcValue, bindingTextValue, blockSchema, boundFieldValue, chainResolvers, createFieldBindingResolver, ensureImportedHtmlDocumentRoots, ensureStableIds, extractFaqEntries, faqPageJsonLd, htmlToPlainText, injectStableIdsTree, isAllowedEmbedSrc, isAllowedMapEmbedSrc, isInCollectionMode, isValidBlock, issuePreviewToken, normalizeEmbed, normalizeImageAlt, parseBlock, postsForCollection, postsInAnyCollection, postsNotInAnyCollection, resolveCategoryPath, resolveCategoryTreeChain, resolveCategoryTreeEntryPath, resolveCategoryTreeHubPaths, resolvePostCategorySlug, resolvePostCollection, resolvePostPath, resolvePostUrl, sanitizeHtml, sanitizeImportedCss, sanitizeImportedHtml, scopeImportedCss, serializeBlock, validateCollections, verifyPreviewToken };