lookbook 1.5.0 → 2.0.0.beta.0

data/lib/lookbook/tags/type_tag.rb

@@ -0,0 +1,7 @@
+module Lookbook
+  class TypeTag < YardTag
+    def value
+      text.downcase.to_sym
+    end
+  end
+end

data/lib/lookbook/tags/yard_tag.rb

@@ -44,8 +44,7 @@ module Lookbook
           TagOptionsParser.call(@text, {
             file: host_file,
             base_dir: host_file&.dirname,
-            eval_context: host_class_instance,
-            permit_eval: Lookbook.config.preview_params_options_eval
+            eval_context: host_class_instance
           })
         else
           [{}, @text]

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "1.5.0"
+  VERSION = "2.0.0.beta.0"
 end

data/lib/lookbook/websocket.rb

@@ -1,60 +1,13 @@
 module Lookbook
   class Websocket
-    attr_reader :engine_mount_path, :server, :logger
+    class << self
+      def new(mount_path, **kwargs)
+        require_relative "./cable/cable"
 
-    def initialize(engine_mount_path, logger: Lookbook.logger)
-      @engine_mount_path = engine_mount_path
-      @logger = logger
-
-      logger.info "Initializing websocket"
-
-      if Gem::Version.new(Rails.version) >= Gem::Version.new(6.0)
-        @server = ActionCable::Server::Base.new config: cable_config
-      else
-        @server = ActionCable::Server::Base.new
-        @server.config = cable_config
+        Cable.new(mount_path, **kwargs)
+      rescue LoadError
+        NullWebsocket.new
       end
     end
-
-    def broadcast(message, payload = nil)
-      logger.debug message.to_s
-      server.broadcast(message.to_s, payload.to_h)
-    end
-
-    def mount_path
-      "/cable"
-    end
-
-    def full_mount_path
-      "#{engine_mount_path}/#{mount_path}".gsub("//", "/")
-    end
-
-    def mountable?
-      true
-    end
-
-    alias_method :mounted?, :mountable?
-
-    def self.noop
-      NullWebsocket.new
-    end
-
-    protected
-
-    def cable_config
-      cable = ActionCable::Server::Configuration.new
-      cable.cable = {adapter: "async"}.with_indifferent_access
-      cable.mount_path = nil
-      cable.connection_class = -> { Lookbook::Connection }
-      cable.logger = logger
-      cable
-    end
-  end
-
-  class NullWebsocket < NullObject
-    def mountable?
-      false
-    end
-    alias_method :mounted?, :mountable?
   end
 end

data/lib/lookbook.rb

@@ -7,34 +7,193 @@ loader.push_dir("#{__dir__}/lookbook", namespace: Lookbook)
 loader.collapse("#{__dir__}/lookbook/*")
 loader.collapse("#{__dir__}/lookbook/*/*")
 loader.collapse("#{__dir__}/lookbook/*/*/*")
+loader.ignore("#{__dir__}/lookbook/support/evented_file_update_checker.rb")
+loader.ignore("#{__dir__}/lookbook/cable")
 loader.setup
 
+# The Lookbook application entry point.
+#
+# @api public
 module Lookbook
   class << self
+    # Returns the installed Lookbook version
+    #
+    # @example :erb
+    #   <p>Using Lookbook v<%= Lookbook.version %></p>
+    #
+    # @return [String] Version number string
     def version
       Lookbook::VERSION
     end
 
+    # Provides access to the Lookbook config store
+    #
+    # @example :ruby
+    #   Lookbook.config.project_title = "MyApp"
+    #
+    # @return [ConfigStore] The config store object
     def config
       @_config ||= ConfigStore.init_from_config
     end
 
-    def configure
-      yield(config)
+    # Get an array of component preview objects
+    #
+    # @return [Array<PreviewEntity>] Array of preview entities
+    def previews
+      Engine.previews.to_a
     end
 
-    def engine
-      Engine
+    # Get an array of documentation page objects
+    #
+    # @return [Array<PageEntity>] Array of page entities
+    def pages
+      Engine.pages.to_a
     end
 
+    # Get the global data store instance
+    #
+    # @return [Store] The global data store instance
     def data
       @_data ||= Store.new
     end
 
+    # Replace the global data store contents
+    #
+    # @param new_data [Hash] Hash of data to store
+    # @return [Store] The global data store instance
     def data=(new_data)
       @_data = Store.new(new_data)
     end
 
