poetry-core 0.0.2

data/lib/poetry/core/preview/abstract.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Preview
+      # Provides functionality to mark preview classes as abstract and exclude them from the preview index.
+      # Adapted from an MIT-licensed source (source and license in
+      # THIRD_PARTY_NOTICES.md).
+      #
+      # This module adds an `abstract_class` accessor to preview classes and automatically filters
+      # them out when listing all available previews. This is particularly useful for creating base
+      # preview classes that provide shared functionality but shouldn't appear in the preview UI.
+      #
+      # The module works by extending preview classes (typically ViewComponent::Preview) and prepending
+      # class methods that add the abstract_class attribute and modify the `all` method to exclude
+      # abstract previews from the results.
+      #
+      # @example Marking a base preview class as abstract
+      #   class ApplicationPreview < ViewComponent::Preview
+      #     extend Poetry::Core::Preview::Abstract
+      #     self.abstract_class = true
+      #
+      #     # Shared helper methods for all previews
+      #     def render_in_container(&block)
+      #       content_tag(:div, class: "preview-container", &block)
+      #     end
+      #   end
+      #
+      #   class ButtonPreview < ApplicationPreview
+      #     # This will appear in the preview index
+      #     def default
+      #       render ButtonComponent.new
+      #     end
+      #   end
+      #
+      #   ViewComponent::Preview.all
+      #   # => [ButtonPreview] (ApplicationPreview is excluded)
+      #
+      # @example Using with Poetry::Core::Preview::Base
+      #   # Poetry::Core::Preview::Base automatically uses this module
+      #   class MyBasePreview < Poetry::Core::Preview::Base
+      #     self.abstract_class = true
+      #
+      #     def helper_method
+      #       "shared logic"
+      #     end
+      #   end
+      #
+      #   class ConcretePreview < MyBasePreview
+      #     def example
+      #       render SomeComponent.new
+      #     end
+      #   end
+      #
+      # @example Checking if a preview is abstract
+      #   ApplicationPreview.abstract_class?  # => true
+      #   ButtonPreview.abstract_class?       # => false (or nil)
+      #
+      # @note This module is automatically applied to ViewComponent::Preview when Poetry::Core::Preview::Base
+      #   is loaded, so abstract_class functionality is available throughout the preview system.
+      #
+      module Abstract
+        # Hook method called when this module is extended into a class.
+        #
+        # Prepends ClassMethods to the class's singleton class, making the abstract_class
+        # functionality available to the extending class and overriding its `all` method.
+        #
+        # @param base [Class] the class being extended with this module
+        # @return [void]
+        # @api private
+        def self.extended(base)
+          base.singleton_class.prepend(ClassMethods)
+        end
+
+        # Class methods added to preview classes that extend the Abstract module.
+        #
+        # These methods provide the abstract_class attribute and modify preview collection
+        # behavior to automatically filter out abstract classes.
+        module ClassMethods
+          # @!attribute [rw] abstract_class
+          #   @return [Boolean, nil] whether this preview class is abstract
+          attr_accessor :abstract_class
+
+          # Checks if this preview class is marked as abstract.
+          #
+          # @return [Boolean, nil] true if abstract, false or nil otherwise
+          # @example
+          #   MyPreview.abstract_class = true
+          #   MyPreview.abstract_class?  # => true
+          alias abstract_class? abstract_class
+
+          # Returns all non-abstract descendant preview classes.
+          #
+          # This method overrides the default ViewComponent::Preview.all to exclude
+          # any preview classes marked as abstract. It ensures previews are loaded
+          # before filtering if no descendants exist yet.
+          #
+          # @return [Array<Class>] array of non-abstract preview classes
+          # @example
+          #   class BasePreview < ViewComponent::Preview
+          #     extend Poetry::Core::Preview::Abstract
+          #     self.abstract_class = true
+          #   end
+          #
+          #   class ButtonPreview < BasePreview; end
+          #   class CardPreview < BasePreview; end
+          #
+          #   ViewComponent::Preview.all
+          #   # => [ButtonPreview, CardPreview] (BasePreview excluded)
+          def all
+            # Loading delegates to Sidecarable#load_previews when present
+            # (poetry's engine wires both onto ViewComponent::Preview);
+            # standalone, already-loaded descendants are filtered as-is.
+            load_previews if respond_to?(:load_previews) && descendants.reject(&:abstract_class?).empty?
+            descendants.reject(&:abstract_class?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/preview/base.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The preview stack: base class, template resolution, and gallery glue.
+    # Adapted from an MIT-licensed source (source and license in
+    # THIRD_PARTY_NOTICES.md).
+    module Preview
+      # First, enable abstract classes (if not already extended)
+      unless ViewComponent::Preview.singleton_class.is_a?(Preview::Abstract)
+        ViewComponent::Preview.extend Preview::Abstract
+      end
+
+      # Enhanced base class for ViewComponent previews with additional features.
+      #
+      # Poetry::Core::Preview::Base extends the standard ViewComponent::Preview with several enhancements:
+      # - Automatic component class inference from preview class name
+      # - Template rendering support with custom layouts
+      # - Container class configuration with inheritance
+      # - Convenient shortcut methods for rendering components
+      #
+      # Theme and mode switching in Lookbook is a LAYOUT concern, not a
+      # preview-class one: the preview layout reads
+      # `lookbook_display(:theme)` / `lookbook_display(:mode)` and stamps
+      # classes on <html>; components stay theme-agnostic by construction.
+      #
+      # @example Basic usage
+      #   class ButtonPreview < Poetry::Core::Preview::Base
+      #     # Automatically infers Button::Component, ButtonComponent, or Button
+      #     def default
+      #       render_component(text: "Click me", variant: :primary)
+      #     end
+      #
+      #     def with_custom_container
+      #       self.class.container_class = "p-4 bg-gray-100"
+      #       render_component(text: "Styled container")
+      #     end
+      #   end
+      #
+      # @example Using render_with for template locals
+      #   class CardPreview < Poetry::Core::Preview::Base
+      #     def default
+      #       render_with(title: "Card Title", description: "Card description")
+      #     end
+      #   end
+      #
+      # @example Passing a component instance directly
+      #   class AlertPreview < Poetry::Core::Preview::Base
+      #     def warning
+      #       component = AlertComponent.new(type: :warning, dismissible: true)
+      #       render_component(component)
+      #     end
+      #   end
+      #
+      class Base < ViewComponent::Preview
+        self.abstract_class = true
+
+        include Poetry::Core::Preview::Template
+
+        # The container class previews render inside when neither the
+        # preview class nor an ancestor sets one.
+        DEFAULT_CONTAINER_CLASS = ""
+
+        class << self
+          # Ensures child preview classes inherit layout configuration.
+          #
+          # @param child [Class] the inheriting preview class
+          # @return [void]
+          # @api private
+          def inherited(child)
+            child.layout(@layout) if defined?(@layout)
+            super
+          end
+
+          attr_writer :container_class, :component_class_name
+
+          # Returns the configured container CSS class for the preview.
+          #
+          # Container classes are inherited from parent preview classes. If not explicitly set,
+          # uses the parent's container class or DEFAULT_CONTAINER_CLASS.
+          #
+          # @return [String] the container CSS class
+          # @example
+          #   class MyPreview < Poetry::Core::Preview::Base
+          #     self.container_class = "p-8 bg-white"
+          #   end
+          #
+          #   MyPreview.container_class # => "p-8 bg-white"
+          def container_class
+            return @container_class if defined?(@container_class)
+
+            @container_class =
+              if superclass.respond_to?(:container_class)
+                superclass.container_class
+              else
+                DEFAULT_CONTAINER_CLASS
+              end
+          end
+
+          # Prepares render arguments by building component instance and setting container class.
+          #
+          # @return [Hash] render arguments with locals configured
+          # @api private
+          def render_args(...)
+            super.tap do |res|
+              res[:locals] ||= {}
+              build_component_instance(res[:locals])
+              res[:locals][:container_class] ||= container_class
+            end
+          end
+
+          # Infers the component class name from the preview class name.
+          #
+          # Tries multiple naming conventions in order:
+          # - Namespace::ButtonPreview => Namespace::Button::Component
+          # - Namespace::ButtonPreview => Namespace::ButtonComponent
+          # - Namespace::ButtonPreview => Namespace::Button
+          # - Button::Preview => Button::Component | ButtonComponent | Button
+          #
+          # @return [String, nil] the inferred component class name or nil if not found
+          # @example
+          #   class MyApp::ButtonPreview < Poetry::Core::Preview::Base
+          #   end
+          #
+          #   MyApp::ButtonPreview.component_class_name
+          #   # => "MyApp::Button::Component" (if it exists)
+          #   # or "MyApp::ButtonComponent" (if it exists)
+          #   # or "MyApp::Button" (if it exists)
+          def component_class_name
+            @component_class_name ||= begin
+              component_name = name.sub(/(::Preview|Preview)$/, "")
+              [
+                "#{component_name}::Component",
+                "#{component_name}Component",
+                component_name
+              ].find(&:safe_constantize)
+            end
+          end
+
+          private
+
+          # Builds a component instance and adds it to locals.
+          #
+          # If component is already present in locals, returns unchanged.
+          # If component class cannot be instantiated, sets error message in locals.
+          #
+          # @param locals [Hash] the locals hash to modify
+          # @return [Hash] the modified locals hash
+          # @api private
+          def build_component_instance(locals)
+            return locals unless locals[:component].nil?
+
+            locals[:component] = component_class_name.safe_constantize&.new
+          rescue StandardError => e
+            locals[:component] = nil
+            locals[:error] = e.message
+          end
+        end
+
+        # Renders a NESTED component inside a slot/content block. Plain
+        # render() there resolves to the preview DSL's own render (a
+        # declaration returning a hash) and the nested component silently
+        # vanishes - button icons, card actions, dialog footer buttons were
+        # all missing from every preview until the a11y preview rig caught it.
+        #
+        # @param component [ViewComponent::Base] the component instance to render
+        # @return [String] the rendered HTML
+        def embed(component, &)
+          ApplicationController.new.view_context.render(component, &)
+        end
+
+        # Renders the preview with custom template locals.
+        #
+        # This is a convenience method that wraps render_with_template, making it easier
+        # to pass locals to your preview templates.
+        #
+        # @param locals [Hash] key-value pairs to pass as local variables to the template
+        # @return [String] the rendered template
+        # @example
+        #   def default
+        #     render_with(title: "Hello", message: "World")
+        #   end
+        def render_with(**locals)
+          render_with_template(locals: locals)
+        end
+
+        # Renders a component instance or creates one from props.
+        #
+        # This method provides a convenient way to render components in previews. It can accept
+        # either a component instance directly, or a hash of props to instantiate the component.
+        # The component class is automatically inferred from the preview class name.
+        #
+        # @param component_or_props [ViewComponent::Base, Hash, nil] either a component instance
+        #   or a hash of props to pass to the component constructor
+        # @param block [Proc, nil] optional block to pass as content to the component
+        # @yield the component's content
+        # @return [String] the rendered component
+        # @example With props hash
+        #   def default
+        #     render_component(variant: :primary, text: "Click me")
+        #   end
+        #
+        # @example With component instance
+        #   def custom
+        #     component = ButtonComponent.new(variant: :primary)
+        #     render_component(component)
+        #   end
+        #
+        # @example With content block
+        #   def with_content
+        #     render_component(variant: :primary) do
+        #       "Custom content"
+        #     end
+        #   end
+        def render_component(component_or_props = nil, &block)
+          component = if component_or_props.is_a?(::ViewComponent::Base)
+                        component_or_props
+                      else
+                        self.class.component_class_name.constantize.new(**(component_or_props || {}))
+                      end
+
+          render_with(component: component, content_block: block)
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/preview/sidecarable.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Preview
+      # Provides sidecar file loading and naming utilities for preview classes.
+      # Adapted from an MIT-licensed source (source and license in
+      # THIRD_PARTY_NOTICES.md).
+      #
+      # This module adds functionality to automatically load preview files from configured paths
+      # and derive component names from preview class names. It's designed to support the "sidecar"
+      # pattern where preview files are organized alongside their corresponding components.
+      #
+      # The module extends preview classes (typically ViewComponent::Preview) and prepends class
+      # methods that handle preview file discovery and name extraction, making it easier to organize
+      # and load previews in a consistent, convention-based manner.
+      #
+      # @example Basic usage with ViewComponent::Preview
+      #   ViewComponent::Preview.extend Poetry::Core::Preview::Sidecarable
+      #
+      #   # Load all preview files from configured paths
+      #   ViewComponent::Preview.load_previews
+      #
+      # @example Preview name extraction
+      #   class MyApp::Button::Preview < ViewComponent::Preview
+      #     extend Poetry::Core::Preview::Sidecarable
+      #   end
+      #
+      #   MyApp::Button::Preview.preview_name
+      #   # => "my_app/button"
+      #
+      # @example Namespace variations
+      #   class ButtonPreview < ViewComponent::Preview
+      #     extend Poetry::Core::Preview::Sidecarable
+      #   end
+      #
+      #   ButtonPreview.preview_name  # => "button"
+      #
+      #   class Admin::CardPreview < ViewComponent::Preview
+      #     extend Poetry::Core::Preview::Sidecarable
+      #   end
+      #
+      #   Admin::CardPreview.preview_name  # => "admin/card"
+      #
+      # @note Preview files are discovered using the glob pattern `**/{preview.rb,*_preview.rb}`,
+      #   which matches both standalone `preview.rb` files and files ending with `_preview.rb`.
+      #
+      module Sidecarable
+        # Glob pattern for discovering preview files.
+        #
+        # Matches:
+        # - `preview.rb` - Standalone preview files
+        # - `*_preview.rb` - Named preview files (e.g., `button_preview.rb`)
+        #
+        # @return [String] the glob pattern for preview file discovery
+        PREVIEW_GLOB = "**/{preview.rb,*_preview.rb}"
+
+        # Hook method called when this module is extended into a class.
+        #
+        # Prepends ClassMethods to the class's singleton class, making the sidecar loading
+        # functionality available to the extending class.
+        #
+        # @param base [Class] the class being extended with this module
+        # @return [void]
+        # @api private
+        def self.extended(base)
+          base.singleton_class.prepend(ClassMethods)
+        end
+
+        # Class methods added to preview classes that extend the Sidecarable module.
+        #
+        # These methods provide preview file loading and component name extraction functionality.
+        module ClassMethods
+          # Loads all preview files from configured preview paths.
+          #
+          # Iterates through each configured preview path and requires all files matching
+          # the PREVIEW_GLOB pattern. Files are loaded in sorted order to ensure consistent
+          # loading sequence across environments.
+          #
+          # @return [void]
+          # @example Loading previews
+          #   ViewComponent::Preview.preview_paths = ["app/components"]
+          #   ViewComponent::Preview.load_previews
+          #   # Loads: app/components/**/preview.rb
+          #   #        app/components/**/*_preview.rb
+          #
+          # @example With multiple paths
+          #   ViewComponent::Preview.preview_paths = [
+          #     "app/components",
+          #     "app/views/components"
+          #   ]
+          #   ViewComponent::Preview.load_previews
+          #   # Loads previews from both directories
+          #
+          # @note Uses `require_dependency` to ensure proper reloading in development mode.
+          def load_previews
+            Array(preview_paths).each do |preview_path|
+              Dir["#{preview_path}/#{PREVIEW_GLOB}"].each { |file| require_dependency file }
+            end
+          end
+
+          # Extracts the component name from the preview class name.
+          #
+          # Removes the "Preview" or "::Preview" suffix from the class name and converts
+          # it to underscore/snake_case format. This is useful for deriving file paths,
+          # identifiers, and component names from preview class names.
+          #
+          # @return [String] the underscored component name
+          # @example Basic usage
+          #   class ButtonPreview < ViewComponent::Preview
+          #     extend Poetry::Core::Preview::Sidecarable
+          #   end
+          #
+          #   ButtonPreview.preview_name  # => "button"
+          #
+          # @example With namespace
+          #   class Admin::Dashboard::CardPreview < ViewComponent::Preview
+          #     extend Poetry::Core::Preview::Sidecarable
+          #   end
+          #
+          #   Admin::Dashboard::CardPreview.preview_name  # => "admin/dashboard/card"
+          #
+          # @example With trailing Preview namespace
+          #   class Components::Alert::Preview < ViewComponent::Preview
+          #     extend Poetry::Core::Preview::Sidecarable
+          #   end
+          #
+          #   Components::Alert::Preview.preview_name  # => "components/alert"
+          def preview_name
+            name.sub(/(::Preview|Preview)$/, "").underscore
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/preview/template.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Preview
+      # Provides flexible template resolution for ViewComponent previews.
+      # Adapted from an MIT-licensed source (source and license in
+      # THIRD_PARTY_NOTICES.md).
+      #
+      # This module extends ViewComponent's preview template system to support multiple
+      # template locations and fallback strategies. It allows previews to use:
+      # - Example-specific templates (e.g., `previews/default.html.erb`)
+      # - Shared preview templates (e.g., `preview.html.erb`)
+      # - A configurable default template
+      #
+      # The template resolution follows this priority order:
+      # 1. ViewComponent's standard template location (via super)
+      # 2. Example-specific template: `preview_name/previews/example_name.html.*`
+      # 3. Preview-level template: `preview_name/preview.html.*`
+      # 4. Default template (configurable, defaults to "poetry/core/preview")
+      #
+      # @example Basic usage with default template
+      #   class ButtonPreview < Poetry::Core::Preview::Base
+      #     # Uses the default template (poetry/core/preview)
+      #     def default
+      #       render_component(text: "Click me")
+      #     end
+      #   end
+      #
+      # @example Using example-specific template
+      #   # File: test/components/previews/button_preview.rb
+      #   class ButtonPreview < Poetry::Core::Preview::Base
+      #     def complex
+      #       render_with(button: ButtonComponent.new)
+      #     end
+      #   end
+      #
+      #   # Template: test/components/previews/button_preview/previews/complex.html.erb
+      #   <div class="preview-container">
+      #     <%= render @button %>
+      #     <p>Additional markup for this specific preview</p>
+      #   </div>
+      #
+      # @example Using shared preview template
+      #   # File: test/components/previews/card_preview.rb
+      #   class CardPreview < Poetry::Core::Preview::Base
+      #     def basic; render_component; end
+      #     def featured; render_component(featured: true); end
+      #   end
+      #
+      #   # Template: test/components/previews/card_preview/preview.html.erb
+      #   # This template is shared by all examples in this preview
+      #   <div class="card-demo-wrapper">
+      #     <%= render @component %>
+      #   </div>
+      #
+      # @example Configuring custom default template
+      #   class MyBasePreview < Poetry::Core::Preview::Base
+      #     self.default_preview_template = "my_app/custom_preview"
+      #   end
+      #
+      #   class ButtonPreview < MyBasePreview
+      #     # Inherits the custom default template
+      #     def default
+      #       render_component
+      #     end
+      #   end
+      #
+      # @see Poetry::Core::Preview::Base
+      module Template
+        # The default template path used when no specific template is found.
+        #
+        # This template is rendered for previews that don't have:
+        # - A ViewComponent standard template
+        # - An example-specific template
+        # - A preview-level shared template
+        #
+        # @api public
+        DEFAULT_TEMPLATE = "poetry/core/preview"
+
+        # @api private
+        def self.included(base)
+          base.singleton_class.prepend(ClassMethods)
+        end
+
+        # Class-level methods added to preview classes when Template is included.
+        #
+        # These methods provide template configuration and resolution logic that
+        # operates at the class level, allowing inheritance and customization.
+        module ClassMethods
+          # @!attribute [w] default_preview_template
+          #   Sets the default template path for this preview class.
+          #
+          #   @return [String] the configured template path
+          #
+          #   @example
+          #     class MyPreview < Poetry::Core::Preview::Base
+          #       self.default_preview_template = "my_app/special_preview"
+          #     end
+          attr_writer :default_preview_template
+
+          # Returns the default preview template path for this class.
+          #
+          # The template path is inherited from parent classes. If not explicitly set,
+          # it walks up the class hierarchy until it finds a configured template or
+          # falls back to {DEFAULT_TEMPLATE}.
+          #
+          # @return [String] the default template path
+          #
+          # @example Using default template
+          #   Poetry::Core::Preview::Base.default_preview_template
+          #   # => "poetry/core/preview"
+          #
+          # @example Custom template with inheritance
+          #   class BasePreview < Poetry::Core::Preview::Base
+          #     self.default_preview_template = "custom/layout"
+          #   end
+          #
+          #   class ButtonPreview < BasePreview
+          #   end
+          #
+          #   ButtonPreview.default_preview_template
+          #   # => "custom/layout" (inherited from BasePreview)
+          def default_preview_template
+            return @default_preview_template if defined?(@default_preview_template)
+
+            @default_preview_template =
+              if superclass.respond_to?(:default_preview_template)
+                superclass.default_preview_template
+              else
+                DEFAULT_TEMPLATE
+              end
+          end
+
+          # Resolves the template path for a preview example with multiple fallbacks.
+          #
+          # This method implements a flexible template resolution strategy that tries
+          # multiple locations in order:
+          #
+          # 1. First calls ViewComponent's default resolution (via super)
+          # 2. If not found, looks for example-specific template at:
+          #    `preview_name/previews/example_name.html.*`
+          # 3. If not found, looks for shared preview template at:
+          #    `preview_name/preview.html.*`
+          # 4. Falls back to {#default_preview_template}
+          #
+          # This fallback behavior allows previews to share templates across examples
+          # or use a common default template, reducing duplication.
+          #
+          # @param example [String] the name of the preview example method
+          # @return [String] the resolved template path
+          #
+          # @example Template resolution for ButtonPreview#primary
+          #   # Tries in order:
+          #   # 1. ViewComponent default (e.g., test/components/previews/button_preview/primary.html.erb)
+          #   # 2. test/components/previews/button_preview/previews/primary.html.erb
+          #   # 3. test/components/previews/button_preview/preview.html.erb
+          #   # 4. the default template (poetry/core/preview)
+          #
+          # @note The method searches across all configured preview_paths
+          # @note Supports any template handler (erb, haml, slim, etc.)
+          def preview_example_template_path(example)
+            super
+          rescue ViewComponent::MissingPreviewTemplateError
+            # Look for example-specific template: preview_name/previews/example.html.*
+            has_example_preview = preview_paths.find do |path|
+              Dir.glob(File.join(path, preview_name, "previews", "#{example}.html.*")).any?
+            end
+
+            return File.join(preview_name, "previews", example) if has_example_preview
+
+            # Look for shared preview template: preview_name/preview.html.*
+            has_root_preview = preview_paths.find do |path|
+              Dir.glob(File.join(path, preview_name, "preview.html.*")).any?
+            end
+
+            return File.join(preview_name, "preview") if has_root_preview
+
+            # Fall back to configured default template
+            default_preview_template
+          end
+        end
+      end
+    end
+  end
+end