@linxin666/dsh-usage 0.3.22 → 0.3.24

package/src/client/sidebar-entry-core.ts

@@ -0,0 +1,321 @@
+// Generated by scripts/sync-shared.mjs from shared/client/sidebar-entry-core.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared sidebar entry injection core.
+ *
+ * dsh's sidebar shell exposes no slot an external plugin can register into,
+ * so the entry row is injected between the shell's New Session button and the
+ * workspace browser. The injection self-heals: a MutationObserver watches the
+ * sidebar root and re-inserts the row whenever a React re-render displaces it
+ * (re-insertion happens in the same frame, before paint, so no flicker).
+ *
+ * The row is plain DOM (no React tree) so it can never disturb the shell's
+ * reconciliation; the view it toggles is a separate root owned by the caller.
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit the shared source and re-run the sync instead of editing a copy.
+ */
+import { subscribeBodyInvalidations } from './body-mutations.ts'
+
+/**
+ * One trailing action button seated at the entry row's right edge (e.g. a
+ * refresh command or a collapse chevron). Rows with actions switch from the
+ * classic single-button structure to a container with a main button plus the
+ * action buttons (nested interactive elements are invalid HTML); rows without
+ * actions keep the classic structure untouched.
+ */
+export interface SidebarEntryAction {
+  /** Stable id stamped as data-dsh-entry-action="<id>" (CSS hooks and tests). */
+  id: string
+  /** Inline icon markup while the row is active (always, when inactiveIcon is unset). */
+  icon: string
+  /**
+   * Optional icon while the row is inactive. Setting it makes the action a
+   * state mirror (a collapse chevron): the core swaps the icon and stamps
+   * aria-expanded on every active-state change. Requires the active bridge.
+   */
+  inactiveIcon?: string
+  /** Localized accessible label (aria-label + title); receives the active state. */
+  label(active: boolean): string
+  /**
+   * Click handler; receives the button so the caller can drive transient
+   * affordances (a refresh cooldown) without a re-render.
+   */
+  onClick(button: HTMLButtonElement): void
+}
+
+/** Per-package configuration for one sidebar entry row. */
+export interface SidebarEntryOptions {
+  /** Full attribute name identifying the injected row (idempotency key), e.g. 'data-dsh-ssh-entry'. */
+  rowAttribute: string
+  /** CSS selector matching the injected row, e.g. '[data-dsh-ssh-entry]'. */
+  rowSelector: string
+  /**
+   * L2 semantic-attribute plugin id (issue #506, enum table:
+   * skins/skin-center/contracts/semantic-attrs-v1.md). When set, the row also
+   * outputs data-dsh-plugin="<id>" and data-dsh-part="sidebar-entry"; unset
+   * leaves the row without semantic attributes.
+   */
+  plugin?: string
+  /** Inline icon markup (matches the shell's 16px nav-icon look). */
+  icon: string
+  /** CSS module class names for the row and its two spans (entry / entryIcon / entryLabel). */
+  css: Record<string, string>
+  /** Localized row label (aria-label + visible text). */
+  label(): string
+  /** Optional localized tooltip (title attribute). */
+  tooltip?(): string
+  /**
+   * Optional locale-change subscription: re-applies label / aria-label /
+   * tooltip whenever the active locale changes. Plain-DOM rows would
+   * otherwise keep the label captured at mount; pass the SDK locale runtime
+   * subscription (ctx.locale.subscribe) so the row follows the language
+   * switch without a reload.
+   */
+  refresh?: { subscribe(listener: () => void): () => void }
+  /** Click action (open/toggle the owning panel). */
+  onToggle(): void
+  /**
+   * Optional trailing action buttons at the row's right edge. Requires the
+   * package CSS to seat entryMain / entryAction; empty keeps the classic
+   * single-button row.
+   */
+  actions?: readonly SidebarEntryAction[]
+  /** Family-block position: 'before' inserts ahead of sibling plugin rows, 'after' behind them. */
+  position: 'before' | 'after'
+  /**
+   * Selectors of the sibling plugin entry rows this package orders against
+   * (its own row included — the placement guard excludes a row that is
+   * already inside the root). Each package passes the same list it used
+   * before the consolidation so the rendered order stays stable.
+   */
+  familySelectors: readonly string[]
+  /** Optional active-state bridge; highlights the row while the panel is open. */
+  active?: {
+    subscribe(listener: () => void): () => void
+    isOpen(): boolean
+  }
+}
+
+/** Find the sidebar shell root element, or undefined while not yet mounted. */
+function sidebarRoot(): HTMLElement | undefined {
+  const column = document.querySelector<HTMLElement>('[data-pane="sidebar"], [class*="sidebarCol"]')
+  if (column === null) return undefined
+  // Current shells wrap the sidebar UI: column > wrapper > root(logoRow owner).
+  // Prefer the element that owns the logo row — the real sidebar UI root —
+  // and fall back to the column's first child for legacy shells.
+  const logoOwner = column.querySelector<HTMLElement>('[class*="logoRow"]')?.parentElement
+  return logoOwner ?? (column.firstElementChild as HTMLElement | undefined)
+}
+
+/** The New Session button: nested in the logo row on current shells, a direct child on legacy shells. */
+function newSessionButton(root: HTMLElement): HTMLButtonElement | undefined {
+  const nested = root.querySelector<HTMLButtonElement>('button[class*="newSession"]')
+  if (nested !== null) return nested
+  for (const child of root.children) {
+    if (child.tagName === 'BUTTON') return child as HTMLButtonElement
+  }
+  return undefined
+}
+
+/** Build the entry row (detached; inserted once the shell is up). */
+function createEntry(options: SidebarEntryOptions): { entry: HTMLElement; applyLabel: () => void; setOpen: (open: boolean) => void } {
+  const actions = options.actions ?? []
+  const composite = actions.length > 0
+  const entry = document.createElement(composite ? 'div' : 'button') as HTMLElement
+  if (!composite) (entry as HTMLButtonElement).type = 'button'
+  entry.setAttribute(options.rowAttribute, '')
+  if (options.plugin !== undefined) {
+    entry.setAttribute('data-dsh-plugin', options.plugin)
+    entry.setAttribute('data-dsh-part', 'sidebar-entry')
+  }
+  entry.className = options.css['entry'] ?? ''
+  const labelSpan = document.createElement('span')
+  labelSpan.className = options.css['entryLabel'] ?? ''
+  const iconSpan = document.createElement('span')
+  iconSpan.className = options.css['entryIcon'] ?? ''
+  iconSpan.innerHTML = options.icon
+  // The main hit area: the classic row IS the button; with trailing actions
+  // the row becomes a container and the main area its own button, so the row
+  // never nests interactive elements.
+  const main = composite ? document.createElement('button') : (entry as HTMLButtonElement)
+  if (composite) {
+    main.type = 'button'
+    main.className = options.css['entryMain'] ?? ''
+    main.append(iconSpan, labelSpan)
+    entry.append(main)
+  } else {
+    entry.append(iconSpan, labelSpan)
+  }
+  const actionButtons: { action: SidebarEntryAction; button: HTMLButtonElement }[] = []
+  for (const action of actions) {
+    const button = document.createElement('button')
+    button.type = 'button'
+    button.className = options.css['entryAction'] ?? ''
+    button.setAttribute('data-dsh-entry-action', action.id)
+    button.innerHTML = action.icon
+    button.addEventListener('click', () => { action.onClick(button) })
+    entry.append(button)
+    actionButtons.push({ action, button })
+  }
+  let open = false
+  const applyActions = (): void => {
+    for (const { action, button } of actionButtons) {
+      button.innerHTML = open || action.inactiveIcon === undefined ? action.icon : action.inactiveIcon
+      const text = action.label(open)
+      button.setAttribute('aria-label', text)
+      button.setAttribute('title', text)
+      if (action.inactiveIcon !== undefined) button.setAttribute('aria-expanded', String(open))
+    }
+  }
+  const applyLabel = (): void => {
+    main.setAttribute('aria-label', options.label())
+    if (options.tooltip !== undefined) main.setAttribute('title', options.tooltip())
+    labelSpan.textContent = options.label()
+    applyActions()
+  }
+  applyLabel()
+  main.addEventListener('click', options.onToggle)
+  if (composite) {
+    // The old row was clickable edge to edge; keep the padding between the
+    // main area and the action buttons a toggle target as well.
+    entry.addEventListener('click', (event) => {
+      if (event.target === entry) options.onToggle()
+    })
+  }
+  return {
+    entry,
+    applyLabel,
+    setOpen: (next: boolean) => {
+      open = next
+      applyActions()
+    },
+  }
+}
+
+/** Re-insert the entry after the New Session row (before the browser region). */
+function placeEntry(root: HTMLElement, entry: HTMLElement, options: SidebarEntryOptions): boolean {
+  const button = newSessionButton(root)
+  if (button === undefined) return false
+  if (entry.parentElement !== root) {
+    // Position relative to the family block (entries injected by sibling
+    // plugins), never relative to transient logoRow geometry: every family
+    // plugin that self-heals during a re-render then lands in the same
+    // relative order, so the entries cannot swap positions regardless of
+    // observer callback order or of shell wrapper changes. There is no
+    // append-to-end fallback: appending at the end would randomly reorder
+    // the block after a shell re-render.
+    const row = button.closest('[class*="logoRow"]')
+    const base = (row !== null && row.parentElement === root) ? row : button
+    const family = Array.from(root.children).filter(
+      (el): el is HTMLElement => el instanceof HTMLElement && el.matches(options.familySelectors.join(', ')),
+    )
+    const anchor = options.position === 'before'
+      ? (family.length > 0 ? family[0] : base.nextElementSibling)
+      : (family.length > 0 ? family[family.length - 1]!.nextElementSibling : base.nextElementSibling)
+    root.insertBefore(entry, anchor)
+  }
+  return true
+}
+
+/**
+ * Mount the sidebar entry, waiting for the shell to render and self-healing
+ * on later React re-renders.
+ * @param options - the row's attribute/icon/copy/action/ordering configuration.
+ * @returns disposer removing the entry and its observers.
+ */
+export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
+  // DOM-level idempotency: whatever path mounted an entry row before this
+  // call (a duplicated apply, an HMR re-injection, a stale module still
+  // alive), never mount a second one. The existing row keeps working; a full
+  // page reload is the ultimate reset.
+  if (typeof document !== 'undefined' && document.querySelector(options.rowSelector) !== null) {
+    return () => {}
+  }
+  const { entry, applyLabel, setOpen } = createEntry(options)
+  let root: HTMLElement | undefined
+  let placed = false
+  let unsubscribeRefresh: (() => void) | undefined
+  if (options.refresh !== undefined) {
+    try {
+      unsubscribeRefresh = options.refresh.subscribe(applyLabel)
+    } catch {
+      // A throwing subscription must not break the mount; the label stays at
+      // its initial value and the next reload resolves it again.
+    }
+  }
+
+  const tryPlace = (): void => {
+    if (root !== undefined && !root.isConnected) {
+      // The shell rebuilt the sidebar pane (whole-tree teardown); the root
+      // observer is gone with the old tree, so detach it and re-query from
+      // scratch. The new pane is later noticed by the body-level watcher.
+      rootObserver.disconnect()
+      root = undefined
+      placed = false
+    }
+    if (placed) {
+      // Cheap short-circuit: entry still lives in a mountable subtree.
+      if (document.body.contains(entry)) return
+      // Entry was torn down together with the old tree; reset and re-place.
+      rootObserver.disconnect()
+      root = undefined
+      placed = false
+    }
+    root ??= sidebarRoot()
+    if (root === undefined) return
+    placed = placeEntry(root, entry, options)
+    if (placed) {
+      rootObserver.observe(root, { childList: true, subtree: true })
+    }
+  }
+
+  // Body-level watcher retained as the "whole rebuild" fallback: when the shell
+  // tears down the whole sidebar pane, the root observer is gone with it and
+  // only this body observation can notice the new pane mounting. It stays
+  // subscribed after placement; the placed-and-still-mounted case
+  // short-circuits through the cheap document.body.contains(entry) check, so
+  // unrelated app mutations (e.g. chat streaming) cost one contains check per
+  // frame instead of churning the full re-query. The body observation itself is
+  // the page-wide hub (shared/client/body-mutations.ts): every family plugin
+  // used to hold its own body subtree observer, so the per-mutation cost grew
+  // with the number of installed plugins; the hub keeps exactly one.
+  const unsubscribeBody = subscribeBodyInvalidations(() => { tryPlace() })
+
+  // Self-heal: if a React re-render displaces the row, re-insert it in the
+  // same frame (microtask before paint -> no visible flicker).
+  const rootObserver = new MutationObserver(() => {
+    if (root === undefined || !root.isConnected) {
+      placed = false
+      tryPlace()
+      return
+    }
+    if (!root.contains(entry)) {
+      placed = placeEntry(root, entry, options)
+    }
+  })
+
+  // Reflect the panel's open state on the row (active highlight). Note: assigning
+  // undefined to dataset.active materializes data-active="undefined" and keeps the
+  // row permanently highlighted — delete the attribute instead.
+  const unsubscribeActive = options.active === undefined ? undefined : (() => {
+    const syncActive = (): void => {
+      const open = options.active!.isOpen()
+      if (open) entry.dataset.active = 'true'
+      else delete entry.dataset.active
+      setOpen(open)
+    }
+    const unsubscribe = options.active.subscribe(syncActive)
+    syncActive()
+    return unsubscribe
+  })()
+
+  tryPlace()
+
+  return () => {
+    unsubscribeBody()
+    rootObserver.disconnect()
+    unsubscribeRefresh?.()
+    unsubscribeActive?.()
+    entry.remove()
+  }
+}

