@deot/docs-theme 1.0.1

package/README.md

@@ -0,0 +1,44 @@
+# @deot/docs-theme
+
+`@deot/docs-theme` 提供 `@deot/docs` 各浏览器子包共享的 Light/Dark 类型、语义变量和 SCSS 工具，不包含主题状态、持久化或界面组件。
+
+## 安装
+
+```bash
+pnpm add @deot/docs-theme
+```
+
+## SCSS 与 CSS
+
+```scss
+@use '@deot/docs-theme/variables';
+@use '@deot/docs-theme/functions' as *;
+@use '@deot/docs-theme/mixins' as *;
+@use '@deot/docs-theme/theme';
+
+.example {
+	color: varfix(foreground-color);
+	background: varfix(background-color);
+}
+```
+
+编译后的 CSS 变量样式可通过 `@deot/docs-theme/style.css` 引入（对应 `dist/index.style.css`）。Markdown、Playground 与 Client 的构建会内联同一份变量，通常不必单独加载。
+
+运行时由 `@deot/docs-client` 负责同步 `data-doc-theme` 与 `data-vc-theme`。直接使用 Markdown、Playground 或 Renderer 时，也可以自行在祖先元素设置这两个属性之一。
+
+语义变量覆盖前景/背景、主色、链接、提示与警告背景，以及成对的 `error-color` 与 `error-background`。组件库已有的颜色继续复用 `--vc-*`。
+
+公共导出包括 `DOCS_THEMES`、`isDocsTheme`，以及 `DocsTheme`、`DocsThemePreference`、`DocsThemeOptions` 类型。
+
+## 仓库内验证
+
+在仓库根目录执行：
+
+```bash
+npm run test -- --package-name theme
+npm run build -- --package-name theme
+```
+
+## 许可证
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,12 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region packages/theme/src/index.ts
+var DOCS_THEMES = ["light", "dark"];
+/**
+* 判断外部配置或持久化数据是否属于主题协议。
+* @param value 待检查的外部值。
+* @returns 是否为受支持的主题值。
+*/
+var isDocsTheme = (value) => DOCS_THEMES.includes(value);
+//#endregion
+exports.DOCS_THEMES = DOCS_THEMES;
+exports.isDocsTheme = isDocsTheme;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export declare const DOCS_THEMES: readonly ["light", "dark"];
+
+export declare type DocsTheme = typeof DOCS_THEMES[number];
+
+export declare interface DocsThemeOptions {
+    default?: DocsThemePreference;
+}
+
+export declare type DocsThemePreference = DocsTheme | 'system';
+
+export declare const isDocsTheme: (value: unknown) => value is DocsTheme;
+
+export { }

package/dist/index.js

@@ -0,0 +1,10 @@
+//#region packages/theme/src/index.ts
+var DOCS_THEMES = ["light", "dark"];
+/**
+* 判断外部配置或持久化数据是否属于主题协议。
+* @param value 待检查的外部值。
+* @returns 是否为受支持的主题值。
+*/
+var isDocsTheme = (value) => DOCS_THEMES.includes(value);
+//#endregion
+export { DOCS_THEMES, isDocsTheme };

package/dist/index.style.css

