@_tc/template-core 0.2.0-bate.3 → 0.2.0-bate.4

package/README.md

@@ -176,7 +176,7 @@ http://localhost:9000/dash?projk=demo
 
 ## 常用公开入口
 
-完整 exports 以发布包内 `package.json` 为准，除下表外还包含 `./fe/main`、`./fe/*`、`./fe/rc/*`、`./fe/rc/hooks/*` 等子路径。
+完整 exports 以发布包内 `package.json` 为准，除下表外还包含 `./fe/main`、`./fe/*`、`./fe/rc/*`、`./fe/rc/hooks` 等子路径。
 
 | 入口 | 用途 |
 | --- | --- |
@@ -184,6 +184,7 @@ http://localhost:9000/dash?projk=demo
 | `@_tc/template-core/bundler` | 构建入口，提供前端资源构建 `buildFE` 和消费方 Node/backend 构建 `buildBE` |
 | `@_tc/template-core/fe` | 前端初始化、Dash 路由扩展、请求方法、SchemaPage 事件、共享状态和内置前端组件 |
 | `@_tc/template-core/fe/rc` | UI/SchemaForm 组件和类型 |
+| `@_tc/template-core/fe/rc/hooks` | React hooks 汇总入口 |
 | `@_tc/template-core/fe/tailwind_ui.css` | 前端全局样式入口，源码对应 `frontend/src/main.css` |
 | `@_tc/template-core/model` | model 配置类型 |
 
