prawn-widget 2.0.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.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 3e30e986197cab5c5b408c2ea6f426c012831f32806f76a5ce29ba1fc72c7b7e
4
+ data.tar.gz: 6d6497d4a4d7a3640e6e6e69242caf95b22b1efc2e6484fff5352d472317bdb3
5
+ SHA512:
6
+ metadata.gz: 7dc791c749cdaad519051180fe073e0d67947c5439c9c0b26c50952390ad006d354744488a0f94543c29e60f13e32c8539116dca771267769f13b1aabcc2b94c
7
+ data.tar.gz: 91afbb699dff5adbf91a7e537494bfcecc3c9e946ae83b35e8aef2e22f79a1ffdf18a8dc206b87b58b244175a28ca993593bd9aeef106a9ea96a75b0f6c89f73
data/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ ## 2.0.0 (unreleased)
4
+
5
+ Modernization on the road to `prawn-widget`.
6
+
7
+ ### Renamed
8
+
9
+ - Gem renamed `prawn-component` to `prawn-widget` (the old name is taken on RubyGems).
10
+ - The Ruby API is unchanged: components still inherit from `Prawn::Widget`.
11
+
12
+ ### Changed
13
+
14
+ - Slot setters follow the current ViewComponent API: `with_title`, `with_article`, `with_articles`.
15
+ - The old bare setters (`title`, `article`) were removed.
16
+
17
+ ### Removed
18
+
19
+ - String callables (`renders_one :x, "SomeClass"`) are gone; use a component class or a lambda.
20
+
21
+ ### Tooling
22
+
23
+ - Tests moved from RSpec to Megatest (`bin/tests` runs the suite).
24
+ - Pinned to Ruby 4.0.9 (`.ruby-version`), refreshed `Gemfile.lock`.
25
+ - SPDX license headers in every Ruby file, singular SPDX `license` field in the gemspec.
26
+
27
+ ## 1.0.0
28
+
29
+ - First release: ViewComponent-style slots for Prawn.
30
+ - `renders_one` and `renders_many` with bare setters, `Slot#draw`, `render_in` and `call_in`.
31
+ - Params and options via `dry-initializer` (through a vendored `method_object` copy).
data/README.md ADDED
@@ -0,0 +1,234 @@
1
+ [![License](http://img.shields.io/badge/license-MIT-blue.svg)](http://github.com/halo/prawn-component/blob/master/LICENSE.md)
2
+
3
+ > [!NOTE]
4
+ > **Looking for the old API?** Pin the legacy gem:
5
+ > ```ruby
6
+ > gem 'prawn-component', github: 'halo/prawn-component', tag: 'v1.0.0'
7
+ > ```
8
+ > **New here?** Use the renamed gem from RubyGems:
9
+ > ```ruby
10
+ > gem 'prawn-widget'
11
+ > ```
12
+
13
+ ## TL;DR
14
+
15
+ This is an implementation of the popular [view_component](https://viewcomponent.org) gem for Prawn.
16
+
17
+ ## Usage
18
+
19
+ You define a component just like you would using the `view_component` gem. The only difference, of course, is that you
20
+ don't have templates. We're in all-ruby land and the implementation resides in the `#call` method.
21
+
22
+ ```ruby
23
+ # app/components/hello_world_component.rb
24
+ class HelloWorldComponent < Prawn::Widget
25
+ def call
26
+ pdf.text 'Hello World!'
27
+ end
28
+ end
29
+ ```
30
+
31
+ To render a component into an existing PDF, use the `#render_in` method:
32
+
33
+ ```ruby
34
+ # app/models/generate_some_pdf.rb
35
+ pdf = Prawn::Document.new
36
+
37
+ HelloWorldComponent.new.render_in(pdf)
38
+ ```
39
+
40
+ You can use `renders_one` and `renders_many` to use subcomponents.
41
+ In fact, when using your component with a block, you must at least use `renders_one` to pass in your content.
42
+
43
+ Slots are set with `with_*` methods (e.g. `box.with_title`, `blog.with_article`), matching the current `view_component` API.
44
+
45
+ ```ruby
46
+ # app/components/box_component.rb
47
+ class BoxComponent < Prawn::Widget
48
+ renders_one :title, TitleComponent
49
+ renders_one :description
50
+ renders_many :comments
51
+
52
+ def call
53
+ pdf.text 'This is a box'
54
+ title.draw # In Rails you would simply use `#to_s` but we use `#draw`.
55
+ description.draw
56
+ comments.each(&:draw)
57
+ end
58
+ end
59
+
60
+ # app/components/title_component.rb
61
+ class TitleComponent < Prawn::Widget
62
+ renders_one :content
63
+
64
+ def call
65
+ pdf.font_size 14
66
+ content.draw
67
+ end
68
+ end
69
+ ```
70
+
71
+ And then render the component:
72
+
73
+ ```ruby
74
+ # app/models/generate_some_pdf.rb
75
+ pdf = Prawn::Document.new
76
+
77
+ BoxComponent.new.render_in(pdf) do |box|
78
+ box.with_title do
79
+ pdf.text 'I am the title'
80
+ end
81
+
82
+ box.with_description do
83
+ pdf.text 'I am the description'
84
+ end
85
+
86
+ box.with_comment do
87
+ pdf.text 'First comment'
88
+ end
89
+
90
+ box.with_comment do
91
+ pdf.text 'Second comment'
92
+ end
93
+ end
94
+ ```
95
+
96
+ You can define params and options like with the [calls](https://github.com/halo/calls) gem (built on [dry-initializer](https://dry-rb.org/gems/dry-initializer)).
97
+
98
+ ```ruby
99
+ # app/components/title_component.rb
100
+ class SayItComponent < Prawn::Widget
101
+ option :message
102
+
103
+ def call
104
+ pdf.text message
105
+ end
106
+ end
107
+ ```
108
+
109
+ And call it like so:
110
+
111
+ ```ruby
112
+ # app/models/generate_some_pdf.rb
113
+ pdf = Prawn::Document.new
114
+
115
+ SayItComponent.new(message: 'Hello!').render_in(pdf) do |box|
116
+ ```
117
+
118
+ Of course you could render a component inside of another component:
119
+
120
+ ```ruby
121
+ # app/components/blog_component.rb
122
+ class BlogComponent < Prawn::Widget
123
+ renders_many :articles, ArticleComponent
124
+
125
+ def call
126
+ pdf.push 'Welcome to my blog'
127
+ articles.each(&:draw)
128
+ end
129
+ end
130
+
131
+ # app/components/article_component.rb
132
+ class ArticleComponent < Prawn::Widget
133
+ renders_one :title
134
+ renders_one :body
135
+
136
+ def call
137
+ TitleComponent.new.render_in(pdf) do |title|
138
+ title.with_content do
139
+ title.draw
140
+ end
141
+ end
142
+
143
+ body.draw
144
+ end
145
+ end
146
+ ```
147
+
148
+ And render it:
149
+
150
+ ```ruby
151
+ # app/models/generate_some_pdf.rb
152
+ pdf = Prawn::Document.new
153
+ @comments = load_some_comments!
154
+
155
+ BlogComponent.new.render_in(pdf) do |blog|
156
+ blog.with_article do |article|
157
+ article.with_title do
158
+ pdf.text 'Breaking news'
159
+ end
160
+
161
+ article.with_body do
162
+ pdf.text 'The weather is good.'
163
+ end
164
+ end
165
+ end
166
+ ```
167
+
168
+ ## Caveats
169
+
170
+ Rendering a Rails view is pretty simple compared to a PDF.
171
+ Because you simply pre-generate an HTML String that you can wrap or concatenate.
172
+
173
+ In Prawn, the "view" is a living PDF document and you cannot pre-generate any content.
174
+
175
+ That means, we cannot use wrappers like this:
176
+
177
+ ```ruby
178
+ # Would be nice but does NOT work.
179
+ ButtonComponent.new.render_in(pdf) do
180
+ pdf.text 'I am a button'
181
+ end
182
+ ```
183
+
184
+ Instead we're forced to use this:
185
+
186
+ ```ruby
187
+ # Cumbersome, but it has its advantages.
188
+ ButtonComponent.new.render_in(pdf) do |button|
189
+ button.with_title do
190
+ pdf.text 'I am a button'
191
+ end
192
+ end
193
+ ```
194
+
195
+ The technical reason behind this is this:
196
+
197
+ ```ruby
198
+ # This causes a problem for the block/yield mechanism.
199
+ BoxComponent.new.render_in(pdf) do |box|
200
+ box.with_title do
201
+ pdf.text 'I am the title'
202
+ end
203
+
204
+ pdf.text 'I am the description'
205
+ end
206
+ ```
207
+
208
+ In this example, the box title is first properly set-up when the entire block is exectued. But executing that block already modifies the pdf in-place (with the description). Which makes this uninituitive (in Rails you would just capture the output of the description block and keep it for later use, that's not possible in a PDF).
209
+
210
+ So you have to use either or: blocks never have arguments or always (which we chose here for this gem).
211
+
212
+ ## History
213
+
214
+ When it comes to "resusable components", it's really hard to find the balance between too much opinion and too much flexibility.
215
+
216
+ For Prawn it might look like
217
+ [this](https://github.com/kaspermeyer/canned_tuna/blob/ea4e05a4ff7b10cd73c3bb3246173a9f0f749b40/example/outlets.rb#L26-L28)
218
+ or like
219
+ [this](https://github.com/prawnpdf/prawn-component/blob/af0c1e6c9fcac7d036c024a53e18dfe563eb50e3/example/simple.rb#L3)
220
+ or
221
+ [this](https://github.com/neume/sugpoko/blob/1e81c069f6a6cb58431866b1090667d5b8d783ad/README.md#usage).
222
+ For Rails you might come up with something like
223
+ [this](https://github.com/github/view_component/blob/0afe05da0c3ea5ce99dc431447bcb61359bc6e09/docs/content_areas.md)
224
+ but that's not good enough, so let's use
225
+ [this](https://github.com/github/view_component/blob/0afe05da0c3ea5ce99dc431447bcb61359bc6e09/docs/slots_v1.md)
226
+ and after years of iterations, we finally landed
227
+ [here](https://viewcomponent.org/guide/slots.html).
228
+
229
+ So, now that that API is somewhat stable, I felt it was time to use it with Prawn.
230
+
231
+ ## Copyright
232
+
233
+ MIT 2021 halo, `SPDX-License-Identifier: MIT`.
234
+ See [MIT-LICENSE](http://github.com/halo/prawn-component/blob/master/LICENSE.md).
@@ -0,0 +1,184 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-License-Identifier: MIT
4
+ module Prawn
5
+ module Components
6
+ # Adaptation of https://github.com/ViewComponent/view_component/blob/main/lib/view_component/slotable.rb
7
+ # But without action view and caching.
8
+ # ViewComponent adaptation, MIT (c) 2019 GitHub.
9
+ class Base
10
+ include ::Calls
11
+
12
+ # Components are instantiated with `.new`, not `.call`.
13
+ # The `calls` gem makes `.new` private.
14
+ # We make `.new` public again so components render via `Component.new.render_in(pdf)`.
15
+ public_class_method :new
16
+
17
+ class_attribute :registered_slots
18
+ self.registered_slots = {}
19
+
20
+ def self.renders_one(slot_name, callable = nil)
21
+ define_method(:"with_#{slot_name}") do |*args, **kwargs, &block|
22
+ set_slot(slot_name, *args, **kwargs, &block)
23
+ end
24
+
25
+ define_method(slot_name) do
26
+ get_slot(slot_name)
27
+ end
28
+
29
+ register_slot(slot_name, collection: false, callable:)
30
+ end
31
+
32
+ def self.renders_many(slot_name, callable = nil)
33
+ singular_name = ActiveSupport::Inflector.singularize(slot_name)
34
+
35
+ # Define setter for singular names
36
+ # e.g. `renders_many :items` allows fetching all tabs with
37
+ # `component.tabs` and setting a tab with `component.with_tab`
38
+ define_method(:"with_#{singular_name}") do |*args, **kwargs, &block|
39
+ set_slot(slot_name, *args, **kwargs, &block)
40
+ end
41
+
42
+ # Instantiates and and adds multiple slots forwarding the first
43
+ # argument to each slot constructor
44
+ define_method(:"with_#{slot_name}") do |collection_args = nil, &block|
45
+ set_many_slots(slot_name, collection_args, &block)
46
+ end
47
+
48
+ define_method(slot_name) do
49
+ get_slot(slot_name)
50
+ end
51
+
52
+ register_slot(slot_name, collection: true, callable:)
53
+ end
54
+
55
+ # Clone slot configuration into child class
56
+ # see #test_slots_pollution
57
+ def self.inherited(child)
58
+ child.registered_slots = registered_slots.clone
59
+ super
60
+ end
61
+
62
+ # PRIVATE
63
+
64
+ def self.register_slot(slot_name, collection:, callable:)
65
+ # Setup basic slot data
66
+ slot = { collection: }
67
+ # If callable responds to `render_in`, we set it on the slot as a renderable
68
+ if callable.respond_to?(:method_defined?) && callable.method_defined?(:render_in)
69
+ slot[:renderable] = callable
70
+
71
+ elsif callable
72
+ # If slot does not respond to `render_in`, we assume it's a proc,
73
+ # define a method, and save a reference to it to call when setting
74
+ method_name = :"_call_#{slot_name}"
75
+ define_method method_name, &callable
76
+ slot[:renderable_function] = instance_method(method_name)
77
+ end
78
+
79
+ # Register the slot on the component
80
+ registered_slots[slot_name] = slot
81
+ end
82
+ private_class_method :register_slot
83
+
84
+ def set_slot(slot_name, *, **, &block)
85
+ slot_definition = self.class.registered_slots[slot_name]
86
+
87
+ slot = Slot.new(self)
88
+
89
+ # Passing the block to the sub-component wrapper like this has two
90
+ # benefits:
91
+ #
92
+ # 1. If this is a `content_area` style sub-component, we will render the
93
+ # block via the `slot`
94
+ #
95
+ # 2. Since we have to pass block content to components when calling
96
+ # `render`, evaluating the block here would require us to call
97
+ # `view_context.capture` twice, which is slower
98
+ slot._content_block = block if block_given?
99
+
100
+ build_slot_component(slot_definition, slot, *, **, &block)
101
+
102
+ @_set_slots ||= {}
103
+
104
+ if slot_definition[:collection]
105
+ @_set_slots[slot_name] ||= []
106
+ @_set_slots[slot_name].push(slot)
107
+ else
108
+ @_set_slots[slot_name] = slot
109
+ end
110
+
111
+ slot
112
+ end
113
+
114
+ # Creates the renderable for a slot, if the slot declares one.
115
+ # Plain slots without a callable only carry the content block.
116
+ def build_slot_component(slot_definition, slot, *, **, &)
117
+ if slot_definition[:renderable]
118
+ # If class
119
+ slot._component_instance = slot_definition[:renderable].new(*, **)
120
+
121
+ elsif slot_definition[:renderable_function]
122
+ # If passed a lambda
123
+ # Use `bind(self)` to ensure lambda is executed in the context of the
124
+ # current component. This is necessary to allow the lambda to access helper
125
+ # methods like `content_tag` as well as parent component state.
126
+ renderable_value = slot_definition[:renderable_function].bind(self).call(*, **, &)
127
+
128
+ # Function calls can return components, so if it's a component handle it specially
129
+ slot._component_instance = renderable_value if renderable_value.respond_to?(:render_in)
130
+ end
131
+ end
132
+
133
+ def get_slot(slot_name)
134
+ @_set_slots ||= {}
135
+
136
+ # Unset slots read as empty, so getters never return stale state.
137
+ # Collections read as an empty list, single slots read as nil.
138
+ @_set_slots.fetch(slot_name) do
139
+ self.class.registered_slots[slot_name][:collection] ? [] : nil
140
+ end
141
+ end
142
+
143
+ def render_in(pdf)
144
+ @pdf = pdf
145
+
146
+ # We have to yield eventually, because otherwise the components' block would not be executed.
147
+ # Also, we have to yield before trying to draw subcomponents (because they are set up by executing the block).
148
+ # It's unintuitive to leave that up to the developer to figure out in all their components.
149
+ # So, we keep things simple and always yield right away, so everything is set up properly.
150
+ # The downside is that this forces `renders_one` subcomponents instead of simply `yield` to render the block.
151
+ yield self if block_given?
152
+
153
+ call if render?
154
+ end
155
+
156
+ # However, we also provide this custom method to have the component handle the `yield` itself.
157
+ def call_in(pdf, &)
158
+ @pdf = pdf
159
+
160
+ call(&) if render?
161
+ end
162
+
163
+ private
164
+
165
+ # Adds one slot per entry, forwarding each entry to the slot constructor.
166
+ def set_many_slots(slot_name, collection_args, &)
167
+ collection_args.map do |collection_item_args|
168
+ if collection_item_args.respond_to?(:to_hash)
169
+ set_slot(slot_name, **collection_item_args, &)
170
+ else
171
+ set_slot(slot_name, *collection_item_args, &)
172
+ end
173
+ end
174
+ end
175
+
176
+ attr_reader :pdf
177
+
178
+ # Override this with logic in your component.
179
+ def render?
180
+ true
181
+ end
182
+ end
183
+ end
184
+ end
@@ -0,0 +1,39 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-License-Identifier: MIT
4
+ module Prawn
5
+ module Components
6
+ # Adaptation of https://github.com/ViewComponent/view_component/blob/main/lib/view_component/slot.rb
7
+ # But without string capturing.
8
+ # ViewComponent adaptation, MIT (c) 2019 GitHub.
9
+ class Slot
10
+ attr_writer :_component_instance, :_content_block
11
+
12
+ def initialize(parent)
13
+ @parent = parent
14
+ end
15
+
16
+ # This is what `to_s` is in the view_component gem.
17
+ # It renders the content into the view context (that is, the PDF)
18
+ def draw
19
+ pdf = @parent.send(:pdf)
20
+
21
+ if defined?(@_component_instance)
22
+ @_component_instance.render_in(pdf, &@_content_block)
23
+
24
+ elsif defined?(@_content_block)
25
+ @_content_block.call
26
+ end
27
+ end
28
+
29
+ # Give a component access to its slot instances through this wrapper.
30
+ def method_missing(symbol, *, &)
31
+ @_component_instance.public_send(symbol, *, &)
32
+ end
33
+
34
+ def respond_to_missing?(symbol, include_all = false)
35
+ defined?(@_component_instance) && @_component_instance.respond_to?(symbol, include_all)
36
+ end
37
+ end
38
+ end
39
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-License-Identifier: MIT
4
+ module Prawn
5
+ module Components
6
+ module VERSION # :nodoc:
7
+ MAJOR = 2
8
+ MINOR = 0
9
+ TINY = 0
10
+ PRE = nil
11
+
12
+ STRING = [MAJOR, MINOR, TINY, PRE].compact.join '.'
13
+ end
14
+ end
15
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-License-Identifier: MIT
4
+ require 'calls'
5
+ require 'active_support/core_ext/class/attribute'
6
+ require 'active_support/inflector/methods'
7
+
8
+ require 'prawn/components/version'
9
+ require 'prawn/components/base'
10
+ require 'prawn/components/slot'
11
+
12
+ module Prawn
13
+ class Widget < ::Prawn::Components::Base
14
+ end
15
+ end
metadata ADDED
@@ -0,0 +1,74 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: prawn-widget
3
+ version: !ruby/object:Gem::Version
4
+ version: 2.0.0
5
+ platform: ruby
6
+ authors:
7
+ - halo
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: activesupport
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: '0'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - ">="
24
+ - !ruby/object:Gem::Version
25
+ version: '0'
26
+ - !ruby/object:Gem::Dependency
27
+ name: calls
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '0'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ version: '0'
40
+ description: The gem `view_component` syntax, but implemented for Prawn. So you can
41
+ create reusable components.
42
+ executables: []
43
+ extensions: []
44
+ extra_rdoc_files: []
45
+ files:
46
+ - CHANGELOG.md
47
+ - README.md
48
+ - lib/prawn/components/base.rb
49
+ - lib/prawn/components/slot.rb
50
+ - lib/prawn/components/version.rb
51
+ - lib/prawn/widget.rb
52
+ homepage: https://github.com/halo/prawn-component
53
+ licenses:
54
+ - MIT
55
+ metadata:
56
+ rubygems_mfa_required: 'true'
57
+ rdoc_options: []
58
+ require_paths:
59
+ - lib
60
+ required_ruby_version: !ruby/object:Gem::Requirement
61
+ requirements:
62
+ - - ">="
63
+ - !ruby/object:Gem::Version
64
+ version: '4.0'
65
+ required_rubygems_version: !ruby/object:Gem::Requirement
66
+ requirements:
67
+ - - ">="
68
+ - !ruby/object:Gem::Version
69
+ version: '0'
70
+ requirements: []
71
+ rubygems_version: 4.0.24
72
+ specification_version: 4
73
+ summary: The gem `view_component` syntax, but implemented for Prawn.
74
+ test_files: []