view_spec 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db2b2ddc540389235a0c75db6bf93c85e65b854574623ea09b782e24d330d6ad
-  data.tar.gz: f7c9400e0487de9c32c2cd0fa345c4c29e6bdceae3143bdb310c0bd2568c0390
+  metadata.gz: b0f44c0f0dbadabf2479727d19e5744a33c1d3e029ae7a3ea2d2c2d0a47bfe9f
+  data.tar.gz: 4f78e8fd46c7780e7816358375a0d67ae46e18c7858e67dd1871d7db1349c51c
 SHA512:
-  metadata.gz: e8fe0a339f4f6e8b22c212f5f21d70c66bdedf8e1ffb1c56b03ce236025185a2b28a0cce1510fec59ceeab038550689016d998dce823af51d30b61d83c68f3f1
-  data.tar.gz: 6d720f348d61915a323f0217d30af8fa09cb633918a13d4480e65db52c1433dc37b552b5e3abc407eff994e464f5212e90a8d990389d34fb185fe0acea3ab315
+  metadata.gz: 46dab0defa019b13aa07e9ea04392f810b4673b3a79379bff869d32d3adfeb0a93bd3da59397b2c9c49e8a64eb2d89cfbfa7911cb94a4ae56d7f462460568137
+  data.tar.gz: 2a165392e7a6864738aa841f0926164ad4aa701f0bc9acaad3baaf89d9df33f9b3b995077382a9ca7804ebdf6aedae4a038419937496e430c4fc6995006dabeb

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021-present Mark Perkins
+Copyright (c) 2025-present Mark Perkins
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,51 +1,294 @@
-# ViewSpec  
+# ViewSpec
 
-ViewSpec lets you create example-led specifications for components, partials and views using an expressive Ruby DSL.
+<p><a href="https://rubygems.org/gems/view_spec"><img src="https://img.shields.io/gem/v/view_spec" alt="Gem version"></a>
+<a href="https://github.com/lookbook/view_spec/actions/workflows/ci.yml"><img src="https://github.com/lookbook/view_spec/actions/workflows/ci.yml/badge.svg" alt="CI status"></a></p>
 
