@brftech/filex-core 0.1.56

package/src/styles/variables.css

@@ -0,0 +1,90 @@
+/**
+ * CSS variables — theme hooks.
+ *
+ * Consumer overrides by setting `--fe-*` on a higher scope.
+ */
+:root {
+  --fe-bg: #ffffff;
+  --fe-bg-elev: #f7f8fa;
+  --fe-bg-hover: #edf0f5;
+  --fe-bg-selected: #dfe8ff;
+  --fe-border: #e2e6ed;
+  --fe-border-strong: #c7ced9;
+  --fe-text: #1a1e27;
+  --fe-text-muted: #5a6475;
+  --fe-text-on-primary: #ffffff;
+  --fe-primary: #3b82f6;
+  --fe-primary-hover: #2563eb;
+  --fe-danger: #dc2626;
+  --fe-danger-hover: #b91c1c;
+  --fe-shadow: 0 10px 32px rgba(15, 23, 42, 0.14);
+  --fe-shadow-sm: 0 2px 6px rgba(15, 23, 42, 0.08);
+  --fe-radius: 8px;
+  --fe-radius-sm: 4px;
+  --fe-radius-lg: 12px;
+  --fe-font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --fe-font-mono: ui-monospace, "SF Mono", Consolas, Menlo, monospace;
+  --fe-gap: 12px;
+}
+
+.fe--theme-dark,
+:root[data-theme='dark'] .fe,
+.fe.fe--theme-dark,
+/* Tailwind dark-mode class shipped by the host admin shell —
+ * web/src/lib/theme.ts toggles document.documentElement.classList
+ * .toggle('dark', dark), so we adopt the same hook here. Without
+ * this selector the embedded explorer stayed on the :root light
+ * defaults even when the rest of the admin UI flipped dark.
+ *
+ * The bare `:root.dark` / `.dark` selectors (no `.fe` descendant)
+ * also publish the variables at the html-level so non-SFC consumers —
+ * the standalone /files/edit Editor.vue route, which doesn't wrap its
+ * host div in `.fe` — pick up the dark palette via CSS-variable
+ * cascade. v0.1.11 added the bare selectors after operators reported
+ * the new tab opening light when the admin panel was dark. */
+:root.dark,
+.dark,
+:root.dark .fe,
+.dark .fe,
+/* Teleported context menu lives outside the `.fe` parent, so we have
+ * to apply the same dark-mode variable overrides on its backdrop too —
+ * otherwise it stays on the :root light defaults and the menu renders
+ * as white-on-white inside dark hosts. */
+.fe-ctx-backdrop--theme-dark,
+.fe-ctx-backdrop--theme-auto[data-prefers-dark='1'] {
+  --fe-bg: #0f1419;
+  --fe-bg-elev: #161c25;
+  --fe-bg-hover: #1f2733;
+  --fe-bg-selected: #23324a;
+  --fe-border: #2a323e;
+  --fe-border-strong: #3a4453;
+  --fe-text: #e5e9f0;
+  --fe-text-muted: #8b95a7;
+  --fe-primary: #60a5fa;
+  --fe-primary-hover: #3b82f6;
+  --fe-danger: #f87171;
+  --fe-danger-hover: #ef4444;
+  --fe-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+  --fe-shadow-sm: 0 2px 6px rgba(0, 0, 0, 0.25);
+}
+
+@media (prefers-color-scheme: dark) {
+  .fe:not(.fe--theme-light),
+  /* Same trick for the teleported backdrop in auto mode. */
+  .fe-ctx-backdrop--theme-auto:not(.fe-ctx-backdrop--theme-light) {
+    --fe-bg: #0f1419;
+    --fe-bg-elev: #161c25;
+    --fe-bg-hover: #1f2733;
+    --fe-bg-selected: #23324a;
+    --fe-border: #2a323e;
+    --fe-border-strong: #3a4453;
+    --fe-text: #e5e9f0;
+    --fe-text-muted: #8b95a7;
+    --fe-primary: #60a5fa;
+    --fe-primary-hover: #3b82f6;
+    --fe-danger: #f87171;
+    --fe-danger-hover: #ef4444;
+    --fe-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+    --fe-shadow-sm: 0 2px 6px rgba(0, 0, 0, 0.25);
+  }
+}

package/src/types/ExplorerConfig.ts

