ruff-sync 0.1.5.dev1__tar.gz → 0.1.5.dev3__tar.gz

ruff_sync-0.1.5.dev3/.agents/DEPENDENCIES.md

@@ -0,0 +1,47 @@
+# Optional Dependencies & Lazy Loading
+
+To keep the `ruff-sync` CLI fast and lightweight, while still allowing for extensible features (like a TUI or specialized formatters), we use a standardized pattern for **Optional Dependencies**.
+
+## Requirements
+
+1. **Defensive Coding**: The application must never crash at startup if an optional dependency is missing. Instead, it should fail gracefully ONLY when the specific feature requiring that dependency is invoked.
+2. **Delayed Import Cycles**: We must avoid expensive imports of optional dependencies during the initial CLI application boot.
+3. **User-Friendly Errors**: If a dependency is missing, we must provide clear instructions on how the user can install it using `ruff-sync` extras.
+
+## Standard Pattern
+
+All code that relies on an optional dependency MUST follow this pattern:
+
+### 1. Define the Extra in `pyproject.toml`
+
+Add the dependency to the `[project.optional-dependencies]` section.
+
+```toml
+[project.optional-dependencies]
+tui = ["textual>=8.2.2"]
+```
+
+### 2. Check and Lazy-Import (Locally)
+
+Never import optional dependencies at the top level of a module. All imports must happen inside the function or method that requires them, AFTER a defensive check.
+
+```python
+def run_tui_feature():
+    # 1. First, check availability (fast, lightweight)
+    from ruff_sync.dependencies import require_dependency
+    require_dependency("textual", extra_name="tui")
+
+    # 2. Then, perform local import (delayed expensive cycle)
+    from textual.app import App
+    ...
+```
+
+## The Dependency Helper (`ruff_sync.dependencies`)
+
+Use the utilities in `src/ruff_sync/dependencies.py` to handle these checks.
+
+- `is_installed(package_name: str) -> bool`: A fast check using `importlib.util.find_spec` that doesn't trigger the package initialization.
+- `require_dependency(package_name: str, extra_name: str) -> None`: Checks if a package is installed and raises a helpful `ImportError` if it is not.
+
+### Example ImportError
+> "The 'textual' package is required for this feature. Install it with: pip install 'ruff-sync[tui]'"

