skinsuite 0.1.0

package/src/types.ts

@@ -0,0 +1,226 @@
+/**
+ * 主题包契约
+ *
+ * === 主题包 = 一整套呈现方案（版式 + 配色），设备是包内的一层 ===
+ * ```
+ * theme/themes/<包>/                 主题包：一套设计，三端都住这里
+ * ├── index.ts                       包定义：meta + （可选）views 声明
+ * ├── mobile/                        该设计的**手机端**呈现
+ * │   ├── <page>/index.vue           版式实现：该包在该设备的**唯一**版式
+ * │   └── colors/<配色>/             手机端配色：index.ts + theme.scss + assets/
+ * ├── standard/                      该设计的**桌面主窗口**呈现（结构同上）
+ * │   ├── <page>/index.vue
+ * │   └── colors/<配色>/
+ * └── mini/                          该设计的**iframe 紧凑版**呈现（结构同上）
+ *     ├── <page>/index.vue
+ *     └── colors/<配色>/
+ * ```
+ * 两个 glob 决定注册表：包定义的 `index.ts`（给出 meta 与 views）与
+ * `<包>/<设备>/<页面>/colors/<配色>/index.ts`（id = 配色目录名）。
+ * 设备段只认 `mobile` / `standard` / `mini` 三个值，写错则整个目录跳过。
+ * **加一个包、加一种设备的配色，都不需要改任何其它文件。**
+ *
+ * 🔴 **一个主题包 = 一种版式**（2026-09-26 定案，用户：「变体版式使用新包」）：
+ *    `<页面>/` 下**只有** `index.vue` 与 `colors/`，**没有**「版式」这一层目录。
+ *    要另一种版式 → **新建包**（`themes/compact/<设备>/<页面>/`）。曾支持过的
+ *    `<页面>/<版式>/colors/` 形态已删除：换版式要复制整套配色，两套必然漂移。
+ *
+ * ⚠️ 描述 glob 模式时别写出「星号紧跟斜杠」的字符组合：它会**提前闭合本段块注释**，
+ *    报错行号会落在注释之后的正文上（本文件踩过一次）。
+ *
+ * ⚠️ 包定义**不再是**"该包的默认配色"：黑白是**两个具名配色目录**
+ *    （`<设备>/<页面>/colors/{black,white}/`），与 blue/cyan/rainbow 平级。这样"黑白"
+ *    能被显式选中、出现在配色列表里，而不是一个没有名字的隐式兜底。
+ *    （⚠️ 早期注释里的 `mono` 早已改名成 `black` / `white`，`colors/mono/` 不存在。）
+ *
+ * ⚠️ **版式跟随主题包 + 设备**：某一页的版式只在**当前包、当前设备**下查找
+ *    （见 `views/registry.ts`），换一套设计就是换一个包。
+ *    版式的**契约**与**注册表**是每页一份的页面文件（应用侧 `theme/views/<page>.ts`），
+ *    留在应用侧架构层，**每个包共用一份** —— 跟着进包就会变成 N 份副本，必然漂移。
+ *
+ * ⚠️ 配色 id 的唯一性作用域是「**同包 × 同设备 × 同页面**」（2026-09-26 收窄：
+ *    版式不再是独立维度）；跨设备、跨包、跨页面都**可以同名**。
+ *    `mobile/login/colors/black` 与 `standard/login/colors/black` 并存是正常且必要的
+ *    —— 它们本就是两套各自独立的配色（这正是"手机端、电脑端分别配置主题"的落点）。
+ *    URL 上的 `?theme=` 只给一个 id，设备那一段由各调用点在解析时补上
+ *    （`getThemeRecord(id, pkg, device, page, view)`），歧义在入口就被消解。
+ *
+ * ⚠️ 同一目录下的 `index.ts` 与 `theme.scss` 配套：只有样式、没有 `index.ts` 的目录
+ *    视为残缺（样式被忽略）；反过来只有 `index.ts` 没有样式是正常情况。
+ *
+ * === 值怎么给：token 还是 theme.scss ===
+ *   • 颜色、圆角、间距、字体族名  → `tokens`（走 `--mauth-*` 变量，会被白名单校验）
+ *   • 背景图片、webfont、装饰边框、动画、结构级差异
+ *                                → `theme.scss`（写真实 CSS，选择器必须带
+ *                                   `html[data-mauth-theme='<id>']` 前缀）
+ * 分界线的依据：token 取值要能被白名单校验（因此不接受 url()），
+ * 凡是必须写 url() 或需要伪元素/keyframes 的，都用 theme.scss。
+ *
+ * @author yijiu2025
+ */
+import type { ThemeTone } from './tone.js';
+import type { ThemeTokenOverrides } from './tokens.js';
+
+/**
+ * 设备维度取值：**由宿主的设备清单决定**（内核不绑定某个应用的设备集合）
+ *
+ * 内核只承诺"设备名是个 `[a-z0-9-]` 字符串"这条形态约定；`mobile` / `standard` /
+ * `mini` 是 `oauth21` 的词汇表，不是机制的一部分。取值集合、中文名、判定规则、
+ * 容器位置都声明在宿主（本仓 = `oauth21/src/theme/devices.ts`），
+ * 于是「加一种设备」只需改宿主清单，内核与任何其它前端都无感。
+ *
+ * 因此这里用宽松的 `string`：内核无从（也不该）知道有哪些设备。
+ * 白名单归一在宿主（`asThemeDevice`）。
+ */
+type ThemeDevice = string;
+
+/**
+ * 配色的元信息（用于列表展示与日志，不参与渲染）
+ */
+export interface MauthThemeMeta {
+  /**
+   * 配色 id，以目录名为准：`themes/<包>/<设备>/<页面>/colors/<配色>/` → 末段目录名。
+   * 只允许 `[a-z0-9-]`（它会进 `data-mauth-theme` 属性选择器）。
+   * 唯一性作用域 = 「同包 × 同设备 × 同页面」；**跨设备 / 跨包 / 跨页面可以同名**
+   * （同名不算冲突：取一份配色时这三段必然同时给出）。
+   */
+  id: string;
+  /** 中文显示名 */
+  name: string;
+  /** 一句话描述，便于部署方挑选 */
+  description?: string;
+  /** 主色/强调色，供后台预览色卡使用（不参与渲染，渲染以 tokens 为准） */
+  preview?: { primary: string; accent: string };
+  /** 作者（可选） */
+  author?: string;
+}
+
+/**
+ * 主题包定义（`themes/<包>/index.ts` 的默认导出）
+ *
+ * ⚠️ 它**不再是**"该包的默认配色"：黑白等基础档以实体配色目录存在。本文件只声明
+ *    包级信息与可选的版式声明。
+ */
+export interface MauthThemePackage {
+  meta: MauthThemeMeta;
+  /**
+   * 包级版式声明（可选）—— 该包**所有设备、所有配色**共用的默认
+   *
+   *   key   = 页面名，与 `theme/views/<page>.ts` 的页面名一致（如 `register`）
+   *   value = 版式 id。**注意版式 id ≡ 主题包名**（一个主题包 = 一种版式），所以合法
+   *           取值只有两种：本包自己的名字，或**另一个包的名字**（跨包切版式）。
+   *
+   * 写在**包定义**（`themes/<包>/index.ts`）→ 全包共用；
+   * 写在**配色里**（`<设备>/colors/<配色>/index.ts`）→ 只覆盖那一套配色。
+   *
+   * 写错 / 未登记一律回退**当前包**的版式（由 `theme/views/<page>.ts` 判定，
+   * 不会因为包写错而白屏）。
+   *
+   * ⚠️ URL `?view=` 优先级更高：声明不会挡住联调时的单次覆盖。
+   */
+  views?: Record<string, string>;
+  /**
+   * 本包的**覆盖范围声明**（可选，2026-09-27 起）
+   *
+   * 主题包可以只覆盖部分设备 / 部分页面（例：`compact` 只覆盖 `mobile` 设备的
+   * `register` 页，其余页面回退到 `default` 包）。以前这个"只覆盖一部分"是**数据性
+   * 事实**，却只能靠目录口径关卡里的 `if (pkg === 'compact')` 这类**写死的包名**来表达
+   * —— 于是每新增一个部分覆盖的包，都要回来改一个上千行的关卡脚本（「关卡即配置」）。
+   *
+   * 现在把范围写成包**自带的声明**（声明与实现同目录，复制主题包时声明跟着走）：
+   *   • `devices` —— 覆盖哪些设备；缺省 = **全部设备**
+   *   • `pages`   —— 覆盖哪些页面；缺省 = **全部页面**
+   *   • `requiredColors` —— 每个「包×设备×页面」作用域都应具备的配色目录名；
+   *                         缺省 = `['black','white']`（黑白是并列实体颜色）
+   *
+   * 目录口径关卡据此**推导**该包应有的目录，不再写死包名 / 颜色名。
+   *
+   * ⚠️ 声明**只影响关卡校验**，不改变运行时行为：注册表仍是"glob 扫到什么就登记什么"，
+   *    声明只是把"这个包本来就只打算覆盖这些范围"从隐式约定变成显式契约。
+   *    声明的范围**只能 ≤ 实际目录**（写多会红，写少无害）。
+   */
+  coverage?: {
+    devices?: string[];
+    pages?: string[];
+    requiredColors?: string[];
+  };
+}
+
+/**
+ * 一套**配色**的定义（`<设备>/colors/<配色>/index.ts` 的默认导出）
+ *
+ * `tokens` 的语义（2026-09-25 改）：
+ *   • 是**一组扁平值**（`Record<string, string>`），**不分明暗档**
+ *   • 每套配色**自带完整底色**，选谁就是谁 —— 与当前明暗偏好无关
+ *   • 明暗（`mode`）仍存在，但只在**基线 SCSS** 那层生效（`html.dark` 选择器）
+ *
+ * ⚠️ 因此**不要**再写 `{ light, dark }` 两档，也**不要**为"深色版"单开一份 token：
+ *    需要深色品牌色就**另加一个颜色目录**（如 `navy`）。用户 2026-09-25 原话：
+ *    「没有深浅两档了，深和浅就是两种颜色配置。」
+ *
+ * ⚠️ 若配色把 `--mauth-header-bg` 设为 `transparent`（把底色交还给页面），
+ *    必须同时声明 `--mauth-canvas`（页面最上沿的颜色），否则"页面之外的画布色"
+ *    会退回给浏览器内核自己决定 → 真机与电脑不一致。参考 cyan 配色的 theme.scss。
+ *
+ * ⚠️ 黑白（`black` / `white`）是与 `blue` / `cyan` **完全并列**的普通颜色，
+ *    各自写全 token（自带底色），不再是"零 token 的基线配色"。见 README「五色并列」。
+ */
+export interface MauthThemeColor {
+  meta: MauthThemeMeta;
+  /**
+   * 这套配色自带的**明暗系别** —— 决定切换夜间模式时如何联动（见 `./tone`）
+   *
+   *   `'light'` 白系：浅底深字（`white` / `blue` / `cyan` / `rainbow`）
+   *   `'dark'`  黑系：深底浅字（`black`）
+   *
+   * 🔴 **必填**：漏写直接编译报错。系别判错会让"开夜间自动变黑"整个失效，
+   *    而且现象隐蔽（只是不联动、不报错），所以宁可让它构建期就变红。
+   *
+   * ⚠️ 它描述的是**配色之间**的关系，不是"一套配色内部的明暗两档"
+   *    （那个概念已于 2026-09-25 取消，见 `tokens` 说明）。
+   */
+  tone: ThemeTone;
+  tokens?: ThemeTokenOverrides;
+  /** 该套配色专属的版式声明（覆盖包级声明）；一般不必写，见 `MauthThemePackage.views` */
+  views?: Record<string, string>;
+}
+
+/** 注册表里一条已解析好的配色记录 */
+export interface MauthThemeRecord {
+  /**
+   * 该配色所属的**主题包** id（= `themes/<包>/` 的目录名）
+   *
+   * 版式只在当前包内查找（版式跟随主题），所以容器与版式注册表都需要它。
+   * 它同时是调试面板上"这套配色来自哪个包"的答案。
+   */
+  pkg: string;
+  /**
+   * 该配色所属的**设备**（= `themes/<包>/<设备>/` 的目录名）
+   *
+   * 决定版式在 `mobile/` / `standard/` / `mini/` 下查找。与 `pkg` 一起构成版式的
+   * 查找范围（版式 = 当前包 × 当前设备）。
+   */
+  device: ThemeDevice;
+  /**
+   * 该配色所属的**页面**（= `themes/<包>/<设备>/<页面>/` 的目录名，如 `register`）
+   *
+   * 🔴 配色与**版式同级**（`<页面>/colors/<颜色>/`，2026-09-26 收窄），
+   *    所以"这套颜色给哪一页用"是它归属的一部分 —— 同一个颜色 id 在不同页面下
+   *    各有一份（那是正常且必要的，两页的尺寸/间距本就不必一致）。
+   */
+  page: string;
+  meta: MauthThemeMeta;
+  /**
+   * 该配色的**明暗系别**（从配色定义原样带出）—— 供 store 做明暗联动判定
+   *
+   * ⚠️ 与 `meta` 不同，它**参与逻辑**（决定"开夜间该切到哪套配色"），
+   *    因此不塞进 `meta` 这个"只用于展示、不参与渲染"的口袋。
+   */
+  tone: ThemeTone;
+  /** 该主题的 token（已从配色里取出，未做安全校验——校验在注入时统一做） */
+  tokens: ThemeTokenOverrides | undefined;
+  /** 该主题的版式声明（页面名 → 版式 id）；未声明为 undefined */
+  views: Record<string, string> | undefined;
+  /** 该主题附加样式的惰性加载器；无 theme.scss 时为 undefined */
+  loadStyle: (() => Promise<string>) | undefined;
+}

