prawn-widget 2.0.0 → 2.0.1

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3e30e986197cab5c5b408c2ea6f426c012831f32806f76a5ce29ba1fc72c7b7e
4
- data.tar.gz: 6d6497d4a4d7a3640e6e6e69242caf95b22b1efc2e6484fff5352d472317bdb3
3
+ metadata.gz: 0cb69d6d12a27421d143b41973acd524d49f966f60eccd4457697c4eb5ccd23d
4
+ data.tar.gz: c1f107425d1bc8dc8497367425c2e692b12ec323ddbaeea8583b8193ecde652f
5
5
  SHA512:
6
- metadata.gz: 7dc791c749cdaad519051180fe073e0d67947c5439c9c0b26c50952390ad006d354744488a0f94543c29e60f13e32c8539116dca771267769f13b1aabcc2b94c
7
- data.tar.gz: 91afbb699dff5adbf91a7e537494bfcecc3c9e946ae83b35e8aef2e22f79a1ffdf18a8dc206b87b58b244175a28ca993593bd9aeef106a9ea96a75b0f6c89f73
6
+ metadata.gz: 334abb81bcae2162bb4d4828ab5fa8f1a47aa178bf7bb2830d7f3498965033a6737ee1a632b8a745b1e8453a420b4d4b119814bd6622d12cef877f7a76848313
7
+ data.tar.gz: d4247404a59dc4e8e4d2c0b510bdf24c6d517e37ef4a12a8e6aef690d6f5ea73399283968cdaa8f3f12b086b4977de378324ccd17d0f4a8124af92fc57042670
data/CHANGELOG.md CHANGED
@@ -1,13 +1,15 @@
1
1
  # Changelog
2
2
 
3
- ## 2.0.0 (unreleased)
3
+ ## 2.0.1
4
4
 
5
5
  Modernization on the road to `prawn-widget`.
6
6
 
7
7
  ### Renamed
8
8
 
9
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`.
10
+ - The Ruby API is unchanged: widgets still inherit from `Prawn::Widget`.
11
+ - Internal namespace renamed `Prawn::Components` to `Prawn::Widgets` (no alias).
12
+ - Default require file added, so `gem 'prawn-widget'` works without `require: 'prawn/widget'`.
11
13
 
12
14
  ### Changed
13
15
 
@@ -16,7 +18,7 @@ Modernization on the road to `prawn-widget`.
16
18
 
17
19
  ### Removed
18
20
 
19
- - String callables (`renders_one :x, "SomeClass"`) are gone; use a component class or a lambda.
21
+ - String callables (`renders_one :x, "SomeClass"`) are gone; use a widget class or a lambda.
20
22
 
21
23
  ### Tooling
22
24
 
data/README.md CHANGED
@@ -1,11 +1,11 @@
1
- [![License](http://img.shields.io/badge/license-MIT-blue.svg)](http://github.com/halo/prawn-component/blob/master/LICENSE.md)
1
+ [![License](http://img.shields.io/badge/license-MIT-blue.svg)](http://github.com/halo/prawn-widget/blob/master/LICENSE.md)
2
2
 
3
3
  > [!NOTE]
4
4
  > **Looking for the old API?** Pin the legacy gem:
5
5
  > ```ruby
6
6
  > gem 'prawn-component', github: 'halo/prawn-component', tag: 'v1.0.0'
7
7
  > ```
8
- > **New here?** Use the renamed gem from RubyGems:
8
+ > **New here?** Use the renamed gem from RubyGems (no `require` option needed):
9
9
  > ```ruby
10
10
  > gem 'prawn-widget'
11
11
  > ```
@@ -16,36 +16,36 @@ This is an implementation of the popular [view_component](https://viewcomponent.
16
16
 
17
17
  ## Usage
18
18
 
19
- You define a component just like you would using the `view_component` gem. The only difference, of course, is that you
19
+ You define a widget just like you would using the `view_component` gem. The only difference, of course, is that you
20
20
  don't have templates. We're in all-ruby land and the implementation resides in the `#call` method.
21
21
 
22
22
  ```ruby
23
- # app/components/hello_world_component.rb
24
- class HelloWorldComponent < Prawn::Widget
23
+ # app/widgets/hello_world_widget.rb
24
+ class HelloWorldWidget < Prawn::Widget
25
25
  def call
26
26
  pdf.text 'Hello World!'
27
27
  end
28
28
  end
29
29
  ```
