@mandujs/core 0.9.39 → 0.9.40

package/src/seo/resolve/index.ts

@@ -0,0 +1,353 @@
+/**
+ * Mandu SEO - Metadata Resolution
+ *
+ * Layout 체인에서 메타데이터를 수집하고 병합
+ */
+
+import type {
+  Metadata,
+  ResolvedMetadata,
+  MetadataItem,
+  MetadataParams,
+  Author,
+  Icons,
+  IconDescriptor,
+  ResolvedIcons,
+  Verification,
+  ResolvedVerification,
+  JsonLd,
+  ThemeColor,
+  ResourceHint,
+  FormatDetection,
+  GoogleMeta,
+  AppLinks,
+} from '../types'
+import { resolveTitle, extractTitleTemplate } from './title'
+import { normalizeMetadataBase, resolveUrl } from './url'
+import { resolveRobots } from './robots'
+import { resolveOpenGraph } from './opengraph'
+import { resolveTwitter } from './twitter'
+
+/**
+ * 기본 메타데이터 생성
+ */
+export function createDefaultMetadata(): ResolvedMetadata {
+  return {
+    metadataBase: null,
+    title: null,
+    description: null,
+    applicationName: null,
+    authors: null,
+    generator: 'Mandu',
+    keywords: null,
+    referrer: null,
+    creator: null,
+    publisher: null,
+    robots: null,
+    alternates: null,
+    icons: null,
+    manifest: null,
+    openGraph: null,
+    twitter: null,
+    verification: null,
+    category: null,
+    classification: null,
+    jsonLd: null,
+    // Google SEO 최적화
+    google: null,
+    formatDetection: null,
+    resourceHints: null,
+    themeColor: null,
+    viewport: null,
+    appLinks: null,
+    other: null,
+  }
+}
+
+/**
+ * Author 배열로 정규화
+ */
+function resolveAuthors(authors: Author | Author[] | null | undefined): Author[] | null {
+  if (!authors) return null
+  return Array.isArray(authors) ? authors : [authors]
+}
+
+/**
+ * Keywords 배열로 정규화
+ */
+function resolveKeywords(keywords: string | string[] | null | undefined): string[] | null {
+  if (!keywords) return null
+  if (typeof keywords === 'string') {
+    return keywords.split(',').map(k => k.trim())
+  }
+  return keywords
+}
+
+/**
+ * Icons 해석
+ */
+function resolveIcons(icons: Metadata['icons'], metadataBase: URL | null): ResolvedIcons | null {
+  if (!icons) return null
+
+  const result: ResolvedIcons = {
+    icon: [],
+    apple: [],
+    shortcut: [],
+    other: [],
+  }
+
+  // 단순 문자열 URL
+  if (typeof icons === 'string') {
+    const url = resolveUrl(icons, metadataBase)
+    if (url) {
+      result.icon.push({ url: url.href })
+    }
+    return result
+  }
+
+  // 배열
+  if (Array.isArray(icons)) {
+    for (const icon of icons) {
+      const descriptor = typeof icon === 'string'
+        ? { url: icon }
+        : icon instanceof URL
+          ? { url: icon.href }
+          : { ...icon, url: typeof icon.url === 'string' ? icon.url : icon.url.href }
+
+      const resolvedUrl = resolveUrl(descriptor.url, metadataBase)
+      if (resolvedUrl) {
+        result.icon.push({ ...descriptor, url: resolvedUrl.href })
+      }
+    }
+    return result
+  }
+
+  // Icons 객체
+  const iconsObj = icons as Icons
+
+  const processIconArray = (
+    items: typeof iconsObj.icon,
+    target: IconDescriptor[]
+  ) => {
+    if (!items) return
+    const arr = Array.isArray(items) ? items : [items]
+    for (const item of arr) {
+      const descriptor = typeof item === 'string'
+        ? { url: item }
+        : item instanceof URL
+          ? { url: item.href }
+          : { ...item, url: typeof item.url === 'string' ? item.url : item.url.href }
+
+      const resolvedUrl = resolveUrl(descriptor.url, metadataBase)
+      if (resolvedUrl) {
+        target.push({ ...descriptor, url: resolvedUrl.href })
+      }
+    }
+  }
+
+  processIconArray(iconsObj.icon, result.icon)
+  processIconArray(iconsObj.apple, result.apple)
+  processIconArray(iconsObj.shortcut, result.shortcut)
+
+  if (iconsObj.other) {
+    const others = Array.isArray(iconsObj.other) ? iconsObj.other : [iconsObj.other]
+    for (const other of others) {
+      const resolvedUrl = resolveUrl(other.url, metadataBase)
+      if (resolvedUrl) {
+        result.other.push({ ...other, url: resolvedUrl.href })
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Verification 해석
+ */
+function resolveVerification(verification: Verification | null | undefined): ResolvedVerification | null {
+  if (!verification) return null
+
+  const toArray = (val: string | string[] | undefined): string[] | null => {
+    if (!val) return null
+    return Array.isArray(val) ? val : [val]
+  }
+
+  return {
+    google: toArray(verification.google),
+    yahoo: toArray(verification.yahoo),
+    yandex: toArray(verification.yandex),
+    me: toArray(verification.me),
+    other: verification.other
+      ? Object.fromEntries(
+          Object.entries(verification.other).map(([k, v]) => [k, toArray(v)!])
+        )
+      : null,
+  }
+}
+
+/**
+ * JSON-LD 배열로 정규화
+ */
+function resolveJsonLd(jsonLd: JsonLd | JsonLd[] | null | undefined): JsonLd[] | null {
+  if (!jsonLd) return null
+  const arr = Array.isArray(jsonLd) ? jsonLd : [jsonLd]
+  // @context 기본값 추가
+  return arr.map(item => ({
+    '@context': 'https://schema.org',
+    ...item,
+  }))
+}
+
+/**
+ * Theme Color 배열로 정규화
+ */
+function resolveThemeColor(
+  themeColor: string | ThemeColor | ThemeColor[] | null | undefined
+): ThemeColor[] | null {
+  if (!themeColor) return null
+  if (typeof themeColor === 'string') {
+    return [{ color: themeColor }]
+  }
+  return Array.isArray(themeColor) ? themeColor : [themeColor]
+}
+
+/**
+ * Viewport 문자열로 정규화
+ */
+function resolveViewport(
+  viewport: Metadata['viewport']
+): string | null {
+  if (!viewport) return null
+  if (typeof viewport === 'string') return viewport
+
+  const parts: string[] = []
+
+  if (viewport.width !== undefined) {
+    parts.push(`width=${viewport.width}`)
+  }
+  if (viewport.height !== undefined) {
+    parts.push(`height=${viewport.height}`)
+  }
+  if (viewport.initialScale !== undefined) {
+    parts.push(`initial-scale=${viewport.initialScale}`)
+  }
+  if (viewport.minimumScale !== undefined) {
+    parts.push(`minimum-scale=${viewport.minimumScale}`)
+  }
+  if (viewport.maximumScale !== undefined) {
+    parts.push(`maximum-scale=${viewport.maximumScale}`)
+  }
+  if (viewport.userScalable !== undefined) {
+    parts.push(`user-scalable=${viewport.userScalable ? 'yes' : 'no'}`)
+  }
+  if (viewport.viewportFit !== undefined) {
+    parts.push(`viewport-fit=${viewport.viewportFit}`)
+  }
+
+  return parts.length > 0 ? parts.join(', ') : null
+}
+
+/**
+ * 두 메타데이터 객체 병합
+ */
+export function mergeMetadata(
+  parent: ResolvedMetadata,
+  child: Metadata
+): ResolvedMetadata {
+  const metadataBase = normalizeMetadataBase(child.metadataBase) || parent.metadataBase
+
+  // 부모의 title template 추출
+  const parentTemplate = parent.title?.template || null
+
+  return {
+    metadataBase,
+    title: resolveTitle(child.title, parentTemplate) ?? parent.title,
+    description: child.description ?? parent.description,
+    applicationName: child.applicationName ?? parent.applicationName,
+    authors: resolveAuthors(child.authors) ?? parent.authors,
+    generator: child.generator ?? parent.generator,
+    keywords: resolveKeywords(child.keywords) ?? parent.keywords,
+    referrer: child.referrer ?? parent.referrer,
+    creator: child.creator ?? parent.creator,
+    publisher: child.publisher ?? parent.publisher,
+    robots: resolveRobots(child.robots) ?? parent.robots,
+    alternates: parent.alternates, // TODO: resolve alternates
+    icons: resolveIcons(child.icons, metadataBase) ?? parent.icons,
+    manifest: resolveUrl(child.manifest, metadataBase) ?? parent.manifest,
+    openGraph: resolveOpenGraph(child.openGraph, metadataBase) ?? parent.openGraph,
+    twitter: resolveTwitter(child.twitter, metadataBase) ?? parent.twitter,
+    verification: resolveVerification(child.verification) ?? parent.verification,
+    category: child.category ?? parent.category,
+    classification: child.classification ?? parent.classification,
+    jsonLd: resolveJsonLd(child.jsonLd) ?? parent.jsonLd,
+    // Google SEO 최적화
+    google: child.google ?? parent.google,
+    formatDetection: child.formatDetection ?? parent.formatDetection,
+    resourceHints: child.resourceHints ?? parent.resourceHints,
+    themeColor: resolveThemeColor(child.themeColor) ?? parent.themeColor,
+    viewport: resolveViewport(child.viewport) ?? parent.viewport,
+    appLinks: child.appLinks ?? parent.appLinks,
+    other: child.other ?? parent.other,
+  }
+}
+
+/**
+ * 메타데이터 항목 해석 (정적/동적)
+ */
+async function resolveMetadataItem(
+  item: MetadataItem,
+  params: MetadataParams,
+  parentPromise: Promise<ResolvedMetadata>
+): Promise<Metadata | null> {
+  if (!item) return null
+
+  // 정적 메타데이터
+  if (typeof item !== 'function') {
+    return item
+  }
+
+  // 동적 메타데이터 (generateMetadata)
+  return await item(params, parentPromise)
+}
+
+/**
+ * 전체 메타데이터 해석 파이프라인
+ *
+ * Layout 체인을 순회하며 메타데이터를 병합
+ *
+ * @param metadataItems - [rootLayout, ...nestedLayouts, page]
+ * @param params - URL 파라미터
+ * @param searchParams - 쿼리 파라미터
+ */
+export async function resolveMetadata(
+  metadataItems: MetadataItem[],
+  params: Record<string, string> = {},
+  searchParams: Record<string, string> = {}
+): Promise<ResolvedMetadata> {
+  let resolved = createDefaultMetadata()
+
+  for (const item of metadataItems) {
+    // 현재 resolved를 Promise로 래핑 (generateMetadata의 parent 파라미터용)
+    const parentPromise = Promise.resolve(resolved)
+
+    const metadata = await resolveMetadataItem(
+      item,
+      { params, searchParams },
+      parentPromise
+    )
+
+    if (metadata) {
+      resolved = mergeMetadata(resolved, metadata)
+    }
+  }
+
+  return resolved
+}
+
+// Re-export sub-modules
+export { resolveTitle, extractTitleTemplate } from './title'
+export { normalizeMetadataBase, resolveUrl, urlToString } from './url'
+export { resolveRobots } from './robots'
+export { resolveOpenGraph } from './opengraph'
+export { resolveTwitter } from './twitter'

package/src/seo/resolve/opengraph.ts

@@ -0,0 +1,143 @@
+/**
+ * Mandu SEO - Open Graph Resolution
+ */
+
+import type {
+  OpenGraph,
+  OpenGraphImage,
+  OpenGraphVideo,
+  OpenGraphAudio,
+  ResolvedOpenGraph,
+} from '../types'
+import { resolveUrl } from './url'
+
+/**
+ * OG 이미지 배열로 정규화
+ */
+function resolveOgImages(
+  images: OpenGraph['images'],
+  metadataBase: URL | null
+): OpenGraphImage[] | null {
+  if (!images) return null
+
+  const arr = Array.isArray(images) ? images : [images]
+  const resolved: OpenGraphImage[] = []
+
+  for (const image of arr) {
+    if (typeof image === 'string' || image instanceof URL) {
+      const url = resolveUrl(image, metadataBase)
+      if (url) {
+        resolved.push({ url: url.href })
+      }
+    } else {
+      const url = resolveUrl(image.url, metadataBase)
+      if (url) {
+        resolved.push({
+          ...image,
+          url: url.href,
+          secureUrl: image.secureUrl
+            ? resolveUrl(image.secureUrl, metadataBase)?.href
+            : undefined,
+        })
+      }
+    }
+  }
+
+  return resolved.length > 0 ? resolved : null
+}
+
+/**
+ * OG 비디오 배열로 정규화
+ */
+function resolveOgVideos(
+  videos: OpenGraph['videos'],
+  metadataBase: URL | null
+): OpenGraphVideo[] | null {
+  if (!videos) return null
+
+  const arr = Array.isArray(videos) ? videos : [videos]
+  const resolved: OpenGraphVideo[] = []
+
+  for (const video of arr) {
+    if (typeof video === 'string' || video instanceof URL) {
+      const url = resolveUrl(video, metadataBase)
+      if (url) {
+        resolved.push({ url: url.href })
+      }
+    } else {
+      const url = resolveUrl(video.url, metadataBase)
+      if (url) {
+        resolved.push({
+          ...video,
+          url: url.href,
+          secureUrl: video.secureUrl
+            ? resolveUrl(video.secureUrl, metadataBase)?.href
+            : undefined,
+        })
+      }
+    }
+  }
+
+  return resolved.length > 0 ? resolved : null
+}
+
+/**
+ * OG 오디오 배열로 정규화
+ */
+function resolveOgAudio(
+  audio: OpenGraph['audio'],
+  metadataBase: URL | null
+): OpenGraphAudio[] | null {
+  if (!audio) return null
+
+  const arr = Array.isArray(audio) ? audio : [audio]
+  const resolved: OpenGraphAudio[] = []
+
+  for (const item of arr) {
+    if (typeof item === 'string' || item instanceof URL) {
+      const url = resolveUrl(item, metadataBase)
+      if (url) {
+        resolved.push({ url: url.href })
+      }
+    } else {
+      const url = resolveUrl(item.url, metadataBase)
+      if (url) {
+        resolved.push({
+          ...item,
+          url: url.href,
+          secureUrl: item.secureUrl
+            ? resolveUrl(item.secureUrl, metadataBase)?.href
+            : undefined,
+        })
+      }
+    }
+  }
+
+  return resolved.length > 0 ? resolved : null
+}
+
+/**
+ * Open Graph 메타데이터 해석
+ */
+export function resolveOpenGraph(
+  openGraph: OpenGraph | null | undefined,
+  metadataBase: URL | null
+): ResolvedOpenGraph | null {
+  if (!openGraph) return null
+
+  return {
+    type: openGraph.type || 'website',
+    url: resolveUrl(openGraph.url, metadataBase),
+    title: openGraph.title || null,
+    description: openGraph.description || null,
+    siteName: openGraph.siteName || null,
+    locale: openGraph.locale || null,
+    images: resolveOgImages(openGraph.images, metadataBase),
+    videos: resolveOgVideos(openGraph.videos, metadataBase),
+    audio: resolveOgAudio(openGraph.audio, metadataBase),
+    determiner: openGraph.determiner || null,
+    article: openGraph.article || null,
+    profile: openGraph.profile || null,
+    book: openGraph.book || null,
+  }
+}

package/src/seo/resolve/robots.ts

@@ -0,0 +1,73 @@
+/**
+ * Mandu SEO - Robots Resolution
+ *
+ * robots 메타 태그 값 생성
+ */
+
+import type { Robots, ResolvedRobots } from '../types'
+
+/**
+ * Robots 객체를 문자열로 변환
+ */
+function robotsToString(robots: Robots): string {
+  const values: string[] = []
+
+  // Boolean directives
+  if (robots.index === true) values.push('index')
+  if (robots.index === false) values.push('noindex')
+  if (robots.follow === true) values.push('follow')
+  if (robots.follow === false) values.push('nofollow')
+  if (robots.noarchive) values.push('noarchive')
+  if (robots.nosnippet) values.push('nosnippet')
+  if (robots.noimageindex) values.push('noimageindex')
+  if (robots.nocache) values.push('nocache')
+  if (robots.notranslate) values.push('notranslate')
+
+  // Numeric directives
+  if (robots['max-snippet'] !== undefined) {
+    values.push(`max-snippet:${robots['max-snippet']}`)
+  }
+  if (robots['max-image-preview']) {
+    values.push(`max-image-preview:${robots['max-image-preview']}`)
+  }
+  if (robots['max-video-preview'] !== undefined) {
+    values.push(`max-video-preview:${robots['max-video-preview']}`)
+  }
+
+  return values.join(', ')
+}
+
+/**
+ * Robots 설정 해석
+ */
+export function resolveRobots(
+  robots: string | Robots | null | undefined
+): ResolvedRobots | null {
+  if (!robots) return null
+
+  // 문자열 그대로 사용
+  if (typeof robots === 'string') {
+    return {
+      basic: robots,
+      googleBot: null,
+    }
+  }
+
+  // 객체에서 문자열 생성
+  const basicString = robotsToString(robots)
+
+  return {
+    basic: basicString || null,
+    googleBot: null, // 향후 googleBot 별도 설정 지원
+  }
+}
+
+/**
+ * 기본 robots 값 생성 (index, follow)
+ */
+export function getDefaultRobots(): ResolvedRobots {
+  return {
+    basic: 'index, follow',
+    googleBot: null,
+  }
+}

package/src/seo/resolve/title.ts

@@ -0,0 +1,94 @@
+/**
+ * Mandu SEO - Title Resolution
+ *
+ * title.template 패턴 처리
+ * Layout의 template이 Page의 title에 적용됨
+ */
+
+import type { Title, TemplateString, AbsoluteTemplateString, AbsoluteString } from '../types'
+
+/**
+ * Title이 TemplateString 객체인지 확인 (default 필드 있음)
+ */
+function isTemplateString(title: Title): title is TemplateString {
+  return typeof title === 'object' && title !== null && 'default' in title
+}
+
+/**
+ * Title이 AbsoluteString 객체인지 확인 (absolute 필드만 있음, default 없음)
+ */
+function isAbsoluteString(title: Title): title is AbsoluteString {
+  return typeof title === 'object' && title !== null && 'absolute' in title && !('default' in title)
+}
+
+/**
+ * Title을 AbsoluteTemplateString으로 변환
+ */
+export function resolveTitle(
+  title: Title | null | undefined,
+  parentTemplate: string | null
+): AbsoluteTemplateString | null {
+  if (title === null || title === undefined) {
+    return null
+  }
+
+  // String title
+  if (typeof title === 'string') {
+    // 부모 템플릿 적용
+    const absolute = parentTemplate
+      ? parentTemplate.replace('%s', title)
+      : title
+
+    return {
+      absolute,
+      template: null,
+    }
+  }
+
+  // AbsoluteString object ({ absolute: string }) - 템플릿 무시
+  if (isAbsoluteString(title)) {
+    return {
+      absolute: title.absolute,
+      template: title.template || null,
+    }
+  }
+
+  // TemplateString object ({ default: string, template?: string })
+  if (isTemplateString(title)) {
+    // default에 부모 템플릿 적용
+    const absolute = parentTemplate
+      ? parentTemplate.replace('%s', title.default)
+      : title.default
+
+    return {
+      absolute,
+      template: title.template || null,
+    }
+  }
+
+  return null
+}
+
+/**
+ * Layout 체인에서 title template 추출
+ */
+export function extractTitleTemplate(title: Title | null | undefined): string | null {
+  if (!title) return null
+
+  if (typeof title === 'string') {
+    return null
+  }
+
+  if (isTemplateString(title)) {
+    return title.template || null
+  }
+
+  return null
+}
+
+/**
+ * title.absolute 값 추출 (렌더링용)
+ */
+export function getTitleString(resolved: AbsoluteTemplateString | null): string | null {
+  return resolved?.absolute || null
+}