clarity-theme 0.1.0

package/app/components/widget/BlogTech.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { Icon } from '#components'
+
+const clarity = useClarityConfig()
+const runtimeConfig = useRuntimeConfig()
+const buildInfo = runtimeConfig.public.clarity as {
+	theme: string
+	themeVersion: string
+	siteVersion: string
+	sitePackageManager: string
+	nuxtVersion: string
+	vueVersion: string
+}
+const { public: { arch, ci, nodeVersion, platform } } = runtimeConfig
+
+const ciPlatform = computed(() => {
+	const iconName = ciIcons[ci]
+	if (!iconName)
+		return ''
+
+	const iconNode = iconName.startsWith('http')
+		? h('img', { src: iconName, alt: '' })
+		: h(Icon, { name: iconName })
+
+	return h('span', {}, [iconNode, ` ${ci.split(' ')[0]}`])
+})
+
+const service = computed(() => ([
+	...ci ? [{ label: '构建平台', value: ciPlatform }] : [],
+	{ label: '文章许可', value: clarity.site.copyright?.abbr || '未配置' },
+	{ label: '规范域名', value: getDomain(clarity.site.url) },
+]))
+
+const techstack = computed(() => ([
+	{ label: 'Blog', value: buildInfo.siteVersion || '--' },
+	{ label: 'Theme', value: `${buildInfo.theme} ${buildInfo.themeVersion}` },
+	{ label: 'Vue', value: buildInfo.vueVersion },
+	{ label: 'Nuxt', value: buildInfo.nuxtVersion },
+	{ label: 'Node', value: nodeVersion },
+	{ label: 'OS', value: platform },
+	{ label: 'Arch', value: arch },
+]))
+
+const expand = ref(false)
+</script>
+
+<template>
+<BlogWidget card grayscale title="技术信息">
+	<ZDlGroup :items="service" />
+	<ZExpand v-model="expand" in-place name="构建信息">
+		<ZDlGroup size="small" :items="techstack" />
+	</ZExpand>
+</BlogWidget>
+</template>
+
+<style lang="scss" scoped>
+.z-expand {
+	margin-top: 0.2em;
+}
+
+.dl-group :deep(img) {
+	height: 1.2em;
+	vertical-align: sub;
+}
+</style>

package/app/components/widget/Empty.vue

@@ -0,0 +1,3 @@
+<template>
+<div />
+</template>

package/app/components/widget/Toc.vue

