Files
faunosteo/apps/app/src/editor/history/entry.ts
T
bchanot cd794f3c39 feat(editor): properties dialog over the column, transactional save
U2 Task 6 (A1, A2, A3, A9, A10, R-3, R-5, R-6, R-14, R-16).

- Dialog: `anchor` places the panel at the column's left and width,
  from its top, under a 22 % ink veil that ignores clicks; the visual
  viewport below 320 px; centred without an anchor box.
- Navigation: `annotation` layer (LAYERS, EditorView, history entry,
  leave guards, left-draft flag); Back closes, Forward reopens.
- AnnotationDialog: read body, « Modifier » form (CreationFields with
  « Couleur », missingFields, R-3 messages), one `update` on the
  current annotation by id, « Marquer comme relu », « Modifier la
  forme », « Supprimer »; read-only flip keeps the draft.
- The column always shows the overview, selected row marked; Enter on
  it, a second click or a double click, the strip's « Propriétés »
  open the dialog. « Aller à » focuses the row (R-5).
- Read-only twin: strip and read-only dialog at 1 024 px and wider,
  inline read body below. PropertiesPanel and AnnotationFields gone.
- Strip lead 256 px and a fixed status slot, so the commands fit at
  1 024 px and a status change moves nothing.
- e2e: `aside-content` exemption removed; scroll-to-top workarounds
  of editor-geometry, editor-zones and editor-journey removed.

