LearnNewsExamplesServices
Frontmatter
id8601
title[Epic] Implement Neo.container.Fragment
stateClosed
labels
epicaicorefeature
assigneestobiu
createdAtJan 13, 2026, 3:34 PM
updatedAtJan 14, 2026, 2:49 AM
githubUrlhttps://github.com/neomjs/neo/issues/8601
authortobiu
commentsCount1
parentIssuenull
subIssues
8602 Implement Neo.container.Fragment Class & VNode Support
8603 VDOM Helper Support for Fragment Indexing & Deltas
8604 Fragment Rendering Support (DomApi & StringBased)
8605 Fragment Range Operations in DeltaUpdates
8606 Comprehensive Testing for Fragments
8607 Advanced Fragment Lifecycle Testing (Moves & Nesting)
8609 Add Fragment Helper Methods to DeltaUpdates
8613 Update DeltaUpdates.insertNodeBatch to support Fragments
8611 Update DeltaUpdates.moveNode to support Fragments
8612 Update DeltaUpdates.insertNode to support Fragments
8614 Fix moveNode off-by-one error for forward moves in same parent
8615 Refactor Container to support atomic component moves
8616 Create Fragment Example App (Form Grouping)
8617 Refactor StringBasedRenderer for API Parity (Separate Creation from Insertion)
8618 Implement insertNodeBatch support for StringBasedRenderer
8619 Create Playwright Test Fixtures for Neo.mjs VDOM & State Inspection
8625 Fragment Move Operation Instability
8626 Container.insert() should be a no-op for same-index moves
8627 Fragment hidden config fails: removeNode delta missing parentId
8628 [Docs] Apply Knowledge Base Enhancement Strategy to Fragment Implementation
8629 [Docs] Create ''Fragments'' Guide in UI Building Blocks
subIssuesCompleted21
subIssuesTotal21
blockedBy[]
blocking[]
closedAtJan 14, 2026, 2:49 AM

[Epic] Implement Neo.container.Fragment

Closed v11.21.0 epicaicorefeature
tobiu
tobiu commented on Jan 13, 2026, 3:34 PM

Implement a Neo.container.Fragment that allows grouping items without rendering a wrapper DOM element.

Core Requirements:

  1. No Wrapper Node: Renders as a range of sibling nodes in the DOM (anchored by Comments), allowing children to sit directly in the parent's layout context (e.g., CSS Grid).
  2. Container Capability: Supports items config to manage child components.
  3. VDOM Structure: Uses tag: 'fragment' in the VNode tree to maintain Component-to-VNode symmetry.
  4. Smart Runtime Architecture: The VDOM Helper generates high-level Fragment Deltas, and the Main Thread (DeltaUpdates) handles the complex DOM range manipulation locally to minimize IPC.
  5. Multi-Window Support: Seamlessly moving a Fragment container (and its children) to a different browser window must work out-of-the-box.
  6. Non-Destructive Moves: Moving items into, out of, or within Fragments in the same window must NOT trigger re-rendering (no destroy/create). It must use physical DOM moves.

Acceptance Criteria:

  • Fragment renders with Comment Anchors (<!-- fragment-id-start -->) and no wrapper element.
  • Fragment children participate correctly in parent CSS Grid/Flex layouts.
  • Moving a Fragment to a new window works correctly.
  • Moving items in/out of Fragments preserves their DOM state (focus, input values).
tobiu added the epic label on Jan 13, 2026, 3:34 PM
tobiu added the ai label on Jan 13, 2026, 3:34 PM
tobiu added the core label on Jan 13, 2026, 3:34 PM
tobiu added the feature label on Jan 13, 2026, 3:34 PM
tobiu cross-referenced by #8602 on Jan 13, 2026, 3:38 PM
tobiu added sub-issue #8602 on Jan 13, 2026, 3:40 PM
tobiu cross-referenced by #8603 on Jan 13, 2026, 3:52 PM
tobiu added sub-issue #8603 on Jan 13, 2026, 3:53 PM
tobiu cross-referenced by #8604 on Jan 13, 2026, 3:57 PM
tobiu added sub-issue #8604 on Jan 13, 2026, 4:01 PM
tobiu cross-referenced by #8605 on Jan 13, 2026, 4:09 PM
tobiu added sub-issue #8605 on Jan 13, 2026, 4:10 PM
tobiu cross-referenced by #8606 on Jan 13, 2026, 4:11 PM
tobiu added sub-issue #8606 on Jan 13, 2026, 4:11 PM
tobiu assigned to @tobiu on Jan 13, 2026, 4:18 PM
tobiu
tobiu Jan 13, 2026, 5:28 PM

Input from Gemini 3 Pro:

✦ All sub-tasks for this Epic have been completed and verified.

Implementation Summary:

  1. Core Class: Neo.container.Fragment (tag: 'fragment', layout: null).
  2. VDOM Engine:
    • Helper: Updated getPhysicalIndex to recursively count fragment anchors and children.
    • Helper: Updated compareAttributes to treat fragments as transparent.
  3. Rendering Engines:
    • DomApiRenderer (Main): Renders DocumentFragment with <!-- id-start --> ... <!-- id-end --> anchors.
    • StringFromVnode (SSR): Generates corresponding HTML string.
  4. Delta Updates:
    • insertNode: Supports fragment insertion via renderers.
    • removeNode: Detects fragment anchors and removes the full range.
    • moveNode: Uses XPath to locate fragment anchors globally (robust against missing IDs), extracts the DOM range into a DocumentFragment, and moves it physically to the new location (preserving state).
  5. Testing:
    • Unit tests for VDOM indexing and deltas.
    • E2E tests verifying DOM structure (no wrappers, anchors present) and layout participation.

The feature is ready for use.

tobiu cross-referenced by #8607 on Jan 13, 2026, 5:37 PM
tobiu added sub-issue #8607 on Jan 13, 2026, 5:37 PM
tobiu added sub-issue #8609 on Jan 13, 2026, 7:49 PM
tobiu added sub-issue #8613 on Jan 13, 2026, 8:03 PM
tobiu added sub-issue #8611 on Jan 13, 2026, 8:04 PM
tobiu added sub-issue #8612 on Jan 13, 2026, 8:05 PM
tobiu added sub-issue #8614 on Jan 13, 2026, 8:26 PM
tobiu added sub-issue #8615 on Jan 13, 2026, 8:49 PM
tobiu added sub-issue #8616 on Jan 13, 2026, 8:50 PM
tobiu added sub-issue #8617 on Jan 13, 2026, 8:54 PM
tobiu added sub-issue #8618 on Jan 13, 2026, 8:54 PM
tobiu added sub-issue #8619 on Jan 13, 2026, 8:54 PM
tobiu added sub-issue #8625 on Jan 14, 2026, 1:15 AM
tobiu added sub-issue #8626 on Jan 14, 2026, 1:16 AM
tobiu added sub-issue #8627 on Jan 14, 2026, 1:49 AM
tobiu cross-referenced by #8628 on Jan 14, 2026, 2:14 AM
tobiu added sub-issue #8628 on Jan 14, 2026, 2:14 AM
tobiu added sub-issue #8629 on Jan 14, 2026, 2:24 AM
tobiu closed this issue on Jan 14, 2026, 2:49 AM