@@ -0,0 +1,129 @@
+<script setup lang="ts">
+import type { TocLink } from '@nuxt/content'
+
+const [DefineTemplate, ReuseTemplate] = createReusableTemplate({
+	props: {
+		tocTree: { type: Array as PropType<TocLink[]> },
+	},
+})
+
+const { toc } = useArticle()
+const scrollableEl = useTemplateRef('toc')
+const { tocOffsets, activeHeadingId } = useToc(toc, computed(() => scrollableEl.value?.body))
+
+function hasHeading(tocTree: TocLink, heading?: string): boolean {
+	return tocTree.id === heading || !!tocTree.children?.some(child => hasHeading(child, heading))
+}
+</script>
+
+<template>
+<BlogWidget
+	ref="toc"
+	title="文章目录"
+	shrink
+	:style="{ minHeight: `clamp(4rem, ${tocOffsets.length}rem, 20rem)` }"
+>
+	<template #action>
+		<!-- use <a> for anchor -->
+		<a href="#main-content" aria-label="返回开头">
+			<Icon name="tabler:arrow-bar-to-up" />
+		</a>
+
+		<a href="#twikoo" aria-label="评论区">
+			<Icon name="tabler:message-dots" />
+		</a>
+	</template>
+
+	<!-- 放在顶层会导致 Transition 失效 -->
+	<DefineTemplate v-slot="{ tocTree }">
+		<ol>
+			<li
+				v-for="(entry, index) in tocTree"
+				:key="index"
+				:class="{
+					'has-active': hasHeading(entry, activeHeadingId),
+					'active': entry.id === activeHeadingId,
+				}"
+			>
+				<!-- 使用 <a> 确保键盘焦点切换 -->
+				<a :href="`#${entry?.id}`" :title="entry.text">{{ entry.text }}</a>
+				<ReuseTemplate v-if="entry.children" :toc-tree="entry.children" />
+			</li>
+		</ol>
+	</DefineTemplate>
+
+	<ReuseTemplate
+		v-if="toc?.links.length"
+		class="toc"
+		:toc-tree="toc.links"
+	/>
+	<p v-else class="no-toc">
+		暂无目录信息
+	</p>
+</BlogWidget>
+</template>
+
+<style lang="scss" scoped>
+.toc {
+	position: relative;
+
+	&::before {
+		content: "";
+		position: absolute;
+		inset: 0.3rem;
+		width: 3px;
+		border-radius: 1rem;
+		background-color: var(--c-bg-soft);
+	}
+}
+
+ol {
+	padding-inline-start: 0.8rem;
+}
+
+li {
+	opacity: 0.6;
+	font-size: 0.94em;
+	color: var(--c-text);
+	transition: opacity 0.2s;
+
+	&:hover {
+		opacity: 0.94;
+	}
+
+	&.has-active, &.active {
+		opacity: 1;
+		font-size: 1em;
+	}
+
+	&.active::before {
+		content: "";
+		position: absolute;
+		inset-inline-start: 0.3rem;
+		margin: 0.2rem 0;
+		padding: 0.6rem 1.5px;
+		border-radius: 1rem;
+		background-color: var(--c-primary);
+	}
+
+	> a {
+		display: block;
+		overflow: hidden;
+		padding: 0.2em 0.5em;
+		border-radius: 0.5em;
+		white-space: nowrap;
+		text-overflow: ellipsis;
+		transition: all 0.2s;
+
+		&:hover {
+			background-color: var(--c-bg-soft);
+		}
+	}
+}
+
+.no-toc {
+	padding: 1em;
+	text-align: center;
+	color: var(--c-text-3);
+}
+</style>

package/app/composables/useArticle.ts

@@ -0,0 +1,118 @@
+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'
+
+/** 获取已加载的文章内容/元信息 */
+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)
+
+	return {
+		dataKey,
+		post,
+		toc: computed(() => post.value?.body.toc),
+		metaSlots: computed(() => post.value?.meta.slots as Record<string, MetaSlotsTree>),
+	}
+}
+
+/**
+ * 生成文章查询参数，完全包装 useAsyncData 会使 SSR 行为异常，缓存 key 需要暴露
+ * @see https://nuxt.com/docs/4.x/api/composables/use-async-data#usage
+ * @see https://github.com/nuxt/nuxt/issues/14736
+ * @todo 支持分页/分类筛选
+ */
+export function getArticleIndexOptions(path = 'posts/%') {
+	return queryCollection('content')
+		.where('stem', 'LIKE', path)
+		.select('categories', 'date', 'description', 'image', 'path', 'readingTime', 'recommend', 'tags', 'title', 'type', 'updated')
+		.all()
+}
+
+interface UseCategoryOptions {
+	bindQuery?: string
+}
+
+export function useCategory(list: MaybeRefOrGetter<ArticleProps[]>, options?: UseCategoryOptions) {
+	const { bindQuery } = options || {}
+
+	const category = bindQuery
+		? useRouteQuery(bindQuery, undefined)
+		: ref<string | undefined>()
+
+	const categories = computed(() => [...new Set(toValue(list).map(item => item.categories?.[0]))])
+
+	const listCategorized = computed(
+		() => toValue(list).filter(
+			item => !category.value || item.categories?.[0] === category.value,
+		),
+	)
+
+	return {
+		category,
+		categories,
+		listCategorized,
+	}
+}
+
+interface UseArticleSortOptions {
+	bindDirectionQuery?: string
+	bindOrderQuery?: string
+	initialAscend?: boolean
+	initialOrder?: ArticleOrderType
+}
+
+export function useArticleSort(list: MaybeRefOrGetter<ArticleProps[]>, options?: UseArticleSortOptions) {
+	const clarity = useClarityConfig()
+	const {
+		bindDirectionQuery,
+		bindOrderQuery,
+		initialAscend = false,
+		initialOrder = (clarity.pagination.sortOrder as ArticleOrderType) || 'date',
+	} = options || {}
+
+	const sortOrder = bindOrderQuery
+		? useRouteQuery(bindOrderQuery, initialOrder)
+		: ref<ArticleOrderType>(initialOrder)
+
+	const booleanQueryTransformer = {
+		get: (val: string) => val === 'true',
+		set: (val: boolean) => val.toString(),
+	}
+
+	const isAscending = bindDirectionQuery
+		? useRouteQuery(bindDirectionQuery, initialAscend.toString(), { transform: booleanQueryTransformer })
+		: ref<boolean>(initialAscend)
+
+	const listSorted = computed(() => orderBy(
+		toValue(list),
+		[sortOrder.value, 'date'] as any,
+		[isAscending.value ? 'asc' : 'desc'],
+	))
+
+	return {
+		sortOrder,
+		isAscending,
+		listSorted,
+	}
+}
+
+export function getCategoryIcon(category?: string) {
+	const clarity = useClarityConfig()
+	return clarity.article.categories[category!]?.icon ?? 'tabler:folder'
+}
+
+export function getCategoryColor(category?: string) {
+	const clarity = useClarityConfig()
+	return clarity.article.categories[category!]?.color
+}
+
+interface GetPostTypeClassNameOptions {
+	prefix?: string
+}
+
+export function getPostTypeClassName(type = 'tech', options?: GetPostTypeClassNameOptions) {
+	const { prefix = 'text' } = options || {}
+	return `${prefix}-${type}`
+}

