Files
outline/app/utils/splitView.ts
T
Tom Moor d57db81c6b feat: Split view (#13044)
Adds the ability to open a second route alongside the current one:

- The secondary route is stored in a `split` query string parameter so
  that reloading the page hydrates both panes.
- The secondary pane runs in its own in-memory router kept in sync with
  the query parameter, so links followed inside the pane navigate the
  pane rather than the primary route.
- Navigation while a split is open preserves the split, is directed to
  the focused pane, and routes that cannot render in a pane (such as
  settings) close the split.
- The focused pane is shown with an accent outline, updated as panes are
  clicked or focused, and keyboard shortcuts only apply to the focused
  pane.
- "Open in split view" added to document and collection menus and the
  command bar.
2026-07-19 11:57:33 -04:00

205 lines
5.9 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 } from "history";
import { parsePath } from "history";
import { action, observable } from "mobx";
import queryString from "query-string";
/**
* 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 (!isSplitablePath(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 isSplitablePath(pathname: string): boolean {
// Require an internal, absolute pathname – full URLs and protocol-relative
// values must never be treated as splitable.
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;
}
}
/**
* 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),
});
});
}