ruff_sync-0.1.5.dev3/.agents/skills/mike/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mike
+description: Use this skill to manage multiple versions of documentation for MkDocs-powered sites. Deploy new versions, update aliases (like 'latest' or 'stable'), set the default version for the site root, and manage versioned subdirectories in the deployment branch. Use this whenever the user wants to publish, version, or alias documentation, even if they don't explicitly mention "mike". Also use this when the user wants to troubleshoot or debug versioned documentation.
+---
+
+# mike: MkDocs Versioning
+
+`mike` is used in this project to manage a versioned documentation site, allowing side-by-side availability of `dev` (main branch) and stable release docs (e.g., `0.1.4`).
+
+## Prerequisites
+
+`mike` is included in the `docs` dependency group.
+```bash
+# Sync documentation dependencies
+uv sync --group docs
+```
+
+## Project Strategy
+
+This project follows a specific versioning strategy:
+1.  **`dev`**: Represents the current `main` branch.
+2.  **Stable Releases**: Versioned documentation (e.g., `0.1.4`) created upon release.
+3.  **`stable`**: An alias always pointing to the most recent non-dev release.
+4.  **`latest`**: An alias pointing to the most recent release (including dev, if applicable).
+
+## Theme Overrides
+
+To support the version switcher and custom banners, the project uses a `custom_dir` override in `mkdocs.yml`:
+
+```yaml
+theme:
+  name: material
+  custom_dir: docs/overrides
+```
+
+### Version switcher
+
+The version switcher is enabled via `extra.version.provider: mike`:
+
+```yaml
+extra:
+  version:
+    provider: mike
+```
+
+## Versioning Banner
+
+A custom banner is displayed when users are viewing the `dev` documentation. This is handled via `docs/overrides/main.html` and `docs/overrides/partials/version_warning.html`.
+
+### How it works:
+-   `main.html`: Extends the base template and includes the `version_warning.html` partial at the start of the `content` block.
+-   `version_warning.html`: Contains an HTML snippet that is hidden by default and shown via JavaScript if the URL path contains `/dev/`.
+
+Example in `version_warning.html`:
+```html
+<div id="version-warning" style="display: none;">
+  <div class="admonition warning">
+    <p class="admonition-title">Warning</p>
+    <p>
+      You are viewing the documentation for the <strong>development</strong> version.
+      The latest stable release can be found at <a href="https://kilo59.github.io/ruff-sync/">kilo59.github.io/ruff-sync</a>.
+    </p>
+  </div>
+</div>
+<script>
+  (function() {
+    const version_warning = document.getElementById("version-warning");
+    if (!version_warning) return;
+
+    // mike provides a 'mike' object with some metadata if available
+    // Otherwise fall back to checking the pathname
+    const isDev = window.location.pathname.includes("/dev/") ||
+                 (window.mike && typeof window.mike.version === 'string' && window.mike.version === "dev");
+
+    if (isDev) {
+      version_warning.style.display = "block";
+    }
+  })();
+</script>
+```
+
+### 1. Deploying Development Docs
+Run this from the `main` branch to update the `dev` version:
+```bash
+mike deploy dev --push --update-aliases
+```
+
+### 2. Deploying a Stable Release
+When a new version is released (e.g., `0.1.4`), deploy it and update the `stable` alias:
+```bash
+# Deploy the specific version and update 'stable'
+mike deploy 0.1.4 stable --push --update-aliases
+
+# Set 'stable' as the default version for the site root
+mike set-default --push stable
+```
+
+## Reference Commands
+
+| Action | Command |
+| :--- | :--- |
+| **Deploy** | `mike deploy <version> [alias]` |
+| **List** | `mike list` |
+| **Set Default** | `mike set-default <version>` |
+| **Alias** | `mike alias <version> <alias>` |
+| **Delete** | `mike delete <identifier>` |
+
+## CI/CD Integration
+
+The deployment logic is automated in [.github/workflows/ci.yaml](.github/workflows/ci.yaml). It automatically:
+- Extracts the version from `pyproject.toml`.
+- Deploys to `dev` if the version contains `.dev`.
+- Deploys to `<version>` and updates `stable` for official releases.
+
+> [!IMPORTANT]
+> **Do NOT** use `mike install-gh-pages`. It is deprecated and removed in the version used by this project. `mike deploy` handles branch initialization automatically.
+
+> [!TIP]
+> Use `mike serve` locally to preview the version switcher before pushing changes.
+
+## Troubleshooting
+
+### Version Selector Not Appearing
+- **Missing `versions.json`**: Ensure `mike deploy` or `mike update-aliases` has been run. The file must exist at the site root.
+- **Incomplete `versions.json`**: If the current page's version (e.g., `stable`) is not listed in `versions.json`, some themes (like Material) may hide the selector.
+- **`site_url` Case Sensitivity**: On GitHub Pages, ensure `site_url` in `mkdocs.yml` matches the actual deployment URL (usually lowercase). Discrepancies can cause the switcher to fail to find `versions.json` due to 404s.
+- **Redundant Config**: Ensure `theme.version` is NOT set in `mkdocs.yml`. Use `extra.version.provider: mike` instead.
+- **`canonical_version` Missing**: If the switcher is hidden on the root page, adding `canonical_version: stable` (or your main alias) to the `mike` plugin configuration can help the theme associate the root with the switcher metadata.
+
+### 404 for `versions.json`
+- If you see a 404 for `/versions.json` but `https://<user>.github.io/<repo>/versions.json` exists, the switcher is looking at the domain root instead of the project root. Verify `site_url` includes the repository name and has a trailing slash.
+
+## Post-Mortem & Known Issues
+
+> [!CAUTION]
+> **Current Status**: Documentation versioning is currently **BROKEN** on the live site (`kilo59.github.io/ruff-sync`).
+
+### Failed Repair History
+The following fixes have been attempted and **FAILED** to resolve the issue:
+1.  **Lowercasing `site_url`**: Normalizing the repository name in the URL (e.g., `ruff-sync` instead of `Ruff-Sync`) did not fix the 404s for `versions.json`.
+2.  **Removing `theme.version`**: Removing the redundant Material 9.x config did not restore the switcher.
+3.  **Adding `canonical_version: stable`**: Adding this to the `mike` plugin in `mkdocs.yml` was intended to fix path resolution but has not fixed the root page 404.
+4.  **CI Restoration Logic**: Adding `mike alias --push stable stable` to the CI to manually repair `versions.json` hasn't restored the picker on the root page.
+
+### Root Cause Suspicions
+- **GitHub Pages Subfolder Pathing**: The site is served from a subfolder (`/ruff-sync/`). `mike`'s JavaScript for the version switcher frequently struggles with calculating relative paths to `versions.json` when served from a subfolder if `site_url` or base paths are not perfectly aligned with the deployment environment.
+- **`versions.json` Drift**: The `versions.json` file on the `gh-pages` branch frequently becomes desynchronized or loses the `stable` entry, which triggers `mkdocs-material` to hide the switcher entirely.
+
+### Guidance for Future Agents
+Before attempting another "fix," you **MUST** verify the current state of `versions.json` on the `gh-pages` branch and check the browser console on the live site for 404 paths. Do not assume standard configurations will work without manual verification of the deployed assets.

