@grapecity-software/dsh-spreadjs-editor 0.1.0

package/src/client/SpreadsheetHost.tsx

@@ -0,0 +1,420 @@
+/**
+ * SpreadJS Designer host: mounts the full designer into the generic editor
+ * panel and loads workspace files through the /spreadjs file bridge.
+ *
+ * The browser bundle imports the current @grapecity-software 19.x plugin set:
+ * core sheets + IO, Chinese resources, charts/shapes/slicers/sparklines,
+ * print/pdf/barcode/formula panel, PivotTable, TableSheet, data charts,
+ * GanttSheet, ReportSheet, and the Designer itself.
+ */
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react'
+import * as GC from '@grapecity-software/spread-sheets'
+import * as ExcelIO from '@grapecity-software/spread-excelio'
+import '@grapecity-software/spread-sheets-io'
+import '@grapecity-software/spread-sheets-resources-zh'
+import '@grapecity-software/spread-sheets-shapes'
+import '@grapecity-software/spread-sheets-charts'
+import '@grapecity-software/spread-sheets-slicers'
+import '@grapecity-software/spread-sheets-sparklines'
+import '@grapecity-software/spread-sheets-print'
+import '@grapecity-software/spread-sheets-pdf'
+import '@grapecity-software/spread-sheets-barcode'
+import '@grapecity-software/spread-sheets-formula-panel'
+import '@grapecity-software/spread-sheets-pivot-addon'
+import '@grapecity-software/spread-sheets-tablesheet'
+import '@grapecity-software/spread-sheets-datacharts-addon'
+import '@grapecity-software/spread-sheets-ganttsheet'
+import '@grapecity-software/spread-sheets-reportsheet-addon'
+import '@grapecity-software/spread-sheets-languagepackages'
+import '@grapecity-software/spread-sheets-designer-resources-cn'
+import * as GCDesigner from '@grapecity-software/spread-sheets-designer'
+
+export type ExportFormat = 'xlsx' | 'sjs' | 'ssjson' | 'csv'
+export type StatusTone = 'idle' | 'busy' | 'error'
+
+export interface SpreadsheetHostHandle {
+  save: () => Promise<void>
+  exportAs: (format: ExportFormat) => Promise<void>
+  newWorkbook: () => void
+}
+
+/** Result of one write-back operation. */
+export type SpreadsheetSaveResult = 'saved' | 'download'
+
+/** File access seam: the host panel may use /spreadjs or /sidebar routes. */
+export interface SpreadsheetFileAccess {
+  fileUrl(path: string): string
+  save(blob: Blob, path: string): Promise<SpreadsheetSaveResult>
+}
+
+export interface SpreadsheetHostProps {
+  /** Absolute path of the file to open (undefined = nothing). */
+  filePath: string | undefined
+  /** SpreadJS license key from /spreadjs/api/config. */
+  licenseKey: string
+  /** Whether the host config fetch has completed. */
+  ready: boolean
+  /** Concrete read/write access chosen by the active adapter. */
+  fileAccess: SpreadsheetFileAccess
+  onStatus: (status: string, tone?: StatusTone) => void
+  onLoadingChange: (loading: boolean) => void
+  onNewWorkbook: () => void
+}
+
+type LoadStatus = { kind: 'idle' } | { kind: 'loading' } | { kind: 'error'; message: string }
+
+interface DesignerLike {
+  getWorkbook(): any
+  setWorkbook(spread: any): void
+  destroy?(): void
+}
+
+interface DesignerNamespace {
+  Designer?: new (host: HTMLDivElement, config?: unknown, spread?: unknown, spreadOptions?: unknown) => DesignerLike
+  DefaultConfig?: unknown
+  LicenseKey?: string
+  setTheme?(theme: Record<string, string | undefined> | null): void
+}
+
+function basename(path: string): string {
+  return path.split(/[\\/]/).pop() ?? path
+}
+
+function extname(path: string): string {
+  const name = basename(path)
+  const idx = name.lastIndexOf('.')
+  return idx >= 0 ? name.slice(idx).toLowerCase() : ''
+}
+
+function replaceExt(path: string, ext: string): string {
+  const current = extname(path)
+  const base = current === '' ? path : path.slice(0, path.length - current.length)
+  return `${base}.${ext}`
+}
+
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = filename
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+function designerNamespace(): DesignerNamespace | undefined {
+  const designer = GCDesigner as unknown as { Spread?: { Sheets?: { Designer?: DesignerNamespace } } }
+  if (designer.Spread?.Sheets?.Designer !== undefined) return designer.Spread.Sheets.Designer
+  const gc = GC as unknown as { Spread?: { Sheets?: { Designer?: DesignerNamespace } } }
+  return gc.Spread?.Sheets?.Designer
+}
+
+function cloneDefaultDesignerConfig(): unknown {
+  const ns = designerNamespace()
+  if (ns?.DefaultConfig === undefined) return undefined
+  try {
+    return JSON.parse(JSON.stringify(ns.DefaultConfig))
+  } catch {
+    return undefined
+  }
+}
+
+/** Dark palette for the Designer chrome (ribbon, tabs, dialogs, panels). */
+const DARK_THEME: Record<string, string | undefined> = {
+  colorForeground: '#e8eaed',
+  colorForegroundDisabled: '#7a808a',
+  colorBackground: '#1e2227',
+  colorBackgroundHover: '#2a2f36',
+  colorBackgroundSelected: '#33383f',
+  colorBackgroundDisabled: '#262a30',
+  colorBackground2: '#171a1f',
+  colorBackground2Hover: '#23272d',
+  colorBackground2Selected: '#2c3138',
+  colorBrandForeground: '#ffffff',
+  colorBrandBackground: '#3b6ef6',
+  colorBrandBackgroundHover: '#2f5ce0',
+  colorBrandBackgroundSelected: '#2748b8',
+  colorStroke: '#3a414a',
+  colorStrokeHover: '#4b5563',
+  colorStrokeSelected: '#5a6470',
+  colorStrokeDisabled: '#2c3036',
+  borderRadiusM: '4px',
+  borderRadiusL: '6px',
+  borderRadiusXL: '8px',
+  shadow4: '0 1px 2px rgba(0, 0, 0, 0.55)',
+  shadow8: '0 2px 6px rgba(0, 0, 0, 0.5)',
+}
+
+function applyDesignerTheme(): void {
+  const ns = designerNamespace()
+  if (ns?.setTheme === undefined) return
+  const dark = typeof window !== 'undefined'
+    && typeof window.matchMedia === 'function'
+    && window.matchMedia('(prefers-color-scheme: dark)').matches === true
+  try {
+    ns.setTheme(dark ? DARK_THEME : null)
+  } catch {
+    // Theming is cosmetic; never block the editor for a palette failure.
+  }
+}
+
+export function workbookFileType(path: string): GC.Spread.Sheets.FileType {
+  const ext = extname(path)
+  if (ext === '.xlsx' || ext === '.xlsm') return GC.Spread.Sheets.FileType.excel
+  if (ext === '.csv') return GC.Spread.Sheets.FileType.csv
+  return GC.Spread.Sheets.FileType.ssjson
+}
+
+export function exportFileType(format: ExportFormat): GC.Spread.Sheets.FileType {
+  if (format === 'xlsx') return GC.Spread.Sheets.FileType.excel
+  if (format === 'csv') return GC.Spread.Sheets.FileType.csv
+  return GC.Spread.Sheets.FileType.ssjson
+}
+
+interface ExcelIoLike {
+  open(
+    file: File,
+    success: (json: object) => void,
+    error: (error?: { errorMessage?: string }) => void,
+  ): void
+}
+
+function excelJson(file: File): Promise<object> {
+  const IO = (ExcelIO as unknown as { IO?: new () => ExcelIoLike }).IO
+  if (IO === undefined) return Promise.reject(new Error('spread-excelio IO is unavailable'))
+  return new Promise((resolve, reject) => {
+    const io = new IO()
+    io.open(file, json => resolve(json), error => {
+      reject(new Error(error?.errorMessage ?? 'excel import failed'))
+    })
+  })
+}
+
+async function loadIntoWorkbook(
+  spread: any,
+  file: File,
+  path: string,
+): Promise<void> {
+  const ext = extname(path)
+  if (ext === '.xlsx' || ext === '.xlsm') {
+    // ExcelIO is the proven path for xlsx/xlsm: parse to workbook JSON, then
+    // fromJSON into a fresh workbook before handing it to the Designer.
+    spread.fromJSON(await excelJson(file))
+    return
+  }
+  if (ext === '.ssjson') {
+    spread.fromJSON(JSON.parse(await file.text()) as object)
+    return
+  }
+  await new Promise<void>((resolve, reject) => {
+    const fail = (error: unknown) => {
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
+    if (ext === '.sjs') {
+      spread.open(file, resolve, fail)
+      return
+    }
+    spread.import(file, resolve, fail, {
+      fileType: workbookFileType(path),
+      includeBindingSource: true,
+    })
+  })
+}
+
+function resetWorkbook(spread: any): void {
+  const count = spread.getSheetCount()
+  for (let i = count - 1; i > 0; i--) spread.removeSheet(i)
+  const sheet = spread.getSheet(0)
+  if (sheet !== undefined) {
+    sheet.reset()
+    sheet.setRowCount(200)
+    sheet.setColumnCount(20)
+  }
+}
+
+function workbookBlob(spread: any, path: string, format?: ExportFormat): Promise<Blob> {
+  const target = format === undefined && extname(path) === '.sjs'
+    ? 'sjs'
+    : format === undefined
+      ? workbookFileType(path)
+      : exportFileType(format)
+  return new Promise((resolve, reject) => {
+    const fail = (error: unknown) => {
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
+    if (target === 'sjs') {
+      spread.save(resolve, fail, { includeBindingSource: true })
+      return
+    }
+    spread.export(resolve, fail, {
+      fileType: target,
+      includeBindingSource: true,
+    })
+  })
+}
+
+export const SpreadsheetHost = forwardRef<SpreadsheetHostHandle, SpreadsheetHostProps>(
+  function SpreadsheetHost({ filePath, licenseKey, ready, fileAccess, onStatus, onLoadingChange, onNewWorkbook }, ref) {
+    const hostRef = useRef<HTMLDivElement | null>(null)
+    const designerRef = useRef<DesignerLike | null>(null)
+    const loadSeqRef = useRef(0)
+    const pathRef = useRef(filePath)
+    const [status, setStatus] = useState<LoadStatus>({ kind: 'idle' })
+
+    pathRef.current = filePath
+
+    // SpreadJS and Designer require separate license keys and both must be set
+    // before the designer is constructed.
+    useEffect(() => {
+      if (!ready || licenseKey === '') return
+      const sheets = (GC as any).Spread?.Sheets
+      if (sheets !== undefined) sheets.LicenseKey = licenseKey
+      const ns = designerNamespace()
+      if (ns !== undefined) ns.LicenseKey = licenseKey
+    }, [licenseKey, ready])
+
+    // Follow the OS light/dark preference for the Designer chrome. This runs
+    // before the Designer is constructed so the instance starts on the right
+    // palette, and keeps listening for live system theme changes.
+    useEffect(() => {
+      if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return
+      const mq = window.matchMedia('(prefers-color-scheme: dark)')
+      applyDesignerTheme()
+      const onChange = (): void => applyDesignerTheme()
+      if (typeof mq.addEventListener === 'function') mq.addEventListener('change', onChange)
+      else if (typeof mq.addListener === 'function') (mq as MediaQueryList & { addListener(cb: () => void): void }).addListener(onChange)
+      return () => {
+        if (typeof mq.removeEventListener === 'function') mq.removeEventListener('change', onChange)
+        else if (typeof mq.removeListener === 'function') (mq as MediaQueryList & { removeListener(cb: () => void): void }).removeListener(onChange)
+      }
+    }, [])
+
+    // Create / destroy the designer with the host element.
+    useEffect(() => {
+      const el = hostRef.current
+      const ns = designerNamespace()
+      if (!ready || el === null || ns?.Designer === undefined) return
+      const designer = new ns.Designer(el, cloneDefaultDesignerConfig())
+      const spread = designer.getWorkbook()
+      if (spread !== undefined) {
+        spread.options.tabStripVisible = true
+        spread.options.newTabVisible = true
+      }
+      designerRef.current = designer
+      return () => {
+        const current = designer.getWorkbook()
+        if (current !== undefined && typeof current.destroy === 'function') current.destroy()
+        if (typeof designer.destroy === 'function') designer.destroy()
+        designerRef.current = null
+      }
+    }, [ready])
+
+    // Load the selected file; a stale async result is dropped by seq. This must
+    // wait for `ready` because the Designer is created in a separate effect that
+    // runs only after the host config fetch completes.
+    useEffect(() => {
+      const designer = designerRef.current
+      if (!ready || designer === null || filePath === undefined || filePath === '') {
+        if (filePath === undefined || filePath === '') setStatus({ kind: 'idle' })
+        return
+      }
+      const seq = ++loadSeqRef.current
+      setStatus({ kind: 'loading' })
+      onLoadingChange(true)
+      onStatus(`Loading ${basename(filePath)}…`, 'busy')
+      void (async () => {
+        const response = await fetch(fileAccess.fileUrl(filePath))
+        if (!response.ok) {
+          const body = await response.json().catch(() => null) as { error?: string } | null
+          throw new Error(body?.error ?? `HTTP ${response.status}`)
+        }
+        const buffer = await response.arrayBuffer()
+        const name = basename(filePath)
+        const file = new File([buffer], name, { type: response.headers.get('content-type') ?? 'application/octet-stream' })
+        const spread = designer.getWorkbook()
+        if (spread === undefined) throw new Error('Designer workbook is not available')
+        spread.suspendPaint()
+        try {
+          await loadIntoWorkbook(spread, file, filePath)
+        } finally {
+          spread.resumePaint()
+        }
+        if (seq !== loadSeqRef.current) return
+        spread.refresh?.()
+      })().then(() => {
+        if (seq !== loadSeqRef.current) return
+        setStatus({ kind: 'idle' })
+        onLoadingChange(false)
+        onStatus(`Loaded ${basename(filePath)}`, 'idle')
+      }).catch((error: unknown) => {
+        if (seq !== loadSeqRef.current) return
+        const message = error instanceof Error ? error.message : String(error)
+        setStatus({ kind: 'error', message })
+        onLoadingChange(false)
+        onStatus(`Load failed: ${message}`, 'error')
+      })
+    }, [fileAccess, filePath, ready, onLoadingChange, onStatus])
+
+    async function save(): Promise<void> {
+      const designer = designerRef.current
+      const path = pathRef.current
+      if (designer === null || path === undefined || path === '') return
+      onLoadingChange(true)
+      onStatus(`Saving ${basename(path)}…`, 'busy')
+      try {
+        const blob = await workbookBlob(designer.getWorkbook(), path)
+        const result = await fileAccess.save(blob, path)
+        onStatus(
+          result === 'download' ? `Saved ${basename(path)} as download` : `Saved ${basename(path)}`,
+          'idle',
+        )
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        onStatus(`Save failed: ${message}`, 'error')
+      } finally {
+        onLoadingChange(false)
+      }
+    }
+
+    async function exportAs(format: ExportFormat): Promise<void> {
+      const designer = designerRef.current
+      if (designer === null) return
+      const path = pathRef.current ?? 'workbook.sjs'
+      const name = replaceExt(path, format)
+      onLoadingChange(true)
+      onStatus(`Exporting ${name}…`, 'busy')
+      try {
+        const blob = await workbookBlob(designer.getWorkbook(), path, format)
+        downloadBlob(blob, name)
+        onStatus(`Exported ${name}`, 'idle')
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        onStatus(`Export failed: ${message}`, 'error')
+      } finally {
+        onLoadingChange(false)
+      }
+    }
+
+    function newWorkbook(): void {
+      const designer = designerRef.current
+      if (designer === null) return
+      resetWorkbook(designer.getWorkbook())
+      loadSeqRef.current += 1
+      setStatus({ kind: 'idle' })
+      onNewWorkbook()
+      onStatus('New workbook', 'idle')
+    }
+
+    useImperativeHandle(ref, () => ({ save, exportAs, newWorkbook }), [onLoadingChange, onNewWorkbook, onStatus])
+
+    return (
+      <div className="dsh-spreadjs-host">
+        <div ref={hostRef} />
+        {filePath === undefined || filePath === '' ? (
+          <div className="dsh-spreadjs-empty">New workbook ready. Use Export to save a copy.</div>
+        ) : null}
+        {status.kind === 'loading' ? <div className="dsh-spreadjs-loading">Loading…</div> : null}
+        {status.kind === 'error' ? <div className="dsh-spreadjs-error">{status.message}</div> : null}
+      </div>
+    )
+  },
+)

package/src/client/SpreadsheetViewer.tsx

@@ -0,0 +1,92 @@
+/**
+ * BetterSidebar file viewer for SpreadJS workbooks.
+ *
+ * ui-all mounts dsh-better-sidebar; this component is registered through its
+ * `registerFileViewer` API. Files are read from the sidebar `/sidebar/file`
+ * media route and written back through `/sidebar/upload`, so the viewer works
+ * inside the active session's workspace without the generic web editor plugin.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { SpreadsheetHost, type SpreadsheetFileAccess, type StatusTone } from './SpreadsheetHost.tsx'
+import {
+  sidebarFileUrl,
+  sidebarUploadUrl,
+  type SidebarFileViewerProps,
+} from './better-sidebar.ts'
+
+interface ConfigResponse {
+  licenseKey: string
+}
+
+function basename(path: string): string {
+  return path.split(/[\\/]/).pop() ?? path
+}
+
+export function SpreadsheetViewer(props: SidebarFileViewerProps): React.JSX.Element {
+  const { scope, path } = props
+  const [licenseKey, setLicenseKey] = useState('')
+  const [configReady, setConfigReady] = useState(false)
+  const [status, setStatus] = useState('')
+  const [statusTone, setStatusTone] = useState<StatusTone>('idle')
+
+  useEffect(() => {
+    let alive = true
+    void fetch('/spreadjs/api/config')
+      .then(async response => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`)
+        return await response.json() as ConfigResponse
+      })
+      .then(config => {
+        if (!alive) return
+        setLicenseKey(config.licenseKey ?? '')
+        setConfigReady(true)
+      })
+      .catch(() => {
+        if (alive) setConfigReady(true)
+      })
+    return () => {
+      alive = false
+    }
+  }, [])
+
+  const fileAccess = useMemo<SpreadsheetFileAccess>(() => ({
+    fileUrl: (target) => sidebarFileUrl(scope, target),
+    save: async (blob, target) => {
+      const response = await fetch(sidebarUploadUrl(scope, target), {
+        method: 'POST',
+        body: blob,
+      })
+      if (!response.ok) {
+        const body = await response.json().catch(() => null) as { error?: { message?: string } } | null
+        throw new Error(body?.error?.message ?? `HTTP ${response.status}`)
+      }
+      return 'saved'
+    },
+  }), [scope.cwd, scope.sessionId])
+
+  const handleStatus = useCallback((next: string, tone: StatusTone = 'idle') => {
+    setStatus(next)
+    setStatusTone(tone)
+  }, [])
+
+  const noop = useCallback(() => {}, [])
+
+  return (
+    <div className="dsh-spreadjs-panel" role="region" aria-label={`SpreadJS: ${basename(path)}`}>
+      <div className="dsh-spreadjs-editor">
+        <SpreadsheetHost
+          filePath={path}
+          licenseKey={licenseKey}
+          ready={configReady}
+          fileAccess={fileAccess}
+          onStatus={handleStatus}
+          onLoadingChange={noop}
+          onNewWorkbook={noop}
+        />
+      </div>
+      {status !== '' && (
+        <div className={`dsh-spreadjs-statusbar dsh-spreadjs-status-${statusTone}`}>{status}</div>
+      )}
+    </div>
+  )
+}

package/src/client/better-sidebar.ts

@@ -0,0 +1,98 @@
+/**
+ * Minimal public face of the `dsh-better-sidebar` client service.
+ *
+ * The ui-all bundle exposes this service as `ctx.betterSidebar`; external
+ * plugins register file viewers with `registerFileViewer`. The plugin keeps
+ * its own types here so the client bundle does not need to import another
+ * package's runtime module.
+ */
+import type { ComponentType } from 'react'
+
+/** One request's session scope, mirroring better-sidebar's SessionScope. */
+export interface SidebarSessionScope {
+  sessionId: string
+  cwd?: string
+}
+
+/** How the sidebar host loads bytes for a file viewer. */
+export type SidebarFileFetchStrategy = 'mediaUrl' | 'custom' | 'none' | 'fsRead' | 'binary-download'
+
+/** Props handed to a registered file viewer component. */
+export interface SidebarFileViewerProps {
+  ctx: unknown
+  store: unknown
+  scope: SidebarSessionScope
+  path: string
+  title: string
+  viewerId: string
+  mediaUrl?: string
+  content?: string
+  customData?: unknown
+}
+
+/** Registration payload consumed by `betterSidebar.registerFileViewer`. */
+export interface SidebarFileViewerDescriptor {
+  id: string
+  title?: string | (() => string)
+  exts: readonly string[]
+  priority?: number
+  fetchStrategy: SidebarFileFetchStrategy
+  component: ComponentType<SidebarFileViewerProps>
+}
+
+/** Client service published by dsh-better-sidebar. */
+export interface SidebarService {
+  registerFileViewer(descriptor: SidebarFileViewerDescriptor): () => void
+}
+
+const ABSOLUTE_WINDOWS = /^[a-zA-Z]:[\\/]/
+
+function pathSegments(path: string): string[] {
+  return path.split(/[\\/]/).filter(part => part !== '')
+}
+
+function isAbsolute(path: string): boolean {
+  return path.startsWith('/') || path.startsWith('\\') || ABSOLUTE_WINDOWS.test(path)
+}
+
+/** Resolve a better-sidebar path against the session cwd when needed. */
+export function sidebarAbsolutePath(path: string, cwd?: string): string {
+  if (isAbsolute(path)) return path
+  if (cwd === undefined || cwd === '') return path
+  return `${cwd.replace(/[\\/]+$/, '')}/${path}`
+}
+
+function pathBase(path: string): string {
+  const segments = pathSegments(path)
+  return segments.at(-1) ?? path
+}
+
+function pathDir(path: string): string {
+  const segments = pathSegments(path)
+  if (segments.length <= 1) return path.startsWith('/') ? '/' : '.'
+  const base = segments.slice(0, -1).join('/')
+  if (ABSOLUTE_WINDOWS.test(path) && segments.length === 2) return `${segments[0]}:/`
+  if (path.startsWith('/')) return `/${base}`
+  if (path.startsWith('\\\\')) return `\\\\${base}`
+  return base
+}
+
+/** Raw-bytes media URL served by the sidebar host for one file. */
+export function sidebarFileUrl(scope: SidebarSessionScope, path: string): string {
+  const target = sidebarAbsolutePath(path, scope.cwd)
+  const params = new URLSearchParams({ sessionId: scope.sessionId, path: target })
+  if (scope.cwd !== undefined && scope.cwd !== '') params.set('cwd', scope.cwd)
+  return `/sidebar/file?${params.toString()}`
+}
+
+/** Raw upload URL that writes a blob back to the file's directory. */
+export function sidebarUploadUrl(scope: SidebarSessionScope, path: string): string {
+  const target = sidebarAbsolutePath(path, scope.cwd)
+  const params = new URLSearchParams({
+    sessionId: scope.sessionId,
+    dir: pathDir(target),
+    relativePath: pathBase(target),
+  })
+  if (scope.cwd !== undefined && scope.cwd !== '') params.set('cwd', scope.cwd)
+  return `/sidebar/upload?${params.toString()}`
+}

package/src/client/global.d.ts

@@ -0,0 +1,5 @@
+/** Module declaration for the css-as-text build plugin. */
+declare module '*.css' {
+  const content: string
+  export default content
+}

package/src/client/index.ts

@@ -0,0 +1,50 @@
+/**
+ * dsh-spreadjs-editor -- browser half.
+ *
+ * Registers the SpreadJS file viewer into `dsh-better-sidebar`, which is
+ * bundled by `@linxin666/dsh-web-all` (ui-all). The plugin has no generic
+ * web-editors dependency: opening and saving go through better-sidebar's
+ * session `/sidebar/file` and `/sidebar/upload` routes.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { SpreadsheetViewer } from './SpreadsheetViewer.tsx'
+import type { SidebarService } from './better-sidebar.ts'
+import { injectStyles } from './styles.ts'
+
+export const name = 'dsh-spreadjs-editor'
+
+/** Optional service discovery: the plugin stays idle if better-sidebar is absent. */
+export const inject: string[] = []
+
+const SIDEBAR_VIEWER = {
+  id: 'spreadjs',
+  title: 'SpreadJS',
+  exts: ['xlsx', 'xlsm', 'csv', 'sjs', 'ssjson'],
+  fetchStrategy: 'mediaUrl',
+  priority: 0,
+  component: SpreadsheetViewer,
+} as const
+
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => injectStyles(), 'dsh-spreadjs-editor: styles')
+
+  ctx.effect(() => {
+    const fiber = ctx.inject(['betterSidebar'], (child) => {
+      child.effect(() => {
+        const service = child.get('betterSidebar') as SidebarService
+        let dispose: (() => void) | undefined
+        try {
+          dispose = service.registerFileViewer({ ...SIDEBAR_VIEWER })
+        } catch (error) {
+          console.error('[dsh-spreadjs-editor] betterSidebar registration failed:', error)
+        }
+        return () => {
+          try { dispose?.() } catch { /* already disposed */ }
+        }
+      }, 'dsh-spreadjs-editor: betterSidebar registration')
+    })
+    return () => {
+      try { fiber.dispose() } catch { /* already disposed */ }
+    }
+  }, 'dsh-spreadjs-editor: betterSidebar adapter')
+}

package/src/client/styles.ts

@@ -0,0 +1,27 @@
+/**
+ * Stylesheet injection for the client bundle. SpreadJS ships its own CSS and
+ * the editor adds a small stylesheet; both are inlined as text by the build
+ * plugin and injected here at factory materialization (framework style).
+ */
+import spreadSheetsCss from '@grapecity-software/spread-sheets/styles/gc.spread.sheets.excel2013white.css'
+import designerCss from '@grapecity-software/spread-sheets-designer/styles/gc.spread.sheets.designer.light.min.css'
+import viewerCss from './viewer.css'
+
+const STYLES = [spreadSheetsCss, designerCss, viewerCss]
+
+/** Inject the stylesheets; returns a disposer that removes the tags. */
+export function injectStyles(): () => void {
+  const tags: HTMLStyleElement[] = []
+  if (typeof document !== 'undefined' && document.head !== null) {
+    for (const css of STYLES) {
+      const tag = document.createElement('style')
+      tag.dataset.plugin = 'dsh-spreadjs-editor'
+      tag.textContent = css
+      document.head.appendChild(tag)
+      tags.push(tag)
+    }
+  }
+  return () => {
+    for (const tag of tags) tag.remove()
+  }
+}