RubyGems - silk_layout - Versions diffs - 0.1.0 - Mend

silk_layout 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +20 -0
data/LICENSE +21 -0
data/README.md +154 -0
data/lib/silk_layout/css/cascade.rb +49 -0
data/lib/silk_layout/css/computed_style.rb +83 -0
data/lib/silk_layout/css/parser.rb +50 -0
data/lib/silk_layout/css/properties.rb +19 -0
data/lib/silk_layout/css/rule.rb +15 -0
data/lib/silk_layout/css/selector.rb +165 -0
data/lib/silk_layout/html/node.rb +56 -0
data/lib/silk_layout/html/parser.rb +188 -0
data/lib/silk_layout/layout/block_layout.rb +93 -0
data/lib/silk_layout/layout/box.rb +80 -0
data/lib/silk_layout/layout/box_builder.rb +11 -0
data/lib/silk_layout/layout/context.rb +13 -0
data/lib/silk_layout/layout/engine.rb +22 -0
data/lib/silk_layout/layout/flex_layout.rb +508 -0
data/lib/silk_layout/layout/formatting_builder.rb +425 -0
data/lib/silk_layout/layout/inline.rb +88 -0
data/lib/silk_layout/layout/inline_formatter.rb +132 -0
data/lib/silk_layout/layout/root.rb +15 -0
data/lib/silk_layout/render/font_library.rb +127 -0
data/lib/silk_layout/render/painter.rb +247 -0
data/lib/silk_layout/render/pdf_renderer.rb +31 -0
data/lib/silk_layout/version.rb +5 -0
data/lib/silk_layout.rb +55 -0
metadata +251 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98125df0dda9b67eb2040377c0d095ed91b33e2f62b944643c57565ba2c45cf3
+  data.tar.gz: b19305f2b4f6e72d5a438ff299f0b6c5378eecda536436c865d10c8b82ac93fb
+SHA512:
+  metadata.gz: 9d12cfbb00fdfa50249fe3890ffc8c2d0742975089c8e19562e23fbff2a7055f4b52fee5af7a203fcf34ef5e195eb4d7f27b5f365484eef49e5a5d787489a7d1
+  data.tar.gz: 50e90dbf3aa62fb150b028925bc8de3636c0fa54654c4ae68aedcd3eb9cd1b2187680b3ba90cc9cca2bff7557763e39eb3c6ec9eaaa973badcef0caebf896ed0

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,20 @@
+# Changelog
+All notable changes to SilkLayout will be documented here.
+This project follows a lightweight changelog format while it is pre-1.0.
+## Unreleased
+No changes yet.
+## 0.1.0
+- Add public project README, MIT license, contribution guide, security policy,
+  and issue templates.
+- Prepare repository metadata for public visibility.
+- Ruby-native HTML/CSS parsing, layout, and PDF rendering foundation.
+- Block and inline layout support.
+- Box model support for margins, padding, borders, and backgrounds.
+- Basic flex layout support.
+- Visual regression tests against Chromium output.

data/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Reegan Viljoen
+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 ADDED Viewed

