clarity-theme 0.1.2 → 0.1.4

package/src/composables/useArticle.ts

@@ -1,5 +1,5 @@
+import type { ContentCollectionItem } from '@nuxt/content'
 import type { MetaSlotsTree } from '../remark-plugins/rehype-meta-slots'
-import type { ClarityContentRow } from '../shared/types/content'
 import type { ArticleOrderType, ArticleProps } from '../types/article'
 import { orderBy } from 'es-toolkit/array'
 
@@ -7,7 +7,7 @@ import { orderBy } from 'es-toolkit/array'
 export function useArticle(path?: MaybeRefOrGetter<string | undefined>) {
 	const route = useRoute()
 	const dataKey = computed(() => `content:${toValue(path) ?? route.path}`)
-	const post = computed(() => useNuxtData<ClarityContentRow | null | undefined>(dataKey.value).data.value)
+	const post = computed(() => useNuxtData<ContentCollectionItem | null | undefined>(dataKey.value).data.value)
 
 	return {
 		dataKey,
@@ -64,12 +64,12 @@ interface UseArticleSortOptions {
 }
 
 export function useArticleSort(list: MaybeRefOrGetter<ArticleProps[]>, options?: UseArticleSortOptions) {
-	const clarity = useClarityConfig()
+	const appConfig = useAppConfig()
 	const {
 		bindDirectionQuery,
 		bindOrderQuery,
 		initialAscend = false,
-		initialOrder = (clarity.pagination.sortOrder as ArticleOrderType) || 'date',
+		initialOrder = appConfig.pagination.sortOrder || 'date',
 	} = options || {}
 
 	const sortOrder = bindOrderQuery
@@ -87,7 +87,7 @@ export function useArticleSort(list: MaybeRefOrGetter<ArticleProps[]>, options?:
 
 	const listSorted = computed(() => orderBy(
 		toValue(list),
-		[sortOrder.value, 'date'] as any,
+		[sortOrder.value, 'date'],
 		[isAscending.value ? 'asc' : 'desc'],
 	))
 
@@ -99,13 +99,13 @@ export function useArticleSort(list: MaybeRefOrGetter<ArticleProps[]>, options?:
 }
 
 export function getCategoryIcon(category?: string) {
-	const clarity = useClarityConfig()
-	return clarity.article.categories[category!]?.icon ?? 'tabler:folder'
+	const appConfig = useAppConfig()
+	return appConfig.article.categories[category!]?.icon ?? 'tabler:folder'
 }
 
 export function getCategoryColor(category?: string) {
-	const clarity = useClarityConfig()
-	return clarity.article.categories[category!]?.color
+	const appConfig = useAppConfig()
+	return appConfig.article.categories[category!]?.color
 }
 
 interface GetPostTypeClassNameOptions {

package/src/composables/usePagination.ts

@@ -5,10 +5,10 @@ interface UsePaginationOptions {
 }
 
 export default function usePagination<T>(list: MaybeRefOrGetter<T[]>, options?: UsePaginationOptions) {
-	const clarity = useClarityConfig()
+	const appConfig = useAppConfig()
 	const {
 		initialPage = 1,
-		perPage = clarity.pagination.perPage || 10,
+		perPage = appConfig.pagination.perPage || 10,
 		bindQuery,
 	} = options || {}
 

package/src/composables/useWidgets.ts

@@ -5,6 +5,7 @@ import {
 	LazyWidgetBlogLog,
 	LazyWidgetBlogStats,
 	LazyWidgetBlogTech,
+	LazyWidgetCommGroup,
 	LazyWidgetEmpty,
 	LazyWidgetToc,
 } from '#components'
@@ -14,6 +15,7 @@ const rawWidgets = {
 	LazyWidgetBlogLog,
 	LazyWidgetBlogStats,
 	LazyWidgetBlogTech,
+	LazyWidgetCommGroup,
 	LazyWidgetEmpty,
 	LazyWidgetToc,
 }

package/src/config/app.ts

@@ -1,5 +1,6 @@
 import type { NavItem } from '../types/nav'
-import type { ClarityPublicConfig } from './public'
+import type { ClarityPublicConfig, ClarityPublicIntegrationsConfig } from './public'
+import type { ClarityArticleConfig, ClarityAuthor, ClarityFeedConfig, ClarityHeadScript, ClarityStatsConfig } from './schema'
 
 export interface NavGroup {
 	title: string
@@ -27,8 +28,10 @@ export interface ClarityUiConfig {
 			showTitle: boolean
 		}
 		stats: {
-			/** 归档页面每年标题对应的年龄 */
-			birthYear?: number
+			/** 归档页面每年标题对应的年龄，0 表示不展示 */
+			birthYear: number
+			/** blog-stats widget 的预置文本 */
+			wordCount: string
 		}
 	}
 	footer: {
@@ -70,10 +73,53 @@ export interface ClarityUiConfig {
 	}>
 }
 
+/**
+ * CustomAppConfig 中 article 的声明形状。
+ *
+ * 必须是 interface（而非 type 别名）：MergedAppConfig 对 extends Record 的
+ * 类型会进入递归合并，Record<string, string> 的索引签名会把 order 键类型
+ * 碾碎成 keyof any；interface 不带隐式索引签名，直接整体采用本类型。
+ */
+export interface ClarityAppConfigArticle extends ClarityArticleConfig {
+	categories: Record<string, { icon?: string, color?: string }>
+}
+
+/**
+ * 上游 blog-v3 的扁平 AppConfig 形状（blog.config.ts 展开进 app.config.ts）。
+ * Clarity 由 clarity-config 模块注入同一形状，上游同步组件保持 byte-identical。
+ */
+export interface ClarityFlatAppConfig extends ClarityUiConfig {
+	title: string
+	subtitle: string
+	description: string
+	author: ClarityAuthor
+	copyright: { abbr: string, name: string, url: string }
+	favicon: string
+	language: string
+	timeEstablished: string
+	timeZone: string
+	url: string
+	defaultCategory: string
+	article: ClarityArticleConfig
+	feed: ClarityFeedConfig
+	scripts: ClarityHeadScript[]
+	stats: ClarityStatsConfig
+	twikoo?: ClarityPublicIntegrationsConfig['twikoo']
+}
+
+/** 消费项目 app/app.config.ts 顶层扁平键的覆盖输入类型（深层可选，数组整体替换） */
+export type ClarityFlatAppConfigInput<T = ClarityFlatAppConfig> = {
+	[K in keyof T]?: T[K] extends readonly unknown[]
+		? T[K]
+		: T[K] extends object
+			? ClarityFlatAppConfigInput<T[K]>
+			: T[K]
+}
+
 export type ClarityAppConfig = ClarityPublicConfig & ClarityUiConfig
 
 /**
- * app/app.config.ts 中 `clarity` 键的覆盖输入类型：
+ * app/app.config.ts 中 `clarity` 键的覆盖输入类型（0.1.x 兼容）：
  * UI 配置深度可选（数组整体替换，与 defu 行为一致）。
  *
  * 站点级字段（site / article / feed / stats / integrations / features / changelog）

package/src/config/content.ts

@@ -22,6 +22,12 @@ export interface ArticleSchema {
 	permalink?: string
 
 	readingTime?: ReadTimeResults
+
+	/**
+	 * 开放索引签名：clarity.config.ts 的 article.order 允许自定义排序键，
+	 * 上游归档页通过 article[sortOrder] 索引（上游依赖其配置字面量类型）。
+	 */
+	[key: string]: unknown
 }
 
 function createArticleSchema(config: ClarityConfig) {

package/src/config/define.mjs

@@ -13,7 +13,7 @@ export function defineClarityConfig(config) {
 			.join('\n')
 		throw new Error(
 			`clarity.config.ts 校验失败：\n${issues}\n`
-			+ '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
+			+ '未知字段会被拒绝：请检查拼写，或参考 docs/guides/configuration.md 的字段契约。',
 			{ cause: result.error },
 		)
 	}

package/src/config/define.ts

@@ -15,7 +15,7 @@ export function defineClarityConfig(config: ClarityConfigInput): ClarityConfig {
 			.join('\n')
 		throw new Error(
 			`clarity.config.ts 校验失败：\n${issues}\n`
-			+ '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
+			+ '未知字段会被拒绝：请检查拼写，或参考 docs/guides/configuration.md 的字段契约。',
 			{ cause: result.error },
 		)
 	}

package/src/config/feed.ts

@@ -1,42 +1,2 @@
-import type { Arch } from '../shared/utils/icon'
-
-/**
- * 友链数据类型：数据由消费项目提供，结构由 Theme 定义。
- */
-export type { Arch }
-
-export interface FeedEntry {
-	/** 博客作者，使用作者明确的自称 */
-	author: string
-	/** 友链卡片的作者名后缀；作者自称明确且较短时，可填简短站名，避免重复作者名 */
-	sitenick?: string
-	/** 悬浮卡片与订阅源使用的完整站点标题；与作者名相同时省略，默认使用 sitenick 或 author */
-	title?: string
-	/** 个人简介/博客描述 */
-	desc?: string
-	/** 博客地址 */
-	link: string
-	/** 订阅源 */
-	feed?: string
-	/** 站点小图标 */
-	icon: string
-	/** 个人头像 */
-	avatar: string
-	/** 博客技术架构 */
-	archs?: Arch[]
-	/** 申请/评论日期；主动收录时使用收录日期 */
-	date: string
-	/** 博主备注 */
-	comment?: string
-	/** 错误信息 */
-	error?: string
-}
-
-export interface FeedGroup {
-	/** 分组名 */
-	name: string
-	/** 描述 */
-	desc?: string
-	/** 友链列表 */
-	entries: FeedEntry[]
-}
+export type { Arch } from '../shared/utils/icon'
+export type { FeedEntry, FeedGroup } from '../types/feed'

package/src/config/pnpm-workspace.ts

@@ -0,0 +1,19 @@
+/**
+ * Theme 内置的技术栈版本数据（上游 BlogTech 通过 ~~/pnpm-workspace.yaml
+ * 的 catalogs 展示 Vue / Nuxt / Nuxt Content 版本）。
+ *
+ * 分组结构与上游 blog-v3 的 pnpm-workspace.yaml 保持一致：上游 BlogTech
+ * 使用 es-toolkit 的 merge(...Object.values(catalogs))（二元签名），
+ * 至少需要两个分组才能正常展开。
+ */
+export const fallbackPnpmWorkspace = {
+	catalogs: {
+		content: {
+			'@nuxt/content': '^3.16.0',
+		},
+		framework: {
+			nuxt: '^4.5.2',
+			vue: '^3.5.42',
+		},
+	},
+} as const

package/src/config/public.ts

@@ -10,7 +10,7 @@ import type {
 /**
  * 由 clarity.config.ts 注入 appConfig 的客户端可见配置。
  *
- * 可见性约定（详见 docs/config-api-audit.md）：
+ * 可见性约定（详见 docs/guides/configuration.md）：
  * - 只有客户端渲染确实需要的字段进入 appConfig；
  * - feed、完整 stats、features 与 site.author.email 等服务端/构建期字段
  *   改由 Nitro 私有 runtimeConfig 提供（config/server.ts），不进入客户端 bundle；

package/src/config/ui.ts

@@ -0,0 +1,111 @@
+/**
+ * Clarity Theme UI 默认值（上游 blog-v3 `app/app.config.ts` 的可分发子集）。
+ *
+ * 上游的 app/app.config.ts 属于消费项目文件（其 init-project 会重置），
+ * Layer 无法引用消费项目的 blog.config 来派生 logo / subtitle / copyright，
+ * 因此这些站点派生值由 src/modules/clarity-config 注入；
+ * 本文件只保留不携带个人数据的结构性默认值（footer.iconNav / footer.nav
+ * 的个人链接不能随 npm 包分发，默认置空，由消费项目自行填写）。
+ */
+import type { Nav, NavItem } from '../types/nav'
+
+// @keep-sorted
+export default {
+	component: {
+		alert: {
+			/** 默认使用卡片风格还是扁平风格 */
+			defaultStyle: 'card' as 'card' | 'flat',
+		},
+
+		codeblock: {
+			/** 代码块触发折叠的行数 */
+			triggerRows: 32,
+			/** 代码块折叠后的行数 */
+			collapsedRows: 16,
+			/** 启用代码块缩进导航会关闭空格渲染 */
+			enableIndentGuide: true,
+			/** 代码块缩进导航(Indent Guide)竖线匹配空格数 */
+			indent: 4,
+			/** tab渲染宽度 */
+			tabSize: 3,
+		},
+
+		/** 文章开头摘要 */
+		excerpt: {
+			animation: true,
+			caret: '_',
+		},
+
+		/** 精选文章 Slide */
+		slide: {
+			/** 适合封面图无字时启用 */
+			showTitle: true,
+		},
+
+		stats: {
+			/** 归档页面每年标题对应的年龄，无需展示时可设为 0 */
+			birthYear: 0,
+			/** blog-stats widget 的预置文本 */
+			wordCount: '',
+		},
+	},
+
+	// @keep-sorted
+	footer: {
+		/** 侧边栏底部图标导航（个人链接不随 Theme 分发，由消费项目配置） */
+		iconNav: [] as NavItem[],
+		/** 页脚站点地图（同上，默认为空） */
+		nav: [] as Nav,
+	},
+
+	/** 左侧栏顶部 Logo */
+	header: {
+		/** 展示标题文本，否则展示纯 Logo */
+		showTitle: true,
+		/** 标题后的随机表情 */
+		emojiTail: ['📝', '✨', '🌱'] as string[],
+	},
+
+	/** 友链页面 */
+	link: {
+		/** 无订阅源展示静音图标 */
+		remindNoFeed: true,
+		/** 友链分组内随机排序 */
+		randomInGroup: true,
+	},
+
+	/** 左侧栏导航 */
+	nav: [
+		{
+			title: '',
+			items: [
+				{ icon: 'tabler:files', text: '文章', url: '/' },
+				{ icon: 'tabler:link', text: '友链', url: '/link' },
+				{ icon: 'tabler:archive', text: '归档', url: '/archive' },
+			],
+		},
+	] as Nav,
+
+	pagination: {
+		perPage: 10,
+		/** 默认排序方式，需要是 article.order 中的键名 */
+		sortOrder: 'date',
+		/** 允许（普通/预览/归档）文章列表正序，开启后排序方式左侧图标可切换顺序 */
+		allowAscending: false,
+	},
+
+	themes: {
+		light: {
+			icon: 'tabler:sun',
+			tip: '浅色模式',
+		},
+		system: {
+			icon: 'tabler:device-desktop',
+			tip: '跟随系统',
+		},
+		dark: {
+			icon: 'tabler:moon',
+			tip: '深色模式',
+		},
+	},
+}

package/src/generated/blog.config.mjs

@@ -0,0 +1,3 @@
+const blogConfig = {"title":"Clarity Playground","subtitle":"Clarity Theme 示例站点","description":"Clarity Theme 的最小可运行示例，用于验证 Layer 独立构建与站点配置注入。","author":{"name":"Clarity 用户","avatar":"","email":"user@example.com","homepage":"https://clarity-theme.example.com/"},"copyright":{"abbr":"CC BY 4.0","name":"署名 4.0 国际","url":"https://creativecommons.org/licenses/by/4.0/deed.zh-hans"},"favicon":"/favicon.svg","language":"zh-CN","timeEstablished":"2026-01-01","timeZone":"Asia/Shanghai","url":"http://localhost:22098/","defaultCategory":"未分类","article":{"categories":{"未分类":{"icon":"tabler:circle-dashed"},"技术":{"icon":"tabler:code","color":"#7777ff"},"生活":{"icon":"tabler:leaf","color":"#ff7777"}},"types":{"tech":{},"story":{}},"order":{"date":"创建日期","updated":"更新日期"},"useRandomPremalat":false,"hidePostPrefix":true,"robotsNotIndex":[]},"feed":{"limit":20,"enableStyle":true},"scripts":[],"stats":{"includePaths":["posts/%"]},"twikoo":{"envId":"","preload":""}}
+export default blogConfig
+export const myFeed = {"author":"Clarity 用户","sitenick":"Clarity Playground","title":"Clarity Playground","desc":"Clarity Theme 示例站点","link":"http://localhost:22098/","feed":"http://localhost:22098/atom.xml","icon":"/favicon.svg","avatar":"","archs":["Nuxt"],"date":"2026-01-01","comment":"这是我自己"}

package/src/generated/package-json.mjs

@@ -0,0 +1,4 @@
+const packageJson = {"name":"clarity-theme-playground","version":"0.0.0","packageManager":"pnpm@12.4.1"}
+export default packageJson
+export const packageManager = "pnpm@12.4.1"
+export const version = "0.0.0"

package/src/generated/pnpm-workspace.mjs

@@ -0,0 +1 @@
+export default {"catalogs":{"content":{"@nuxt/content":"^3.16.0"},"framework":{"nuxt":"^4.5.2","vue":"^3.5.42"}}}

package/src/modules/anti-mirror/index.ts

@@ -0,0 +1,33 @@
+import { defineNuxtModule } from 'nuxt/kit'
+import { minifySync } from 'oxc-minify'
+import handleMirror from './runtime/client'
+
+const blacklist = [
+	'dgjlx.com', // blog.revincx.icu
+	'dgvhqt.com', // blog.zhilu.cyou
+	'hcmsla.com', // thyuu.com
+	'wmlop.com', // xaoxuu.com
+	'yswjxs.com', // blog.zhilu.cyou
+]
+
+export default defineNuxtModule({
+	meta: {
+		name: 'anti-mirror',
+	},
+	async setup(options, nuxt) {
+		// 生成的数据模块由 clarity-config 在 setup 阶段写入，静态 import 会在
+		// 模块加载阶段读到上一次构建的旧值，因此改为 setup 内动态 import。
+		const { default: blogConfig } = await import('../../generated/blog.config.mjs')
+		nuxt.options.app.head.script ??= []
+		nuxt.options.app.head.script.push({
+			innerHTML: toIifeString(handleMirror, blacklist.map(btoa), btoa(blogConfig.url)),
+		})
+	},
+})
+
+function toIifeString<T extends unknown[]>(fn: (...args: T) => void, ...args: T) {
+	const fnString = fn.toString()
+	const argsString = JSON.stringify(args).slice(1, -1)
+	const minified = minifySync('', `(${fnString})(${argsString})`)
+	return minified.code
+}

package/src/modules/{clarity-config/anti-mirror-client.ts → anti-mirror/runtime/client.ts}

@@ -1,11 +1,11 @@
 export default (sourcesEncoded: string[], targetEncoded: string) => {
 	const sources = sourcesEncoded.map(atob)
-	const canonicalHost = new URL(atob(targetEncoded)).host
+	const target = atob(targetEncoded)
 	const canonical = document.querySelector<HTMLLinkElement>('link[rel="canonical"]')
 	const isBadMirror = sources.some(domain => location.hostname.endsWith(domain))
 	if (isBadMirror) {
 		if (canonical)
-			canonical.href = canonical.href.replace(location.host, canonicalHost)
-		location.host = canonicalHost
+			canonical.href = canonical.href.replace(location.host, target)
+		location.host = target
 	}
 }