fh-matui 0.9__py3-none-any.whl

fh_matui/datatable.py

@@ -0,0 +1,718 @@
+"""Data table with pagination, search, sorting, and inline actions"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/05_table.ipynb.
+
+# %% auto 0
+__all__ = ['PAGE_SIZES', 'table_state_from_request', 'DataTable', 'DataTableResource']
+
+# %% ../nbs/05_table.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_table.ipynb 6
+#| 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_table.ipynb 8
+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)
+
+
+class DataTableResource:
+    "High-level resource that auto-registers all routes for a data table."
+    
+    def __init__(
+        self,
+        app,
+        base_route: str,
+        columns: list[dict],
+        get_all: Callable[[], list],
+        get_by_id: Callable[[Any], Any],
+        create: Callable[[dict], Any] = None,
+        update: Callable[[Any, dict], Any] = None,
+        delete: Callable[[Any], bool] = None,
+        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.",
+        # Lifecycle hooks
+        on_before_create: Callable[[dict], dict] = None,
+        on_after_create: Callable[[Any], None] = None,
+        on_before_update: Callable[[Any, dict], dict] = None,
+        on_after_update: Callable[[Any], None] = None,
+        on_before_delete: Callable[[Any], bool] = None,
+        on_after_delete: Callable[[Any], None] = None,
+        # Multi-tenant
+        user_filter: Callable = None,
+        # 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,
+                "update": update is not None,
+                "delete": delete is not None
+            }
+        else:
+            self.crud_ops = crud_ops
+        
+        # Lifecycle hooks
+        self.on_before_create = on_before_create
+        self.on_after_create = on_after_create
+        self.on_before_update = on_before_update
+        self.on_after_update = on_after_update
+        self.on_before_delete = on_before_delete
+        self.on_after_delete = on_after_delete
+        
+        # Multi-tenant
+        self.user_filter = user_filter
+        
+        # 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"
+        
+        # Register routes
+        self._register_routes()
+    
+    def _register_routes(self):
+        """Register all data table routes with the app."""
+        rt = self.app.route
+        
+        # Main table route
+        @rt(self.base_route)
+        def _table_handler(req):
+            return self._handle_table(req)
+        
+        # Action route (view/edit/create/delete)
+        @rt(f"{self.base_route}/action")
+        def _action_handler(req):
+            return self._handle_action(req)
+        
+        # Save route (form submission)
+        @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, optionally filtered by user_filter."""
+        all_data = self.get_all()
+        
+        # Convert to list of dicts
+        data = [_to_dict(item) for item in all_data]
+        
+        # Apply user filter if provided
+        if self.user_filter and callable(self.user_filter):
+            filter_criteria = self.user_filter(req)
+            if filter_criteria:
+                data = [
+                    row for row in data
+                    if all(row.get(k) == v for k, v in filter_criteria.items())
+                ]
+        
+        return 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 no columns marked searchable, search all
+        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."""
+        # Extract pagination state
+        state = table_state_from_request(req, page_sizes=self.page_sizes)
+        search, page, page_size = state["search"], state["page"], state["page_size"]
+        
+        # Get and filter data
+        data = self._get_filtered_data(req)
+        filtered = self._filter_by_search(data, search)
+        
+        # Paginate
+        page_data, total, page = self._paginate(filtered, page, page_size)
+        
+        # Build table
+        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
+        )
+        
+        return table
+    
+    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)
+        
+        # Handle dismiss
+        if getter("dismiss") is not None:
+            return Div(id=self.feedback_id)
+        
+        record_id = getter("id")
+        # Try to convert to int if numeric
+        if record_id:
+            try:
+                record_id = int(record_id)
+            except (TypeError, ValueError):
+                pass  # Keep as string (e.g., UUID)
+        
+        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)
+        
+        # URLs
+        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(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.")
+            
+            # Check before_delete hook
+            if self.on_before_delete:
+                if not self.on_before_delete(record_id):
+                    return self._error_toast("Delete cancelled by validation.")
+            
+            # Perform delete
+            try:
+                self.delete_fn(record_id)
+                
+                # After delete hook
+                if self.on_after_delete:
+                    self.on_after_delete(record_id)
+                
+                return self._success_toast(f"Record deleted successfully.")
+            except Exception as e:
+                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)
+            
+            # Try to convert ID
+            if record_id:
+                try:
+                    record_id = int(record_id)
+                except (TypeError, ValueError):
+                    pass
+            
+            # Build data dict from form, excluding the ID field
+            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)
+                
+                # Type conversion based on form config
+                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
+                if self.on_before_update:
+                    data = self.on_before_update(record_id, data)
+                
+                result = self.update_fn(record_id, data)
+                
+                if self.on_after_update:
+                    self.on_after_update(result)
+                
+                return self._success_toast("Record updated successfully.")
+            else:
+                # CREATE
+                if self.on_before_create:
+                    data = self.on_before_create(data)
+                
+                # Generate ID if needed
+                if self.id_generator:
+                    data[self.row_id_field] = self.id_generator()
+                
+                result = self.create_fn(data)
+                
+                if self.on_after_create:
+                    self.on_after_create(result)
+                
+                return self._success_toast("Record created successfully.")
+        
+        except Exception as e:
+            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 in the feedback div."""
+        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 Div(toast, id=self.feedback_id)
+    
+    def _error_toast(self, message: str):
+        """Return an error toast in the feedback div."""
+        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)