30
30
 
31
- To render a component into an existing PDF, use the `#render_in` method:
31
+ To render a widget into an existing PDF, use the `#render_in` method:
32
32
 
33
33
  ```ruby
34
34
  # app/models/generate_some_pdf.rb
35
35
  pdf = Prawn::Document.new
36
36
 
37
- HelloWorldComponent.new.render_in(pdf)
37
+ HelloWorldWidget.new.render_in(pdf)
38
38
  ```
39
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.
40
+ You can use `renders_one` and `renders_many` to use subwidgets.
41
+ In fact, when using your widget with a block, you must at least use `renders_one` to pass in your content.
42
42
 
43
43
  Slots are set with `with_*` methods (e.g. `box.with_title`, `blog.with_article`), matching the current `view_component` API.
44
44
 
45
45
  ```ruby
46
- # app/components/box_component.rb
47
- class BoxComponent < Prawn::Widget
48
- renders_one :title, TitleComponent
46
+ # app/widgets/box_widget.rb
47
+ class BoxWidget < Prawn::Widget
48
+ renders_one :title, TitleWidget
49
49
  renders_one :description
50
50
  renders_many :comments
51
51
 
@@ -57,8 +57,8 @@ class BoxComponent < Prawn::Widget
57
57
  end
58
58
  end
59
59
 
60
- # app/components/title_component.rb
61
- class TitleComponent < Prawn::Widget
60
+ # app/widgets/title_widget.rb
61
+ class TitleWidget < Prawn::Widget
62
62
  renders_one :content
63
63
 
64
64
  def call
@@ -68,13 +68,13 @@ class TitleComponent < Prawn::Widget
68
68
  end
69
69
  ```
70
70
 
71
- And then render the component:
71
+ And then render the widget:
72
72
 
73
73
  ```ruby
74
74
  # app/models/generate_some_pdf.rb
75
75
  pdf = Prawn::Document.new
76
76
 
77
- BoxComponent.new.render_in(pdf) do |box|
77
+ BoxWidget.new.render_in(pdf) do |box|
78
78
  box.with_title do
79
79
  pdf.text 'I am the title'
80
80
  end
@@ -96,8 +96,8 @@ end
96
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
97
 
98
98
  ```ruby
99
- # app/components/title_component.rb
100
- class SayItComponent < Prawn::Widget
99
+ # app/widgets/title_widget.rb
100
+ class SayItWidget < Prawn::Widget
101
101
  option :message
102
102
 
103
103
  def call
@@ -112,15 +112,15 @@ And call it like so:
112
112
  # app/models/generate_some_pdf.rb
113
113
  pdf = Prawn::Document.new
114
114
 
115
- SayItComponent.new(message: 'Hello!').render_in(pdf) do |box|
115
+ SayItWidget.new(message: 'Hello!').render_in(pdf) do |box|
116
116
  ```
117
117
 
118
- Of course you could render a component inside of another component:
118
+ Of course you could render a widget inside of another widget:
119
119
 
120
120
  ```ruby
121
- # app/components/blog_component.rb
122
- class BlogComponent < Prawn::Widget
123
- renders_many :articles, ArticleComponent
121
+ # app/widgets/blog_widget.rb
122
+ class BlogWidget < Prawn::Widget
123
+ renders_many :articles, ArticleWidget
124
124
 
125
125
  def call
126
126
  pdf.push 'Welcome to my blog'
@@ -128,13 +128,13 @@ class BlogComponent < Prawn::Widget
128
128
  end
129
129
  end
130
130
 
131
- # app/components/article_component.rb
132
- class ArticleComponent < Prawn::Widget
131
+ # app/widgets/article_widget.rb
132
+ class ArticleWidget < Prawn::Widget
133
133
  renders_one :title
134
134
  renders_one :body
135
135
 
136
136
  def call
137
- TitleComponent.new.render_in(pdf) do |title|
137
+ TitleWidget.new.render_in(pdf) do |title|
138
138
  title.with_content do
139
139
  title.draw
140
140
  end
@@ -152,7 +152,7 @@ And render it:
152
152
  pdf = Prawn::Document.new
153
153
  @comments = load_some_comments!
154
154
 
