@hienlh/ppm 0.17.57 → 0.18.0

package/src/web/components/os-explorer/skins/macos-window-chrome.tsx

@@ -0,0 +1,69 @@
+/**
+ * Finder-flavoured unified titlebar: traffic lights left (grey when unfocused, hover
+ * reveals the glyph), title centred. Height matches the shared `TITLEBAR_HEIGHT` contract
+ * constant (not the real Finder 38px) so a minimised window's collapsed height agrees with
+ * what `FloatingWindow` reserves for it. The toolbar row (back/forward/view-switch/search)
+ * is the existing `ExplorerToolbar` in the window body, tinted by `skins.css` — the chrome
+ * slot is only the titlebar itself.
+ *
+ * `data-skin` is set here (not only on the explorer body) because this titlebar is a
+ * sibling of the body in the window tree — the `--x-*` vars it reads only resolve on an
+ * element that itself carries the attribute.
+ */
+
+import { Minus, Plus, X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { TITLEBAR_HEIGHT, type WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+
+/** The traffic-light colours, plus the unfocused grey — the documented hardcoded hexes. */
+const LIGHTS = [
+  { color: "#FF5F57", label: "Close window", Icon: X },
+  { color: "#FEBC2E", label: "Minimize window", Icon: Minus },
+  { color: "#28C840", label: "Maximize window", Icon: Plus },
+] as const;
+
+export function MacosWindowChrome({
+  title, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
+}: WindowChromeProps) {
+  const { className, style, ...rest } = titlebarProps;
+  const actions = [onClose, onMinimize, onToggleMaximize];
+  return (
+    <div
+      {...rest}
+      data-skin="macos"
+      style={{ height: TITLEBAR_HEIGHT, fontFamily: "var(--x-font)", ...style }}
+      className={cn(
+        "group/titlebar relative flex items-center shrink-0 rounded-t-[var(--x-radius)] overflow-hidden",
+        "bg-[var(--x-titlebar-bg)] border-b border-border",
+        "outline-none focus-visible:ring-1 focus-visible:ring-primary focus-visible:ring-inset",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2 pl-3">
+        {LIGHTS.map(({ color, label, Icon }, i) => (
+          <button
+            key={label}
+            type="button"
+            aria-label={label}
+            onClick={actions[i]}
+            className="grid size-3 place-items-center rounded-full"
+            style={{ backgroundColor: focused ? color : "#8E8E93" }}
+          >
+            <Icon
+              className="size-2 text-black/60 can-hover:opacity-0 can-hover:group-hover/titlebar:opacity-100"
+              strokeWidth={3}
+            />
+          </button>
+        ))}
+      </div>
+      <span
+        className={cn(
+          "pointer-events-none absolute inset-x-0 truncate text-center text-[13px]",
+          focused ? "text-text" : "text-text-2",
+        )}
+      >
+        {title}
+      </span>
+    </div>
+  );
+}

package/src/web/components/os-explorer/skins/skin-types.ts

@@ -0,0 +1,40 @@
+/**
+ * A skin is everything that makes the explorer window look native to a host OS: the
+ * titlebar/toolbar chrome, the sidebar section names, and the folder glyph. Views, the
+ * toolbar body and the sidebar rows themselves stay skin-agnostic — they read `vocab` and
+ * the folder icon slot, nothing else changes.
+ *
+ * Colours are deliberately not part of this type: skin-specific CSS lives in `skins.css`
+ * scoped under `[data-skin]`, reusing PPM's existing semantic tokens (`bg-panel`,
+ * `text-text`, …) so both PPM dark and light modes fall out for free instead of needing a
+ * second light/dark table here.
+ */
+
+import type { ComponentProps, FC } from "react";
+import type { WindowChrome } from "@/components/floating-window/window-chrome-contract";
+
+export type SkinId = "windows" | "macos";
+
+/** Sidebar section labels that differ between a Windows and a Mac/Linux file manager. */
+export interface SkinVocab {
+  /** "Home" on both, kept explicit in case a future skin wants to drop it. */
+  home: string;
+  /** "Quick access" (Windows) vs "Favorites" (macOS). */
+  pinned: string;
+  /** "Folders" (Windows) vs "Locations" (macOS) — the known-folders section. */
+  known: string;
+  /** "Drives" (Windows) vs "Devices" (macOS) — rendered as its own section, so it needs a
+   *  label distinct from `known` even though Finder visually groups both under Locations. */
+  drives: string;
+}
+
+export type FolderIconComponent = FC<ComponentProps<"svg">>;
+
+export interface ExplorerSkin {
+  id: SkinId;
+  vocab: SkinVocab;
+  FolderIcon: FolderIconComponent;
+  FolderOpenIcon: FolderIconComponent;
+  /** Window titlebar/toolbar chrome for this skin. */
+  chrome: WindowChrome;
+}

package/src/web/components/os-explorer/skins/skins.css

@@ -0,0 +1,25 @@
+/*
+ * OS Explorer skin tokens, scoped to `[data-skin]` set on the explorer root
+ * (`ExplorerBody`). Colours stay derived from PPM's existing semantic tokens
+ * (`--panel-2`, `--border`, `--accent-2`, …) via `color-mix()` rather than a second
+ * light/dark table, so both PPM themes stay legible without duplicating that logic here.
+ * Layout metrics (radius, font stack) are the only skin-owned constants.
+ */
+
+[data-skin="windows"] {
+  --x-radius: 8px;
+  --x-font: "Segoe UI Variable Text", "Segoe UI", system-ui, -apple-system, sans-serif;
+  --x-titlebar-bg: var(--panel-2);
+  --x-toolbar-bg: var(--panel-2);
+  /* A flat "Mica-ish" wash: a touch lighter than the base panel, same on any theme. */
+  --x-sidebar-bg: color-mix(in srgb, var(--panel-2) 90%, white 10%);
+}
+
+[data-skin="macos"] {
+  --x-radius: 10px;
+  --x-font: -apple-system, "SF Pro Text", "SF Pro", system-ui, sans-serif;
+  --x-titlebar-bg: var(--panel-2);
+  --x-toolbar-bg: var(--panel-2);
+  /* Finder's sidebar reads a hair cooler than its content pane. */
+  --x-sidebar-bg: color-mix(in srgb, var(--panel-2) 85%, var(--accent-2) 6%);
+}

package/src/web/components/os-explorer/skins/use-explorer-skin.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolves which skin an explorer window should wear: the user's Settings override when
+ * set, otherwise the host `platform` — Linux gets the macOS look since there is no single
+ * dominant Linux file-manager chrome to imitate (same call the plan made for pinned
+ * folders and known folders).
+ */
+
+import { useSettingsStore } from "@/stores/settings-store";
+import { useHostInfo } from "../use-host-info";
+import { macosSkin } from "./macos-skin";
+import type { ExplorerSkin } from "./skin-types";
+import { windowsSkin } from "./windows-skin";
+
+export function useExplorerSkin(): ExplorerSkin {
+  const override = useSettingsStore((s) => s.explorerSkin);
+  const { host } = useHostInfo();
+
+  if (override === "windows") return windowsSkin;
+  if (override === "macos") return macosSkin;
+  return host?.platform === "win32" ? windowsSkin : macosSkin;
+}

package/src/web/components/os-explorer/skins/windows-skin.ts

@@ -0,0 +1,11 @@
+import { WindowsFolderIcon, WindowsFolderOpenIcon } from "./folder-icon-windows";
+import { WindowsWindowChrome } from "./windows-window-chrome";
+import type { ExplorerSkin } from "./skin-types";
+
+export const windowsSkin: ExplorerSkin = {
+  id: "windows",
+  vocab: { home: "Home", pinned: "Quick access", known: "Folders", drives: "Drives" },
+  FolderIcon: WindowsFolderIcon,
+  FolderOpenIcon: WindowsFolderOpenIcon,
+  chrome: WindowsWindowChrome,
+};

package/src/web/components/os-explorer/skins/windows-window-chrome.tsx

@@ -0,0 +1,56 @@
+/**
+ * Windows 11 File Explorer-flavoured titlebar: window icon + title left, caption buttons
+ * right (46px wide, close hover red). Height matches the shared `TITLEBAR_HEIGHT` contract
+ * constant (not the real Win11 32px) so a minimised window's collapsed height agrees with
+ * what `FloatingWindow` reserves for it. The toolbar row (back/forward/breadcrumb/search) is
+ * the existing `ExplorerToolbar` in the window body, tinted by `skins.css` — the chrome slot
+ * is only the titlebar itself.
+ *
+ * `data-skin` is set here (not only on the explorer body) because this titlebar is a
+ * sibling of the body in the window tree — the `--x-*` vars it reads (`--x-titlebar-bg`,
+ * `--x-radius`, `--x-font`) only resolve on an element that itself carries the attribute.
+ */
+
+import { Minus, Square, Copy, X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { TITLEBAR_HEIGHT, type WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+import { WindowsFolderIcon } from "./folder-icon-windows";
+
+/** Windows metric: 46px wide caption buttons, full titlebar height. */
+const CAPTION_BUTTON =
+  "grid place-items-center w-[46px] self-stretch text-text-2 can-hover:hover:bg-surface-elevated can-hover:hover:text-text transition-colors";
+/** The one documented hardcoded hex: Windows' close-button hover red. */
+const CLOSE_BUTTON = cn(CAPTION_BUTTON, "can-hover:hover:!bg-[#c42b1c] can-hover:hover:!text-white");
+
+export function WindowsWindowChrome({
+  title, state, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
+}: WindowChromeProps) {
+  const { className, style, ...rest } = titlebarProps;
+  return (
+    <div
+      {...rest}
+      data-skin="windows"
+      style={{ height: TITLEBAR_HEIGHT, fontFamily: "var(--x-font)", ...style }}
+      className={cn(
+        "flex items-stretch shrink-0 rounded-t-[var(--x-radius)] overflow-hidden",
+        "bg-[var(--x-titlebar-bg)] border-b border-border",
+        "outline-none focus-visible:ring-1 focus-visible:ring-primary focus-visible:ring-inset",
+        className,
+      )}
+    >
+      <div className="flex flex-1 min-w-0 items-center gap-2 px-2.5 cursor-default">
+        <WindowsFolderIcon className="size-4 shrink-0" />
+        <span className={cn("truncate text-[12px]", focused ? "text-text" : "text-text-2")}>{title}</span>
+      </div>
+      <button type="button" aria-label="Minimize window" className={CAPTION_BUTTON} onClick={onMinimize}>
+        <Minus className="size-3.5" />
+      </button>
+      <button type="button" aria-label={state === "maximized" ? "Restore window" : "Maximize window"} className={CAPTION_BUTTON} onClick={onToggleMaximize}>
+        {state === "maximized" ? <Copy className="size-3" /> : <Square className="size-3" />}
+      </button>
+      <button type="button" aria-label="Close window" className={CLOSE_BUTTON} onClick={onClose}>
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}

package/src/web/components/os-explorer/sort-and-filter-entries.ts

@@ -0,0 +1,52 @@
+/**
+ * The visible row order: the filter text applied first, then the sort.
+ *
+ * Directories always come before files regardless of the sort column, which is what every
+ * desktop file manager does and what keyboard navigation assumes.
+ */
+
+import type { FsEntry } from "@/lib/fs-api";
+import { extensionOf } from "./can-open-in-ppm";
+import type { SortDir, SortKey } from "./explorer-store";
+
+/** Locale-aware, digit-aware name compare so "file10" sorts after "file9". */
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+
+function compareBy(key: SortKey, a: FsEntry, b: FsEntry): number {
+  switch (key) {
+    case "size":
+      return (a.size ?? 0) - (b.size ?? 0);
+    case "modified":
+      return new Date(a.modified).getTime() - new Date(b.modified).getTime();
+    case "kind": {
+      const byExt = collator.compare(extensionOf(a.name), extensionOf(b.name));
+      return byExt !== 0 ? byExt : collator.compare(a.name, b.name);
+    }
+    case "name":
+      return collator.compare(a.name, b.name);
+  }
+}
+
+export function sortAndFilterEntries(
+  entries: FsEntry[],
+  filter: string,
+  sort: { key: SortKey; dir: SortDir },
+): FsEntry[] {
+  const needle = filter.trim().toLowerCase();
+  const visible = needle ? entries.filter((e) => e.name.toLowerCase().includes(needle)) : entries;
+  const sign = sort.dir === "asc" ? 1 : -1;
+
+  return [...visible].sort((a, b) => {
+    const aDir = a.type === "directory";
+    const bDir = b.type === "directory";
+    if (aDir !== bDir) return aDir ? -1 : 1;
+    const result = compareBy(sort.key, a, b);
+    // Equal keys fall back to the name so the order never depends on readdir sequence.
+    return (result !== 0 ? result : collator.compare(a.name, b.name)) * sign;
+  });
+}
+
+/** Total bytes of the given entries; directories contribute nothing (size unknown). */
+export function totalSize(entries: FsEntry[]): number {
+  return entries.reduce((sum, e) => sum + (e.type === "file" ? (e.size ?? 0) : 0), 0);
+}

package/src/web/components/os-explorer/sort-options.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared sort vocabulary: the four sortable keys and the two directions, with the labels
+ * shown to the user. The toolbar sort menu, the background context menu's "Sort by"
+ * submenu, the List view's column headers and the mobile More sheet all read from here so
+ * the four surfaces can never say something different about what "Kind" or "Descending"
+ * means.
+ */
+
+import type { SortDir, SortKey } from "./explorer-store";
+
+export const SORT_KEY_OPTIONS: readonly { key: SortKey; label: string }[] = [
+  { key: "name", label: "Name" },
+  { key: "size", label: "Size" },
+  { key: "modified", label: "Modified" },
+  { key: "kind", label: "Kind" },
+];
+
+export const SORT_DIR_OPTIONS: readonly { dir: SortDir; label: string }[] = [
+  { dir: "asc", label: "Ascending" },
+  { dir: "desc", label: "Descending" },
+];
+
+export function sortKeyLabel(key: SortKey): string {
+  return SORT_KEY_OPTIONS.find((option) => option.key === key)?.label ?? key;
+}
+
+export function sortDirLabel(dir: SortDir): string {
+  return SORT_DIR_OPTIONS.find((option) => option.dir === dir)?.label ?? dir;
+}

package/src/web/components/os-explorer/toolbar-icon-button.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared square icon-button styling for the window toolbar and any trigger that sits
+ * alongside it (e.g. the sort menu button) — one class builder keeps their hit-box
+ * behaviour identical instead of two toolbars drifting apart.
+ *
+ * The visible box stays `size-7` (28px) on every pointer type — only the tap-registering
+ * area grows to the 44px minimum on a coarse pointer, via an invisible expanded `::before`
+ * (a click anywhere in it still hits this element; nothing about the button's look moves).
+ */
+
+import { cn } from "@/lib/utils";
+
+export function toolbarButtonClass(coarse: boolean): string {
+  return cn(
+    "relative flex size-7 shrink-0 items-center justify-center rounded text-text-subtle can-hover:hover:bg-surface-elevated can-hover:hover:text-text disabled:opacity-30",
+    coarse && "before:absolute before:-inset-2 before:content-['']",
+  );
+}

package/src/web/components/os-explorer/use-coarse-long-press.ts

@@ -0,0 +1,97 @@
+/**
+ * Long-press → context menu on touch screens that are wide enough to get the desktop
+ * layout (an iPad is ≥ 768 px, so `useIsMobile` is false and the bottom-sheet path never
+ * runs). Radix opens its own menu on long-press but only after 700 ms; the design rules
+ * ask for 400 ms, so the press is timed here and delivered as a synthetic `contextmenu`
+ * event, which is exactly what the trigger already listens for.
+ *
+ * Attached only when the primary pointer is coarse — a mouse keeps plain right-click.
+ */
+
+import { useCallback, useEffect, useRef, useState, type MouseEvent, type TouchEvent } from "react";
+
+const LONG_PRESS_MS = 400;
+/** Finger travel that turns a press into a scroll instead. */
+const MOVE_TOLERANCE_PX = 10;
+
+export function usePrefersCoarsePointer(): boolean {
+  const [coarse, setCoarse] = useState(
+    () => typeof window !== "undefined" && window.matchMedia?.("(pointer: coarse)").matches === true,
+  );
+  useEffect(() => {
+    const query = window.matchMedia?.("(pointer: coarse)");
+    if (!query) return;
+    const update = () => setCoarse(query.matches);
+    query.addEventListener("change", update);
+    return () => query.removeEventListener("change", update);
+  }, []);
+  return coarse;
+}
+
+export interface LongPressHandlers {
+  onTouchStart?(event: TouchEvent): void;
+  onTouchMove?(event: TouchEvent): void;
+  onTouchEnd?(event: TouchEvent): void;
+  onContextMenu?(event: MouseEvent): void;
+}
+
+/**
+ * Handlers to spread on a row. `onBeforeOpen` runs first so the menu acts on the pressed
+ * row rather than whatever was selected before.
+ */
+export function useCoarseLongPress(onBeforeOpen?: () => void): LongPressHandlers {
+  const coarse = usePrefersCoarsePointer();
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const origin = useRef<{ x: number; y: number } | null>(null);
+  const fired = useRef(false);
+
+  const cancel = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+  }, []);
+
+  useEffect(() => cancel, [cancel]);
+
+  const start = useCallback(
+    (event: TouchEvent) => {
+      const touch = event.touches[0];
+      if (!touch) return;
+      const target = event.currentTarget as HTMLElement;
+      origin.current = { x: touch.clientX, y: touch.clientY };
+      fired.current = false;
+      cancel();
+      timer.current = setTimeout(() => {
+        fired.current = true;
+        onBeforeOpen?.();
+        target.dispatchEvent(
+          new MouseEvent("contextmenu", {
+            bubbles: true,
+            cancelable: true,
+            clientX: touch.clientX,
+            clientY: touch.clientY,
+          }),
+        );
+      }, LONG_PRESS_MS);
+    },
+    [cancel, onBeforeOpen],
+  );
+
+  const move = useCallback(
+    (event: TouchEvent) => {
+      const touch = event.touches[0];
+      if (!touch || !origin.current) return;
+      const moved =
+        Math.abs(touch.clientX - origin.current.x) > MOVE_TOLERANCE_PX ||
+        Math.abs(touch.clientY - origin.current.y) > MOVE_TOLERANCE_PX;
+      if (moved) cancel();
+    },
+    [cancel],
+  );
+
+  if (!coarse) return {};
+  return {
+    onTouchStart: start,
+    onTouchMove: move,
+    onTouchEnd: cancel,
+  };
+}

package/src/web/components/os-explorer/use-explorer-keyboard.ts

@@ -0,0 +1,124 @@
+/**
+ * Keyboard behaviour for an explorer view container, shared by every view mode.
+ *
+ * Bound to the scrolling element rather than the window so two open explorers never both
+ * react to the same key, and so PPM's global shortcuts keep working when focus is
+ * elsewhere.
+ */
+
+import { useCallback } from "react";
+import type { KeyboardEvent } from "react";
+import type { FsEntry } from "@/lib/fs-api";
+import type { ExplorerActions } from "./actions/use-explorer-actions";
+import type { ExplorerSlice } from "./explorer-store";
+import type { ExplorerNavigation } from "./use-explorer-navigation";
+import type { EntrySelection } from "./views/use-entry-selection";
+
+export interface ExplorerKeyboardOptions {
+  /** Undefined for the one frame before the window has a slice. */
+  slice: ExplorerSlice | undefined;
+  /** Rows in visible order. */
+  entries: FsEntry[];
+  actions: ExplorerActions;
+  selection: EntrySelection;
+  nav: ExplorerNavigation;
+}
+
+/** Entries the keyboard acts on: the selection, or the cursor row when nothing is selected. */
+export function activeEntries(slice: ExplorerSlice, entries: FsEntry[]): FsEntry[] {
+  if (slice.selection.size > 0) return entries.filter((e) => slice.selection.has(e.path));
+  const cursor = entries.find((e) => e.path === slice.anchor);
+  return cursor ? [cursor] : [];
+}
+
+export function useExplorerKeyboard({
+  slice, entries, actions, selection, nav,
+}: ExplorerKeyboardOptions): (event: KeyboardEvent) => void {
+  return useCallback(
+    (event: KeyboardEvent) => {
+      if (!slice) return;
+      // The inline rename field and the filter box own their own keys.
+      const target = event.target as HTMLElement;
+      if (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable) return;
+
+      const mod = event.ctrlKey || event.metaKey;
+      const targets = activeEntries(slice, entries);
+
+      if (mod) {
+        switch (event.key.toLowerCase()) {
+          case "a":
+            event.preventDefault();
+            selection.selectAll();
+            return;
+          case "c":
+            event.preventDefault();
+            actions.copy(targets);
+            return;
+          case "x":
+            event.preventDefault();
+            actions.cut(targets);
+            return;
+          case "v":
+            event.preventDefault();
+            actions.paste();
+            return;
+          default:
+            return; // leave every other accelerator to the app
+        }
+      }
+
+      switch (event.key) {
+        case "ArrowDown":
+          event.preventDefault();
+          selection.moveTo(1, event.shiftKey);
+          return;
+        case "ArrowUp":
+          event.preventDefault();
+          selection.moveTo(-1, event.shiftKey);
+          return;
+        case "Home":
+          event.preventDefault();
+          if (entries[0]) selection.selectOnly(entries[0].path);
+          return;
+        case "End":
+          event.preventDefault();
+          if (entries.length > 0) selection.selectOnly(entries[entries.length - 1]!.path);
+          return;
+        case "ArrowLeft":
+          if (event.altKey) { event.preventDefault(); nav.back(); }
+          return;
+        case "ArrowRight":
+          if (event.altKey) { event.preventDefault(); nav.forward(); }
+          return;
+        case "Backspace":
+          event.preventDefault();
+          nav.back();
+          return;
+        case "Enter":
+          event.preventDefault();
+          if (targets.length === 1) actions.openEntry(targets[0]!);
+          return;
+        case "F2":
+          event.preventDefault();
+          if (targets.length === 1) actions.startRename(targets[0]!);
+          return;
+        case "Delete":
+          event.preventDefault();
+          if (targets.length === 0) return;
+          if (event.shiftKey) actions.confirmPermanentDelete(targets);
+          else actions.trash(targets);
+          return;
+        case "Escape":
+          selection.clear();
+          return;
+      }
+
+      // Type-ahead: a single printable character with no modifier jumps to a name.
+      if (event.key.length === 1 && !event.altKey) {
+        event.preventDefault();
+        selection.typeAhead(event.key);
+      }
+    },
+    [slice, entries, actions, selection, nav],
+  );
+}