niuma-ui 2.1.2 → 2.1.4

package/CHANGELOG.md

@@ -6,6 +6,19 @@
 
 ## [Unreleased]
 
+
+## [2.1.4] - 2026-09-23
+
+### 变更
+
+- 文档站：组件页和指南页共用 `site-doc` 文章样式（眉题、标题、导语、小节）。演示、代码块、API / Token 表、翻页和首页卡片的圆角与底色走 `--site-panel-radius` / `--site-panel-bg`，暗色不再单独换成抬升表面。文档区背景跟首页画布，网格线走 `--site-home-grid`；暗色画布用 `--rs-bg`，网格为浅色细线。
+
+## [2.1.3] - 2026-09-22
+
+### 变更
+
+- 颜色主题：`applyColorTheme` / `clearColorTheme`。主题包只覆盖 `RS_COLOR_THEME_VARS` 里的语义 `--rs-*`，并标记 `data-rs-color-theme`。明暗仍是 `data-rs-theme="light|dark"`。同一明暗下更换皮肤时，代码编辑器、Monaco、终端和代码块会重读 token。文档站「主题定制」有可切换的演示。
+
 ## [2.1.2] - 2026-09-22
 
 ### 修复

package/dist/components/code-block/src/code-block-utils.js

@@ -1,3 +1,4 @@
+import { documentThemeAttributes } from "../../../theme/color-theme.js";
 //#region src/components/code-block/src/code-block-utils.ts
 var COPY_FEEDBACK_MS = 1500;
 var DOWNLOAD_REVOKE_MS = 1500;
@@ -51,7 +52,7 @@ function ensureThemeObserver() {
 	});
 	themeObserver.observe(document.documentElement, {
 		attributes: true,
-		attributeFilter: ["data-rs-theme"],
+		attributeFilter: [...documentThemeAttributes],
 		subtree: true
 	});
 }

package/dist/components/code-editor/src/code-editor-utils.js

@@ -1,4 +1,5 @@
 import { readResolvedTheme } from "../../../theme/apply.js";
+import { documentThemeAttributes } from "../../../theme/color-theme.js";
 //#region src/components/code-editor/src/code-editor-utils.ts
 var SUPPORTED_LANGUAGES = [
 	"plaintext",
@@ -81,7 +82,7 @@ function subscribeDocumentTheme(listener) {
 		});
 		themeObserver.observe(document.documentElement, {
 			attributes: true,
-			attributeFilter: ["data-rs-theme"]
+			attributeFilter: [...documentThemeAttributes]
 		});
 	}
 	let active = true;

package/dist/components/monaco-editor/src/monaco-editor-utils.js

@@ -1,3 +1,4 @@
+import { documentThemeAttributes } from "../../../theme/color-theme.js";
 import { MONACO_CLICKHOUSE_LANGUAGE, MONACO_DAMENG_LANGUAGE, MONACO_KINGBASE_LANGUAGE, MONACO_MYSQL_LANGUAGE, MONACO_ORACLE_LANGUAGE, MONACO_POSTGRESQL_LANGUAGE, MONACO_SQLITE_LSP_LANGUAGE, MONACO_SQLSERVER_LANGUAGE } from "../../../monaco/languages/types.js";
 import { MONACO_MONGODB_SHELL_LANGUAGE } from "../../../monaco/languages/mongodb-shell.js";
 import { readCodeFontFamily, readCodeFontSizePx, readCssLengthPx, readCssVar } from "../../../theme/css-token.js";
@@ -213,7 +214,7 @@ function subscribeDocumentTheme(listener) {
 		});
 		themeObserver.observe(document.documentElement, {
 			attributes: true,
-			attributeFilter: ["data-rs-theme"]
+			attributeFilter: [...documentThemeAttributes]
 		});
 	}
 	let active = true;

package/dist/components/terminal/src/terminal-utils.js

