lookbook 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 746247239c9d22b8537a0327dfa40e3d4a2b687a9d48e0a4b61819cba7766bec
-  data.tar.gz: c288e6e752520bb2b4b90b5e1f682cd68c99961939496b5d698abf2604962efc
+  metadata.gz: d6235a52e2104d528b7c3d4a56fee91f3db334ef9ce3d9da43cc11e50792cf77
+  data.tar.gz: 5bd16de7e7dbe99e7552efb07d719230bd1c108d13340d4fcb790dd8e034ef1e
 SHA512:
-  metadata.gz: 6b0aae039cf5d29f2d9f93aca8f2fd62996ecbce1ad9cc9ab8c8b19e82343f71a3dc6694406182e5ebd41b0a6ad97c160a7c156e51463cda51f522b186a25a1d
-  data.tar.gz: cf44c51bfa10e5eabc5dc6c88931d3e1676e5b72599e00304c83aca343d6a080ef31afa0044e39383d1c4b4ccc179260832afb5951d5427858767b09ff749a4a
+  metadata.gz: 990f07de7b0ab03d9e9577d3c84768542ebc2af7e5d587fc85f95532ade53f88abc34b2f371a776a0f48b2a3c0db5a1be606e6a42653f57e92ae19e6735ac81c
+  data.tar.gz: a2e17e85420de7603fdd3277eebd473b3bcff413f9d8507b38600290d6d35c081a034c4f70c14d8e3be9075b6b22caade8d2d6610ab3d6a2fd5e863bf1555bc8

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 allmarkedup
+Copyright (c) 2021 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,30 +1,42 @@
-# Lookbook
-
-<div>
-<a href="https://rubygems.org/gems/lookbook"><img src="https://img.shields.io/gem/v/lookbook" alt="Gem version"></a>
-<a href="https://github.com/allmarkedup/lookbook/actions/workflows/ci.yml"><img src="https://github.com/allmarkedup/lookbook/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
-</div>
 <br>
