@semiont/react-ui 0.5.27 → 0.5.28

package/src/components/modals/ReferenceWizardModal.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import { Dialog, DialogPanel, DialogTitle, Transition, TransitionChild } from '@headlessui/react';
 import type { GatheredContext, CollaboratorEntry } from '@semiont/core';
 import { uuidV4 } from '@semiont/core';
@@ -14,13 +14,18 @@ import { ConfigureSearchStep } from './ConfigureSearchStep';
 import type { SearchConfig } from './ConfigureSearchStep';
 import type { GenerationDraft } from './ConfigureGenerationStep';
 import { SearchResultsStep } from './SearchResultsStep';
+import { ComposeStep } from './ComposeStep';
+import type { ComposeDraft, ComposeParams } from './ComposeStep';
+import { DiscardPrompt } from './DiscardPrompt';
+import { useLineNumbers } from '../../contexts/LineNumbersContext';
 import type { ScoredResult } from './SearchResultsStep';
 
 type WizardStep =
   | { step: 'gather' }
   | { step: 'configure-search' }
   | { step: 'search-results'; results: ScoredResult[] }
-  | { step: 'configure-generation' };
+  | { step: 'configure-generation' }
+  | { step: 'compose' };
 
 export interface ReferenceWizardModalProps {
   /**
@@ -39,6 +44,12 @@ export interface ReferenceWizardModalProps {
   defaultTitle: string;
   /** Entity types from the annotation */
   entityTypes: string[];
+  /**
+   * The source resource's display name — a page fact (the wizard opens FROM
+   * that resource), shown in the gather skeleton's source line before the
+   * gathered context can say it itself.
+   */
+  resourceName?: string;
   /** Current locale for generation defaults */
   locale: string;
   /** Gathered context state */
@@ -48,21 +59,36 @@ export interface ReferenceWizardModalProps {
   /** Callbacks */
   onGenerateSubmit: (referenceId: string, config: GenerationConfig) => void;
   onLinkResource: (referenceId: string, targetResourceId: string) => void;
-  onComposeNavigate: (context: GatheredContext, annotationId: string, resourceId: string, title: string, entityTypes: string[]) => void;
+  /**
+   * Create-and-link (COMPOSE-IN-MODAL): the host runs `yield.resource` then
+   * `bind.body` and settles the promise; rejection keeps the modal open with
+   * the compose footer re-enabled. Replaces the old navigate-to-page flow.
+   */
+  onComposeSubmit: (referenceId: string, params: ComposeParams) => Promise<void>;
+  /** Picker vocabulary for compose when the reference fixed no entity types. */
+  entityTypeOptions?: string[];
+  /** Editor hover delay for the compose step's CodeMirror. */
+  hoverDelayMs?: number;
   /** Translation strings */
   translations: {
-    gatherTitle: string;
-    configureGenerationTitle: string;
-    configureSearchTitle: string;
-    searchResultsTitle: string;
+    /** The ONE title, all steps — the flow is resolving a reference; the
+        strategy band below says where in it you are. */
+    resolveTitle: string;
     sourceContextLabel: string;
     connectionsLabel: string;
     citedByLabel: string;
+    graphPaneTitle: string;
+    graphEmpty: string;
+    resourceLinkLabel: string;
+    corpusPaneTitle: string;
+    corpusEmpty: string;
+    excludedReceipt: string;
+    machineRead: string;
     userHintLabel: string;
+    userHintEffect: string;
     userHintPlaceholder: string;
     loadingContext: string;
     failedContext: string;
-    cancel: string;
     search: string;
     searching: string;
     generate: string;
@@ -74,6 +100,7 @@ export interface ReferenceWizardModalProps {
     noResults: string;
     resourceTitle: string;
     resourceTitlePlaceholder: string;
+    saveLocation: string;
     additionalInstructions: string;
     additionalInstructionsPlaceholder: string;
     language: string;
@@ -87,6 +114,14 @@ export interface ReferenceWizardModalProps {
     maxResults: string;
     semanticScoring: string;
     semanticScoringHelp: string;
+    searchFailed: string;
+    entityTypes: string;
+    contentLabel: string;
+    createAndLink: string;
+    creatingAndLinking: string;
+    discardDraftPrompt: string;
+    discardDraft: string;
+    keepEditing: string;
   };
 }
 
@@ -97,13 +132,16 @@ export function ReferenceWizardModal({
   resourceId,
   defaultTitle,
   entityTypes,
+  resourceName,
   locale,
   context,
   contextLoading,
   contextError,
   onGenerateSubmit,
   onLinkResource,
-  onComposeNavigate,
+  onComposeSubmit,
+  entityTypeOptions = [],
+  hoverDelayMs = 300,
   translations: t,
   generationAgent,
 }: ReferenceWizardModalProps) {
@@ -118,11 +156,27 @@ export function ReferenceWizardModal({
     temperature: 0.7, maxTokensText: '500',
   });
   const [isSearching, setIsSearching] = useState(false);
+  const [searchError, setSearchError] = useState<string | null>(null);
   const [userHint, setUserHint] = useState('');
+  const freshComposeDraft = (): ComposeDraft => ({
+    name: defaultTitle, storagePath: '', content: '', entityTypes: [], language: locale,
+  });
+  const [composeDraft, setComposeDraft] = useState<ComposeDraft>(freshComposeDraft);
+  const [showDiscardPrompt, setShowDiscardPrompt] = useState(false);
+  // The editor consumes the shared display setting; the step itself stays
+  // provider-free, so the wizard resolves it and passes it down.
+  const { showLineNumbers } = useLineNumbers();
+
+  // The dirty baseline is what was SEEDED, not the live prop: defaultTitle
+  // derives from observable wizard state and can re-emit while the modal is
+  // open; an untouched draft must not read as dirty because the baseline
+  // moved under it.
+  const seededTitle = useRef(defaultTitle);
 
   // Reset to gather step when modal opens
   useEffect(() => {
     if (isOpen) {
+      seededTitle.current = defaultTitle;
       setWizardStep({ step: 'gather' });
       setSearchConfig({ limit: 10, useSemanticScoring: true });
       setGenerationDraft({
@@ -130,7 +184,10 @@ export function ReferenceWizardModal({
         temperature: 0.7, maxTokensText: '500',
       });
       setIsSearching(false);
+      setSearchError(null);
       setUserHint('');
+      setComposeDraft(freshComposeDraft());
+      setShowDiscardPrompt(false);
     }
   }, [isOpen]);
 
@@ -143,6 +200,17 @@ export function ReferenceWizardModal({
     }
   });
 
+  // …and to failures, same scoping. A refused emit (/bus/emit 4xx), a matcher
+  // error, and the match unit's timeout all land here — without this
+  // subscription every one of them left the button on "Searching…" forever.
+  useEventSubscription('match:search-failed', (event) => {
+    if (!isOpen) return;
+    if (annotationId && event.referenceId === annotationId) {
+      setIsSearching(false);
+      setSearchError(event.error);
+    }
+  });
+
   const handleBind = useCallback(() => {
     setWizardStep({ step: 'configure-search' });
   }, []);
@@ -158,9 +226,9 @@ export function ReferenceWizardModal({
    * `focus.userHint` ("hint to supplement or replace the selected text for search and
    * generation"). So the hint was misplaced on every path, not just missing on one.
    *
-   * NOTE: no production code reads `focus.userHint` yet — this is correct plumbing
-   * for a field nothing consumes. Making the hint actually steer search or generation
-   * is a separate change (see WIZARD-NAVIGATION's execution log).
+   * Both consumers read it: the matcher folds it into its search term and its
+   * LLM-scoring passage (matcher.ts, since #911), and generation's prompt builder
+   * renders it in the annotation section (resource-generation.ts).
    */
   const contextWithHint = !context
     ? null
@@ -173,18 +241,57 @@ export function ReferenceWizardModal({
   }, []);
 
   const handleCompose = useCallback(() => {
-    if (!contextWithHint || !annotationId || !resourceId) return;
-    onComposeNavigate(contextWithHint, annotationId, resourceId, defaultTitle, entityTypes);
+    if (!context || !annotationId || !resourceId) return;
+    setWizardStep({ step: 'compose' });
+  }, [context, annotationId, resourceId]);
+
+  const handleComposeSubmit = useCallback(async (params: ComposeParams) => {
+    if (!annotationId) return;
+    // Rejection propagates to ComposeStep (footer re-enables); the host
+    // surfaces the error. Success closes UNCONDITIONALLY — the dirty guard
+    // protects dismissal, not completion.
+    await onComposeSubmit(annotationId, params);
     onClose();
-  }, [contextWithHint, annotationId, resourceId, defaultTitle, entityTypes, onComposeNavigate, onClose]);
+  }, [annotationId, onComposeSubmit, onClose]);
+
+  // D4 (widened by GATHER-AT-THE-TOP): a modal dies on ✕/Escape/backdrop, but
+  // typed work must not die with it — WHEREVER the user currently is (drafts
+  // survive stepping away, so the guard must too). Typed text only (D5):
+  // seeded titles, toggles, and sliders never nag.
+  const draftDirty =
+    composeDraft.content.trim() !== '' ||
+    composeDraft.storagePath.trim() !== '' ||
+    composeDraft.name !== seededTitle.current ||
+    generationDraft.title !== seededTitle.current ||
+    generationDraft.storagePath.trim() !== '' ||
+    generationDraft.prompt.trim() !== '';
+  const handleDismiss = useCallback(() => {
+    if (draftDirty) {
+      setShowDiscardPrompt(true);
+      return;
+    }
+    onClose();
+  }, [draftDirty, onClose]);
 
   const handleBackToGather = useCallback(() => {
     setWizardStep({ step: 'gather' });
   }, []);
 
+  // The strategy steps stack evidence + step content in ONE scroll pane. On
+  // entry, start at the BOTTOM: the step's own content (form, results) shows
+  // in full, the evidence tucks up under the modal top, reachable by
+  // scrolling up. jsdom has no layout (scrollHeight 0), so this is a no-op
+  // in tests — the same posture as the viewer's guarded scrolls.
+  const stepScrollRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const el = stepScrollRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [wizardStep.step]);
+
   const handleSearchSubmit = useCallback((config: SearchConfig) => {
     if (!annotationId || !contextWithHint || !resourceId) return;
     setIsSearching(true);
+    setSearchError(null);
     session?.client.match.requestSearch({
       correlationId: uuidV4(),
       resourceId,
@@ -208,18 +315,29 @@ export function ReferenceWizardModal({
     onClose();
   }, [annotationId, onLinkResource, onClose]);
 
-  // Determine title based on step
-  const stepTitle = wizardStep.step === 'gather'
-    ? t.gatherTitle
-    : wizardStep.step === 'configure-generation'
-      ? t.configureGenerationTitle
-      : wizardStep.step === 'configure-search'
-        ? t.configureSearchTitle
-        : t.searchResultsTitle;
+  // The evidence display's translations — shared by the gather step and the
+  // strategy steps, which keep the context in view (display-only, GFR A2)
+  // above their forms rather than navigating away from it.
+  const displayTranslations = {
+    loadingContext: t.loadingContext,
+    failedContext: t.failedContext,
+    sourceContextLabel: t.sourceContextLabel,
+    connectionsLabel: t.connectionsLabel,
+    citedByLabel: t.citedByLabel,
+    graphPaneTitle: t.graphPaneTitle,
+    graphEmpty: t.graphEmpty,
+    resourceLinkLabel: t.resourceLinkLabel,
+    corpusPaneTitle: t.corpusPaneTitle,
+    corpusEmpty: t.corpusEmpty,
+    excludedReceipt: t.excludedReceipt,
+    machineRead: t.machineRead,
+    score: t.score,
+  };
+
 
   return (
     <Transition appear show={isOpen}>
-      <Dialog as="div" className="semiont-search-modal" onClose={onClose}>
+      <Dialog as="div" className="semiont-search-modal" onClose={handleDismiss}>
         {/* Backdrop */}
         <TransitionChild
           enter="ease-out duration-200"
@@ -243,13 +361,15 @@ export function ReferenceWizardModal({
               leaveFrom="opacity-100 scale-100"
               leaveTo="opacity-0 scale-95"
             >
-              <DialogPanel className={`semiont-search-modal__panel semiont-search-modal__panel--with-border${wizardStep.step === 'search-results' ? ' semiont-search-modal__panel--wide' : ''}${wizardStep.step === 'gather' ? ' semiont-search-modal__panel--gather' : ''}`}>
+              {/* Every step shows the evidence display now, so every step is
+                  wide and gets the gather layout (flex column, capped height). */}
+              <DialogPanel className="semiont-search-modal__panel semiont-search-modal__panel--with-border semiont-search-modal__panel--gather semiont-search-modal__panel--wide">
                 <div className="semiont-search-modal__header">
                   <DialogTitle className="semiont-search-modal__title">
-                    {stepTitle}
+                    {t.resolveTitle}
                   </DialogTitle>
                   <button
-                    onClick={onClose}
+                    onClick={handleDismiss}
                     className="semiont-search-modal__close-button"
                     aria-label="Close"
                   >
@@ -257,36 +377,87 @@ export function ReferenceWizardModal({
                   </button>
                 </div>
 
+                {showDiscardPrompt && (
+                  <DiscardPrompt
+                    prompt={t.discardDraftPrompt}
+                    discardLabel={t.discardDraft}
+                    keepLabel={t.keepEditing}
+                    onDiscard={() => { setShowDiscardPrompt(false); onClose(); }}
+                    onKeepEditing={() => setShowDiscardPrompt(false)}
+                  />
+                )}
+
                 {wizardStep.step === 'gather' && (
                   <GatherContextStep
                     context={context}
                     contextLoading={contextLoading}
                     contextError={contextError}
-                    userHint={userHint}
-                    onUserHintChange={setUserHint}
-                    onBind={handleBind}
-                    onGenerate={handleGenerate}
-                    onCompose={handleCompose}
+                    pending={{ exact: defaultTitle, entityTypes, ...(resourceName ? { resourceName } : {}) }}
+                    annotate={{
+                      userHint,
+                      onUserHintChange: setUserHint,
+                      onBind: handleBind,
+                      onGenerate: handleGenerate,
+                      onCompose: handleCompose,
+                      translations: {
+                        search: t.search,
+                        generate: t.generate,
+                        compose: t.compose,
+                        resolutionStrategyLabel: t.resolutionStrategyLabel,
+                        userHintLabel: t.userHintLabel,
+                        userHintEffect: t.userHintEffect,
+                        userHintPlaceholder: t.userHintPlaceholder,
+                      },
+                    }}
+                    translations={displayTranslations}
+                  />
+                )}
+
+                {wizardStep.step === 'compose' && context && (
+                  <div className="semiont-wizard__step-scroll" ref={stepScrollRef}>
+                  <GatherContextStep
+                    context={context}
+                    contextLoading={contextLoading}
+                    contextError={contextError}
+                    chosenStrategy={{ label: t.resolutionStrategyLabel, value: `✍️ ${t.compose}` }}
+                    translations={displayTranslations}
+                  />
+                  <ComposeStep
+                    draft={composeDraft}
+                    onDraftChange={(patch) => setComposeDraft((d) => ({ ...d, ...patch }))}
+                    referenceEntityTypes={entityTypes}
+                    entityTypeOptions={entityTypeOptions}
+                    showLineNumbers={showLineNumbers}
+                    hoverDelayMs={hoverDelayMs}
+                    onBack={handleBackToGather}
+                    onCompose={handleComposeSubmit}
                     translations={{
-                      title: t.gatherTitle,
-                      sourceContextLabel: t.sourceContextLabel,
-                      connectionsLabel: t.connectionsLabel,
-                      citedByLabel: t.citedByLabel,
-                      userHintLabel: t.userHintLabel,
-                      userHintPlaceholder: t.userHintPlaceholder,
-                      loadingContext: t.loadingContext,
-                      failedContext: t.failedContext,
-                      search: t.search,
-                      generate: t.generate,
-                      compose: t.compose,
-                      resolutionStrategyLabel: t.resolutionStrategyLabel,
+                      resourceTitle: t.resourceTitle,
+                      resourceTitlePlaceholder: t.resourceTitlePlaceholder,
+                      saveLocation: t.saveLocation,
+                      entityTypes: t.entityTypes,
+                      language: t.language,
+                      contentLabel: t.contentLabel,
+                      back: t.back,
+                      createAndLink: t.createAndLink,
+                      creatingAndLinking: t.creatingAndLinking,
                     }}
                   />
+                  </div>
                 )}
 
                 {wizardStep.step === 'configure-generation' && context && (
+                  <div className="semiont-wizard__step-scroll" ref={stepScrollRef}>
+                  <GatherContextStep
+                    context={context}
+                    contextLoading={contextLoading}
+                    contextError={contextError}
+                    chosenStrategy={{ label: t.resolutionStrategyLabel, value: `✨ ${t.generate}` }}
+                    translations={displayTranslations}
+                  />
                   <ConfigureGenerationStep
                     {...(generationAgent ? { generationAgent } : {})}
+                    {...(userHint ? { hintEcho: { label: t.userHintLabel, value: userHint } } : {})}
                     context={contextWithHint ?? context}
                     config={generationDraft}
                     onConfigChange={setGenerationDraft}
@@ -295,6 +466,7 @@ export function ReferenceWizardModal({
                     translations={{
                       resourceTitle: t.resourceTitle,
                       resourceTitlePlaceholder: t.resourceTitlePlaceholder,
+                      saveLocation: t.saveLocation,
                       additionalInstructions: t.additionalInstructions,
                       additionalInstructionsPlaceholder: t.additionalInstructionsPlaceholder,
                       language: t.language,
@@ -309,13 +481,24 @@ export function ReferenceWizardModal({
                       generate: t.generate,
                     }}
                   />
+                  </div>
                 )}
 
                 {wizardStep.step === 'configure-search' && (
+                  <div className="semiont-wizard__step-scroll" ref={stepScrollRef}>
+                  <GatherContextStep
+                    context={context}
+                    contextLoading={contextLoading}
+                    contextError={contextError}
+                    chosenStrategy={{ label: t.resolutionStrategyLabel, value: `🔍 ${t.search}` }}
+                    translations={displayTranslations}
+                  />
                   <ConfigureSearchStep
                     config={searchConfig}
+                    {...(userHint ? { hintEcho: { label: t.userHintLabel, value: userHint } } : {})}
                     onConfigChange={setSearchConfig}
                     isSearching={isSearching}
+                    searchError={searchError}
                     onBack={handleBackToGather}
                     onSearch={handleSearchSubmit}
                     translations={{
@@ -325,14 +508,23 @@ export function ReferenceWizardModal({
                       back: t.back,
                       search: t.search,
                       searching: t.searching,
+                      searchFailed: t.searchFailed,
                     }}
                   />
+                  </div>
                 )}
 
                 {wizardStep.step === 'search-results' && context && (
+                  <div className="semiont-wizard__step-scroll" ref={stepScrollRef}>
+                  <GatherContextStep
+                    context={context}
+                    contextLoading={contextLoading}
+                    contextError={contextError}
+                    chosenStrategy={{ label: t.resolutionStrategyLabel, value: `🔍 ${t.search}` }}
+                    translations={displayTranslations}
+                  />
                   <SearchResultsStep
                     results={wizardStep.results}
-                    context={context}
                     onLink={handleLink}
                     onBack={handleBackToGather}
                     translations={{
@@ -340,13 +532,9 @@ export function ReferenceWizardModal({
                       link: t.link,
                       back: t.back,
                       score: t.score,
-                      sourceContextLabel: t.sourceContextLabel,
-                      connectionsLabel: t.connectionsLabel,
-                      citedByLabel: t.citedByLabel,
-                      userHintLabel: t.userHintLabel,
-                      userHintPlaceholder: t.userHintPlaceholder,
                     }}
                   />
+                  </div>
                 )}
               </DialogPanel>
             </TransitionChild>