glidepath 0.2.0__py3-none-any.whl

glidepath/gui/forms.py

@@ -0,0 +1,359 @@
+"""Facts entry widgets: thin bindings over the form specs (§4.7, 8.2).
+
+Every label, hint, and message comes from the app layer's
+:class:`~glidepath.app.FactsFormViewModel`; these widgets only render
+fields, collect raw text back, and forward it to the submit callback.
+"""
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QDate, Qt
+from PySide6.QtWidgets import (
+    QCalendarWidget,
+    QComboBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QScrollArea,
+    QStyle,
+    QVBoxLayout,
+    QWidget,
+)
+
+from glidepath.app import (
+    DATE_PICKER_TOOLTIP,
+    ENTITY_ID_KEY,
+    FactsFormData,
+    FactsFormViewModel,
+    FieldKind,
+    PlanEntityIds,
+    SectionSpec,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+    from PySide6.QtGui import QWheelEvent
+
+
+class ScrollSafeComboBox(QComboBox):
+    """A combo box that scroll gestures pass over instead of spinning.
+
+    Inside a scrolling form, a stock ``QComboBox`` under the pointer
+    swallows wheel events and changes its value — so scrolling the
+    page silently edits the plan. This variant only reacts to the
+    wheel once the user has clicked into it; otherwise the event
+    propagates to the surrounding scroll area.
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Take focus by click or tab only, never by wheel-over."""
+        super().__init__(parent)
+        self.setFocusPolicy(Qt.FocusPolicy.StrongFocus)
+
+    def wheelEvent(self, event: QWheelEvent) -> None:  # noqa: N802
+        """Spin the value only when focused; else let the page scroll."""
+        if self.hasFocus():
+            super().wheelEvent(event)
+        else:
+            event.ignore()
+
+
+class DateEntry(QLineEdit):
+    """An ISO date field: typed text first, a calendar popup as assist.
+
+    A plain line edit (so blank stays honestly blank — the app layer's
+    blank-means-today/none semantics survive, `FieldKind.DATE`) with a
+    trailing action that pops a calendar; picking a day writes it back
+    as ``YYYY-MM-DD`` text, exactly as if typed.
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Build the line edit with its calendar action and popup."""
+        super().__init__(parent)
+        self.calendar = QCalendarWidget(self)
+        self.calendar.setWindowFlags(Qt.WindowType.Popup)
+        self.calendar.clicked.connect(self._day_picked)
+        # clicked covers the mouse; activated (Enter/Return) covers the
+        # keyboard — without it the popup can be navigated but never
+        # committed by keyboard users.
+        self.calendar.activated.connect(self._day_picked)
+        self.pick_action = self.addAction(
+            self.style().standardIcon(QStyle.StandardPixmap.SP_ArrowDown),
+            QLineEdit.ActionPosition.TrailingPosition,
+        )
+        self.pick_action.setToolTip(DATE_PICKER_TOOLTIP)
+        self.pick_action.triggered.connect(self._open_calendar)
+
+    def _open_calendar(self) -> None:
+        """Pop the calendar under the field, seeded from its text."""
+        current = QDate.fromString(self.text().strip(), Qt.DateFormat.ISODate)
+        if current.isValid():
+            self.calendar.setSelectedDate(current)
+        self.calendar.move(self.mapToGlobal(self.rect().bottomLeft()))
+        self.calendar.show()
+
+    def _day_picked(self, day: QDate) -> None:
+        """Write the picked day back as ISO text and close the popup."""
+        self.setText(day.toString(Qt.DateFormat.ISODate))
+        self.calendar.hide()
+
+
+class SectionForm(QGroupBox):
+    """One titled group of fields rendered from a :class:`SectionSpec`."""
+
+    def __init__(self, spec: SectionSpec, parent: QWidget | None = None) -> None:
+        """Render the section's fields as labelled editors."""
+        super().__init__(spec.title, parent)
+        self._editors: dict[str, QLineEdit | QComboBox] = {}
+        layout = QFormLayout(self)
+        if spec.description:
+            description = QLabel(spec.description, self)
+            description.setWordWrap(True)
+            layout.addRow(description)
+        for field in spec.fields:
+            if field.kind is FieldKind.CHOICE:
+                combo = ScrollSafeComboBox(self)
+                for option in field.choices:
+                    combo.addItem(option.label, option.value)
+                self._editors[field.key] = combo
+                layout.addRow(field.label, combo)
+            else:
+                edit = (
+                    DateEntry(self) if field.kind is FieldKind.DATE else QLineEdit(self)
+                )
+                edit.setPlaceholderText(field.hint)
+                self._editors[field.key] = edit
+                layout.addRow(field.label, edit)
+
+    def editor(self, key: str) -> QLineEdit | QComboBox:
+        """The editor widget for ``key`` (tests and shells drive it)."""
+        return self._editors[key]
+
+    def set_value(self, key: str, value: str) -> None:
+        """Set one field's raw value programmatically."""
+        editor = self._editors[key]
+        if isinstance(editor, QComboBox):
+            editor.setCurrentIndex(editor.findData(value))
+        else:
+            editor.setText(value)
+
+    def values(self) -> dict[str, str]:
+        """The section's raw text, keyed exactly like its spec."""
+        collected: dict[str, str] = {}
+        for key, editor in self._editors.items():
+            if isinstance(editor, QComboBox):
+                collected[key] = str(editor.currentData())
+            else:
+                collected[key] = editor.text()
+        return collected
+
+    def set_values(self, values: Mapping[str, str]) -> None:
+        """Set the given fields; keys absent from ``values`` are untouched."""
+        for key, value in values.items():
+            self.set_value(key, value)
+
+    def clear(self) -> None:
+        """Blank every text field and reset every choice to its first option."""
+        for editor in self._editors.values():
+            if isinstance(editor, QComboBox):
+                editor.setCurrentIndex(0)
+            else:
+                editor.setText("")
+
+
+class RepeatableSection(QWidget):
+    """A list of :class:`SectionForm` instances with add/remove controls.
+
+    Each instance carries its entity id opaquely (blank for a row the
+    user added), so deleting or reordering rows keeps every surviving
+    entity's identity — the id travels with its row, never with its
+    position (§4.3).
+    """
+
+    def __init__(self, spec: SectionSpec, parent: QWidget | None = None) -> None:
+        """Render the empty list with its add button."""
+        super().__init__(parent)
+        self._spec = spec
+        self._entries: list[QWidget] = []
+        self._forms: list[SectionForm] = []
+        self._entity_ids: list[str] = []
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        self._list_layout = QVBoxLayout()
+        layout.addLayout(self._list_layout)
+        self.add_button = QPushButton(spec.add_label, self)
+        self.add_button.clicked.connect(self.add_entry)
+        layout.addWidget(self.add_button)
+
+    def add_entry(self, *, entity_id: str = "") -> SectionForm:
+        """Append one more section instance and return its form."""
+        container = QWidget(self)
+        container_layout = QVBoxLayout(container)
+        container_layout.setContentsMargins(0, 0, 0, 0)
+        form = SectionForm(self._spec, container)
+        remove = QPushButton(self._spec.remove_label, container)
+        remove.clicked.connect(lambda: self._remove_entry(container))
+        container_layout.addWidget(form)
+        container_layout.addWidget(remove)
+        self._list_layout.addWidget(container)
+        self._entries.append(container)
+        self._forms.append(form)
+        self._entity_ids.append(entity_id)
+        return form
+
+    def _remove_entry(self, container: QWidget) -> None:
+        """Drop one section instance — and its entity id — from the list."""
+        index = self._entries.index(container)
+        del self._entries[index]
+        del self._forms[index]
+        del self._entity_ids[index]
+        self._list_layout.removeWidget(container)
+        container.deleteLater()
+
+    @property
+    def forms(self) -> tuple[SectionForm, ...]:
+        """The live section instances, in display order."""
+        return tuple(self._forms)
+
+    def values_list(self) -> tuple[dict[str, str], ...]:
+        """Raw text for every instance, its entity id included, in order."""
+        return tuple(
+            {ENTITY_ID_KEY: entity_id, **form.values()}
+            for entity_id, form in zip(self._entity_ids, self._forms, strict=True)
+        )
+
+    def set_values_list(self, values_list: Sequence[Mapping[str, str]]) -> None:
+        """Replace every instance with one per entry of ``values_list``."""
+        self.clear()
+        for values in values_list:
+            form = self.add_entry(entity_id=values.get(ENTITY_ID_KEY, ""))
+            form.set_values(
+                {key: value for key, value in values.items() if key != ENTITY_ID_KEY}
+            )
+
+    def set_entity_ids(self, entity_ids: Sequence[str]) -> None:
+        """Re-seed every row's entity id, e.g. after a successful save."""
+        if len(entity_ids) != len(self._forms):
+            msg = "one entity id per section instance required"
+            raise ValueError(msg)
+        self._entity_ids = list(entity_ids)
+
+    def clear(self) -> None:
+        """Drop every section instance."""
+        for container in tuple(self._entries):
+            self._remove_entry(container)
+
+
+class FactsEntryPane(QWidget):
+    """The facts tab: sections, submit and clear buttons, a status line."""
+
+    def __init__(
+        self,
+        view_model: FactsFormViewModel,
+        on_submit: Callable[[FactsFormData], str],
+        on_clear: Callable[[], str],
+        parent: QWidget | None = None,
+    ) -> None:
+        """Render the form and wire the submit and clear callbacks."""
+        super().__init__(parent)
+        self._on_submit = on_submit
+        self._on_clear = on_clear
+
+        intro = QLabel(view_model.intro, self)
+        intro.setWordWrap(True)
+        self.person_form = SectionForm(view_model.person)
+        self.spending_form = SectionForm(view_model.spending)
+        self.state_pension_form = SectionForm(view_model.state_pension)
+        self.wrappers = RepeatableSection(view_model.wrapper)
+        self.db_pensions = RepeatableSection(view_model.db_pension)
+        self.annuity_purchases = RepeatableSection(view_model.annuity_purchase)
+        self.submit_button = QPushButton(view_model.submit_label, self)
+        self.submit_button.setObjectName("primaryButton")
+        self.submit_button.clicked.connect(self.submit)
+        self.clear_button = QPushButton(view_model.clear_label, self)
+        self.clear_button.clicked.connect(self.clear)
+        self.status_label = QLabel("", self)
+        self.status_label.setWordWrap(True)
+
+        content = QWidget(self)
+        content_layout = QVBoxLayout(content)
+        content_layout.addWidget(intro)
+        content_layout.addWidget(self.person_form)
+        content_layout.addWidget(self.spending_form)
+        content_layout.addWidget(self.state_pension_form)
+        content_layout.addWidget(self.wrappers)
+        content_layout.addWidget(self.db_pensions)
+        content_layout.addWidget(self.annuity_purchases)
+        content_layout.addStretch()
+
+        scroll = QScrollArea(self)
+        scroll.setWidgetResizable(True)
+        scroll.setWidget(content)
+
+        buttons = QWidget(self)
+        buttons_layout = QHBoxLayout(buttons)
+        buttons_layout.setContentsMargins(0, 0, 0, 0)
+        buttons_layout.addWidget(self.clear_button)
+        buttons_layout.addStretch()
+        buttons_layout.addWidget(self.submit_button)
+
+        layout = QVBoxLayout(self)
+        layout.addWidget(scroll)
+        layout.addWidget(self.status_label)
+        layout.addWidget(buttons)
+
+    def form_data(self) -> FactsFormData:
+        """The whole form's raw text as one submission."""
+        return FactsFormData(
+            person=self.person_form.values(),
+            spending=self.spending_form.values(),
+            state_pension=self.state_pension_form.values(),
+            wrappers=self.wrappers.values_list(),
+            db_pensions=self.db_pensions.values_list(),
+            annuity_purchases=self.annuity_purchases.values_list(),
+        )
+
+    def set_form_data(self, data: FactsFormData) -> None:
+        """Replace the whole form's raw text (e.g. the launch example)."""
+        self.person_form.clear()
+        self.person_form.set_values(data.person)
+        self.spending_form.clear()
+        self.spending_form.set_values(data.spending)
+        self.state_pension_form.clear()
+        self.state_pension_form.set_values(data.state_pension)
+        self.wrappers.set_values_list(data.wrappers)
+        self.db_pensions.set_values_list(data.db_pensions)
+        self.annuity_purchases.set_values_list(data.annuity_purchases)
+
+    def set_entity_ids(self, ids: PlanEntityIds) -> None:
+        """Seed every repeatable row's entity id from the saved plan.
+
+        Called after a successful save so rows the user typed fresh
+        adopt their minted ids — the next resubmission then edits the
+        same entities instead of minting again (§4.3).
+        """
+        self.wrappers.set_entity_ids(ids.wrappers)
+        self.db_pensions.set_entity_ids(ids.db_pensions)
+        self.annuity_purchases.set_entity_ids(ids.annuity_purchases)
+
+    def submit(self) -> None:
+        """Forward the submission and show the returned status text."""
+        self.status_label.setText(self._on_submit(self.form_data()))
+
+    def clear(self) -> None:
+        """Empty every section, then show the clear callback's status."""
+        self.set_form_data(FactsFormData())
+        self.status_label.setText(self._on_clear())
+
+
+__all__ = [
+    "DateEntry",
+    "FactsEntryPane",
+    "RepeatableSection",
+    "ScrollSafeComboBox",
+    "SectionForm",
+]

glidepath/gui/inspector.py

@@ -0,0 +1,186 @@
+"""The stated-vs-assumed widgets (§4.7, roadmap 8.3).
+
+Four read-only tables — facts, assumptions, decisions, and the
+entity-level plan structure (issue #70) — bound to the app layer's
+:class:`~glidepath.app.InspectorViewModel`. Double-clicking an
+assumption row opens the in-place override prompt (multi-line for
+table-valued rows, issue #71); the new raw text goes straight back to
+the app layer.
+"""
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import (
+    QGroupBox,
+    QHBoxLayout,
+    QInputDialog,
+    QLabel,
+    QVBoxLayout,
+    QWidget,
+)
+
+from glidepath.gui.tableview import fill_table, read_only_table
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from glidepath.app import AssumptionRow, InspectorViewModel
+
+
+class InspectorPane(QWidget):
+    """The stated-vs-assumed tab (roadmap 8.3)."""
+
+    def __init__(
+        self,
+        on_override: Callable[[str, str], str | None],
+        parent: QWidget | None = None,
+    ) -> None:
+        """Build the stacked surface and wire the override callback.
+
+        Facts and choices share the top row; every other table gets the
+        full width, so no section is squeezed into a horizontal
+        scrollbar.
+        """
+        super().__init__(parent)
+        self._on_override = on_override
+        self._view_model: InspectorViewModel | None = None
+
+        self._facts_box = QGroupBox(self)
+        self.facts_table = read_only_table(self._facts_box)
+        facts_layout = QVBoxLayout(self._facts_box)
+        facts_layout.addWidget(self.facts_table)
+
+        self._roll_forwards_box = QGroupBox(self)
+        self.roll_forwards_table = read_only_table(self._roll_forwards_box)
+        roll_forwards_layout = QVBoxLayout(self._roll_forwards_box)
+        roll_forwards_layout.addWidget(self.roll_forwards_table)
+
+        self._assumptions_box = QGroupBox(self)
+        self.assumptions_table = read_only_table(self._assumptions_box)
+        self.assumptions_table.cellDoubleClicked.connect(self._edit_assumption)
+        assumptions_layout = QVBoxLayout(self._assumptions_box)
+        assumptions_layout.addWidget(self.assumptions_table)
+
+        self._decisions_box = QGroupBox(self)
+        self.decisions_table = read_only_table(self._decisions_box)
+        decisions_layout = QVBoxLayout(self._decisions_box)
+        decisions_layout.addWidget(self.decisions_table)
+
+        self._structure_box = QGroupBox(self)
+        self.structure_table = read_only_table(self._structure_box)
+        structure_layout = QVBoxLayout(self._structure_box)
+        structure_layout.addWidget(self.structure_table)
+
+        self.summary_label = QLabel("", self)
+        self.summary_label.setWordWrap(True)
+        self.status_label = QLabel("", self)
+        self.status_label.setWordWrap(True)
+
+        stated_row = QHBoxLayout()
+        stated_row.addWidget(self._facts_box, 4)
+        stated_row.addWidget(self._decisions_box, 3)
+
+        layout = QVBoxLayout(self)
+        layout.addLayout(stated_row, 2)
+        layout.addWidget(self._roll_forwards_box, 1)
+        layout.addWidget(self._assumptions_box, 3)
+        layout.addWidget(self._structure_box, 2)
+        layout.addWidget(self.summary_label)
+        layout.addWidget(self.status_label)
+
+    def refresh(self, view_model: InspectorViewModel) -> None:
+        """Re-render every table from a fresh view model."""
+        self._view_model = view_model
+        self._facts_box.setTitle(view_model.facts_heading)
+        self._assumptions_box.setTitle(view_model.assumptions_heading)
+        self._decisions_box.setTitle(view_model.decisions_heading)
+        fill_table(
+            self.facts_table,
+            view_model.facts_columns,
+            [
+                (row.label, row.value, row.as_of, row.recorded)
+                for row in view_model.facts
+            ],
+        )
+        fill_table(
+            self.assumptions_table,
+            view_model.assumptions_columns,
+            [
+                (
+                    row.label,
+                    row.value,
+                    row.default_value,
+                    row.status,
+                    row.usage,
+                    row.source,
+                    row.recorded,
+                )
+                for row in view_model.assumptions
+            ],
+            # Joining id to description is layout, not copy — both
+            # strings come from the app layer (§4.7).
+            tooltips=[
+                f"{row.description} ({row.key})" for row in view_model.assumptions
+            ],
+        )
+        fill_table(
+            self.decisions_table,
+            view_model.decisions_columns,
+            [(row.label, row.value, row.recorded) for row in view_model.decisions],
+        )
+        self._roll_forwards_box.setTitle(view_model.roll_forwards_heading)
+        self._roll_forwards_box.setVisible(bool(view_model.roll_forwards))
+        fill_table(
+            self.roll_forwards_table,
+            view_model.roll_forwards_columns,
+            [
+                (row.label, row.stated, row.as_of, row.months, row.opening)
+                for row in view_model.roll_forwards
+            ],
+        )
+        self._structure_box.setTitle(view_model.structure_heading)
+        fill_table(
+            self.structure_table,
+            view_model.structure_columns,
+            [(row.entity, row.setting, row.value) for row in view_model.structure],
+        )
+        self.summary_label.setText(view_model.summary)
+        self.summary_label.setToolTip(view_model.summary_detail)
+
+    def assumption_row(self, row_index: int) -> AssumptionRow:
+        """The assumption row behind a table row (refresh must have run)."""
+        if self._view_model is None:
+            msg = "refresh() must run before rows can be read"
+            raise RuntimeError(msg)
+        return self._view_model.assumptions[row_index]
+
+    def _edit_assumption(self, row_index: int, _column: int) -> None:
+        """Open the in-place override prompt for a double-clicked row."""
+        if self._view_model is None:  # pragma: no cover - tables imply a model
+            return
+        row = self.assumption_row(row_index)
+        # Joining the row's label to the prompt is layout, not copy —
+        # both strings come from the app layer (§4.7).
+        if row.structured:
+            text, accepted = QInputDialog.getMultiLineText(
+                self,
+                self._view_model.override_title,
+                f"{row.label} — {self._view_model.table_override_prompt}",
+                row.edit_text,
+            )
+        else:
+            text, accepted = QInputDialog.getText(
+                self,
+                self._view_model.override_title,
+                f"{row.label} — {self._view_model.override_prompt}",
+                text=row.edit_text,
+            )
+        if not accepted:
+            return
+        error = self._on_override(row.key, text)
+        self.status_label.setText(error or "")
+
+
+__all__ = [
+    "InspectorPane",
+]

glidepath/gui/main.py

@@ -0,0 +1,51 @@
+"""Desktop entry point: first-run disclaimer, then the shell (§1, §4.7).
+
+The disclaimer must be accepted before the shell opens; declining
+exits without recording anything, so the next launch asks again.
+"""
+
+import contextlib
+import sys
+from datetime import UTC, datetime
+
+from PySide6.QtWidgets import QApplication
+
+from glidepath.app import (
+    build_shell_view_model,
+    default_state_path,
+    load_state,
+    record_disclaimer_acknowledged,
+    should_show_disclaimer,
+)
+from glidepath.gui import widgets
+from glidepath.gui.style import apply_theme
+
+
+def run(argv: list[str] | None = None) -> int:
+    """Run the desktop shell; returns the process exit code."""
+    app = QApplication.instance() or QApplication(sys.argv if argv is None else argv)
+    if isinstance(app, QApplication):
+        apply_theme(app)
+    view_model = build_shell_view_model()
+    state_path = default_state_path()
+    first_run = load_state(state_path)
+    if should_show_disclaimer(first_run):
+        if not widgets.prompt_disclaimer(view_model.disclaimer):
+            return 0
+        # The acknowledgement file only skips future prompts; an unwritable
+        # config directory must not kill the session the user just accepted
+        # (worst case the next launch asks again).
+        with contextlib.suppress(OSError):
+            record_disclaimer_acknowledged(state_path, datetime.now(tz=UTC).date())
+    window = widgets.MainWindow(view_model, settings_path=state_path)
+    # Reopen the last saved or opened plan; if it fails to load, the
+    # launch example stays on screen and the status bar explains.
+    if first_run.last_plan_path is not None:
+        window.open_plan(first_run.last_plan_path)
+    window.show()
+    return app.exec()
+
+
+def main() -> None:
+    """Console-script entry point."""
+    raise SystemExit(run())