@lijian-ui/dsh-file-manager 0.1.20

package/src/client/locales.ts

@@ -0,0 +1,247 @@
+/**
+ * Locale strings for the panel surfaces (zh/en). The client registers the
+ * dictionary through the locale service like the sibling plugins; copy is
+ * deliberately short and technical.
+ * @module dsh-filemgr/client/locales
+ */
+
+const zh = {
+  'explorer.tabs.files': '文件',
+  'explorer.tabs.changes': '变更',
+  'explorer.search.placeholder': '按文件名搜索',
+  'explorer.search.searching': '搜索中…',
+  'explorer.search.empty': '没有匹配的文件',
+  'explorer.search.error': '搜索失败',
+  'explorer.search.truncated': '结果过多，仅显示前 {count} 条',
+  'explorer.tree.empty': '项目为空',
+  'explorer.collapse': '收起面板',
+  'explorer.expand': '展开面板',
+  'explorer.maximize': '最大化文件面板',
+  'explorer.restore': '还原面板',
+  'explorer.openPreview': '打开预览',
+  'explorer.drag.dropHint': '松手插入文件路径',
+  'scm.repositories': '存储库',
+  'scm.changes': '变更',
+  'scm.staged': '已暂存',
+  'scm.unstaged': '变更',
+  'scm.untracked': '未跟踪',
+  'scm.conflicted': '冲突',
+  'scm.stage': '暂存',
+  'scm.unstage': '取消暂存',
+  'scm.discard': '放弃更改',
+  'scm.stageAll': '全部暂存',
+  'scm.discardAll': '全部放弃',
+  'scm.empty': '没有更改',
+  'scm.notRepo': '当前目录不是 git 仓库',
+  'scm.gitMissing': '未检测到 git，请先安装 git 后重试',
+  'scm.loading': '读取状态中…',
+  'scm.failed': '操作失败',
+  'scm.viewList': '列表视图',
+  'scm.viewTree': '树视图',
+  'scm.discardConfirmTracked': '放弃对 {count} 个文件的更改？此操作不可恢复。',
+  'scm.discardConfirmUntracked': '删除 {count} 个未跟踪文件？此操作不可恢复。',
+  'preview.noTabs': '没有打开的预览',
+  'preview.newUrlTab': '新建 URL 预览',
+  'preview.collapsePanel': '收起预览面板',
+  'preview.maximize': '最大化预览面板',
+  'preview.restore': '还原面板',
+  'preview.source': '源码',
+  'preview.preview': '预览',
+  'preview.editor': '编辑器',
+  'preview.split': '分屏',
+  'preview.refresh': '刷新',
+  'preview.refresh.updated': '文件已在磁盘更新',
+  'preview.save': '保存',
+  'preview.download': '下载',
+  'preview.copyCode': '复制代码',
+  'preview.copyCodeDone': '已复制',
+  'preview.openExternal': '在系统应用中打开',
+  'preview.dirty': '未保存的更改',
+  'preview.closeLeft': '关闭左侧',
+  'preview.closeRight': '关闭右侧',
+  'preview.closeOthers': '关闭其他',
+  'preview.closeAll': '关闭全部',
+  'preview.closeConfirmTitle': '关闭未保存的标签页',
+  'preview.closeConfirmBody': '{count} 个标签页有未保存的更改，关闭将丢失这些更改。',
+  'preview.saved': '已保存',
+  'preview.saveConflict': '文件已在磁盘上被修改，保存冲突：请刷新后重试',
+  'preview.errorOversized': '文件过大，仅加载前 80,000 字符',
+  'preview.unsupported': '此格式暂不支持预览',
+  'preview.downloadHint': '可在系统应用中打开或下载查看',
+  'preview.url.placeholder': '输入网址，回车打开',
+  'preview.url.hint': '按 Esc 还原',
+  'common.cancel': '取消',
+  'common.confirm': '确定',
+  'common.close': '关闭',
+  'common.delete': '删除',
+  'common.copyPath': '复制路径',
+  'common.copied': '已复制',
+  'explorer.menu.copyPath': '复制路径',
+  'explorer.menu.copyName': '复制名称',
+  'explorer.menu.reveal': '在文件管理器中显示',
+  'explorer.menu.openWithDefault': '用默认应用打开',
+  'explorer.menu.rename': '重命名',
+  'explorer.menu.newFile': '新建文件',
+  'explorer.menu.newFolder': '新建文件夹',
+  'explorer.menu.delete': '删除',
+  'explorer.rename.title': '重命名',
+  'explorer.newFile.title': '新建文件',
+  'explorer.newFolder.title': '新建文件夹',
+  'explorer.deleteConfirmTitle': '删除确认',
+  'explorer.deleteConfirmBody': '确定要删除「{name}」吗？此操作不可恢复。',
+  'explorer.opFailed': '操作失败',
+  'explorer.refToInput': '引用到输入框',
+  'settings.title': '右侧面板',
+  'settings.description': 'Explorer / Preview 与 SCM 变更面板的总开关。',
+  'settings.enabled': '启用右侧面板',
+  'settings.enabledHint': '关闭后不再挂载右侧文件树与预览列、不显示浮动展开按钮、不注册 /filemgr 路由，也不做工作区监视与 git 轮询；聚合包其余插件不受影响。',
+  'settings.overridden': '已覆盖',
+  'settings.reset': '恢复默认',
+  'settings.notExposed': '当前 DSH 版本未向设置页暴露本插件的配置命名空间，表单不可用。可编辑 ~/.dsh/settings.yaml 直接配置，或为 dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES 白名单补充本命名空间后重启。',
+  'settings.readOnly': '当前部署的设置只读。',
+  'settings.inherit': '继承',
+  'settings.on': '开',
+  'settings.off': '关',
+  'settings.expand': '展开设置',
+  'settings.collapse': '收起设置',
+  'settings.save': '保存',
+  'settings.saving': '保存中…',
+  'settings.discard': '放弃',
+  'settings.unsaved': '未保存',
+  'settings.saveFailed': '部署未接受这些值，已保留供你修改。',
+  'settings.invalidNumber': '请输入数字，留空则使用默认值。',
+} as const
+
+const en: Record<keyof typeof zh, string> = {
+  'explorer.tabs.files': 'Files',
+  'explorer.tabs.changes': 'Changes',
+  'explorer.search.placeholder': 'Search file names',
+  'explorer.search.searching': 'Searching…',
+  'explorer.search.empty': 'No matching files',
+  'explorer.search.error': 'Search failed',
+  'explorer.search.truncated': 'Too many results, showing first {count}',
+  'explorer.tree.empty': 'The project is empty',
+  'explorer.collapse': 'Collapse panel',
+  'explorer.expand': 'Expand panel',
+  'explorer.maximize': 'Maximize files panel',
+  'explorer.restore': 'Restore panel',
+  'explorer.openPreview': 'Open preview',
+  'explorer.drag.dropHint': 'Release to insert the file path',
+  'scm.repositories': 'Repositories',
+  'scm.changes': 'Changes',
+  'scm.staged': 'Staged',
+  'scm.unstaged': 'Changes',
+  'scm.untracked': 'Untracked',
+  'scm.conflicted': 'Conflict',
+  'scm.stage': 'Stage',
+  'scm.unstage': 'Unstage',
+  'scm.discard': 'Discard',
+  'scm.stageAll': 'Stage all',
+  'scm.discardAll': 'Discard all',
+  'scm.empty': 'No changes',
+  'scm.notRepo': 'Not a git repository',
+  'scm.gitMissing': 'Git is not installed. Install git and reload to use the changes panel',
+  'scm.loading': 'Loading status…',
+  'scm.failed': 'Operation failed',
+  'scm.viewList': 'List view',
+  'scm.viewTree': 'Tree view',
+  'scm.discardConfirmTracked': 'Discard changes in {count} files? This cannot be undone.',
+  'scm.discardConfirmUntracked': 'Delete {count} untracked files? This cannot be undone.',
+  'preview.noTabs': 'No open previews',
+  'preview.newUrlTab': 'New URL preview',
+  'preview.collapsePanel': 'Collapse preview panel',
+  'preview.maximize': 'Maximize preview panel',
+  'preview.restore': 'Restore panel',
+  'preview.source': 'Source',
+  'preview.preview': 'Preview',
+  'preview.editor': 'Editor',
+  'preview.split': 'Split',
+  'preview.refresh': 'Refresh',
+  'preview.refresh.updated': 'File updated on disk',
+  'preview.save': 'Save',
+  'preview.download': 'Download',
+  'preview.copyCode': 'Copy code',
+  'preview.copyCodeDone': 'Copied',
+  'preview.openExternal': 'Open in system app',
+  'preview.dirty': 'Unsaved changes',
+  'preview.closeLeft': 'Close left',
+  'preview.closeRight': 'Close right',
+  'preview.closeOthers': 'Close others',
+  'preview.closeAll': 'Close all',
+  'preview.closeConfirmTitle': 'Close unsaved tabs',
+  'preview.closeConfirmBody': '{count} tabs have unsaved changes. Closing will lose them.',
+  'preview.saved': 'Saved',
+  'preview.saveConflict': 'File changed on disk. Save conflict: refresh and retry',
+  'preview.errorOversized': 'File too large, only the first 80,000 characters loaded',
+  'preview.unsupported': 'Preview not supported for this format',
+  'preview.downloadHint': 'Open in a system app or download to view',
+  'preview.url.placeholder': 'Enter a URL and press Enter',
+  'preview.url.hint': 'Press Esc to revert',
+  'common.cancel': 'Cancel',
+  'common.confirm': 'OK',
+  'common.close': 'Close',
+  'common.delete': 'Delete',
+  'common.copyPath': 'Copy path',
+  'common.copied': 'Copied',
+  'explorer.menu.copyPath': 'Copy path',
+  'explorer.menu.copyName': 'Copy name',
+  'explorer.menu.reveal': 'Reveal in file manager',
+  'explorer.menu.openWithDefault': 'Open with default app',
+  'explorer.menu.rename': 'Rename',
+  'explorer.menu.newFile': 'New file',
+  'explorer.menu.newFolder': 'New folder',
+  'explorer.menu.delete': 'Delete',
+  'explorer.rename.title': 'Rename',
+  'explorer.newFile.title': 'New file',
+  'explorer.newFolder.title': 'New folder',
+  'explorer.deleteConfirmTitle': 'Confirm delete',
+  'explorer.deleteConfirmBody': 'Delete "{name}"? This cannot be undone.',
+  'explorer.opFailed': 'Operation failed',
+  'explorer.refToInput': 'Reference to input',
+  'settings.title': 'Right panel',
+  'settings.description': 'Master switch for the Explorer / Preview and SCM changes panels.',
+  'settings.enabled': 'Enable the right panel',
+  'settings.enabledHint': 'When off, the Explorer and Preview columns are not mounted, the floating expand button disappears, the /filemgr routes are not registered, and workspace watching and git polling stop. The rest of the family bundle is unaffected.',
+  'settings.overridden': 'Overridden',
+  'settings.reset': 'Reset',
+  'settings.notExposed': 'This DSH version does not expose this plugin\'s settings namespace; the form is unavailable. Edit ~/.dsh/settings.yaml directly, or add the namespace to the WEB_SETTINGS_NAMESPACES allowlist of dsh-host-apiproxy and restart.',
+  'settings.readOnly': 'Settings are read-only in this deployment.',
+  'settings.inherit': 'Inherit',
+  'settings.on': 'On',
+  'settings.off': 'Off',
+  'settings.expand': 'Expand settings',
+  'settings.collapse': 'Collapse settings',
+  'settings.save': 'Save',
+  'settings.saving': 'Saving…',
+  'settings.discard': 'Discard',
+  'settings.unsaved': 'Unsaved',
+  'settings.saveFailed': 'The deployment rejected these values; your edits are kept.',
+  'settings.invalidNumber': 'Enter a number, or leave it empty to use the default.',
+}
+
+export type FileManagerPanelKey = keyof typeof zh
+
+/** The dictionary namespace this plugin owns. */
+export const NS = 'filemgr'
+
+/** Format one copy string with {name} placeholders. */
+export function format(template: string, params: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (_, key: string) => String(params[key] ?? `{${key}}`))
+}
+
+/** Simple dictionary access (zh/en by a global flag the client sets). */
+export const dictionaries: Record<'zh' | 'en', Record<FileManagerPanelKey, string>> = { zh, en }
+
+let currentLanguage: 'zh' | 'en' = 'zh'
+
+/** Set the active language (the client mirrors the locale service). */
+export function setLanguage(language: string): void {
+  currentLanguage = language === 'en' ? 'en' : 'zh'
+}
+
+/** Translate one key with optional params. */
+export function t(key: FileManagerPanelKey, params?: Record<string, string | number>): string {
+  const table = dictionaries[currentLanguage] ?? zh
+  const template = table[key] ?? zh[key]
+  return params === undefined ? template : format(template, params)
+}