@@ -0,0 +1,154 @@
+# SilkLayout
+SilkLayout is a Ruby-native HTML/CSS layout engine that renders documents to PDF.
+The long-term goal is to make PDF generation feel natural inside Ruby apps without
+delegating layout to a browser engine. The project is currently on the `0.1`
+release track: useful for experimentation, regression testing, and early document
+rendering, but not yet 1.0 or browser-spec complete.
+## Current Status
+SilkLayout currently supports:
+- HTML parsing with Nokogiri
+- CSS parsing with Crass
+- CSS cascade basics, selector matching, specificity, inheritance, inline styles,
+  and `!important`
+- block layout, inline text layout, line wrapping, and whitespace normalization
+- box model spacing: margin, padding, borders, border colors, width, and height
+- basic flex layout: rows, columns, reverse directions, wrapping, gaps, grow,
+  shrink, basis, justify, and align basics
+- PDF rendering with HexaPDF for text, borders, border colors, and simple
+  background colors
+- visual regression tests against Chromium output
+Not yet supported:
+- CSS Grid
+- percentage and `calc()` sizing
+- images
+- pagination and page-break controls
+- positioning, floats, tables, and list markers
+- border radius, shadows, gradients, and background images
+- full CSS color syntax such as `rgb()`, `rgba()`, and `hsl()`
+## Installation
+Add the gem to your bundle once released:
+```ruby
+gem "silk_layout"
+```
+For local development from this repository:
+```sh
+bundle install
+```
+## Usage
+```ruby
+require "silk_layout"
+html = <<~HTML
+  <!doctype html>
+  <html>
+    <head>
+      <style>
+        body { font-family: Helvetica; margin: 0; }
+        .row {
+          display: flex;
+          gap: 16px;
+          padding: 16px;
+          border: 2px solid black;
+        }
+        .item {
+          width: 80px;
+          padding: 8px;
+          border: 1px solid blue;
+          background: lightblue;
+        }
+      </style>
+    </head>
+    <body>
+      <div class="row">
+        <div class="item">One</div>
+        <div class="item">Two</div>
+      </div>
+    </body>
+  </html>
+HTML
+SilkLayout.render_document(html, "out.pdf")
+```
+## Documentation
+The documentation site lives in [`docs/`](docs/index.md). It includes the project
+goal, current support matrix, before-1.0 roadmap, and Chromium-vs-SilkLayout
+screenshots from the visual regression suite.
+## Development
+Run the full local gate:
+```sh
+bundle exec rake
+```
+Run tests only:
+```sh
+bundle exec rake test
+```
+Run lint:
+```sh
+bundle exec standardrb
+```
+Run a single test file:
+```sh
+bundle exec ruby -Ilib:test test/layout/flex_layout_test.rb
+```
+Visual regression tests require Chromium or Chrome plus PDF-to-PNG tooling such
+as Poppler or ImageMagick. Generated visual artifacts are written to
+`tmp/visual/`.
+## Releasing
+SilkLayout releases use the checked-in release script:
+```sh
+DRY_RUN=1 script/release
+script/release
+```
+The script must be run from a clean, up-to-date `main` branch after the release
+PR is merged. It installs dependencies, runs the test/lint/build gate, publishes
+the gem through Bundler's release task, and creates a GitHub release from the
+matching `CHANGELOG.md` section.
+This gem is still pre-1.0. Before a public 1.0 release, the project should
+stabilize the supported CSS surface, add pagination, improve visual parity, and
+document compatibility promises.
+## Contributing
+Contributions are welcome while the engine is young. Please read
+[`CONTRIBUTING.md`](CONTRIBUTING.md) and open issues or PRs with focused examples
+and, where possible, visual regression fixtures.
+## Security
+Please report security issues privately using the process in
+[`SECURITY.md`](SECURITY.md).
+## License
+SilkLayout is available under the MIT License. See [`LICENSE`](LICENSE).

data/lib/silk_layout/css/cascade.rb ADDED Viewed

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+require "crass"
+module SilkLayout
+  module CSS
+    class Cascade
+      def self.apply(node, rules, parent_style = nil)
+        return unless node
+        return unless node.respond_to?(:element?)
+        matching = rules.select { |rule| rule.selector.match?(node) }
+        inline = inline_rule(node)
+        matching << inline if inline
+        matching.sort_by! { |rule| [rule.specificity, rule.order] }
+        node.computed_style = ComputedStyle.new(matching, parent_style)
+        node.children.each do |child|
+          apply(child, rules, node.computed_style)
+        end
+      end
+      def self.inline_rule(node)
+        return nil unless node.attributes
+        style = node.attributes["style"].to_s.strip
+        return nil if style.empty?
+        declarations = {}
+        Crass.parse_properties(style).each do |child|
+          next unless child[:node] == :property
+          declarations[child[:name]] = Declaration.new(value: child[:value], important: child[:important] ? true : false)
+        end
+        Rule.new(
+          selector: nil,
+          declarations: declarations,
+          specificity: [1000, 0, 0],
+          order: 1_000_000_000,
+          origin: :author
+        )
+      end
+    end
+  end
+end