package/app/composables/useAvoid.ts

@@ -0,0 +1,87 @@
+import type { UseElementBoundingReturn } from '@vueuse/core'
+
+export type AvoidTarget = Ref<HTMLElement | null | undefined>
+
+export function useAvoidTransform(
+	originRef: AvoidTarget,
+	targets: Ref<AvoidTarget[]>,
+) {
+	const { height: windowHeight, width: windowWidth } = useWindowSize()
+	const targetBounds = shallowRef(new Map<AvoidTarget, UseElementBoundingReturn>())
+	const originRect = shallowRef({ top: 0, bottom: 0, left: 0, right: 0 })
+
+	function updateOriginPosition() {
+		const origin = originRef.value
+		if (!origin)
+			return
+		const style = getComputedStyle(origin)
+		const bottom = Number.parseFloat(style.bottom) || 0
+		const right = Number.parseFloat(style.insetInlineEnd || style.right) || 0
+		originRect.value = {
+			top: windowHeight.value - bottom - origin.offsetHeight,
+			bottom: windowHeight.value - bottom,
+			left: windowWidth.value - right - origin.offsetWidth,
+			right: windowWidth.value - right,
+		}
+	}
+
+	watch([windowHeight, windowWidth], updateOriginPosition)
+	onMounted(updateOriginPosition)
+
+	watchImmediate(targets, (list) => {
+		const newMap = new Map<AvoidTarget, UseElementBoundingReturn>()
+		for (const target of list) {
+			if (target.value)
+				newMap.set(target, targetBounds.value.get(target) ?? useElementBounding(target))
+		}
+		targetBounds.value = newMap
+	}, { deep: true })
+
+	const transform = computed(() => {
+		if (!originRef.value)
+			return ''
+		const { bottom: originBottom, left: originLeft, right: originRight, top: originTop } = originRect.value
+
+		const shifts = Array.from(targetBounds.value.values())
+			.filter(({ top, bottom, left, right }) => {
+				const hasHOverlap = originLeft < right.value && originRight > left.value
+				const hasVOverlap = top.value < originBottom && bottom.value > originTop
+				return hasHOverlap && hasVOverlap
+			})
+			.map(({ top }) => originBottom - top.value)
+
+		const maxShift = Math.max(...shifts)
+		return maxShift > 0 ? `translateY(-${maxShift + 16}px)` : ''
+	})
+
+	return {
+		transform,
+	}
+}
+
+export function useAvoidTarget(
+	targetRef: AvoidTarget,
+	active?: MaybeRefOrGetter<boolean>,
+) {
+	const layoutStore = useLayoutStore()
+
+	function add() {
+		if (!layoutStore.avoidTargets.includes(targetRef))
+			layoutStore.avoidTargets.push(targetRef)
+	}
+
+	function remove() {
+		const idx = layoutStore.avoidTargets.indexOf(targetRef)
+		if (idx > -1)
+			layoutStore.avoidTargets.splice(idx, 1)
+	}
+
+	watchImmediate([toRef(active), targetRef], ([isActive]) => {
+		if (isActive ?? true)
+			add()
+		else
+			remove()
+	})
+
+	onUnmounted(remove)
+}

