clarity-theme 0.1.0

package/app/stores/layout.ts

@@ -0,0 +1,34 @@
+export type LayoutState = 'none' | 'sidebar' | 'aside' | 'search' | 'lightbox'
+
+export const useLayoutStore = defineStore('layout', () => {
+	const router = useRouter()
+
+	const state = ref<LayoutState>('none')
+	const avoidTargets = ref<AvoidTarget[]>([])
+
+	const close = () => state.value = 'none'
+
+	const toggle = (key: LayoutState) => {
+		if (state.value === key)
+			return close()
+		state.value = key
+	}
+
+	useEventListener('keydown', (e) => {
+		if (state.value !== 'none' && e.key === 'Escape') {
+			e.preventDefault()
+			close()
+		}
+	})
+
+	router.beforeEach(() => {
+		close()
+	})
+
+	return {
+		state,
+		avoidTargets,
+		close,
+		toggle,
+	}
+})

package/app/stores/search.ts

@@ -0,0 +1,37 @@
+import { LazyPopoverSearch } from '#components'
+
+export const useSearchStore = defineStore('search', () => {
+	// 搜索框应和侧边栏状态联动
+	const layoutStore = useLayoutStore()
+	const modalStore = useModalStore()
+
+	const word = ref('')
+	const debouncedWord = refDebounced(word)
+
+	const {
+		open: _open,
+		close: _close,
+	} = modalStore.use(() => h(LazyPopoverSearch, {
+		onClose: () => {
+			_close()
+			layoutStore.close()
+		},
+	}), {
+		unique: true,
+		duration: 200,
+	})
+
+	// 从外部调用时应该操作 layoutStore
+	watch(() => layoutStore.state, (state) => {
+		if (state !== 'search')
+			return _close()
+
+		word.value = window.getSelection()?.toString().trim() || word.value
+		_open()
+	})
+
+	return {
+		word,
+		debouncedWord,
+	}
+})

package/app/types/article.ts

@@ -0,0 +1,16 @@
+import type { ClarityAppConfig } from '../../config/app'
+import type { ArticleSchema } from '../../config/content'
+import type { MetaSlotsTree } from '../../remark-plugins/rehype-meta-slots'
+
+export type ArticleOrderType = keyof ClarityAppConfig['article']['order']
+
+export interface ArticleProps extends ArticleSchema {
+	path: string
+
+	meta?: {
+		coverDim?: boolean
+		coverFilter?: string
+		hideInfo?: boolean
+		slots?: Record<string, MetaSlotsTree>
+	}
+}

package/app/types/feed.ts

@@ -0,0 +1 @@
+export type { FeedEntry, FeedGroup } from '../../config/feed'

package/app/types/index.ts

@@ -0,0 +1,14 @@
+declare global {
+	interface Window {
+		twikoo?: {
+			init: (options: {
+				envId: string
+				el: string
+				region?: string
+				path?: string
+				lang?: string
+			}) => void
+			version: string
+		}
+	}
+}

package/app/types/modal.ts

@@ -0,0 +1,16 @@
+/**
+ * 与 @bikariya/modals 的 runtime/types 保持一致的类型定义。
+ *
+ * 该包 exports 未暴露 runtime/types 子路径，其 `#modals` 虚拟别名在
+ * 真实 npm 消费项目中无法被 Vue SFC 编译器稳定解析，因此 Theme 内联维护。
+ */
+export interface ModalProps {
+	/** 过渡动画时长 (ms) @default 400 */
+	duration?: number
+	/** 模态框开关状态 @internal */
+	open?: boolean
+}
+
+export interface ModalEmits {
+	close: []
+}

package/app/types/nav.ts

@@ -0,0 +1,11 @@
+export interface NavItem {
+	icon: string
+	text: string
+	url: string
+	external?: boolean
+}
+
+export type Nav = {
+	title: string
+	items: NavItem[]
+}[]

package/app/utils/anim.ts

