tcoda 0.8.0__tar.gz

tcoda-0.8.0/.editorconfig

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

tcoda-0.8.0/.gitattributes

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+* text=auto eol=lf

tcoda-0.8.0/.github/workflows/build.yml

@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+name: Build
+on:
+  push:
+    branches: ["**"]
+    tags: ["v[0-9]*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  #-----------------------------------------------------------------------------
+
+  Lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      # keep aligned with [tool.ruff] in pyproject.toml
+      - name: Check formatting
+        run: uvx --from 'ruff~=0.16.0' ruff format --check .
+
+      - name: Lint
+        run: uvx --from 'ruff~=0.16.0' ruff check .
+
+      - name: Check REUSE compliance
+        run: uvx reuse lint
+
+  #-----------------------------------------------------------------------------
+
+  Test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.12"]
+        include:
+          - os: ubuntu-latest
+            python: "3.14"
+    runs-on: ${{ matrix.os }}
+    steps:
+      # full history for hatch-vcs
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Run tests
+        run: uv run --locked pytest
+
+  #-----------------------------------------------------------------------------
+
+  Build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Build project
+        run: uv build --no-sources
+
+      - name: Smoke-test wheel
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python - <<'EOF'
+          import os
+          import tcoda
+          print(tcoda.__version__)
+          if os.environ["GITHUB_REF_TYPE"] == "tag":
+              expected = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+              assert tcoda.__version__ == expected, (tcoda.__version__, expected)
+          EOF
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  #-----------------------------------------------------------------------------
+
+  Release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs:
+      - Lint
+      - Test
+      - Build
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME" dist/*
+          --repo "$GITHUB_REPOSITORY"
+          --draft
+          --verify-tag
+          --generate-notes
+
+  #-----------------------------------------------------------------------------
+
+  PyPI:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    needs:
+      - Build
+      - Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tcoda
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

tcoda-0.8.0/.gitignore

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+src/tcoda/version.py
+
+# Virtual environments
+.venv
+
+# Tooling caches
+.mypy_cache
+.pytest_cache
+.ruff_cache

tcoda-0.8.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+//
+// SPDX-License-Identifier: 0BSD
+{
+    "ignores": [
+        "LICENSE"
+    ]
+}

tcoda-0.8.0/.python-version

@@ -0,0 +1 @@
+3.12

tcoda-0.8.0/CLAUDE.md

@@ -0,0 +1,21 @@
+# tcoda
+
+**Read `docs/DESIGN.md` first.** It carries the conventions shared across every
+widget and dialog, and the reasoning behind them.
+
+## Instructions
+
+This is a Textual-based library using Python 3.12. Use the `.venv` to call
+`python`. Use `uv` for package management.
+
+The codebase is ruff-formatted, `ruff` is available globally on this system.
+
+The project is REUSE-compliant (`reuse` is available globally). New files
+start with the SPDX header that `reuse annotate` writes; files that can't
+carry a comment get covered in `REUSE.toml`. `reuse lint` must pass.
+
+## Documentation
+
+Every public widget, dialog and module has a doc under `docs/`. When changing
+public behaviour, update that doc; when adding one, add a doc and a row to the
+README table.

tcoda-0.8.0/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contribution guidelines
+
+I'm open to receiving bug reports, but I'm not really interested in anything else at this point. You can still bring forward whatever you want to say, just manage your expectations accordingly.

tcoda-0.8.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (C) 2026 by René de Hesselle
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

tcoda-0.8.0/LICENSES/0BSD.txt

@@ -0,0 +1,5 @@
+Copyright (C) 2026 by René de Hesselle
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

tcoda-0.8.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: tcoda
+Version: 0.8.0
+Summary: Textual coda: widgets, dialogs and helpers
+Author-email: René de Hesselle <dehesselle@web.de>
+License-Expression: 0BSD
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: platformdirs>=4.11.0
+Requires-Dist: textual<9,>=8.2.8
+Description-Content-Type: text/markdown
+
+# tcoda — Textual coda
+
+> _A coda is a final part that brings something to a close, completing what came before it._
+
+tcoda is a widget library to extend Textual with things I regularly use in my projects.
+
+## Installation
+
+```sh
+uv add tcoda      # or: pip install tcoda
+```
+
+## Demo
+
+`python -m tcoda` runs a demo app that uses every widget and dialog, the way
+`python -m textual` runs Textual's own. See [docs/demo.md](docs/demo.md) for
+where each component appears in it.
+
+## Widgets — `tcoda.widgets`
+
+| Widget | Description |
+| --- | --- |
+| [Header](docs/widgets/Header.md) | One-line header with clickable left, middle and right areas |
+| [Footer](docs/widgets/Footer.md) | Key bar with pinned keys, sorting, and a status corner that holds widgets |
+| [Countdown](docs/widgets/Countdown.md) | Seconds counter with a spinner for work in flight |
+| [MenuBar](docs/widgets/MenuBar.md) | Midnight-Commander style pulldown menu bar, declared inline |
+| [LogViewer](docs/widgets/LogViewer.md) | Slide-down panel showing the app's `logging` output, filterable by level and source |
+| [ChordViewer](docs/widgets/ChordViewer.md) | which-key style panel listing what can follow a pending chord |
+| [DataTable](docs/widgets/DataTable.md) | Textual's `DataTable` plus clickable sorting and per-cell tooltips |
+| [Resizable](docs/widgets/Resizable.md) | Mixin that makes a pane resizable by dragging its border |
+
+## Dialogs — `tcoda.dialogs`
+
+| Dialog | Description |
+| --- | --- |
+| [Dialog](docs/dialogs/Dialog.md) | Shared chrome for centered modal dialogs |
+| [ConfirmDialog](docs/dialogs/ConfirmDialog.md) | Generic yes/no question |
+| [AboutDialog](docs/dialogs/AboutDialog.md) | About box read from a text file, with `AboutMenuItem` |
+| [SettingsDialog](docs/dialogs/SettingsDialog.md) | Editor for every declared setting, with `SettingsMenuItem` |
+
+## Modules
+
+| Module | Description |
+| --- | --- |
+| [tcoda.chords](docs/chords.md) | VSCode-style multi-key bindings (`ctrl+k ctrl+s`) via an App mixin |
+| [tcoda.terminal_title](docs/terminal_title.md) | Sets the terminal's window title and restores it on exit, via an App mixin |
+| [tcoda.settings](docs/settings.md) | Self-registering typed settings, persisted only when overridden |
+| [tcoda.log_sink](docs/widgets/LogViewer.md#the-sink-tcodalog_sink) | In-memory `logging` handler behind `LogViewer` |
+| [tcoda.demo](docs/demo.md) | The demo app behind `python -m tcoda` |
+
+The conventions every component follows, and why, are in
+[docs/DESIGN.md](docs/DESIGN.md).
+
+## AI disclosure
+
+Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x. Generated code was tested, but not every line was reviewed in detail.
+
+## License
+
+[0BSD](LICENSES/0BSD.txt)

tcoda-0.8.0/README.md

@@ -0,0 +1,60 @@
+# tcoda — Textual coda
+
+> _A coda is a final part that brings something to a close, completing what came before it._
+
+tcoda is a widget library to extend Textual with things I regularly use in my projects.
+
+## Installation
+
+```sh
+uv add tcoda      # or: pip install tcoda
+```
+
+## Demo
+
+`python -m tcoda` runs a demo app that uses every widget and dialog, the way
+`python -m textual` runs Textual's own. See [docs/demo.md](docs/demo.md) for
+where each component appears in it.
+
+## Widgets — `tcoda.widgets`
+
+| Widget | Description |
+| --- | --- |
+| [Header](docs/widgets/Header.md) | One-line header with clickable left, middle and right areas |
+| [Footer](docs/widgets/Footer.md) | Key bar with pinned keys, sorting, and a status corner that holds widgets |
+| [Countdown](docs/widgets/Countdown.md) | Seconds counter with a spinner for work in flight |
+| [MenuBar](docs/widgets/MenuBar.md) | Midnight-Commander style pulldown menu bar, declared inline |
+| [LogViewer](docs/widgets/LogViewer.md) | Slide-down panel showing the app's `logging` output, filterable by level and source |
+| [ChordViewer](docs/widgets/ChordViewer.md) | which-key style panel listing what can follow a pending chord |
+| [DataTable](docs/widgets/DataTable.md) | Textual's `DataTable` plus clickable sorting and per-cell tooltips |
+| [Resizable](docs/widgets/Resizable.md) | Mixin that makes a pane resizable by dragging its border |
+
+## Dialogs — `tcoda.dialogs`
+
+| Dialog | Description |
+| --- | --- |
+| [Dialog](docs/dialogs/Dialog.md) | Shared chrome for centered modal dialogs |
+| [ConfirmDialog](docs/dialogs/ConfirmDialog.md) | Generic yes/no question |
+| [AboutDialog](docs/dialogs/AboutDialog.md) | About box read from a text file, with `AboutMenuItem` |
+| [SettingsDialog](docs/dialogs/SettingsDialog.md) | Editor for every declared setting, with `SettingsMenuItem` |
+
+## Modules
+
+| Module | Description |
+| --- | --- |
+| [tcoda.chords](docs/chords.md) | VSCode-style multi-key bindings (`ctrl+k ctrl+s`) via an App mixin |
+| [tcoda.terminal_title](docs/terminal_title.md) | Sets the terminal's window title and restores it on exit, via an App mixin |
+| [tcoda.settings](docs/settings.md) | Self-registering typed settings, persisted only when overridden |
+| [tcoda.log_sink](docs/widgets/LogViewer.md#the-sink-tcodalog_sink) | In-memory `logging` handler behind `LogViewer` |
+| [tcoda.demo](docs/demo.md) | The demo app behind `python -m tcoda` |
+
+The conventions every component follows, and why, are in
+[docs/DESIGN.md](docs/DESIGN.md).
+
+## AI disclosure
+
+Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x. Generated code was tested, but not every line was reviewed in detail.
+
+## License
+
+[0BSD](LICENSES/0BSD.txt)

tcoda-0.8.0/REUSE.toml

@@ -0,0 +1,14 @@
+version = 1
+
+# Files that can't carry an SPDX comment, or shouldn't: docs stay clean when
+# rendered, the about boxes are shown verbatim, uv.lock is regenerated.
+[[annotations]]
+path = [
+    "**.md",
+    "src/tcoda/**.txt",
+    "src/tcoda/py.typed",
+    "uv.lock",
+    ".python-version",
+]
+SPDX-FileCopyrightText = "2026 René de Hesselle <dehesselle@web.de>"
+SPDX-License-Identifier = "0BSD"

tcoda-0.8.0/docs/DESIGN.md

@@ -0,0 +1,112 @@
+# tcoda — design
+
+This document holds the decisions that span more than one widget, dialog or
+module. Reasoning specific to one component lives in that component's own doc,
+next to what it explains — see the tables in the [README](../README.md).
+
+## Why tcoda exists
+
+The widgets here are meant to be shared between Textual apps, so a fix is made
+once rather than in every app. Several docs open by naming the workarounds the
+widget replaces.
+
+The name is short for "Textual coda": what comes after the widgets Textual
+itself provides.
+
+## Styling is inline `DEFAULT_CSS`
+
+All styling is inline `DEFAULT_CSS` — a library cannot rely on a consumer's
+`CSS_PATH`. Textual scopes it to the declaring widget's subtree, and an app's
+own stylesheet outranks it regardless of specificity, so anything here can be
+overridden.
+
+Where a choice is purely cosmetic and apps might reasonably differ, it is
+exposed as a class attribute to override in a subclass rather than as a
+constructor argument (e.g. `SettingsDialog.INSTANCE_GLYPH`,
+`Countdown.SPINNER`). Where one consistent look across apps is the point, it
+is not configurable at all (e.g. the `DataTable` sort glyphs).
+
+## Naming: dialog, screen and overlays
+
+Modal classes are named for what they are, not for the base class they
+extend. A **`Dialog`** is a centered box that asks something and dismisses
+with a result — `AboutDialog`, `ConfirmDialog`, `SettingsDialog`, and
+whatever a consuming app adds. `MenuBarOverlay` and `MenuDropdown` are *not*
+dialogs: they are transparent, render no chrome of their own, and exist only
+to capture input while a menu is in use. **`Screen`** stays reserved for a
+host app's own screens, such as its main one.
+
+Textual has no `Dialog` of its own — its vocabulary stops at `Screen` and
+`ModalScreen` — but it does not claim the term either, and everyone who has
+met Qt, GTK or wxWidgets already knows what a dialog is.
+
+The shared chrome is [`Dialog`](dialogs/Dialog.md).
+
+## Widgets that own a key bind it on their screen
+
+A widget with a key of its own ([`MenuBar`](widgets/MenuBar.md)'s F9,
+[`LogViewer`](widgets/LogViewer.md)'s F1) installs the binding on whichever
+screen it is mounted on. Textual only consults the focus chain plus the screen
+and the app when resolving a key, so a widget that is never focused cannot own
+one.
+
+- The action is exported as a constant (`OPEN_ACTION`, `TOGGLE_ACTION`) so
+  something other than the key can reach it with `run_action(...)`, and so a
+  [`Footer`](widgets/Footer.md) pin keeps working when an app rebinds the key.
+- `key=` changes the key; `key=None` installs nothing, leaving the app to bind
+  it.
+- `show_key=False` keeps the binding out of the footer altogether, but *where*
+  it appears is never the widget's business — that is the footer's.
+
+## Keys are shown through `App.get_key_display`
+
+No widget formats a key itself. The [`Footer`](widgets/Footer.md), the
+[`ChordViewer`](widgets/ChordViewer.md), the [chord](chords.md) status text
+and a [`MenuItem`](widgets/MenuBar.md)'s shortcut all take a key in `Binding`
+syntax and ask the app how to show it. Textual's answer is caret notation:
+`^q`, `^k ^s`, lowercase `f5`, `esc`.
+
+So the style is the app's choice, made once. An app that prefers `Ctrl+Q`
+overrides `get_key_display` and every one of these follows, along with
+Textual's own footer and key panel. A widget that accepted
+pre-formatted text instead would be the one place that does not.
+
+## Hide with `display`, never with an empty render
+
+A widget that has nothing to show is hidden with `display = False`, not by
+rendering an empty string. An empty render would mean "nothing to say", which
+is not the same thing as a genuine zero, and a widget that conflates the two
+cannot express either. It also matters structurally: the
+[`Footer`](widgets/Footer.md)'s dividers follow `display`, so an empty-but-
+displayed widget leaves a stray divider behind.
+[`Countdown`](widgets/Countdown.md) renders `0` at zero for this reason.
+
+## Mixins go first and have no `__init__`
+
+Behaviour added to someone else's class ([`Resizable`](widgets/Resizable.md)
+onto a widget, [`ChordMixin`](chords.md) onto an app) is a mixin, listed
+*ahead* of the class it extends so its handlers run first in the MRO.
+
+A mixin defines no `__init__`: one would have to cooperate with the signature
+of every class it is mixed into. State it needs starts life as a class-level
+default instead.
+
+## `import tcoda` imports nothing
+
+`tcoda/__init__.py` is deliberately empty of imports: pulling in `tcoda` must not
+drag Textual (or a config file read) into a module that only wanted the
+version. Consumers import from `tcoda.widgets`, `tcoda.dialogs`, `tcoda.settings`,
+`tcoda.chords`, `tcoda.terminal_title` or `tcoda.log_sink`.
+
+The same rule applies between subpackages: `tcoda.widgets` stays importable
+without the settings machinery, so `SettingsMenuItem` imports
+`SettingsDialog` lazily, when it is chosen.
+
+## Persisted state is an optimisation, never a dependency
+
+Every store built on `tcoda.paths` (the settings file, and anything an app keeps
+in its per-user config/cache/data directories) is an optimisation: an absent,
+unreadable or corrupt file means "no data", not a crash on startup. That is
+why `read_json` degrades to a default instead of raising, and why writes go
+through a temp file (`write_json_atomic`) so a crash or a concurrent read
+never sees half a file.

tcoda-0.8.0/docs/chords.md

@@ -0,0 +1,83 @@
+# Chords
+
+VSCode-style bindings of several keystrokes in a row, declared in the ordinary
+`BINDINGS` with the steps separated by a space. The mixin goes on the app,
+because only the app sees a key before the focused widget does.
+
+```python
+from tcoda.chords import ChordMixin
+
+
+class MyApp(ChordMixin, App[None]):
+    CHORD_TIMEOUT = 2.0  # the default; None waits forever
+
+    BINDINGS = [
+        Binding("ctrl+k ctrl+s", "save_all", "Save all", id="save-all"),
+    ]
+```
+
+- **It has to live on the App.** `App.on_event` is the one funnel every key
+  press passes through before priority bindings are checked and before the
+  focused widget sees the key. Anything later is too late — an `Input` would
+  already have acted on its own `ctrl+k`.
+- **Everything else about a binding still works**: `check_action`, `show`,
+  `id`, keymaps (`set_keymap({"save-all": "ctrl+k ctrl+w"})`), and any node in
+  the focus chain can declare one. Textual stores a chord as one key that no
+  single press can match, so it already lists them — the mixin only adds the
+  matching.
+- **A chord's first step beats a single-key binding on the same key**, however
+  near the focus that binding is: while `ctrl+k ctrl+s` is active, `ctrl+k`
+  starts it even in an `Input`, whose own `ctrl+k` deletes to the end of the
+  line. The exception is a key the focused widget would *type*, so `g g` does
+  not stop anyone typing a g.
+- **A key that continues no chord abandons it and is swallowed**, `escape`
+  included, rather than being typed halfway through what was meant as a
+  command.
+- **`CHORD_TIMEOUT` drops the steps typed so far**; it does not replay them to
+  the focused widget.
+- **The [footer](widgets/Footer.md) shows a pending chord** in its status
+  corner, beside the app's own `status.update(...)` text rather than in place
+  of it, and displays chord keys step by step (`^k ^s`). Clicking one runs it.
+  The steps typed so far are also available as the app's `pending_chord`
+  reactive.
+- **A [`ChordViewer`](widgets/ChordViewer.md) lists what can come next**, in
+  the style of which-key.nvim, if the user hesitates partway through a chord.
+
+## Naming groups
+
+A prefix that leads to further chords can be given a name for the
+[`ChordViewer`](widgets/ChordViewer.md) to show, in a class variable next to
+`BINDINGS`:
+
+```python
+class MyApp(ChordMixin, App[None]):
+    BINDINGS = [
+        Binding("ctrl+k g a", "stage", "Stage"),
+        Binding("ctrl+k g c", "commit", "Commit"),
+    ]
+    CHORD_GROUPS = {"ctrl+k": "Keyboard", "ctrl+k g": "Git"}
+```
+
+- **Only the names live there; the chords stay in `BINDINGS`.** That is what
+  keeps `check_action`, keymaps, the footer and focus-chain scoping working,
+  so the variable is deliberately `CHORD_GROUPS` and not `CHORDS`. A group is
+  also not a fake binding: it has no action to run and nothing to match, so
+  the mixin's matching does not change.
+- **Any node with bindings may declare one**, app, screen or widget, and its
+  names apply on the same terms as its bindings: while it is in the focus
+  chain, with a node nearer the focus winning. A subclass adds to its
+  parents' names rather than replacing them all, as `BINDINGS` does.
+- **A group has no condition of its own.** It is shown only while some chord
+  under it is, so it comes and goes with its chords.
+- **A keymap that moves a chord's prefix does not move its group's name.**
+  `set_keymap` only knows about bindings.
+- `chord_groups(screen)` returns the names in force, keyed by steps.
+
+## Holding a chord
+
+`hold_chord()` is for whatever has just shown the user what can come next
+(the `ChordViewer` calls it when it appears). The pending chord then waits
+until it completes or is abandoned, whatever `CHORD_TIMEOUT` says, and
+`CHORD_BACK_KEY` (`"backspace"`, or None for no back key) drops the last step
+instead of abandoning the chord. Stepping back from the first step abandons
+it. A chord that actually continues with that key still wins.

tcoda-0.8.0/docs/demo.md

@@ -0,0 +1,33 @@
+# Demo
+
+```sh
+python -m tcoda          # wherever tcoda is installed
+uv run python -m tcoda   # from this repository
+```
+
+This is the same idea as `python -m textual`. The demo is a small browser
+over tcoda's own installed source files, with every widget and dialog in its
+natural place. All of it is ordinary consumer code, so
+[`src/tcoda/demo/`](../src/tcoda/demo/) doubles as a worked example.
+
+| Component | Where to find it |
+| --- | --- |
+| [Header](widgets/Header.md) | Top row. The middle tracks the screen title, which is the directory being browsed. Click the left area for About, the right one for versions. |
+| [MenuBar](widgets/MenuBar.md) | F9, or click where it appears. Items use `@on(MenuItem.Pressed)` (File, Dialogs) and `action=` strings (View). View has one disabled item. |
+| [Resizable](widgets/Resizable.md) | The directory tree on the left. Drag its right border. |
+| [DataTable](widgets/DataTable.md) | The file list. Click a header to sort. Size and Modified show rounded values but rank by the exact bytes and mtime. Hover a cell for its tooltip. |
+| [Footer](widgets/Footer.md) | Bottom row: `F9`, `F1` and `^q` pinned, the other keys sorted, and a countdown plus a file count in the status corner. |
+| [Countdown](widgets/Countdown.md) | Footer status corner. It spins during an auto-refresh. Turning auto-refresh off in the settings hides it. |
+| [LogViewer](widgets/LogViewer.md) | F1. Four `tcoda.demo.*` loggers write to it, so the source filter has something to filter. |
+| [Chords](chords.md) and [ChordViewer](widgets/ChordViewer.md) | `ctrl+k` then a pause lists every chord: `s …` sorts, `d …` opens each dialog, `r` refreshes, `t` changes theme. |
+| [Terminal title](terminal_title.md) | The terminal's window or tab title reads "tcoda demo" while the demo runs, and goes back to what it was on exit. |
+| [ConfirmDialog](dialogs/ConfirmDialog.md) | Dialogs → Confirm, and Delete files (the `danger=True, focus_cancel=True` variant, which deletes nothing). |
+| [Dialog](dialogs/Dialog.md) | Dialogs → Filter (F2): `FilterDialog`, the demo's own dialog on the shared chrome. |
+| [AboutDialog](dialogs/AboutDialog.md) | Help → About: the demo's own about-text, with `$version` filled in through `variables=`. |
+| [SettingsDialog](dialogs/SettingsDialog.md) and [settings](settings.md) | File → Settings. The dotted `Demo.Refresh` and `Demo.Table` groups include a `choices=` setting and a `SettingAction`. Changes apply when the dialog closes. |
+
+- **Settings persist.** They go to the per-user settings file of an app named
+  `tcoda-demo`, and only overridden values are written.
+- **`tcoda.demo` is an app, not a library module.** Importing it declares the
+  demo's settings and points `tcoda.settings.config` at that file, so nothing
+  else should import it.

tcoda-0.8.0/docs/dialogs/AboutDialog.md

@@ -0,0 +1,36 @@
+# About dialog
+
+A small modal that reads its text from a file: the first five lines are a
+fixed header (never scrolled — a logo or tagline), everything after that is
+a scrollable body capped at ten lines, so the dialog never grows past
+fifteen lines or 57 columns wide.
+
+```python
+from tcoda.widgets import AboutMenuItem
+
+from myapp import __version__
+
+
+class MainScreen(Screen):
+    def compose(self) -> ComposeResult:
+        with MenuBar():
+            with Menu("Help", id="help"):
+                yield AboutMenuItem(
+                    path="myapp/about.txt",
+                    variables={"app": "myapp", "version": __version__},
+                )
+```
+
+- **`path` is optional.** Omit it and `AboutDialog` shows a bundled
+  placeholder — useful before an app has written its own about-text, or in
+  tests. `AboutMenuItem(path=...)` passes it straight through.
+- **`variables` fills in `$name` / `${name}` placeholders** in the
+  about-text (via `string.Template.safe_substitute`) — handy for an app
+  name or version number that only the consuming app knows. It's optional;
+  omit it and the text is shown as-is. A placeholder with no matching key
+  is left in the output untouched rather than raising.
+- **Pushed directly, without a menu item**, with
+  `self.app.push_screen(AboutDialog(path="myapp/about.txt"))`.
+- **`escape` dismisses it** — inherited from [`Dialog`](Dialog.md), like every
+  other dialog here. There is no button row; this dialog only ever dismisses,
+  nothing to confirm.