{ruff_sync-0.1.5.dev1 → ruff_sync-0.1.5.dev3}/.agents/skills/mkdocs-generation/templates/mkdocs.yml

@@ -10,10 +10,13 @@ repo_name: [GITHUB_USER]/[REPO_NAME]
 extra:
   version:
     provider: mike
-    default: latest
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/[GITHUB_USER]/[REPO_NAME]
 
 theme:
   name: material
+  custom_dir: docs/overrides
   features:
     - navigation.sections
     - navigation.top

ruff_sync-0.1.5.dev3/.agents/skills/textual/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: textual
+description: Build sophisticated Terminal User Interfaces (TUIs) in Python using an async, CSS-inspired framework.
+---
+
+# Textual TUI Framework (>=8.2.2)
+
+Textual is a Python framework for creating interactive, beautiful Terminal User Interfaces (TUIs). It uses an asynchronous engine and a layout system inspired by modern web development (Flexbox/Grid and CSS).
+
+## Quick Start
+
+```python
+from __future__ import annotations
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Static
+
+class SimpleApp(App[None]):
+    """A minimal Textual app."""
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("Hello, [bold blue]Textual[/bold blue]!")
+        yield Footer()
+
+if __name__ == "__main__":
+    SimpleApp().run()
+```
+
+## Core Workflow
+
+1. **`compose()`**: Define the UI structure by `yield`-ing widgets.
+2. **Styling**: Use **TCSS** (Textual Cascading Style Sheets) for layout and design.
+3. **Event Handlers**: Handle interaction via specially named methods (e.g., `on_button_pressed`).
+4. **Reactivity**: Use `reactive` attributes to automatically update the UI when data changes.
+
+## Progressive Disclosure (Detailed References)
+
+- [**Styling & Layout**](references/styling.md): TCSS, Flexbox, Grid, and Units.
+- [**Events & Reactivity**](references/events.md): Message passing, watchers, and state management.
+- [**Widget Library**](references/widgets.md): Common components (DataTable, Input, ListView).
+- [**Testing**](references/testing.md): Unit testing apps with `pilot` and `App.run_test`.
+
+## Gotchas & Breaking Changes (>=8.2.2)
+
+> [!WARNING]
+> - **8.2.2 Breaking Changes**:
+>   - `Static.renderable` and `Label.renderable` are now **`Static.content`** and **`Label.content`**.
+>   - `Select.BLANK` is now **`Select.NULL`**.
+> - **Fractional Units**: Use `fr` for fractional units (e.g. `width: 1fr`). A common typo is `rf`, which is invalid.
+> - **Async Handlers**: Event handlers can be `async def` or `def`. Use `async` if you need to `await` I/O or `post_message`.
+> - **Main Thread**: Do not block the main thread with long-running synchronous code. Use `self.run_worker()` for background tasks.

ruff_sync-0.1.5.dev3/.agents/skills/textual/examples/basic_app.py