@@ -0,0 +1,282 @@
+/**
+ * ExplorerConfig — props passed to the FileExplorer component.
+ *
+ * Two equivalent ways to wire it up:
+ *
+ *   1. New clean API (preferred — RESTful, server-agnostic):
+ *      { apiBase: 'https://files.example.com', auth: { kind: 'bearer', token } }
+ *      → URLs like `${apiBase}/api/files/manager`, `${apiBase}/api/files/upload/init`.
+ *
+ *   2. Legacy API (Vuefinder-compat — for embedders that mounted the
+ *      old `@brftech/file-explorer` package against their own routes):
+ *      { endpoint: '/api/files/manager', uploadInit: '/api/files/upload/init', … }
+ *      → caller fully controls every URL.
+ *
+ * If both `apiBase` AND any explicit `endpoint`/`uploadInit`/etc. are
+ * present, the explicit field wins (lets you override one route while
+ * keeping the auto-derived rest).
+ */
+
+/**
+ * Auth strategy. Discriminated union so request building is type-safe.
+ *
+ * - `bearer`  — `Authorization: Bearer <token>`. Token may be a string
+ *               OR a sync/async function (auto-refresh).
+ * - `csrf`    — `X-CSRF-TOKEN` + `credentials: include` (Laravel/Filament).
+ * - `basic`   — `Authorization: Basic <base64(user:pass)>`.
+ * - `none`    — no auth (development / public sandbox).
+ */
+export type AuthConfig =
+  | { kind: 'bearer'; token: string | (() => string | Promise<string>) }
+  | { kind: 'csrf'; csrf: string }
+  | { kind: 'basic'; user: string; pass: string }
+  | { kind: 'none' }
+  /**
+   * Legacy `type` field (back-compat with @brftech/file-explorer 0.1.0).
+   * Internally normalized to the `kind`-tagged shape.
+   */
+  | { type: 'bearer'; token: string }
+  | { type: 'csrf'; csrf: string };
+
+export type ThemeMode = 'light' | 'dark' | 'auto';
+export type LocaleCode = 'tr' | 'en';
+
+/**
+ * Resolved endpoint map. `useFileApi` derives this once on construction
+ * — components never need to think about config/apiBase precedence.
+ */
+export interface EndpointMap {
+  manager: string;
+  uploadInit: string | null;
+  uploadFinalize: string | null;
+  uploadAbort: string | null;
+  shareCreate: string | null;
+  shareList: string | null;
+  shareDelete: string | null;
+  limits: string | null;
+  capabilities: string | null;
+  archiveList: string | null;
+  archiveExtract: string | null;
+  archiveAdd: string | null;
+  copy: string | null;
+  moveAsync: string | null;
+  deleteAsync: string | null;
+  opsList: string | null;
+  opsShow: string | null;
+  onlyOfficeConfig: string | null;
+  saveText: string | null;
+  restore: string | null;
+  trashList: string | null;
+  trashRestore: string | null;
+}
+
+export interface ExplorerConfig {
+  /**
+   * Modern shorthand: URL prefix for the standard /api/files/* layout.
+   * Example: `https://files.example.com` → `${apiBase}/api/files/manager`,
+   * `${apiBase}/api/files/upload/init`, etc. Any explicit endpoint*
+   * field below overrides the derived URL.
+   */
+  apiBase?: string;
+
+  /** Legacy main endpoint (Vuefinder-compat: GET/POST `?q=…`). */
+  endpoint?: string;
+
+  // ——— Per-route overrides (optional; auto-derived from apiBase if absent) ———
+  uploadInit?: string;
+  uploadFinalize?: string;
+  uploadAbort?: string;
+
+  shareCreate?: string;
+  shareList?: string;
+  /** DELETE template; `{uuid}` placeholder is replaced at call time. */
+  shareDelete?: string;
+
+  limits?: string;
+  capabilities?: string;
+
+  archiveList?: string;
+  archiveExtract?: string;
+  archiveAdd?: string;
+
+  /** Recursive S3-side copy with "-copy" collision suffix (async). */
+  copy?: string;
+
+  /** Async move endpoint — returns {op}, client polls /opsList. */
+  moveAsync?: string;
+
+  /** Async delete endpoint — returns {op}, client polls /opsList. */
+  deleteAsync?: string;
+
+  /** Pending ops list endpoint (poll target). */
+  opsList?: string;
+
+  /** Single op show endpoint — `{id}` placeholder. */
+  opsShow?: string;
+
+  /**
+   * OnlyOffice config endpoint. Backend POST returns
+   * `{ config, documentServerUrl }` where `config` is a JWT-signed
+   * DocEditor config. PreviewModal mounts the editor against this
+   * when the user opens an office file with mode=edit.
+   */
+  onlyOfficeConfig?: string;
+
+  /**
+   * Standalone editor page base — when set, "Aç" on an office file
+   * opens `${openPageBase}?path=...&mode=edit` in a new tab instead
+   * of the modal preview.
+   */
+  openPageBase?: string;
+
+  /**
+   * Plain-text save endpoint — POST `{path, content}`. When set, code
+   * preview gains an editable mode + save button. Falsy = read-only.
+   */
+  saveText?: string;
+
+  /**
+   * Trash restore endpoint — `POST {source: string[]}`. When set, a
+   * "Geri Getir" action shows up in `.trash/` listings.
+   */
+  restore?: string;
+
+  /** filex trash listing endpoint — `GET → { entries: TrashEntry[] }`. */
+  trashList?: string;
+  /** filex trash restore endpoint — `POST { node_id }`. */
+  trashRestore?: string;
+
+  /** Public share base URL — `${shareBase}/${uuid}` */
+  shareBase?: string;
+
+  /** Auth strategy (see AuthConfig). */
+  auth?: AuthConfig;
+
+  /** Show the virtual `.trash/` entry in the root listing. */
+  trashVisible?: boolean;
+
+  /** UI dil kodu */
+  locale?: LocaleCode;
+
+  /** OnlyOffice iframe base (e.g. `https://docs.example.com`). */
+  onlyOfficeBase?: string;
+
+  /** Drawio iframe base. */
+  drawioBase?: string;
+
+  /** Universal converter (p2r3/convert fork) iframe base, e.g. `https://fm.example.com/convert`. */
+  convertBase?: string;
+
+  /**
+   * Drawio embed URL (full URL to the embed endpoint). Defaults to
+   * `https://embed.diagrams.net`. The DrawioViewer iframes this with
+   * `?embed=1&proto=json` postMessage handshake to load + save XML.
+   */
+  drawioUrl?: string;
+
+  /**
+   * Optional URL where serialized PDF annotations / form data is
+   * persisted. POST `{ path, base64 }` — the rich PdfViewer uses
+   * `pdf.saveDocument()` and forwards the saved bytes here when the
+   * user clicks the save annotation button.
+   */
+  pdfSaveUrl?: string;
+
+  /**
+   * Override the pdf.js worker URL. Defaults to a CDN copy matching
+   * the version pdfjs-dist resolves to at runtime — hosts can pin
+   * their own self-hosted worker for CSP-strict environments.
+   */
+  pdfWorkerUrl?: string;
+
+  /**
+   * Standalone full-screen viewer route. The PreviewModal toolbar's
+   * "Open in new tab" button navigates to
+   * `${viewerBaseUrl}?path=…&storage=…&type=…`. The consumer wires
+   * that route to mount the same viewer fullscreen (admin UI / fishapp
+   * embed). Defaults to `/files/viewer`.
+   */
+  viewerBaseUrl?: string;
+
+  /** Upload chunk size (bytes). Default 5 MB. */
+  chunkSize?: number;
+
+  /** Parallel chunks. Default 4. */
+  parallelChunks?: number;
+
+  /** Theme. */
+  theme?: ThemeMode;
+
+  /** Initial path (storage-prefix included: `local://`). Default: root. */
+  initialPath?: string;
+
+  /**
+   * Confine the explorer to this folder (qualified: `main://projeler/acme`).
+   * The UI opens here, hides the multi-storage drives root, and blocks
+   * navigation above it. SECURITY IS NOT THIS — enforce it server-side with an
+   * X-Filex-Root header / root-scoped API token; this is the clean-embed UX.
+   */
+  rootPath?: string;
+
+  /** Whether the info panel toggle is visible. */
+  showInfoPanel?: boolean;
+
+  /** Default view. */
+  viewMode?: 'list' | 'grid';
+
+  /** Override max upload size (MB) — falls back to /limits otherwise. */
+  maxFileSizeMb?: number;
+
+  /** Accept patterns (MIME or extension). Empty = unrestricted. */
+  acceptTypes?: string[];
+
+  /** Storage adapter to default to (avoids the initial flash). */
+  defaultAdapter?: string;
+
+  /**
+   * Where to persist the current path so reload lands the user back
+   * in the same folder.
+   *   'hash'         — URL hash. Default — works on plain web pages.
+   *   'localStorage' — `brf-file-explorer:path` key. Best for SPAs that
+   *                    already own the URL (Ionic / Vue Router / Next).
+   *   'none'         — don't persist. Embedder controls path externally.
+   */
+  pathPersist?: 'hash' | 'localStorage' | 'none';
+
+  /**
+   * Multi-storage root mode. When true, the explorer's "/" virtual
+   * folder lists every entry in `storages` as a clickable directory.
+   * Clicking one drills into that storage's root; the breadcrumb
+   * walks `/ › <storage> › <sub> › …`.
+   *
+   * When false (default) the SFC still works against a single
+   * storage — `defaultAdapter` / `initialPath` decide which one.
+   *
+   * Pair with `storages` so the SFC has labels + driver hints to
+   * render even before the first API call.
+   */
+  multiStorageRoot?: boolean;
+
+  /**
+   * Storage list for `multiStorageRoot` mode. Provide name + driver
+   * + (optional) display label / read-only flag. The SFC mirrors
+   * each entry as a virtual `dir` row at "/".
+   */
+  storages?: Array<{
+    name: string;
+    label?: string;
+    driver?: string;
+    readOnly?: boolean;
+  }>;
+}
+
+/** Component emits — the parent listens for these events. */
+export interface ExplorerEmits {
+  'share-created': (payload: { path: string; url: string; pin: string | null }) => void;
+  'file-opened': (file: { path: string; basename: string }) => void;
+  error: (err: { message: string; context?: unknown }) => void;
+  'upload-progress': (p: { uploadId: string; percent: number; done: boolean }) => void;
+  'selection-change': (
+    items: Array<{ path: string; basename: string; type: 'file' | 'dir' }>,
+  ) => void;
+}