package/app/composables/useCopy.ts

@@ -0,0 +1,21 @@
+import type { MaybeComputedElementRef } from '@vueuse/core'
+
+/**
+ * 点击触发元素时，将文本复制到剪贴板，并在触发元素上显示提示信息。
+ * @param target - 提供复制文本、目标元素或组件实例。可为字符串、输入框（复制其 `value`）或其他 HTMLElement（复制其文本内容）。
+ */
+export default function useCopy(
+	target: MaybeComputedElementRef | string,
+) {
+	function getText() {
+		if (typeof target === 'string')
+			return target
+
+		const el = unrefElement(target)
+		if (el instanceof HTMLInputElement)
+			return el.value
+		return el?.textContent || ''
+	}
+
+	return useClipboard({ source: getText, legacy: true })
+}

package/app/composables/usePagination.ts

@@ -0,0 +1,70 @@
+interface UsePaginationOptions {
+	initialPage?: number
+	perPage?: number
+	bindQuery?: string
+}
+
+export default function usePagination<T>(list: MaybeRefOrGetter<T[]>, options?: UsePaginationOptions) {
+	const clarity = useClarityConfig()
+	const {
+		initialPage = 1,
+		perPage = clarity.pagination.perPage || 10,
+		bindQuery,
+	} = options || {}
+
+	const totalPages = computed(() => Math.ceil(toValue(list).length / perPage) || initialPage)
+
+	function transformPage(val: string) {
+		const page = Number(val)
+		return page >= 1 && page <= totalPages.value ? page : initialPage
+	}
+
+	// 仅从无查询参数增加 query 时 push 一次
+	const mode = computed({
+		get: () => bindQuery && useRoute().query[bindQuery] ? 'replace' : 'push',
+		set() { },
+	})
+
+	const page = bindQuery
+		? useRouteQuery(bindQuery, initialPage.toString(), { transform: transformPage, mode })
+		: ref(initialPage)
+
+	const listPaged = computed(() => {
+		const start = (page.value - 1) * perPage
+		return toValue(list).slice(start, start + perPage)
+	})
+
+	// 不应在此处 watch list
+
+	return {
+		totalPages,
+		page,
+		listPaged,
+	}
+}
+
+/**
+ * 生成分页数组
+ *
+ * 根据当前页码、扩展范围和总页数，生成一个用于显示的分页数组，包含起始页、结束页和省略符号位置。
+ *
+ * @param current 当前页码
+ * @param total 总页数
+ * @param expand 当前页码的扩展范围，默认值为1
+ * @returns  返回一个包含可显示页码的数组。
+ * 数组中的 `Number.NEGATIVE_INFINITY` 表示向前省略页码符号（...）的位置；
+ * 数组中的 `Number.POSITIVE_INFINITY` 表示向后省略页码符号（...）的位置。
+ *
+ */
+export function getPaginationIndicator(current: number, total: number, expand: number = 1) {
+	const start = Math.max(2, Math.min(current - expand, total - 2 * expand))
+	const end = Math.min(total, start + 2 * expand)
+	const pageArr = Array.from({ length: end - start + 1 }, (_, i) => start + i)
+	start > 3 && pageArr.unshift(Number.NEGATIVE_INFINITY)
+	start === 3 && pageArr.unshift(2)
+	start > 1 && pageArr.unshift(1)
+	end < total - 2 && pageArr.push(Number.POSITIVE_INFINITY)
+	end === total - 2 && pageArr.push(total - 1)
+	end < total && pageArr.push(total)
+	return pageArr
+}