package/src/client/maximize.ts

@@ -0,0 +1,34 @@
+/**
+ * Maximize-mode geometry (issue #315): when a panel is maximized the layout
+ * controller rewrites the frame grid so the target column takes the whole
+ * row (sidebar, details, chat and the other panel collapse to 0px tracks —
+ * everything stays mounted, nothing unmounts). On narrow viewports the
+ * maximized column instead leaves the grid and renders as a fixed
+ * full-screen overlay (mobile-friendly full-screen mode), so the shell's
+ * own narrow layout stays untouched behind it.
+ * @module dsh-filemgr/client/maximize
+ */
+
+import type { MaximizeTarget } from './store.ts'
+
+/** Below this available row width the maximized panel renders as a fixed
+ * full-screen overlay instead of a grid takeover. */
+export const MAXIMIZE_OVERLAY_BREAKPOINT_PX = 640
+
+/**
+ * The five grid tracks while one panel is maximized: shell sidebar, chat,
+ * shell details and the other panel all collapse to 0px; the target column
+ * takes the whole measured frame width. Tracks are the same string shape the
+ * shell's own inline style uses (px + fr), so nothing else needs to change.
+ */
+export function maximizedGridTracks(target: MaximizeTarget, frameWidth: number): string {
+  const wide = `${Math.max(0, Math.round(frameWidth))}px`
+  return target === 'explorer'
+    ? `0px 0px 0px 0px ${wide}`
+    : `0px 0px 0px ${wide} 0px`
+}
+
+/** Whether the maximized panel should render as a fixed full-screen overlay. */
+export function maximizedOverlay(availableWidth: number): boolean {
+  return availableWidth > 0 && availableWidth < MAXIMIZE_OVERLAY_BREAKPOINT_PX
+}

