py-sparcli 0.3.0__tar.gz → 0.4.0__tar.gz

py_sparcli-0.4.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] – 2026-07-19
+
+### Added
+
+- `Card`, a filled counterpart to `Panel`: a colored surface with its own title and footer rows instead of a title embedded in the border. A single `accent()` derives the whole palette through HSL – the title keeps the accent saturated, the body text and both backgrounds become desaturated, darker shades of the same hue. The border is opt-in, the card fills the width it is rendered into, content wraps, and title, body and footer each take their own padding and alignment. The style setters patch the derived values rather than replacing them. Below truecolor support the backgrounds are dropped and the card renders as accented text, because the derived shades would collapse onto one ANSI-16 color. Ported from the Rust original, whose output it matches byte for byte.
+- `BorderType.TALL`, a thin block border around a card's filled surface: the side bars ink a quarter of their cell's width and the top and bottom lines an eighth of their cell's height, which comes out equally thick because a terminal cell is about twice as tall as it is wide, and the horizontal lines run across the corner cells so the corners close. Only `Card` draws it natively – the bars need a filled surface to read against, all four edges use a different glyph, and the right-hand one is painted with foreground and background swapped, none of which `BorderChars` can express. Every other widget receives the `BorderType.THICK` glyphs from `BorderType.chars`.
+- `Color.to_rgb` returns the 24-bit value of any color: named colors and palette indices resolve through the standard xterm palette (fixed table, 6x6x6 cube, grayscale ramp). `Color.RESET` has no fixed value and returns `None`.
+- `width.wrap_line` and `width.truncate_line` are style-preserving counterparts to `wrap` and `truncate`. They keep each span's style and hyperlink, and a word straddling a span boundary stays whole instead of being wrapped apart.
+- `core.command`, holding the quote-aware `split_command` and the `resolve_from_env` precedence rule. Both `input/editor.py` and `output/pager.py` had carried their own private copy of the splitter. Mirrors the Rust port.
+- `terminal.is_error_tty`, `terminal.output_width` and `terminal.UNCONSTRAINED_WIDTH` expose which stream a widget draws to and how wide printed output should be laid out. Mirrors the Rust port.
+- Coverage gate: `pytest` now measures branch coverage of `sparcli` and fails below the configured threshold.
+- Direct test coverage for `output/box.py`, `output/table/plan.py`, the key decoding primitives, persisted history and the external editor/pager command handling.
+
+### Changed
+
+- Progress indicators (`ProgressBar`, `Spinner`, `MultiProgress`) now draw on standard error rather than standard output, and only when standard error is itself a terminal. A caller piping standard output onward no longer receives animation frames in the payload. Interactive prompts and `Live` continue to draw on standard output. Mirrors the Rust port.
+- `Renderable.print` and `print_to` no longer truncate when standard output is not a terminal. Previously they laid out for an invented 80 columns, so piping a wide table clipped its cells with `…` and lost data without saying so. An explicit `render(max_width)` is unaffected. Mirrors the Rust port.
+- A `Card` without an explicit `width` now lays out at its natural content width when the available width is unconstrained, instead of filling it. Mirrors the Rust port.
+- A blank `Pager` command override now falls through to `$PAGER` and the platform default instead of raising `ConfigError`. Blank counts as unset everywhere, which is how `$EDITOR` already behaved. An unparsable command still raises `ConfigError`. Mirrors the Rust port.
+- `sparcli.core.width` is a package: `measure` holds the plain-string helpers, `line` the style-preserving ones. Every importer keeps writing `from sparcli.core.width import ...`, and the `sparcli.width` namespace is unchanged.
+- The Ruff rule set now covers the full documented list (docstrings, annotations, complexity, security, pathlib, pytest and more) instead of nine groups; every exception carries a comment explaining why.
+- `InPlace` moved from `sparcli.output.live` to `sparcli.core.inplace` so that `input` no longer depends on `output`. It is still re-exported from `sparcli.output.live` and the flat `sparcli` namespace, so imports keep working.
+- `TextInput` delegates suggestion handling to `sparcli.input.completion.Completion` and history recall to `sparcli.input.recall.HistoryRecall`. Public behavior and the builder API are unchanged.
+- The list prompts share `sparcli.input.selection` for cursor movement, scrolling and result collection; the free-text prompts share the Ctrl-key tables and the caret keys from `sparcli.input.line_edit`.
+- `ProgressBar` keeps its appearance in a `ProgressOpts` value object, mirroring how `Table` uses `TableOpts`.
+- The byte-level primitives behind the terminal event source live in `sparcli.input.keydecode`.
+
+### Fixed
+
+- `$EDITOR`, `$VISUAL` and `$PAGER` are split with `shlex` instead of `str.split`, so an editor or pager path containing spaces no longer breaks into invalid arguments.
+- A pager that cannot be spawned now raises `TerminalError` instead of a bare `FileNotFoundError`, matching how the editor already behaved.
+- The history state directory is resolved to an absolute path, and an application name containing a path separator or `..` is rejected instead of being written outside the state directory.
+- `History.load` keeps only the newest `max_entries` lines instead of reading the whole file into memory. The file is foreign input and may have been written by a build with a larger limit. Mirrors the Rust port.
+
+## [0.3.0] – 2026-07-11
+
+### Added
+
+- `Style.remove_modifier` clears one or more attributes from a layered style (the counterpart to `add_modifier`).
+- `TextInput` and `PasswordInput` gained keyword-only constructor options mirroring their fluent setters, so they configure like every other widget.
+- `OutcomeKind` is re-exported from the flat `sparcli` namespace.
+
+### Changed
+
+- Hide the terminal hardware cursor during in-place redraws (spinner, progress, multi-progress, live) and interactive prompts, and restore it reliably on finish, on prompt exit and at interpreter exit.
+
+### Fixed
+
+- `DatePicker` navigation past the representable date range (before year 1 or after year 9999) no longer raises; it clamps to `date.min` / `date.max`.
+- Inline markup no longer swallows a closed bracket that names no known style or attribute (such as `array[0]`); such text is emitted literally.
+- `char_width` no longer raises on an empty or multi-character string.
+- A negative `NumberInput.decimals` setting is clamped to zero instead of raising when the value is formatted.
+- The raw-mode paths in `TerminalGuard` and the external-editor suspension now also catch `termios.error`, so a non-terminal stdin falls back to the documented no-op instead of raising (`termios.error` is not an `OSError`).
+- `TextInput`'s Ctrl-G external editor now runs with raw mode suspended (cooked), matching `Textarea` and the Rust original; previously the editor launched while the terminal was still in raw mode.
+- `KeyValue` rows are no longer padded with trailing spaces when there is no right margin; shorter rows stay ragged, matching the Rust original.
+- Word wrapping splits on runs of whitespace (tabs, repeated spaces), matching Rust's `split_whitespace`, instead of on a single space only.
+- History files are split into entries on newlines only (like Rust's `str::lines`), so an entry containing an exotic line separator is no longer split in two.
+
+### Security
+
+- Control characters (C0, DEL and C1, except tab) are stripped from span content and OSC-8 link URLs before they reach the terminal, so untrusted text can no longer inject escape sequences or terminate a hyperlink early.
+- History files are written atomically (temp file plus rename), so a crash or a concurrent writer can no longer truncate the file.
+
+### Documentation
+
+- Align the minor version with the Rust `sparcli` port (both at 0.3.x); the two ports now track the same minor number.
+- Add `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `TODO.md`, README badges and editor/VCS tooling configs (`.editorconfig`, `.gitattributes`); migrate packaging metadata to an SPDX license expression and expand the project URLs for PyPI.
+
+### Notes
+
+- `DatePicker`'s initial "today" uses the local date here, while the Rust original uses UTC (it stays dependency-free). This one-point divergence is intentional; near midnight the default day can differ by one between the two ports.
+
+## [0.1.0] – 2026-07-10
+
+### Added
+
+- Initial release: idiomatic Python port of the Rust `sparcli` library.
+- Styled output widgets: `Panel`, `Table`, `List`, `Rule`, `Alert`, `Badge`, `Columns`, `Tree`, `KeyValue`, `Diff`, `Spinner`, `ProgressBar`, `MultiProgress`, `Live`, `Pager`.
+- Interactive input widgets: `TextInput`, `PasswordInput`, `NumberInput`, `Confirm`, `Select`, `FuzzySelect`, `DatePicker`, `Textarea`.
+- Unified `Theme`, inline `markup`, width utilities, terminal capability detection, validators, shortcuts and command history.
+- Dependency-free (standard library only).
+
+[Unreleased]: https://github.com/cgroening/py-sparcli/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/cgroening/py-sparcli/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/cgroening/py-sparcli/compare/v0.1.0...v0.3.0
+[0.1.0]: https://github.com/cgroening/py-sparcli/releases/tag/v0.1.0

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/CLAUDE.md

@@ -27,12 +27,24 @@ Requirements for all future sessions in this project. On conflict, this file tak
 
 ## Architecture (keep the layers strictly separated)
 
-- `core/` – foundation: style, color, text, render, geometry, border, theme, width, terminal, markup. No widget logic.
+- `core/` – foundation: style, color, text, render, geometry, border, theme, width, terminal, markup, `inplace` (the redraw engine), `command` (quote-aware splitting and env resolution for `$EDITOR`/`$PAGER`). No widget logic.
 - `output/` – printable widgets, subclass `Renderable` (`render(max_width) -> Rendered`). Shared helpers: `layout`, `compose`, `box`, `live`.
-- `input/` – interactive prompts over `EventSource` (DI) + the `prompt.run_prompt` loop + `line_edit.LineEditor` (SSOT for text editing) + `field` (rendering).
-- **Dependency direction:** `output`/`input` → `core`. Never cyclic, never `core` → widget layer.
+- `input/` – interactive prompts over `EventSource` (DI) + the `prompt.run_prompt` loop and `prompt.run_on_terminal` guard + `line_edit.LineEditor` (SSOT for text editing, plus the shared `CTRL_ACTIONS` tables and `apply_caret_key`) + `field` (rendering). The prompts are composed from small collaborators: `completion.Completion`, `recall.HistoryRecall`, `selection.SelectionCursor` and the `keydecode` byte primitives.
+- **Dependency direction:** `output`/`input` → `core`. Never cyclic, never `core` → widget layer, and never `input` → `output` (this is why `InPlace` lives in `core/inplace.py`; `output/live.py` re-exports it for the public API).
 - **A single unified theme** in `core/theme.py` drives both input and output.
-- The public API is re-exported flat (`from sparcli import ...`, 80 symbols) plus the namespaces `sparcli.width/terminal/markup/event/validate/shortcut`. Every `__init__.py` carries an explicit `__all__` list.
+
+### One helper per rule
+
+Where a rule applies in more than one widget it lives in exactly one place. Do not reimplement these per call site: `core.width.truncate`/`truncate_line` for `…` clipping, `input.selection.SelectionCursor` for cursor and scroll window, `input.prompt.run_on_terminal` for the terminal handover, `core.command.split_command`/`resolve_from_env` for external commands.
+
+## Output streams (§1.6)
+
+sparcli is a library, not a CLI program, so §1.6 binds it only through what it prints:
+
+- Payload goes to **stdout**, progress indicators to **stderr**, and progress draws only when stderr is a terminal. `InPlace.progress()` is the seam.
+- `print`/`print_to` do **not** truncate when stdout is not a terminal: they lay out at `UNCONSTRAINED_WIDTH`, because clipping to an invented width loses piped data silently. An explicit `render(max_width)` still truncates – that width is the caller's decision.
+- §1.7 (TUI) rules – scrollbar on overflow, a `?` overlay in every prompt, `Ctrl+Q` – are deliberately **not** implemented. They govern terminal UIs, not a CLI output library.
+- The public API is re-exported flat (`from sparcli import ...`, 81 symbols) plus the namespaces `sparcli.width/terminal/markup/event/validate/shortcut`. Every `__init__.py` carries an explicit `__all__` list.
 
 ## Dependencies
 
@@ -47,17 +59,19 @@ Requirements for all future sessions in this project. On conflict, this file tak
 ## Style & tooling
 
 - Target Python: **3.12+** (`requires-python = ">=3.12"`).
-- **Strings: double quotes `"..."`** – a deliberate, user-mandated deviation from the style-guide default (§12.5). Enforced via `[tool.ruff.format] quote-style = "double"`. Exceptions that stay single-quoted: string literals nested inside a double-quoted f-string (`';'`, `' '`) and `repr` outputs in doctests.
-- **Formatting/linting:** `ruff` (format + lint). 80-character lines. Imports isort-sorted (stdlib → third-party → local). `from __future__ import annotations` as the first line of every module.
+- **Strings: double quotes `"..."`** everywhere, including nested inside f-strings (PEP 701). Enforced via the `Q` lint rules with `inline-quotes = "double"` and `avoid-escape = false`; the formatter uses `quote-style = "preserve"` so it cannot rewrite the nested case back to single quotes. `repr` outputs in doctests keep their single quotes, because that is what Python prints.
+- **Formatting/linting:** `ruff` (format + lint), running the full rule set from the style guide. 80-character lines, enforced (`E501` is on). Imports isort-sorted (stdlib → third-party → local). `from __future__ import annotations` as the first line of every module. Every entry in the `ignore` list carries a comment saying why.
+- **Docstrings:** NumPy convention. The fluent builder setters keep a single-line docstring instead of full `Parameters`/`Returns` blocks – they take one argument and return `self`, so the blocks would add length without information. Full blocks are required everywhere else.
 - **Type checking:** `basedpyright` in **strict** mode must report 0 errors. Complete, modern type hints (`X | None`, builtin generics, PEP 695).
 - No em dash; straight quotes/apostrophes; named constants instead of magic numbers/strings.
 
-Commands (from the project root):
+Commands (from the project root, all four must be clean):
 
 ```bash
 ruff check --fix . && ruff format .
 basedpyright sparcli examples
-python -m pytest -q
+python -m pytest -q          # includes doctests and the branch-coverage gate
+pip-audit .
 ```
 
 ## API conventions (idiomatic)
@@ -91,6 +105,8 @@ python -m pytest -q
 - Doctests in `# Examples` count as tests (`--doctest-modules`) and must pass. `repr` expected-outputs keep single quotes.
 - Test override: `SPARCLI_NO_TTY=1` forces non-TTY.
 - **Run all tests after every change** and keep ruff + basedpyright clean.
+- Shared helpers and fixtures live in `tests/conftest.py` (`plain_lines`, `joined`, `render_to_string`, the theme reset and the `state_home` fixture). Import them as `from conftest import ...`.
+- Branch coverage is measured on every run and gated by `fail_under` in `[tool.coverage.report]`. Do not lower it to make a change pass.
 
 ## Environment variables
 

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/CONTRIBUTING.md

@@ -16,12 +16,7 @@ ruff format --check .          # formatting (drop --check to apply)
 basedpyright sparcli examples  # strict type checking
 ```
 
-All three checks must be clean before a change is ready. Optionally, install the pre-commit hooks to run linting, formatting and type checks automatically:
-
-```bash
-pre-commit install          # once
-pre-commit run --all-files  # on demand
-```
+All four checks must be clean before a change is ready.
 
 ## Ground rules
 

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-sparcli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Styled CLI output and interactive input widgets, dependency-free
 Project-URL: Homepage, https://github.com/cgroening/py-sparcli
 Project-URL: Repository, https://github.com/cgroening/py-sparcli
@@ -40,7 +40,7 @@ sparcli is a native Python port of the Rust library of the same name. It renders
 
 ## Highlights
 
-- Output: styled text, inline markup, tables (colspan, rowspan, striping, wrapping, titles), panels, alerts, rules, lists, trees, key-value lists, badges, progress bars, spinners, multi-progress, diffs, columns, live in-place display, pager, and the composition helpers `align`, `pad` and `vstack`.
+- Output: styled text, inline markup, tables (colspan, rowspan, striping, wrapping, titles), panels, cards (a filled surface whose whole palette is derived from one accent color), alerts, rules, lists, trees, key-value lists, badges, progress bars, spinners, multi-progress, diffs, columns, live in-place display, pager, and the composition helpers `align`, `pad` and `vstack`.
 - Input: confirm, text (validation, character filters, history, ghost autocomplete, dropdown), password, number (with a calculator), textarea, single and multi select, an inline fuzzy select, and a calendar date picker.
 - A unified `Theme` for input and output, set once and overridable per call.
 - Robust by design: prompts never raise on input, a RAII terminal guard restores the terminal, and results come back as values rather than exceptions.
@@ -66,7 +66,7 @@ sparcli requires Python 3.12 or newer.
 | Category | Components |
 | --- | --- |
 | Text and style | `Style`, `Color`, `Attribute`, `Span`, `Line`, `Text`, `markup` |
-| Framing and layout | `Panel`, `Rule`, `Columns`, `align`, `pad`, `vstack`, `BorderType`, `Align`, `Edges`, `Title` |
+| Framing and layout | `Panel`, `Card`, `Rule`, `Columns`, `align`, `pad`, `vstack`, `BorderType`, `Align`, `Edges`, `Title` |
 | Data widgets | `Table` (`Column`, `Cell`), `List` (`Marker`), `Tree` (`TreeNode`), `KeyValue`, `Diff`, `Badge`, `Alert` (`AlertKind`) |
 | Progress and live | `Spinner` (`SpinnerStyle`), `ProgressBar` (`ProgressStyle`, `Thresholds`), `MultiProgress`, `Live`, `Pager` |
 | Input prompts | `TextInput`, `PasswordInput`, `NumberInput`, `Confirm`, `Select`, `FuzzySelect`, `DatePicker`, `Textarea` |
@@ -99,7 +99,7 @@ Table().columns(["Name", "Status"]).row(["web-1", "online"]).row(
 ╰───────┴────────╯
 ```
 
-A `Panel` frames content with a rounded border and an optional title. A left-aligned title reads as part of the frame: one connecting border glyph sits before it, never a flush corner - unless the title is too wide for the frame, in which case it is truncated into the border rather than widening the panel.
+A `Panel` frames content with a rounded border and an optional title. A left-aligned title reads as part of the frame: one connecting border glyph sits before it, never a flush corner – unless the title is too wide for the frame, in which case it is truncated into the border rather than widening the panel.
 
 ```python
 from sparcli import Panel
@@ -113,6 +113,30 @@ Panel("All systems nominal.").title("Status").print()
 ╰──────────────────────╯
 ```
 
+Where a `Panel` draws a frame, a `Card` fills a surface. It takes a single accent color and derives everything else from it through HSL: the title stays saturated, the body text and both backgrounds become desaturated, darker shades of the same hue. Title and footer sit on rows of their own, each with its own background, and each region takes its own padding and alignment.
+
+```python
+from sparcli import BorderType, Card, Color
+
+Card("Deployed to production.").title("Release 1.4.0").footer(
+    "3 minutes ago"
+).accent(Color.from_hex("#a6e3a1") or Color.GREEN).border(
+    BorderType.TALL
+).width(40).print()
+```
+
+```text
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Release 1.4.0                        ┃
+┃                                      ┃
+┃ Deployed to production.              ┃
+┃                                      ┃
+┃ 3 minutes ago                        ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+That block is what the card degrades to, because the preview above is captured without color. With truecolor, `BorderType.TALL` draws a thin block frame instead: the side bars ink a quarter of their cell's width and the top and bottom lines an eighth of their cell's height, which comes out equally thick since a terminal cell is about twice as tall as it is wide, and the horizontal lines run across the corner cells so the corners close. Only `Card` renders it that way – the bars need a filled surface to read against, so every other framed widget receives the heavy line glyphs shown here. The same applies to a card without truecolor support, and `BorderType.ASCII` takes over when the theme disables Unicode.
+
 ## Input example
 
 Prompts return an `Outcome` – a submitted value, a cancellation, or a fired shortcut – and never raise on input. They require an interactive terminal; without one, `run()` raises `NoTerminalError`. Each prompt also has a `frame()` method that renders its static opening frame without a TTY, which is how the previews below are produced.

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/README.md

@@ -14,7 +14,7 @@ sparcli is a native Python port of the Rust library of the same name. It renders
 
 ## Highlights
 
-- Output: styled text, inline markup, tables (colspan, rowspan, striping, wrapping, titles), panels, alerts, rules, lists, trees, key-value lists, badges, progress bars, spinners, multi-progress, diffs, columns, live in-place display, pager, and the composition helpers `align`, `pad` and `vstack`.
+- Output: styled text, inline markup, tables (colspan, rowspan, striping, wrapping, titles), panels, cards (a filled surface whose whole palette is derived from one accent color), alerts, rules, lists, trees, key-value lists, badges, progress bars, spinners, multi-progress, diffs, columns, live in-place display, pager, and the composition helpers `align`, `pad` and `vstack`.
 - Input: confirm, text (validation, character filters, history, ghost autocomplete, dropdown), password, number (with a calculator), textarea, single and multi select, an inline fuzzy select, and a calendar date picker.
 - A unified `Theme` for input and output, set once and overridable per call.
 - Robust by design: prompts never raise on input, a RAII terminal guard restores the terminal, and results come back as values rather than exceptions.
@@ -40,7 +40,7 @@ sparcli requires Python 3.12 or newer.
 | Category | Components |
 | --- | --- |
 | Text and style | `Style`, `Color`, `Attribute`, `Span`, `Line`, `Text`, `markup` |
-| Framing and layout | `Panel`, `Rule`, `Columns`, `align`, `pad`, `vstack`, `BorderType`, `Align`, `Edges`, `Title` |
+| Framing and layout | `Panel`, `Card`, `Rule`, `Columns`, `align`, `pad`, `vstack`, `BorderType`, `Align`, `Edges`, `Title` |
 | Data widgets | `Table` (`Column`, `Cell`), `List` (`Marker`), `Tree` (`TreeNode`), `KeyValue`, `Diff`, `Badge`, `Alert` (`AlertKind`) |
 | Progress and live | `Spinner` (`SpinnerStyle`), `ProgressBar` (`ProgressStyle`, `Thresholds`), `MultiProgress`, `Live`, `Pager` |
 | Input prompts | `TextInput`, `PasswordInput`, `NumberInput`, `Confirm`, `Select`, `FuzzySelect`, `DatePicker`, `Textarea` |
@@ -73,7 +73,7 @@ Table().columns(["Name", "Status"]).row(["web-1", "online"]).row(
 ╰───────┴────────╯
 ```
 
-A `Panel` frames content with a rounded border and an optional title. A left-aligned title reads as part of the frame: one connecting border glyph sits before it, never a flush corner - unless the title is too wide for the frame, in which case it is truncated into the border rather than widening the panel.
+A `Panel` frames content with a rounded border and an optional title. A left-aligned title reads as part of the frame: one connecting border glyph sits before it, never a flush corner – unless the title is too wide for the frame, in which case it is truncated into the border rather than widening the panel.
 
 ```python
 from sparcli import Panel
@@ -87,6 +87,30 @@ Panel("All systems nominal.").title("Status").print()
 ╰──────────────────────╯
 ```
 
+Where a `Panel` draws a frame, a `Card` fills a surface. It takes a single accent color and derives everything else from it through HSL: the title stays saturated, the body text and both backgrounds become desaturated, darker shades of the same hue. Title and footer sit on rows of their own, each with its own background, and each region takes its own padding and alignment.
+
+```python
+from sparcli import BorderType, Card, Color
+
+Card("Deployed to production.").title("Release 1.4.0").footer(
+    "3 minutes ago"
+).accent(Color.from_hex("#a6e3a1") or Color.GREEN).border(
+    BorderType.TALL
+).width(40).print()
+```
+
+```text
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Release 1.4.0                        ┃
+┃                                      ┃
+┃ Deployed to production.              ┃
+┃                                      ┃
+┃ 3 minutes ago                        ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+That block is what the card degrades to, because the preview above is captured without color. With truecolor, `BorderType.TALL` draws a thin block frame instead: the side bars ink a quarter of their cell's width and the top and bottom lines an eighth of their cell's height, which comes out equally thick since a terminal cell is about twice as tall as it is wide, and the horizontal lines run across the corner cells so the corners close. Only `Card` renders it that way – the bars need a filled surface to read against, so every other framed widget receives the heavy line glyphs shown here. The same applies to a card without truecolor support, and `BorderType.ASCII` takes over when the theme disables Unicode.
+
 ## Input example
 
 Prompts return an `Outcome` – a submitted value, a cancellation, or a fired shortcut – and never raise on input. They require an interactive terminal; without one, `run()` raises `NoTerminalError`. Each prompt also has a `frame()` method that renders its static opening frame without a TTY, which is how the previews below are produced.

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/docs/DEVELOPMENT.md

@@ -5,15 +5,29 @@ How to build, test and work on `sparcli`. This is a dependency-free Python libra
 ## Prerequisites
 
 - Python 3.12 or newer (the code uses PEP 695 generics and `type` statements).
-- The dev tools `ruff`, `basedpyright` and `pytest`. No runtime dependencies and no system dependencies beyond a terminal.
+- The dev tools `ruff`, `basedpyright`, `pytest` and `pytest-cov`, plus `pip-audit`. No runtime dependencies and no system dependencies beyond a terminal.
 
 Install the package in editable mode together with the dev tools:
 
 ```bash
 pip install -e .
-pip install ruff basedpyright pytest
+pip install --group dev
 ```
 
+## The quality gate
+
+Four commands define what has to pass. All four must be clean before a change is ready:
+
+```bash
+ruff check .                   # lint
+ruff format --check .          # formatting
+basedpyright sparcli examples  # strict type checking, zero errors
+python -m pytest -q            # tests, doctests and the coverage gate
+pip-audit .                    # known vulnerabilities in the dev toolchain
+```
+
+`ruff check --fix . && ruff format .` applies what ruff can repair on its own. The sections below spell each step out.
+
 ## Test
 
 The whole suite is headless: output widgets render to an in-memory `Rendered` block and are asserted on their visible text, and input prompts are driven by a scripted fake event source. No test needs a real terminal, so it is safe to run in CI.
@@ -22,7 +36,7 @@ The whole suite is headless: output widgets render to an in-memory `Rendered` bl
 python -m pytest -q
 ```
 
-The pytest configuration in `pyproject.toml` also runs docstring examples (`--doctest-modules`) across the package and ignores the `examples/` directory. A few focused runs:
+The pytest configuration in `pyproject.toml` also runs docstring examples (`--doctest-modules`) across the package, ignores the `examples/` directory, turns warnings into errors and measures branch coverage. The run fails if coverage drops below the `fail_under` threshold in `[tool.coverage.report]`. A few focused runs:
 
 ```bash
 python -m pytest tests/test_table.py       # one test module
@@ -38,7 +52,15 @@ ruff format --check .         # formatting (drop --check to apply)
 basedpyright sparcli examples # strict type checking
 ```
 
-Both `ruff check` and `basedpyright` must be clean. The project targets strict typing: every public item is annotated, and `ruff` enforces double quotes, an 80-column line length (the `E501` long-line rule is relaxed because rendered strings and docstrings sometimes exceed it) and an import ordering.
+Both `ruff check` and `basedpyright` must be clean. The project targets strict typing: every public item is annotated, and `ruff` runs the full documented rule set, including docstring style (NumPy convention), annotations, complexity, security (`flake8-bandit`), `pathlib` usage and import ordering. Line length is enforced at 80 columns.
+
+Every entry in the `ignore` list in `pyproject.toml` carries a comment saying why it is there. The two that most often surprise newcomers: `D401` is off because the style guide mandates third-person docstring summaries ("Returns ...") where that rule wants the imperative, and `FBT001`/`FBT002` are off because the fluent builder API takes booleans by design (`Table.striped(True)`) to mirror the Rust port.
+
+Dependencies are audited separately:
+
+```bash
+pip-audit .
+```
 
 ## Run the examples
 
@@ -56,15 +78,22 @@ Piping the static examples (`| cat`, `> file`) or setting `NO_COLOR=1` yields pl
 
 ```text
 sparcli/
-  core/     Foundation: color, style, text, markup, theme, border, geometry,
-            width, terminal, render. No widget logic.
-  output/   Printable widgets implementing Renderable.
+  core/     Foundation: color, hsl, style, text, markup, theme, border,
+            geometry, width, terminal, render, inplace. No widget logic.
+            width/ is a package: measure holds the plain-string helpers,
+            line the style-preserving ones.
+  output/   Printable widgets implementing Renderable. A widget large enough
+            to warrant it becomes a package instead of a module, splitting
+            along responsibilities: table/ and card/ do this.
   input/    Interactive prompts over an EventSource, plus the shared line
-            editor, terminal guard and prompt driver.
+            editor, terminal guard, prompt driver and the collaborators the
+            prompts are composed from: completion, recall, selection and the
+            keydecode primitives.
   errors.py The SparcliError hierarchy.
 examples/   Runnable demos (output_gallery, output_dynamic, prompts,
             output_readme, prompt_readme).
-tests/      Headless tests over the public API.
+tests/      Headless tests over the public API; shared helpers and fixtures
+            live in tests/conftest.py.
 docs/       This document.
 ```
 
@@ -72,7 +101,7 @@ The public API is the curated set re-exported at the package root (`sparcli/__in
 
 ## Dependency direction
 
-The dependency direction is strictly one-way: `output` and `input` depend on `core`, never the reverse, and `core` depends on nothing internal. Keep it that way when adding code – a `core` module must not import from `output` or `input`. This keeps the foundation reusable and the layering easy to reason about.
+The dependency direction is strictly one-way: `output` and `input` depend on `core`, never the reverse, and `core` depends on nothing internal. `input` must not depend on `output` either, which is why the in-place redraw engine `InPlace` lives in `sparcli.core.inplace` rather than next to `Live`. Keep it that way when adding code – a `core` module must not import from `output` or `input`. This keeps the foundation reusable and the layering easy to reason about.
 
 ## Environment variables
 
@@ -94,7 +123,8 @@ from sparcli import Table
 def test_table_has_a_header_row() -> None:
     rendered = Table().columns(["A", "B"]).row(["1", "2"]).render(80)
     lines = [line.plain() for line in rendered.lines]
-    assert "A" in lines[1] and "B" in lines[1]
+    assert "A" in lines[1]
+    assert "B" in lines[1]
 ```
 
 Input prompts are driven headlessly through `run_with(source)`, where the source is a `ScriptedSource` of queued keys. The scripted source auto-cancels on exhaustion, so a prompt can never loop forever in a test:
@@ -117,5 +147,5 @@ def test_types_and_submits() -> None:
 2. Keep the dependency direction: import only from `core` (and, within a layer, sibling helpers). Never import `output` or `input` from `core`.
 3. Add unit tests under `tests/`, following the patterns above. Name tests for the behavior they assert.
 4. Re-export the public type from `sparcli/__init__.py` and add it to `__all__`; free-function utilities go into the relevant facade submodule.
-5. Run `python -m pytest -q`, `ruff check .`, `ruff format .` and `basedpyright sparcli` until clean.
+5. Run the quality gate above until clean.
 6. Add a docstring to every public item (with a `# Examples` doctest where the usage is not obvious) and update `README.md` and, if relevant, the example gallery.

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/examples/output_dynamic.py

@@ -1,4 +1,5 @@
-"""Time-based and interactive output widgets.
+"""
+Time-based and interactive output widgets.
 
 Covers the spinner, a single progress bar, a multi-progress group, a live
 in-place redraw and the pager. Run it in a real terminal for the full effect:

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/examples/output_gallery.py

@@ -1,4 +1,5 @@
-"""A gallery of every static output widget.
+"""
+A gallery of every static output widget.
 
 Run it with ``python examples/output_gallery.py``. Everything here renders to a
 fixed frame, so the output is deterministic and pipe-friendly: piping it
@@ -14,6 +15,7 @@ from sparcli import (
     Align,
     Badge,
     BorderType,
+    Card,
     Cell,
     Color,
     Column,
@@ -126,6 +128,32 @@ def panels() -> None:
     ).width(40).print()
 
 
+def cards() -> None:
+    """Cards: filled surfaces whose colors all come from one accent."""
+    section("Cards")
+    Card("Every tone is derived from the theme accent.").title("Default").width(
+        52
+    ).print()
+    print()
+    Card("A single accent sets title, surface, text and border.").title(
+        "Derived from one color"
+    ).footer("border and footer, same accent").accent(
+        Color.from_hex("#a6e3a1") or Color.GREEN
+    ).border(BorderType.ROUNDED).width(52).print()
+    print()
+    Card("A thin block frame with even strokes and closed corners.").title(
+        "Tall border"
+    ).accent(Color.from_hex("#cba6f7") or Color.MAGENTA).border(
+        BorderType.TALL
+    ).title_padding(Edges.symmetric(1, 1)).width(52).print()
+    print()
+    Card("Centered, flat title, wider padding.").title("Flat").accent(
+        Color.from_hex("#f9e2af") or Color.YELLOW
+    ).flat_title().title_align(Align.CENTER).content_align(
+        Align.CENTER
+    ).padding(Edges.symmetric(1, 3)).width(52).print()
+
+
 def tables() -> None:
     """Tables: colspan plus striping, and a footer with a wrapping column."""
     section("Tables")
@@ -252,6 +280,7 @@ def main() -> None:
     sections()
     alerts()
     panels()
+    cards()
     tables()
     lists_and_trees()
     key_values_and_badges()

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/examples/output_readme.py

@@ -1,4 +1,5 @@
-"""The output showcase collage embedded in the README.
+"""
+The output showcase collage embedded in the README.
 
 Prints a titled hero panel, a three-column dashboard (table | list + tree |
 key-value + badges) and a progress bar. Everything is deterministic, so

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/examples/prompt_readme.py

@@ -1,4 +1,5 @@
-"""The input showcase collage embedded in the README.
+"""
+The input showcase collage embedded in the README.
 
 Renders the static opening frame of every interactive prompt via its
 ``frame()`` method – no TTY and no interaction – and arranges them into a

{py_sparcli-0.3.0 → py_sparcli-0.4.0}/examples/prompts.py

@@ -1,4 +1,5 @@
-"""Interactive prompt examples covering every input widget.
+"""
+Interactive prompt examples covering every input widget.
 
 Run it in a real terminal: ``python examples/prompts.py``. Each prompt runs in
 turn; pressing Esc cancels that prompt and the demo reports it as cancelled
@@ -9,7 +10,7 @@ notice and exits cleanly when standard input or output is redirected.
 from __future__ import annotations
 
 import sys
-from collections.abc import Callable
+from typing import TYPE_CHECKING
 
 from sparcli import (
     Confirm,
@@ -30,6 +31,9 @@ from sparcli import (
     validate,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 
 class _Block(Renderable):
     """Wraps a pre-rendered block so the footer hint can be printed."""