dsh-wsl-desktop 0.7.6 → 0.8.0

package/README.en.md

@@ -86,6 +86,14 @@ A few details you will run into:
   this plugin does not override it.
 - Inside an open WSL workspace, the file list and the terminal are the distro's. PowerShell in Windows
   workspaces is unaffected.
+- **The W button has its own shortcut, and its hint follows a rebind.** The Windows desktop default is
+  `Ctrl+Alt+W` (the web profile declares none: the sidebar page-close command's web binding is the
+  same combination, and registration validates every profile's defaults, so declaring it would refuse
+  the command on the desktop too); hovering or focusing W shows the action name and keycaps the same way the
+  adjacent "+" does. The command is registered in Keyboard shortcuts, so rebinding or clearing it
+  updates the keycaps and `aria-keyshortcuts` immediately. When another command already owns the
+  default combination and registration is refused, the W button still works and merely omits the
+  keycaps; the shortcut service itself is a desktop dependency present since 0.1.7.
 
 ## What will surprise you
 

package/README.md

@@ -72,6 +72,11 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
   表示网络/子系统路径的写法，形如 `\\wsl.localhost\<发行版>\home\...`。
 - 自带的「+」保持部署原本的行为（桌面上是 Electron 的目录选择器），本插件不改写它。
 - 已经打开的 WSL 工作区里，文件列表和终端都是发行版内的。Windows 工作区里的 PowerShell 不受影响。
+- **W 按钮有自己的快捷键，提示会跟着改绑走。** Windows 桌面的默认是 `Ctrl+Alt+W`（Web 端不声明默认：
+  侧栏页面关闭（`page.close`）的 Web 组合也是它，而快捷键注册会校验所有平台的默认值，声明它会让命令在桌面端也注册失败）；
+  悬停或聚焦 W 时，提示会和左边的「+」一样显示动作名与键帽。命令登记在「快捷键」设置里，
+  改绑或清除后键帽与 `aria-keyshortcuts` 随即更新。默认组合被别的命令占用、导致注册被拒时，
+  W 按钮照常工作，只是不显示键帽；快捷键服务本身是 0.1.7 起桌面自带的依赖。
 
 ## 会意外的地方
 

package/lib/client.js

@@ -3,6 +3,10 @@
  *
  * Adds one control beside the shipped "add workspace" button in the sidebar
  * section header: a `W` button opening this plugin's WSL workspace picker.
+ * The button carries the same kind of shortcut hint the shipped trigger does:
+ * its tooltip shows the effective keys from the shell's shortcut catalog, and
+ * the registered command opens the picker from anywhere the page owns the
+ * keyboard.
  *
  * The shipped button keeps its own behaviour: this half registers no slot
  * occupant, because `sidebar.workspaces.directoryFlow` is `kind: 'single'` and
