Files
faunosteo/apps/app/src/editor/useReferenceMoves.ts
T

215 lines
7.5 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { useCallback, useEffect, useRef, useState } from 'react'
import type { ElementKey, Reference } from '@faunosteo/core-wasm/types'
import type { NavigationState } from './navigation'
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 a creation started from the citations dialog's edit form does with its value
* (Rev 6): the reference joins that form's draft, nothing is written.
*/
export type CiteCreated = (value: Reference) => void
/** A draft creation: the citing form, and the pending reference modified (null: a new one). */
export interface Drafting {
initial: Reference | null
cite: CiteCreated
}
/** 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 or the citations dialog. `cite` is the
* citations edit form that started it (Rev 6): the dialog writes nothing and hands the
* value to its draft; `initial` is the pending reference it modifies.
*/
start: (opener?: Opener, cite?: CiteCreated, initial?: Reference) => void
/** The open dialog's draft creation, read from what started it; null for any other. */
drafting: () => Drafting | null
/** 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 library creation succeeded: its entry becomes the reference's own, then the dialog
* closes and the library says it.
*/
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
}
/**
* What the open dialog was started from: its opener, and for a draft creation the citing
* form and the pending value (both forgotten once the dialog closes or is replaced).
*/
interface Held {
opener: Opener
cite: CiteCreated | null
initial: Reference | null
}
/** No draft creation any more: the citing form and its pending value go together. */
function forget(held: Held) {
held.cite = null
held.initial = null
}
/** The moves that add the dialog: an edit of a reference, a creation. */
function useOpening({ dispatch, mark }: LayerContext, held: Held) {
const open = useCallback(
(id: string, opener?: Opener) => {
held.opener = opener
forget(held)
mark()
dispatch({ type: 'open_reference', id })
},
[dispatch, mark, held],
)
const start = useCallback(
(opener?: Opener, cite?: CiteCreated, initial?: Reference) => {
held.opener = opener
held.cite = cite ?? null
held.initial = cite ? (initial ?? null) : null
mark()
dispatch({ type: 'create_reference' })
},
[dispatch, mark, held],
)
return { open, start }
}
/** A user close: the form may refuse it (a dirty draft asks first). */
function useClose({ dispatch, guards, mark }: LayerContext, held: Held) {
return useCallback(
(forced = false) => {
if (!guards.ask('reference', forced).allowed) return false
forget(held)
mark()
dispatch({ type: 'close_reference' })
return true
},
[guards, dispatch, mark, held],
)
}
/** The replace that is no Back step; with `text`, forced and said with a dropped draft. */
function useReplace(ctx: LayerContext, held: Held) {
const { dispatch, announce, guards, mark } = ctx
return useCallback(
(id: string | null, text?: string) => {
forget(held)
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, held],
)
}
/** The moves that take it away: a user close, and the replace that is no Back step. */
function useClosing(ctx: LayerContext, held: Held) {
return { close: useClose(ctx, held), replace: useReplace(ctx, held) }
}
/**
* A library creation that succeeded: its entry becomes the reference's own, then it
* closes, and the library says it. A draft creation never comes here (it writes nothing).
*/
function useCreated(ctx: LayerContext, replace: ReferenceMoves['replace']) {
const { dispatch, mark } = ctx
const [added, setAdded] = useState<AddedReference | null>(null)
const created = useCallback(
(id: string) => {
replace(id)
setAdded((last) => ({ id, serial: (last?.serial ?? 0) + 1 }))
// Precondition: the caller is a discrete event (the form's submit). React then
// renders the replace and runs the history effect before this microtask, so the
// entry is the reference's own before the close goes back over it and a Forward
// never reopens a creation. Called from anywhere else, the replace and the close
// would merge into one view change (a Back, and the entry keeps its creation).
// The microtask also keeps `mark()` from overwriting the replace hint early.
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(ctx: LayerContext, trace: MoveTrace) {
const { dispatch, announce, mark } = ctx
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,
view: NavigationState['reference'],
): ReferenceMoves {
const held = useRef<Held>({ opener: null, cite: null, initial: null }).current
const creating = view !== null && 'create' in view
// A Back that removes the creation dialog leaves no citing form to answer.
useEffect(() => {
if (!creating) forget(held)
}, [creating, held])
const drafting = useCallback(
(): Drafting | null =>
held.cite ? { initial: held.initial, cite: held.cite } : null,
[held],
)
const opener = useCallback((): HTMLElement | null => {
const element = held.opener
return element?.isConnected && !element.closest('[hidden]') ? element : null
}, [held])
const closing = useClosing(ctx, held)
return {
...useOpening(ctx, held),
...closing,
...useCreated(ctx, closing.replace),
...useFilter(ctx, trace),
opener,
drafting,
}
}