fastapi-admin-kit 0.1.0__py3-none-any.whl

fastapi_admin_kit/templates/partials/pagination.html

@@ -0,0 +1,82 @@
+{# partials/pagination.html — reusable pagination component #}
+{% macro render_pagination(page, total_pages, total_items, per_page, next_cursor=None, has_next=false, pagination_mode="offset") %}
+{% if pagination_mode and "cursor" in pagination_mode %}
+{# Cursor-based pagination #}
+<div class="pagination">
+  <div class="pagination-info">
+    {% if has_next or total_items > per_page %}
+    {% if page is defined and page > 1 %}
+    Showing cursor-based results (page {{ page }})
+    {% else %}
+    Showing cursor-based results
+    {% endif %}
+    {% else %}
+    Showing all {{ total_items | int }} results
+    {% endif %}
+  </div>
+  <div class="pagination-links">
+    {% if has_next %}
+    <a href="?after={{ next_cursor }}" class="pagination-link" title="Next page">
+      {{ icon("chevron-right") }}
+    </a>
+    {% else %}
+    <span class="pagination-link pagination-link--disabled">
+      {{ icon("chevron-right") }}
+    </span>
+    {% endif %}
+  </div>
+</div>
+{% else %}
+{# Offset-based pagination (default) #}
+<div class="pagination">
+  <div class="pagination-info">
+    Showing {{ ((page - 1) * per_page + 1) | int }} to {{ (page * per_page) if page < total_pages else total_items | int }} of {{ total_items | int }} results
+  </div>
+  <div class="pagination-links">
+    {% if page > 1 %}
+    <a href="?page={{ page - 1 }}" class="pagination-link" title="Previous page">
+      {{ icon("chevron-left") }}
+    </a>
+    {% else %}
+    <span class="pagination-link pagination-link--disabled">
+      {{ icon("chevron-left") }}
+    </span>
+    {% endif %}
+
+    {% set start_page = [1, page - 2] | max %}
+    {% set end_page = [total_pages, page + 2] | min %}
+
+    {% if start_page > 1 %}
+    <a href="?page=1" class="pagination-link">1</a>
+    {% if start_page > 2 %}
+    <span class="pagination-ellipsis">...</span>
+    {% endif %}
+    {% endif %}
+
+    {% for p in range(start_page, end_page + 1) %}
+    <a href="?page={{ p }}"
+       class="pagination-link {% if p == page %}pagination-link--active{% endif %}">
+      {{ p }}
+    </a>
+    {% endfor %}
+
+    {% if end_page < total_pages %}
+    {% if end_page < total_pages - 1 %}
+    <span class="pagination-ellipsis">...</span>
+    {% endif %}
+    <a href="?page={{ total_pages }}" class="pagination-link">{{ total_pages }}</a>
+    {% endif %}
+
+    {% if page < total_pages %}
+    <a href="?page={{ page + 1 }}" class="pagination-link" title="Next page">
+      {{ icon("chevron-right") }}
+    </a>
+    {% else %}
+    <span class="pagination-link pagination-link--disabled">
+      {{ icon("chevron-right") }}
+    </span>
+    {% endif %}
+  </div>
+</div>
+{% endif %}
+{% endmacro %}

fastapi_admin_kit/templates/partials/permission_widget.html

@@ -0,0 +1,86 @@
+{# partials/permission_widget.html
+   Args: search_url, perm_data (JSON-serializable dict)
+#}
+<div x-data="permissionWidget('{{ search_url }}', {{ perm_data | tojson | forceescape }})">
+  <input type="hidden" name="perm_data" :value="serializedPermData">
+
+  <div class="space-y-3">
+    <template x-for="(table, index) in selectedTables" :key="table.id">
+      <div class="border border-[var(--color-gray-200)] rounded-lg overflow-hidden">
+        <div class="flex items-center justify-between px-4 py-3 bg-[var(--color-gray-50)] cursor-pointer hover:bg-[var(--color-gray-100)]"
+             @click="toggleExpand(table.id)">
+          <div class="flex items-center gap-3">
+            <span class="text-sm font-medium text-[var(--color-gray-900)]" x-text="table.label"></span>
+            <span class="text-xs text-[var(--color-gray-500)]" x-text="table.id"></span>
+          </div>
+          <div class="flex items-center gap-2">
+            <span class="text-xs px-2 py-0.5 rounded-full"
+                  :class="permData[table.id]?.view || permData[table.id]?.create || permData[table.id]?.edit || permData[table.id]?.delete
+                    ? 'bg-green-100 text-green-700'
+                    : 'bg-[var(--color-gray-100)] text-[var(--color-gray-500)]'"
+                  x-text="(permData[table.id]?.view ? 'V ' : '') + (permData[table.id]?.create ? 'C ' : '') + (permData[table.id]?.edit ? 'E ' : '') + (permData[table.id]?.delete ? 'D ' : '') || 'None'">
+            </span>
+            <button type="button" @click.stop="toggleExpand(table.id)"
+                    class="text-[var(--color-gray-400)] hover:text-[var(--color-gray-600)]">
+              <svg class="w-4 h-4 transition-transform" :class="expandedTable === table.id ? 'rotate-180' : ''"
+                   fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
+              </svg>
+            </button>
+            <button type="button" @click.stop="removeTable(index)"
+                    class="text-[var(--color-gray-400)] hover:text-red-500 ml-1">
+              <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/>
+              </svg>
+            </button>
+          </div>
+        </div>
+
+        <div x-show="expandedTable === table.id" x-collapse class="px-4 py-4 bg-white">
+          <div class="flex items-center justify-between mb-3">
+            <span class="text-xs font-medium text-[var(--color-gray-500)] uppercase tracking-wide">Actions</span>
+            <div class="flex gap-2">
+              <button type="button" @click="toggleAllActions(table.id, true)"
+                      class="text-xs text-[var(--color-primary-600)] hover:text-[var(--color-primary-500)]">All</button>
+              <span class="text-[var(--color-gray-300)]">|</span>
+              <button type="button" @click="toggleAllActions(table.id, false)"
+                      class="text-xs text-[var(--color-gray-500)] hover:text-[var(--color-gray-700)]">None</button>
+            </div>
+          </div>
+          <div class="grid grid-cols-2 md:grid-cols-4 gap-3">
+            <template x-for="action in ['view', 'create', 'edit', 'delete']" :key="action">
+              <label class="flex items-center gap-2 p-2 rounded border border-[var(--color-gray-200)] cursor-pointer hover:bg-[var(--color-gray-50)]">
+                <input type="checkbox"
+                       :checked="permData[table.id]?.[action]"
+                       @change="permData[table.id][action] = $event.target.checked"
+                       class="rounded border-[var(--color-gray-300)] text-[var(--color-primary-600)] focus:ring-[var(--color-primary-500)]">
+                <span class="text-sm capitalize" x-text="action"></span>
+              </label>
+            </template>
+          </div>
+        </div>
+      </div>
+    </template>
+  </div>
+
+  <div class="mt-4" style="position: relative;">
+    <div class="flex items-center gap-2">
+      <div class="flex-1 relative">
+        <input type="text" x-model="searchQuery" @input="search()" @focus="open = true" @click.outside="open = false"
+               placeholder="Search tables to add..."
+               class="form-input w-full">
+      </div>
+    </div>
+    <div x-show="open && results.length > 0" x-cloak
+         style="position: absolute; z-index: 50; width: 100%; margin-top: 4px; background: var(--surface-base); border: 1px solid var(--surface-border); border-radius: var(--radius-md); box-shadow: var(--shadow-md); max-height: 200px; overflow-y: auto;">
+      <template x-for="result in results" :key="result.id">
+        <div @click="addTable(result)"
+             style="padding: 8px 12px; cursor: pointer; font-size: 0.875rem;"
+             onmouseover="this.style.background='var(--surface-hover)'" onmouseout="this.style.background=''">
+          <span x-text="result.label"></span>
+          <span class="text-xs text-[var(--color-gray-400)] ml-2" x-text="result.id"></span>
+        </div>
+      </template>
+    </div>
+  </div>
+</div>

fastapi_admin_kit/templates/partials/scripts.html

@@ -0,0 +1,13 @@
+    <script src="/static/js/admin.js?v={{ static_version }}"></script>
+    <script src="/static/js/htmx-config.js"></script>
+    <script>
+      // Mobile menu button visibility
+      (function() {
+        var mql = window.matchMedia('(max-width: 1024px)');
+        var btn = document.getElementById('mobile-menu-btn');
+        function check(e) { btn.style.display = e.matches ? 'inline-flex' : 'none'; }
+        mql.addEventListener('change', check);
+        check(mql);
+      })();
+    </script>
+    {% block scripts %}{% endblock %}

fastapi_admin_kit/templates/partials/sidebar.html

@@ -0,0 +1,94 @@
+{# partials/sidebar.html — navigation sidebar with collapsible groups #}
+{% set _ui = ui_config | default({}) %}
+<aside class="admin-sidebar sidebar--{{ _ui.sidebar_style | default('default') }}{% if _ui.sidebar_position | default('left') == 'right' %} sidebar--right{% endif %}"
+       :class="{ 'open': sidebarOpen, 'collapsed': sidebarCollapsed && window.innerWidth >= 1024 }"
+       :style="sidebarCollapsed && window.innerWidth >= 1024 ? 'width: var(--sidebar-collapsed-width)' : 'width: var(--sidebar-width)'"
+       x-show="true">
+
+  <nav class="sidebar-nav">
+    <ul class="sidebar-nav-list">
+      {# Dashboard link #}
+      {% if dashboard_visible | default(true) %}
+      <li class="sidebar-nav-item">
+        <a href="{{ admin_path | default('/admin') }}/"
+           class="nav-link {% if request.url.path == admin_path | default('/admin') ~ '/' %}active{% endif %}">
+          {{ icon("home", size="18px") }}
+          <span class="nav-link-label">Dashboard</span>
+          <span class="nav-tooltip" x-show="sidebarCollapsed">Dashboard</span>
+        </a>
+      </li>
+      {% endif %}
+
+      {# Nav Groups — collapsible #}
+
+      {% for group in nav_groups %}
+      <li class="sidebar-section" x-data="{ open: {{ 'true' if not group.collapsed_by_default else 'false' }} }">
+        <button type="button" @click="open = !open"
+                class="sidebar-section-toggle">
+          <span class="sidebar-section-label">{{ group.label }}</span>
+          {{ icon("chevron-right", size="14px") }}
+        </button>
+        <ul class="sidebar-section-items" x-show="open" x-collapse x-cloak>
+          {% for item in group.items %}
+          <li class="sidebar-nav-item">
+            <a href="{{ item.url }}"
+               class="nav-link {% if not item.icon %}nav-link--no-icon{% endif %} {% if request.url.path.startswith(item.url) %}active{% endif %}">
+              {% if item.icon %}
+              {{ icon(item.icon, size="18px") }}
+              {% endif %}
+              <span class="nav-link-label">{{ item.label }}</span>
+              {% if item.badge_fn %}
+              {% set badge = item.badge_fn() %}
+              {% if badge %}
+              <span class="nav-link-badge">{{ badge }}</span>
+              {% endif %}
+              {% endif %}
+              <span class="nav-tooltip" x-show="sidebarCollapsed">{{ item.label }}</span>
+            </a>
+            {% if item.children %}
+            <ul class="sidebar-sub-items">
+              {% for child in item.children %}
+              <li class="sidebar-nav-item sidebar-nav-item--child">
+                <a href="{{ child.url }}"
+                   class="nav-link nav-link--child {% if request.url.path.startswith(child.url) %}active{% endif %}">
+                  {% if child.icon %}
+                  {{ icon(child.icon, size="16px") }}
+                  {% endif %}
+                  <span class="nav-link-label">{{ child.label }}</span>
+                </a>
+              </li>
+              {% endfor %}
+            </ul>
+            {% endif %}
+          </li>
+          {% endfor %}
+        </ul>
+      </li>
+      {% endfor %}
+    </ul>
+  </nav>
+
+  {# Settings at bottom #}
+  {% if settings_visible | default(true) %}
+  <div class="sidebar-bottom">
+    <ul class="sidebar-nav-list">
+      <li class="sidebar-nav-item">
+        <a href="{{ admin_path | default('/admin') }}/settings/"
+           class="nav-link {% if request.url.path.startswith(admin_path | default('/admin') ~ '/settings') %}active{% endif %}">
+          {{ icon("cog-6-tooth", size="18px") }}
+          <span class="nav-link-label">Settings</span>
+          <span class="nav-tooltip" x-show="sidebarCollapsed">Settings</span>
+        </a>
+      </li>
+    </ul>
+  </div>
+  {% endif %}
+</aside>
+
+{# Mobile sidebar overlay #}
+<div class="admin-sidebar-overlay"
+     :class="{ 'open': sidebarOpen }"
+     @click="sidebarOpen = false"
+     x-show="window.innerWidth < 1024 && sidebarOpen"
+     style="display: none;">
+</div>

fastapi_admin_kit/templates/partials/topbar.html

@@ -0,0 +1,95 @@
+{# partials/topbar.html — top navigation bar matching reference #}
+{% set _ui = ui_config | default({}) %}
+<header class="admin-topbar topbar--{{ _ui.topbar_style | default('default') }}">
+  {# Left zone: collapse toggle, logo #}
+  <div class="topbar-left">
+    <button class="collapse-toggle"
+            @click="if (window.innerWidth < 1024) { toggleMobileSidebar(); } else { sidebarCollapsed = !sidebarCollapsed; }"
+            title="Toggle sidebar">
+      {{ icon("bars-3", size="18px") }}
+    </button>
+
+    <a href="{{ admin_path | default('/admin') }}/" class="topbar-logo">
+      {% if admin_config.logo_url %}
+      <img src="{{ admin_config.logo_url }}" alt="Logo" style="height: 28px; max-width: 120px;">
+      {% else %}
+      <span class="topbar-logo-icon">
+        {{ icon("shield-check", size="24px") }}
+      </span>
+      <span>{{ admin_config.title | default("Admin") }}</span>
+      {% endif %}
+    </a>
+  </div>
+
+  {# Center zone: search bar #}
+  <div class="topbar-center">
+    <div class="topbar-search" @click="$dispatch('open-command-palette')">
+      {{ icon("magnifying-glass", size="16px") }}
+      <span class="topbar-search-placeholder">Search anything...</span>
+      <span class="topbar-search-shortcut">
+        <kbd>⌘</kbd><kbd>K</kbd>
+      </span>
+    </div>
+  </div>
+
+  {# Right zone: environment, notifications, dark toggle, user #}
+  <div class="topbar-right">
+    {% if _ui.environment_label | default('') %}
+    <span class="badge badge-{{ _ui.environment_color | default('info') }}">
+      {{ _ui.environment_label }}
+    </span>
+    {% endif %}
+
+    {# Dark mode toggle #}
+    <button class="icon-btn"
+            @click="$store.theme.toggle()"
+            title="Toggle dark mode">
+      <span x-show="!$store.theme.dark">{{ icon("moon", size="18px") }}</span>
+      <span x-show="$store.theme.dark" style="display: none;">{{ icon("sun", size="18px") }}</span>
+    </button>
+
+    {# Notifications #}
+    <button class="icon-btn" title="Notifications">
+      {{ icon("bell", size="18px") }}
+    </button>
+
+    {# User avatar dropdown #}
+    <div class="topbar-user" x-data="{ open: false }">
+      <button @click="open = !open" @click.outside="open = false"
+              class="topbar-user-btn">
+        <div class="user-avatar">
+          {{ current_user.full_name[0] | upper if current_user and current_user.full_name else "A" }}
+        </div>
+        <div class="topbar-user-info">
+          <span class="topbar-user-name">{{ current_user.full_name | default("Admin") }}</span>
+          <span class="topbar-user-role">{{ "Superuser" if current_user and current_user.is_superuser else "Admin" }}</span>
+        </div>
+        {{ icon("chevron-down", size="14px") }}
+      </button>
+
+      <div x-show="open"
+           x-transition:enter="transition ease-out duration-100"
+           x-transition:enter-start="opacity-0 scale-95"
+           x-transition:enter-end="opacity-100 scale-100"
+           x-transition:leave="transition ease-in duration-75"
+           x-transition:leave-start="opacity-100 scale-100"
+           x-transition:leave-end="opacity-0 scale-95"
+           class="user-dropdown"
+           style="display: none;">
+        <div class="user-dropdown-header">
+          <div class="user-dropdown-name">{{ current_user.full_name | default("Admin") }}</div>
+          <div class="user-dropdown-email">{{ current_user.email | default("") }}</div>
+        </div>
+        <a href="{{ admin_path | default('/admin') }}/profile/" class="user-dropdown-item">
+          Profile
+        </a>
+        <form method="post" action="{{ admin_path | default('/admin') }}/logout/">
+          <input type="hidden" name="csrf_token" value="{{ get_csrf_token(request) }}">
+          <button type="submit" class="user-dropdown-item danger">
+            Sign out
+          </button>
+        </form>
+      </div>
+    </div>
+  </div>
+</header>

fastapi_admin_kit/types.py

@@ -0,0 +1,145 @@
+"""Core data structures for FastAPI Admin Kit — ColumnMeta, RelationMeta, FieldMeta, etc."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ColumnMeta:
+    """Metadata for a single SQLAlchemy column."""
+
+    name: str
+    type: Any  # SQLAlchemy type instance
+    nullable: bool = True
+    primary_key: bool = False
+    foreign_keys: list = field(default_factory=list)
+    default: Any = None
+    server_default: Any = None
+    index: bool = False
+    unique: bool = False
+
+    @property
+    def is_foreign_key(self) -> bool:
+        return bool(self.foreign_keys)
+
+
+@dataclass
+class RelationMeta:
+    """Metadata for a single SQLAlchemy relationship."""
+
+    name: str
+    direction: str  # MANYTOONE, ONETOMANY, MANYTOMANY
+    target_model: type
+    uselist: bool = True
+    back_populates: str | None = None
+    secondary: Any = None  # association table for many-to-many
+
+
+@dataclass
+class FieldMeta:
+    """Metadata for a form field — drives widget rendering and validation."""
+
+    name: str
+    label: str
+    required: bool
+    readonly: bool = False
+    help_text: str | None = None
+    placeholder: str | None = None
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass
+class PermissionSet:
+    """Set of boolean permissions for a single model."""
+
+    can_view: bool = False
+    can_create: bool = False
+    can_edit: bool = False
+    can_delete: bool = False
+
+
+@dataclass
+class FieldsetSpec:
+    """Defines a logical grouping of fields within a form."""
+
+    title: str | None = None
+    collapsed: bool = False
+    fields: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SeedRole:
+    """Defines a role to be seeded on first startup."""
+
+    name: str
+    description: str = ""
+    permissions: dict[str, dict[str, bool]] = field(default_factory=dict)
+
+
+@dataclass
+class FieldRenderContext:
+    meta: FieldMeta
+    widget_macro: str
+    widget_context: dict = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FieldsetContext:
+    title: str | None = None
+    collapsed: bool = False
+    fields: list[FieldRenderContext] = field(default_factory=list)
+
+
+@dataclass
+class FormContext:
+    model_name: str
+    verbose_name: str
+    is_create: bool
+    obj: Any = None
+    fieldsets: list[FieldsetContext] = field(default_factory=list)
+    errors: dict[str, list[str]] = field(default_factory=dict)
+    values: dict[str, Any] = field(default_factory=dict)
+    action_url: str = ""
+    list_url: str = ""
+    can_delete: bool = False
+    permissions: PermissionSet = field(default_factory=PermissionSet)
+    readonly: bool = False
+
+
+@dataclass
+class ExtraField:
+    name: str
+    label: str = ""
+    widget: Any = None
+    default: Any = None
+    required: bool = False
+    required_on_create: bool | None = None
+
+
+@dataclass
+class TabConfig:
+    """Configuration for changelist tabs."""
+    title: str
+    url: str = ""
+    permission: str | None = None
+    is_active: bool = False
+
+
+@dataclass
+class TableSection:
+    """Expandable section showing a related table."""
+    title: str
+    related_model: Any = None
+    related_field: str = ""
+    list_display: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TemplateSection:
+    """Expandable section rendering a custom template."""
+    title: str
+    template: str = ""
+    context_fn: Any = None

fastapi_admin_kit/validation.py

@@ -0,0 +1,43 @@
+"""FormValidator — three-level validation runner."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FormValidator:
+    def run(
+        self,
+        registered: Any,
+        parsed: dict[str, Any],
+        obj: Any = None,
+    ) -> dict[str, list[str]]:
+        errors: dict[str, list[str]] = {}
+
+        for field_meta in registered.form_fields:
+            if field_meta.readonly:
+                continue
+            widget = registered.get_widget(field_meta.name)
+            value = parsed.get(field_meta.name)
+
+            widget_errors = widget.validate(value, field_meta)
+            if widget_errors:
+                errors[field_meta.name] = widget_errors
+                continue
+
+            validator_fn = getattr(
+                registered.admin, f"validate_{field_meta.name}", None
+            )
+            if validator_fn:
+                result = validator_fn(value, obj=obj)
+                if result:
+                    errors[field_meta.name] = (
+                        [result] if isinstance(result, str) else list(result)
+                    )
+
+        if not errors and hasattr(registered.admin, "validate"):
+            obj_errors = registered.admin.validate(parsed, obj=obj)
+            for fname, err in obj_errors.items():
+                errors[fname] = [err] if isinstance(err, str) else list(err)
+
+        return errors

fastapi_admin_kit/views/__init__.py

@@ -0,0 +1,78 @@
+"""Views package — re-exports ModelAdmin and route factories."""
+
+from fastapi_admin_kit.modeladmin import ModelAdmin
+from fastapi_admin_kit.views.bulk import bulk_factory
+from fastapi_admin_kit.views.class_views import (
+    BaseView,
+    BulkView,
+    CreateView,
+    DeleteView,
+    EditView,
+    ListView,
+    SearchView,
+    _resolve_view_class,
+)
+from fastapi_admin_kit.views.context import DisplayColumn, ViewContextBuilder
+from fastapi_admin_kit.views.delete import delete_factory
+from fastapi_admin_kit.views.extra import AdminExtra
+from fastapi_admin_kit.views.factory import ViewFactory
+from fastapi_admin_kit.views.form import (
+    create_form_factory,
+    create_submit_factory,
+    edit_form_factory,
+    edit_submit_factory,
+)
+from fastapi_admin_kit.views.list import list_view_factory
+from fastapi_admin_kit.views.search import search_factory
+from fastapi_admin_kit.views.sidebar import inject_sidebar_context
+
+
+def create_model_router(registered):
+    """Create a model router - backward compatible wrapper around build_model_router."""
+    from fastapi_admin_kit.router import build_model_router
+
+    return build_model_router(registered)
+
+
+__all__ = [
+    "ModelAdmin",
+    "ViewContextBuilder",
+    "ViewFactory",
+    "DisplayColumn",
+    "inject_sidebar_context",
+    "_resolve_view_class",
+    # Protocols (ISP: small focused interfaces)
+    "QueryProvider",
+    "FormParser",
+    "HTMLRenderer",
+    "APIRenderer",
+    # Concrete implementations (SRP: each does one thing)
+    "DefaultQueryProvider",
+    "HTMLFormParser",
+    "JSONBodyParser",
+    "ListHTMLRenderer",
+    "FormHTMLRenderer",
+    "ListAPIRenderer",
+    "ItemAPIRenderer",
+    "DeleteAPIRenderer",
+    # View classes (OCP: extend without modifying)
+    "BaseView",
+    "ListView",
+    "CreateView",
+    "EditView",
+    "DeleteView",
+    "BulkView",
+    "SearchView",
+    # Per-model assets
+    "AdminExtra",
+    # Backward-compatible factory functions
+    "list_view_factory",
+    "create_form_factory",
+    "create_submit_factory",
+    "edit_form_factory",
+    "edit_submit_factory",
+    "delete_factory",
+    "bulk_factory",
+    "search_factory",
+    "create_model_router",
+]