@brftech/filex-core 0.39.1 → 0.41.0

package/src/lib/dateGroups.ts

@@ -0,0 +1,197 @@
+/**
+ * dateGroups — ONE date ladder, for every view that draws one.
+ *
+ * ⚠⚠ WHY THIS FILE EXISTS. The ladder used to live inside `ListView.vue` as a
+ * private `bucketFor()`, and only the list drew headings at all: the grid and
+ * the gallery showed the same rows in the same date order with nothing naming
+ * the days. The owner asked for the headings in every view ("Ve bunu her
+ * görünümde de yapması lazım"), and the shape of that request is exactly the
+ * shape this repository keeps getting wrong — a rule copied into a second view
+ * agrees with the first on the day it is written and on no day after it.
+ * `lib/sortOrder` and `lib/listing.byFoldersFirst` are here for the same
+ * reason, after the grid and the list had already drifted once (filex lesson
+ * #67). So the ladder is written once, and List, Grid and Gallery all read it.
+ *
+ * ⚠ THE HEADING IS A CLAIM ABOUT THE ORDER. "Today / Yesterday / March 2026"
+ * over rows that are not in date order is not a grouping, it is a lie: the
+ * same heading would reappear wherever the real order happened to interleave
+ * two days. `groupingActive()` is that rule, and it is the reason grouping
+ * follows the SORT KEY rather than a switch of its own — a switch would create
+ * a state in which the key says one thing and the grouping another, and no
+ * view could honestly draw both (`lib/viewPrefs`'s header says the same).
+ *
+ * ⚠ zaman:z1 — every boundary here is a boundary in the VIEWER's zone, never
+ * the device's. A file touched at 01:00 in Istanbul belongs under "Yesterday"
+ * for a reader on UTC and under "Today" for a reader on Istanbul, and the
+ * header has to agree with the date the cell four pixels away prints. That is
+ * why the labels and the month id are taken from the caller (`useLocale`,
+ * which reads `lib/timezone`) instead of being formatted here.
+ */
+import { zonedDayNumber } from './timezone';
+
+import type { ListingOrder, SortKey } from './sortOrder';
+
+/** One rung: a stable id to compare runs by, and the words to draw. */
+export interface DateBucket {
+  id: string;
+  label: string;
+}
+
+/**
+ * What a view lends this module so the headings speak its language and read
+ * its clock. All three come straight off `useLocale(...)`.
+ */
+export interface DateGroupLabels {
+  t: (key: string) => string;
+  /** "September 2026", in the viewer's locale and zone. */
+  formatMonthYear: (value: number | Date | undefined | null) => string;
+  /** `YYYY-MM` in the viewer's zone — a bucket id, not a label. */
+  zonedYearMonth: (value: number | Date | undefined | null) => string;
+}
+
+/**
+ * THE LADDER.
+ *
+ * Today · Yesterday · This Week · This Month · then one rung per month,
+ * named ("September 2026"). Undated rows land in "No date", which the sort
+ * already parks at the end in both directions (`lib/sortOrder.byActiveKey`).
+ *
+ * Measured against the reference the owner pointed at — filex.blipnova.com,
+ * 2026-09-13, the `/recent` page, which is the only surface there that groups.
+ * Its ladder is `Today · Yesterday · <that day's date>`: one heading per
+ * calendar day for ever, taken from the browser's own clock. Ours keeps its
+ * first two rungs verbatim and then collapses, deliberately:
+ *
+ *   - a heading per day is not a grouping once a listing is long — a folder
+ *     touched file-by-file over a month draws thirty headings over thirty
+ *     single rows;
+ *   - the owner's own words name the rungs we keep: "son bir hafta, dün,
+ *     bugün, bu ay içinde vb." (last week, yesterday, today, within this
+ *     month, and so on);
+ *   - and the reference reads the DEVICE's calendar, which is the bug
+ *     `lib/timezone` exists to have fixed here.
+ *
+ * ⚠ "This Week" is the six days before yesterday (`day > today - 7`), NOT a
+ * calendar week: a Monday listing with a calendar rule would put Sunday —
+ * eighteen hours ago — under a month heading.
+ *
+ * ⚠ A stamp in the future reads best as "today". Clock skew between a storage
+ * and the reader is ordinary, and "September 2027" over the file somebody just
+ * saved is worse than a day's imprecision.
+ */
+export function dateBucketFor(d: Date | null, l: DateGroupLabels): DateBucket {
+  if (!d) return { id: 'none', label: l.t('group.no_date') };
+  const now = new Date();
+  const today = zonedDayNumber(now);
+  const day = zonedDayNumber(d);
+  if (day >= today) return { id: 'today', label: l.t('group.today') };
+  if (day === today - 1) return { id: 'yesterday', label: l.t('group.yesterday') };
+  if (day > today - 7) return { id: 'week', label: l.t('group.this_week') };
+  const ym = l.zonedYearMonth(d);
+  if (ym === l.zonedYearMonth(now)) return { id: 'month', label: l.t('group.this_month') };
+  return { id: `m-${ym}`, label: l.formatMonthYear(d) };
+}
+
+/**
+ * Is a date heading honest over THIS listing?
+ *
+ * Both halves are required and neither is cosmetic:
+ *   - the key has to be `modified`, because that is the only order in which
+ *     consecutive rows share a day;
+ *   - the listing must not be the server's RANKED answer, where the key is
+ *     still `modified` (nothing cleared it) and the rows simply are not
+ *     obeying it.
+ *
+ * Sorting by name with date headings on would be exactly the lie above, so
+ * every other key draws no headings at all — in all three views.
+ */
+export function groupingActive(key: SortKey, order: ListingOrder | undefined): boolean {
+  return order !== 'relevance' && key === 'modified';
+}
+
+/** A contiguous run of items that share a heading. `label: null` = no heading. */
+export interface DateRun<T> {
+  id: string;
+  label: string | null;
+  items: T[];
+}
+
+/** An item that is not filed under a date, and the run it belongs to instead. */
+export interface AsideRun {
+  id: string;
+  /** A heading for that run, or null/absent for a run drawn without one. */
+  label?: string | null;
+}
+
+export interface DateGroupOptions<T> {
+  /** `groupingActive(...)`. False → one unlabelled run holding everything. */
+  active: boolean;
+  /** The instant this item is filed under, or null for "no date". */
+  dateOf: (item: T) => Date | null;
+  /**
+   * Items that are NOT filed under a date — return the run they belong to, or
+   * null to bucket them by date like everything else.
+   *
+   * ⚠ This is how "folders first" survives a date sort. Folders are given a
+   * run of their own at the top rather than floating to the top of each
+   * bucket, because floating would split a bucket in two and draw "Today"
+   * twice — once over the folders, once over the files. A folder has no
+   * meaningful modification date to file under anyway. The list uses it for
+   * its pinned storage rows as well.
+   */
+  aside?: (item: T) => AsideRun | null;
+  labels: DateGroupLabels;
+}
+
+/**
+ * The grouping, in the two shapes the three views need.
+ *
+ * `runs` is for a view that renders segment by segment (the list, whose rows
+ * are already nested under a heading element). `headingBefore` is for a view
+ * that renders one flat sequence of cards and inserts a full-width heading
+ * item in front of the card that starts a run (the grid and the gallery).
+ *
+ * ⚠ They are two readings of ONE pass, not two implementations: the map is
+ * built from the runs. A view that used its own "did the bucket change since
+ * the previous card" test would be the second copy this module exists to
+ * prevent.
+ */
+export interface DateGrouping<T> {
+  /** Mirrors the `active` that was asked for — views branch on it. */
+  active: boolean;
+  runs: DateRun<T>[];
+  /** The heading to draw immediately before this item, or null. */
+  headingBefore: (item: T) => string | null;
+}
+
+export function groupByDate<T>(items: readonly T[], opts: DateGroupOptions<T>): DateGrouping<T> {
+  const runs: DateRun<T>[] = [];
+  if (!opts.active) {
+    runs.push({ id: 'all', label: null, items: [...items] });
+  } else {
+    let cur: DateRun<T> | null = null;
+    for (const item of items) {
+      const side = opts.aside?.(item) ?? null;
+      const b: { id: string; label: string | null } = side
+        ? { id: side.id, label: side.label ?? null }
+        : dateBucketFor(opts.dateOf(item), opts.labels);
+      if (!cur || cur.id !== b.id) {
+        cur = { id: b.id, label: b.label, items: [] };
+        runs.push(cur);
+      }
+      cur.items.push(item);
+    }
+  }
+  /* Identity-keyed: the items are the very objects the template loops over in
+   * the same render, so no key function has to be invented — and inventing one
+   * is how two views end up disagreeing about what "the same row" means. */
+  const firsts = new Map<T, string>();
+  for (const r of runs) {
+    if (r.label && r.items.length) firsts.set(r.items[0], r.label);
+  }
+  return {
+    active: opts.active,
+    runs,
+    headingBefore: (item: T) => firsts.get(item) ?? null,
+  };
+}

