showcase-rails 0.4.0 → 0.4.1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 7bf404f8262fdae51c6ab3541595e310d63777b55f20125d41240565e77c147f
4
- data.tar.gz: 145c8eb4f5c2f90ae15946d277fd444d0c8c3c6cd3f18357daa004391ec3ecf7
3
+ metadata.gz: 0c5d33100bd6414501e65b9739978d060032490a480bcf17cac74b689c556605
4
+ data.tar.gz: ac2cf1b91db211cce86ad10ac4b9acc9dbfd5c19a7d4fdda17e853b3e81ebade
5
5
  SHA512:
6
- metadata.gz: a95d16e34f3e0c500356c38217a0e859e1963635c4b0ae14262c5d293c0c11e43063f2e6457b2a698b554351d847c8372885194edfd66c3885e2169978c404e1
7
- data.tar.gz: 2584d6cab57b362d6a685f0b2268f8dbe02135dac6919628780d9de1a5d21fd3a865aae08a67155f309638291b3d474c50017ec15530668721be77fd8960c75f
6
+ metadata.gz: 754d2bfcd10de161792834a56b470dc88652ac393429295d794e05b6c97b8da6a309af9aad284456742f34fde3faa6f7de50583f43f341178e2a0f22f13e314d
7
+ data.tar.gz: 2bb6891dd5236ce84728bb6c86db146de9724152f471b5e7f71fd1149941866572e9e2d5fd23e575e87019db5c62eb4597ef3807e28b3c20c33265cc896c479d
data/README.md CHANGED
@@ -38,7 +38,7 @@ Here's how to showcase a standard button component written with standard Rails p
38
38
 
39
39
  ### Components with ViewComponent
40
40
 
