bootstack 0.1.0a5__tar.gz → 0.1.0a6__tar.gz

{bootstack-0.1.0a5/src/bootstack.egg-info → bootstack-0.1.0a6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.1.0a5
+Version: 0.1.0a6
 Summary: A full UI framework for Python desktop apps built on tkinter — rich widgets, theming, and application structure out of the box.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.1.0a5"
+version = "0.1.0a6"
 description = "A full UI framework for Python desktop apps built on tkinter — rich widgets, theming, and application structure out of the box."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -82,7 +82,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.1.0a5"
+current_version = "0.1.0a6"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/__init__.py

@@ -50,6 +50,7 @@ if TYPE_CHECKING:
     from bootstack.api.style import (
         Font,
         Style,
+        Typography,
         get_style,
         get_style_builder,
         get_theme,
@@ -58,6 +59,7 @@ if TYPE_CHECKING:
         toggle_theme,
         get_theme_color,
         get_themes,
+        register_user_theme,
     )
     from bootstack.api.widgets import (
         Button,
@@ -80,6 +82,8 @@ if TYPE_CHECKING:
         Label,
         LabelFrame,
         LabeledScale,
+        ListItem,
+        ListView,
         MenuBar,
         MenuButton,
         Meter,
@@ -158,10 +162,11 @@ _MODULE_EXPORTS = {
     ],
     # Style & Theming
     "bootstack.api.style": [
-        "BootstrapIcon", "Font", "Style",
+        "BootstrapIcon", "Font", "Style", "Typography",
         "get_style", "get_style_builder", "get_theme",
         "get_theme_provider", "set_theme", "get_theme_color",
         "toggle_theme", "get_themes",
+        "register_user_theme",
     ],
     # Widgets
     "bootstack.api.widgets": [
@@ -173,7 +178,7 @@ _MODULE_EXPORTS = {
         "RadioToggle",
         "Calendar", "ContextMenu", "ContextMenuItem", "DateEntry",
         "Accordion", "DropdownButton", "Expander", "Field", "FieldOptions", "FloodGauge", "Form",
-        "GridFrame", "LabeledScale", "MenuBar", "Meter",
+        "GridFrame", "LabeledScale", "ListItem", "ListView", "MenuBar", "Meter",
         "SideNav", "SideNavItem", "SideNavGroup",
         "SideNavHeader", "SideNavSeparator",
         "NumericEntry", "PackFrame", "PageStack",

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/api/style.py

@@ -6,12 +6,14 @@ from ttkbootstrap_icons_bs import BootstrapIcon
 
 from bootstack.style.style import (Style, get_style, get_style_builder, get_theme, get_theme_color,
                                       get_theme_provider, set_theme, toggle_theme, get_themes)
-from bootstack.style.typography import Font
+from bootstack.style.theme_provider import register_user_theme
+from bootstack.style.typography import Font, Typography
 
 __all__ = [
     "BootstrapIcon",
     "Font",
     "Style",
+    "Typography",
     "get_style",
     "get_style_builder",
     "get_theme",
@@ -20,4 +22,5 @@ __all__ = [
     "get_theme_provider",
     "get_theme_color",
     "get_themes",
+    "register_user_theme",
 ]

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/api/widgets.py

@@ -35,6 +35,7 @@ from bootstack.widgets.primitives.gridframe import GridFrame
 from bootstack.widgets.primitives.label import Label
 from bootstack.widgets.primitives.labelframe import LabelFrame
 from bootstack.widgets.composites.labeledscale import LabeledScale
+from bootstack.widgets.composites.list import ListItem, ListView
 from bootstack.widgets.composites.menubar import MenuBar
 from bootstack.widgets.primitives.menubutton import MenuButton
 from bootstack.widgets.composites.meter import Meter
@@ -93,6 +94,8 @@ __all__ = [
     "Label",
     "LabelFrame",
     "LabeledScale",
+    "ListItem",
+    "ListView",
     "MenuBar",
     "SideNav",
     "SideNavItem",

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/cli/__init__.py

@@ -20,6 +20,7 @@ Usage:
     bootstack list themes            List available themes
     bootstack doctor                 Diagnose project and environment health
     bootstack gallery                 Launch the widget gallery
+    bootstack icons                   Browse Bootstrap Icons
 """
 
 from __future__ import annotations
@@ -28,7 +29,7 @@ import argparse
 import sys
 from typing import Sequence
 
-from bootstack.cli import add, build, doctor, list_cmd, promote, run, start
+from bootstack.cli import add, build, doctor, icons, list_cmd, promote, run, start
 from bootstack.cli.demo import run_demo
 
 
@@ -50,6 +51,7 @@ Examples:
   bootstack list themes              List available themes
   bootstack doctor                   Diagnose project and environment health
   bootstack gallery                  Launch the widget gallery
+  bootstack icons                    Browse Bootstrap Icons
 
 For more information on a command:
   bootstack <command> --help
@@ -82,6 +84,7 @@ For more information on a command:
     add.add_parser(subparsers)
     list_cmd.add_parser(subparsers)
     doctor.add_parser(subparsers)
+    icons.add_parser(subparsers)
 
     # Gallery command
     gallery_parser = subparsers.add_parser(

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/cli/add.py

@@ -305,7 +305,7 @@ def run_add_theme(args: argparse.Namespace) -> None:
     print()
     print("  from bootstack.style.theme_provider import register_user_theme")
     print(f'  register_user_theme("{theme_name}", "themes/{theme_name}.json")')
-    print(f'  app = ttk.App(theme="{theme_name}")')
+    print(f'  app = bs.App(theme="{theme_name}")')
 
 
 def run_add_i18n(args: argparse.Namespace) -> None:
@@ -340,7 +340,7 @@ def run_add_i18n(args: argparse.Namespace) -> None:
     print("Next steps:")
     print("  1. Add translatable strings to your .po files")
     print("  2. Compile with: msgfmt locales/<lang>/LC_MESSAGES/messages.po -o locales/<lang>/LC_MESSAGES/messages.mo")
-    print("  3. Use translations in code: ttk.mc('Hello')")
+    print("  3. Use translations in code: bs.L('Hello')")
 
 
 _BASE_SHADES = {

bootstack-0.1.0a6/src/bootstack/cli/icons.py

@@ -0,0 +1,28 @@
+"""Icons command — delegates to the ttkbootstrap-icons browser."""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "icons",
+        help="Browse Bootstrap Icons available in bootstack",
+        description=(
+            "Launch the Bootstrap Icons browser.\n\n"
+            "Delegates to the ttkbootstrap-icons tool bundled with the "
+            "ttkbootstrap_icons_bs package. Any icon name shown there can "
+            "be used as the icon= parameter on any bootstack widget."
+        ),
+    )
+    parser.set_defaults(func=lambda args: run_icons())
+
+
+def run_icons() -> None:
+    scripts = Path(sys.executable).parent
+    name = "ttkbootstrap-icons.exe" if sys.platform == "win32" else "ttkbootstrap-icons"
+    result = subprocess.run([str(scripts / name)])
+    sys.exit(result.returncode)

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/datasource/sqlite_source.py

@@ -34,6 +34,10 @@ from typing import Any, Dict, List, Optional, Union, Sequence
 from bootstack.datasource.base import BaseDataSource
 from bootstack.datasource.types import Primitive, Record
 
+# Internal column names — reserved by SqliteDataSource, never exposed to user data.
+_ROW_ID = "_bs_row_id"
+_ROW_SEL = "_bs_selected"
+
 
 class SqliteDataSource(BaseDataSource):
     """SQLite-backed data manager with pagination, filtering, sorting, and CRUD operations.
@@ -61,8 +65,9 @@ class SqliteDataSource(BaseDataSource):
         - The database connection persists for the lifetime of the object
         - Close the connection explicitly with conn.close() if needed
         - Schema is inferred from first record's data types
-        - 'id' field is automatically set as PRIMARY KEY
-        - 'selected' field is added automatically for selection tracking
+        - An internal row-identity column (_bs_row_id) is added automatically as PRIMARY KEY
+        - An internal selection column (_bs_selected) is added automatically for selection tracking
+        - These internal columns are filtered out of the display column list automatically
     """
 
     def __init__(self, name: str = ":memory:", page_size: int = 10):
@@ -121,12 +126,12 @@ class SqliteDataSource(BaseDataSource):
             using_dicts = True
 
         if using_dicts:
-            # Ensure helper columns
+            # Ensure internal helper columns
             for i, record in enumerate(records):
-                if "id" not in record:
-                    record["id"] = i
-                if "selected" not in record:
-                    record["selected"] = 0
+                if _ROW_ID not in record:
+                    record[_ROW_ID] = i
+                if _ROW_SEL not in record:
+                    record[_ROW_SEL] = 0
 
             self._columns = list(records[0].keys())
             col_types = {col: self._infer_type(records[0][col]) for col in self._columns}
@@ -136,25 +141,25 @@ class SqliteDataSource(BaseDataSource):
             keys = list(column_keys or [])
             if not keys:
                 keys = [str(i) for i in range(len(first))]
-            need_id = "id" not in keys
-            need_selected = "selected" not in keys
+            need_id = _ROW_ID not in keys
+            need_sel = _ROW_SEL not in keys
             if need_id:
-                keys.append("id")
-            if need_selected:
-                keys.append("selected")
+                keys.append(_ROW_ID)
+            if need_sel:
+                keys.append(_ROW_SEL)
             self._columns = keys
 
             # Infer types from first row (pad to keys length)
             padded_first = list(first) + [None] * (len(keys) - len(first))
-            if need_id and "id" in keys:
-                padded_first[keys.index("id")] = 0
-            if need_selected and "selected" in keys:
-                padded_first[keys.index("selected")] = 0
+            if need_id and _ROW_ID in keys:
+                padded_first[keys.index(_ROW_ID)] = 0
+            if need_sel and _ROW_SEL in keys:
+                padded_first[keys.index(_ROW_SEL)] = 0
             col_types = {col: self._infer_type(padded_first[idx]) for idx, col in enumerate(keys)}
 
             rows_to_insert = []
-            id_idx = keys.index("id") if "id" in keys else None
-            sel_idx = keys.index("selected") if "selected" in keys else None
+            id_idx = keys.index(_ROW_ID) if _ROW_ID in keys else None
+            sel_idx = keys.index(_ROW_SEL) if _ROW_SEL in keys else None
             value_len = len(keys)
             for i, row in enumerate(records):
                 base_values = list(row[: value_len]) + [""] * (value_len - len(row))
@@ -165,7 +170,7 @@ class SqliteDataSource(BaseDataSource):
                 rows_to_insert.append(tuple(base_values))
 
         col_definitions = ", ".join(
-            f"{self._quote_identifier(col)} {col_types[col]}" + (" PRIMARY KEY" if col == "id" else "")
+            f"{self._quote_identifier(col)} {col_types[col]}" + (" PRIMARY KEY" if col == _ROW_ID else "")
             for col in self._columns
         )
         placeholders = ", ".join("?" for _ in self._columns)
@@ -241,11 +246,11 @@ class SqliteDataSource(BaseDataSource):
 
     def create_record(self, record: Dict[str, Any]) -> int:
         """Create new record and return its ID."""
-        if "id" not in record:
-            record["id"] = self._generate_new_id()
+        if _ROW_ID not in record:
+            record[_ROW_ID] = self._generate_new_id()
 
-        if "selected" not in record:
-            record["selected"] = 0
+        if _ROW_SEL not in record:
+            record[_ROW_SEL] = 0
 
         # Ensure table exists (handles empty datasources)
         self._ensure_table_for_record(record)
@@ -257,11 +262,11 @@ class SqliteDataSource(BaseDataSource):
 
         with self.conn:
             self.conn.execute(f"INSERT INTO {self._table} ({cols}) VALUES ({placeholders})", values)
-        return record["id"]
+        return record[_ROW_ID]
 
     def read_record(self, record_id: Any) -> Optional[Dict[str, Any]]:
         """Retrieve single record by ID."""
-        cursor = self.conn.execute(f"SELECT * FROM {self._table} WHERE id = ?", (record_id,))
+        cursor = self.conn.execute(f"SELECT * FROM {self._table} WHERE {_ROW_ID} = ?", (record_id,))
         row = cursor.fetchone()
         return dict(row) if row else None
 
@@ -272,19 +277,19 @@ class SqliteDataSource(BaseDataSource):
         set_clause = ", ".join(f"{self._quote_identifier(k)} = ?" for k in updates)
         values = tuple(updates.values()) + (record_id,)
         with self.conn:
-            cur = self.conn.execute(f"UPDATE {self._table} SET {set_clause} WHERE id = ?", values)
+            cur = self.conn.execute(f"UPDATE {self._table} SET {set_clause} WHERE {_ROW_ID} = ?", values)
             return cur.rowcount > 0
 
     def delete_record(self, record_id: Any) -> bool:
         """Delete record by ID."""
         with self.conn:
-            cur = self.conn.execute(f"DELETE FROM {self._table} WHERE id = ?", (record_id,))
+            cur = self.conn.execute(f"DELETE FROM {self._table} WHERE {_ROW_ID} = ?", (record_id,))
             return cur.rowcount > 0
 
     def _generate_new_id(self) -> int:
         """Generate next available integer ID."""
         try:
-            cursor = self.conn.execute(f"SELECT MAX(id) FROM {self._table}")
+            cursor = self.conn.execute(f"SELECT MAX({_ROW_ID}) FROM {self._table}")
             max_id = cursor.fetchone()[0]
         except Exception:
             max_id = 0
@@ -301,23 +306,23 @@ class SqliteDataSource(BaseDataSource):
             pass
 
         cols = list(self._columns) if self._columns else list(record.keys())
-        if "id" not in cols:
-            cols.append("id")
-        if "selected" not in cols:
-            cols.append("selected")
+        if _ROW_ID not in cols:
+            cols.append(_ROW_ID)
+        if _ROW_SEL not in cols:
+            cols.append(_ROW_SEL)
         self._columns = cols
 
         col_types = {}
         for c in cols:
-            if c == "id":
+            if c == _ROW_ID:
                 col_types[c] = "INTEGER"
-            elif c == "selected":
+            elif c == _ROW_SEL:
                 col_types[c] = "INTEGER"
             else:
                 col_types[c] = self._infer_type(record.get(c))
 
         col_definitions = ", ".join(
-            f"{self._quote_identifier(col)} {col_types[col]}" + (" PRIMARY KEY" if col == "id" else "")
+            f"{self._quote_identifier(col)} {col_types[col]}" + (" PRIMARY KEY" if col == _ROW_ID else "")
             for col in cols
         )
         with self.conn:
@@ -337,40 +342,40 @@ class SqliteDataSource(BaseDataSource):
         """Select all records (optionally only current page)."""
         self._ensure_selected_column()
         if current_page_only:
-            ids = [row["id"] for row in self.get_page()]
+            ids = [row[_ROW_ID] for row in self.get_page()]
             if not ids:
                 return 0
             placeholders = ", ".join("?" for _ in ids)
-            query = f"UPDATE {self._table} SET selected = 1 WHERE id IN ({placeholders})"
+            query = f"UPDATE {self._table} SET {_ROW_SEL} = 1 WHERE {_ROW_ID} IN ({placeholders})"
             with self.conn:
                 cur = self.conn.execute(query, ids)
                 return cur.rowcount
         else:
             with self.conn:
-                cur = self.conn.execute(f"UPDATE {self._table} SET selected = 1")
+                cur = self.conn.execute(f"UPDATE {self._table} SET {_ROW_SEL} = 1")
                 return cur.rowcount
 
     def unselect_all(self, current_page_only: bool = False) -> int:
         """Unselect all records (optionally only current page)."""
         self._ensure_selected_column()
         if current_page_only:
-            ids = [row["id"] for row in self.get_page()]
+            ids = [row[_ROW_ID] for row in self.get_page()]
             if not ids:
                 return 0
             placeholders = ", ".join("?" for _ in ids)
-            query = f"UPDATE {self._table} SET selected = 0 WHERE id IN ({placeholders})"
+            query = f"UPDATE {self._table} SET {_ROW_SEL} = 0 WHERE {_ROW_ID} IN ({placeholders})"
             with self.conn:
                 cur = self.conn.execute(query, ids)
                 return cur.rowcount
         else:
             with self.conn:
-                cur = self.conn.execute(f"UPDATE {self._table} SET selected = 0")
+                cur = self.conn.execute(f"UPDATE {self._table} SET {_ROW_SEL} = 0")
                 return cur.rowcount
 
     def get_selected(self, page: Optional[int] = None) -> List[Dict[str, Any]]:
         """Get selected records, optionally paginated."""
         self._ensure_selected_column()
-        query = f"SELECT * FROM {self._table} WHERE selected = 1"
+        query = f"SELECT * FROM {self._table} WHERE {_ROW_SEL} = 1"
 
         if page is not None:
             offset = page * self.page_size
@@ -380,28 +385,30 @@ class SqliteDataSource(BaseDataSource):
         return [dict(row) for row in cursor.fetchall()]
 
     def _ensure_selected_column(self):
-        """Add 'selected' column to table if it doesn't exist."""
-        if "selected" not in self._columns:
+        """Add selection column to table if it doesn't exist."""
+        if _ROW_SEL not in self._columns:
             with self.conn:
-                self.conn.execute(f"ALTER TABLE {self._table} ADD COLUMN selected INTEGER DEFAULT 0")
-            self._columns.append("selected")
+                self.conn.execute(f"ALTER TABLE {self._table} ADD COLUMN {_ROW_SEL} INTEGER DEFAULT 0")
+            self._columns.append(_ROW_SEL)
 
     def selected_count(self) -> int:
         """Get total number of selected records."""
         self._ensure_selected_column()
-        query = f"SELECT COUNT(*) FROM {self._table} WHERE selected = 1"
+        query = f"SELECT COUNT(*) FROM {self._table} WHERE {_ROW_SEL} = 1"
         return self.conn.execute(query).fetchone()[0]
 
     def _set_selected_flag(self, record_id: Any, flag: int) -> bool:
         """Set selection flag for record by ID."""
-        if "selected" not in self._columns:
-            # Add selected column if it doesn't exist
+        if _ROW_SEL not in self._columns:
             with self.conn:
-                self.conn.execute(f"ALTER TABLE {self._table} ADD COLUMN selected INTEGER DEFAULT 0")
-            self._columns.append("selected")
+                self.conn.execute(f"ALTER TABLE {self._table} ADD COLUMN {_ROW_SEL} INTEGER DEFAULT 0")
+            self._columns.append(_ROW_SEL)
 
         with self.conn:
-            cur = self.conn.execute(f"UPDATE {self._table} SET selected = ? WHERE id = ?", (flag, record_id))
+            cur = self.conn.execute(
+                f"UPDATE {self._table} SET {_ROW_SEL} = ? WHERE {_ROW_ID} = ?",
+                (flag, record_id),
+            )
             return cur.rowcount > 0
 
     # === DATA EXPORT ===
@@ -411,7 +418,7 @@ class SqliteDataSource(BaseDataSource):
         self._ensure_selected_column()
         query = f"SELECT * FROM {self._table}"
         if not include_all:
-            query += " WHERE selected = 1"
+            query += f" WHERE {_ROW_SEL} = 1"
 
         cursor = self.conn.execute(query)
         rows = cursor.fetchall()

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/widgets/composites/field.py

@@ -176,8 +176,8 @@ class Field(EntryMixin, Frame):
         show_message_explicit = 'show_message' in kwargs
         show_message = kwargs.pop('show_message', show_message)
 
-        # Auto-enable show_message if message is provided and user didn't explicitly disable it
-        if message and not show_message_explicit:
+        # Auto-enable show_message if there is any chance a message will be shown
+        if (message or required) and not show_message_explicit:
             show_message = True
 
         accent = kwargs.pop('accent', None)
@@ -266,8 +266,19 @@ class Field(EntryMixin, Frame):
         self.signal = self._entry.textsignal
 
         # enty validation
-        self.add_validation_rule = self._entry.add_validation_rule
-        self.add_validation_rules = self._entry.add_validation_rules
+        _add_rule = self._entry.add_validation_rule
+        _add_rules = self._entry.add_validation_rules
+
+        def add_validation_rule(rule_type, **kwargs):
+            self._reserve_message_space()
+            _add_rule(rule_type, **kwargs)
+
+        def add_validation_rules(rules):
+            self._reserve_message_space()
+            _add_rules(rules)
+
+        self.add_validation_rule = add_validation_rule
+        self.add_validation_rules = add_validation_rules
         self.validation = self._entry.validate
 
         # Copy Field's delegate handlers to entry for configuration forwarding
@@ -421,6 +432,11 @@ class Field(EntryMixin, Frame):
         instance.bind('<FocusIn>', lambda _: self._field.state(['focus']), add=True)
         instance.bind('<FocusOut>', lambda _: self._field.state(['!focus']), add=True)
 
+    def _reserve_message_space(self) -> None:
+        if not self._show_messages:
+            self._show_messages = True
+            self._message_lbl.pack(side='top', fill='x', padx=4)
+
     def _show_error(self, event: Any) -> None:
         """Display a validation error message below the input field."""
         self._message_lbl['text'] = event.data['message']
@@ -429,7 +445,7 @@ class Field(EntryMixin, Frame):
 
     def _clear_error(self, _: Any) -> None:
         """Clear the error message and restore the original message text."""
-        self._message_lbl['text'] = self._message_text
+        self._message_lbl['text'] = self._message_text or ''
         self._message_lbl['accent'] = "secondary"
 
     def _set_addons_state(self, disabled: bool) -> None:

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/widgets/composites/form.py

@@ -629,8 +629,7 @@ class Form(Frame):
     def _build_buttons(self, parent: Frame, buttons: Sequence[ButtonInput]) -> None:
         parsed = self._normalize_buttons(buttons)
         for spec in reversed(parsed):
-            # Support both color and legacy bootstyle from DialogButton
-            btn_color = getattr(spec, 'color', None) or spec.bootstyle
+            btn_color = getattr(spec, 'accent', None) or getattr(spec, 'color', None) or getattr(spec, 'bootstyle', None)
             btn_variant = getattr(spec, 'variant', None)
 
             if not btn_color:

{bootstack-0.1.0a5 → bootstack-0.1.0a6}/src/bootstack/widgets/composites/tableview/tableview.py

@@ -17,7 +17,7 @@ from bootstack.widgets.types import Master
 
 from ttkbootstrap_icons_bs import BootstrapIcon
 from bootstack.style.style import get_style
-from bootstack.datasource.sqlite_source import SqliteDataSource
+from bootstack.datasource.sqlite_source import SqliteDataSource, _ROW_ID, _ROW_SEL
 from bootstack.widgets.primitives.button import Button
 from bootstack.runtime.utility import bind_right_click
 from bootstack.widgets.composites.contextmenu import ContextMenu
@@ -382,7 +382,7 @@ class TableView(Frame):
                 new_id = self._datasource.create_record(dict(rec))
                 rec = dict(rec)
                 if new_id is not None:
-                    rec["id"] = new_id
+                    rec[_ROW_ID] = new_id
                 inserted.append(rec)
             except Exception:
                 logger.exception("Failed to insert record")
@@ -392,13 +392,13 @@ class TableView(Frame):
             self.event_generate("<<RowInsert>>", data={"records": inserted})
 
     def update_rows(self, rows: list[dict]) -> None:
-        """Update rows by id; each dict must include an 'id' key."""
+        """Update rows by internal row id; each dict must include the internal row-id key."""
         updated: list[dict] = []
         for rec in rows:
-            rec_id = rec.get("id")
+            rec_id = rec.get(_ROW_ID)
             if rec_id is None:
                 continue
-            updates = {k: v for k, v in rec.items() if k != "id"}
+            updates = {k: v for k, v in rec.items() if k != _ROW_ID}
             try:
                 self._datasource.update_record(rec_id, updates)
                 updated.append(rec)
@@ -417,7 +417,7 @@ class TableView(Frame):
             rec = {}
             if isinstance(item, dict):
                 rec = item
-                rec_id = item.get("id")
+                rec_id = item.get(_ROW_ID)
             else:
                 rec_id = item
             if rec_id is None:
@@ -425,7 +425,7 @@ class TableView(Frame):
             try:
                 self._datasource.delete_record(rec_id)
                 if not rec:
-                    rec = {"id": rec_id}
+                    rec = {_ROW_ID: rec_id}
                 deleted.append(rec)
             except Exception:
                 logger.exception("Failed to delete record id=%s", rec_id)
@@ -689,7 +689,7 @@ class TableView(Frame):
         if not inferred:
             inferred = getattr(self._datasource, "_columns", []) or []
 
-        inferred = [c for c in inferred if c not in ("id", "selected")]
+        inferred = [c for c in inferred if c not in (_ROW_ID, _ROW_SEL)]
         if not inferred:
             inferred = ["value"]
 
@@ -1326,7 +1326,7 @@ class TableView(Frame):
         form_options.setdefault('resizable', True)
 
         # Build buttons: Cancel, Delete (only for existing records), Save
-        if record and "id" in record:
+        if record and _ROW_ID in record:
             buttons: list[str | dict] = ['Cancel']
             if self._editing['deleting']:
                 buttons.append({"text": "Delete", "role": "secondary", "result": "delete"})
@@ -1353,21 +1353,21 @@ class TableView(Frame):
             return
 
         # Handle delete action
-        if result == "delete" and record and "id" in record:
+        if result == "delete" and record and _ROW_ID in record:
             try:
-                self._datasource.delete_record(record["id"])
+                self._datasource.delete_record(record[_ROW_ID])
                 self._clear_cache()
                 self._load_page(self._current_page)
             except Exception:
-                logger.exception("Failed to delete record id=%s", record["id"])
+                logger.exception("Failed to delete record id=%s", record[_ROW_ID])
             return
 
         data = result
         new_id = None
-        if record and "id" in record:
-            rec_id = record["id"]
+        if record and _ROW_ID in record:
+            rec_id = record[_ROW_ID]
             updates = dict(data)
-            updates.pop("id", None)
+            updates.pop(_ROW_ID, None)
             try:
                 logger.debug("Updating record id=%s with %s", rec_id, updates)
                 self._datasource.update_record(rec_id, updates)
@@ -1539,7 +1539,7 @@ class TableView(Frame):
             return
         iid = sel[0]
         rec = self._row_map.get(iid, {})
-        rec_id = rec.get("id")
+        rec_id = rec.get(_ROW_ID)
         if rec_id is not None:
             try:
                 self._datasource.delete_record(rec_id)
@@ -1557,7 +1557,7 @@ class TableView(Frame):
             rec = dict(self._row_map.get(iid) or {})
             if rec:
                 deleted_records.append(rec)
-            rec_id = rec.get("id")
+            rec_id = rec.get(_ROW_ID)
             if rec_id is not None:
                 try:
                     self._datasource.delete_record(rec_id)
@@ -1629,7 +1629,7 @@ class TableView(Frame):
         try:
             rid = str(record_id)
             for iid, rec in self._row_map.items():
-                if str(rec.get("id")) == rid:
+                if str(rec.get(_ROW_ID)) == rid:
                     self._tree.selection_set(iid)
                     self._tree.see(iid)
                     break
@@ -1646,7 +1646,7 @@ class TableView(Frame):
                     rows = self._datasource.get_page(page_idx)
                 except Exception:
                     break
-                if any(str(rec.get("id")) == rid for rec in rows):
+                if any(str(rec.get(_ROW_ID)) == rid for rec in rows):
                     return page_idx
         except Exception:
             pass