showcase-rails 0.1.0

data/app/assets/config/showcase_manifest.js

@@ -0,0 +1,2 @@
+//= link showcase.js
+//= link_tree ../builds/ .css

data/app/assets/javascripts/showcase.js

@@ -0,0 +1,28 @@
+window.customElements.define("showcase-sample", class extends HTMLElement {
+  connectedCallback() {
+    this.events.forEach((name) => this.addEventListener(name, this.emit))
+  }
+
+  disconnectedCallback() {
+    this.events.forEach(this.removeEventListener)
+  }
+
+  emit(event) {
+    console.log({ originator: this, event })
+    this.relay(event)
+  }
+
+  relay({ type, detail }) {
+    const node = document.createElement("div")
+    node.innerHTML = JSON.stringify({ type, detail })
+    this.relayTarget?.appendChild(node)
+  }
+
+  get relayTarget() {
+    return this.querySelector("[data-showcase-sample-target='relay']")
+  }
+
+  get events() {
+    return JSON.parse(this.getAttribute("events")) || []
+  }
+})

data/app/controllers/showcase/application_controller.rb

@@ -0,0 +1,3 @@
+class Showcase::ApplicationController < ActionController::Base
+  layout "showcase"
+end

data/app/controllers/showcase/pages_controller.rb

@@ -0,0 +1,8 @@
+class Showcase::PagesController < Showcase::ApplicationController
+  def index
+  end
+
+  def show
+    @page = Showcase::Path.new(params[:id]).page_for view_context
+  end
+end

data/app/models/showcase/page/options.rb

@@ -0,0 +1,51 @@
+class Showcase::Page::Options
+  include Enumerable
+
+  def initialize(view_context)
+    @view_context = view_context
+    @options = []
+    @order = [:name, :required, :type, :default, :description]
+  end
+  delegate :empty?, to: :@options
+
+  def required(*arguments, **keywords, &block)
+    option(*arguments, **keywords, required: true, &block)
+  end
+
+  def optional(*arguments, **keywords, &block)
+    option(*arguments, **keywords, required: false, &block)
+  end
+
+  DEFAULT_OMITTED = Object.new
+
+  def option(name, description = nil, required: false, type: nil, default: DEFAULT_OMITTED, **options, &block)
+    description ||= @view_context.capture(&block).remove(/^\s+/).html_safe if block
+
+    type ||= type_from_default(default)
+    default = default == DEFAULT_OMITTED ? nil : default.inspect
+
+    @options << options.with_defaults(name: name, default: default, type: type, description: description, required: required)
+  end
+
+  def headers
+    @headers ||= @order | @options.flat_map(&:keys).uniq.sort
+  end
+
+  def each(&block)
+    @options.each do |option|
+      yield headers.index_with { option[_1] }
+    end
+  end
+
+  private
+
+  def type_from_default(default)
+    case default
+    when DEFAULT_OMITTED then String
+    when true, false then "Boolean"
+    when nil then "nil"
+    else
+      default.class
+    end
+  end
+end

data/app/models/showcase/page/sample.rb

@@ -0,0 +1,43 @@
+class Showcase::Page::Sample
+  attr_reader :name, :id, :events, :details
+  attr_reader :source
+
+  def initialize(view_context, name, description: nil, id: name.parameterize, events: nil, **details)
+    @view_context = view_context
+    @name, @id, @details = name, id, details
+    @events = Array(events)
+    description description if description
+  end
+
+  def description(content = nil, &block)
+    @description = content || @view_context.capture(&block) if content || block_given?
+    @description
+  end
+
+  def collect(&block)
+    preview(&block)
+    extract(&block)
+  end
+
+  def preview(&block)
+    block_given? ? @preview = @view_context.capture(&block) : @preview
+  end
+
+  def extract(&block)
+    @source = Showcase.sample_renderer.call \
+      extract_block_lines_via_matched_indentation_from(*block.source_location)
+  end
+
+  private
+
+  def extract_block_lines_via_matched_indentation_from(file, starting_index)
+    first_line, *lines = File.readlines(file).from(starting_index - 1)
+
+    indentation = first_line.match(/^\s+(?=<%)/).to_s
+    matcher = /^#{indentation}\S/
+
+    index = lines.index { _1.match?(matcher) }
+    lines.slice!(index..) if index
+    lines
+  end
+end

