@eightyfourthousand/lib-editing 2026.3.1 → 2026.4.0

package/src/lib/components/shared/NavigationContext.ts

@@ -9,7 +9,7 @@ import type {
   Work,
 } from '@eightyfourthousand/data-access';
 import { createContext, useContext } from 'react';
-import { PanelName, PanelsState, PanelState, TabName } from './types';
+import { PanelName, PanelsState, PanelState } from './types';
 
 export interface NavigationState {
   uuid: string;

package/src/lib/components/shared/NavigationProvider.tsx

@@ -27,14 +27,16 @@ import {
 import { ReadonlyURLSearchParams, useSearchParams } from 'next/navigation';
 import {
   PANEL_NAMES,
+  PANEL_FOR_SECTION,
   PanelName,
   PanelsState,
   PanelState,
+  TAB_FOR_SECTION,
   TabName,
 } from './types';
 import { HoverCardProvider } from './HoverCardProvider';
 import { GatedFeature, useFeatureFlagEnabled } from '@eightyfourthousand/lib-instr';
-import { useIsMobile } from '@eightyfourthousand/lib-utils';
+import { isXmlId, useIsMobile } from '@eightyfourthousand/lib-utils';
 import { RestrictionWarning } from './RestrictionWarning';
 import { NavigationContext, DEFAULT_PANELS } from './NavigationContext';
 
@@ -267,6 +269,36 @@ export const NavigationProvider = ({
     window.history.replaceState(null, '', newUrl);
   }, [toh, panels]);
 
+  // On initial load, check for an XML ID in the URL hash and resolve it to a passage UUID
+  useEffect(() => {
+    const hash = window.location.hash.replace(/^#/, '');
+    if (!hash || !isXmlId(hash)) {
+      return;
+    }
+
+    // Remove hash from URL immediately
+    window.history.replaceState(
+      null,
+      '',
+      `${window.location.pathname}${window.location.search}`,
+    );
+
+    (async () => {
+      const passage = await getPassage({ client: graphqlClient, xmlId: hash });
+      if (!passage) {
+        return;
+      }
+
+      const panel = PANEL_FOR_SECTION[passage.type] ?? 'main';
+      const tab = TAB_FOR_SECTION[passage.type] ?? 'translation';
+
+      updatePanel({
+        name: panel,
+        state: { open: true, tab, hash: passage.uuid },
+      });
+    })();
+  }, []);
+
   useEffect(() => {
     if (!uuid || !toh) {
       return;

package/src/lib/components/shared/ReaderSearchButton.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { BodyItemType } from '@eightyfourthousand/data-access';
+import {
+  PassageMatch,
+  SearchButton,
+  SearchResult,
+} from '@eightyfourthousand/lib-search';
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { useEditorState } from '../editor/EditorProvider';
+import { useNavigation } from './NavigationProvider';
+import { SearchReplacePanel } from './SearchReplacePanel';
+import { PanelName, PanelState, TabName } from './types';
+
+export const ReaderSearchButton = () => {
+  const { uuid, toh, updatePanel } = useNavigation();
+  const { applyReplacedPassages, canEdit, dirtyStore } = useEditorState();
+  const [canReplace, setCanReplace] = useState(false);
+  const isDirty = useSyncExternalStore(
+    dirtyStore.subscribe.bind(dirtyStore),
+    dirtyStore.getSnapshot.bind(dirtyStore),
+    () => false,
+  );
+
+  useEffect(() => {
+    let active = true;
+
+    (async () => {
+      const editable = await canEdit();
+      if (active) {
+        setCanReplace(editable);
+      }
+    })();
+
+    return () => {
+      active = false;
+    };
+  }, [canEdit]);
+
+  const onResultSelected = useCallback(
+    (result: SearchResult) => {
+      let side: PanelName = 'main';
+      const panelState: PanelState = {
+        open: true,
+        hash: result.uuid,
+      };
+
+      const TAB_FOR_PASSAGE_SECTION: Partial<Record<BodyItemType, TabName>> = {
+        abbreviations: 'abbreviations',
+        endnotes: 'endnotes',
+        summary: 'front',
+        introduction: 'front',
+        acknowledgements: 'front',
+      };
+
+      const SIDE_FOR_PASSAGE_SECTION: Partial<Record<BodyItemType, PanelName>> =
+      {
+        abbreviations: 'right',
+        endnotes: 'right',
+      };
+
+      switch (result.type) {
+        case 'passage':
+          {
+            const passage = result as PassageMatch;
+            side = SIDE_FOR_PASSAGE_SECTION[passage.section] || 'main';
+            panelState.tab =
+              TAB_FOR_PASSAGE_SECTION[passage.section] || 'translation';
+          }
+          break;
+        case 'alignment':
+          side = 'main';
+          panelState.tab = 'compare';
+          break;
+        case 'bibliography':
+          side = 'right';
+          panelState.tab = 'bibliography';
+          break;
+        case 'glossary':
+          side = 'right';
+          panelState.tab = 'glossary';
+          break;
+      }
+
+      updatePanel({
+        name: side,
+        state: panelState,
+      });
+    },
+    [updatePanel],
+  );
+
+  return (
+    <SearchButton
+      workUuid={uuid}
+      toh={toh}
+      onResultSelected={onResultSelected}
+      renderActions={(searchContext) => (
+        <SearchReplacePanel
+          canReplace={canReplace}
+          replaceDisabledReason={
+            isDirty ? 'Save changes before using search and replace.' : undefined
+          }
+          onPassagesReplaced={applyReplacedPassages}
+          searchContext={searchContext}
+        />
+      )}
+    />
+  );
+};

package/src/lib/components/shared/SearchReplacePanel.tsx

@@ -0,0 +1,259 @@
+'use client';
+
+import {
+  createGraphQLClient,
+  replace,
+  type ReplacedPassage,
+} from '@eightyfourthousand/client-graphql';
+import {
+  Button,
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+  Input,
+} from '@eightyfourthousand/design-system';
+import type { SearchActionContext } from '@eightyfourthousand/lib-search';
+import { ChevronDownIcon, ChevronRightIcon } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+
+const REPLACE_CHUNK_SIZE = 200;
+
+export interface SearchReplacePanelProps {
+  canReplace: boolean;
+  onPassagesReplaced?: (passages: ReplacedPassage[]) => Promise<void> | void;
+  replaceDisabledReason?: string;
+  searchContext: SearchActionContext;
+}
+
+export const SearchReplacePanel = ({
+  canReplace,
+  onPassagesReplaced,
+  replaceDisabledReason,
+  searchContext,
+}: SearchReplacePanelProps) => {
+  const client = useMemo(() => createGraphQLClient(), []);
+  const [replaceOpen, setReplaceOpen] = useState(false);
+  const [replaceQuery, setReplaceQuery] = useState('');
+  const [replacing, setReplacing] = useState(false);
+
+  const canRunReplace =
+    canReplace &&
+    !replaceDisabledReason &&
+    !!searchContext.searchQuery &&
+    !!replaceQuery &&
+    searchContext.passageOccurrences.length > 0 &&
+    !replacing;
+  const canStepBackward =
+    replaceOpen && searchContext.activeOccurrenceIndex > 0;
+  const canStepForward =
+    replaceOpen &&
+    searchContext.activeOccurrenceIndex <
+      searchContext.passageOccurrences.length - 1;
+
+  useEffect(() => {
+    searchContext.setShouldScrollActiveOccurrence(replaceOpen);
+
+    return () => {
+      searchContext.setShouldScrollActiveOccurrence(false);
+    };
+  }, [replaceOpen, searchContext]);
+
+  useEffect(() => {
+    if (!replaceOpen || searchContext.passageOccurrences.length === 0) {
+      return;
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        searchContext.moveActiveOccurrence('previous');
+      }
+
+      if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        searchContext.moveActiveOccurrence('next');
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [replaceOpen, searchContext]);
+
+  if (!canReplace || !searchContext.searchQuery) {
+    return null;
+  }
+
+  const runReplace = async ({ replaceAll }: { replaceAll: boolean }) => {
+    if (!canRunReplace) {
+      return;
+    }
+
+    setReplacing(true);
+
+    try {
+      if (replaceAll) {
+        const targetUuids = searchContext.passages.map((passage) => passage.uuid);
+        if (targetUuids.length === 0) {
+          return;
+        }
+
+        const allReplacedPassages: ReplacedPassage[] = [];
+        for (let i = 0; i < targetUuids.length; i += REPLACE_CHUNK_SIZE) {
+          const chunk = targetUuids.slice(i, i + REPLACE_CHUNK_SIZE);
+          const response = await replace({
+            client,
+            searchText: searchContext.searchQuery,
+            replaceText: replaceQuery,
+            targetUuids: chunk,
+          });
+
+          if (!response.success) {
+            console.error(`Replace failed: ${response.error ?? 'unknown error'}`);
+            return;
+          }
+
+          allReplacedPassages.push(...response.passages);
+        }
+
+        await onPassagesReplaced?.(allReplacedPassages);
+        await searchContext.refreshSearch({ nextSelection: { kind: 'index', index: 0 } });
+        return;
+      }
+
+      // Single replace: target only the active passage and use its exact position as the cursor.
+      const activeOccurrence = searchContext.activeOccurrence;
+      if (!activeOccurrence) {
+        return;
+      }
+
+      const response = await replace({
+        client,
+        searchText: searchContext.searchQuery,
+        replaceText: replaceQuery,
+        targetUuids: [activeOccurrence.passageUuid],
+        cursorPassageUuid: activeOccurrence.passageUuid,
+        cursorStart: activeOccurrence.start,
+      });
+
+      if (!response.success) {
+        console.error(`Replace failed: ${response.error ?? 'unknown error'}`);
+        return;
+      }
+
+      await onPassagesReplaced?.(response.passages);
+
+      const nextSelection =
+        response.nextPassageUuid != null && response.nextOccurrenceStart != null
+          ? {
+              kind: 'cursor' as const,
+              passageUuid: response.nextPassageUuid,
+              start: response.nextOccurrenceStart,
+            }
+          : {
+              kind: 'index' as const,
+              index: Math.min(
+                searchContext.activeOccurrenceIndex + 1,
+                Math.max(searchContext.passageOccurrences.length - 1, 0),
+              ),
+            };
+
+      await searchContext.refreshSearch({ nextSelection });
+    } catch (error) {
+      console.error('Replace failed:', error);
+    } finally {
+      setReplacing(false);
+    }
+  };
+
+  return (
+    <Collapsible
+      open={replaceOpen}
+      onOpenChange={setReplaceOpen}
+      className="bg-background border rounded-lg px-4 py-3 text-foreground"
+    >
+      <CollapsibleTrigger asChild>
+        <button
+          type="button"
+          className="group/collapsible flex w-full items-center justify-start gap-2 text-left text-sm font-medium cursor-pointer"
+        >
+          <ChevronRightIcon className="size-4 transition-transform group-data-[state=open]/collapsible:rotate-90" />
+          <span>Replace</span>
+        </button>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="pt-3">
+        <div className="flex flex-col">
+          <Input
+            id="replace-query"
+            placeholder="Replace with..."
+            value={replaceQuery}
+            onChange={(e) => {
+              const nextValue = e.target.value;
+              if (nextValue === replaceQuery) {
+                return;
+              }
+              setReplaceQuery(nextValue);
+              if (nextValue) {
+                searchContext.scrollActiveOccurrenceIntoView();
+              }
+            }}
+          />
+          <div className="flex flex-wrap items-center gap-2 text-sm text-secondary-foreground">
+            <span>
+              {searchContext.passageOccurrences.length > 0 &&
+              searchContext.activePassageUuid
+                ? `Occurrence ${searchContext.activeOccurrenceIndex + 1} of ${searchContext.passageOccurrences.length} in ${searchContext.activePassageLabel || searchContext.activePassageUuid}`
+                : 'No exact passage occurrences available for replacement.'}
+            </span>
+            {replaceDisabledReason && <span>{replaceDisabledReason}</span>}
+          </div>
+          <div className="text-sm text-muted-foreground pb-4">
+            Replace is case sensitive and is only applied to passages.
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
+            <Button
+              size="sm"
+              disabled={!canRunReplace}
+              onClick={() => void runReplace({ replaceAll: false })}
+            >
+              {replacing ? 'Replacing…' : 'Replace'}
+            </Button>
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={!canRunReplace}
+              onClick={() => void runReplace({ replaceAll: true })}
+            >
+              Replace all
+            </Button>
+            <div className="ml-auto flex items-center gap-2">
+              <Button
+                size="icon"
+                variant="ghost"
+                className="size-8"
+                disabled={!canStepBackward}
+                onClick={() => {
+                  searchContext.moveActiveOccurrence('previous');
+                }}
+              >
+                <ChevronRightIcon className="size-4 rotate-[-90deg]" />
+                <span className="sr-only">Previous occurrence</span>
+              </Button>
+              <Button
+                size="icon"
+                variant="ghost"
+                className="size-8"
+                disabled={!canStepForward}
+                onClick={() => {
+                  searchContext.moveActiveOccurrence('next');
+                }}
+              >
+                <ChevronDownIcon className="size-4" />
+                <span className="sr-only">Next occurrence</span>
+              </Button>
+            </div>
+          </div>
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+};

package/src/lib/components/shared/SourceReader.tsx

@@ -3,7 +3,10 @@
 import { useInView } from 'motion/react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useNavigation } from './NavigationProvider';
-import { createGraphQLClient, getWorkFolios } from '@eightyfourthousand/client-graphql';
+import {
+  createGraphQLClient,
+  getWorkFolios,
+} from '@eightyfourthousand/client-graphql';
 import type { Folio } from '@eightyfourthousand/data-access';
 import { LabeledElement } from './LabeledElement';
 import { PassageSkeleton } from './PassageSkeleton';
@@ -61,9 +64,15 @@ export const SourceReader = () => {
           className="mt-0.5"
           contentType="source"
         >
-          <div className="leading-7 font-tibetan text-lg 2xl:whitespace-pre-wrap whitespace-normal">
-            {folio.content}
-          </div>
+          {folio.content ? (
+            <div className="leading-7 min-h-8 font-tibetan text-lg 2xl:whitespace-pre-wrap whitespace-normal">
+              {folio.content}
+            </div>
+          ) : (
+            <div className="h-12 text-center text-muted-foreground">
+              [blank]
+            </div>
+          )}
         </LabeledElement>
       ))}
       <div ref={loadMoreRef} className="h-0" />

package/src/lib/components/shared/SuggestRevisionForm.tsx

@@ -58,7 +58,7 @@ export const SuggestRevisionForm = ({
   return (
     <div className="p-1">
       <p className="text-sm font-semibold">Suggest a Revision</p>
-      <p className="text-secondary text-xs capitalize py-2">
+      <p className="text-primary text-xs capitalize py-2">
         {parseToh(toh)} &middot; {type} {label}
       </p>
       <form onSubmit={handleSubmit}>

package/src/lib/components/shared/TableOfContents.tsx

@@ -14,7 +14,7 @@ import {
   Separator,
 } from '@eightyfourthousand/design-system';
 import { cn, parseToh } from '@eightyfourthousand/lib-utils';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 import { useNavigation } from './NavigationProvider';
 import {
   PanelName,
@@ -59,38 +59,51 @@ export const TableOfContentsSection = ({
   }
 
   return (
-    <Accordion type="multiple" className={cn(depth && 'pl-2.5')}>
-      {node.children.map((child) => {
+    <Accordion type="multiple" className={cn(depth && 'pl-5')}>
+      {node.children.map((child, index) => {
         // 'The Translation' is always bold
         const maybeBold =
           child.content === 'The Translation' ? 'font-bold' : '';
+        // Show dividers above and below the top-level introduction section
+        const isIntroduction =
+          depth === 0 && child.section === 'introduction';
+        const prevChild = node.children[index - 1];
+        const prevWasIntroduction =
+          depth === 0 && prevChild?.section === 'introduction';
+        const showDividerBefore =
+          isIntroduction && !prevWasIntroduction;
         return child.children?.length ? (
-          <AccordionItem
-            key={child.uuid}
-            value={child.uuid}
-            className="border-b-0"
-          >
-            <AccordionTrigger className={cn(baseStyle, className)}>
+          <React.Fragment key={child.uuid}>
+            {showDividerBefore && <Separator className="my-4" />}
+            <AccordionItem
+              value={child.uuid}
+              className="border-b-0"
+            >
+              <AccordionTrigger className={cn(baseStyle, className)}>
+                <span
+                  className={cn('line-clamp-2', maybeBold)}
+                  onClick={() => onClick(child)}
+                >
+                  {child.content}
+                </span>
+              </AccordionTrigger>
+              <AccordionContent className="border-l border-dotted py-0">
+                <TableOfContentsSection node={child} depth={depth + 1} />
+              </AccordionContent>
+            </AccordionItem>
+          </React.Fragment>
+        ) : (
+          <React.Fragment key={child.uuid}>
+            {showDividerBefore && <Separator className="my-4" />}
+            <div className={baseStyle}>
               <span
                 className={cn('line-clamp-2', maybeBold)}
                 onClick={() => onClick(child)}
               >
                 {child.content}
               </span>
-            </AccordionTrigger>
-            <AccordionContent className="border-l border-dotted py-0">
-              <TableOfContentsSection node={child} depth={depth + 1} />
-            </AccordionContent>
-          </AccordionItem>
-        ) : (
-          <div key={child.uuid} className={baseStyle}>
-            <span
-              className={cn('line-clamp-2', maybeBold)}
-              onClick={() => onClick(child)}
-            >
-              {child.content}
-            </span>
-          </div>
+            </div>
+          </React.Fragment>
         );
       })}
     </Accordion>
@@ -216,7 +229,7 @@ export const TableOfContents = ({
   return (
     <div>
       <div className={cn(baseStyle, 'flex gap-2 mt-6')}>
-        <div className="size-5 text-primary-200 [&_svg]:stroke-1 [&_svg]:size-5 my-auto">
+        <div className="size-5 text-primary [&_svg]:stroke-1 [&_svg]:size-5 my-auto">
           <LibraryBigIcon />
         </div>
         <span className="my-auto font-light">
@@ -224,13 +237,13 @@ export const TableOfContents = ({
         </span>
       </div>
       <div className={cn(baseStyle, 'flex gap-2')}>
-        <div className="size-5 text-primary-200 [&_svg]:stroke-1 [&_svg]:size-5 my-auto">
+        <div className="size-5 text-primary [&_svg]:stroke-1 [&_svg]:size-5 my-auto">
           <BookOpenIcon />
         </div>
-        <span className="my-auto font-semibold">{title}</span>
+        <span className="my-auto font-bold">{title}</span>
       </div>
       <div className="flex gap-2">
-        <div className="size-5 text-primary-200 [&_svg]:stroke-1 [&_svg]:size-5 my-auto">
+        <div className="size-5 text-primary [&_svg]:stroke-1 [&_svg]:size-5 my-auto">
           <HashIcon />
         </div>
         {work.toh.length > 1 ? (

package/src/lib/components/shared/ThreeColumnRenderer.tsx

@@ -1,10 +1,12 @@
 'use client';
 
 import { ThreeColumns } from '@eightyfourthousand/design-system';
-import { ReactNode } from 'react';
+import { ReactNode, useMemo } from 'react';
 import { useNavigation } from './NavigationProvider';
 import { cn } from '@eightyfourthousand/lib-utils';
 import { TranslationHeader } from './TranslationHeader';
+import { ReaderSearchButton } from './ReaderSearchButton';
+import { GatedFeature } from '@eightyfourthousand/lib-instr';
 
 export const ThreeColumnRenderer = ({
   withHeader = false,
@@ -16,6 +18,8 @@ export const ThreeColumnRenderer = ({
   const { panels, updatePanel, hasTranslationContent } = useNavigation();
   const rightPanelEnabled = hasTranslationContent;
 
+  const searchButton = useMemo(() => <ReaderSearchButton />, []);
+
   return (
     <div
       className={cn(
@@ -23,13 +27,16 @@ export const ThreeColumnRenderer = ({
         withHeader ? 'pb-20' : '',
       )}
     >
-      <div className="pb-2.5">
-        <TranslationHeader className="rounded-full shadow-lg" />
-      </div>
+      <GatedFeature flag='show-reader-header'>
+        <div className="pb-2.5">
+          <TranslationHeader className="rounded-full shadow-lg" />
+        </div>
+      </GatedFeature>
       <ThreeColumns
         leftPanelOpen={panels.left.open}
         rightPanelOpen={rightPanelEnabled ? panels.right.open : false}
         rightPanelEnabled={rightPanelEnabled}
+        mainPanelActions={searchButton}
         onLeftPanelOpenChange={(open) => {
           updatePanel({
             name: 'left',
@@ -39,11 +46,11 @@ export const ThreeColumnRenderer = ({
         onRightPanelOpenChange={
           rightPanelEnabled
             ? (open) => {
-                updatePanel({
-                  name: 'right',
-                  state: { open, tab: panels.right.tab },
-                });
-              }
+              updatePanel({
+                name: 'right',
+                state: { open, tab: panels.right.tab },
+              });
+            }
             : undefined
         }
       >