@brftech/filex-core 0.41.2 → 0.42.0

package/src/composables/useRowTouch.ts

@@ -1,34 +1,45 @@
 /**
- * useRowTouch — the one touch grammar every file view speaks (list, grid,
- * gallery).
+ * useRowTouch — the one click and touch grammar every file view speaks (list,
+ * grid, gallery).
  *
- * A mouse selects with a click and opens with a double-click. A finger has no
- * double-click: the browser swallows the second tap into a zoom or never sends
- * `dblclick` at all, so on a phone the desktop grammar left nothing openable
- * (issue #26). What a finger does instead is what every mobile file manager
- * does:
+ * The rule (issue #26, fourth round — the reporter's words: "only clicking on
+ * checkbox selects it, any other click will open"), the same on every device:
  *
- *   - a long press opens the item's menu (and, through it, selects the item);
- *   - a tap is reported AS a tap, so the host can open instead of select.
+ *   - the item's CHECKBOX selects: a tick adds or removes, shift+tick extends
+ *     the range from the anchor;
+ *   - a click or tap ANYWHERE ELSE on the item opens it — the name, the icon,
+ *     the size column, the empty space beside the name, with or without a
+ *     selection, with or without Ctrl/Shift held;
+ *   - a right click (mouse) or a long press (finger) opens the item's menu;
+ *   - the item's own controls — the star, the ⋮ button — do their own job.
  *
- * The views only report. What a tap means is decided once, in FilePane.
+ * The views only report. What a click means is decided once, in FilePane.
  *
- * Issue #26, second round (the reporter's rule, on EVERY device):
- *   - a press on the item's NAME opens it — mouse click or finger tap, with or
- *     without a selection;
- *   - a long press (finger) or a right click (mouse) opens the menu;
- *   - the checkbox selects, exactly as before.
- * So the views also report whether the click landed on the name (`name`).
+ * How the rule got here:
+ *   - First round: a finger has no double-click, so on a phone nothing could
+ *     be opened at all. A tap was made to open.
+ *   - Second round: a press on the NAME opened on every device, a press
+ *     beside it still selected. The reporter: "need to click precisely on
+ *     name, if a lil bit on the right then it selects file".
+ *   - Third round: on a phone the name still needed two taps. A tap reaches a
+ *     page as a click only at the end of the browser's compatibility sequence
+ *     (touch → mouse move → hover → mouse down/up → click), and iOS WebKit
+ *     stops that sequence when the hover step reveals content. So a finger
+ *     lifted on the item opens it right there, at `touchend`, and cancels the
+ *     emulated mouse events that would follow (`onTap`); the hover reveals are
+ *     kept off screens that cannot hover (styles/base.css,
+ *     `@media (hover: hover)`).
+ *   - Fourth round: the checkbox became the only way a click selects, and the
+ *     grid and gallery cards got one too (they had none).
  *
  * ⚠ A tap is judged from the gesture that produced the click, never from the
  * screen: `pointerType` where the browser sets it on click (Chromium, Firefox),
  * and the touchend that just preceded the click where it does not (older
- * WebKit). A touch laptop's trackpad therefore keeps the desktop grammar while
- * its screen gets the phone one. A `(pointer: coarse)` media query cannot tell
- * those two apart.
+ * WebKit). A touch laptop's trackpad and its screen are two different gestures
+ * a `(pointer: coarse)` media query cannot tell apart.
  *
  * ⚠ It used to live as three identical copies of the long-press timer, one per
- * view; the tap rule is exactly the kind of addition a copy misses.
+ * view; a rule like this one is exactly the kind of addition a copy misses.
  */
 import { onBeforeUnmount } from 'vue';
 
@@ -39,6 +50,15 @@ const TAP_WINDOW_MS = 800;
 /** A finger that travels further than this is scrolling, not pressing. */
 const MOVE_TOLERANCE_PX = 10;
 