-Specs can then be used in your tests, to render previews for development and visual testing or to generate documentation.
+ViewSpec helps you **develop**, **test** and **document** the view layer of your Rails app using **example-led specifications** written in an **expressive Ruby DSL**. Specs can be created for your app's **components**, **partials**, **helpers**, **views** and more.
+
+Each spec is made up of one or more **scenarios**, each of which represents a particular state or variant of the the subject of the spec. You can define a **preview**, add contextual **tests** and include **usage information** for each scenario.
+
+ViewSpec then handles generating **live preview endpoints** and **integrating the tests into your test suite**, and makes it easy to **generate developer documentation** from the specs you create.
+
+> [!IMPORTANT]
+> **ViewSpec is at a very early stage of development.** Bugs are very likely and breaking changes may happen without warning.
+> Please give it a try and share any thoughts, feedback or comments via issues/discussions but be aware that there will likely be significant changes to ViewSpec's functionality and API before a stable `v1.0` release candidate is reached.
+
+## ViewSpec files and DSL 
+
+ViewSpec spec files are written in Ruby and should be placed in the `test/view_specs` directory. Their filenames should end in `_vspec.rb` and can be organised in whatever subfolder struture is appropriate for your needs.
+
+ViewSpec specs are written in a bespoke Ruby DSL that should feel somewhat familiar if you have used [RSpec](https://github.com/rspec/rspec) before.
+
+Here's what an example spec file for a button component might look like:
 
 ```rb
-# button_vspec.rb
+# test/view_specs/button_vspec.rb
 
 ViewSpec.spec ButtonComponent do
-  title "Button (ViewComponent)"
-
   scenario "default" do
+    notes <<~MD
+      Default button with the `primary` theme.
+      _Appropriate for the majority of use-cases._
+    MD
+
     preview do
       render ButtonComponent.new(text: "Button text")
     end
+
+    tests do
+      test "it renders" do
+        render_preview
+        assert_selector("button")
+      end
+
+      test "it displays the label text" do
+        render_preview
+        assert_selector("button", text: "Button text")
+      end
+    end
   end
 
-  scenario "editable params" do
+  scenario "themes" do
+    title "Available Themes"
+
+    notes <<~MD
+      There are three button themes available for use:
+
+      * `:primary` (default)
+      * `:secondary` (use for less important actions)
+      * `:danger` (use for destructive actions)
+    MD
+    
+    preview <<~ERB
+      <%= render ButtonComponent.new(text: "Primary", theme: :primary) %>
+      <%= render ButtonComponent.new(text: "Secondary", theme: :secondary) %>
+      <%= render ButtonComponent.new(text: "Danger", theme: :danger) %>
+    ERB
+
+    tests do
+      test "it applies themes to the buttons" do
+        render_preview
+        assert_selector(%(button[data-theme="primary"]))
+        assert_selector(%(button[data-theme="secondary"]))
+        assert_selector(%(button[data-theme="danger"]))
+      end
+    end
+  end
+
+  scenario "playground" do
+    notes <<~MD
+      You can append query parameters to the preview URL to
+      set the button's `text`, `type` and `theme` properties.
+    MD
+
     param :text, :string, default: "Button text"
     param :type, :symbol, default: :button
+    param :theme, :symbol, default: :primary
 
     preview do
       render ButtonComponent.new(**params)
     end
   end
-  
-  scenario "buttons galore" do
-    preview <<~ERB
-      <%= render ButtonComponent.new(text: "Button 1") %>
-      <%= render ButtonComponent.new(text: "Button 2") %>
-      <%= render ButtonComponent.new(text: "Button 3") %>
-      <%= render ButtonComponent.new(text: "Button 4") %>
-    ERB
-  end
+end
+```
+
+> [!NOTE]
+> ViewSpec is completely agnostic to your choice of component framework (e.g. ViewComponent, Phlex, etc), templating language (ERB, HAML, etc) and test suite.
+> If you can use it with Rails you can use it with ViewSpec!
+
+## Workflow example
 
-  group "themes" do
-    scenario "primary" do
-      preview { render ButtonComponent.new(text: "Primary", theme: :primary) }
+Below is an outline of what a ViewSpec-based workflow for developing, testing and documenting a new `button` component might look like.
+
+The button component in this example will be implemented using a standard Rails/ActionView partial, but could equally be created using ViewComponent, Phlex, a view helper or even just vanilla HTML.
+
+We'll assume that the ViewSpec gem has already been installed and configured in the example app.
+
+### 1. Create the component
+
+First we create the basic `button` component partial in the `app/views/components` directory.
+
+```erb
+<%# locals: (text:, theme: :primary, type: :button) %>
+
+<%= button_tag(text, type: type, data: {theme: theme}, class: "button") %>
+```
+
+From the file above you can see that there are default values for the `theme` and `type` options. Only the button `text` argument is required to render the partial. 
+
+### 2. Add a spec file
+
+Now we'll start by creating a bare-bones button spec at `test/view_specs/button_vspec.rb` that includes a single scenario describing the default state of the button.
+
+```rb
+# test/view_specs/button_vspec.rb
+
+ViewSpec.spec "components/button" do
+  title "Basic button"
+
+  scenario "default" do
+    notes <<~MD
+      Default button with `primary` theme.
+      _Appropriate for the majority of use-cases._
+    MD
+
+    preview do
+      render "components/button", text: "Click here"
     end
+  end
+end
+```
+
+### 3. Inspect the preview
+
+The default button preview defined above will now be available for viewing at [`https://localhost:3000/rails/view_spec/previews/button@default`](https://localhost:3000/rails/view_spec/previews/button@default).
+
+Previews are rendered in isolation from the rest of your app which makes them perfect for using whilst developing your components/partials/helpers etc.
+
+> [!NOTE]
+> By default previews are only available when your app is running in `development` and `test` environments, although this behaviour is configurable if required.
+
+### 4. Add some tests
+
+Once a scenario preview has been added you can then add some tests to run against it.
+
+Tests are defined within the context of the scenario in a `tests do ... end` block.
+
+For this example we'll add a couple of test to check that the rendered output of this default button component state is as expected.
+
+```rb
+# test/view_specs/button_vspec.rb
+
+ViewSpec.spec "components/button" do
+  # ...
+
+  scenario "default" do
+    # ...
 
-    scenario "secondary" do
-      preview { render ButtonComponent.new(text: "Secondary", theme: :secondary) }
+    preview do
+      render "components/button", text: "Click here"
     end
 
-    scenario "danger" do
-      preview { render ButtonComponent.new(text: "Danger", theme: :danger) }
+    tests do 
+      setup { render_preview }
+        
+      test "it renders the button component" do
+        assert_selector("button.button")
+      end
+
+      test "it has the default attributes set" do
+        assert_selector(%(button[type="button"][data-theme="primary"]))
+      end
+
+      test "it displays the label text" do
+        assert_selector("button", text: "Click here")
+      end
     end
   end
 end
-```
+```
+
+### 5. Run the tests
+
+To run the tests as part of your Minitest-based test suite you will first need to add a ViewSpec test file into your `tests` directory. It should contain the following content:
+
+```rb
+# tests/view_specs_test.rb
+
+require "test_helper"
+
+module ViewSpecsTest
+  include ViewSpec::Minitest::Tests
+end
+```
+
+This only needs to be done once. With with this file in place all the preview tests defined in your spec files will be included everytime your test suite is run using `rails test`.
+
+If you only wish to run your ViewSpec tests then just run the ViewSpec test file directly:
+
+```sh
+rails test test/view_specs_test.rb
+```
+
+> [!NOTE]
+> Only Minitest is currently supported but adapters for RSpec and more are in the works!
+
+### 6. Add more scenarios
+
+At this point it often makes sense to add more scenarios to demonstrate/document other states or properties of the subject of the spec.
+
+A spec can have as many scenarios as needed, each with it's own preview, tests and usage notes.
+
+> [!TIP]
+> Scenarios can also be grouped together in a `group do ... end` block if required. See below for more details on scenarios and scenario groups.
+
+### 7. Generate documentation
+
+ViewSpec files are designed to act as readable developer-documentation in their own right. However you may also wish to have HTML-formatted documentation for your components/partials/views etc.
+
+ViewSpec provides some bare-bones default templates to make it easy to generate HTML docs from your specs. 
+
+For simplicity the example below just shows how you could generate docs specifically for the single button spec defined above (although in reality you would probably want to make this dynamic so you wouldn't need to manually add a separate action for each spec file).
+
+```rb
+class DocsController < ApplicationController
+  def button
+    @spec = ViewSpec.specs.find(ButtonComponent)
+    @params = request.query_parameters
+  end
+end
+```
+
+```erb
+# views/docs/button.html.erb
+ 
+<%= render @spec, params: @params %>
+```
+
+The example above will render documentation for the button spec using [the default templates](./app/views/view_specs/).
+
+Styling the docs with CSS is up to you, no default stylesheet is provided. With some basic styles applied the default templates look like this:
+
+<img src="./.github/assets/button_view_spec_docs.png">
+
+You can override one or all of the default templates by copying them into a `view_specs` folder in your `app/views` directory, and then customising them as needed.
+
+## Usage
+
+ViewSpec has the following requirements:
+
+* `Rails 7.0+`
+* `Ruby 3.1+`
+
+### Installation
+
+Add the following to your Rails app Gemfile:
+
+```rb
+gem "view_spec"
+```
+
+And then run `bundle install`. You are good to go!
+
+### Configuration
+
+_Docs coming soon_
+
+### ViewSpec DSL
+
+_Docs coming soon_
+
+## About ViewSpec (& Lookbook)
+
+ViewSpec is being developed as a standalone replacement for [Lookbook's](https://lookbook.build/) underlying [preview system](https://lookbook.build/guide/previews).
+
+It shares a lot of concepts with the existing Lookbook preview class format (which was based on ViewComponent's preview system - itself in turn inspired by Rails' ActionMailer previews). However using a pure Ruby DSL in place of YARD-style comment tags results in much better performance and has many other benefits (including 'native' syntax error handling and more).
+
+Additionally, having a standalone file format and preview system which is not tied to any particular UI tool (such as Lookbook) or component system (such as ViewComponent) hopefully means that ViewSpec can be adopted by teams that don't want those dependencies but do still want a way to efficiently develop and document the frontend of their Rails app.
+
+**The plan is for the next major version of Lookbook to built upon the ViewSpec file format**. It will provide a user interface for browsing and inspecting your ViewSpec previews in much the same way it does at the moment for the current (ViewComponent-style) preview class files.
+
+_(Note that the current `v2.x` branch of Lookbook is **not** compatible with ViewSpec and there is no intention to add support for it in the future.)_
+
+> [!IMPORTANT]
+> Projects can (and always will be able to) use ViewSpec to help preview, test and document their view layer **without any requirement** to use Lookbook.

data/app/controllers/concerns/view_specs/preview_actions.rb

@@ -0,0 +1,37 @@
+module ViewSpecs
+  module PreviewActions
+    extend ActiveSupport::Concern
+
+    def index
+      @view_specs = ViewSpec.specs
+
+      layout = self.class._layout || ViewSpec.config.preview_layout
+      options = {}
+      options[:layout] = layout if layout
+
+      render "view_specs/previews/index", **options
+    end
+
+    def preview
+      spec = ViewSpec.specs.find_where(lookup_path: params[:spec])
+      raise ActionController::RoutingError, "Spec not found" unless spec
+
+      entry = spec.entries.find_where(short_identifier: params[:entry])
+      raise ActionController::RoutingError, "`#{params[:entry]}` not found for spec `#{spec.subject}`" unless entry
+
+      preview = entry.preview(params: view_spec_preview_params)
+
+      options = {}
+      layout = entry.determine_layout(self.class._layout) || ViewSpec.config.preview_layout
+      (options[:layout] = layout) if layout
+
+      render preview, **options
+    end
+
+    private
+
+    def view_spec_preview_params
+      request.query_parameters.fetch(:params, {})
+    end
+  end
+end

data/app/controllers/view_spec_previews_controller.rb

@@ -0,0 +1,3 @@
+class ViewSpecPreviewsController < ApplicationController
+  include ViewSpecs::PreviewActions
+end

data/app/views/view_specs/_group.html.erb

@@ -0,0 +1,56 @@
+<%# locals: (group:, params: {}, details: true) -%>
+
+<%
+details = (details == true) ? [ :notes, :preview, :source, :html] : Array.wrap(details)
+previewable_scenarios = group.scenarios.filter(&:preview?)
+request_params = request.query_parameters.fetch("params", {})
+%>
+
+<section class="vs-entry vs-entry--group">
+  <header class="vs-entry-header">
+    <h2 class="vs-entry-title"><%= group.title %></h2>
+  </header>
+  <div class="vs-entry-content">
+    <% if details.include?(:notes) && group.notes? %>
+      <article class="vs-entry-notes">
+        <%= group.notes %>
+      </article>
+    <% end %>
+    <% if previewable_scenarios.any? %>
+      <% preview = group.preview(params:) %>
+      <% if details.include?(:preview) %>
+        <details class="vs-entry-details vs-entry-details--preview" open>
+          <summary>
+            <h4 class="vs-entry-subtitle">Preview</h4>
+          </summary>
+          <p class="vs-entry-preview-link">
+            <%= link_to "View in new window", preview.to_path(params: {params: request_params}), target: "_blank" %>
+          </p>
+          <div class="vs-entry-details-display vs-preview">
+            <%= preview %>
+          </div>
+        </details>
+      <% end %>
+      <% if details.include?(:source) %>
+        <details class="vs-entry-details vs-entry-details--source" open>
+          <summary>
+            <h4 class="vs-entry-subtitle">Source</h4>
+          </summary>
+          <code class="vs-code-block" data-lang="<%= preview.lang %>">
+            <pre><%= preview.source %></pre>
+          </code>
+        </details>
+      <% end %>
+      <% if details.include?(:html) %>
+        <details class="vs-entry-details vs-entry-details--html">
+          <summary>
+            <h4 class="vs-entry-subtitle">Output</h4>
+          </summary>
+          <code class="vs-code-block" data-lang="html">
+            <pre><%= preview.raw %></pre>
+          </code>
+        </details>
+      <% end %>
+    <% end %>
+  </div>
+</section>

data/app/views/view_specs/_scenario.html.erb

@@ -0,0 +1,55 @@
+<%# locals: (scenario:, params: {}, details: true) -%>
+
+<%
+details = (details == true) ? [ :notes, :preview, :source, :html] : Array.wrap(details)
+request_params = request.query_parameters.fetch("params", {})
+%>
+
+<section class="vs-entry vs-entry--scenario">
+  <header class="vs-entry-header">
+    <h3 class="vs-entry-title"><%= scenario.title %></h3>
+  </header>
+  <div class="vs-entry-content">
+    <% if details.include?(:notes) && scenario.notes? %>
+      <article class="vs-entry-notes">
+        <%= scenario.notes %>
+      </article>
+    <% end %>
+    <% if scenario.preview? %>
+      <% preview = scenario.preview(params:) %>
+      <% if details.include?(:preview) %>
+        <details class="vs-entry-details vs-entry-details--preview" open>
+          <summary>
+            <h4 class="vs-entry-subtitle">Preview</h4>
+          </summary>
+          <p class="vs-entry-preview-link">
+            <%= link_to "View in new window", preview.to_path(params: {params: request_params}), target: "_blank" %>
+          </p>
+          <div class="vs-preview">
+            <%= preview %>
+          </div>
+        </details>
+      <% end %>
+      <% if details.include?(:source) %>
+        <details class="vs-entry-details vs-entry-details--source" open>
+          <summary>
+            <h4 class="vs-entry-subtitle">Source</h4>
+          </summary>
+          <code class="vs-code-block" data-lang="<%= preview.lang %>">
+            <pre><%= preview.source %></pre>
+          </code>
+        </details>
+      <% end %>
+      <% if details.include?(:html) %>
+        <details class="vs-entry-details vs-entry-details--html">
+          <summary>
+            <h4 class="vs-entry-subtitle">HTML output</h4>
+          </summary>
+          <code class="vs-code-block" data-lang="html">
+            <pre><%= preview.raw %></pre>
+          </code>
+        </details>
+      <% end %>
+    <% end %>
+  </div>
+</section>

data/app/views/view_specs/_spec.html.erb

@@ -0,0 +1,18 @@
+<%# locals: (spec:, params: {}, header: true, details: true) -%>
+
+<article class="vs-spec" data-view-spec data-view-spec-subject="<%= spec.subject %>">
+  <% if header %>
+    <header class="vs-spec-header">
+      <h2 class="vs-spec-title"><%= spec.title %></h2>
+    </header>
+  <% end %>
+  <div class="vs-spec-content">
+    <div class="vs-spec-entries">
+      <% spec.entries.each do |entry| %>
+        <div class="vs-spec-entry">
+          <%= render entry, params:, details: %>
+        </div>
+      <% end %>
+    </div>
+  </div>
+</article>

data/app/views/view_specs/group/_notes.html.erb

@@ -0,0 +1,14 @@
+<%# locals: {group:, notes: nil}  %>
+<% scenarios_with_notes =  group.scenarios.filter { _1.notes? } %>
+<%= notes if notes.present? %>
+
+
+
+<% scenarios_with_notes.each do |scenario| %>
+  <div style="all: revert; padding-left: 0.5rem">
+    <h4 style="all: revert; margin: 0 0 0.5rem -0.5rem;"><%= scenario.title %></h4>
+    <%= scenario.notes %>
+  </div>
+<% end %>
+
+

data/app/views/view_specs/group/_preview.html.erb

@@ -0,0 +1,19 @@
+<%# locals: {group:, params: {}}  %>
+
+<% group.scenarios.each do |scenario| %>
+  <% preview = scenario.preview(params:) %>
+  <div style="display: block;<%= " margin-bottom: 1.5rem;" unless scenario == group.scenarios.last %>">
+    <h6 style="all: revert; display: flex; align-items: center; font-family: ui-monospace, monospace; font-weight: normal; font-size: 0.9rem; margin-top: 0; margin-bottom: 0.8rem; color: currentColor">
+      <span style="all: revert; margin-right: 0.3rem; color: currentColor"><%= scenario.title %></span>
+      <a style="all: revert; display: flex; align-items: center; text-decoration: underline; cursor: pointer; opacity: 0.7;" href="<%= preview.to_path %>" target="_blank" title="Open in new window">
+        <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="unset: all; display: inline-block;">
+          <path d="M21 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h6"/><path d="m21 3-9 9"/>
+          <path d="M15 3h6v6"/>
+        </svg>
+      </a>
+    </h6>
+    <div>
+      <%= preview %>
+    </div>
+  </div>
+<% end %>

data/app/views/view_specs/group/_raw.html.erb

@@ -0,0 +1,7 @@
+<%# locals: {group:, params: {}}  %>
+
+<% group.scenarios.each do |scenario| %>
+<!-- <%= scenario.title %> -->
+<%= scenario.preview(params:) %>
+
+<% end %>

data/app/views/view_specs/group/_source.html.erb

@@ -0,0 +1,7 @@
+<%# locals: {group:, params: {}}  %>
+
+<% group.scenarios.each do |scenario| %>
+# <%= scenario.title %>
+<%= scenario.preview(params:).source %>
+
+<% end %>

data/app/views/view_specs/previews/index.html.erb

@@ -0,0 +1,22 @@
+<% if @view_specs.any? %>
+  <ul id="view-spec-previews">
+    <% @view_specs.each do |view_spec| %>
+      <li>
+        <h2><%= view_spec.title %></h2>
+        <% if view_spec.previews? %>
+        <ul>
+          <% view_spec.entries.each do |entry| %>
+            <% if entry.preview? %>
+              <li>
+                <%= link_to entry.title, entry.preview.to_path %>
+              </li>
+            <% end %>
+          <% end %>
+        </ul>
+        <% else %>
+          <p><em>No previews added.</em></p>
+        <% end %>
+      </li>
+    <% end%>
+  </ul>
+<% end %>

data/lib/view_spec/collection.rb

@@ -0,0 +1,43 @@
+module ViewSpec
+  module Collection
+    extend ActiveSupport::Concern
+    include Enumerable
+
+    included do
+      attr_reader :items
+      delegate_missing_to :items
+    end
+
+    def initialize(items = [])
+      @items = items.is_a?(Collection) ? items.to_a : items
+    end
+
+    def find_where(conditions)
+      where(conditions).first
+    end
+
+    def find_where!(conditions)
+      result = find_where(conditions)
+      result.nil? ? raise("No matching item found for conditions #{conditions}") : result
+    end
+
+    def where(conditions)
+      conditions.reduce(items.dup) do |collection, (key, value)|
+        collection.filter! { _1.respond_to?(key) && (_1.public_send(key) == value) }
+      end
+    end
+
+    def <<(item)
+      items.push(item)
+      self
+    end
+
+    def +(other)
+      self.class.new(items + other.items)
+    end
+
+    def to_a
+      items
+    end
+  end
+end