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(md): improve highlight sync logic for md toc (#7325)

Seamus5a938f9fa07e
diff --git a/apps/web/src/features/block-md/component/MarkdownOutline.test.ts b/apps/web/src/features/block-md/component/MarkdownOutline.test.ts
index 005d95fabe..9067135d1d 100644
--- a/apps/web/src/features/block-md/component/MarkdownOutline.test.ts
+++ b/apps/web/src/features/block-md/component/MarkdownOutline.test.ts
@@ -1,17 +1,44 @@
import { describe, expect, it } from 'vitest';
-import { getActiveHeadingIndex, shouldShowOutline } from './MarkdownOutline';
+import { getVisibleHeadingIndexes, shouldShowOutline } from './MarkdownOutline';
-describe('getActiveHeadingIndex', () => {
- it('selects the first heading before the document reaches it', () => {
- expect(getActiveHeadingIndex([120, 320, 640], 80)).toBe(0);
+describe('getVisibleHeadingIndexes', () => {
+ it('highlights every section overlapping the viewport', () => {
+ expect(getVisibleHeadingIndexes([20, 100, 300, 700], 900, 80, 600)).toEqual(
+ [0, 1, 2]
+ );
});
- it('selects the last heading above the active line', () => {
- expect(getActiveHeadingIndex([20, 100, 300], 150)).toBe(1);
+ it('keeps a long section highlighted after its heading scrolls away', () => {
+ expect(getVisibleHeadingIndexes([-900, 700, 1000], 1300, 0, 600)).toEqual([
+ 0,
+ ]);
});
- it('returns no selection when the document has no headings', () => {
- expect(getActiveHeadingIndex([], 150)).toBe(-1);
+ it('does not select a heading below the viewport', () => {
+ expect(getVisibleHeadingIndexes([700, 900, 1200], 1500, 0, 600)).toEqual(
+ []
+ );
+ });
+
+ it('excludes sections that only touch the viewport boundary', () => {
+ expect(getVisibleHeadingIndexes([-100, 0, 300, 600], 900, 0, 600)).toEqual([
+ 1, 2,
+ ]);
+ });
+
+ it('stops highlighting the last section after the editor ends', () => {
+ expect(getVisibleHeadingIndexes([-600, -400, -200], 0, 0, 600)).toEqual([]);
+ });
+
+ it('includes the last section while its content is still visible', () => {
+ expect(getVisibleHeadingIndexes([-600, -400, -200], 100, 0, 600)).toEqual([
+ 2,
+ ]);
+ });
+
+ it('returns no selection without headings or a visible viewport', () => {
+ expect(getVisibleHeadingIndexes([], 900, 0, 600)).toEqual([]);
+ expect(getVisibleHeadingIndexes([0, 100, 200], 900, 300, 300)).toEqual([]);
});
});
diff --git a/apps/web/src/features/block-md/component/MarkdownOutline.tsx b/apps/web/src/features/block-md/component/MarkdownOutline.tsx
index 4733c61a84..1c9698efe9 100644
--- a/apps/web/src/features/block-md/component/MarkdownOutline.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownOutline.tsx
@@ -7,15 +7,18 @@ import {
createSignal,
For,
onCleanup,
+ Show,
} from 'solid-js';
type OutlineHeading = {
key: string;
level: number;
text: string;
+ preview: string;
};
-const ACTIVE_HEADING_OFFSET = 80;
+const HEADING_SCROLL_OFFSET = 80;
+const SECTION_PREVIEW_LENGTH = 240;
const MIN_OUTLINE_HEADINGS = 3;
export const MARKDOWN_OUTLINE_WIDTH = 40;
@@ -26,18 +29,21 @@ export function shouldShowOutline(
return enabled && headingCount >= MIN_OUTLINE_HEADINGS;
}
-export function getActiveHeadingIndex(
+/** A section runs from its heading to the next heading (or the editor end). */
+export function getVisibleHeadingIndexes(
headingTops: number[],
- activeLine: number
-): number {
- if (headingTops.length === 0) return -1;
-
- let activeIndex = 0;
- for (const [index, top] of headingTops.entries()) {
- if (top > activeLine) break;
- activeIndex = index;
- }
- return activeIndex;
+ documentBottom: number,
+ viewportTop: number,
+ viewportBottom: number
+): number[] {
+ if (viewportBottom <= viewportTop) return [];
+
+ return headingTops.flatMap((top, index) => {
+ const bottom = headingTops[index + 1] ?? documentBottom;
+ return top < viewportBottom && bottom > viewportTop && bottom > top
+ ? [index]
+ : [];
+ });
}
function headingsEqual(a: OutlineHeading[], b: OutlineHeading[]) {
@@ -47,7 +53,8 @@ function headingsEqual(a: OutlineHeading[], b: OutlineHeading[]) {
(heading, index) =>
heading.key === b[index]?.key &&
heading.level === b[index]?.level &&
- heading.text === b[index]?.text
+ heading.text === b[index]?.text &&
+ heading.preview === b[index]?.preview
)
);
}
@@ -66,17 +73,29 @@ export function useMarkdownOutline(props: {
}
const refreshHeadings = () => {
- const nextHeadings = editor.getEditorState().read(() =>
- $getRoot()
- .getChildren()
- .filter($isHeadingNode)
- .map((node) => ({
- key: node.getKey(),
- level: Number(node.getTag().slice(1)),
- text: node.getTextContent().trim(),
- }))
- .filter((heading) => heading.text.length > 0)
- );
+ const nextHeadings = editor.getEditorState().read(() => {
+ const sections: OutlineHeading[] = [];
+ for (const node of $getRoot().getChildren()) {
+ const text = node.getTextContent().trim();
+ if ($isHeadingNode(node) && text) {
+ sections.push({
+ key: node.getKey(),
+ level: Number(node.getTag().slice(1)),
+ text,
+ preview: '',
+ });
+ } else {
+ const section = sections.at(-1);
+ if (section && section.preview.length < SECTION_PREVIEW_LENGTH) {
+ section.preview = `${section.preview} ${text}`
+ .replace(/\s+/g, ' ')
+ .trim()
+ .slice(0, SECTION_PREVIEW_LENGTH);
+ }
+ }
+ }
+ return sections;
+ });
setHeadings((current) =>
headingsEqual(current, nextHeadings) ? current : nextHeadings
@@ -95,44 +114,16 @@ export function useMarkdownOutline(props: {
type MarkdownOutlineState = ReturnType<typeof useMarkdownOutline>;
-function OutlineDash(props: { active: boolean }) {
- return (
- <span
- class={
- props.active
- ? 'h-px w-3 rounded-full bg-accent'
- : 'h-px w-2 rounded-full bg-ink/20'
- }
- />
- );
-}
-
-function OutlineItem(props: {
- active: boolean;
- label: string;
- onClick: () => void;
-}) {
- return (
- <button
- type="button"
- aria-label={props.label}
- aria-current={props.active ? 'location' : undefined}
- class="h-7 w-full truncate rounded-md px-2 text-left text-xs text-ink-muted hover:bg-hover hover:text-ink"
- classList={{ 'font-semibold text-accent': props.active }}
- onClick={props.onClick}
- >
- {props.label}
- </button>
- );
-}
-
export function MarkdownOutline(props: {
editor: Accessor<LexicalEditor | undefined>;
outline: MarkdownOutlineState;
portalMount: Accessor<HTMLElement>;
scrollContainer: Accessor<HTMLElement | undefined>;
}) {
- const [activeHeadingKey, setActiveHeadingKey] = createSignal<string>();
+ const [visibleHeadingKeys, setVisibleHeadingKeys] = createSignal<Set<string>>(
+ new Set()
+ );
+ const [hoveredIndex, setHoveredIndex] = createSignal<number>();
const [viewportCenter, setViewportCenter] = createSignal(0);
createEffect(() => {
@@ -156,30 +147,65 @@ export function MarkdownOutline(props: {
let frame: number | undefined;
- const syncActiveHeading = () => {
- const containerTop = scrollContainer.getBoundingClientRect().top;
- const activeLine = containerTop + ACTIVE_HEADING_OFFSET;
- const headingTops = currentHeadings.map(
- (heading) =>
- editor.getElementByKey(heading.key)?.getBoundingClientRect().top ??
- Number.POSITIVE_INFINITY
+ const syncVisibleHeadings = () => {
+ const root = editor.getRootElement();
+ const containerRect = scrollContainer.getBoundingClientRect();
+ const viewportTop = Math.max(
+ 0,
+ containerRect.top + scrollContainer.clientTop
+ );
+ const viewportBottom = Math.min(
+ window.innerHeight,
+ containerRect.top +
+ scrollContainer.clientTop +
+ scrollContainer.clientHeight
+ );
+ const renderedHeadings = currentHeadings.flatMap((heading) => {
+ const element = editor.getElementByKey(heading.key);
+ return element
+ ? [{ key: heading.key, top: element.getBoundingClientRect().top }]
+ : [];
+ });
+ const indexes = getVisibleHeadingIndexes(
+ renderedHeadings.map((heading) => heading.top),
+ root?.getBoundingClientRect().bottom ?? viewportTop,
+ viewportTop,
+ viewportBottom
+ );
+ setVisibleHeadingKeys(
+ new Set(indexes.map((index) => renderedHeadings[index].key))
);
- const activeIndex = getActiveHeadingIndex(headingTops, activeLine);
- setActiveHeadingKey(currentHeadings[activeIndex]?.key);
};
const queueViewportSync = () => {
- if (frame !== undefined) cancelAnimationFrame(frame);
+ if (frame !== undefined) return;
frame = requestAnimationFrame(() => {
- syncActiveHeading();
+ frame = undefined;
+ syncVisibleHeadings();
});
};
+ const resizeObserver = new ResizeObserver(queueViewportSync);
+ resizeObserver.observe(scrollContainer);
+ const unregisterRootListener = editor.registerRootListener(
+ (root, previousRoot) => {
+ if (previousRoot) resizeObserver.unobserve(previousRoot);
+ if (root) resizeObserver.observe(root);
+ queueViewportSync();
+ }
+ );
+ const unregisterUpdateListener =
+ editor.registerUpdateListener(queueViewportSync);
queueViewportSync();
scrollContainer.addEventListener('scroll', queueViewportSync, {
passive: true,
});
+ window.addEventListener('resize', queueViewportSync);
onCleanup(() => {
+ unregisterRootListener();
+ unregisterUpdateListener();
+ resizeObserver.disconnect();
scrollContainer.removeEventListener('scroll', queueViewportSync);
+ window.removeEventListener('resize', queueViewportSync);
if (frame !== undefined) cancelAnimationFrame(frame);
});
});
@@ -195,8 +221,8 @@ export function MarkdownOutline(props: {
scrollContainer.scrollTop +
elementTop -
containerTop -
- ACTIVE_HEADING_OFFSET,
- behavior: 'smooth',
+ HEADING_SCROLL_OFFSET,
+ behavior: 'instant',
});
};
@@ -205,51 +231,87 @@ export function MarkdownOutline(props: {
if (!headingElement) return;
scrollToElement(headingElement);
- setActiveHeadingKey(heading.key);
};
return (
- <div
- class="pointer-events-auto sticky z-1 w-3 -translate-y-1/2"
+ <nav
+ aria-label="Document outline"
+ class="pointer-events-auto sticky z-1 w-7 -translate-y-1/2"
style={{ top: `${viewportCenter()}px` }}
>
- <HoverCard
- closeDelay={0}
- content={
- <div class="max-h-[calc(100vh-6rem)] w-52 overflow-y-auto rounded-xl border border-edge bg-surface p-2 shadow-menu">
- <For each={props.outline.headings()}>
- {(heading) => (
- <OutlineItem
- active={activeHeadingKey() === heading.key}
- label={heading.text}
- onClick={() => scrollToHeading(heading)}
- />
- )}
- </For>
- </div>
- }
- contentZIndexClass="z-item-options-menu"
- gutter={-12}
- openDelay={0}
- placement="right"
- portalMount={props.portalMount()}
- trigger={
- <div
- aria-hidden="true"
- class="flex w-3 flex-col items-start gap-2 py-1"
- >
- <For each={props.outline.headings()}>
- {(heading) => (
- <OutlineDash active={activeHeadingKey() === heading.key} />
- )}
- </For>
- </div>
- }
- triggerAriaLabel="Document outline"
- triggerAs="nav"
- triggerClass="w-3 outline-none"
- triggerTabIndex={0}
- />
- </div>
+ <div
+ class="flex w-7 flex-col items-start overflow-y-auto py-1"
+ style={{ 'max-height': `${Math.max(0, viewportCenter() * 2 - 32)}px` }}
+ >
+ <For each={props.outline.headings()}>
+ {(heading, index) => {
+ const active = () => visibleHeadingKeys().has(heading.key);
+ const distance = () =>
+ Math.abs(index() - (hoveredIndex() ?? Number.POSITIVE_INFINITY));
+ const width = () => [26, 20, 14, 10][distance()] ?? 6;
+ const emphasized = () =>
+ hoveredIndex() === undefined ? active() : distance() === 0;
+
+ return (
+ <HoverCard
+ closeDelay={80}
+ closeOnScroll={false}
+ keepOpenOnTriggerPress
+ openDelay={0}
+ open={hoveredIndex() === index()}
+ onOpenChange={(open) => {
+ setHoveredIndex((current) =>
+ open ? index() : current === index() ? undefined : current
+ );
+ }}
+ content={
+ <div class="w-80 max-w-[calc(100vw-3rem)] rounded-xl border border-edge bg-surface px-3 py-2 shadow-menu">
+ <div class="truncate text-sm font-medium text-ink">
+ {heading.text}
+ </div>
+ <Show when={heading.preview}>
+ <p class="mt-1 line-clamp-3 text-sm leading-relaxed text-ink-muted">
+ {heading.preview}
+ </p>
+ </Show>
+ </div>
+ }
+ contentZIndexClass="z-item-options-menu"
+ gutter={10}
+ placement="right"
+ portalMount={props.portalMount()}
+ trigger={
+ <button
+ type="button"
+ aria-label={heading.text}
+ aria-current={active() ? 'location' : undefined}
+ class="flex h-2.5 w-7 items-center outline-none focus-visible:rounded-sm focus-visible:ring-1 focus-visible:ring-ink"
+ onFocus={() => setHoveredIndex(index())}
+ onBlur={() =>
+ setHoveredIndex((current) =>
+ current === index() ? undefined : current
+ )
+ }
+ onClick={() => scrollToHeading(heading)}
+ >
+ <span
+ aria-hidden="true"
+ class="h-0.5 shrink-0 transition-[width,background-color] duration-150 ease-out motion-reduce:transition-none"
+ classList={{
+ 'bg-ink': emphasized(),
+ 'bg-ink/20': !emphasized(),
+ }}
+ style={{ width: `${width()}px` }}
+ />
+ </button>
+ }
+ triggerClass="block w-7"
+ triggerTabIndex={-1}
+ />
+ );
+ }}
+ </For>
+ </div>
+ </nav>
);
}
diff --git a/apps/web/src/lib/core/component/HoverCard.test.tsx b/apps/web/src/lib/core/component/HoverCard.test.tsx
index e3d2e7ea91..bea2b830f9 100644
--- a/apps/web/src/lib/core/component/HoverCard.test.tsx
+++ b/apps/web/src/lib/core/component/HoverCard.test.tsx
@@ -10,7 +10,10 @@ vi.mock('@core/mobile/isTouchDevice', () => ({
isTouchDevice: () => false,
}));
-async function renderOpenCard(keepOpenOnTriggerPress?: boolean) {
+async function renderOpenCard(
+ keepOpenOnTriggerPress?: boolean,
+ closeOnScroll?: boolean
+) {
const onOpenChange = vi.fn();
render(() => (
<>
@@ -18,6 +21,7 @@ async function renderOpenCard(keepOpenOnTriggerPress?: boolean) {
open
onOpenChange={onOpenChange}
keepOpenOnTriggerPress={keepOpenOnTriggerPress}
+ closeOnScroll={closeOnScroll}
trigger={<span>Standup</span>}
content={<div>Card</div>}
/>
@@ -54,4 +58,24 @@ describe('HoverCard', () => {
expect(onOpenChange).toHaveBeenCalledWith(false);
});
+
+ it('dismisses on outside scrolling by default', async () => {
+ const onOpenChange = await renderOpenCard();
+
+ fireEvent.scroll(window);
+
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+
+ it('keeps stationary previews open through trigger presses and scrolling', async () => {
+ const onOpenChange = await renderOpenCard(true, false);
+
+ fireEvent.pointerDown(screen.getByText('Standup'));
+ fireEvent.scroll(window);
+
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+ fireEvent.pointerDown(screen.getByText('Elsewhere'));
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
});
diff --git a/apps/web/src/lib/core/component/HoverCard.tsx b/apps/web/src/lib/core/component/HoverCard.tsx
index c2559075e5..2551b9ca0d 100644
--- a/apps/web/src/lib/core/component/HoverCard.tsx
+++ b/apps/web/src/lib/core/component/HoverCard.tsx
@@ -120,6 +120,8 @@ export type HoverCardComponentProps = {
* otherwise the pointer-down dismisses it and the click reopens it.
*/
keepOpenOnTriggerPress?: boolean;
+ /** Dismiss on outside scrolling (default: true). Disable for stationary triggers. */
+ closeOnScroll?: boolean;
/** Callback when open state changes */
onOpenChange?: (open: boolean) => void;
/**
@@ -305,11 +307,11 @@ export function HoverCard(props: HoverCardComponentProps) {
// rapid scrolling never fires the close — leaving cards stranded as new
// triggers slide under the cursor.
createEffect(() => {
- if (!isHoverCardOpen()) return;
+ if (!isHoverCardOpen() || props.closeOnScroll === false) return;
const onScroll = (e: Event) => {
- const target = e.target as Node | null;
- if (contentEl && target && contentEl.contains(target)) return;
+ const target = e.target;
+ if (target instanceof Node && contentEl?.contains(target)) return;
handleOpenChange(false);
};
diff --git a/docs/AGENT_GUIDE/documents.md b/docs/AGENT_GUIDE/documents.md
index eb1a2c3bb1..8776fbb449 100644
--- a/docs/AGENT_GUIDE/documents.md
+++ b/docs/AGENT_GUIDE/documents.md
@@ -4,6 +4,19 @@ The document header has separate Share, Copy Share Link, and Side Panel buttons.
They are borderless with a soft rounded background on hover. Share opens the
sharing dialog; copying a link is a separate action.
+## Markdown outline
+
+On desktop, Markdown documents with at least three headings show a tick rail in
+the left margin. Every section whose content overlaps the editor viewport is
+highlighted, including a section whose heading has already scrolled above it.
+Hover a tick (or Tab to its button) to expand it and nearby ticks and show a
+rounded preview with the section heading and up to three lines of body text.
+While a preview is open, only its tick is emphasized; visible-section highlights
+return when the preview closes.
+Click a tick or press Enter to jump immediately to its heading without closing its preview
+or collapsing the expanded ticks. Scrolling, resizing, and
+editor updates refresh the visible-section highlights.
+
On a local HTTPS stack, document and image downloads use `/local-storage/`
on the app's HTTPS origin. A request to HTTP localhost indicates a stale
storage URL or stack configuration; hard-refresh after updating the stack.