+/**
+ * What on an item is a control of its own: a press there is the control's,
+ * not the item's. The checkbox is one (it selects on its own click), and so
+ * are the star and the ⋮ button. A wrapper cell that swallows its clicks
+ * carries `data-fe-control` so a finger on its padding is not an open either.
+ */
+export const ITEM_CONTROL_SELECTOR =
+  'button, a, input, select, textarea, label, [role="checkbox"], [data-fe-control]';
+
 export interface TouchPoint {
   clientX: number;
   clientY: number;
@@ -50,30 +70,47 @@ export interface ClickMod {
   shift: boolean;
   /** The click was a finger's tap. */
   touch?: boolean;
-  /** The click landed on the item's name. */
-  name?: boolean;
+  /** The click was on the item's checkbox — the one click that selects. */
+  check?: boolean;
+}
+
+/** The one place a view turns a click on an item into a `ClickMod`. */
+export function clickMod(ev: MouseEvent, touch: boolean): ClickMod {
+  return { ctrl: ev.ctrlKey || ev.metaKey, shift: ev.shiftKey, touch };
 }
 
 /**
- * The one place a view turns a click into a `ClickMod`. `nameSelector` is the
- * view's own name element (`.fe-list__name`, `.fe-grid__label`, …).
+ * The one place a view turns a click on an item's CHECKBOX into a `ClickMod`.
+ * `ctrl` because a tick adds to a selection rather than replacing it; `shift`
+ * passes through so a shift-tick still extends the range from the anchor.
  */
-export function clickMod(ev: MouseEvent, touch: boolean, nameSelector: string): ClickMod {
-  const target = ev.target as Element | null;
-  return {
-    ctrl: ev.ctrlKey || ev.metaKey,
-    shift: ev.shiftKey,
-    touch,
-    name: typeof target?.closest === 'function' && target.closest(nameSelector) !== null,
-  };
+export function checkMod(ev: MouseEvent): ClickMod {
+  return { ctrl: true, shift: ev.shiftKey, check: true };
 }
 
-export function useRowTouch<T>(onLongPress: (item: T, at: TouchPoint) => void) {
+export interface RowTouchOptions<T> {
+  /** A tap on the item outside its controls: open it, before any click. */
+  onTap?: (item: T) => void;
+}
+
+/** Whether the press started on one of the item's own controls. */
+function onControl(ev: Event): boolean {
+  const el = ev.target as Element | null;
+  if (typeof el?.closest !== 'function') return false;
+  const control = el.closest(ITEM_CONTROL_SELECTOR);
+  const item = ev.currentTarget as Element | null;
+  // Only a control INSIDE the item counts: the listing itself may sit in a
+  // label or a link on some host page, and that must not disarm every tap.
+  return control !== null && (item === null || typeof item.contains !== 'function' || item.contains(control));
+}
+
+export function useRowTouch<T>(onLongPress: (item: T, at: TouchPoint) => void, options: RowTouchOptions<T> = {}) {
   let timer: ReturnType<typeof setTimeout> | undefined;
   let target: T | null = null;
   let origin: TouchPoint = { clientX: 0, clientY: 0 };
   let longPressed = false;
   let tapEndedAt = 0;
+  let startedOnItem = false;
 
   function stopTimer() {
     if (timer) clearTimeout(timer);
@@ -87,6 +124,7 @@ export function useRowTouch<T>(onLongPress: (item: T, at: TouchPoint) => void) {
     target = item;
     longPressed = false;
     origin = { clientX: t0.clientX, clientY: t0.clientY };
+    startedOnItem = !onControl(ev);
     timer = setTimeout(() => {
       timer = undefined;
       if (target === null) return;
@@ -107,10 +145,22 @@ export function useRowTouch<T>(onLongPress: (item: T, at: TouchPoint) => void) {
     }
   }
 
-  function onTouchEnd() {
+  /**
+   * ⚠ Bind it WITHOUT `.passive`: a passive listener cannot cancel the
+   * emulated mouse events, and the click they end in would then reach the new
+   * listing under the finger (FilePane's open guard catches that too).
+   */
+  function onTouchEnd(ev?: TouchEvent) {
     stopTimer();
-    if (target !== null && !longPressed) tapEndedAt = Date.now();
+    const item = target;
+    const tapped = item !== null && !longPressed;
+    if (tapped) tapEndedAt = Date.now();
     target = null;
+    if (tapped && startedOnItem && options.onTap) {
+      if (ev?.cancelable) ev.preventDefault();
+      options.onTap(item as T);
+    }
+    startedOnItem = false;
   }
 
   /** Whether this click is a finger's tap. */

package/src/styles/base.css

@@ -466,11 +466,22 @@ filex-explorer {
   opacity: 0;
   transition: opacity 0.12s;
 }
-.fe-list__row:hover .fe-list__col--star,
+/* issue #26, third round — a reveal ON HOVER only where hovering exists.
+   iOS WebKit treats a tap whose :hover styles reveal content (an opacity
+   transition from 0 counts) as "the user wanted to see the hover state": it
+   applies the hover and swallows the click, so the first tap on a row or card
+   only highlighted it and a second tap was needed to open. `(hover: hover)`
+   keeps these reveals off touch screens, where they could never be hovered on
+   purpose anyway. `:focus-within` and a starred item stay visible everywhere. */
 .fe-list__row:focus-within .fe-list__col--star,
 .fe-list__col--star:has(.is-starred) {
   opacity: 1;
 }
+@media (hover: hover) {
+  .fe-list__row:hover .fe-list__col--star {
+    opacity: 1;
+  }
+}
 .fe-list__col--star .filex-star-btn.is-starred {
   color: var(--fe-warning, #f59e0b);
 }
@@ -3683,11 +3694,25 @@ filex-explorer {
   transition: opacity 0.12s ease, transform 0.12s ease;
   pointer-events: none;
 }
-.fe-gal__card:hover .fe-gal__meta,
 .fe-gal__card:focus-visible .fe-gal__meta {
   opacity: 1;
   transform: translateY(0);
 }
+/* issue #26 — see the note on .fe-list__col--star: no hover reveal on touch.
+   A screen that cannot hover shows the caption outright instead, since it
+   would otherwise never be seen there. */
+@media (hover: hover) {
+  .fe-gal__card:hover .fe-gal__meta {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+@media (hover: none) {
+  .fe-gal__meta {
+    opacity: 1;
+    transform: none;
+  }
+}
 .fe-gal__meta-line {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -4560,9 +4585,7 @@ filex-explorer {
   opacity: 0;
   transition: opacity 120ms ease;
 }
-.fe-grid__card:hover .fe-grid__star,
 .fe-grid__card:focus-within .fe-grid__star,
-.fe-gal__card:hover .fe-gal__star,
 .fe-gal__card:focus-within .fe-gal__star,
 .fe-grid__star:focus-within,
 .fe-gal__star:focus-within,
@@ -4570,12 +4593,88 @@ filex-explorer {
 .fe-gal__star:has(.is-starred) {
   opacity: 1;
 }
+/* issue #26 — see the note on .fe-list__col--star: no hover reveal on touch. */
+@media (hover: hover) {
+  .fe-grid__card:hover .fe-grid__star,
+  .fe-gal__card:hover .fe-gal__star {
+    opacity: 1;
+  }
+}
 /* `:has()` is the modern half of the rule above; this is the same thing for
    engines without it — a starred chip paints itself. Both are needed: the
    parent wrapper carries the opacity, the child cannot raise it on its own. */
 .filex-star-btn.is-card.is-starred {
   opacity: 1;
 }
+/* === issue #26 — the checkbox on a grid / gallery card ================
+   The one click on a card that selects; a click anywhere else opens it. The
+   box itself is ItemCheck (.fe-list__check, the list's own tick). It shows
+   when the card is hovered (where hovering exists — see the star note), when
+   something inside the card is focused, when the card is selected, and on
+   every card once anything is selected — which is how a finger, with no
+   hover, finds the next box to tick after a long press selected the first.
+   ⚠ Hidden means `pointer-events: none` as well: an invisible box would take
+   the tap meant to open the card under it. */
+.fe-item-check {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 120ms ease;
+}
+.fe-grid__card.is-selected .fe-item-check,
+.fe-gal__card.is-selected .fe-item-check,
+.fe-grid.has-selection .fe-item-check,
+.fe-gal.has-selection .fe-item-check,
+.fe-grid__card:focus-within .fe-item-check,
+.fe-gal__card:focus-within .fe-item-check {
+  opacity: 1;
+  pointer-events: auto;
+}
+@media (hover: hover) {
+  .fe-grid__card:hover .fe-item-check,
+  .fe-gal__card:hover .fe-item-check {
+    opacity: 1;
+    pointer-events: auto;
+  }
+}
+/* On a grid card the box takes the type tile's 24px slot in the card's row,
+   so the name does not move when it appears; the tile steps aside. */
+.fe-grid__lead {
+  position: relative;
+  flex: 0 0 24px;
+  width: 24px;
+  height: 24px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.fe-grid__lead > .fe-item-check {
+  position: absolute;
+  inset: 0;
+}
+.fe-grid__lead > .fe-grid__tile {
+  transition: opacity 120ms ease;
+}
+.fe-grid__card.is-selected .fe-grid__lead--pick > .fe-grid__tile,
+.fe-grid.has-selection .fe-grid__lead--pick > .fe-grid__tile,
+.fe-grid__card:focus-within .fe-grid__lead--pick > .fe-grid__tile {
+  opacity: 0;
+}
+@media (hover: hover) {
+  .fe-grid__card:hover .fe-grid__lead--pick > .fe-grid__tile {
+    opacity: 0;
+  }
+}
+/* On a gallery card it is the thumbnail's top-left corner, opposite the star. */
+.fe-gal__check {
+  position: absolute;
+  top: 6px;
+  left: 6px;
+  z-index: 2;
+}
+
 /* The chip itself: a round translucent puck, legible over a photo thumbnail
    as well as over a flat icon tile. */
 .filex-star-btn.is-card {
@@ -5932,8 +6031,9 @@ filex-explorer {
   border-bottom: 1px solid var(--fe-border-soft);
 }
 
-/* The tick. It selects the same thing the row does — see ListView.onCheckClick
-   — so it gets the plain control look, not an accent of its own. */
+/* The tick — the one click on an item that selects (issue #26; ListView
+   onCheckClick, components/ItemCheck). The plain control look, not an accent
+   of its own. */
 .fe-list__col--check {
   display: flex;
   align-items: center;
@@ -10285,6 +10385,11 @@ filex-explorer {
 .fe-list__col--star {
   justify-content: center;
 }
+/* issue #26 — the star's click guard (ListView): stops the click without a
+   box of its own, so the star sits where it always did. */
+.fe-list__star-hit {
+  display: contents;
+}
 /* Location was never in the muted-value rule above it — it is a value like
    Type and Owner and reads like one. */
 .fe-list__col--location {

package/src/types/ExplorerConfig.ts

@@ -454,6 +454,38 @@ export interface ExplorerConfig {
   callerKind?: 'user' | 'app';
 
 
+  /**
+   * How a mouse opens an item.
+   *
+   *   'double' (default) — a single click SELECTS, a double click OPENS
+   *                        (classic desktop file-manager). This is a
+   *                        per-viewer preference the host may expose as a
+   *                        setting.
+   *   'single'           — a single click OPENS (the item is opened on the
+   *                        first click; the checkbox is still the one click
+   *                        that selects).
+   *
+   * ⚠ TOUCH is not governed by this: a finger tap always opens (the mobile
+   * convention, and there is no hover-to-select on a touchscreen). The
+   * checkbox always selects, on every device and in either mode. See
+   * FilePane.onViewClick + composables/useRowTouch.
+   */
+  openTrigger?: 'single' | 'double';
+
+  /**
+   * Hand the OPEN of a file to the host instead of opening the in-page
+   * preview/editor overlay. When true, opening a file emits `file-opened`
+   * (path + basename) and the explorer does NOT mount its own PreviewModal —
+   * the host decides what to do (the desktop app opens the file in its own
+   * window per document). Directories still navigate inline, and Space
+   * quick-look still peeks in-page. Default false (web/embeds preview inline).
+   *
+   * ⚠ Ignored inside an unlocked E2E-encrypted folder: the host window would
+   * fetch raw server bytes (ciphertext), so those keep the in-page decrypted
+   * preview.
+   */
+  openInHost?: boolean;
+
   /** Default view. */
   viewMode?: 'list' | 'grid';