+    # @!group Params
+
+    # Add a custom `@param` tag input type
+    #
+    # @param name [Symbol] Unique input type name
+    # @param partial_path [String] Path to the partial template used to render the input
+    # @param opts [Hash] Set of default options to be passed to the input. Any supplied param options will override these values
+    def add_input_type(name, partial_path, opts = {})
+      Engine.inputs.add_input(name, partial_path, opts)
+    end
+
+    # @!endgroup
+
+    # @!group Inspector Panels
+
+    # Add a custom inspector panel
+    #
+    # @example :ruby
+    #   Lookbook.add_panel(:info, "panels/info", {
+    #     label: "Extra Info"
+    #   })
+    #
+    # @param name [Symbol, String] Unique panel name
+    # @param partial_path [String] Path to the partial template used to render the panel
+    # @param opts [Hash] Set of panel options
+    # @option opts [String] :label The text to be displayed in the panel tab
+    # @option opts [String] :hotkey [Keyboard shortcut](https://alpinejs.dev/directives/on#keyboard-events) used to switch to the panel
+    # @option opts [Boolean] :disabled Disabled tabs are still accessible but are greyed out in the UI
+    # @option opts [String] :copy If present, the panel will display a copy button that copies the value of this property to the clipboard when clicked
+    # @option opts [Hash] :locals A hash of local variables that will be passed to the panel when it is rendered
+    def add_panel(name, partial_path, opts = {})
+      Engine.panels.add_panel(name, partial_path, opts)
+    end
+
+    # Edit the properties of an existing inspector panel
+    #
+    # @example :ruby
+    #   Lookbook.update_panel(:notes, {
+    #     label: "Usage Info",
+    #     hotkey: "u",
+    #   })
+    #
+    # @param name [Symbol, String] Name of target panel
+    # @param opts [Hash] Set of panel options
+    # @option opts [String] :label The text to be displayed in the panel tab
+    # @option opts [String] :hotkey [Keyboard shortcut](https://alpinejs.dev/directives/on#keyboard-events) used to switch to the panel
+    # @option opts [Boolean] :disabled Disabled tabs are still accessible but are greyed out in the UI
+    # @option opts [String] :copy If present, the panel will display a copy button that copies the value of this property to the clipboard when clicked
+    # @option opts [Hash] :locals A hash of local variables that will be passed to the panel when it is rendered
+    def update_panel(name, opts)
+      Engine.panels.update_panel(name, opts)
+    end
+
+    # Remove a panel from the inspector
+    #
+    # @example :ruby
+    #   Lookbook.remove_panel(:notes)
+    #
+    # @param name [Symbol, String] Name of target panel
+    def remove_panel(name)
+      Engine.panels.remove_panel(name)
+    end
+
+    # @!endgroup
+
+    # @!group Custom Tags
+
+    # Add a custom tag
+    #
+    # @param name [Symbol, String] Tag name
+    # @param args [Array<Symbol>] Array of argument names
+    # @yield [tag] The custom tag instance
+    def add_tag(name, args = nil, &block)
+      Engine.tags.add_tag(name, {
+        named_args: args.to_a,
+        after_parse: block
+      })
+    end
+
+    # @!endgroup
+
+    # @!group Lifecycle Callbacks
+
+    # Add a callback to run after app initialization.
+    #
+    # @example :ruby
+    #   Lookbook.after_initialize do |app|
+    #     puts "Lookbook has started!"
+    #   end
+    #
+    # @yield [app] Lookbook app
+    def after_initialize(&block)
+      Engine.hooks.add_hook(:after_initialize, block)
+    end
+
+    # Add a callback to run before Lookbook shuts down
+    #
+    # @yield [app] Lookbook app
+    def before_exit(&block)
+      Engine.hooks.add_hook(:before_exit, block)
+    end
+
+    # Add a callback to run when a change to a watched
+    # file occurs. Only called when an evented file watcher is being
+    # used to detect changes.
+    #
+    # @yield [app, changes] Lookbook app and hash of files changed, added & removed
+    def after_change(&block)
+      Engine.hooks.add_hook(:after_change, block)
+    end
+
+    # @!endgroup
+
+    # @api private
+    def broadcast(event_name, data = {})
+      Engine.websocket&.broadcast(event_name.to_s, data)
+    end
+
+    # @api private
+    def engine
+      Engine
+    end
+
+    # @api private
+    def configure
+      yield(config)
+    end
+
+    # @api private
     def logger
       @_logger ||= if Rails.logger.present? && config.log_use_rails_logger
         Rails.logger
@@ -45,12 +204,20 @@ module Lookbook
       end
     end
 
+    # @api private
     def debug_data
       {
         version: version,
         env: Rails.env.to_s,
         config: [
           config.to_h,
+          {
+            dependencies: {
+              actioncable: Engine.runtime_context.actioncable_installed?,
+              listen: Engine.runtime_context.listen_installed?,
+              view_component: config.using_view_component
+            }
+          },
           {panels: Engine.panels.to_h},
           {inputs: Engine.inputs.to_h},
           {tags: Engine.tags.to_h}
@@ -58,56 +225,15 @@ module Lookbook
       }
     end
 
-    def previews
-      Engine.previews
-    end
+    alias_method :define_param_input, :add_input_type
+    alias_method :define_panel, :add_panel
+    alias_method :amend_panel, :update_panel
+    alias_method :define_tag, :add_tag
 
-    def pages
-      Engine.pages
-    end
-
-    def broadcast(event_name, data = {})
-      Engine.websocket&.broadcast(event_name.to_s, data)
-    end
-
-    def theme
-      @_theme ||= Lookbook::Theme.new(config.ui_theme, config.ui_theme_overrides)
-    end
-
-    def define_param_input(*args)
-      Engine.inputs.add_input(*args)
-    end
-
-    def define_panel(name, *args)
-      Engine.panels.add_panel(name, :drawer, *args)
-    end
-
-    def amend_panel(*args)
-      Engine.panels.update_panel(*args)
-    end
-
-    def remove_panel(name)
-      Engine.panels.remove_panel(name)
-    end
-
-    def define_tag(name, args = nil, &block)
-      Engine.tags.add_tag(name, {
-        named_args: args.to_a,
-        after_parse: block
-      })
-    end
-
-    def after_initialize(&block)
-      Engine.hooks.add_hook(:after_initialize, block)
-    end
-
-    def before_exit(&block)
-      Engine.hooks.add_hook(:before_exit, block)
-    end
-
-    def after_change(&block)
-      Engine.hooks.add_hook(:after_change, block)
-    end
+    deprecate define_param_input: :add_input_type, deprecator: Deprecation
+    deprecate define_panel: :add_panel, deprecator: Deprecation
+    deprecate amend_panel: :update_panel, deprecator: Deprecation
+    deprecate define_tag: :add_tag, deprecator: Deprecation
   end
 end