@longzai-intelligence-layout/theming 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+import { ComponentType } from "react";
+import { StoreApi, UseBoundStore } from "zustand";
+/**
+ * 设计语言偏好工具
+ *
+ * 为界面设计语言提供偏好取值类型、选项条目形态与偏好定义构造，
+ * 异常取值一律回落默认设计语言
+ */
+/**
+ * 设计语言选项条目
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type DesignLanguageOption<L extends string> = {
+  /**
+   * 选项偏好值，与文档根元素 `data-design-language` 属性取值一致
+   */
+  value: L;
+  /**
+   * 选项可访问名称
+   */
+  label: string;
+};
+/**
+ * 设计语言偏好定义形态
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type DesignLanguagePreferenceDefinition<L extends string> = ReturnType<typeof defineDesignLanguagePreference<L>>;
+/**
+ * 构造设计语言偏好定义
+ *
+ * @remarks
+ *   仅接受清单内合法取值，键缺失与其余异常取值一律回落默认设计语言，
+ *   让首次使用与存储异常都收敛到默认设计语言形态
+ * @typeParam L - 设计语言名类型
+ * @param languages - 设计语言合法取值清单
+ * @param defaultLanguage - 默认设计语言，结构层基座语言形态
+ * @param key - 完整存储键名，约定挂消费方命名空间前缀
+ * @param tier - 偏好存储层级
+ * @returns 设计语言偏好定义
+ */
+declare function defineDesignLanguagePreference<L extends string>(languages: readonly L[], defaultLanguage: L, key: string, tier: 'persistent' | 'session'): import("@longzai-intelligence-layout/preferences").PreferenceDefinition<L>;
+/**
+ * 界面设计语言状态形态
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type DesignLanguageState<L extends string> = {
+  /**
+   * 当前设计语言偏好，初值读本地存储，缺省为默认设计语言
+   */
+  preference: L;
+  /**
+   * 切换设计语言偏好并记忆到本地存储
+   *
+   * @param next - 切换后的设计语言偏好
+   */
+  setPreference: (next: L) => void;
+};
+/**
+ * 设计语言偏好读写绑定形态
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type DesignLanguagePreferenceBinding<L extends string> = {
+  /**
+   * 当前设计语言偏好
+   */
+  preference: L;
+  /**
+   * 切换设计语言偏好动作，切换即持久化
+   */
+  setPreference: (next: L) => void;
+};
+/**
+ * 设计语言控制器形态
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type DesignLanguageController<L extends string> = {
+  /**
+   * 全局设计语言偏好 store，切换动作随写随存
+   */
+  useStore: UseBoundStore<StoreApi<DesignLanguageState<L>>>;
+  /**
+   * 设计语言选项表，消费方注入的清单原样保留渲染顺序
+   */
+  options: readonly DesignLanguageOption<L>[];
+  /**
+   * 默认设计语言，该形态下文档根元素不携带 `data-design-language` 属性
+   */
+  defaultLanguage: L;
+  /**
+   * 设计语言应用同步 hook，全局挂载一次，偏好变化时应用到文档根元素
+   */
+  useSync: () => void;
+  /**
+   * 设计语言偏好读写 hook
+   *
+   * @returns 当前设计语言偏好与切换动作的绑定，切换即持久化
+   */
+  usePreference: () => DesignLanguagePreferenceBinding<L>;
+  /**
+   * 渲染前按 store 当前偏好同步应用设计语言，供应用入口在首次渲染前调用以避免非默认语言用户首帧闪回默认视觉
+   */
+  applyFromStorage: () => void;
+};
+/**
+ * 设计语言控制器选项
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type CreateDesignLanguageControllerOptions<L extends string> = {
+  /**
+   * 设计语言选项表，渲染顺序即切换控件选项顺序
+   */
+  options: readonly DesignLanguageOption<L>[];
+  /**
+   * 默认设计语言，约定为结构层基座语言，该形态清除根元素属性回落结构层直供
+   */
+  defaultLanguage: L;
+  /**
+   * 设计语言偏好定义
+   */
+  preference: DesignLanguagePreferenceDefinition<L>;
+};
+/**
+ * 创建设计语言控制器
+ *
+ * @typeParam L - 设计语言名类型
+ * @param options - 设计语言控制器选项
+ * @returns 设计语言控制器实例
+ */
+declare function createDesignLanguageController<L extends string>(options: CreateDesignLanguageControllerOptions<L>): DesignLanguageController<L>;
+/**
+ * 设计语言切换组件属性
+ *
+ * @typeParam L - 设计语言名类型
+ */
+type DesignLanguageSwitcherProps<L extends string> = {
+  /**
+   * 设计语言控制器实例
+   */
+  controller: DesignLanguageController<L>;
+  /**
+   * 选项图标组件映射，键为选项偏好值，缺省选项回退通用图标
+   */
+  icons?: Partial<Record<L, ComponentType<{
+    size?: number;
+    'aria-hidden'?: boolean;
+  }>>>;
+};
+/**
+ * 设计语言切换组件
+ *
+ * @typeParam L - 设计语言名类型
+ * @param options - 设计语言切换组件属性
+ * @param options.controller - 设计语言控制器实例
+ * @param options.icons - 选项图标组件映射，未注入映射的选项回退通用图标
+ * @returns 多态分段切换控件
+ */
+declare function DesignLanguageSwitcher<L extends string>({ controller, icons }: DesignLanguageSwitcherProps<L>): import("react").JSX.Element;
+/**
+ * 主题偏好工具
+ *
+ * 为界面主题提供偏好取值类型、偏好定义构造与生效暗色判定，
+ * 异常取值一律回落跟随系统
+ */
+/**
+ * 主题偏好取值
+ */
+type ThemePreference = 'light' | 'dark' | 'system';
+/**
+ * 主题偏好定义形态
+ */
+type ThemePreferenceDefinition = ReturnType<typeof defineThemePreference>;
+/**
+ * 构造主题偏好定义
+ *
+ * @remarks
+ *   仅接受 `light` 与 `dark` 与 `system` 三个合法取值，键缺失与其余异常取值一律回落 `system`，
+ *   让首次使用与存储异常都收敛到跟随系统偏好的形态
+ * @param key - 完整存储键名，约定挂消费方命名空间前缀
+ * @param tier - 偏好存储层级
+ * @returns 主题偏好定义
+ */
+declare function defineThemePreference(key: string, tier: 'persistent' | 'session'): import("@longzai-intelligence-layout/preferences").PreferenceDefinition<ThemePreference>;
+/**
+ * 包内默认主题偏好定义
+ *
+ * @default 键 `layout.theme`，层级 persistent
+ */
+declare const defaultThemePreference: import("@longzai-intelligence-layout/preferences").PreferenceDefinition<ThemePreference>;
+/**
+ * 解析主题偏好的生效暗色标记
+ *
+ * @param preference - 主题偏好
+ * @param systemPrefersDark - 系统当前是否偏好暗色
+ * @returns 生效主题是否为暗色
+ */
+declare function resolveThemeDark(preference: ThemePreference, systemPrefersDark: boolean): boolean;
+/**
+ * 界面主题状态形态
+ */
+type ThemeState = {
+  /**
+   * 当前主题偏好，初值读本地存储，缺省跟随系统
+   */
+  preference: ThemePreference;
+  /**
+   * 切换主题偏好并记忆到本地存储
+   *
+   * @param next - 切换后的主题偏好
+   */
+  setPreference: (next: ThemePreference) => void;
+};
+/**
+ * 主题偏好读写绑定形态
+ */
+type ThemePreferenceBinding = {
+  /**
+   * 当前主题偏好
+   */
+  preference: ThemePreference;
+  /**
+   * 切换主题偏好动作，切换即持久化
+   */
+  setPreference: (next: ThemePreference) => void;
+};
+/**
+ * 主题控制器形态
+ */
+type ThemeController = {
+  /**
+   * 全局主题偏好 store，切换动作随写随存
+   */
+  useStore: UseBoundStore<StoreApi<ThemeState>>;
+  /**
+   * 订读生效暗色标记
+   *
+   * @returns 生效主题是否为暗色，系统偏好变化与偏好切换实时更新
+   */
+  useResolvedDark: () => boolean;
+  /**
+   * 主题应用同步 hook，全局挂载一次，生效暗色标记变化时应用到文档根元素
+   */
+  useSync: () => void;
+  /**
+   * 主题偏好读写 hook
+   *
+   * @returns 当前主题偏好与切换动作的绑定，切换即持久化
+   */
+  usePreference: () => ThemePreferenceBinding;
+  /**
+   * 渲染前按 store 当前偏好同步应用主题，供应用入口在首次渲染前调用以避免暗色用户首帧闪亮
+   */
+  applyFromStorage: () => void;
+};
+/**
+ * 主题控制器选项
+ */
+type CreateThemeControllerOptions = {
+  /**
+   * 主题偏好定义
+   *
+   * @default 包内默认定义，键 `layout.theme`
+   */
+  preference?: ThemePreferenceDefinition;
+};
+/**
+ * 创建主题控制器
+ *
+ * @param options - 主题控制器选项
+ * @returns 主题控制器实例
+ */
+declare function createThemeController(options?: CreateThemeControllerOptions): ThemeController;
+/**
+ * 主题切换组件属性
+ */
+type ThemeSwitcherProps = {
+  /**
+   * 主题控制器实例
+   */
+  controller: ThemeController;
+};
+/**
+ * 主题切换组件
+ *
+ * @param options - 主题切换组件属性
+ * @param options.controller - 主题控制器实例
+ * @returns 三态分段切换控件
+ */
+declare function ThemeSwitcher({ controller }: ThemeSwitcherProps): import("react").JSX.Element;
+export { type CreateDesignLanguageControllerOptions, type CreateThemeControllerOptions, type DesignLanguageController, type DesignLanguageOption, type DesignLanguagePreferenceBinding, type DesignLanguagePreferenceDefinition, type DesignLanguageState, DesignLanguageSwitcher, type DesignLanguageSwitcherProps, type ThemeController, type ThemePreference, type ThemePreferenceBinding, type ThemePreferenceDefinition, type ThemeState, ThemeSwitcher, type ThemeSwitcherProps, createDesignLanguageController, createThemeController, defaultThemePreference, defineDesignLanguagePreference, defineThemePreference, resolveThemeDark };