package/app/composables/useShiki.ts

@@ -0,0 +1,129 @@
+import type { BundledLanguage, CodeToHastOptions, HighlighterCore, ShikiTransformer } from 'shiki'
+import { transformerColorizedBrackets } from '@shikijs/colorized-brackets'
+import { transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight, transformerRenderIndentGuides, transformerRenderWhitespace } from '@shikijs/transformers'
+
+type TransformerOptions = Array<
+	| 'ignoreColorizedBrackets'
+	| 'ignoreRenderWhitespace'
+	| 'ignoreRenderIndentGuides'
+>
+type ShikiOptions = CodeToHastOptions<BundledLanguage, string>
+
+const plainTextLanguages = new Set(['ansi', 'log', 'text'])
+
+interface ShikiCodeOptions {
+	language: string
+	transformerOptions?: TransformerOptions
+	shikiOptions?: Omit<ShikiOptions, 'lang'>
+}
+
+type ShikiHtmlOptions = ShikiCodeOptions & {
+	embeddedLanguages?: boolean
+}
+
+function getEmbeddedMarkdownLanguages(code: string, language: string) {
+	if (language !== 'markdown' && !language.startsWith('md'))
+		return []
+
+	// 处理 Markdown 高亮内代码块中的语言
+	// 加载 TeX 语言有概率导致 LaTeX 语言高亮炸掉
+	const mdLangRegex = /^\s*`{3,}(\S+)/gm
+	return [...new Set(
+		Array
+			.from(code.matchAll(mdLangRegex), match => match[1])
+			.filter(lang => lang !== undefined),
+	)]
+}
+
+function transformerUnwrap(): ShikiTransformer {
+	return {
+		root: (hast) => {
+			const lines = (hast.children[0] as any).children[0].children
+
+			return {
+				type: 'root',
+				children: lines,
+			}
+		},
+		line(node, line) {
+			node.properties['data-line'] = line
+		},
+	}
+}
+
+function getTransformers(options: ShikiCodeOptions): ShikiTransformer[] {
+	const ignored = new Set(options.transformerOptions)
+	const inline = options.shikiOptions?.structure === 'inline'
+	const ignoreInvisibleChars = inline || plainTextLanguages.has(options.language)
+
+	return [
+		transformerNotationDiff(),
+		transformerNotationHighlight(),
+		transformerNotationWordHighlight(),
+		transformerNotationFocus(),
+		transformerNotationErrorLevel(),
+		ignored.has('ignoreRenderIndentGuides') || ignoreInvisibleChars ? {} : transformerRenderIndentGuides(),
+		ignored.has('ignoreRenderWhitespace') || ignoreInvisibleChars ? {} : transformerRenderWhitespace(),
+		ignored.has('ignoreColorizedBrackets') ? {} : transformerColorizedBrackets(),
+		inline ? {} : transformerUnwrap(),
+	]
+}
+
+export default function useShiki() {
+	const shikiStore = useShikiStore()
+	let shiki: HighlighterCore
+
+	function getOptions(options: ShikiCodeOptions): ShikiOptions {
+		// Shiki 未收录的语言会在高亮时抛错，回退为纯文本
+		// ansi 是内置特殊语言，不在已加载语法列表中
+		const language = options.language === 'ansi' || shiki.getLoadedLanguages().includes(options.language) ? options.language : 'text'
+
+		return {
+			...shikiStore.options,
+			lang: language,
+			transformers: getTransformers({ ...options, language }),
+			...options.shikiOptions,
+		}
+	}
+
+	async function codeToHtml(code: string, language: string): Promise<string>
+	async function codeToHtml(code: string, options: ShikiHtmlOptions): Promise<string>
+	async function codeToHtml(code: string, languageOrOptions: string | ShikiHtmlOptions): Promise<string> {
+		const options = typeof languageOrOptions === 'string' ? { language: languageOrOptions } : languageOrOptions
+		shiki = await shikiStore.load()
+		await shikiStore.loadLang(options.language)
+
+		if (typeof languageOrOptions !== 'string' && languageOrOptions.embeddedLanguages)
+			await shikiStore.loadLang(...getEmbeddedMarkdownLanguages(code, options.language))
+
+		return shiki.codeToHtml(code, getOptions(options))
+	}
+
+	async function mountPlain(target: HTMLElement, language: string): Promise<void>
+	async function mountPlain(target: HTMLElement, options: ShikiCodeOptions): Promise<void>
+	async function mountPlain(target: HTMLElement, languageOrOptions: string | ShikiCodeOptions): Promise<void> {
+		const options = typeof languageOrOptions === 'string' ? { language: languageOrOptions } : languageOrOptions
+		shiki = await shikiStore.load()
+		const { createPlainShiki } = await import('plain-shiki')
+
+		await shikiStore.loadLang(options.language)
+		createPlainShiki(shiki).mount(target, getOptions(options))
+	}
+
+	async function mountInline(target: HTMLElement, code: string, options: ShikiCodeOptions): Promise<void> {
+		target.classList.add('shiki')
+		target.insertAdjacentHTML('afterbegin', await codeToHtml(code, {
+			...options,
+			shikiOptions: {
+				...options.shikiOptions,
+				structure: 'inline',
+			},
+		}))
+	}
+
+	return {
+		codeToHtml,
+		mountInline,
+		mountPlain,
+	}
+}

package/app/composables/useToc.ts

@@ -0,0 +1,57 @@
+import type { Toc, TocLink } from '@nuxt/content'
+import type { MaybeComputedElementRef } from '@vueuse/core'
+
+interface TocList {
+	id: string
+	offsetTop: number | undefined
+}
+
+export function useToc(toc: MaybeRefOrGetter<Toc | undefined>, scrollableEl?: MaybeComputedElementRef) {
+	const { height: bodyHeight } = useElementSize(document?.body)
+	const { y: scrollY } = useWindowScroll()
+
+	function flattenToc(tocTree: TocLink[], tocList: TocList[] = []) {
+		tocTree.forEach(({ id, children }) => {
+			const headingOffset = document?.getElementById(id)?.offsetTop
+			tocList.push({ id, offsetTop: headingOffset })
+			children && flattenToc(children, tocList)
+		})
+		return tocList
+	}
+
+	const tocOffsets = computedWithControl(
+		refDebounced(bodyHeight),
+		() => flattenToc(toValue(toc)?.links || []).reverse(),
+	)
+
+	function getActiveHeading() {
+		const scrollMargin = Number.parseFloat(getComputedStyle(document.documentElement).getPropertyValue('scroll-margin-top'))
+		const scrollOffset = scrollY.value + (scrollMargin || 64)
+		// 为兼容性不使用 findLast，而是使用倒序的 tocOffsets
+		return tocOffsets.value.find(item => item.offsetTop && item.offsetTop <= scrollOffset)?.id
+	}
+
+	const activeHeadingId = computedWithControl(
+		refThrottled(scrollY, undefined, true),
+		() => document && getActiveHeading(),
+	)
+
+	function scrollToActiveTocItem() {
+		const el = unrefElement(scrollableEl)
+		const active = el?.querySelector<HTMLLinkElement>(`a[href="#${activeHeadingId.value}"]`)
+
+		if (el && active) {
+			el.scrollTo({
+				top: active.offsetTop - el.clientHeight / 4,
+				behavior: 'smooth',
+			})
+		}
+	}
+
+	watch(activeHeadingId, scrollToActiveTocItem)
+
+	return {
+		tocOffsets,
+		activeHeadingId,
+	}
+}