@@ -0,0 +1,37 @@
+import { toArray } from '@vueuse/core'
+
+interface Rect {
+	left: number | string
+	top: number | string
+	width: number | string
+	height: number | string
+}
+
+type MaybeArray<T> = T | T[]
+
+function toRect(rect: Element | Rect): Rect {
+	return rect instanceof Element ? rect.getBoundingClientRect() : rect
+}
+
+const ensurePx = (val: number | string) => typeof val === 'number' ? `${val}px` : val
+
+export function animateBetweenRects(
+	el: MaybeRefOrGetter<Element>,
+	rect: MaybeArray<MaybeRefOrGetter<Element> | Rect>,
+	options?: KeyframeAnimationOptions,
+) {
+	const rects = toArray(rect).map(r => toRect(toValue(r)))
+
+	return toValue(el).animate(rects.map(r => ({
+		left: ensurePx(r.left),
+		top: ensurePx(r.top),
+		width: ensurePx(r.width),
+		height: ensurePx(r.height),
+	})), {
+		duration: 100,
+		fill: 'forwards',
+		...options,
+	})
+}
+
+export const getFixedDelay = (s: number, fixed = 2) => ({ '--delay': `${s.toFixed(fixed)}s` })

package/app/utils/img.ts

@@ -0,0 +1,83 @@
+// @keep-sorted
+const services = {
+	baidu: 'https://image.baidu.com/search/down?url=',
+	/** https://webp.se/fly/ */
+	fly: 'https://fly.webp.se/?url=',
+	/** https://wsrv.nl/docs/ */
+	weserv: 'https://wsrv.nl/?url=',
+}
+
+export type ImgService = keyof typeof services | boolean
+
+// https://wsrv.nl/docs/quick-reference.html
+export function getWsrvGhAvatar(name = '', options: Record<string, any> = { size: 92 }) {
+	const srcUrl = `github.com/${name}.png?size=${options.size}`
+	delete options.size
+
+	const params = new URLSearchParams(srcUrl)
+	Object.entries(options).forEach(([key, value]) => params.set(key, value))
+	return services.weserv + params.toString()
+}
+
+// https://docs.webp.se/public-services/github-avatar/
+export function getGithubAvatar(name = '', options = { size: 120 }) {
+	return `https://avatars-githubusercontent-webp.webp.se/${name}?s=${options.size}`
+}
+
+export const getGithubIcon = (name = '') => getWsrvGhAvatar(name, { size: 32, mask: 'circle' })
+
+export enum OicqAvatarSize {
+	Size1080,
+	Size40,
+	Size40_,
+	Size100,
+	Size140,
+	Size640,
+	Size40__ = 40,
+	Size100_ = 100,
+	Size640_ = 640,
+}
+
+// https://users.qzone.qq.com/fcg-bin/cgi_get_portrait.fcg?uins=
+export function getOicqAvatar(qq = '', size = OicqAvatarSize.Size140) {
+	return `https://q1.qlogo.cn/g?b=qq&nk=${qq}&s=${size}`
+}
+
+export enum QgroupAvatarSize {
+	Size640,
+	Size100 = 100,
+	Size640_ = 640,
+}
+
+export function getOciqGroupAvatar(group = '', size = QgroupAvatarSize.Size100) {
+	return `https://p.qlogo.cn/gh/${group}/${group}/${size}/`
+}
+
+interface GstaticFaviconOptions {
+	provider?: 'gstatic'
+	size?: 16 | 32 | 64 | 96 | 128 | 256 | 512
+}
+
+interface WebpseFaviconOptions {
+	provider: 'google' | 'duckduckgo' | 'microlink'
+	size?: number
+}
+
+// https://github.com/microlinkhq/unavatar
+// https://docs.webp.se/public-services/unavatar/
+export function getFavicon(domain: string, options?: GstaticFaviconOptions | WebpseFaviconOptions) {
+	const { provider = 'gstatic', size = 32 } = options || {}
+	if (provider === 'gstatic')
+		return `https://t0.gstatic.cn/faviconV2?client=SOCIAL&fallback_opts=SIZE&url=http://${domain}&size=${size}`
+	return `https://unavatar.webp.se/${provider}/${domain}?w=${size}`
+}
+
+export function getImgUrl(src: string, service?: ImgService | true) {
+	if (!service)
+		return src
+	if (service === true)
+		service = 'fly'
+	if (service in services)
+		return services[service] + src
+	return src
+}