data/lib/silk_layout/css/computed_style.rb ADDED Viewed

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+module SilkLayout
+  module CSS
+    class ComputedStyle
+      def initialize(rules, parent_style = nil)
+        @values = {}
+        @explicit_properties = {}
+        apply_rules(rules)
+        apply_inheritance(parent_style)
+        apply_defaults
+      end
+      def [](property)
+        @values[property]
+      end
+      def width
+        @values["width"]
+      end
+      def explicit_width?
+        value = @values["width"]
+        value && value != "auto"
+      end
+      def explicit_height?
+        value = @values["height"]
+        value && value != "auto"
+      end
+      def explicit_display?
+        @explicit_properties.key?("display")
+      end
+      private
+      INLINE_SPECIFICITY = [1000, 0, 0].freeze
+      def apply_rules(rules)
+        winners = {}
+        rules.each do |rule|
+          spec = rule.specificity || INLINE_SPECIFICITY
+          order = rule.order || 0
+          rule.declarations.each do |property, decl|
+            value = decl.is_a?(Declaration) ? decl.value : decl
+            important = decl.is_a?(Declaration) ? decl.important : false
+            key = [important ? 1 : 0, spec, order]
+            current = winners[property]
+            if current.nil? || (key <=> current[:key]) == 1
+              winners[property] = {key: key, value: value}
+              @explicit_properties[property] = true
+            end
+          end
+        end
+        winners.each do |prop, data|
+          @values[prop] = data[:value]
+        end
+      end
+      def apply_inheritance(parent)
+        return unless parent
+        Properties::INHERITED.each do |prop|
+          @values[prop] ||= parent[prop]
+        end
+      end
+      def apply_defaults
+        Properties::DEFAULTS.each do |prop, value|
+          @values[prop] ||= value
+        end
+      end
+    end
+  end
+end

data/lib/silk_layout/css/parser.rb ADDED Viewed

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+require "crass"
+module SilkLayout
+  module CSS
+    class Parser
+      def self.parse_all(stylesheets)
+        rules = []
+        order = 0
+        stylesheets.each do |css|
+          Crass.parse(css).each do |node|
+            next unless node[:node] == :style_rule
+            selector_text = node[:selector][:value].strip
+            selectors = selector_text.split(",").map(&:strip)
+            declarations = {}
+            node[:children].each do |child|
+              next unless child[:node] == :property
+              property = child[:name]
+              value = child[:value]
+              declarations[property] = Declaration.new(value: value, important: child[:important] ? true : false)
+            end
+            selectors.each do |raw_selector|
+              selector = Selector.new(raw_selector)
+              rules << Rule.new(
+                selector: selector,
+                declarations: declarations,
+                specificity: selector.specificity,
+                order: order,
+                origin: :author
+              )
+              order += 1
+            end
+          end
+        end
+        rules
+      end
+    end
+  end
+end

data/lib/silk_layout/css/properties.rb ADDED Viewed

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+module SilkLayout
+  module CSS
+    module Properties
+      INHERITED = %w[
+        color
+        font-size
+        font-family
+      ].freeze
+      DEFAULTS = {
+        "color" => "black",
+        "font-size" => "16px",
+        "display" => "inline"
+      }.freeze
+    end
+  end
+end

data/lib/silk_layout/css/rule.rb ADDED Viewed

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module SilkLayout
+  module CSS
+    Declaration = Struct.new(:value, :important)
+    Rule = Struct.new(
+      :selector,
+      :declarations,
+      :specificity,
+      :order,
+      :origin
+    )
+  end
+end

