sillsdev / sillsdev/interlinearizer-extension
Decide the shape of the focus-request seam: `requestFocusToken` has no production caller
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 2
- Forks
- 0
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 55
Description
requestFocusToken has no production caller, and the pairing contract it carries is not self-enforcing.
Raised by @imnasnainaec in review of #235 (https://github.com/sillsdev/interlinearizer-extension/pull/235#issuecomment-5370191365), where it was explicitly out of scope.
What's there now
InterlinearNavContext exposes a focus-request slot as three members:
requestFocusToken(tokenRef)— producer,src/components/InterlinearNavContext.tsx:172focusRequestCount— the notice signal,src/components/InterlinearNavContext.tsx:179consumeFocusRequest(bookCode)— consumer,src/components/InterlinearNavContext.tsx:189
The consumer end is live: Interlinearizer.tsx:305 calls consumeFocusRequest(book.bookRef) and focuses the returned token. The producer end is not — the only calls to requestFocusToken are in src/__tests__/components/Interlinearizer.test.tsx and src/__tests__/components/InterlinearNavContext.test.tsx. So the slot can currently only ever be filled by a test.
Why it's worth deciding
The doc comment states the contract the caller has to honor:
A request moves focus and nothing else, so the caller must navigate to the token's verse itself: unpaired, the focus lands outside the verse on screen, and the request is dropped only once navigation happens to leave the book it names.
That pairing is asserted only by tests that already do it correctly. Nothing fails if a future caller forgets the navigate half — the failure is a focus silently landing outside the verse on screen, and a request that lingers until navigation happens to leave the book. The first production caller has to read the doc comment to get it right.
The first caller is already planned
#193 (analysis catalog: read-only panel) states "Depends on the store hoist and focus seam, and on the pure query core", and lists jump-to-usage navigation among its deliverables. Jumping from a catalog row to a usage is exactly the paired gesture the contract describes: navigate to that usage's verse and focus that token. So this is not dead code to delete — it is a seam about to get its first real caller, which is the moment to decide whether the pairing should be enforced by the API.
Options
- (a) Fold the navigate into
requestFocusTokenso the pairing can't be forgotten. Makes the hazard unrepresentable; changes the API and touchesInterlinearNavContextplus its tests. Cheapest to do before #193 adds the first call site rather than after. - (b) Keep the seam as-is and note in the doc comment that it currently has no production caller, so a reader knows the contract is untested against real usage.
Not exclusive — (b) is worth doing regardless if (a) is deferred past #193.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the focus-request members in src/components/InterlinearNavContext.tsx at lines 172, 179, and 189, then read the consumer at Interlinearizer.tsx:305 and the tests in src/tests/components/Interlinearizer.test.tsx and src/tests/components/InterlinearNavContext.test.tsx. Decide whether the pairing should be enforced by the API or documented as-is, and update the affected context, tests, and documentation so the chosen contract is explicit before #193 adds a caller.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- frontend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100