milo-cli 0.1.0__py3-none-any.whl

milo/flow.py

@@ -0,0 +1,146 @@
+"""Declarative screen state machine with >> operator."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from milo._errors import ErrorCode, FlowError
+from milo._types import Action, Quit, ReducerResult, Transition
+
+
+def _default_transition(from_name: str, to_name: str) -> Transition:
+    return Transition(from_screen=from_name, to_screen=to_name, on_action="@@NAVIGATE")
+
+
+@dataclass(frozen=True, slots=True)
+class FlowScreen:
+    """A screen in a flow with its template and reducer."""
+
+    name: str
+    template: str
+    reducer: Callable
+
+    def __rshift__(self, other: FlowScreen) -> Flow:
+        """screen_a >> screen_b creates a Flow."""
+        return Flow(
+            screens=(self, other),
+            transitions=(_default_transition(self.name, other.name),),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class FlowState:
+    """Runtime state for a flow."""
+
+    current_screen: str
+    screen_states: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Flow:
+    """Declarative multi-screen state machine."""
+
+    screens: tuple[FlowScreen, ...]
+    transitions: tuple[Transition, ...]
+
+    def __rshift__(self, other: FlowScreen) -> Flow:
+        """flow >> screen_c extends the flow."""
+        last = self.screens[-1]
+        return Flow(
+            screens=(*self.screens, other),
+            transitions=(*self.transitions, _default_transition(last.name, other.name)),
+        )
+
+    @classmethod
+    def from_screens(cls, *screens: FlowScreen) -> Flow:
+        """Create a flow from an ordered sequence of screens."""
+        if len(screens) < 2:
+            raise FlowError(ErrorCode.FLW_SCREEN, "Flow requires at least 2 screens")
+        transitions = tuple(
+            _default_transition(screens[i].name, screens[i + 1].name)
+            for i in range(len(screens) - 1)
+        )
+        return cls(screens=screens, transitions=transitions)
+
+    def with_transition(self, from_screen: str, to_screen: str, *, on: str) -> Flow:
+        """Add a custom transition."""
+        # Validate screen names
+        names = {s.name for s in self.screens}
+        if from_screen not in names:
+            raise FlowError(ErrorCode.FLW_SCREEN, f"Unknown screen: {from_screen}")
+        if to_screen not in names:
+            raise FlowError(ErrorCode.FLW_SCREEN, f"Unknown screen: {to_screen}")
+        return Flow(
+            screens=self.screens,
+            transitions=(*self.transitions, Transition(from_screen, to_screen, on)),
+        )
+
+    def build_reducer(self) -> Callable:
+        """Build a combined reducer that routes actions to the current screen's reducer."""
+        screen_map = {s.name: s for s in self.screens}
+        transition_map: dict[tuple[str, str], str] = {}
+        for t in self.transitions:
+            transition_map[(t.from_screen, t.on_action)] = t.to_screen
+
+        def flow_reducer(state: FlowState | None, action: Action) -> FlowState:
+            if state is None:
+                first = self.screens[0]
+                initial_states = {s.name: s.reducer(None, Action("@@INIT")) for s in self.screens}
+                return FlowState(
+                    current_screen=first.name,
+                    screen_states=initial_states,
+                )
+
+            current = state.current_screen
+
+            # Check for transitions
+            target = transition_map.get((current, action.type))
+            if target is None and action.type == "@@NAVIGATE" and action.payload:
+                target = action.payload if action.payload in screen_map else None
+
+            if target is not None and target in screen_map:
+                return FlowState(
+                    current_screen=target,
+                    screen_states=state.screen_states,
+                )
+
+            # Route action to current screen's reducer
+            screen = screen_map.get(current)
+            if screen is None:
+                raise FlowError(ErrorCode.FLW_SCREEN, f"Unknown screen: {current}")
+
+            result = screen.reducer(state.screen_states.get(current), action)
+
+            # Unwrap Quit/ReducerResult to propagate sagas
+            sagas = ()
+            quit_signal: Quit | None = None
+            if isinstance(result, Quit):
+                quit_signal = result
+                new_screen_state = result.state
+                sagas = result.sagas
+            elif isinstance(result, ReducerResult):
+                new_screen_state = result.state
+                sagas = result.sagas
+            else:
+                new_screen_state = result
+
+            new_states = {**state.screen_states, current: new_screen_state}
+            flow_state = FlowState(
+                current_screen=current,
+                screen_states=new_states,
+            )
+
+            if quit_signal is not None:
+                return Quit(state=flow_state, code=quit_signal.code, sagas=sagas)
+            if sagas:
+                return ReducerResult(state=flow_state, sagas=sagas)
+            return flow_state
+
+        return flow_reducer
+
+    @property
+    def template_map(self) -> dict[str, str]:
+        """Map screen names to template names."""
+        return {s.name: s.template for s in self.screens}

