skinsuite 0.1.0 → 0.2.1

package/src/views/device.ts

@@ -0,0 +1,107 @@
+/**
+ * 设备清单机制（**纯逻辑半边**）—— 「哪些设备、怎么判定」的唯一实现（内核版）
+ *
+ * === 设备 = 路由 + 容器 = 版式信息的一部分 ===
+ * 「有哪些设备」是宿主的部署事实（每个应用设备不同、容器位置不同），所以**设备清单
+ * （`DeviceDef[]`）由宿主声明**；但「怎么从清单判定出当前设备、怎么归一化外部输入、
+ * 怎么取容器」是**通用机制**，收在这里 —— 加一种设备时宿主只加一条声明，判定逻辑零改动。
+ *
+ * === 为什么这里只有「判定」、没有「组件」 ===
+ * 本文件是**纯逻辑**（不含 `Component` 类型），能被内核 tsc 独立检查、也能被任何前端复用。
+ * `containers` 用泛型 `T` 表达（宿主的「设备容器加载器」是 `T`），组件加载的**具体机制**
+ * （`pageContainers` / `resolveContainerOf`）在 `skinsuite/vue` 的 `device-containers`，
+ * 那里才 import Vue 的 `Component`。
+ *
+ * === 判定顺序就是清单顺序（先命中先用），最后一条必须无条件成立 ===
+ * 它是兜底设备。宿主关卡会核这一条。
+ *
+ * === 为什么判定必须收在一处 ===
+ * 三个分发器曾经各写一份「mini 来源」判定，口径不一致 → 同一个链接在不同页面落到
+ * 不同设备。现在判定只有一份，各页面自然同形。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17（从 oauth21/src/theme/devices.ts 下沉）
+ */
+
+/** 判定上下文 —— 判定所需的**全部**外部信息（与页面无关的原始事实） */
+export interface DeviceMatchContext {
+  /** `?isMobile=true` —— 显式意图，优先级最高 */
+  explicitMobile: boolean;
+  /** 路由 path（不含 query / hash） */
+  path: string;
+  /** `?from=` 的取值（iframe 来源标记，空串表示没给） */
+  from: string;
+  /** `?fromLogin=` 的取值（历史键：从 mini 登录页跳来） */
+  fromLogin: string;
+  /** 视口/UA 判定结果 */
+  viewportIsMobile: boolean;
+}
+
+/** 一条设备声明（`containers` 是泛型：纯逻辑侧不关心它到底是什么，只透传） */
+export interface DeviceDef<T = unknown> {
+  /** 设备 id = 主题包内的目录名，只允许 `[a-z0-9-]` */
+  id: string;
+  /** 中文名（调试面板 / 日志用） */
+  label: string;
+  /** 缩写名（URL 专属参数后缀用，如 `?th_<urlKey>` / `?th_color_<urlKey>`）；缺省回落 `id` */
+  urlKey?: string;
+  /** 该设备在某页的容器（分发器渲染它）；返回 undefined 表示「该设备没有这一页的容器」 */
+  containers: ReadonlyMap<string, T>;
+  /** 该设备在路由表里占的 path（相对根，`{page}` 由页面名替换） */
+  routePath(page: string): string;
+  /** 本次访问是否属于这台设备（清单顺序 = 优先级，先命中先用） */
+  match(ctx: DeviceMatchContext): boolean;
+}
+
+/** 归一化外部传入的设备名；不认识的取值返回 null（**不是**落默认设备） */
+export function asDeviceId<T extends string>(
+  known: readonly string[],
+  raw: unknown
+): T | null {
+  return typeof raw === 'string' && (known as readonly string[]).includes(raw)
+    ? (raw as T)
+    : null;
+}
+
+/** 设备 id → 中文名（调试面板用；加设备不必再改面板） */
+export function deviceLabel<T>(defs: readonly DeviceDef<T>[], id: string): string {
+  return defs.find(def => def.id === id)?.label ?? id;
+}
+
+/** 从外部输入判定「本次访问属于哪台设备」；清单顺序 = 优先级，返回值永远非空 */
+export function pickDeviceId<T>(
+  defs: readonly DeviceDef<T>[],
+  ctx: DeviceMatchContext,
+  defaultDevice: string
+): string {
+  for (const def of defs) {
+    if (def.match(ctx)) return def.id;
+  }
+  // 清单被改坏（末条不再无条件成立）时的保底
+  return defaultDevice;
+}
+
+/** 取某设备的容器表；未知设备返回空表（调用方退到兜底设备） */
+export function containersOf<T>(
+  defs: readonly DeviceDef<T>[],
+  id: string
+): ReadonlyMap<string, T> {
+  return defs.find(def => def.id === id)?.containers ?? new Map();
+}
+
+/** 从当前访问信息构造判定上下文 */
+export function deviceContext(
+  query: Record<string, unknown> | undefined,
+  path: string,
+  viewportIsMobile: boolean
+): DeviceMatchContext {
+  const text = (key: string): string =>
+    typeof query?.[key] === 'string' ? (query[key] as string) : '';
+  return {
+    explicitMobile: text('isMobile') === 'true',
+    path: path.split(/[?#]/)[0],
+    from: text('from'),
+    fromLogin: text('fromLogin'),
+    viewportIsMobile
+  };
+}

package/src/views/params.ts

@@ -1,16 +1,22 @@
 /**
- * 版式参数的**设备维度**解析 —— `?view.<设备>` 支持
+ * 版式 / 配色参数的**设备维度**解析 —— `?th` / `?th_color`（下划线 + 设备缩写名）
+ *
+ * === 参数命名（2026-10-18 定稿，统一用下划线、禁用点号）===
+ *   版式：`?th`（三端通用）          `?th_<设备缩写>`（某设备专属）
+ *   配色：`?th_color`（三端通用）     `?th_color_<设备缩写>`（某设备专属）
+ *   设备专属键的后缀是**设备缩写名（urlKey）**，不是设备 id —— 由设备清单声明
+ *   （`defineThemeDevice` 的 `urlKey`，缺省回落 `id`），内核不硬编码任何缩写。
  *
  * === 解决什么 ===
  * 同一条链接要能给三台设备各指定一套版式：
  * ```
- * /login?view=compact                               三端共用（哪端没有就自动下沉到当前包）
- * /login?view.mobile=default&view.standard=compact   各端各指定（mini 走通用/包默认）
- * /login?view.mobile=default&view=default            设备专属优先，通用键兜底
+ * /login?th=compact                             三端共用（哪端没有就自动下沉到当前包）
+ * /login?th_mobile=default&th_std=compact       各端各指定（mini 走通用/包默认）
+ * /login?th_mobile=default&th=default           设备专属优先，通用键兜底
  * ```
  *
  * === 取值链（每台设备各一条）===
- *   `view.<设备>`  →  `view`  →  （返回 undefined：由调用方走包声明 → 环境变量 → 当前包）
+ *   `th_<urlKey>`  →  `th`  →  （返回 undefined：由调用方走包声明 → 当前包）
  *
  * === 为什么收在内核（而不是各页文件里）===
  * 三个页面（login / register / forgot-password）各有**一份**注册表文件，但"哪个 query
@@ -21,21 +27,18 @@
  *
  * === 与配色侧同形（很重要）===
  * 配色侧（`oauth21/src/stores/theme.ts` 的 `readUrlIntent`）用同样的键形
- * （`theme.<设备>` / `skin.<设备>`）与同样的"设备专属优先"链。**两侧必须同形**，
- * 否则配置者要记两套规则，`?theme.mobile=blue&view.standard=compact` 这种混搭就写不出来。
+ * （`th_color_<urlKey>` / `th_color`）与同样的"设备专属优先"链。**两侧必须同形**，
+ * 否则配置者要记两套规则，`?th_color_mobile=blue&th_std=compact` 这种混搭就写不出来。
  * 但两侧读的入口不同：配色侧读 `window.location.search`（store 是全局的，不依赖路由），
  * 版式侧读**路由 query**（容器手上只有 `route.query`）—— 所以不是同一个函数，是同一套规则。
  *
- * ⚠️ query key 里带 `.` 是合法的（`URLSearchParams` 与 vue-router 都原样保留），
- *    但访问时**必须用下标**（`query['view.standard']`）—— 点号在 JS 里不是合法标识符。
- *
  * @author yijiu2025
- * @since 2026-09-26
+ * @since 2026-09-26（2026-10-18 改下划线 + urlKey：`?view.` → `?th_`、`?theme.` → `?th_color_`）
  */
 /** 支持设备维度的参数名（与配色侧 `readUrlIntent` 的键保持一致） */
-export type DeviceScopedParam = 'view' | 'theme';
+export type DeviceScopedParam = 'th' | 'th_color';
 
-export const DEVICE_SCOPED_PARAMS: readonly DeviceScopedParam[] = ['view', 'theme'];
+export const DEVICE_SCOPED_PARAMS: readonly DeviceScopedParam[] = ['th', 'th_color'];
 
 /** 值"存在且非空" —— 空串 / 空数组视为**未指定**，不顶掉兜底键 */
 function isPresent(value: unknown): boolean {
@@ -50,26 +53,26 @@ function isPresent(value: unknown): boolean {
 /**
  * 按**设备**读取版式 / 配色参数
  *
- * @param query  路由 query（`route.query`）
- * @param name   参数名（`'view'` / `'theme'`）
- * @param device 当前设备 —— 容器用自己的设备常量传进来（文件位置即身份）
- * @returns `query['<name>.<device>']` 优先；缺席或空值时退 `query[name]`；
+ * @param query     路由 query（`route.query`）
+ * @param name      参数名（`'th'` / `'th_color'`）
+ * @param deviceKey 设备**缩写名（urlKey）** —— 由调用方用 `urlKeyOf(deviceId)` 从设备清单查
+ * @returns `query['<name>_<deviceKey>']` 优先；缺席或空值时退 `query[name]`；
  *          两者都没有则返回 undefined，表示"**这台设备**没有被显式指定"
  *
  * ⚠️ 只决定"取哪个键"，**不做合法性校验** —— 校验属于各页 `pick*ViewId` 与配色注册表
- *    （本函数也拿不到"当前包里有没有这套版式"）。返回值可能是数组（`?view=a&view=b`），
+ *    （本函数也拿不到"当前包里有没有这套版式"）。返回值可能是数组（`?th=a&th=b`），
  *    由下游按"非字符串即非法"处理，与改前的行为一致。
- * ⚠️ 空串视为"未指定"：`?view.standard=` 不该把 `?view=compact` 顶掉 ——
+ * ⚠️ 空串视为"未指定"：`?th_std=` 不该把 `?th=compact` 顶掉 ——
  *    部署方常把参数留空当作"这台设备不特殊指定"。
- * ⚠️ 设备名是**宿主**的词汇表（本包不认识具体取值），所以这里只把它当字符串拼键；
- *    「这个名字认不认得」由宿主的设备清单归一（`asThemeDevice`）。
+ * ⚠️ 缩写名是**宿主**的词汇表（本包不认识具体取值），所以这里只把它当字符串拼键；
+ *    「这个缩写名认不认得」由宿主的设备清单归一（`urlKeyOf`）。
  */
 export function readDeviceParam(
   query: Record<string, unknown> | undefined,
   name: DeviceScopedParam,
-  device: string
+  deviceKey: string
 ): unknown {
-  const scoped = query?.[`${name}.${device}`];
+  const scoped = query?.[`${name}_${deviceKey}`];
   if (isPresent(scoped)) return scoped;
   return query?.[name];
 }

package/src/vite/dir.ts

@@ -0,0 +1,85 @@
+/**
+ * 主题**根目录**的解析入口（构建期，随 `skinsuite/vite` 一起发布）
+ *
+ * 属于主题库自带的构建能力：任何宿主（Vue / React / 任意 Vite 工程）引入
+ * `skinsuite` 后，只要在 `vite.config.ts` 挂上 `themeAssets()` 插件、并把目录解析
+ * 交给本文件的 `resolveThemeDir()`，就**不再需要自己写一行扫描/目录代码**。
+ *
+ * === 为什么走 env 而不是一份 TS 配置文件 ===
+ * 目录是**部署事实**（可能整包换掉一套品牌主题、可能放在 monorepo 的另一处），
+ * 写进源码就意味着换目录要改代码 + 重新 review。env 是"同一份产物服务多个部署"
+ * 的既有通道，目录也走同一条：
+ *
+ *   ```
+ *   VITE_THEME_DIR=src/theme          # 相对宿主工程根；主题**根目录**
+ *   ```
+ *
+ * === `VITE_THEME_DIR` 指向的是「主题根目录」，不是「主题包目录」===
+ * 根目录内是**三个固定子目录/文件**（约定俗成、名字固定，换根目录位置时整包跟着走）：
+ *
+ *   ```
+ *   <根目录>/                          ← VITE_THEME_DIR（如 src/theme）
+ *   ├── theme.config.ts               清单：调试开关（契约 = defineThemeManifest）
+ *   ├── themes/                       主题包目录（一个包 = 一种版式）
+ *   │   ├── default/  ├── compact/
+ *   └── views/                        声明目录（devices.ts 设备声明 + login.ts 等页面契约）
+ *   ```
+ *
+ * 于是「主题域」是**一个自足目录**：换根目录位置时，主题包、清单、声明一起走，
+ * 宿主要改的只有 `VITE_THEME_DIR` 这一个变量。
+ *
+ * ⚠️ `themes` 与 `views` 是**固定子目录名**（不是可配置项）：构建插件扫包目录与
+ *    声明目录都认这两个名字 —— 靠「名字固定」对齐，不靠配置。
+ *
+ * 而**主题域自己的策略**（调试开关、路由投影）不在这里 —— 那份配置跟着主题域走，
+ * 住在根目录的 `theme.config.ts`（契约见 `skinsuite` 的 `defineThemeManifest`）。
+ * 分工是「宿主说根目录在哪」/「主题域说自己怎么用」，不是同一类东西。
+ *
+ * ⚠️ 必须用 `loadEnv()` 读，不能直接 `process.env.VITE_THEME_DIR`：
+ *    vite.config 执行时 Vite 还没加载 `.env` 文件（那只在 config 解析后发生），
+ *    直接读 `process.env` 在 `npm run dev` 下恒 undefined —— 于是永远回落默认值，
+ *    看着能用、改 env 却不生效，属于最难发现的一类。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+import path from 'node:path';
+import { loadEnv } from 'vite';
+
+/**
+ * 缺省主题根目录（相对宿主工程根）
+ *
+ * 留这个默认值是为了 **CI 与独立克隆**：`.env` 通常被 gitignore，全新 checkout 里
+ * 没有它，此时必须仍能构建 —— 否则"没配 env 就构建失败"会把部署门槛抬高。
+ * 宿主可通过 `resolveThemeDir(mode, root, { defaultDir })` 覆盖。
+ */
+export const DEFAULT_THEME_DIR = 'src/theme';
+
+/** 主题根目录内、主题包的子目录名（固定约定，宿主 `views/*.ts` 的字面量 glob 依赖它稳定） */
+export const THEME_PACKAGES_SUBDIR = 'themes';
+
+/** 主题根目录内的版式契约目录名（`views/*.ts`，设备声明 + 页面契约，插件副作用 import 拉齐） */
+export const THEME_VIEWS_SUBDIR = 'views';
+
+/** 主题根目录内的清单文件名（插件按它找 `theme.config.ts`） */
+export const DEFAULT_THEME_MANIFEST = 'theme.config.ts';
+
+/**
+ * 解析主题**根目录**为**绝对路径**
+ *
+ * @param mode  Vite 的 mode（development / production / test …），决定叠加哪个 `.env.<mode>`
+ * @param root  以哪个目录为工程根找 `.env`，缺省 `process.cwd()`
+ * @param opts  可选覆盖：`defaultDir` 缺省回落目录、`envKey` 环境变量名
+ */
+export function resolveThemeDir(
+  mode: string,
+  root: string = process.cwd(),
+  opts: { defaultDir?: string; envKey?: string } = {}
+): string {
+  const envKey = opts.envKey ?? 'VITE_THEME_DIR';
+  const defaultDir = opts.defaultDir ?? DEFAULT_THEME_DIR;
+  // 第三个参数是前缀白名单：只读 VITE_ 开头的，避免把后端密钥之类带进来
+  const env = loadEnv(mode, root, 'VITE_');
+  const configured = (env[envKey] ?? '').trim();
+  return path.resolve(root, configured || defaultDir);
+}

package/src/vite/index.ts

@@ -0,0 +1,41 @@
+/**
+ * `skinsuite/vite` —— 主题库的**构建期适配器**（Vite 插件 + 目录解析）
+ *
+ * 纯内核（`skinsuite`）与 Vue 绑定（`skinsuite/vue`）都刻意不碰构建器，因为
+ * "扫描主题目录"是 Vite 专属的能力（webpack 要写成 `require.context`）。这一半
+ * 收在这里，让宿主在 `vite.config.ts` 里三行接完，不必自己抄扫描逻辑：
+ *
+ * ```ts
+ * import { themeAssets, resolveThemeDir } from 'skinsuite/vite';
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [themeAssets({ dir: resolveThemeDir(mode) })]
+ * }));
+ * ```
+ *
+ * === 为什么这个子路径指向源码 `.ts` 而不是 `dist/` ===
+ * `vite.config.ts` 由 Vite 用 esbuild 预打包后执行，裸包说明符会被当外部依赖交给
+ * Node `import()`。若指向 `dist/`，就要求"包必须先构建" —— CI 里 `npm ci` 不会
+ * 构建工作区包，配置会直接起不来。Vite 自己能转译 TS，源码直供就绕开这个前提，
+ * 与 `skinsuite/vue` 同一手法。
+ *
+ * ⚠️ 本层相对 import **必须用显式 `.ts` 后缀**（`./plugin.ts` 而非 `./plugin` 或
+ *    `./plugin.js`）：
+ *    这个入口是**唯一在 vite.config / vitest.config 里被 import 的子路径**，config
+ *    被 Node 直接执行（Vite 的 config 加载器只 bundle config 自身），Node 既不自动补
+ *    无后缀、也不把 `.js` 映射到 `.ts` 源码。而纯内核（`./tone.js`）走 NodeNext 编译、
+ *    `skinsuite/vue` 走应用代码的 Vite 转译，两者都用不上这个入口的约束，所以这里
+ *    自成一套后缀规则。`.ts` 后缀由宿主的 `allowImportingTsExtensions` + Vite 转译共同消化。
+ *
+ * @author yijiu2025
+ * @since 2026-10-17
+ */
+/// <reference path="./theme.d.ts" />
+
+export { themeAssets } from './plugin.ts';
+export type { ThemeAssetsPluginOptions } from './plugin.ts';
+export {
+  DEFAULT_THEME_DIR,
+  THEME_PACKAGES_SUBDIR,
+  DEFAULT_THEME_MANIFEST,
+  resolveThemeDir
+} from './dir.ts';