@qijenchen/design-system 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/components/FileUpload/file-upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload.js","sources":["../../../src/components/FileUpload/file-upload.tsx"],"sourcesContent":["// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.\nimport * as React from 'react'\nimport { Upload as UploadIcon, X } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Empty } from '@/design-system/components/Empty/empty'\nimport { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'\nimport { FileItem } from '@/design-system/components/FileItem/file-item'\nimport { Button } from '@/design-system/components/Button/button'\n\n/**\n * FileUpload — 拖放 / 點擊上傳區塊\n *\n * 世界級對照:Ant Design `Upload.Dragger`、Polaris `DropZone`、Material community MUI-File-Input。\n * 與本 DS 既有 FileItem(顯示已上傳檔案)配對 — 這裡 own「上傳觸發 + 拖放偵測」,\n * 上傳後的檔案清單顯示交給 consumer 用 FileItem 渲染。\n *\n * ── 4 狀態 ──\n * idle     (default) — border-dashed border-divider  bg-surface\n * drag-over         — border-dashed border-primary  bg-primary-subtle\n * loading           — 上傳中(async)顯示 CircularProgress,阻擋新互動\n * disabled          — opacity-disabled pointer-events-none\n *\n * ── children 插槽 ──\n * 預設渲染 `<Empty icon={Upload} title description />` — 重用 Empty 元件 own\n * 的「icon + title + description 垂直居中」SSOT 避免視覺漂移。Empty 改字體 /\n * gap / icon 尺寸時 FileUpload 自動跟進。若 consumer 傳 children 則整個覆寫。\n *\n * ── API ──\n * onUpload: 使用者選取或拖放檔案時觸發,回傳 File[](至少 1 個)。\n * multiple: 允許多檔。預設 false(單檔)。\n * accept:   MIME filter(例 \"image/*,.pdf\"),傳給 <input type=file>。\n * maxSize:  單檔最大 bytes;超過靜默忽略(consumer 若需要錯誤提示,走 onReject)。\n * onReject: 被 maxSize / accept 擋下的檔案(提供錯誤訊息顯示機會)。\n */\n\n/**\n * Uploaded / uploading file status item(for `files` prop)。\n * Consumer 持 state(progress / status),FileUpload 只負責渲染。\n */\nexport interface FileUploadStatus {\n  id: string\n  name: string\n  /** bytes */\n  size?: number\n  /** Upload 進度(0-100)— uploading 時顯示 progress bar */\n  progress?: number\n  status?: 'uploading' | 'completed' | 'error'\n  /** Error 訊息 / size 等 description */\n  description?: React.ReactNode\n  /** Thumbnail URL for rich mode */\n  thumbnailSrc?: string\n}\n\nexport interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onDrop'> {\n  onUpload?: (files: File[]) => void\n  onReject?: (files: File[], reason: 'size' | 'type') => void\n  multiple?: boolean\n  accept?: string\n  maxSize?: number\n  disabled?: boolean\n  /**\n   * Loading 狀態(async 上傳 / 伺服器處理中)。\n   * - 顯示 CircularProgress 取代預設 Empty 內容\n   * - 阻擋新點擊 / drag 事件(避免 double-submit)\n   * - 宣告 `aria-busy=\"true\"` 讓 screen reader 感知處理中\n   * - Consumer 負責在上傳完成後自己切回 `loading={false}`\n   */\n  loading?: boolean\n  /** Loading 狀態的文字標題(預設「上傳中…」) */\n  loadingTitle?: string\n  /** 標題文字(預設「Click or drag file here to upload」) */\n  title?: string\n  /** 說明文字(預設「Support for a single or bulk upload」) */\n  description?: string\n  /** 若傳入 children,覆寫預設 Empty 結構 */\n  children?: React.ReactNode\n  /**\n   * Uploaded / uploading 檔案清單。傳入 → FileUpload 在 drop zone 下方渲染列表。\n   * 不傳 → 不顯示(consumer 可自行用 FileItem 組成,pre-2026-04-24 行為)。\n   * 每項有 status 狀態會對應 icon:\n   *   - `uploading`:CircularProgress(+ progress bar 若 progress 給)\n   *   - `completed`:綠色 ✓(success 狀態視覺確認)\n   *   - `error`:紅色 ✗(+ description 顯示錯誤訊息)\n   */\n  files?: FileUploadStatus[]\n  /** File list 每項顯示模式。Default: 'compact'(單行);'rich' = 含 thumbnail / size / progress bar */\n  fileListMode?: 'compact' | 'rich'\n  /** File list 移除 callback。有值 → 每項右側顯示 X dismiss button;無 → 不可移除(view-only) */\n  onRemove?: (id: string) => void\n  /** File list dismiss button ARIA label template。預設 `移除 {name}`。For i18n. */\n  removeAriaLabel?: (name: string) => string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(\n  (\n    {\n      onUpload,\n      onReject,\n      multiple = false,\n      accept,\n      maxSize,\n      disabled = false,\n      loading = false,\n      loadingTitle = '上傳中…', // i18n-allow: DS default; consumer override via loadingTitle prop\n      title = 'Click or drag file here to upload', // i18n-allow: DS default; consumer override via title prop\n      description = multiple ? 'Support for a single or bulk upload' : 'Support for a single file upload', // i18n-allow: DS default; consumer override via description prop\n      children,\n      files,\n      fileListMode = 'compact',\n      onRemove,\n      removeAriaLabel = (name: string) => `移除 ${name}`, // i18n-allow: DS default; consumer override via removeAriaLabel prop\n      className,\n      onClick,\n      ...props\n    },\n    ref,\n  ) => {\n    const inputRef = React.useRef<HTMLInputElement>(null)\n    const [isDragOver, setDragOver] = React.useState(false)\n\n    const filterAndDispatch = (files: FileList | null) => {\n      if (!files || files.length === 0) return\n      const accepted: File[] = []\n      const rejectedBySize: File[] = []\n      const rejectedByType: File[] = []\n\n      Array.from(files).forEach((f) => {\n        if (maxSize != null && f.size > maxSize) {\n          rejectedBySize.push(f)\n          return\n        }\n        if (accept && !matchAccept(f, accept)) {\n          rejectedByType.push(f)\n          return\n        }\n        accepted.push(f)\n      })\n\n      if (rejectedBySize.length) onReject?.(rejectedBySize, 'size')\n      if (rejectedByType.length) onReject?.(rejectedByType, 'type')\n      if (accepted.length) onUpload?.(multiple ? accepted : accepted.slice(0, 1))\n    }\n\n    const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {\n      if (!disabled) inputRef.current?.click()\n      onClick?.(e)\n    }\n\n    // State 優先序:disabled > loading > drag-over > idle(disabled 最硬,loading 次之)\n    const state = disabled ? 'disabled' : loading ? 'loading' : isDragOver ? 'drag-over' : 'idle'\n    const isBlocked = disabled || loading\n\n    const hasFiles = Array.isArray(files) && files.length > 0\n\n    const fileListNode = hasFiles ? (\n      <ul\n        className={cn(\n          // stack vertically with consistent gap;bg-surface 在容器外的 chrome / consumer bg 之上\n          'flex flex-col gap-2 w-full',\n          'mt-3',\n        )}\n        aria-label=\"Uploaded files\"\n      >\n        {files!.map((f) => (\n          <li key={f.id} className=\"list-none\">\n            <FileItem\n              mode={fileListMode}\n              name={f.name}\n              status={f.status}\n              progress={f.progress}\n              description={f.description ?? (f.size != null ? formatBytes(f.size) : undefined)}\n              thumbnailSrc={f.thumbnailSrc}\n              actions={\n                onRemove ? (\n                  // Collection remove(per-file)— 不是 dismiss surface,故不套 `dismiss` prop。\n                  // 視覺與 dismiss 一致(text variant + fg-muted dim)— 對齊 inline-action.spec.md\n                  // 「Dismiss canonical — X close only」L249-251:onRemove callback 不觸發 dismiss prop。\n                  <Button\n                    iconOnly\n                    variant=\"text\"\n                    size=\"xs\"\n                    startIcon={X}\n                    aria-label={removeAriaLabel(f.name)}\n                    onClick={(e) => {\n                      e.stopPropagation()\n                      onRemove(f.id)\n                    }}\n                    className=\"text-fg-muted hover:text-foreground\"\n                  />\n                ) : undefined\n              }\n            />\n          </li>\n        ))}\n      </ul>\n    ) : null\n\n    return (\n      <div ref={ref} className={cn('w-full', hasFiles && 'flex flex-col')}>\n      <div\n        role=\"button\"\n        tabIndex={isBlocked ? -1 : 0}\n        aria-disabled={disabled || undefined}\n        aria-busy={loading || undefined}\n        data-state={state}\n        onClick={handleClick}\n        onKeyDown={(e) => {\n          if (isBlocked) return\n          if (e.key === 'Enter' || e.key === ' ') {\n            e.preventDefault()\n            inputRef.current?.click()\n          }\n        }}\n        onDragEnter={(e) => {\n          if (isBlocked) return\n          e.preventDefault()\n          setDragOver(true)\n        }}\n        onDragLeave={(e) => {\n          if (isBlocked) return\n          e.preventDefault()\n          setDragOver(false)\n        }}\n        onDragOver={(e) => {\n          if (isBlocked) return\n          e.preventDefault()\n        }}\n        onDrop={(e) => {\n          if (isBlocked) return\n          e.preventDefault()\n          setDragOver(false)\n          filterAndDispatch(e.dataTransfer.files)\n        }}\n        className={cn(\n          // 寬度 w-full 填滿 consumer 容器(user 明示「寬度填滿」);高度由 padding + 內容物決定(不固定 h)\n          'flex flex-col items-center justify-center gap-2 text-center w-full',\n          // 對稱 padding p-[var(--layout-space-loose)]:四邊等距,density-aware(md=24px / lg=32px),對齊 DS chrome padding canonical。\n          // 不再硬寫 px-6 py-10(不對稱+非 token)。內容物(icon + title + description)垂直堆疊由 gap-2 控制\n          'rounded-md border-2 border-dashed p-[var(--layout-space-loose)]',\n          'cursor-pointer transition-colors',\n          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',\n          // idle\n          'border-divider bg-surface hover:bg-neutral-hover',\n          // drag-over\n          'data-[state=drag-over]:border-primary data-[state=drag-over]:bg-primary-subtle data-[state=drag-over]:hover:bg-primary-subtle',\n          // loading(阻擋新互動但不 opacity-disabled — 避免跟 disabled 視覺撞,保持「處理中」語意)\n          'data-[state=loading]:cursor-progress data-[state=loading]:pointer-events-none',\n          // disabled\n          'data-[state=disabled]:opacity-disabled data-[state=disabled]:pointer-events-none data-[state=disabled]:cursor-not-allowed',\n          className,\n        )}\n        {...props}\n      >\n        <input\n          ref={inputRef}\n          type=\"file\"\n          className=\"hidden\"\n          multiple={multiple}\n          accept={accept}\n          disabled={disabled}\n          onChange={(e) => filterAndDispatch(e.target.files)}\n        />\n        {loading ? (\n          <Empty\n            icon={<CircularProgress size={48} />}\n            title={loadingTitle}\n          />\n        ) : (\n          children ?? (\n            <Empty\n              icon={UploadIcon}\n              title={title}\n              description={description}\n            />\n          )\n        )}\n      </div>\n      {fileListNode}\n      </div>\n    )\n  },\n)\nFileUpload.displayName = 'FileUpload'\n\n// ── helper: bytes formatter ───────────────────────────────────────────────\nfunction formatBytes(n: number): string {\n  if (n < 1024) return `${n} B`\n  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`\n  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`\n  return `${(n / (1024 * 1024 * 1024)).toFixed(1)} GB`\n}\n\n// ── helpers ─────────────────────────────────────────────────────────────────\n\nfunction matchAccept(file: File, accept: string): boolean {\n  const patterns = accept.split(',').map((s) => s.trim().toLowerCase())\n  const fileName = file.name.toLowerCase()\n  const fileType = file.type.toLowerCase()\n  return patterns.some((p) => {\n    if (p.startsWith('.')) return fileName.endsWith(p) // 副檔名 e.g. \".pdf\"\n    if (p.endsWith('/*')) return fileType.startsWith(p.slice(0, -1)) // e.g. \"image/*\"\n    return fileType === p // 完整 MIME\n  })\n}\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const fileUploadMeta = {\n  component: 'FileUpload',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-neutral-hover', 'bg-primary-subtle', 'bg-surface'],\n    fg: [],\n    ring: ['ring-ring'],\n  },\n} as const\n\nexport { FileUpload }\n"],"names":["files","UploadIcon"],"mappings":"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"}

