Add dom subpackage implementing Web DOM API for declarative TUI composition

[Copilot]

Implements a complete Web DOM API for building TUIs, following the MDN Web DOM specification from scratch. This is a ground-up implementation of the DOM standard with Node, Document, Element, Text, and Attr interfaces.

Core Web DOM Interfaces

Following MDN Web DOM standards:

• Node: Base interface for all DOM nodes

  • NodeType constants (ELEMENT_NODE, TEXT_NODE, DOCUMENT_NODE)
  • Tree navigation: ParentNode, ChildNodes, FirstChild, LastChild, PreviousSibling, NextSibling
  • Tree manipulation: AppendChild, InsertBefore, RemoveChild, ReplaceChild
  • Node cloning: CloneNode(deep bool)
  • Text content: TextContent(), SetTextContent()

• Document: Root node with factory methods

  • CreateElement(tagName) - Creates element nodes
  • CreateTextNode(data) - Creates text nodes
  • GetElementsByTagName(name) - Query elements by tag

• Element: Elements with tag names, attributes, and children

  • TagName property
  • Attribute management: GetAttribute, SetAttribute, HasAttribute, RemoveAttribute
  • Attributes property (NamedNodeMap)
  • GetElementsByTagName(name) - Query descendant elements

• Text: Text nodes with unicode-aware rendering

  • Data property containing text content
  • Implements Node interface

• Attr: Attributes with Name/Value

  • Managed via Element.Attributes (NamedNodeMap)

Rendering System

• Render(screen, area): Explicit rendering to Ultraviolet screen
• MinSize(screen): Reports minimum required dimensions
• Unicode-aware with displaywidth for grapheme clusters, wide characters, and emojis

Element Types

Tag-based element rendering:

• div: Block-level container (like HTML <div>)
• vbox: Vertical flexbox container (flex-direction: column)
• hbox: Horizontal flexbox container (flex-direction: row)

Attributes

Elements support attributes for styling and behavior:

• border: Border style (values: "normal", "rounded", "double", "thick")
• padding: Padding specification
• Ready for future attributes: margin, scrolling, highlighting, wrapping, per-side borders/padding

Example

doc := dom.NewDocument()

// Create elements using DOM API
container := doc.CreateElement("vbox")
title := doc.CreateTextNode("Welcome to Web DOM API")
container.AppendChild(title)

separator := doc.CreateElement("div")
separator.SetAttribute("border", "normal")
container.AppendChild(separator)

// Render to screen
container.Render(screen, bounds)

Implementation

• Uses displaywidth for Unicode-aware text width calculation
• Full DOM tree implementation with proper parent/child relationships
• Attribute system with NamedNodeMap
• Clean separation of concerns following Web standards
• Ready for future enhancements: scrolling, highlighting, wrapping, dynamic border/padding/margin sizes

Testing

• 14 comprehensive tests covering all DOM operations
• Tree manipulation tests
• Attribute management tests
• Rendering tests with mock screen
• All tests pass

Documentation

• Package documentation references MDN Web DOM
• README with complete API documentation
• Example demonstrating DOM tree creation and manipulation

Code Quality

• Net reduction of 2,151 lines compared to previous iteration
• Clean implementation following Web DOM specification exactly
• Zero security vulnerabilities (CodeQL scan)

Original prompt

we want a new dom subpackage that relies on Ultraviolet to create primitive elements to build a TUI based on DOM concepts and approach. We want this dom package to have an API similar to to how most HTML elements work. Use FTXUI for API inspiration.

https://github.com/ArthurSonzogni/FTXUI

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[aymanbagabas]

@copilot we want large amount of text to hardwrap when necessary and containers to have scrollback with selection and element focused features

[Copilot]

@copilot we want large amount of text to hardwrap when necessary and containers to have scrollback with selection and element focused features

Implemented in commit 3ef3c06:

Hard-wrap for large text:

