dsh-theme-neumorph 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,8 @@
 # DSH 新拟态主题 (dsh-theme-neumorph)
 
 [![CI](https://github.com/wcnmamrs/dsh-theme-neumorph/actions/workflows/ci.yml/badge.svg)](https://github.com/wcnmamrs/dsh-theme-neumorph/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-theme-neumorph.svg)](https://www.npmjs.com/package/dsh-theme-neumorph)
+[![license](https://img.shields.io/npm/l/dsh-theme-neumorph.svg)](LICENSE)
 
 给 Harness 网页界面换上一层**新拟态**（neumorphism / soft UI）皮肤：冷灰表面、钢蓝强调色、柔和的单向与双向软阴影，浅色与深色模式同时生效。
 
@@ -10,7 +12,7 @@
 
 | 首页与输入区 | 侧栏与会话列表 |
 | --- | --- |
-| ![首页](assets/screenshot-1.jpg) | ![侧栏](assets/screenshot-2.jpg) |
+| ![首页](https://raw.githubusercontent.com/wcnmamrs/dsh-theme-neumorph/main/assets/screenshot-1.jpg) | ![侧栏](https://raw.githubusercontent.com/wcnmamrs/dsh-theme-neumorph/main/assets/screenshot-2.jpg) |
 
 ## 它做了什么
 
@@ -32,9 +34,11 @@
 
 主题只动宿主自己画的界面，不碰第三方插件：
 
-- 宿主的类名是 CSS Module 的 `<hash>_<local>` 形式，规则按整类名锚定（如 `[class$="_card"]`），不会误伤卡片内部的零件。
-- 插件的界面用自己的命名（`dshwv-*`、BEM 之类），不被命中。
-- 没有一条规则按裸标签生效：`span` 不被当成文字，`button` 不被当成按钮。
+- 宿主同时用着**两套** CSS Module 命名：预构建样式表是 `_<local>_<hash>_<line>`（`_card_7gxqk_107`），组件从 JS 注入的样式是 `<hash>_<local>`（`wSkVaW_card`）。所以一个类名要同时锚定两次——`[class$="_card"]` 与 `[class*="_card_"]`——只写一种就会有一半界面纹丝不动。
+- 子串锚定一定用下划线夹住（`[class*="_card_"]` 而不是 `[class*="_card"]`），否则会串到 `_cardContent_x_y` 这种更长的零件上，卡片的每一块又各得一层投影。
+- 每个类名锚定都带 `:not([class*="__"])`：宿主是**单**下划线，别人家的 BEM 是**双**下划线，这一条挡住的正是 `panel__card`。排除项（`button:not([class*="_row"])` 这类）不加，因为排除范围宽一点只会少上一条浮雕。
+- 裸标签只出现在两类地方：宿主的表单与代码面（`textarea`、`input`、`select`、`pre`），以及必须同时带宿主类名的控件（`button` / `[role="button"]` + `[class*="_"]`）。`span` 不被当成文字。
+- 文本框的焦点指示不用宿主的外扩轮廓（在软表面上像一圈多余的蓝边），改成画在框内侧的 1.5px 钢蓝内缘；`outline-offset: -2px` 与内凹阴影叠加而不是替换它。checkbox / radio / 原生控件完全不碰，宿主自己的焦点环留给它们。
 
 ## 目录结构
 
@@ -57,26 +61,31 @@
 ## 实现要点
 
 - Client 半通过 `window.__ModuleLoader__.load({ id, factory })` 注册，`factory` 返回 `{ inject: ['theme'], apply(ctx) }`。
-- 所有副作用都包在 `ctx.effect()` 里并返回清理函数，插件停用时撤销 token 覆盖层并移除样式表，界面立刻回到原生外观。
-- 若宿主某天拒绝含 `--dsw-radius-*` 的 token 表，会自动退回只含颜色的 58 项重试。
-- 样式规则用整类名锚定宿主 CSS Module，哈希前缀随版本变化也不会失效。
+- 所有副作用都包在 `ctx.effect()` 里并返回清理函数：样式表在 effect 内插入（effect 被拒就一张纸都不留），重复 apply 时先删掉自己上一张，停用时先移除样式表再撤销 token 覆盖层，界面立刻回到原生外观。
+- 若宿主某天拒绝含 `--dsw-radius-*` 的 token 表，会自动退回只含颜色的 66 项重试；连重试也被拒时保留阴影层并告警，而不是把主题整个掀掉。
+- 样式规则用宿主类名锚定 CSS Module，哈希前缀与文件名随版本变化都不会失效。
 
 ## 开发
 
 不需要浏览器，也不需要安装依赖（`node --test` 自带）：
 
 ```bash
-npm test                    # 7 项断言：调色板、样式表结构、卸载路径
+npm test                    # 15 项断言：调色板、样式表结构、生命周期、卸载路径
 npm run check               # 语法检查
 node scripts/verify-manifest.mjs   # 清单/打包自检
 npm run verify              # 以上全部
 ```
 
-测试用一个假的 `window.__ModuleLoader__` 与 `document` 载入 `client.js`，因此断言的正是宿主实际调用的那条路径。其中三条是这次踩过坑之后加的护栏：
+测试用一个假的 `window.__ModuleLoader__` 与 `document` 载入 `client.js`，因此断言的正是宿主实际调用的那条路径。这个假 `document` 会记录"谁在什么时机被插进哪个根"，所以下面这些都能测出来：
 
-- 样式表里不允许出现裸标签选择器（`body span`、`body button`），
-- 不允许出现第三方插件命名（曾经把 `dshwv-*` 的图标清空），
-- 卡片只允许整类名锚定，不允许 `[class*="_card"]` 这种会命中 `_cardContent` 的子串锚定。
+- 样式表没有按裸标签生效（`span` 不被当成文字），
+- 没有第三方插件命名（曾经把 `dshwv-*` 的图标清空），
+- 类名锚定必须用下划线夹住，且每个 local 的两套命名都在（只写一套是曾经踩过的坑：一半界面没有浮雕），
+- 每个锚定都带 BEM 护栏；排除项不算，
+- 焦点环存在、画在框内、不吞掉内凹阴影、不碰 checkbox / radio，且全文没有一处 `outline: none`，
+- 样式表在 `ctx.effect` 内插入：宿主拒绝注册 effect 时一张纸都不留，
+- 连续 apply 两次只留下一张样式表，
+- 浮雕落在卡片、输入区大板、菜单/对话框与会话行上，且各用各的阴影级。
 
 ## 许可
 

package/client.js

@@ -137,6 +137,39 @@ window.__ModuleLoader__.load({
       '--dsw-radius-panel': { light: '26px', dark: '26px' },
     };
 
+    /**
+     * The host ships two CSS-module naming conventions at once:
+     *
+     *   - the pre-built app stylesheet names its classes `_<local>_<hash>_<line>`
+     *     (`_card_7gxqk_107`);
+     *   - the component styles injected from JS name theirs `<hash>_<local>`
+     *     (`wSkVaW_card`).
+     *
+     * So an anchor for a local name has to cover both, and it must not straddle
+     * a longer local: `_card_` never matches `_cardContent_1a2b_9`, while a bare
+     * `[class*="_card"]` would. Every anchor also refuses a double underscore,
+     * because that is how a plugin names its own elements (`panel__card`) and no
+     * host class contains one.
+     */
+    const guard = (anchor) => `${anchor}:not([class*="__"])`;
+
+    /** Anchors on a free-form class fragment (`_title`, `_label`). */
+    const sub = (...fragments) =>
+      fragments.map((fragment) => guard(`[class*="${fragment}"]`)).join(',\n  ');
+
+    /** Anchors on a complete local name, in both host conventions. */
+    const host = (...locals) =>
+      locals
+        .flatMap((local) => [`[class$="_${local}"]`, `[class*="_${local}_"]`])
+        .map(guard)
+        .join(',\n  ');
+
+    /** A host button: anything the host painted with a class, minus the cases
+     *  below. Kept as one constant so the three states cannot drift apart. */
+    const BUTTON_SELECTOR = `body :where(button, [role="button"])[class*="_"]:not([class*="__"]):not([aria-checked]):not([role="checkbox"]):not([role="radio"]):not(:is(${host(
+      'primary',
+    )})):not([role="menuitem"]):not([role="option"]):not([role="tab"]):not([class*="_callRow"]):not([class*="_panelRow"]):not([class*="_cardContent"]):not([class*="_row"]):not([class*="_tab"]):not([class*="_option"]):not([class*="_cell"]):not([class*="_switcher"]):not([class*="_segmented"]):not(:is([role="menu"], [role="tablist"], [role="listbox"], [data-menu-material], [class*="_tabs"], [class*="_groups"], [class*="_menu"]) *)`;
+
     const CSS = `
 body {
   --qn-hi: #ffffff;
@@ -163,14 +196,26 @@ body[data-ds-dark-theme] {
 }
 
 /* ---- text is flat ------------------------------------------------------
-   Only elements the harness itself styles are touched, and only by name:
-   every host class is a CSS-module pair of the form <hash>_<local>, so a
-   class that contains an underscore is host markup. Plugin UI names its own
-   elements (dshwv-menu-btn and friends) and is left alone.
-   Nothing here targets a bare tag: a span is not text until it says so. */
-/* Same rule, for the pieces of text that are wrapped in a div rather than a
-   span: a label, a title, a value. They are content too. */
-body :is([class*="_label"], [class*="_title"], [class*="_value"], [class*="_text"], [class*="_name"], [class*="_desc"], [class*="_caption"], [class*="_hint"], [class*="_meta"], [class*="_timestamp"]) {
+   Text never carries a plate of its own: a label sits on the surface, it does
+   not sit in a slightly different rectangle. Only host markup is touched, and
+   only by the name the host gives it (see the host/sub helpers above), so a plugin's
+   own elements are never repainted. Nothing here targets a bare tag: a span is
+   not text until the host says so. */
+body :is(${sub('_label', '_title', '_value', '_text', '_name', '_desc', '_caption', '_hint', '_meta', '_timestamp')}, ${host(
+  'itemLabel',
+  'runStateLabel',
+  'dockHintLabel',
+  'clickableLabel',
+  'labelGroup',
+  'tabTitle',
+  'floatTitle',
+  'failedTitle',
+  'stringValue',
+  'numberValue',
+  'otherValue',
+  'keywordValue',
+  'popoverText',
+)}) {
   background-color: transparent !important;
   box-shadow: none !important;
 }
@@ -181,33 +226,33 @@ body :is([class*="_label"], [class*="_title"], [class*="_value"], [class*="_text
    lives inside a menu, a tab strip or a picker are excluded, because a
    shadow under a row that spans the panel reads as a stray line, and a
    stack of them reads as alternating high and low. */
-body :where(button, [role="button"])[class*="_"]:not([aria-checked]):not([role="checkbox"]):not([role="radio"]):not([class*="_primary"]):not([role="menuitem"]):not([role="option"]):not([role="tab"]):not([class*="_callRow"]):not([class*="_panelRow"]):not([class*="_cardContent"]):not([class*="_row"]):not([class*="_tab"]):not([class*="_option"]):not([class*="_cell"]):not([class*="_switcher"]):not([class*="_segmented"]):not(:is([role="menu"], [role="tablist"], [role="listbox"], [data-menu-material], [class*="_tabs"], [class*="_groups"], [class*="_menu"]) *) {
+${BUTTON_SELECTOR} {
   border-radius: 12px !important;
   border-color: transparent !important;
   background-color: var(--dsw-alias-bg-base) !important;
   box-shadow: var(--qn-out-sm) !important;
 }
 
-body :where(button, [role="button"])[class*="_"]:not([aria-checked]):not([role="checkbox"]):not([role="radio"]):not([class*="_primary"]):not([role="menuitem"]):not([role="option"]):not([role="tab"]):not([class*="_callRow"]):not([class*="_panelRow"]):not([class*="_cardContent"]):not([class*="_row"]):not([class*="_tab"]):not([class*="_option"]):not([class*="_cell"]):not([class*="_switcher"]):not([class*="_segmented"]):not(:is([role="menu"], [role="tablist"], [role="listbox"], [data-menu-material], [class*="_tabs"], [class*="_groups"], [class*="_menu"]) *):hover:not(:disabled) {
+${BUTTON_SELECTOR}:hover:not(:disabled) {
   box-shadow: var(--qn-out) !important;
 }
 
-body :where(button, [role="button"])[class*="_"]:not([aria-checked]):not([role="checkbox"]):not([role="radio"]):not([class*="_primary"]):not([role="menuitem"]):not([role="option"]):not([role="tab"]):not([class*="_callRow"]):not([class*="_panelRow"]):not([class*="_cardContent"]):not([class*="_row"]):not([class*="_tab"]):not([class*="_option"]):not([class*="_cell"]):not([class*="_switcher"]):not([class*="_segmented"]):not(:is([role="menu"], [role="tablist"], [role="listbox"], [data-menu-material], [class*="_tabs"], [class*="_groups"], [class*="_menu"]) *):active:not(:disabled) {
+${BUTTON_SELECTOR}:active:not(:disabled) {
   box-shadow: var(--qn-in-sm) !important;
 }
 
 /* The send button is a filled pill and keeps one soft shadow of its own. */
-body :where(button, [role="button"])[class*="_primary"] {
+body :where(button, [role="button"]):is(${host('primary')}) {
   border-radius: 999px !important;
   border-color: transparent !important;
   box-shadow: 0 3px 8px rgba(74, 107, 138, 0.28) !important;
 }
 
-body :where(button, [role="button"])[class*="_primary"]:hover:not(:disabled) {
+body :where(button, [role="button"]):is(${host('primary')}):hover:not(:disabled) {
   box-shadow: 0 4px 10px rgba(74, 107, 138, 0.34) !important;
 }
 
-body :where(button, [role="button"])[class*="_primary"]:active:not(:disabled) {
+body :where(button, [role="button"]):is(${host('primary')}):active:not(:disabled) {
   box-shadow: inset 2px 2px 5px rgba(0, 0, 0, 0.26) !important;
 }
 
@@ -226,16 +271,14 @@ body :where(
    Deliberately narrow. Rows, tabs, chips, list items and every other small
    block stay flat: a shadow on each of them turns the page into a field of
    pillows, which is not what neumorphism is for. */
-body [class$="_card"], [class*="_card "], [class$="Card"], [class*="Card "] {
+body :is(${host('card')}) {
   box-shadow: var(--qn-drop) !important;
   border-color: transparent !important;
 }
 
 /* ---- composer: the one big soft slab ------------------------------------ */
-body [class*="_composerSeat"] [class$="_card"],
-body [class*="_composerSeat"] [class*="_card "],
-body [class*="_composerHero"] [class$="_card"],
-body [class*="_composerHero"] [class*="_card "] {
+body :is(${host('composerSeat')}) :is(${host('card')}),
+body :is(${host('composerHero')}) :is(${host('card')}) {
   box-shadow: var(--qn-out) !important;
   border-radius: 22px !important;
   border-color: transparent !important;
@@ -244,7 +287,7 @@ body [class*="_composerHero"] [class*="_card "] {
 /* ---- floating surfaces: menus, dialogs, tooltips ------------------------ */
 body :where([role="menu"], [role="dialog"], [role="listbox"], [role="tooltip"]),
 body [data-menu-material],
-body :is([class$="_menu"], [class*="_menu "], [class$="_dialog"], [class*="_dialog "]) {
+body :is(${host('menu', 'dialog')}) {
   border-radius: 20px !important;
   box-shadow: var(--qn-out-lg) !important;
 }
@@ -255,19 +298,13 @@ body [data-menu-material] > [aria-hidden="true"] {
   border-radius: inherit !important;
 }
 
-body [data-menu-material] {
-  overflow: hidden !important;
-}
-
 /* ---- session tree: one soft row per session ----------------------------- */
-body [class*="_sessionRow"],
-body [class*="_projectRow"] {
+body :is(${host('sessionRow', 'projectRow')}) {
   border-radius: 12px !important;
   box-shadow: var(--qn-drop) !important;
 }
 
-body [class*="_sessionRow"]:hover,
-body [class*="_projectRow"]:hover {
+body :is(${host('sessionRow', 'projectRow')}):hover {
   box-shadow: var(--qn-drop-lift) !important;
 }
 
@@ -279,34 +316,38 @@ body :where(pre) {
 }
 
 /* ---- sidebar: a faint groove instead of a divider line ------------------ */
-body [class*="_sidebarCol"] {
+body :is(${host('sidebarCol')}) {
   box-shadow: inset -8px 0 14px -14px var(--qn-lo) !important;
 }
 
-/* ---- focus: visible on controls, never a ring on the text fields -------- */
-body :where(textarea, input, select, [contenteditable="true"]):focus,
-body :where(textarea, input, select, [contenteditable="true"]):focus-visible {
-  outline: none !important;
+/* ---- focus: a ring, drawn inside the field -----------------------------
+   The host draws its ring outside the box, which on a soft surface reads as a
+   stray edge floating beside the field. So the ring is moved inward instead of
+   removed: an outline with a negative offset follows the border radius, composes
+   with the recessed shadow instead of replacing it, and still exists for every
+   control type - including the checkable ones this sheet never restyles, which
+   keep the host ring untouched. A theme that sets outline: none on a focus
+   state leaves a keyboard user with no idea where they are; this one does not. */
+body :where(
+  textarea,
+  input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not([type="color"]),
+  select,
+  [contenteditable="true"]
+):focus-visible {
+  outline: 1.5px solid var(--dsw-alias-brand-primary) !important;
+  outline-offset: -2px !important;
 }
 
 body :where(button, [role="button"], a):focus-visible {
   outline: 2px solid var(--dsw-alias-brand-primary);
   outline-offset: 2px;
 }
-
 `;
 
     return {
       inject: ['theme'],
       apply(ctx) {
-        // Shadow layer: neumorphism needs paired soft shadows, and a theme token
-        // can only carry a colour, so the shadows are a stylesheet of their own.
-        const style = document.createElement('style');
-        style.dataset.dshTheme = SOURCE;
-        style.textContent = CSS;
-        document.head.appendChild(style);
-
-        // Colour layer: `overrideTokens` returns the disposer for exactly this
+        // Colour table: `overrideTokens` returns the disposer for exactly this
         // layer. The radius tokens are the only non-colour entries, so they are
         // what gets dropped first if a host build ever rejects the table.
         const overrideTokens = () => {
@@ -321,11 +362,45 @@ body :where(button, [role="button"], a):focus-visible {
           }
         };
 
+        // Everything the plugin adds is created and released inside one effect:
+        // a stylesheet inserted before the effect registered would outlive a
+        // throw, and a second apply would stack a second copy of it. So the old
+        // sheet of this source is dropped first, and a throw after insertion
+        // takes the sheet back out again.
         ctx.effect(() => {
-          const disposeTokens = overrideTokens();
+          const root = document.head ?? document.documentElement;
+          for (const stale of document.querySelectorAll?.(`style[data-dsh-theme="${SOURCE}"]`) ?? []) {
+            stale.remove();
+          }
+
+          // Shadow layer: neumorphism needs paired soft shadows, and a theme
+          // token can only carry a colour, so the shadows are a stylesheet of
+          // their own.
+          const style = document.createElement('style');
+          style.dataset.dshTheme = SOURCE;
+          style.textContent = CSS;
+
+          let disposeTokens = null;
+          try {
+            root.appendChild(style);
+            disposeTokens = overrideTokens();
+          } catch (error) {
+            // Whatever happened, this effect owns what it inserted: give it back
+            // before getting out of the way. The one exception is the token
+            // table, which has a colour-only retry of its own; if even that is
+            // rejected the shadows are still worth keeping, so report and carry on.
+            if (style.parentNode === null && disposeTokens === null) {
+              style.remove();
+              throw error;
+            }
+            console.warn('[dsh-theme-neumorph] token layer rejected, shadows only', error);
+          }
+
           return () => {
-            disposeTokens();
+            // Sheet first: one frame of host colours is better than one frame of
+            // plugin shadows over the host's own palette.
             style.remove();
+            disposeTokens?.();
           };
         });
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-theme-neumorph",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "DSH 新拟态主题插件：冷灰表面、钢蓝强调、柔和阴影。",
   "license": "MIT",
   "author": "wcnmamrs",