hxadmin 0.1.0__tar.gz

hxadmin-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+node_modules/
+
+# Demo
+demo/demo.db
+demo_tables/demo_tables.db
+
+# Docs
+site/

hxadmin-0.1.0/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.1.0] - 2026-10-08
+
+### Features
+
+- Add ModelView base and test scaffolding
+- Mount HxAdmin sub-app with dashboard and layout
+- Redirect unauthenticated admin requests to login_url
+- Build sidebar navigation from registered views
+- Vendor htmx, alpine and compiled tailwind assets
+- Add demo todo app for manual testing
+- Derive Field and RelationField from SQLAlchemy mappers
+- Resolve list, detail, sort and pk config on ModelView
+- Add list query params, search, sort, pagination and fetch_one
+- Add searchable, sortable, paginated model list page
+- Add model detail page with lazy related-collection tabs
+- Carry default, unique, autoincrement, choices and widget on fields
+- Resolve form fields and build pydantic schemas per view
+- Parse, validate and apply form values; narrow fetch_one eager loads
+- Add create, edit and delete with inline validation errors
+- Add relation combobox backed by _lookup search
+- Add toasts via HX-Trigger and a one-shot flash cookie
+- Declare row and bulk actions with @action on ModelView
+- Add row and bulk action endpoints with toast responses
+- Render row actions, bulk selection bar and htmx confirm modal
+- Add admin.page and admin.route custom pages in the admin shell
+- Show row counts on the dashboard and add top-bar global search
+- Declare list filters and apply them from f.* query params
+- Add the list filter panel and removable filter chips
+- Write CSV and XLSX exports with typed cells behind the xlsx extra
+- Export the list as shown or the selection from the list page
+- Toast after create, edit and delete; let on_save raise FormError
+- Gate actions with is_action_allowed; show row controls without hover
+- Semantic design tokens and inline Lucide icons
+- Component macro library with popover, menu and dialog behaviour
+- Command palette route and results partial
+- Redesigned shell with collapsible rail sidebar and user menu
+- Dashboard cards, empty-state error page and stat-based demo stats
+- Merge the dashboard, error page and docs redesign
+- Redesign list filters as per-field popovers with OOB summaries
+- Add ModelView.badges for tone-mapped enum/bool cells
+- Float the bulk-selection bar over the list and share its Alpine scope
+- Redesign list table with a row-action menu and mobile card view
+- Redesign detail page header with actions menu and badges
+- Redesign form layout, confirm dialog and toasts
+- Add a themed date/datetime/time picker component
+- Merge the detail, form, dialog, toast and date picker redesign
+- Support plain Core tables mapped with __table__
+- Add a demo built only on plain Core tables
+- Refuse cross-origin writes from browsers
+
+### Bug fixes
+
+- Resolve admin links from request root_path, not mount prefix
+- Install tailwindcss before compiling in nox css session
+- Enforce can_view on related rows and keep list state across swaps
+- Scope relation lookups on save through the target view and harden forms
+- Roll back half-applied edits on unknown selection; keep identifying relations read-only on edit
+- Honour model defaults on create, require non-nullable values on edit, roll back failed hooks
+- Toast HTTP errors on htmx requests and redirect to login only for auth failures
+- Serialise JSON-able page results, allow split-method page routes, reject duplicate pages
+- Send Allow on action 405s and keep HTTPException headers in error responses
+- Keep a handler's own page context key; expose the registration as admin_page
+- Truncate long flash messages so the cookie is not dropped
+- Return native list actions to the list with its search, sort and page
+- Count dashboard rows in one query and isolate views whose counts fail
+- Re-render the detail heading and buttons with the panel after an action
+- Drop filter and pk values outside the 64-bit integer range
+- Read only visible filters, and none on the related tab
+- Reject reverse one-to-one relations as list filters
+- Write NaN and infinite numbers as Excel errors in XLSX exports
+- Keep range bounds and pks that Postgres would reject out of the query
+- Keep range bounds in the form their inputs write
+- Compute toast labels where lazy loads work
+- Return to the list as shown after delete and detail-less save
+- Show the active filter count on the Filters toggle
+- Move sidebar toggle to icon button and restore full breadcrumbs
+- Force the date picker's built-in locale to English
+- Disable htmx settle so swapped popovers keep their Alpine state
+- Render list relation cells as muted text and link only the primary column
+- Use the themed date picker in date, datetime and time range filters
+- Load the date picker stylesheet before the theme so its overrides apply
+- Size list columns to content so the primary column takes the remaining width
+- Show the list row count and stop repeating the page title in breadcrumbs
+- Align the list toolbar on one 32px row and scroll filters on mobile
+- Inset icon-less action items so menu labels line up
+- Make the select-all checkbox select every row and show its indeterminate state
+- Highlight selected list rows and cards
+- Make form inputs 36px high and align the sticky footer with the form
+- Listen for htmx 4 event names so the palette, bulk bar and date picker react to swaps
+- Load palette results when it opens and anchor it near the top
+- Give the error page a clear heading, explanation and way back
+- Drop the date picker's white pointer arrow and tighten its offset
+- Reach the palette on mobile and hide the filter row's scrollbar
+- Stack the detail header on mobile so the title is not truncated
+- Give form selects the same chevron and padding as the comboboxes
+- Close the mobile drawer with an X instead of the desktop rail toggle
+- Keep list pagination on one row on mobile
+- Render the user menu for any auth return value
+- Keep the theme menu when auth returns no user
+- Stop palette typing from re-querying the list behind it
+- Clear only the chosen filter, not filters sharing its prefix
+- Reset the toolbar form from the empty state's Reset filters
+- Submit typed dates and stop date-only values shifting a day
+- Stop nesting a neutral badge round the detail header badges
+- Give the mobile card row menus their own ids
+- Show closed nav groups' items in the rail and hide them pre-paint
+- Set the palette's aria-activedescendant when results load
+- Reject badges values a column cannot hold
+- Remove the phase 5 macros and helpers nothing uses
+- Leave inaccessible views out of the sidebar and palette
+- Quote the date input's x-data like every other JSON attribute
+- Announce error toasts as alerts, link related tabs, show Ctrl off Mac
+- Drop empty params from toolbar requests and pushed URLs
+- Draw checkboxes and radios with the theme tokens
+- Keep the table header visible while the rows scroll
+- Match the spec's page title size, pager label and form alignment
+- Lay the detail body out as a two-column description list
+- Put short form fields two to a row
+- Stop heading a single dashboard card with its category
+- Keep the rail's brand row aligned with the 56px top bar
+- Tidy the mobile list toolbar, selection and bulk bar
+- Open filter calendars beside their popover, not over it
+- Show the pointer cursor on buttons, links and menu items
+- Write the palette shortcut as Ctrl+K like Ctrl+B
+- Disable autoflush inside forms.apply
+- Harden list ordering, lookups, form bounds and database error handling
+
+### Refactoring
+
+- Make ModelView and register generic, inherit view naming
+- Move primary-key helpers to a leaf module; add demo __str__
+- One relation scope resolver, built once per relation filter
+- Group one-model dashboard categories in Python
+- Resolve form widgets and widths in Python
+- Keep the date input formats in one map
+- Render both select-all boxes from one macro
+- Split the list reset into two named helpers
+
+### Documentation
+
+- Add HxAdmin usage to README
+- Configure demo views and document list/detail options
+- Configure demo forms and document form options
+- Add Task.priority to the demo to exercise defaulted non-nullable columns
+- Demo actions and custom pages; document them in the README
+- GET actions must be read-only
+- Add user docs built with Zensical and slim the README
+- Demo filters, built-in export and FormError
+- Relation option order, bound normalisation and Excel limits
+- Describe the redesigned list, detail, forms, shell and components
+- Mention the list row count, row highlight and breadcrumb rule
+- Describe the list selection and mobile toolbar as shipped
+- Turn the besidePanel comment into JSDoc
+
+<!-- generated by git-cliff -->

