tui-notes 0.1.0__py3-none-any.whl

tui_notes/__init__.py

@@ -0,0 +1,3 @@
+"""tui-notes: A terminal-based post-it notes application."""
+
+__version__ = "0.1.0"

tui_notes/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point for tui-notes application."""
+
+from tui_notes.app import NotesApp
+
+
+def main() -> None:
+    """Run the tui-notes application."""
+    app = NotesApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

tui_notes/app.py

@@ -0,0 +1,457 @@
+"""Main application module for tui-notes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Grid
+from textual.events import Key
+from textual.reactive import reactive
+from textual.widgets import Footer, Header
+
+from tui_notes.constants import GRID_COLUMNS, MAX_NOTES
+from tui_notes.screens import ColorPickerScreen, ConfirmScreen, EditPostItScreen, HelpScreen
+from tui_notes.storage import load_notes, save_notes
+from tui_notes.widgets import EmptySlot, PostIt
+
+
+class NotesApp(App):
+    """A TUI application for managing post-it notes in a 3x3 grid."""
+
+    CSS_PATH = "style.tcss"
+    TITLE = "TUI Notes"
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("a", "add_note", "Add"),
+        Binding("d", "delete_note", "Delete"),
+        Binding("e", "edit_note", "Edit"),
+        Binding("enter", "edit_note", "Edit", show=False),
+        Binding("c", "change_color", "Color"),
+        Binding("m", "toggle_move", "Move"),
+        Binding("escape", "cancel_move", "Cancel", show=False),
+        Binding("ctrl+s", "save", "Save"),
+        Binding("ctrl+r", "reload", "Reload"),
+        Binding("ctrl+e", "export", "Export"),
+        Binding("question_mark", "help", "Help"),
+    ]
+
+    move_mode: reactive[bool] = reactive(False)
+    _moving_post_it: PostIt | None = None
+    _note_counter: int = 0
+
+    # ── Lifecycle ───────────────────────────────────────────────
+
+    def compose(self) -> ComposeResult:
+        """Compose the application layout with header, grid, and footer."""
+        yield Header()
+        yield Grid(
+            *[EmptySlot() for _ in range(MAX_NOTES)],
+            id="notes-grid",
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Load saved notes from disk and focus the first slot."""
+        self._load_from_disk()
+        self._focus_first()
+
+    # ── Grid helpers ────────────────────────────────────────────
+
+    def _get_grid(self) -> Grid:
+        """Return the notes grid widget.
+
+        Returns:
+            The Grid container holding all post-its and empty slots.
+        """
+        return self.query_one("#notes-grid", Grid)
+
+    def _get_post_its(self) -> list[PostIt]:
+        """Return all active post-it widgets in DOM order.
+
+        Returns:
+            List of PostIt widgets currently in the grid.
+        """
+        return list(self.query(PostIt))
+
+    def _focus_first(self) -> None:
+        """Focus the first child in the grid."""
+        grid = self._get_grid()
+        if grid.children:
+            grid.children[0].focus()
+
+    # ── Persistence ─────────────────────────────────────────────
+
+    def _save_to_disk(self) -> None:
+        """Serialize all post-its and save to the JSON file."""
+        grid = self._get_grid()
+        children = list(grid.children)
+        data: list[dict[str, Any]] = [
+            child.to_dict(grid_index=idx)
+            for idx, child in enumerate(children)
+            if isinstance(child, PostIt)
+        ]
+        try:
+            save_notes(data)
+        except OSError as exc:
+            self.notify(f"Save error: {exc}", severity="error")
+
+    def _load_from_disk(self) -> None:
+        """Load post-its from disk and place them at their saved positions."""
+        notes = load_notes()
+        if not notes:
+            return
+
+        grid = self._get_grid()
+        children = list(grid.children)
+
+        for note in notes:
+            pos = note["position"]
+            if (
+                0 <= pos < MAX_NOTES
+                and pos < len(children)
+                and isinstance(children[pos], EmptySlot)
+            ):
+                post_it = PostIt.from_dict(note)
+                grid.mount(post_it, before=children[pos])
+                children[pos].remove()
+                self._note_counter += 1
+
+    def action_save(self) -> None:
+        """Save notes to disk manually."""
+        self._save_to_disk()
+        self.notify("Notes saved!")
+
+    def action_reload(self) -> None:
+        """Reload all notes from disk, discarding unsaved changes."""
+        grid = self._get_grid()
+        for child in list(grid.children):
+            child.remove()
+        for _ in range(MAX_NOTES):
+            grid.mount(EmptySlot())
+        self._note_counter = 0
+        self._load_from_disk()
+        self.set_timer(0.1, self._focus_first)
+        self.notify("Notes reloaded!")
+
+    # ── CRUD actions ────────────────────────────────────────────
+
+    def action_add_note(self) -> None:
+        """Add a new post-it at the focused position (or next available)."""
+        post_its = self._get_post_its()
+        if len(post_its) >= MAX_NOTES:
+            self.notify("Grid is full! Remove a note first.", severity="warning")
+            return
+
+        focused = self.focused
+        grid = self._get_grid()
+        children = list(grid.children)
+
+        idx = children.index(focused) if isinstance(focused, EmptySlot) else len(post_its)
+
+        self._note_counter += 1
+        new_post_it = PostIt(idx, title=f"Note {self._note_counter}")
+
+        if isinstance(focused, EmptySlot):
+            grid.mount(new_post_it, before=focused)
+            focused.remove()
+        else:
+            empty_slots = list(self.query("EmptySlot"))
+            if empty_slots:
+                empty_slots[-1].remove()
+            grid.mount(new_post_it)
+
+        new_post_it.focus()
+        self.notify(f"Added: {new_post_it.title}")
+        self._save_to_disk()
+
+    def action_delete_note(self) -> None:
+        """Delete the focused post-it after user confirmation."""
+        focused = self.focused
+        if not isinstance(focused, PostIt):
+            self.notify("Select a note to delete.", severity="warning")
+            return
+
+        self.push_screen(
+            ConfirmScreen(f"Delete '{focused.title}'?"),
+            callback=lambda confirmed: self._do_delete(focused, confirmed),
+        )
+
+    def _do_delete(self, post_it: PostIt, confirmed: bool) -> None:
+        """Replace the confirmed post-it with an empty slot in-place.
+
+        Args:
+            post_it: The PostIt widget to remove.
+            confirmed: Whether the user confirmed the deletion.
+        """
+        if not confirmed:
+            return
+
+        title = post_it.title
+        self._note_counter -= 1
+        grid = self._get_grid()
+        empty = EmptySlot()
+        grid.mount(empty, before=post_it)
+        post_it.remove()
+        empty.focus()
+        self.notify(f"Deleted: {title}")
+        self._save_to_disk()
+
+    def action_edit_note(self) -> None:
+        """Open the edit modal for the focused post-it."""
+        focused = self.focused
+        if isinstance(focused, PostIt):
+            self.push_screen(
+                EditPostItScreen(focused.title, focused.content),
+                callback=lambda result: self._apply_edit(focused, result),
+            )
+
+    def _apply_edit(self, post_it: PostIt, result: dict[str, str] | None) -> None:
+        """Apply edits returned from the edit modal.
+
+        Args:
+            post_it: The PostIt widget being edited.
+            result: Dict with 'title' and 'content' keys, or None if cancelled.
+        """
+        if result is not None:
+            post_it.title = result["title"]
+            post_it.content = result["content"]
+            self._save_to_disk()
+
+    # ── Color ───────────────────────────────────────────────────
+
+    def action_change_color(self) -> None:
+        """Open the color picker for the focused post-it."""
+        focused = self.focused
+        if not isinstance(focused, PostIt):
+            self.notify("Select a note to change color.", severity="warning")
+            return
+        self.push_screen(
+            ColorPickerScreen(),
+            callback=lambda idx: self._apply_color(focused, idx),
+        )
+
+    def _apply_color(self, post_it: PostIt, color_idx: int | None) -> None:
+        """Apply the selected color to a post-it.
+
+        Args:
+            post_it: The PostIt widget to recolor.
+            color_idx: Selected palette index, or None if cancelled.
+        """
+        if color_idx is not None:
+            post_it.color_index = color_idx
+            self._save_to_disk()
+
+    # ── Export ──────────────────────────────────────────────────
+
+    def action_export(self) -> None:
+        """Export all post-its to a Markdown file in the user's home directory."""
+        post_its = self._get_post_its()
+        if not post_its:
+            self.notify("No notes to export.", severity="warning")
+            return
+
+        lines = ["# TUI Notes Export\n"]
+        for post_it in post_its:
+            lines.append(f"## {post_it.title}\n")
+            if post_it.content:
+                lines.append(f"{post_it.content}\n")
+            lines.append("")
+
+        export_path = Path.home() / "tui-notes-export.md"
+        try:
+            export_path.write_text("\n".join(lines), encoding="utf-8")
+            self.notify(f"Exported to {export_path}")
+        except OSError as exc:
+            self.notify(f"Export error: {exc}", severity="error")
+
+    # ── Help ────────────────────────────────────────────────────
+
+    def action_help(self) -> None:
+        """Show the help screen with all keyboard shortcuts."""
+        self.push_screen(HelpScreen())
+
+    # ── Move mode ───────────────────────────────────────────────
+
+    def watch_move_mode(self, active: bool) -> None:
+        """Update the subtitle bar when move mode toggles.
+
+        Args:
+            active: Whether move mode is now active.
+        """
+        self.sub_title = "MOVE MODE - Arrows to move, Enter/Esc to exit" if active else ""
+
+    def action_toggle_move(self) -> None:
+        """Enter or exit move mode for the focused post-it."""
+        focused = self.focused
+        if not isinstance(focused, PostIt):
+            self.notify("Select a note to move.", severity="warning")
+            return
+
+        if self.move_mode:
+            self._exit_move_mode()
+        else:
+            self._moving_post_it = focused
+            focused.add_class("moving")
+            self.move_mode = True
+
+    def action_cancel_move(self) -> None:
+        """Cancel move mode via Escape."""
+        if self.move_mode:
+            self._exit_move_mode()
+
+    def _exit_move_mode(self) -> None:
+        """Exit move mode and remove visual indicators."""
+        if self._moving_post_it:
+            self._moving_post_it.remove_class("moving")
+            self._moving_post_it.focus()
+        self._moving_post_it = None
+        self.move_mode = False
+
+    # ── Navigation ──────────────────────────────────────────────
+
+    @staticmethod
+    def _calc_target_idx(key: str, current_idx: int, total: int) -> int | None:
+        """Calculate the target grid index for an arrow-key press.
+
+        Args:
+            key: The key name ('up', 'down', 'left', 'right').
+            current_idx: Current position in the flat grid.
+            total: Total number of grid children.
+
+        Returns:
+            Target index, or None if the move is out of bounds.
+        """
+        if key == "up" and current_idx >= GRID_COLUMNS:
+            return current_idx - GRID_COLUMNS
+        if key == "down" and current_idx + GRID_COLUMNS < total:
+            return current_idx + GRID_COLUMNS
+        if key == "left" and current_idx % GRID_COLUMNS > 0:
+            return current_idx - 1
+        if (
+            key == "right"
+            and current_idx % GRID_COLUMNS < GRID_COLUMNS - 1
+            and current_idx + 1 < total
+        ):
+            return current_idx + 1
+        return None
+
+    def on_key(self, event: Key) -> None:
+        """Handle arrow keys for grid navigation and move mode.
+
+        Args:
+            event: The key event from Textual.
+        """
+        if event.key not in ("up", "down", "left", "right", "enter", "escape"):
+            return
+
+        if self.move_mode and self._moving_post_it:
+            if event.key in ("enter", "escape"):
+                self._exit_move_mode()
+                event.prevent_default()
+                return
+
+            grid = self._get_grid()
+            children = list(grid.children)
+            current_idx = children.index(self._moving_post_it)
+            target_idx = self._calc_target_idx(event.key, current_idx, len(children))
+
+            if target_idx is not None:
+                self._swap_positions(current_idx, target_idx)
+                event.prevent_default()
+            return
+
+        if event.key in ("up", "down", "left", "right"):
+            grid = self._get_grid()
+            children = list(grid.children)
+            focused = self.focused
+            if focused not in children:
+                return
+            current_idx = children.index(focused)
+            target_idx = self._calc_target_idx(event.key, current_idx, len(children))
+
+            if target_idx is not None:
+                children[target_idx].focus()
+                event.prevent_default()
+
+    # ── Swap logic ──────────────────────────────────────────────
+
+    def _swap_positions(self, idx_a: int, idx_b: int) -> None:
+        """Swap two grid positions. Supports PostIt↔PostIt and PostIt↔EmptySlot.
+
+        Args:
+            idx_a: First grid index.
+            idx_b: Second grid index.
+        """
+        grid = self._get_grid()
+        children = list(grid.children)
+
+        if idx_a >= len(children) or idx_b >= len(children):
+            return
+
+        widget_a = children[idx_a]
+        widget_b = children[idx_b]
+
+        if isinstance(widget_a, PostIt) and isinstance(widget_b, PostIt):
+            self._swap_post_its(widget_a, widget_b)
+        elif isinstance(widget_a, PostIt) and isinstance(widget_b, EmptySlot):
+            self._move_to_empty(widget_a, widget_b, idx_b, grid)
+        elif isinstance(widget_a, EmptySlot) and isinstance(widget_b, PostIt):
+            self._move_to_empty(widget_b, widget_a, idx_a, grid)
+
+        self._save_to_disk()
+
+    def _swap_post_its(self, widget_a: PostIt, widget_b: PostIt) -> None:
+        """Swap data between two PostIt widgets and update move-mode tracking.
+
+        Args:
+            widget_a: First post-it.
+            widget_b: Second post-it.
+        """
+        widget_a.title, widget_b.title = widget_b.title, widget_a.title
+        widget_a.content, widget_b.content = widget_b.content, widget_a.content
+        widget_a.color_index, widget_b.color_index = widget_b.color_index, widget_a.color_index
+
+        if self._moving_post_it is widget_a:
+            self._transfer_moving_class(widget_a, widget_b)
+        elif self._moving_post_it is widget_b:
+            self._transfer_moving_class(widget_b, widget_a)
+
+    def _move_to_empty(
+        self, post_it: PostIt, empty: EmptySlot, target_idx: int, grid: Grid
+    ) -> None:
+        """Move a PostIt to an EmptySlot position, leaving an EmptySlot behind.
+
+        Args:
+            post_it: The post-it being moved.
+            empty: The empty slot at the target position.
+            target_idx: The grid index of the target position.
+            grid: The grid container.
+        """
+        new_post = PostIt.from_dict(post_it.to_dict(grid_index=target_idx))
+        new_empty = EmptySlot()
+
+        grid.mount(new_post, before=empty)
+        empty.remove()
+        grid.mount(new_empty, before=post_it)
+        post_it.remove()
+
+        if self._moving_post_it is post_it:
+            self._moving_post_it = new_post
+        new_post.add_class("moving")
+        new_post.focus()
+
+    def _transfer_moving_class(self, from_widget: PostIt, to_widget: PostIt) -> None:
+        """Transfer the 'moving' visual class from one post-it to another.
+
+        Args:
+            from_widget: The post-it losing the moving state.
+            to_widget: The post-it gaining the moving state.
+        """
+        from_widget.remove_class("moving")
+        self._moving_post_it = to_widget
+        to_widget.add_class("moving")
+        to_widget.focus()

tui_notes/constants.py

@@ -0,0 +1,20 @@
+"""Shared constants for tui-notes."""
+
+MAX_NOTES: int = 9
+"""Maximum number of post-its in the grid."""
+
+GRID_COLUMNS: int = 3
+"""Number of columns in the grid layout."""
+
+COLORS: list[tuple[str, str]] = [
+    ("Yellow", "post-it-0"),
+    ("Green", "post-it-1"),
+    ("Blue", "post-it-2"),
+    ("Pink", "post-it-3"),
+    ("Orange", "post-it-4"),
+    ("Purple", "post-it-5"),
+]
+"""Available post-it colors as (display_name, css_class) tuples."""
+
+NUM_COLORS: int = len(COLORS)
+"""Total number of available colors."""

tui_notes/screens/__init__.py

@@ -0,0 +1,8 @@
+"""Screen components for tui-notes."""
+
+from tui_notes.screens.color_picker import ColorPickerScreen
+from tui_notes.screens.confirm import ConfirmScreen
+from tui_notes.screens.edit_post_it import EditPostItScreen
+from tui_notes.screens.help import HelpScreen
+
+__all__ = ["ColorPickerScreen", "ConfirmScreen", "EditPostItScreen", "HelpScreen"]

tui_notes/screens/color_picker.py

@@ -0,0 +1,38 @@
+"""Color picker modal screen."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal
+from textual.screen import ModalScreen
+from textual.widgets import Button, Static
+
+from tui_notes.constants import COLORS
+
+
+class ColorPickerScreen(ModalScreen[int | None]):
+    """Modal screen for selecting a post-it color from the palette."""
+
+    BINDINGS = [
+        Binding("escape", "cancel", "Cancel"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Compose the color picker layout with one button per color."""
+        with Container(id="color-modal"):
+            yield Static("Choose a color", id="color-modal-title")
+            with Horizontal(id="color-options"):
+                for i, (name, css_class) in enumerate(COLORS):
+                    yield Button(name, id=f"color-{i}", classes=f"color-btn {css_class}")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Dismiss with the selected color index."""
+        btn_id = event.button.id or ""
+        if btn_id.startswith("color-"):
+            idx = int(btn_id.split("-")[1])
+            self.dismiss(idx)
+
+    def action_cancel(self) -> None:
+        """Dismiss without selecting a color."""
+        self.dismiss(None)

tui_notes/screens/confirm.py

@@ -0,0 +1,40 @@
+"""Confirmation modal screen."""
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal
+from textual.screen import ModalScreen
+from textual.widgets import Button, Static
+
+
+class ConfirmScreen(ModalScreen[bool]):
+    """Modal screen that asks for yes/no confirmation."""
+
+    BINDINGS = [
+        Binding("escape", "cancel", "Cancel"),
+    ]
+
+    def __init__(self, message: str) -> None:
+        """Initialize with a confirmation message.
+
+        Args:
+            message: The question to display.
+        """
+        super().__init__()
+        self._message = message
+
+    def compose(self) -> ComposeResult:
+        """Compose the confirmation dialog layout."""
+        with Container(id="confirm-modal"):
+            yield Static(self._message, id="confirm-message")
+            with Horizontal(id="confirm-buttons"):
+                yield Button("Yes", variant="error", id="confirm-yes")
+                yield Button("No", variant="default", id="confirm-no")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Dismiss with True for Yes, False for No."""
+        self.dismiss(event.button.id == "confirm-yes")
+
+    def action_cancel(self) -> None:
+        """Dismiss as cancelled (False)."""
+        self.dismiss(False)

tui_notes/screens/edit_post_it.py

@@ -0,0 +1,51 @@
+"""Edit post-it modal screen."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal
+from textual.screen import ModalScreen
+from textual.widgets import Button, Input, Static, TextArea
+
+
+class EditPostItScreen(ModalScreen[dict | None]):
+    """Modal screen for editing a post-it note's title and content."""
+
+    BINDINGS = [
+        Binding("escape", "cancel", "Cancel"),
+    ]
+
+    def __init__(self, title: str, content: str) -> None:
+        """Initialize with the current note values.
+
+        Args:
+            title: Current note title.
+            content: Current note content.
+        """
+        super().__init__()
+        self._edit_title = title
+        self._edit_content = content
+
+    def compose(self) -> ComposeResult:
+        """Compose the edit modal layout."""
+        with Container(id="edit-modal"):
+            yield Static("Edit Note", id="edit-modal-title")
+            yield Input(value=self._edit_title, placeholder="Title", id="edit-title-input")
+            yield TextArea(self._edit_content, id="edit-content-input")
+            with Horizontal(id="edit-buttons"):
+                yield Button("Save", variant="primary", id="edit-save")
+                yield Button("Cancel", variant="default", id="edit-cancel")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle Save or Cancel button clicks."""
+        if event.button.id == "edit-save":
+            title = self.query_one("#edit-title-input", Input).value
+            content = self.query_one("#edit-content-input", TextArea).text
+            self.dismiss({"title": title, "content": content})
+        else:
+            self.dismiss(None)
+
+    def action_cancel(self) -> None:
+        """Dismiss the modal without saving."""
+        self.dismiss(None)

tui_notes/screens/help.py

@@ -0,0 +1,61 @@
+"""Help modal screen."""
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Container
+from textual.events import Key
+from textual.screen import ModalScreen
+from textual.widgets import Static
+
+
+class HelpScreen(ModalScreen[None]):
+    """Modal screen showing all keyboard shortcuts."""
+
+    BINDINGS = [
+        Binding("escape", "close", "Close"),
+        Binding("question_mark", "close", "Close", show=False),
+    ]
+
+    HELP_TEXT = """\
+╔══════════════════════════════════════╗
+║         TUI Notes - Help             ║
+╠══════════════════════════════════════╣
+║                                      ║
+║  Navigation                          ║
+║  ← ↑ ↓ →    Move between slots       ║
+║                                      ║
+║  Notes                               ║
+║  a          Add note at position     ║
+║  e / Enter  Edit selected note       ║
+║  d          Delete selected note     ║
+║  c          Change note color        ║
+║                                      ║
+║  Organization                        ║
+║  m          Move mode (swap notes)   ║
+║  Escape     Cancel move mode         ║
+║                                      ║
+║  File                                ║
+║  Ctrl+S     Save notes               ║
+║  Ctrl+R     Reload notes             ║
+║  Ctrl+E     Export to markdown       ║
+║                                      ║
+║  Other                               ║
+║  ?          Show this help           ║
+║  q          Quit                     ║
+║                                      ║
+╚══════════════════════════════════════╝\
+"""
+
+    def compose(self) -> ComposeResult:
+        """Compose the help screen layout."""
+        with Container(id="help-modal"):
+            yield Static(self.HELP_TEXT, id="help-text")
+            yield Static("Press Escape or ? to close", id="help-close-hint")
+
+    def action_close(self) -> None:
+        """Dismiss the help screen."""
+        self.dismiss(None)
+
+    def on_key(self, event: Key) -> None:
+        """Dismiss on any key press."""
+        self.dismiss(None)

tui_notes/storage.py

@@ -0,0 +1,104 @@
+"""Persistence layer for tui-notes. Saves/loads post-its as JSON."""
+
+import json
+import os
+import platform
+from pathlib import Path
+from typing import Any
+
+
+def _get_data_dir() -> Path:
+    """Return the platform-specific data directory for tui-notes.
+
+    Returns:
+        Path to the tui-notes configuration directory.
+    """
+    system = platform.system()
+    if system == "Windows":
+        base = Path.home() / "AppData" / "Roaming"
+    elif system == "Darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        xdg_config = os.environ.get("XDG_CONFIG_HOME")
+        base = Path(xdg_config) if xdg_config else Path.home() / ".config"
+    return base / "tui-notes"
+
+
+def _get_data_file() -> Path:
+    """Return the path to the notes JSON file.
+
+    Returns:
+        Path to notes.json inside the data directory.
+    """
+    return _get_data_dir() / "notes.json"
+
+
+def save_notes(post_its: list[dict[str, Any]]) -> None:
+    """Save post-its to JSON file using atomic write.
+
+    Writes to a temporary file first, then atomically replaces the
+    target file to prevent data corruption on failures.
+
+    Args:
+        post_its: List of dicts with keys: position, title, content, color_index.
+
+    Raises:
+        OSError: If the file cannot be written.
+    """
+    data_dir = _get_data_dir()
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    data = {"version": "1.0", "post_its": post_its}
+
+    tmp_file = _get_data_file().with_suffix(".tmp")
+    try:
+        tmp_file.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        tmp_file.replace(_get_data_file())
+    except OSError:
+        tmp_file.unlink(missing_ok=True)
+        raise
+
+
+def _validate_note(note: Any) -> dict[str, Any] | None:
+    """Validate and normalize a single note dictionary.
+
+    Args:
+        note: Raw note data from JSON.
+
+    Returns:
+        Normalized note dict, or None if invalid.
+    """
+    if not isinstance(note, dict):
+        return None
+    if "position" not in note or "title" not in note:
+        return None
+    return {
+        "position": int(note["position"]),
+        "title": str(note["title"]),
+        "content": str(note.get("content", "")),
+        "color_index": int(note.get("color_index", note["position"] % 6)),
+    }
+
+
+def load_notes() -> list[dict[str, Any]]:
+    """Load post-its from JSON file.
+
+    Returns:
+        List of validated note dicts. Empty list if file doesn't
+        exist, is corrupted, or contains no valid notes.
+    """
+    data_file = _get_data_file()
+    if not data_file.exists():
+        return []
+
+    try:
+        raw = data_file.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        if not isinstance(data, dict) or "post_its" not in data:
+            return []
+        notes = data["post_its"]
+        if not isinstance(notes, list):
+            return []
+        return [v for note in notes if (v := _validate_note(note)) is not None]
+    except (json.JSONDecodeError, OSError, ValueError):
+        return []

tui_notes/style.tcss

@@ -0,0 +1,224 @@
+/* Main application styles */
+
+Screen {
+    background: $surface;
+}
+
+#notes-grid {
+    grid-size: 3 3;
+    grid-gutter: 1;
+    padding: 1;
+    height: 1fr;
+}
+
+PostIt {
+    height: 100%;
+    width: 100%;
+    padding: 0 1;
+    border: solid #888;
+}
+
+/* Yellow */
+.post-it-0 {
+    background: #fff59d;
+    border: solid #fbc02d;
+}
+
+/* Green */
+.post-it-1 {
+    background: #a5d6a7;
+    border: solid #388e3c;
+}
+
+/* Blue */
+.post-it-2 {
+    background: #90caf9;
+    border: solid #1976d2;
+}
+
+/* Pink */
+.post-it-3 {
+    background: #f48fb1;
+    border: solid #c2185b;
+}
+
+/* Orange */
+.post-it-4 {
+    background: #ffcc80;
+    border: solid #f57c00;
+}
+
+/* Purple */
+.post-it-5 {
+    background: #ce93d8;
+    border: solid #7b1fa2;
+}
+
+.post-it-title {
+    text-style: bold;
+    color: #212121;
+    height: auto;
+    padding: 0 0 1 0;
+}
+
+.post-it-content {
+    color: #212121;
+    height: 1fr;
+}
+
+/* Focus indicator */
+PostIt:focus {
+    border: double #fff;
+}
+
+/* Moving indicator */
+PostIt.moving {
+    border: double #ff5722;
+    opacity: 0.9;
+}
+
+/* Edit Modal */
+#edit-modal {
+    width: 60;
+    height: 24;
+    background: $surface;
+    border: thick $primary;
+    padding: 1 2;
+}
+
+#edit-modal-title {
+    text-style: bold;
+    text-align: center;
+    width: 100%;
+    height: auto;
+    padding: 0 0 1 0;
+}
+
+#edit-title-input {
+    width: 100%;
+    margin: 0 0 1 0;
+}
+
+#edit-content-input {
+    width: 100%;
+    height: 1fr;
+    margin: 0 0 1 0;
+}
+
+#edit-buttons {
+    width: 100%;
+    height: auto;
+    align-horizontal: right;
+}
+
+#edit-buttons Button {
+    margin: 0 0 0 1;
+}
+
+EditPostItScreen {
+    align: center middle;
+}
+
+/* Empty slot placeholder */
+.empty-slot {
+    height: 100%;
+    width: 100%;
+    padding: 0 1;
+    border: dashed #555;
+    color: #666;
+    content-align: center middle;
+    text-style: italic;
+}
+
+.empty-slot:focus {
+    border: dashed #aaa;
+}
+
+/* Confirm Modal */
+#confirm-modal {
+    width: 50;
+    height: 10;
+    background: $surface;
+    border: thick $error;
+    padding: 1 2;
+}
+
+#confirm-message {
+    text-align: center;
+    width: 100%;
+    height: auto;
+    padding: 1 0;
+}
+
+#confirm-buttons {
+    width: 100%;
+    height: auto;
+    align-horizontal: center;
+}
+
+#confirm-buttons Button {
+    margin: 0 1;
+}
+
+ConfirmScreen {
+    align: center middle;
+}
+
+/* Help Modal */
+HelpScreen {
+    align: center middle;
+}
+
+#help-modal {
+    width: 46;
+    height: auto;
+    background: $surface;
+    border: thick $primary;
+    padding: 1 2;
+}
+
+#help-text {
+    width: 100%;
+    height: auto;
+}
+
+#help-close-hint {
+    text-align: center;
+    color: $text-muted;
+    width: 100%;
+    height: auto;
+    padding: 1 0 0 0;
+}
+
+/* Color Picker Modal */
+ColorPickerScreen {
+    align: center middle;
+}
+
+#color-modal {
+    width: 76;
+    height: auto;
+    background: $surface;
+    border: thick $primary;
+    padding: 1 2;
+}
+
+#color-modal-title {
+    text-style: bold;
+    text-align: center;
+    width: 100%;
+    height: auto;
+    padding: 0 0 1 0;
+}
+
+#color-options {
+    width: 100%;
+    height: auto;
+    align-horizontal: center;
+}
+
+.color-btn {
+    margin: 0 1;
+    min-width: 8;
+    color: #212121;
+}

tui_notes/widgets/__init__.py

@@ -0,0 +1,6 @@
+"""Widget components for tui-notes."""
+
+from tui_notes.widgets.empty_slot import EmptySlot
+from tui_notes.widgets.post_it import PostIt
+
+__all__ = ["EmptySlot", "PostIt"]

tui_notes/widgets/empty_slot.py

@@ -0,0 +1,18 @@
+"""Empty slot placeholder widget."""
+
+from typing import Any
+
+from textual.widgets import Static
+
+
+class EmptySlot(Static, can_focus=True):
+    """Placeholder widget for an empty position in the post-it grid."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize an empty slot with placeholder text.
+
+        Args:
+            **kwargs: Additional keyword arguments passed to Static.
+        """
+        super().__init__("Press 'a' to add a note", **kwargs)
+        self.add_class("empty-slot")

tui_notes/widgets/post_it.py

@@ -0,0 +1,103 @@
+"""Post-it note widget."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from textual.app import ComposeResult
+from textual.containers import Container
+from textual.reactive import reactive
+from textual.widgets import Static
+
+from tui_notes.constants import NUM_COLORS
+
+
+class PostIt(Container, can_focus=True):
+    """A single post-it note widget with reactive title, content, and color."""
+
+    title: reactive[str] = reactive("")
+    content: reactive[str] = reactive("")
+    position: reactive[int] = reactive(0)
+    color_index: reactive[int] = reactive(0)
+
+    def __init__(
+        self,
+        position: int,
+        title: str = "",
+        content: str = "",
+        color_index: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a post-it note.
+
+        Args:
+            position: Grid position index (0-8).
+            title: Note title. Defaults to 'Note {position + 1}'.
+            content: Note body text.
+            color_index: Color palette index (0-5). Defaults to position % 6.
+            **kwargs: Additional keyword arguments passed to Container.
+        """
+        super().__init__(**kwargs)
+        self.position = position
+        self.title = title or f"Note {position + 1}"
+        self.content = content
+        self.color_index = color_index if color_index is not None else position % NUM_COLORS
+        self.add_class(f"post-it-{self.color_index}")
+
+    def compose(self) -> ComposeResult:
+        """Compose the post-it layout with title and content labels."""
+        yield Static(self.title, classes="post-it-title")
+        yield Static(self.content or "( empty )", classes="post-it-content")
+
+    def watch_title(self, new_title: str) -> None:
+        """Update the title label when the reactive property changes."""
+        try:
+            self.query_one(".post-it-title", Static).update(new_title)
+        except Exception:  # noqa: BLE001 - widget may not be composed yet
+            pass
+
+    def watch_content(self, new_content: str) -> None:
+        """Update the content label when the reactive property changes."""
+        try:
+            self.query_one(".post-it-content", Static).update(new_content or "( empty )")
+        except Exception:  # noqa: BLE001 - widget may not be composed yet
+            pass
+
+    def watch_color_index(self, new_color: int) -> None:
+        """Swap CSS color class when the color index changes."""
+        for i in range(NUM_COLORS):
+            self.remove_class(f"post-it-{i}")
+        self.add_class(f"post-it-{new_color}")
+
+    def to_dict(self, grid_index: int | None = None) -> dict[str, Any]:
+        """Serialize this post-it to a dictionary for persistence.
+
+        Args:
+            grid_index: Override position with actual grid index. If None, uses self.position.
+
+        Returns:
+            Dictionary with position, title, content, and color_index keys.
+        """
+        return {
+            "position": grid_index if grid_index is not None else self.position,
+            "title": self.title,
+            "content": self.content,
+            "color_index": self.color_index,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "PostIt":
+        """Create a PostIt instance from a persistence dictionary.
+
+        Args:
+            data: Dictionary with position, title, content, and optional color_index.
+
+        Returns:
+            A new PostIt instance.
+        """
+        return cls(
+            position=data["position"],
+            title=data["title"],
+            content=data.get("content", ""),
+            color_index=data.get("color_index"),
+        )

tui_notes-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: tui-notes
+Version: 0.1.0
+Summary: A terminal-based post-it notes application with a 3x3 grid layout
+Project-URL: Homepage, https://github.com/Douglas019BR/tui-notes
+Project-URL: Repository, https://github.com/Douglas019BR/tui-notes
+Author: Douglas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: notes,post-it,terminal,textual,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: textual>=0.50.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: textual-dev>=1.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TUI Notes 📝
+
+A terminal-based post-it notes application — organize your thoughts in a 3×3 grid, right from the command line.
+
+![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+## Features
+
+- **3×3 Post-it Grid** — Up to 9 notes displayed simultaneously
+- **6 Colors** — Yellow, Green, Blue, Pink, Orange, Purple (press `c` to change)
+- **Persistent Storage** — Auto-saves to `~/.config/tui-notes/notes.json`
+- **Move Mode** — Rearrange notes freely, even to empty slots
+- **Export** — Export all notes to Markdown (`Ctrl+E`)
+- **Keyboard-driven** — Full operation without mouse
+
+## Installation
+
+```bash
+# Clone and install
+git clone https://github.com/douglas/tui-notes.git
+cd tui-notes
+pip install -e .
+
+# Or with pipx (recommended for CLI tools)
+pipx install .
+```
+
+## Usage
+
+```bash
+tui-notes
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `a` | Add note at selected position |
+| `e` / `Enter` | Edit selected note |
+| `d` | Delete selected note (with confirmation) |
+| `c` | Change note color |
+| `m` | Enter Move mode (swap/reorder) |
+| `←` `↑` `↓` `→` | Navigate between slots |
+| `Ctrl+S` | Save notes manually |
+| `Ctrl+R` | Reload notes from disk |
+| `Ctrl+E` | Export to `~/tui-notes-export.md` |
+| `?` | Show help screen |
+| `Escape` | Cancel move mode |
+| `q` | Quit |
+
+## Data Storage
+
+Notes are stored as JSON in the platform-specific config directory:
+
+| Platform | Path |
+|----------|------|
+| Linux | `~/.config/tui-notes/notes.json` |
+| macOS | `~/Library/Application Support/tui-notes/notes.json` |
+| Windows | `%APPDATA%/tui-notes/notes.json` |
+
+## Development
+
+```bash
+# Setup
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+pip install -r requirements-dev.txt
+
+# Run
+python -m tui_notes
+
+# Tests
+pytest
+
+# Linting
+black tui_notes/ tests/
+isort tui_notes/ tests/
+pylint tui_notes/
+```
+
+## Requirements
+
+- Python 3.9+
+- Terminal with color support
+
+## License
+
+MIT — see [LICENSE](LICENSE) file.

tui_notes-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+tui_notes/__init__.py,sha256=1hQttvKLgFR_tAvCTz5fj3iPhVBfj3uEPaFUmPTobyk,84
+tui_notes/__main__.py,sha256=3QV3suxWxyY1Yc_U_yoxUIIBU9xlgLWIByAQXB0tI14,219
+tui_notes/app.py,sha256=fckExxpe2yFfG6WLmXKtZ0W1RPDBVJBxNU2loB4OIWs,17001
+tui_notes/constants.py,sha256=eYUgw0xAGU7yZVMI1hE-etGWo7dNmeSk5h5VKlqEnY8,516
+tui_notes/storage.py,sha256=dQKKRJ_O-sOPmVxMQmYQ1igjGYFwBdktnKkmlqgZatU,3027
+tui_notes/style.tcss,sha256=m_O-wIiA_CN_Mk5K8VNshL26L8yBiSvLode5eMdvzt4,3128
+tui_notes/screens/__init__.py,sha256=cu87bksor5Mlam0t2cDG8pvFd6RqErAtv_WaPI3LPEY,343
+tui_notes/screens/color_picker.py,sha256=HOoBrdblN66Y307OO6rdfJTAvqR21Ife1i2hhIv4gDE,1323
+tui_notes/screens/confirm.py,sha256=Gg-SDlXQhz5If-fo2LX6pvSOJ7xBHaYf3ThAcv2zuHk,1323
+tui_notes/screens/edit_post_it.py,sha256=0nb0d8BXP0UeP2LR9WpCzUHh3inRgqjfSVMQ-sBWGMo,1879
+tui_notes/screens/help.py,sha256=q1uxQrWpR9kV_8D2ueLxu68YFE3NlgEjqSP9dMulDYo,2426
+tui_notes/widgets/__init__.py,sha256=sp6pZ1wVKqaTIPGjWMV-lsTAdfaD8lvJqUWZVD33raE,171
+tui_notes/widgets/empty_slot.py,sha256=_zrCcYh_5BQTL6_PDkW-3XVeLNFVGB03D2zBAqA3mqY,514
+tui_notes/widgets/post_it.py,sha256=Z0rT8vfizD8j3O6BLljtp7gQZ1M_bd4pqsU6tFkg1Ao,3640
+tui_notes-0.1.0.dist-info/METADATA,sha256=D7yNltJNEcIbboQhK8F-lyvAZHLJgMqi3kbJGgNU9w4,3182
+tui_notes-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tui_notes-0.1.0.dist-info/entry_points.txt,sha256=clRZAS4oLB4kpcpT_wX-KrGJ4Cs-8c7cMNlzpkyN2Yc,54
+tui_notes-0.1.0.dist-info/licenses/LICENSE,sha256=RDTcpOFpOBHhc5B8W82fNXED63zMXBRBEOq7jk7MZvg,1074
+tui_notes-0.1.0.dist-info/RECORD,,

tui_notes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tui_notes-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tui-notes = tui_notes.__main__:main

tui_notes-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douglas Sermarini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.