skinsuite 0.1.0 → 0.2.0

package/src/vue/view-page.ts

@@ -0,0 +1,99 @@
+/**
+ * 页面工厂 —— 「这一页接入可换 UI 机制」的**唯一写法**（内核版）
+ *
+ * === 它收掉的是什么 ===
+ * 三个页面文件原先各自抄了一遍同样的机制：声明 glob → `createViewRegistry` →
+ * `createViewPicker` → 两个转发函数。机制逐字相同，改一条口径要改三处。现在机制只在
+ * 这里写一次，页面文件退化成「一份契约 + 一次声明」。
+ *
+ * === 版式组件从哪来 ===
+ * `themeViews` 来自 `virtual:theme` 插件（主题目录 = `VITE_THEME_DIR`，构建期扫
+ * `themes/<包>/<设备>/<页面>/index.vue` 按页面分组）。页面文件**不自己 glob、也不 import
+ * `virtual:theme`**：`loaders` 在取名（渲染期）由 `themeViewsFor(page)` 惰性解析 ——
+ * 注册时零依赖，`virtual:theme` 反过来副作用 import 页面文件时才不会踩循环。
+ *
+ * === 页面名从哪来 ===
+ * 页面名同时是：目录名、`views/<页面>.ts` 的文件名、路由 path 的末段。三处必须字面一致。
+ *
+ * === 页面身份与路由的关系（2026-10-18 解耦）===
+ * 页面清单是**宿主事实**（router 固定声明 `/<page>` 等主路由），本工厂只注册
+ * 「页面名 → 版式」，**不驱动路由、不声明标题**（`document.title` 归路由）。容器里
+ * `<ThemeView page="...">` 的 `page` 与路由 path 靠字面一致对齐。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（从 oauth21/src/theme/views/page.ts 下沉；2026-10-18 惰性 loader 解析）
+ */
+import type { ViewRegistry, ViewPickerSource } from './view-registry';
+import { createViewRegistry, createViewPicker } from './view-registry';
+import { themeViewsFor } from './theme-views';
+
+/** 页面对象的运行时标记（`Symbol.for` = 跨模块实例也同一个键） */
+const PAGE_BRAND = Symbol.for('mauth.themePage');
+
+export interface ThemePageOptions {
+  /** 页面名（目录名 / 文件名 / 路由末段三处一致） */
+  page: string;
+}
+
+/** 一个页面接入版式机制后的全部能力（页面文件的公开面就长这样） */
+export interface ThemePage {
+  readonly page: string;
+  readonly views: ViewRegistry;
+  pick(source?: ViewPickerSource): string;
+}
+
+/** 已自动注册的页面（页面域；按页面名取 `ThemePage`） */
+const registeredPages = new Map<string, ThemePage>();
+
+/**
+ * 声明一个页面
+ *
+ * 用法（页面文件里就这么多）：
+ * ```ts
+ * defineThemePage({ page: 'login' });
+ * ```
+ *
+ * 无 `device` 字段：设备归一化由设备域自动提供。
+ * 无 `envView` 字段：部署级默认版式（`VITE_<PAGE>_VIEW`）机制已取消。
+ * 无 `title` 字段：标题（`document.title`）是路由职责，由宿主路由表声明（router 与主题分层）。
+ * 无 `loaders` 字段：版式组件清单由 `themeViewsFor(page)` 惰性解析（`virtual:theme` 装单例）。
+ */
+export function defineThemePage(options: ThemePageOptions): ThemePage {
+  const { page } = options;
+  const views = createViewRegistry(() => themeViewsFor(page), { page });
+  const picker = createViewPicker({ registry: views });
+
+  const result: ThemePage = {
+    page,
+    views,
+    pick: (source: ViewPickerSource = {}) => picker.pick(source)
+  };
+  // 标记不可枚举：它只是个身份戳，不该出现在日志 / 序列化里
+  Object.defineProperty(result, PAGE_BRAND, { value: true, enumerable: false });
+  registeredPages.set(page, result);
+  return result;
+}
+
+/** 这个值是不是 `defineThemePage` 的产物 */
+export function isThemePage(value: unknown): value is ThemePage {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    (value as Record<PropertyKey, unknown>)[PAGE_BRAND] === true
+  );
+}
+
+/** 按页面名取已注册的页面（`<ThemeView>` 内部用）；未注册返回 undefined */
+export function pageOf(name: string): ThemePage | undefined {
+  return registeredPages.get(name);
+}
+
+/** 已注册的页面名清单（调试面板用） */
+export function registeredPageNames(): readonly string[] {
+  return [...registeredPages.keys()];
+}
+
+/** 重置模块级页面域（单测 / HMR 用） */
+export function resetPages(): void {
+  registeredPages.clear();
+}