package/src/lib/destinationTree.ts

@@ -0,0 +1,235 @@
+/**
+ * destinationTree — the rules behind "choose a folder".
+ *
+ * filex had no folder chooser. Copy and move existed (cut/paste, drag between
+ * panes) but both required the destination to already be on screen, which is
+ * why there was no "Move to…" or "Copy to…" anywhere: the verb was never the
+ * missing part, the picker was. `NewDocumentModal` grew a private one-level
+ * browser for its own "where should this document go?" question, and a second
+ * private copy for Move/Copy would have been the moment the two started
+ * disagreeing about what a writable folder is.
+ *
+ * Everything here is DOM-free and synchronous so the rules can be tested
+ * without mounting anything. The component
+ * (`modals/DestinationPickerModal.vue`) owns the reactive state and the
+ * listing calls; this module owns the answers.
+ *
+ * # Wire paths
+ *
+ * A destination is an adapter-qualified wire path — `main://belgeler/2026` —
+ * exactly what `api.copy` / `api.moveAsync` take and what the backend resolves
+ * to a storage. The tree therefore spans storages, because copy and move
+ * already do: `internal/ops` streams bytes between two drivers when the source
+ * and destination storages differ. A picker that could only offer folders in
+ * the current storage would hide a capability the product already has.
+ */
+
+import type { FileNode } from '../types/FileNode';
+
+/**
+ * The browser's top level: the list of drives rather than a folder.
+ *
+ * It cannot collide with a real destination because every wire path contains
+ * `://` and this string does not. (The same sentinel and the same reasoning as
+ * NewDocumentModal's private browser, which this module is meant to replace.)
+ */
+export const DRIVES = '@@drives';
+
+/** Split `adapter://rel` into its two halves; a bare path has no adapter. */
+export function splitWire(p: string): [string, string] {
+  const i = p.indexOf('://');
+  if (i < 0) return ['', trimSlashes(p)];
+  return [p.slice(0, i), trimSlashes(p.slice(i + 3))];
+}
+
+/** Rebuild `adapter://rel`. An empty rel is the storage root. */
+export function joinWire(adapter: string, rel: string): string {
+  const r = trimSlashes(rel);
+  return r ? `${adapter}://${r}` : `${adapter}://`;
+}
+
+function trimSlashes(s: string): string {
+  return s.replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * The wire path one level up, or null when there is nowhere further up.
+ *
+ * `multiDrive` decides what sits above a storage root: with more than one
+ * storage the answer is the list of drives, with exactly one there is nothing
+ * above the root and the Up button must be disabled rather than land the user
+ * on a one-row list of the drive they are already in.
+ */
+export function parentOfWire(p: string, multiDrive: boolean): string | null {
+  if (p === DRIVES) return null;
+  const [adapter, rel] = splitWire(p);
+  if (!adapter) return null;
+  if (!rel) return multiDrive ? DRIVES : null;
+  const parts = rel.split('/');
+  parts.pop();
+  return joinWire(adapter, parts.join('/'));
+}
+
+/** The last segment of a wire path — what a breadcrumb or a row shows. */
+export function labelOfWire(p: string, drivesLabel: string): string {
+  if (p === DRIVES) return drivesLabel;
+  const [adapter, rel] = splitWire(p);
+  if (!rel) return adapter || drivesLabel;
+  const parts = rel.split('/');
+  return parts[parts.length - 1] || adapter;
+}
+
+/** Every step from the storage root down to `p`, for a clickable breadcrumb. */
+export function crumbsOfWire(p: string): Array<{ label: string; path: string }> {
+  if (p === DRIVES || !p) return [];
+  const [adapter, rel] = splitWire(p);
+  if (!adapter) return [];
+  const out = [{ label: adapter, path: joinWire(adapter, '') }];
+  if (!rel) return out;
+  let acc = '';
+  for (const seg of rel.split('/')) {
+    acc = acc ? `${acc}/${seg}` : seg;
+    out.push({ label: seg, path: joinWire(adapter, acc) });
+  }
+  return out;
+}
+
+/**
+ * May the caller write into a folder with this `perm`?
+ *
+ * ⚠ `undefined` AND `''` both mean "this storage does not enforce ACL", which
+ * is the pre-RBAC default and full access. The declared type says one of four
+ * levels, but the wire really does carry `''` for an unenforced storage, so
+ * reading both as allowed is the truthful reading and not a convenience.
+ *
+ * This is deliberately the same predicate as `FileExplorer.permCanEdit` and
+ * `NewDocumentModal.permAllowsWrite`. Two answers to "may I write here" is how
+ * a dialog ends up offering a destination the toolbar hides.
+ */
+export function permAllowsWrite(perm: string | undefined | null): boolean {
+  return perm === undefined || perm === null || perm === '' || perm === 'editor' || perm === 'owner';
+}
+
+/** Is `child` the same as, or inside, `ancestor`? Both are wire paths. */
+export function isAtOrInside(child: string, ancestor: string): boolean {
+  if (child === DRIVES || ancestor === DRIVES) return false;
+  const [ca, cr] = splitWire(child);
+  const [aa, ar] = splitWire(ancestor);
+  if (ca !== aa) return false;
+  if (ar === '') return true;
+  return cr === ar || cr.startsWith(ar + '/');
+}
+
+/**
+ * Why this folder cannot be the destination, or null when it can.
+ *
+ * `'self'` and `'descendant'` are kept apart because they need different
+ * sentences. "You cannot move a folder into itself" and "…into a folder inside
+ * it" are the two halves of the mistake, and a single message covering both
+ * reads as a riddle at the moment the person is trying to work out what they
+ * did wrong.
+ *
+ * ⚠ This is a courtesy, not a control. The same refusal exists in
+ * `internal/ops.SubmitTo` and answers 400 whatever the picker offered —
+ * measured on a live local storage 2026-09-13, where the API accepted the
+ * request and the queue worker failed it minutes later with an errno.
+ */
+export function blockedReason(
+  candidate: string,
+  moving: string[] | undefined,
+): 'self' | 'descendant' | null {
+  if (!moving || moving.length === 0) return null;
+  if (candidate === DRIVES) return null;
+  const norm = (p: string) => {
+    const [a, r] = splitWire(p);
+    return joinWire(a, r);
+  };
+  const c = norm(candidate);
+  for (const src of moving) {
+    if (!src) continue;
+    // Order matters: equality is also "inside", and the two need different
+    // sentences.
+    if (c === norm(src)) return 'self';
+    if (isAtOrInside(candidate, src)) return 'descendant';
+  }
+  return null;
+}
+
+/** One row in the picker's list. */
+export interface DestinationRow {
+  /** Wire path of the folder. */
+  path: string;
+  /** What to show — the folder's own name. */
+  label: string;
+  /** May the caller write into it? Drives the disabled Choose button. */
+  writable: boolean;
+  /** Set when this row is one of the folders being moved, or inside one. */
+  blocked: 'self' | 'descendant' | null;
+}
+
+/**
+ * Turn a listing into rows.
+ *
+ * ⚠ An unwritable folder is LISTED and stays OPENABLE. The grant that allows
+ * writing may live on a subfolder, so hiding the parent would make the
+ * destination unreachable; hiding it also tells the user their folder is gone
+ * rather than that they may not write into it. Same rule NewDocumentModal
+ * settled on.
+ *
+ * ⚠ A blocked folder (the one being moved, or inside it) is also listed rather
+ * than hidden: seeing it greyed out with a reason is how a person understands
+ * the refusal. It is not openable, because everything under it is blocked too
+ * and walking into a dead end is not navigation.
+ */
+export function destinationRows(
+  files: FileNode[] | undefined,
+  moving?: string[],
+): DestinationRow[] {
+  const out: DestinationRow[] = [];
+  for (const f of files ?? []) {
+    if (f.type !== 'dir') continue;
+    out.push({
+      path: f.path,
+      label: f.basename,
+      writable: permAllowsWrite(f.perm as string | undefined),
+      blocked: blockedReason(f.path, moving),
+    });
+  }
+  return out;
+}
+
+/** The drives level: one row per storage, each its own root. */
+export function driveRows(storages: string[] | undefined, moving?: string[]): DestinationRow[] {
+  return (storages ?? []).map((name) => {
+    const path = joinWire(name, '');
+    return {
+      path,
+      label: name,
+      // A storage root's own writability is not knowable from the drive list;
+      // it is answered by the listing when the user opens it. Offering it as
+      // writable here and letting the listing correct that is the honest
+      // order — the alternative greys out every drive until each is opened.
+      writable: true,
+      blocked: blockedReason(path, moving),
+    };
+  });
+}
+
+/**
+ * Where the picker should open.
+ *
+ * The current folder, because that is where the person is standing and most
+ * destinations are near it. Falls back to the drives list when there is more
+ * than one storage and no current folder, and to the single storage's root
+ * when there is only one.
+ */
+export function initialLocation(
+  current: string | undefined,
+  storages: string[] | undefined,
+): string {
+  const multi = (storages?.length ?? 0) > 1;
+  if (current && current.includes('://')) return current;
+  if (multi) return DRIVES;
+  const only = storages?.[0];
+  return only ? joinWire(only, '') : DRIVES;
+}

package/src/lib/downloadSelection.ts

@@ -0,0 +1,154 @@
+/**
+ * downloadSelection — hand the browser ONE archive for a set of files.
+ *
+ * # What was there before
+ *
+ * `downloadFile(n)` is `window.open(api.downloadUrl(n.path), '_blank')` — one
+ * tab, one body, one file. Five selected rows would have been five
+ * `window.open` calls, and the browser stops the second one: they are popups
+ * once the user gesture has been spent. That is the whole reason the selection
+ * bar HID Download the moment a second row was selected, rather than doing
+ * something bad with it.
+ *
+ * # Why two steps
+ *
+ * A download has to be a NAVIGATION. `fetch()` + `URL.createObjectURL(blob)`
+ * buffers the entire archive in the tab before a single byte reaches disk,
+ * which is exactly what a 4 GB selection cannot survive. Only a navigation
+ * streams.
+ *
+ * But a navigation is a GET: it carries its arguments in the URL, where 300
+ * selected paths do not fit, and it carries no `Authorization` header, which is
+ * how the embedded hosts (work.example.com, fishapp) authenticate. So the server
+ * splits it — an authenticated POST that resolves and authorizes the member
+ * list and returns a short ticket URL, then a plain navigation to that URL.
+ * `POST /api/files/archive/download` → `GET /z/<ticket>`.
+ *
+ * # Why an iframe and not window.open
+ *
+ * ⚠ The navigation happens AFTER an await. The user's gesture token is spent by
+ * then, so `window.open` at that point is a popup and gets blocked — the same
+ * failure the whole feature exists to avoid, moved one step later where it is
+ * harder to notice. `location.href = url` is not blocked, but if the server
+ * ever answers with a text error instead of an attachment the app navigates
+ * away and the user loses their place. A hidden iframe is neither: an
+ * attachment response is handed to the download manager, and an error body
+ * lands somewhere invisible.
+ */
+
+import type { FileApi } from '../composables/useFileApi';
+
+/** What the mint returns. Mirrors `archiveDownloadInfo` in the Go handler. */
+export interface ArchiveTicket {
+  /** Path to navigate to. Server-relative, e.g. `/z/<token>`. */
+  url: string;
+  ticket: string;
+  /** Filename the browser will save, e.g. `Faturalar.zip`. */
+  name: string;
+  /** How many files the archive will contain, after the server expanded any
+   *  selected folders and dropped what the caller may not read. */
+  files: number;
+  /** Uncompressed total. NOT the archive's size — see the Go handler on why
+   *  there is no such number until the last member is deflated. */
+  bytes: number;
+  expires_at: string;
+}
+
+/**
+ * The mint endpoint for a given manager URL.
+ *
+ * Derived by swapping the trailing `/manager` segment, which is how every
+ * route outside the endpoint map is built in useFileApi (`/permissions`,
+ * `/versions`, `/comments`, `/ws-ticket`). Doing it this way rather than
+ * hardcoding `/api/files/...` is what keeps a cross-origin embed working: the
+ * host configured `apiBase`, and the archive call has to land on the same
+ * origin as the rest of the explorer.
+ */
+export function archiveTicketUrl(managerUrl: string): string {
+  const base = managerUrl.split('?')[0];
+  return base.replace(/\/manager$/, '/archive/download');
+}
+
+/**
+ * Where the ticket URL should be fetched from.
+ *
+ * The server answers a server-relative `/z/<token>`, which is correct for the
+ * same-origin case and wrong for an embed whose API lives on another host. The
+ * origin comes from the manager URL, which is the one thing that is always
+ * right.
+ */
+export function absoluteTicketUrl(managerUrl: string, ticketUrl: string): string {
+  if (/^https?:\/\//i.test(ticketUrl)) return ticketUrl;
+  const base = managerUrl.split('?')[0];
+  const m = /^(https?:\/\/[^/]+)/i.exec(base);
+  return m ? m[1] + ticketUrl : ticketUrl;
+}
+
+/**
+ * Ask the server to prepare an archive of `paths` and return the ticket.
+ *
+ * Throws the same shaped error every other call in useFileApi throws — a
+ * localized `message` plus `status`/`detail` — so a caller can toast
+ * `err.message` and branch on `err.status` (409 = nothing readable in the
+ * selection, 413 = too many files).
+ */
+export async function requestArchive(
+  api: Pick<FileApi, 'jsonFetch' | 'endpoints'>,
+  paths: string[],
+  name?: string,
+): Promise<ArchiveTicket> {
+  const url = archiveTicketUrl(api.endpoints.manager);
+  return api.jsonFetch<ArchiveTicket>(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(name ? { paths, name } : { paths }),
+  });
+}
+
+/**
+ * How long a download iframe is left in the document.
+ *
+ * It only has to outlive the moment the browser reads the response headers and
+ * hands the body to its download manager; the transfer itself continues after
+ * the element is gone. Sixty seconds is slack for a storage that takes a while
+ * to produce the first byte, and is short enough that a session of repeated
+ * downloads does not accumulate frames.
+ */
+export const DOWNLOAD_FRAME_TTL_MS = 60_000;
+
+/**
+ * Navigate to `url` in a way that saves a file instead of moving the page.
+ *
+ * Exported separately from `downloadArchive` so a caller that already has a
+ * ticket (a retry, a test) can trigger it, and so the DOM half can be replaced
+ * in an environment that has no document.
+ */
+export function triggerFileNavigation(url: string, doc: Document = document): void {
+  const frame = doc.createElement('iframe');
+  frame.hidden = true;
+  frame.setAttribute('aria-hidden', 'true');
+  frame.style.display = 'none';
+  frame.src = url;
+  doc.body.appendChild(frame);
+  setTimeout(() => frame.remove(), DOWNLOAD_FRAME_TTL_MS);
+}
+
+/**
+ * Mint an archive for `paths` and start downloading it.
+ *
+ * Resolves with the ticket once the download has been STARTED — not once it has
+ * finished, which the page cannot observe. A caller that wants to say "12 files"
+ * in a toast reads it off the returned ticket.
+ */
+export async function downloadArchive(
+  api: Pick<FileApi, 'jsonFetch' | 'endpoints'>,
+  paths: string[],
+  opts: { name?: string; doc?: Document } = {},
+): Promise<ArchiveTicket> {
+  const ticket = await requestArchive(api, paths, opts.name);
+  triggerFileNavigation(
+    absoluteTicketUrl(api.endpoints.manager, ticket.url),
+    opts.doc ?? document,
+  );
+  return ticket;
+}