bootstack 0.2.2__tar.gz → 0.2.3__tar.gz

bootstack-0.2.3/NOTICE

@@ -0,0 +1,30 @@
+bootstack
+Copyright (c) 2021 - 2026 Israel Dryer
+
+This project is derived from ttkbootstrap
+(https://github.com/israel-dryer/ttkbootstrap),
+Copyright (c) 2021 - 2026 Israel Dryer and ttkbootstrap contributors,
+licensed under the MIT License.
+
+The original ttkbootstrap license and copyright notice are preserved above
+in compliance with the MIT License terms.
+
+This project also contains code derived from IDLE, part of the CPython
+standard library (https://github.com/python/cpython),
+Copyright (c) 2001-2023 Python Software Foundation; All Rights Reserved,
+licensed under the Python Software Foundation License Agreement, Version 2.
+
+  src/bootstack/widgets/_impl/composites/textarea/redirector.py
+
+is a port of idlelib/redirector.py, carrying its WidgetRedirector and
+OriginalCommand classes and their dispatch logic. Summary of the changes made,
+as the Python Software Foundation License Agreement asks for: the
+OriginalCommand interface was narrowed to three private attributes,
+WidgetRedirector.__repr__ was dropped, the operation name is coerced to a
+string before lookup, the widget reference is retained after close() rather
+than deleted, and type hints and rewritten documentation were added.
+
+Other modules in the same package implement designs described in IDLE — the
+Delegator and Percolator chain, UndoDelegator, the editor sidebar, and
+parenmatch's flash-and-restore highlighting — but share no substantial code
+with it and are original implementations.

{bootstack-0.2.2/src/bootstack.egg-info → bootstack-0.2.3}/PKG-INFO

@@ -1,302 +1,302 @@
-Metadata-Version: 2.4
-Name: bootstack
-Version: 0.2.2
-Summary: Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate.
-Author-email: Israel Dryer <israel.dryer@gmail.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/israel-dryer/bootstack
-Project-URL: Documentation, https://bootstack.org/
-Keywords: tkinter,ttk,gui,desktop,python3,ui,widgets,theming,cross-platform,modern,framework,application-framework,desktop-ui,python-gui
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Win32 (MS Windows)
-Classifier: Environment :: MacOS X
-Classifier: Environment :: X11 Applications
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: User Interfaces
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: pillow<=12,>=10
-Requires-Dist: pygments>=2.15
-Requires-Dist: typing-extensions>=4.10
-Requires-Dist: Babel>=2.12
-Requires-Dist: python-dateutil>=2.9
-Requires-Dist: dateparser>=1.1
-Requires-Dist: pywinstyles>=1.8; sys_platform == "win32"
-Requires-Dist: screeninfo>=0.8
-Provides-Extra: excel
-Requires-Dist: XlsxWriter>=3; extra == "excel"
-Provides-Extra: parquet
-Requires-Dist: pyarrow>=14; extra == "parquet"
-Provides-Extra: hdf5
-Requires-Dist: pandas>=2; extra == "hdf5"
-Requires-Dist: tables>=3.8; extra == "hdf5"
-Provides-Extra: viz
-Requires-Dist: matplotlib>=3.8; extra == "viz"
-Provides-Extra: viz-seaborn
-Requires-Dist: matplotlib>=3.8; extra == "viz-seaborn"
-Requires-Dist: seaborn>=0.13; extra == "viz-seaborn"
-Provides-Extra: docs
-Requires-Dist: sphinx>=7.2; extra == "docs"
-Requires-Dist: pydata-sphinx-theme; extra == "docs"
-Requires-Dist: sphinx-design; extra == "docs"
-Requires-Dist: sphinx-copybutton; extra == "docs"
-Requires-Dist: sphinx-autobuild; extra == "docs"
-Requires-Dist: myst-parser; extra == "docs"
-Dynamic: license-file
-
-![bootstack](https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/banner-readme.png)
-
-![](https://img.shields.io/github/release/israel-dryer/bootstack.svg)
-[![Downloads](https://pepy.tech/badge/bootstack)](https://pepy.tech/project/bootstack)
-[![Downloads](https://pepy.tech/badge/bootstack/month)](https://pepy.tech/project/bootstack)
-![](https://img.shields.io/github/issues/israel-dryer/bootstack.svg)
-![](https://img.shields.io/github/issues-closed/israel-dryer/bootstack.svg)
-![](https://img.shields.io/github/license/israel-dryer/bootstack.svg)
-![](https://img.shields.io/github/stars/israel-dryer/bootstack.svg)
-![](https://img.shields.io/github/forks/israel-dryer/bootstack.svg)
-
-> Full documentation is at **[bootstack.org](https://bootstack.org)**.
-
-### Desktop apps in pure Python — Tk underneath, none of the boilerplate.
-
-bootstack is built on Tk, so the install is light and your app ships as a small standalone executable. But you'll never
-write a `StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state, and a CLI that scaffolds and
-packages the whole thing.
-
-<p align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/hero-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/hero-light.png">
-  <img alt="bootstack hero demo" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/hero-light.png">
-</picture>
-</p>
-
-## Why bootstack?
-
-Most Python desktop frameworks make you fight the framework. bootstack gets out of the way.
-
-- **30% less code** — the declarative, context-manager layout eliminates geometry calls, explicit parenting, and most of the wiring boilerplate
-- **Reads like Python** — nested `with` blocks mirror your UI structure; the code hierarchy *is* the layout
-- **Modern layout system** — `Row`, `Column`, and `Grid` containers handle spacing, alignment, and growth automatically; a screen-axis vocabulary (`gap`, `padding`, `margin`, `horizontal`, `vertical`, `grow`) without writing CSS
-- **60+ widgets out of the box** — primitives through full composites: tables, trees, calendars, date pickers, gauges, sliders, and more — including a full `CodeEditor` with syntax highlighting, line numbers, bracket matching, smart indent, and search; no external editor dependency required
-- **Reactive signals** — observable state that flows between widgets; bind once, update everywhere
-- **Event and stream pipelines** — compose, filter, debounce, and throttle UI events with a chainable stream API
-- **Built-in icons** — the full Bootstrap Icons catalog, theme-aware and recolorable, bundled with the framework
-- **Built-in localization** — 23 language catalogs, locale-aware number/date/time formatting, runtime language switching
-- **Semantic styling** — `accent="primary"`, `variant="outline"` — no hard-coded colors; looks right across every theme automatically
-- **10 paired light/dark themes** — popular dev color schemes plus Bootstrap, with a runtime switcher and a custom-theme API
-- **Forms and validation** — field-level validators, inline error messages, and a `FormDialog` for quick modal forms
-- **DataSource abstraction** — one interface over SQLite, in-memory, and file backends with filtering, sorting, pagination, and CRUD
-- **Data visualization** — embed `matplotlib` (and `seaborn`) figures with `Chart`; they recolor with the theme and live-update from a `Signal` or `DataSource` (optional `viz` extra)
-- **A real CLI** — scaffold, run, add pages/views/dialogs/themes, and package for distribution
-- **Hot reload** — `bootstack dev app.py` updates the running app on save and keeps your place; module-level state and the active page survive the reload
-- **PyInstaller packaging built in** — `bootstack build` produces a standalone executable; no separate toolchain required
-
-## Hot reload
-
-Edit and save — the running window updates in place. `bootstack dev app.py`
-reloads the UI on every save while keeping your window position, module-level
-state, and active page, so you never lose your spot.
-
-<p align="center">
-<video src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/docs/_static/examples/live-reload.mp4" controls muted loop playsinline></video>
-</p>
-
-## Installation
-
-Requires Python 3.12+ and Tk/Tcl (bundled with most Python distributions).
-Install with pip:
-
-```bash
-python -m pip install bootstack
-```
-
-See the [installation guide](https://bootstack.org/getting-started/installation/)
-for platform-specific Tk setup and the optional data-format extras.
-
-## See it
-
-The widget gallery is a single-window tour of everything bootstack ships — every widget, theme switcher, accent variants, and layout containers. Fastest way to see the framework in action without writing a line of code:
-
-```bash
-bootstack gallery
-```
-
-<p align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/gallery-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/gallery-light.png">
-  <img alt="bootstack widget gallery" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/gallery-light.png">
-</picture>
-</p>
-
-## Quick Start
-
-```python
-import bootstack as bs
-
-with bs.App(title="Hello", padding=16, gap=16) as app:
-    bs.Label("Hello from bootstack!")
-    bs.Button("Primary", accent="primary")
-    bs.Button("Success", accent="success")
-    bs.Button("Danger Outline", accent="danger", variant="outline")
-
-app.run()
-```
-
-<p align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-quickstart-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-quickstart-light.png">
-  <img alt="bootstack quick start example" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-quickstart-light.png">
-</picture>
-</p>
-
-For navigation-based apps, use `AppShell` — it gives you stacked toolbars, a sidebar, and a page stack in one call:
-
-```python
-import bootstack as bs
-
-shell = bs.AppShell(title="My App", size=(1000, 650))
-
-with shell.page_nav() as nav:
-    with nav.add_page("home", text="Home", icon="house"):
-        bs.Label("Welcome!")
-    with nav.add_page("docs", text="Documents", icon="file-earmark-text"):
-        bs.Label("Your documents.")
-
-shell.run()
-```
-
-## How it works
-
-### Layout containers
-
-`Column`, `Row`, and `Grid` let you describe a layout once instead of repeating geometry calls on each child:
-
-```python
-with bs.App(title="Sign In") as app:
-    with bs.Grid(columns=["auto", 1], gap=(12, 6), horizontal_items="stretch", padding=16):
-        bs.Label("Name:")
-        bs.TextField(placeholder="Full name")
-        bs.Label("Email:")
-        bs.TextField(placeholder="email@example.com")
-        bs.Label("Role:")
-        bs.Select(options=["Admin", "User", "Viewer"], value="User")
-        bs.Button("Submit", accent="primary", columnspan=2)
-
-app.run()
-```
-
-<p align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-layout-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-layout-light.png">
-  <img alt="bootstack layout containers example" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-layout-light.png">
-</picture>
-</p>
-
-### Semantic styling
-
-Widgets take an `accent` (color intent) and `variant` (visual weight) instead of hard-coded colors, so the same code looks right across themes and light/dark modes:
-
-```python
-bs.Button("Save", accent="primary")
-bs.Button("Cancel", accent="secondary", variant="outline")
-bs.Label("Heading", font="heading-lg")
-```
-
-<p align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-semantic-styling-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-semantic-styling-light.png">
-  <img alt="bootstack semantic styling example" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-semantic-styling-light.png">
-</picture>
-</p>
-
-### Signals (optional)
-
-Plain callbacks work fine for most things. When state needs to flow between widgets, signals give you a small reactive primitive with two-way binding:
-
-```python
-with bs.App(title="Hello") as app:
-    name = bs.Signal("World")
-    bs.Label(textsignal=name)      # updates automatically when name changes
-    bs.TextField(textsignal=name)  # two-way binding to the same state
-
-app.run()
-```
-
-## Features
-
-- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, `Workbench` for two-tier workspace apps, `Splash` for a startup intro screen, undecorated windows with custom chrome
-- **60+ themed widgets** — primitives plus higher-level composites (DataTable, Tree, ListView, Calendar, DateField, Form, Gauge, ToggleGroup, PageStack, Carousel, Tooltip, and more)
-- **Dialogs and messages** — `alert()` / `confirm()` / `ask_*()` prompts and `FormDialog` / `FontDialog` / `FilterDialog`, plus non-blocking `toast()`, `Notification`, and `Snackbar` surfaces
-- **Layout containers** — `Column`, `Row`, `Grid`, and `Spacer` for declarative layouts; `Card`, `GroupBox`, `ScrollView`, `SplitView`, `Accordion`, `Divider`
-- **Design system** — semantic `accent` colors (primary, secondary, success, danger, warning, info) and `variant` tokens (solid, outline, ghost), consistent across widgets
-- **Built-in themes** — 10 paired light/dark variants (bootstrap, catppuccin, dracula, everforest, gruvbox, nord, one, pydata, solarized, tokyo-night) with runtime theme switching and a custom-theme API
-- **Reactive signals** — observable state with subscribe/set, integrates with widgets via `signal=` / `textsignal=`
-- **Forms & validation** — `Form` with built-in field-level validators and inline error messages
-- **DataSource** — common interface over in-memory, SQLite, and file backends, with pagination, filtering, sorting, CRUD, and CSV/TSV/Excel export
-- **Data visualization** — `Chart` embeds `matplotlib`/`seaborn` figures that theme themselves and live-update from a `Signal` or `DataSource`; managed render, blitting animation, and a themed navigation toolbar (optional `viz` / `viz-seaborn` extras)
-- **Localization (i18n)** — 23 bundled message catalogs, locale-aware number/date/time formatting via Babel, runtime language switching
-- **Icons & images** — Bootstrap Icons catalog with theme-aware recoloring and caching
-- **Platform support** — DPI awareness, multi-monitor centering, mica/acrylic effects on Windows
-- **CLI (`bootstack`)** — project scaffolding, run, add components, theme/i18n setup, doctor, build/package
-
-## Widget Categories
-
-| Category | Widgets |
-|----------|---------|
-| **Actions** | Button, ButtonGroup, MenuButton, ContextMenu, Toolbar, ThemeToggle |
-| **Inputs** | TextField, PasswordField, PathField, NumberField, SpinnerField, Slider, RangeSlider, TextArea, CodeEditor, DateField, TimeField |
-| **Selection** | Checkbox, Switch, ToggleButton, Radio, RadioGroup, ToggleGroup, Select, SelectButton, Calendar |
-| **Data Display** | Label, Badge, ListView, Tree, DataTable, ProgressBar, Gauge |
-| **Media** | Avatar, Picture, Gallery, Carousel |
-| **Layout** | Column, Row, Grid, Spacer, Card, GroupBox, SplitView, ScrollView, Accordion, Divider |
-| **Navigation** | AppShell, Workbench, Window, Splash, StatusBar, Tabs, PageStack |
-| **Dialogs** | `alert()`, `confirm()`, `ask_*()` prompts, FormDialog, FontDialog, FilterDialog |
-| **Overlays** | `toast()`, Notification, Snackbar, Tooltip |
-| **Forms** | Form, with field-level validation |
-
-## CLI
-
-bootstack ships with an optional CLI for scaffolding, running, and packaging applications:
-
-```bash
-bootstack gallery                           # Launch the interactive widget gallery
-bootstack icons                             # Browse the built-in icon catalog
-bootstack appicon                           # Design an app icon and export it
-bootstack start MyApp                       # Create a new project (basic template)
-bootstack start MyApp --template appshell   # ...or with sidebar navigation
-bootstack run                               # Run the app defined in the project config
-bootstack dev app.py                        # Run with hot reload (live edit-and-save)
-bootstack add page Dashboard                # Add a new page (appshell)
-bootstack add view Settings                 # Add a new view (basic)
-bootstack add dialog Preferences            # Add a new dialog
-bootstack doctor                            # Diagnose project & environment
-bootstack promote                           # Make the project packaging-ready
-bootstack build                             # Package for distribution
-```
-
-## Documentation
-
-Full documentation — guides, the widget catalog, and the API reference — lives at
-**[bootstack.org](https://bootstack.org)**.
-
-## Contributing
-
-Contributions are welcome — code, bug reports, and especially **translations**.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the pull-request
-workflow, and how to review the bundled language catalogs.
-
-## Links
-
-- **GitHub**: https://github.com/israel-dryer/bootstack
+Metadata-Version: 2.4
+Name: bootstack
+Version: 0.2.3
+Summary: Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate.
+Author-email: Israel Dryer <israel.dryer@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/israel-dryer/bootstack
+Project-URL: Documentation, https://bootstack.org/
+Keywords: tkinter,ttk,gui,desktop,python3,ui,widgets,theming,cross-platform,modern,framework,application-framework,desktop-ui,python-gui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: MacOS X
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pillow<=12,>=10
+Requires-Dist: pygments>=2.15
+Requires-Dist: typing-extensions>=4.10
+Requires-Dist: Babel>=2.12
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: dateparser>=1.1
+Requires-Dist: pywinstyles>=1.8; sys_platform == "win32"
+Requires-Dist: screeninfo>=0.8
+Provides-Extra: excel
+Requires-Dist: XlsxWriter>=3; extra == "excel"
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14; extra == "parquet"
+Provides-Extra: hdf5
+Requires-Dist: pandas>=2; extra == "hdf5"
+Requires-Dist: tables>=3.8; extra == "hdf5"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == "viz"
+Provides-Extra: viz-seaborn
+Requires-Dist: matplotlib>=3.8; extra == "viz-seaborn"
+Requires-Dist: seaborn>=0.13; extra == "viz-seaborn"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Dynamic: license-file
+
+![bootstack](https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/banner-readme.png)
+
+![](https://img.shields.io/github/release/israel-dryer/bootstack.svg)
+[![Downloads](https://pepy.tech/badge/bootstack)](https://pepy.tech/project/bootstack)
+[![Downloads](https://pepy.tech/badge/bootstack/month)](https://pepy.tech/project/bootstack)
+![](https://img.shields.io/github/issues/israel-dryer/bootstack.svg)
+![](https://img.shields.io/github/issues-closed/israel-dryer/bootstack.svg)
+![](https://img.shields.io/github/license/israel-dryer/bootstack.svg)
+![](https://img.shields.io/github/stars/israel-dryer/bootstack.svg)
+![](https://img.shields.io/github/forks/israel-dryer/bootstack.svg)
+
+> Full documentation is at **[bootstack.org](https://bootstack.org)**.
+
+### Desktop apps in pure Python — Tk underneath, none of the boilerplate.
+
+bootstack is built on Tk, so the install is light and your app ships as a small standalone executable. But you'll never
+write a `StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state, and a CLI that scaffolds and
+packages the whole thing.
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/hero-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/hero-light.png">
+  <img alt="bootstack hero demo" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/hero-light.png">
+</picture>
+</p>
+
+## Why bootstack?
+
+Most Python desktop frameworks make you fight the framework. bootstack gets out of the way.
+
+- **30% less code** — the declarative, context-manager layout eliminates geometry calls, explicit parenting, and most of the wiring boilerplate
+- **Reads like Python** — nested `with` blocks mirror your UI structure; the code hierarchy *is* the layout
+- **Modern layout system** — `Row`, `Column`, and `Grid` containers handle spacing, alignment, and growth automatically; a screen-axis vocabulary (`gap`, `padding`, `margin`, `horizontal`, `vertical`, `grow`) without writing CSS
+- **60+ widgets out of the box** — primitives through full composites: tables, trees, calendars, date pickers, gauges, sliders, and more — including a full `CodeEditor` with syntax highlighting, line numbers, bracket matching, smart indent, and search; no external editor dependency required
+- **Reactive signals** — observable state that flows between widgets; bind once, update everywhere
+- **Event and stream pipelines** — compose, filter, debounce, and throttle UI events with a chainable stream API
+- **Built-in icons** — the full Bootstrap Icons catalog, theme-aware and recolorable, bundled with the framework
+- **Built-in localization** — 23 language catalogs, locale-aware number/date/time formatting, runtime language switching
+- **Semantic styling** — `accent="primary"`, `variant="outline"` — no hard-coded colors; looks right across every theme automatically
+- **10 paired light/dark themes** — popular dev color schemes plus Bootstrap, with a runtime switcher and a custom-theme API
+- **Forms and validation** — field-level validators, inline error messages, and a `FormDialog` for quick modal forms
+- **DataSource abstraction** — one interface over SQLite, in-memory, and file backends with filtering, sorting, pagination, and CRUD
+- **Data visualization** — embed `matplotlib` (and `seaborn`) figures with `Chart`; they recolor with the theme and live-update from a `Signal` or `DataSource` (optional `viz` extra)
+- **A real CLI** — scaffold, run, add pages/views/dialogs/themes, and package for distribution
+- **Hot reload** — `bootstack dev app.py` updates the running app on save and keeps your place; module-level state and the active page survive the reload
+- **PyInstaller packaging built in** — `bootstack build` produces a standalone executable; no separate toolchain required
+
+## Hot reload
+
+Edit and save — the running window updates in place. `bootstack dev app.py`
+reloads the UI on every save while keeping your window position, module-level
+state, and active page, so you never lose your spot.
+
+<p align="center">
+<video src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/docs/_static/examples/live-reload.mp4" controls muted loop playsinline></video>
+</p>
+
+## Installation
+
+Requires Python 3.12+ and Tk/Tcl (bundled with most Python distributions).
+Install with pip:
+
+```bash
+python -m pip install bootstack
+```
+
+See the [installation guide](https://bootstack.org/getting-started/installation/)
+for platform-specific Tk setup and the optional data-format extras.
+
+## See it
+
+The widget gallery is a single-window tour of everything bootstack ships — every widget, theme switcher, accent variants, and layout containers. Fastest way to see the framework in action without writing a line of code:
+
+```bash
+bootstack gallery
+```
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/gallery-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/gallery-light.png">
+  <img alt="bootstack widget gallery" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/gallery-light.png">
+</picture>
+</p>
+
+## Quick Start
+
+```python
+import bootstack as bs
+
+with bs.App(title="Hello", padding=16, gap=16) as app:
+    bs.Label("Hello from bootstack!")
+    bs.Button("Primary", accent="primary")
+    bs.Button("Success", accent="success")
+    bs.Button("Danger Outline", accent="danger", variant="outline")
+
+app.run()
+```
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-quickstart-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-quickstart-light.png">
+  <img alt="bootstack quick start example" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-quickstart-light.png">
+</picture>
+</p>
+
+For navigation-based apps, use `AppShell` — it gives you stacked toolbars, a sidebar, and a page stack in one call:
+
+```python
+import bootstack as bs
+
+shell = bs.AppShell(title="My App", size=(1000, 650))
+
+with shell.page_nav() as nav:
+    with nav.add_page("home", text="Home", icon="house"):
+        bs.Label("Welcome!")
+    with nav.add_page("docs", text="Documents", icon="file-earmark-text"):
+        bs.Label("Your documents.")
+
+shell.run()
+```
+
+## How it works
+
+### Layout containers
+
+`Column`, `Row`, and `Grid` let you describe a layout once instead of repeating geometry calls on each child:
+
+```python
+with bs.App(title="Sign In") as app:
+    with bs.Grid(columns=["auto", 1], gap=(12, 6), horizontal_items="stretch", padding=16):
+        bs.Label("Name:")
+        bs.TextField(placeholder="Full name")
+        bs.Label("Email:")
+        bs.TextField(placeholder="email@example.com")
+        bs.Label("Role:")
+        bs.Select(options=["Admin", "User", "Viewer"], value="User")
+        bs.Button("Submit", accent="primary", columnspan=2)
+
+app.run()
+```
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-layout-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-layout-light.png">
+  <img alt="bootstack layout containers example" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-layout-light.png">
+</picture>
+</p>
+
+### Semantic styling
+
+Widgets take an `accent` (color intent) and `variant` (visual weight) instead of hard-coded colors, so the same code looks right across themes and light/dark modes:
+
+```python
+bs.Button("Save", accent="primary")
+bs.Button("Cancel", accent="secondary", variant="outline")
+bs.Label("Heading", font="heading-lg")
+```
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-semantic-styling-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-semantic-styling-light.png">
+  <img alt="bootstack semantic styling example" src="https://raw.githubusercontent.com/israel-dryer/bootstack/main/assets/readme/ex-semantic-styling-light.png">
+</picture>
+</p>
+
+### Signals (optional)
+
+Plain callbacks work fine for most things. When state needs to flow between widgets, signals give you a small reactive primitive with two-way binding:
+
+```python
+with bs.App(title="Hello") as app:
+    name = bs.Signal("World")
+    bs.Label(textsignal=name)      # updates automatically when name changes
+    bs.TextField(textsignal=name)  # two-way binding to the same state
+
+app.run()
+```
+
+## Features
+
+- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, `Workbench` for two-tier workspace apps, `Splash` for a startup intro screen, undecorated windows with custom chrome
+- **60+ themed widgets** — primitives plus higher-level composites (DataTable, Tree, ListView, Calendar, DateField, Form, Gauge, ToggleGroup, PageStack, Carousel, Tooltip, and more)
+- **Dialogs and messages** — `alert()` / `confirm()` / `ask_*()` prompts and `FormDialog` / `FontDialog` / `FilterDialog`, plus non-blocking `toast()`, `Notification`, and `Snackbar` surfaces
+- **Layout containers** — `Column`, `Row`, `Grid`, and `Spacer` for declarative layouts; `Card`, `GroupBox`, `ScrollView`, `SplitView`, `Accordion`, `Divider`
+- **Design system** — semantic `accent` colors (primary, secondary, success, danger, warning, info) and `variant` tokens (solid, outline, ghost), consistent across widgets
+- **Built-in themes** — 10 paired light/dark variants (bootstrap, catppuccin, dracula, everforest, gruvbox, nord, one, pydata, solarized, tokyo-night) with runtime theme switching and a custom-theme API
+- **Reactive signals** — observable state with subscribe/set, integrates with widgets via `signal=` / `textsignal=`
+- **Forms & validation** — `Form` with built-in field-level validators and inline error messages
+- **DataSource** — common interface over in-memory, SQLite, and file backends, with pagination, filtering, sorting, CRUD, and CSV/TSV/Excel export
+- **Data visualization** — `Chart` embeds `matplotlib`/`seaborn` figures that theme themselves and live-update from a `Signal` or `DataSource`; managed render, blitting animation, and a themed navigation toolbar (optional `viz` / `viz-seaborn` extras)
+- **Localization (i18n)** — 23 bundled message catalogs, locale-aware number/date/time formatting via Babel, runtime language switching
+- **Icons & images** — Bootstrap Icons catalog with theme-aware recoloring and caching
+- **Platform support** — DPI awareness, multi-monitor centering, mica/acrylic effects on Windows
+- **CLI (`bootstack`)** — project scaffolding, run, add components, theme/i18n setup, doctor, build/package
+
+## Widget Categories
+
+| Category | Widgets |
+|----------|---------|
+| **Actions** | Button, ButtonGroup, MenuButton, ContextMenu, Toolbar, ThemeToggle |
+| **Inputs** | TextField, PasswordField, PathField, NumberField, SpinnerField, Slider, RangeSlider, TextArea, CodeEditor, DateField, TimeField |
+| **Selection** | Checkbox, Switch, ToggleButton, Radio, RadioGroup, ToggleGroup, Select, SelectButton, Calendar |
+| **Data Display** | Label, Badge, ListView, Tree, DataTable, ProgressBar, Gauge |
+| **Media** | Avatar, Picture, Gallery, Carousel |
+| **Layout** | Column, Row, Grid, Spacer, Card, GroupBox, SplitView, ScrollView, Accordion, Divider |
+| **Navigation** | AppShell, Workbench, Window, Splash, StatusBar, Tabs, PageStack |
+| **Dialogs** | `alert()`, `confirm()`, `ask_*()` prompts, FormDialog, FontDialog, FilterDialog |
+| **Overlays** | `toast()`, Notification, Snackbar, Tooltip |
+| **Forms** | Form, with field-level validation |
+
+## CLI
+
+bootstack ships with an optional CLI for scaffolding, running, and packaging applications:
+
+```bash
+bootstack gallery                           # Launch the interactive widget gallery
+bootstack icons                             # Browse the built-in icon catalog
+bootstack appicon                           # Design an app icon and export it
+bootstack start MyApp                       # Create a new project (basic template)
+bootstack start MyApp --template appshell   # ...or with sidebar navigation
+bootstack run                               # Run the app defined in the project config
+bootstack dev app.py                        # Run with hot reload (live edit-and-save)
+bootstack add page Dashboard                # Add a new page (appshell)
+bootstack add view Settings                 # Add a new view (basic)
+bootstack add dialog Preferences            # Add a new dialog
+bootstack doctor                            # Diagnose project & environment
+bootstack promote                           # Make the project packaging-ready
+bootstack build                             # Package for distribution
+```
+
+## Documentation
+
+Full documentation — guides, the widget catalog, and the API reference — lives at
+**[bootstack.org](https://bootstack.org)**.
+
+## Contributing
+
+Contributions are welcome — code, bug reports, and especially **translations**.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the pull-request
+workflow, and how to review the bundled language catalogs.
+
+## Links
+
+- **GitHub**: https://github.com/israel-dryer/bootstack