mirror of
https://github.com/outline/outline.git
synced 2026-11-20 21:23:06 +03:00
348 lines
10 KiB
TypeScript
348 lines
10 KiB
TypeScript
import type { History } from "history";
|
||
import { 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";
|
||
import Desktop from "./Desktop";
|
||
|
||
/**
|
||
* 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 = [
|
||
"/api",
|
||
"/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. The desktop app has no tabs of its own, so
|
||
* the modifier stands in for the browser's open-in-new-tab; in the browser the
|
||
* shift key is added so that both native behaviors remain available.
|
||
*
|
||
* @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 {
|
||
if (!isModKey(event) || event.altKey) {
|
||
return false;
|
||
}
|
||
|
||
return Desktop.isElectron() ? !event.shiftKey : event.shiftKey;
|
||
}
|
||
|
||
/**
|
||
* Starts handling navigation that should be directed to the secondary pane of
|
||
* the split view. While active:
|
||
*
|
||
* - Clicks on internal links held with the split view modifier open the link
|
||
* in the secondary pane rather than following it.
|
||
* - Whether the modifier is held during events dispatched to the window is
|
||
* recorded, allowing code without direct access to the triggering event,
|
||
* such as the patched history methods, 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.
|
||
*
|
||
* @param history the history instance to navigate with.
|
||
* @returns a function that stops handling navigation.
|
||
*/
|
||
export function initSplitViewNavigation(history: History): () => void {
|
||
let timeout: ReturnType<typeof setTimeout> | undefined;
|
||
|
||
const record = (event: KeyboardEvent | MouseEvent) => {
|
||
splitModifierPressed = isSplitViewModifierEvent(event);
|
||
|
||
// Scope the recorded state to the dispatch of this event so that a
|
||
// navigation triggered later, while the modifier happens to still be held,
|
||
// is unaffected.
|
||
clearTimeout(timeout);
|
||
timeout = setTimeout(() => {
|
||
splitModifierPressed = false;
|
||
}, 0);
|
||
};
|
||
|
||
const handleClick = (event: MouseEvent) => {
|
||
// Clicks not produced by a pointer press carry no modifier state.
|
||
if (event.detail === 0) {
|
||
return;
|
||
}
|
||
record(event);
|
||
|
||
const path = splitViewPathFromClick(event);
|
||
if (path) {
|
||
// Also stops the click reaching the link, as react-router ignores an
|
||
// event that has had its default prevented.
|
||
event.preventDefault();
|
||
openRouteInSplit(history, path);
|
||
}
|
||
};
|
||
|
||
window.addEventListener("keydown", record, { capture: true });
|
||
window.addEventListener("click", handleClick, { capture: true });
|
||
|
||
return () => {
|
||
clearTimeout(timeout);
|
||
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 initSplitViewNavigation. 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;
|
||
}
|
||
|
||
/**
|
||
* Resolves the path that a click should open in the secondary pane of the
|
||
* split view.
|
||
*
|
||
* @param event the click event to inspect.
|
||
* @returns the internal path to open, or undefined when the click should be
|
||
* handled normally.
|
||
*/
|
||
function splitViewPathFromClick(event: MouseEvent): string | undefined {
|
||
if (
|
||
event.defaultPrevented ||
|
||
event.button !== 0 ||
|
||
isMobile() ||
|
||
!isSplitViewModifierEvent(event) ||
|
||
!(event.target instanceof Element)
|
||
) {
|
||
return undefined;
|
||
}
|
||
|
||
const anchor = event.target.closest("a[href]");
|
||
if (
|
||
!(anchor instanceof HTMLAnchorElement) ||
|
||
anchor.target ||
|
||
anchor.hasAttribute("download")
|
||
) {
|
||
return undefined;
|
||
}
|
||
|
||
// Editor links resolve their own destination, see useEditorClickHandlers.
|
||
if (anchor.closest(".ProseMirror")) {
|
||
return undefined;
|
||
}
|
||
|
||
if (
|
||
anchor.origin !== window.location.origin ||
|
||
!isSplittablePath(anchor.pathname)
|
||
) {
|
||
return undefined;
|
||
}
|
||
|
||
return `${anchor.pathname}${anchor.search}${anchor.hash}`;
|
||
}
|
||
|
||
/**
|
||
* 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");
|
||
|
||
// The location below is already the intended result, so it is pushed without
|
||
// further split view handling.
|
||
withoutSplitViewNavigation(() => {
|
||
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),
|
||
});
|
||
});
|
||
}
|