Vectored.Elements.Element (Vectored v0.4.0)

Core macros and helpers for defining SVG elements.

This module provides the foundation for all SVG elements in the library. It defines common attributes shared by almost all SVG elements and provides a macro system to easily create new element types with consistent setter functions.

Common Presentation Attributes: How shapes are styled

In SVG, shapes are just geometries. To make them visible and styled, you use presentation attributes. Most elements in this library include these:

Fill (fill): The color of the inside of the shape. Defaults to black. Use "none" for transparent interiors.
Stroke (stroke): The color of the outline. Shapes have no outline by default.
Stroke Width (stroke_width): How thick the outline is.
Opacity (opacity): How transparent the whole element is (0.0 to 1.0).
Transform (transform): Used to move (translate), rotate, or scale the element relative to its original position.

Helper Functions

When a module uses Vectored.Elements.Element, it automatically gains several helper functions:

with_ATTR/2 - For every attribute defined, a setter function is created. For example, with_fill(element, "red").
with_style/2 - Accepts a keyword list of CSS styles. Use this if you prefer CSS-style strings over individual attributes.
put_dataset/3, delete_dataset/2, with_dataset/2 - For data-* attributes. Useful for passing metadata to JavaScript or CSS.
Security: dataset keys become atoms
Dataset keys are converted to atoms when rendered (the underlying :xmerl serializer requires atom attribute names). Atoms are never garbage-collected, so passing untrusted, user-derived strings as dataset keys can exhaust the atom table and crash the BEAM. Always use static, developer-controlled key names. Dataset values are unrestricted and safe.
with_description/2, with_title/2 - For metadata children that help with accessibility (ARIA).

Summary

Types

attributes()

Functions

__using__(opts)

Makes the calling module an SVG element.

attributes(element, attrs)

defelement(attributes)

Defines the struct for an SVG element, including common SVG attributes.

maybe_cast(v)

render_common_children(element)

Types

attributes()

@type attributes() :: %{
  optional(:attributes) => Keyword.t(),
  optional(:attribute_overrides) => Keyword.t()
}

Functions

using(opts)

(macro)

Makes the calling module an SVG element.

Options

:attributes - A keyword list of element-specific attributes and their defaults.
:attribute_overrides - A keyword list mapping internal field names to SVG attribute names (e.g., stroke_width: :"stroke-width").

When used, it defines a struct and a set of with_* setter functions.