data/app/models/showcase/page.rb

@@ -0,0 +1,45 @@
+class Showcase::Page
+  autoload :Sample,  "showcase/page/sample"
+  autoload :Options, "showcase/page/options"
+
+  attr_reader :id, :badges, :samples
+
+  def initialize(view_context, id:, title: nil)
+    @view_context, @id = view_context, id
+    @badges, @samples = [], []
+    title title
+  end
+
+  def title(content = nil)
+    @title = content if content
+    @title
+  end
+
+  def description(content = nil, &block)
+    @description = content || @view_context.capture(&block) if content || block_given?
+    @description
+  end
+
+  def badge(*badges)
+    @badges.concat badges
+  end
+
+  def sample(name, **options, &block)
+    @samples << sample = Sample.new(@view_context, name, **options)
+
+    if block.arity.zero?
+      sample.collect(&block)
+    else
+      @view_context.capture(sample, &block)
+    end
+  end
+
+  def options
+    @options ||= Options.new(@view_context).tap { yield _1 if block_given? }
+  end
+
+  def render_template
+    @view_context.render template: id, prefixes: [Showcase.templates_path], locals: { showcase: self }
+    nil
+  end
+end

data/app/models/showcase/path.rb

@@ -0,0 +1,30 @@
+class Showcase::Path
+  class Tree < Struct.new(:id, :paths)
+    def name
+      root? ? "Pages" : id
+    end
+
+    def root?
+      id == "."
+    end
+  end
+
+  def self.tree
+    all.group_by(&:dirname).map { Tree.new _1, _2 }
+  end
+
+  def self.all
+    Showcase.filenames.map { new _1 }.sort_by!(&:id)
+  end
+
+  attr_reader :id, :dirname, :basename
+
+  def initialize(path)
+    @id = path.split(".").first
+    @dirname, @basename = File.split(@id)
+  end
+
+  def page_for(view_context)
+    Showcase::Page.new(view_context, id: id, title: basename.titleize).tap(&:render_template)
+  end
+end

data/app/views/layouts/showcase.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Showcase</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+
+    <%= stylesheet_link_tag    "application", "showcase" %>
+    <%= javascript_include_tag "application", "showcase" %>
+  </head>
+
+  <body>
+    <%= render "showcase/root" %>
+  </body>
+</html>

data/app/views/showcase/_root.html.erb

@@ -0,0 +1,13 @@
+<main class="flex flex-wrap">
+  <section class="grid grid-cols-12 w-full">
+    <nav class="col-span-3 xl:col-span-2 py-5 h-full border-r">
+      <h1 class="font-black text-2xl py-2 pl-4 cursor-pointer"><%= link_to "Showcase", root_url %></h1>
+
+      <%= render partial: "showcase/path/tree", collection: Showcase::Path.tree %>
+    </nav>
+
+    <section class="col-span-9 xl:col-span-10 w-full min-h-screen p-12 pt-7">
+      <%= yield %>
+    </section>
+  </section>
+</main>

data/app/views/showcase/pages/_options.html.erb

@@ -0,0 +1,27 @@
+<section class="w-full overflow-x-auto">
+  <h2 class="text-xl font-semibold mb-2">Options</h2>
+
+  <table class="table border-collapse border border-gray-200">
+    <thead>
+      <tr class="bg-slate-50">
+        <% options.headers.each do |header| %>
+          <th class="px-4 py-2"><%= header.to_s.humanize %></th>
+        <% end %>
+      </tr>
+    </thead>
+
+    <tbody>
+      <% options.each do |option| %>
+        <tr class="border-t border-gray-200">
+          <% option.each do |key, value| %>
+            <% if key == :required %>
+              <td class="p-4"><%= tag.input type: :checkbox, checked: value, disabled: true if value %></td>
+            <% else %>
+              <td class="p-4"><%= tag.pre value %></td>
+            <% end %>
+          <% end %>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</section>

data/app/views/showcase/pages/_page.html.erb

@@ -0,0 +1,26 @@
+<div class="space-y-8">
+  <section>
+    <% if page.title %>
+      <div class="flex items-center space-x-2 mb-2">
+        <h2 class="font-semibold text-3xl"><%= page.title %></h2>
+
+        <%# TODO: Insert default badge support here. %>
+      </div>
+    <% end %>
+
+    <% if page.description %>
+      <p class="font-normal text-base"><%= page.description %></p>
+    <% end %>
+  </section>
+
+  <% if page.samples.any? %>
+    <section>
+      <h2 class="font-semibold text-xl mb-2">Samples</h2>
+      <%= render partial: "showcase/pages/sample", collection: page.samples %>
+    </section>
+  <% end %>
+
+  <% if options = page.options.presence %>
+    <%= render "showcase/pages/options", options: options %>
+  <% end %>
+</div>

data/app/views/showcase/pages/_sample.html.erb

@@ -0,0 +1,37 @@
+<section class="mb-4 border border-gray-200 rounded-md">
+  <showcase-sample id="<%= sample.id %>" events="<%= sample.events %>">
+    <header class="bg-slate-100/50">
+      <h3 class="px-4 py-2 font-medium text-base md:text-lg leading-snug truncate"><%= link_to sample.name, "##{sample.id}" %></h3>
+
+      <% if sample.description %>
+        <p class="px-4 py-2 text-base"><%= sample.description %></p>
+      <% end %>
+    </header>
+
+    <% if sample.preview %>
+      <section class="px-4 py-2 border border-gray-200 border-0 border-b">
+        <%= sample.preview %>
+      </section>
+    <% end %>
+
+    <% if sample.source %>
+      <details>
+        <summary class="px-4 py-2 hover:bg-indigo-50 cursor-pointer select-none">View Source</summary>
+
+        <section class="px-4 py-2 relative overflow-hidden hover:select-all">
+          <%= sample.source %>
+        </section>
+      </details>
+    <% end %>
+
+    <% if sample.events.any? %>
+      <section class="px-4 py-2 font-small bg-slate-50">
+        <h4 class="mb-2 font-medium text-base">JavaScript Events</h4>
+
+        <div class="overflow-scroll max-h-20">
+          <pre data-showcase-sample-target="relay"></pre>
+        </div>
+      </section>
+    <% end %>
+  </showcase-sample>
+</section>

data/app/views/showcase/pages/index.html.erb

@@ -0,0 +1,33 @@
+<article class="space-y-4 font-normal text-base">
+  <p class="font-normal text-xl">👋  Welcome to <span class="italic">Showcase</span> — the UI Pattern Library!</p>
+
+  <section class="space-y-4">
+    <h2 class="font-semibold text-2xl">What is this thing?</h2>
+    <p>This resource is intended to be a hub for all-things UI for your developers, with the goal of <span class="italic font-semibold">sharing knowledge</span>, <span class="italic font-semibold">promoting reuse of existing code</span>, and <span class="italic font-semibold">ensuring consistency</span> across your application.</p>
+  </section>
+
+  <section class="space-y-4">
+    <h2 class="font-semibold text-2xl">How do I use it?</h2>
+    <p>On each page, you can add a series of usage examples for each component, style, or pattern. In the samples blocks, you'll see a live preview, as well as the source used to produce the example.</p>
+    <p>At the bottom of most pages, you will see a table, listing any options for configuring the partial or component.</p>
+  </section>
+
+  <section class="space-y-4">
+    <h2 class="font-semibold text-2xl">But I don't see the thing I need 🤔</h2>
+    <p>If you don't see the pattern or component here, that doesn't mean it doesn't aleady exist or can't be created with some combination of existing building blocks.</p>
+  </section>
+
+  <section class="space-y-4">
+    <h2 class="font-semibold text-2xl">I have questions, who do I reach out to?</h2>
+    <p>If you need help or have questions, please reach out to <%#= Showcase.links.support %>.</p>
+  </section>
+
+  <section class="space-y-4">
+    <h2 class="font-semibold text-2xl">Additional resources</h2>
+    <ul class="list-none">
+      <li>
+        <%= link_to "Bullet Train field partials documentation", "https://bullettrain.co/docs/field-partials", target: "_blank" %>
+      </li>
+    </ul>
+  </section>
+</article>

data/app/views/showcase/pages/show.html.erb

