dsh-sidebar-suite 0.0.0-stage → 0.1.3

package/DETAIL.md

@@ -0,0 +1,64 @@
+# 侧栏布局大师 · Sidebar Suite
+
+> **中文**：左侧栏里「扩展」和「工作区」永远在抢同一块高度。装了几插件之后，找一个入口要滚半天；项目一多，扩展就被挤没。这个插件把它们理顺成三种布局，一键切换，而且**默认布局就在本页最上方**，打开详情页第一眼就能改。
+>
+> **English**: The panels group and the workspaces group fight for the same vertical space in the DSH sidebar. Once you install a few plugins, finding anything means scrolling; add more projects and the panels vanish entirely. Sidebar Suite gives you three clean layouts, switches them in one click, and puts the **startup-default picker at the very top of this page** — no scrolling, no YAML editing.
+
+---
+
+## 三种布局 / Three layouts
+
+| 模式 / Mode | 中文 | English |
+| --- | --- | --- |
+| `a` 折叠 / Fold | 两组各自收起，想留哪块留哪块。 | Each group folds independently — keep exactly what you need. |
+| `b` 标签页 / Toggle (**默认 / default**) | 两组共用一栏，用顶部按钮互斥切换，侧栏再长也不打架。 | Both groups share one space; the bar swaps between them. The sidebar stays short. |
+| `c` 浮层 / Overlay | 工作区常驻，扩展以浮层盖在上面，随时展开/收起。 | Workspaces stay put; panels open as a floating layer you can show or hide. |
+
+每张布局卡片都画了示意图，选中的那张标着「当前默认 / Current」。点一下就通过官方配置层写入，**立刻生效、下次启动照旧**。
+Each card draws a small diagram of its layout, and the selected one is marked as the current default. A click writes through the official config layer — **effective immediately and on every future launch**.
+
+## 为什么好用 / Why you'll like it
+
+- **设置项置顶 / Settings first** — 图形化设置被提到详情页最上方，长说明、版本信息、组件列表都排在它后面。The graphical defaults are pinned above the long description, version info and component list.
+- **会话与默认分离 / Session ≠ default** — 侧栏上临时换布局只影响本次会话，不写盘；只有详情页的设置会改默认值。Switching from the sidebar bar is session-only; only this page changes the startup default.
+- **零侵入 / Zero rewrites** — 只往 `<html>` 上写属性、加一条控制栏，绝不重构宿主 DOM，React 重绘后自动重新挂载。Only `<html>` attributes and one control bar; the host's markup is never restructured, and everything re-resolves after React rebuilds.
+- **中英双语 / Bilingual** — 界面文案、详情内容、设置说明全部中英对照。UI labels, this document and the settings copy are all bilingual.
+- **不联网 / Offline** — 收款码随插件打包由宿主本地提供，配置只落在本机 profile。The QR ships with the bundle and is served locally; config stays in your profile.
+
+## 支持作者 / Support the author
+
+如果这个插件让你每天少滚几次侧栏，欢迎请作者喝杯咖啡 —— **完全自愿，无任何回报承诺，也没有付费墙**。
+If this plugin saves you a few scrolls every day, you can buy the author a coffee. **Entirely voluntary, no rewards promised, no paywall.**
+
+![微信支付收款码 / WeChat Pay QR code](assets/wechat-pay.jpg)
+
+**微信支付 / WeChat Pay** — 打开微信「扫一扫」即可 / open WeChat → Scan.
+作者本机另外把同一个码登记进了 **dsh-tip-jar 打赏罐**；那份注册表属于本机配置，**不随本插件分发**。
+The author also registers the same QR locally in the **dsh-tip-jar** sponsor centre; that registry is **not shipped with this bundle**.
+
+---
+
+## 控制栏在哪 / Where the controls are
+
+侧栏顶部一排文字按钮：`折叠 · 标签页 · 浮层 │ 显示工作区 / 展开扩展 · 换布局`。
+A single row of text buttons sits at the top of the sidebar. `换布局 / Cycle` is hidden below 300 px and can be turned off with `showQuickSwitch: false`.
+
+## 安装与生效 / Install & apply
+
+```sh
+dsh plugin --profile desktop add dsh-sidebar-suite
+```
+
+本地开发可把包名换成本目录路径或 `.tgz` 安装包。已在 **DSH 0.2.2-rc.1（desktop profile）** 验证。
+For local development, point the same command at this folder or a packed `.tgz`. Tested on **DSH 0.2.2-rc.1 (desktop profile)**.
+
+**客户端代码不会热重载 / the client half is not hot-reloaded** — 安装或改动文件后请完全退出并重新打开 DSH / fully quit and reopen DSH after installing or editing files.
+
+> 组合包自带的 `cordis.patch.yml` 会自动挂载，不要再往 profile 的 `cordis.patch.yml` 里加同名行，否则会加载两次。
+> The bundle patch mounts the plugin automatically; do not add a manual mount line or it loads twice.
+
+## 已知限制 / Known limits
+
+- `[data-slot="sidebar.workspaces"]` 与 `panelList` 是宿主的半稳定约定；若宿主改版，插件会退化成「有控制栏但无效果」而不是抛错。These host markup contracts are semi-stable; a host change degrades gracefully instead of throwing.
+- 浮层定位依赖 `:has()`，需要 Chromium 内核（DSH 桌面端即是）。Overlay positioning uses `:has()`, so it needs a Chromium-based client.
+- 标签页模式会整块隐藏工作区区域，里面的其它入口也一并隐藏 —— 这是「一组一栏」的刻意设计。Toggle mode hides the whole workspaces region, including anything else the host renders inside it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yonan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# 侧栏布局大师 · Sidebar Suite
 
