NativeElixirPdfUtilities.HtmlToPdf.CssParser (native_elixir_pdf_utilities v0.8.0)

Strict CSS parser for the native HTML-to-PDF renderer.

The parser accepts the document-oriented selector subset used by the style cascade: element, class, id, element.class, descendant, child, and comma groups. Bare @page { ... } and simple @font-face rules are accepted outside the style cascade, and @media print rules are included in the active print cascade. Page selectors, named-page preludes, and misspelled @page at-rules are rejected. Declarations are kept as normalized property/value pairs so the style layer can validate values against the renderer's supported property set.

Summary

Types

declaration()

font_face()

page_option()

rule()

selector()

selector_part()

stylesheet()

Functions

font_faces(css)

Extracts active local font declarations from @font-face rules.

page_options(css)

Extracts renderer page defaults from bare @page { ... } rules.

parse(css)

Parses a CSS stylesheet into strict renderer rules.

parse_declarations(css)

Parses a CSS declaration block into normalized property/value pairs.

parse_declarations_detailed(css)

Parses a CSS declaration block and returns source-location details on failure.

parse_detailed(css)

Parses a CSS stylesheet and returns source-location details when parsing fails.

Types

declaration()

@type declaration() :: {String.t(), String.t()} | {String.t(), String.t(), :important}

font_face()

@type font_face() :: %{
  family: String.t(),
  sources: [String.t()],
  weight: 100..900,
  style: :normal | :italic
}

page_option()

@type page_option() ::
  {:page_size,
   NativeElixirPdfUtilities.HtmlToPdf.PageGeometry.page_size_input()}
  | {:margin, NativeElixirPdfUtilities.HtmlToPdf.PageGeometry.margin_input()}

rule()

@type rule() :: %{
  selectors: [selector()],
  declarations: [declaration()],
  order: non_neg_integer()
}

selector()

@type selector() :: %{
  parts: [selector_part()],
  specificity: {non_neg_integer(), non_neg_integer(), non_neg_integer()}
}

selector_part()

@type selector_part() :: %{
  tag: String.t() | nil,
  id: String.t() | nil,
  classes: [String.t()],
  pseudo_classes: [
    :first_child | :last_child | :root | {:nth_child, pos_integer()}
  ],
  combinator: nil | :descendant | :child
}

stylesheet()

@type stylesheet() :: [rule()]

Functions

font_faces(css)

@spec font_faces(String.t()) :: {:ok, [font_face()]} | {:error, :invalid_css}

Extracts active local font declarations from @font-face rules.

Sources must use url(...) with a TrueType or OpenType source. Remote URLs, data URIs, WOFF/WOFF2 sources, and unsupported descriptors are rejected. Relative paths are returned unchanged for the style layer to resolve against the stylesheet location or renderer :base_url. Supported sources retain their declared order so loading can fall back when an earlier file is unavailable or invalid.

page_options(css)

@spec page_options(String.t()) :: {:ok, [page_option()]} | {:error, :invalid_css}

Extracts renderer page defaults from bare @page { ... } rules.

Valid page-context properties are accepted even when the renderer does not apply them yet. Rendering consumes accepted named and explicit two-length size values, portrait and landscape orientations, one-to-four-value margin shorthands, and the four margin longhands. Malformed declarations, unknown properties, invalid paged-media descriptor values, page selectors, named-page preludes, and misspelled @page at-rules return {:error, :invalid_css}.

parse(css)

@spec parse(String.t()) :: {:ok, stylesheet()} | {:error, :invalid_css}

Parses a CSS stylesheet into strict renderer rules.

parse_declarations(css)

@spec parse_declarations(String.t()) ::
  {:ok, [declaration()]} | {:error, :invalid_css}

Parses a CSS declaration block into normalized property/value pairs.

This is used for both stylesheet blocks and inline style attributes.

parse_declarations_detailed(css)

@spec parse_declarations_detailed(String.t()) ::
  {:ok, [declaration()]} | {:error, {:invalid_css, map()}}

Parses a CSS declaration block and returns source-location details on failure.

parse_detailed(css)

@spec parse_detailed(String.t()) ::
  {:ok, stylesheet()} | {:error, {:invalid_css, map()}}

Parses a CSS stylesheet and returns source-location details when parsing fails.