@brftech/filex-core 0.42.1 → 0.43.0

package/src/lib/tour.ts

@@ -0,0 +1,152 @@
+/**
+ * tour — "has this person already been offered the first-use tour?"
+ *
+ * ⚠⚠ Why this module exists (v0.43.0). The tour used to open 900 ms after
+ * EVERY explorer mount whose browser had no `filex.tourDone` flag, and the
+ * flag was written only when the tour was CLOSED. So a person who opened a
+ * second tab before closing the tour got it again; so did every new tab, every
+ * route that remounted the explorer, every other browser, every other device.
+ * A browser-automation run met it on each fresh mount and its clicks landed on
+ * the tour card one run in two. The owner's rule: the tour is offered to a
+ * PERSON once — never once per mount.
+ *
+ * The answer is kept in two places and read as ONE (an "or"):
+ *
+ *   · the account document (`lib/prefs`, key `tour`) — the person's answer,
+ *     on every browser and device that signs in as them;
+ *   · this browser's `filex.tourDone` — the answer before the account's
+ *     arrives, and the only one an embed without an account copy has.
+ *
+ * ⚠ It only ever goes one way. Nothing clears it: a tour that has been seen
+ * cannot be un-seen, and "Restart the tour" opens it without resetting it.
+ * That is why the local flag is NOT a per-person mirror cleared at sign-out —
+ * a flag that can only say "yes" cannot leak a wrong "no" to the next person.
+ *
+ * ⚠ It is recorded when the tour is OFFERED, not when it is closed. Closing
+ * was the old trigger, and it is exactly what made a second tab, opened while
+ * the first still showed the tour, offer it again.
+ */
+import {
+  currentPrefs,
+  onPrefs,
+  onPrefsSettled,
+  prefsConfigured,
+  prefsHydrated,
+  prefsSettled,
+  savePref,
+} from './prefs';
+
+/** This browser's copy. The name is the one every earlier release wrote. */
+export const TOUR_LS_KEY = 'filex.tourDone';
+
+/** The value the account document carries once the tour was offered. */
+export const TOUR_DONE = 'done';
+
+/** How long after a mount the tour opens — the listing and toolbar are laid out by then. */
+export const TOUR_DELAY_MS = 900;
+
+/**
+ * How long a mount waits for the account's answer before it decides on this
+ * browser's alone. Bounded: a server that never answers must not mean a tour
+ * that never comes, nor one that lands in the middle of somebody's work.
+ */
+export const TOUR_ACCOUNT_WAIT_MS = 5000;
+
+function seenHere(): boolean {
+  try {
+    return !!localStorage.getItem(TOUR_LS_KEY);
+  } catch {
+    // No storage (blocked site data, a private window that refuses it): never
+    // auto-nag. The tour is one menu row away for anybody who wants it.
+    return true;
+  }
+}
+
+/** Has this person — here, or on the account — already been offered the tour? */
+export function tourSeen(): boolean {
+  return seenHere() || !!currentPrefs().tour;
+}
+
+let accountWriteQueued: (() => void) | null = null;
+
+/**
+ * Record that the tour has been offered: in this browser at once, and on the
+ * account as soon as the account's document is known.
+ *
+ * ⚠⚠ Never written to the account BEFORE its document has arrived. `PUT
+ * /api/me/prefs` replaces the whole document, and a write made from an empty
+ * copy would erase the person's palette, density and language to record a
+ * tour.
+ */
+export function markTourSeen(): void {
+  try {
+    localStorage.setItem(TOUR_LS_KEY, '1');
+  } catch {
+    /* see seenHere */
+  }
+  if (!prefsConfigured()) return;
+  if (prefsHydrated()) {
+    if (!currentPrefs().tour) savePref('tour', TOUR_DONE);
+    return;
+  }
+  if (accountWriteQueued) return;
+  const off = onPrefs((p) => {
+    off();
+    accountWriteQueued = null;
+    if (!p.tour) savePref('tour', TOUR_DONE);
+  });
+  accountWriteQueued = off;
+}
+
+/**
+ * Offer the tour once, `delayMs` after a mount, unless this person has already
+ * been offered it. Returns a cancel for the unmount.
+ *
+ * With an account behind the explorer the decision waits for the account's
+ * answer (at most `accountWaitMs`), so a person who took the tour on another
+ * device is not shown it again while the answer is on its way.
+ */
+export function offerTourOnce(
+  show: () => void,
+  opts: { delayMs?: number; accountWaitMs?: number } = {},
+): () => void {
+  const delayMs = opts.delayMs ?? TOUR_DELAY_MS;
+  const waitMs = opts.accountWaitMs ?? TOUR_ACCOUNT_WAIT_MS;
+  let cancelled = false;
+  let delay: ReturnType<typeof setTimeout> | undefined;
+  let giveUp: ReturnType<typeof setTimeout> | undefined;
+  let unwait: (() => void) | undefined;
+
+  const cancel = () => {
+    cancelled = true;
+    if (delay) clearTimeout(delay);
+    if (giveUp) clearTimeout(giveUp);
+    unwait?.();
+  };
+  if (tourSeen()) return cancel;
+
+  const decide = () => {
+    if (giveUp) clearTimeout(giveUp);
+    unwait?.();
+    if (cancelled || tourSeen()) return;
+    markTourSeen();
+    show();
+  };
+
+  delay = setTimeout(() => {
+    if (cancelled || tourSeen()) return;
+    if (!prefsConfigured() || prefsSettled()) {
+      decide();
+      return;
+    }
+    giveUp = setTimeout(decide, waitMs);
+    unwait = onPrefsSettled(decide);
+  }, delayMs);
+  return cancel;
+}
+
+/** Testing seam. */
+export function resetTourState(): void {
+  accountWriteQueued?.();
+  accountWriteQueued = null;
+}