@@ -0,0 +1 @@
+<%= render "showcase/pages/page", page: @page %>

data/app/views/showcase/path/_tree.html.erb

@@ -0,0 +1,9 @@
+<details open class="flex flex-col">
+  <%= tag.summary tree.name.titleize, class: "hover:bg-indigo-50 font-medium text-black text-base py-2 pl-4 cursor-pointer" %>
+
+  <% tree.paths.each do |path| %>
+    <article class="hover:bg-indigo-50 <%= "bg-indigo-50" if path.id == params[:id] %>">
+      <%= link_to path.basename.titleize, page_path(path.id), class: "inline-block py-2 px-8 w-full" %>
+    </article>
+  <% end %>
+</details>

data/config/routes.rb

@@ -0,0 +1,4 @@
+Showcase::Engine.routes.draw do
+  get "pages/*id", to: "pages#show", as: :page
+  root to: "pages#index"
+end

data/config/tailwind.config.js

@@ -0,0 +1,22 @@
+const defaultTheme = require('tailwindcss/defaultTheme')
+
+module.exports = {
+  content: [
+    './public/*.html',
+    './app/helpers/**/*.rb',
+    './app/javascript/**/*.js',
+    './app/views/**/*.{erb,haml,html,slim}'
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: defaultTheme.fontFamily.sans,
+      },
+    },
+  },
+  plugins: [
+    require('@tailwindcss/forms'),
+    require('@tailwindcss/aspect-ratio'),
+    require('@tailwindcss/typography'),
+  ]
+}

data/lib/showcase/engine.rb

@@ -0,0 +1,9 @@
+module Showcase
+  class Engine < ::Rails::Engine
+    isolate_namespace Showcase
+
+    initializer "showcase.assets" do |app|
+      app.config.assets.precompile += %w[showcase_manifest]
+    end
+  end
+end

data/lib/showcase/version.rb

@@ -0,0 +1,3 @@
+module Showcase
+  VERSION = "0.1.0"
+end

data/lib/showcase.rb

@@ -0,0 +1,16 @@
+require "showcase/version"
+require "showcase/engine"
+
+module Showcase
+  singleton_class.attr_accessor :templates_directory_prefix, :sample_renderer
+  @templates_directory_prefix = ""
+  @sample_renderer = ->(lines) { lines.join }
+
+  def self.templates_path
+    @templates_path ||= File.join(templates_directory_prefix, "showcase/pages/templates").delete_prefix("/")
+  end
+
+  def self.filenames
+    Dir.glob("**/*.*", base: Rails.root.join("app/views", templates_path))
+  end
+end

data/lib/tasks/showcase_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :showcase do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: showcase-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Pence
+- Kasper Timm Hansen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-12-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.0
+- !ruby/object:Gem::Dependency
+  name: tailwindcss-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- hey@kaspth.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/builds/showcase.css
+- app/assets/config/showcase_manifest.js
+- app/assets/javascripts/showcase.js
+- app/controllers/showcase/application_controller.rb
+- app/controllers/showcase/pages_controller.rb
+- app/models/showcase/page.rb
+- app/models/showcase/page/options.rb
+- app/models/showcase/page/sample.rb
+- app/models/showcase/path.rb
+- app/views/layouts/showcase.html.erb
+- app/views/showcase/_root.html.erb
+- app/views/showcase/pages/_options.html.erb
+- app/views/showcase/pages/_page.html.erb
+- app/views/showcase/pages/_sample.html.erb
+- app/views/showcase/pages/index.html.erb
+- app/views/showcase/pages/show.html.erb
+- app/views/showcase/path/_tree.html.erb
+- config/routes.rb
+- config/tailwind.config.js
+- lib/showcase.rb
+- lib/showcase/engine.rb
+- lib/showcase/version.rb
+- lib/tasks/showcase_tasks.rake
+homepage: https://github.com/kaspth/showcase
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kaspth/showcase
+  source_code_uri: https://github.com/kaspth/showcase
+  changelog_uri: https://github.com/kaspth/showcase/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.24
+signing_key:
+specification_version: 4
+summary: Showcase helps you show off and document your partials, components, view
+  helpers and Stimulus controllers.
+test_files: []