feat: implement explicit action-aware template naming convention for improved clarity in product catalog

Author: mkjsix

README.md

@@ -13,7 +13,7 @@ Facet is a server-side rendering framework that maps REST API responses to HTML
 ```http
 GET /shop/products
 Accept: application/json  →  JSON response (REST API unchanged)
-Accept: text/html         →  HTML rendered from templates/shop/products/index.html
+Accept: text/html         →  HTML rendered from templates/shop/products/list.html
 ```
 
 Templates are opt-in. Add HTML rendering only where you need it; your REST API continues working unchanged.
@@ -74,14 +74,19 @@ Here's the actual product list template from the example (simplified):
 
 ### Convention-Based Routing
 
-Templates automatically resolve based on request path:
+Templates automatically resolve based on request path with explicit action templates:
 
 ```http
-GET /shop/products  →  templates/shop/products/index.html
-GET /shop/products/123  →  templates/shop/products/view.html
+GET /shop/products      →  templates/shop/products/list.html (collection view)
+GET /shop/products/123  →  templates/shop/products/view.html (document view)
 ```
 
-Hierarchical fallback: if `shop/products/index.html` doesn't exist, tries `shop/index.html`, then `index.html`.
+**Naming convention:**
+- **`list.html`** - Collection views (recommended - no conditional logic needed)
+- **`view.html`** - Document views (recommended - no conditional logic needed)
+- **`index.html`** - Optional fallback (when list/view can share template logic)
+
+Hierarchical fallback: if `shop/products/list.html` doesn't exist, tries `shop/products/index.html`, then `shop/list.html`, then `shop/index.html`, finally `list.html` and `index.html`.
 
 ### HTMX Support Built In
 

core/src/main/java/org/facet/templates/PathBasedTemplateResolver.java

@@ -12,22 +12,46 @@
  *
  * <p>
  * This resolver maps request paths to template files using a convention-over-configuration
- * approach. Templates are organized in a directory structure that mirrors the URL structure,
- * with each resource having an optional {@code index.html} template.
+ * approach. Templates are organized in a directory structure that mirrors the URL structure.
  *
  * <p>
- * <strong>Full Page Resolution Algorithm:</strong>
+ * <strong>Recommended Template Naming Convention:</strong>
+ * </p>
+ * <ul>
+ * <li><strong>list.html</strong> - For collection views (recommended for clarity, no conditional logic needed)</li>
+ * <li><strong>view.html</strong> - For document views (recommended for clarity, no conditional logic needed)</li>
+ * <li><strong>index.html</strong> - Optional unified fallback (use when list/view can share template logic)</li>
+ * </ul>
+ *
+ * <p>
+ * <strong>Collection Request Resolution Example:</strong>
+ * </p>
+ *
+ * <pre>
+ * Request: GET /products (COLLECTION)
+ *
+ * Search order:
+ * 1. templates/products/list.html      (recommended - explicit collection view)
+ * 2. templates/products/index.html     (optional fallback)
+ * 3. templates/list.html               (global collection template)
+ * 4. templates/index.html              (global fallback)
+ * 5. return empty Optional             (no template found)
+ * </pre>
+ *
+ * <p>
+ * <strong>Document Request Resolution Example:</strong>
  * </p>
  *
  * <pre>
- * Request: GET /a/b/c
+ * Request: GET /products/123 (DOCUMENT)
  *
  * Search order:
- * 1. templates/a/b/c/index.html    (most specific - exact match)
- * 2. templates/a/b/index.html      (parent level)
- * 3. templates/a/index.html        (top level)
- * 4. templates/index.html          (root fallback - catch-all)
- * 5. return empty Optional         (no template found)
+ * 1. templates/products/123/view.html  (document-specific override)
+ * 2. templates/products/view.html      (recommended - explicit document view)
+ * 3. templates/products/index.html     (optional fallback)
+ * 4. templates/view.html               (global document template)
+ * 5. templates/index.html              (global fallback)
+ * 6. return empty Optional             (no template found)
  * </pre>
  *
  * <p>
