proscenium 0.15.0.beta.4-x86_64-linux → 0.15.0.beta.5-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93000fde1226789c26de17f4d0d075412e9be6e7733be78580f16474776c5dd7
-  data.tar.gz: d76651fcd12c177882a28bf5652dd137727020a9d3f4d71c022510d67c09565e
+  metadata.gz: b32b5cbadeca029ce04a376125a924b059d388b60e90835b9a8e6d7a152a9c72
+  data.tar.gz: ff4a5b0ca38e8b028313f1a4bfc6fc214a11f2bf3cd6a49f89125d15ba26190f
 SHA512:
-  metadata.gz: 196e4a7b647e0a7e0c61ee3c359661287ead2fa709c7e844fac398a812e988d593a094ba0b58219ac474cdfa9e83961e99cb494183656ec022804ccd4663b8bd
-  data.tar.gz: 316e36fe6fda602134a282d738003d953459252f959ab4d875ca6adcf4d87c39f93e085b495fab880faffd873c52a592ad7b6950593c21d944c21a3ca4d30a6f
+  metadata.gz: 3b900744ef723e3cb4d6d7c83a242d8fd8635d72fdcd7b297df131db407def41f934641125c230bc4feeab3a8694710d6300804558812bd8374dc1e4fb93618a
+  data.tar.gz: b24280e853b5d57051af8f681d3b4b7923902dcb45226451fa8e01663c3025dc94987c534ddc740a08936a46a6a3ac14935ebbf08fefe2c732431c08e37cffce

data/README.md

@@ -681,7 +681,7 @@ console.log(version);
 
 ```ruby
 class MyView < Proscenium::Phlex
-  def template
+  def view_template
     h1 { 'Hello World' }
   end
 end
@@ -693,7 +693,7 @@ In your layouts, include `Proscenium::Phlex::AssetInclusions`, and call the `inc
 class ApplicationLayout < Proscenium::Phlex
   include Proscenium::Phlex::AssetInclusions # <--
 
-  def template(&)
+  def view_template(&)
     doctype
     html do
       head do
@@ -721,7 +721,7 @@ Within your Phlex classes, any class names that begin with `@` will be treated a
 ```ruby
 # /app/views/users/show_view.rb
 class Users::ShowView < Proscenium::Phlex
-  def template
+  def view_template
     h1 class: :@user_name do
       @user.name
     end
@@ -750,7 +750,7 @@ You can of course continue to reference regular class names in your view, and th
 ```ruby
 # /app/views/users/show_view.rb
 class Users::ShowView < Proscenium::Phlex
-  def template
+  def view_template
     h1 class: :[@user_name, :title] do
       @user.name
     end
