@brftech/filex-core 0.4.2 → 0.6.0

package/src/composables/useOperations.ts

@@ -0,0 +1,291 @@
+/**
+ * useOperations — unified long-running-operation store (wiring:c3).
+ *
+ * One presentation-level aggregation point for everything that used to be
+ * scattered across corner UIs:
+ *   - uploads        (useUploadChunked jobs / legacy multipart rows)
+ *   - ops-queue jobs (usePendingOps copy/move/delete worker ops)
+ *   - future kinds   (convert / archive — same `sync()` contract, own group)
+ *
+ * The store does NOT talk to the network. Publishers (renderless
+ * UploadProgress / PendingOpsTray adapters) reconcile their reactive source
+ * lists into the store via `sync(group, items)`; OperationsCenter renders the
+ * merged picture (badge + panel). Action callbacks (cancel/retry/dismiss)
+ * are registered per row so the panel can route user intent back to the
+ * owning surface without the store knowing any transport details.
+ *
+ * Lifecycle rules (per the İşlem Merkezi contract):
+ *   - running rows live in `active`;
+ *   - done/aborted rows linger in `active` for DONE_LINGER_MS ("bitti"
+ *     flash) then move to `history` (session-only, capped);
+ *   - error rows are STICKY: they stay in `active` until the user
+ *     dismisses or retries them — even after the source list swept them
+ *     (usePendingOps drops terminal ops after its RETAIN window).
+ */
+
+import { computed, getCurrentScope, onScopeDispose, ref } from 'vue';
+
+export type OperationKind = 'upload' | 'copy' | 'move' | 'delete' | 'convert' | 'archive';
+export type OperationStatus = 'running' | 'done' | 'error' | 'aborted';
+
+/** What a publisher hands to `sync()` for one row. */
+export interface OperationInput {
+  /** Stable id within the group (upload uuid / ops row id). */
+  id: string | number;
+  kind: OperationKind;
+  /** Primary label — file name or target path. '' → renderer falls back to the kind verb. */
+  name: string;
+  /** 0..100, or null for indeterminate (renderer shows a spinner). */
+  percent: number | null;
+  status: OperationStatus;
+  error?: string | null;
+  /** Queue op accepted but not started yet ("Sırada"). */
+  queued?: boolean;
+  /** Progress counters for queue ops (3/5 items). */
+  doneCount?: number;
+  totalCount?: number;
+  /** Byte progress for uploads. */
+  uploadedBytes?: number;
+  totalBytes?: number;
+  cancellable?: boolean;
+  retryable?: boolean;
+}
+
+export interface OperationActions {
+  cancel?: () => void;
+  /** Clean the row out of the OWNING source list (called on retire/dismiss). */
+  dismiss?: () => void;
+  retry?: () => void;
+}
+
+export interface Operation {
+  /** `${group}:${id}` — unique across publishers. */
+  key: string;
+  kind: OperationKind;
+  name: string;
+  percent: number | null;
+  status: OperationStatus;
+  error: string | null;
+  queued: boolean;
+  doneCount: number | null;
+  totalCount: number | null;
+  uploadedBytes: number | null;
+  totalBytes: number | null;
+  cancellable: boolean;
+  retryable: boolean;
+  startedAt: number;
+  settledAt: number | null;
+}
+
+const DONE_LINGER_MS = 4000;
+const HISTORY_CAP = 50;
+
+function toOperation(key: string, input: OperationInput, prev?: Operation): Operation {
+  const terminal = input.status !== 'running';
+  return {
+    key,
+    kind: input.kind,
+    name: input.name,
+    percent: input.percent,
+    status: input.status,
+    error: input.error ?? null,
+    queued: input.queued ?? false,
+    doneCount: input.doneCount ?? null,
+    totalCount: input.totalCount ?? null,
+    uploadedBytes: input.uploadedBytes ?? null,
+    totalBytes: input.totalBytes ?? null,
+    cancellable: input.cancellable ?? false,
+    retryable: input.retryable ?? false,
+    startedAt: prev?.startedAt ?? Date.now(),
+    settledAt: prev?.settledAt ?? (terminal ? Date.now() : null),
+  };
+}
+
+export function useOperations() {
+  const active = ref<Operation[]>([]);
+  const history = ref<Operation[]>([]);
+
+  const actions = new Map<string, OperationActions>();
+  /** Keys already moved to history — sync must not resurrect them. */
+  const retired = new Set<string>();
+  const lingerTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  function clearTimer(key: string) {
+    const tm = lingerTimers.get(key);
+    if (tm !== undefined) {
+      clearTimeout(tm);
+      lingerTimers.delete(key);
+    }
+  }
+
+  /** Move a row from active to the session history (newest first). */
+  function retire(key: string, opts: { toHistory?: boolean } = {}) {
+    clearTimer(key);
+    const idx = active.value.findIndex((o) => o.key === key);
+    if (idx === -1) return;
+    const [op] = active.value.splice(idx, 1);
+    active.value = [...active.value];
+    retired.add(key);
+    if (opts.toHistory !== false) {
+      history.value = [{ ...op, settledAt: op.settledAt ?? Date.now() }, ...history.value].slice(
+        0,
+        HISTORY_CAP,
+      );
+    }
+  }
+
+  function scheduleLinger(key: string) {
+    if (lingerTimers.has(key)) return;
+    lingerTimers.set(
+      key,
+      setTimeout(() => {
+        lingerTimers.delete(key);
+        // Retire + ask the owning source to drop its row so it doesn't
+        // resurrect on the next sync (uploads keep done rows forever).
+        const acts = actions.get(key);
+        retire(key);
+        acts?.dismiss?.();
+      }, DONE_LINGER_MS),
+    );
+  }
+
+  /**
+   * Full-list reconcile for one publisher group. Upserts every present row,
+   * removes vanished ones (sticky errors excepted), and manages the
+   * done-linger → history hand-off.
+   */
+  function sync(
+    group: string,
+    items: Array<{ input: OperationInput; actions?: OperationActions }>,
+  ): void {
+    const prefix = `${group}:`;
+    const present = new Set<string>();
+    let next = [...active.value];
+    let changed = false;
+
+    for (const item of items) {
+      const key = `${group}:${item.input.id}`;
+      present.add(key);
+      if (item.actions) actions.set(key, item.actions);
+      if (retired.has(key)) continue; // already history — don't resurrect
+      const idx = next.findIndex((o) => o.key === key);
+      const op = toOperation(key, item.input, idx === -1 ? undefined : next[idx]);
+      if (idx === -1) {
+        next = [op, ...next];
+        changed = true;
+      } else if (JSON.stringify(next[idx]) !== JSON.stringify(op)) {
+        next[idx] = op;
+        changed = true;
+      }
+      if (op.status === 'done' || op.status === 'aborted') scheduleLinger(key);
+    }
+
+    // Vanished from source: running → drop silently (superseded elsewhere),
+    // done/aborted → straight to history, error → sticky (keep visible).
+    for (const o of [...next]) {
+      if (!o.key.startsWith(prefix) || present.has(o.key)) continue;
+      if (o.status === 'error') continue;
+      clearTimer(o.key);
+      next = next.filter((x) => x.key !== o.key);
+      changed = true;
+      if (o.status !== 'running') {
+        retired.add(o.key);
+        history.value = [{ ...o, settledAt: o.settledAt ?? Date.now() }, ...history.value].slice(
+          0,
+          HISTORY_CAP,
+        );
+      }
+    }
+
+    // Bookkeeping: retired keys whose source rows are gone can be forgotten
+    // (their ids won't reappear — uuids / monotonic op ids).
+    for (const key of [...retired]) {
+      if (key.startsWith(prefix) && !present.has(key)) retired.delete(key);
+    }
+    for (const key of [...actions.keys()]) {
+      if (key.startsWith(prefix) && !present.has(key) && !active.value.some((o) => o.key === key)) {
+        // keep actions for rows still on screen (sticky errors)
+        if (!next.some((o) => o.key === key)) actions.delete(key);
+      }
+    }
+
+    if (changed) active.value = next;
+  }
+
+  function cancel(key: string) {
+    actions.get(key)?.cancel?.();
+  }
+
+  function retry(key: string) {
+    const acts = actions.get(key);
+    retire(key); // failed attempt goes to history; retry publishes a fresh row
+    acts?.dismiss?.();
+    acts?.retry?.();
+  }
+
+  function dismiss(key: string) {
+    const acts = actions.get(key);
+    retire(key);
+    acts?.dismiss?.();
+  }
+
+  function clearHistory() {
+    history.value = [];
+  }
+
+  const runningCount = computed(
+    () => active.value.filter((o) => o.status === 'running').length,
+  );
+  const errorCount = computed(() => active.value.filter((o) => o.status === 'error').length);
+  const hasError = computed(() => errorCount.value > 0);
+
+  /**
+   * Aggregate progress across determinate running rows (uploads weighted by
+   * bytes, queue ops by item counts). null → nothing determinate is running
+   * (badge ring spins instead of filling).
+   */
+  const overallPercent = computed<number | null>(() => {
+    const running = active.value.filter((o) => o.status === 'running');
+    let sum = 0;
+    let n = 0;
+    for (const o of running) {
+      let frac: number | null = null;
+      if (o.totalBytes && o.totalBytes > 0) {
+        frac = Math.min(1, (o.uploadedBytes ?? 0) / o.totalBytes);
+      } else if (o.totalCount && o.totalCount > 0) {
+        frac = Math.min(1, (o.doneCount ?? 0) / o.totalCount);
+      } else if (o.percent !== null) {
+        frac = Math.min(1, o.percent / 100);
+      }
+      if (frac !== null) {
+        sum += frac;
+        n += 1;
+      }
+    }
+    if (n === 0) return null;
+    return Math.round((sum / n) * 100);
+  });
+
+  if (getCurrentScope()) {
+    onScopeDispose(() => {
+      for (const tm of lingerTimers.values()) clearTimeout(tm);
+      lingerTimers.clear();
+    });
+  }
+
+  return {
+    active,
+    history,
+    runningCount,
+    errorCount,
+    hasError,
+    overallPercent,
+    sync,
+    cancel,
+    retry,
+    dismiss,
+    clearHistory,
+  };
+}
+
+export type OperationsStore = ReturnType<typeof useOperations>;

