@hienlh/ppm 0.17.57 → 0.18.1

package/src/web/components/os-explorer/views/column-view-column.tsx

@@ -0,0 +1,112 @@
+/**
+ * One fixed-width, independently virtualised and independently scrolled column of the
+ * Miller browser. Column view keeps a single highlighted entry per column rather than the
+ * multi-select semantics List/Icons use — Finder's own column browser works the same way,
+ * and it is what lets "the highlighted entry" double as "which directory the next column
+ * shows" with no extra state.
+ */
+
+import { useRef } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import type { FsEntry } from "@/lib/fs-api";
+import { cn } from "@/lib/utils";
+import type { ExplorerActions } from "../actions/use-explorer-actions";
+import { DROP_TARGET_CLASS } from "../dnd/drop-target-style";
+import { useDragAutoScroll } from "../dnd/use-drag-auto-scroll";
+import { usePathDropTarget } from "../dnd/use-path-drop-target";
+import { ColumnRow } from "./column-row";
+
+export const COLUMN_WIDTH = 220;
+/** Mobile's single full-width column needs a 44px+ touch target, bigger than the desktop
+ *  (fine/coarse-pointer) `rowHeight` threaded in from `ExplorerBody`. Exported so
+ *  `column-view-mobile.tsx` can pass a real value instead of a duplicated magic number —
+ *  the `fullWidth` branch here always wins over whatever `rowHeight` prop it receives. */
+export const ROW_HEIGHT_MOBILE = 48;
+
+export interface ColumnViewColumnProps {
+  path: string;
+  entries: FsEntry[];
+  loading: boolean;
+  error: string | null;
+  selectedPath: string | null;
+  isFocused: boolean;
+  currentDir: string;
+  hasClipboard: boolean;
+  isPinned(path: string): boolean;
+  actions: ExplorerActions;
+  /** Row height in px; larger on coarse-pointer devices, same as List/Icons. */
+  rowHeight: number;
+  onSelect(entry: FsEntry): void;
+  onOpen(entry: FsEntry): void;
+  onFocus(): void;
+  /** Mobile's single-column mode: fill the container instead of the fixed desktop width. */
+  fullWidth?: boolean;
+}
+
+export function ColumnViewColumn({
+  path, entries, loading, error, selectedPath, isFocused, currentDir,
+  hasClipboard, isPinned, actions, rowHeight, onSelect, onOpen, onFocus, fullWidth,
+}: ColumnViewColumnProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  useDragAutoScroll(scrollRef);
+  // Mobile's single full-width column always wants the bigger touch target, regardless of
+  // whatever fine/coarse-pointer density the caller threaded in for the desktop Miller strip.
+  const effectiveRowHeight = fullWidth ? ROW_HEIGHT_MOBILE : rowHeight;
+  const virtualizer = useVirtualizer({
+    count: entries.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => effectiveRowHeight,
+    overscan: 8,
+  });
+  // The column's own empty area is a drop target for its own directory — dropping below the
+  // last row of an ancestor column moves/copies into that ancestor, not just the deepest one.
+  // Mobile's single full-width column never gets one: no drag source can ever start on touch.
+  const backgroundDrop = usePathDropTarget({ targetDir: path, run: actions.transferInto, disabled: fullWidth });
+
+  return (
+    <div
+      className={cn("flex h-full shrink-0 flex-col", !fullWidth && "border-r border-border", isFocused && "bg-panel-2/40")}
+      style={fullWidth ? undefined : { width: COLUMN_WIDTH }}
+    >
+      <div
+        ref={scrollRef}
+        role="listbox"
+        aria-label={path}
+        className={cn("flex-1 overflow-y-auto outline-none", backgroundDrop.isOver && DROP_TARGET_CLASS)}
+        {...backgroundDrop.handlers}
+      >
+        {loading && entries.length === 0 && <p className="p-2 text-xs text-text-subtle">Loading…</p>}
+        {error && <p className="p-2 text-xs text-error">{error}</p>}
+        {!loading && !error && entries.length === 0 && <p className="p-2 text-xs text-text-subtle">Empty</p>}
+        <div className="relative w-full" style={{ height: virtualizer.getTotalSize() }}>
+          {virtualizer.getVirtualItems().map((item) => {
+            const entry = entries[item.index]!;
+            const selected = entry.path === selectedPath;
+            return (
+              <div
+                key={entry.path}
+                className="absolute left-0 top-0 w-full"
+                style={{ transform: `translateY(${item.start}px)` }}
+              >
+                <ColumnRow
+                  entry={entry}
+                  selected={selected}
+                  currentDir={currentDir}
+                  hasClipboard={hasClipboard}
+                  isPinned={isPinned}
+                  actions={actions}
+                  rowHeight={effectiveRowHeight}
+                  onSelect={() => {
+                    onFocus();
+                    onSelect(entry);
+                  }}
+                  onOpen={() => onOpen(entry)}
+                />
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/web/components/os-explorer/views/column-view-mobile.tsx

@@ -0,0 +1,98 @@
+/**
+ * Column view's mobile presentation: only the focused column ever renders, full width, with
+ * a Back row above it instead of the desktop's side-by-side Miller strip — there is no room
+ * for more than one column on a phone, and no preview pane (files open directly on tap, see
+ * `column-view-column.tsx`'s mobile branch).
+ */
+
+import type { KeyboardEvent, RefObject } from "react";
+import { ArrowLeft } from "lucide-react";
+import { ContextMenu, ContextMenuTrigger } from "@/components/ui/adaptive-context-menu";
+import type { FsEntry } from "@/lib/fs-api";
+import type { ExplorerActions } from "../actions/use-explorer-actions";
+import { ExplorerContextMenu } from "../explorer-context-menu";
+import type { ExplorerSlice } from "../explorer-store";
+import type { LongPressHandlers } from "../use-coarse-long-press";
+import { ColumnViewColumn, ROW_HEIGHT_MOBILE } from "./column-view-column";
+import type { ColumnState } from "./use-column-view-state";
+
+export interface ColumnViewMobileProps {
+  containerRef: RefObject<HTMLDivElement | null>;
+  onKeyDown(event: KeyboardEvent): void;
+  backgroundLongPress: LongPressHandlers;
+  columns: ColumnState[];
+  focusedIndex: number;
+  setFocusedIndex(update: (i: number) => number): void;
+  selectedPathFor(index: number): string | null;
+  slice: ExplorerSlice;
+  hasClipboard: boolean;
+  isPinned(path: string): boolean;
+  actions: ExplorerActions;
+  onSelect(index: number, entry: FsEntry): void;
+  onOpen(entry: FsEntry): void;
+}
+
+export function ColumnViewMobile({
+  containerRef, onKeyDown, backgroundLongPress, columns, focusedIndex, setFocusedIndex,
+  selectedPathFor, slice, hasClipboard, isPinned, actions, onSelect, onOpen,
+}: ColumnViewMobileProps) {
+  const current = columns[focusedIndex];
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <div
+          ref={containerRef}
+          tabIndex={0}
+          data-testid="explorer-columns"
+          aria-label="Column view"
+          onKeyDown={onKeyDown}
+          className="flex h-full min-h-0 w-full flex-col outline-none"
+          {...backgroundLongPress}
+        >
+          {focusedIndex > 0 && (
+            <button
+              type="button"
+              onClick={() => setFocusedIndex((i) => i - 1)}
+              aria-label="Back"
+              className="flex h-11 shrink-0 items-center gap-1.5 border-b border-border px-3 text-sm text-text-2 active:bg-surface-elevated"
+            >
+              <ArrowLeft className="size-4" /> Back
+            </button>
+          )}
+          {current && (
+            <div
+              key={current.path}
+              className="min-h-0 flex-1 motion-safe:animate-in motion-safe:slide-in-from-right-4 motion-safe:duration-150"
+            >
+              <ColumnViewColumn
+                path={current.path}
+                entries={current.entries}
+                loading={current.loading}
+                error={current.error}
+                selectedPath={selectedPathFor(focusedIndex)}
+                isFocused
+                fullWidth
+                rowHeight={ROW_HEIGHT_MOBILE}
+                currentDir={slice.path}
+                hasClipboard={hasClipboard}
+                isPinned={isPinned}
+                actions={actions}
+                onSelect={(entry) => onSelect(focusedIndex, entry)}
+                onOpen={onOpen}
+                onFocus={() => {}}
+              />
+            </div>
+          )}
+        </div>
+      </ContextMenuTrigger>
+      <ExplorerContextMenu
+        targets={[]}
+        currentDir={slice.path}
+        hasClipboard={hasClipboard}
+        isPinned={isPinned}
+        actions={actions}
+      />
+    </ContextMenu>
+  );
+}

package/src/web/components/os-explorer/views/column-view-preview.tsx

@@ -0,0 +1,70 @@
+/**
+ * Preview pane for Column view — the file currently highlighted anywhere in the columns
+ * (deepest column, or an earlier one the user clicked into without drilling).
+ */
+
+import type { FsEntry } from "@/lib/fs-api";
+import { canOpenInPpm, extensionOf, viewerKindOf } from "../can-open-in-ppm";
+import { formatDateTime, formatSize } from "../format-file-meta";
+import { FileTypeIcon } from "../icons/file-type-icon";
+import { ThumbnailImage } from "../icons/thumbnail-image";
+
+export interface ColumnViewPreviewProps {
+  entry: FsEntry | null;
+  onOpen(entry: FsEntry): void;
+}
+
+export function ColumnViewPreview({ entry, onOpen }: ColumnViewPreviewProps) {
+  if (!entry) {
+    return (
+      <div className="flex h-full items-center justify-center p-4 text-center text-xs text-text-subtle">
+        Select a file to preview
+      </div>
+    );
+  }
+
+  const isImage = entry.type !== "directory" && viewerKindOf(entry.name) === "image";
+
+  return (
+    <div
+      key={entry.path}
+      className="flex h-full min-w-0 flex-col items-center gap-3 overflow-y-auto p-4 text-center"
+    >
+      <div className="flex h-24 w-24 shrink-0 items-center justify-center">
+        {isImage ? (
+          <ThumbnailImage entry={entry} size={96} />
+        ) : (
+          <FileTypeIcon name={entry.name} kind={entry.kind} className="size-16" />
+        )}
+      </div>
+      <p className="w-full truncate text-sm font-medium text-text" title={entry.name}>
+        {entry.name}
+      </p>
+      <dl className="w-full space-y-1 text-left text-xs text-text-2">
+        <div className="flex justify-between gap-2">
+          <dt className="text-text-subtle">Kind</dt>
+          <dd className="truncate">{entry.type === "directory" ? "Folder" : extensionOf(entry.name) || "File"}</dd>
+        </div>
+        {entry.type !== "directory" && (
+          <div className="flex justify-between gap-2">
+            <dt className="text-text-subtle">Size</dt>
+            <dd>{formatSize(entry.size)}</dd>
+          </div>
+        )}
+        <div className="flex justify-between gap-2">
+          <dt className="text-text-subtle">Modified</dt>
+          <dd className="truncate">{formatDateTime(entry.modified)}</dd>
+        </div>
+      </dl>
+      {canOpenInPpm(entry.name) && (
+        <button
+          type="button"
+          onClick={() => onOpen(entry)}
+          className="mt-2 w-full rounded border border-border bg-panel-2 py-1.5 text-xs font-medium text-text can-hover:hover:bg-surface-elevated"
+        >
+          Open
+        </button>
+      )}
+    </div>
+  );
+}

package/src/web/components/os-explorer/views/column-view.tsx

@@ -0,0 +1,204 @@
+/**
+ * Column (Miller) view: one fixed-width column per breadcrumb ancestor, plus a preview
+ * pane for the selected leaf file. Drilling into a directory — by click or arrow key — is
+ * just `nav.go`, the same call the toolbar's back/forward/breadcrumb use, so history and
+ * the breadcrumb agree with whatever this view is showing and switching to List/Icons
+ * never loses the place.
+ */
+
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import { ContextMenu, ContextMenuTrigger } from "@/components/ui/adaptive-context-menu";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import type { FsEntry } from "@/lib/fs-api";
+import { useDragAutoScroll } from "../dnd/use-drag-auto-scroll";
+import { ExplorerContextMenu } from "../explorer-context-menu";
+import { ColumnViewColumn } from "./column-view-column";
+import { ColumnViewMobile } from "./column-view-mobile";
+import { ColumnViewPreview } from "./column-view-preview";
+import type { ExplorerViewProps } from "./explorer-view-registry";
+import { useColumnViewState } from "./use-column-view-state";
+
+/** Below this window width the preview pane would leave no room for the columns themselves. */
+const NARROW_PREVIEW_THRESHOLD = 720;
+
+export function ColumnView({
+  slice, entries, actions, selection, hasClipboard, isPinned, nav, backgroundLongPress, rowHeight,
+}: ExplorerViewProps) {
+  const paths = useMemo(
+    () => (slice.breadcrumbs.length > 0 ? slice.breadcrumbs.map((b) => b.path) : [slice.path]),
+    [slice.breadcrumbs, slice.path],
+  );
+  const { columns } = useColumnViewState(paths, entries, slice.loading);
+  const isMobile = useIsMobile();
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Horizontal auto-scroll across the Miller strip itself; each column also scrolls
+  // vertically on its own (see `column-view-column.tsx`). Harmless on mobile — no drag
+  // source ever fires a `dragover` there, since `draggable` is withheld on coarse pointers.
+  useDragAutoScroll(containerRef);
+  const [focusedIndex, setFocusedIndex] = useState(columns.length - 1);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const prevLength = useRef(columns.length);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const measure = () => setContainerWidth(el.clientWidth);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  // A new column (deeper drill, or a fresh window) moves the keyboard cursor onto it and
+  // scrolls it into view — every Miller browser keeps the newest column in frame.
+  useEffect(() => {
+    if (columns.length === prevLength.current) return;
+    prevLength.current = columns.length;
+    setFocusedIndex(columns.length - 1);
+    const el = containerRef.current;
+    if (!el) return;
+    const reduceMotion = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+    el.scrollTo({ left: el.scrollWidth, behavior: reduceMotion ? "auto" : "smooth" });
+  }, [columns.length]);
+
+  // The preview pane follows the shared window selection wherever it lands, even in an
+  // earlier column — the deepest column is just the common case.
+  const previewEntry: FsEntry | null = useMemo(() => {
+    if (!slice.anchor) return null;
+    for (const column of columns) {
+      const found = column.entries.find((e) => e.path === slice.anchor);
+      if (found) return found;
+    }
+    return null;
+  }, [columns, slice.anchor]);
+
+  const selectedPathFor = (index: number): string | null =>
+    index === columns.length - 1 ? slice.anchor : (columns[index + 1]?.path ?? null);
+
+  const entryAt = (index: number): FsEntry | null => {
+    const column = columns[index];
+    if (!column) return null;
+    const path = selectedPathFor(index);
+    return column.entries.find((e) => e.path === path) ?? null;
+  };
+
+  const handleSelect = (index: number, entry: FsEntry) => {
+    setFocusedIndex(index);
+    if (entry.type === "directory") nav.go(entry.path);
+    else selection.selectOnly(entry.path);
+  };
+
+  const handleOpen = (entry: FsEntry) => actions.openEntry(entry);
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+
+    if (event.key === "ArrowRight" && focusedIndex < columns.length - 1) {
+      event.preventDefault();
+      event.stopPropagation();
+      setFocusedIndex(focusedIndex + 1);
+      return;
+    }
+    if (event.key === "ArrowLeft" && focusedIndex > 0) {
+      event.preventDefault();
+      event.stopPropagation();
+      setFocusedIndex(focusedIndex - 1);
+      return;
+    }
+    if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+      const column = columns[focusedIndex];
+      if (!column) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const current = entryAt(focusedIndex);
+      const currentIndex = current ? column.entries.findIndex((e) => e.path === current.path) : -1;
+      const delta = event.key === "ArrowDown" ? 1 : -1;
+      const nextIndex = Math.min(column.entries.length - 1, Math.max(0, currentIndex < 0 ? 0 : currentIndex + delta));
+      const next = column.entries[nextIndex];
+      if (next) handleSelect(focusedIndex, next);
+      return;
+    }
+    if (event.key === "Enter") {
+      const current = entryAt(focusedIndex);
+      if (current) {
+        event.preventDefault();
+        event.stopPropagation();
+        handleOpen(current);
+      }
+    }
+  };
+
+  // Defaults hidden (not shown) before the ResizeObserver's first report — showing it then
+  // hiding it a frame later on a narrow window is a worse flash than the reverse.
+  const showPreview = containerWidth >= NARROW_PREVIEW_THRESHOLD;
+
+  // Mobile has no room for a side-by-side Miller strip — see `column-view-mobile.tsx`.
+  if (isMobile) {
+    return (
+      <ColumnViewMobile
+        containerRef={containerRef}
+        onKeyDown={onKeyDown}
+        backgroundLongPress={backgroundLongPress}
+        columns={columns}
+        focusedIndex={focusedIndex}
+        setFocusedIndex={setFocusedIndex}
+        selectedPathFor={selectedPathFor}
+        slice={slice}
+        hasClipboard={hasClipboard}
+        isPinned={isPinned}
+        actions={actions}
+        onSelect={handleSelect}
+        onOpen={handleOpen}
+      />
+    );
+  }
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <div
+          ref={containerRef}
+          tabIndex={0}
+          data-testid="explorer-columns"
+          aria-label="Column view"
+          onKeyDown={onKeyDown}
+          className="flex h-full min-h-0 w-full overflow-x-auto outline-none"
+          {...backgroundLongPress}
+        >
+          {columns.map((column, index) => (
+            <ColumnViewColumn
+              key={column.path}
+              path={column.path}
+              entries={column.entries}
+              loading={column.loading}
+              error={column.error}
+              selectedPath={selectedPathFor(index)}
+              isFocused={index === focusedIndex}
+              currentDir={slice.path}
+              hasClipboard={hasClipboard}
+              isPinned={isPinned}
+              actions={actions}
+              rowHeight={rowHeight}
+              onSelect={(entry) => handleSelect(index, entry)}
+              onOpen={handleOpen}
+              onFocus={() => setFocusedIndex(index)}
+            />
+          ))}
+          {showPreview && (
+            <div className="min-w-[240px] flex-1 border-l border-border bg-panel-2/30">
+              <ColumnViewPreview entry={previewEntry} onOpen={handleOpen} />
+            </div>
+          )}
+        </div>
+      </ContextMenuTrigger>
+      <ExplorerContextMenu
+        targets={[]}
+        currentDir={slice.path}
+        hasClipboard={hasClipboard}
+        isPinned={isPinned}
+        actions={actions}
+      />
+    </ContextMenu>
+  );
+}

package/src/web/components/os-explorer/views/compose-interactive-row-props.ts

@@ -0,0 +1,77 @@
+/**
+ * Merges the props a parent injects into a row with the row's own props.
+ *
+ * Radix's `ContextMenuTrigger asChild` clones its child and merges `ref`, `onContextMenu`,
+ * `onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerCancel`, `data-state`,
+ * `data-disabled` and `style={{ WebkitTouchCallout: "none", … }}` onto it. When the child is
+ * a custom component rather than a DOM element, those land in its props object and a fixed
+ * destructuring list silently drops every one it does not name — which is how the injected
+ * `style` (the only thing suppressing the native long-press callout on iOS) and Radix's own
+ * pointer-based long-press fallback disappeared before reaching the real `<div>`.
+ *
+ * Rules, in the order a row needs them:
+ * - two handlers for the same event chain, injected first, so the parent's behaviour (open
+ *   the menu) happens before the row's own (select, then stop the event travelling further);
+ * - `style` and `className` merge, with the row's own values winning per key;
+ * - anything else defined by the row wins outright.
+ */
+
+import { cn } from "@/lib/utils";
+import type { EntryRowDndProps } from "../dnd/use-entry-row-dnd";
+
+type RowProps = Record<string, unknown>;
+
+/**
+ * The two props every row/tile adds on top of whatever Radix injects: the drag-and-drop
+ * handler bag from `useEntryRowDnd`, and whether this row is the currently claimed drop
+ * target (draws `DROP_TARGET_CLASS`).
+ *
+ * Deliberately *not* `extends Record<string, unknown>` — React's `PropsWithoutRef<P>` picks
+ * over `keyof P`, and an index signature widens that to `string | number`, which collapses
+ * every other named property's type to `unknown` for any component using this as its props
+ * type. Radix's own injected props (`onContextMenu`, pointer handlers, `data-state`, `style`,
+ * …) still land in the `...rest` destructured alongside this — object rest/spread copies
+ * every own enumerable property at runtime regardless of what the static type declares, so
+ * they are forwarded correctly whether or not the type says so.
+ */
+export interface InjectedRowProps {
+  dnd: EntryRowDndProps;
+  dropActive: boolean;
+}
+
+type Handler = (event: unknown) => void;
+
+function isHandlerKey(key: string): boolean {
+  return key.startsWith("on") && key.length > 2 && key[2] === key[2]?.toUpperCase();
+}
+
+function chain(first: unknown, second: unknown): Handler {
+  return (event) => {
+    (first as Handler | undefined)?.(event);
+    (second as Handler | undefined)?.(event);
+  };
+}
+
+export function composeInteractiveRowProps<P extends RowProps>(injected: P | undefined, own: P): P {
+  if (!injected) return own;
+  const merged: RowProps = { ...injected };
+
+  for (const [key, value] of Object.entries(own)) {
+    const existing = merged[key];
+    if (isHandlerKey(key) && typeof existing === "function" && typeof value === "function") {
+      merged[key] = chain(existing, value);
+      continue;
+    }
+    if (key === "style" && existing && value) {
+      merged[key] = { ...(existing as object), ...(value as object) };
+      continue;
+    }
+    if (key === "className") {
+      merged[key] = cn(existing as string | undefined, value as string | undefined);
+      continue;
+    }
+    if (value !== undefined) merged[key] = value;
+  }
+
+  return merged as P;
+}

package/src/web/components/os-explorer/views/explorer-view-registry.tsx

@@ -0,0 +1,55 @@
+/**
+ * View mode → component. The body renders whatever is registered for the current mode and
+ * falls back to List for a mode that is not implemented yet, so a persisted preference
+ * can never leave a window blank.
+ *
+ * Adding Icons or Column view means adding the component file and one entry here; nothing
+ * else in the explorer needs to change. The toolbar offers exactly the registered modes.
+ */
+
+import type { ComponentType } from "react";
+import type { FsEntry } from "@/lib/fs-api";
+import type { ExplorerActions } from "../actions/use-explorer-actions";
+import type { ExplorerSlice, ViewMode } from "../explorer-store";
+import type { LongPressHandlers } from "../use-coarse-long-press";
+import type { ExplorerNavigation } from "../use-explorer-navigation";
+import type { EntrySelection } from "./use-entry-selection";
+import { ColumnView } from "./column-view";
+import { IconsView } from "./icons-view";
+import { ListView } from "./list-view";
+
+export interface ExplorerViewProps {
+  windowId: string;
+  slice: ExplorerSlice;
+  /** Already filtered and sorted — every view shares one order. */
+  entries: FsEntry[];
+  actions: ExplorerActions;
+  selection: EntrySelection;
+  /** Message from the last rejected inline commit, shown under the input. */
+  inlineError: string | null;
+  hasClipboard: boolean;
+  isPinned(path: string): boolean;
+  /** Row height in px; larger on coarse-pointer devices. */
+  rowHeight: number;
+  /** Column view drills by navigating like every other entry point (history/breadcrumb stay in sync). */
+  nav: ExplorerNavigation;
+  /**
+   * Long-press handlers for the empty-space background menu. Must land on the same element
+   * the view's background `ContextMenuTrigger` wraps — a wrapper further up the tree fires
+   * the synthetic `contextmenu` event on itself, and it never bubbles down to a descendant
+   * trigger.
+   */
+  backgroundLongPress: LongPressHandlers;
+}
+
+export const EXPLORER_VIEWS: Partial<Record<ViewMode, ComponentType<ExplorerViewProps>>> = {
+  list: ListView,
+  icons: IconsView,
+  columns: ColumnView,
+};
+
+export const AVAILABLE_VIEW_MODES = Object.keys(EXPLORER_VIEWS) as ViewMode[];
+
+export function viewComponentFor(mode: ViewMode): ComponentType<ExplorerViewProps> {
+  return EXPLORER_VIEWS[mode] ?? ListView;
+}