carve-hexapdf 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ca1e064f1b2cfe5886e3c9ead5c523e39d8017f560fa045c01e18af746ebdcc
-  data.tar.gz: 7a5055cb52def857760862d08a68aa112623a698760169e85a23358f6f04d548
+  metadata.gz: e542a29c024a850009d9f9fa32d6fe69ba870a97eab23f595522878d7da1c367
+  data.tar.gz: 05d84eaa30d5ad7c4d6f111dc442f88a113bf8a7aa817849df4ee7b58bb5942f
 SHA512:
-  metadata.gz: 3f24bf3e136eb703f0a3561b8f929f6ede44f372b2722fdf19560669420df44ada47ead8f14e3b2f3d858681c4ab0a5488c4723e44c9598e620c9920ab63bd68
-  data.tar.gz: 5db634aa0f278239009b35018bc524a27295f1494c92be78f577f955d1af139086e06190207bc68f7fe4906650c52d3853fa5444f0a56b44308ec1fa07fd9e49
+  metadata.gz: 1382a76d094f651b2cc1b6cbae0ce65409d27222e02f4355361fce93ef6c9cc873b1ebd58ea01b6f02003ebb112ee8228784bb4dddf0aea60ac7186fc4e48f74
+  data.tar.gz: 25cd7967c9fe80a6c18df8a2d261c6d27d041a874029c056b52f43f621af5e97f939e3a19f9c141eaa51a87292829445ac58b8074a09a477c8afd61cff31b149

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-11-12
+
+Definition lists and table cell alignment now reach the PDF, the gem loads on Ruby 3.4, and the engine moves to carve-lang 0.1.14.
+
+### Fixes
+
+- Definition list terms and descriptions are drawn; they were dropped from the page on every engine (#66).
+- `require "carve/hexapdf"` works on Ruby 3.4, where `base64` is no longer a default gem (#64).
+
+### Improvements
+
+- Table cells keep their horizontal alignment, from the cell or its column's header (#67).
+- Developed and tested against carve-lang 0.1.14. Its braced alignment spelling (`|={>}`) right-aligns the column; a first-line `---` now opens frontmatter that runs to the end of an unclosed document, so nothing below it is drawn (#68).
+
+**Full Changelog**: https://github.com/markup-carve/carve-hexapdf/compare/v0.1.5...v0.1.6
+
+## [0.1.5] - 2026-10-24
+
+Ruby interchange text now appears in rendered PDFs, and tables with span markers render without a PDF layout error.
+
+### Fixes
+
+- Ruby base text and annotations render together instead of losing the annotation (#58).
+- Tables with ownerless span markers or a header rowspan crossing into body rows render without a PDF layout error (#60).
+
+**Full Changelog**: https://github.com/markup-carve/carve-hexapdf/compare/v0.1.4...v0.1.5
+
+
 ## [0.1.4] - 2026-10-23
 
 ### Fixed

data/README.md

@@ -1,274 +1,27 @@
 # 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.
+Ruby PDF renderer for Carve documents. It supports `carve-lang` 0.1.1 or later and uses the HexaPDF composition engine. See the [Carve documentation](https://markup-carve.github.io/carve/).
 
 ## Install
 
-```ruby
-# Gemfile
-gem "carve-hexapdf"
-```
-
 ```sh
-bundle install
+gem install carve-hexapdf
 ```
 
-`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)
-```
-
-### Includes
-
-A Carve document can pull another file in with `{{ path }}`. A String has no
-identity of its own, so a directive in one stays literal; name the file instead
-and it expands:
-
-```ruby
-pdf_bytes = Carve::Hexapdf.render_from_file("report/index.crv")
-```
-
-`render_from_file` READS Carve from a path and hands back PDF bytes.
-`render_file` is its opposite pair: it takes Carve source and WRITES the PDF out,
-and a directive in that source stays literal.
-
-Containment defaults to the input file's own directory, so a sibling or a file
-below it resolves and nothing above it does. `include_root:` moves that root:
-
-```ruby
-Carve::Hexapdf.render_from_file("report/index.crv", include_root: "/srv/docs")
 ```
 
-The root must be **absolute**. A relative one is refused rather than resolved,
-because resolving it lands on whatever directory the process happens to run in,
-which is not a root anyone chose. The named document has to sit inside the root.
-
-A target that cannot be read leaves the directive drawn as written, and the
-reason goes to stderr. The message does not say whether the file was missing or
-refused by containment: both report `include-unresolved`, so a document cannot
-be used to probe the filesystem. Pass `on_includes:` to take reporting over and
-get the dependency identities with it:
-
-```ruby
-Carve::Hexapdf.render_from_file(
-  "report/index.crv",
-  on_includes: lambda { |warnings:, dependencies:, suppressed_warnings:|
-    dependencies.each { |d| puts "#{d[:path]} #{d[:resolved] ? 'read' : d[:denial]}" }
-  }
-)
-```
-
-`extensions:` and `profile:` reach the engine on the include path, and a child
-file is parsed with the same ones as its parent. Without a root they raise,
-rather than being dropped: `Carve.parse` accepts neither.
-
-### 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.
-
-## Development
+## Documentation
 
-Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).
+- [Carve documentation](https://markup-carve.github.io/carve/)
+- [Guide](docs/guide.md)
+- [Documentation index](docs/README.md)
+- [Contributing and development](docs/development.md)
 
-## Licensing
+## License
 
-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.
+[MIT](LICENSE). HexaPDF has separate licensing terms; see the [guide](docs/guide.md#licensing).

data/lib/carve/hexapdf/renderer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "stringio"
-require "base64"
 
 require_relative "style_map"
 
@@ -258,13 +257,15 @@ module Carve
       def definition_list(node, target)
         style = style_for("definition_list", with_box: true)
         target.container(style: style[:box]) do |cont|
+          # `items` is a flat run of definition_term / definition_description
+          # nodes, not term/definition pairs.
           Array(node[:items]).each do |item|
-            Array(item[:terms]).each do |term|
-              cont.formatted_text(inline_runs(term, bold: true), margin: [2, 0, 1])
-            end
-            Array(item[:definitions]).each do |defn|
+            case item[:type]
+            when "definition_term"
+              cont.formatted_text(inline_runs(item[:children], bold: true), margin: [2, 0, 1])
+            when "definition_description"
               cont.container(style: { padding: [0, 0, 0, style[:definition_indent]] }) do |dcont|
-                Array(defn).each { |ch| block(ch, dcont) }
+                Array(item[:children]).each { |ch| block(ch, dcont) }
               end
             end
           end
@@ -429,9 +430,12 @@ module Carve
         resolved = resolve_spans(Array(node[:rows]))
         return if resolved.empty?
 
-        header_count = resolved.first.any? { |o| o[:header] } ? 1 : 0
+        # HexaPDF cannot repeat a header whose cell spans into the body.
+        header_count = resolved.first.any? { |o| o[:header] } &&
+                       resolved.first.none? { |o| o[:row_span] > 1 } ? 1 : 0
         table_style = style_for("table")
         header_style = style_for("table.header")
+        columns = column_alignments(node)
 
         cell_boxes = resolved.map do |row|
           row.map do |o|
@@ -442,6 +446,9 @@ module Carve
             # :margin belongs to the table box, :cell_padding is our pseudo-prop.
             box_opts = cell_style.except(:margin, :cell_padding, :box)
             box_opts[:padding] = cell_style[:cell_padding]
+            column = columns[o[:col]] || {}
+            align = o[:cell][:align] || column[:align]
+            box_opts[:text_align] = CELL_ALIGN[align] if CELL_ALIGN.key?(align)
             box = @layout.formatted_text_box(runs, **box_opts)
             hash = { content: box }
             hash[:col_span] = o[:col_span] if o[:col_span] > 1
@@ -462,9 +469,37 @@ module Carve
         end
       end
 
+      CELL_ALIGN = { "left" => :left, "center" => :center, "right" => :right }.freeze
+
+      # A cell without its own alignment inherits its column's: the table's
+      # `columns` metadata, overridden by the head rows (the HTML `thead`), a
+      # later row winning. Any other cell's alignment is local. The head is
+      # `rowGroups.headRows` when published, else the leading header rows.
+      # Vertical alignment is not drawn: `text_valign` overflows a table cell.
+      def column_alignments(node)
+        columns = Array(node[:columns]).map { |c| (c || {}).slice(:align) }
+        rows = Array(node[:rows])
+        declared = node.dig(:rowGroups, :headRows)
+        head = declared.is_a?(Integer) ? rows.first(declared) : rows.take_while { |row| header_row?(row) }
+        head.each do |row|
+          Array(row[:cells]).each_with_index do |cell, col|
+            next if cell[:span]
+
+            (columns[col] ||= {})[:align] = cell[:align] if cell[:align]
+          end
+        end
+        columns
+      end
+
+      # A `^` / `<` marker is not a header cell, but leaves its row in the head.
+      def header_row?(row)
+        content = Array(row[:cells]).reject { |cell| cell[:span] }
+        !content.empty? && content.all? { |cell| cell[:header] }
+      end
+
       # Resolve Carve's explicit span markers (a `<` cell = merge left, a `^`
       # cell = merge up) into per-cell col_span / row_span counts, returning
-      # rows of originator hashes {cell:, header:, col_span:, row_span:} with
+      # rows of originator hashes {cell:, header:, col:, col_span:, row_span:} with
       # marker cells dropped. Every covered grid position is explicit in Carve,
       # so a cell's column index equals its position in the row.
       def resolve_spans(rows)
@@ -478,8 +513,17 @@ module Carve
             case cell[:span]
             when "colspan"
               owner = last || col_owner[col - 1]
-              owner[:col_span] += 1 if owner
-              col_owner[col] = owner if owner
+              if owner
+                owner[:col_span] += 1
+                col_owner[col] = owner
+              else
+                # A leading marker has no cell to extend. Keep its grid slot
+                # so the table has a drawable cell in this row.
+                o = { cell: cell, header: cell[:header], col: col, col_span: 1, row_span: 1 }
+                emitted << o
+                last = o
+                col_owner[col] = o
+              end
             when "rowspan"
               owner = col_owner[col]
               # A multi-column cell has one `^` per covered column on the next
@@ -488,10 +532,14 @@ module Carve
                 owner[:row_span] += 1
                 bumped[owner.object_id] = true
               end
-              # col_owner[col] stays pointing at the same originator so a
-              # further `^` in the next row chains onto it.
+              if owner.nil?
+                o = { cell: cell, header: cell[:header], col: col, col_span: 1, row_span: 1 }
+                emitted << o
+                col_owner[col] = o
+              end
+              # A valid owner's slot remains available for further `^` rows.
             else
-              o = { cell: cell, header: cell[:header], col_span: 1, row_span: 1 }
+              o = { cell: cell, header: cell[:header], col: col, col_span: 1, row_span: 1 }
               emitted << o
               last = o
               col_owner[col] = o
@@ -594,6 +642,13 @@ module Carve
         when "substitution"
           emit_half(node[:old], node[:oldText], ctx.merge(strike: true), out)
           emit_half(node[:new], node[:newText], ctx.merge(underline: true), out)
+        when "ruby"
+          Array(node[:pairs]).each do |pair|
+            Array(pair[:base]).each { |part| emit_inline(part, ctx, out) }
+            out << run("(", ctx)
+            Array(pair[:annotation]).each { |part| emit_inline(part, ctx, out) }
+            out << run(")", ctx)
+          end
         when "smart_punctuation" then out << run(smart_punctuation_text(node), ctx)
         # A character the author escaped. The backslash is authoring syntax, so
         # the page shows the character - but the node has no children, so
@@ -883,7 +938,7 @@ module Carve
           meta, data = src.split(",", 2)
           return nil unless data
 
-          bytes = meta.include?(";base64") ? Base64.decode64(data) : data
+          bytes = meta.include?(";base64") ? data.unpack1("m") : data
           return StringIO.new(bytes)
         end
         return src if File.file?(src)

data/lib/carve/hexapdf/version.rb

@@ -2,6 +2,6 @@
 
 module Carve
   module Hexapdf
-    VERSION = "0.1.4"
+    VERSION = "0.1.6"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carve-hexapdf
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang