Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { URL_PARAMS } from '@block-pdf/constants';
import type { PDFViewer } from '@block-pdf/PdfViewer';
import {
FindState,
type IUpdateFindControlStateEvent,
} from '@block-pdf/PdfViewer/EventBus';
import type { FindController } from '@block-pdf/PdfViewer/FindController';
import { buildSimpleEntityUrl } from '@core/util/url';
import { waitForSignal } from '@core/util/waitForSignal';
import { createCallback } from '@solid-primitives/rootless';
import type { Accessor } from 'solid-js';
import { z } from 'zod';
import { usePdfDocument } from '../context/pdf-document-context';
import { usePdfViewer } from '../context/pdf-viewer-context';
export { URL_PARAMS };
export type LocationSearchParams = {
annotationId?: string;
searchPage?: string;
searchMatchNumOnPage?: string;
searchSnippet?: string;
searchRawQuery?: string;
highlightTerms?: string;
pageNumber?: string;
yPos?: string;
x?: string;
width?: string;
height?: string;
};
/**
* Type for location parameters received from block params (e.g., from URL query string).
* All values are strings as they come from URL parameters.
*/
export type LocationBlockParams = Partial<
Record<(typeof URL_PARAMS)[keyof typeof URL_PARAMS], string>
>;
export enum LocationType {
General = 'general',
Precise = 'precise',
Annotation = 'annotation',
}
/**
* Types of PDF locations, ordered by increasing precision.
*/
export const PdfLocationTypes = ['general', 'precise', 'annotation'] as const;
export type PdfLocationType = (typeof PdfLocationTypes)[number];
/**
* Map showing which location types can be used for each fidelity level.
* Higher fidelity levels can use all lower fidelity locations.
*/
export const LOCATION_FIDELITY_MAP: Record<PdfLocationType, PdfLocationType[]> =
{
general: ['general'],
precise: ['precise', 'general'],
annotation: ['annotation', 'precise', 'general'],
} as const;
export interface GeneralLocation {
type: 'general';
pageIndex: number;
y: number;
}
export interface PreciseLocation {
type: 'precise';
pageIndex: number;
y: number;
x: number;
width: number;
height: number;
}
export interface AnnotationLocation {
type: 'annotation';
pageIndex: number;
id: string;
}
export type PdfShareLocation = PreciseLocation | AnnotationLocation;
export interface SearchLocation {
type: 'search';
pageIndex: number;
snippet: string;
rawQuery: string;
highlightTerms: string[];
}
export type PdfLocation =
| GeneralLocation
| PreciseLocation
| AnnotationLocation
| SearchLocation;
export const PdfOrderInfoSchema = z.object({
pageIndex: z.number(),
pageOrder: z.number().optional(),
});
export type PdfOrderInfo = z.infer<typeof PdfOrderInfoSchema>;
const useIsViewerReadyForScroll = () => {
const rootViewer = usePdfViewer().root;
return () => rootViewer.isReady() && rootViewer.hasVisiblePages();
};
/** Builds a standalone PDF link with only the selected location parameters. */
export function locationToUrl(
documentId: string,
location: PdfLocation | undefined
): string {
const url = new URL(buildSimpleEntityUrl({ type: 'pdf', id: documentId }));
const params = url.searchParams;
if (!location) {
return url.toString();
}
const format = (n: number) => Number(n.toFixed(3)).toString();
switch (location.type) {
case 'general':
params.set(URL_PARAMS.pageNumber, format(location.pageIndex));
params.set(URL_PARAMS.yPos, format(location.y));
break;
case 'precise':
params.set(URL_PARAMS.pageNumber, format(location.pageIndex));
params.set(URL_PARAMS.yPos, format(location.y));
params.set(URL_PARAMS.x, format(location.x));
params.set(URL_PARAMS.width, format(location.width));
params.set(URL_PARAMS.height, format(location.height));
break;
case 'annotation':
params.set(URL_PARAMS.annotationId, location.id);
break;
}
return url.toString();
}
/**
* Selects the most appropriate location for the desired fidelity level.
* Higher precision locations are preferred when available.
*
* @param fidelity - Desired fidelity level
* @param locations - Available locations
* @returns Most appropriate location for the fidelity level, or undefined if none available
*
*/
export function selectLocationForFidelity(
fidelity: PdfLocationType,
locations: Partial<Record<PdfLocationType, PdfLocation>>
): PdfLocation | undefined {
// Get allowed location types for this fidelity level
const allowedTypes = LOCATION_FIDELITY_MAP[fidelity];
// Filter to available locations of allowed types, and sort by precision (reverse order of PdfLocationTypes)
const validLocations = Object.entries(locations)
.filter(
([type, location]) =>
location && allowedTypes.includes(type as PdfLocationType)
)
.sort(
([a], [b]) =>
PdfLocationTypes.indexOf(b as PdfLocationType) -
PdfLocationTypes.indexOf(a as PdfLocationType)
);
return validLocations[0]?.[1];
}
/** Builds a link to the PDF at the most precise location for `fidelity`. */
export function useCreateShareUrl() {
const pdf = usePdfDocument();
const rootViewer = usePdfViewer().root;
const createShareUrl = (fidelity: PdfLocationType): string => {
const shareLocation = pdf.shareLocation();
const locations = {
general: {
type: 'general',
pageIndex: rootViewer.currentPageNumber(),
y: 0,
} satisfies GeneralLocation,
precise: shareLocation?.type === 'precise' ? shareLocation : undefined,
annotation:
shareLocation?.type === 'annotation' ? shareLocation : undefined,
};
const selectedLocation = selectLocationForFidelity(fidelity, locations);
return locationToUrl(pdf.documentId(), selectedLocation);
};
return createCallback(createShareUrl);
}
/**
* Internal helper to parse location parameters into a PDF location.
* Returns most precise location type possible based on available parameters.
*/
function parseLocationParams(params: {
annotationId?: string;
searchPage?: string;
searchSnippet?: string;
searchRawQuery?: string;
searchHighlightTerms?: string;
pageNumber?: string;
yPos?: string;
x?: string;
width?: string;
height?: string;
}): PdfLocation | null {
// Check for annotation first as it's highest priority
const id = params.annotationId;
if (id?.trim()) {
return {
type: 'annotation',
pageIndex: 1,
id,
};
}
// Next highest priority is a search result
const searchPage = params.searchPage;
const searchSnippet = params.searchSnippet;
const searchRawQuery = params.searchRawQuery;
const searchHighlightTermsString = params.searchHighlightTerms;
const searchHighlightTerms = searchHighlightTermsString
? JSON.parse(searchHighlightTermsString)
: [];
if (searchPage && searchRawQuery && searchSnippet && searchHighlightTerms) {
return {
type: 'search',
pageIndex: Number(searchPage) + 1,
snippet: searchSnippet,
rawQuery: searchRawQuery,
highlightTerms: searchHighlightTerms,
};
}
const pageIndex = Number(params.pageNumber);
const y = Number(params.yPos);
if (isNaN(pageIndex) || isNaN(y) || pageIndex < 1) {
return null;
}
const x = Number(params.x);
const width = Number(params.width);
const height = Number(params.height);
if (!isNaN(x) && !isNaN(width) && !isNaN(height) && width > 0 && height > 0) {
return {
type: 'precise',
pageIndex,
y,
x,
width,
height,
};
}
// Fall back to general location
return {
type: 'general',
pageIndex,
y,
};
}
/**
* Parses params into a PDF location.
* Returns most precise location type possible based on available parameters.
*
* @param params - Block parameters containing location information
* @returns PDF location object or null if no valid location found
*/
export function parseLocationFromBlockParams(
params: LocationBlockParams
): PdfLocation | null {
return parseLocationParams({
annotationId: params[URL_PARAMS.annotationId],
searchPage: params[URL_PARAMS.searchPage],
searchSnippet: params[URL_PARAMS.searchSnippet],
searchRawQuery: params[URL_PARAMS.searchRawQuery],
searchHighlightTerms: params[URL_PARAMS.searchHighlightTerms],
pageNumber: params[URL_PARAMS.pageNumber],
yPos: params[URL_PARAMS.yPos],
x: params[URL_PARAMS.x],
width: params[URL_PARAMS.width],
height: params[URL_PARAMS.height],
});
}
/**
* Parses URL search parameters into a PDF location.
* Returns most precise location type possible based on available parameters.
*
* @param params - URL search parameters to parse
* @returns PDF location object or null if no valid location found
*/
export function parseLocationFromUrl(
params: LocationSearchParams
): PdfLocation | null {
return parseLocationParams({
annotationId: params.annotationId,
searchPage: params.searchPage,
searchSnippet: params.searchSnippet,
searchRawQuery: params.searchRawQuery,
searchHighlightTerms: params.highlightTerms,
pageNumber: params.pageNumber,
yPos: params.yPos,
x: params.x,
width: params.width,
height: params.height,
});
}
/**
* Applies custom highlights using phraseSearch: false to highlight all macro_em terms
* in a single search pass, filtered to only matches within the snippet boundaries.
*/
async function applyCustomHighlights(
viewer: PDFViewer,
currentScrollTop: number,
currentScrollLeft: number,
findController: FindController,
findControllerStateEventSignal: Accessor<
IUpdateFindControlStateEvent | undefined
>,
pageIndex: number,
terms: string[],
snippetStartPos: number,
snippetEndPos: number
) {
if (terms.length === 0) {
console.warn('No highlight terms found');
return;
}
// Join all terms with spaces for multi-term search
// phraseSearch: false will create an alternation regex (term1|term2|term3)
const query = terms.join(' ');
// Perform single search with phraseSearch: false to highlight all terms
viewer.search({
query,
again: false,
phraseSearch: false,
caseSensitive: true,
entireWord: false,
highlightAll: true,
findPrevious: false,
});
// Wait for search to complete
const searchResult = await waitForSignal(
findControllerStateEventSignal,
(val) => {
return (
val?.state === FindState.FOUND || val?.state === FindState.NOT_FOUND
);
}
);
// Restore the scroll position to where we were before the search
viewer.container().scrollTop = currentScrollTop;
viewer.container().scrollLeft = currentScrollLeft;
if (searchResult.isErr()) {
console.warn('Highlight search timed out:', terms);
return;
}
if (searchResult.value?.state === FindState.NOT_FOUND) {
console.warn('Terms not found:', terms);
return;
}
const pageMatches = findController.pageMatches;
const pageMatchesLength = findController.pageMatchesLength;
if (!pageMatches || !pageMatchesLength) {
console.warn('pageMatches or pageMatchesLength is undefined');
return;
}
const filteredMatches: number[] = [];
const filteredLengths: number[] = [];
const targetPageMatches = pageMatches[pageIndex] || [];
const targetPageLengths = pageMatchesLength[pageIndex] || [];
for (let i = 0; i < targetPageMatches.length; i++) {
const matchStart = targetPageMatches[i];
const matchEnd = matchStart + targetPageLengths[i];
// Only keep matches that are completely within the snippet bounds
if (matchStart >= snippetStartPos && matchEnd <= snippetEndPos) {
filteredMatches.push(matchStart);
filteredLengths.push(targetPageLengths[i]);
}
}
// Clear matches on all pages
if (findController._pageMatches && findController._pageMatchesLength) {
for (let i = 0; i < pageMatches.length; i++) {
findController._pageMatches[i] = [];
findController._pageMatchesLength[i] = [];
}
// Set only the filtered matches on the target page
findController._pageMatches[pageIndex] = filteredMatches;
findController._pageMatchesLength[pageIndex] = filteredLengths;
}
findController._matchesCountTotal = filteredMatches.length;
// Force re-render with the filtered matches
findController._updateAllPages();
viewer.markPageHighlightsSelected(pageIndex);
}
function useGoToPdfLocation() {
const pdfViewer = usePdfViewer();
const rootRuntime = pdfViewer.root;
const rootViewer = rootRuntime.instance;
const findControllerStateEventSignal = rootRuntime.findControlState;
const go = async (location: PdfLocation): Promise<void> => {
const viewer = rootViewer();
if (!viewer) return;
switch (location.type) {
case 'general':
await viewer.scrollTo({
pageNumber: location.pageIndex,
yPos: location.y,
});
return;
case 'precise':
await viewer.scrollTo({
pageNumber: location.pageIndex,
yPos: location.y,
});
viewer.generateOverlayForSelectionRect(
location.pageIndex - 1,
location
);
return;
case 'annotation':
// TODO: implement specific annotation navigation, e.g. comments
await viewer.scrollTo({
pageNumber: location.pageIndex,
yPos: 0,
});
return;
case 'search':
await viewer.scrollTo({
pageNumber: location.pageIndex,
yPos: 0,
});
// Save the current scroll position to restore after search
const currentScrollTop = viewer.container().scrollTop;
const currentScrollLeft = viewer.container().scrollLeft;
// Pre-warm text extraction for just the target page
const findController = viewer.findController;
const pageIdx = location.pageIndex - 1; // Convert to 0-indexed
await findController.warmSearchTextForPage(pageIdx);
// Use the snippet to find the location in the PDF
viewer.search({
query: location.snippet,
again: false,
phraseSearch: true,
caseSensitive: true,
entireWord: false,
highlightAll: false,
findPrevious: false,
});
// Wait for the find controller to be ready
const findControllerStateEvent = await waitForSignal(
findControllerStateEventSignal,
(val) =>
val?.state === FindState.FOUND || val?.state === FindState.NOT_FOUND
);
if (findControllerStateEvent.isErr()) {
console.warn('search timed out', { location });
return;
}
if (findControllerStateEvent.value?.state === FindState.NOT_FOUND) {
console.warn('unable to find match', { location });
// TODO: fallback to raw query
return;
}
viewer.container().scrollTop = currentScrollTop;
viewer.container().scrollLeft = currentScrollLeft;
if (
!findController._selected ||
!findController._pageMatches ||
!findController._pageMatchesLength
) {
console.error('FindController state is incomplete');
return;
}
const snippetMatchIdx = findController._selected.matchIdx;
const snippetStartPos =
findController._pageMatches[pageIdx]?.[snippetMatchIdx];
const snippetLength =
findController._pageMatchesLength[pageIdx]?.[snippetMatchIdx];
if (snippetStartPos === undefined || snippetLength === undefined) {
console.error('Could not find snippet position');
return;
}
const snippetEndPos = snippetStartPos + snippetLength;
// Clear the snippet search highlights without resetting state
// This preserves the findController's ability to emit events
findController._highlightMatches = false;
findController._updatePage(pageIdx);
await applyCustomHighlights(
viewer,
currentScrollTop,
currentScrollLeft,
findController,
findControllerStateEventSignal,
pageIdx,
location.highlightTerms,
snippetStartPos,
snippetEndPos
);
// Trigger full extraction in the background immediately
findController.forceFullExtraction();
// resets the highlight after a short delay
return new Promise((resolve) => {
setTimeout(() => {
viewer.findBarClose();
resolve();
}, 2000);
});
}
};
return async (location: PdfLocation) => {
if (location.type === 'search') {
pdfViewer.beginSearchNavigation();
try {
await go(location);
} finally {
pdfViewer.endSearchNavigation();
}
return;
}
await go(location);
};
}
const useGoToPreviousLocation = () => {
const pdf = usePdfDocument();
const viewer = usePdfViewer().root.instance;
const isViewerReady = useIsViewerReadyForScroll();
return async () => {
const prevLocationHash = pdf.persistedViewLocation();
if (!prevLocationHash) return;
const ready = await waitForSignal(isViewerReady);
if (ready.isErr()) return;
viewer()?.goToLocationHash(prevLocationHash);
};
};
/**
* Go to the location in the pdf viewer based on the current url
*/
export function useGoToLinkLocation() {
const goToPreviousLocation = useGoToPreviousLocation();
const goToPdfLocation = useGoToPdfLocation();
return async (params: LocationSearchParams) => {
const location = parseLocationFromUrl(params);
if (location) {
await goToPdfLocation(location);
return;
}
await goToPreviousLocation();
};
}
/**
* Go to the location in the pdf viewer based on the params
*/
export function useGoToLinkLocationFromParams() {
const goToPreviousLocation = useGoToPreviousLocation();
const goToPdfLocation = useGoToPdfLocation();
return async (params: LocationBlockParams) => {
const location = parseLocationFromBlockParams(params);
if (location) {
await goToPdfLocation(location);
return;
}
await goToPreviousLocation();
};
}