NativeElixirPdfUtilities.HtmlToPdf.Style (native_elixir_pdf_utilities v1.1.0)

View Source

Style computation for the native HTML-to-PDF renderer.

This module applies defaults, inheritance, font resolution, and the CSS cascade for the supported text, generated-content, named-counter, selector, box, list, link, table, page-break, flexbox, grid, image, static form-control, and embedded-font styling subset. Unsupported properties or invalid values fail the render instead of being ignored.

Summary

Functions

Builds an anonymous formatting box with inherited text and initial box properties.

Computes styles for a parsed HTML document tree.

Styles a child using separate client layout and media viewport dimensions in points.

Computes styles and returns detailed CSS/document diagnostics when validation fails.

Returns the normal line height of an already validated embedded-font style in points.

Visits original HTML declaration contexts without reading fonts, files or assets.

Types

render_option()

styled_element()

@type styled_element() :: %{
  type: :element,
  tag: String.t(),
  style: map(),
  children: [text_node() | styled_element()]
}

styled_tree()

@type styled_tree() :: %{
  :type => :document,
  :children => [text_node() | styled_element()],
  optional(atom()) => term()
}

stylesheet_entry()

@type stylesheet_entry() :: %{
  css: String.t(),
  source_kind: :configured | :embedded,
  base_url: String.t() | nil,
  trusted_local_resources: boolean()
}

text_node()

@type text_node() :: %{type: :text, text: String.t(), style: map()}

Functions

anonymous_box_style(parent, display)

@spec anonymous_box_style(map(), atom()) :: map()

Builds an anonymous formatting box with inherited text and initial box properties.

compute(dom, opts \\ [])

@spec compute(term(), [render_option()]) ::
  {:ok, styled_tree()} | {:error, :invalid_document}

Computes styles for a parsed HTML document tree.

compute_child_detailed(dom, opts, image_budget, document_url, client, media, frame_margins \\ nil)

@spec compute_child_detailed(
  term(),
  [render_option()],
  NativeElixirPdfUtilities.Validators.HtmlValidator.image_budget(),
  String.t() | nil,
  term(),
  term(),
  term()
) :: {:ok, styled_tree()} | {:error, {atom(), map()}}

Styles a child using separate client layout and media viewport dimensions in points.

compute_detailed(dom, opts \\ [])

@spec compute_detailed(term(), [render_option()]) ::
  {:ok, styled_tree()}
  | {:error,
     {:invalid_css
      | :invalid_document
      | :invalid_options
      | :unsupported_html
      | :unsupported_glyph
      | :resource_limit_exceeded, map()}}

Computes styles and returns detailed CSS/document diagnostics when validation fails.

Table styles preserve :_table_model, and cell styles preserve :_table_cell. Recoverable HTML table model errors remain in :_table_model.errors; success means renderable input, not that the source table has no conformance errors. Logical spans and associations are independent of visible CSS grid geometry.

normal_line_height(style)

@spec normal_line_height(map()) :: number()

Returns the normal line height of an already validated embedded-font style in points.

with_source_style_contexts(dom, sources, budget, consumer, opts \\ [])

@spec with_source_style_contexts(term(), term(), term(), term(), keyword()) ::
  {:ok, map()}
  | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Visits original HTML declaration contexts without reading fonts, files or assets.

This internal execution path shares normal DOM validation, defaults, inheritance, selectors and cascade ordering. The three-argument consumer receives the original node with added render metadata, a pseudo-element or nil, and a limited context. :resolved means declaration/context policy only, never a render-ready style. Detached template contents retain their unresolved authored scope. MathML contexts need selected MATH metrics and remain unresolved without font reads.

source_obligations.declaration_contexts records each exact authored inline or rule declaration and the original node/pseudo contexts where its shared value validation completed. Declarations without such a context retain an explicit unresolved reason, including detached template and inactive stylesheet sources. Element-independent literal checks carry :checked_without_element_context with empty contexts and retain their authored source ownership. Unapplied stylesheet values carry :checked_symbolically with their exact source grammar and dependency types, empty element contexts and the actual original selection basis. They grant no measured geometry, selected font or resource permission. A matching rule awaiting real Math metrics stays pending. Checked contexts do not certify any future insertion.

The result preserves source obligations for unmatched rules, inactive media, references and detached insertion contexts. Font selection, metrics, decorations and resource authorization/contents remain unchecked runtime obligations. Canonical inline and embedded CSS records bind verified original HTML tokens, including newline preprocessing and attribute references. Metadata-free trees retain local records with provenance: :unbound. Record owners carry unchanged logical identities, never resource permissions.

CSS sources are strings, never filenames to load. No certificate, receipt, permission or parser mutation is produced. Keep the enclosing render budget and the same CSS budget across the original invocation.