u

docs/navigationAutomat.md

@@ -0,0 +1,115 @@
+# `navigationAutomat`
+
+> **Source File**: [`src/automats/navigationAutomat.js`](file:///home/seb/src/dashfront/src/automats/navigationAutomat.js)  
+> **Registration Key**: `'navigation'` (`Automat.get('navigation')` / `window.__AUTOMATS__.get('navigation')`)
+
+---
+
+## 1. Overview & Purpose
+
+`navigationAutomat` tracks the user's most recently visited delivery document path and article SKU. When navigating across main sidebar sections (for example, switching from `/lieferung` to `/artikel` and back), it enables the navigation system to restore the user's active context instead of resetting them back to the root list page.
+
+### Core Responsibilities
+- **Context Preservation**: Remembers the exact active subpath (e.g. `/lieferung/42` or `/lieferung/neu`) and article SKU (e.g. `'SKU-8910'`).
+- **Seamless Multitasking**: Users working on a delivery who need to quickly check an article warehouse stock can navigate to `/artikel` and return to `/lieferung` without losing their spot.
+- **Session-Scoped History**: In-memory state (`persist: false`) kept during active application usage.
+
+---
+
+## 2. State Structure
+
+```ts
+interface NavigationState {
+  /** Last delivery path visited, e.g. '/lieferung/19' or '/lieferung/neu'. */
+  lastDeliveryPath: string | null;
+  /** Last article SKU visited, e.g. '10042'. */
+  lastArticleSku: string | null;
+}
+```
+
+### Initial State
+```js
+const initialState = {
+  lastDeliveryPath: null,
+  lastArticleSku: null,
+};
+```
+
+---
+
+## 3. Configuration & Options
+
+```js
+new Automat(initialState, actions, {
+  name: 'navigation',
+  persist: false,
+});
+```
+
+- **`name`**: `'navigation'`
+- **`persist`**: `false`
+
+---
+
+## 4. Actions & Methods
+
+Actions are exported both on `navigationAutomat.actions` and as standalone named functions:
+
+### `setLastDeliveryPath(path: string | null): void`
+Stores the full delivery route path (e.g. `'/lieferung/19'`, `'/lieferung/neu'`).
+
+### `setLastArticleSku(sku: string | null): void`
+Stores the SKU of the article currently being edited or viewed.
+
+### `clearNavigation(): void`
+Resets both `lastDeliveryPath` and `lastArticleSku` to `null`.
+
+---
+
+## 5. Usage Examples
+
+### A. Recording Active SKU in `ArtikelSkuPage`
+
+```jsx
+import { PureComponent } from 'react';
+import { setLastArticleSku } from '../automats/navigationAutomat';
+
+export class ArtikelSkuPage extends PureComponent {
+  componentDidMount() {
+    setLastArticleSku(this.props.sku);
+  }
+
+  componentDidUpdate(prevProps) {
+    if (prevProps.sku !== this.props.sku) {
+      setLastArticleSku(this.props.sku);
+    }
+  }
+
+  render() {
+    return <div>Artikel Detail für SKU {this.props.sku}</div>;
+  }
+}
+```
+
+### B. Dynamic Navigation Link in `src/nav.js`
+
+```js
+import navigationAutomat from './automats/navigationAutomat';
+
+export function getDeliveryNavPath() {
+  const lastPath = navigationAutomat.state.lastDeliveryPath;
+  return lastPath || '/lieferung';
+}
+
+export function getArticleNavPath() {
+  const lastSku = navigationAutomat.state.lastArticleSku;
+  return lastSku ? `/artikel/${encodeURIComponent(lastSku)}` : '/artikel';
+}
+```
+
+---
+
+## 6. Best Practices & Gotchas
+
+1. **Path Formatting**: Always pass normalized route paths to `setLastDeliveryPath` (with leading slash).
+2. **Clear on Logout**: If resetting application state on logout, call `clearNavigation()`.