CTkKanBan 1.0.0__tar.gz

ctkkanban-1.0.0/.gitattributes

@@ -0,0 +1,18 @@
+* text=auto
+
+.gitattributes text eol=lf
+.gitignore text eol=lf
+MANIFEST.in text eol=lf
+*.css text eol=lf
+*.html text eol=lf
+*.ini text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.py text eol=lf
+*.toml text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+
+*.ico binary
+*.png binary

ctkkanban-1.0.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## Unreleased
+
+## 1.0.0 - 2026-07-24
+
+- Added live, field-aware editing inside default cards, including empty-field placeholders, typed controls, keyboard save/cancel behavior, validation feedback, and persistence through the normal card update pipeline.
+- Added `enable_inline_card_editing` and `start_inline_card_edit()` while retaining the explicit popup and side-panel form APIs for compatibility.
+- Kept invalid inline edits from triggering release-driven host controls under CustomTkinter 6 while preserving CustomTkinter 5 behavior.
+
+## 0.3.0 - 2026-07-24
+
+- Added `CRUDKanbanDataSource`, a four-callback bridge for connecting existing SQL, NoSQL, ORM, and API repositories without implementing the full persistence protocol.
+- Hardened SQLite mutation replay, schema migration, conflict snapshots, batch rollback, identifier validation, and offline queue ordering.
+- Fixed paged-board totals, offsets, undo/redo persistence, column rename handling, timestamp sorting, dirty-form replacement, and style snapshots.
+- Expanded supported CustomTkinter releases through 6.x and strengthened source/wheel validation, compatibility testing, documentation checks, and release smoke tests.
+- Added cross-platform CI for Python 3.10 through 3.14, branch coverage, dependency auditing, installed-wheel smoke tests, and package validation.
+- Added CodeQL scanning, Dependabot, workflow security linting, GitHub Pages deployment, and repository contribution templates.
+- Added trusted TestPyPI and PyPI publishing with protected environments, artifact attestations, checksums, and automated GitHub releases.
+- Added local tox environments and release preparation, validation, and installed-package smoke-test scripts.
+
+## 0.2.0 - 2026-06-14
+
+- Added typed mutation, result, conflict, query, paging, and load contracts.
+- Added threaded data-source coordination, retries, offline queueing, polling, canonical IDs, and optimistic concurrency.
+- Added a transactional SQLite adapter and runnable database example.
+- Added sparse card ranking, atomic batches, undo/redo, immutable IDs, timestamps, and revisions.
+- Added persistence status, filter chips, active sort and result summaries, search clearing and highlighting.
+- Added responsive and adjustable columns, drag handles, WIP/lock indicators, and invalid-drop feedback.
+- Added date picking, field-level validation, dirty-form protection, and normalized optional values.
+- Redesigned the default light and dark appearance with layered surfaces, priority rails, metadata tiles, compact toolbar states, polished columns, and cohesive forms.
+- Added visual-state regression coverage and light/dark/form showcase modes.
+- Added integration, performance, reliability, and usability tests.
+
+## 0.1.0
+
+- Initial configurable CustomTkinter Kanban board.

ctkkanban-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+## Our standard
+
+We want participation in CTkKanban to be welcoming, constructive, and safe. Be respectful, assume good intent while still discussing technical disagreements directly, and focus criticism on behavior and code rather than people.
+
+Harassment, discrimination, threats, sexualized attention, deliberate intimidation, and publication of private information are not acceptable.
+
+## Enforcement
+
+Report conduct concerns privately to the project maintainer through GitHub. The maintainer may edit or remove contributions, limit participation, or ban contributors when needed to protect the community. Reports will be handled as confidentially as practical.
+
+This policy applies in project spaces and when someone is publicly representing the project.
+

ctkkanban-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+1. Create a virtual environment with Python 3.10 or newer.
+2. Install the project in editable mode: `python -m pip install -e ".[dev]"`.
+3. Keep public mutations database-neutral and operation-first.
+4. Add focused tests for behavior, rollback, thread boundaries, and widget identity.
+5. Run `tox -e lint,type,py314,package` before opening a change.
+
+Tk widgets must only be touched by Tk's owning thread. Persistence adapters may block because the coordinator runs them on a dedicated worker.
+
+Do not introduce a second persistence writer into a board. Use a `KanbanDataSource` or the legacy `on_data_changed` callback.
+
+User-visible changes belong under `## Unreleased` in `CHANGELOG.md`. See [docs/publishing.md](docs/publishing.md) for TestPyPI and production release steps.