package/src/types/FileNode.ts

@@ -0,0 +1,136 @@
+/**
+ * FileNode — node shape returned by the manager endpoint.
+ *
+ * Backend `?q=index` (or `GET /api/files/manager?action=index`) returns:
+ *   { adapter, storages, dirname, files: FileNode[] }
+ */
+export interface FileNode {
+  /** DB node ID — needed by the per-user meta routes (starred, tags,
+   *  recently-opened). Backend's projectFileNodes() emits it for every
+   *  row; only client-synthesized rows (e.g. multi-storage virtual
+   *  folders) lack one. */
+  id?: number;
+  /** Full adapter-qualified path: `local://receipts/2024/invoice.pdf` */
+  path: string;
+  /** Relative basename: `invoice.pdf` */
+  basename: string;
+  /** Adapter-stripped relative path: `receipts/2024/invoice.pdf` */
+  relativePath?: string;
+  /** `file` or `dir` */
+  type: 'file' | 'dir';
+  /** Extension (lowercased, no dot). Empty string = no extension. */
+  extension?: string;
+  /** Bytes. 0 = directory. */
+  size?: number;
+  /** Unix ms (backend "last_modified"). */
+  last_modified?: number;
+  /** MIME. */
+  mime_type?: string;
+  /** Optional thumbnail URL (backend may inline). */
+  thumb_url?: string | null;
+  /** Visibility: private | public. */
+  visibility?: 'private' | 'public';
+  /** File count for directories. */
+  count?: number;
+  /** Client-side tag (localStorage or backend). */
+  starred?: boolean;
+  /** Hex color tag. */
+  color?: string | null;
+  /** Server-side trash marker. */
+  trashed?: boolean;
+  /** RBAC effective level for the current user on this entry (backend
+   *  projectFileNodes emits it when a storage has RBAC on). '' / undefined =
+   *  ACL not enforced. Used to gate edit/manage affordances client-side. */
+  perm?: 'none' | 'viewer' | 'editor' | 'owner';
+  /** Generic — any additional fields the backend wants to inline. */
+  [k: string]: unknown;
+}
+
+export interface ShareInfo {
+  uuid: string;
+  url: string;
+  password_pin?: string | null;
+  expires_at?: string | null;
+  max_downloads?: number | null;
+  downloads?: number;
+  created_at?: string;
+}
+
+export interface UploadLimits {
+  max_upload_mb: number;
+}
+
+export type ExternalServiceState = 'ok' | 'error' | 'disabled' | 'unknown';
+
+export interface ExternalServiceStatus {
+  enabled: boolean;
+  state: ExternalServiceState;
+  url?: string;
+  last_check?: string;
+  detail?: string;
+}
+
+export interface Capabilities {
+  ffmpeg?: boolean;
+  ghostscript?: boolean;
+  libreoffice?: boolean;
+  onlyoffice_url?: string | null;
+  drawio_url?: string | null;
+  convert_url?: string | null;
+  max_chunk_mb?: number;
+  upload_limit_mb?: number;
+  external?: {
+    onlyoffice?: ExternalServiceStatus;
+    drawio?: ExternalServiceStatus;
+    mermaid?: ExternalServiceStatus;
+  };
+}
+
+/** Single source of truth for "is the IdP/editor/diagram service ready?".
+ *  A capability is usable only when both flags say so — `enabled=true` but
+ *  `state='error'` means an operator turned it on but a probe just failed,
+ *  and we'd rather hide the entry than offer a button that 500s on click.
+ */
+export function isExternalUsable(s: ExternalServiceStatus | undefined): boolean {
+  return !!s && s.enabled && s.state === 'ok';
+}
+
+export interface UploadInitResponse {
+  uploadId: string;
+  parts: Array<{ partNumber: number; presignedUrl: string }>;
+  expiresAt: string;
+  s3Key?: string;
+}
+
+export interface UploadFinalizeResponse {
+  s3Key: string;
+  url?: string;
+}
+
+export interface ArchiveEntry {
+  name: string;
+  size: number;
+  isDir: boolean;
+  lastModified?: number;
+}
+
+export type ViewMode = 'list' | 'grid';
+
+export interface ClipboardState {
+  mode: 'cut' | 'copy' | null;
+  items: FileNode[];
+  sourcePath: string | null;
+}
+
+/** A soft-deleted node as returned by the filex trash listing endpoint. */
+export interface TrashEntry {
+  id: number;
+  storage_id: number;
+  storage_name?: string;
+  path: string;
+  name: string;
+  size: number;
+  mime?: string;
+  deleted_at: string;
+  ttl_days?: number | null;
+}

