Files
outline/app/utils/splitView.ts
T

295 lines
8.8 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import type { History, LocationDescriptor } from "history";
import { createPath, parsePath } from "history";
import { action, observable } from "mobx";
import queryString from "query-string";
import { isMobile } from "@shared/utils/browser";
import { isModKey } from "@shared/utils/keyboard";
/**
* Name of the query string parameter that holds the route displayed in the
* secondary pane of the split view. Keeping the value in the URL allows a
* reload to hydrate both panes.
*/
export const splitViewQueryParam = "split";
/** Identifies a pane within the split view. */
export type SplitViewPane = "primary" | "secondary";
/**
* Parses the split view route from a location search string.
*
* @param search the location search string, with or without a leading "?".
* @returns the internal path shown in the secondary pane, or undefined when
* no valid split route is present.
*/
export function getSplitPath(search: string): string | undefined {
const value = queryString.parse(search)[splitViewQueryParam];
const path = Array.isArray(value) ? value[value.length - 1] : value;
if (typeof path !== "string") {
return undefined;
}
// Only allow internal, absolute paths – never protocol-relative or full
// URLs – as the value is used to drive the router directly.
if (!path.startsWith("/") || path.startsWith("//")) {
return undefined;
}
if (!isSplittablePath(parsePath(path).pathname)) {
return undefined;
}
return path;
}
/**
* Returns a new search string with the split view route set or removed,
* preserving all other query parameters.
*
* @param search the current location search string.
* @param path the internal path to open in the secondary pane, or undefined
* to remove the split view parameter.
* @returns the updated search string, prefixed with "?" when non-empty.
*/
export function setSplitPath(search: string, path: string | undefined): string {
const params = queryString.parse(search);
if (path === undefined) {
delete params[splitViewQueryParam];
} else {
params[splitViewQueryParam] = path;
}
const stringified = queryString.stringify(params);
return stringified ? `?${stringified}` : "";
}
const nonSplitViewPrefixes = [
"/settings",
"/s",
"/share",
"/login",
"/logout",
"/create",
"/desktop-redirect",
"/oauth",
"/auth",
"/404",
];
/**
* Whether a route can be rendered inside a split view pane. Routes such as
* settings or authentication render their own chrome and must always be
* displayed full width.
*
* @param pathname the pathname to check.
* @returns true if the route can be displayed in a split view pane.
*/
export function isSplittablePath(pathname: string): boolean {
// Require an internal, absolute pathname – full URLs and protocol-relative
// values must never be treated as splittable.
if (!pathname.startsWith("/") || pathname.startsWith("//")) {
return false;
}
if (pathname === "/") {
return false;
}
return !nonSplitViewPrefixes.some(
(prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`)
);
}
const focusedSplitPane = observable.box<SplitViewPane>("primary");
/**
* Returns the pane of the split view that currently has focus. Defaults to
* the primary pane when no split view is open. The value is observable, so
* observer components reading it re-render when focus changes.
*
* @returns the focused pane.
*/
export function getFocusedSplitPane(): SplitViewPane {
return focusedSplitPane.get();
}
/**
* Sets the pane of the split view that currently has focus. Navigation
* triggered outside of a pane, such as from the sidebar or command bar, is
* directed to the focused pane.
*
* @param pane the pane to focus.
*/
export const setFocusedSplitPane = action((pane: SplitViewPane): void => {
focusedSplitPane.set(pane);
});
let navigationSuppressed = false;
/**
* Whether split view handling of navigation is temporarily suppressed, used
* when closing the split view so that the navigation is not rewritten.
*
* @returns true if split view navigation handling is suppressed.
*/
export function isSplitViewNavigationSuppressed(): boolean {
return navigationSuppressed;
}
/**
* Runs a callback with split view handling of navigation disabled, allowing
* the exact location passed to history.push or history.replace to be used.
*
* @param callback the callback to run.
*/
export function withoutSplitViewNavigation(callback: () => void): void {
navigationSuppressed = true;
try {
callback();
} finally {
navigationSuppressed = false;
}
}
let splitModifierPressed = false;
/**
* Whether an event carries the modifier combination that opens a route in the
* secondary pane of the split view.
*
* @param event the keyboard or mouse event to check.
* @returns true if the split view modifier combination is held.
*/
export function isSplitViewModifierEvent(
event: KeyboardEvent | MouseEvent
): boolean {
return isModKey(event) && !event.shiftKey && !event.altKey;
}
/**
* Starts tracking whether the split view modifier combination is held during
* events dispatched to the window, allowing code without direct access to the
* triggering event, such as command bar actions, to check it with
* isSplitViewModifierPressed. Synthetic clicks, such as the one kbar
* dispatches when Enter is pressed, are ignored so the state of the
* originating keyboard event is preserved.
*
* @returns a function that stops tracking.
*/
export function trackSplitViewModifier(): () => void {
const record = (event: KeyboardEvent | MouseEvent) => {
splitModifierPressed = isSplitViewModifierEvent(event);
};
const handleClick = (event: MouseEvent) => {
// Clicks not produced by a pointer press carry no modifier state.
if (event.detail === 0) {
return;
}
record(event);
};
window.addEventListener("keydown", record, { capture: true });
window.addEventListener("click", handleClick, { capture: true });
return () => {
splitModifierPressed = false;
window.removeEventListener("keydown", record, { capture: true });
window.removeEventListener("click", handleClick, { capture: true });
};
}
/**
* Whether the split view modifier combination was held during the most recent
* tracked event, see trackSplitViewModifier. Intended to be read while that
* event is still being dispatched.
*
* @returns true if the split view modifier is held.
*/
export function isSplitViewModifierPressed(): boolean {
return splitModifierPressed;
}
/**
* Navigates to the given location, opening it in the secondary pane of the
* split view instead when the split view modifier is held and the route can
* render in a pane.
*
* @param history the history instance to navigate with.
* @param to the path or location descriptor to navigate to.
*/
export function pushOrOpenInSplit(
history: History,
to: LocationDescriptor
): void {
if (isSplitViewModifierPressed() && !isMobile()) {
const location = typeof to === "string" ? parsePath(to) : to;
// Location state cannot be represented in the split query parameter, so
// routes that rely on it must navigate normally.
if (
location.state === undefined &&
location.pathname &&
isSplittablePath(location.pathname)
) {
openRouteInSplit(history, createPath(location));
return;
}
}
history.push(to);
}
/**
* Opens the given path in the secondary pane of the split view, keeping the
* current route in the primary pane, and focuses the secondary pane.
*
* @param history the history instance to navigate with.
* @param path the internal path to open in the secondary pane.
*/
export function openRouteInSplit(history: History, path: string): void {
const { location } = history;
setFocusedSplitPane("secondary");
history.push({
pathname: location.pathname,
hash: location.hash,
state: location.state,
search: setSplitPath(location.search, path),
});
}
/**
* Closes one pane of the split view, leaving the other pane's route as the
* single displayed route, and returns focus to the primary pane. Closing the
* primary pane promotes the secondary route to become the main route.
*
* @param history the history instance to navigate with.
* @param pane the pane to close, defaults to the secondary pane.
*/
export function closeSplitPane(
history: History,
pane: SplitViewPane = "secondary"
): void {
const { location } = history;
const splitPath = getSplitPath(location.search);
setFocusedSplitPane("primary");
withoutSplitViewNavigation(() => {
if (pane === "primary" && splitPath !== undefined) {
const target = parsePath(splitPath);
history.push({
...target,
search: setSplitPath(target.search, undefined),
});
return;
}
history.push({
pathname: location.pathname,
hash: location.hash,
state: location.state,
search: setSplitPath(location.search, undefined),
});
});
}