41
- If we take the `MessageComponent` as seen on [https://viewcomponent.org]():
41
+ If we take the `MessageComponent` as seen on [https://viewcomponent.org](https://viewcomponent.org):
42
42
 
43
43
  ```ruby
44
44
  # app/components/message_component.rb
@@ -168,9 +168,67 @@ We can then render it to showcase it:
168
168
 
169
169
  Note that by adding `events: "welcome:greeting"` we're listening for any time that event is dispatched. Events are logged with `console.log`, but also output alongside the sample in the browser.
170
170
 
171
- ## Syntax Highlighting
171
+ ## Installation
172
+
173
+ Add these lines to your application's Gemfile. See next section for why Showcase is in the test group.
174
+
175
+ ```ruby
176
+ group :development, :test do
177
+ gem "showcase-rails"
178
+ gem "rouge" # Optional. For out-of-the-box syntax highlighting.
179
+ end
180
+ ```
181
+
182
+ And then execute:
183
+
184
+ ```bash
185
+ $ bundle
186
+ ```
187
+
188
+ Or install it yourself as:
189
+ ```bash
190
+ $ gem install showcase-rails
191
+ ```
192
+
193
+ Then add the following in your `config/routes.rb` within the block passed to `Rails.application.routes.draw`:
194
+
195
+ ```ruby
196
+ mount Showcase::Engine, at: "/docs/showcase" if defined?(Showcase::Engine)
197
+ ```
198
+
199
+ ### Automatic previews testing
200
+
201
+ To have Showcase generate tests to exercise all your previews on CI, run `bin/rails showcase:install:previews_test` to add `test/views/showcase_test.rb`.
202
+
203
+ There you can add `setup` and `teardown` hooks, plus override the provided `assert_showcase_preview` to add custom assertions for any preview.
204
+
205
+ If you need custom assertions for specific previews, you can use the `test` helper:
206
+
207
+ ```ruby
208
+ # test/views/showcase_test.rb
209
+ require "test_helper"
210
+
211
+ class ShowcaseTest < Showcase::PreviewsTest
212
+ test showcase: "combobox" do
213
+ # This test block runs within the #combobox container element.
214
+ assert_text "This is a combobox, for sure."
215
+ end
216
+
217
+ test showcase: "button" do
218
+ assert_selector id: "basic" do
219
+ assert_button class: ["text-xs"]
220
+ end
221
+ end
172
222
 
173
- To have out of the box syntax highlighting, add `gem "rouge"` to your Gemfile and Showcase will set it up. Any denoted syntaxes in your samples are then highlighted, e.g.
223
+ test "some non-Showcase test" do
224
+ # You can still use the regular Rails `test` method too.
225
+ end
226
+ end
227
+ ```
228
+
229
+ ### Syntax Highlighting
230
+
231
+ Add `gem "rouge"` to your Gemfile and Showcase will set syntax highlighting up for you. Any denoted syntaxes in your samples are then highlighted, e.g.:
174
232
 
175
233
  ```erb
176
234
  # app/views/showcase/previews/_plain_ruby.ruby
@@ -179,102 +237,106 @@ To have out of the box syntax highlighting, add `gem "rouge"` to your Gemfile an
179
237
  <% end %>
180
238
  ```
181
239
 
182
- To change the default theme, look at [Loading your own syntax highlighting theme](#loading-your-own-syntax-highlighting-theme).
240
+ By default, `syntax: :erb` is used, so you don't need to mark the majority of your samples.
241
+
242
+ #### Replacing the highlighter
183
243
 
184
- To use a different syntax highlighter, you can assign your own Proc to `sample_renderer` like this:
244
+ To use a different syntax highlighter, assign your own Proc to `sample_renderer` like this:
185
245
 
186
246
  ```ruby
187
247
  # config/initializers/showcase.rb
188
- if defined?(Showcase)
189
- Showcase.sample_renderer = ->(source, syntax) do
190
- # Return a String of lexed and formatted code.
191
- end
248
+ return unless defined?(Showcase)
249
+
250
+ Showcase.sample_renderer = ->(source, syntax) do
251
+ # Return a String of lexed and formatted code.
192
252
  end
193
253
  ```
194
254
 
195
- ### Loading your own syntax highlighting theme
255
+ #### Replacing the theme
196
256
 
197
- By default, Showcase's syntax highlighting runs on Rouge's "github" theme.
257
+ By default, Showcase's syntax highlighting runs on Rouge's `"github"` theme.
198
258
 
199
- To use a different theme, override [showcase/engine/_stylesheets.html.erb][] with the following, replacing `:magritte` with a [valid theme](rouge-themes):
259
+ To use a different theme, override [showcase/engine/_stylesheets.html.erb](app/views/showcase/engine/_stylesheets.html.erb) with the following, replacing `:magritte` with a [valid theme](rouge-themes):
200
260
 
201
261
  ```erb
202
- <%= stylesheet_link_tag "showcase" %> # We've removed the default showcase.highlights file here.
262
+ <%= stylesheet_link_tag "showcase" %> <%# We've removed the default showcase.highlights file here. %>
203
263
  <%= tag.style Rouge::Theme.find(:magritte).render(scope: ".sc-highlight") %>
204
264
  ```
205
265
 
206
266
  [rouge-themes]: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
207
267
 
208
- ## Using options contexts
268
+ ## Taking Showcase further
209
269
 
210
- Showcase also supports custom options contexts. They're useful for cases where the options have a very specific format and it would be nice to keep them standardized.
270
+ ### View examples
211
271
 
212
- By default, Showcase ships Nice Partials and Stimulus contexts out of the box. See [lib/showcase.rb][] for how they're defined.
272
+ Clone the repository, run `bundle install`, then run `bin/rails server`, and visit localhost:3000 in your browser. You'll see the examples from [test/dummy/app/views/showcase/previews](test/dummy/app/views/showcase/previews).
213
273
 
214
- To add a new context, you can do this:
274
+ ### Configuring what trees to open
275
+
276
+ Showcase's sidebar mirrors your `app/views/showcase/previews` directory with their paths, and then trees at each directory level.
277
+
278
+ So a `showcase/previews` directory with `_top_level.html.erb`, `components/_button.html.erb`, `deeply/nested/_partial.html.erb`, will generate a sidebar like this:
279
+
280
+ - Previews
281
+ - Top Level
282
+ - Components
283
+ - Button
284
+ - Deeply
285
+ - Nested
286
+ - Partial
287
+
288
+ Internally, Showcase renders an open `details` element for each tree. You can control that with this:
215
289
 
216
290
  ```ruby
217
291
  # config/initializers/showcase.rb
218
292
  return unless defined?(Showcase)
219
293
 
220
- Showcase.options.define :some_context do
221
- def targets(name, ...)
222
- option("data-#{@prefix}-#{name}", ...)
223
- end
224
- end
294
+ Showcase.tree_opens = true # All trees are open (the default).
295
+ Showcase.tree_opens = false # All trees are closed.
296
+ Showcase.tree_opens = ->(tree) { tree.root? } # Only open the root level trees (Previews, Components, Deeply but not Nested).
297
+ Showcase.tree_opens = ->(tree) { tree.id.start_with? ".", "components" } # Just open the top-level tree and the components tree.
225
298
  ```
226
299
 
227
- And now we can use it, here passing in `prefix:` which becomes an instance variable available in the `define` block.
300
+ ### Linking to previews
301
+
302
+ Call `showcase.link_to` with the URL path to the other Showcase:
228
303
 
229
304
  ```erb
230
- <% showcase.options.context :some_context, prefix: "super-" do |o| %>
231
- <% o.required.targets :title %>
232
- <% end %>
305
+ <%= showcase.link_to "stimulus_controllers/welcome" %>
306
+ <%= showcase.link_to "components/button", id: "extra-large" %> <%# Pass an id to link to a specific sample %>
307
+
308
+ <%# You can also pass just an id: to target a sample on the current showcase %>
309
+ <%= showcase.link_to id: "extra-large" %>
233
310
  ```
234
311
 
235
- ## Automatic previews testing
312
+ ### Adding options contexts
236
313
 
237
- Showcase can automatically generate tests for all your Showcases to have it executed in your CI setup, run `bin/rails showcase:install:previews_test` to set this up.
314
+ Showcase also supports custom options contexts. They're useful for cases where the options have a very specific format and it would be nice to keep them standardized.
238
315
 
239
- You can then open `test/views/showcase_test.rb` and add your own `setup` and `teardown` hooks, as well as override the provided `assert_showcase_preview` to add custom assertions.
316
+ By default, Showcase ships Nice Partials and Stimulus contexts out of the box. See [lib/showcase.rb](lib/showcase.rb) for how they're defined.
240
317
 
241
- If you need custom assertions for specific previews and their samples, you can use the `test` helper:
318
+ To add a new context, you can do this:
242
319
 
243
320
  ```ruby
244
- # test/views/showcase_test.rb
245
- require "test_helper"
246
-
247
- class ShowcaseTest < Showcase::PreviewsTest
248
- test showcase: "combobox" do
249
- # This test block runs within the #combobox container element.
250
- assert_text "This is a combobox, for sure."
251
- end
252
-
253
- test showcase: "button" do
254
- assert_selector id: "basic" do
255
- assert_button class: ["text-xs"]
256
- end
257
- end
321
+ # config/initializers/showcase.rb
322
+ return unless defined?(Showcase)
258
323
 
259
- test "some non-Showcase test" do
260
- # You can still use the regular Rails `test` method too.
324
+ Showcase.options.define :some_context do
325
+ def targets(name, ...)
326
+ option("data-#{@prefix}-#{name}", ...)
261
327
  end
262
328
  end
263
329
  ```
264
330
 
265
- ## Linking to previews
266
-
267
- Call `showcase.link_to` with the URL path to the other Showcase:
331
+ And now we can use it, here passing in `prefix:` which becomes an instance variable available in the `define` block.
268
332
 
269
333
  ```erb
270
- <%= showcase.link_to "stimulus_controllers/welcome" %>
271
- <%= showcase.link_to "components/button", id: "extra-large" %> <%# Pass an id to link to a specific sample %>
272
-
273
- <%# You can also pass just an id: to target a sample on the current showcase %>
274
- <%= showcase.link_to id: "extra-large" %>
334
+ <% showcase.options.context :some_context, prefix: "super-" do |o| %>
335
+ <% o.required.targets :title %>
336
+ <% end %>
275
337
  ```
276
338
 
277
- ## Full Rails engine support
339
+ ### Full Rails engine support
278
340
 
279
341
  Any Rails engines in your app that ships previews in their `app/views/showcase/previews` directory will automatically be surfaced in your app. Here's an example from the [bullet_train-themes-light Rails engine](https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-themes-light/app/views/showcase/previews).
280
342
 
@@ -282,11 +344,7 @@ Showcase respects the Rails views rendering order, allowing you to override a sp
282
344
 
283
345
  _📖 How does this work? 📖_ Internally, Showcase leverages Rails controllers' ordered set of `view_paths` — which each engine automatically prepends their app/views directory to by calling something like [`ActionController::Base.prepend_view_path`](https://github.com/rails/rails/blob/e78ed07e008676752b2ed2cff97e74b31ffacaf5/railties/lib/rails/engine.rb#L606) when initializing.
284
346
 
285
- ## View examples
286
-
287
- Clone the repository, run `bundle install`, then run `bin/rails server`, visit localhost:3000 in your browser.
288
-
289
- ## Overriding Showcase's default rendering
347
+ ### Overriding Showcase's default rendering
290
348
 
291
349
  Showcase's rendering happens through two controllers:
292
350
 
@@ -330,36 +388,9 @@ partials, make sure to include `"showcase"` in your list of assets.
330
388
 
331
389
  [javascript_include_tag]: https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-javascript_include_tag
332
390
  [stylesheet_link_tag]: https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-stylesheet_link_tag
333
- [showcase/engine/_head.html.erb]: ./showcase/engine/_head.html.erb
334
- [showcase/engine/_javascripts.html.erb]: ./showcase/engine/_javascripts.html.erb
335
- [showcase/engine/_stylesheets.html.erb]: ./showcase/engine/_stylesheets.html.erb
336
-
337
- ## Installation
338
-
339
- Add this line to your application's Gemfile. To get the previews testing make sure the `showcase-rails` gem is available to your test environment:
340
-
341
- ```ruby
342
- group :development, :test do
343
- gem "showcase-rails"
344
- gem "rouge" # For syntax highlighting in Showcase.
345
- end
346
- ```
347
-
348
- And then execute:
349
- ```bash
350
- $ bundle
351
- ```
352
-
353
- Or install it yourself as:
354
- ```bash
355
- $ gem install showcase-rails
356
- ```
357
-
358
- Then add the following in your `config/routes.rb` within the block passed to `Rails.application.routes.draw`:
359
-
360
- ```ruby
361
- mount Showcase::Engine, at: "/docs/showcase" if defined?(Showcase::Engine)
362
- ```
391
+ [showcase/engine/_head.html.erb]: app/views/showcase/engine/_head.html.erb
392
+ [showcase/engine/_javascripts.html.erb]: app/views/showcase/engine/_javascripts.html.erb
393
+ [showcase/engine/_stylesheets.html.erb]: app/views/showcase/engine/_stylesheets.html.erb
363
394
 
364
395
  ## Contributing
365
396
  Contribution directions go here.
@@ -13,6 +13,10 @@ class Showcase::Path
13
13
  id == "." ? "Previews" : id
14
14
  end
15
15
 
16
+ def open?
17
+ Showcase.tree_opens.call(self)
18
+ end
19
+
16
20
  def ordered_children
17
21
  children.partition { !_1.is_a?(Tree) }.flatten
18
22
  end
@@ -1,4 +1,4 @@
1
- <details open class="sc-flex sc-flex-col <%= "sc-pl-4" unless tree.root? %>">
1
+ <%= tag.details open: tree.open?, class: ["sc-flex sc-flex-col", "sc-pl-4" => !tree.root?] do %>
2
2
  <%= tag.summary tree.name.titleize, class: "sc-list-item hover:sc-bg-indigo-50 dark:hover:sc-bg-neutral-700/50 sc-font-medium sc-text-base sc-py-2 sc-pl-4 sc-cursor-pointer" %>
3
3
  <%= render tree.ordered_children %>
4
- </details>
4
+ <% end %>
@@ -1,3 +1,3 @@
1
1
  module Showcase
2
- VERSION = "0.4.0"
2
+ VERSION = "0.4.1"
3
3
  end
data/lib/showcase.rb CHANGED
@@ -12,6 +12,17 @@ module Showcase
12
12
  autoload :RouteHelper, "showcase/route_helper"
13
13
  autoload :Options, "showcase/options"
14
14
 
15
+ class << self
16
+ attr_reader :tree_opens
17
+
18
+ def tree_opens=(opens)
19
+ @tree_opens = opens.respond_to?(:call) ? opens : proc { opens }
20
+ end
21
+ end
22
+ self.tree_opens = true # All open by default
23
+ # self.tree_opens = false # All closed by default
24
+ # self.tree_opens = ->(tree) { tree.root? } # Just keep the root-level trees open.
25
+
15
26
  singleton_class.attr_accessor :sample_renderer
16
27
  @sample_renderer = proc { _1 }
17
28
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: showcase-rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.0
4
+ version: 0.4.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Daniel Pence
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2023-03-28 00:00:00.000000000 Z
12
+ date: 2023-03-29 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: rails