+<img src=".github/assets/lookbook_logo.svg" width="180"> 
 
 A tool to help browse, develop, test & document [ViewComponents](https://viewcomponent.org/) in Ruby on Rails apps.
 
+[![Gem version](https://img.shields.io/gem/v/lookbook)](https://rubygems.org/gems/lookbook)
+[![CI status](https://github.com/allmarkedup/lookbook/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allmarkedup/lookbook/actions/workflows/ci.yml)
+<br>
+
 ## Documentation
 
-**Lookbook (v1.x)** documentation: **[https://lookbook.build](https://lookbook.build)**
+✨ **Lookbook guide and API docs**: [lookbook.build](https://lookbook.build)
 
-> _Looking for v0.9.x docs? [Head over here](https://github.com/allmarkedup/lookbook/tree/0.9.x)._
+> _Looking for pre-v1.0 documentation? [Head over here](https://github.com/allmarkedup/lookbook/tree/0.9.x)._
 
 
 ## Demo
 
-**Online Demo:** [https://lookbook-demo-app.herokuapp.com/lookbook](https://lookbook-demo-app.herokuapp.com/lookbook) 
+✨ **Online Demo**: [lookbook-demo-app.herokuapp.com/lookbook](https://lookbook-demo-app.herokuapp.com/lookbook)
+
+✨ **Demo repo**: [github.com/allmarkedup/lookbook-demo](https://github.com/allmarkedup/lookbook-demo)
 
 [![Lookbook UI](.github/assets/lookbook_screenshot_v1.0_beta.png)](https://lookbook-demo-app.herokuapp.com/lookbook/)
 
 
 ## Development
 
-Lookbook's UI is itself built using ViewComponents. To preview these components in a Lookbook instance you can run the included `workbench` app:
+Lookbook is implemented as an isolated [Rails Engine](https://guides.rubyonrails.org/engines.html) and uses [ViewComponent](https://viewcomponent.org), [Tailwind](https://tailwindcss.com/) and [Alpine](https://alpinejs.dev/) for it's UI.
+
+This repository contains:
+
+* The Lookbook source code ([`/app`](https://github.com/allmarkedup/lookbook/tree/main/app), [`/lib`](https://github.com/allmarkedup/lookbook/tree/main/lib), [`/config`](https://github.com/allmarkedup/lookbook/tree/main/config), etc)
+* A '[workbench](#workbench)' app used for Lookbook component development ([`/workbench`](https://github.com/allmarkedup/lookbook/tree/main/workbench)).
+* The Lookbook [documentation site](#docs-site) source code and content ([`/docs`](https://github.com/allmarkedup/lookbook/tree/main/docs)).
+* A [test suite](#testing) with a 'runable' dummy app ([`/spec`](https://github.com/allmarkedup/lookbook/tree/main/spec)).
+
+### Workbench
+
+To preview the Lookbook components within a Lookbook instance you can run the included `workbench` app:
 
 1. Clone this repo
 2. Install dependencies: `bundle install & npm install`
@@ -33,21 +45,42 @@ Lookbook's UI is itself built using ViewComponents. To preview these components
 
 The `workbench` app will be started in development mode and any changes to Lookbook's views or assets will immediately be reflected in the UI.
 
-### Docs site
+### Documentation site
 
 The [Lookbook docs site](https://lookbook.build) is built using [Bridgetown](https://www.bridgetownrb.com/) and the source files can be found in the `./docs` directory.
 
-To see a local version of the site run `bin/docs` from the root of this repo and then visit http://localhost:4000 in your browser.
+To preview changes locally you can run a development version of the docs site:
+
+1. Clone this repo
+2. Install dependencies: `bundle install`
+3. Start the app: `bin/docs`
+4. Visit http://localhost:4000 
 
 ### Testing
 
-Lookbook uses RSpec for testing.
+Lookbook uses [RSpec](https://relishapp.com/rspec) for testing.
 
 Tests can be run using the `rake spec` or `bundle exec rspec` commands.
 
 The dummy app that the tests are being run against can be viewed by running the `bin/dummy` command and then browsing to http://localhost:9292/lookbook
 
 
+## Contributing
+
+Lookbook is an un-funded open source project and contributions of all types and sizes are most welcome!
+
+Please take the time to read over the [Contributing](./CONTRIBUTING.md) guide before making your first contribution and if anything isn't clear then [start a discussion](https://github.com/allmarkedup/lookbook/discussions) and we will do our best to help you out.
+
+## Contributors 
+
+Lookbook was created by [Mark Perkins](https://github.com/allmarkedup) and continues to grow
+&amp; improve thanks to the ideas, suggestions and hard work of all of [these excellent humans](https://github.com/allmarkedup/lookbook/graphs/contributors):
+<br>
+<br>
+<a href="https://github.com/allmarkedup/lookbook/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=allmarkedup/lookbook&columns=14" width="800" />
+</a>
+
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/components/lookbook/code/component.html.erb

@@ -6,5 +6,5 @@
       "h-full": full_height?
     } 
   ] do %>
-  <%= Lookbook::CodeFormatter.highlight(source, **@highlight_opts) %>
+  <%= Lookbook::CodeHighlighter.call(source, **@highlight_opts) %>
 <% end %>

data/app/components/lookbook/inspector_panel/component.rb

@@ -1,5 +1,3 @@
-require "css_parser"
-
 module Lookbook
   class InspectorPanel::Component < Lookbook::BaseComponent
     attr_reader :panel_styles, :panel_html
@@ -14,9 +12,9 @@ module Lookbook
     end
 
     def before_render
-      tpl = TemplateParser.new(content)
-      @panel_styles = tpl.styles.map { |s| "##{id} #{s}" }.join("\n")
-      @panel_html = tpl.content
+      styles, html = StylesExtractor.call(content)
+      @panel_styles = styles.map { |s| "##{id} #{s}" }.join("\n")
+      @panel_html = html.html_safe
     end
   end
 end

data/app/components/lookbook/nav/item/component.html.erb

@@ -6,7 +6,7 @@
     "entity-type": item.type
   },
   cloak: true do %>
-  <%= lookbook_tag href.present? ? :a : :div,
+  <%= lookbook_tag href.present? ? :a : :button,
     href: href,
     class: "flex items-center py-1 select-none cursor-pointer text-lookbook-nav-text hover:bg-lookbook-nav-item-hover transition",
     style: "padding-left: #{left_pad}px",

data/app/components/lookbook/params/editor/component.rb

@@ -1,20 +1,13 @@
 module Lookbook
   module Params
     class Editor::Component < Lookbook::BaseComponent
-      renders_many :fields, ->(input:, description: nil, **attrs) do
+      renders_many :fields, ->(**attrs) do
         @field_count += 1
-        @descriptions = true if description.present?
-        input_config = @inputs[input.tr("-", "_").to_sym]
-        Lookbook::Params::Field::Component.new(input: input,
-          description: description,
-          index: @field_count,
-          config: input_config, **attrs)
+        Lookbook::Params::Field::Component.new(**attrs, index: @field_count)
       end
 
-      def initialize(inputs: nil, **html_attrs)
-        @inputs = inputs.to_h
+      def initialize(**html_attrs)
         @field_count = -1
-        @descriptions = false
         @@input_styles = {}
         super(**html_attrs)
       end

data/app/components/lookbook/params/field/component.html.erb

@@ -1,27 +1,27 @@
 <%= render_component_tag :tr, "@keydown.stop": true do %>  
   <td class="param-label">
-    <label for="param-<%= @name %>">
-      <span class="mr-0.5"><%== @label %></span>
-      <% if hint? %>
+    <label for="param-<%= param.name %>">
+      <span class="mr-0.5"><%== param.label %></span>
+      <% if param.hint.present? %>
         <span x-data="tooltipComponent" class="inline-block cursor-help relative top-[2px]">
           <%= icon :help_circle, size: 3.5, class: "opacity-40 hover:opacity-100 transition" %>
           <div class="hidden" x-ref="tooltip">
-            <%= @hint %>
+            <%= param.hint %>
           </div>
         </span>
       <% end %>
     </label>
   </td>
-  <td class="param-description <%= "param-description-empty" unless description? %>">
-    <% if description? %>
-      <p class="opacity-70"><%= @description %></p>
+  <td class="param-description <%= "param-description-empty" unless param.description %>">
+    <% if param.description %>
+      <p class="opacity-70"><%= param.description %></p>
     <% else %>
       <p class="italic opacity-40">&mdash;</p>
     <% end %>
   </td>
   <td class="param-input">
     <div class="param-input-wrapper">
-      <%= input %>
+      <%= rendered_input %>
     </div>
   </td>
 <% end %>

data/app/components/lookbook/params/field/component.rb

@@ -1,92 +1,41 @@
 module Lookbook
   module Params
     class Field::Component < Lookbook::BaseComponent
-      def initialize(name:, input:, index:, label: nil, hint: nil, description: nil, value: nil, value_default: nil, value_type: nil, input_options: {}, config: nil, **html_attrs)
-        @input_name = input
-        @name = name
-        @label = label || name.titleize
-        @hint = hint
-        @description = description
-        @value = value
+      attr_reader :param, :rendered_input
+
+      def initialize(param:, index:, **html_attrs)
+        @param = param
         @index = index
-        @input_options = input_options
-        @value_default = value_default
-        @value_type = value_type
-        @config = config || {}
         @rendered_input = nil
         super(**html_attrs)
       end
 
-      def hint?
-        @hint.present?
-      end
-
-      def description?
-        @description.present?
-      end
-
-      def input
-        @rendered_input
-      end
-
       def before_render
-        tpl = TemplateParser.new(render_input)
-        Editor::Component.add_styles(@input_name, tpl.styles)
+        styles, html = StylesExtractor.call(render_input)
+        Editor::Component.add_styles(param.input, styles)
 
+        escaped_value = json_escape(param.value.to_json)
         wrapper_attrs = {
-          data: {"param-input": @input_name},
-          "x-data": "paramsInputComponent({name: '#{@name}', value: #{escaped_value}})"
+          data: {"param-input": param.input},
+          "x-data": "paramsInputComponent({name: '#{param.name}', value: #{escaped_value}})"
         }
-
-        @rendered_input = tag.div(**wrapper_attrs) do
-          tpl.content
-        end
+        @rendered_input = tag.div(**wrapper_attrs) { html.html_safe }
       end
 
       protected
 
-      def input_error(error)
-        tag.div error, class: "p-2 text-red-500 italic"
-      end
-
-      def value
-        val = @value.presence || @value_default
-        @value_type.downcase == "boolean" ? val == "true" || val == true : val
-      end
-
-      def escaped_value
-        json_escape(value.to_json)
-      end
-
-      def input_options
-        config_options = @config.fetch(:opts, {})
-        opts = config_options.merge(@input_options).symbolize_keys
-        opts[:id] = "param-#{@name}"
-        opts
-      end
-
-      def render_props
-        {
-          name: @name,
-          input: @input_name,
-          value: value,
-          value_type: @value_type,
-          value_default: @value_default,
-          input_options: input_options.except(:choices),
-          choices: input_options[:choices]
-        }
-      end
-
       def render_input
-        target = @config[:partial]
-        if target
-          render(target, **render_props)
-        else
-          input_error "No param input defined for input type '#{@input_name}'."
-        end
-      rescue ::ActionView::MissingTemplate => exception
-        Lookbook.logger.error exception
-        input_error "Param input partial '#{@config[:partial]}' could not be found."
+        input_options = param.input_options.to_h
+        input_options[:id] = "param-#{param.name}"
+
+        render(param.input_partial,
+          name: param.name,
+          input: param.input,
+          value: param.value,
+          value_type: param.value_type,
+          value_default: param.value_default,
+          input_options: input_options.except(:choices),
+          choices: input_options[:choices])
       end
 
       def alpine_component

data/app/controllers/concerns/lookbook/targetable_concern.rb

@@ -0,0 +1,156 @@
+module Lookbook
+  module TargetableConcern
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :lookup_entities, only: [:show]
+      before_action :set_title
+      before_action :set_display_options
+      before_action :set_params
+    end
+
+    def set_title
+      @title = @target.present? ? [@target&.label, @preview&.label].compact.join(" :: ") : "Not found"
+    end
+
+    def lookup_entities
+      @target = Lookbook.previews.find_example(params[:path])
+      if @target.present?
+        @preview = @target.preview
+        if params[:path] == @preview&.lookup_path
+          redirect_to lookbook_inspect_path "#{params[:path]}/#{@preview.default_example.name}"
+        end
+      else
+        @preview = Lookbook.previews.find(params[:path])
+        if @preview.present?
+          first_example = @preview.examples.first
+          redirect_to lookbook_inspect_path(first_example.lookup_path) if first_example
+        else
+          @preview = Lookbook.previews.find(path_segments.slice(0, path_segments.size - 1).join("/"))
+        end
+      end
+    end
+
+    def set_display_options
+      @dynamic_display_options = []
+      @static_display_options = []
+
+      if @target.present?
+        opts = @target.display_options
+        @dynamic_display_options = opts.select { _2.is_a?(Array) || _2.is_a?(Hash) }
+        @static_display_options = opts.except(*@dynamic_display_options.keys)
+
+        if params[:_display]
+          display_params = SearchParamParser.call(params[:_display])
+          display_params.each do |name, value|
+            if @dynamic_display_options.key?(name)
+              cookies["lookbook-display-#{name}"] = value
+            end
+          end
+        end
+
+        @dynamic_display_options.each do |name, opts|
+          choices = opts.is_a?(Hash) ? opts[:choices].to_a : opts
+          @static_display_options[name] ||= cookies.fetch("lookbook-display-#{name}", choices.first)
+        end
+
+        unless params[:_display]
+          display_params = @dynamic_display_options.map do |name, opts|
+            [name, @static_display_options[name]]
+          end.to_h
+          request.query_parameters[:_display] = SearchParamBuilder.call(display_params)
+        end
+      end
+    end
+
+    def set_params
+      @params = []
+
+      if @target
+        @params = @target.tags("param").map do |param_tag|
+          Param.from_tag(
+            param_tag,
+            value: preview_controller.params[param_tag.name]
+          )
+        end
+
+        # cast known param values to correct type
+        @params.each do |param|
+          if preview_controller.params.key?(param.name)
+            preview_controller.params[param.name] = param.cast_value
+          end
+        end
+
+        # set display and data params for use in preview layouts
+        preview_controller.params[:lookbook] = {
+          display: @static_display_options,
+          data: Lookbook.data
+        }
+      end
+
+      preview_controller.params.permit!
+      @preview_params = preview_controller.params.to_h.select do |key, value|
+        !!@params.find { |param_tag| param_tag.name == key.to_s }
+      end
+    end
+
+    def inspector_data
+      return @inspector_data if @inspector_data.present?
+
+      context_data = {
+        preview_params: @preview_params,
+        path: params[:path]
+      }
+
+      preview = @preview
+      target_examples = @target.type == :group ? @target.examples : [@target]
+
+      examples = target_examples.map do |example|
+        render_args = @preview.render_args(example.name, params: preview_controller.params)
+        has_template = render_args[:template] != "view_components/preview"
+        output = preview_controller.process(:render_example_to_string, @preview, example.name)
+        source = has_template ? example.template_source(render_args[:template]) : example.method_source
+        source_lang = has_template ? example.template_lang(render_args[:template]) : example.lang
+
+        example.define_singleton_method(:output, proc { output })
+        example.define_singleton_method(:source, proc { source })
+        example.define_singleton_method(:source_lang, proc { source_lang })
+        example
+      end
+
+      target = @target.type == :group ? @target : examples.find { |e| e.lookup_path == @target.lookup_path }
+
+      params_ref = @params
+      preview.define_singleton_method(:params, proc { params_ref })
+
+      @inspector_data ||= Lookbook::Store.new({
+        context: context_data,
+        preview: preview,
+        examples: examples,
+        example: examples.first,
+        target: target,
+        data: Lookbook.data,
+        app: Lookbook
+      })
+    end
+
+    def show_404(layout: nil)
+      locals = if @preview
+        {
+          message: "Example not found",
+          description: "The '#{@preview.label}' preview does not have an example named '#{path_segments.last}'."
+        }
+      else
+        {
+          message: "Not found",
+          description: "Looked for '#{params[:path]}'.<br>The preview may have been renamed or deleted."
+        }
+      end
+      render_in_layout "lookbook/404", layout: layout, **locals
+    end
+
+    def path_segments
+      params[:path].split("/")
+    end
+  end
+end

data/app/controllers/concerns/lookbook/with_preview_controller_concern.rb

@@ -0,0 +1,13 @@
+module Lookbook
+  module WithPreviewControllerConcern
+    extend ActiveSupport::Concern
+
+    def preview_controller
+      return @preview_controller if @preview_controller
+      controller = Lookbook::Engine.preview_controller.new
+      controller.request = request
+      controller.response = response
+      @preview_controller ||= controller
+    end
+  end
+end

data/app/controllers/lookbook/application_controller.rb

@@ -1,8 +1,6 @@
 module Lookbook
   class ApplicationController < ActionController::Base
-    if respond_to?(:content_security_policy)
-      content_security_policy false, if: -> { Rails.env.development? }
-    end
+    content_security_policy(false) if respond_to?(:content_security_policy)
 
     protect_from_forgery with: :exception
 
@@ -45,5 +43,17 @@ module Lookbook
       @error = locals[:error]
       render path, layout: layout.presence || (params[:lookbook_embed] ? "lookbook/basic" : "lookbook/application"), locals: locals
     end
+
+    def prettify_error(exception)
+      error_params = {}
+      if exception.is_a?(ViewComponent::PreviewTemplateError)
+        error_params = {
+          file_path: @preview&.full_path,
+          line_number: 0,
+          source_code: @target&.source
+        }
+      end
+      Lookbook::Error.new(exception, **error_params)
+    end
   end
 end

data/app/controllers/lookbook/inspector_controller.rb

@@ -0,0 +1,45 @@
+module Lookbook
+  class InspectorController < ApplicationController
+    include TargetableConcern
+    include WithPreviewControllerConcern
+
+    layout "lookbook/inspector"
+    helper Lookbook::PreviewHelper
+
+    def self.controller_path
+      "lookbook/inspector"
+    end
+
+    def show
+      if @target
+        begin
+          @main_panels = main_panels
+          @drawer_panels = drawer_panels
+        rescue => exception
+          render_in_layout "lookbook/error", layout: "lookbook/inspector", error: prettify_error(exception)
+        end
+      else
+        show_404
+      end
+    end
+
+    def show_legacy
+      Lookbook.logger.warn("Legacy URL path detected. These paths are deprecated and will be removed in a future version")
+      redirect_to lookbook_inspect_path params[:path]
+    end
+
+    private
+
+    def main_panels
+      Engine.panels.in_group(:main).map do |config|
+        PanelStore.resolve_config(config, inspector_data)
+      end
+    end
+
+    def drawer_panels
+      Engine.panels.in_group(:drawer).map do |config|
+        PanelStore.resolve_config(config, inspector_data)
+      end
+    end
+  end
+end

data/app/controllers/lookbook/page_controller.rb

@@ -13,13 +13,17 @@ module Lookbook
       @pages = Lookbook.pages
       @next_page = @pages.find_next(@page)
       @previous_page = @pages.find_previous(@page)
-      content = render_to_string inline: @page.content, locals: {
-        page: @page,
-        next_page: @next_page,
-        previous_page: @previous_page,
-        pages: @pages
-      }
-      @page.markdown? ? Lookbook::Markdown.render(content) : content
+
+      content = ActionViewAnnotationsHandler.call(disable_annotations: true) do
+        render_to_string inline: @page.content, locals: {
+          page: @page,
+          next_page: @next_page,
+          previous_page: @previous_page,
+          pages: @pages
+        }
+      end
+
+      @page.markdown? ? MarkdownRenderer.call(content, Lookbook.config.markdown_options) : content
     end
   end
 end