hast-util-dom-attributes

Attribute utilities for hast elements, consistent with the DOM.

In hast, the values of the properties record may be, in addition to the intuitively reasonable string, boolean, number, and (string | number)[], also null and undefined (v2/v3). This is convenient when constructing a tree, but things get a bit complicated when you want to check for presence or obtain a string in a type-safe way.

Below are the results observed from the input/output of hast-util-to-html. You can see that simply relying on truthy/falsy or using String does not yield correct results.

| properties: | toHtml(node) | | ---------------------- | -------------------------- | | undefined (v2) | <div></div> | | {} | <div></div> | | { foo: true } | <div foo></div> | | { foo: false } | <div></div> | | { foo: 42 } | <div foo="42"></div> | | { foo: 0 } | <div foo="0"></div> | | { foo: "bar" } | <div foo="bar"></div> | | { foo: "" } | <div foo=""></div> | | { foo: [42, "bar"] } | <div foo="42 bar"></div> | | { foo: [] } | <div foo=""></div> | | { foo: null } | <div></div> | | { foo: undefined } | <div></div> |

Writing attributes with both camel case and kebab case names can create collisions. For example, both dataFoo and data-foo serialize to data-foo. If both keys have values that are serialized, the resulting HTML contains duplicate attributes, and the value read by the DOM or getAttribute depends on their insertion order. Writing either name with setAttribute produces a single dataFoo property for that attribute in the returned properties.

In hast, both class and className correspond to the HTML class attribute, and their values can be strings or arrays. For example, { class: "foo bar" }, { class: ["foo", "bar"] }, { className: "foo bar" }, and { className: ["foo", "bar"] } all serialize to class="foo bar". Reading a property directly therefore requires handling both names and both value forms to determine which classes an element has. getClassList provides access to those classes without making callers account for these differences in representation.

Hast consumers such as hast-util-select expect className to be an array of individual class names. setAttribute and setClassList produce that representation so class selectors match complete tokens.

Removing an attribute also requires accounting for its aliases. Given { class: "foo", className: "bar" }, deleting either key leaves a class attribute in the serialized HTML; both keys must be removed. removeAttribute removes all properties that represent the requested attribute, so callers do not need to find and delete each alias themselves.

External hast trees may already contain attribute names such as class or data-foo, while writes through these utilities use className or dataFoo. Reads return the first value that would be serialized for the requested attribute. setAttribute and setClassList collapse aliases of the requested attribute into one property, preserving unrelated keys and values, including null and undefined. These values remain subject to the usual toHtml serialization rules shown above. Names that serialize to distinct attributes, such as data--foo and data-foo, remain distinct; property-name conversion is used only when it preserves the serialized attribute name. This lets callers use trees from other transforms without preparing their properties first.

Reading attributes should not modify a shared tree, and writing attributes should let the caller decide when to update it. All utilities accept read-only elements. setAttribute, removeAttribute, and setClassList return a new hast.Properties record, which can be assigned to the original element while preserving its identity in the tree:

target.properties = setAttribute(target, "data-foo", "bar");
target.properties = setClassList(target, ["foo", "bar"]);

For nested SVG elements, pass { root } to these attribute utilities so attribute names are resolved in the original element's namespace.