@roottale/cms-core 0.53.1 → 0.55.0

package/dist/index.d.cts

@@ -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;
@@ -316,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, ensureImportedHtmlDocumentRoots, ensureStableIds, extractFaqEntries, faqPageJsonLd, htmlToPlainText, injectStableIdsTree, isAllowedEmbedSrc, isAllowedMapEmbedSrc, isInCollectionMode, isValidBlock, issuePreviewToken, normalizeEmbed, normalizeImageAlt, parseBlock, postsForCollection, postsInAnyCollection, postsNotInAnyCollection, resolvePostCollection, resolvePostPath, resolvePostUrl, sanitizeHtml, sanitizeImportedCss, sanitizeImportedHtml, scopeImportedCss, 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 };

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;
@@ -316,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, ensureImportedHtmlDocumentRoots, ensureStableIds, extractFaqEntries, faqPageJsonLd, htmlToPlainText, injectStableIdsTree, isAllowedEmbedSrc, isAllowedMapEmbedSrc, isInCollectionMode, isValidBlock, issuePreviewToken, normalizeEmbed, normalizeImageAlt, parseBlock, postsForCollection, postsInAnyCollection, postsNotInAnyCollection, resolvePostCollection, resolvePostPath, resolvePostUrl, sanitizeHtml, sanitizeImportedCss, sanitizeImportedHtml, scopeImportedCss, 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 };

package/dist/index.js

@@ -127,18 +127,38 @@ function resolvePostCollection(post, collections) {
   return collections.find((c) => c.key === post.collectionKey) ?? null;
 }
 function resolvePostUrl(siteUrl, post, collections) {
-  const collection = resolvePostCollection(post, collections);
-  if (!collection) return null;
-  if (collection.detail === false) return null;
-  if (!collection.basePath) return null;
-  return `${trimTrailingSlash(siteUrl)}${trimTrailingSlash(collection.basePath)}/${encodeURIComponent(post.slug)}`;
+  const path = resolvePostPath(post, collections);
+  return path ? `${trimTrailingSlash(siteUrl)}${path}` : null;
+}
+function resolvePostCategorySlug(post, collection) {
+  const allowed = new Set(collection.categories);
+  const slugs = [
+    ...new Set(
+      post.terms.filter(
+        (term) => term.taxonomy === "category" && allowed.has(term.slug)
+      ).map((term) => term.slug)
+    )
+  ];
+  return slugs.length === 1 ? slugs[0] : null;
+}
+function resolveCategoryPath(collection, categorySlug) {
+  if (!collection.archives || !collection.basePath || !categorySlug) return null;
+  const basePath = trimTrailingSlash(collection.basePath);
+  const encodedSlug = encodeURIComponent(categorySlug);
+  return collection.categoryPath === "direct" ? `${basePath}/${encodedSlug}` : `${basePath}/categories/${encodedSlug}`;
 }
 function resolvePostPath(post, collections) {
   const collection = resolvePostCollection(post, collections);
   if (!collection) return null;
   if (collection.detail === false) return null;
   if (!collection.basePath) return null;
-  return `${trimTrailingSlash(collection.basePath)}/${encodeURIComponent(post.slug)}`;
+  const basePath = trimTrailingSlash(collection.basePath);
+  const encodedPostSlug = encodeURIComponent(post.slug);
+  if (collection.detailPath !== "category") {
+    return `${basePath}/${encodedPostSlug}`;
+  }
+  const categorySlug = resolvePostCategorySlug(post, collection);
+  return categorySlug ? `${basePath}/${encodeURIComponent(categorySlug)}/${encodedPostSlug}` : null;
 }
 function postsForCollection(posts, collections, key) {
   return posts.filter((p) => resolvePostCollection(p, collections)?.key === key);
@@ -178,10 +198,87 @@ function validateCollections(collections) {
       }
       categoryOwner.set(slug, c.key);
     }
