import type { ElementKey } from '@faunosteo/core-wasm/types' import { MAX_FINDING_PATH } from '../findings/tree' import { ANNOTATION_SECTIONS, isCitable, sameView, type AnnotationSection, type EditorView, } from '../navigation' import { EDITOR_TABS, type EditorTabId } from '../tabs' /** * What one browser history entry of the editor holds (R2F-1): the view, the view below * it (the place a Back returns to), and whose editor wrote it: the sheet and the session * tag (criterion 22), a random label bound to the signed-in account, never its id. * Navigation only: never typed text, a search term or a draft. */ export interface HistoryEntry { /** Keys the scroll map: one per entry written, kept by a replace. */ id: string view: EditorView below: EditorView | null sheetId: string tag: string } /** The sheet and the session tag an entry may be restored for. */ export interface HistoryOwner { sheetId: string tag: string } /** The key of the entry inside the router's `location.state`. */ export const ENTRY_KEY = 'editorEntry' const isRecord = (value: unknown): value is Record => typeof value === 'object' && value !== null /** Longest id or key read back: a longer one is no id this editor wrote. */ const MAX_ID_LENGTH = 128 const isId = (value: unknown): value is string => typeof value === 'string' && value.length <= MAX_ID_LENGTH /** A finding path no deeper than the tree allows, each id within the cap. */ const isPath = (path: unknown): path is string[] => Array.isArray(path) && path.length <= MAX_FINDING_PATH && Array.from(path).every(isId) /** A finding or zone key as the tree builds it, or null when `raw` is no such key. */ function sanitizeKey(raw: unknown): ElementKey | null { if (!isRecord(raw)) return null if (raw.kind === 'zone' && isId(raw.id)) return { kind: 'zone', id: raw.id } const { zone_id: zoneId, path } = raw if (raw.kind !== 'finding' || !isId(zoneId) || !isPath(path)) return null return { kind: 'finding', zone_id: zoneId, path } } const CREATION_KINDS = ['zone', 'category', 'node'] /** A finding creation, a form: only read back where forms are kept. */ function sanitizeCreation(raw: unknown): EditorView['finding'] { if (!isRecord(raw) || !isRecord(raw.create)) return null const { kind, parent } = raw.create if (typeof kind !== 'string' || !CREATION_KINDS.includes(kind)) return null const key = parent === null ? null : sanitizeKey(parent) if (parent !== null && key === null) return null return { create: { kind, parent: key } } } /** The finding layer of a view: its dialog, with its citations dialog over it. */ function sanitizeFinding(raw: unknown, forms: boolean): EditorView['finding'] { if (!isRecord(raw)) return null if ('create' in raw) return forms ? sanitizeCreation(raw) : null const key = sanitizeKey(raw.key) if (!key) return null const citations = raw.citations === true && isCitable(key) return { key, citations } } /** * The reference dialog of a view: over the References tab, or over the citations dialog * (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 cited = !!finding && 'key' in finding && finding.citations if (raw.create === true) return tab === 'references' ? { create: true } : null const id = raw.edit if (!isId(id) || id === '') return null return tab === 'references' || cited ? { edit: id } : null } /** The element the References tab is filtered by: a family or a node, on that tab only. */ function sanitizeFilter(raw: unknown, tab: unknown): ElementKey | null { const key = tab === 'references' ? sanitizeKey(raw) : null return key && isCitable(key) ? key : null } /** * The annotation dialog of a view: over the drawing of Annotations only. Whether the * annotation still exists is the dialog's own gone rule. */ function sanitizeAnnotation( raw: Record, section: AnnotationSection, ): EditorView['annotation'] { const layer = raw.annotation const onDrawing = raw.tab === 'annotations' && section === 'drawing' if (!onDrawing || !isRecord(layer) || !isId(layer.id)) return null return layer.id === '' ? null : { id: layer.id } } /** * 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 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 if (!EDITOR_TABS.includes(raw.tab as EditorTabId)) return 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 const section = known ? (raw.section as AnnotationSection) : 'drawing' return { tab: raw.tab as EditorTabId, section, annotation: sanitizeAnnotation(raw, section), finding, reference, referenceFilter: sanitizeFilter(raw.referenceFilter, raw.tab), } } /** The view a reload shows for an entry: its reading layers, never a form. */ export function withoutForms(view: EditorView): EditorView { return sanitizeView(view, false) ?? view } /** * The entry's id and owner, each a string within the cap, or null. An entry of the older * shape (an account id, no tag) has no owner: it reads as foreign. */ function idsOf(raw: Record) { const { id, sheetId, tag } = raw const valid = isId(id) && isId(sheetId) && isId(tag) return valid ? { id, sheetId, tag } : null } /** The entry `state` (a `location.state`) carries, or null when it carries none. */ export function readEntry(state: unknown): HistoryEntry | null { const raw = isRecord(state) ? state[ENTRY_KEY] : null if (!isRecord(raw)) return null const view = sanitizeView(raw.view) const ids = idsOf(raw) if (!view || !ids) return null const below = raw.below === null ? null : sanitizeView(raw.below) return { ...ids, view, below } } /** An entry restores only for the sheet and the session tag that wrote it. */ export function ownedEntry( state: unknown, owner: HistoryOwner, ): HistoryEntry | null { const entry = readEntry(state) // An empty id is no owner: no tag known yet (fail closed), no sheet known. if (!owner.sheetId || !owner.tag) return null const mine = entry?.sheetId === owner.sheetId && entry.tag === owner.tag return mine ? entry : null } export const entryState = (entry: HistoryEntry) => ({ [ENTRY_KEY]: entry }) /** * Layers over the place: the annotation dialog, the finding dialog and the citations * dialog over it, the reference dialog, each count one. */ export function layerCount(view: EditorView): number { const { finding } = view const cited = finding && 'key' in finding && finding.citations const dialogs = (view.annotation ? 1 : 0) + (finding ? 1 : 0) return dialogs + (cited ? 1 : 0) + (view.reference ? 1 : 0) } /** An Annotations section other than the drawing is a step over it, like a layer. */ function isStepOver(view: EditorView): boolean { return view.tab === 'annotations' && view.section !== 'drawing' } /** True when the move took a layer away, or left a section for its drawing. */ function isRemoval(top: EditorView, view: EditorView): boolean { // Another tab is a move of its own (« Tout afficher »): it pushes. if (view.tab !== top.tab) return false if (layerCount(view) < layerCount(top)) return true const backToDrawing = view.tab === top.tab && isStepOver(top) return backToDrawing && !isStepOver(view) && layerCount(view) === 0 } /** 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 its citations). */ 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. `backTo` (« Revenir au constat ») goes back when the entry below * shows that finding. `own` (« Aller à ») is a move of its own: it pushes, even when it * leaves fewer layers on the same tab, so the place it left stays one Back away. */ export function planWrite( top: HistoryEntry, view: EditorView, replace: boolean, backTo: ElementKey | null = null, own = false, ): 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 (own) return 'push' if (isRemoval(top.view, view)) { return top.below && sameView(top.below, view) ? 'back' : 'replace' } return 'push' } /** Sliding-window budget of history writes: past it a view stays in memory. */ export function createWriteBudget(limit: number, windowMs: number) { const stamps: number[] = [] return (now: number): boolean => { while (stamps.length > 0 && now - stamps[0] >= windowMs) stamps.shift() if (stamps.length >= limit) return false stamps.push(now) return true } }