@@ -1,3 +1,4 @@
+import { documentThemeAttributes } from "../../../theme/color-theme.js";
 //#region src/components/terminal/src/terminal-utils.ts
 var TERMINAL_CSS_KEYS = [
 	["background", "--rs-terminal-bg"],
@@ -235,7 +236,7 @@ function ensureTerminalThemeObserver() {
 	});
 	sharedThemeObserver.observe(document.documentElement, {
 		attributes: true,
-		attributeFilter: ["data-rs-theme"],
+		attributeFilter: [...documentThemeAttributes],
 		subtree: true
 	});
 }

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export { RsDivider } from './components/divider';
 export type { RsDividerOrientation } from './components/divider';
 export { RsDescriptions } from './components/descriptions';
 export { RsDescriptionsItem } from './components/descriptions';
-export type { RsDescriptionsItem as RsDescriptionsItemData, RsDescriptionsLabelAlign, RsDescriptionsLabelPlacement, RsDescriptionsSize, } from './components/descriptions';
+export type { RsDescriptionsItemData, RsDescriptionsLabelAlign, RsDescriptionsLabelPlacement, RsDescriptionsSize, } from './components/descriptions';
 export { RsLoadingBar } from './components/loading-bar';
 export type { RsLoadingBarAttach, RsLoadingBarExpose, RsLoadingBarInstance, RsLoadingBarPosition, RsLoadingBarTone, } from './components/loading-bar';
 export { useRsLoadingBar } from './composables/useRsLoadingBar';