package/dist/components/FileViewer/file-viewer-types.d.ts

@@ -0,0 +1,73 @@
+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 值本身是否變。
+ */
+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>;
+}
+//# sourceMappingURL=file-viewer-types.d.ts.map

package/dist/components/FileViewer/file-viewer-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-viewer-types.d.ts","sourceRoot":"","sources":["../../../src/components/FileViewer/file-viewer-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;;GAMG;AAEH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAA;IACb,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,2BAA2B;IAC3B,UAAU,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAChD;AAED;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,GAAG,EAAE,WAAW,GAAG,UAAU,CAAA;IAC7B,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAA;IACd,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9B;;;;OAIG;IACH,oBAAoB,EAAE,CAAC,IAAI,EAAE,wBAAwB,KAAK,IAAI,CAAA;CAC/D;AAED,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAA;IACtC,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAA;CAClD"}

package/dist/components/FileViewer/file-viewer.d.ts

@@ -0,0 +1,82 @@
+import * as React from 'react';
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import type { FileInfo, FileRenderer } from './file-viewer-types';
+export declare function registerFileRenderer(renderer: FileRenderer): void;
+/**
+ * i18n-able labels for FileViewer chrome / controls.
+ * All keys are optional — defaults are CJK (see `DEFAULT_LABELS`).
+ * Consumer typically spreads partial override:
+ *   `<FileViewer labels={{ close: 'Close', download: 'Download' }} />`
+ */
+export interface FileViewerLabels {
+    /** Zoom input ARIA label */
+    zoomInput?: string;
+    /** Zoom menu trigger ARIA label */
+    zoomMenu?: string;
+    /** Info panel toggle button — shown when panel is OPEN */
+    infoToggleCollapse?: string;
+    /** Info panel toggle button — shown when panel is CLOSED */
+    infoToggleExpand?: string;
+    /** Download button ARIA label */
+    download?: string;
+    /** Close viewer button ARIA label */
+    close?: string;
+    /** InfoPanel outer aside ARIA label */
+    detailPanel?: string;
+    /** InfoPanel heading text */
+    detailsHeading?: string;
+    /** InfoPanel close button ARIA label */
+    detailPanelClose?: string;
+    /** Description textarea placeholder (readOnly) */
+    descriptionPlaceholderReadOnly?: string;
+    /** Description textarea placeholder (editable) */
+    descriptionPlaceholderEdit?: string;
+    /** Detail section — file info section heading */
+    fileInfoHeading?: string;
+    /** Filmstrip tablist ARIA label */
+    filmstripLabel?: string;
+    /** Previous-file nav button ARIA label */
+    previousFile?: string;
+    /** Next-file nav button ARIA label */
+    nextFile?: string;
+}
+export interface FileViewerProps extends Omit<React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, 'onOpenChange'> {
+    files: FileInfo[];
+    initialIndex?: number;
+    /** Controlled open state。與 `defaultOpen` 二擇一。 */
+    open?: boolean;
+    /** Uncontrolled open 預設(2026-04-25 加,對齊 Dialog/Sheet/Popover dual-mode canonical)。 */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** 當前索引(controlled);consumer 想自己控制 active file 時傳。不傳則 shell 管理。 */
+    index?: number;
+    onIndexChange?: (index: number) => void;
+    /** 當前檔案 description 變化。consumer 負責持久化。readOnly 為 true 時不觸發。 */
+    onDescriptionChange?: (fileId: string, description: string) => void;
+    /** true → InfoPanel 的 description textarea 為 readOnly。預設 false。 */
+    readOnly?: boolean;
+    /** 顯示底部 filmstrip。預設 false;files.length < 2 時自動隱藏。 */
+    showFilmstrip?: boolean;
+    /** 是否提供 download 按鈕。預設 true。 */
+    allowDownload?: boolean;
+    /** 自訂 download 行為;未傳則用 anchor download attribute。 */
+    onDownload?: (file: FileInfo) => void;
+    /** i18n labels override. Partial — merged with DS defaults. */
+    labels?: FileViewerLabels;
+}
+declare const FileViewer: React.ForwardRefExoticComponent<FileViewerProps & React.RefAttributes<HTMLDivElement>>;
+export declare const fileViewerMeta: {
+    readonly component: "FileViewer";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-muted", "bg-surface", "bg-surface-raised"];
+        readonly fg: readonly ["text-fg-muted", "text-foreground"];
+        readonly ring: readonly ["ring-primary", "ring-ring"];
+    };
+};
+export { FileViewer };
+export type { FileInfo, FileRenderer, FileRendererCapabilities, FileRendererProps } from './file-viewer-types';
+//# sourceMappingURL=file-viewer.d.ts.map

package/dist/components/FileViewer/file-viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-viewer.d.ts","sourceRoot":"","sources":["../../../src/components/FileViewer/file-viewer.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAA;AAuCzD,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EAEb,MAAM,qBAAqB,CAAA;AA6D5B,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAQjE;AA4gBD;;;;;GAKG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kDAAkD;IAClD,8BAA8B,CAAC,EAAE,MAAM,CAAA;IACvC,kDAAkD;IAClD,0BAA0B,CAAC,EAAE,MAAM,CAAA;IACnC,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAqBD,MAAM,WAAW,eACf,SAAQ,IAAI,CACV,KAAK,CAAC,wBAAwB,CAAC,OAAO,eAAe,CAAC,OAAO,CAAC,EAC9D,cAAc,CACf;IACD,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;IACnE,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gCAAgC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,qDAAqD;IACrD,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAA;IACrC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAC1B;AAED,QAAA,MAAM,UAAU,wFA0Td,CAAA;AAKF,eAAO,MAAM,cAAc;;;;;;;;;;;CAejB,CAAA;AAEV,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA"}