feat: implement attribute, class list, dataset, and style views for H… (#19)

* feat: implement attribute, class list, dataset, and style views for HTMLElement

* feat: reorder type definitions for clarity in elementMapView

* feat: refactor HTMLElement to use dedicated attribute, class, dataset, and style handlers

* feat: refactor HTMLElement to use provider methods for attributes, styles, and wait targets

* feat: enhance HTMLElement to support attributes, styles, classes, and dataset manipulation

* fix: normalize html view assignment keys

Author: ziflex

modules/web/article/lib/helpers.go

@@ -92,7 +92,12 @@ func sourceFromElement(ctx context.Context, el htmldrivers.HTMLElement) (core.So
 }
 
 func snapshotElementHTML(ctx context.Context, el htmldrivers.HTMLElement) (string, error) {
-	innerHTML, err := el.GetInnerHTML(ctx)
+	content, err := htmldrivers.ToContentTarget(el)
+	if err != nil {
+		return "", err
+	}
+
+	innerHTML, err := content.GetInnerHTML(ctx)
 	if err != nil {
 		return "", err
 	}
@@ -107,7 +112,12 @@ func snapshotElementHTML(ctx context.Context, el htmldrivers.HTMLElement) (strin
 		return innerHTML.String(), nil
 	}
 
-	attrs, err := el.GetAttributes(ctx)
+	attributes, err := htmldrivers.ToAttributeTarget(el)
+	if err != nil {
+		return "", err
+	}
+
+	attrs, err := attributes.GetAttributes(ctx)
 	if err != nil {
 		return "", err
 	}

modules/web/html/README.md

@@ -283,7 +283,7 @@ RETURN sections[* RETURN {
 
 ## Reading And Mutating DOM Content
 
-HTML page, document, and element values expose a read-only dot-access surface for convenient reads. Use explicit module functions for mutations.
+HTML page, document, and element values expose a dot-access surface for convenient reads. Static/memory-backed values are read-only through dot access. CDP-backed elements also support a small write-through assignment surface.
 
 ```fql
 LET page = DOCUMENT($url)
@@ -307,10 +307,10 @@ Common readable properties include:
 | --- | --- |
 | `HTMLPage` | `response`, `mainFrame`, `document`, `frames`, `url`, `URL`, `cookies`, `title`, `isClosed`, plus document properties through the main frame. |
 | `HTMLDocument` | `url`, `URL`, `name`, `title`, `parent`, `body`, `head`, `innerHTML`, `innerText`, plus node properties. |
-| `HTMLElement` | `innerText`, `innerHTML`, `value`, `attributes`, `style`, `previousElementSibling`, `nextElementSibling`, `parentElement`, plus node properties. |
+| `HTMLElement` | `innerText`, `innerHTML`, `textContent`, `value`, `checked` (CDP), `disabled` (CDP), `selected` (CDP), `attributes`, `style`, `classes` (CDP), `dataset` (CDP), `previousElementSibling`, `nextElementSibling`, `parentElement`, plus node properties. |
 | HTML node values | integer child indexes, `nodeType`, `nodeName`, `children`, `length`. |
 
-Dot access does not write back to HTML values. Use the mutation module functions instead:
+Use the mutation module functions for driver-portable writes:
 
 ```fql
 LET page = DOCUMENT($url, { driver: "cdp" })
@@ -324,6 +324,27 @@ STYLE_SET(preview, "display", "block")
 RETURN preview.innerHTML
 ```
 
+CDP-backed elements can also be mutated with normal assignment. Top-level assignment supports content/value properties plus `attributes`, `style`, `classes`, and `dataset`; nested assignment writes through snapshot views returned by those collection properties. A captured view keeps its read snapshot while writes through that view update the browser:
+
+```fql
+LET page = DOCUMENT($url, { driver: "cdp" })
+LET button = ELEMENT(page, "button[type=submit]")
+
+button.textContent = "Continue"
+button.innerHTML = "<strong>Continue</strong>"
+button.disabled = FALSE
+button.attributes = { "aria-label": "Continue" }
+button.attributes["data-state"] = "ready"
+button.style.display = "block"
+button.classes.active = TRUE
+button.dataset.productId = "123"
+
+button.attributes["data-state"] = NONE
+button.style.display = NONE
+button.classes.active = FALSE
+button.dataset.productId = NONE
+```
+
 Attribute and style module functions can work with individual names or maps depending on the function:
 
 ```fql

modules/web/html/drivers/capabilities_test.go

@@ -8,6 +8,8 @@ import (
 	"testing"
 
 	"github.com/PuerkitoBio/goquery"
+	cdpruntime "github.com/mafredri/cdp/protocol/runtime"
+	"github.com/rs/zerolog"
 
 	"github.com/MontFerret/contrib/modules/web/html/drivers"
 	"github.com/MontFerret/contrib/modules/web/html/drivers/cdp"
@@ -61,12 +63,9 @@ var (
 	_ drivers.NodeInspector     = (*cdpdom.HTMLElement)(nil)
 	_ drivers.QueryTarget       = (*cdpdom.HTMLElement)(nil)
 	_ drivers.ContentTarget     = (*cdpdom.HTMLElement)(nil)
-	_ drivers.AttributeTarget   = (*cdpdom.HTMLElement)(nil)
-	_ drivers.StyleTarget       = (*cdpdom.HTMLElement)(nil)
 	_ drivers.ValueTarget       = (*cdpdom.HTMLElement)(nil)
 	_ drivers.RelationTarget    = (*cdpdom.HTMLElement)(nil)
 	_ drivers.InteractionTarget = (*cdpdom.HTMLElement)(nil)
-	_ drivers.WaitTarget        = (*cdpdom.HTMLElement)(nil)
 	_ runtime.Dispatchable      = (*cdpdom.HTMLElement)(nil)
 )
 
@@ -168,12 +167,9 @@ func TestBackendCapabilityMatrix(t *testing.T) {
 				"NodeInspector":     true,
 				"QueryTarget":       true,
 				"ContentTarget":     true,
-				"AttributeTarget":   true,
-				"StyleTarget":       true,
 				"ValueTarget":       true,
 				"RelationTarget":    true,
 				"InteractionTarget": true,
-				"WaitTarget":        true,
 			},
 		},
 	}
@@ -200,6 +196,87 @@ func TestBackendCapabilityMatrix(t *testing.T) {
 	}
 }
 
+func TestCDPElementCapabilityResolversUseProviders(t *testing.T) {
+	t.Parallel()
+
+	element := cdpdom.NewHTMLElement(zerolog.Nop(), nil, nil, nil, nil, cdpruntime.RemoteObjectID("node"))
+
+	if reflect.TypeOf((*cdpdom.HTMLElement)(nil)).Implements(reflect.TypeOf((*drivers.AttributeTarget)(nil)).Elem()) {
+		t.Fatal("expected cdp element to stop directly implementing AttributeTarget")
+	}
+
+	if reflect.TypeOf((*cdpdom.HTMLElement)(nil)).Implements(reflect.TypeOf((*drivers.StyleTarget)(nil)).Elem()) {
+		t.Fatal("expected cdp element to stop directly implementing StyleTarget")
+	}
+
+	if reflect.TypeOf((*cdpdom.HTMLElement)(nil)).Implements(reflect.TypeOf((*drivers.WaitTarget)(nil)).Elem()) {
+		t.Fatal("expected cdp element to stop directly implementing WaitTarget")
+	}
+
+	if _, err := drivers.ToAttributeTarget(element); err != nil {
+		t.Fatalf("expected cdp element attribute provider: %v", err)
+	}
+
+	if _, err := drivers.ToStyleTarget(element); err != nil {
+		t.Fatalf("expected cdp element style provider: %v", err)
+	}
+
+	if _, err := drivers.ToWaitTarget(element); err != nil {
+		t.Fatalf("expected cdp element wait provider: %v", err)
+	}
+}
+
+func TestCapabilityResolversUseProviderMethods(t *testing.T) {
+	t.Parallel()
+
+	base := newMemoryDocument(t, `<html><body><button id="cta">go</button></body></html>`).GetElement()
+	attrs, err := drivers.ToAttributeTarget(base)
+	if err != nil {
+		t.Fatalf("base attribute target: %v", err)
+	}
+
+	styles, err := drivers.ToStyleTarget(base)
+	if err != nil {
+		t.Fatalf("base style target: %v", err)
+	}
+
+	wait := &providerWaitTarget{}
+	element := &providerElement{
+		HTMLNode: base,
+		attrs:    attrs,
+		styles:   styles,
+		wait:     wait,
+	}
+
+	if reflect.TypeOf(element).Implements(reflect.TypeOf((*drivers.AttributeTarget)(nil)).Elem()) {
+		t.Fatal("provider element should not directly implement AttributeTarget")
+	}
+
+	resolvedAttrs, err := drivers.ToAttributeTarget(element)
+	if err != nil {
+		t.Fatalf("resolve attribute provider: %v", err)
+	}
+	if resolvedAttrs != attrs {
+		t.Fatal("expected attribute resolver to return provider target")
+	}
+
+	resolvedStyles, err := drivers.ToStyleTarget(element)
+	if err != nil {
+		t.Fatalf("resolve style provider: %v", err)
+	}
+	if resolvedStyles != styles {
+		t.Fatal("expected style resolver to return provider target")
+	}
+
+	resolvedWait, err := drivers.ToWaitTarget(element)
+	if err != nil {
+		t.Fatalf("resolve wait provider: %v", err)
+	}
+	if resolvedWait != wait {
+		t.Fatal("expected wait resolver to return provider target")
+	}
+}
+
 func TestRoleResolversAreExact(t *testing.T) {
 	t.Parallel()
 

modules/web/html/drivers/capability_provider_element_test.go

@@ -0,0 +1,22 @@
+package drivers_test
+
+import "github.com/MontFerret/contrib/modules/web/html/drivers"
+
+type providerElement struct {
+	drivers.HTMLNode
+	attrs  drivers.AttributeTarget
+	styles drivers.StyleTarget
+	wait   drivers.WaitTarget
+}
+
+func (el *providerElement) AsAttributeTarget() drivers.AttributeTarget {
+	return el.attrs
+}
+
+func (el *providerElement) AsStyleTarget() drivers.StyleTarget {
+	return el.styles
+}
+
+func (el *providerElement) AsWaitTarget() drivers.WaitTarget {
+	return el.wait
+}

modules/web/html/drivers/capability_provider_wait_target_test.go

@@ -0,0 +1,54 @@
+package drivers_test
+
+import (
+	"context"
+
+	"github.com/MontFerret/contrib/modules/web/html/drivers"
+	"github.com/MontFerret/ferret/v2/pkg/runtime"
+)
+
+type providerWaitTarget struct{}
+
+func (target *providerWaitTarget) WaitForElement(context.Context, drivers.QuerySelector, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForElementAll(context.Context, drivers.QuerySelector, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForAttribute(context.Context, runtime.String, runtime.Value, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForAttributeBySelector(context.Context, drivers.QuerySelector, runtime.String, runtime.Value, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForAttributeBySelectorAll(context.Context, drivers.QuerySelector, runtime.String, runtime.Value, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForStyle(context.Context, runtime.String, runtime.Value, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForStyleBySelector(context.Context, drivers.QuerySelector, runtime.String, runtime.Value, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForStyleBySelectorAll(context.Context, drivers.QuerySelector, runtime.String, runtime.Value, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForClass(context.Context, runtime.String, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForClassBySelector(context.Context, drivers.QuerySelector, runtime.String, drivers.WaitEvent) error {
+	return nil
+}
+
+func (target *providerWaitTarget) WaitForClassBySelectorAll(context.Context, drivers.QuerySelector, runtime.String, drivers.WaitEvent) error {
+	return nil
+}

modules/web/html/drivers/cdp/dom/attribute_view.go

@@ -0,0 +1,37 @@
+package dom
+
+import (
+	"context"
+
+	"github.com/MontFerret/ferret/v2/pkg/runtime"
+)
+
+type attributeView struct {
+	*elementMapView
+}
+
+func newAttributeView(ctx context.Context, attrs *elementAttributes) (*attributeView, error) {
+	snapshot, err := attrs.GetAttributes(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	return &attributeView{
+		elementMapView: newElementMapView(
+			snapshot,
+			func(ctx context.Context, key, value runtime.Value) (runtime.Value, bool, error) {
+				name := runtime.ToString(key)
+				if value == runtime.None {
+					return runtime.None, true, attrs.RemoveAttribute(ctx, name)
+				}
+
+				next := runtime.ToString(value)
+
+				return next, false, attrs.SetAttribute(ctx, name, next)
+			},
+			func(ctx context.Context, key runtime.Value) error {
+				return attrs.RemoveAttribute(ctx, runtime.ToString(key))
+			},
+		),
+	}, nil
+}

modules/web/html/drivers/cdp/dom/class_list_view.go

@@ -0,0 +1,44 @@
+package dom
+
+import (
+	"context"
+
+	"github.com/MontFerret/ferret/v2/pkg/runtime"
+)
+
+type classListView struct {
+	*elementMapView
+}
+
+func newClassListView(ctx context.Context, classes *elementClasses) (*classListView, error) {
+	snapshot, err := classes.GetClassList(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	return &classListView{
+		elementMapView: newElementMapView(
+			snapshot,
+			func(ctx context.Context, key, value runtime.Value) (runtime.Value, bool, error) {
+				enabled, err := runtime.CastBoolean(value)
+				if err != nil {
+					return runtime.None, false, err
+				}
+
+				name := runtime.ToString(key)
+				if err := classes.SetClass(ctx, name, enabled); err != nil {
+					return runtime.None, false, err
+				}
+
+				if !enabled {
+					return runtime.None, true, nil
+				}
+
+				return runtime.True, false, nil
+			},
+			func(ctx context.Context, key runtime.Value) error {
+				return classes.SetClass(ctx, runtime.ToString(key), runtime.False)
+			},
+		),
+	}, nil
+}