package/config/app.ts

@@ -0,0 +1,88 @@
+import type { NavItem } from '../app/types/nav'
+import type { ClarityPublicConfig } from './public'
+
+export interface NavGroup {
+	title: string
+	items: NavItem[]
+}
+
+/** Theme 提供的 UI 默认值，全部可由消费项目在 app/app.config.ts 中覆盖 */
+export interface ClarityUiConfig {
+	component: {
+		alert: {
+			defaultStyle: 'card' | 'flat'
+		}
+		codeblock: {
+			triggerRows: number
+			collapsedRows: number
+			enableIndentGuide: boolean
+			indent: number
+			tabSize: number
+		}
+		excerpt: {
+			animation: boolean
+			caret: string
+		}
+		slide: {
+			showTitle: boolean
+		}
+		stats: {
+			/** 归档页面每年标题对应的年龄 */
+			birthYear?: number
+		}
+	}
+	footer: {
+		/** 页脚版权信息，支持 <br> 等内联 HTML */
+		copyright: string
+		/** 侧边栏底部图标导航 */
+		iconNav: NavItem[]
+		/** 页脚站点地图 */
+		nav: NavGroup[]
+	}
+	header: {
+		/** 左侧栏顶部 Logo，默认使用 site.author.avatar */
+		logo: string
+		/** 展示标题文本，否则仅展示 Logo */
+		showTitle: boolean
+		/** 标题下的副标题，默认使用 site.subtitle */
+		subtitle: string
+		/** 标题后的随机表情 */
+		emojiTail: string[]
+	}
+	link: {
+		/** 无订阅源展示静音图标 */
+		remindNoFeed: boolean
+		/** 友链分组内随机排序 */
+		randomInGroup: boolean
+	}
+	/** 左侧栏导航 */
+	nav: NavGroup[]
+	pagination: {
+		perPage: number
+		/** 默认排序方式，需为 article.order 中的键名 */
+		sortOrder: string
+		/** 允许文章列表正序，开启后排序方式左侧图标可切换顺序 */
+		allowAscending: boolean
+	}
+	themes: Record<'light' | 'system' | 'dark', {
+		icon: string
+		tip: string
+	}>
+}
+
+export type ClarityAppConfig = ClarityPublicConfig & ClarityUiConfig
+
+/**
+ * app/app.config.ts 中 `clarity` 键的覆盖输入类型：
+ * UI 配置深度可选（数组整体替换，与 defu 行为一致）。
+ *
+ * 站点级字段（site / article / feed / stats / integrations / features / changelog）
+ * 不属于 app.config.ts，请写入 clarity.config.ts。
+ */
+export type ClarityUiConfigInput<T = ClarityUiConfig> = {
+	[K in keyof T]?: T[K] extends readonly unknown[]
+		? T[K]
+		: T[K] extends object
+			? ClarityUiConfigInput<T[K]>
+			: T[K]
+}

package/config/content.d.mts

@@ -0,0 +1 @@
+export * from './content.ts'

package/config/content.mjs