@@ -0,0 +1 @@
+@media (prefers-color-scheme:light){:root{--docs-background-color:#fff;--docs-background-color-soft:#f7f8fa;--docs-background-color-mute:#f2f3f5;--docs-foreground-color:#17233d;--docs-foreground-color-light:#515a6e;--docs-foreground-color-mute:#808695;--docs-border-color:#e8eaec;--docs-border-color-light:#f0f1f2;--docs-primary-color:#873bf4;--docs-primary-color-light:#f2ebfe;--docs-link-color:#2d8cf0;--docs-mask-color:hsla(0,0%,100%,.72);--docs-shadow-color:rgba(0,0,0,.14);--docs-code-background:#f6f8fa;--docs-footer-background:#141313;--docs-footer-foreground:#999;--docs-tip-background:#f9f0ff;--docs-warning-background:#fff6f7;--docs-error-color:#ed4014;--docs-error-background:#fef2f2}}@media (prefers-color-scheme:dark){:root{--docs-background-color:#171b24;--docs-background-color-soft:#252b3a;--docs-background-color-mute:#303748;--docs-foreground-color:#f8f8f8;--docs-foreground-color-light:#d9d9d9;--docs-foreground-color-mute:#b9b9b9;--docs-border-color:#3b4355;--docs-border-color-light:#303748;--docs-primary-color:#873bf4;--docs-primary-color-light:#35244d;--docs-link-color:#6daeff;--docs-mask-color:rgba(10,13,18,.76);--docs-shadow-color:rgba(0,0,0,.45);--docs-code-background:#202630;--docs-footer-background:#0d0f14;--docs-footer-foreground:#999;--docs-tip-background:#30223f;--docs-warning-background:#3d2529;--docs-error-color:#ff6b6b;--docs-error-background:#41272b}}[data-doc-theme=light],[data-vc-theme=light]{--docs-background-color:#fff;--docs-background-color-soft:#f7f8fa;--docs-background-color-mute:#f2f3f5;--docs-foreground-color:#17233d;--docs-foreground-color-light:#515a6e;--docs-foreground-color-mute:#808695;--docs-border-color:#e8eaec;--docs-border-color-light:#f0f1f2;--docs-primary-color:#873bf4;--docs-primary-color-light:#f2ebfe;--docs-link-color:#2d8cf0;--docs-mask-color:hsla(0,0%,100%,.72);--docs-shadow-color:rgba(0,0,0,.14);--docs-code-background:#f6f8fa;--docs-footer-background:#141313;--docs-footer-foreground:#999;--docs-tip-background:#f9f0ff;--docs-warning-background:#fff6f7;--docs-error-color:#ed4014;--docs-error-background:#fef2f2}[data-doc-theme=dark],[data-vc-theme=dark]{--docs-background-color:#171b24;--docs-background-color-soft:#252b3a;--docs-background-color-mute:#303748;--docs-foreground-color:#f8f8f8;--docs-foreground-color-light:#d9d9d9;--docs-foreground-color-mute:#b9b9b9;--docs-border-color:#3b4355;--docs-border-color-light:#303748;--docs-primary-color:#873bf4;--docs-primary-color-light:#35244d;--docs-link-color:#6daeff;--docs-mask-color:rgba(10,13,18,.76);--docs-shadow-color:rgba(0,0,0,.45);--docs-code-background:#202630;--docs-footer-background:#0d0f14;--docs-footer-foreground:#999;--docs-tip-background:#30223f;--docs-warning-background:#3d2529;--docs-error-color:#ff6b6b;--docs-error-background:#41272b}/*$vite$:1*/

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@deot/docs-theme",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sass": "src/variables.scss",
+  "style": "dist/index.style.css",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./functions": "./src/functions.scss",
+    "./mixins": "./src/mixins.scss",
+    "./theme": "./src/theme.scss",
+    "./variables": {
+      "types": "./src/variables.d.ts",
+      "sass": "./src/variables.scss",
+      "style": "./src/variables.scss",
+      "default": "./src/variables.scss"
+    },
+    "./style.css": "./dist/index.style.css"
+  },
+  "files": [
+    "dist",
+    "src/*.scss",
+    "src/*.d.ts"
+  ],
+  "sideEffects": [
+    "**/*.scss"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/functions.scss

@@ -0,0 +1,19 @@
+@use 'sass:map';
+@use 'sass:meta';
+@use './theme' as *;
+
+/** 返回 Docs 语义变量，可为组件提供更细粒度的覆盖入口。 */
+@function varfix($value, $component-name: false, $fallback: false) {
+	$theme-value: map.get($theme, $value);
+	$has-component: meta.type-of($component-name) == 'string';
+
+	@if $has-component and $theme-value {
+		@return #{'var(--docs-#{$component-name}-#{$value}, var(--docs-'}#{$value}#{'))'};
+	} @else if $has-component and $fallback {
+		@return #{'var(--docs-'}#{$component-name}-#{$value}#{','}#{$fallback}#{')'};
+	} @else if $theme-value {
+		@return #{'var(--docs-'}#{$value}#{')'};
+	}
+
+	@error '#{$value} is not a valid docs theme value.';
+}

package/src/mixins.scss

@@ -0,0 +1,28 @@
+/** 为需要强制覆盖的组件分别生成 Light/Dark 样式。 */
+@mixin themefix($light: true) {
+	@if $light {
+		@media (prefers-color-scheme: light) {
+			:root {
+				@content;
+			}
+		}
+
+		// 显式属性的权重必须高于 :root 媒体规则，调用 Light/Dark mixin 的
+		// 先后顺序才不会让系统主题覆盖用户选择。
+		[data-doc-theme='light'][data-doc-theme],
+		[data-vc-theme='light'][data-vc-theme] {
+			@content;
+		}
+	} @else {
+		@media (prefers-color-scheme: dark) {
+			:root {
+				@content;
+			}
+		}
+
+		[data-doc-theme='dark'][data-doc-theme],
+		[data-vc-theme='dark'][data-vc-theme] {
+			@content;
+		}
+	}
+}

package/src/theme.scss

@@ -0,0 +1,26 @@
+/**
+ * Docs 只声明文档自身的语义色；组件库已有颜色继续复用 --vc-*。
+ * map 值允许为 light/dark 对象，单值表示两个主题保持一致。
+ */
+$theme: (
+	background-color: (light: #fff, dark: #171b24),
+	background-color-soft: (light: #f7f8fa, dark: #252b3a),
+	background-color-mute: (light: #f2f3f5, dark: #303748),
+	foreground-color: (light: #17233d, dark: #f8f8f8),
+	foreground-color-light: (light: #515a6e, dark: #d9d9d9),
+	foreground-color-mute: (light: #808695, dark: #b9b9b9),
+	border-color: (light: #e8eaec, dark: #3b4355),
+	border-color-light: (light: #f0f1f2, dark: #303748),
+	primary-color: #873bf4,
+	primary-color-light: (light: #f2ebfe, dark: #35244d),
+	link-color: (light: #2d8cf0, dark: #6daeff),
+	mask-color: (light: rgb(255 255 255 / 72%), dark: rgb(10 13 18 / 76%)),
+	shadow-color: (light: rgb(0 0 0 / 14%), dark: rgb(0 0 0 / 45%)),
+	code-background: (light: #f6f8fa, dark: #202630),
+	footer-background: (light: #141313, dark: #0d0f14),
+	footer-foreground: #999,
+	tip-background: (light: #f9f0ff, dark: #30223f),
+	warning-background: (light: #fff6f7, dark: #3d2529),
+	error-color: (light: #ed4014, dark: #ff6b6b),
+	error-background: (light: #fef2f2, dark: #41272b)
+) !default;

package/src/variables.d.ts

@@ -0,0 +1 @@
+export {};

package/src/variables.scss

@@ -0,0 +1,45 @@
+@use 'sass:map';
+@use 'sass:meta';
+@use './theme' as *;
+
+@mixin generate-theme($light: true) {
+	@each $key, $value in $theme {
+		$theme-value: $value;
+
+		@if meta.type-of($value) == 'map' {
+			$light-value: map.get($value, light);
+			$dark-value: map.get($value, dark);
+
+			// 自定义主题只声明 Light 值时，Dark 继续使用该值而不是输出空变量。
+			$theme-value: $light-value;
+
+			@if not $light and $dark-value {
+				$theme-value: $dark-value;
+			}
+		}
+
+		--docs-#{$key}: #{$theme-value};
+	}
+}
+
+@media (prefers-color-scheme: light) {
+	:root {
+		@include generate-theme(true);
+	}
+}
+
+@media (prefers-color-scheme: dark) {
+	:root {
+		@include generate-theme(false);
+	}
+}
+
+[data-doc-theme='light'],
+[data-vc-theme='light'] {
+	@include generate-theme(true);
+}
+
+[data-doc-theme='dark'],
+[data-vc-theme='dark'] {
+	@include generate-theme(false);
+}