mdedit 0.1.0__tar.gz

mdedit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+# Triggered by pushing a version tag, e.g.:
+#   git tag v0.1.0 && git push origin v0.1.0
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(grep -m1 '__version__' src/mdedit/__init__.py | sed -E 's/.*"([^"]+)".*/\1/')
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME (version $TAG_VERSION) does not match" \
+                 "src/mdedit/__init__.py's __version__ ($PKG_VERSION)."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

mdedit-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.log
+.DS_Store

mdedit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matplo
+
+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.

mdedit-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: mdedit
+Version: 0.1.0
+Summary: A terminal Markdown viewer and editor built with Textual
+Project-URL: Homepage, https://github.com/matplo/mdedit
+Project-URL: Repository, https://github.com/matplo/mdedit
+Author-email: matplo <ploskon@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: editor,markdown,terminal,textual,tui
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Text Editors
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.7
+Requires-Dist: textual[syntax]<9,>=8.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: textual-dev; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mdedit
+
+A terminal Markdown viewer and editor, built with
+[Textual](https://github.com/Textualize/textual) and
+[Rich](https://github.com/Textualize/rich).
+
+Open a `.md` file to a fully rendered view (headings, tables, code blocks,
+lists, block quotes...) and press a single key to toggle into a
+syntax-highlighted source editor for the same file — then toggle back to see
+your changes rendered.
+
+## Install
+
+```bash
+pip install git+https://github.com/matplo/mdedit
+```
+
+## Usage
+
+```bash
+mdedit path/to/file.md   # open (or create) a file
+mdedit                   # start with a prompt to open/create a file
+```
+
+### Key bindings
+
+| Key      | Action                          |
+|----------|----------------------------------|
+| `ctrl+t` | Toggle between view and edit mode |
+| `ctrl+s` | Save                              |
+| `ctrl+r` | Reload from disk                  |
+| `ctrl+q` | Quit (prompts if unsaved changes) |
+
+> **Note:** if `ctrl+s` doesn't seem to do anything in your terminal, it may
+> be intercepted by terminal flow control (XON/XOFF). Run `stty -ixon` in
+> your shell first, or use the Save option from the command palette
+> (`ctrl+p`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+```
+
+### Releasing to PyPI
+
+Releases publish automatically via GitHub Actions using
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (no API
+token stored anywhere). To cut a release:
+
+1. Bump `__version__` in `src/mdedit/__init__.py`, commit it.
+2. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`
+3. The `Publish to PyPI` workflow builds the sdist/wheel and uploads them.
+
+## Roadmap
+
+v1 is intentionally scoped to a single-file, toggle-based view/edit
+experience. Not yet included (candidates for a future version):
+
+- Always-rendered, true WYSIWYG editing (edit directly on rendered text,
+  no separate source view)
+- Split-pane side-by-side edit + preview
+- Browser-style navigation history, bookmarks, remote/URL loading
+- Multiple open files / tabs
+
+## License
+
+MIT

mdedit-0.1.0/README.md

@@ -0,0 +1,71 @@
+# mdedit
+
+A terminal Markdown viewer and editor, built with
+[Textual](https://github.com/Textualize/textual) and
+[Rich](https://github.com/Textualize/rich).
+
+Open a `.md` file to a fully rendered view (headings, tables, code blocks,
+lists, block quotes...) and press a single key to toggle into a
+syntax-highlighted source editor for the same file — then toggle back to see
+your changes rendered.
+
+## Install
+
+```bash
+pip install git+https://github.com/matplo/mdedit
+```
+
+## Usage
+
+```bash
+mdedit path/to/file.md   # open (or create) a file
+mdedit                   # start with a prompt to open/create a file
+```
+
+### Key bindings
+
+| Key      | Action                          |
+|----------|----------------------------------|
+| `ctrl+t` | Toggle between view and edit mode |
+| `ctrl+s` | Save                              |
+| `ctrl+r` | Reload from disk                  |
+| `ctrl+q` | Quit (prompts if unsaved changes) |
+
+> **Note:** if `ctrl+s` doesn't seem to do anything in your terminal, it may
+> be intercepted by terminal flow control (XON/XOFF). Run `stty -ixon` in
+> your shell first, or use the Save option from the command palette
+> (`ctrl+p`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+```
+
+### Releasing to PyPI
+
+Releases publish automatically via GitHub Actions using
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (no API
+token stored anywhere). To cut a release:
+
+1. Bump `__version__` in `src/mdedit/__init__.py`, commit it.
+2. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`
+3. The `Publish to PyPI` workflow builds the sdist/wheel and uploads them.
+
+## Roadmap
+
+v1 is intentionally scoped to a single-file, toggle-based view/edit
+experience. Not yet included (candidates for a future version):
+
+- Always-rendered, true WYSIWYG editing (edit directly on rendered text,
+  no separate source view)
+- Split-pane side-by-side edit + preview
+- Browser-style navigation history, bookmarks, remote/URL loading
+- Multiple open files / tabs
+
+## License
+
+MIT

mdedit-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mdedit"
+dynamic = ["version"]
+description = "A terminal Markdown viewer and editor built with Textual"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "matplo", email = "ploskon@gmail.com" },
+]
+keywords = ["markdown", "tui", "textual", "editor", "terminal"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Editors",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "textual[syntax]>=8.2,<9",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "textual-dev",
+    "ruff",
+]
+
+[project.scripts]
+mdedit = "mdedit.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/matplo/mdedit"
+Repository = "https://github.com/matplo/mdedit"
+
+[tool.hatch.version]
+path = "src/mdedit/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mdedit"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

mdedit-0.1.0/src/mdedit/__init__.py

@@ -0,0 +1,3 @@
+"""mdedit — a terminal Markdown viewer and editor built with Textual."""
+
+__version__ = "0.1.0"

mdedit-0.1.0/src/mdedit/__main__.py

@@ -0,0 +1,40 @@
+"""Command-line entry point for mdedit."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from mdedit import __version__
+from mdedit.app import MDEditApp
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mdedit",
+        description="A terminal Markdown viewer and editor.",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        default=None,
+        help="Markdown file to open (created on first save if it doesn't exist yet)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"mdedit {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    file_path = Path(args.file).expanduser() if args.file else None
+    app = MDEditApp(file_path=file_path)
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

mdedit-0.1.0/src/mdedit/app.py

@@ -0,0 +1,55 @@
+"""The mdedit Textual application."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual import work
+from textual.app import App
+
+from mdedit.document import Document, DocumentError
+from mdedit.screens.editor import EditorScreen
+from mdedit.screens.quit_confirm import QuitConfirmScreen
+from mdedit.screens.welcome import WelcomeScreen
+
+
+class MDEditApp(App[None]):
+    """A terminal Markdown viewer/editor."""
+
+    TITLE = "mdedit"
+    CSS_PATH = "styles/mdedit.tcss"
+
+    def __init__(self, file_path: Path | None = None) -> None:
+        super().__init__()
+        self._initial_path = file_path
+
+    def on_mount(self) -> None:
+        if self._initial_path is not None:
+            self.open_path(self._initial_path)
+        else:
+            self.push_screen(WelcomeScreen())
+
+    def open_path(self, path: Path) -> None:
+        """Load ``path`` as a Document and switch to the editor screen."""
+        try:
+            document = Document.from_path(path)
+        except DocumentError as exc:
+            self.notify(str(exc), severity="error", timeout=6)
+            return
+        self.push_screen(EditorScreen(document))
+
+    @work
+    async def action_quit(self) -> None:
+        screen = self.screen
+        document = getattr(screen, "document", None)
+        if document is not None and document.dirty:
+            choice = await self.push_screen_wait(QuitConfirmScreen())
+            if choice == "cancel":
+                return
+            if choice == "save":
+                try:
+                    document.save()
+                except DocumentError as exc:
+                    self.notify(str(exc), severity="error", timeout=6)
+                    return
+        self.exit()

mdedit-0.1.0/src/mdedit/document.py

@@ -0,0 +1,105 @@
+"""Core document model.
+
+This module is intentionally free of any Textual (or other UI-framework)
+imports. It is the seam between the on-disk file and whichever widget is
+currently displaying it (rendered view or source editor), so that a future
+"always-rendered" WYSIWYG editing mode could be layered in later behind the
+same narrow interface (``.text`` / ``.set_text()`` / ``.dirty``) without
+rewriting the screens or widgets that consume it today.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class DocumentError(Exception):
+    """Raised when a document fails to load or save."""
+
+
+class Document:
+    """An in-memory Markdown document, optionally backed by a file on disk."""
+
+    def __init__(self, path: Path | None = None, text: str = "") -> None:
+        self.path = path
+        self._text = text
+        self._saved_text = text
+        self._dirty = False
+
+    def __repr__(self) -> str:
+        return f"Document(path={self.path!r}, dirty={self._dirty!r})"
+
+    @classmethod
+    def from_path(cls, path: Path) -> Document:
+        """Load a document from ``path``.
+
+        If ``path`` does not exist, an empty new document is returned with
+        ``path`` pre-set (matching common editor UX: the file is created on
+        first save). Genuine I/O errors (permission denied, path is a
+        directory, etc.) raise :class:`DocumentError`.
+        """
+        path = Path(path)
+        if not path.exists():
+            return cls(path=path, text="")
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise DocumentError(f"Could not read {path}: {exc}") from exc
+        return cls(path=path, text=text)
+
+    @property
+    def text(self) -> str:
+        """The current in-memory content."""
+        return self._text
+
+    def set_text(self, new_text: str) -> None:
+        """Replace the in-memory content, updating the dirty flag."""
+        self._text = new_text
+        self._dirty = self._text != self._saved_text
+
+    @property
+    def dirty(self) -> bool:
+        """Whether the in-memory content differs from what's on disk."""
+        return self._dirty
+
+    @property
+    def is_new(self) -> bool:
+        """Whether this document has no backing file yet."""
+        return self.path is None
+
+    @property
+    def display_name(self) -> str:
+        """A short, human-readable name for status/title display."""
+        return self.path.name if self.path is not None else "untitled.md"
+
+    def save(self, path: Path | None = None) -> None:
+        """Write the current content to disk.
+
+        Pass ``path`` to save-as; otherwise saves to the document's existing
+        path. Raises :class:`DocumentError` if there is no path to save to,
+        or if the write fails.
+        """
+        target = path if path is not None else self.path
+        if target is None:
+            raise DocumentError("No path to save to")
+        target = Path(target)
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(self._text, encoding="utf-8")
+        except OSError as exc:
+            raise DocumentError(f"Could not write {target}: {exc}") from exc
+        self.path = target
+        self._saved_text = self._text
+        self._dirty = False
+
+    def reload(self) -> None:
+        """Discard in-memory changes and re-read the file from disk."""
+        if self.path is None:
+            raise DocumentError("Cannot reload a document with no path")
+        try:
+            text = self.path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise DocumentError(f"Could not read {self.path}: {exc}") from exc
+        self._text = text
+        self._saved_text = text
+        self._dirty = False

mdedit-0.1.0/src/mdedit/screens/editor.py

@@ -0,0 +1,102 @@
+"""The main screen: a view/edit toggle over a single Document."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import ContentSwitcher, Footer, Header
+
+from mdedit.document import Document, DocumentError
+from mdedit.widgets.source_editor import SourceEditor
+from mdedit.widgets.status_bar import StatusBar
+from mdedit.widgets.viewer import DocumentViewer
+
+
+class EditorScreen(Screen):
+    """Displays a Document in either rendered (view) or source (edit) mode."""
+
+    BINDINGS = [
+        ("ctrl+t", "toggle_mode", "Toggle view/edit"),
+        ("ctrl+s", "save", "Save"),
+        ("ctrl+r", "reload", "Reload"),
+    ]
+
+    VIEW_ID = "viewer"
+    EDIT_ID = "editor"
+
+    DEFAULT_CSS = """
+    EditorScreen > Vertical {
+        height: 1fr;
+    }
+
+    EditorScreen ContentSwitcher {
+        height: 1fr;
+    }
+    """
+
+    def __init__(self, document: Document) -> None:
+        super().__init__()
+        self.document = document
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical():
+            with ContentSwitcher(initial=self.VIEW_ID):
+                yield DocumentViewer(id=self.VIEW_ID, show_table_of_contents=True)
+                yield SourceEditor.for_document(self.document, id=self.EDIT_ID)
+            yield StatusBar()
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        await self.query_one(DocumentViewer).load_document(self.document)
+        self._refresh_status()
+
+    @property
+    def mode(self) -> str:
+        switcher = self.query_one(ContentSwitcher)
+        return "EDIT" if switcher.current == self.EDIT_ID else "VIEW"
+
+    def _refresh_status(self) -> None:
+        self.query_one(StatusBar).update_status(self.document, self.mode)
+        self.title = self.document.display_name
+
+    async def action_toggle_mode(self) -> None:
+        switcher = self.query_one(ContentSwitcher)
+        if switcher.current == self.EDIT_ID:
+            # Leaving edit mode: sync the editor's text back into the
+            # Document before switching, so view mode always reflects the
+            # latest edits.
+            source = self.query_one(SourceEditor).text
+            self.document.set_text(source)
+            await self.query_one(DocumentViewer).load_document(self.document)
+            switcher.current = self.VIEW_ID
+        else:
+            switcher.current = self.EDIT_ID
+            self.query_one(SourceEditor).focus()
+        self._refresh_status()
+
+    def action_save(self) -> None:
+        # If currently in edit mode, make sure in-flight edits are captured
+        # before writing to disk.
+        if self.mode == "EDIT":
+            self.document.set_text(self.query_one(SourceEditor).text)
+        try:
+            self.document.save()
+        except DocumentError as exc:
+            self.notify(str(exc), severity="error")
+        else:
+            self.notify(f"Saved {self.document.display_name}")
+        self._refresh_status()
+
+    async def action_reload(self) -> None:
+        try:
+            self.document.reload()
+        except DocumentError as exc:
+            self.notify(str(exc), severity="error")
+            return
+        self.query_one(SourceEditor).text = self.document.text
+        if self.mode == "VIEW":
+            await self.query_one(DocumentViewer).load_document(self.document)
+        self.notify(f"Reloaded {self.document.display_name}")
+        self._refresh_status()

mdedit-0.1.0/src/mdedit/screens/quit_confirm.py

@@ -0,0 +1,54 @@
+"""Modal shown when quitting with unsaved changes."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button, Label
+
+
+class QuitConfirmScreen(ModalScreen[str]):
+    """Ask the user whether to save, discard, or cancel before quitting.
+
+    Dismisses with one of ``"save"``, ``"discard"``, or ``"cancel"``.
+    """
+
+    DEFAULT_CSS = """
+    QuitConfirmScreen {
+        align: center middle;
+    }
+
+    QuitConfirmScreen > Vertical {
+        width: auto;
+        height: auto;
+        border: thick $panel;
+        padding: 1 2;
+    }
+
+    QuitConfirmScreen Label {
+        width: 100%;
+        content-align: center middle;
+        padding-bottom: 1;
+    }
+
+    QuitConfirmScreen Horizontal {
+        width: auto;
+        height: auto;
+    }
+
+    QuitConfirmScreen Button {
+        margin: 0 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            yield Label("You have unsaved changes. Save before quitting?")
+            with Horizontal():
+                yield Button("Save", id="save", variant="success")
+                yield Button("Discard", id="discard", variant="error")
+                yield Button("Cancel", id="cancel")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        self.dismiss(event.button.id)

mdedit-0.1.0/src/mdedit/screens/welcome.py

@@ -0,0 +1,47 @@
+"""Shown on startup when no file was given on the command line."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Input, Static
+
+
+class WelcomeScreen(Screen):
+    """Prompt for a Markdown file path to open (or create)."""
+
+    DEFAULT_CSS = """
+    WelcomeScreen {
+        align: center middle;
+    }
+
+    WelcomeScreen > Vertical {
+        width: 60;
+        height: auto;
+        border: thick $panel;
+        padding: 1 2;
+    }
+
+    WelcomeScreen Static {
+        padding-bottom: 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical():
+            yield Static("mdedit — open or create a Markdown file")
+            yield Input(placeholder="path/to/file.md", id="path-input")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one(Input).focus()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        value = event.value.strip()
+        if not value:
+            return
+        self.app.open_path(Path(value).expanduser())

mdedit-0.1.0/src/mdedit/styles/mdedit.tcss

@@ -0,0 +1,6 @@
+/* Global styles for mdedit. Most widgets rely on Textual's defaults; this
+   file only overrides what needs project-specific tweaks. */
+
+Screen {
+    background: $surface;
+}

mdedit-0.1.0/src/mdedit/widgets/source_editor.py

@@ -0,0 +1,25 @@
+"""The editable, syntax-highlighted source view of a Document."""
+
+from __future__ import annotations
+
+from textual.widgets import TextArea
+
+from mdedit.document import Document
+
+
+class SourceEditor(TextArea):
+    """A TextArea configured for editing Markdown source."""
+
+    @classmethod
+    def for_document(cls, document: Document, id: str | None = None) -> SourceEditor:
+        """Build a SourceEditor pre-populated with ``document``'s text."""
+        editor = cls.code_editor(
+            document.text,
+            language="markdown",
+            theme="monokai",
+            soft_wrap=True,
+            tab_behavior="indent",
+            id=id,
+        )
+        editor.show_line_numbers = False
+        return editor

mdedit-0.1.0/src/mdedit/widgets/status_bar.py

@@ -0,0 +1,33 @@
+"""A small status bar: filename, dirty indicator, current mode."""
+
+from __future__ import annotations
+
+from textual.reactive import reactive
+from textual.widgets import Static
+
+from mdedit.document import Document
+
+
+class StatusBar(Static):
+    """Shows the open file's name, dirty state, and view/edit mode."""
+
+    # Deliberately NOT docked: EditorScreen's Footer already docks to the
+    # bottom of the screen, and a second bottom-docked widget in the same
+    # container overlaps it exactly rather than stacking above it. Instead
+    # StatusBar is a normal flow child placed just above the Footer, inside
+    # a wrapping Vertical (see EditorScreen).
+    DEFAULT_CSS = """
+    StatusBar {
+        height: 1;
+        background: $panel;
+        color: $text-muted;
+        padding: 0 1;
+    }
+    """
+
+    mode: reactive[str] = reactive("VIEW")
+
+    def update_status(self, document: Document, mode: str) -> None:
+        self.mode = mode
+        dirty = " •" if document.dirty else ""
+        self.update(f"{document.display_name}{dirty}  —  {mode}")

mdedit-0.1.0/src/mdedit/widgets/viewer.py

@@ -0,0 +1,15 @@
+"""The read-only rendered view of a Document."""
+
+from __future__ import annotations
+
+from textual.widgets import MarkdownViewer
+
+from mdedit.document import Document
+
+
+class DocumentViewer(MarkdownViewer):
+    """A MarkdownViewer bound to a :class:`~mdedit.document.Document`."""
+
+    async def load_document(self, document: Document) -> None:
+        """Render ``document``'s current text."""
+        await self.document.update(document.text)

mdedit-0.1.0/tests/conftest.py

@@ -0,0 +1,9 @@
+import pytest
+
+
+@pytest.fixture
+def sample_md_path(tmp_path):
+    """A temporary Markdown file with some content."""
+    path = tmp_path / "sample.md"
+    path.write_text("# Title\n\nSome **bold** text.\n", encoding="utf-8")
+    return path

mdedit-0.1.0/tests/test_app_smoke.py

@@ -0,0 +1,115 @@
+from pathlib import Path
+
+import pytest
+from textual.widgets import Footer
+
+from mdedit.app import MDEditApp
+from mdedit.screens.editor import EditorScreen
+from mdedit.screens.welcome import WelcomeScreen
+from mdedit.widgets.source_editor import SourceEditor
+from mdedit.widgets.status_bar import StatusBar
+
+
+@pytest.fixture
+def sample_file(tmp_path: Path) -> Path:
+    path = tmp_path / "sample.md"
+    path.write_text("# Hello\n\nSome **bold** text.\n", encoding="utf-8")
+    return path
+
+
+async def test_opens_directly_to_editor_screen_with_file_arg(sample_file):
+    app = MDEditApp(file_path=sample_file)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        assert isinstance(app.screen, EditorScreen)
+        assert app.screen.document.text == sample_file.read_text(encoding="utf-8")
+
+
+async def test_no_file_arg_shows_welcome_screen():
+    app = MDEditApp()
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        assert isinstance(app.screen, WelcomeScreen)
+
+
+async def test_toggle_mode_switches_between_view_and_edit(sample_file):
+    app = MDEditApp(file_path=sample_file)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        screen = app.screen
+        assert screen.mode == "VIEW"
+        await pilot.press("ctrl+t")
+        await pilot.pause()
+        assert screen.mode == "EDIT"
+        await pilot.press("ctrl+t")
+        await pilot.pause()
+        assert screen.mode == "VIEW"
+
+
+async def test_edit_and_save_writes_to_disk(sample_file):
+    app = MDEditApp(file_path=sample_file)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        screen = app.screen
+        await pilot.press("ctrl+t")
+        await pilot.pause()
+        editor = screen.query_one(SourceEditor)
+        editor.text = "# Changed\n"
+        await pilot.press("ctrl+s")
+        await pilot.pause()
+        assert not screen.document.dirty
+        assert sample_file.read_text(encoding="utf-8") == "# Changed\n"
+
+
+async def test_toggle_syncs_edits_into_document(sample_file):
+    app = MDEditApp(file_path=sample_file)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        screen = app.screen
+        await pilot.press("ctrl+t")
+        await pilot.pause()
+        editor = screen.query_one(SourceEditor)
+        editor.text = "# Edited in place\n"
+        await pilot.press("ctrl+t")  # back to view mode
+        await pilot.pause()
+        assert screen.document.text == "# Edited in place\n"
+        assert screen.document.dirty
+
+
+async def test_quit_confirm_appears_on_dirty_document(sample_file):
+    app = MDEditApp(file_path=sample_file)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        screen = app.screen
+        screen.document.set_text("# dirty\n")
+        await pilot.press("ctrl+q")
+        await pilot.pause()
+        # A modal should now be on top of the screen stack, and the app
+        # should not have exited.
+        assert app.is_running
+        assert len(app.screen_stack) >= 2
+
+
+async def test_status_bar_does_not_overlap_footer(sample_file):
+    # Regression test: StatusBar and Footer both used `dock: bottom` at one
+    # point, which made them occupy the exact same region (the status bar
+    # was silently hidden underneath the footer).
+    app = MDEditApp(file_path=sample_file)
+    async with app.run_test(size=(100, 35)) as pilot:
+        await pilot.pause()
+        status_bar = app.screen.query_one(StatusBar)
+        footer = app.screen.query_one(Footer)
+        assert status_bar.region.y != footer.region.y
+        assert not status_bar.region.overlaps(footer.region)
+
+
+async def test_welcome_screen_opens_new_file(tmp_path):
+    app = MDEditApp()
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        target = tmp_path / "new-from-welcome.md"
+        app.open_path(target)
+        await pilot.pause()
+        assert isinstance(app.screen, EditorScreen)
+        assert app.screen.document.is_new is False  # path is set
+        assert not target.exists()  # not written until save

mdedit-0.1.0/tests/test_document.py

@@ -0,0 +1,93 @@
+from pathlib import Path
+
+import pytest
+
+from mdedit.document import Document, DocumentError
+
+
+def test_from_path_loads_existing_file(sample_md_path):
+    doc = Document.from_path(sample_md_path)
+    assert doc.text == "# Title\n\nSome **bold** text.\n"
+    assert doc.path == sample_md_path
+    assert not doc.dirty
+    assert not doc.is_new
+
+
+def test_from_path_missing_file_is_new_document(tmp_path):
+    missing = tmp_path / "does-not-exist.md"
+    doc = Document.from_path(missing)
+    assert doc.text == ""
+    assert doc.path == missing
+    assert not doc.dirty
+    # path is set, so it's not "is_new" in the no-path sense, but nothing
+    # exists on disk yet until save() is called.
+    assert not missing.exists()
+
+
+def test_from_path_directory_raises(tmp_path):
+    with pytest.raises(DocumentError):
+        Document.from_path(tmp_path)
+
+
+def test_set_text_marks_dirty(sample_md_path):
+    doc = Document.from_path(sample_md_path)
+    doc.set_text(doc.text + "\nMore.\n")
+    assert doc.dirty
+
+
+def test_set_text_same_content_not_dirty(sample_md_path):
+    doc = Document.from_path(sample_md_path)
+    doc.set_text(doc.text)
+    assert not doc.dirty
+
+
+def test_save_writes_to_disk_and_clears_dirty(sample_md_path):
+    doc = Document.from_path(sample_md_path)
+    doc.set_text("# Changed\n")
+    doc.save()
+    assert not doc.dirty
+    assert sample_md_path.read_text(encoding="utf-8") == "# Changed\n"
+
+
+def test_save_new_document_creates_file(tmp_path):
+    target = tmp_path / "new.md"
+    doc = Document()
+    doc.set_text("# New\n")
+    doc.save(target)
+    assert doc.path == target
+    assert not doc.dirty
+    assert target.read_text(encoding="utf-8") == "# New\n"
+
+
+def test_save_without_path_raises():
+    doc = Document()
+    doc.set_text("content")
+    with pytest.raises(DocumentError):
+        doc.save()
+
+
+def test_reload_discards_in_memory_changes(sample_md_path):
+    doc = Document.from_path(sample_md_path)
+    doc.set_text("# Overwritten locally\n")
+    assert doc.dirty
+    doc.reload()
+    assert not doc.dirty
+    assert doc.text == "# Title\n\nSome **bold** text.\n"
+
+
+def test_reload_without_path_raises():
+    doc = Document()
+    with pytest.raises(DocumentError):
+        doc.reload()
+
+
+def test_is_new_true_without_path():
+    doc = Document()
+    assert doc.is_new
+
+
+def test_display_name():
+    doc = Document()
+    assert doc.display_name == "untitled.md"
+    doc2 = Document(path=Path("/tmp/foo.md"))
+    assert doc2.display_name == "foo.md"