milo/form.py

@@ -0,0 +1,277 @@
+"""Form fields and form reducer."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any
+
+from milo._types import (
+    Action,
+    FieldSpec,
+    FieldState,
+    FieldType,
+    FormState,
+    Key,
+    SpecialKey,
+)
+from milo.input._platform import is_tty
+
+
+def _make_initial_fields(specs: tuple[FieldSpec, ...]) -> tuple[FieldState, ...]:
+    """Create initial field states from specs."""
+    fields = []
+    for i, spec in enumerate(specs):
+        default = spec.default if spec.default is not None else ""
+        if spec.field_type == FieldType.CONFIRM:
+            default = spec.default if spec.default is not None else False
+        elif spec.field_type == FieldType.SELECT:
+            default = spec.default if spec.default is not None else 0
+        fields.append(
+            FieldState(
+                value=default,
+                cursor=len(str(default)) if isinstance(default, str) else 0,
+                focused=(i == 0),
+            )
+        )
+    return tuple(fields)
+
+
+def form_reducer(state: FormState | None, action: Action) -> FormState:
+    """Reducer for form state."""
+    if state is None:
+        return FormState()
+
+    if state.submitted:
+        return state
+
+    if action.type == "@@INIT" and action.payload and isinstance(action.payload, tuple):
+        specs = action.payload
+        return FormState(
+            fields=_make_initial_fields(specs),
+            specs=specs,
+            active_index=0,
+        )
+
+    if action.type != "@@KEY":
+        return state
+
+    key: Key = action.payload
+    if not isinstance(key, Key):
+        return state
+
+    idx = state.active_index
+    if idx >= len(state.fields) or idx >= len(state.specs):
+        return state
+
+    field = state.fields[idx]
+    spec = state.specs[idx]
+
+    # Tab / Enter: move to next field or submit
+    if key.name == SpecialKey.TAB or key.name == SpecialKey.ENTER:
+        if key.name == SpecialKey.ENTER and spec.field_type != FieldType.TEXT:
+            pass  # Enter confirms select/confirm fields too
+        # Validate current field
+        if spec.validator:
+            ok, err = spec.validator(field.value)
+            if not ok:
+                new_field = replace(field, error=err)
+                fields = _replace_field(state.fields, idx, new_field)
+                return replace(state, fields=fields)
+
+        if idx < len(state.fields) - 1:
+            # Move to next field
+            fields = _replace_field(
+                state.fields,
+                idx,
+                replace(field, focused=False, error=""),
+            )
+            next_field = replace(state.fields[idx + 1], focused=True)
+            fields = _replace_field(fields, idx + 1, next_field)
+            return replace(state, fields=fields, active_index=idx + 1)
+        else:
+            # Submit
+            return replace(state, submitted=True)
+
+    # Shift+Tab: move to previous field
+    if key.name == SpecialKey.TAB and key.shift:
+        if idx > 0:
+            fields = _replace_field(state.fields, idx, replace(field, focused=False))
+            prev_field = replace(state.fields[idx - 1], focused=True)
+            fields = _replace_field(fields, idx - 1, prev_field)
+            return replace(state, fields=fields, active_index=idx - 1)
+        return state
+
+    # Field-type specific handling
+    match spec.field_type:
+        case FieldType.TEXT | FieldType.PASSWORD:
+            new_field = _handle_text_key(field, key)
+        case FieldType.SELECT:
+            new_field = _handle_select_key(field, key, spec)
+        case FieldType.CONFIRM:
+            new_field = _handle_confirm_key(field, key)
+        case _:
+            new_field = field
+
+    if new_field is not field:
+        fields = _replace_field(state.fields, idx, new_field)
+        return replace(state, fields=fields)
+
+    return state
+
+
+def _handle_text_key(field: FieldState, key: Key) -> FieldState:
+    """Handle keypress for text/password fields."""
+    value = str(field.value)
+    cursor = field.cursor
+
+    if key.name == SpecialKey.BACKSPACE:
+        if cursor > 0:
+            value = value[: cursor - 1] + value[cursor:]
+            cursor -= 1
+        else:
+            return field
+    elif key.name == SpecialKey.DELETE:
+        if cursor < len(value):
+            value = value[:cursor] + value[cursor + 1 :]
+        else:
+            return field
+    elif key.name == SpecialKey.LEFT:
+        cursor = max(0, cursor - 1)
+    elif key.name == SpecialKey.RIGHT:
+        cursor = min(len(value), cursor + 1)
+    elif key.name == SpecialKey.HOME:
+        cursor = 0
+    elif key.name == SpecialKey.END:
+        cursor = len(value)
+    elif key.char and key.char.isprintable() and not key.ctrl and not key.alt:
+        value = value[:cursor] + key.char + value[cursor:]
+        cursor += 1
+    else:
+        return field
+
+    return replace(field, value=value, cursor=cursor, error="")
+
+
+def _handle_select_key(field: FieldState, key: Key, spec: FieldSpec) -> FieldState:
+    """Handle keypress for select fields."""
+    idx = field.selected_index
+    count = len(spec.choices)
+
+    if key.name == SpecialKey.UP:
+        idx = (idx - 1) % count if count else 0
+    elif key.name == SpecialKey.DOWN:
+        idx = (idx + 1) % count if count else 0
+    else:
+        return field
+
+    return replace(field, selected_index=idx, value=spec.choices[idx] if spec.choices else "")
+
+
+def _handle_confirm_key(field: FieldState, key: Key) -> FieldState:
+    """Handle keypress for confirm fields."""
+    if key.char in ("y", "Y"):
+        return replace(field, value=True)
+    elif key.char in ("n", "N"):
+        return replace(field, value=False)
+    elif key.name in (SpecialKey.LEFT, SpecialKey.RIGHT):
+        return replace(field, value=not field.value)
+    return field
+
+
+def _replace_field(
+    fields: tuple[FieldState, ...], index: int, new: FieldState
+) -> tuple[FieldState, ...]:
+    """Return a new tuple with one field replaced."""
+    lst = list(fields)
+    lst[index] = new
+    return tuple(lst)
+
+
+def make_form_reducer(*specs: FieldSpec, navigate_on_submit: bool = False) -> Callable:
+    """Create a form reducer pre-loaded with field specs.
+
+    The returned reducer initializes with the given fields on @@INIT,
+    so you don't need to pass specs via action payload.
+
+    If navigate_on_submit=True, dispatches @@NAVIGATE when the form
+    is submitted — useful in flows where the next screen should appear
+    automatically after form completion.
+    """
+    from milo._types import Put, ReducerResult
+
+    initial = FormState(
+        fields=_make_initial_fields(specs),
+        specs=specs,
+        active_index=0,
+    )
+
+    def _navigate_saga():
+        yield Put(Action("@@NAVIGATE"))
+
+    def reducer(state: FormState | None, action: Action) -> FormState | ReducerResult:
+        if state is None:
+            return initial
+        new_state = form_reducer(state, action)
+        if navigate_on_submit and not state.submitted and new_state.submitted:
+            return ReducerResult(state=new_state, sagas=(_navigate_saga,))
+        return new_state
+
+    return reducer
+
+
+def form(
+    *specs: FieldSpec,
+    env: Any = None,
+) -> dict[str, Any]:
+    """Run an interactive form, return field values.
+
+    Falls back to input() if not a TTY.
+    """
+    if not is_tty():
+        return _form_fallback(specs)
+
+    from milo.app import App
+
+    initial = FormState(
+        fields=_make_initial_fields(specs),
+        specs=specs,
+        active_index=0,
+    )
+    # Focus the first field
+    if initial.fields:
+        fields = list(initial.fields)
+        fields[0] = replace(fields[0], focused=True)
+        initial = replace(initial, fields=tuple(fields))
+
+    app = App(
+        template="form.kida",
+        reducer=form_reducer,
+        initial_state=initial,
+        env=env,
+    )
+    final: FormState = app.run()
+    return {spec.name: field.value for spec, field in zip(specs, final.fields, strict=False)}
+
+
+def _form_fallback(specs: tuple[FieldSpec, ...] | tuple) -> dict[str, Any]:
+    """Non-TTY fallback using input()."""
+    values: dict[str, Any] = {}
+    for spec in specs:
+        match spec.field_type:
+            case FieldType.CONFIRM:
+                raw = input(f"{spec.label} (y/n): ").strip().lower()
+                values[spec.name] = raw in ("y", "yes")
+            case FieldType.SELECT:
+                print(f"{spec.label}:")
+                for i, choice in enumerate(spec.choices):
+                    print(f"  {i + 1}. {choice}")
+                raw = input("Choice: ").strip()
+                try:
+                    idx = int(raw) - 1
+                    values[spec.name] = spec.choices[idx]
+                except ValueError, IndexError:
+                    values[spec.name] = spec.choices[0] if spec.choices else ""
+            case _:
+                values[spec.name] = input(f"{spec.label}: ").strip()
+    return values