# `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()`.