u

docs/userSettingsAutomat.md

@@ -0,0 +1,116 @@
+# `userSettingsAutomat`
+
+> **Source File**: [`src/automats/userSettingsAutomat.js`](file:///home/seb/src/dashfront/src/automats/userSettingsAutomat.js)  
+> **Registration Key**: `'userSettings'` (`Automat.get('userSettings')` / `window.__AUTOMATS__.get('userSettings')`)
+
+---
+
+## 1. Overview & Purpose
+
+`userSettingsAutomat` manages client-side user interface preferences and layout options. Unlike most other automats in Dashfront that synchronize with the backend, `userSettingsAutomat` is persisted locally using IndexedDB (`persist: true`).
+
+### Core Responsibilities
+- **Local Persistence**: Preferences are saved across browser reloads and restarts without requiring server calls or database migrations.
+- **Docking Preferences**: Remembers the user's preferred layout docking position for attachment viewers (such as the PDF receipt preview and text editor) relative to the article list.
+- **Zero Latency**: State is instantly available in local storage/IndexedDB on client startup.
+
+---
+
+## 2. State Structure
+
+```ts
+type ViewerPosition = 'top' | 'right' | 'below';
+
+interface UserSettingsState {
+  /**
+   * Preferred docking position of the attachment viewer
+   * (text editor / PDF preview) relative to the article list.
+   */
+  viewerPosition: ViewerPosition;
+}
+```
+
+### Initial State
+```js
+const initialState = {
+  viewerPosition: 'top',
+};
+```
+
+---
+
+## 3. Configuration & Options
+
+```js
+new Automat(initialState, actions, {
+  name: 'userSettings',
+  persist: true,
+});
+```
+
+- **`name`**: `'userSettings'`
+- **`persist`**: `true` — `react-automat` automatically reads and writes this state to IndexedDB.
+
+---
+
+## 4. Actions & Methods
+
+Actions are available on `userSettingsAutomat.actions` and exported as standalone functions:
+
+### `setViewerPosition(position: 'top' | 'right' | 'below'): void`
+Validates that `position` is one of `'top'`, `'right'`, or `'below'`. If valid, updates `state.viewerPosition` and automatically commits the change to IndexedDB.
+
+---
+
+## 5. Usage Examples
+
+### A. React `PureComponent` Layout Container
+
+```jsx
+import { PureComponent } from 'react';
+import userSettingsAutomat, { setViewerPosition } from '../automats/userSettingsAutomat';
+
+export class DeliveryEditorLayout extends PureComponent {
+  constructor(props) {
+    super(props);
+    this.state = {
+      viewerPosition: userSettingsAutomat.state.viewerPosition,
+    };
+  }
+
+  componentDidMount() {
+    this.unsub = userSettingsAutomat.subscribe(this, 'viewerPosition');
+  }
+
+  componentWillUnmount() {
+    this.unsub?.();
+  }
+
+  render() {
+    const { viewerPosition } = this.state;
+    const isHorizontal = viewerPosition === 'right';
+
+    return (
+      <div className={`editor-container ${viewerPosition}`}>
+        <div className="toolbar">
+          <span>Viewer Position:</span>
+          <button onClick={() => setViewerPosition('top')}>Oben</button>
+          <button onClick={() => setViewerPosition('right')}>Rechts</button>
+          <button onClick={() => setViewerPosition('below')}>Unten</button>
+        </div>
+        <div className={`layout-body ${isHorizontal ? 'row' : 'column'}`}>
+          <div className="viewer-panel">PDF / Beleg-Vorschau</div>
+          <div className="table-panel">Positionen-Tabelle</div>
+        </div>
+      </div>
+    );
+  }
+}
+```
+
+---
+
+## 6. Best Practices & Gotchas
+
+1. **Validation**: Invalid values passed to `setViewerPosition` are ignored and will not update state.
+2. **Persistence Reset**: To clear persisted settings programmatically, `react-automat` provides `userSettingsAutomat.clearPersistence()`.