package/src/client/sidebar-entry.ts

@@ -0,0 +1,101 @@
+/**
+ * Sidebar entry injection for the usage panel (issue #1592) — wiring over the
+ * shared core. Unlike the panel-takeover family (task board / SSH / skill
+ * center) this row does not participate in the family block, so it is placed
+ * directly under the New Session row and ordered after those entries. The row
+ * seats the panel's controls as trailing actions: a refresh command and a
+ * collapse chevron mirroring the open state, so the panel below renders only
+ * its content.
+ * @module @linxin666/dsh-usage/client/sidebar-entry
+ */
+
+import { t } from './locales.ts'
+import css from './usage.module.css'
+import { mountSidebarEntry as mountSharedSidebarEntry, type SidebarEntryAction } from './sidebar-entry-core.ts'
+
+/** Stable data attribute identifying the injected entry row. */
+export const ENTRY_SELECTOR = '[data-dsh-usage-entry]'
+
+/** Inline gauge glyph normalized to the shell's 18px navigation glyph size. */
+const ICON = '<svg viewBox="0 0 16 16" width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2.5 12.5a7 7 0 0 1 11 -4.3"/><path d="M8 12.5V8.2l2.9-2.1"/><circle cx="8" cy="12.5" r="1"/></svg>'
+
+/** Refresh glyph: a clockwise circular arrow, 14px like the sibling action icons. */
+const REFRESH_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M13.4 8a5.4 5.4 0 1 1-1.58-3.82"/><path d="M13.4 2.6v2.7h-2.7"/></svg>'
+
+/** Disclosure chevrons: down while expanded, right while collapsed. */
+const CHEVRON_OPEN_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m4 6 4 4 4-4"/></svg>'
+const CHEVRON_CLOSED_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 4 4 4-4 4"/></svg>'
+
+/** Refresh cooldown: one forced probe cycle per click, the icon spins meanwhile. */
+const REFRESH_COOLDOWN_MS = 3000
+
+/** Locale-change subscription the shared core asks for (ctx.locale.subscribe shape). */
+export interface LocaleRefreshSource { subscribe(listener: () => void): () => void }
+
+/** Panel-facing callbacks and state the entry row's controls drive. */
+export interface UsageSidebarEntryHandlers {
+  /** Toggles the panel (the row's main area and the collapse chevron). */
+  onToggle(): void
+  /** Forces one host probe cycle (the refresh action). */
+  onRefresh(): void
+  /** Reads the panel's expanded state (row highlight and chevron direction). */
+  isOpen(): boolean
+  /** Subscribes to expanded-state changes (the chevron mirrors them live). */
+  subscribeOpen(listener: () => void): () => void
+}
+
+/** Trailing actions seated at the row's right edge. */
+function entryActions(handlers: UsageSidebarEntryHandlers): readonly SidebarEntryAction[] {
+  return [
+    {
+      id: 'refresh',
+      icon: REFRESH_ICON,
+      label: () => t('usage.refresh'),
+      onClick: (button) => {
+        handlers.onRefresh()
+        button.disabled = true
+        window.setTimeout(() => { button.disabled = false }, REFRESH_COOLDOWN_MS)
+      },
+    },
+    {
+      id: 'collapse',
+      icon: CHEVRON_OPEN_ICON,
+      inactiveIcon: CHEVRON_CLOSED_ICON,
+      label: (open) => t(open ? 'usage.sidebar.toggle.collapse' : 'usage.sidebar.toggle.expand'),
+      onClick: () => { handlers.onToggle() },
+    },
+  ]
+}
+
+/**
+ * Mount the usage sidebar entry.
+ * @param handlers - the panel's toggle/refresh callbacks and open-state face.
+ * @param locale - locale-change source; when given, re-applies the label on a
+ *   language switch (the plain-DOM row otherwise keeps the mount-time copy).
+ * @returns disposer removing the entry and its observers.
+ */
+export function mountSidebarEntry(
+  handlers: UsageSidebarEntryHandlers,
+  locale?: LocaleRefreshSource,
+): () => void {
+  return mountSharedSidebarEntry({
+    rowAttribute: 'data-dsh-usage-entry',
+    rowSelector: ENTRY_SELECTOR,
+    plugin: 'usage',
+    icon: ICON,
+    css,
+    label: () => t('usage.sidebar.entry.label'),
+    tooltip: () => t('usage.sidebar.entry.tooltip'),
+    refresh: locale === undefined ? undefined : { subscribe: (listener) => locale.subscribe(listener) },
+    onToggle: handlers.onToggle,
+    actions: entryActions(handlers),
+    // Directly after the family entries (task board / SSH / skill center) and
+    // before the workspace browser, matching the requested sidebar order.
+    position: 'after',
+    familySelectors: ['[data-dsh-taskboard-entry]', '[data-dsh-ssh-entry]', '[data-dsh-skill-explorer-entry]', '[data-dsh-usage-entry]'],
+    active: {
+      subscribe: handlers.subscribeOpen,
+      isOpen: handlers.isOpen,
+    },
+  })
+}

