carve-hexapdf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d47fc98c98ecd21adba76ed8abb6150aabe535bcb99ad844b6f48705f115dce8
+  data.tar.gz: 3213a192f274a65f6e262ac73009dda8d33d88945406b20096120ce38d5a6158
+SHA512:
+  metadata.gz: 84ad78a47f2cbb33608373ed0d05e3af1f7a14b2f250ed193ad42586bce5e3bae4bdd0b58659517d58e410e6d5f2d7d4a739d9aacd167597c2ff1ffc44a5834d
+  data.tar.gz: 8f88fe4e7cfb412788e3d4c045937db3a03707d891221561ab181485fc6026577cfbbc058c74334c1a5fb4cd07d38dce5d3a4b21bc1f98024142d8e42731ee89

data/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-19
+
+### Added
+
+- Initial release: `Carve::Hexapdf.render`, `.render_ast`, and `.render_file`
+  to render Carve markup to PDF via the pure-Ruby HexaPDF engine.
+- AST walker mapping Carve blocks to HexaPDF text/list/table/container/image
+  boxes and Carve inline nodes to styled text runs.
+- All inline emphasis renders with its decoration: strong/italic/bold-italic
+  (font variants), underline, strikethrough, superscript, subscript, and
+  highlight; critic insert/delete map to underline/strikethrough; footnote
+  references render as superscript.
+- Tables with header rows and full **row / column span** resolution (`^` / `<`
+  markers map to HexaPDF `row_span` / `col_span`).
+- Math and diagram fences render as embedded raster images via optional
+  `renderers:` callables (`:math`, `:mermaid`, `:graphviz`, `:chart`), degrading
+  to monospace source when no renderer is supplied.
+- Images (block and inline) embedded from local file paths or `data:` URIs.
+- Footnotes (inline `^[..]` and referenced `[^id]`) render as superscript
+  `[n]` markers with their bodies collected into a numbered endnote section.
+- Task-list checkboxes are drawn in the list marker column, so item text and
+  nested lists align like any other list.
+- Renderer callables may return `{ bytes:, width:, height: }` to control the
+  drawn size, so high-DPI rasters embed crisply.
+- Hierarchical `styles:` support through `Carve::Hexapdf::StyleMap` for
+  restyling headings, code, links, highlights, admonitions, tables, images,
+  math fallbacks, and other renderer surfaces; the `base_font:`, `code_font:`,
+  `link_color:`, and `highlight_color:` keyword options are convenience sugar
+  under the style map.
+- Graceful degradation: unknown nodes fall back to text/children, remote image
+  URLs show alt text, raw HTML and comments are dropped; the renderer never
+  raises.
+
+[Unreleased]: https://github.com/markup-carve/carve-hexapdf/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/markup-carve/carve-hexapdf/releases/tag/v0.1.0
+
+- **Composite figures render as one grouped float.** A bare `::: figure`
+  container is one numbered figure of ordered panels (Carve PART 9 section 4c,
+  AST node `figure_group`). Its panels, the content preserved between them and
+  the group caption are laid out as a single box a page break may not enter,
+  and each panel keeps its own caption the same way, so the caption that numbers
+  the figure cannot land on the page after it. A group too tall for a page
+  splits rather than failing the render, panels still in source order. A
+  `.columns-N` hint is honored when the page can give every column
+  `figure.group.min_column_width` points and is otherwise ignored in favor of a
+  stack - every panel is drawn either way. Two new style keys, `figure.group`
+  and `figure.group.caption`. The parser this gem consumes does not produce the
+  node yet; `render_ast` accepts one from any engine that does.
+
+### Fixed
+
+- **The `carve-lang` floor moves to `>= 0.1.1`.** At `>= 0.1` a consumer could
+  resolve carve-lang 0.1.0, which predates the Carve 0.1.3 security release and
+  renders a list-valued URL attribute unsanitized - so this gem's own suite
+  could be green while every install of it carried a vulnerable engine. 0.1.1 is
+  the rebuild onto carve-rs 0.1.3.
+
+- **A table's caption no longer loses the whole document.** `table.caption`
+  sits under `table` in the style chain, so it inherited `cell_padding` - a
+  property this renderer reads itself and HexaPDF has never heard of - and
+  splatting it into the caption's text box raised `NoMethodError`. Every
+  captioned table was affected; no fixture had captioned one.
+
+- **A resolved no-break space renders instead of killing the render.** The
+  engines publish U+E000 in a text value to stand for a no-break space the parser
+  resolved - from an escaped space (`a\ b`) or a line block's preserved
+  indentation - and PART 12 says a consumer maps it to its target's no-break
+  space and must not emit it. It was drawn as-is, and the default Type1 font has
+  no glyph for a private-use codepoint, so an ordinary escaped space raised
+  `HexaPDF::MissingGlyphError` and produced no document at all. It now maps to
+  U+00A0 in text, inline code, code blocks and image alt text.
+
+- **Four more inline nodes reach the page instead of vanishing.** `symbol`,
+  `literal_inline`, `caption_number` and `inline_extension` each carry their
+  content in `name`, `content` or `n` rather than in `children`, and the inline
+  fallback emits children only - so they contributed nothing at all: no error, no
+  placeholder, just missing text. A captioned figure rendered its caption without
+  its number. The `emoji` arm had also gone dead when that type was renamed to
+  `symbol` upstream; both names are accepted now. What each prints follows the
+  reference engine's plain-text target. `heading_ref` and `substitution` are still
+  dropped and are pinned as known gaps, since each needs a decision rather than an
+  arm.
+
+- **Bold, italic, underline, strike, superscript and subscript reach the page
+  again.** Each emphasis sort is its own node type now, not one `emphasis` node
+  carrying a `kind` (carve-rb#32). The renderer matched only `emphasis`, so all
+  seven fell through to the default branch: the text still rendered, in the
+  regular face with no decoration, and the PDF stayed valid - which is why the
+  smoke test kept passing. `/*both*/` is a single `strong` carrying
+  `boldItalic`, so the italic is read off the flag rather than inferred from
+  nesting.
+
+- **Footnote endnote numbers are back, and the body appears once.** Definitions
+  used to arrive as a `footnote_defs` map on the root; PART 12 fixes the root at
+  three fields, so they moved into the tree as `footnote` block nodes carrying a
+  `label` (carve-rb#19, #21), and the inline became `footnote_ref` /
+  `inline_footnote` rather than `footnote`. Reading the old root field found
+  nothing, every reference failed to resolve, and the `[1]` markers silently
+  vanished while the bodies still rendered. A definition is now relocated to the
+  endnote section wherever it sits, including inside a container.
+
+  Both old spellings are still accepted, so an AST stored by an earlier version
+  renders the same.
+
+- **An escaped character no longer vanishes from the page.** `escaped_text` is
+  its own inline node (carve#350), and it carries no children - so without an
+  arm of its own it fell through to the branch that emits children and rendered
+  nothing at all. `a\-b` came out as `ab`. The same silent-drop shape as the
+  smart-punctuation node before it (carve#355).
+
+  Dormant until the engine behind `Carve.parse` emits the node; handled here
+  first so the bump lands into a renderer that already copes.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 markup-carve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# carve-hexapdf
+
+Render the [Carve](https://github.com/markup-carve/carve) markup language to
+**PDF** from Ruby, using the pure-Ruby [HexaPDF](https://hexapdf.gettalong.org)
+document composition engine.
+
+Carve source is parsed with [`Carve.parse`](https://github.com/markup-carve/carve-rb)
+(from the `carve-lang` gem) and the resulting AST is walked onto a
+`HexaPDF::Composer`:
+
+- **Inline** nodes become HexaPDF styled text runs: `*strong*` and `/emphasis/`
+  map to bold / italic font variants, `` `code` `` to a monospace font, links to
+  a colored run with a clickable URI overlay.
+- **Block** nodes map to HexaPDF boxes: headings and paragraphs to text boxes,
+  lists to list boxes (ordered / unordered / task), tables to table boxes,
+  block quotes / divs / admonitions to styled containers, and images to image
+  boxes.
+
+## Install
+
+```ruby
+# Gemfile
+gem "carve-hexapdf"
+```
+
+```sh
+bundle install
+```
+
+`carve-hexapdf` depends on `carve-lang` (a native gem that builds the Carve
+engine via Rust) and on `hexapdf`.
+
+## Usage
+
+```ruby
+require "carve/hexapdf"
+
+# Carve syntax note: *...* is STRONG (bold), /.../ is EMPHASIS (italic).
+pdf_bytes = Carve::Hexapdf.render(<<~CRV)
+  # Report
+
+  A paragraph with *bold*, /italic/, `code`, and a [link](https://example.com).
+
+  |= Name |= Score |
+  | Ann   | 42     |
+  | Bob   | 7      |
+CRV
+
+# Write straight to a file:
+Carve::Hexapdf.render_file("# Hello", "hello.pdf")
+
+# Render an already-parsed / transformed AST:
+ast = Carve.parse("# From AST")
+pdf_bytes = Carve::Hexapdf.render_ast(ast)
+```
+
+### Options
+
+| Option | Default | Meaning |
+| ------ | ------- | ------- |
+| `page_size` | `:A4` | HexaPDF page size (e.g. `:A4`, `:Letter`) |
+| `margin` | `45` | Page margin in points |
+| `base_font` | `"Times"` | Proportional font family |
+| `code_font` | `"Courier"` | Monospace font family |
+| `link_color` | `"hp-blue"` | Fill color for links |
+| `highlight_color` | `"fff3a3"` | Background color for `=highlight=` |
+| `styles` | `nil` | Hierarchical style overrides (see below) |
+| `renderers` | `nil` | Callables that turn math / diagram source into image bytes (see below) |
+
+## Styling
+
+Pass `styles:` to restyle renderer output without patching the renderer. Keys are
+hierarchical dotted names; more specific entries win before parent entries, and
+user values win over defaults at the same key.
+
+```ruby
+Carve::Hexapdf.render(source, styles: {
+  "heading" => { fill_color: "333333" },
+  "code.block" => { box: { background_color: "fff8dd", padding: 8 } },
+  "admonition.warning" => { box: { background_color: "fff0f0" } },
+})
+```
+
+Resolution examples:
+
+- `heading.1` resolves through `heading` and then `base`.
+- `code.inline` resolves through `code` and then `base`.
+- `admonition.warning` resolves through `admonition` and then `base`.
+- `box:` hashes deep-merge; other values, including margin arrays, replace as a
+  whole.
+- `box:` only takes effect on keys that draw a surrounding box (`code.block`,
+  `quote`, `admonition`, `definition_list`, `math`); on text-only keys it is
+  ignored.
+- `list` accepts only its structural properties (`item_spacing`,
+  `content_indentation`); item text styling flows through `paragraph`.
+
+Specificity comes first: `"heading" => { font_size: 30 }` does not override the
+default `heading.1` size of `22`, but `"heading" => { fill_color: "333333" }`
+does apply to all heading levels. To change all heading sizes, set
+`heading.1` through `heading.6` individually.
+
+Existing keyword options are sugar under `styles:` and explicit style entries
+win: `base_font:` maps to `base.font`, `code_font:` to `code.font`,
+`link_color:` to `link.fill_color`, and `highlight_color:` to
+`highlight.background_color`.
+
+| Key | Defaults |
+| --- | -------- |
+| `base` | `{ font: "Times" }` |
+| `heading` | `{ margin: [10, 0, 6] }` |
+| `heading.1` ... `heading.6` | `{ font_size: 22 }`, `{ font_size: 18 }`, `{ font_size: 15 }`, `{ font_size: 13 }`, `{ font_size: 12 }`, `{ font_size: 11 }` |
+| `paragraph` | `{ margin: [0, 0, 8] }` |
+| `code` | `{ font: "Courier" }` |
+| `code.block` | `{ font_size: 9, margin: [2, 0, 8], box: { background_color: "f2f2f2", padding: 6 } }` |
+| `code.inline` | `{}` |
+| `quote` | `{ box: { margin: [2, 0, 8], padding: [4, 10], background_color: "f7f7f7" } }` |
+| `admonition` | `{ box: { margin: [2, 0, 8], padding: [6, 10], background_color: "eef3fb" }, title_margin: [0, 0, 4] }` |
+| `admonition.<kind>` | No defaults; any kind the parser accepts works (including hyphenated ones) |
+| `list` | `{ item_spacing: 3, content_indentation: 18 }` |
+| `definition_list` | `{ box: { margin: [0, 0, 8] }, definition_indent: 16 }` |
+| `table` | `{ font_size: 10, cell_padding: 4, margin: [2, 0, 8] }` |
+| `table.header` | `{}` |
+| `table.caption` | `{ font_size: 9, margin: [0, 0, 8] }` |
+| `figure.caption` | `{ font_size: 9, margin: [2, 0, 8], text_align: :center }` (panel captions too) |
+| `figure.group` | `{ box: { margin: [2, 0, 8] }, column_gap: 18, min_column_width: 90 }` |
+| `figure.group.caption` | `{ font_size: 9, margin: [4, 0, 0], text_align: :center }` |
+| `footnote` | `{ font_size: 9, margin: [0, 0, 3] }` (endnote section entries) |
+| `link` | `{ fill_color: "hp-blue" }` |
+| `highlight` | `{ background_color: "fff3a3" }` |
+| `image` | `{ margin: [2, 0, 8] }` |
+| `math` | `{ font_size: 11, margin: [4, 0, 8], box: { padding: 4 } }` |
+| `thematic_break` | `{ height: 2, margin: [8, 0, 8], background_color: "cccccc" }` |
+
+## Supported constructs
+
+Headings, paragraphs, all inline emphasis (strong / emphasis / bold-italic /
+**underline** / **strikethrough** / **superscript** / **subscript** /
+**highlight**), code, links, autolinks, soft & hard breaks, ordered / unordered
+/ task lists (nested), **tables with header rows and full row / column spans**,
+block quotes (with attribution), fenced code blocks, divs, admonitions,
+definition lists, figures, thematic breaks, critic markup (insert → underline,
+delete → strikethrough), **footnotes** (superscript `[n]` markers with the
+bodies collected into a numbered endnote section - inline `^[..]` and
+referenced `[^id]` alike), and **images** - both block and inline, embedded
+from a local file path or a `data:` URI. Task-list checkboxes are drawn in the
+list marker column, so item text and nested lists align like any other list.
+
+### Composite figures
+
+A bare `::: figure` container is one figure of ordered panels (Carve PART 9
+section 4c):
+
+```
+{.columns-2}
+::: figure
+![one](a.png)
+^ (a) One
+
+![two](b.png)
+^ (b) Two
+:::
+^ Figure #: Both samples
+```
+
+On a page that group is one float. Its panels, any content preserved between
+them and the group caption are laid out as a single box a page break may not
+enter, and each panel keeps its own caption the same way - so the caption that
+numbers the figure never lands on the page after the panels it numbers. A
+group too tall to fit a page splits instead of failing the render, with the
+panels still in source order.
+
+`.columns-N` on the attribute line is honored when the page is wide enough to
+give every column `figure.group.min_column_width` points, and is otherwise
+ignored in favor of a stack. Every panel is drawn either way: the hint decides
+arrangement, never content.
+
+An opener that carries a title or a label (`::: figure "T"`, `::: figure [g]`)
+is deliberately NOT this construct - it stays a generic container and renders
+as one.
+
+> [!NOTE]
+> The parser this gem consumes (`carve-lang`, over carve-rs) does not produce
+> `figure_group` nodes yet. The renderer accepts them today - through
+> `Carve.parse` once the engine ships the construct, and through
+> `Carve::Hexapdf.render_ast` with an AST from any engine that already does.
+
+### Math and diagrams (renderer callables)
+
+PDF has no client-side renderer, so math and diagram fences are turned into
+embedded raster images through callables you supply in `renderers:`. Each
+returns image bytes (PNG/JPG) as a String - or a Hash `{ bytes:, width:,
+height: }` (points) to control the drawn size, so high-DPI rasters embed
+crisply at their intended dimensions. A missing renderer, or one that returns
+anything else or raises, degrades that construct to its monospace source.
+
+```ruby
+Carve::Hexapdf.render(source, renderers: {
+  # inline `$`x`$` and display `$$`x`$$` math:
+  math: ->(tex, display) { my_tex_to_png(tex, display) },   # -> bytes | {bytes:, width:, height:} | nil
+  # fenced ```mermaid / ```dot|graphviz / ```chart|vega:
+  mermaid:  ->(src) { my_mermaid_to_png(src) },
+  graphviz: ->(src) { my_dot_to_png(src) },
+  chart:    ->(src) { my_chart_to_png(src) },
+})
+```
+
+### Graceful degradation
+
+The renderer never raises on an unsupported node - it degrades so a document
+always produces a PDF:
+
+- **Math / diagram** fences without a matching `renderers:` callable render
+  their source in a monospace run.
+- **Remote image URLs** (`http(s)://`) are shown as alt text - no network
+  fetching. Local files and `data:` URIs are embedded.
+- **Raw HTML** blocks/inlines and **comments** are dropped.
+
+## Licensing
+
+This gem is **MIT** licensed. However, **HexaPDF is dual-licensed AGPL-3.0 /
+commercial**. If you distribute software or offer it over a network while
+depending on HexaPDF, you must comply with the AGPL (open-source your
+application) or hold a
+[HexaPDF commercial license](https://hexapdf.gettalong.org/#pricing). This gem
+only bridges Carve to HexaPDF; your use of HexaPDF is governed by HexaPDF's own
+terms.
+
+## License
+
+MIT, markup-carve. See [LICENSE](LICENSE).