@@ -502,7 +503,7 @@ export function Toolbar() {
 }
 ```
 
-`ThemeSwitch` 会切换 `document.documentElement` 上的 `dark` class，并同步 `color-scheme`。默认写入 localStorage，key 是 `tc_theme`。刷新页面后会优先读取本地主题；没有本地主题时，读取当前根节点是否已有 `dark` class。
+`ThemeSwitch` 会切换 `document.documentElement` 上的 `dark` class，并同步 `color-scheme`。默认写入 localStorage，key 是 `tc_theme`。刷新页面后会优先读取本地主题；没有本地主题时，读取当前根节点是否已有 `dark` class。默认 Dashboard 会在渲染前调用 `initThemeMode()`，让已保存主题尽早生效。
 
 常用参数：
 
@@ -514,6 +515,17 @@ export function Toolbar() {
 | `persist` | 是否写入 localStorage，默认 `true`。 |
 | `storageKey` | 自定义本地存储 key，默认 `tc_theme`。 |
 
+如需在自定义入口或组件外手动初始化/切换主题，可以从 `@_tc/template-core/fe` 导入主题工具：
+
+```ts
+import { applyThemeMode, getCurrentThemeMode, initThemeMode, themeSwitchStorageKey } from '@_tc/template-core/fe'
+
+initThemeMode()
+applyThemeMode('dark', true)
+```
+
+`@_tc/template-core/fe/rc` 和 `@_tc/template-core/fe/rc/hooks` 也会随发布包提供对应 UI 与 hooks 入口；hooks 汇总入口包含 `useBreadcrumb`、`useExecuteOnce`、`useInit`、`useLanguage`、`usePagination`、`useRefState`、`useWatch`。
+
 ### 前端请求封装详解
 
 框架内置的请求封装基于 `@tc/common/http`，底层使用原生 `fetch` API，实现了类似 Axios 的接口和拦截器机制，提供了签名、鉴权、错误处理等能力。

package/fe/frontend/apps/dash/dash.entry.js

@@ -1,6 +1,7 @@
 import { QK, leftSidebarBasePath } from "../../src/common/menu.js";
 import Dashboard from "./Dashboard.js";
 import { renderImportComponent } from "../../src/common/importComponent.js";
+import { initThemeMode } from "../../src/common/theme.js";
 import { initApp } from "../../src/main.js";
 import { jsx } from "react/jsx-runtime";
 import extendDashRoutes from "@tc/scalability/dash/customRoutes";
@@ -54,6 +55,7 @@ initApp(({ children }) => /* @__PURE__ */ jsx("div", {
 }), {
 	routes: getDefaultPageRoutes(),
 	beforeRender: async (context) => {
+		initThemeMode();
 		if (typeof initDash === "function") await initDash(context);
 	}
 });

package/fe/frontend/src/common/theme.d.ts

@@ -0,0 +1,7 @@
+export type ThemeSwitchMode = 'light' | 'dark';
+export declare const themeSwitchStorageKey = "tc_theme";
+export declare const getStoredThemeMode: (storageKey?: string) => ThemeSwitchMode | null;
+export declare const getCurrentThemeMode: (defaultValue?: ThemeSwitchMode, storageKey?: string) => ThemeSwitchMode;
+export declare const persistThemeMode: (mode: ThemeSwitchMode, storageKey?: string) => void;
+export declare const applyThemeMode: (mode?: ThemeSwitchMode, persist?: boolean, storageKey?: string) => void;
+export declare const initThemeMode: (defaultValue?: ThemeSwitchMode, storageKey?: string) => ThemeSwitchMode;

package/fe/frontend/src/common/theme.js

@@ -0,0 +1,33 @@
+//#region frontend/src/common/theme.ts
+var themeSwitchStorageKey = "tc_theme";
+var canUseDocument = () => typeof document !== "undefined";
+var canUseLocalStorage = () => typeof localStorage !== "undefined";
+var getStoredThemeMode = (storageKey = themeSwitchStorageKey) => {
+	if (!canUseLocalStorage()) return null;
+	const value = localStorage.getItem(storageKey);
+	return value === "light" || value === "dark" ? value : null;
+};
+var getCurrentThemeMode = (defaultValue, storageKey = themeSwitchStorageKey) => {
+	const storedMode = getStoredThemeMode(storageKey);
+	if (storedMode) return storedMode;
+	if (defaultValue) return defaultValue;
+	if (!canUseDocument()) return "light";
+	return document.documentElement.classList.contains("dark") ? "dark" : "light";
+};
+var persistThemeMode = (mode, storageKey = themeSwitchStorageKey) => {
+	if (canUseLocalStorage()) localStorage.setItem(storageKey, mode);
+};
+var applyThemeMode = (mode = getCurrentThemeMode(), persist = false, storageKey = themeSwitchStorageKey) => {
+	if (!canUseDocument()) return;
+	const root = document.documentElement;
+	root.classList.toggle("dark", mode === "dark");
+	root.style.colorScheme = mode;
+	if (persist) persistThemeMode(mode, storageKey);
+};
+var initThemeMode = (defaultValue, storageKey = themeSwitchStorageKey) => {
+	const mode = getCurrentThemeMode(defaultValue, storageKey);
+	applyThemeMode(mode, false, storageKey);
+	return mode;
+};
+//#endregion
+export { applyThemeMode, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey };

package/fe/frontend/src/components/ThemeSwitch/ThemeSwitch.d.ts

@@ -1,4 +1,6 @@
-export type ThemeSwitchMode = 'light' | 'dark';
+import { type ThemeSwitchMode } from "../../common/theme";
+export { applyThemeMode, themeSwitchStorageKey } from "../../common/theme";
+export type { ThemeSwitchMode } from "../../common/theme";
 export interface ThemeSwitchProps {
     value?: ThemeSwitchMode;
     defaultValue?: ThemeSwitchMode;
@@ -9,6 +11,5 @@ export interface ThemeSwitchProps {
     persist?: boolean;
     storageKey?: string;
 }
-export declare const themeSwitchStorageKey = "tc_theme";
 declare const ThemeSwitch: ({ value, defaultValue, onChange, disabled, className, showLabel, persist, storageKey, }: ThemeSwitchProps) => import("react/jsx-runtime").JSX.Element;
 export default ThemeSwitch;

package/fe/frontend/src/components/ThemeSwitch/ThemeSwitch.js

@@ -6,35 +6,11 @@ import { cn } from "../../../../packages/react/ui/lib/utils.js";
 import { Switch } from "../../../../packages/react/ui/components/Switch/Switch.js";
 import { Tooltip } from "../../../../packages/react/ui/components/Tooltip/Tooltip.js";
 import "../../../../packages/react/ui/index.js";
+import { applyThemeMode, getCurrentThemeMode, persistThemeMode, themeSwitchStorageKey } from "../../common/theme.js";
 import { useEffect, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Moon, Sun } from "lucide-react";
 //#region frontend/src/components/ThemeSwitch/ThemeSwitch.tsx
-var themeSwitchStorageKey = "tc_theme";
-var canUseDocument = () => typeof document !== "undefined";
-var canUseLocalStorage = () => typeof localStorage !== "undefined";
-var getStoredThemeMode = (storageKey) => {
-	if (!canUseLocalStorage()) return null;
-	const value = localStorage.getItem(storageKey);
-	return value === "light" || value === "dark" ? value : null;
-};
-var getCurrentThemeMode = (defaultValue, storageKey = themeSwitchStorageKey) => {
-	const storedMode = getStoredThemeMode(storageKey);
-	if (storedMode) return storedMode;
-	if (defaultValue) return defaultValue;
-	if (!canUseDocument()) return "light";
-	return document.documentElement.classList.contains("dark") ? "dark" : "light";
-};
-var persistThemeMode = (mode, storageKey) => {
-	if (canUseLocalStorage()) localStorage.setItem(storageKey, mode);
-};
-var applyThemeMode = (mode, persist, storageKey) => {
-	if (!canUseDocument()) return;
-	const root = document.documentElement;
-	root.classList.toggle("dark", mode === "dark");
-	root.style.colorScheme = mode;
-	if (persist) persistThemeMode(mode, storageKey);
-};
 var ThemeSwitch = ({ value, defaultValue, onChange, disabled, className, showLabel = false, persist = true, storageKey = themeSwitchStorageKey }) => {
 	useI18nStore((state) => state.language);
 	const [internalMode, setInternalMode] = useState(() => getCurrentThemeMode(defaultValue, storageKey));
@@ -84,4 +60,4 @@ var ThemeSwitch = ({ value, defaultValue, onChange, disabled, className, showLab
 	});
 };
 //#endregion
-export { ThemeSwitch as default, themeSwitchStorageKey };
+export { applyThemeMode, ThemeSwitch as default, themeSwitchStorageKey };

package/fe/frontend/src/components/ThemeSwitch/index.d.ts

@@ -1,3 +1,4 @@
 import ThemeSwitch from "./ThemeSwitch";
 export * from "./ThemeSwitch";
+export * from "../../common/theme";
 export default ThemeSwitch;

package/fe/frontend/src/components/ThemeSwitch/index.js

@@ -1,5 +1,6 @@
-import ThemeSwitch, { themeSwitchStorageKey } from "./ThemeSwitch.js";
+import { applyThemeMode, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey } from "../../common/theme.js";
+import ThemeSwitch from "./ThemeSwitch.js";
 //#region frontend/src/components/ThemeSwitch/index.ts
 var ThemeSwitch_default = ThemeSwitch;
 //#endregion
-export { ThemeSwitch_default as default, themeSwitchStorageKey };
+export { applyThemeMode, ThemeSwitch_default as default, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey };

package/fe/frontend/src/components/index.js

@@ -1,7 +1,7 @@
 import HeaderView from "./BasePage/HeaderView.js";
+import { applyThemeMode, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey } from "../common/theme.js";
 import { generateRouter } from "./Router/index.js";
 import AsyncSelect_default from "./AsyncSelect/index.js";
 import LanguageSwitch_default from "./LanguageSwitch/index.js";
-import { themeSwitchStorageKey } from "./ThemeSwitch/ThemeSwitch.js";
 import ThemeSwitch_default from "./ThemeSwitch/index.js";
-export { AsyncSelect_default as AsyncSelect, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, generateRouter, themeSwitchStorageKey };
+export { AsyncSelect_default as AsyncSelect, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, applyThemeMode, generateRouter, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey };

package/fe/frontend/src/index.d.ts

@@ -8,6 +8,8 @@ export { api, del, get, patch, post, put, request } from "./common/request";
 export type { AxiosError, BaseResponse, PageParams, PageResponse, RequestConfig, ResponseConfig } from "./common/request";
 export { clearRafTimer, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout } from "./common/rafTimer";
 export type { RafTimerCallback, RafTimerId } from "./common/rafTimer";
+export { applyThemeMode, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey, } from "./common/theme";
+export type { ThemeSwitchMode } from "./common/theme";
 export * from "./defaultPages/SchemaPage/data/eventInfo";
 export { merge } from "./defaultPages/SchemaPage/utils/permissions";
 export * from "./exportStore";

package/fe/frontend/src/index.js

@@ -5,6 +5,7 @@ import { FreezeState, apiFreezerStore, useApiFreezer } from "./stores/apiFreezer
 import { api, del, get, patch, post, put, request } from "./common/request.js";
 import { modeStore, useModeStore } from "./stores/mode.js";
 import HeaderView from "./components/BasePage/HeaderView.js";
+import { applyThemeMode, getCurrentThemeMode, getStoredThemeMode, initThemeMode, persistThemeMode, themeSwitchStorageKey } from "./common/theme.js";
 import { generateRouter } from "./components/Router/index.js";
 import { schemaEventBus } from "./stores/schemaEventBus.js";
 import { schemaStore, useSchemaStore } from "./stores/schemaStore.js";
@@ -13,9 +14,8 @@ import { initApp } from "./main.js";
 import { clearRafTimer, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout } from "./common/rafTimer.js";
 import AsyncSelect_default from "./components/AsyncSelect/index.js";
 import LanguageSwitch_default from "./components/LanguageSwitch/index.js";
-import { themeSwitchStorageKey } from "./components/ThemeSwitch/ThemeSwitch.js";
 import ThemeSwitch_default from "./components/ThemeSwitch/index.js";
 import "./components/index.js";
 import { eventsInfo } from "./defaultPages/SchemaPage/data/eventInfo.js";
 import { merge } from "./defaultPages/SchemaPage/utils/permissions.js";
-export { AsyncSelect_default as AsyncSelect, FreezeState, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, api, apiFreezerStore, clearRafTimer, del, eventsInfo, generateRouter, get, getAuthToken, i18n, i18nStore, initApp, localKeyMap, merge, modeStore, patch, post, put, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout, request, schemaEventBus, schemaStore, setAuthToken, themeSwitchStorageKey, useApiFreezer, useModeStore, useSchemaStore };
+export { AsyncSelect_default as AsyncSelect, FreezeState, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, api, apiFreezerStore, applyThemeMode, clearRafTimer, del, eventsInfo, generateRouter, get, getAuthToken, getCurrentThemeMode, getStoredThemeMode, i18n, i18nStore, initApp, initThemeMode, localKeyMap, merge, modeStore, patch, persistThemeMode, post, put, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout, request, schemaEventBus, schemaStore, setAuthToken, themeSwitchStorageKey, useApiFreezer, useModeStore, useSchemaStore };

package/fe/packages/react/hooks/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./useBreadcrumb";
+export { default as useExecuteOnce } from "./useExecuteOnce";
+export * from "./useExecuteOnce";
+export { default as useInit } from "./useInit";
+export * from "./useLanguage";
+export { default as usePagination } from "./usePagination";
+export { default as useRefState } from "./useRefState";
+export { default as useWatch } from "./useWatch";
+export * from "./useWatch";

package/fe/packages/react/hooks/index.js

@@ -0,0 +1,8 @@
+import { useBreadcrumb } from "./useBreadcrumb.js";
+import { useLanguage } from "./useLanguage.js";
+import useInit from "./useInit.js";
+import useExecuteOnce, { executionPhaseType } from "./useExecuteOnce.js";
+import useRefState from "./useRefState.js";
+import useWatch, { defaultCompare, identityCompare, shallowCompare } from "./useWatch.js";
+import usePagination from "./usePagination.js";
+export { defaultCompare, executionPhaseType, identityCompare, shallowCompare, useBreadcrumb, useExecuteOnce, useInit, useLanguage, usePagination, useRefState, useWatch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_tc/template-core",
-  "version": "0.2.0-bate.3",
+  "version": "0.2.0-bate.4",
   "description": "A full-stack TypeScript admin framework powered by Koa, React, and Vite - monorepo root",
   "types": "./types/index.d.ts",
   "exports": {
@@ -34,10 +34,10 @@
       "require": "./fe/packages/react/ui/index.js",
       "types": "./fe/packages/react/ui/index.d.ts"
     },
-    "./fe/rc/hooks/*": {
-      "import": "./fe/packages/react/hooks/*",
-      "require": "./fe/packages/react/hooks/*",
-      "types": "./fe/packages/react/hooks/*"
+    "./fe/rc/hooks": {
+      "import": "./fe/packages/react/hooks/index.js",
+      "require": "./fe/packages/react/hooks/index.js",
+      "types": "./fe/packages/react/hooks/index.d.ts"
     },
     "./fe/rc/*": {
       "import": "./fe/packages/react/ui/*",