@@ -240,6 +240,7 @@ export { rsCommonIconNames, rsBrandIconNames, rsBrandIconAccentVar, LUCIDE_ATTRI
 export { registerRsIcon } from './icons/host';
 export type { RsBrandIconName } from './icons/registry';
 export type { RsThemeMode, RsResolvedTheme, RsThemeTokens, RsComponentSize, RsRadius, RsFontSize, RsFontWeight, } from './theme/types';
+export type { RsColorTheme, RsColorThemeToken } from './theme/color-theme';
 export { RS_COMPONENT_SIZES, RS_COMPONENT_SIZE_ICON_PX, RS_RADII, RS_RADIUS_CSS, RS_FONT_SIZES, RS_FONT_SIZE_CSS, RS_FONT_WEIGHTS, RS_FONT_WEIGHT_CSS, } from './theme/types';
 export type { RsBuiltinLocale, RsDirMode, RsLocale, RsLocaleMessages, RsTextDirection, } from './locale/types';
 export { defaultLocale, fallbackLocale } from './locale/types';
@@ -250,4 +251,5 @@ export { useResolvedRsComponentSize, resolveRsComponentSize } from './components
 export { useResolvedRsRadius, rsRadiusCss } from './components/_shared';
 export { themePresets } from './theme/presets';
 export { applyTheme, prefersColorSchemeDark, readResolvedTheme, resolveThemeMode, subscribePreferredColorScheme, } from './theme/apply';
+export { RS_COLOR_THEME_VARS, applyColorTheme, clearColorTheme, colorThemeAttribute, isSafeColorThemeId, isSafeColorThemeValue, } from './theme/color-theme';
 export { parseCssLengthToPx, readCodeFontFamily, readCodeFontSizePx, readCssLengthPx, readCssVar, readRootFontSizePx, readTerminalFontFamily, readTerminalFontSizePx, readTerminalFontWeight, readTerminalFontWeightBold, } from './theme/css-token';

package/dist/index.js

@@ -11,6 +11,7 @@ export { MONACO_MYSQL_LANGUAGE } from './monaco/languages/types.js'
 export { MONACO_PGSQL_LANGUAGE } from './monaco/languages/types.js'
 export { MONACO_POSTGRESQL_LANGUAGE } from './monaco/languages/types.js'
 export { MONACO_SQLITE_LANGUAGE } from './monaco/languages/types.js'
+export { RS_COLOR_THEME_VARS } from './theme/color-theme.js'
 export { RS_COMPONENT_SIZES } from './theme/types.js'
 export { RS_COMPONENT_SIZE_ICON_PX } from './theme/types.js'
 export { RS_DATETIME_FORMAT } from './utils/rs-dayjs.js'
@@ -130,6 +131,7 @@ export { TIME_HOUR12_OPTIONS } from './components/time-picker/src/time-picker-ut
 export { TIME_HOUR_OPTIONS } from './components/time-picker/src/time-picker-utils.js'
 export { TIME_SECOND_OPTIONS } from './components/time-picker/src/time-picker-utils.js'
 export { aggregateColumnSummary } from './components/table/src/utils/table-summary-utils.js'
+export { applyColorTheme } from './theme/color-theme.js'
 export { applyLocale } from './locale/apply.js'
 export { applyMonacoDebugDecorations } from './monaco/debug-decorations2.js'
 export { applySplitResize } from './components/split-pane/src/split-pane-utils.js'
@@ -155,6 +157,7 @@ export { clampLogCount } from './components/log/src/log-utils.js'
 export { clampNumber } from './components/input-number/src/input-number-utils.js'
 export { clampPage } from './components/pagination/src/pagination-utils.js'
 export { clampRsDrawerSize } from './components/drawer/src/drawer-utils.js'
+export { clearColorTheme } from './theme/color-theme.js'
 export { cloneFormFieldValue } from './components/form/src/form-utils.js'
 export { codeEditorLanguageLabel } from './components/code-editor/src/code-editor-utils.js'
 export { collapseSplitPane } from './components/split-pane/src/split-pane-utils.js'
@@ -164,6 +167,7 @@ export { collectHalfCheckedKeys } from './components/tree/src/tree-utils.js'
 export { collectTableTreeDescendantKeys } from './components/table/src/utils/table-utils.js'
 export { collectTableTreeExpandableKeys } from './components/table/src/utils/table-utils.js'
 export { collectTableTreeHalfCheckedKeys } from './components/table/src/utils/table-utils.js'
+export { colorThemeAttribute } from './theme/color-theme.js'
 export { compareTableValues } from './components/table/src/utils/table-utils.js'
 export { concatNamePath } from './components/form/src/form-path.js'
 export { containsEscapeSequence } from './components/terminal/src/terminal-utils.js'
@@ -270,6 +274,8 @@ export { isRsLocaleRegistered } from './locale/registry.js'
 export { isRsLogLevel } from './components/log/src/log-utils.js'
 export { isRsSplitPaneAutoSize } from './components/split-pane/src/split-pane-utils.js'
 export { isRsTableApi } from './components/table/src/rs-table-api.js'
+export { isSafeColorThemeId } from './theme/color-theme.js'
+export { isSafeColorThemeValue } from './theme/color-theme.js'
 export { isSafeHref } from './components/markdown/src/markdown-utils.js'
 export { isSafeImageSrc } from './components/markdown/src/markdown-utils.js'
 export { isSelectLabeledValue } from './components/select/src/select-utils.js'

package/dist/theme/color-theme.d.ts

@@ -0,0 +1,64 @@
+import { type RsResolvedTheme } from './types';
+/**
+ * 颜色主题身份。只标记当前皮肤，组件样式不要用它做选择器。
+ * 明暗仍只写 `data-rs-theme="light|dark"`。
+ */
+export declare const colorThemeAttribute = "data-rs-color-theme";
+/** 文档级编辑器要同时观察明暗和颜色主题，否则同为暗色时换皮肤不会重读 token。 */
+export declare const documentThemeAttributes: readonly ["data-rs-theme", "data-rs-color-theme"];
+/**
+ * 主题包可以覆盖的语义令牌。表格、树、按钮等已用 var() 指向这些名字。
+ * 键是主题文件里的字段，值是要写到元素上的 CSS 变量。
+ */
+export declare const RS_COLOR_THEME_VARS: {
+    readonly primary: "--rs-primary";
+    readonly primaryHover: "--rs-primary-hover";
+    readonly primaryForeground: "--rs-primary-foreground";
+    readonly primaryContainer: "--rs-primary-container";
+    readonly onPrimaryContainer: "--rs-on-primary-container";
+    readonly bg: "--rs-bg";
+    readonly surface: "--rs-surface";
+    readonly surfaceElevated: "--rs-surface-elevated";
+    readonly surfaceHover: "--rs-surface-hover";
+    readonly itemHover: "--rs-item-hover";
+    readonly inputBg: "--rs-input-bg";
+    readonly inputBorder: "--rs-input-border";
+    readonly inputBorderHover: "--rs-input-border-hover";
+    readonly border: "--rs-border";
+    readonly borderSubtle: "--rs-border-subtle";
+    readonly text: "--rs-text-primary";
+    readonly muted: "--rs-text-secondary";
+    readonly placeholder: "--rs-text-tertiary";
+    readonly textDisabled: "--rs-text-disabled";
+    readonly textInverse: "--rs-text-inverse";
+    readonly danger: "--rs-danger";
+    readonly dangerContainer: "--rs-danger-container";
+    readonly onDangerContainer: "--rs-on-danger-container";
+    readonly success: "--rs-success";
+    readonly successContainer: "--rs-success-container";
+    readonly onSuccessContainer: "--rs-on-success-container";
+    readonly warning: "--rs-warning";
+    readonly warningContainer: "--rs-warning-container";
+    readonly onWarningContainer: "--rs-on-warning-container";
+    readonly info: "--rs-info";
+    readonly infoContainer: "--rs-info-container";
+    readonly onInfoContainer: "--rs-on-info-container";
+};
+export type RsColorThemeToken = keyof typeof RS_COLOR_THEME_VARS;
+/** 一份可安装的颜色主题。`id` 不翻译；`label` 用英文，宿主自己做语言包。 */
+export interface RsColorTheme {
+    id: string;
+    label: string;
+    uiTheme: RsResolvedTheme;
+    colors: Partial<Record<RsColorThemeToken, string>>;
+}
+/** 拒绝能逃出自定义属性、注入样式或外链的值。允许 hex、函数色和 var()。 */
+export declare function isSafeColorThemeValue(value: string): boolean;
+export declare function isSafeColorThemeId(id: string): boolean;
+/**
+ * 把主题包写到元素的内联 `--rs-*` 上，盖过 styles.css 与 brand.css。
+ * 未列出的字段保持样式表原值。非法 id 或没有目标元素时不改 DOM。
+ */
+export declare function applyColorTheme(theme: RsColorTheme, el?: HTMLElement | null): boolean;
+/** 去掉该元素上由颜色主题写上的变量，回到样式表。 */
+export declare function clearColorTheme(el?: HTMLElement | null): void;

package/dist/theme/color-theme.js

@@ -0,0 +1,100 @@
+import { themeAttribute } from "./types.js";
+//#region src/theme/color-theme.ts
+/**
+* 颜色主题身份。只标记当前皮肤，组件样式不要用它做选择器。
+* 明暗仍只写 `data-rs-theme="light|dark"`。
+*/
+var colorThemeAttribute = "data-rs-color-theme";
+/** 文档级编辑器要同时观察明暗和颜色主题，否则同为暗色时换皮肤不会重读 token。 */
+var documentThemeAttributes = [themeAttribute, colorThemeAttribute];
+/**
+* 主题包可以覆盖的语义令牌。表格、树、按钮等已用 var() 指向这些名字。
+* 键是主题文件里的字段，值是要写到元素上的 CSS 变量。
+*/
+var RS_COLOR_THEME_VARS = {
+	primary: "--rs-primary",
+	primaryHover: "--rs-primary-hover",
+	primaryForeground: "--rs-primary-foreground",
+	primaryContainer: "--rs-primary-container",
+	onPrimaryContainer: "--rs-on-primary-container",
+	bg: "--rs-bg",
+	surface: "--rs-surface",
+	surfaceElevated: "--rs-surface-elevated",
+	surfaceHover: "--rs-surface-hover",
+	itemHover: "--rs-item-hover",
+	inputBg: "--rs-input-bg",
+	inputBorder: "--rs-input-border",
+	inputBorderHover: "--rs-input-border-hover",
+	border: "--rs-border",
+	borderSubtle: "--rs-border-subtle",
+	text: "--rs-text-primary",
+	muted: "--rs-text-secondary",
+	placeholder: "--rs-text-tertiary",
+	textDisabled: "--rs-text-disabled",
+	textInverse: "--rs-text-inverse",
+	danger: "--rs-danger",
+	dangerContainer: "--rs-danger-container",
+	onDangerContainer: "--rs-on-danger-container",
+	success: "--rs-success",
+	successContainer: "--rs-success-container",
+	onSuccessContainer: "--rs-on-success-container",
+	warning: "--rs-warning",
+	warningContainer: "--rs-warning-container",
+	onWarningContainer: "--rs-on-warning-container",
+	info: "--rs-info",
+	infoContainer: "--rs-info-container",
+	onInfoContainer: "--rs-on-info-container"
+};
+var THEME_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var appliedVars = /* @__PURE__ */ new WeakMap();
+function themeTarget(el) {
+	if (el) return el;
+	if (typeof document === "undefined") return null;
+	return document.documentElement;
+}
+/** 拒绝能逃出自定义属性、注入样式或外链的值。允许 hex、函数色和 var()。 */
+function isSafeColorThemeValue(value) {
+	const raw = value.trim();
+	if (!raw || raw.length > 240) return false;
+	if (/[;{}<>]|url\s*\(|expression\s*\(|@import|\/\*|\*\//i.test(raw)) return false;
+	return true;
+}
+function isSafeColorThemeId(id) {
+	return THEME_ID.test(id);
+}
+/**
+* 把主题包写到元素的内联 `--rs-*` 上，盖过 styles.css 与 brand.css。
+* 未列出的字段保持样式表原值。非法 id 或没有目标元素时不改 DOM。
+*/
+function applyColorTheme(theme, el) {
+	const target = themeTarget(el);
+	if (!target || !isSafeColorThemeId(theme.id)) return false;
+	const previous = appliedVars.get(target) ?? /* @__PURE__ */ new Set();
+	const next = /* @__PURE__ */ new Set();
+	for (const key of Object.keys(RS_COLOR_THEME_VARS)) {
+		const value = theme.colors[key];
+		if (value == null) continue;
+		const raw = String(value).trim();
+		if (!isSafeColorThemeValue(raw)) continue;
+		const prop = RS_COLOR_THEME_VARS[key];
+		target.style.setProperty(prop, raw);
+		next.add(prop);
+	}
+	for (const prop of previous) if (!next.has(prop)) target.style.removeProperty(prop);
+	appliedVars.set(target, next);
+	target.setAttribute(colorThemeAttribute, theme.id);
+	return true;
+}
+/** 去掉该元素上由颜色主题写上的变量，回到样式表。 */
+function clearColorTheme(el) {
+	const target = themeTarget(el);
+	if (!target) return;
+	const previous = appliedVars.get(target);
+	if (previous) {
+		for (const prop of previous) target.style.removeProperty(prop);
+		appliedVars.delete(target);
+	}
+	target.removeAttribute(colorThemeAttribute);
+}
+//#endregion
+export { RS_COLOR_THEME_VARS, applyColorTheme, clearColorTheme, colorThemeAttribute, documentThemeAttributes, isSafeColorThemeId, isSafeColorThemeValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niuma-ui",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "license": "Apache-2.0",
   "type": "module",
   "description": "Vue 3 workbench design system — Rs* components, --rs-* tokens, optional Monaco / CodeMirror / xterm",