@@ -71,6 +75,28 @@ window.__ModuleLoader__.load({
     /** Sprite symbol id shape, as `iconSymbolId` composes it: `dsw-icon-<glyph>-<weight>`. */
     const SPRITE_ICON_ID = /^#?dsw-icon-(.+)-(?:regular|medium)$/
 
+    /**
+     * Stable command identity of the W button's keyboard action.
+     *
+     * The id is the plugin's public shortcut identity: it travels through the
+     * shell's command catalog, appears in the Keyboard shortcuts reference, and
+     * survives user rebinds. Renaming it orphans every saved override, so it
+     * names the action rather than the button's ever-changing presentation.
+     */
+    const SHORTCUT_ID = 'wsl.workspace.open'
+
+    /**
+     * The add-workspace trigger's own tooltip delay, mirrored so the two
+     * controls beside each other reveal their shortcut hints together.
+     */
+    const TOOLTIP_HOVER_DELAY_MS = 500
+
+    /** Gap between the W button and its shortcut tooltip, in CSS pixels. */
+    const TOOLTIP_GAP = 8
+
+    /** Minimum distance the shortcut tooltip keeps from the viewport edges. */
+    const TOOLTIP_MARGIN = 12
+
     /**
      * The row glyphs whose artwork is FILL-only, as sprite names.
      *
@@ -1518,7 +1544,15 @@ window.__ModuleLoader__.load({
 
     /** The injected services the picker and its trigger read. */
     // ── 5. the companion button and workspace rows ─────────────────────────────
-    const companion = { button: null, fallback: null, trigger: null, observer: null, scheduled: false, disposed: false }
+    const companion = {
+      button: null,
+      fallback: null,
+      hideHint: null,
+      trigger: null,
+      observer: null,
+      scheduled: false,
+      disposed: false,
+    }
 
     /** Whether the missing-workspace-source warning was already printed. */
     let warnedWorkspaceSource = false
@@ -1876,6 +1910,10 @@ window.__ModuleLoader__.load({
         companion.trigger = trigger
       }
       if (trigger === null) {
+        // React took the anchor away, so the companion leaves too. The tooltip
+        // is a fixed portal with no pointer to leave; withdraw it explicitly or
+        // it outlives the control it describes.
+        companion.hideHint?.()
         if (button.isConnected) button.remove()
         return
       }
@@ -1896,7 +1934,13 @@ window.__ModuleLoader__.load({
       const box = button.getBoundingClientRect()
       const fits = row === undefined || box.right <= row.right + 1
       const triggerVisible = getComputedStyle(trigger).visibility !== 'hidden'
-      button.style.display = fits && triggerVisible ? '' : 'none'
+      const shown = fits && triggerVisible
+      button.style.display = shown ? '' : 'none'
+      // The shipped cluster hides itself (inline search, narrow rail) by
+      // visibility and the companion follows via display; a visible tooltip must
+      // follow too, because no pointerleave fires for a control that left the
+      // hit-test tree.
+      if (!shown) companion.hideHint?.()
     }
 
     /**
@@ -1911,6 +1955,362 @@ window.__ModuleLoader__.load({
       return document.body ?? document.documentElement
     }
 
+    /**
+     * The effective catalog row for the W shortcut, or null when the shell has
+     * no shortcut service or has not published the command yet.
+     *
+     * The row is the SINGLE source of the hint: `keys` are the platform-formatted
+     * labels the shortcut service presents, and `aria` is the same binding in
+     * `aria-keyshortcuts` spelling. A rebind replaces the row, so the tooltip
+     * follows the user's setting instead of the default first seen.
+     * @param {object} ctx - the client plugin context.
+     * @returns {object | null} the row for `SHORTCUT_ID`, or null.
+     */
+    function shortcutRowOf(ctx) {
+      const catalog = ctx.shortcuts?.catalog
+      if (typeof catalog?.getSnapshot !== 'function') return null
+      const rows = catalog.getSnapshot()
+      if (!Array.isArray(rows)) return null
+      return rows.find((row) => row.id === SHORTCUT_ID) ?? null
+    }
+
+    /**
+     * Publish or withdraw the accessible shortcut claim on one control.
+     * @param {HTMLElement | null} node - the control, or null when it is absent.
+     * @param {object | null} row - the effective catalog row.
+     */
+    function setKeyshortcuts(node, row) {
+      if (node === null) return
+      if (typeof row?.aria === 'string' && row.aria !== '') node.setAttribute('aria-keyshortcuts', row.aria)
+      else node.removeAttribute('aria-keyshortcuts')
+    }
+
+    /** Tooltip bubble styling, mirrored from the shipped tooltip's semantic tokens. */
+    const SHORTCUT_TOOLTIP_STYLE = {
+      position: 'fixed',
+      zIndex: '1100',
+      display: 'none',
+      alignItems: 'center',
+      gap: '8px',
+      width: 'max-content',
+      maxWidth: 'min(50vw, calc(100vw - 24px))',
+      boxSizing: 'border-box',
+      padding: '3px 7px',
+      borderRadius: 'var(--dsw-radius-sm, 8px)',
+      background: 'var(--dsw-alias-tooltip-bg, #3a3a3a)',
+      color: 'var(--dsw-static-neutral-bluish-00, #ffffff)',
+      fontSize: '13px',
+      lineHeight: '20px',
+      whiteSpace: 'pre-line',
+      overflowWrap: 'break-word',
+      pointerEvents: 'none',
+    }
+
+    /** The keycap strip's layout inside a tooltip. */
+    const SHORTCUT_KEYS_STYLE = {
+      display: 'inline-flex',
+      flex: 'none',
+      alignItems: 'center',
+      gap: '2px',
+      color: 'inherit',
+      fontSize: '11px',
+      lineHeight: '14px',
+      whiteSpace: 'nowrap',
+    }
+
+    /** One keycap: the shipped tooltip's 16px badge. */
+    const SHORTCUT_KEY_STYLE = {
+      boxSizing: 'border-box',
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      font: 'inherit',
+    }
+
+    /**
+     * One shortcut tooltip attached to a plain DOM control.
+     *
+     * The shipped "add workspace" button gets this from the React Tooltip in
+     * `ui-primitives`; this half is a hand-written factory with no module graph,
+     * and a feature plugin may not reach into another feature's values, so the
+     * same presentation is rebuilt here on the shared semantic tokens. The
+     * bubble is portaled to the body and positioned fixed, so the sidebar's
+     * clipping and stacking contexts cannot hide it.
+     * @param {HTMLElement} anchor - the control the tooltip belongs to.
+     * @param {string} label - the action name shown before the keycaps.
+     * @returns {{ setKeys: (keys: readonly string[]) => void, dismiss: () => void, dispose: () => void }}
+     *   the key publisher, the layout-driven dismissal, and the disposer.
+     */
+    function createShortcutHint(anchor, label) {
+      let bubble = null
+      let keys = []
+      let showTimer = null
+      let visible = false
+      // The shipped Tooltip keeps hover and focus as INDEPENDENT triggers and
+      // withdraws the bubble only after BOTH clear: hovering away from a focused
+      // anchor must not drop it, and blurring while the pointer is still over
+      // the anchor must not drop it either.
+      let hovered = false
+      let focused = false
+
+      function clearShowTimer() {
+        if (showTimer === null) return
+        clearTimeout(showTimer)
+        showTimer = null
+      }
+
+      /**
+       * Render the current keycap labels into the bubble, or hide the strip.
+       *
+       * Windows presents a combination as one plus-separated run in a single
+       * pill; a modifier set without a separator (macOS symbols) gets one cap
+       * per key. Both shapes are built from the catalog's labels, never from a
+       * key spelling written in this file.
+       */
+      function renderKeys() {
+        if (bubble === null) return
+        const strip = bubble.querySelector('[data-wsl-tooltip-keys]')
+        if (strip === null) return
+        strip.replaceChildren()
+        if (keys.length === 0) {
+          strip.style.display = 'none'
+          bubble.style.paddingInlineEnd = '7px'
+          return
+        }
+        strip.style.display = 'inline-flex'
+        bubble.style.paddingInlineEnd = '5px'
+        const joined = keys.includes('+')
+        strip.style.background = joined
+          ? 'var(--dsw-alias-tooltip-key-bg, rgba(255,255,255,0.18))'
+          : 'transparent'
+        strip.style.height = joined ? '16px' : ''
+        strip.style.padding = joined ? '0 4px' : '0'
+        strip.style.borderRadius = joined ? '4px' : ''
+        for (const token of keys) {
+          const key = document.createElement('kbd')
+          key.textContent = token
+          Object.assign(key.style, SHORTCUT_KEY_STYLE)
+          if (!joined) {
+            key.style.minWidth = '16px'
+            key.style.height = '16px'
+            key.style.padding = '0 2px'
+            key.style.borderRadius = '4px'
+            key.style.background = 'var(--dsw-alias-tooltip-key-bg, rgba(255,255,255,0.18))'
+          }
+          strip.append(key)
+        }
+      }
+
+      /** Build the bubble once: a label span and a keycap strip. */
+      function ensureBubble() {
+        if (bubble !== null) return bubble
+        bubble = el('span', SHORTCUT_TOOLTIP_STYLE)
+        bubble.setAttribute('role', 'tooltip')
+        bubble.setAttribute('aria-hidden', 'true')
+        bubble.setAttribute('data-wsl-shortcut-tooltip', '')
+        const text = el('span', { minWidth: '0' }, label)
+        text.setAttribute('data-wsl-tooltip-label', '')
+        const strip = el('span', SHORTCUT_KEYS_STYLE)
+        strip.setAttribute('data-wsl-tooltip-keys', '')
+        bubble.append(text, strip)
+        renderKeys()
+        return bubble
+      }
+
+      /** Place the bubble below the anchor, clamped to the viewport. */
+      function position() {
+        if (bubble === null) return
+        const anchorBox = anchor.getBoundingClientRect()
+        // A media query or an ancestor class can collapse the header on resize
+        // without any DOM mutation, so no layout pass reaches the hint. A zero
+        // box means the tooltip has no anchor left to describe: withdraw it
+        // instead of placing it from (0, 0).
+        if (anchorBox.width <= 0 && anchorBox.height <= 0) {
+          hide()
+          return
+        }
+        const bubbleBox = bubble.getBoundingClientRect()
+        const centered = anchorBox.left + anchorBox.width / 2 - bubbleBox.width / 2
+        const left = Math.min(
+          Math.max(TOOLTIP_MARGIN, centered),
+          Math.max(TOOLTIP_MARGIN, window.innerWidth - bubbleBox.width - TOOLTIP_MARGIN),
+        )
+        let top = anchorBox.bottom + TOOLTIP_GAP
+        // The sidebar header sits near the top edge, but a short window or a
+        // moved trigger still has to get a readable bubble: flip above the
+        // anchor when the space below cannot hold it.
+        if (top + bubbleBox.height > window.innerHeight - TOOLTIP_MARGIN) {
+          top = Math.max(TOOLTIP_MARGIN, anchorBox.top - bubbleBox.height - TOOLTIP_GAP)
+        }
+        bubble.style.left = `${left}px`
+        bubble.style.top = `${top}px`
+        bubble.style.visibility = 'visible'
+      }
+
+      function show() {
+        if (!anchor.isConnected || anchor.style.display === 'none') return
+        // Closing the picker refocuses its opener. When that opener already sits
+        // in a hidden subtree its box is zero; placing a fixed bubble from that
+        // box would paint it at the viewport origin.
+        const anchorBox = anchor.getBoundingClientRect()
+        if (anchorBox.width <= 0 && anchorBox.height <= 0) return
+        const node = ensureBubble()
+        if (!node.isConnected) hostElement().append(node)
+        visible = true
+        node.style.display = 'inline-flex'
+        node.style.visibility = 'hidden'
+        position()
+      }
+
+      function hide() {
+        clearShowTimer()
+        visible = false
+        if (bubble !== null) bubble.style.display = 'none'
+      }
+
+      /**
+       * Withdraw the bubble AND clear both triggers.
+       *
+       * The layout pass calls this when the anchor leaves the layout, mirroring
+       * the shipped Tooltip's disabled effect: without the reset, a hover that
+       * was live when the header hid survives the withdrawal, and a later
+       * focus/blur can keep a bubble on screen with no pointer over the anchor.
+       */
+      function dismiss() {
+        hovered = false
+        focused = false
+        hide()
+      }
+
+      function reveal(delay) {
+        clearShowTimer()
+        if (delay <= 0) {
+          show()
+          return
+        }
+        showTimer = setTimeout(() => {
+          showTimer = null
+          show()
+        }, delay)
+      }
+
+      const onPointerEnter = (event) => {
+        // Touch has no hover state; tapping still invokes the button.
+        if (event.pointerType === 'touch') return
+        hovered = true
+        reveal(TOOLTIP_HOVER_DELAY_MS)
+      }
+      const onPointerLeave = () => {
+        hovered = false
+        // A pending hover reveal is cancelled even when focus holds the bubble
+        // open; otherwise it would reappear after the pointer has left.
+        clearShowTimer()
+        if (!focused) hide()
+      }
+      const onFocus = () => {
+        // The shared input-modality attribute is how the shell publishes
+        // pointer-acquired focus; a picker closing back onto its trigger must
+        // not flash the shortcut bubble after a click.
+        if (document.documentElement.getAttribute('data-input-modality') === 'pointer') return
+        focused = true
+        reveal(0)
+      }
+      const onBlur = () => {
+        focused = false
+        clearShowTimer()
+        if (!hovered) hide()
+      }
+      const onClick = () => {
+        // Activating the button dismisses the bubble even though the pointer
+        // stays over it; the shipped tooltip clears its focus trigger here too.
+        focused = false
+        hide()
+      }
+      const onResize = () => { if (visible) position() }
+      anchor.addEventListener('pointerenter', onPointerEnter)
+      anchor.addEventListener('pointerleave', onPointerLeave)
+      anchor.addEventListener('focus', onFocus)
+      anchor.addEventListener('blur', onBlur)
+      anchor.addEventListener('click', onClick)
+      window.addEventListener('resize', onResize)
+
+      return {
+        /**
+         * Publish the effective keys to the (possibly not yet built) bubble.
+         * @param {readonly string[]} nextKeys - the catalog's presented labels.
+         */
+        setKeys(nextKeys) {
+          const normalized = Array.isArray(nextKeys) ? nextKeys.map(String) : []
+          if (normalized.join('\u0000') === keys.join('\u0000')) return
+          keys = normalized
+          if (bubble === null) return
+          renderKeys()
+          if (visible) position()
+        },
+        /** Withdraw the bubble and clear both triggers when its anchor leaves the layout. */
+        dismiss,
+        /** Release the bubble and every listener it installed. */
+        dispose() {
+          clearShowTimer()
+          visible = false
+          hovered = false
+          focused = false
+          anchor.removeEventListener('pointerenter', onPointerEnter)
+          anchor.removeEventListener('pointerleave', onPointerLeave)
+          anchor.removeEventListener('focus', onFocus)
+          anchor.removeEventListener('blur', onBlur)
+          anchor.removeEventListener('click', onClick)
+          window.removeEventListener('resize', onResize)
+          if (bubble !== null) {
+            bubble.remove()
+            bubble = null
+          }
+          keys = []
+        },
+      }
+    }
+
+    /**
+     * Register the W button's keyboard command, tolerating a host without the
+     * shortcut service or a catalog that refuses the default.
+     *
+     * Registration is deliberately outside the button's click path: the command
+     * resolves to the same `openPicker` the click calls, so the two entries cannot
+     * drift. A refused registration (another command already owns the same
+     * default on one of this command's profiles) is logged and leaves the
+     * button usable; the hint then carries the label alone.
+     * @param {object} ctx - the client plugin context.
+     * @returns {() => void} the registration's disposer, or a no-op.
+     */
+    function installShortcut(ctx) {
+      try {
+        // The access itself is inside the guard: a context whose service getter
+        // throws must degrade the hint, not abort the install that owns W.
+        const shortcuts = ctx.shortcuts
+        if (typeof shortcuts?.register !== 'function') return () => {}
+        return shortcuts.register({
+          id: SHORTCUT_ID,
+          label: () => BUTTON_LABEL,
+          aliases: ['wsl', 'wsl workspace', 'open wsl workspace'],
+          defaults: {
+            // Desktop only. On the Web profile the shell's page.close command
+            // already owns KeyW+primary+alt, and the shortcut registry
+            // validates EVERY profile's defaults at registration:
+            // declaring the Web default here makes this command throw even on
+            // a desktop runtime, so the hint loses its keys and the key does
+            // nothing. Web users can bind the command themselves.
+            'desktop:windows': { code: 'KeyW', modifiers: ['primary', 'alt'] },
+          },
+          regions: ['page', 'editable'],
+          modals: ['sidebar'],
+          resolve: () => ({ status: 'handled', run: () => openPicker(ctx) }),
+        })
+      } catch (error) {
+        console.warn('dsh-wsl-desktop: W 快捷键注册失败，W 按钮仍然可用', error)
+        return () => {}
+      }
+    }
+
     /**
      * Install the companion button and keep it attached.
      * @param {object} ctx - the client plugin context.
@@ -1923,19 +2323,22 @@ window.__ModuleLoader__.load({
       button.setAttribute('aria-label', BUTTON_LABEL)
       button.setAttribute('aria-haspopup', 'dialog')
       button.setAttribute('aria-expanded', 'false')
-      button.title = BUTTON_LABEL
       button.append(el('span', {
         fontWeight: '600',
         fontSize: '13px',
         lineHeight: '1',
         letterSpacing: '0.02em',
       }, 'W'))
+      // The hint replaces the native title: it carries the SAME action name plus
+      // the effective keycaps, and a title would show a second, stale tooltip.
+      const hint = createShortcutHint(button, BUTTON_LABEL)
       button.addEventListener('click', (event) => {
         event.preventDefault()
         event.stopPropagation()
         openPicker(ctx)
       })
       companion.button = button
+      companion.hideHint = hint.dismiss
 
       /** The degraded entry shown when the sidebar anchor is missing. */
       let fallbackEntry = null
@@ -1994,7 +2397,45 @@ window.__ModuleLoader__.load({
         hostElement().append(entry)
         fallbackEntry = entry
         companion.fallback = open
+        // The fallback is the W button's only visible entry in this phase, so
+        // the shortcut claim belongs on it too; the visual bubble stays with the
+        // real button to keep the failure path minimal.
+        applyShortcut()
+      }
+
+      /**
+       * Publish the effective shortcut row to the button, hint, and fallback.
+       *
+       * Called once at install and again for every catalog change (a rebind, a
+       * clear, another command's registration). The row is read from the live
+       * catalog rather than remembered, so a rebind cannot leave the hint
+       * claiming keys the command no longer owns.
+       */
+      function applyShortcut() {
+        let row = null
+        try {
+          row = shortcutRowOf(ctx)
+        } catch (error) {
+          // A throwing catalog is a shell fault, not a reason to lose the W
+          // button: the hint is peripheral and degrades to its label.
+          console.warn('dsh-wsl-desktop: W 快捷键目录读取失败，W 按钮仍然可用', error)
+        }
+        setKeyshortcuts(button, row)
+        hint.setKeys(row?.keys ?? [])
+        setKeyshortcuts(fallbackEntry?.querySelector('[data-wsl-fallback-entry]') ?? null, row)
+      }
+
+      const disposeShortcut = installShortcut(ctx)
+      let disposeCatalog = null
+      try {
+        const catalog = ctx.shortcuts?.catalog
+        disposeCatalog = typeof catalog?.subscribe === 'function'
+          ? catalog.subscribe(applyShortcut)
+          : null
+      } catch (error) {
+        console.warn('dsh-wsl-desktop: W 快捷键目录订阅失败，W 按钮仍然可用', error)
       }
+      applyShortcut()
 
       // `sync` is idempotent and never removes the node it manages, so its own
       // work cannot re-trigger the observer it runs from.
@@ -2049,6 +2490,12 @@ window.__ModuleLoader__.load({
       return () => {
         clearTimeout(warning)
         removeFallback()
+        // Unsubscribe BEFORE the command leaves the catalog: removing it makes
+        // the service publish a fresh snapshot, and a listener still attached
+        // would rebuild the bubble this teardown is about to delete.
+        if (disposeCatalog !== null) disposeCatalog()
+        disposeShortcut()
+        hint.dispose()
         observer.disconnect()
         unsubscribe?.()
         // disconnect() does not cancel a callback already handed to
@@ -2066,6 +2513,7 @@ window.__ModuleLoader__.load({
         }
         button.remove()
         companion.button = null
+        companion.hideHint = null
         companion.trigger = null
         companion.observer = null
         teardown?.()
@@ -2078,7 +2526,7 @@ window.__ModuleLoader__.load({
       // `remote.session` is the namespace the create request travels through
       // (see `createBoundSession`); the harness's own client plugins inject it
       // the same way.
-      inject: ['workspaces', 'uiWorkspace', 'sessions', 'remote', 'remote.session'],
+      inject: ['workspaces', 'uiWorkspace', 'sessions', 'remote', 'remote.session', 'shortcuts'],
       apply(ctx) {
         ctx.effect(() => install(ctx), 'wsl-desktop: sidebar WSL workspace trigger')
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",