package/src/client/mount.tsx

@@ -0,0 +1,74 @@
+/**
+ * DOM mounting: two React roots rendered into the panel columns the layout
+ * controller appends to the frame grid. The roots wait for their columns
+ * (the shell mounts asynchronously), and everything is wrapped so a DOM
+ * failure degrades the panels, never the GUI boot.
+ * @module dsh-filemgr/client/mount
+ */
+
+import { createRoot, type Root } from 'react-dom/client'
+import type { PanelStores } from './store.ts'
+import { ExplorerPanel } from './components/ExplorerPanel.tsx'
+import { PreviewPanel } from './preview/PreviewPanel.tsx'
+import type { FileReferenceSelection } from './preview/selection.ts'
+
+const EXPLORER_COL_SELECTOR = '[data-filemgr-explorer-col]'
+const PREVIEW_COL_SELECTOR = '[data-filemgr-preview-col]'
+
+/** Wait for one selector (the shell/frame mounts after boot settlement). */
+function waitForElement(selector: string, onFound: (el: HTMLElement) => void): () => void {
+  let disposed = false
+  let observer: MutationObserver | undefined
+  const tryFind = (): void => {
+    if (disposed) return
+    const el = document.querySelector<HTMLElement>(selector)
+    if (el !== null) {
+      observer?.disconnect()
+      onFound(el)
+    }
+  }
+  observer = new MutationObserver(() => { tryFind() })
+  observer.observe(document.body, { childList: true, subtree: true })
+  tryFind()
+  return () => {
+    disposed = true
+    observer?.disconnect()
+  }
+}
+
+/**
+ * Mount both panel roots.
+ * @param stores - the panel store bundle.
+ * @param onToggleExplorer - collapse toggle (owned by the layout controller).
+ * @param onReference - insert a file-reference chip into the draft for a file
+ *   (the Explorer row @-reference button); folders should call a different
+ *   helper because the chip has no line concept for them.
+ * @param onAddFileReference - insert a file-reference chip into the draft for
+ *   a preview selection (path + start/end line).
+ * @returns a disposer unmounting both trees.
+ */
+export function mountPanels(
+  stores: PanelStores,
+  onToggleExplorer: () => void,
+  onReference: (path: string, isDir: boolean) => void,
+  onAddFileReference: (selection: FileReferenceSelection) => boolean,
+): () => void {
+  let explorerRoot: Root | undefined
+  let previewRoot: Root | undefined
+  const disposers: Array<() => void> = []
+
+  disposers.push(waitForElement(EXPLORER_COL_SELECTOR, (el) => {
+    explorerRoot = createRoot(el)
+    explorerRoot.render(<ExplorerPanel stores={stores} onToggleCollapse={onToggleExplorer} onReference={onReference} />)
+  }))
+  disposers.push(waitForElement(PREVIEW_COL_SELECTOR, (el) => {
+    previewRoot = createRoot(el)
+    previewRoot.render(<PreviewPanel stores={stores} onAddFileReference={onAddFileReference} />)
+  }))
+
+  return () => {
+    for (const dispose of disposers) dispose()
+    explorerRoot?.unmount()
+    previewRoot?.unmount()
+  }
+}