155
- BlogComponent.new.render_in(pdf) do |blog|
155
+ BlogWidget.new.render_in(pdf) do |blog|
156
156
  blog.with_article do |article|
157
157
  article.with_title do
158
158
  pdf.text 'Breaking news'
@@ -176,7 +176,7 @@ That means, we cannot use wrappers like this:
176
176
 
177
177
  ```ruby
178
178
  # Would be nice but does NOT work.
179
- ButtonComponent.new.render_in(pdf) do
179
+ ButtonWidget.new.render_in(pdf) do
180
180
  pdf.text 'I am a button'
181
181
  end
182
182
  ```
@@ -185,7 +185,7 @@ Instead we're forced to use this:
185
185
 
186
186
  ```ruby
187
187
  # Cumbersome, but it has its advantages.
188
- ButtonComponent.new.render_in(pdf) do |button|
188
+ ButtonWidget.new.render_in(pdf) do |button|
189
189
  button.with_title do
190
190
  pdf.text 'I am a button'
191
191
  end
@@ -196,7 +196,7 @@ The technical reason behind this is this:
196
196
 
197
197
  ```ruby
198
198
  # This causes a problem for the block/yield mechanism.
199
- BoxComponent.new.render_in(pdf) do |box|
199
+ BoxWidget.new.render_in(pdf) do |box|
200
200
  box.with_title do
201
201
  pdf.text 'I am the title'
202
202
  end