data/lib/silk_layout/css/selector.rb ADDED Viewed

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+module SilkLayout
+  module CSS
+    class Selector
+      def initialize(raw)
+        @raw = raw.to_s.strip
+        @steps = parse_steps(@raw)
+      end
+      def match?(node)
+        return false unless node.respond_to?(:element?)
+        return false unless node.element?
+        return false if node.tag.nil?
+        return false unless step_match?(@steps.last[:simple], node)
+        current = node
+        i = @steps.length - 2
+        while i >= 0
+          comb = @steps[i + 1][:combinator]
+          simple = @steps[i][:simple]
+          case comb
+          when :child
+            current = current.parent
+            return false unless current
+            return false unless step_match?(simple, current)
+          when :descendant
+            current = find_ancestor(current.parent, simple)
+            return false unless current
+          else
+            return false
+          end
+          i -= 1
+        end
+        true
+      end
+      def specificity
+        ids = 0
+        classes = 0
+        elements = 0
+        @steps.each do |step|
+          simple = step[:simple]
+          ids += 1 if simple[:id]
+          classes += simple[:classes].length
+          elements += 1 if simple[:tag]
+        end
+        [ids, classes, elements]
+      end
+      private
+      def parse_steps(raw)
+        tokens = tokenize(raw)
+        parts = []
+        pending_combinator = nil
+        tokens.each do |tok|
+          if tok == ">"
+            pending_combinator = :child
+            next
+          end
+          if tok == " "
+            pending_combinator ||= :descendant
+            next
+          end
+          parts << {simple: parse_simple(tok), combinator: pending_combinator}
+          pending_combinator = nil
+        end
+        # Default combinator between left/right parts is descendant.
+        # Combinator is stored on the RIGHT step to indicate how it relates to the LEFT.
+        parts.each_with_index do |part, idx|
+          next if idx == 0
+          part[:combinator] ||= :descendant
+        end
+        parts
+      end
+      def tokenize(raw)
+        raw = raw.strip
+        tokens = []
+        buf = +""
+        in_space = false
+        raw.each_char do |ch|
+          if ch == ">"
+            tokens << buf unless buf.empty?
+            buf = +""
+            tokens << ">"
+            in_space = false
+            next
+          end
+          if ch.match?(/\s/)
+            tokens << buf unless buf.empty?
+            buf = +""
+            tokens << " " unless in_space
+            in_space = true
+            next
+          end
+          in_space = false
+          buf << ch
+        end
+        tokens << buf unless buf.empty?
+        tokens.reject(&:empty?)
+      end
+      def parse_simple(token)
+        tag = nil
+        id = nil
+        classes = []
+        rest = token.to_s
+        if rest.match?(/\A[a-zA-Z][a-zA-Z0-9_-]*/)
+          m = rest.match(/\A([a-zA-Z][a-zA-Z0-9_-]*)/)
+          tag = m[1]
+          rest = rest[m[1].length..]
+        end
+        rest.scan(/([#.])([a-zA-Z0-9_-]+)/) do |kind, value|
+          if kind == "#"
+            id = value
+          else
+            classes << value
+          end
+        end
+        {tag: tag, id: id, classes: classes}
+      end
+      def step_match?(simple, node)
+        return false if simple[:tag] && node.tag != simple[:tag]
+        return false if simple[:id] && node.attributes["id"] != simple[:id]
+        if simple[:classes].any?
+          node_classes = node.attributes.fetch("class", "").split
+          return false unless simple[:classes].all? { |c| node_classes.include?(c) }
+        end
+        true
+      end
+      def find_ancestor(node, simple)
+        current = node
+        while current
+          return current if step_match?(simple, current)
+          current = current.parent
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/silk_layout/html/node.rb ADDED Viewed

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+module SilkLayout
+  module HTML
+    class Node
+      attr_reader :tag, :attributes, :text
+      attr_accessor :children, :parent
+      attr_accessor :computed_style
+      def initialize(tag:, attributes:, children:, text: nil, parent: nil)
+        @tag = tag
+        @attributes = attributes
+        @children = children
+        @text = text
+        @parent = parent
+      end
+      def element?
+        !tag.nil?
+      end
+      def self.from_nokogiri(node, parent = nil)
+        if node.text?
+          build_text_node(node, parent)
+        else
+          build_element_node(node, parent)
+        end
+      end
+      def self.build_text_node(node, parent)
+        text = node.text.to_s
+        return nil if text.empty?
+        new(
+          tag: nil,
+          attributes: {},
+          children: [],
+          text: text,
+          parent: parent
+        )
+      end
+      def self.build_element_node(node, parent)
+        element = new(
+          tag: node.name,
+          attributes: node.attributes.transform_values(&:value),
+          children: [],
+          parent: parent
+        )
+        element.children = node.children.map { |child| from_nokogiri(child, element) }.compact
+        element
+      end
+    end
+  end
+end