device-builder/esphome_device_builder/models/preferences.py at main · ApolloAutomation/device-builder · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
"""User preferences models."""

from __future__ import annotations

from dataclasses import dataclass, field
from enum import StrEnum

from mashumaro.mixins.orjson import DataClassORJSONMixin


class DashboardView(StrEnum):
    """Dashboard device list view mode."""

    CARDS = "cards"
    TABLE = "table"


class Theme(StrEnum):
    """UI theme."""

    LIGHT = "light"
    DARK = "dark"
    SYSTEM = "system"


class SortDirection(StrEnum):
    """Table sort direction."""

    ASC = "asc"
    DESC = "desc"


class EditorLayout(StrEnum):
    """Device editor pane layout: the form, the YAML pane, or both."""

    VISUAL = "visual"
    YAML = "yaml"
    BOTH = "both"


class SecretsEditorLayout(StrEnum):
    """Secrets editor layout: the form or the YAML pane, never both."""

    VISUAL = "visual"
    YAML = "yaml"


class ExperienceLevel(StrEnum):
    """
    How much ESPHome the user knows; tailors UI weight.

    Chosen in onboarding, changeable any time via the Settings expert-mode
    toggle. ``EXPERT`` unlocks the power-user surfaces (editor diff, navigator
    and YAML search). ``None`` (a fresh install that hasn't picked) is handled
    separately; a pre-existing install migrates to ``EXPERT``.
    """

    BEGINNER = "beginner"
    EXPERT = "expert"


@dataclass
class UserPreferences(DataClassORJSONMixin):
    """Per-user UI preferences.

    Stored in .device-builder.json under the _preferences key.
    All fields have sensible defaults so a fresh install works out of the box.
    """

    # Dashboard view
    dashboard_view: DashboardView = DashboardView.CARDS
    theme: Theme = Theme.SYSTEM

    # Device editor
    navigator_visible: bool = True
    # Which editor panes the user last had open, persisted so the choice
    # survives a new browser. The secrets editor has no split view, so a
    # dedicated enum makes "never both" a type rather than a comment.
    device_editor_layout: EditorLayout = EditorLayout.BOTH
    secrets_editor_layout: SecretsEditorLayout = SecretsEditorLayout.VISUAL

    # Table view settings
    table_page_size: int = 25
    table_column_visibility: dict[str, bool] = field(default_factory=dict)
    table_sort_column: str | None = None
    table_sort_direction: SortDirection | None = None

    # Experience level chosen in onboarding (None = not yet chosen).
    # ``EXPERT`` unlocks the power-user editor and search surfaces.
    experience_level: ExperienceLevel | None = None
    # This install is only a remote build node: onboarding skips the
    # Wi-Fi step and device-creation entry points are hidden.
    remote_compute_only: bool = False

    # Highest onboarding-flow version the user has acknowledged.
    # Default 0 ⇒ never gone through onboarding; the dashboard
    # surfaces the wizard on next load. See
    # ``models/onboarding.ONBOARDING_VERSION`` for the server
    # side; bumping that constant when adding new steps re-prompts
    # users at lower versions.
    onboarding_completed_version: int = 0