@@ -211,14 +211,14 @@ So you have to use either or: blocks never have arguments or always (which we ch
211
211
 
212
212
  ## History
213
213
 
214
- When it comes to "resusable components", it's really hard to find the balance between too much opinion and too much flexibility.
214
+ When it comes to "reusable widgets", it's really hard to find the balance between too much opinion and too much flexibility.
215
215
 
216
216
  For Prawn it might look like
217
- [this](https://github.com/kaspermeyer/canned_tuna/blob/ea4e05a4ff7b10cd73c3bb3246173a9f0f749b40/example/outlets.rb#L26-L28)
217
+ [this](https://github.com/kaspermeyer/canned_tuna/blob/ea4e05a4ff7b10cd73c3a4173a9f0f749b40/example/outlets.rb#L26-L28)
218
218
  or like
219
219
  [this](https://github.com/prawnpdf/prawn-component/blob/af0c1e6c9fcac7d036c024a53e18dfe563eb50e3/example/simple.rb#L3)
220
220
  or
221
- [this](https://github.com/neume/sugpoko/blob/1e81c069f6a6cb58431866b1090667d5b8d783ad/README.md#usage).
221
+ [this](https://github.com/neume/sugpoko/blob/1e81c069f6a6cb58431866b10962783ad49d8b3ac/README.md#usage).
222
222
  For Rails you might come up with something like
223
223
  [this](https://github.com/github/view_component/blob/0afe05da0c3ea5ce99dc431447bcb61359bc6e09/docs/content_areas.md)
224
224
  but that's not good enough, so let's use
@@ -231,4 +231,4 @@ So, now that that API is somewhat stable, I felt it was time to use it with Praw
231
231
  ## Copyright
232
232
 
233
233
  MIT 2021 halo, `SPDX-License-Identifier: MIT`.
234
- See [MIT-LICENSE](http://github.com/halo/prawn-component/blob/master/LICENSE.md).
234
+ See [MIT-LICENSE](http://github.com/halo/prawn-widget/blob/master/LICENSE.md).
data/lib/prawn/widget.rb CHANGED
@@ -5,11 +5,11 @@ require 'calls'
5
5
  require 'active_support/core_ext/class/attribute'
6
6
  require 'active_support/inflector/methods'
7
7
 
8
- require 'prawn/components/version'
9
- require 'prawn/components/base'
10
- require 'prawn/components/slot'
8
+ require 'prawn/widgets/version'
9
+ require 'prawn/widgets/base'
10
+ require 'prawn/widgets/slot'
11
11
 
12
12
  module Prawn
13
- class Widget < ::Prawn::Components::Base
13
+ class Widget < ::Prawn::Widgets::Base
14
14
  end
15
15
  end
@@ -2,16 +2,16 @@
2
2
 
3
3
  # SPDX-License-Identifier: MIT
4
4
  module Prawn
5
- module Components
5
+ module Widgets
6
6
  # Adaptation of https://github.com/ViewComponent/view_component/blob/main/lib/view_component/slotable.rb
7
7
  # But without action view and caching.
8
8
  # ViewComponent adaptation, MIT (c) 2019 GitHub.
9
9
  class Base
10
10
  include ::Calls
11
11
 
12
- # Components are instantiated with `.new`, not `.call`.
12
+ # Widgets are instantiated with `.new`, not `.call`.
13
13
  # The `calls` gem makes `.new` private.
14
- # We make `.new` public again so components render via `Component.new.render_in(pdf)`.
14
+ # We make `.new` public again so widgets render via `Widget.new.render_in(pdf)`.
15
15
  public_class_method :new
16
16
 
17
17
  class_attribute :registered_slots
@@ -34,7 +34,7 @@ module Prawn
34
34
 
35
35
  # Define setter for singular names
36
36
  # e.g. `renders_many :items` allows fetching all tabs with
37
- # `component.tabs` and setting a tab with `component.with_tab`
37
+ # `widget.tabs` and setting a tab with `widget.with_tab`
38
38
  define_method(:"with_#{singular_name}") do |*args, **kwargs, &block|
39
39
  set_slot(slot_name, *args, **kwargs, &block)
40
40
  end
@@ -76,7 +76,7 @@ module Prawn
76
76
  slot[:renderable_function] = instance_method(method_name)
77
77
  end
78
78
 
79
- # Register the slot on the component
79
+ # Register the slot on the widget
80
80
  registered_slots[slot_name] = slot
81
81
  end
82
82
  private_class_method :register_slot
@@ -86,18 +86,18 @@ module Prawn
86
86
 
87
87
  slot = Slot.new(self)
88
88
 
89
- # Passing the block to the sub-component wrapper like this has two
89
+ # Passing the block to the sub-widget wrapper like this has two
90
90
  # benefits:
91
91
  #
92
- # 1. If this is a `content_area` style sub-component, we will render the
92
+ # 1. If this is a `content_area` style sub-widget, we will render the
93
93
  # block via the `slot`
94
94
  #
95
- # 2. Since we have to pass block content to components when calling
95
+ # 2. Since we have to pass block content to widgets when calling
96
96
  # `render`, evaluating the block here would require us to call
97
97
  # `view_context.capture` twice, which is slower
98
98
  slot._content_block = block if block_given?
99
99
 
100
- build_slot_component(slot_definition, slot, *, **, &block)
100
+ build_slot_widget(slot_definition, slot, *, **, &block)
101
101
 
102
102
  @_set_slots ||= {}
103
103
 
@@ -113,20 +113,20 @@ module Prawn
113
113
 
114
114
  # Creates the renderable for a slot, if the slot declares one.
115
115
  # Plain slots without a callable only carry the content block.
116
- def build_slot_component(slot_definition, slot, *, **, &)
116
+ def build_slot_widget(slot_definition, slot, *, **, &)
117
117
  if slot_definition[:renderable]
118
118
  # If class
119
- slot._component_instance = slot_definition[:renderable].new(*, **)
119
+ slot._widget_instance = slot_definition[:renderable].new(*, **)
120
120
 
121
121
  elsif slot_definition[:renderable_function]
122
122
  # If passed a lambda
123
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.
124
+ # current widget. This is necessary to allow the lambda to access helper
125
+ # methods like `content_tag` as well as parent widget state.
126
126
  renderable_value = slot_definition[:renderable_function].bind(self).call(*, **, &)
127
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)
128
+ # Function calls can return widgets, so if it's a widget handle it specially
129
+ slot._widget_instance = renderable_value if renderable_value.respond_to?(:render_in)
130
130
  end
131
131
  end
132
132
 
@@ -143,17 +143,17 @@ module Prawn
143
143
  def render_in(pdf)
144
144
  @pdf = pdf
145
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.
146
+ # We have to yield eventually, because otherwise the widgets' block would not be executed.
147
+ # Also, we have to yield before trying to draw subwidgets (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 widgets.
149
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.
150
+ # The downside is that this forces `renders_one` subwidgets instead of simply `yield` to render the block.
151
151
  yield self if block_given?
152
152
 
153
153
  call if render?
154
154
  end
155
155
 
156
- # However, we also provide this custom method to have the component handle the `yield` itself.
156
+ # However, we also provide this custom method to have the widget handle the `yield` itself.
157
157
  def call_in(pdf, &)
158
158
  @pdf = pdf
159
159
 
@@ -175,7 +175,7 @@ module Prawn
175
175
 
176
176
  attr_reader :pdf
177
177
 
178
- # Override this with logic in your component.
178
+ # Override this with logic in your widget.
179
179
  def render?
180
180
  true
181
181
  end
@@ -2,12 +2,12 @@
2
2
 
3
3
  # SPDX-License-Identifier: MIT
4
4
  module Prawn
5
- module Components
5
+ module Widgets
6
6
  # Adaptation of https://github.com/ViewComponent/view_component/blob/main/lib/view_component/slot.rb
7
7
  # But without string capturing.
8
8
  # ViewComponent adaptation, MIT (c) 2019 GitHub.
9
9
  class Slot
10
- attr_writer :_component_instance, :_content_block
10
+ attr_writer :_widget_instance, :_content_block
11
11
 
12
12
  def initialize(parent)
13
13
  @parent = parent
@@ -18,21 +18,21 @@ module Prawn
18
18
  def draw
19
19
  pdf = @parent.send(:pdf)
20
20
 
21
- if defined?(@_component_instance)
22
- @_component_instance.render_in(pdf, &@_content_block)
21
+ if defined?(@_widget_instance)
22
+ @_widget_instance.render_in(pdf, &@_content_block)
23
23
 
24
24
  elsif defined?(@_content_block)
25
25
  @_content_block.call
26
26
  end
27
27
  end
28
28
 
29
- # Give a component access to its slot instances through this wrapper.
29
+ # Give a widget access to its slot instances through this wrapper.
30
30
  def method_missing(symbol, *, &)
31
- @_component_instance.public_send(symbol, *, &)
31
+ @_widget_instance.public_send(symbol, *, &)
32
32
  end
33
33
 
34
34
  def respond_to_missing?(symbol, include_all = false)
35
- defined?(@_component_instance) && @_component_instance.respond_to?(symbol, include_all)
35
+ defined?(@_widget_instance) && @_widget_instance.respond_to?(symbol, include_all)
36
36
  end
37
37
  end
38
38
  end
@@ -2,11 +2,11 @@
2
2
 
3
3
  # SPDX-License-Identifier: MIT
4
4
  module Prawn
5
- module Components
5
+ module Widgets
6
6
  module VERSION # :nodoc:
7
7
  MAJOR = 2
8
8
  MINOR = 0
9
- TINY = 0
9
+ TINY = 1
10
10
  PRE = nil
11
11
 
12
12
  STRING = [MAJOR, MINOR, TINY, PRE].compact.join '.'
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ # Default require file for the `prawn-widget` gem.
6
+ # This allows `gem 'prawn-widget'` in a Gemfile without `require: 'prawn/widget'`.
7
+ require 'prawn/widget'
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: prawn-widget
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.0
4
+ version: 2.0.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - halo
@@ -37,19 +37,20 @@ dependencies:
37
37
  - - ">="
38
38
  - !ruby/object:Gem::Version
39
39
  version: '0'
40
- description: The gem `view_component` syntax, but implemented for Prawn. So you can
41
- create reusable components.
40
+ description: The `view_component` syntax, but implemented for Prawn. So you can create
41
+ reusable widgets.
42
42
  executables: []
43
43
  extensions: []
44
44
  extra_rdoc_files: []
45
45
  files:
46
46
  - CHANGELOG.md
47
47
  - README.md
48
- - lib/prawn/components/base.rb
49
- - lib/prawn/components/slot.rb
50
- - lib/prawn/components/version.rb
48
+ - lib/prawn-widget.rb
51
49
  - lib/prawn/widget.rb
52
- homepage: https://github.com/halo/prawn-component
50
+ - lib/prawn/widgets/base.rb
51
+ - lib/prawn/widgets/slot.rb
52
+ - lib/prawn/widgets/version.rb
53
+ homepage: https://github.com/halo/prawn-widget
53
54
  licenses:
54
55
  - MIT
55
56
  metadata:
@@ -70,5 +71,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
70
71
  requirements: []
71
72
  rubygems_version: 4.0.24
72
73
  specification_version: 4
73
- summary: The gem `view_component` syntax, but implemented for Prawn.
74
+ summary: The `view_component` syntax, but implemented for Prawn.
74
75
  test_files: []