package/src/types/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @brftech/filex-core — public types.
+ *
+ * Types are split across two files for legacy reasons; this barrel
+ * re-exports the lot so consumers only ever need the package root.
+ */
+
+export type {
+  ExplorerConfig,
+  ExplorerEmits,
+  AuthConfig,
+  ThemeMode,
+  LocaleCode,
+  EndpointMap,
+} from './ExplorerConfig';
+
+export type {
+  FileNode,
+  ShareInfo,
+  UploadLimits,
+  Capabilities,
+  UploadInitResponse,
+  UploadFinalizeResponse,
+  ArchiveEntry,
+  ViewMode,
+  ClipboardState,
+} from './FileNode';

package/src/types/peers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Type shims for peer-style optional dependencies.
+ *
+ * These libraries are lazy-loaded via dynamic import and listed under
+ * `peerDependenciesMeta.optional` (and `optionalDependencies` for
+ * convenience). We don't want hard `@types/*` deps just to please the
+ * compiler, so we declare them as `any` here. The dynamic import call
+ * sites cast through `any` anyway.
+ *
+ * Keep in sync with packages/webcomponent/src/peers.d.ts and
+ * packages/react/src/peers.d.ts — the rolled-up `dist/index.d.ts`
+ * forwards these references and vue-tsc walks the type graph in the
+ * sibling packages, so the same shims must live there too.
+ */
+declare module 'markdown-it';
+declare module 'highlight.js';
+declare module 'monaco-editor';
+declare module '@google/model-viewer';
+declare module 'epubjs';
+declare module 'mermaid';
+declare module 'utif';
+declare module 'ag-psd';
+declare module 'pdfjs-dist';
+declare module 'pdfjs-dist/legacy/build/pdf';
+declare module 'pdfjs-dist/build/pdf.worker.min';
+declare module 'papaparse';
+declare module 'katex';
+
+/**
+ * Custom element registered by `@google/model-viewer` — keeps the
+ * compiler happy when the SFC template includes `<model-viewer>`.
+ */
+declare namespace JSX {
+  interface IntrinsicElements {
+    'model-viewer': {
+      src?: string;
+      alt?: string;
+      'auto-rotate'?: boolean | string;
+      'camera-controls'?: boolean | string;
+      'touch-action'?: string;
+      'shadow-intensity'?: string | number;
+      [key: string]: unknown;
+    };
+  }
+}