package/src/vue/view-registry.ts

@@ -0,0 +1,215 @@
+/**
+ * 版式（view）注册表 + 选择器 —— 「业务容器 + 可换 UI」的通用机制（内核版）
+ *
+ * === 这一层解决什么 ===
+ * 页面拆成两半：
+ *   · **业务容器** —— 状态、校验、请求、路由跳转。只此一份。
+ *   · **版式（UI）** —— 只负责「长什么样」，通过 props 拿到容器给的 `ctx` 来渲染与回调。
+ * 于是「换一套 UI」= 加一个目录，不用碰业务代码，也不会出现两份校验逻辑各自漂移。
+ *
+ * === 版式跟随主题包与设备 ===
+ * 版式实现住在主题包里、且按设备分区（`themes/<包>/<设备>/<page>/index.vue`），
+ * 查找范围就是**当前主题包 × 当前设备**。契约与注册表是**每页一份**的页面文件
+ * （`views/<page>.ts`），留在宿主架构层，所有包共用一份。
+ *
+ * === 选择优先级（高 → 低）===
+ *   1. URL `?th[_<设备缩写>]`  2. 主题包/配色声明的 `views.<page>`
+ *   3. 当前包名（一个主题包 = 一种版式 ⇒ 版式 id ≡ 包名）
+ * 🔴 第 1 档命中后不再回退；非法值一律落当前包名。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（从 oauth21 下沉；2026-10-17 末合并原 view-picker.ts，共 180 行）
+ */
+import type { Component } from 'vue';
+import { registeredDevices } from './define-theme-device';
+
+/**
+ * 版式组件加载表形态：键 → 加载器
+ *
+ * 内置包（`default`）的加载器由 `virtual:theme` 插件**同步**返回（eager 静态 import，
+ * 零请求首屏）；非内置包返回 `Promise`（`import()` 惰性 chunk）。`await` 对两者都成立，
+ * 但只有同步形态能支撑「首帧同步拿到内置包版式」的 `builtin()` 路径。
+ */
+export type ViewModuleLoader = () => { default: Component } | Promise<{ default: Component }>;
+export type ViewModuleMap = Record<string, ViewModuleLoader>;
+/**
+ * 版式加载表的**惰性提供者**：`() => ViewModuleMap`。
+ *
+ * 页面契约文件在注册时（`defineThemePage`）可能早于 `virtual:theme` 把 `themeViews`
+ * 装入单例，所以建注册表时**不立即读**加载表，而是传一个 provider，等首次查询
+ * （渲染期）再取 —— 既打破「页面契约 → virtual:theme」的循环，又保证取到的是终态。
+ */
+export type ViewModuleProvider = () => ViewModuleMap;
+
+/** 某个主题包在**某设备**该页登记了哪些版式 */
+export interface PackageViews {
+  pkg: string;
+  device: string;
+  ids: string[];
+}
+
+export interface ViewRegistry {
+  readonly baseId: string;
+  readonly builtinPackage: string;
+  packages(): PackageViews[];
+  has(raw: unknown, pkg: string, device: string): boolean;
+  resolve(raw: unknown, pkg: string, device: string): string | null;
+  load(id: string | null, pkg: string, device: string): Promise<Component | null>;
+  /** 内置包（`default`）在**某设备**该页的版式组件（同步，eager 静态 import；无则 null） */
+  builtin(device: string): Component | null;
+}
+
+export interface ViewRegistryOptions {
+  page: string;
+  baseId?: string;
+  builtinPackage?: string;
+  idRe?: RegExp;
+}
+
+/** 选择器的输入：四个都是外部值，全部未校验 */
+export interface ViewPickerSource {
+  url?: unknown;
+  theme?: unknown;
+  pkg?: unknown;
+  device?: unknown;
+}
+
+export interface ViewPicker {
+  pick(source?: ViewPickerSource): string;
+}
+
+export interface ViewPickerOptions {
+  registry: ViewRegistry;
+}
+
+const DEFAULT_VIEW_ID_RE = /^[a-z0-9-]+$/;
+
+function asText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+
+/** 设备名是否在设备域白名单里（`defineThemeDevice` 自动注册） */
+function isKnownDevice(raw: unknown): raw is string {
+  return typeof raw === 'string' && registeredDevices().some(d => d.id === raw);
+}
+
+/** 归一化设备名：不在白名单返回空串（建表时据此跳过非法设备目录） */
+function normalizeDevice(raw: string): string {
+  return isKnownDevice(raw) ? raw : '';
+}
+
+export function createViewRegistry(
+  loaders: ViewModuleMap | ViewModuleProvider,
+  options: ViewRegistryOptions
+): ViewRegistry {
+  const baseId = options.baseId ?? 'base';
+  const builtinPackage = options.builtinPackage ?? 'default';
+  const idRe = options.idRe ?? DEFAULT_VIEW_ID_RE;
+  const { page } = options;
+  if (!idRe.test(page)) {
+    throw new Error(`[view] page 名「${page}」不合规：只允许小写字母/数字/短横线`);
+  }
+
+  // 惰性提供者：注册时可能还拿不到 `themeViews`（`virtual:theme` 还没装单例），
+  // 所以这里只记「怎么取」，首次查询（渲染期）才真正建 `bases` 表。
+  const resolveLoaders = typeof loaders === 'function' ? loaders : () => loaders;
+  const scopeKey = (pkg: string, device: string): string => `${pkg}/${device}`;
+
+  // 🔴 键形与 `virtual:theme` 的 `themeViews` 一致：`./<包>/<设备>/<页面>/index.vue`
+  //    （相对 `themes/` 目录，`./` 开头）—— 不再是 `import.meta.glob('/src/theme/themes/...')`
+  //    那种 `/src/...` 根绝对路径键。改键形（2026-10-18）后这里必须同步，否则建空表。
+  const baseKeyRe = new RegExp(`^\\./([^/]+)/([^/]+)/${page}/index\\.vue$`);
+
+  let bases: Map<string, ViewModuleLoader> | null = null;
+  const ensure = (): Map<string, ViewModuleLoader> => {
+    if (bases) return bases;
+    bases = new Map();
+    for (const [key, loader] of Object.entries(resolveLoaders())) {
+      const m = baseKeyRe.exec(key);
+      const pkg = m?.[1];
+      const device = m?.[2];
+      if (!pkg || !device) continue;
+      if (!idRe.test(pkg)) continue;
+      if (normalizeDevice(device) !== device) continue;
+      bases.set(scopeKey(pkg, device), loader);
+    }
+    return bases;
+  };
+
+  const resolve = (raw: unknown, pkg: string, device: string): string | null => {
+    if (typeof raw !== 'string') return null;
+    const id = raw.trim().toLowerCase();
+    if (!id || !idRe.test(id)) return null;
+    if (id === baseId) return pkg;
+    const b = ensure();
+    if (b.has(scopeKey(id, device))) return id;
+    if (id === pkg && b.has(scopeKey(pkg, device))) return pkg;
+    return null;
+  };
+
+  return {
+    baseId,
+    builtinPackage,
+    packages() {
+      const b = ensure();
+      return [...b.keys()]
+        .map(k => {
+          const cut = k.indexOf('/');
+          return { pkg: k.slice(0, cut), device: k.slice(cut + 1) };
+        })
+        .sort((a, b2) => `${a.pkg}/${a.device}`.localeCompare(`${b2.pkg}/${b2.device}`))
+        .map(({ pkg, device }) => ({ pkg, device, ids: [pkg] }));
+    },
+    has: (raw, pkg, device) => resolve(raw, pkg, device) !== null,
+    resolve,
+    async load(id, pkg, device) {
+      if (!id || !idRe.test(pkg)) return null;
+      const b = ensure();
+      const target = id !== pkg && b.has(scopeKey(id, device)) ? id : pkg;
+      const loader = b.get(scopeKey(target, device));
+      if (!loader) return null;
+      try {
+        return (await loader()).default ?? null;
+      } catch (err) {
+        console.warn(`[view] 主题包「${target}」${device} 端的版式加载失败，已回退`, err);
+        return null;
+      }
+    },
+    builtin(device) {
+      const loader = ensure().get(scopeKey(builtinPackage, device));
+      if (!loader) return null;
+      const mod = loader();
+      // 内置包是 eager 静态 import → 同步返回模块命名空间；非内置包才是 Promise
+      return mod instanceof Promise ? null : (mod.default ?? null);
+    }
+  };
+}
+
+/** 选择器工厂：从外部输入挑出版式 id（永远返回可用 id，最差是当前包名） */
+export function createViewPicker(options: ViewPickerOptions): ViewPicker {
+  const { registry } = options;
+
+  function asPackage(value: unknown): string {
+    return asText(value) ?? registry.builtinPackage;
+  }
+
+  function asDevice(value: unknown): string {
+    // 设备名归一化：白名单命中取原值，否则兜底到末条 fallback 设备
+    if (isKnownDevice(value)) return value;
+    const defs = registeredDevices();
+    return defs[defs.length - 1]?.id ?? '';
+  }
+
+  function pick(source: ViewPickerSource = {}): string {
+    const pkg = asPackage(source.pkg);
+    const device = asDevice(source.device);
+    const url = asText(source.url);
+    // 第 1 档：URL 显式意图 —— 非法值也**不回退**到下面的档
+    if (url) return registry.resolve(url, pkg, device) ?? pkg;
+
+    // 第 2 档 → 第 3 档：主题包/配色声明 → 当前包（一个主题包 = 一种版式）
+    return registry.resolve(source.theme, pkg, device) ?? pkg;
+  }
+
+  return { pick };
+}

