generated from coulomb/repo-seed
Implement CE-WP-0003 T01-T08: form binding + visual guide overlay
T01 EvidenceLink/EvidenceSet types
- src/shared/evidence-link.ts: status (§2.4), relation (§2.5), target
- src/shared/evidence-set.ts: ordered group + activeEvidenceItemId
- enum-conformance test parses SharedContracts.md and asserts the
runtime lists match exactly
T02 Binding service + in-memory link repo + active-state machine
- src/binder/repos/in-memory-links.ts: Map-backed EvidenceLinkRepository
- src/binder/services/bindings.ts: link/unlink/list/update/setActive
emitting §4 EvidenceLinkCreated / EvidenceLinkUpdated /
EvidenceItemActivated
- src/binder/state/active.ts: (target, evidence, annotation) reducer
+ ActiveStateProvider + useActiveState hook
- extended engine/events/types.ts with EvidenceLinkCreated,
EvidenceLinkUpdated, FormFieldActivated payloads
T03 Rect registry (SharedContracts §7 — contract FROZEN)
- src/binder/visual-guide/rect-registry.ts: register/getRect/subscribe
+ invalidate + getVersion for useSyncExternalStore
- events.ts: scroll/resize/focus pumps via window + ResizeObserver +
IntersectionObserver, rAF-throttled
- react-hooks.ts: RectRegistryProvider, useRegisterRect(kind,id,ref),
useRectRegistryVersion
T04 Form schema + renderer
- src/app/forms/demo-schema.ts: text/textarea/date minimal schema
- src/binder/FormRenderer.tsx: renders schema, each field registers
as rect kind="field"; active field gets aria-current="true"
- placed in binder/ (not work/) because work cannot import binder per
DependencyMap.md §2 and the renderer needs the rect-registry hook;
workplan T04 was amended in-place to document this
T05 Side-by-side Forms layout + click-to-link
- src/app/forms/FormsApp.tsx + src/app/App.tsx top-bar router with
hash route #/forms/demo
- BinderProvider mounted at app root so links survive tab switching
- stage-evidence-then-click-field linking interaction with banner
+ per-field link-count chip
T06 Active-evidence cycling
- src/app/forms/ActiveEvidenceChips.tsx: chips per active target,
Tab cycles natively, first chip auto-activates on field focus,
each chip registers as rect kind="evidence-card"
- ScrollBridge in FormsApp wires activeAnnotationId to viewer scroll
- EvidenceSidebar + EvidenceStrip highlight the active item via the
new useLastActivatedEvidence hook in work/EngineContext
T07 SVG visual-guide overlay
- src/binder/visual-guide/Overlay.tsx: single fixed-positioned SVG,
draws field→card and card→highlight bezier curves for the active
triple, rAF-throttled via the registry
- src/anchor exposes getHighlightClientRects(annotationId); the
spike viewer wraps highlights in [data-highlight-id] so the helper
can locate them
- src/app/forms/HighlightRectBridge.tsx: registers the active
annotation's rect via that helper
T08 End-to-end test (PRD scenario steps 5-9)
- tests/integration/forms-overlay-e2e.dom.test.tsx: full path from
Review-mode capture through Forms-mode link to active triple +
aria-current assertions + 2 SVG paths in the overlay
- additional integration coverage: forms-link-flow + forms-active-cycling
Gates: typecheck ✓ · lint ✓ · build ✓ · 152/152 tests across 21 files.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
97
src/binder/BinderProvider.tsx
Normal file
97
src/binder/BinderProvider.tsx
Normal file
@@ -0,0 +1,97 @@
|
||||
/**
|
||||
* BinderProvider — composition root for the binder subsystem.
|
||||
*
|
||||
* Wires the four binder concerns (rect registry, binding service, link
|
||||
* repo, active state machine) into one provider so a single mount inside
|
||||
* the EngineProvider gives every binder consumer (FormRenderer, evidence
|
||||
* picker, SVG overlay) what it needs.
|
||||
*
|
||||
* The provider is split out from the engine because in a future
|
||||
* subsystem-extraction these will live in separate packages — the engine
|
||||
* will publish only the event bus and the engine services, while
|
||||
* `evidence-binder` will export this provider.
|
||||
*/
|
||||
|
||||
import {
|
||||
createContext,
|
||||
useContext,
|
||||
useEffect,
|
||||
useMemo,
|
||||
type ReactNode,
|
||||
} from "react";
|
||||
|
||||
import type { EventBus } from "@engine/events";
|
||||
|
||||
import {
|
||||
ActiveStateProvider,
|
||||
useActiveState,
|
||||
} from "./state/active";
|
||||
import {
|
||||
createInMemoryLinkRepo,
|
||||
type EvidenceLinkRepository,
|
||||
} from "./repos/in-memory-links";
|
||||
import {
|
||||
createBindingService,
|
||||
type BindingService,
|
||||
} from "./services/bindings";
|
||||
import {
|
||||
RectRegistryProvider,
|
||||
createRectRegistryContextValue,
|
||||
type RectRegistryContextValue,
|
||||
} from "./visual-guide/react-hooks";
|
||||
|
||||
export interface BinderServices {
|
||||
readonly links: EvidenceLinkRepository;
|
||||
readonly bindings: BindingService;
|
||||
readonly rect: RectRegistryContextValue;
|
||||
}
|
||||
|
||||
const BinderServicesContext = createContext<BinderServices | null>(null);
|
||||
|
||||
export function useBinder(): BinderServices {
|
||||
const ctx = useContext(BinderServicesContext);
|
||||
if (!ctx) throw new Error("useBinder: missing <BinderProvider />");
|
||||
return ctx;
|
||||
}
|
||||
|
||||
export interface BinderProviderProps {
|
||||
readonly children: ReactNode;
|
||||
/**
|
||||
* The engine's event bus, threaded in by the composition root so the
|
||||
* binder can emit §4 events without importing work/EngineContext
|
||||
* (work cannot be a dependency of binder — see DependencyMap §2).
|
||||
*/
|
||||
readonly bus: EventBus;
|
||||
/**
|
||||
* Tests can inject a pre-built service set; production constructs a
|
||||
* fresh one. The rect registry is *always* fresh per provider mount
|
||||
* because its observers attach to the current `window`.
|
||||
*/
|
||||
readonly services?: Omit<BinderServices, "rect">;
|
||||
}
|
||||
|
||||
export function BinderProvider({ children, bus, services }: BinderProviderProps) {
|
||||
const built = useMemo<BinderServices>(() => {
|
||||
const links = services?.links ?? createInMemoryLinkRepo();
|
||||
const bindings = services?.bindings ?? createBindingService(links, bus);
|
||||
const rect = createRectRegistryContextValue();
|
||||
return { links, bindings, rect };
|
||||
}, [bus, services]);
|
||||
|
||||
// Disconnect rect observers + listeners on unmount.
|
||||
useEffect(() => {
|
||||
return () => {
|
||||
built.rect.observer.disconnect();
|
||||
};
|
||||
}, [built.rect]);
|
||||
|
||||
return (
|
||||
<BinderServicesContext.Provider value={built}>
|
||||
<RectRegistryProvider value={built.rect}>
|
||||
<ActiveStateProvider bus={bus}>{children}</ActiveStateProvider>
|
||||
</RectRegistryProvider>
|
||||
</BinderServicesContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
export { useActiveState };
|
||||
Reference in New Issue
Block a user