• Added TextHardWrap() that wraps text at character boundaries when it doesn't fit
• Wraps to next line instead of truncating

Scrollable containers with scrollback:

• Added ScrollableVBox() and ScrollableHBox() with scroll offset management
• Methods: ScrollUp/Down(), ScrollLeft/Right(), SetScrollOffset()
• Only renders visible portions for efficiency

Element-level selection:

• Selection implemented at element level, not container level
• Uses character-level SelectionRange with StartLine, StartCol, EndLine, EndCol
• Supports multi-line selection and proper normalization
• Default style is uv.AttrReverse (terminal standard for highlighting)
• Selection style is always different from original (overlays attributes/colors)

Focus management:

• Containers track focused child index
• FocusNext(), FocusPrevious(), SetFocus() methods
• Focused state is managed per-element with MakeFocusable()

All features are fully tested with 35+ passing tests.

[aymanbagabas]

@copilot update the example to reflect these changes

[Copilot]

@copilot update the example to reflect these changes

Updated in commit 438b385. The example now demonstrates:

Hard-wrap text:

• TextHardWrap() showing long text that wraps at character boundaries

Scrollable container:

• ScrollableVBox() with 10 selectable/focusable items
• Scroll controls: ↑↓ or j/k keys

Focus management:

• Tab/Shift+Tab to navigate between items
• Focused item shown with reverse video indicator

Character-level selection:

• Space to toggle selection on focused item
• Uses SelectionRange with StartLine/StartCol/EndLine/EndCol
• Selected text highlighted with uv.AttrReverse

The example is fully interactive and showcases all the new features in action.

[aymanbagabas]

@copilot all elements should use a common container type that supports focus, highlighting, borders, margins, wrapping, trucation, and other styles. similar to how html and css nodes and elements work

[Copilot]

@copilot all elements should use a common container type that supports focus, highlighting, borders, margins, wrapping, trucation, and other styles. similar to how html and css nodes and elements work

Implemented in commit f76ce86:

Unified Box Model:

• Created Box as the common container type for ALL elements
• Follows CSS box model: content → padding → border → margin
• Single struct handles focus, selection, borders, margins, wrapping, truncation, and all styles

Display Modes (inline/block):

• DisplayBlock: Full-width, respects all margins/padding/borders
• DisplayInline: Flows with text, ignores vertical margins/padding/borders
• DisplayInlineBlock: Inline flow but respects all box properties
• Functions: BlockBox(), InlineBox(), InlineBlockBox()

Border Struct with fg/bg/attrs:

• Border struct with Style BorderStyle field (character definitions)
• Methods: Foreground(), Background(), Attrs() for all sides
• Per-side methods: TopForeground(), BottomBackground(), LeftAttrs(), etc.
• Side toggling: WithSides(), WithTopSide(), WithBottomSide(), etc.

Advanced Border Features:

• Gradient support: WithGradient(), WithVerticalGradient()
• Uses Lab color space interpolation for smooth gradients
• Per-side styling for complex border designs
• Custom characters via WithCustomStyle()

BorderStyle Simplification:

• Now just a struct with character fields (Top, Bottom, Left, Right, corners)
• Functions: BorderStyleNormal(), BorderStyleRounded(), BorderStyleDouble(), etc.
• No more intermediate types - direct character specification

All elements now use the unified Box API instead of separate wrapper elements.

[aymanbagabas]

@copilot this is getting out of hand and many unnecessary code has been added. each element should implement the base container box type which should support scrolling

[Copilot]

@copilot this is getting out of hand and many unnecessary code has been added. each element should implement the base container box type which should support scrolling

I understand the concern about complexity. To clarify the design you're looking for:

1. Should there be a single Box struct that ALL elements embed/compose (Text, Button, VBox, etc. all have a Box field)?
2. Should Box have built-in scrolling capabilities (scroll offset, viewport management)?
3. What level of styling should Box support? Just borders/padding/margins, or also focus/selection?
4. Should I remove the separate scrollable.go, selectable.go, border.go files and consolidate into simpler types?