@@ -0,0 +1,62 @@
+"""A minimal Textual app boilerplate."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from textual.app import App, ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Button, Footer, Header, Static
+
+
+class BasicApp(App[None]):
+    """A minimal Textual app boilerplate."""
+
+    # v8.x.x: Specify a default theme
+    theme: ClassVar[str] = "nord"
+
+    BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
+        ("q", "quit", "Quit application"),
+        ("d", "toggle_dark", "Toggle Dark Mode"),
+    ]
+
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+
+    Vertical {
+        width: 30;
+        height: auto;
+        border: solid $accent;
+        padding: 1;
+    }
+
+    Static {
+        text-align: center;
+        width: 100%;
+        margin-bottom: 1;
+    }
+
+    /* v8.x.x: New pointer rule */
+    Button {
+        pointer: pointer;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        """Compose the UI."""
+        yield Header()
+        with Vertical():
+            yield Static("Basic Textual App")
+            yield Button("Click Me!", id="hello-btn", variant="primary")
+        yield Footer()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button press events."""
+        if event.button.id == "hello-btn":
+            self.notify("Action Triggered!")
+
+
+if __name__ == "__main__":
+    BasicApp().run()

ruff_sync-0.1.5.dev3/.agents/skills/textual/examples/reactive_example.py

@@ -0,0 +1,51 @@
+"""Demonstrating Textual's reactive system."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.containers import Container
+from textual.reactive import reactive
+from textual.widgets import Footer, Header, Input, Static
+
+
+class ReactiveApp(App[None]):
+    """Demonstrating Textual's reactive system."""
+
+    # Reactive attribute: UI can respond to changes automatically
+    search_query: reactive[str] = reactive("")
+
+    CSS = """
+    #status {
+        background: $primary;
+        color: $text;
+        /* v8.x.x: Simplified padding for text content */
+        text-padding: 1 2;
+        margin-top: 1;
+        width: 100%;
+        text-align: center;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        """Compose the UI."""
+        yield Header()
+        with Container():
+            yield Input(placeholder="Type to search...", id="search-input")
+            yield Static("Waiting for input...", id="status")
+        yield Footer()
+
+    def watch_search_query(self, query: str) -> None:
+        """Called automatically when search_query changes."""
+        status = self.query_one("#status")
+        if query:
+            status.update(f"Searching for: [bold]{query}[/bold]")
+        else:
+            status.update("Waiting for input...")
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Update reactive state on input."""
+        self.search_query = event.value
+
+
+if __name__ == "__main__":
+    ReactiveApp().run()

ruff_sync-0.1.5.dev3/.agents/skills/textual/references/events.md

@@ -0,0 +1,84 @@
+# Events & Reactivity
+
+Textual uses a powerful event-driven architecture and a reactive state system to keep the UI in sync with your data.
+
+## Event Handlers
+
+Naming follows the convention: `on_<widget_name>_<event_type>`.
+
+```python
+class MySidebar(Vertical):
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle any button press within the sidebar."""
+        self.log(f"Button {event.button.id} was pressed!")
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Handle specifically an Input widget change."""
+        self.app.notify(f"Searching for: {event.value}")
+```
+
+## Theming (v8.x.x)
+
+Textual v8.x.x introduced a robust theming system.
+
+- **`App.theme`**: Set the active theme (e.g., `self.theme = "nord"`).
+- **`App.register_theme(theme)`**: Add custom themes to the app.
+- **`App.search_themes()`**: Bring up the theme switcher in the command palette.
+- **`variant`**: Use `Button(variant="primary")` or `Label(variant="warning")` for themed styles.
+
+## Reactive Attributes
+
+Define `reactive` attributes to automatically trigger updates. Use `watch_<attribute_name>` to side-effect when a value changes.
+
+```python
+from textual.reactive import reactive
+
+class Counter(Static):
+    # Reactive state: UI updates whenever 'count' is modified
+    count: reactive[int] = reactive(0)
+
+    def watch_count(self, old_value: int, new_value: int) -> None:
+        """Called automatically when count changes."""
+        self.update(f"Current Count: {new_value}")
+
+    def on_click(self) -> None:
+        self.count += 1
+```
+
+## Message Passing
+
+Widgets can communicate with parents via custom messages:
+
+1. **Define a Message**:
+   ```python
+   from textual.message import Message
+   class DataLoaded(Message):
+       def __init__(self, data: list[str]) -> None:
+           self.data = data
+           super().__init__()
+   ```
+2. **Post it**: `self.post_message(DataLoaded(my_data))`
+3. **Handle it in Parent**:
+   ```python
+   def on_data_loaded(self, event: DataLoaded) -> None:
+       self.query_one(DataTable).add_rows(event.data)
+   ```
+
+## Procedure: Implementing a Search Feature
+
+1. **Reactive Search Query**:
+   ```python
+   search_query: reactive[str] = reactive("")
+   ```
+2. **Watch the Query**:
+   ```python
+   def watch_search_query(self, query: str) -> None:
+       """Perform search whenever the query changes."""
+       results = self.search_database(query)
+       self.results_container.update_results(results)
+   ```
+3. **Bridge from UI**:
+   ```python
+   def on_input_changed(self, event: Input.Changed) -> None:
+       self.search_query = event.value
+   ```