package/src/lib/trashEmpty.ts

@@ -0,0 +1,111 @@
+/**
+ * trashEmpty — "empty the trash" from the explorer's trash view, followed to
+ * the end.
+ *
+ * ⚠⚠ POST /api/admin/trash/empty used to purge inside the request, so for a
+ * large trash it never answered: nginx gave up with a 504 at sixty seconds and
+ * the view reported "504". The endpoint now answers within seconds — 200 with
+ * the final counts when the purge is done, 202 `{running: true, …}` while it
+ * goes on in the background — and GET on the same path reports the run until
+ * it ends. A 2xx is therefore not "emptied" any more; a status whose
+ * `running` is false is.
+ */
+
+/** One run as the endpoint reports it. `{running: false}` alone (no
+ *  `started_at`) is "no run known" — the server restarted under it. */
+export interface TrashEmptyStatus {
+  /** The ops row behind the run (GET /api/files/ops/{id}, and its cancel). */
+  op_id?: number;
+  running: boolean;
+  /** Waiting its turn behind another purge; `running` is true meanwhile. */
+  queued?: boolean;
+  /** Somebody stopped it; what it had not reached is still in the trash. */
+  cancelled?: boolean;
+  total?: number;
+  scanned?: number;
+  purged?: number;
+  failed?: number;
+  bytes?: number;
+  error?: string;
+  started_at?: string;
+  finished_at?: string;
+}
+
+export interface TrashEmptyIO {
+  /** POST /api/admin/trash/empty. */
+  start(): Promise<Response>;
+  /** GET /api/admin/trash/empty. */
+  status(): Promise<Response>;
+  /** The run the server started (or, on BUSY, the caller's own run it is
+   *  following) — once, whether or not it is still going. */
+  onStart?(st: TrashEmptyStatus): void;
+  /** Each look at a run that is still going. */
+  onProgress?(st: TrashEmptyStatus): void;
+  /** Another press had already started this caller's run; it is followed. */
+  onBusy?(): void;
+  /** True once nobody is watching any more — the view went away. */
+  stopped?(): boolean;
+  /** The pause between looks (a seam for tests). */
+  sleep?(ms: number): Promise<void>;
+}
+
+/** A purge holds the trash and it is not one this caller may follow. */
+export class TrashEmptyBusy extends Error {}
+
+export const TRASH_EMPTY_POLL_MS = 1500;
+
+type Json = Record<string, unknown>;
+
+async function body(res: Response): Promise<Json> {
+  try {
+    const parsed: unknown = await res.json();
+    return parsed && typeof parsed === 'object' ? (parsed as Json) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Starts the purge and resolves with its final status — or `null` once
+ * `stopped()` says nobody is watching, which ends the watching, never the
+ * purge. Throws TrashEmptyBusy, or the server's own sentence for any other
+ * refusal.
+ */
+export async function emptyTrashAndFollow(
+  io: TrashEmptyIO,
+  pollMs = TRASH_EMPTY_POLL_MS,
+): Promise<TrashEmptyStatus | null> {
+  const sleep = io.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const res = await io.start();
+  const first = await body(res);
+  let st: TrashEmptyStatus;
+  if (res.status === 409 && first.code === 'BUSY') {
+    // The server hands back the caller's own run when it is that one; a run
+    // it does not describe (another tenant's, the nightly sweep) cannot be
+    // followed from here, and must not be reported as this caller's ending.
+    const job = first.job as TrashEmptyStatus | undefined;
+    if (!job?.running) throw new TrashEmptyBusy(String(first.error ?? 'busy'));
+    io.onBusy?.();
+    st = job;
+  } else if (!res.ok) {
+    throw new Error(typeof first.error === 'string' && first.error ? first.error : String(res.status));
+  } else {
+    st = first as unknown as TrashEmptyStatus;
+  }
+  io.onStart?.(st);
+  while (st.running) {
+    io.onProgress?.(st);
+    await sleep(pollMs);
+    if (io.stopped?.()) return null;
+    try {
+      const look = await io.status();
+      const next = look.ok ? await body(look) : {};
+      // Only an answer that says whether it is running moves the state on;
+      // anything else is a look that failed.
+      if (typeof next.running === 'boolean') st = next as unknown as TrashEmptyStatus;
+    } catch {
+      // One look that failed is not the end of the run: look again.
+    }
+  }
+  return st;
+}

package/src/lib/trashTimeLeft.ts

@@ -0,0 +1,23 @@
+/**
+ * The Trash's "time left" for one item, in words: the server's own count of
+ * whole days before it is purged (`ttl_days`, trash/service.go — retention
+ * minus the days since deletion, never below zero).
+ *
+ *   30 → "30 days"   1 → "1 day"   0 → "Due for deletion"   none → "—"
+ *
+ * ⚠ ONE sentence for one concept, shared by the explorer's Trash view
+ * (ListView) and the admin panel's Trash page. They used to carry two key
+ * families for it — `trash.days_left` in the explorer's table and
+ * `trash.days_remaining` in the admin panel's — and the admin page printed
+ * "0 days" for an item the explorer called due for deletion. The keys live in
+ * the explorer's table (`trash.days_remaining`, `_one`, `_due`); a caller
+ * hands its own `t` so a surface keeps its own reactivity.
+ */
+export function trashTimeLeft(
+  ttl: number | null | undefined,
+  t: (key: string, vars?: Record<string, string | number>) => string,
+): string {
+  if (typeof ttl !== 'number' || !Number.isFinite(ttl)) return '—';
+  if (ttl <= 0) return t('trash.days_remaining_due');
+  return t('trash.days_remaining', { n: ttl });
+}