@qijenchen/design-system 0.1.0-beta.3

package/src/components/FileViewer/file-viewer-types.ts

@@ -0,0 +1,76 @@
+import * as React from 'react'
+
+/**
+ * FileViewer — shared types
+ *
+ * 單獨檔避免 file-viewer.tsx 跟 renderer 檔之間的 circular import
+ * (renderer 檔需要 FileInfo / FileRendererProps,shell 也需要 FileRenderer
+ * interface 做 registry iteration)。
+ */
+
+export interface FileInfo {
+  id: string
+  url: string
+  name: string
+  mimeType: string
+  /** Bytes。consumer 負責格式化,shell 只呈現 formatted 字串。 */
+  size?: number
+  /** 描述文字,顯示於 InfoPanel(consumer 透過 onDescriptionChange 持久化)。 */
+  description?: string
+  /** 自由 metadata 欄位,InfoPanel 逐行呈現 key: value。 */
+  metadata?: Record<string, string | number>
+}
+
+/**
+ * Renderer 能力宣告 — 告訴 shell 目前 renderer 支援哪些 toolbar affordances。
+ * Shell 根據這個 object 動態決定 toolbar 顯示(zoom controls / page nav 等)。
+ */
+export interface FileRendererCapabilities {
+  /** 是否支援 zoom(shell 據此顯示 ZoomInput)。 */
+  zoom: boolean
+  /** 是否支援旋轉(預留給未來 PDF / Image rotate)。 */
+  rotate?: boolean
+  /** PDF 專用:當前頁 / 總頁數。預留。 */
+  pageNumber?: { current: number; total: number }
+}
+
+/**
+ * Fit-to-* 指令:shell 向 renderer 下指令「請用 width 或 page fit 比例重新 zoom」。
+ * 採 nonce(counter)模式而非 boolean,讓 shell 可以重複下同一個 fit 指令
+ * (例:user 連按兩次 Fit to page 應該都觸發 ImageRenderer 重新計算)。
+ * renderer 收到 nonce 變化時才執行 fit,不看 fit 值本身是否變。
+ */
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export interface FitRequest {
+  /** 'fit-width' = 寬度填滿;'fit-page' = 整頁符合(width 和 height 都 fit,取較小 scale) */
+  fit: 'fit-width' | 'fit-page'
+  /** 每次 shell 下指令時 +1,renderer watch 此值變化才觸發 fit */
+  nonce: number
+}
+
+export interface FileRendererProps {
+  file: FileInfo
+  /** 當前 zoom(%);shell own state,passed down 給 renderer。 */
+  zoom: number
+  /** Renderer 內部 zoom 變化時呼叫(wheel / pinch)。 */
+  onZoomChange: (next: number) => void
+  /**
+   * Shell 下的 fit-to-* 指令。renderer 負責算出 container / image 比例,
+   * 並透過 `onZoomChange` 回報算出的 zoom %。null 時不動作。
+   * renderer 若不支援 fit(未計算能力),可忽略此 prop。
+   */
+  fitRequest?: FitRequest | null
+  /**
+   * Renderer 在 mount 或 file/capability 改變時呼叫,告訴 shell 目前支援哪些
+   * capability。不 emit 代表 shell 維持上一個 renderer 的 capability(第一個
+   * renderer mount 時必須 emit)。
+   */
+  onCapabilitiesChange: (caps: FileRendererCapabilities) => void
+}
+
+export interface FileRenderer {
+  /** unique id(registry debug 用)。 */
+  id: string
+  canRender: (file: FileInfo) => boolean
+  component: React.ComponentType<FileRendererProps>
+}