package/dist/index.js

@@ -0,0 +1 @@
+import{definePreference as e,enumCodec as t,readPreference as n,writePreference as r}from"@longzai-intelligence-layout/preferences";import{useEffect as i,useSyncExternalStore as a}from"react";import{create as o}from"zustand";import{Layers as s,Monitor as c,Moon as l,Sun as u}from"lucide-react";import{jsx as d}from"react/jsx-runtime";function f(e,t){t===e?delete document.documentElement.dataset.designLanguage:document.documentElement.dataset.designLanguage=t}function p(e){let t=e.options.map(e=>e.value),a=o(i=>({preference:n(e.preference),setPreference:n=>{t.includes(n)&&(r(e.preference,n),i({preference:n}))}}));function s(){let t=a(e=>e.preference);i(()=>{f(e.defaultLanguage,t)},[t])}function c(){return{preference:a(e=>e.preference),setPreference:a(e=>e.setPreference)}}return{useStore:a,options:e.options,defaultLanguage:e.defaultLanguage,useSync:s,usePreference:c,applyFromStorage:()=>{let t=a.getState().preference;f(e.defaultLanguage,t)}}}function m(n,r,i,a){return e({key:i,tier:a},t(n,r))}function h({controller:e,icons:t={}}){let{preference:n,setPreference:r}=e.usePreference();return/* @__PURE__ */ d(`div`,{role:`group`,"aria-label":`设计语言`,className:`flex shrink-0 overflow-hidden rounded-md border border-input`,children:e.options.map(({value:e,label:i})=>{let a=t[e]??s;return/* @__PURE__ */ d(`button`,{type:`button`,"aria-pressed":n===e,"aria-label":i,title:i,onClick:()=>r(e),className:`flex h-7 w-8 items-center justify-center transition-colors ${n===e?`bg-primary text-primary-foreground`:`bg-card text-muted-foreground hover:bg-accent`}`,children:/* @__PURE__ */ d(a,{size:13,"aria-hidden":!0})},e)})})}const g=[`light`,`dark`,`system`];function _(n,r){return e({key:n,tier:r},t(g,`system`))}const v=_(`layout.theme`,`persistent`);function y(e,t){return e===`dark`||e===`system`&&t}function b(e){document.documentElement.classList.toggle(`dark`,e),document.documentElement.style.colorScheme=e?`dark`:`light`}function x(e){let t=window.matchMedia(`(prefers-color-scheme: dark)`);return t.addEventListener(`change`,e),()=>{t.removeEventListener(`change`,e)}}function S(e={}){let t=e.preference??v,s=o(e=>({preference:n(t),setPreference:n=>{r(t,n),e({preference:n})}}));function c(){return y(s(e=>e.preference),a(x,()=>window.matchMedia(`(prefers-color-scheme: dark)`).matches,()=>!1))}function l(){let e=c();i(()=>{b(e)},[e])}function u(){return{preference:s(e=>e.preference),setPreference:s(e=>e.setPreference)}}return{useStore:s,useResolvedDark:c,useSync:l,usePreference:u,applyFromStorage:()=>{let e=s.getState().preference;b(y(e,window.matchMedia(`(prefers-color-scheme: dark)`).matches))}}}const C=[{value:`light`,label:`浅色主题`,Icon:u},{value:`dark`,label:`深色主题`,Icon:l},{value:`system`,label:`跟随系统`,Icon:c}];function w({controller:e}){let{preference:t,setPreference:n}=e.usePreference();return/* @__PURE__ */ d(`div`,{role:`group`,"aria-label":`界面主题`,className:`flex shrink-0 overflow-hidden rounded-md border border-input`,children:C.map(({value:e,label:r,Icon:i})=>/* @__PURE__ */ d(`button`,{type:`button`,"aria-pressed":t===e,"aria-label":r,title:r,onClick:()=>n(e),className:`flex h-7 w-8 items-center justify-center transition-colors ${t===e?`bg-primary text-primary-foreground`:`bg-card text-muted-foreground hover:bg-accent`}`,children:/* @__PURE__ */ d(i,{size:13,"aria-hidden":!0})},e))})}export{h as DesignLanguageSwitcher,w as ThemeSwitcher,p as createDesignLanguageController,S as createThemeController,v as defaultThemePreference,m as defineDesignLanguagePreference,_ as defineThemePreference,y as resolveThemeDark};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@longzai-intelligence-layout/theming",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence 双正交轴主题接线包：明暗轴与设计语言轴",
+  "keywords": [
+    "design-language",
+    "layout",
+    "longzai-intelligence",
+    "theming"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:unit": "bun test src/__tests__/unit/",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-layout/preferences": "0.0.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.17.0",
+    "tailwind-merge": "^3.6.0",
+    "zustand": "^5.0.15"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^20.11.2",
+    "react": "19.2.6",
+    "react-dom": "19.2.6"
+  },
+  "peerDependencies": {
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.