@@ -86,8 +110,8 @@ public PathBasedTemplateResolver() {
     /**
      * Resolves a template name for the given request path using hierarchical fallback.
      *
-     * <p>This method uses the legacy resolution strategy (index.html only).
-     * For action-aware resolution, use {@link #resolve(TemplateProcessor, String, TYPE)}.
+     * <p>This method only checks for index.html templates.
+     * For explicit action-aware resolution (list.html, view.html), use {@link #resolve(TemplateProcessor, String, TYPE)}.
      *
      * @param templateProcessor the template processor to check for template existence
      * @param requestPath the request path (e.g., "/restheart/users")
@@ -99,23 +123,30 @@ public Optional<String> resolve(final TemplateProcessor templateProcessor, final
     }
 
     /**
-     * Resolves a template name with action-aware resolution (list.html, view.html, index.html).
+     * Resolves a template name with explicit action-aware resolution (list.html, view.html, index.html).
+     *
+     * <p><strong>Recommended Pattern:</strong> Use explicit templates for clean separation:
+     * <ul>
+     * <li><strong>list.html</strong> - Collection views (recommended - no conditional logic needed)</li>
+     * <li><strong>view.html</strong> - Document views (recommended - no conditional logic needed)</li>
+     * <li><strong>index.html</strong> - Optional fallback (for simple cases where list/view share logic)</li>
+     * </ul>
      *
      * <p><strong>Resolution Strategy:</strong></p>
      * <ul>
      * <li><strong>COLLECTION requests:</strong>
      *   <ol>
-     *     <li>products/list.html (explicit - recommended)</li>
-     *     <li>products/index.html (unified fallback)</li>
+     *     <li>products/list.html (recommended - explicit collection view)</li>
+     *     <li>products/index.html (optional fallback)</li>
      *     <li>Hierarchical parent fallback</li>
      *   </ol>
      * </li>
      * <li><strong>DOCUMENT requests:</strong>
      *   <ol>
-     *     <li>products/:id/view.html (specific override)</li>
-     *     <li>products/:id/index.html (specific unified)</li>
-     *     <li>products/view.html (explicit generic)</li>
-     *     <li>products/index.html (unified fallback)</li>
+     *     <li>products/:id/view.html (document-specific override)</li>
+     *     <li>products/:id/index.html (document-specific fallback)</li>
+     *     <li>products/view.html (recommended - explicit document view)</li>
+     *     <li>products/index.html (optional fallback)</li>
      *     <li>Hierarchical parent fallback</li>
      *   </ol>
      * </li>

core/src/main/java/org/facet/templates/TemplateResolver.java

@@ -11,20 +11,27 @@
  * in the Facet SSR framework. Implementations determine which template
  * file should be used to render a given resource path.
  *
+ * <p><strong>Recommended Convention:</strong> Use explicit action templates for clean separation:
+ * <ul>
+ * <li><strong>list.html</strong> - For collection views (multiple items)</li>
+ * <li><strong>view.html</strong> - For document views (single item)</li>
+ * <li><strong>index.html</strong> - Optional unified fallback (when list/view can share logic)</li>
+ * </ul>
+ *
  * <p>Example resolution for path "/products" (collection):
  * <pre>
- * 1. templates/products/list.html      (explicit - recommended)
- * 2. templates/products/index.html     (unified fallback)
- * 3. templates/list.html               (global explicit)
+ * 1. templates/products/list.html      (recommended - explicit collection view)
+ * 2. templates/products/index.html     (optional unified fallback)
+ * 3. templates/list.html               (global collection template)
  * 4. templates/index.html              (global fallback)
  * </pre>
  *
  * <p>Example resolution for path "/products/:id" (document):
  * <pre>
- * 1. templates/products/:id/view.html  (specific override)
- * 2. templates/products/view.html      (explicit - recommended)
- * 3. templates/products/index.html     (unified fallback)
- * 4. templates/view.html               (global explicit)
+ * 1. templates/products/:id/view.html  (document-specific override)
+ * 2. templates/products/view.html      (recommended - explicit document view)
+ * 3. templates/products/index.html     (optional unified fallback)
+ * 4. templates/view.html               (global document template)
  * 5. templates/index.html              (global fallback)
  * </pre>
  *
@@ -35,10 +42,10 @@ public interface TemplateResolver {
     /**
      * Resolves a template name for the given request path.
      *
-     * <p>This method uses the legacy resolution strategy that only checks for index.html.
-     * For action-aware resolution (list.html, view.html), use {@link #resolve(TemplateProcessor, String, TYPE)}.
+     * <p>This method only checks for index.html templates.
+     * For explicit action-aware resolution (list.html, view.html), use {@link #resolve(TemplateProcessor, String, TYPE)}.
      *
-     * <p>The resolver should search for templates in a hierarchical manner,
+     * <p>The resolver searches for templates in a hierarchical manner,
      * starting with the most specific path and falling back to parent paths
      * until a template is found.
      *
@@ -50,10 +57,14 @@ public interface TemplateResolver {
     Optional<String> resolve(TemplateProcessor templateProcessor, String requestPath);
 
     /**
-     * Resolves a template name for the given request path with action-aware resolution.
+     * Resolves a template name for the given request path with explicit action-aware resolution.
      *
-     * <p>This method supports both explicit action-based templates (list.html, view.html)
-     * and unified templates (index.html) as fallback.
+     * <p><strong>Recommended Pattern:</strong> Use explicit templates for clarity:
+     * <ul>
+     * <li><strong>list.html</strong> - Collection views (no conditional logic needed)</li>
+     * <li><strong>view.html</strong> - Document views (no conditional logic needed)</li>
+     * <li><strong>index.html</strong> - Optional fallback (for simple cases)</li>
+     * </ul>
      *
      * <p><strong>Resolution Strategy:</strong></p>
      * <ul>

docs/DEVELOPERS_GUIDE.md

@@ -9,7 +9,7 @@ This guide provides a complete reference for Facet's features and capabilities.
 
 Facet is a data-driven web framework that transforms JSON documents into server-rendered HTML through path-based templates. It's a RESTHeart plugin that provides **hybrid API/UI from the same endpoint**—JSON for API clients, HTML for browsers.
 
-**Core principle**: Convention over Configuration. Your template structure mirrors your API paths. A request to `/mydb/products` automatically uses `templates/mydb/products/index.html` when the browser requests HTML.
+**Core principle**: Convention over Configuration. Your template structure mirrors your API paths. A request to `/mydb/products` (collection) automatically uses `templates/mydb/products/list.html` or falls back to `index.html` when the browser requests HTML.
 
 **Technology stack**:
 - **[RESTHeart](https://restheart.org/)** - MongoDB REST API server (provides the plugin architecture, HTTP layer, auth, and more)
@@ -58,18 +58,46 @@ Accept: text/html
 5. Browser receives HTML page
 ```
 
+### Template Naming Convention
+
+**Recommended Pattern (Explicit):**
+- **`list.html`** - For collection views (recommended - clean, no conditional logic)
+- **`view.html`** - For document views (recommended - clean, no conditional logic)
+- **`index.html`** - Optional fallback (use when list/view can share template logic)
+
+**Why explicit templates?** Templates are cleaner without conditional logic checking request type. File names clearly indicate purpose.
+
 ### Template Resolution Algorithm
 
-**Full Page Requests** (no HTMX headers):
+**Collection Requests** (e.g., `/mydb/products`):
 ```
 GET /mydb/products?page=1
 Accept: text/html
 
 Search order:
-1. templates/mydb/products/index.html    ✓ (if exists)
-2. templates/mydb/index.html              (parent fallback)
-3. templates/index.html                    (global fallback)
-4. No template → return JSON (the API remains unchanged)
+1. templates/mydb/products/list.html      (recommended - explicit collection view)
+2. templates/mydb/products/index.html     (optional fallback)
+3. templates/mydb/list.html               (parent fallback)
+4. templates/mydb/index.html              (parent fallback)
+5. templates/list.html                    (global collection template)
+6. templates/index.html                   (global fallback)
+7. No template → return JSON (the API remains unchanged)
+```
+
+**Document Requests** (e.g., `/mydb/products/123`):
+```
+GET /mydb/products/123
+Accept: text/html
+
+Search order:
+1. templates/mydb/products/123/view.html  (document-specific override)
+2. templates/mydb/products/view.html      (recommended - explicit document view)
+3. templates/mydb/products/index.html     (optional fallback)
+4. templates/mydb/view.html               (parent fallback)
+5. templates/mydb/index.html              (parent fallback)
+6. templates/view.html                    (global document template)
+7. templates/index.html                   (global fallback)
+8. No template → return JSON (the API remains unchanged)
 ```
 
 **HTMX Fragment Requests** (with HX-Target header):
@@ -102,22 +130,28 @@ Organize templates by resource path to match your API structure:
 ```
 templates/
 ├── layout.html              # Your main layout
-├── index.html               # Root resource template (e.g., databases list)
+├── list.html                # Root resource template (e.g., databases list)
 ├── error.html               # Global error page
 ├── _fragments/              # HTMX-routable fragments (optional)
 │   └── my-fragment.html
 └── mydb/                    # Database-specific templates
-    ├── index.html           # Collections list for 'mydb'
+    ├── list.html            # Collections list for 'mydb' (recommended)
+    ├── view.html            # Database detail view (if needed)
+    ├── index.html           # Optional fallback for both
     └── products/
-        └── index.html       # Documents list for 'products' collection
+        ├── list.html        # Product collection view (recommended)
+        ├── view.html        # Single product detail view (recommended)
+        └── index.html       # Optional fallback for both
 ```
 
 **You can organize templates however you prefer** - this is just a recommended pattern that mirrors your API paths.
 
 ### Naming Conventions
 
+- **`list.html`**: Collection view template (recommended - explicit, no conditional logic)
+- **`view.html`**: Document view template (recommended - explicit, no conditional logic)
+- **`index.html`**: Optional unified fallback (when list/view share logic, or for simple cases)
 - **`_fragments/`**: HTMX-routable fragments (underscore prefix indicates not directly accessible via URL)
-- **`index.html`**: Default template for a resource path
 - **`layout.html`**: Base layout template using Pebble inheritance
 - **Path-based**: Directory structure mirrors your API URLs
 

docs/TUTORIAL_PRODUCT_CATALOG.md

@@ -131,12 +131,12 @@ The `documents` variable contains all products from MongoDB.
 
 ### Template Naming Convention
 
-Facet uses action-aware resolution:
+Facet uses explicit action-aware resolution:
 
-- **Collection requests** → looks for `list.html` first, then `index.html`
-- **Document requests** → looks for `view.html` first, then `index.html`
+- **Collection requests** → looks for `list.html` first, then `index.html` (optional fallback)
+- **Document requests** → looks for `view.html` first, then `index.html` (optional fallback)
 
-This is why our file is named `list.html` not `index.html`.
+**Recommended:** Use explicit templates (`list.html` and `view.html`) for cleaner code without conditional logic. This example uses `list.html` for the collection view and `view.html` for the document view, keeping each template focused and simple.
 
 ---
 
@@ -253,10 +253,12 @@ When requesting `/shop/products/65abc123...`:
 
 1. `templates/shop/products/65abc123.../view.html` ❌ (document-specific, doesn't exist)
 2. `templates/shop/products/view.html` ✅ **FOUND!**
-3. `templates/shop/products/index.html` (fallback if view.html missing)
-4. `templates/shop/index.html` (parent directory fallback)
-5. `templates/index.html` (root fallback)
-6. **No template found** → return JSON (API unchanged)
+3. `templates/shop/products/index.html` (optional fallback if view.html missing)
+4. `templates/shop/view.html` (parent-level document template)
+5. `templates/shop/index.html` (parent directory fallback)
+6. `templates/view.html` (global document template)
+7. `templates/index.html` (root fallback)
+8. **No template found** → return JSON (API unchanged)
 
 This is **hierarchical resolution** - walks up the tree until it finds a template.
 
@@ -701,7 +703,7 @@ document.getElementById('productEditForm').addEventListener('submit', async func
 
 #### Create Product Fragment
 
-The create flow works similarly. Open [templates/shop/products/index.html](../examples/product-catalog/templates/shop/products/index.html) (lines 18-26):
+The create flow works similarly. Open [templates/shop/products/list.html](../examples/product-catalog/templates/shop/products/list.html) (lines 18-26):
 
 ```html
 <button hx-get="{{ path }}"
@@ -787,7 +789,7 @@ async function deleteProduct() {
 ### Key Files
 
 - [templates/shop/products/view.html](../examples/product-catalog/templates/shop/products/view.html) - Product detail page with HTMX buttons
-- [templates/shop/products/index.html](../examples/product-catalog/templates/shop/products/index.html) - Product list with "Add Product" button
+- [templates/shop/products/list.html](../examples/product-catalog/templates/shop/products/list.html) - Product list with "Add Product" button
 - [templates/_fragments/product-form.html](../examples/product-catalog/templates/_fragments/product-form.html) - Edit form (HTMX fragment)
 - [templates/_fragments/product-new.html](../examples/product-catalog/templates/_fragments/product-new.html) - Create form (HTMX fragment)
 

examples/product-catalog/README.md

@@ -109,8 +109,8 @@ templates/
 ├── layout.html                      # Base layout with navigation
 ├── shop/
 │   └── products/
-│       ├── index.html              # Product list page
-│       └── view.html               # Product detail page
+│       ├── list.html               # Product list page (collection view)
+│       └── view.html               # Product detail page (document view)
 └── _fragments/
     └── product-list.html           # Reusable product list (for HTMX)
 ```
@@ -130,8 +130,8 @@ When you request different URLs, Facet resolves templates hierarchically:
 
 | Request URL | Template Resolved | Fallback Order |
 |-------------|-------------------|----------------|
-| `GET /shop/products` | `shop/products/index.html` | → `shop/index.html` → `index.html` |
-| `GET /shop/products/65abc...` | `shop/products/view.html` | → `shop/products/index.html` → ... |
+| `GET /shop/products` | `shop/products/list.html` | → `shop/products/index.html` → `shop/list.html` → `shop/index.html` → `list.html` → `index.html` |
+| `GET /shop/products/65abc...` | `shop/products/view.html` | → `shop/products/index.html` → `shop/view.html` → ... |
 | `GET /shop/products` (HTMX, target: `#product-list`) | `_fragments/product-list.html` | No fallback (strict mode) |
 
 ## Key Features Explained