package/src/client/persist.ts

@@ -0,0 +1,194 @@
+/**
+ * Persistence helpers for panel preferences: range-validated reads (invalid
+ * stored values fall back to defaults — a broken or hand-edited value must
+ * never produce a 0px or NaN panel), debounced writes, and the LRU registry
+ * for preview scopes (at most 12 scopes; the oldest savedAt evicts).
+ *
+ * Keys follow the FileManager contract verbatim:
+ *   chat-workspace-width-px, chat-preview-width-px, preview-panel-split-ratio,
+ *   project-panel-collapse:<root>, explorer-ui:<root>, scm-ui:<root>,
+ *   preview-ui:<root>.
+ * @module dsh-filemgr/client/persist
+ */
+
+/** Read a stored number, validating it against [min, max]; fallback otherwise. */
+export function readStoredNumber(key: string, min: number, max: number, fallback: number): number {
+  try {
+    const raw = localStorage.getItem(key)
+    if (raw === null) return fallback
+    const value = Number(raw)
+    if (!Number.isFinite(value)) return fallback
+    if (value < min || value > max) return fallback
+    return value
+  } catch {
+    return fallback
+  }
+}
+
+/** Write a number if it differs from the stored value (avoids churn). */
+export function writeStoredNumber(key: string, value: number): void {
+  try {
+    const raw = String(Math.round(value))
+    if (localStorage.getItem(key) === raw) return
+    localStorage.setItem(key, raw)
+  } catch {
+    // persistence is best-effort; the panel still works
+  }
+}
+
+/**
+ * A single debounce pipeline used by the stores for its search and persist
+ * timers: coalesces rapid schedules into one trailing run (the latest fn wins).
+ * `flush` runs the pending fn immediately (pagehide/beforeunload), `dispose`
+ * cancels a pending schedule. Behavior is equivalent to the stores' previous
+ * hand-rolled setTimeout + clearTimeout pairs, just centralized.
+ */
+export interface Debounced {
+  /** Queue a fn; repeated calls before the delay replaces the pending fn. */
+  schedule: (fn: () => void) => void
+  /** Run the pending fn now and clear the timer. */
+  flush: () => void
+  /** Cancel the pending fn and timer. */
+  dispose: () => void
+}
+
+/** Create one debounced scheduler (default 150ms). */
+export function createDebounced(delayMs = 150): Debounced {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let pending: (() => void) | null = null
+  const flush = (): void => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+    const fn = pending
+    pending = null
+    if (fn !== null) fn()
+  }
+  return {
+    schedule(fn: () => void) {
+      pending = fn
+      // Reset on every schedule so the run trails the LAST change (the same
+      // trailing-edge semantics the stores' former clear+setTimeout had).
+      if (timer !== undefined) clearTimeout(timer)
+      timer = setTimeout(flush, delayMs)
+    },
+    flush,
+    dispose() {
+      if (timer !== undefined) clearTimeout(timer)
+      timer = undefined
+      pending = null
+    },
+  }
+}
+
+/** The preview-ui scope registry: keys, savedAt values, eviction. */
+export const PREVIEW_SCOPE_PREFIX = 'preview-ui:'
+/** LRU cap on distinct preview scopes. */
+export const PREVIEW_SCOPE_CAP = 12
+
+/**
+ * Collect every stored key under a prefix. localStorage has no prefix index,
+ * so the whole store is swept once, then filtered to the package's own keys
+ * — enumeration is never interleaved with removal (removals would shift the
+ * indices mid-loop and skip entries).
+ */
+function listStoredKeysByPrefix(prefix: string): string[] {
+  const keys: string[] = []
+  try {
+    for (let i = 0; i < localStorage.length; i += 1) {
+      const key = localStorage.key(i)
+      if (key !== null && key.startsWith(prefix)) keys.push(key)
+    }
+  } catch {
+    return []
+  }
+  return keys
+}
+
+/**
+ * Precisely delete every stored key under a prefix. Only this package's own
+ * prefixed keys are removed — foreign-application keys are never touched,
+ * replacing the former all-at-once `localStorage.clear()` sweep.
+ */
+export function removeStoredByPrefix(prefix: string): number {
+  const keys = listStoredKeysByPrefix(prefix)
+  let removed = 0
+  for (const key of keys) {
+    try {
+      localStorage.removeItem(key)
+      removed += 1
+    } catch {
+      // best-effort; a storage failure does not abort the rest
+    }
+  }
+  return removed
+}
+
+/** All stored preview scopes with their savedAt timestamps, oldest first. */
+export function listPreviewScopes(): Array<{ root: string; savedAt: number }> {
+  const out: Array<{ root: string; savedAt: number }> = []
+  for (const key of listStoredKeysByPrefix(PREVIEW_SCOPE_PREFIX)) {
+    const root = key.slice(PREVIEW_SCOPE_PREFIX.length)
+    let savedAt = 0
+    try {
+      const raw = localStorage.getItem(key)
+      if (raw !== null) {
+        const parsed = JSON.parse(raw) as { savedAt?: unknown }
+        if (typeof parsed.savedAt === 'number') savedAt = parsed.savedAt
+      }
+    } catch {
+      savedAt = 0
+    }
+    out.push({ root, savedAt })
+  }
+  out.sort((a, b) => a.savedAt - b.savedAt)
+  return out
+}
+
+/** Evict the oldest scopes beyond the cap. */
+export function evictPreviewScopes(keep: string): void {
+  // Cheap pre-check first: enumerate keys only (no JSON.parse, no sort).
+  // Writes far below the cap — the common case — return here instead of
+  // parsing and sorting every stored preview scope on each persist.
+  if (listStoredKeysByPrefix(PREVIEW_SCOPE_PREFIX).length <= PREVIEW_SCOPE_CAP) return
+  const scopes = listPreviewScopes().filter((scope) => scope.root !== keep)
+  let excess = scopes.length - (PREVIEW_SCOPE_CAP - 1)
+  for (const scope of scopes) {
+    if (excess <= 0) break
+    try {
+      localStorage.removeItem(`${PREVIEW_SCOPE_PREFIX}${scope.root}`)
+    } catch {
+      // best-effort
+    }
+    excess -= 1
+  }
+}
+
+/** Serialize a JSON value with a size guard (quota failures degrade silently). */
+export function writeJson(key: string, value: unknown): boolean {
+  try {
+    localStorage.setItem(key, JSON.stringify(value))
+    return true
+  } catch {
+    try {
+      localStorage.removeItem(key)
+    } catch {
+      // storage unavailable entirely
+    }
+    return false
+  }
+}
+
+/** Parse a stored JSON value; fallback on any failure. */
+export function readJson<T>(key: string, fallback: T): T {
+  try {
+    const raw = localStorage.getItem(key)
+    if (raw === null) return fallback
+    const parsed = JSON.parse(raw) as unknown
+    // JSON.parse('null') yields null without throwing; descending callers
+    // expect an object and would throw on null/primitive, killing their effect.
+    if (parsed === null || typeof parsed !== 'object') return fallback
+    return parsed as T
+  } catch {
+    return fallback
+  }
+}