From 95b1b7e4615edf0343a60a9babe15c6ae323f90a Mon Sep 17 00:00:00 2001 From: bchanot Date: Fri, 6 Nov 2026 18:25:21 +0100 Subject: [PATCH] feat(editor): navigation model for the four-tab shell --- apps/app/src/editor/navigation.ts | 156 ++++++++++++++ apps/app/tests/unit/editor-navigation.test.ts | 192 ++++++++++++++++++ 2 files changed, 348 insertions(+) create mode 100644 apps/app/src/editor/navigation.ts create mode 100644 apps/app/tests/unit/editor-navigation.test.ts diff --git a/apps/app/src/editor/navigation.ts b/apps/app/src/editor/navigation.ts new file mode 100644 index 00000000..0f53dea3 --- /dev/null +++ b/apps/app/src/editor/navigation.ts @@ -0,0 +1,156 @@ +import type { ElementKey } from '@faunosteo/core-wasm/types' +import type { EditorTabId } from './tabs' + +export const ANNOTATION_SECTIONS = [ + 'drawing', + 'views', + 'categories', + 'regions', +] as const +export type AnnotationSection = (typeof ANNOTATION_SECTIONS)[number] + +/** One encoding: a target on Annotations always names its section, null elsewhere. */ +export type EditorTarget = + | { + place: 'tab' + tab: EditorTabId + section: AnnotationSection | null + key: ElementKey | null + } + | { place: 'references'; key: ElementKey | null; citedBy: ElementKey | null } + +/** « Aller à … »: the place to show and a serial so each request is consumed once. */ +export interface FocusRequest { + target: EditorTarget + serial: number +} + +export interface NavigationState { + tab: EditorTabId + section: AnnotationSection + references: { open: boolean; citedBy: ElementKey | null } + /** Places already shown, so a body mounts on first visit and stays mounted. */ + visitedTabs: readonly EditorTabId[] + visitedSections: readonly AnnotationSection[] + referencesMounted: boolean + focus: FocusRequest | undefined + /** Last serial issued: it survives `focus_consumed`, so a serial is never reused. */ + serial: number +} + +export type NavigationAction = + | { type: 'select_tab'; tab: EditorTabId } + | { type: 'open_section'; section: AnnotationSection } + | { type: 'back_to_drawing' } + | { type: 'open_references'; citedBy: ElementKey | null } + | { type: 'close_references' } + | { type: 'go_to'; target: EditorTarget } + | { type: 'focus_consumed'; serial: number } + +const TAB_OF_KIND = { + sheet: 'general', + zone: 'findings', + finding: 'findings', +} as const + +const SECTION_OF_KIND = { + annotation: 'drawing', + view: 'views', + category: 'categories', + region: 'regions', +} as const + +/** The only place an element key meets a place. */ +export function targetOfKey(key: ElementKey): EditorTarget { + switch (key.kind) { + case 'sheet': + case 'zone': + case 'finding': + return { place: 'tab', tab: TAB_OF_KIND[key.kind], section: null, key } + case 'reference': + return { place: 'references', key, citedBy: null } + default: + return { + place: 'tab', + tab: 'annotations', + section: SECTION_OF_KIND[key.kind], + key, + } + } +} + +function withItem(list: readonly T[], item: T): readonly T[] { + return list.includes(item) ? list : [...list, item] +} + +/** Records the tab, and the section when Annotations is the tab shown. */ +function shown(state: NavigationState): NavigationState { + const visitedTabs = withItem(state.visitedTabs, state.tab) + const visitedSections = + state.tab === 'annotations' + ? withItem(state.visitedSections, state.section) + : state.visitedSections + return { ...state, visitedTabs, visitedSections } +} + +export function initialNavigation(tab: EditorTabId): NavigationState { + return shown({ + tab, + section: 'drawing', + references: { open: false, citedBy: null }, + visitedTabs: [], + visitedSections: [], + referencesMounted: false, + focus: undefined, + serial: 0, + }) +} + +function openReferences(state: NavigationState, citedBy: ElementKey | null) { + return { + ...state, + references: { open: true, citedBy }, + referencesMounted: true, + } +} + +function goTo(state: NavigationState, target: EditorTarget): NavigationState { + const serial = state.serial + 1 + const focus = { target, serial } + if (target.place === 'references') { + return { ...openReferences(state, target.citedBy), focus, serial } + } + const moved = { + ...state, + tab: target.tab, + section: target.section ?? state.section, + references: { open: false, citedBy: null }, + focus, + serial, + } + return shown(moved) +} + +export function navigationReducer( + state: NavigationState, + action: NavigationAction, +): NavigationState { + switch (action.type) { + case 'select_tab': + return shown({ ...state, tab: action.tab }) + case 'open_section': + return shown({ ...state, section: action.section }) + case 'back_to_drawing': + return shown({ ...state, section: 'drawing' }) + case 'open_references': + return openReferences(state, action.citedBy) + case 'close_references': + return { ...state, references: { open: false, citedBy: null } } + case 'go_to': + return goTo(state, action.target) + case 'focus_consumed': + return state.focus?.serial === action.serial + ? { ...state, focus: undefined } + : state + } +} diff --git a/apps/app/tests/unit/editor-navigation.test.ts b/apps/app/tests/unit/editor-navigation.test.ts new file mode 100644 index 00000000..18245182 --- /dev/null +++ b/apps/app/tests/unit/editor-navigation.test.ts @@ -0,0 +1,192 @@ +import { describe, expect, it } from 'vitest' +import type { ElementKey } from '@faunosteo/core-wasm/types' +import { + initialNavigation, + navigationReducer, + targetOfKey, + type EditorTarget, + type NavigationState, +} from '../../src/editor/navigation' + +const view: ElementKey = { kind: 'view', id: 'v1' } +const finding: ElementKey = { kind: 'finding', zone_id: 'z1', path: ['a'] } + +function run( + state: NavigationState, + ...actions: Parameters[1][] +) { + return actions.reduce(navigationReducer, state) +} + +describe('targetOfKey', () => { + const tab = (t: string, section: string | null, key: ElementKey) => ({ + place: 'tab', + tab: t, + section, + key, + }) + const cases: [ElementKey, EditorTarget][] = [ + [ + { kind: 'sheet' }, + tab('general', null, { kind: 'sheet' }) as EditorTarget, + ], + [ + { kind: 'zone', id: 'z' }, + tab('findings', null, { kind: 'zone', id: 'z' }) as EditorTarget, + ], + [finding, tab('findings', null, finding) as EditorTarget], + [ + { kind: 'annotation', id: 'a' }, + tab('annotations', 'drawing', { + kind: 'annotation', + id: 'a', + }) as EditorTarget, + ], + [view, tab('annotations', 'views', view) as EditorTarget], + [ + { kind: 'category', id: 'c' }, + tab('annotations', 'categories', { + kind: 'category', + id: 'c', + }) as EditorTarget, + ], + [ + { kind: 'region', code: 'r' }, + tab('annotations', 'regions', { + kind: 'region', + code: 'r', + }) as EditorTarget, + ], + [ + { kind: 'reference', id: 'x' }, + { + place: 'references', + key: { kind: 'reference', id: 'x' }, + citedBy: null, + }, + ], + ] + it.each(cases)('maps %j', (key, expected) => { + expect(targetOfKey(key)).toEqual(expected) + }) +}) + +describe('navigationReducer', () => { + it('starts on the given tab with the drawing section', () => { + const state = initialNavigation('annotations') + expect(state.visitedTabs).toEqual(['annotations']) + expect(state.visitedSections).toEqual(['drawing']) + expect(initialNavigation('general').visitedSections).toEqual([]) + expect(state.referencesMounted).toBe(false) + }) + + it('go_to sets the place and increments the serial', () => { + const first = run(initialNavigation('general'), { + type: 'go_to', + target: targetOfKey(view), + }) + expect(first).toMatchObject({ tab: 'annotations', section: 'views' }) + expect(first.focus).toEqual({ target: targetOfKey(view), serial: 1 }) + const again = run(first, { type: 'go_to', target: targetOfKey(finding) }) + expect(again.tab).toBe('findings') + expect(again.section).toBe('views') + expect(again.focus?.serial).toBe(2) + }) + + it('go_to a reference opens the panel over the current place', () => { + const base = run(initialNavigation('annotations'), { + type: 'open_section', + section: 'views', + }) + const state = run(base, { + type: 'go_to', + target: targetOfKey({ kind: 'reference', id: 'x' }), + }) + expect(state).toMatchObject({ + tab: 'annotations', + section: 'views', + referencesMounted: true, + }) + expect(state.references.open).toBe(true) + }) + + it('go_to a tab closes the panel', () => { + const state = run( + initialNavigation('general'), + { type: 'open_references', citedBy: view }, + { type: 'go_to', target: targetOfKey(finding) }, + ) + expect(state.references).toEqual({ open: false, citedBy: null }) + expect(state.referencesMounted).toBe(true) + }) + + it('select_tab keeps section and panel and issues no request', () => { + const state = run( + initialNavigation('annotations'), + { type: 'open_section', section: 'regions' }, + { type: 'open_references', citedBy: view }, + { type: 'select_tab', tab: 'findings' }, + ) + expect(state).toMatchObject({ + tab: 'findings', + section: 'regions', + focus: undefined, + }) + expect(state.references).toEqual({ open: true, citedBy: view }) + }) + + it('opens a section and goes back to the drawing', () => { + const state = run(initialNavigation('annotations'), { + type: 'open_section', + section: 'views', + }) + expect(state.section).toBe('views') + const back = run(state, { type: 'back_to_drawing' }) + expect(back.section).toBe('drawing') + expect(back.visitedSections).toEqual(['drawing', 'views']) + }) + + it('open and close references keep tab and section', () => { + const opened = run( + initialNavigation('annotations'), + { type: 'open_section', section: 'views' }, + { type: 'open_references', citedBy: view }, + ) + expect(opened).toMatchObject({ tab: 'annotations', section: 'views' }) + expect(opened.references).toEqual({ open: true, citedBy: view }) + const closed = run(opened, { type: 'close_references' }) + expect(closed).toMatchObject({ + tab: 'annotations', + section: 'views', + referencesMounted: true, + }) + expect(closed.references.open).toBe(false) + }) + + it('focus_consumed clears only its serial and serials are not reused', () => { + const asked = run(initialNavigation('general'), { + type: 'go_to', + target: targetOfKey(view), + }) + expect( + run(asked, { type: 'focus_consumed', serial: 9 }).focus, + ).toBeDefined() + const cleared = run(asked, { type: 'focus_consumed', serial: 1 }) + expect(cleared.focus).toBeUndefined() + const next = run(cleared, { type: 'go_to', target: targetOfKey(view) }) + expect(next.focus?.serial).toBe(2) + }) + + it('visited lists only grow and record places as they are shown', () => { + const state = run( + initialNavigation('general'), + { type: 'select_tab', tab: 'annotations' }, + { type: 'open_section', section: 'categories' }, + { type: 'select_tab', tab: 'findings' }, + { type: 'select_tab', tab: 'general' }, + { type: 'back_to_drawing' }, + ) + expect(state.visitedTabs).toEqual(['general', 'annotations', 'findings']) + expect(state.visitedSections).toEqual(['drawing', 'categories']) + }) +})