feat(editor): reference dialog, reading tiles and finding filter in the history

R2F-5 and R2F-6: the reference dialog is a view layer above the References tab or the citations sheet (local draft, one command per changed save, creation entry becomes the reference's own). Tiles only read. « Tout afficher » filters the library by the finding, « Revenir au constat » pops or pushes. Inline tile edit, draft tile and their guards removed.
This commit is contained in:
bchanot committed 2026-11-13 20:27:00 +01:00
1 parent e2d020bd3d
commit 8031e0078f
28 files changed
+1072 -1512

No files matched your search

+12 -1
View File
@@ -1,4 +1,4 @@
import type { FindingLayer } from './tabs'
import type { FindingLayer, ReferenceLayer } from './tabs'
import type { EditorNavigation } from './useEditorNavigation'
/** What Constats needs of the navigation for its dialog and the sheet over it. */
@@ -14,3 +14,14 @@ export function findingLayerOf(nav: EditorNavigation): FindingLayer {
announce: nav.announce,
}
}
/** What the References tab and the reference dialog need of the navigation. */
export function referenceLayerOf(nav: EditorNavigation): ReferenceLayer {
return {
view: nav.state.reference,
filter: nav.state.referenceFilter,
guards: nav.guards,
announce: nav.announce,
...nav.references,
}
}
+1 -2
View File
@@ -174,8 +174,7 @@ export function focusActiveTab(options?: FocusOptions): void {
/**
* The element sits in a transactional form of an open dialog: the form keeps its draft
* and its focus when the editor turns read-only, nothing moves it. (The citations
* sheet's tiles still edit inline until the reference dialog: they are not drafts.)
* and its focus when the editor turns read-only, nothing moves it.
*/
function inOpenDialog(element: HTMLElement): boolean {
return element.closest('dialog[open] [data-draft-form]') !== null
+43 -5
View File
@@ -68,11 +68,35 @@ function sanitizeFinding(raw: unknown, forms: boolean): EditorView['finding'] {
return { key, citations: sheet }
}
/**
* The reference dialog of a view: over the References tab, or over the citations sheet
* (the only other place that opens it). A form, so only read back where forms are kept;
* whether the reference still exists is the dialog's own gone rule.
*/
function sanitizeReference(
raw: unknown,
finding: EditorView['finding'],
tab: unknown,
): EditorView['reference'] {
if (!isRecord(raw)) return null
const sheet = !!finding && 'key' in finding && finding.citations
if (raw.create === true) return tab === 'references' ? { create: true } : null
const id = raw.edit
if (typeof id !== 'string' || id === '') return null
return tab === 'references' || sheet ? { edit: id } : null
}
/** The finding the References tab is filtered by: a finding node, on that tab only. */
function sanitizeFilter(raw: unknown, tab: unknown): ElementKey | null {
const key = tab === 'references' ? sanitizeKey(raw) : null
return key && isFindingNode(key) ? key : null
}
/**
* A view read back from a history entry, or null when it is no view. The finding layer
* must name a well-formed key and sit on the Constats tab; whether the element still
* exists is the dialog's own gone rule. `forms` false drops the creation form (a reload
* never reopens a form). The reference layer and the filter stay null until they exist.
* exists is the dialog's own gone rule. `forms` false drops the forms (a creation, the
* reference dialog): a reload never reopens a form.
*/
export function sanitizeView(raw: unknown, forms = true): EditorView | null {
if (!isRecord(raw)) return null
@@ -80,12 +104,15 @@ export function sanitizeView(raw: unknown, forms = true): EditorView | null {
const known = ANNOTATION_SECTIONS.includes(raw.section as AnnotationSection)
const finding =
raw.tab === 'findings' ? sanitizeFinding(raw.finding, forms) : null
const reference = forms
? sanitizeReference(raw.reference, finding, raw.tab)
: null
return {
tab: raw.tab as EditorTabId,
section: known ? (raw.section as AnnotationSection) : 'drawing',
finding,
reference: null,
referenceFilter: null,
reference,
referenceFilter: sanitizeFilter(raw.referenceFilter, raw.tab),
}
}
@@ -147,19 +174,30 @@ function isRemoval(top: EditorView, view: EditorView): boolean {
/** What a changed view asks of the history. */
export type HistoryWrite = 'none' | 'push' | 'replace' | 'back'
/** True when `view` shows the finding `key` (its dialog, with or without the sheet). */
export function showsFinding(view: EditorView, key: ElementKey): boolean {
const { finding } = view
const shown = finding && 'key' in finding ? finding.key : null
return shown !== null && JSON.stringify(shown) === JSON.stringify(key)
}
/**
* A user move to `view`. A layer taken away, or a section left for its drawing ("Retour
* au dessin"), goes back when the entry holds the view the move lands on (the entry that
* opened it), else it replaces; a layer, tab or section added pushes, unless the move
* asked for a replace.
* asked for a replace. `backTo` (« Revenir au constat ») goes back when the entry below
* shows that finding.
*/
export function planWrite(
top: HistoryEntry,
view: EditorView,
replace: boolean,
backTo: ElementKey | null = null,
): HistoryWrite {
if (sameView(top.view, view)) return 'none'
if (replace) return 'replace'
// « Revenir au constat »: the entry below already shows that finding, a Back is the move.
if (backTo && top.below && showsFinding(top.below, backTo)) return 'back'
if (isRemoval(top.view, view)) {
return top.below && sameView(top.below, view) ? 'back' : 'replace'
}
@@ -120,12 +120,13 @@ function useReconcile(
writer: Writer,
) {
useEffect(() => {
const { scrollY, replace } = nav.trace
const { scrollY, replace, backTo } = nav.trace
nav.trace.scrollY = null
nav.trace.replace = false
nav.trace.backTo = null
const top = book.entry
if (!top || book.pendingBack) return
const plan = planWrite(top, view, replace)
const plan = planWrite(top, view, replace, backTo)
if (plan === 'none') return
book.scrolls.set(top.id, scrollY ?? window.scrollY)
if (plan === 'back') writer.back()
+55 -10
View File
@@ -29,9 +29,9 @@ export interface FocusRequest {
/**
* What the browser history records of the editor (R2F-1): where the user is, never what
* they typed. A layer (`finding`, `reference`) is a dialog over a place; `citations` is
* the side sheet over the finding dialog; `referenceFilter` narrows the references
* library to the citers of an element. `reference` and `referenceFilter` stay null until
* the reference dialog and the filter exist.
* the side sheet over the finding dialog; `reference` is the reference dialog above
* either; `referenceFilter` (only on the References tab) narrows the library to the
* references a finding cites. The search text is a personal search: never part of a view.
*/
export interface EditorView {
tab: EditorTabId
@@ -64,7 +64,11 @@ export type NavigationAction =
| { type: 'close_finding' }
| { type: 'open_citations'; citedBy: ElementKey }
| { type: 'close_citations' }
| { type: 'show_all_references' }
| { type: 'open_reference'; id: string }
| { type: 'create_reference' }
| { type: 'close_reference' }
| { type: 'show_all_references'; filter: ElementKey }
| { type: 'clear_reference_filter' }
| { type: 'go_to'; target: EditorTarget }
| { type: 'restore_view'; view: EditorView }
| { type: 'focus_consumed'; serial: number }
@@ -115,6 +119,9 @@ function shown(state: NavigationState): NavigationState {
return { ...state, visitedTabs, visitedSections }
}
/** What a move to another tab leaves behind: the reference dialog and the filter. */
const LEFT_REFERENCES = { reference: null, referenceFilter: null } as const
const DEFAULT_VIEW = {
section: 'drawing',
finding: null,
@@ -207,7 +214,7 @@ function closeCitations(state: NavigationState): NavigationState {
/** The finding dialog of `key`, in view mode, on the Constats tab. */
function openFinding(state: NavigationState, key: ElementKey): NavigationState {
const finding = { key, citations: false }
return shown({ ...state, tab: 'findings', finding })
return shown({ ...state, ...LEFT_REFERENCES, tab: 'findings', finding })
}
/** The creation form of a zone, a category or a node, on the Constats tab. */
@@ -215,40 +222,70 @@ function createFinding(
state: NavigationState,
create: { kind: string; parent: ElementKey | null },
): NavigationState {
return shown({ ...state, tab: 'findings', finding: { create } })
const finding = { create }
return shown({ ...state, ...LEFT_REFERENCES, tab: 'findings', finding })
}
function goTo(state: NavigationState, target: EditorTarget): NavigationState {
const serial = state.serial + 1
// The filter survives only a move to the tab itself that names no reference.
const keep = target.tab === 'references' && target.key === null
const moved = {
...state,
tab: target.tab,
section: target.section ?? state.section,
finding: null,
reference: null,
referenceFilter: keep ? state.referenceFilter : null,
focus: { target, serial },
serial,
}
return shown(moved)
}
/** « Tout afficher dans l'onglet Références »: the layers close, the library starts afresh. */
function showAllReferences(state: NavigationState): NavigationState {
/**
* « Tout afficher dans l'onglet Références »: the layers close, the library starts afresh
* and lists what `filter` (the finding the sheet belongs to) cites.
*/
function showAllReferences(
state: NavigationState,
filter: ElementKey,
): NavigationState {
const moved = {
...state,
tab: 'references' as const,
finding: null,
reference: null,
referenceFilter: filter,
libraryReset: state.libraryReset + 1,
}
return shown(moved)
}
/** A tab other than References has no filter: the filter belongs to that tab's view. */
function selectTab(state: NavigationState, tab: EditorTabId): NavigationState {
const filter = tab === 'references' ? state.referenceFilter : null
const left = { finding: null, reference: null, referenceFilter: filter }
return shown({ ...state, ...left, tab })
}
/** The reference dialog of `id`, above the place (and the sheet) the view shows. */
function openReference(state: NavigationState, id: string): NavigationState {
return shown({ ...state, reference: { edit: id } })
}
/** The creation form of a reference: only the References tab adds one. */
function createReference(state: NavigationState): NavigationState {
return shown({ ...state, tab: 'references', reference: { create: true } })
}
export function navigationReducer(
state: NavigationState,
action: NavigationAction,
): NavigationState {
switch (action.type) {
case 'select_tab':
return shown({ ...state, tab: action.tab, finding: null })
return selectTab(state, action.tab)
case 'open_section':
return shown({ ...state, section: action.section })
case 'back_to_drawing':
@@ -263,8 +300,16 @@ export function navigationReducer(
return openCitations(state, action.citedBy)
case 'close_citations':
return closeCitations(state)
case 'open_reference':
return openReference(state, action.id)
case 'create_reference':
return createReference(state)
case 'close_reference':
return { ...state, reference: null }
case 'show_all_references':
return showAllReferences(state)
return showAllReferences(state, action.filter)
case 'clear_reference_filter':
return { ...state, referenceFilter: null }
case 'go_to':
return goTo(state, action.target)
case 'restore_view':
+17 -6
View File
@@ -7,9 +7,12 @@ export interface ReferenceView {
sort: ReferenceSort
}
/** Stored order, no search: the only view where ↑ / ↓ mean something (A1). */
export const isSheetView = (view: ReferenceView) =>
view.sort === 'sheet' && view.query.trim() === ''
/**
* Stored order, no search, no finding filter: the only view where ↑ / ↓ mean something
* (A1). `filtered` is true while the library lists one finding's citations (R2F-6).
*/
export const isSheetView = (view: ReferenceView, filtered = false) =>
!filtered && view.sort === 'sheet' && view.query.trim() === ''
/**
* The tile in edit, kept in the shown set at `index` whatever the search or the sort
@@ -20,18 +23,26 @@ export interface Pin {
index: number
}
/** The positions to show: the search, then the sort, then the pinned tile put back. */
/**
* The positions to show: the finding filter (`cited`, the ids that finding cites; null for
* none), the search, then the sort, then the pinned tile put back. A pin is for the
* unfiltered library only: a tile outside the filter never shows.
*/
export function shownPositions(
references: readonly Reference[],
view: ReferenceView,
context: SortContext,
pin: Pin | null,
cited: ReadonlySet<string> | null = null,
): number[] {
const matching = references.flatMap((reference, position) =>
referenceMatches(reference, view.query) ? [position] : [],
referenceMatches(reference, view.query) &&
(cited === null || cited.has(reference.id))
? [position]
: [],
)
const sorted = sortReferenceIds(references, matching, view.sort, context)
if (pin === null) return sorted
if (pin === null || cited !== null) return sorted
const rest = sorted.filter((position) => position !== pin.position)
rest.splice(Math.min(pin.index, rest.length), 0, pin.position)
return rest
+24
View File
@@ -3,6 +3,7 @@ import type { EditorTarget, EditorView, FocusRequest } from './navigation'
import { unmeasuredViews } from './issues'
import type { TabTier } from './useViewport'
import type { Guards } from './useEditorNavigation'
import type { AddedReference } from './useReferenceMoves'
export const EDITOR_TABS = [
'general',
@@ -54,6 +55,27 @@ export interface FindingLayer {
announce: (text: string) => void
}
/**
* What the References tab and the reference dialog need of the navigation (R2F-5, R2F-6):
* the layer and the filter the view holds, and the moves on them.
*/
export interface ReferenceLayer {
view: EditorView['reference']
/** The finding whose citations the library lists; null for the whole bibliography. */
filter: ElementKey | null
guards: Guards
open: (id: string, opener?: HTMLElement | null) => void
start: (opener?: HTMLElement | null) => void
close: (forced?: boolean) => boolean
replace: (id: string | null, text?: string) => void
created: (id: string) => void
added: AddedReference | null
opener: () => HTMLElement | null
clearFilter: (text?: string) => void
backToFinding: (key: ElementKey) => void
announce: (text: string) => void
}
/** Props of every place (tab body, Annotations section). */
export interface EditorPlaceProps {
/** Not editable now: a mode that cannot save, or a recovery offer not answered yet. */
@@ -64,6 +86,8 @@ export interface EditorPlaceProps {
focus?: FocusRequest
/** The finding dialog and the citations sheet over it (only Constats has them). */
layer?: FindingLayer
/** The reference dialog and the filter (only the References tab and the sheet use them). */
references?: ReferenceLayer
/** Bumped by « Tout afficher »: the references library resets its search once per bump. */
libraryReset?: number
/** Reads the sheet's overview again (after a submission: the round freezes the draft). */
+30 -13
View File
@@ -33,6 +33,7 @@ import {
type NavigationState,
} from './navigation'
import { MORE_BUTTON_ID, tabDomId, type EditorTabId } from './tabs'
import { useReferenceMoves, type ReferenceMoves } from './useReferenceMoves'
type MoveKind = 'go_to' | 'show_all' | 'tab_selected' | 'section' | 'back'
@@ -52,7 +53,7 @@ export interface LeaveAnswer {
export type CanLeave = (forced: boolean) => LeaveAnswer
/** The layers that can hold a form the user must settle before leaving, top one last. */
const LAYERS = ['citations', 'finding', 'reference'] as const
const LAYERS = ['finding', 'reference'] as const
export type LayerName = (typeof LAYERS)[number]
/** One guard per layer (R2F-1): each layer registers its own check while it is mounted. */
@@ -72,6 +73,8 @@ export interface Guards {
export interface MoveTrace {
scrollY: number | null
replace: boolean
/** « Revenir au constat »: a Back when the entry below shows this finding. */
backTo: ElementKey | null
}
/** Options of a tab choice. */
@@ -107,8 +110,13 @@ export interface EditorNavigation {
closeCitations: () => boolean
/** « X références », where the focus returns once the sheet is closed. */
citationsTrigger: () => HTMLElement | null
/** « Tout afficher dans l'onglet Références »: layers closed, tab shown, library reset. */
showAllReferences: () => void
/**
* « Tout afficher dans l'onglet Références »: layers closed, tab shown, library reset
* and filtered by the finding the sheet belongs to.
*/
showAllReferences: (filter: ElementKey) => void
/** The reference dialog and the References tab's filter. */
references: ReferenceMoves
guards: Guards
trace: MoveTrace
/** A Back or Forward landed on `view` (the history adapter's way in): no move, no request. */
@@ -197,11 +205,16 @@ function useGuards(): Guards {
}
function useMoveTrace() {
const trace = useRef<MoveTrace>({ scrollY: null, replace: false }).current
const trace = useRef<MoveTrace>({
scrollY: null,
replace: false,
backTo: null,
}).current
const mark = useCallback(
(replace = false) => {
trace.scrollY = window.scrollY
trace.replace = replace
trace.backTo = null
},
[trace],
)
@@ -227,6 +240,7 @@ function useGo(dispatch: Dispatch<NavigationAction>, trace: MoveTrace) {
announce(text)
trace.scrollY = window.scrollY
trace.replace = false
trace.backTo = null
dispatch(action)
setMove({ kind })
},
@@ -255,7 +269,7 @@ function useSectionMoves(go: Go, openers: Openers) {
}
/** What the layers' moves need of the hook. */
interface LayerContext {
export interface LayerContext {
dispatch: Dispatch<NavigationAction>
announce: (text: string) => void
guards: Guards
@@ -315,7 +329,7 @@ function useFindingClosing({ dispatch, announce, guards, mark }: LayerContext) {
/** The citations sheet over the finding dialog: opened from a finding node only. */
function useSheetLayer(ctx: LayerContext, openers: Openers) {
const { dispatch, guards, mark } = ctx
const { dispatch, mark } = ctx
const openCitations = useCallback(
(citedBy: ElementKey, opener?: Opener) => {
if (!isFindingNode(citedBy)) return
@@ -327,11 +341,10 @@ function useSheetLayer(ctx: LayerContext, openers: Openers) {
[openers, dispatch, mark],
)
const closeCitations = useCallback(() => {
if (!guards.ask('citations', false).allowed) return false
mark()
dispatch({ type: 'close_citations' })
return true
}, [guards, dispatch, mark])
}, [dispatch, mark])
return { openCitations, closeCitations }
}
@@ -346,11 +359,14 @@ function useLeavingMoves(go: Go, guards: Guards) {
},
[go, guards, moveText],
)
const showAllReferences = useCallback(() => {
if (!guards.askAll(false).allowed) return
const text = t('editor.tab.references')
go({ type: 'show_all_references' }, 'show_all', text)
}, [go, guards, t])
const showAllReferences = useCallback(
(filter: ElementKey) => {
if (!guards.askAll(false).allowed) return
const text = t('editor.tab.references')
go({ type: 'show_all_references', filter }, 'show_all', text)
},
[go, guards, t],
)
return { navigate, showAllReferences }
}
@@ -497,6 +513,7 @@ export function useEditorNavigation(
...useFindingLayer(ctx),
...useSheetLayer(ctx, openers),
...useLeavingMoves(base.go, guards),
references: useReferenceMoves(ctx, base.trace),
citationsTrigger: useCallback(() => triggerOf(openers), [openers]),
guards,
trace: base.trace,
+147
View File
@@ -0,0 +1,147 @@
import { useCallback, useRef, useState, type RefObject } from 'react'
import type { ElementKey } from '@faunosteo/core-wasm/types'
import type { LayerContext, MoveTrace } from './useEditorNavigation'
/** The reference a creation just made: the library shows a notice for it, once per serial. */
export interface AddedReference {
id: string
serial: number
}
type Opener = HTMLElement | null | undefined
/** What the reference dialog (R2F-5) and the References tab's filter (R2F-6) do to the view. */
export interface ReferenceMoves {
/** The dialog of reference `id`, over the place the view shows. */
open: (id: string, opener?: Opener) => void
/** The creation dialog, over the References tab. */
start: (opener?: Opener) => void
/** A user close; false when the form refused it (a dirty draft asks first). */
close: (forced?: boolean) => boolean
/**
* The dialog becomes another view of itself, by replace (no Back entry): `null` closes
* it. With `text`, a close the user did not ask for (the reference vanished): forced,
* said once the dialogs are closed.
*/
replace: (id: string | null, text?: string) => void
/** A creation succeeded: its entry becomes the reference's own, then the dialog closes. */
created: (id: string) => void
added: AddedReference | null
/** The element that opened the dialog, while it is still on the page. */
opener: () => HTMLElement | null
/** « × » of the filter chip, or a vanished finding (`text` says so): a replace. */
clearFilter: (text?: string) => void
/** « Revenir au constat »: a Back when the entry below shows it, else its dialog. */
backToFinding: (key: ElementKey) => void
}
/** The moves that add the dialog: an edit of a reference, a creation. */
function useOpening({ dispatch, mark }: LayerContext, held: RefObject<Opener>) {
const open = useCallback(
(id: string, opener?: Opener) => {
held.current = opener
mark()
dispatch({ type: 'open_reference', id })
},
[dispatch, mark, held],
)
const start = useCallback(
(opener?: Opener) => {
held.current = opener
mark()
dispatch({ type: 'create_reference' })
},
[dispatch, mark, held],
)
return { open, start }
}
/** The moves that take it away: a user close, and the replace that is no Back step. */
function useClosing({ dispatch, announce, guards, mark }: LayerContext) {
const close = useCallback(
(forced = false) => {
if (!guards.ask('reference', forced).allowed) return false
mark()
dispatch({ type: 'close_reference' })
return true
},
[guards, dispatch, mark],
)
const replace = useCallback(
(id: string | null, text?: string) => {
const note = text ? guards.ask('reference', true).note : undefined
if (text) announce(note ? `${note}. ${text}` : text)
mark(true)
dispatch(
id ? { type: 'open_reference', id } : { type: 'close_reference' },
)
},
[guards, announce, dispatch, mark],
)
return { close, replace }
}
/** A creation that succeeded: its entry becomes the reference's own, then it closes. */
function useCreated(
{ dispatch, mark }: LayerContext,
replace: ReferenceMoves['replace'],
) {
const [added, setAdded] = useState<AddedReference | null>(null)
const created = useCallback(
(id: string) => {
replace(id)
setAdded((last) => ({ id, serial: (last?.serial ?? 0) + 1 }))
// After the commit that wrote the replace: the entry is the reference's own before
// the close goes back over it, so a Forward never reopens a creation.
queueMicrotask(() => {
mark()
dispatch({ type: 'close_reference' })
})
},
[replace, mark, dispatch],
)
return { created, added }
}
/** The filter's two moves: remove it by replace, return to the finding it names. */
function useFilter(
{ dispatch, announce, mark }: LayerContext,
trace: MoveTrace,
) {
const clearFilter = useCallback(
(text?: string) => {
if (text) announce(text)
mark(true)
dispatch({ type: 'clear_reference_filter' })
},
[announce, dispatch, mark],
)
const backToFinding = useCallback(
(key: ElementKey) => {
mark()
trace.backTo = key
dispatch({ type: 'open_finding', key })
},
[dispatch, mark, trace],
)
return { clearFilter, backToFinding }
}
export function useReferenceMoves(
ctx: LayerContext,
trace: MoveTrace,
): ReferenceMoves {
const held = useRef<Opener>(null)
const opener = useCallback((): HTMLElement | null => {
const element = held.current
return element?.isConnected && !element.closest('[hidden]') ? element : null
}, [held])
const closing = useClosing(ctx)
return {
...useOpening(ctx, held),
...closing,
...useCreated(ctx, closing.replace),
...useFilter(ctx, trace),
opener,
}
}