proscenium-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca2623aea45e90824299d7c043f1ed80814fc18dea6598c43a798cc9afa33a7f
+  data.tar.gz: 8c4140e7664ad61705fee670455761b2ccef3aa429b149c5733f14e374eff45a
+SHA512:
+  metadata.gz: 83809d6e7fbe7a7bf033ef58a68468c690abe17034e1327ba326dea1d13218a571988a621c23ce339bab0ecb04345084c605cd658e20ec80cb35d9dd9e06ba8f
+  data.tar.gz: 407fee2ddd35600f3722b2abb7b3794288248c0b07ff666fb318555bbb51826e4c84c721b0e24c4750e6dbb07fdfc5100a3241f8b840b38d816664efa76340ce

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Joel Moss
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,28 @@
+# Proscenium::UI
+Short description and motivation.
+
+## Usage
+How to use my plugin.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "proscenium-ui"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install proscenium-ui
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/proscenium/ui/badge/index.css

@@ -0,0 +1,75 @@
+@layer pui {
+  pui-badge {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: baseline;
+    gap: 0.25em;
+    padding: 0.15em 0.5em;
+    border-radius: 0.25em;
+    font-size: 0.875em;
+    font-variant-numeric: tabular-nums;
+    line-height: 1.4;
+    white-space: nowrap;
+    background-color: var(--puiBadge--bg, color-mix(in srgb, currentColor 10%, transparent));
+    color: var(--puiBadge--color, inherit);
+    border: var(--puiBadge--border, 1px solid color-mix(in srgb, currentColor 20%, transparent));
+
+    &[data-size='sm'] {
+      font-size: 0.75em;
+      padding: 0.1em 0.35em;
+    }
+
+    &[data-size='lg'] {
+      font-size: 1em;
+      padding: 0.2em 0.6em;
+    }
+
+    &[data-variant='success'] {
+      background-color: var(
+        --puiBadge--success-bg,
+        color-mix(in srgb, light-dark(#15803d, #4ade80) 15%, transparent)
+      );
+      color: var(--puiBadge--success-color, light-dark(#15803d, #4ade80));
+      border-color: var(
+        --puiBadge--success-border-color,
+        color-mix(in srgb, light-dark(#15803d, #4ade80) 30%, transparent)
+      );
+    }
+
+    &[data-variant='warning'] {
+      background-color: var(
+        --puiBadge--warning-bg,
+        color-mix(in srgb, light-dark(#a16207, #fbbf24) 15%, transparent)
+      );
+      color: var(--puiBadge--warning-color, light-dark(#a16207, #fbbf24));
+      border-color: var(
+        --puiBadge--warning-border-color,
+        color-mix(in srgb, light-dark(#a16207, #fbbf24) 30%, transparent)
+      );
+    }
+
+    &[data-variant='danger'] {
+      background-color: var(
+        --puiBadge--danger-bg,
+        color-mix(in srgb, light-dark(#dc2626, #f87171) 15%, transparent)
+      );
+      color: var(--puiBadge--danger-color, light-dark(#dc2626, #f87171));
+      border-color: var(
+        --puiBadge--danger-border-color,
+        color-mix(in srgb, light-dark(#dc2626, #f87171) 30%, transparent)
+      );
+    }
+
+    &[data-variant='info'] {
+      background-color: var(
+        --puiBadge--info-bg,
+        color-mix(in srgb, light-dark(#2563eb, #60a5fa) 15%, transparent)
+      );
+      color: var(--puiBadge--info-color, light-dark(#2563eb, #60a5fa));
+      border-color: var(
+        --puiBadge--info-border-color,
+        color-mix(in srgb, light-dark(#2563eb, #60a5fa) 30%, transparent)
+      );
+    }
+  }
+}

data/lib/proscenium/ui/badge.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Proscenium::UI
+  class Badge < Component
+    register_element :pui_badge
+
+    # @param text [String] The text content of the badge.
+    prop :text, String, :positional
+
+    # @param variant [Symbol] The visual style variant. (:default, :success, :warning, :danger,
+    # :info)
+    prop :variant, _Union(:default, :success, :warning, :danger, :info), default: -> { :default }
+
+    # @param size [Symbol] The size of the badge. (:sm, :md, :lg)
+    prop :size, _Union(:sm, :md, :lg), default: -> { :md }
+
+    # @param rest [Hash] Additional HTML attributes passed to the root element.
+    prop :rest, Hash, :**
+
+    def self.source_path
+      super.sub_ext('').join('index.rb')
+    end
+
+    def view_template
+      data = {}
+      data[:variant] = @variant if @variant != :default
+      data[:size] = @size if @size != :md
+
+      pui_badge(**{ data: }.deep_merge(@rest)) { @text }
+    end
+  end
+end

data/lib/proscenium/ui/breadcrumbs/computed_element.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+class Proscenium::UI::Breadcrumbs
+  class ComputedElement
+    def initialize(element, context)
+      @element = element
+      @context = context
+    end
+
+    delegate :options, to: :@element
+
+    # If name is a Symbol of a controller method, that method is called.
+    # If name is a Symbol of a controller instance variable, that variable is returned.
+    # If name is a Proc, it is executed in the context of the controller instance.
+    #
+    # @return [String] the content of the breadcrumb element.
+    def name
+      @name ||= case name = @element.name
+                when Symbol
+                  if name.to_s.starts_with?('@')
+                    name = get_instance_variable(name)
+                    name.respond_to?(:for_breadcrumb) ? name.for_breadcrumb : name.to_s
+                  else
+                    res = @context.controller.send(name)
+                    res.try(:for_breadcrumb) || res.to_s
+                  end
+                when Proc
+                  @context.controller.instance_exec(&name)
+                else
+                  name.respond_to?(:for_breadcrumb) ? name.for_breadcrumb : name.to_s
+                end
+    end
+
+    # If path is a Symbol of a controller method, that method is called.
+    # If path is a Symbol of a controller instance variable, that variable is returned.
+    # If path is an Array, each element is processed as above.
+    # If path is a Proc, it is executed in the context of the controller instance.
+    #
+    # No matter what, the result is always passed to `url_for` before being returned.
+    #
+    # @return [String] the URL for the element
+    def path
+      @path ||= if !@element.path.nil?
+                  case path = @element.path
+                  when Array
+                    path.map! { |x| x.to_s.starts_with?('@') ? get_instance_variable(x) : x }
+                  when Symbol
+                    if path.to_s.starts_with?('@')
+                      path = get_instance_variable(path)
+                    elsif @context.controller.respond_to?(path, true)
+                      path = @context.controller.send(path)
+                    end
+                  when Proc
+                    path = @context.controller.instance_exec(&path)
+                  end
+
+                  @context.url_for path
+                end
+    end
+
+    private
+
+      def get_instance_variable(element)
+        if !@context.instance_variable_defined?(element)
+          raise NameError, "undefined instance variable `#{element}' for breadcrumb", caller
+        end
+
+        @context.instance_variable_get element
+      end
+  end
+end

data/lib/proscenium/ui/breadcrumbs/control.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+class Proscenium::UI::Breadcrumbs
+  # Include this module in your controller to add support for adding breadcrumb elements. You can
+  # then use the `add_breadcrumb` and `prepend_breadcrumb` class methods to append and/or prepend
+  # breadcrumb elements.
+  module Control
+    extend ActiveSupport::Concern
+    include ActionView::Helpers::SanitizeHelper
+
+    included do
+      helper_method :breadcrumbs_as_json, :breadcrumbs_for_title if respond_to?(:helper_method)
+    end
+
+    module ClassMethods
+      # Appends a new breadcrumb element into the collection.
+      #
+      # @param name [String, Symbol, Proc, #for_breadcrumb] The name or content of the breadcrumb.
+      # @param path [String, Symbol, Array, Proc, nil] The path (route) to use as the HREF for the
+      #   breadcrumb.
+      # @param options [Hash] Filter options to pass through to the before_action filter. Options
+      #   include :if, :unless, :only, and :except. Any options not included in the filter options
+      #   will be passed as options to the breadcrumb element. For example, you could pass a :class
+      #   option to add a CSS class to the breadcrumb element.
+      def add_breadcrumb(name, path = nil, **options)
+        filter_options = options.slice(:if, :unless, :only, :except)
+        element_options = options.except(:if, :unless, :only, :except)
+
+        before_action(filter_options) do |controller|
+          controller.send :add_breadcrumb, name, path, element_options
+        end
+      end
+
+      # Prepend a new breadcrumb element into the collection.
+      #
+      # @param name [String, Symbol, Proc, #for_breadcrumb] The name or content of the breadcrumb.
+      # @param path [String, Symbol, Array, Proc, nil] The path (route) to use as the HREF for the
+      #   breadcrumb.
+      # @param options [Hash] Filter options to pass through to the before_action filter. Options
+      #   include :if, :unless, :only, and :except. Any options not included in the filter options
+      #   will be passed as options to the breadcrumb element. For example, you could pass a :class
+      #   option to add a CSS class to the breadcrumb element.
+      def prepend_breadcrumb(name, path = nil, **options)
+        filter_options = options.slice(:if, :unless, :only, :except)
+        element_options = options.except(:if, :unless, :only, :except)
+
+        before_action(filter_options) do |controller|
+          controller.send :prepend_breadcrumb, name, path, element_options
+        end
+      end
+    end
+
+    # Pushes a new breadcrumb element into the collection.
+    #
+    # @param name [String, Symbol, Proc, #for_breadcrumb] The name or content of the breadcrumb.
+    # @param path [String, Symbol, Array, Proc, nil] The path (route) to use as the HREF for the
+    #   breadcrumb.
+    # @param options [Hash]
+    def add_breadcrumb(name, path = nil, options = {})
+      breadcrumbs << Element.new(name, path, options)
+    end
+
+    # Prepend a new breadcrumb element into the collection.
+    #
+    # @param name [String, Symbol, Proc, #for_breadcrumb] The name or content of the breadcrumb.
+    # @param path [String, Symbol, Array, Proc, nil] The path (route) to use as the HREF for the
+    #   breadcrumb.
+    # @param options [Hash]
+    def prepend_breadcrumb(name, path = nil, options = {})
+      breadcrumbs.prepend Element.new(name, path, options)
+    end
+
+    def breadcrumbs
+      @breadcrumbs ||= []
+    end
+
+    def breadcrumbs_as_json
+      computed_breadcrumbs.map do |ele|
+        path = ele.path
+
+        { name: ele.name, path: ele.path.nil? || view_context.current_page?(path) ? nil : path }
+      end
+    end
+
+    # @param primary [Boolean] whether to return only the primary breadcrumb.
+    def breadcrumbs_for_title(primary: false)
+      names = computed_breadcrumbs.map(&:name)
+      return names.pop if primary
+
+      out = [names.pop]
+      out << names.join(': ') if !names.empty?
+      strip_tags out.join(' - ')
+    end
+
+    private
+
+      def computed_breadcrumbs
+        @computed_breadcrumbs ||= breadcrumbs.map do |ele|
+          ComputedElement.new ele, view_context
+        end
+      end
+  end
+end

data/lib/proscenium/ui/breadcrumbs/element.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Represents a navigation element in the breadcrumb collection.
+class Proscenium::UI::Breadcrumbs::Element
+  attr_accessor :name, :path, :options
+
+  # @param  name [String] the element/link name
+  # @param  path [String] the element/link URL
+  # @param  options [Hash] the element/link options
+  # @return [Element]
+  def initialize(name, path = nil, options = {})
+    self.name = name
+    self.path = path
+    self.options = options
+  end
+end

data/lib/proscenium/ui/breadcrumbs/index.css

@@ -0,0 +1,84 @@
+@define-mixin _separator {
+  display: inline-block;
+  content: '';
+  height: 1em;
+  width: 1em;
+  -webkit-mask: var(--puiBreadcrumbs--separator, var(--_puiBreadcrumbs--separator)) no-repeat center
+    center;
+  mask: var(--puiBreadcrumbs--separator, var(--_puiBreadcrumbs--separator)) no-repeat center center;
+  vertical-align: sub;
+  background-color: var(--puiBreadcrumbs--separator-color, var(--_puiBreadcrumbs--separator-color));
+}
+
+@layer pui {
+  /*
+   * Properties:
+   *
+   *   --puiBreadcrumbs--link-color: LinkText;
+   *   --puiBreadcrumbs--link-hover-color: HighlightText;
+   *   --puiBreadcrumbs--separator-color: GrayText;
+   *   --puiBreadcrumbs--separator: url("...");
+   */
+
+  pui-breadcrumbs {
+    --_puiBreadcrumbs--separator-color: GrayText;
+    --_puiBreadcrumbs--separator: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20' fill='currentColor'%3E%3Cpath fill-rule='evenodd' d='M8.22 5.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L11.94 10 8.22 6.28a.75.75 0 0 1 0-1.06Z' clip-rule='evenodd'/%3E%3C/svg%3E");
+
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+
+    pui-breadcrumbs-home,
+    pui-breadcrumbs-element {
+      text-transform: uppercase;
+      display: flex;
+      align-items: center;
+
+      @media (max-width: 426px) {
+        &:not(:nth-last-child(2)) {
+          display: none;
+        }
+
+        &:nth-last-child(2)::before {
+          @mixin _separator;
+          margin: 0 0.5em 0 0;
+          transform: rotate(180deg);
+        }
+      }
+
+      @media (min-width: 427px) {
+        &:not(:last-child)::after {
+          @mixin _separator;
+          margin: 0 0.5em;
+        }
+      }
+
+      &:last-child,
+      &:last-child > a {
+        font-weight: 500;
+        text-transform: none;
+      }
+
+      a {
+        color: var(--puiBreadcrumbs--link-color, revert);
+        display: flex;
+        align-items: center;
+
+        &:hover {
+          color: var(--puiBreadcrumbs--link-hover-color, revert);
+        }
+
+        @media (pointer: coarse) {
+          min-height: 44px;
+        }
+      }
+    }
+
+    pui-breadcrumbs-home {
+      svg {
+        height: 1em;
+        width: 1em;
+      }
+    }
+  }
+}

data/lib/proscenium/ui/breadcrumbs.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Proscenium::UI
+  # Provides breadcrumb functionality for controllers and views. Breadcrumbs are a type of
+  # navigation that show the user where they are in the application's hierarchy.
+  # The `Proscenium::UI::Breadcrumbs::Control` module provides the `add_breadcrumb` and
+  # `prepend_breadcrumb` class methods for adding breadcrumb elements, and is intended to be
+  # included in your controllers.
+  #
+  # The `add_breadcrumb` method adds a new breadcrumb element to the end of the collection, while
+  # the `prepend_breadcrumb` method adds a new breadcrumb element to the beginning of the
+  # collection. Both methods take a name, and path as arguments. The name argument is the name or
+  # content of the breadcrumb, while the path argument is the path (route) to use as the HREF for
+  # the breadcrumb.
+  #
+  #   class UsersController < ApplicationController
+  #     include Proscenium::UI::Breadcrumbs::Control
+  #     add_breadcrumb 'Users', :users_path
+  #   end
+  #
+  # Display the breadcrumbs in your view:
+  #
+  #   render Proscenium::UI::Breadcrumbs
+  #
+  # At its simplest, you can add a breadcrumb with a name of "Users", and a path of "/users" like
+  # this:
+  #
+  #   add_breadcrumb 'Users', '/users'
+  #
+  # The value of the path is always passed to `url_for` before being rendered. It is also optional,
+  # and if omitted, the breadcrumb will be rendered as plain text.
+  #
+  # Both name and path can be given a Symbol, which can be used to call a method of the same name on
+  # the controller. If a Symbol is given as the path, and no method of the same name exists, then
+  # `url_for` will be called with the Symbol as the argument. Likewise, if an Array is given as the
+  # path, then `url_for` will be called with the Array as the argument.
+  #
+  # If a Symbol is given as the path or name, and it begins with `@` (eg. `:@foo`), then the
+  # instance variable of the same name will be called.
+  #
+  #   add_breadcrumb :@foo, :@bar
+  #
+  # A Proc can also be given as the name and/or path. The Proc will be called within the context of
+  # the controller.
+  #
+  #   add_breadcrumb -> { @foo }, -> { @bar }
+  #
+  # Passing an object that responds to `#for_breadcrumb` as the name will call that method on the
+  # object to get the breadcrumb name.
+  #
+  class Breadcrumbs < Component
+    include Phlex::Rails::Helpers::URLFor
+
+    register_element :pui_breadcrumbs
+    register_element :pui_breadcrumbs_home
+    register_element :pui_breadcrumbs_element
+
+    # @param home_path [String, Symbol] The path (route) to use as the HREF for the home segment.
+    prop :home_path, _Union(String, Symbol), default: -> { :root }
+
+    # @param with_home [Boolean] Whether to show the home segment. Set to false to hide it.
+    prop :with_home, _Boolean, default: -> { true }
+
+    def self.source_path
+      super.sub_ext('').join('index.rb')
+    end
+
+    # TODO: For if and when we need to pass instance level css module.
+    #
+    # prop :css_module_path, _Nilable(Pathname)
+    #
+    # def css_module_path
+    #   @css_module_path ||= self.class.css_module_path
+    # end
+
+    def view_template
+      pui_breadcrumbs do
+        if @with_home
+          pui_breadcrumbs_home do
+            yield if block_given?
+            home_template
+          end
+        end
+
+        breadcrumbs.each do |ce|
+          pui_breadcrumbs_element(**ce.options) do
+            path = ce.path
+            path.nil? ? ce.name : a(href: url_for(path)) { ce.name }
+          end
+        end
+      end
+    end
+
+    # Override this to customise the home breadcrumb. You can call super with a block to use the
+    # default template, but with custom content.
+    #
+    # @example
+    #  def home_template
+    #    super { 'hello' }
+    #  end
+    def home_template(&block)
+      a href: url_for(@home_path) do
+        if block
+          yield
+        else
+          svg role: 'img', aria_label: 'Home', xmlns: 'http://www.w3.org/2000/svg',
+              viewBox: '0 0 24 24', fill: 'currentColor' do |s|
+            s.path d: <<~SVG.delete("\n")
+              M11.47 3.841a.75.75 0 0 1 1.06 0l8.69 8.69a.75.75 0 1 0 1.06-1.061l-8.689
+              -8.69a2.25 2.25 0 0 0-3.182 0l-8.69 8.69a.75.75 0 1 0 1.061 1.06l8.69-8.69Z
+            SVG
+            s.path d: <<~SVG.delete("\n")
+              M12 5.432l8.159 8.159c.03.03.06.058.091.086v6.198c0 1.035-.84 1.875-1.875
+              1.875H15.75a.75.75 0 0 1-.75-.75v-4.5a.75.75 0 0 0-.75-.75h-4.5a.75.75 0 0
+              0-.75.75V21a.75.75 0 0 1-.75.75H5.625a1.875 1.875 0 0 1-1.875-1.875v-6.198
+              a2.29 2.29 0 0 0 .091-.086L12 5.432Z
+            SVG
+          end
+        end
+      end
+    end
+
+    # Don't render if @hide_breadcrumbs is true.
+    def render?
+      controller.instance_variable_get(:@hide_breadcrumbs) != true
+    end
+
+    private
+
+      def breadcrumbs
+        controller.breadcrumbs.map do |e|
+          Breadcrumbs::ComputedElement.new e, view_context
+        end
+      end
+  end
+end