Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(settings): url layout and structure (#6992)

dev-rb7cae9e2b70d9
diff --git a/apps/web/src/components/app/split-layout/tests/activity-registration.test.tsx b/apps/web/src/components/app/split-layout/tests/activity-registration.test.tsx
index 9e9446bdce..c702526c74 100644
--- a/apps/web/src/components/app/split-layout/tests/activity-registration.test.tsx
+++ b/apps/web/src/components/app/split-layout/tests/activity-registration.test.tsx
@@ -13,6 +13,16 @@ const state = vi.hoisted(() => ({
mountActivity: vi.fn(),
}));
+vi.mock('@service-storage/websocket', () => ({
+ storageWS: { reconnectIfDisconnected: vi.fn() },
+ createWebSocketJob: vi.fn(),
+}));
+vi.mock('@service-connection/websocket', () => ({
+ ws: { addEventListener: vi.fn(), send: vi.fn() },
+ state: () => 'closed',
+ createConnectionBlockWebsocketEffect: vi.fn(),
+ createConnectionWebsocketEffect: vi.fn(),
+}));
vi.mock('@core/auth', () => ({
useIsAuthenticated: () => () => state.authenticated(),
}));
@@ -96,7 +106,9 @@ vi.mock('@core/mobile/isTouchDevice', () => ({
isTouchDevice: () => false,
}));
vi.mock('@queries/agent-schedule/entities', () => ({}));
-vi.mock('@ui', () => ({}));
+vi.mock('@ui', () => ({
+ createVariants: () => () => '',
+}));
beforeEach(() => {
vi.clearAllMocks();
diff --git a/apps/web/src/features/auth/EmailAuth.tsx b/apps/web/src/features/auth/EmailAuth.tsx
index 9e29dce427..33f505cbed 100644
--- a/apps/web/src/features/auth/EmailAuth.tsx
+++ b/apps/web/src/features/auth/EmailAuth.tsx
@@ -8,7 +8,6 @@ import { publishLoginSuccess } from '@core/auth/login-events';
import { LoadingBlock } from '@core/component/LoadingBlock';
import { toast } from '@core/component/Toast/Toast';
import { restoreSettingsReturnTo } from '@core/constant/SettingsState';
-import { appendSettingsSplitToUrl } from '@core/constant/settingsSplitUrl';
import { settingsTabToSlug } from '@core/constant/settingsTabsConfig';
import { useEmailLinks } from '@core/email-link';
import { consumeInboxLinkReturn } from '@core/email-link/return-layout';
@@ -107,10 +106,7 @@ function EmailSignupCallback(props: Pick<EmailAuthParams, 'successPath'>) {
* granted access still sees the result. Only reachable when the stash is
* missing — storage blocked, or a callback URL opened outside its own flow.
*/
-const POST_LINK_FALLBACK_ROUTE = appendSettingsSplitToUrl(
- DEFAULT_ROUTE,
- settingsTabToSlug('Connected')
-);
+const POST_LINK_FALLBACK_ROUTE = `${DEFAULT_ROUTE}/~/settings/${settingsTabToSlug('Connected')}`;
/**
* Handles the OAuth callback after an already-authenticated user adds another Gmail
diff --git a/apps/web/src/features/settings/Settings.tsx b/apps/web/src/features/settings/Settings.tsx
index dacd7bbba9..43deb43713 100644
--- a/apps/web/src/features/settings/Settings.tsx
+++ b/apps/web/src/features/settings/Settings.tsx
@@ -1,4 +1,3 @@
-import { toBaseRelative } from '@app/constants/routerBase';
import { useParams, useNavigate as useSplitNavigate } from '@app/split-router';
import { PillTabs } from '@components/app/mobile/PillTabs';
import { HeaderIsland } from '@components/app/split-layout/components/HeaderIsland';
@@ -11,10 +10,8 @@ import { TabsInsetDropdown } from '@core/component/TabsInsetDropdown';
import {
isSoloSettings,
type SettingsTab,
- settingsTabFromSplitPath,
useSettingsState,
} from '@core/constant/SettingsState';
-import { stripSettingsSplitFromUrl } from '@core/constant/settingsSplitUrl';
import {
settingsSlugToTab,
settingsTabToSlug,
@@ -29,7 +26,6 @@ import ArrowsIn from '@phosphor/arrows-in.svg';
import ArrowsOut from '@phosphor/arrows-out.svg';
import CaretLeftIcon from '@phosphor/caret-left.svg';
import SignOutIcon from '@phosphor/sign-out.svg';
-import { useLocation, useNavigate } from '@solidjs/router';
import { Button, cn, Layer, SideNav } from '@ui';
import {
createRenderEffect,
@@ -53,7 +49,6 @@ const COMPACT_WIDTH = 660;
const NARROW_WIDTH = 820;
export function SettingsPanelComponentWrapper() {
- const location = useLocation();
const params = useParams<{ tab?: string }>();
// Sync the active page from the docked split's URL (`settings/<slug>`). Read
@@ -65,11 +60,9 @@ export function SettingsPanelComponentWrapper() {
// activeTabId read is untracked so a tab click (which sets it, then updates
// the URL) isn't reverted by this effect firing before the URL catches up.
createRenderEffect(() => {
- const tab =
- (params.tab && settingsSlugToTab(params.tab)) ??
- settingsTabFromSplitPath(location.pathname);
+ const tab = settingsSlugToTab(params.tab ?? '') ?? 'Account';
- if (tab && untrack(activeTabId) !== tab) setActiveTabId(tab);
+ if (untrack(activeTabId) !== tab) setActiveTabId(tab);
});
return (
@@ -81,20 +74,12 @@ export function SettingsPanelComponentWrapper() {
/** Old settings URLs still open their section, over the restored app surface. */
function MobileSettingsDeepLink() {
- const location = useLocation();
- const navigate = useNavigate();
- const { openSettings } = useSettingsState();
+ const params = useParams<{ tab?: string }>();
+ const { openSettings, restoreMobileDeepLink } = useSettingsState();
onMount(() => {
- const tab = settingsTabFromSplitPath(location.pathname) ?? activeTabId();
-
- openSettings(tab);
- navigate(
- stripSettingsSplitFromUrl(
- `${toBaseRelative(location.pathname)}${location.search}${location.hash}`
- ),
- { replace: true }
- );
+ openSettings(settingsSlugToTab(params.tab ?? '') ?? 'Account');
+ restoreMobileDeepLink();
});
return null;
diff --git a/apps/web/src/lib/core/constant/SettingsState.test.tsx b/apps/web/src/lib/core/constant/SettingsState.test.tsx
index d0cf089598..0596715b11 100644
--- a/apps/web/src/lib/core/constant/SettingsState.test.tsx
+++ b/apps/web/src/lib/core/constant/SettingsState.test.tsx
@@ -18,10 +18,12 @@ import { useSettingsState } from './SettingsState';
const mocks = vi.hoisted(() => ({
mobile: true,
hasSettingsSplit: false,
+ otherSplit: false,
+ solo: false,
updateCurrentEntry: vi.fn(),
removeSplit: vi.fn(),
openWithSplit: vi.fn(),
- replaceAllSplits: vi.fn(),
+ managerOpenWithSplit: vi.fn(),
navigate: vi.fn(),
}));
vi.mock('@core/mobile/isMobile', () => ({ isMobile: () => mocks.mobile }));
@@ -30,8 +32,21 @@ vi.mock('@core/mobile/isTouchDevice', () => ({
}));
vi.mock('@app/signal/splitLayout', () => ({
globalSplitManager: () => ({
- splits: () =>
- mocks.hasSettingsSplit
+ splits: () => [
+ ...(mocks.otherSplit
+ ? [{ id: 'app-split', content: { type: 'component', id: 'inbox' } }]
+ : []),
+ ...(mocks.hasSettingsSplit
+ ? [
+ {
+ id: 'settings-split',
+ content: { type: 'component', id: 'settings' },
+ },
+ ]
+ : []),
+ ],
+ getVisibleSplits: () =>
+ mocks.solo
? [
{
id: 'settings-split',
@@ -40,6 +55,7 @@ vi.mock('@app/signal/splitLayout', () => ({
]
: [],
removeSplit: mocks.removeSplit,
+ openWithSplit: mocks.managerOpenWithSplit,
getSplit: () => ({ updateCurrentEntry: mocks.updateCurrentEntry }),
}),
}));
@@ -54,10 +70,6 @@ vi.mock('@solidjs/router', () => ({
hash: '#position',
}),
}));
-vi.mock('./settingsSplitUrl', () => ({
- stripSettingsSplitFromUrl: (url: string) => url,
- appendSettingsSplitToUrl: (url: string) => url,
-}));
vi.mock('./settingsTabsConfig', () => ({
settingsTabToSlug: (tab: string) => tab.toLowerCase(),
settingsSlugToTab: () => undefined,
@@ -87,6 +99,8 @@ beforeEach(() => {
vi.clearAllMocks();
mocks.mobile = true;
mocks.hasSettingsSplit = false;
+ mocks.otherSplit = false;
+ mocks.solo = false;
setSplitActiveTabId('Account');
});
afterEach(cleanup);
@@ -164,7 +178,6 @@ describe('settings entry points', () => {
expect(mobile.page()).toBeUndefined();
expect(state.activeTabId()).toBeUndefined();
expect(mocks.openWithSplit).not.toHaveBeenCalled();
- expect(mocks.replaceAllSplits).not.toHaveBeenCalled();
expect(mocks.navigate).not.toHaveBeenCalled();
});
@@ -247,15 +260,7 @@ describe('settings entry points', () => {
state.openSettings('Billing');
expect(mobile.open()).toBe(false);
expect(state.activeTabId()).toBe('Billing');
- expect(mocks.replaceAllSplits).toHaveBeenCalledWith({
- type: 'component',
- id: 'settings',
- entryMetadata: {
- route: {
- matches: [{ id: 'settings', params: { tab: 'billing' } }],
- },
- },
- });
+ expect(mocks.navigate).toHaveBeenCalledWith('/settings/billing');
state.openSettingsInSplit('Appearance');
expect(mocks.openWithSplit).toHaveBeenCalledWith(
{
@@ -270,4 +275,50 @@ describe('settings entry points', () => {
expect.objectContaining({ allowDuplicate: false, preferNewSplit: true })
);
});
+
+ it('restores the previous split URL when closing fullscreen settings', () => {
+ mocks.mobile = false;
+ const { state } = mountSettings();
+ state.openSettings('Billing');
+ mocks.hasSettingsSplit = true;
+ mocks.solo = true;
+ state.closeSettings();
+ expect(mocks.navigate).toHaveBeenLastCalledWith(
+ '/component/inbox?keep=1#position',
+ { replace: true }
+ );
+ });
+
+ it('restores the app and docks the selected page without constructing a split URL', async () => {
+ mocks.mobile = false;
+ const { state } = mountSettings();
+ state.openSettingsInSplit('Account');
+ mocks.hasSettingsSplit = true;
+ state.moveSettingsToSolo('Connected');
+ expect(mocks.navigate).toHaveBeenCalledWith('/settings/connected');
+ mocks.solo = true;
+ await state.moveSettingsToSplit('Billing');
+ expect(mocks.navigate).toHaveBeenLastCalledWith(
+ '/component/inbox?keep=1#position',
+ { replace: true }
+ );
+ expect(mocks.managerOpenWithSplit).toHaveBeenCalledWith(
+ expect.objectContaining({
+ entryMetadata: {
+ route: { matches: [{ id: 'settings', params: { tab: 'billing' } }] },
+ },
+ }),
+ expect.objectContaining({ allowDuplicate: false, preferNewSplit: true })
+ );
+ });
+
+ it('restores mobile deep links by closing the pane or using Inbox alone', () => {
+ mocks.hasSettingsSplit = true;
+ const { state } = mountSettings();
+ state.restoreMobileDeepLink();
+ expect(mocks.navigate).toHaveBeenCalledWith('/inbox', { replace: true });
+ mocks.otherSplit = true;
+ state.restoreMobileDeepLink();
+ expect(mocks.removeSplit).toHaveBeenCalledWith('settings-split');
+ });
});
diff --git a/apps/web/src/lib/core/constant/SettingsState.tsx b/apps/web/src/lib/core/constant/SettingsState.tsx
index 5618a86793..d1eb64ecaa 100644
--- a/apps/web/src/lib/core/constant/SettingsState.tsx
+++ b/apps/web/src/lib/core/constant/SettingsState.tsx
@@ -13,12 +13,7 @@ import { isTouchDevice } from '@core/mobile/isTouchDevice';
import { activeTabId, setActiveTabId } from '@core/signal/settingsTab';
import { useLocation, useNavigate } from '@solidjs/router';
import { createMemo, createSignal } from 'solid-js';
-import {
- appendSettingsSplitToUrl,
- settingsTabSlugFromUrl,
- stripSettingsSplitFromUrl,
-} from './settingsSplitUrl';
-import { settingsSlugToTab, settingsTabToSlug } from './settingsTabsConfig';
+import { settingsTabToSlug } from './settingsTabsConfig';
export type SettingsTab =
| 'Account'
@@ -66,18 +61,6 @@ export const restoreSettingsReturnTo = (url: string) => {
/** Read-only view of {@link settingsReturnTo} for capture across a reload. */
export const currentSettingsReturnTo = settingsReturnTo;
-/**
- * Extract the active settings tab from a docked-split path
- * (`.../settings/<slug>`), or undefined if the path has no settings split.
- * Scans type positions (even indices, base stripped) so a block id that happens
- * to be "settings" isn't mistaken for one — mirrors
- * {@link stripSettingsSplitFromUrl}.
- */
-export const settingsTabFromSplitPath = (
- pathname: string
-): SettingsTab | undefined =>
- settingsSlugToTab(settingsTabSlugFromUrl(toBaseRelative(pathname)) ?? '');
-
/**
* Whether settings is the only visible split — the "clobbered" mode that
* looks and behaves like the old fullscreen route (app sidebar hidden,
@@ -107,9 +90,11 @@ export const isSoloSettings = () => {
export const useSettingsState = () => {
const mobileSettings = useMobileSettings();
- const { openWithSplit, replaceAllSplits } = useSplitLayout();
+ const { openWithSplit } = useSplitLayout();
const navigate = useNavigate();
const location = useLocation();
+ const currentUrl = () =>
+ `${toBaseRelative(location.pathname)}${location.search}${location.hash}`;
const getSettingsSplit = () => {
const splitManager = globalSplitManager();
@@ -178,30 +163,18 @@ export const useSettingsState = () => {
}, 10);
};
- // Capture the current layout (minus any settings split) as where "Back to
- // app"/"Move to split" should return to, then clobber every other split so
- // settings becomes the sole one. Shared by opening settings fresh and by
- // collapsing a docked-alongside layout back down to solo. Capture query and
- // hash too so content locations are restored.
+ // The standalone settings URL is a normal history entry. Browser Back
+ // restores the exact docked layout (if there was one).
const collapseToSoloSettings = (tab: SettingsTab) => {
- setSettingsReturnTo(
- stripSettingsSplitFromUrl(
- `${toBaseRelative(location.pathname)}${location.search}${location.hash}`
- )
- );
+ if (!splitOpen()) setSettingsReturnTo(currentUrl());
setActiveTabId(tab);
- replaceAllSplits(settingsContent(tab));
+ navigate(`/settings/${settingsTabToSlug(tab)}`);
};
// Mobile opens an in-place settings sheet; a fresh open lands on its index.
// Desktop keeps the solo/split layout and defaults to Account.
const openSettings = (tab?: SettingsTab) => {
if (isMobile()) {
- setSettingsReturnTo(
- stripSettingsSplitFromUrl(
- `${toBaseRelative(location.pathname)}${location.search}${location.hash}`
- )
- );
mobileSettings.openSettings(tab);
return;
@@ -250,6 +223,7 @@ export const useSettingsState = () => {
if (activeTabId) setActiveTabId(activeTabId);
const tab = activeTabId ?? 'Account';
+ if (!splitOpen()) setSettingsReturnTo(currentUrl());
openWithSplit(settingsContent(tab), {
activate: true,
@@ -264,49 +238,42 @@ export const useSettingsState = () => {
const removeSettingsSplit = () => {
const settingsSplit = getSettingsSplit();
- if (settingsSplit) {
- globalSplitManager()?.removeSplit(settingsSplit.id);
- }
+ if (settingsSplit) globalSplitManager()?.removeSplit(settingsSplit.id);
+ setSettingsReturnTo(undefined);
};
const closeSettings = () => {
if (isMobile()) {
mobileSettings.close();
-
return;
}
if (isSoloSettings()) {
- navigate(settingsReturnTo() ?? DEFAULT_ROUTE, { replace: true });
-
+ const returnTo = settingsReturnTo() ?? DEFAULT_ROUTE;
+ setSettingsReturnTo(undefined);
+ navigate(returnTo, { replace: true });
return;
}
removeSettingsSplit();
};
- // Dock settings alongside the layout we came from: rebuild that layout and
- // add settings back as a `settings/<tab>` split. Navigating straight to the
- // composed path (rather than mutating splits directly) lets the URL→layout
- // sync rebuild everything in one pass.
- const moveSettingsToSplit = (tab?: SettingsTab) => {
- if (tab) setActiveTabId(tab);
- // Strip any settings split already in the target layout before re-adding
- // one, so repeatedly toggling fullscreen ⇄ split reuses a single settings
- // split (on the current tab) instead of stacking a new one each cycle.
- // Preserve the return layout's query and hash when appending settings.
- const returnTo = stripSettingsSplitFromUrl(
- settingsReturnTo() ?? DEFAULT_ROUTE
- );
-
- navigate(
- appendSettingsSplitToUrl(returnTo, settingsTabToSlug(activeTabId()))
- );
+ // Restore the layout from before settings opened, then dock the current tab.
+ // The layout manager owns URL serialization for the new settings pane.
+ const moveSettingsToSplit = async (tab?: SettingsTab) => {
+ const currentTab = tab ?? activeTabId();
+ setActiveTabId(currentTab);
+ await navigate(settingsReturnTo() ?? DEFAULT_ROUTE, { replace: true });
+ globalSplitManager()?.openWithSplit(settingsContent(currentTab), {
+ activate: true,
+ allowDuplicate: false,
+ preferNewSplit: true,
+ mergeHistory: false,
+ });
+ focusSettingsPanel();
};
- // Collapse a docked-alongside layout back down to a lone settings split.
- // The return layout is the current path minus the settings split, so "Back
- // to app" / "Move to split" land correctly.
+ // Fullscreen has its own URL; browser Back restores the docked layout.
const moveSettingsToSolo = (tab?: SettingsTab) => {
collapseToSoloSettings(tab ?? activeTabId());
};
@@ -330,28 +297,35 @@ export const useSettingsState = () => {
const settingsSplit = getSettingsSplit();
if (settingsSplit) {
const manager = globalSplitManager();
- // Docked but not the active split → bring focus to it instead of closing.
+ // Docked but not active: bring settings forward. Otherwise minimize it.
if (manager && manager.activeSplitId() !== settingsSplit.id) {
manager.activateSplit(settingsSplit.id);
focusSettingsPanel();
-
return;
}
- // Docked and already focused → close it.
- manager?.removeSplit(settingsSplit.id);
-
+ removeSettingsSplit();
return;
}
- // Nothing open → open settings as a solo split on desktop.
openSettings();
};
+ const restoreMobileDeepLink = () => {
+ const manager = globalSplitManager();
+ const split = getSettingsSplit();
+ if (!manager || !split || manager.splits().length === 1) {
+ navigate(DEFAULT_ROUTE, { replace: true });
+ return;
+ }
+ manager.removeSplit(split.id);
+ };
+
return {
settingsOpen: () => (isMobile() ? mobileSettings.open() : splitOpen()),
openSettings,
openSettingsInSplit,
selectTab,
+ restoreMobileDeepLink,
closeSettings,
moveSettingsToSplit,
moveSettingsToSolo,
diff --git a/apps/web/src/lib/core/constant/settingsSplitUrl.test.ts b/apps/web/src/lib/core/constant/settingsSplitUrl.test.ts
deleted file mode 100644
index 0ef0d47bd0..0000000000
--- a/apps/web/src/lib/core/constant/settingsSplitUrl.test.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-import { DEFAULT_ROUTE } from '@app/constants/defaultRoute';
-import { describe, expect, it, vi } from 'vitest';
-import {
- appendSettingsSplitToUrl,
- settingsTabSlugFromUrl,
- stripSettingsSplitFromUrl,
-} from './settingsSplitUrl';
-
-// Legacy split decoding only needs alias resolution to exist.
-vi.mock('@core/constant/allBlocks', () => ({
- isBlockAlias: vi.fn(() => false),
- resolveBlockAlias: vi.fn((type: string) => type),
-}));
-
-vi.mock('@service-storage/websocket', () => ({
- storageWS: { reconnectIfDisconnected: vi.fn() },
- createWebSocketJob: vi.fn(),
-}));
-vi.mock('@service-connection/websocket', () => ({
- ws: { addEventListener: vi.fn(), send: vi.fn() },
- state: () => 'closed',
- createConnectionBlockWebsocketEffect: vi.fn(),
- createConnectionWebsocketEffect: vi.fn(),
-}));
-
-describe('settingsTabSlugFromUrl', () => {
- it('reads schema-defaulted settings state from a framed layout', () => {
- expect(settingsTabSlugFromUrl('/drive/folder/f-1/~/settings')).toBe(
- 'account'
- );
- });
-});
-
-describe('stripSettingsSplitFromUrl', () => {
- it('canonicalizes an old flat URL and drops unowned search', () => {
- expect(
- stripSettingsSplitFromUrl('/component/mail/email/e-1?filter=all#sel')
- ).toBe('/component/mail/~/email/e-1#sel');
- });
-
- it('strips a trailing settings split, preserving the hash', () => {
- expect(
- stripSettingsSplitFromUrl(
- '/component/mail/email/e-1/settings/account?filter=all#sel'
- )
- ).toBe('/component/mail/~/email/e-1#sel');
- });
-
- it('strips the legacy component/settings form', () => {
- expect(
- stripSettingsSplitFromUrl('/component/inbox/component/settings')
- ).toBe('/component/inbox');
- });
-
- it('does not mistake a block id named settings for a settings split', () => {
- expect(stripSettingsSplitFromUrl('/md/settings')).toBe('/md/settings');
- });
-
- it('falls back to the default route when settings was the only split', () => {
- expect(stripSettingsSplitFromUrl('/settings/account')).toBe(DEFAULT_ROUTE);
- });
-
- it('remaps owned repeated search state after removing a variable-length pane', () => {
- expect(
- stripSettingsSplitFromUrl(
- '/drive/folder/f-1/~/settings/account/~/component/mail?s0.drive.sort=created_at&s1.settings.tab=account&s2.mail.filter=unread&s2.mail.filter=starred'
- )
- ).toBe(
- '/drive/folder/f-1/~/component/mail?s0.drive.sort=created_at&s1.mail.filter=unread&s1.mail.filter=starred'
- );
- });
-
- it('accepts an old Agents chat alias and emits its canonical route', () => {
- expect(
- stripSettingsSplitFromUrl('/agent-chats/chat-1/~/settings/account')
- ).toBe('/agents/chat/chat-1');
- });
-});
-
-describe('appendSettingsSplitToUrl', () => {
- it('appends the settings split before the query and hash', () => {
- expect(
- appendSettingsSplitToUrl(
- '/component/mail/email/e-1?filter=all#sel',
- 'account'
- )
- ).toBe('/component/mail/~/email/e-1/~/settings/account#sel');
- });
-
- it('handles a trailing slash on the base path', () => {
- expect(appendSettingsSplitToUrl('/component/inbox/', 'account')).toBe(
- '/component/inbox/~/settings/account'
- );
- });
-
- it('canonicalizes aliases and preserves repeated owned search values', () => {
- expect(
- appendSettingsSplitToUrl(
- '/drive/tab/owned?s0.drive.tag=one&s0.drive.tag=two#sel',
- 'billing'
- )
- ).toBe('/drive/~/settings/billing?s0.drive.tag=one&s0.drive.tag=two#sel');
- });
-});
diff --git a/apps/web/src/lib/core/constant/settingsSplitUrl.ts b/apps/web/src/lib/core/constant/settingsSplitUrl.ts
deleted file mode 100644
index 7826180e5a..0000000000
--- a/apps/web/src/lib/core/constant/settingsSplitUrl.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-import { DEFAULT_ROUTE } from '@app/constants/defaultRoute';
-import {
- createRoutesManifest,
- decodeSplitRouterLocation,
- rootRouteMatch,
- routeParams,
- serializeSplitRouterLocation,
-} from '@app/lib/split-router';
-import { appSplitRoutes } from '@components/app/split-layout/split-router/app-routes';
-
-export const settingsTabSlugFromUrl = (
- urlString: string
-): string | undefined => {
- // Standalone URL operations can run before a router exists; keep state local.
- const routes = createRoutesManifest(appSplitRoutes);
- const entry = decodeSplitRouterLocation({
- routes,
- location: urlString,
- }).entries.find(
- ({ location }) => rootRouteMatch(location.route)?.id === 'settings'
- );
-
- const tab = routeParams(entry?.location.route).tab;
- return typeof tab === 'string' ? tab : undefined;
-};
-
-/**
- * Drop a settings split from a base-relative split-layout URL, if present.
- * Handles both the URL encoding (`settings/<tab>`) and the legacy internal
- * form (`component/settings`). Only type positions (even indices) are
- * inspected so a block id that happens to be "settings" isn't mistaken for
- * one.
- *
- * The owned query string and hash are preserved. When settings was the only
- * split there is no layout left to return to, so the default route is returned.
- */
-export const stripSettingsSplitFromUrl = (urlString: string): string => {
- const routes = createRoutesManifest(appSplitRoutes);
- const parsed = decodeSplitRouterLocation({
- routes,
- location: urlString,
- });
- const entries = [...parsed.entries];
- const removedSplitIndex = entries.findIndex(
- ({ location }) => rootRouteMatch(location.route)?.id === 'settings'
- );
- if (removedSplitIndex >= 0) entries.splice(removedSplitIndex, 1);
-
- if (entries.length === 0) return DEFAULT_ROUTE;
-
- return serializeSplitRouterLocation({
- routes,
- entries,
- previous: parsed.externalLocation,
- preserveHash: true,
- });
-};
-
-/**
- * Append a docked settings split (`settings/<slug>`) to a base-relative
- * split-layout URL, keeping its owned query string and hash.
- */
-export const appendSettingsSplitToUrl = (
- urlString: string,
- settingsTabSlug: string
-): string => {
- const routes = createRoutesManifest(appSplitRoutes);
- const parsed = decodeSplitRouterLocation({
- routes,
- location: urlString,
- });
- return serializeSplitRouterLocation({
- routes,
- entries: [
- ...parsed.entries,
- {
- location: {
- route: {
- matches: [
- {
- id: 'settings',
- params: { tab: settingsTabSlug },
- },
- ],
- },
- },
- },
- ],
- previous: parsed.externalLocation,
- preserveHash: true,
- });
-};
diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.md
index c4637cf911..218fd47074 100644
--- a/docs/AGENT_GUIDE/surfaces.md
+++ b/docs/AGENT_GUIDE/surfaces.md
@@ -1129,8 +1129,12 @@ outside tap, or a downward swipe dismisses the sheet. Opening Settings again
starts at the main page; explicit links (for example Account) open their
section directly. Existing settings URLs open the requested section in the sheet
and restore the underlying app route. The header stays visible while forms
-scroll, including with the keyboard open. Desktop settings retain their panel
-and split navigation.
+scroll, including with the keyboard open. On desktop, `/app/settings/<tab>`
+opens settings fullscreen, while `/app/inbox/~/settings/<tab>` docks it beside
+Inbox. **Open fullscreen** pushes a standalone settings URL; browser Back
+restores the preceding split layout. **Move to split** restores the app layout
+and docks the selected tab, while closing a docked settings pane minimizes it.
+A direct fullscreen link returns to Inbox when there is no prior app layout.
Left nav: General → `Account` (profile, delete account), `API Keys` (create /
list / delete personal keys; the secret is shown only once and is sent as