hxadmin-0.1.0/LICENSE

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

hxadmin-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: hxadmin
+Version: 0.1.0
+Summary: Admin interface for FastAPI and SQLAlchemy 2.0+, built with Tailwind CSS and htmx
+Project-URL: Homepage, https://github.com/gledi-ai/hxadmin
+Project-URL: Documentation, https://github.com/gledi-ai/hxadmin/tree/main/docs
+Project-URL: Source, https://github.com/gledi-ai/hxadmin
+Project-URL: Issues, https://github.com/gledi-ai/hxadmin/issues
+Project-URL: Changelog, https://github.com/gledi-ai/hxadmin/blob/main/CHANGELOG.md
+Author: Gledi Caushaj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,fastapi,htmx,sqlalchemy,tailwind
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: anyio<5.0,>=4.10
+Requires-Dist: fastapi<1.0,>=0.139
+Requires-Dist: jinja2<4.0,>=3.1.6
+Requires-Dist: markupsafe<4.0,>=3.0
+Requires-Dist: pydantic<3.0,>=2.12
+Requires-Dist: python-multipart<1.0.0,>=0.0.30
+Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0.45
+Requires-Dist: starlette<2.0,>=1.2
+Provides-Extra: xlsx
+Requires-Dist: xlsxwriter<4,>=3.2; extra == 'xlsx'
+Description-Content-Type: text/markdown
+
+# hxadmin
+
+Admin interface for FastAPI and async SQLAlchemy 2.0+, built with Jinja2, htmx, Alpine.js and Tailwind CSS.
+
+List, detail, create, edit and delete from class attributes, with search, sort, pagination, per-column filters, row and bulk actions, custom pages, CSV / Excel export and light / dark themes. Async only and fully typed.
+
+## Install
+
+```bash
+pip install hxadmin            # CSV export included
+pip install 'hxadmin[xlsx]'    # adds Excel export
+```
+
+## Quickstart
+
+```python
+from fastapi import FastAPI
+from hxadmin import HxAdmin, ModelView
+
+app = FastAPI()
+admin = HxAdmin(app, session=get_session, auth=current_admin_user, title="My admin")
+
+
+@admin.register
+class UserView(ModelView[User]):
+    model = User
+    list_columns = ("email", "name", "group")
+    searchable = ("email", "name")
+    list_filters = ("active", "group")
+    export_formats = ("csv", "xlsx")
+```
+
+`session` yields an `AsyncSession`; `auth` returns the current user or raises `HTTPException(401)`. Open `/admin/`.
+
+Documentation: [docs](https://github.com/gledi-ai/hxadmin/tree/main/docs) (build locally with `nox -s docs`). Try everything in the demo: `uv run python -m demo`, then open http://127.0.0.1:8001/admin/. For projects built on plain Core `Table`s instead of ORM models, see `uv run python -m demo_tables` (http://127.0.0.1:8002/admin/).
+
+## Development
+
+```bash
+uv sync            # installs the dev group (lint + test + ipython)
+prek install       # git hooks: ruff, pyrefly, uv-lock
+nox                # lint + tests on every supported Python
+nox -s tests-3.14  # single Python version
+nox -s tests_lowest  # tests against the lowest supported dependency versions
+nox -s tests_latest  # tests against the newest allowed releases (weekly in CI)
+nox -s wheel       # tests against the built wheel
+nox -s audit       # dependency vulnerability audit
+nox -s docs        # build the docs strictly into site/
+nox -s css         # rebuild hxadmin.css after template changes (needs Node.js)
+```
+
+Versions come from git tags (`v0.1.0`) via uv-dynamic-versioning.

hxadmin-0.1.0/README.md

@@ -0,0 +1,52 @@
+# hxadmin
+
+Admin interface for FastAPI and async SQLAlchemy 2.0+, built with Jinja2, htmx, Alpine.js and Tailwind CSS.
+
+List, detail, create, edit and delete from class attributes, with search, sort, pagination, per-column filters, row and bulk actions, custom pages, CSV / Excel export and light / dark themes. Async only and fully typed.
+
+## Install
+
+```bash
+pip install hxadmin            # CSV export included
+pip install 'hxadmin[xlsx]'    # adds Excel export
+```
+
+## Quickstart
+
+```python
+from fastapi import FastAPI
+from hxadmin import HxAdmin, ModelView
+
+app = FastAPI()
+admin = HxAdmin(app, session=get_session, auth=current_admin_user, title="My admin")
+
+
+@admin.register
+class UserView(ModelView[User]):
+    model = User
+    list_columns = ("email", "name", "group")
+    searchable = ("email", "name")
+    list_filters = ("active", "group")
+    export_formats = ("csv", "xlsx")
+```
+
+`session` yields an `AsyncSession`; `auth` returns the current user or raises `HTTPException(401)`. Open `/admin/`.
+
+Documentation: [docs](https://github.com/gledi-ai/hxadmin/tree/main/docs) (build locally with `nox -s docs`). Try everything in the demo: `uv run python -m demo`, then open http://127.0.0.1:8001/admin/. For projects built on plain Core `Table`s instead of ORM models, see `uv run python -m demo_tables` (http://127.0.0.1:8002/admin/).
+
+## Development
+
+```bash
+uv sync            # installs the dev group (lint + test + ipython)
+prek install       # git hooks: ruff, pyrefly, uv-lock
+nox                # lint + tests on every supported Python
+nox -s tests-3.14  # single Python version
+nox -s tests_lowest  # tests against the lowest supported dependency versions
+nox -s tests_latest  # tests against the newest allowed releases (weekly in CI)
+nox -s wheel       # tests against the built wheel
+nox -s audit       # dependency vulnerability audit
+nox -s docs        # build the docs strictly into site/
+nox -s css         # rebuild hxadmin.css after template changes (needs Node.js)
+```
+
+Versions come from git tags (`v0.1.0`) via uv-dynamic-versioning.

hxadmin-0.1.0/docs/actions.md

@@ -0,0 +1,55 @@
+# Actions
+
+```python
+from collections.abc import Sequence
+
+from hxadmin import ActionResult, action
+
+
+@admin.register
+class UserView(ModelView[User]):
+    model = User
+
+    @action("deactivate", label="Deactivate", bulk=True, confirm="Deactivate selected users?")
+    async def deactivate(
+        self, request: Request, session: AsyncSession, objs: Sequence[User]
+    ) -> ActionResult:
+        for user in objs:
+            user.active = False
+        return ActionResult.message(f"Deactivated {len(objs)} users")
+
+    @action("reset_password", label="Reset password")
+    async def reset_password(
+        self, request: Request, session: AsyncSession, obj: User
+    ) -> ActionResult:
+        ...
+        return ActionResult.message("Reset link sent", level="info")
+```
+
+Row actions (the default) receive one object. They appear in each list row's `⋯` menu and on the detail page: as buttons when a view has at most two and none has `confirm`, otherwise in the detail `⋯` menu. Bulk actions receive the checked rows, always loaded through `get_query`, and appear in the floating bar at the bottom of the viewport once rows are selected (see [Bulk actions](lists.md#bulk-actions)). `confirm` opens the shared confirmation dialog.
+
+The result shows as a toast in the bottom-right corner with an icon per level. Toasts pause while hovered, and error toasts stay until dismissed.
+
+Return one of:
+
+- `ActionResult.message(text, level="success" | "info" | "warning" | "error")`: re-render the view with a toast;
+- `ActionResult.redirect(url)`;
+- `ActionResult.response(response)`: any Starlette response, for example a download.
+
+hxadmin commits after the handler returns. Any exception rolls back and shows a "<label> failed." toast (the traceback goes to the `hxadmin` logger), except `HTTPException`, which propagates.
+
+POST actions run over htmx. `method="GET"` actions are plain links and form submits, so a returned file downloads. A GET action runs from a plain link, so it must not change data: another site could trigger it. Use POST for anything with side effects.
+
+Handlers get objects without eager-loaded relationships: `await session.refresh(obj, ["group"])` before touching one. A row action that deletes its object should return a redirect; if it returns a message, hxadmin falls back to the list.
+
+## Permissions
+
+Override `is_action_allowed` to limit who may run an action:
+
+```python
+class UserView(ModelView[User]):
+    def is_action_allowed(self, request: Request, name: str) -> bool:
+        return name != "deactivate" or request.state.hxadmin_user.is_superuser
+```
+
+A disallowed action is not rendered anywhere, and its routes answer 403. `request.state.hxadmin_user` is the value your `auth` dependency returned.

hxadmin-0.1.0/docs/auth.md

@@ -0,0 +1,46 @@
+# Auth and sessions
+
+```python
+admin = HxAdmin(
+    app,
+    session=get_session,  # dependency yielding an AsyncSession
+    auth=current_admin_user,  # dependency returning the user, or raising HTTPException
+    prefix="/admin",
+    login_url="/login",  # optional
+    logout_url="/logout",  # optional; shown in the top bar
+    trusted_origins=(),  # optional; other origins allowed to send writes
+)
+```
+
+## Sessions
+
+`session` is any FastAPI dependency that yields or returns an `AsyncSession`. hxadmin uses one session per request, commits after a successful save, delete or action, and rolls back on errors. hxadmin re-queries after commits, so `expire_on_commit=True` sessionmakers work.
+
+## Auth
+
+`auth` runs on every admin request. Its return value is available as `request.state.hxadmin_user` and as `user` in templates. The top bar's user menu shows `user.name` (an attribute or a mapping key) when it is set, otherwise `str(user)`, with initials derived from it. Any return value works: `None` or a bool (an `auth` that only answers "allowed") shows a generic avatar with no name.
+
+To deny access, raise `HTTPException(401)` or `HTTPException(403)`. With `login_url` set, these send the browser to the login page (303, or `HX-Redirect` for htmx requests). Without it, they render an error page.
+
+Per view, `is_accessible(request)` and `is_visible(request)` narrow access further. Per action, `is_action_allowed(request, name)` does; see [Actions](actions.md).
+
+## Cross-site requests
+
+hxadmin refuses state-changing requests (`POST`, `PUT`, `PATCH`, `DELETE`) that a browser sends from another origin, so another site cannot make a signed-in admin's browser create, edit, delete or run an action. This covers every admin route, custom pages included, whatever your `auth` uses (cookies included), and needs no tokens in your templates.
+
+- Browsers send `Sec-Fetch-Site`; a write passes when it is `same-origin` (or `none`, a request the user started directly). `same-site` is refused too, so a sibling subdomain cannot write.
+- Browsers too old for `Sec-Fetch-Site` send `Origin`, which must match the request's `Host`.
+- Requests with neither header do not come from a browser (scripts, tests, server-to-server calls) and pass; `auth` still applies.
+- `GET`, `HEAD` and `OPTIONS` always pass, which is why `method="GET"` actions must not change data (see [Actions](actions.md)).
+
+A refused request gets a 403 ("Cross-origin request blocked.": an error page, or an error toast for htmx) and a warning on the `hxadmin` logger naming the method, path, `Origin` and `Sec-Fetch-Site`.
+
+To accept writes from another origin you control, such as a separate frontend, list it:
+
+```python
+admin = HxAdmin(app, ..., trusted_origins=["https://ops.example.com"])
+```
+
+Each entry is a bare origin, `scheme://host[:port]`, with no path; anything else raises `ValueError`.
+
+Behind a reverse proxy, browsers that only send `Origin` need the proxy to pass the public `Host` header through (e.g. nginx `proxy_set_header Host $host;`). Current browsers send `Sec-Fetch-Site`, which does not depend on the proxy.

hxadmin-0.1.0/docs/export.md

@@ -0,0 +1,45 @@
+# Export
+
+```python
+@admin.register
+class TaskView(ModelView[Task]):
+    model = Task
+    export_formats = ("csv", "xlsx")  # default (): no export
+    export_columns = ()  # default: list_columns
+    export_max_rows = 10_000  # default; None removes the limit
+```
+
+CSV needs nothing extra. Excel export needs XlsxWriter:
+
+```bash
+pip install 'hxadmin[xlsx]'
+```
+
+Listing `"xlsx"` without it installed raises `ImportError` when the view is registered.
+
+## What is exported
+
+The list footer links to `/{prefix}/{identity}/_export/csv` (and `xlsx`) with the current search, filters and sort, and the export contains every matching row across all pages. With rows checked, the selection bar offers an export of just those rows. Rows always come through `get_query`.
+
+When more rows match than `export_max_rows`, no file is produced: the browser returns to the list with a warning toast.
+
+## Cells
+
+The header row has the field labels. A column with a `format_<name>` method exports its output; otherwise:
+
+| Value | CSV | XLSX |
+|---|---|---|
+| empty | empty | blank cell |
+| bool | `true` / `false` | boolean |
+| number | as written | number; NaN is `#NUM!`, infinity `#DIV/0!` |
+| date, datetime, time | ISO 8601 | date cell; aware datetimes converted to UTC |
+| enum | its value | text |
+| many-to-one relation | the related row's `display()` | text |
+| to-many relation | number of rows | number |
+| JSON | JSON text | text |
+
+CSV files are UTF-8 with a byte-order mark so Excel detects the encoding. Text cells starting with `=`, `+`, `-`, `@`, tab or carriage return are prefixed with `'` so spreadsheet programs do not run them as formulas; XLSX cells are always written as text, never as formulas.
+
+Excel's own limits apply to XLSX files: a cell holds at most 32,767 characters (longer text is cut), dates before 1900 are not real dates to Excel, and a sheet has at most 1,048,576 rows.
+
+Files are named `{identity}-{YYYYMMDD-HHMMSS}.{csv|xlsx}` (UTC).

hxadmin-0.1.0/docs/forms.md

@@ -0,0 +1,63 @@
+# Forms
+
+Create and edit forms are derived from the mapper:
+
+- autoincrement primary keys, foreign-key columns covered by a relationship, and columns of a type hxadmin has no input for (`LargeBinary`, `ARRAY`, `Interval`, ...) are skipped; naming such a column in `form_fields` raises at registration;
+- `String(n)` columns accept at most `n` characters, and integer columns the range of their type (`SmallInteger` 16-bit, `Integer` 32-bit, `BigInteger` 64-bit);
+- enum columns become selects, booleans checkboxes, dates and times the themed [date picker](#dates-and-times);
+- relationships become a search-as-you-type combobox, backed by the related view's `searchable` columns (without any, it matches each row's display text, scanning the first 2,000 rows, so give large related tables `searchable` columns): a single relation looks like a select showing the current value with a clear `×`, a multiple one shows its values as removable chips;
+- primary keys, including relationships whose foreign keys form the primary key, are read-only on edit.
+
+The form is a left-aligned column up to 720px wide. Short fields (selects, numbers, checkboxes, dates and times, single relations) sit two to a row from the `sm` breakpoint; text, JSON and multiple relations take the full width.
+
+```python
+from hxadmin import Field
+
+
+@admin.register
+class UserView(ModelView[User]):
+    model = User
+    form_fields = (
+        Field("name", "str", help_text="Full name"),
+        Field("email", "str", "E-mail", widget="email"),
+        "projects",
+    )
+    form_exclude = ("password_hash",)
+```
+
+`form_fields` takes names or `Field(...)` overrides for `label`, `widget`, `required`, `help_text` and `readonly`. An empty non-nullable input is left to the model default on create and reported as required on edit. `DateTime(timezone=True)` columns receive naive values from the datetime picker.
+
+Each field shows its label (with a red `*` when required), the input, the help text and then the error. The Cancel / Save footer sticks to the bottom of the viewport on long forms; the edit page title carries the row's `#pk`.
+
+## Dates and times
+
+Date, datetime and time fields use a vendored [Air Datepicker](https://air-datepicker.com), themed with the admin tokens in light and dark. The visible input shows `mm/dd/yyyy` (plus `hh:mm`), while a hidden input carries the submitted ISO value: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM` or `HH:MM`. Clearing the input with its `×` clears the value. Use it in your own templates through the `date_input` macro:
+
+```jinja
+{% import "_macros.html" as m with context %}
+{{ m.date_input("published_at", "2026-09-23T14:30", kind="datetime") }}
+```
+
+`date_input(name, value=None, kind="date" | "datetime" | "time", id=None, required=False, error=False, readonly=False, form=None, class="", value_class="")`: `class` styles the visible input, `value_class` goes on the hidden one, and `form` sets the hidden input's `form=` attribute. Every change fires a bubbling `change` event on the hidden input. Inside a popover, the calendar opens within it on click or ArrowDown.
+
+## Saving
+
+Validation errors re-render the form in place with status 422, with each message under its field and form-level errors in an alert above the fields. On success, `on_save(request, session, obj, *, created)` runs, then hxadmin commits and redirects with a toast such as *Task "Write docs" created.*
+
+Raise `FormError` from `on_save` to reject a save with a message:
+
+```python
+from hxadmin import FormError
+
+
+class TaskView(ModelView[Task]):
+    async def on_save(
+        self, request: Request, session: AsyncSession, obj: Task, *, created: bool
+    ) -> None:
+        if obj.due_date is not None and obj.due_date < date.today():
+            raise FormError("Due date is in the past.", field="due_date")
+```
+
+The session is rolled back and the form re-renders with the message under `field`, or at the top of the form when `field` is omitted or not on the form. Integrity errors (such as a duplicate unique value) and values the database rejects also roll back and show a generic form-level error; the database's own message, which can name constraints and values, goes to the `hxadmin` logger instead. Any other exception rolls back and propagates: htmx requests get a "Something went wrong." toast, page loads the error page.
+
+Delete lives in the detail page's `⋯` menu and in each list row's menu, and asks first in the shared confirm dialog. Deleting runs `on_delete(request, session, obj)` first; a row that other rows still reference answers 409 with "other records still refer to it" (an error toast over htmx, else the error page).

hxadmin-0.1.0/docs/getting-started.md

@@ -0,0 +1,69 @@
+# Getting started
+
+## Install
+
+```bash
+pip install hxadmin            # CSV export included
+pip install 'hxadmin[xlsx]'    # adds Excel export (XlsxWriter)
+```
+
+hxadmin needs Python 3.13+, FastAPI and SQLAlchemy 2.0+ with an async driver (`asyncpg`, `aiosqlite`, ...).
+
+## A minimal admin
+
+```python
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from hxadmin import HxAdmin, ModelView
+from myapp.models import User
+
+engine = create_async_engine("sqlite+aiosqlite:///app.db")
+sessionmaker = async_sessionmaker(engine, expire_on_commit=False)
+
+
+async def get_session() -> AsyncIterator[AsyncSession]:
+    async with sessionmaker() as session:
+        yield session
+
+
+def current_admin_user() -> dict[str, str]:
+    return {"name": "admin"}
+
+
+app = FastAPI()
+admin = HxAdmin(app, session=get_session, auth=current_admin_user, title="My admin")
+
+
+@admin.register
+class UserView(ModelView[User]):
+    model = User
+```
+
+Run it with `uvicorn myapp:app` and open `/admin/`. The admin is mounted at `prefix` (default `/admin`); the dashboard lists every registered view with its row count, grouped under a heading per `category`; a category holding a single view joins the ungrouped cards, labelled with its category, instead of heading one card.
+
+`session` and `auth` are ordinary FastAPI dependencies; see [Auth and sessions](auth.md).
+
+## Branding
+
+Pass `logo_url` for an image in the sidebar brand block:
+
+```python
+admin = HxAdmin(
+    app, session=get_session, auth=current_admin_user, title="My admin", logo_url="/static/logo.svg"
+)
+```
+
+Without it, the brand block shows the title's first letter in an accent tile.
+
+## The demo
+
+The repository ships a small todo app that exercises every feature:
+
+```bash
+uv run python -m demo
+```
+
+Then open <http://127.0.0.1:8001/admin/>.

hxadmin-0.1.0/docs/index.md

@@ -0,0 +1,30 @@
+# hxadmin
+
+Admin interface for FastAPI and async SQLAlchemy 2.0+, rendered with Jinja2, htmx, Alpine.js and Tailwind CSS.
+
+- One `ModelView` class per model: list, detail, create, edit and delete from class attributes.
+- Search, sort, pagination and per-column filters on every list.
+- Row and bulk actions with a shared confirmation dialog and toasts.
+- Custom pages that share the admin shell.
+- CSV export built in; Excel `.xlsx` export with the `xlsx` extra.
+- Light, dark and system themes.
+- Async only, fully typed (`py.typed`), no WTForms, no sync engines.
+
+```python
+from fastapi import FastAPI
+from hxadmin import HxAdmin, ModelView
+
+app = FastAPI()
+admin = HxAdmin(app, session=get_session, auth=current_admin_user)
+
+
+@admin.register
+class UserView(ModelView[User]):
+    model = User
+    list_columns = ("email", "name", "group")
+    searchable = ("email", "name")
+    list_filters = ("active", "group")
+    export_formats = ("csv",)
+```
+
+Start with [Getting started](getting-started.md).