@@ -785,7 +785,7 @@ Any ViewComponent class that inherits `Proscenium::ViewComponent` will automatic
 ```ruby
 # /app/components/user_component.rb
 class UserComponent < Proscenium::ViewComponent
-  def template
+  def view_template
     div.h1 @user.name, class: css_module(:user_name)
   end
 end

data/lib/proscenium/builder.rb

@@ -71,7 +71,7 @@ module Proscenium
           msg << " at #{location['file']}:#{location['line']}:#{location['column']}"
         end
 
-        super msg
+        super(msg)
       end
     end
 
@@ -79,7 +79,7 @@ module Proscenium
       attr_reader :error_msg, :path
 
       def initialize(path, error_msg)
-        super "Failed to resolve '#{path}' -- #{error_msg}"
+        super("Failed to resolve '#{path}' -- #{error_msg}")
       end
     end
 
@@ -100,7 +100,7 @@ module Proscenium
       @base_url = base_url
     end
 
-    def build_to_path(path) # rubocop:disable Metrics/AbcSize
+    def build_to_path(path)
       ActiveSupport::Notifications.instrument('build_to_path.proscenium',
                                               identifier: path,
                                               cached: Proscenium.cache.exist?(path)) do
@@ -163,7 +163,9 @@ module Proscenium
     end
 
     def engines
-      Proscenium.config.engines.to_h { |e| [e.engine_name, e.root.to_s] }
+      Proscenium.config.engines.to_h { |e| [e.engine_name, e.root.to_s] }.tap do |x|
+        x['proscenium/ui'] = Proscenium.ui_path.to_s
+      end
     end
 
     def import_map

data/lib/proscenium/libs/custom_element.js

@@ -0,0 +1,54 @@
+/**
+ * Base class for custom elements, providing support for event delegation, and idempotent
+ * customElement registration.
+ *
+ * The `handleEvent` method is called any time an event defined in `delegatedEvents` is triggered.
+ * It's a central handler to handle events for this custom element.
+ *
+ * @example
+ *   class MyComponent extends CustomElement {
+ *     static componentName = 'my-component'
+ *     static delegatedEvents = ['click']
+ *
+ *     handleEvent(event) {
+ *       console.log('Hello, world!')
+ *     }
+ *   }
+ *   MyComponent.register()
+ */
+export default class CustomElement extends HTMLElement {
+  /**
+   * Register the component as a custom element, inferring the component name from the kebab-cased
+   * class name. You can override the component name by setting a static `componentName` property.
+   *
+   * This method is idempotent.
+   */
+  static register() {
+    if (this.componentName === undefined) {
+      this.componentName = this.name
+        .replaceAll(/(.)([A-Z])/g, "$1-$2")
+        .toLowerCase();
+    }
+
+    if (!customElements.get(this.componentName)) {
+      customElements.define(this.componentName, this);
+    }
+  }
+
+  /**
+   * A list of event types to be delegated for the lifetime of the custom element.
+   *
+   * @type {Array}
+   */
+  static delegatedEvents = [];
+
+  constructor() {
+    super();
+
+    if (typeof this.handleEvent !== "undefined") {
+      this.constructor.delegatedEvents?.forEach((event) => {
+        this.addEventListener(event, this);
+      });
+    }
+  }
+}

data/lib/proscenium/libs/stimulus-loading.js

@@ -1,22 +1,9 @@
-const controllerAttribute = "data-controller";
-const controllerFilenameExtension = ".js";
+export function lazyLoadControllersFrom(under, app, element = document) {
+  const { controllerAttribute } = app.schema;
 
-export function lazyLoadControllersFrom(
-  under,
-  application,
-  element = document
-) {
-  lazyLoadExistingControllers(under, application, element);
-  lazyLoadNewControllers(under, application, element);
-}
-
-function lazyLoadExistingControllers(under, application, element) {
-  queryControllerNamesWithin(element).forEach((controllerName) =>
-    loadController(controllerName, under, application)
-  );
-}
+  lazyLoadExistingControllers(element);
 
-function lazyLoadNewControllers(under, application, element) {
+  // Lazy load new controllers.
   new MutationObserver((mutationsList) => {
     for (const { attributeName, target, type } of mutationsList) {
       switch (type) {
@@ -26,13 +13,13 @@ function lazyLoadNewControllers(under, application, element) {
             target.getAttribute(controllerAttribute)
           ) {
             extractControllerNamesFrom(target).forEach((controllerName) =>
-              loadController(controllerName, under, application)
+              loadController(controllerName)
             );
           }
         }
 
         case "childList": {
-          lazyLoadExistingControllers(under, application, target);
+          lazyLoadExistingControllers(target);
         }
       }
     }
@@ -41,43 +28,38 @@ function lazyLoadNewControllers(under, application, element) {
     subtree: true,
     childList: true,
   });
-}
 
-function queryControllerNamesWithin(element) {
-  return Array.from(element.querySelectorAll(`[${controllerAttribute}]`))
-    .map(extractControllerNamesFrom)
-    .flat();
-}
-
-function extractControllerNamesFrom(element) {
-  return element
-    .getAttribute(controllerAttribute)
-    .split(/\s+/)
-    .filter((content) => content.length);
-}
+  function lazyLoadExistingControllers(element) {
+    Array.from(element.querySelectorAll(`[${controllerAttribute}]`))
+      .map(extractControllerNamesFrom)
+      .flat()
+      .forEach(loadController);
+  }
 
-function loadController(name, under, application) {
-  if (canRegisterController(name, application)) {
-    import(controllerFilename(name, under))
-      .then((module) => registerController(name, module, application))
-      .catch((error) =>
-        console.error(`Failed to autoload controller: ${name}`, error)
-      );
+  function extractControllerNamesFrom(element) {
+    return element
+      .getAttribute(controllerAttribute)
+      .split(/\s+/)
+      .filter((content) => content.length);
   }
-}
 
-function controllerFilename(name, under) {
-  return `${under}/${name
-    .replace(/--/g, "/")
-    .replace(/-/g, "_")}_controller${controllerFilenameExtension}`;
-}
+  function loadController(name) {
+    if (canRegisterController(name)) {
+      const fileToImport = `${under}/${name
+        .replace(/--/g, "/")
+        .replace(/-/g, "_")}_controller.js`;
 
-function registerController(name, module, application) {
-  if (canRegisterController(name, application)) {
-    application.register(name, module.default);
+      import(fileToImport)
+        .then((module) => {
+          canRegisterController(name) && app.register(name, module.default);
+        })
+        .catch((error) =>
+          console.error(`Failed to autoload controller: ${name}`, error)
+        );
+    }
   }
-}
 
-function canRegisterController(name, application) {
-  return !application.router.modulesByIdentifier.has(name);
+  function canRegisterController(name) {
+    return !app.router.modulesByIdentifier.has(name);
+  }
 }

data/lib/proscenium/libs/ujs/class.js

@@ -3,15 +3,13 @@ import DataDisableWith from "./data_disable_with";
 
 export default class UJS {
   constructor() {
-    const dc = new DataConfirm();
-    const ddw = new DataDisableWith();
+    this.dc = new DataConfirm();
+    this.ddw = new DataDisableWith();
 
-    document.body.addEventListener(
-      "submit",
-      (event) => {
-        dc.onSubmit(event) && ddw.onSubmit(event);
-      },
-      { capture: true }
-    );
+    document.addEventListener("submit", this, { capture: true });
+  }
+
+  handleEvent(event) {
+    this.dc.onSubmit(event) && this.ddw.onSubmit(event);
   }
 }

data/lib/proscenium/middleware/base.rb

@@ -15,7 +15,7 @@ module Proscenium
         def initialize(args)
           @detail = args[:detail]
           @file = args[:file]
-          super "Failed to build '#{args[:file]}' -- #{detail}"
+          super("Failed to build '#{args[:file]}' -- #{detail}")
         end
       end
 

data/lib/proscenium/middleware/engines.rb

@@ -20,18 +20,26 @@ module Proscenium
     #
     class Engines < Esbuild
       def real_path
-        @real_path ||= Pathname.new(@request.path.delete_prefix("/#{engine.engine_name}")).to_s
+        @real_path ||= Pathname.new(@request.path.delete_prefix("/#{engine_name}")).to_s
       end
 
       def root_for_readable
-        engine.root
+        ui? ? Proscenium.ui_path : engine.root
       end
 
       def engine
-        @engine ||= Proscenium.config.engines.find do |engine|
-          @request.path.start_with?("/#{engine.engine_name}")
+        @engine ||= Proscenium.config.engines.find do |x|
+          @request.path.start_with?("/#{x.engine_name}")
         end
       end
+
+      def engine_name
+        ui? ? 'proscenium/ui' : engine.engine_name
+      end
+
+      def ui?
+        @request.path.start_with?('/proscenium/ui/')
+      end
     end
   end
 end

data/lib/proscenium/middleware/esbuild.rb

@@ -15,7 +15,7 @@ module Proscenium
                             detail[:text]
                           end
 
-          super args
+          super(args)
         end
       end
 

data/lib/proscenium/middleware.rb

@@ -45,17 +45,26 @@ module Proscenium
       return Runtime if request.path.match?(%r{^/@proscenium/})
       return Esbuild if Pathname.new(request.path).fnmatch?(app_path_glob, File::FNM_EXTGLOB)
 
-      Engines if Pathname.new(request.path).fnmatch?(engines_path_glob, File::FNM_EXTGLOB)
+      pathname = Pathname.new(request.path)
+      Engines if pathname.fnmatch?(ui_path_glob, File::FNM_EXTGLOB) ||
+                 pathname.fnmatch?(engines_path_glob, File::FNM_EXTGLOB)
     end
 
     def app_path_glob
-      "/{#{Proscenium::ALLOWED_DIRECTORIES}}/**.{#{FILE_EXTENSIONS.join(',')}}"
+      "/{#{Proscenium::ALLOWED_DIRECTORIES}}/**.{#{file_extensions}}"
     end
 
     def engines_path_glob
       names = Proscenium.config.engines.map(&:engine_name)
+      "/{#{names.join(',')}}/{#{Proscenium::ALLOWED_DIRECTORIES}}/**.{#{file_extensions}}"
+    end
+
+    def ui_path_glob
+      "/proscenium/ui/**.{#{file_extensions}}"
+    end
 
-      "/{#{names.join(',')}}/{#{Proscenium::ALLOWED_DIRECTORIES}}/**.{#{FILE_EXTENSIONS.join(',')}}"
+    def file_extensions
+      @file_extensions ||= FILE_EXTENSIONS.join(',')
     end
 
     # TODO: handle precompiled assets

data/lib/proscenium/phlex/css_modules.rb

@@ -40,7 +40,7 @@ module Proscenium
     #
     #   # app/components/user/component.rb
     #   class User::Component < Proscenium::Phlex
-    #     def template
+    #     def view_template
     #       div class: :@user_name do
     #         'Joel Moss'
     #       end
@@ -54,7 +54,7 @@ module Proscenium
     # add the CSS Module name `name` to the <div>.
     #
     #   class User::Component < Proscenium::Phlex
-    #     def template
+    #     def view_template
     #       div class: '/lib/users@name' do
     #         'Joel Moss'
     #       end

data/lib/proscenium/phlex/react_component.rb

@@ -18,14 +18,14 @@ module Proscenium
     # Override this to provide your own loading UI.
     #
     # @example
-    #   def template(**attributes, &block)
+    #   def view_template(**attributes, &block)
     #     super do
     #       'Look at me! I am loading now...'
     #     end
     #   end
     #
     # @yield the given block to a `div` within the top level component div.
-    def template(**attributes, &block)
+    def view_template(**attributes, &block)
       send root_tag, **{ data: data_attributes }.deep_merge(attributes), &block
     end
   end

data/lib/proscenium/railtie.rb

@@ -49,6 +49,12 @@ module Proscenium
       end
     end
 
+    initializer 'proscenium.ui' do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym 'UI'
+      end
+    end
+
     initializer 'proscenium.debugging' do
       if Rails.gem_version >= Gem::Version.new('7.1.0')
         tpl_path = root.join('lib', 'proscenium', 'templates').to_s
@@ -75,6 +81,16 @@ module Proscenium
         ActionView::PartialRenderer.prepend Monkey::PartialRenderer
       end
     end
+
+    initializer 'proscenium.public_path' do |app|
+      if app.config.public_file_server.enabled
+        headers = app.config.public_file_server.headers || {}
+        index = app.config.public_file_server.index_name || 'index'
+
+        app.middleware.insert_after(ActionDispatch::Static, ActionDispatch::Static,
+                                    root.join('public').to_s, index: index, headers: headers)
+      end
+    end
   end
 end
 

data/lib/proscenium/resolver.rb

@@ -23,6 +23,8 @@ module Proscenium
 
         if path.start_with?('@proscenium/')
           "/#{path}"
+        elsif path.start_with?(Proscenium.ui_path.to_s)
+          path.delete_prefix Proscenium.root.join('lib').to_s
         elsif (engine = Proscenium.config.engines.find { |e| path.start_with? "#{e.root}/" })
           path.sub(/^#{engine.root}/, "/#{engine.engine_name}")
         elsif path.start_with?("#{Rails.root}/")

data/lib/proscenium/side_load.rb

@@ -10,7 +10,7 @@ module Proscenium
 
           append_after_action :capture_and_replace_proscenium_stylesheets,
                               :capture_and_replace_proscenium_javascripts,
-                              if: -> { request.format.html? && !response.redirect? }
+                              if: -> { response.content_type&.include?('html') }
         end
       end
 
@@ -20,7 +20,7 @@ module Proscenium
         end
       end
 
-      def capture_and_replace_proscenium_stylesheets # rubocop:disable Metrics/*
+      def capture_and_replace_proscenium_stylesheets
         return if response_body.nil?
         return if response_body.first.blank? || !Proscenium::Importer.css_imported?
         return unless response_body.first.include? '<!-- [PROSCENIUM_STYLESHEETS] -->'
@@ -52,7 +52,7 @@ module Proscenium
         response_body.first.gsub! '<!-- [PROSCENIUM_STYLESHEETS] -->', out.join.html_safe
       end
 
-      def capture_and_replace_proscenium_javascripts # rubocop:disable Metrics/*
+      def capture_and_replace_proscenium_javascripts
         return if response_body.nil?
         return if response_body.first.blank? || !Proscenium::Importer.js_imported?
 
@@ -108,7 +108,7 @@ module Proscenium
       #
       # If the class responds to `.sideload`, it will be called instead of the regular side loading.
       # You can use this to customise what is side loaded.
-      def sideload_inheritance_chain(obj, options) # rubocop:disable Metrics/*
+      def sideload_inheritance_chain(obj, options)
         return unless Proscenium.config.side_load
 
         options = {} if options.nil?

data/lib/proscenium/ui/breadcrumbs/component.module.css

@@ -0,0 +1,14 @@
+@layer proscenium-ui-component {
+  /*
+   * Custom properties:
+   *
+   *   --puiBreadcrumbs--link-color: LinkText;
+   *   --puiBreadcrumbs--link-hover-color: HighlightText;
+   *   --puiBreadcrumbs--separator-color: GrayText;
+   *   --puiBreadcrumbs--separator: url("/proscenium/icons/angle-right-regular.svg");
+   */
+
+  .base {
+    @mixin breadcrumbs from url("./mixins.css");
+  }
+}

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Proscenium::UI
+  class Breadcrumbs::Component < Component
+    include Phlex::Rails::Helpers::URLFor
+
+    # The path (route) to use as the HREF for the home segment. Defaults to `:root`.
+    option :home_path, Types::String | Types::Symbol, default: -> { :root }
+
+    # Assign false to hide the home segment.
+    option :with_home, Types::Bool, default: -> { true }
+
+    # One or more class name(s) for the base div element which will be appended to the default.
+    option :class, Types::Coercible::String | Types::Array.of(Types::Coercible::String),
+           as: :class_name, default: -> { [] }
+
+    # One or more class name(s) for the base div element which will replace the default. If both
+    # `class` and `class!` are provided, all values will be merged. Defaults to `:@base`.
+    option :class!, Types::Coercible::String | Types::Array.of(Types::Coercible::String),
+           as: :class_name_override, default: -> { :@base }
+
+    def view_template
+      div class: [*class_name_override, *class_name] do
+        ol do
+          if with_home
+            li do
+              home_template
+            end
+          end
+
+          breadcrumbs.each do |ce|
+            li do
+              path = ce.path
+              path.nil? ? ce.name : a(href: url_for(path)) { ce.name }
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    # 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', xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 576 512' do |s|
+            s.path fill: 'currentColor',
+                   d: 'M488 312.7V456c0 13.3-10.7 24-24 24H348c-6.6 0-12-5.4-12-12V356c0-6.6-5.4-' \
+                      '12-12-12h-72c-6.6 0-12 5.4-12 12v112c0 6.6-5.4 12-12 12H112c-13.3 0-24-10.' \
+                      '7-24-24V312.7c0-3.6 1.6-7 4.4-9.3l188-154.8c4.4-3.6 10.8-3.6 15.3 0l188 15' \
+                      '4.8c2.7 2.3 4.3 5.7 4.3 9.3zm83.6-60.9L488 182.9V44.4c0-6.6-5.4-12-12-12h-' \
+                      '56c-6.6 0-12 5.4-12 12V117l-89.5-73.7c-17.7-14.6-43.3-14.6-61 0L4.4 251.8c' \
+                      '-5.1 4.2-5.8 11.8-1.6 16.9l25.5 31c4.2 5.1 11.8 5.8 16.9 1.6l235.2-193.7c4' \
+                      '.4-3.6 10.8-3.6 15.3 0l235.2 193.7c5.1 4.2 12.7 3.5 16.9-1.6l25.5-31c4.2-5' \
+                      '.2 3.4-12.7-1.7-16.9z'
+          end
+        end
+      end
+    end
+
+    # Don't render if @hide_breadcrumbs is true.
+    def render?
+      helpers.assigns['hide_breadcrumbs'] != true
+    end
+
+    def breadcrumbs
+      helpers.controller.breadcrumbs.map { |e| Breadcrumbs::ComputedElement.new e, helpers }
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Proscenium::UI::Breadcrumbs
+  class ComputedElement
+    def initialize(element, context)
+      @element = element
+      @context = context
+    end
+
+    # 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 ||= unless @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)
+      unless @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,95 @@
+# frozen_string_literal: true
+
+module 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 filter_options [Hash] Options to pass through to the before_action filter.
+      def add_breadcrumb(name, path = nil, **filter_options)
+        element_options = filter_options.delete(:options) || {}
+
+        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 filter_options [Hash] Options to pass through to the before_action filter.
+      def prepend_breadcrumb(name, path = nil, **filter_options)
+        element_options = filter_options.delete(:options) || {}
+
+        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? || helpers.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(': ') unless names.empty?
+      strip_tags out.join(' - ')
+    end
+
+    private
+
+    def computed_breadcrumbs
+      @computed_breadcrumbs ||= breadcrumbs.map do |ele|
+        ComputedElement.new ele, helpers
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+@define-mixin breadcrumbs {
+  /* Default properties */
+  --_puiBreadcrumbs--separator-color: GrayText;
+  --_puiBreadcrumbs--separator: url("/proscenium/icons/angle-right-regular.svg");
+
+  margin: 10px;
+
+  ol {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    align-items: baseline;
+
+    li {
+      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.5rem 0 0;
+          transform: rotate(180deg);
+        }
+      }
+
+      @media (min-width: 427px) {
+        &:not(:last-child)::after {
+          @mixin _separator;
+          margin: 0 0.5rem;
+        }
+      }
+
+      &:last-child {
+        font-weight: 500;
+        text-transform: none;
+      }
+
+      &:last-child > a {
+        font-weight: 500;
+        text-transform: none;
+      }
+
+      a {
+        color: var(--puiBreadcrumbs--link-color, revert);
+        display: flex;
+
+        &:hover {
+          color: var(--puiBreadcrumbs--link-hover-color, revert);
+        }
+      }
+
+      svg {
+        height: 1em;
+        width: 1em;
+      }
+    }
+  }
+}
+
+@define-mixin _separator {
+  display: inline-block;
+  content: "";
+  height: 1rem;
+  width: 1rem;
+  -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)
+  );
+}

data/lib/proscenium/ui/breadcrumbs.rb

@@ -0,0 +1,72 @@
+# 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 views with the breadcrumbs component.
+  # @see `Proscenium::UI::Breadcrumbs::Component`.
+  #
+  # At it's simplest, you can add a breadcrumb with a name of "User", and a path of "/users" like
+  # this:
+  #
+  #   add_breadcrumb 'Foo', '/foo'
+  #
+  # 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.
+  #
+  module Breadcrumbs
+    extend ActiveSupport::Autoload
+
+    autoload :Control
+    autoload :ComputedElement
+    autoload :Component
+
+    # Represents a navigation element in the breadcrumb collection.
+    class 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
+  end
+end

data/lib/proscenium/ui/component.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'dry-initializer'
+
+module Proscenium::UI
+  class Component < Proscenium::Phlex
+    self.abstract_class = true
+
+    extend Dry::Initializer
+  end
+end

data/lib/proscenium/ui/test.js

@@ -0,0 +1 @@
+console.log("/proscenium/ui/test.js");

data/lib/proscenium/ui.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'dry-types'
+
+module Proscenium::UI
+  extend ActiveSupport::Autoload
+
+  autoload :Component
+  autoload :Breadcrumbs
+
+  module Types
+    include Dry.Types()
+  end
+end

data/lib/proscenium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Proscenium
-  VERSION = '0.15.0.beta.4'
+  VERSION = '0.15.0.beta.5'
 end

data/lib/proscenium.rb

@@ -27,6 +27,7 @@ module Proscenium
   autoload :Builder
   autoload :Importer
   autoload :Resolver
+  autoload :UI
 
   class Deprecator
     def deprecation_warning(name, message, _caller_backtrace = nil)
@@ -55,6 +56,14 @@ module Proscenium
     def cache
       @cache ||= config.cache || ActiveSupport::Cache::NullStore.new
     end
+
+    def ui_path
+      Railtie.root.join('lib', 'proscenium', 'ui')
+    end
+
+    def root
+      Railtie.root
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: proscenium
 version: !ruby/object:Gem::Version
-  version: 0.15.0.beta.4
+  version: 0.15.0.beta.5
 platform: x86_64-linux
 authors:
 - Joel Moss
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-21 00:00:00.000000000 Z
+date: 2024-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -30,6 +30,34 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: dry-initializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: ffi
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: phlex-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.1
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -114,6 +156,7 @@ files:
 - lib/proscenium/ext/proscenium.h
 - lib/proscenium/helper.rb
 - lib/proscenium/importer.rb
+- lib/proscenium/libs/custom_element.js
 - lib/proscenium/libs/react-manager/index.jsx
 - lib/proscenium/libs/react-manager/react.js
 - lib/proscenium/libs/stimulus-loading.js
@@ -140,6 +183,15 @@ files:
 - lib/proscenium/side_load.rb
 - lib/proscenium/source_path.rb
 - lib/proscenium/templates/rescues/build_error.html.erb
+- lib/proscenium/ui.rb
+- lib/proscenium/ui/breadcrumbs.rb
+- lib/proscenium/ui/breadcrumbs/component.module.css
+- lib/proscenium/ui/breadcrumbs/component.rb
+- lib/proscenium/ui/breadcrumbs/computed_element.rb
+- lib/proscenium/ui/breadcrumbs/control.rb
+- lib/proscenium/ui/breadcrumbs/mixins.css
+- lib/proscenium/ui/component.rb
+- lib/proscenium/ui/test.js
 - lib/proscenium/utils.rb
 - lib/proscenium/version.rb
 - lib/proscenium/view_component.rb
@@ -169,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: The engine powering your Rails frontend