@@ -0,0 +1,69 @@
+import { defineCollection, defineContentConfig } from '@nuxt/content'
+import { defineSitemapSchema } from '@nuxtjs/sitemap/content'
+import { z } from 'zod'
+import { clarityConfigSchema } from './schema.mjs'
+
+/**
+ * createClarityContentConfig 运行时实现（JS）。
+ *
+ * 类型真源在同目录 content.ts；
+ * @nuxt/content 的配置加载使用 Node 原生 TS 剥离，
+ * 不允许 node_modules 内的 TS 文件，因此运行时链必须是 .mjs。
+ */
+
+function createArticleSchema(config) {
+	// 兜底：types 为空时 z.enum([]) 非法，统一回退到默认版式
+	const articleTypes = Object.keys(config.article.types)
+	const typeValues = articleTypes.length > 0 ? articleTypes : ['tech']
+
+	return z.object({
+		title: z.string().optional(),
+		description: z.string().optional(),
+		date: z.string().optional(),
+		updated: z.string().optional(),
+		published: z.string().optional(),
+		categories: z.array(z.string()).default([config.article.defaultCategory]),
+		tags: z.array(z.string()).default([]),
+		type: z.enum(typeValues).optional().default(typeValues[0]),
+
+		image: z.string().optional(),
+		recommend: z.number().optional(),
+		references: z.array(z.object({
+			title: z.string().optional(),
+			link: z.string().optional(),
+		})).optional(),
+		draft: z.boolean().default(false),
+		permalink: z.string().optional(),
+
+		readingTime: z.object({
+			text: z.string(),
+			minutes: z.number(),
+			time: z.number(),
+			words: z.number(),
+		}),
+	})
+}
+
+export function createClarityContentConfig(config) {
+	const parsed = clarityConfigSchema.parse(config)
+	return defineContentConfig({
+		collections: {
+			content: defineCollection({
+				source: '**',
+				type: 'page',
+				schema: createArticleSchema(parsed).extend({
+					sitemap: defineSitemapSchema({
+						name: 'content',
+						onUrl: (url, entry) => {
+							const lastmod = (entry.updated || entry.published || entry.date)
+							if (lastmod) {
+								url.lastmod = new Date(lastmod).toLocaleDateString('sv')
+							}
+						},
+						z,
+					}),
+				}),
+			}),
+		},
+	})
+}

package/config/content.ts

@@ -0,0 +1,91 @@
+import type { ReadTimeResults } from 'reading-time'
+import type { ClarityConfig } from './schema'
+import { defineCollection, defineContentConfig } from '@nuxt/content'
+import { defineSitemapSchema } from '@nuxtjs/sitemap/content'
+import { z } from 'zod'
+import { clarityConfigSchema } from './schema'
+
+export interface ArticleSchema {
+	title?: string
+	description?: string
+	date?: string
+	updated?: string
+	published?: string
+	categories?: string[]
+	tags?: string[]
+	type?: keyof ClarityConfig['article']['types']
+
+	image?: string
+	recommend?: number
+	references?: { title?: string, link?: string }[]
+	draft?: boolean
+	permalink?: string
+
+	readingTime?: ReadTimeResults
+}
+
+function createArticleSchema(config: ClarityConfig) {
+	// 兜底：types 为空时 z.enum([]) 非法，统一回退到默认版式
+	const articleTypes = Object.keys(config.article.types)
+	const typeValues = articleTypes.length > 0 ? articleTypes : ['tech']
+
+	return z.object({
+		title: z.string().optional(),
+		description: z.string().optional(),
+		date: z.string().optional(),
+		updated: z.string().optional(),
+		published: z.string().optional(),
+		categories: z.array(z.string()).default([config.article.defaultCategory]),
+		tags: z.array(z.string()).default([]),
+		type: z.enum(typeValues as any).optional().default(typeValues[0]),
+
+		image: z.string().optional(),
+		recommend: z.number().optional(),
+		references: z.array(z.object({
+			title: z.string().optional(),
+			link: z.string().optional(),
+		})).optional(),
+		draft: z.boolean().default(false),
+		permalink: z.string().optional(),
+
+		readingTime: z.object({
+			text: z.string(),
+			minutes: z.number(),
+			time: z.number(),
+			words: z.number(),
+		}),
+	}) satisfies z.ZodType<ArticleSchema>
+}
+
+/**
+ * 在消费项目 content.config.ts 中生成 Clarity Content 集合：
+ *
+ * ```ts
+ * import clarityConfig from './clarity.config'
+ * import { createClarityContentConfig } from 'clarity-theme/content'
+ * export default createClarityContentConfig(clarityConfig)
+ * ```
+ */
+export function createClarityContentConfig(config: ClarityConfig) {
+	const parsed = clarityConfigSchema.parse(config)
+	return defineContentConfig({
+		collections: {
+			content: defineCollection({
+				source: '**',
+				type: 'page',
+				schema: createArticleSchema(parsed).extend({
+					sitemap: defineSitemapSchema({
+						name: 'content',
+						onUrl: (url, entry) => {
+							const lastmod = (entry.updated || entry.published || entry.date) as string | undefined
+							if (lastmod) {
+								url.lastmod = new Date(lastmod).toLocaleDateString('sv')
+							}
+						},
+						z,
+					}),
+				}),
+			}),
+		},
+	})
+}

