@brftech/filex-core 0.39.1 → 0.41.0

package/src/lib/shareTtl.ts

@@ -9,6 +9,8 @@
 // from the same rule. A surface that clamps differently would mean the same
 // product behaves two ways.
 
+import { formatInstant } from '../composables/useLocale'; /* zaman:z1 */
+
 export interface ExpiryOption {
   /** Days; 0 = never. */
   v: number;
@@ -75,9 +77,17 @@ export function expiryInputMax(maxDays: number | undefined, now: Date = new Date
 export function validUntilLine(expiresAt: string | null | undefined, locale: 'tr' | 'en'): string {
   if (!expiresAt) return locale === 'tr' ? 'Bu bağlantının süresi yoktur.' : 'This link does not expire.';
   const d = new Date(expiresAt);
+  // zaman:z1 — the viewer's chosen clock, not the browser's. "Valid until
+  // 14:05" is a deadline, and a deadline printed in somebody else's zone is
+  // the worst kind of wrong: it looks actionable. Both halves of that — the
+  // zone AND the locale tag — come from `formatInstant`, which is the one
+  // place either is decided. This file used to pass the zone correctly and
+  // then map the tag itself, to 'en-GB', while useLocale mapped it to
+  // 'en-US': the same deadline was spelled "20 Sept 2026, 13:53" in the share
+  // dialog and "Sep 20, 2026, 1:53 PM" in the listing behind it.
   const when = Number.isNaN(d.getTime())
     ? expiresAt
-    : d.toLocaleString(locale === 'tr' ? 'tr-TR' : 'en-GB', { dateStyle: 'medium', timeStyle: 'short' });
+    : formatInstant(d, locale, { dateStyle: 'medium', timeStyle: 'short' });
   return locale === 'tr' ? `Bu bağlantı ${when} tarihine kadar geçerli.` : `This link is valid until ${when}.`;
 }
 

package/src/lib/sortOrder.ts

@@ -0,0 +1,459 @@
+/**
+ * sortOrder — THE listing sort: one key, one direction, one comparator, for
+ * every surface that draws a folder's contents.
+ *
+ * ⚠⚠ Why this file exists at all. Before it, the sort lived as two private
+ * refs inside `ListView.vue` and the grid had none, so "sorted by size" was a
+ * fact about one component rather than about the listing: switching grid ⇄
+ * list re-ordered the rows under the user, and any second control that wanted
+ * to sort would have had to keep its own copy of the answer. That is the exact
+ * shape of filex lesson #67 — the grid and the list each holding a private
+ * copy of "folders first" and drifting apart — one level up.
+ *
+ * ⚠⚠ …and why it is no longer a module-level SINGLETON. A singleton answers
+ * "what is the sort" for the whole bundle, which is the right answer only
+ * while the bundle draws one listing. The split view draws two, side by side,
+ * and the owner's ruling (2026-09-13) is that the second pane is the first
+ * pane: it gets the same crumbs, the same filter row, the same view switcher
+ * and the same sort control. Two sort CONTROLS over one piece of state is a
+ * control that moves the listing the person is not looking at — measured the
+ * same day: with the singleton in place, choosing "Size ↓" in the right pane
+ * re-ordered the left one too.
+ *
+ * So the state is a STORE (`createSortStore`) and there is one per pane, while
+ * everything that is genuinely one answer stays module-level:
+ *
+ *   · the RULES (`byActiveKey`, `compareNodes`, folders-first, the two click
+ *     vocabularies) — written once, closed over each store;
+ *   · the LOCALE the `type` key sorts in — one alphabet for the whole bundle;
+ *   · the persisted GLOBAL DEFAULT (`filex.list-sort`) — "the last sort a
+ *     person chose", which is one fact no matter which pane they chose it in.
+ *
+ * ⚠ Panes find their store by INJECTION (`provideSortStore` / `useSortStore`),
+ * not by a prop threaded through every view: `ListView` and `FilterBar` are
+ * two levels down and an embedder may mount either on its own. With no
+ * provider — a bare `<ListView>` in a test, a host that renders one listing —
+ * `useSortStore()` hands back the default store, which IS the old singleton,
+ * so nothing that worked before changes.
+ *
+ * ⚠ Two RULES this file owns, so no caller has to remember them:
+ *
+ *   1. Folders before files, in every key and BOTH directions. `compareNodes`
+ *      applies `byFoldersFirst` as the primary comparator and never multiplies
+ *      it by the direction — multiplying would make "Name ↓" mean "files
+ *      first", i.e. the arrow would silently regroup the listing instead of
+ *      reversing it. The key only decides the order WITHIN each group.
+ *   2. One vocabulary. A column header cycles (`chooseSortKey`: a new key
+ *      arrives in its default direction, the active one flips) and a menu item
+ *      jumps (`setSort`: a named destination never reverses under you). Both
+ *      live here, so the two surfaces reach for the same words instead of each
+ *      re-deriving what a click means.
+ *
+ * ⚠ The persisted shape is the one `ListView` already wrote (`filex.list-sort`,
+ * `{key, dir}`), so a user who had sorted a column keeps that sort. The old
+ * `key: null` — "leave the backend's order alone" — is NOT a key here; see
+ * `ListingOrder` below for where that state went and why it could not be one.
+ */
+import { inject, provide, ref, type InjectionKey, type Ref } from 'vue';
+
+import type { FileNode } from '../types/FileNode';
+import type { LocaleCode } from '../types/ExplorerConfig';
+import { messages } from '../locales';
+import { typeLabelKey } from './fileIcons';
+import { byFoldersFirst } from './listing';
+
+export type SortKey = 'name' | 'type' | 'modified' | 'size';
+export type SortDir = 'asc' | 'desc';
+
+/**
+ * WHERE A LISTING'S ORDER CAME FROM — the third state the old `key: null`
+ * used to express, back as a mode rather than as a fourth key.
+ *
+ *   `sort`      — a folder's contents. The key and the direction below decide
+ *                 the order, which is what every control in the UI drives.
+ *   `relevance` — a RANKED answer. The server decided the order and it is the
+ *                 whole value of the reply; re-applying a key here buries the
+ *                 row the person came for.
+ *
+ * ⚠⚠ Why a mode and not a key. A key is a preference: it is persisted, it is
+ * named by a button, and the user picks it. "Relevance" is none of those — it
+ * is a FACT about the rows in hand, it must not outlive them, and there is no
+ * meaningful "relevance descending". Making it a fifth member of `SortKey`
+ * would have persisted it into the next folder (where nothing is ranked) and
+ * put a word in the Sort-by menu that does nothing in nine listings out of
+ * ten.
+ *
+ * ⚠⚠ …and why it is an ARGUMENT and not a field on the store. The store is a
+ * pane's preference; this is a property of the ROWS a pane happens to be
+ * holding, and one pane can be showing a search while the other shows a
+ * folder. Same pane, two navigations, two answers — the caller holding the
+ * rows is the only one that knows which it has.
+ *
+ * Measured, 2026-09-13 (qldemo, query `s`, Name ↑): the server ranked
+ * `Documents/server.ts` first and the list drew it fifteenth of seventeen,
+ * behind every alphabetically earlier row. The owner's ruling that day:
+ * ordinary search and ⌘K stay in relevance order.
+ */
+export type ListingOrder = 'sort' | 'relevance';
+
+/** The four, in the order the menu draws them. One array, so the menu and
+ *  `isSortKey` cannot disagree about how many there are. */
+export const SORT_KEYS: readonly SortKey[] = ['name', 'type', 'modified', 'size'] as const;
+
+const SORT_LS_KEY = 'filex.list-sort';
+
+/**
+ * The order the listing arrives in when nobody has chosen one.
+ *
+ * ⚠ `name` / ascending, and NOT the reference build's `modified` / descending,
+ * deliberately: the backend answers a listing name-ascending already, so this
+ * default moves nothing on screen for an existing user — and our list view
+ * draws date group headings whenever the key is `modified`, which the
+ * reference has no equivalent of. Making `modified` the default would put a
+ * heading on the first paint of every folder that nobody asked for. Changing
+ * it is this one constant; the consequence is that heading.
+ */
+const DEFAULT_KEY: SortKey = 'name';
+
+/** Dates read newest-first; everything else reads A→Z / smallest-first. */
+export function defaultSortDir(key: SortKey): SortDir {
+  return key === 'modified' ? 'desc' : 'asc';
+}
+
+function isSortKey(v: unknown): v is SortKey {
+  return typeof v === 'string' && (SORT_KEYS as readonly string[]).includes(v);
+}
+
+function readStored(): { key: SortKey; dir: SortDir } {
+  const fallback = { key: DEFAULT_KEY, dir: defaultSortDir(DEFAULT_KEY) };
+  if (typeof localStorage === 'undefined') return fallback;
+  try {
+    const raw = localStorage.getItem(SORT_LS_KEY);
+    if (!raw) return fallback;
+    const p = JSON.parse(raw) as { key?: unknown; dir?: unknown };
+    const key = isSortKey(p.key) ? p.key : DEFAULT_KEY;
+    const dir = p.dir === 'asc' || p.dir === 'desc' ? p.dir : defaultSortDir(key);
+    return { key, dir };
+  } catch {
+    return fallback; // private mode / bad JSON
+  }
+}
+
+/**
+ * The active locale, for the one comparison that needs words: `type` sorts by
+ * the label the Type column PRINTS, so "Image" and "Görsel" have to fall in
+ * their own alphabet's order.
+ *
+ * ⚠ Module-level and NOT per store, and that is deliberate even now that the
+ * key and the direction are per pane: two panes of one window are read by one
+ * person in one language. If each store carried its own resolver, the pane
+ * whose host forgot to set it would sort by a different alphabet than the pane
+ * beside it — the drift this file exists to prevent, in the one field where it
+ * would be hardest to see.
+ */
+const localeRef = ref<LocaleCode>('en');
+
+export function setSortLocale(code: LocaleCode): void {
+  localeRef.value = code;
+}
+
+// ── the comparator ────────────────────────────────────────────────────
+
+function modifiedMs(n: FileNode): number | null {
+  const v = n.last_modified;
+  if (!v) return null;
+  return v * (v < 1e12 ? 1000 : 1);
+}
+
+function nameCompare(a: FileNode, b: FileNode): number {
+  return (a.basename || '').localeCompare(b.basename || '', undefined, {
+    numeric: true,
+    sensitivity: 'base',
+  });
+}
+
+/** The word the Type column prints for this row — the thing a user sorting by
+ *  "Type" is looking at. Unmapped kinds fall back to the uppercased extension,
+ *  exactly as `typeLabelFor` does, so no row sorts as an empty string. */
+function typeLabel(n: FileNode): string {
+  const key = typeLabelKey(n);
+  if (key) {
+    const cat = messages[localeRef.value] ?? messages.en;
+    return cat[key] ?? key;
+  }
+  const ext = (n.extension || '').trim();
+  return ext ? ext.toUpperCase() : '';
+}
+
+/** The active key's own order, direction applied. Folders-first is NOT here —
+ *  it is the primary comparator in `compareNodes` and must not be reversed.
+ *
+ *  ⚠ Written ONCE and closed over each store's refs, rather than copied into
+ *  a store factory: the rule is the same in every pane and a per-pane copy of
+ *  it is how the grid and the list drifted in the first place. */
+function byActiveKey(key: SortKey, dirWord: SortDir, a: FileNode, b: FileNode): number {
+  const dir = dirWord === 'asc' ? 1 : -1;
+  switch (key) {
+    case 'name':
+      return dir * nameCompare(a, b);
+    case 'size':
+      return dir * ((a.size ?? -1) - (b.size ?? -1));
+    case 'type': {
+      const c = typeLabel(a).localeCompare(typeLabel(b), undefined, { sensitivity: 'base' });
+      // ⚠ The tiebreak is name-ASCENDING in both directions, on purpose: every
+      // image in a folder shares one label, so without it a Type sort leaves
+      // whole runs in whatever order the backend happened to answer, and
+      // "Type ↓" would scramble them again rather than reverse the groups.
+      return c !== 0 ? dir * c : nameCompare(a, b);
+    }
+    default: {
+      const am = modifiedMs(a);
+      const bm = modifiedMs(b);
+      // Undated rows go last in BOTH directions, so date groups stay clean.
+      if (am == null && bm == null) return 0;
+      if (am == null) return 1;
+      if (bm == null) return -1;
+      return dir * (am - bm);
+    }
+  }
+}
+
+// ── the store ─────────────────────────────────────────────────────────
+
+/**
+ * One pane's sort. Everything a surface needs to READ the order, to CHANGE it
+ * from either of the two control vocabularies, and to sort rows by it.
+ *
+ * ⚠ `key` and `dir` are exposed as refs so a `computed` that reads them
+ * subscribes to the next change — the property the module-level singleton had
+ * and the reason every listing re-sorted itself for free.
+ */
+export interface SortStore {
+  readonly key: Ref<SortKey>;
+  readonly dir: Ref<SortDir>;
+  /** Set both halves outright. `dir` omitted → the key's own default. */
+  setSort(key: SortKey, dir?: SortDir): void;
+  /** Restore a remembered sort WITHOUT recording it as a fresh choice. */
+  applySort(key: SortKey, dir: SortDir): void;
+  /** Same order, other way round. The direction button's whole job. */
+  toggleSortDir(): void;
+  /** A column header click — see `chooseSortKey` below. */
+  chooseSortKey(key: SortKey): void;
+  /** Folders first, then the active key. Subscribes the reader. */
+  compareNodes(a: FileNode, b: FileNode): number;
+  /** THE comparator for a listing, given where its order came from. */
+  compareInOrder(order: ListingOrder): (a: FileNode, b: FileNode) => number;
+  /** The listing, in its order. A COPY. */
+  sortListing(files: FileNode[], order?: ListingOrder): FileNode[];
+}
+
+function persist(key: SortKey, dir: SortDir): void {
+  try {
+    localStorage.setItem(SORT_LS_KEY, JSON.stringify({ key, dir }));
+  } catch {
+    /* quota / private mode — the in-memory refs still moved */
+  }
+}
+
+/**
+ * A fresh sort store, seeded from the global default.
+ *
+ * ⚠⚠ Every store WRITES the global default when a person chooses in it, and
+ * that is the point rather than an oversight: `filex.list-sort` is defined as
+ * "the last sort a person chose", and a choice made in the right-hand pane is
+ * still a choice. What must not happen — and does not, because the refs are
+ * per store — is the OTHER pane moving when it does. Measured 2026-09-13:
+ * sorting the split pane by Size left the main pane on Name ↑ and made Size
+ * the arrangement the next unconfigured folder opens in.
+ */
+export function createSortStore(): SortStore {
+  const stored = readStored();
+  const key = ref<SortKey>(stored.key);
+  const dir = ref<SortDir>(stored.dir);
+
+  function setSort(k: SortKey, d?: SortDir): void {
+    key.value = k;
+    dir.value = d ?? defaultSortDir(k);
+    persist(key.value, dir.value);
+  }
+
+  /**
+   * tablo:t1 — RESTORE a sort that was already the person's, without recording
+   * it as a fresh choice.
+   *
+   * ⚠⚠ The difference from `setSort` is the whole point and it is not
+   * cosmetic. `filex.list-sort` is the GLOBAL default — "what a folder I have
+   * never set up opens as" — and per-folder memory (`lib/viewPrefs`) is
+   * layered on top of it. If applying a folder's remembered sort went through
+   * `setSort`, walking into one folder that is sorted by size would quietly
+   * make Size the default for every folder in the product, and the person
+   * would have no idea which folder did it. Restoring is not choosing; only a
+   * choice writes the default.
+   */
+  function applySort(k: SortKey, d: SortDir): void {
+    key.value = k;
+    dir.value = d;
+  }
+
+  function toggleSortDir(): void {
+    dir.value = dir.value === 'asc' ? 'desc' : 'asc';
+    persist(key.value, dir.value);
+  }
+
+  /**
+   * A COLUMN HEADER click: a new key arrives in its own default direction, the
+   * key already active flips.
+   *
+   * ⚠ Not what the Sort-by menu calls — see `setSort`. A header is a toggle
+   * (click Name twice and you expect Z→A); a menu item is a destination (pick
+   * Name twice and you expect Name, still). Both meanings are written here so
+   * neither surface has to invent one.
+   */
+  function chooseSortKey(k: SortKey): void {
+    if (key.value === k) toggleSortDir();
+    else setSort(k);
+  }
+
+  function compareNodesFn(a: FileNode, b: FileNode): number {
+    return byFoldersFirst(a, b) || byActiveKey(key.value, dir.value, a, b);
+  }
+
+  function compareInOrderFn(order: ListingOrder): (a: FileNode, b: FileNode) => number {
+    return order === 'relevance' ? byFoldersFirst : compareNodesFn;
+  }
+
+  return {
+    key,
+    dir,
+    setSort,
+    applySort,
+    toggleSortDir,
+    chooseSortKey,
+    compareNodes: compareNodesFn,
+    compareInOrder: compareInOrderFn,
+    sortListing: (files: FileNode[], order: ListingOrder = 'sort') =>
+      [...(files || [])].sort(compareInOrderFn(order)),
+  };
+}
+
+/**
+ * The store a surface gets when nobody provided one: a bare `<ListView>` in a
+ * test, an embedder mounting one listing, and the explorer's own MAIN pane —
+ * which keeps using it so that everything already reading the module-level
+ * functions below (per-folder view memory, `displayFiles`) is talking about
+ * the same state the main pane's controls drive.
+ */
+const defaultStore = createSortStore();
+
+export const SORT_STORE_KEY: InjectionKey<SortStore> = Symbol('fe-sort-store');
+
+/** Hand this subtree its own sort. Called by the pane component, once. */
+export function provideSortStore(store: SortStore): void {
+  provide(SORT_STORE_KEY, store);
+}
+
+/**
+ * THE store for the surface calling it.
+ *
+ * ⚠ Must be called during `setup()` (it injects). Surfaces hold the result and
+ * read `.key` / `.dir` inside their computeds, which is what subscribes them.
+ */
+export function useSortStore(): SortStore {
+  return inject(SORT_STORE_KEY, defaultStore);
+}
+
+// ── the default store's API, as free functions ────────────────────────
+//
+// Everything below is the module-level API this file shipped with, now a thin
+// pass-through to the default store. Kept — not deprecated — because the sort
+// is genuinely one answer for a host that draws ONE listing, which is every
+// embed except the split view, and because the explorer's per-folder view
+// memory reads and writes exactly this state for its main pane.
+
+export function activeSortKey(): SortKey {
+  return defaultStore.key.value;
+}
+
+export function activeSortDir(): SortDir {
+  return defaultStore.dir.value;
+}
+
+export function setSort(key: SortKey, dir?: SortDir): void {
+  defaultStore.setSort(key, dir);
+}
+
+export function applySort(key: SortKey, dir: SortDir): void {
+  defaultStore.applySort(key, dir);
+}
+
+/**
+ * tablo:t1 — THE GLOBAL DEFAULT: the sort a folder nobody has configured opens
+ * in. Re-read from storage rather than mirrored in a second ref, because
+ * `setSort` writes there and `applySort` deliberately does not — so the stored
+ * value IS "the last sort a person chose", which is exactly the definition of
+ * the default, and a mirror could only drift from it.
+ */
+export function globalSort(): { key: SortKey; dir: SortDir } {
+  return readStored();
+}
+
+export function toggleSortDir(): void {
+  defaultStore.toggleSortDir();
+}
+
+export function chooseSortKey(key: SortKey): void {
+  defaultStore.chooseSortKey(key);
+}
+
+/**
+ * The whole rule, in order: folders before files, then the active key.
+ *
+ * Reading this subscribes the caller to the sort state, so a `computed` built
+ * on it re-runs when the key or the direction changes.
+ */
+export function compareNodes(a: FileNode, b: FileNode): number {
+  return defaultStore.compareNodes(a, b);
+}
+
+/**
+ * THE comparator for a listing, given where its order came from. Every
+ * surface that draws rows asks this one question; none of them re-derives the
+ * answer, which is the whole reason this module exists.
+ *
+ * ⚠⚠ `relevance` is `byFoldersFirst` and NOTHING ELSE — deliberately the
+ * exact function `GridView` already sorts by, so the grid needs no knowledge
+ * of relevance at all and cannot drift from the list. `web/tests/lib/
+ * searchRelevanceOrder.test.ts` asserts that identity; if this ever returns
+ * something else, that test goes red and names GridView as the file that has
+ * to change in the same commit. Teaching one view about relevance and leaving
+ * the other sorting is filex lesson #67 one level up.
+ *
+ * ⚠ Folders still come FIRST in a ranked set, and that is a decision, not an
+ * oversight. Folders-first is not a sort here, it is a GROUPING: the grid
+ * draws it as two labelled sections ("Folders" / "Files"), so a result set
+ * that interleaved them would make the grid's own headings false. The ranking
+ * is kept in full INSIDE each group — `Array#sort` is stable and this
+ * comparator returns 0 for any two rows of the same kind — which is as much
+ * relevance as a surface that groups folders can honestly offer. The cost is
+ * visible and bounded: a folder that ranked seventh is drawn above the file
+ * that ranked first. The alternative costs the grid its sections.
+ */
+export function compareInOrder(order: ListingOrder): (a: FileNode, b: FileNode) => number {
+  return defaultStore.compareInOrder(order);
+}
+
+/**
+ * The listing, in its order. A COPY — the caller's array is usually a prop or
+ * a computed's source and sorting it in place mutates somebody else's state.
+ *
+ * `Array#sort` is stable, so rows the comparator calls equal keep the order
+ * they arrived in — which is precisely what carries the server's ranking
+ * through `relevance` mode.
+ *
+ * ⚠ `order` defaults to `'sort'`: an omitted argument is how every caller
+ * holding an ordinary folder listing asks for the active key, and that is the
+ * overwhelming majority of them.
+ */
+export function sortListing(files: FileNode[], order: ListingOrder = 'sort'): FileNode[] {
+  return defaultStore.sortListing(files, order);
+}