ruff_sync-0.1.5.dev3/.agents/skills/textual/references/styling.md

@@ -0,0 +1,54 @@
+# Styling & Layout (TCSS)
+
+Textual uses **TCSS** (Textual Cascading Style Sheets) for design. It is similar to web CSS but optimized for the terminal grid.
+
+## Core Units
+
+- **`fr`**: Fractional units (e.g., `1fr`, `2fr`). Divides available space proportionally.
+- **`%`**: Percentage of the parent container's dimension.
+- **`vh` / `vw`**: Percentage of the entire terminal window height/width.
+- **Integers**: Represent exact terminal character cells (e.g., `width: 20;`).
+
+- **`Vertical`**: Stack widgets top-to-bottom.
+- **`Horizontal`**: Align widgets left-to-right.
+- **`Grid`**: A flexible 2D grid layout. Define `grid-size`, `grid-columns`, and `grid-rows`.
+
+## New CSS Rules (v8.x.x)
+
+- **`pointer`**: Change the mouse cursor style (e.g., `pointer: pointer;`, `pointer: text;`).
+- **`background-tint`**: Apply a translucent color over the background (e.g., `background-tint: $primary 20%;`).
+- **`text-padding`**: Simplified padding for text content within a widget (e.g., `text-padding: 1 2;`).
+- **`scroll-bar-visibility`**: Control when scrollbars are shown (`auto`, `visible`, `hidden`).
+- **`position`**: Support for `relative` and `absolute` positioning.
+
+## Procedure: Rapid Styling
+
+1. **Assign IDs or Classes**:
+   ```python
+   yield Button("Save", id="save-btn", classes="primary-action")
+   ```
+2. **Define TCSS**:
+   ```css
+   .primary-action {
+       background: $accent;
+       color: $text;
+       text-style: bold;
+       width: 100%;
+   }
+
+   #save-btn {
+       border: heavy $success;
+   }
+   ```
+3. **Reference CSS in App**:
+   ```python
+   class MyApp(App):
+       CSS_PATH = "styles.tcss"  # Relative to the Python file
+   ```
+
+## Built-in Design System
+
+Textual includes a set of semantic variables (`$primary`, `$secondary`, `$accent`, `$error`, `$success`) that automatically adapt to the user's terminal theme.
+
+> [!TIP]
+> Use `textual console` or `textual run --dev` to see live styling updates without restarting the application.

ruff_sync-0.1.5.dev3/.agents/skills/textual/references/testing.md

