117 lines
3.5 KiB
Markdown
117 lines
3.5 KiB
Markdown
# `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()`.
|