package/src/composables/useTabs.ts

@@ -0,0 +1,222 @@
+/**
+ * useTabs — wiring:d1 sekmeler (çalışma alanı tab şeridi).
+ *
+ * A LAYER ABOVE FileExplorer's location state, never a replacement for
+ * it: each tab is a location snapshot `{ id, path, viewMode, split }`.
+ * The composable performs no fetching and owns no navigation — the host
+ * activates a tab by running its EXISTING `load(path)` pipeline and
+ * reports navigations back through `syncActive()`, which keeps the
+ * active snapshot glued to wherever the user actually is.
+ *
+ * `path` is stored in the SAME form as FileExplorer's `currentPath`
+ * (virtual `<storage>/<rel>` in multi-storage mode, bare relative path
+ * in single-storage mode) — i.e. the exact string `load(path)` accepts.
+ * Storing the wire form (`adapter://rel`) instead would break the
+ * rootPath-floor clamp inside load() (the floor is compared in user-path
+ * form), so the user-path form is deliberate.
+ *
+ * Persistence: localStorage under a host-supplied key (the host derives
+ * it from the pathPersist scope: disabled when `pathPersist: 'none'`,
+ * suffixed with the rootPath confine so embedded instances with
+ * different confines never clobber each other). Schema:
+ *
+ *   { "v": 1, "active": "<id>",
+ *     "tabs": [ { "id", "path", "viewMode", "split": {"path"}|null } ] }
+ */
+
+import { computed, ref, watch, type Ref } from 'vue';
+import type { ViewMode } from '../types/FileNode';
+
+/** Per-tab split state — the secondary pane's own location. */
+export interface TabSplit {
+  path: string;
+}
+
+export interface TabState {
+  id: string;
+  /** Location snapshot in `currentPath` form (see module docs). */
+  path: string;
+  viewMode: ViewMode;
+  split: TabSplit | null;
+}
+
+export interface UseTabsOptions {
+  /** localStorage key; null disables persistence entirely. */
+  storageKey: string | null;
+}
+
+function makeId(): string {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `t${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+}
+
+export function useTabs(opts: UseTabsOptions) {
+  const tabs: Ref<TabState[]> = ref([]);
+  const activeId = ref<string>('');
+
+  const activeTab = computed<TabState | null>(
+    () => tabs.value.find((t) => t.id === activeId.value) ?? null,
+  );
+  const activeIndex = computed(() => tabs.value.findIndex((t) => t.id === activeId.value));
+  const hasMultiple = computed(() => tabs.value.length > 1);
+
+  // ------------------------------------------------------------------
+  // Persistence
+  // ------------------------------------------------------------------
+
+  /** Restore from storage. Returns true when at least one tab loaded. */
+  function restore(): boolean {
+    if (!opts.storageKey) return false;
+    try {
+      const raw = localStorage.getItem(opts.storageKey);
+      if (!raw) return false;
+      const parsed = JSON.parse(raw) as { v?: unknown; active?: unknown; tabs?: unknown };
+      if (!parsed || !Array.isArray(parsed.tabs) || parsed.tabs.length === 0) return false;
+      const clean: TabState[] = [];
+      for (const t of parsed.tabs as Array<Record<string, unknown>>) {
+        if (!t || typeof t.path !== 'string') continue;
+        // ViewMode is validated loosely on purpose: future modes (e.g. the
+        // gallery wave) must survive a round-trip through an older schema.
+        const vm =
+          typeof t.viewMode === 'string' && t.viewMode ? (t.viewMode as ViewMode) : 'list';
+        const rawSplit = t.split as { path?: unknown } | null | undefined;
+        const split =
+          rawSplit && typeof rawSplit === 'object' && typeof rawSplit.path === 'string'
+            ? { path: rawSplit.path }
+            : null;
+        clean.push({
+          id: typeof t.id === 'string' && t.id ? t.id : makeId(),
+          path: t.path,
+          viewMode: vm,
+          split,
+        });
+      }
+      if (clean.length === 0) return false;
+      tabs.value = clean;
+      activeId.value = clean.some((t) => t.id === parsed.active)
+        ? String(parsed.active)
+        : clean[0].id;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function persist(): void {
+    if (!opts.storageKey) return;
+    try {
+      localStorage.setItem(
+        opts.storageKey,
+        JSON.stringify({ v: 1, active: activeId.value, tabs: tabs.value }),
+      );
+    } catch {
+      /* private mode / quota */
+    }
+  }
+
+  watch([tabs, activeId], persist, { deep: true });
+
+  // ------------------------------------------------------------------
+  // Mutations
+  // ------------------------------------------------------------------
+
+  /** Create the first tab (no-op once any tab exists). */
+  function seed(path: string, viewMode: ViewMode): void {
+    if (tabs.value.length > 0) return;
+    const t: TabState = { id: makeId(), path, viewMode, split: null };
+    tabs.value = [t];
+    activeId.value = t.id;
+  }
+
+  /** Update the ACTIVE tab's snapshot (navigation / view-mode change). */
+  function syncActive(patch: Partial<Pick<TabState, 'path' | 'viewMode'>>): void {
+    const t = activeTab.value;
+    if (!t) return;
+    if (patch.path !== undefined) t.path = patch.path;
+    if (patch.viewMode !== undefined) t.viewMode = patch.viewMode;
+  }
+
+  /** Open a new tab right after the active one (browser convention). */
+  function openTab(
+    path: string,
+    o: { viewMode: ViewMode; background?: boolean; split?: TabSplit | null },
+  ): TabState {
+    const t: TabState = { id: makeId(), path, viewMode: o.viewMode, split: o.split ?? null };
+    const idx = activeIndex.value;
+    tabs.value.splice(idx === -1 ? tabs.value.length : idx + 1, 0, t);
+    if (!o.background) activeId.value = t.id;
+    return t;
+  }
+
+  /**
+   * Close a tab. The last remaining tab never closes. Returns the tab
+   * the host must ACTIVATE (right neighbour, else left) when the active
+   * one was closed; null when the visible location is unchanged.
+   */
+  function closeTab(id: string): TabState | null {
+    if (tabs.value.length <= 1) return null;
+    const idx = tabs.value.findIndex((t) => t.id === id);
+    if (idx === -1) return null;
+    const wasActive = tabs.value[idx].id === activeId.value;
+    tabs.value.splice(idx, 1);
+    if (!wasActive) return null;
+    const next = tabs.value[Math.min(idx, tabs.value.length - 1)];
+    activeId.value = next.id;
+    return next;
+  }
+
+  /** Make a tab active. Returns it when the active tab actually changed. */
+  function activate(id: string): TabState | null {
+    const t = tabs.value.find((x) => x.id === id);
+    if (!t || t.id === activeId.value) return null;
+    activeId.value = t.id;
+    return t;
+  }
+
+  /** Cycle: +1 = next, -1 = previous (wraps). */
+  function step(delta: number): TabState | null {
+    if (tabs.value.length < 2) return null;
+    const idx = activeIndex.value === -1 ? 0 : activeIndex.value;
+    const next = tabs.value[(idx + delta + tabs.value.length) % tabs.value.length];
+    return activate(next.id);
+  }
+
+  /** Drag-sort support: move the tab at `from` to position `to`. */
+  function move(from: number, to: number): void {
+    if (from === to) return;
+    if (from < 0 || to < 0 || from >= tabs.value.length || to >= tabs.value.length) return;
+    const list = [...tabs.value];
+    const [t] = list.splice(from, 1);
+    list.splice(to, 0, t);
+    tabs.value = list;
+  }
+
+  /** Set (or clear with null) the ACTIVE tab's split state. */
+  function setSplit(split: TabSplit | null): void {
+    const t = activeTab.value;
+    if (!t) return;
+    t.split = split;
+  }
+
+  return {
+    tabs,
+    activeId,
+    activeTab,
+    activeIndex,
+    hasMultiple,
+    restore,
+    seed,
+    syncActive,
+    openTab,
+    closeTab,
+    activate,
+    step,
+    move,
+    setSplit,
+  };
+}
+
+export type TabsApi = ReturnType<typeof useTabs>;

package/src/index.ts

@@ -82,3 +82,54 @@ export {
 
 // ——— Locale catalogue (consumers may merge their own keys) ———
 export { messages, tr, en } from './locales';
+
+/* wiring:c1 — theme registry + gallery (hosts can list/apply themes programmatically) */
+export {
+  THEMES,
+  THEME_LS_KEY,
+  DEFAULT_THEME_ID,
+  themeById,
+  useThemeState,
+  setTheme,
+  applyThemeToEl,
+  syncThemeStyle,
+  generateThemeCss,
+} from './lib/themes';
+export type { ThemeDef, ThemeTokenMap } from './lib/themes';
+export { default as ThemeGallery } from './components/ThemeGallery.vue';
+/* wiring:c2 — customizable shortcut registry + settings/quick-look UI */
+export {
+  SHORTCUT_ACTIONS,
+  useShortcutList,
+  effectiveCombo,
+  setShortcutOverride,
+  resetShortcut,
+  resetAllShortcuts,
+  findShortcutConflict,
+  comboFromEvent,
+} from './composables/useKeyboardShortcuts';
+export type {
+  ShortcutActionDef,
+  ShortcutView,
+  ShortcutConflict,
+} from './composables/useKeyboardShortcuts';
+export { default as ShortcutSettings } from './components/ShortcutSettings.vue';
+export { default as QuickLook } from './components/QuickLook.vue';
+/* /wiring:c2 */
+/* wiring:c3 — unified operations center (badge + panel + store) */
+export { useOperations } from './composables/useOperations';
+export type {
+  Operation,
+  OperationInput,
+  OperationActions,
+  OperationKind,
+  OperationStatus,
+  OperationsStore,
+} from './composables/useOperations';
+export { default as OperationsCenter } from './components/OperationsCenter.vue';
+/* wiring:d1 — sekmeler + split panel */
+export { useTabs } from './composables/useTabs';
+export type { TabState, TabSplit, TabsApi } from './composables/useTabs';
+export { default as TabBar } from './components/TabBar.vue';
+export { default as SecondaryPane } from './components/SecondaryPane.vue';
+/* /wiring:d1 */

package/src/lib/dragGhost.ts

@@ -0,0 +1,41 @@
+/**
+ * dragGhost — wiring:c4 custom HTML5 drag image.
+ *
+ * The browser default drag image (a translucent snapshot of the row/card)
+ * reads poorly for multi-selection drags. This builds a small pill with the
+ * dragged item's name and, for multi-drags, a count badge, parks it
+ * off-screen (setDragImage requires a rendered element), and removes it on
+ * the next tick. Purely visual — the dataTransfer payload is untouched.
+ *
+ * Styled by `.fe-dragghost` in base.css via the `--fe-*` tokens published
+ * at :root (and re-published at `.dark`/html level for dark hosts), so it
+ * matches the active theme even though it's appended to <body>.
+ */
+export function applyDragGhost(ev: DragEvent, name: string, count: number): void {
+  const dt = ev.dataTransfer;
+  if (!dt || typeof document === 'undefined' || typeof dt.setDragImage !== 'function') return;
+  try {
+    const el = document.createElement('div');
+    el.className = 'fe-dragghost';
+    const label = document.createElement('span');
+    label.className = 'fe-dragghost__name';
+    label.textContent = name;
+    el.appendChild(label);
+    if (count > 1) {
+      const badge = document.createElement('span');
+      badge.className = 'fe-dragghost__badge';
+      badge.textContent = String(count);
+      el.appendChild(badge);
+    }
+    el.style.position = 'fixed';
+    el.style.top = '-1000px';
+    el.style.left = '-1000px';
+    document.body.appendChild(el);
+    dt.setDragImage(el, 14, 14);
+    // The engine snapshots the element synchronously during dragstart —
+    // safe to drop it right after.
+    setTimeout(() => el.remove(), 0);
+  } catch {
+    /* non-critical visual nicety — native ghost remains */
+  }
+}