+    if (c.detailPath === "category") {
+      if (!c.basePath) {
+        problems.push(
+          `category \uC0C1\uC138 \uACBD\uB85C\uB294 basePath \uAC00 \uD544\uC694\uD568: "${c.key}"`
+        );
+      }
+      if (c.detail === false) {
+        problems.push(
+          `category \uC0C1\uC138 \uACBD\uB85C\uB294 \uAE00\uBCC4 \uC0C1\uC138 \uD398\uC774\uC9C0\uAC00 \uD544\uC694\uD568: "${c.key}"`
+        );
+      }
+      if (!c.archives) {
+        problems.push(
+          `category \uC0C1\uC138 \uACBD\uB85C\uB294 \uCE74\uD14C\uACE0\uB9AC \uC544\uCE74\uC774\uBE0C\uAC00 \uD544\uC694\uD568: "${c.key}"`
+        );
+      }
+      if (c.categoryCardinality !== "exactly-one") {
+        problems.push(
+          `category \uC0C1\uC138 \uACBD\uB85C\uB294 categoryCardinality "exactly-one" \uC774 \uD544\uC694\uD568: "${c.key}"`
+        );
+      }
+    }
   }
   return problems;
 }
 
+// src/category-tree.ts
+function normalizeBasePath(basePath) {
+  return basePath.replace(/\/+$/, "");
+}
+function resolveCategoryTreeChain(presentation, leafId, terms) {
+  if (!Number.isInteger(presentation.categoryDepth) || presentation.categoryDepth < 1) {
+    return null;
+  }
+  const termsById = new Map(terms.map((term) => [term.id, term]));
+  if (termsById.size !== terms.length) return null;
+  if (terms.some((term) => term.parentId === leafId)) return null;
+  const reversed = [];
+  const visited = /* @__PURE__ */ new Set();
+  let currentId = leafId;
+  while (currentId) {
+    if (visited.has(currentId)) return null;
+    visited.add(currentId);
+    const current = termsById.get(currentId);
+    if (!current || !current.slug) return null;
+    reversed.push(current);
+    currentId = current.parentId ?? null;
+  }
+  if (reversed.length !== presentation.categoryDepth) return null;
+  return reversed.reverse();
+}
+function resolveCategoryTreeHubPaths(presentation, termId, terms) {
+  const chain = resolveCategoryTreeChain(presentation, termId, terms);
+  const basePath = normalizeBasePath(presentation.basePath);
+  if (!chain || !basePath) return null;
+  const paths = [basePath];
+  const segments = [];
+  for (const term of chain) {
+    segments.push(encodeURIComponent(term.slug));
+    paths.push(`${basePath}/${segments.join("/")}`);
+  }
+  return paths;
+}
+function resolveCategoryTreeEntryPath(presentation, entry, terms) {
+  if (!entry.slug) return null;
+  const knownIds = new Set(terms.map((term) => term.id));
+  const categoryIds = [
+    ...new Set(
+      entry.terms.filter((term) => term.taxonomy === "category" && knownIds.has(term.id)).map((term) => term.id)
+    )
+  ];
+  if (categoryIds.length !== 1) return null;
+  const hubs = resolveCategoryTreeHubPaths(
+    presentation,
+    categoryIds[0],
+    terms
+  );
+  const leafPath = hubs?.at(-1);
+  return leafPath ? `${leafPath}/${encodeURIComponent(entry.slug)}` : null;
+}
+
 // src/delimiter.ts
 function serializeBlock(block) {
   const exportable = sanitizeAttributesForExport(block);
@@ -1179,6 +1276,11 @@ export {
   postsForCollection,
   postsInAnyCollection,
   postsNotInAnyCollection,
+  resolveCategoryPath,
+  resolveCategoryTreeChain,
+  resolveCategoryTreeEntryPath,
+  resolveCategoryTreeHubPaths,
+  resolvePostCategorySlug,
   resolvePostCollection,
   resolvePostPath,
   resolvePostUrl,