ctkkanban-1.0.0/CTkKanBan/__init__.py

@@ -0,0 +1,10 @@
+"""Public compatibility import for the CTkKanBan distribution.
+
+The implementation lives in :mod:`ctk_kanban`; this package preserves the
+project's branded import spelling for applications that prefer ``import
+CTkKanBan``.
+"""
+
+from ctk_kanban import *  # noqa: F401,F403
+from ctk_kanban import __all__, __version__
+

ctkkanban-1.0.0/CTkKanBan.egg-info/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: CTkKanBan
+Version: 1.0.0
+Summary: A configurable, database-ready Kanban board for CustomTkinter
+Author-email: Harry Gomm <Harry-g25@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Harry-g25/CTkKanBan
+Project-URL: Documentation, https://harry-g25.github.io/CTkKanBan/
+Project-URL: Changelog, https://github.com/Harry-g25/CTkKanBan/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Harry-g25/CTkKanBan/issues
+Project-URL: Source, https://github.com/Harry-g25/CTkKanBan
+Keywords: customtkinter,kanban,desktop,sqlite,database,gui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: customtkinter<7,>=5.2.2
+Requires-Dist: tzdata>=2025.2; platform_system == "Windows"
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=7.6; extra == "test"
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-cov>=6; extra == "test"
+Provides-Extra: quality
+Requires-Dist: mypy>=1.14; extra == "quality"
+Requires-Dist: ruff>=0.9; extra == "quality"
+Requires-Dist: yamllint>=1.35; extra == "quality"
+Requires-Dist: zizmor>=1.7; extra == "quality"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: check-wheel-contents>=0.6; extra == "release"
+Requires-Dist: packaging>=24; extra == "release"
+Requires-Dist: pyroma>=4.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: check-wheel-contents>=0.6; extra == "dev"
+Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: mypy>=1.14; extra == "dev"
+Requires-Dist: packaging>=24; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: pyroma>=4.2; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: tox>=4.23; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: yamllint>=1.35; extra == "dev"
+Requires-Dist: zizmor>=1.7; extra == "dev"
+Dynamic: license-file
+
+# CTkKanban
+
+[![CI](https://github.com/Harry-g25/CTkKanBan/actions/workflows/ci.yml/badge.svg)](https://github.com/Harry-g25/CTkKanBan/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Harry-g25/CTkKanBan/actions/workflows/codeql.yml/badge.svg)](https://github.com/Harry-g25/CTkKanBan/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/CTkKanBan.svg)](https://pypi.org/project/CTkKanBan/)
+[![Python](https://img.shields.io/pypi/pyversions/CTkKanBan.svg)](https://pypi.org/project/CTkKanBan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Harry-g25/CTkKanBan/blob/main/LICENSE)
+
+CTkKanban is a configurable Kanban widget for CustomTkinter desktop applications. It ships with a polished adaptive light/dark design, live inline card editing, generated forms, drag and drop, search, advanced filters, sorting, undo/redo, responsive columns, and database-backed operation.
+
+The built-in design uses layered surfaces, priority-accented cards, responsive metadata tiles, column color rails, active filter treatments, and database status pills. Every visual token remains overridable through `style` or `theme`.
+
+## Install
+
+```bash
+python -m pip install CTkKanBan
+```
+
+## In-memory board
+
+```python
+import customtkinter as ctk
+import CTkKanBan
+
+board_class = CTkKanBan.CTkKanbanBoard
+
+app = ctk.CTk()
+board = board_class(
+    app,
+    columns=[{"id": "todo", "title": "To Do"}, {"id": "done", "title": "Done"}],
+    cards=[{"id": 1, "column": "todo", "title": "Try CTkKanban"}],
+    completed_columns=["done"],
+)
+board.pack(fill="both", expand=True)
+app.mainloop()
+```
+
+## Inline card editing
+
+Inline editing is enabled by default. Click any value rendered on a card—including an empty
+`show_on_card` field—to edit it without opening a dialog. Press Enter or click the check button to
+save, click away to autosave, or press Escape to cancel. Text areas use Ctrl+Enter to save so Enter
+can still insert a new line.
+
+Edits use the same validation, callbacks, undo history, filtering, sorting, and persistence path as
+`update_card()`. Read-only and hidden fields are never editable. To keep the earlier popup/side-panel
+interaction, configure `enable_inline_card_editing=False`; `open_edit_card_form(card_id)` also remains
+available for an explicit full-card form.
+
+```python
+board = CTkKanbanBoard(
+    app,
+    columns=columns,
+    cards=cards,
+    fields=fields,
+    enable_inline_card_editing=True,
+)
+
+# Keyboard-free or application-driven activation is also available.
+board.start_inline_card_edit(card_id=1, field_key="priority")
+```
+
+Automatic field hit targets are available with the default card renderer. Applications using a
+custom `card_renderer` retain the full-card edit flow and can build their own editing controls.
+
+## SQLite board
+
+```python
+import customtkinter as ctk
+from ctk_kanban import CTkKanbanBoard, SQLiteKanbanDataSource
+
+app = ctk.CTk()
+source = SQLiteKanbanDataSource("kanban.db")
+source.seed_board("work", [{"id": "todo", "title": "To Do"}], [])
+
+board = CTkKanbanBoard(
+    app,
+    data_source=source,
+    board_id="work",
+    auto_load=True,
+    server_side_query=True,
+    poll_interval_ms=2000,
+)
+board.pack(fill="both", expand=True)
+app.mainloop()
+```
+
+Database work runs outside Tk's UI thread. Mutations carry event, transaction, actor, board, and expected-revision metadata. Adapters may return canonical records with generated IDs, timestamps, versions, and defaults. Failed network writes can be retried or held in the process-local offline queue until connectivity returns.
+
+The built-in SQLite adapter provides transactional writes, optimistic revisions, atomic batches, server-side search/filter/sort, paging, change polling, generated IDs, and automatic timestamps. The board shows saving, saved, offline, conflict, and error states; duplicate submissions are blocked while a mutation is pending.
+
+For an existing SQL, document, key-value, ORM, or API-backed repository, use
+`CRUDKanbanDataSource` instead of implementing the full adapter contract:
+
+```python
+from ctk_kanban import CRUDKanbanDataSource
+
+source = CRUDKanbanDataSource(
+    read=repository.read_board,
+    create=repository.create,
+    update=repository.update,
+    delete=repository.delete,
+    transaction=repository.transaction,  # Optional
+)
+```
+
+The four callbacks receive either `"card"` or `"column"`, the board ID, the record or ID, and a
+`CRUDContext`. The bridge translates moves, reorders, renames, batching, paging, search, filters, and
+canonical generated IDs. This keeps database-specific connection and query code in your application.
+
+Use only one durable writer: configure either `data_source` or the legacy `on_data_changed` callback, never both.
+
+See the [database integration guide](https://github.com/Harry-g25/CTkKanBan/blob/main/docs/database.md) for the adapter contract, event shape, conflict policies, paging, polling, and a production integration checklist.
+
+The example programs are included in the source repository and source distribution, not the installed wheel. From a [source checkout](https://github.com/Harry-g25/CTkKanBan), run `python example_all_features.py` for the UI showcase or `python example_sqlite.py` for the transactional database example.
+
+Use `python example_all_features.py --light`, `--dark`, or `--form` to inspect specific appearance and form states. Add `--diagnose` to print the exact package path and version being rendered.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+tox -e lint,type,py314,ctk-min,ctk-current,package
+```
+
+CI tests Python 3.10 through 3.14 on Linux and the oldest/latest supported versions on Windows and macOS. It also checks branch coverage, installed-wheel behavior, SQLite persistence, dependency vulnerabilities, package metadata, and workflow security.
+
+See the [changelog](https://github.com/Harry-g25/CTkKanBan/blob/main/CHANGELOG.md), [contribution guide](https://github.com/Harry-g25/CTkKanBan/blob/main/CONTRIBUTING.md), [publishing runbook](https://github.com/Harry-g25/CTkKanBan/blob/main/docs/publishing.md), and [project documentation](https://harry-g25.github.io/CTkKanBan/).

ctkkanban-1.0.0/CTkKanBan.egg-info/SOURCES.txt

@@ -0,0 +1,74 @@
+.gitattributes
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+LICENSE
+MANIFEST.in
+README.md
+SECURITY.md
+example_all_features.py
+example_sqlite.py
+pyproject.toml
+tox.ini
+CTkKanBan/__init__.py
+CTkKanBan.egg-info/PKG-INFO
+CTkKanBan.egg-info/SOURCES.txt
+CTkKanBan.egg-info/dependency_links.txt
+CTkKanBan.egg-info/requires.txt
+CTkKanBan.egg-info/top_level.txt
+ctk_kanban/__init__.py
+ctk_kanban/board.py
+ctk_kanban/card.py
+ctk_kanban/column.py
+ctk_kanban/contracts.py
+ctk_kanban/crud.py
+ctk_kanban/datasource.py
+ctk_kanban/dialogs.py
+ctk_kanban/drag.py
+ctk_kanban/events.py
+ctk_kanban/exceptions.py
+ctk_kanban/models.py
+ctk_kanban/py.typed
+ctk_kanban/query.py
+ctk_kanban/rendering.py
+ctk_kanban/sqlite.py
+ctk_kanban/themes.py
+ctk_kanban/toolbar.py
+ctk_kanban/utils.py
+ctk_kanban/validators.py
+ctk_kanban/version.py
+ctk_kanban/widgets.py
+docs/database.md
+docs/index.html
+docs/publishing.md
+docs/script.js
+docs/styles.css
+docs/assests/favicon/about.txt
+docs/assests/favicon/android-chrome-192x192.png
+docs/assests/favicon/android-chrome-512x512.png
+docs/assests/favicon/apple-touch-icon.png
+docs/assests/favicon/favicon-16x16.png
+docs/assests/favicon/favicon-32x32.png
+docs/assests/favicon/favicon.ico
+docs/assests/favicon/site.webmanifest
+scripts/check_docs.py
+scripts/prepare_release.py
+scripts/run_actionlint.py
+scripts/smoke_install.py
+scripts/validate_dist.py
+scripts/verify_release.py
+tests/gui_test_app.py
+tests/test_board_integrity_regressions.py
+tests/test_card_creation_optimizations.py
+tests/test_card_form_modes.py
+tests/test_crud_datasource.py
+tests/test_database_persistence_api.py
+tests/test_drag_optimizations.py
+tests/test_full_efficiency_audit.py
+tests/test_inline_card_editing.py
+tests/test_new_usability_features.py
+tests/test_performance_regressions.py
+tests/test_persistence_correctness.py
+tests/test_release_validation.py
+tests/test_sqlite_datasource.py
+tests/test_style_customization.py

ctkkanban-1.0.0/CTkKanBan.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ctkkanban-1.0.0/CTkKanBan.egg-info/requires.txt

@@ -0,0 +1,38 @@
+customtkinter<7,>=5.2.2
+
+[:platform_system == "Windows"]
+tzdata>=2025.2
+
+[dev]
+build>=1.2
+check-wheel-contents>=0.6
+coverage[toml]>=7.6
+mypy>=1.14
+packaging>=24
+pip-audit>=2.7
+pyroma>=4.2
+pytest>=8.3
+pytest-cov>=6
+ruff>=0.9
+tox>=4.23
+twine>=6
+yamllint>=1.35
+zizmor>=1.7
+
+[quality]
+mypy>=1.14
+ruff>=0.9
+yamllint>=1.35
+zizmor>=1.7
+
+[release]
+build>=1.2
+check-wheel-contents>=0.6
+packaging>=24
+pyroma>=4.2
+twine>=6
+
+[test]
+coverage[toml]>=7.6
+pytest>=8.3
+pytest-cov>=6

ctkkanban-1.0.0/CTkKanBan.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+CTkKanBan
+ctk_kanban

ctkkanban-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harry Gomm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctkkanban-1.0.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include .gitattributes
+include CHANGELOG.md
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include LICENSE
+include README.md
+include SECURITY.md
+include example_all_features.py
+include example_sqlite.py
+include tests/gui_test_app.py
+include tox.ini
+recursive-include docs *
+recursive-include scripts *.py
+include ctk_kanban/py.typed

ctkkanban-1.0.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: CTkKanBan
+Version: 1.0.0
+Summary: A configurable, database-ready Kanban board for CustomTkinter
+Author-email: Harry Gomm <Harry-g25@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Harry-g25/CTkKanBan
+Project-URL: Documentation, https://harry-g25.github.io/CTkKanBan/
+Project-URL: Changelog, https://github.com/Harry-g25/CTkKanBan/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Harry-g25/CTkKanBan/issues
+Project-URL: Source, https://github.com/Harry-g25/CTkKanBan
+Keywords: customtkinter,kanban,desktop,sqlite,database,gui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: customtkinter<7,>=5.2.2
+Requires-Dist: tzdata>=2025.2; platform_system == "Windows"
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=7.6; extra == "test"
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-cov>=6; extra == "test"
+Provides-Extra: quality
+Requires-Dist: mypy>=1.14; extra == "quality"
+Requires-Dist: ruff>=0.9; extra == "quality"
+Requires-Dist: yamllint>=1.35; extra == "quality"
+Requires-Dist: zizmor>=1.7; extra == "quality"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: check-wheel-contents>=0.6; extra == "release"
+Requires-Dist: packaging>=24; extra == "release"
+Requires-Dist: pyroma>=4.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: check-wheel-contents>=0.6; extra == "dev"
+Requires-Dist: coverage[toml]>=7.6; extra == "dev"
+Requires-Dist: mypy>=1.14; extra == "dev"
+Requires-Dist: packaging>=24; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: pyroma>=4.2; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: tox>=4.23; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: yamllint>=1.35; extra == "dev"
+Requires-Dist: zizmor>=1.7; extra == "dev"
+Dynamic: license-file
+
+# CTkKanban
+
+[![CI](https://github.com/Harry-g25/CTkKanBan/actions/workflows/ci.yml/badge.svg)](https://github.com/Harry-g25/CTkKanBan/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Harry-g25/CTkKanBan/actions/workflows/codeql.yml/badge.svg)](https://github.com/Harry-g25/CTkKanBan/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/CTkKanBan.svg)](https://pypi.org/project/CTkKanBan/)
+[![Python](https://img.shields.io/pypi/pyversions/CTkKanBan.svg)](https://pypi.org/project/CTkKanBan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Harry-g25/CTkKanBan/blob/main/LICENSE)
+
+CTkKanban is a configurable Kanban widget for CustomTkinter desktop applications. It ships with a polished adaptive light/dark design, live inline card editing, generated forms, drag and drop, search, advanced filters, sorting, undo/redo, responsive columns, and database-backed operation.
+
+The built-in design uses layered surfaces, priority-accented cards, responsive metadata tiles, column color rails, active filter treatments, and database status pills. Every visual token remains overridable through `style` or `theme`.
+
+## Install
+
+```bash
+python -m pip install CTkKanBan
+```
+
+## In-memory board
+
+```python
+import customtkinter as ctk
+import CTkKanBan
+
+board_class = CTkKanBan.CTkKanbanBoard
+
+app = ctk.CTk()
+board = board_class(
+    app,
+    columns=[{"id": "todo", "title": "To Do"}, {"id": "done", "title": "Done"}],
+    cards=[{"id": 1, "column": "todo", "title": "Try CTkKanban"}],
+    completed_columns=["done"],
+)
+board.pack(fill="both", expand=True)
+app.mainloop()
+```
+
+## Inline card editing
+
+Inline editing is enabled by default. Click any value rendered on a card—including an empty
+`show_on_card` field—to edit it without opening a dialog. Press Enter or click the check button to
+save, click away to autosave, or press Escape to cancel. Text areas use Ctrl+Enter to save so Enter
+can still insert a new line.
+
+Edits use the same validation, callbacks, undo history, filtering, sorting, and persistence path as
+`update_card()`. Read-only and hidden fields are never editable. To keep the earlier popup/side-panel
+interaction, configure `enable_inline_card_editing=False`; `open_edit_card_form(card_id)` also remains
+available for an explicit full-card form.
+
+```python
+board = CTkKanbanBoard(
+    app,
+    columns=columns,
+    cards=cards,
+    fields=fields,
+    enable_inline_card_editing=True,
+)
+
+# Keyboard-free or application-driven activation is also available.
+board.start_inline_card_edit(card_id=1, field_key="priority")
+```
+
+Automatic field hit targets are available with the default card renderer. Applications using a
+custom `card_renderer` retain the full-card edit flow and can build their own editing controls.
+
+## SQLite board
+
+```python
+import customtkinter as ctk
+from ctk_kanban import CTkKanbanBoard, SQLiteKanbanDataSource
+
+app = ctk.CTk()
+source = SQLiteKanbanDataSource("kanban.db")
+source.seed_board("work", [{"id": "todo", "title": "To Do"}], [])
+
+board = CTkKanbanBoard(
+    app,
+    data_source=source,
+    board_id="work",
+    auto_load=True,
+    server_side_query=True,
+    poll_interval_ms=2000,
+)
+board.pack(fill="both", expand=True)
+app.mainloop()
+```
+
+Database work runs outside Tk's UI thread. Mutations carry event, transaction, actor, board, and expected-revision metadata. Adapters may return canonical records with generated IDs, timestamps, versions, and defaults. Failed network writes can be retried or held in the process-local offline queue until connectivity returns.
+
+The built-in SQLite adapter provides transactional writes, optimistic revisions, atomic batches, server-side search/filter/sort, paging, change polling, generated IDs, and automatic timestamps. The board shows saving, saved, offline, conflict, and error states; duplicate submissions are blocked while a mutation is pending.
+
+For an existing SQL, document, key-value, ORM, or API-backed repository, use
+`CRUDKanbanDataSource` instead of implementing the full adapter contract:
+
+```python
+from ctk_kanban import CRUDKanbanDataSource
+
+source = CRUDKanbanDataSource(
+    read=repository.read_board,
+    create=repository.create,
+    update=repository.update,
+    delete=repository.delete,
+    transaction=repository.transaction,  # Optional
+)
+```
+
+The four callbacks receive either `"card"` or `"column"`, the board ID, the record or ID, and a
+`CRUDContext`. The bridge translates moves, reorders, renames, batching, paging, search, filters, and
+canonical generated IDs. This keeps database-specific connection and query code in your application.
+
+Use only one durable writer: configure either `data_source` or the legacy `on_data_changed` callback, never both.
+
+See the [database integration guide](https://github.com/Harry-g25/CTkKanBan/blob/main/docs/database.md) for the adapter contract, event shape, conflict policies, paging, polling, and a production integration checklist.
+
+The example programs are included in the source repository and source distribution, not the installed wheel. From a [source checkout](https://github.com/Harry-g25/CTkKanBan), run `python example_all_features.py` for the UI showcase or `python example_sqlite.py` for the transactional database example.
+
+Use `python example_all_features.py --light`, `--dark`, or `--form` to inspect specific appearance and form states. Add `--diagnose` to print the exact package path and version being rendered.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+tox -e lint,type,py314,ctk-min,ctk-current,package
+```
+
+CI tests Python 3.10 through 3.14 on Linux and the oldest/latest supported versions on Windows and macOS. It also checks branch coverage, installed-wheel behavior, SQLite persistence, dependency vulnerabilities, package metadata, and workflow security.
+
+See the [changelog](https://github.com/Harry-g25/CTkKanBan/blob/main/CHANGELOG.md), [contribution guide](https://github.com/Harry-g25/CTkKanBan/blob/main/CONTRIBUTING.md), [publishing runbook](https://github.com/Harry-g25/CTkKanBan/blob/main/docs/publishing.md), and [project documentation](https://harry-g25.github.io/CTkKanBan/).