Removed assertions mapped:
  editor-annotations-tab.test.tsx:
  - selectFromList waited for `annotation-properties` -> waits for the strip's « Propriétés » (selection without dialog, A1)
  - refused place: issues block `annotation-geometry-issues` in the panel -> the strip notice alert (present, then gone)
  - keyboard creation / C26 confirmation: `annotation-properties` after create -> strip « Propriétés » (new element selected)
  - Désélectionner from the panel -> « Désélectionner » in the strip (all 7 tests); « panel closes » -> strip has no « Propriétés »
  - undo after deselect (typed name) -> handle key series then deselect then undo
  - commits a valid typed value once without blur (name field) -> a pending handle key series committed once by the strip deselect
  - a refused typed value: the panel closes (two tests: strip deselect, tap deselect) -> removed: no field outside the dialog; the dialog's draft writes nothing before « Enregistrer » (new dialog tests)
  - not offered while a replace tracing runs: panel's Désélectionner absent -> strip offers neither « Désélectionner » nor « Propriétés » during the tracing
  - tap: isDeselected read `annotation-properties` -> strip « Propriétés » absent; link select -> strip title data-selection
  - tap: undo after tap deselect (typed name) -> handle series; typed value committed on blur -> handle series committed on blur
  - strip geometry issues: list read in the panel -> list read in the properties dialog's issues block
  - a new commit replaces the message (typed name) -> « Marquer comme relu » in the dialog
  editor-escape.test.tsx:
  - `panel()` = `annotation-properties` -> the strip's « Propriétés » or the phone twin's inline read body
  - Escape from a panel button (« Marquer comme relu ») -> from the selected row in the side column: focus on the row
  - after A then B from the panel (via « Toutes les annotations ») -> select A, select B, Escape from a button of the side column: focus on B's row
  - a text field (panel « Nom (FR) ») -> the overview « Filtrer par nom »
  - redraw via the panel's « Remplacer par un polygone » -> the strip's command
  - modal / delete dialog opened by the panel's « Supprimer » -> « Supprimer » of the properties dialog
  - read-only width: hidden `annotation-properties` -> hidden strip « Propriétés » of the kept edit body
  editor-history-buttons.test.tsx (typed text and the press, 8 tests): the annotation's committed « Nom (FR) » field of the panel -> the sheet's committed « Nom (FR) » on Général (same TextField commit-on-blur path; annotation fields are now a dialog draft)
  editor-focus-request.test.tsx: « Aller à » focuses `data-properties-heading` inside `annotation-properties` -> focuses the annotation's row, marked aria-current, no dialog (R-5)
  editor-sections.test.tsx: « Aller à » with nothing in progress focused the properties heading -> focuses the row (R-5); creation kept: no `annotation-properties` -> no strip « Propriétés »
  editor-overview.test.tsx (edit and read-only): row opens `annotation-properties`, « Toutes les annotations » returns -> row selects, stays marked aria-current, no dialog; strip « Désélectionner » returns focus to the row; filter kept across select and « Désélectionner »
  editor-citations-guards.test.tsx: LAYERS_TOP_DOWN gains 'annotation' at the bottom
  editor-keep-alive.test.tsx: `annotation-properties` visible after the round trip -> the strip's « Propriétés » visible (selection kept)
  editor-no-loss.test.tsx: ids `ro-annotation-name-fr` and `annotation-name-fr` (both panels' fields) -> the twin's inline read body (no ids), then the dialog edit form's `annotation-edit-fr`, kept through a flip to 800 px, no duplicate id; « Aller à » visible `annotation-properties` -> visible `annotation-read` (inline twin), none at 1 280
  editor-point-edit.test.tsx / editor-zone-edit.test.tsx: `select()` waited for `annotation-properties` and returned it -> waits for the strip's « Propriétés » and returns the strip (its « Désélectionner » and « Remplacer par un polygone » moved there)
  - move mode Escape: `annotation-properties` still there -> the strip's « Propriétés » back after the mode
  - « Toutes les annotations » asks first during a started move -> Enter on the selected row asks first (no dialog), and the strip offers neither « Propriétés » nor « Désélectionner » during the mode
  - Escape from the handle / slider: `annotation-properties` gone -> the strip's « Propriétés » gone
  - I-3 touch tap: `annotation-properties` gone -> the strip's « Propriétés » gone
  e2e (sandbox):
  - support/layout.ts: `aside-content` exemption removed (ShiftExemption type, the loose compare); every `swaps`/`SWAPS` argument removed (editor-annotations, editor-zones, editor-geometry)
  - support/editor.ts pickAnnotation: clicked « Toutes les annotations » first when the panel showed -> the overview is always shown: clicks the row, then scrolls back to the top (the page no longer shortens)
  - editor-annotations: `annotation-properties` visible after a creation -> strip with « Propriétés »; review toggle and « Supprimer » of the panel -> the properties dialog's; a jitter click on the selected point now opens the dialog (A1), closed by Escape before the drag; handle names exact (the marked row shares the prefix); trace close moved out of expectNoShift (creation panel until Task 7, shortcut + TODO)
  - editor-deselect: `annotation-properties` -> the strip with « Propriétés » or the twin's inline read body; Escape in a field: panel « Nom (FR) » -> overview filter; delete dialog from the panel -> from the properties dialog (Escape closes it, then the dialog); « a typed value is applied by the click that deselects » (name field, refused blank) -> a pending point-handle key series applied by the deselecting click and by « Désélectionner » (refused value: no field outside the dialog); « the selected one stays » -> a second click, double click and jitter open the dialog, Escape closes it, selection kept
  - editor-geometry: `annotation-geometry-issues` in the panel -> read in the properties dialog, then the strip notice; after the refusal the error count unchanged; scroll-to-top workaround removed
  - editor-zones: panel « Désélectionner » -> strip; scroll-to-top after pickAnnotation removed (helper does it)
  - editor-structures: panel « Supprimer » -> properties dialog « Supprimer », confirmation over it
  - editor-journey: `#annotation-name-fr` committed field + `#annotation-laterality` -> the dialog's edit form, one « Enregistrer »; scroll-to-top removed
  - editor-shell / editor-shell-journeys: « Aller à » focus on `data-properties-heading` -> the annotation's row (aria-current), no dialog (R-5)
  - editor-shell-layout: focus kind `annotation-properties` -> removed (the overview is the side)
2026-11-17 22:01:57 +01:00

257 lines
9.8 KiB
TypeScript

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<string, unknown> =>
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<string, unknown>,
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<string, unknown>) {
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
}
}