fh-matui 0.9.7__py3-none-any.whl

fh_matui/datatable.py

@@ -0,0 +1,870 @@
+"""Data table with pagination, search, sorting, and inline actions"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/05_datatable.ipynb.
+
+# %% auto 0
+__all__ = ['PAGE_SIZES', 'logger', 'table_state_from_request', 'DataTable', 'CrudContext', 'DataTableResource']
+
+# %% ../nbs/05_datatable.ipynb 2
+from fastcore.utils import *
+from fasthtml.common import *
+from fasthtml.jupyter import *
+from fastlite import *
+import fasthtml.components as fc
+from fasthtml.common import A, Button as FhButton, I, Span
+from .foundations import normalize_tokens, stringify, VEnum, dedupe_preserve_order
+from .core import *
+from nbdev.showdoc import show_doc
+from .components import *
+
+# %% ../nbs/05_datatable.ipynb 7
+#| code-fold: true
+from math import ceil
+from urllib.parse import urlencode
+from typing import Callable, Optional, Any
+
+# Default page size options
+PAGE_SIZES = [5, 10, 20, 50]
+
+def _safe_int(value, default):
+    """Safely convert to positive int or return default."""
+    try:
+        number = int(value)
+        return number if number > 0 else default
+    except (TypeError, ValueError):
+        return default
+
+def table_state_from_request(req, page_sizes=None):
+    """
+    Extract pagination state from request query params.
+    
+    Returns dict with: search, page, page_size
+    """
+    page_sizes = page_sizes or PAGE_SIZES
+    params = getattr(req, "query_params", {})
+    getter = params.get if hasattr(params, "get") else (lambda key, default=None: params[key] if key in params else default)
+    
+    search = (getter("search", "") or "").strip()
+    page = _safe_int(getter("page", 1), 1)
+    page_size = _safe_int(getter("page_size", 10), 10)
+    
+    if page_size not in page_sizes:
+        page_size = page_sizes[0] if page_sizes else 10
+    
+    return {"search": search, "page": page, "page_size": page_size}
+
+
+def _page_size_select(current_size: int, search: str, base_route: str, container_id: str, page_sizes: list):
+    """Build page size dropdown selector."""
+    menu_id = f"{container_id}-page-size-menu"
+    options = []
+    for size in page_sizes:
+        params = urlencode({"search": search, "page_size": size, "page": 1})
+        option_cls = "active" if size == current_size else None
+        options.append(
+            Li(
+                f"Show {size}",
+                hx_get=f"{base_route}?{params}",
+                hx_target=f"#{container_id}",
+                hx_push_url="true",
+                cls=option_cls
+            )
+        )
+    return Button(
+        Span(f"Show {current_size}", cls="small-text grey-text"),
+        Icon("arrow_drop_down", cls="small grey-text"),
+        Menu(*options, cls="border", id=menu_id),
+        cls="transparent small",
+        data_ui=f"#{menu_id}"
+    )
+
+
+def _action_menu(
+    row: dict,
+    row_id: Any,
+    crud_ops: dict,
+    base_route: str,
+    search: str,
+    page: int,
+    page_size: int,
+    container_id: str,
+    feedback_id: str
+):
+    """Build per-row action menu based on enabled CRUD operations."""
+    menu_id = f"crud-actions-{row_id}"
+    base_query = {"id": row_id, "search": search, "page": page, "page_size": page_size}
+    
+    def action_item(label: str, icon: str, action: str, confirm: str = None):
+        query = urlencode({**base_query, "action": action})
+        attrs = {
+            "hx_get": f"{base_route}/action?{query}",
+            "hx_target": f"#{feedback_id}",
+            "hx_swap": "outerHTML"
+        }
+        if confirm:
+            attrs["hx_confirm"] = confirm
+        return Li(
+            A(
+                Icon(icon, cls="tiny"),
+                Span(label, cls="max"),
+                cls="row middle-align",
+                **attrs
+            )
+        )
+    
+    items = []
+    # View is always available (read operation)
+    items.append(action_item("View", "visibility", "view"))
+    
+    if crud_ops.get("update", False):
+        items.append(action_item("Edit", "edit", "edit"))
+    
+    if crud_ops.get("delete", False):
+        items.append(action_item("Delete", "delete", "delete", confirm="Delete this record?"))
+    
+    return Div(
+        Button(
+            Icon("more_vert"),
+            cls=(ButtonT.text, "circle"),
+            data_ui=f"#{menu_id}",
+            title="Row actions"
+        ),
+        Menu(*items, id=menu_id),
+        cls="relative"
+    )
+
+
+def DataTable(
+    data: list[dict],
+    total: int,
+    page: int = 1,
+    page_size: int = 10,
+    search: str = '',
+    columns: list[dict] = None,
+    crud_ops: dict = None,
+    base_route: str = '',
+    row_id_field: str = 'id',
+    title: str = 'Records',
+    container_id: str = None,
+    page_sizes: list = None,
+    search_placeholder: str = 'Search...',
+    create_label: str = 'New Record',
+    empty_message: str = 'No records match the current filters.'
+):
+    "Generic data table with server-side pagination, search, and row actions."
+    # Defaults
+    crud_ops = crud_ops or {"create": False, "update": False, "delete": False}
+    page_sizes = page_sizes or PAGE_SIZES
+    container_id = container_id or f"crud-table-{base_route.replace('/', '-').strip('-')}"
+    feedback_id = f"{container_id}-feedback"
+    
+    # Auto-generate columns from first data row if not provided
+    if columns is None and data:
+        columns = [{"key": k, "label": k.replace("_", " ").title()} for k in data[0].keys()]
+    columns = columns or []
+    
+    # Calculate pagination metadata
+    total_pages = max(1, ceil(total / page_size)) if total > 0 else 1
+    page = min(max(1, page), total_pages)
+    start_index = (page - 1) * page_size + 1 if total else 0
+    end_index = min(start_index + page_size - 1, total) if total else 0
+    summary = f"{start_index}-{end_index} of {total} records" if total else "No matching records"
+    
+    base_query = urlencode({"search": search, "page_size": page_size})
+    
+    # Build table header keys and labels
+    header_keys = [col["key"] for col in columns] + ["actions"]
+    header_labels = [col.get("label", col["key"]) for col in columns] + [""]
+    
+    # Build table rows
+    table_rows = []
+    for row in data:
+        row_id = row.get(row_id_field)
+        row_dict = {}
+        
+        for col in columns:
+            key = col["key"]
+            value = row.get(key, "")
+            renderer = col.get("renderer")
+            
+            if renderer and callable(renderer):
+                row_dict[key] = renderer(value, row)
+            else:
+                row_dict[key] = value
+        
+        # Add actions column
+        row_dict["actions"] = _action_menu(
+            row=row,
+            row_id=row_id,
+            crud_ops=crud_ops,
+            base_route=base_route,
+            search=search,
+            page=page,
+            page_size=page_size,
+            container_id=container_id,
+            feedback_id=feedback_id
+        )
+        table_rows.append(row_dict)
+    
+    # Empty state
+    if not table_rows:
+        empty_row = {col["key"]: "" for col in columns}
+        empty_row[columns[0]["key"]] = Span(empty_message, cls="small-text grey-text")
+        empty_row["actions"] = ""
+        table_rows.append(empty_row)
+    
+    # Build header content
+    header_content = DivFullySpaced(
+        H5(title),
+        Span(f"{total} total", cls="small-text grey-text")
+    )
+    
+    # Build search and create button row
+    toolbar_items = [
+        Field(
+            Input(
+                placeholder=search_placeholder,
+                name="search",
+                value=search,
+                hx_get=f"{base_route}?page_size={page_size}",
+                hx_trigger="keyup changed delay:500ms",
+                hx_target=f"#{container_id}",
+                hx_push_url="true",
+                hx_vals='{"page":1}',
+                autocomplete="off",
+                onfocus="this.parentElement.classList.add('max')",
+                onblur="if(!this.value) this.parentElement.classList.remove('max')"
+            ),
+            cls="border round",
+            style="transition: flex-grow 0.3s ease"
+        )
+    ]
+    
+    if crud_ops.get("create", False):
+        create_query = urlencode({"action": "create", "search": search, "page": page, "page_size": page_size})
+        toolbar_items.append(
+            Button(
+                Icon("add"),
+                Span(create_label),
+                cls=ButtonT.primary,
+                hx_get=f"{base_route}/action?{create_query}",
+                hx_target=f"#{feedback_id}",
+                hx_swap="outerHTML"
+            )
+        )
+    
+    # Build footer with pagination - count on left, paginator centered below table
+    footer_content = Div(
+        Div(Span(summary, cls="small-text grey-text")),
+        Div(
+            _page_size_select(page_size, search, base_route, container_id, page_sizes),
+            Pagination(
+                page,
+                total_pages,
+                f"{base_route}?{base_query}",
+                hx_target=f"#{container_id}"
+            ),
+            cls="row center-align middle-align small-space"
+        ),
+        cls="grid"
+    )
+    
+    # Create header label mapping for custom rendering
+    label_map = dict(zip(header_keys, header_labels))
+    
+    # Build the card
+    card = Card(
+        DivFullySpaced(*toolbar_items, cls="padding"),
+        TableFromDicts(
+            header_keys,
+            table_rows,
+            header_cell_render=lambda k: Th(label_map.get(k, k)),
+            cls="border"
+        ),
+        footer=footer_content,
+        header=header_content,
+        cls="surface-container border round"
+    )
+    
+    return Div(card, Div(id=feedback_id), id=container_id)
+
+# %% ../nbs/05_datatable.ipynb 9
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Callable, Any, Optional
+from starlette.responses import HTMLResponse
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class CrudContext:
+    """
+    🎯 Context object passed to enhanced CRUD operation hooks.
+    
+    Provides rich access to request state, user info, database, and record data.
+    Perfect for implementing complex business logic and external API integration.
+    
+    ## 📦 Fields
+    
+    - `request`: Full Starlette request object (headers, query params, session, state)
+    - `user`: Current user dict from `request.state.user` (if available)
+    - `db`: Database instance from `request.state.tenant_db` (if available)
+    - `tbl`: Table instance from `request.state.tables[table_name]` (if available)
+    - `record`: Form data dict with field values
+    - `record_id`: Record ID for update/delete operations (None for create)
+    
+    ## 💡 Usage in Hooks
+    
+    ### Example: Create with External API
+    ```python
+    async def quiltt_create_connection(ctx: CrudContext) -> dict:
+        # Access user info
+        user_id = ctx.user['user_id']
+        
+        # Call external API
+        api = QuilttClient()
+        response = await api.create_connection(
+            institution=ctx.record['institution_name'],
+            user_id=user_id
+        )
+        
+        # Enrich record with API response
+        ctx.record['connection_id'] = response['id']
+        ctx.record['account_id'] = response['account_id']
+        ctx.record['status'] = 'pending'
+        
+        return ctx.record  # DataTableResource will insert this
+    
+    DataTableResource(
+        ...,
+        on_create=quiltt_create_connection  # 🆕 Enhanced hook
+    )
+    ```
+    
+    ### Example: Soft Delete
+    ```python
+    def soft_delete_budget(ctx: CrudContext) -> None:
+        # Access table directly
+        ctx.tbl.update({
+            'id': ctx.record_id,
+            'is_deleted': True,
+            'deleted_at': datetime.now().isoformat(),
+            'deleted_by': ctx.user['user_id']
+        })
+        # No return needed for delete hooks
+    
+    DataTableResource(
+        ...,
+        on_delete=soft_delete_budget,  # 🆕 Custom delete logic
+        get_table=lambda req: req.state.tables['budgets']
+    )
+    ```
+    
+    ### Example: Update with Sync
+    ```python
+    async def sync_transaction_update(ctx: CrudContext) -> dict:
+        # Update external API first
+        api = TransactionAPI()
+        await api.update_transaction(
+            transaction_id=ctx.record_id,
+            data=ctx.record
+        )
+        
+        # Add sync timestamp
+        ctx.record['last_synced'] = datetime.now().isoformat()
+        return ctx.record
+    ```
+    """
+    request: Any                     # Full Starlette request
+    user: Optional[dict] = None      # request.state.user (if available)
+    db: Optional[Any] = None         # request.state.tenant_db (if available)
+    tbl: Optional[Any] = None        # request.state.tables[table_name] (if available)
+    record: dict = None              # Form data dict
+    record_id: Optional[Any] = None  # ID for update/delete (None for create)
+
+# %% ../nbs/05_datatable.ipynb 13
+from typing import Callable, Optional, Any, Union
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+import uuid
+
+def _to_dict(obj: Any) -> dict:
+    """Convert dataclass, ORM object, or dict to plain dict."""
+    if obj is None:
+        return {}
+    if isinstance(obj, dict):
+        return obj
+    if is_dataclass(obj):
+        return asdict(obj)
+    # ORM-style objects with __dict__
+    if hasattr(obj, "__dict__"):
+        return {k: v for k, v in obj.__dict__.items() if not k.startswith("_")}
+    return dict(obj)
+
+
+def _is_htmx_request(req) -> bool:
+    """Check if request is an HTMX partial request."""
+    headers = getattr(req, 'headers', {})
+    return headers.get('HX-Request') == 'true'
+
+
+class DataTableResource:
+    """
+    🔧 High-level resource that auto-registers all routes for a data table.
+    
+    **Features:**
+    - All callbacks receive `request` for multi-tenant support
+    - Custom CRUD hooks with `CrudContext` for rich business logic
+    - Async/sync hook support for external API integration
+    - Auto-refresh table via HX-Trigger after mutations
+    - Layout wrapper for full-page (non-HTMX) responses
+    
+    **Auto-registers 3 routes:**
+    - `GET {base_route}` → DataTable list view
+    - `GET {base_route}/action` → FormModal for create/edit/view/delete
+    - `POST {base_route}/save` → Save handler with hooks
+    """
+    
+    def __init__(
+        self,
+        app,
+        base_route: str,
+        columns: list[dict],
+        # Data callbacks - ALL receive request as first param
+        get_all: Callable[[Any], list],                    # (req) -> list
+        get_by_id: Callable[[Any, Any], Any],              # (req, id) -> record
+        create: Callable[[Any, dict], Any] = None,         # (req, data) -> record
+        update: Callable[[Any, Any, dict], Any] = None,    # (req, id, data) -> record
+        delete: Callable[[Any, Any], bool] = None,         # (req, id) -> bool
+        # Display options
+        title: str = "Records",
+        row_id_field: str = "id",
+        crud_ops: dict = None,
+        page_sizes: list = None,
+        search_placeholder: str = "Search...",
+        create_label: str = "New Record",
+        empty_message: str = "No records found.",
+        # CRUD Hooks (with CrudContext)
+        on_create: Callable[[CrudContext], dict] = None,
+        on_update: Callable[[CrudContext], dict] = None,
+        on_delete: Callable[[CrudContext], None] = None,
+        # Layout wrapper for full-page responses
+        layout_wrapper: Callable[[Any, Any], Any] = None,  # (content, req) -> wrapped
+        # Custom generators
+        id_generator: Callable[[], Any] = None,
+        timestamp_fields: dict = None
+    ):
+        self.app = app
+        self.base_route = base_route.rstrip("/")
+        self.columns = columns
+        self.get_all = get_all
+        self.get_by_id = get_by_id
+        self.create_fn = create
+        self.update_fn = update
+        self.delete_fn = delete
+        self.title = title
+        self.row_id_field = row_id_field
+        self.page_sizes = page_sizes or PAGE_SIZES
+        self.search_placeholder = search_placeholder
+        self.create_label = create_label
+        self.empty_message = empty_message
+        
+        # Determine CRUD ops from provided functions
+        if crud_ops is None:
+            self.crud_ops = {
+                "create": create is not None or on_create is not None,
+                "update": update is not None or on_update is not None,
+                "delete": delete is not None or on_delete is not None
+            }
+        else:
+            self.crud_ops = crud_ops
+        
+        # CRUD hooks
+        self.on_create_hook = on_create
+        self.on_update_hook = on_update
+        self.on_delete_hook = on_delete
+        
+        # Layout wrapper
+        self.layout_wrapper = layout_wrapper
+        
+        # Generators
+        self.id_generator = id_generator
+        self.timestamp_fields = timestamp_fields or {}
+        
+        # Derived IDs
+        self.container_id = f"crud-table-{base_route.replace('/', '-').strip('-')}"
+        self.feedback_id = f"{self.container_id}-feedback"
+        self.modal_id = f"{self.container_id}-modal"
+        self.refresh_trigger = f"{self.container_id}-refresh"
+        
+        # Register routes
+        self._register_routes()
+    
+    async def _call_hook(self, hook, ctx: CrudContext):
+        """🔄 Call hook function, handling both sync and async."""
+        if hook is None:
+            return None
+        if asyncio.iscoroutinefunction(hook):
+            return await hook(ctx)
+        return hook(ctx)
+    
+    def _build_context(self, req, record: dict = None, record_id: Any = None) -> CrudContext:
+        """🏗️ Build CrudContext from request."""
+        user = None
+        db = None
+        tbl = None
+        
+        # Extract user from request.state if available
+        try:
+            if hasattr(req, 'state') and hasattr(req.state, 'user'):
+                user = req.state.user
+        except AttributeError:
+            pass
+        
+        # Extract db from request.state if available
+        try:
+            if hasattr(req, 'state') and hasattr(req.state, 'tenant_db'):
+                db = req.state.tenant_db
+        except AttributeError:
+            pass
+        
+        return CrudContext(
+            request=req,
+            user=user,
+            db=db,
+            tbl=tbl,
+            record=record or {},
+            record_id=record_id
+        )
+    
+    def _wrap_response(self, content, req):
+        """Wrap content with layout_wrapper if not an HTMX request."""
+        if self.layout_wrapper and not _is_htmx_request(req):
+            return self.layout_wrapper(content, req)
+        return content
+    
+    def _register_routes(self):
+        """Register all data table routes with the app."""
+        rt = self.app.route
+        
+        @rt(self.base_route)
+        def _table_handler(req):
+            return self._handle_table(req)
+        
+        @rt(f"{self.base_route}/action")
+        def _action_handler(req):
+            return self._handle_action(req)
+        
+        @rt(f"{self.base_route}/save")
+        async def _save_handler(req):
+            return await self._handle_save(req)
+    
+    def _get_filtered_data(self, req) -> list:
+        """Get all data from user's callback."""
+        all_data = self.get_all(req)
+        return [_to_dict(item) for item in all_data]
+    
+    def _filter_by_search(self, data: list, search: str) -> list:
+        """Filter data by search term across searchable columns."""
+        if not search:
+            return data
+        
+        needle = search.lower()
+        searchable_keys = [
+            col["key"] for col in self.columns 
+            if col.get("searchable", False)
+        ]
+        
+        if not searchable_keys:
+            searchable_keys = [col["key"] for col in self.columns]
+        
+        return [
+            row for row in data
+            if any(needle in str(row.get(key, "")).lower() for key in searchable_keys)
+        ]
+    
+    def _paginate(self, data: list, page: int, page_size: int) -> tuple:
+        """Paginate data list. Returns (page_rows, total, adjusted_page)."""
+        total = len(data)
+        total_pages = max(1, ceil(total / page_size))
+        page = min(max(1, page), total_pages)
+        start = (page - 1) * page_size
+        end = start + page_size
+        return data[start:end], total, page
+    
+    def _handle_table(self, req):
+        """Handle main table route."""
+        state = table_state_from_request(req, page_sizes=self.page_sizes)
+        search, page, page_size = state["search"], state["page"], state["page_size"]
+        
+        data = self._get_filtered_data(req)
+        filtered = self._filter_by_search(data, search)
+        page_data, total, page = self._paginate(filtered, page, page_size)
+        
+        table = DataTable(
+            data=page_data,
+            total=total,
+            page=page,
+            page_size=page_size,
+            search=search,
+            columns=self.columns,
+            crud_ops=self.crud_ops,
+            base_route=self.base_route,
+            row_id_field=self.row_id_field,
+            title=self.title,
+            container_id=self.container_id,
+            page_sizes=self.page_sizes,
+            search_placeholder=self.search_placeholder,
+            create_label=self.create_label,
+            empty_message=self.empty_message
+        )
+        
+        # Wrap table in auto-refresh container
+        params = urlencode({"search": search, "page": page, "page_size": page_size})
+        table_container = Div(
+            table,
+            id=self.container_id,
+            hx_trigger=f"{self.refresh_trigger} from:body",
+            hx_get=f"{self.base_route}?{params}",
+            hx_target=f"#{self.container_id}",
+            hx_swap="outerHTML"
+        )
+        
+        feedback = Div(id=self.feedback_id)
+        content = Div(feedback, table_container)
+        
+        # Wrap with layout if full-page request
+        return self._wrap_response(content, req)
+    
+    def _handle_action(self, req):
+        """Handle action route (view/edit/create/delete)."""
+        params = getattr(req, "query_params", {})
+        getter = params.get if hasattr(params, "get") else (lambda k, d=None: params[k] if k in params else d)
+        
+        if getter("dismiss") is not None:
+            return Div(id=self.feedback_id)
+        
+        record_id = getter("id")
+        if record_id:
+            try:
+                record_id = int(record_id)
+            except (TypeError, ValueError):
+                pass
+        
+        action = (getter("action", "view") or "view").lower()
+        search = getter("search", "") or ""
+        page = _safe_int(getter("page", 1), 1)
+        page_size = _safe_int(getter("page_size", 10), 10)
+        
+        return_params = urlencode({"search": search, "page": page, "page_size": page_size})
+        cancel_url = f"{self.base_route}/action?dismiss=1"
+        save_url = f"{self.base_route}/save?{return_params}"
+        
+        # Handle CREATE
+        if action == "create":
+            if not self.crud_ops.get("create"):
+                return self._error_toast("Create operation not enabled.")
+            
+            modal = FormModal(
+                columns=self.columns,
+                mode="create",
+                record=None,
+                modal_id=self.modal_id,
+                title=f"New {self.title.rstrip('s')}",
+                save_url=save_url,
+                save_target=f"#{self.feedback_id}",
+                cancel_url=cancel_url,
+                cancel_target=f"#{self.feedback_id}"
+            )
+            return self._wrap_modal(modal)
+        
+        # Get record for view/edit/delete
+        record = None
+        if record_id:
+            raw_record = self.get_by_id(req, record_id)
+            record = _to_dict(raw_record) if raw_record else None
+        
+        if not record:
+            return self._error_toast("Record not found.")
+        
+        # Handle VIEW
+        if action == "view":
+            modal = FormModal(
+                columns=self.columns,
+                mode="view",
+                record=record,
+                modal_id=self.modal_id,
+                title=f"View {self.title.rstrip('s')}",
+                cancel_url=cancel_url,
+                cancel_target=f"#{self.feedback_id}"
+            )
+            return self._wrap_modal(modal)
+        
+        # Handle EDIT
+        if action == "edit":
+            if not self.crud_ops.get("update"):
+                return self._error_toast("Update operation not enabled.")
+            
+            modal = FormModal(
+                columns=self.columns,
+                mode="edit",
+                record=record,
+                modal_id=self.modal_id,
+                title=f"Edit {self.title.rstrip('s')}",
+                save_url=save_url,
+                save_target=f"#{self.feedback_id}",
+                cancel_url=cancel_url,
+                cancel_target=f"#{self.feedback_id}"
+            )
+            return self._wrap_modal(modal)
+        
+        # Handle DELETE
+        if action == "delete":
+            if not self.crud_ops.get("delete"):
+                return self._error_toast("Delete operation not enabled.")
+            
+            try:
+                ctx = self._build_context(req, record=record, record_id=record_id)
+                
+                # Use on_delete hook if provided
+                if self.on_delete_hook:
+                    if asyncio.iscoroutinefunction(self.on_delete_hook):
+                        loop = asyncio.get_event_loop()
+                        loop.run_until_complete(self.on_delete_hook(ctx))
+                    else:
+                        self.on_delete_hook(ctx)
+                else:
+                    # Default: use delete_fn
+                    self.delete_fn(req, record_id)
+                
+                return self._success_toast("Record deleted successfully.")
+            except Exception as e:
+                logger.error(f"Delete failed: {e}", exc_info=True)
+                return self._error_toast(f"Delete failed: {str(e)}")
+        
+        return Div(id=self.feedback_id)
+    
+    async def _handle_save(self, req):
+        """Handle save route (create/update form submission)."""
+        try:
+            form_data = await req.form()
+            record_id = form_data.get(self.row_id_field)
+            
+            if record_id:
+                try:
+                    record_id = int(record_id)
+                except (TypeError, ValueError):
+                    pass
+            
+            # Build data dict from form
+            data = {}
+            for col in self.columns:
+                key = col["key"]
+                if key == self.row_id_field:
+                    continue
+                
+                form_cfg = col.get("form", {})
+                if form_cfg.get("hidden"):
+                    continue
+                
+                value = form_data.get(key)
+                
+                field_type = form_cfg.get("type", "text")
+                if field_type == "number" and value:
+                    try:
+                        value = float(value) if "." in str(value) else int(value)
+                    except (TypeError, ValueError):
+                        pass
+                elif field_type == "checkbox":
+                    value = value == "on" or value == "true" or value == True
+                
+                data[key] = value
+            
+            # Add timestamps
+            now = datetime.now()
+            for field, ts_type in self.timestamp_fields.items():
+                if ts_type == "updated":
+                    data[field] = now
+                elif ts_type == "created" and not record_id:
+                    data[field] = now
+            
+            # CREATE or UPDATE
+            if record_id:
+                # ===== UPDATE =====
+                ctx = self._build_context(req, record=data, record_id=record_id)
+                
+                if self.on_update_hook:
+                    data = await self._call_hook(self.on_update_hook, ctx)
+                    if data is not None:
+                        self.update_fn(req, record_id, data)
+                else:
+                    self.update_fn(req, record_id, data)
+                
+                return self._success_toast("Record updated successfully.")
+            else:
+                # ===== CREATE =====
+                # Generate ID if needed
+                if self.id_generator and self.row_id_field not in data:
+                    data[self.row_id_field] = self.id_generator()
+                
+                ctx = self._build_context(req, record=data, record_id=None)
+                
+                if self.on_create_hook:
+                    data = await self._call_hook(self.on_create_hook, ctx)
+                    if data is not None:
+                        self.create_fn(req, data)
+                else:
+                    self.create_fn(req, data)
+                
+                return self._success_toast("Record created successfully.")
+        
+        except Exception as e:
+            logger.error(f"Save failed: {e}", exc_info=True)
+            return self._error_toast(f"Save failed: {str(e)}")
+    
+    def _wrap_modal(self, modal):
+        """Wrap modal content in feedback div."""
+        if isinstance(modal, list):
+            return Div(*modal, id=self.feedback_id)
+        return Div(modal, id=self.feedback_id)
+    
+    def _success_toast(self, message: str):
+        """✅ Return a success toast with auto-refresh trigger."""
+        toast = Toast(
+            message,
+            variant="success",
+            position="top",
+            action=A(
+                "Dismiss",
+                cls="inverse-link",
+                hx_get=f"{self.base_route}/action?dismiss=1",
+                hx_target=f"#{self.feedback_id}",
+                hx_swap="outerHTML"
+            ),
+            active=True
+        )
+        
+        # Return as HTMLResponse with HX-Trigger for auto-refresh
+        from fasthtml.common import to_xml
+        html_content = to_xml(Div(toast, id=self.feedback_id))
+        response = HTMLResponse(content=html_content)
+        response.headers['HX-Trigger'] = self.refresh_trigger
+        return response
+    
+    def _error_toast(self, message: str):
+        """❌ Return an error toast (no auto-refresh on errors)."""
+        toast = Toast(
+            message,
+            variant="error",
+            position="top",
+            action=A(
+                "Dismiss",
+                cls="inverse-link",
+                hx_get=f"{self.base_route}/action?dismiss=1",
+                hx_target=f"#{self.feedback_id}",
+                hx_swap="outerHTML"
+            ),
+            active=True
+        )
+        return Div(toast, id=self.feedback_id)