package/src/vue/viewport.ts

@@ -0,0 +1,54 @@
+/**
+ * 视口 / UA 设备形态判定（**纯浏览器判定**，SSR 安全）
+ *
+ * 从 `oauth21/src/utils/device.ts` 下沉（2026-10-19）。判定口径只有这一份：
+ * 设备域（`device-domain`）用它的响应式版判「当前设备」，宿主守卫 / 请求拦截等
+ * 用它的纯函数版判「跳哪个登录页」—— 两边同源，不再漂移。
+ *
+ * === 判定口径（三级，宽视口优先于 UA）===
+ *   1. 视口 ≥ 1024px（DESKTOP_MIN_WIDTH）→ 电脑版（UA 说什么都不例外）
+ *   2. 视口 < 768px（MOBILE_BREAKPOINT）→ 移动端
+ *   3. 中间段（768–1023）→ UA 命中真机才算移动端（该区间可能是被缩放的桌面浏览器）
+ *
+ * === 为什么宽视口优先于 UA（2026-09-21 线上问题）===
+ * 平板横屏 / 折叠屏展开 / 手机开「桌面版网站」时 UA 仍报手机、视口却有 1024px+，
+ * 恒定按 UA 判移动端会把移动端版式铺满整屏。宽度比 UA 更贴近「这块屏放不放得下
+ * 桌面布局」这个真问题。
+ *
+ * @author yijiu2025
+ * @since 2026-10-19（从 oauth21/src/utils/device.ts 下沉，供设备域与宿主共用）
+ */
+
+/** 移动端判定阈值（px）：窄于它说明视口放不下桌面双栏布局 */
+export const MOBILE_BREAKPOINT = 768;
+
+/** 桌面端判定阈值（px）：宽于等于它说明屏幕放得下完整桌面布局（对齐 Tailwind lg 断点） */
+export const DESKTOP_MIN_WIDTH = 1024;
+
+/**
+ * UA 兜底检测：视口宽度会被窗口缩放 / 分屏 / DevTools 模拟影响，
+ * UA 能识别「真手机/平板」（新版 iPad UA 已不含 iPad，走 maxTouchPoints 兜底）。
+ */
+export function detectMobileUA(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  const ua = navigator.userAgent || '';
+  const uaMobile = /Android|iPhone|iPod|Windows Phone|IEMobile|BlackBerry|Opera Mini/i.test(ua);
+  const iPadLike =
+    /iPad/i.test(ua) ||
+    (/Macintosh/i.test(ua) && typeof navigator.maxTouchPoints === 'number' && navigator.maxTouchPoints > 1);
+  return uaMobile || iPadLike;
+}
+
+/** 视口是否已宽到该用电脑版（只看宽度，不看 UA） */
+export function isDesktopViewport(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.innerWidth >= DESKTOP_MIN_WIDTH;
+}
+
+/** 当前是否应按移动端处理（一次性判定；SSR / 无 window 环境返回 false = 桌面默认） */
+export function isMobileViewport(): boolean {
+  if (typeof window === 'undefined') return false;
+  if (isDesktopViewport()) return false;
+  if (detectMobileUA()) return true;
+  return window.innerWidth < MOBILE_BREAKPOINT;
+}