package/src/views/params.ts

@@ -0,0 +1,75 @@
+/**
+ * 版式参数的**设备维度**解析 —— `?view.<设备>` 支持
+ *
+ * === 解决什么 ===
+ * 同一条链接要能给三台设备各指定一套版式：
+ * ```
+ * /login?view=compact                               三端共用（哪端没有就自动下沉到当前包）
+ * /login?view.mobile=default&view.standard=compact   各端各指定（mini 走通用/包默认）
+ * /login?view.mobile=default&view=default            设备专属优先，通用键兜底
+ * ```
+ *
+ * === 取值链（每台设备各一条）===
+ *   `view.<设备>`  →  `view`  →  （返回 undefined：由调用方走包声明 → 环境变量 → 当前包）
+ *
+ * === 为什么收在内核（而不是各页文件里）===
+ * 三个页面（login / register / forgot-password）各有**一份**注册表文件，但"哪个 query
+ * key 属于哪台设备"这件事与页面无关 —— 抄三份必然漂移。各页的 `pick*ViewId` 只负责
+ * "拿到原始值之后怎么解析（落在哪个包、是否合法）"，取哪个键这一步交给本模块。
+ * 2026-09-26 抽包 Stage 1 起它住在 `skinsuite`：任何复用这套机制的前端
+ * 都直接拿到这份实现，而不是再抄一遍。
+ *
+ * === 与配色侧同形（很重要）===
+ * 配色侧（`oauth21/src/stores/theme.ts` 的 `readUrlIntent`）用同样的键形
+ * （`theme.<设备>` / `skin.<设备>`）与同样的"设备专属优先"链。**两侧必须同形**，
+ * 否则配置者要记两套规则，`?theme.mobile=blue&view.standard=compact` 这种混搭就写不出来。
+ * 但两侧读的入口不同：配色侧读 `window.location.search`（store 是全局的，不依赖路由），
+ * 版式侧读**路由 query**（容器手上只有 `route.query`）—— 所以不是同一个函数，是同一套规则。
+ *
+ * ⚠️ query key 里带 `.` 是合法的（`URLSearchParams` 与 vue-router 都原样保留），
+ *    但访问时**必须用下标**（`query['view.standard']`）—— 点号在 JS 里不是合法标识符。
+ *
+ * @author yijiu2025
+ * @since 2026-09-26
+ */
+/** 支持设备维度的参数名（与配色侧 `readUrlIntent` 的键保持一致） */
+export type DeviceScopedParam = 'view' | 'theme';
+
+export const DEVICE_SCOPED_PARAMS: readonly DeviceScopedParam[] = ['view', 'theme'];
+
+/** 值"存在且非空" —— 空串 / 空数组视为**未指定**，不顶掉兜底键 */
+function isPresent(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string') return value.trim() !== '';
+  if (Array.isArray(value)) {
+    return value.some(v => typeof v === 'string' && v.trim() !== '');
+  }
+  return true;
+}
+
+/**
+ * 按**设备**读取版式 / 配色参数
+ *
+ * @param query  路由 query（`route.query`）
+ * @param name   参数名（`'view'` / `'theme'`）
+ * @param device 当前设备 —— 容器用自己的设备常量传进来（文件位置即身份）
+ * @returns `query['<name>.<device>']` 优先；缺席或空值时退 `query[name]`；
+ *          两者都没有则返回 undefined，表示"**这台设备**没有被显式指定"
+ *
+ * ⚠️ 只决定"取哪个键"，**不做合法性校验** —— 校验属于各页 `pick*ViewId` 与配色注册表
+ *    （本函数也拿不到"当前包里有没有这套版式"）。返回值可能是数组（`?view=a&view=b`），
+ *    由下游按"非字符串即非法"处理，与改前的行为一致。
+ * ⚠️ 空串视为"未指定"：`?view.standard=` 不该把 `?view=compact` 顶掉 ——
+ *    部署方常把参数留空当作"这台设备不特殊指定"。
+ * ⚠️ 设备名是**宿主**的词汇表（本包不认识具体取值），所以这里只把它当字符串拼键；
+ *    「这个名字认不认得」由宿主的设备清单归一（`asThemeDevice`）。
+ */
+export function readDeviceParam(
+  query: Record<string, unknown> | undefined,
+  name: DeviceScopedParam,
+  device: string
+): unknown {
+  const scoped = query?.[`${name}.${device}`];
+  if (isPresent(scoped)) return scoped;
+  return query?.[name];
+}