Warn when x-for template has multiple root elements and document table workaround

x-for silently discards all but the first child element of a template.
This adds a console.warn so users know what's happening, and documents
the table-specific workaround (use <tr> as the root element).

Co-Authored-By: NFSL2001 <NightFurySL2001@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

packages/alpinejs/src/directives/x-for.js

@@ -111,6 +111,9 @@ function loop(templateEl, iteratorNames, evaluateItems, evaluateKey) {
                     return
                 }
 
+                if (templateEl.content.children.length > 1)
+                    warn('x-for templates require a single root element, additional elements will be ignored.', templateEl)
+
                 let clone = document.importNode(templateEl.content, true).firstElementChild
                 let reactiveScope = reactive(scope)
                 addScopeToNode(clone, reactiveScope, templateEl)

packages/docs/src/en/directives/for.md

@@ -133,3 +133,18 @@ but this code will work:
     </p>
 </template>
 ```
+
+### Limitations with `<table>` elements
+
+HTML tables have strict parsing rules — elements like `<td>` and `<th>` can only appear inside `<tr>`, and `<div>` is invalid inside table rows. If you wrap table cells in a `<div>` inside your `x-for` template, the browser's HTML parser will strip them before Alpine runs. The workaround is to make `<tr>` the root element of your template, iterating over rows instead of cells:
+
+```alpine
+<table x-data="{ colors: ['Red', 'Orange', 'Yellow'] }">
+    <template x-for="(color, index) in colors">
+        <tr>
+            <td x-text="index"></td>
+            <td x-text="color"></td>
+        </tr>
+    </template>
+</table>
+```

tests/cypress/integration/directives/x-for.spec.js

@@ -671,6 +671,27 @@ test('x-for eagerly cleans tree',
     }
 )
 
+test('x-for works with tr as root element inside table',
+    html`
+        <table x-data="{ colors: ['Red', 'Green', 'Blue'] }">
+            <template x-for="(color, index) in colors">
+                <tr>
+                    <td x-text="color"></td>
+                    <td x-text="index"></td>
+                </tr>
+            </template>
+        </table>
+    `,
+    ({ get }) => {
+        get('tr:nth-of-type(1) td:nth-of-type(1)').should(haveText('Red'))
+        get('tr:nth-of-type(1) td:nth-of-type(2)').should(haveText('0'))
+        get('tr:nth-of-type(2) td:nth-of-type(1)').should(haveText('Green'))
+        get('tr:nth-of-type(2) td:nth-of-type(2)').should(haveText('1'))
+        get('tr:nth-of-type(3) td:nth-of-type(1)').should(haveText('Blue'))
+        get('tr:nth-of-type(3) td:nth-of-type(2)').should(haveText('2'))
+    }
+)
+
 // To support rerendering alongside x-sort
 test('x-for handles moved elements correctly',
     html`