feat: Refine trail category model (#1059)

* feat: advanced trail categories

* rename remote_category

* fix merge issues

* subcategories for plugins mapping

* fix refresh

* remove vertical trail filter category scrolling

* cleanup

* add confirm modal for disabling a category

* Fix federation issues

* fix review findings

* redesign category settings page

* remove prio badge

* fix subcategory badge layout

* optimize subcategory settings layout

* further settings page layout optimization

* fix subcategory icon position

* fix

* update docs

---------

Co-authored-by: Christian Beutel <>

docs/astro.config.mjs

@@ -51,6 +51,10 @@ export default defineConfig({
           label: 'Create/Edit a trail',
           link: '/use/create-a-trail/'
         },
+        {
+          label: 'Categories',
+          link: '/use/categories/'
+        },
         {
           label: 'Summit logs',
           link: '/use/summit-logs/'

docs/src/content/docs/develop/plugin-system.md

@@ -536,12 +536,14 @@ Supported host fields:
 | `privacy` | string | Trail import | `original` keeps provider visibility; `settings` uses the local user trail privacy setting. |
 | `merge.enabled` | boolean | Trail import | Runs auto-merge after creating imported trails. |
 | `createSummitLogForCompleted` | boolean | Trail import | Creates summit logs for completed imported trails. Defaults to `true`. |
-| `categoryMapping` | object | Trail import | Maps plugin-provided `metadata.providerCategory` values to local category IDs or category names. |
+| `categoryMapping` | object | Trail import | Maps plugin-provided `metadata.providerCategory` values to local category or subcategory targets. |
 | `connectors` | object | Host request/media policy | Concrete settings for configured connectors. |
 
 The settings UI lets users edit `categoryMapping` per plugin instance for trail
-import plugins. Unknown or empty provider categories still fall back to the
-host's activity-type mapping.
+import plugins. A mapping value can be a string for broad category-only
+compatibility, or an object with `category` and optional `subcategory`. Category
+and subcategory values may be local record IDs or canonical names. Unknown or
+empty provider categories still fall back to the host's activity-type mapping.
 
 Example:
 
@@ -549,7 +551,14 @@ Example:
 {
   "hostConfig": {
     "categoryMapping": {
-      "Ride": "Biking",
+      "Ride": {
+        "category": "Biking",
+        "subcategory": "Road"
+      },
+      "GravelRide": {
+        "category": "Biking",
+        "subcategory": "Gravel"
+      },
       "Hike": "Hiking"
     }
   },

docs/src/content/docs/run/backend-configuration/custom-categories.md

@@ -1,11 +1,12 @@
 ---
 title: Custom categories
-description: How to create custom trail categories
+description: How to configure trail categories and subcategories
 ---
 
 <span class="-tracking-[0.075em]">wanderer</span> uses categories to classify what kind of activity a trail belongs to. 
-Out of the box you get: Biking, Canoeing, Climbing, Hiking, Skiing and Walking. 
-However, you can adapt these categories to your needs or add completely new ones.
+Out of the box you get: Biking, Canoeing, Climbing, Hiking, Running, Skiing and Walking.
+Some broad categories also have subcategories, for example Biking can be refined into MTB, Gravel, Road or E-Bike.
+You can adapt this taxonomy to your needs in the PocketBase admin panel.
 
 ## Modifying categories
 
@@ -15,7 +16,69 @@ In the PocketBase admin panel, click on the `categories` table in the list on th
 All existing categories will be listed here. 
 To edit one simply click on the row, edit the data you want to change, and click "Save". 
 To delete a category check the box at the beginning of the row and click "Delete selected". 
-To create a new category click the "New record" button in the top right corner, give your new category a name and a background image, and click "Save".
+To create a new category click the "New record" button in the top right corner, give your new category a name, optionally fill in display metadata such as `short_name`, `icon`, or localized `translations`, and click "Save".
+
+The category `name` is the canonical, language-independent identity.
+Use stable names such as `Hiking` or `Biking`; display labels in different languages should be stored in `translations`.
+Incoming federated trails and integration imports match categories by a normalized version of `name`, so changing a category name can affect future matching.
+
+### Category fields
+
+| Field | Description |
+| ----- | ----------- |
+| `name` | Canonical category name. This is used for matching across imports and federation. |
+| `short_name` | Optional compact label for space-constrained UI. |
+| `icon` | Optional Font Awesome Free icon name without the `fa-` prefix, for example `person-hiking`. |
+| `translations` | Optional localized display labels. |
+| `settings` | Optional JSON settings for category-specific backend behavior. |
+
+`translations` uses supported base locale codes such as `de`, `en`, `fr`, or `pt` as keys.
+Do not use region-specific keys such as `de-CH` or `pt-BR`; the frontend resolves user locales to their base locale before looking up category translations.
+
+Example:
+
+```json
+{
+  "de": {
+    "name": "Radfahren",
+    "short_name": "RAD"
+  },
+  "en": {
+    "name": "Biking",
+    "short_name": "BIKE"
+  }
+}
+```
+
+## Modifying subcategories
+
+Subcategories live in the `subcategories` table and act as optional refinements below a single parent category. Their names only need to be unique within that parent, so `Road` can exist under both Biking and Running at the same time.
+
+![Pocketbase Subcategories](../../../../assets/guides/pocketbase_subcategories.png)
+
+To add one, create a new record in `subcategories`, choose its parent `category`, set a canonical `name`, and optionally add display metadata.
+
+### Subcategory fields
+
+| Field | Description |
+| ----- | ----------- |
+| `category` | Required parent category. |
+| `name` | Canonical subcategory name, unique within the parent category after normalization. |
+| `short_name` | Compact label shown in icon-based filters, for example `MTB`, `GRVL`, or `ROAD`. |
+| `icon` | Optional Font Awesome Free icon name. If empty, the parent category icon is used. |
+| `badge_icon` | Optional Font Awesome Free overlay icon, for example `snowflake`, `mountain`, `bolt`, or `cross`. |
+| `translations` | Optional localized display labels, using the same structure as category translations. |
+
+Most subcategories should reuse the parent category's icon and rely on `short_name` — plus a `badge_icon` where it helps — to set themselves apart, rather than each carrying a distinct full icon. You can browse available icon names at [fontawesome.com](https://fontawesome.com/search?ic=free-collection).
+
+:::note
+Unknown remote categories and subcategories are not automatically created during federation.
+Raw remote values are stored on the trail and can be matched later when an admin creates a compatible local category or subcategory.
+:::
+
+## Migrating old custom categories
+
+If your instance already had custom categories such as `MTB` or `Gravel` that now overlap with a default subcategory, you can reassign the affected trails in bulk from the web UI. See [Categories](/use/categories/#editing-several-trails-at-once) for the step-by-step migration path.
 
 ## Category settings
 

docs/src/content/docs/use/categories.md

@@ -0,0 +1,58 @@
+---
+title: Categories
+description: How to use trail categories, subcategories, and category visibility settings
+---
+
+Every trail has a category that describes its broad activity type — Hiking, Biking, Running, Skiing, and so on. Many categories can be narrowed down further with a subcategory, such as Biking / Gravel or Hiking / Snowshoeing, whenever you want to be more specific.
+
+## Choosing a category
+
+When you create or edit a trail, pick the activity type with the **Category** selector in the trail form. It lists the broad categories together with their subcategories, so you can stay general or get specific:
+
+- Choose **Hiking** for an ordinary hiking trail.
+- Choose **Hiking / Snowshoeing** to mark it as a snowshoe route.
+- Choose **Biking / Gravel** for a gravel ride.
+
+A broad category on its own is always enough; a subcategory is optional. On trail cards and in lists, the category icon carries a small badge for subcategories that need one — for example a snowflake for winter variants — so you can tell refinements apart at a glance.
+
+## Filtering trails
+
+The filter panel shows each category as an icon. Click an icon to add that category to the filter.
+
+![Trail category filter with the subcategory overlay open](../../../assets/guides/wanderer_trails_category_filter.png)
+
+Categories that have subcategories reveal a subcategory overlay when you hover or focus the icon; on touch devices, long-press it instead. From there you can filter by:
+
+- the whole category,
+- only trails that have no subcategory, or
+- one or more specific subcategories.
+
+When a subcategory filter is active, a small indicator appears on the category icon — that's how you tell "all Biking trails" apart from "only the Biking subcategories I picked".
+
+## Editing several trails at once
+
+To reclassify many trails in one go, select them in the trail list, open the action menu, and choose **Adjust**. The modal lets you set a new category, subcategory, or difficulty for the whole selection.
+
+![The bulk edit modal for adjusting selected trails](../../../assets/guides/wanderer_trails_adjust.png)
+
+This is handy after upgrading an instance, when an older standalone category overlaps with a new subcategory: every trail previously filed under `Gravel`, for instance, can be moved to Biking / Gravel in a single step.
+
+## Category preferences
+
+Open **Settings → Categories** to control how categories behave for your account.
+
+![The category preferences page in Settings](../../../assets/guides/wanderer_settings_categories.png)
+
+Each category has one visibility toggle:
+
+- **Show** controls whether the category is part of your exploration and planning. While it is on, the category appears in search and discovery and is offered in the category picker when you create or edit a trail. Turn it off to hide all trails in that category from those places, including federated trails from other instances.
+
+You can **reorder** categories by dragging them. This order carries over to pickers and filters, and it also decides which category is preselected when you create a new trail. New accounts start with Hiking as the first category unless an older favourite-sport setting is migrated.
+
+Categories with subcategories can be expanded. Inside the expanded section, each subcategory has its own visibility toggle and can be reordered by dragging. Hidden subcategories appear muted and drop out of your pickers and filters; hiding a parent category also hides its subcategories. When a category is collapsed, the compact badges below the category name show which subcategories belong to it.
+
+These settings are personal. They never delete categories, change other users' settings, or remove category assignments that already exist on trails.
+
+:::note
+Categories and subcategories themselves are defined by the instance administrator in PocketBase. As a regular user you choose from the available taxonomy and set your own visibility preferences, but you cannot create global categories from the web UI.
+:::

docs/src/content/docs/use/create-a-trail.md

@@ -65,7 +65,7 @@ While drawing or editing a route, the anchor list shows the route's start, inter
 - **Distance / Duration / Elevation** – These are automatically calculated but can be manually adjusted if needed.
 - **Tags** – Add descriptive tags to help categorize and search for your trail (e.g. forest, sunset, dog-friendly). Start typing to add a tag and press Enter to confirm.
 - **Difficulty** – Select the trail's difficulty (e.g. Easy, Moderate, Hard)
-- **Category** – Choose the activity type (e.g. Hiking, Cycling)
+- **[Category](/use/categories/)** – Choose the activity type. You can select a broad category such as Hiking, or a more specific subcategory such as Biking / Gravel.
 
 #### Visibility
 
@@ -83,7 +83,7 @@ Waypoints are points of interest along the trail.
 - When you are not editing the route, click on the map to open a popup with a **Create waypoint** button at that location.
 - While drawing or editing the route, right-click on the map to open the same popup without placing a route anchor. This works only while waypoint markers are visible (see the waypoint toggle in the route editing toolbar).
 - Each waypoint can have a name, description, icon, and photos.
-- Use Font Awesome icons for map markers. You can browse them at [fontawesome.com](https://fontawesome.com/search?q=share&o=r&m=free).
+- Use Font Awesome icons for map markers. You can browse them at [fontawesome.com](https://fontawesome.com/search?ic=free-collection).
 
 Alternatively, click **From Photos** to upload photos with GPS metadata. Waypoints will be created automatically based on the photo locations.