@@ -0,0 +1,58 @@
+# Testing & Debugging
+
+Textual apps are inherently asynchronous. Testing requires simulating user input and observing the UI state.
+
+## Unit Testing with Pilot
+
+Use the `pilot` object to interact with your app in a headless state.
+
+```python
+import pytest
+from my_app import SimpleApp
+
+@pytest.mark.asyncio
+async def test_button_click():
+    app = SimpleApp()
+    async with app.run_test() as pilot:
+        # Simulate a button click by CSS selector or ID
+        await pilot.click("#say-hello-btn")
+
+        # New in v8.x.x: Rapid clicks (double click)
+        await pilot.click("#say-hello-btn", times=2)
+        # OR use dedicated methods:
+        await pilot.double_click("#say-hello-btn")
+        await pilot.triple_click("#say-hello-btn")
+
+        # Verify state
+        assert app.notification_count >= 1
+```
+
+## Developer Tools
+
+Textual includes powerful tools for live development.
+
+### Textual Devtools
+In one terminal, run:
+```bash
+textual console
+```
+In another, run your app with the `--dev` flag:
+```bash
+textual run --dev my_app.py
+```
+Logs and tracebacks will stream to the console, allowing you to see `self.log()` output and `print()` statements without breaking the UI.
+
+## Procedures
+
+### Simulating Text Entry
+```python
+async with app.run_test() as pilot:
+    await pilot.press("h", "e", "l", "l", "o", "enter")
+    assert app.query_one(Input).value == "hello"
+```
+
+### Waiting for Animations/I/O
+If your UI has transitions or performs background work, use `pilot.wait_for_scheduled_animations()` or simply `await pilot.pause(0.1)`.
+
+> [!IMPORTANT]
+> Always use `pytest-asyncio` with the `@pytest.mark.asyncio` decorator for Textual tests. The boilerplate provided in `app.run_test()` handles the event loop lifecycle for you.

ruff_sync-0.1.5.dev3/.agents/skills/textual/references/widgets.md

@@ -0,0 +1,85 @@
+# Widget Library
+
+Textual includes a rich set of built-in widgets. Always check `textual.widgets` before building your own.
+
+## Content & Navigation
+
+- **`Header`**: Standard title bar with optional clock.
+- **`Footer`**: Keybinding bar (automatically populated from `BINDINGS`).
+- **`Static`**: Pure text or basic content. Use **`content`** (v8.x.x) for raw renderable or `markup=True`.
+- **`Link`**: (v8.x.x) New widget for clickable URLs.
+- **`ProgressBar`**: Real-time progress tracking.
+
+## Interaction
+
+- **`Button`**: Standard clickable button. Variants: `success`, `error`, `primary`, `warning`.
+- **`Input`**: Text entry field. Events: `Changed`, `Submitted`.
+- **`MaskedInput`**: (v8.x.x) New widget for formatted inputs (e.g. phones, CC, etc.).
+- **`Checkbox`** / **`Switch`**: Boolean state inputs.
+- **`Select`**: Dropdown selection. Sentinel: **`Select.NULL`** (v8.x.x).
+
+## Data & Selection
+
+### `DataTable`
+High-performance grid for tabular data.
+
+```python
+table = self.query_one(DataTable)
+table.add_columns("ID", "Name", "Score")
+table.add_row("1", "Alice", "100")
+```
+
+### `ListView` & `ListItem`
+Scrollable lists of items.
+
+```python
+list_view = self.query_one(ListView)
+list_view.append(ListItem(Static("Item One")))
+```
+
+## Procedures
+
+### Adding Data to a Table
+
+1. **Clear existing rows**: `table.clear()`
+2. **Batch add rows**: `table.add_rows(data_generator_or_list)`
+3. **Control selection**: `table.cursor_type = "row"` (default is `"cell"`)
+
+### Handling Keyboard Input
+
+Use the `on_key` handler for low-level input:
+
+```python
+def on_key(self, event: events.Key) -> None:
+    if event.key == "ctrl+s":
+        self.save_data()
+```
+
+> [!TIP]
+> Use `BINDINGS` in your `App` or `Screen` class for most navigation tasks. Textual manages the labels and shortcuts in the `Footer` for you.
+
+### `ModalScreen` & Overlays
+Modals are screens with a transparent or dim background that overlay the main app.
+```python
+from textual.screen import ModalScreen
+from textual.app import App
+
+class OmniboxScreen(ModalScreen[str]):
+    # A modal screen that returns a `str` when dismissed.
+    def compose(self) -> ComposeResult:
+        # yield your input/search widgets here
+        yield Input(placeholder="Search...")
+
+    # Dismiss the screen and return data
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self.dismiss(event.value)
+
+# In the main App or Screen:
+def on_key(self, event: events.Key) -> None:
+    if event.key == "ctrl+p":
+        self.push_screen(OmniboxScreen(), self.handle_omnibox_result)
+
+def handle_omnibox_result(self, result: str | None) -> None:
+    if result:
+        print(f"Selected: {result}")
+```