docs: add sorting

docs/examples/pagination-search.md

@@ -1,6 +1,6 @@
 # Pagination & search
 
-This example builds an articles listing endpoint that supports **offset pagination**, **cursor pagination**, **full-text search**, and **faceted filtering** — all from a single `CrudFactory` definition.
+This example builds an articles listing endpoint that supports **offset pagination**, **cursor pagination**, **full-text search**, **faceted filtering**, and **sorting** — all from a single `CrudFactory` definition.
 
 ## Models
 
@@ -16,7 +16,7 @@ This example builds an articles listing endpoint that supports **offset paginati
 
 ## Crud
 
-Declare `facet_fields` and `searchable_fields` once on [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory). All endpoints built from this class share the same defaults and can override them per call.
+Declare `searchable_fields`, `facet_fields`, and `sort_fields` once on [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory). All endpoints built from this class share the same defaults and can override them per call.
 
 ```python title="crud.py"
 --8<-- "docs_src/examples/pagination_search/crud.py"
@@ -46,14 +46,14 @@ Declare `facet_fields` and `searchable_fields` once on [`CrudFactory`](../refere
 
 Best for admin panels or any UI that needs a total item count and numbered pages.
 
-```python title="routes.py:1:27"
---8<-- "docs_src/examples/pagination_search/routes.py:1:27"
+```python title="routes.py:1:36"
+--8<-- "docs_src/examples/pagination_search/routes.py:1:36"
 ```
 
 **Example request**
 
 ```
-GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published
+GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&sort_by=title&sort_order=asc
 ```
 
 **Example response**
@@ -83,14 +83,14 @@ GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published
 
 Best for feeds, infinite scroll, or any high-throughput API where offset performance degrades.
 
-```python title="routes.py:30:45"
---8<-- "docs_src/examples/pagination_search/routes.py:30:45"
+```python title="routes.py:39:59"
+--8<-- "docs_src/examples/pagination_search/routes.py:39:59"
 ```
 
 **Example request**
 
 ```
-GET /articles/cursor?items_per_page=10&status=published
+GET /articles/cursor?items_per_page=10&status=published&sort_by=created_at&sort_order=desc
 ```
 
 **Example response**

docs/module/crud.md

@@ -295,6 +295,8 @@ Use `filter_by` to pass the client's chosen filter values directly — no need t
 Use [`filter_params()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.filter_params) to generate a dict with the facet filter values from the query parameters:
 
 ```python
+from typing import Annotated
+
 from fastapi import Depends
 
 UserCrud = CrudFactory(
@@ -306,7 +308,7 @@ UserCrud = CrudFactory(
 async def list_users(
     session: SessionDep,
     page: int = 1,
-    filter_by: dict[str, list[str]] = Depends(UserCrud.filter_params()),
+    filter_by: Annotated[dict[str, list[str]], Depends(UserCrud.filter_params())],
 ) -> PaginatedResponse[UserRead]:
     return await UserCrud.offset_paginate(
         session=session,
@@ -323,6 +325,58 @@ GET /users?status=active&country=FR   → filter_by={"status": ["active"], "coun
 GET /users?role=admin&role=editor     → filter_by={"role": ["admin", "editor"]}  (IN clause)
 ```
 
+## Sorting
+
+!!! info "Added in `v1.3`"
+
+Declare `sort_fields` on the CRUD class to expose client-driven column ordering via `sort_by` and `sort_order` query parameters.
+
+```python
+UserCrud = CrudFactory(
+    model=User,
+    sort_fields=[
+        User.name,
+        User.created_at,
+    ],
+)
+```
+
+Call [`sort_params()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.sort_params) to generate a FastAPI dependency that maps the query parameters to an [`OrderByClause`](../reference/crud.md#fastapi_toolsets.crud.factory.OrderByClause) expression:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi_toolsets.crud import OrderByClause
+
+@router.get("")
+async def list_users(
+    session: SessionDep,
+    order_by: Annotated[OrderByClause | None, Depends(UserCrud.sort_params())],
+) -> PaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(session=session, order_by=order_by)
+```
+
+The dependency adds two query parameters to the endpoint:
+
+| Parameter    | Type               |
+| ------------ | ------------------ |
+| `sort_by`    | `str | null`      |
+| `sort_order` | `asc` or `desc` |
+
+```
+GET /users?sort_by=name&sort_order=asc   → ORDER BY users.name ASC
+GET /users?sort_by=name&sort_order=desc  → ORDER BY users.name DESC
+```
+
+An unknown `sort_by` value raises [`InvalidSortFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidSortFieldError) (HTTP 422).
+
+You can also pass `sort_fields` directly to `sort_params()` to override the class-level defaults without modifying them:
+
+```python
+UserSortParams = UserCrud.sort_params(sort_fields=[User.name])
+```
+
 ## Relationship loading
 
 !!! info "Added in `v1.1`"