package/src/client/sidebar-panel-mount.tsx

@@ -0,0 +1,113 @@
+/**
+ * Sidebar usage panel mounting (issue #1592).
+ *
+ * The panel is a plain DOM row inserted into the sidebar right below the
+ * usage entry row, carrying its own React root. Placement self-heals with the
+ * same page-wide body-mutation hub the entry row uses; the entry row stays the
+ * anchor, so the sidebar order never depends on this module's timing.
+ *
+ * The mount owns the panel's single open state: initialized from localStorage,
+ * flipped by the entry row's toggle controls, and mirrored to the React body
+ * through the subscribe/isOpen face (the same face the entry row's chevron
+ * and highlight read).
+ * @module @linxin666/dsh-usage/client/sidebar-panel-mount
+ */
+
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { subscribeBodyInvalidations } from './body-mutations.ts'
+import { UsageSidebarPanel, type OpenStateSource } from './UsageSidebarPanel.tsx'
+import type { UsageStoreInstance } from './usage-store.ts'
+import { ENTRY_SELECTOR } from './sidebar-entry.ts'
+
+/** localStorage key holding the collapsed flag ('1' = collapsed). */
+export const COLLAPSED_STORAGE_KEY = 'dsh-usage.sidebar.collapsed'
+
+/** Read the persisted collapsed flag (absent = expanded). */
+function readCollapsed(): boolean {
+  try {
+    return window.localStorage.getItem(COLLAPSED_STORAGE_KEY) === '1'
+  } catch {
+    // Storage can be unavailable (privacy modes); the panel stays expanded.
+    return false
+  }
+}
+
+/** Persist the collapsed flag; storage failures keep the session state. */
+function writeCollapsed(collapsed: boolean): void {
+  try {
+    window.localStorage.setItem(COLLAPSED_STORAGE_KEY, collapsed ? '1' : '0')
+  } catch {
+    // Storage unavailable: the state still flips for this session.
+  }
+}
+
+/** Panel inputs the mount forwards into the React tree. */
+export interface UsagePanelMountProps {
+  store: UsageStoreInstance
+  /** Fetch one overview now. */
+  poll: () => void
+}
+
+/** Mounted panel controller: the entry row drives the toggle and mirrors the state. */
+export interface UsagePanelMount {
+  /** Whether the panel body is currently expanded. */
+  isOpen(): boolean
+  /** Subscribe to open/collapse changes (the entry row's chevron and highlight). */
+  subscribe(listener: () => void): () => void
+  /** Flip the open state, persist it, and notify subscribers. */
+  toggle(): void
+  /** Unmount the panel and remove its container. */
+  dispose(): void
+}
+
+/**
+ * Mount the sidebar usage panel below its entry row.
+ * @param props - the store and poll callback of the apply body.
+ * @returns the panel controller.
+ */
+export function mountUsagePanel(props: UsagePanelMountProps): UsagePanelMount {
+  const container = document.createElement('div')
+  container.setAttribute('data-dsh-usage-view', '')
+
+  const listeners = new Set<() => void>()
+  let open = !readCollapsed()
+  const emit = (): void => { for (const listener of [...listeners]) listener() }
+  const openState: OpenStateSource = {
+    subscribe: (listener: () => void) => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    isOpen: () => open,
+  }
+
+  const root: Root = createRoot(container)
+  root.render(createElement(UsageSidebarPanel, { store: props.store, poll: props.poll, open: openState }))
+
+  /** Keep the panel as the row directly after the usage entry. */
+  const place = (): void => {
+    const entry = document.querySelector<HTMLElement>(ENTRY_SELECTOR)
+    if (entry === null || entry.parentElement === null) return
+    if (container.parentElement !== entry.parentElement || entry.nextElementSibling !== container) {
+      entry.parentElement.insertBefore(container, entry.nextElementSibling)
+    }
+  }
+  place()
+  const unsubscribeBody = subscribeBodyInvalidations(place)
+
+  return {
+    isOpen: () => open,
+    subscribe: openState.subscribe,
+    toggle: () => {
+      open = !open
+      writeCollapsed(!open)
+      emit()
+    },
+    dispose: () => {
+      unsubscribeBody()
+      root.unmount()
+      container.remove()
+      listeners.clear()
+    },
+  }
+}