package/src/mode.ts

@@ -1,38 +0,0 @@
-/**
- * 明暗意图（mode）的取值、循环顺序与展示文案
- *
- * 🔴 明暗 ≡ 色系（2026-09-25 定）：「明暗切换就是切换白色和黑色这个色系，不是另一套规则」。
- *   mode 不是独立于配色的第二个维度，而是「切到哪一系别」的意图：
- *     light  —— 明 = 白系
- *     dark   —— 暗 = 黑系
- *     system —— 跟随系统偏好（系统暗→黑系、亮→白系）
- *   最终明暗由**当前配色的 tone** 决定（见 `oauth21/src/stores/theme.ts` 的 `isDark`）。
- *   点色卡同步 mode（点黑卡=dark、点白卡=light），切 mode 联动配色 —— 永远一致。
- *
- * @author yijiu2025
- */
-
-/** 明暗三态：'system' 显式跟随系统（旧版只有布尔值，切过就回不来） */
-export type ThemeMode = 'system' | 'light' | 'dark';
-
-/** 切换按钮的循环顺序：跟随系统 → 浅色 → 深色 → 跟随系统 */
-export const MODE_CYCLE: readonly ThemeMode[] = ['system', 'light', 'dark'];
-
-/** 界面与无障碍标签用的中文文案（明=白系 / 暗=黑系 / 跟随系统） */
-export const MODE_LABELS: Record<ThemeMode, string> = {
-  system: '跟随系统',
-  light: '明',
-  dark: '暗'
-};
-
-/** 是否是合法的明暗取值（用于校验 URL 参数、后端下发这类不可信输入） */
-export function isThemeMode(value: unknown): value is ThemeMode {
-  return value === 'system' || value === 'light' || value === 'dark';
-}
-
-/** 归一化外部输入：大小写与首尾空白容忍，非法返回 null（由调用方决定回退） */
-export function normalizeMode(raw: unknown): ThemeMode | null {
-  if (typeof raw !== 'string') return null;
-  const v = raw.trim().toLowerCase();
-  return isThemeMode(v) ? v : null;
-}