-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.
+> 让左侧栏从「抢地盘」变成「听你的」。三种布局、一键切换、零改动宿主结构，默认布局在插件详情页顶部直接改。
+> Tame the DSH sidebar: three layouts, one click, zero DOM rewrites — set your startup default right at the top of the plugin page.
+
+**中文**：DSH 左侧栏把「扩展面板」和「工作区」堆在同一列，互相抢高度。本项目提供三种布局解决这个问题，并带来一个中英双语、带图形化设置的详情页。
+**English**: The panels group and the workspaces group compete for the same vertical space. This bundle offers three layouts for them and ships a bilingual detail page with a graphical settings picker.
+
+详情页长文档见 [DETAIL.md](DETAIL.md)（中英双语 / bilingual, 含收款码 / includes the payment QR）。
+The full detail document is [DETAIL.md](DETAIL.md).
+
+## 三种布局 / Three layouts
+
+| 模式 / Mode | 中文 | English |
+| --- | --- | --- |
+| `a` 折叠 / Fold | 两组各自收起。 | Each group folds on its own. |
+| `b` 标签页 / Toggle（默认 / default） | 两组共用一栏，标签互斥切换。 | The groups share one space; the bar switches between them. |
+| `c` 浮层 / Overlay | 工作区常驻，扩展以浮层展开。 | Workspaces stay put; panels open as an overlay. |
+
+## 默认模式 / Default mode
+
+`config.mode`（profile 的 `cordis.patch.yml`）是**启动默认**。在侧栏控制栏上临时切换只影响本次会话，不写盘、不进 `localStorage`；下次启动回到配置里的默认值。
+`config.mode` in the profile patch is the **startup default**. Choosing a layout from the control bar is session-only: it is deliberately not persisted, so the next launch returns to the configured default.
+
+```yaml
+# ~/.dsh/profiles/desktop/cordis.patch.yml
+- id: dsh-sidebar-suite
+  config:
+    mode: b            # a = fold, b = tabs, c = overlay
+    showQuickSwitch: false
+```
+
+在**插件详情页顶部的图形化设置**里改 `mode` 会通过官方 `configForms` 控制器写入，立刻成为新的启动默认，无需改文件、无需重启。其它字段（`tab`、`foldExt`、`foldWs`、`showQuickSwitch`）仍按控制栏的操作正常持久化。
+Changing `mode` in the **graphical settings card pinned at the top of the plugin page** writes through the host `configForms` controller, so it becomes the startup default immediately — no file editing, no restart. The other fields still persist from the bar.
+
+## 图形化设置页 / Graphical settings page
+
+组合包注册了 `plugins.bundle.config` 这个 keyed slot（key = 包名），因此打开 **插件 → dsh-sidebar-suite** 会在详情页看到三张布局卡片。宿主把 `configForms` 传进来，卡片读写同一个控制器；设置区通过 `order:-1` 被提到详情页所有分区的最上方，并且只在 `[data-plugin-detail="dsh-sidebar-suite"]` 范围内生效，不会影响别的插件。
+The bundle registers the `plugins.bundle.config` keyed slot. The settings section is lifted above every other detail section with `order:-1`, scoped to this bundle's own detail page only.
+
+React 与 slots 服务都是可选依赖：任一不可用时跳过注册，侧栏控制栏照常工作。
+React and the slots service are optional; if either is missing, registration is skipped and the sidebar bar keeps working.
+
+## 收款码 / Payment QR
+
+![微信支付收款码 / WeChat Pay QR](assets/wechat-pay.jpg)
+
+微信「扫一扫」即可，**完全自愿、无任何回报承诺**。作者本机另外用 `dsh-tip-jar` 登记了同一个码；那份注册表属于本机配置，**不随本插件分发**。
+Scan with WeChat Pay — **purely voluntary, no rewards promised**. The author also registers the same QR locally via `dsh-tip-jar`; that local registry is **not shipped with this bundle**.
+
+## 控制栏 / Where the controls are
+
+侧栏顶部一排文字按钮：`折叠 · 标签页 · 浮层 │ 显示工作区 / 展开扩展 · 换布局`。
+`换布局 / Cycle` 在侧栏窄于 300px 时隐藏，可用 `showQuickSwitch: false` 彻底移除。
+A single row of text buttons at the top of the sidebar. `Cycle` hides below 300 px and can be removed with `showQuickSwitch: false`.
+
+## 实现要点 / How it works
+
+- 所有持久状态写在 `<html>` 属性上：`data-dsbs-mode`、`data-dsbs-tab`、`data-dsbs-fold-ext`、`data-dsbs-fold-ws`、`data-dsbs-pop`、`data-dsbs-quick`、`data-dsbs-rail`、`data-dsbs-narrow`。CSS 负责显隐，插件不重构宿主 DOM。All state lives in `<html>` attributes; CSS owns visibility.
+- 每次 sync 都重新解析 `[data-slot="sidebar.workspaces"]` 与 `nav.panelList`，因为 React 会在切换会话时重建侧栏。Both host nodes are resolved on every sync, never cached.
+- 隐藏的组用 `display:none` + `aria-hidden` + `inert`，不卸载；组内菜单先收到 `Escape`，恢复时派发 `resize` 供浮层重新测量。Hidden groups are not unmounted; open menus get an `Escape` first and a `resize` is dispatched on restore.
+- 同一页面重复 apply 时只有第一个实例持有控制栏；旧客户端留下的 `[data-dsbs-bar]` 会在下次 sync 被清掉。Only one run owns the bar; stale bars from older client generations are removed.
+- 官方配置服务不可用时降级到 `localStorage["dsh-sidebar-suite:state"]`，并在控制栏提示。Falls back to `localStorage` when the config service is unavailable.
+
+## 安装 / Install
+
+从 npm 安装 / Install from npm:
+
+```sh
+dsh plugin --profile desktop add dsh-sidebar-suite
+```
+
+本地开发时也可以把命令里的包名换成本目录路径，或 `pnpm pack` 产出的 `.tgz`。
+For local development, point the same command at this folder or a packed `.tgz` instead.
+
+**已在 DSH 0.2.2-rc.1（desktop profile）验证 / Tested on DSH 0.2.2-rc.1 (desktop profile).**
+本包刻意不声明 `engines.dsh`：当前 DSH 是预发布版，semver 默认规则会把常规版本范围误判为不兼容。
+This bundle deliberately omits `engines.dsh`: DSH is currently a prerelease, and semver's default rules would reject any ordinary range.
+
+组合包 patch 会自动挂载，**不要**再往 profile 的 `cordis.patch.yml` 加同名行，否则加载两次。
+The bundle patch mounts the plugin; do not also add a manual mount line.
+
+客户端代码不热重载：安装或改动文件后请完全退出并重新打开 DSH。
+The client half is not hot-reloaded — fully quit and reopen DSH after installing or editing files.
+
+## 已知限制 / Known limits
+
+- `[data-slot="sidebar.workspaces"]` 与 `panelList` 是半稳定宿主约定，变动时插件降级而不抛错。These host contracts are semi-stable; changes degrade gracefully.
+- 浮层定位依赖 `:has()`，需要 Chromium 内核。Overlay positioning needs `:has()` (Chromium-based client).
+- 标签页模式整块隐藏工作区区域，区域内其它入口也一并隐藏，这是刻意的「一组一栏」设计。Toggle hides the whole workspaces region, which is intentional.

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-sidebar-suite bundle patch
+#
+# This is the `dsh.bundle.patch` layer: installing the package through the
+# Plugin Manager (or `dsh plugin add`) appends the bundle to
+# `dsh.profile.bundles`, and the profile boot merges this file — a single
+# `insert` of the plugin row. Do not also keep a manual mount line in the
+# profile's own cordis.patch.yml, or the plugin loads twice.
+- insert:
+    - id: dsh-sidebar-suite
+      name: dsh-sidebar-suite

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="3" y="3" width="18" height="18" rx="3.5"/>
+  <path d="M8 3v18"/>
+  <path d="M11 8h7"/>
+  <path d="M11 12h7"/>
+  <path d="M11 16h4"/>
+</svg>