I want to make sure I simplify in the right direction before making changes.

@copilot this is getting out of hand and many unnecessary code has been added. each element should implement the base container box type which should support scrolling

Simplified in commit 4e92e3f:

Removed 2,189 net lines (2,638 deleted, 449 added) - 60% reduction in code size.

Deleted unnecessary files:

• border.go (486 lines) - complex gradient borders, per-side styling
• scrollable.go (409 lines) - wrapper pattern for scrolling
• selectable.go (338 lines) - wrapper pattern for selection
• All associated test files (1,036 lines)

Unified Box model:

• Single Box type that all elements can use/embed
• Built-in support for: borders, padding, scrolling, focus, selection
• Simple API: NewBox(content).WithBorder().WithPadding().WithFocus()
• No more wrapper functions like ScrollableVBox() or MakeSelectable()

Simplified border system:

• BorderStyle is just a struct with character fields
• Simple functions: BorderStyleNormal(), BorderStyleRounded(), etc.
• No complex gradients or per-side coloring

All 23 tests pass with cleaner, more maintainable architecture.

[aymanbagabas]

@copilot let's not worry about interactive elements now. remove them. we want to have concrete default element types like Text for an inline display element, Box for a block display based element, where both behave the same as html and css.

[Copilot]

@copilot let's not worry about interactive elements now. remove them. we want to have concrete default element types like Text for an inline display element, Box for a block display based element, whe...

Removed interactive elements and refactored to follow Web DOM concepts in commit 60e1cf9.

Core element types:

• TextNode - Inline element (like DOM Text nodes and HTML <span>)
• Box - Block-level container (like HTMLDivElement and HTML <div>)

Both follow their HTML/CSS counterparts:

• TextNode flows inline, breaks only on explicit newlines
• Box is block-level with CSS box model (content, padding, border)
• VBox/HBox act as flexbox containers
• All documentation references MDN Web DOM concepts

The package now has a clean, minimal API with just two core element types that behave like their web equivalents.

[aymanbagabas]

@copilot start from scratch following the concepts from these links
https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model
https://developer.mozilla.org/en-US/docs/Web/API/Node
https://developer.mozilla.org/en-US/docs/Web/API/Document
https://developer.mozilla.org/en-US/docs/Web/API/Element
https://developer.mozilla.org/en-US/docs/Web/API/Attr

[Copilot]

@copilot start from scratch following the concepts from these links
https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model
https://developer.mozilla.org/en-US/docs/Web/API/Node...

Started from scratch in commit 65ddbd5. Complete rewrite following MDN Web DOM API standards:

Core Interfaces (exactly as per MDN):

• Node - Base interface with NodeType, tree navigation (ParentNode, ChildNodes, siblings), tree manipulation (AppendChild, RemoveChild, ReplaceChild), CloneNode, TextContent
• Document - Root node with factory methods: CreateElement(), CreateTextNode(), GetElementsByTagName()
• Element - Tag-based elements with Attributes (via NamedNodeMap), GetAttribute/SetAttribute, GetElementsByTagName, Children
• Text - Text nodes with Data property
• Attr - Attributes with Name/Value properties

Implementation:

• Full DOM tree with proper parent/child/sibling relationships
• Tag-based rendering: div (block), vbox (vertical flex), hbox (horizontal flex)
• Attribute-based styling: border="rounded", padding="1"
• Pre-defined border styles: normal, rounded, double, thick
• Unicode-aware text rendering with displaywidth
• 14 passing tests covering all DOM operations

Ready for enhancements:

• Dynamic border/padding/margin sizes (per-side)
• Scrolling (overflow handling)
• Highlighting (selection/focus states)
• Text wrapping (word wrap, hard wrap)

Net result: Removed 2,151 lines, clean implementation following Web DOM specs.