package/src/tone.ts

@@ -1,56 +0,0 @@
-/**
- * 配色的「明暗系别」（tone）
- *
- * 与 `mode`（明暗偏好）是两个不同的维度，本模块负责把它们**关联起来做联动**：
- *   • tone —— 一套配色**自带**的属性：它的底是浅色还是深色
- *       'light' 白系：浅底深字（white / blue / cyan / rainbow）
- *       'dark'  黑系：深底浅字（black）
- *   • mode —— 用户的明暗偏好（'system' | 'light' | 'dark'，见 ./mode）
- *
- * === 联动规则（用户 2026-09-25 定）===
- *   🔴 明暗 ≡ 色系：「明暗切换就是切换白色和黑色这个色系，不是另一套规则」。
- *   切「暗」→ 落到黑系配色、切「明」→ 落到白系配色，两侧各自记住上一次的选择，
- *   切回来即恢复。例如：白系用 blue，切「暗」→ 自动变 black，切「明」→ 回到 blue。
- *   实现见 `oauth21/src/stores/theme.ts` 的「双侧记忆槽」。
- *
- * ⚠️ 它**不是 CSS 的一部分**：不是 token，不会写成 `--mauth-*` 变量，
- *    也不参与渲染。唯一用途是让 store 判断"当前配色与目标明暗是否一致"。
- *
- * ⚠️ 与 tokens 的分档无关：自 2026-09-25 起 `tokens` 是一组扁平值，
- *    一套配色内部不再分深浅两档 —— tone 描述的是**配色之间**的关系，
- *    不是"一套配色内部的明暗两档"。别再把它理解成旧版的 `light`/`dark` 两块。
- *
- * ⚠️ 明暗与配色**保持一致**：点色卡同步把明暗设成该配色的系别（点黑卡=暗、
- *    点白卡=明），切明暗联动把配色切到目标系别 —— 两条路径互相咬合，不撕裂。
- *
- * @author yijiu2025
- */
-
-/** 明暗系别：配色自带的底色深浅 */
-export type ThemeTone = 'light' | 'dark';
-
-/** 全部系别（遍历 / 校验用；顺序与界面展示一致） */
-export const THEME_TONES: readonly ThemeTone[] = ['light', 'dark'];
-
-/** 界面与日志用的中文文案 */
-export const TONE_LABELS: Record<ThemeTone, string> = {
-  light: '白系',
-  dark: '黑系'
-};
-
-/** 是否是合法的系别取值（用于校验外部输入这一类不可信来源） */
-export function isThemeTone(value: unknown): value is ThemeTone {
-  return value === 'light' || value === 'dark';
-}
-
-/**
- * 归一化外部输入：容忍大小写与首尾空白，非法返回 null（由调用方决定回退）
- *
- * ⚠️ 与 `mode` 不同，这里**没有** `'system'` —— 系别是配色自带的属性，
- *    不存在"跟随系统"这回事。
- */
-export function normalizeTone(raw: unknown): ThemeTone | null {
-  if (typeof raw !== 'string') return null;
-  const v = raw.trim().toLowerCase();
-  return isThemeTone(v) ? v : null;
-}