package/config/define.mjs

@@ -0,0 +1,21 @@
+import { clarityConfigSchema } from './schema.mjs'
+
+/**
+ * defineClarityConfig 运行时实现（JS）。
+ * 类型真源在同目录 define.ts；用于 Node 原生 TS 剥离受限场景
+ * （node_modules 内不允许 TS 文件）与纯 ESM 运行时链。
+ */
+export function defineClarityConfig(config) {
+	const result = clarityConfigSchema.safeParse(config)
+	if (!result.success) {
+		const issues = result.error.issues
+			.map(issue => `  - ${issue.path.join('.') || '(根对象)'}: ${issue.message}`)
+			.join('\n')
+		throw new Error(
+			`clarity.config.ts 校验失败：\n${issues}\n`
+			+ '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
+			{ cause: result.error },
+		)
+	}
+	return result.data
+}

package/config/define.ts

@@ -0,0 +1,23 @@
+import type { ClarityConfig, ClarityConfigInput } from './schema'
+import { clarityConfigSchema } from './schema'
+
+/**
+ * 定义 Clarity Theme 站点配置
+ *
+ * 在消费项目根目录的 clarity.config.ts 中使用，
+ * 此处会立即完成默认值填充与校验，避免错误配置进入构建流程。
+ */
+export function defineClarityConfig(config: ClarityConfigInput): ClarityConfig {
+	const result = clarityConfigSchema.safeParse(config)
+	if (!result.success) {
+		const issues = result.error.issues
+			.map(issue => `  - ${issue.path.join('.') || '(根对象)'}: ${issue.message}`)
+			.join('\n')
+		throw new Error(
+			`clarity.config.ts 校验失败：\n${issues}\n`
+			+ '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
+			{ cause: result.error },
+		)
+	}
+	return result.data
+}

package/config/feed.ts

@@ -0,0 +1,42 @@
+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[]
+}

package/config/feeds.empty.ts

@@ -0,0 +1,4 @@
+import type { FeedGroup } from '../app/types/feed'
+
+/** 消费项目未提供 feeds.ts 时的空数据兜底 */
+export default [] satisfies FeedGroup[]

package/config/index.d.mts

@@ -0,0 +1 @@
+export * from './index.ts'

package/config/index.mjs

@@ -0,0 +1,6 @@
+/**
+ * `clarity-theme/config` 运行时实现（JS）。
+ * 类型真源在同目录 index.ts；类型与运行时分离的原因见 define.mjs。
+ */
+export { defineClarityConfig } from './define.mjs'
+export * from './schema.mjs'

package/config/index.ts

@@ -0,0 +1,6 @@
+export type { Nav, NavItem } from '../app/types/nav'
+export type { ClarityAppConfig, ClarityUiConfig, ClarityUiConfigInput, NavGroup } from './app'
+export { defineClarityConfig } from './define'
+export type { Arch, FeedEntry, FeedGroup } from './feed'
+export type { ClarityPublicConfig, ClarityPublicIntegrationsConfig } from './public'
+export * from './schema'