phlex-stimulus 0.1.0

data/lib/generators/phlex/stimulus/install/templates/app/components/chain_controller.rb.erb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Takes the names of controllers that will get connected
+  # in a particular order.
+  class ChainController < Controller
+    self.controller_name = 'chain'
+
+    #: (chain: String) -> void
+    def initialize(chain:)
+      @chain = chain
+    end
+
+    # @override
+    #: ?{ -> void } -> void
+    def view_template(&block)
+      div(
+        data: {
+          controller:       self.class.controller_name,
+          controller_chain: @chain,
+        },
+      ) do
+        block&.call
+      end
+    end
+
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/classlist_controller.rb.erb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Adds or removes classes in HTML elements.
+  class ClasslistController < Controller
+    self.controller_name = 'classlist'
+
+    actions :add, :remove
+    targets :subject
+
+    #: (classlist: Array[String?]) -> void
+    def initialize(classlist:)
+      @classlist = classlist
+    end
+
+    # @override
+    #: ?{ -> void } -> void
+    def view_template(&block)
+      div(
+        data: {
+          controller: self.class.controller_name,
+          class_list: class_list!(@classlist),
+        },
+      ) do
+        block&.call
+      end
+    end
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/controller.rb.erb

@@ -0,0 +1,10 @@
+# typed: true
+# frozen_string_literal: true
+
+# Abstract class for all Phlex components
+# that wrap Stimulus.js controllers in this app.
+#
+# @abstract
+class Components::Controller < Phlex::Stimulus::Components::Controller
+  # define any custom helpers for controller components here
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/controller_chain.rb.erb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Takes instances of stimulus controller components
+  # and renders them in such a way that they
+  # will get attached in the given order.
+  #
+  # It will wait until the `connect` logic of one controller
+  # finishes before it attempts to connect another controller.
+  class ControllerChain < Base
+    #: (*Controller?) -> void
+    def initialize(*controllers)
+      @controllers = controllers.compact #: Array[Controller]
+    end
+
+    #: -> void
+    def view_template
+      # optimisation when only one controller is present
+      return render @controllers.first if @controllers.length == 1
+
+      render ChainController.new(
+        chain: strlist!(@controllers.map(&:controller_name)),
+      ) do
+        @controllers.each.with_index do |controller, i|
+          render ControllerTemplate.new(controller: controller, index: i)
+        end
+      end
+    end
+
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/controller_template.rb.erb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Renders a template with a deferred Stimulus controller inside.
+  #
+  # Useful with `ChainController` to create a chain of controllers
+  # that will get attached in a particular order one after another.
+  class ControllerTemplate < Base
+    #: (controller: Controller, index: Integer) -> void
+    def initialize(controller:, index:)
+      @controller = controller
+      @index = index
+    end
+
+    #: -> void
+    def view_template
+      template(class: "#{@controller.controller_name}-template-#{@index}") do
+        render @controller
+      end
+    end
+
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/log_controller.rb.erb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Performs a `console.log` after connecting.
+  # Mainly used in development and for debugging.
+  class LogController < Controller
+    self.controller_name = 'log'
+
+    actions :log
+
+    #: (message: String, ?on_event: bool) -> void
+    def initialize(message:, on_event: false)
+      @message = message
+      @on_event = on_event
+    end
+
+    # @override
+    #: ?{ -> void } -> void
+    def view_template(&block)
+      div(
+        data: {
+          controller: self.class.controller_name,
+          message:    @message,
+          on_event:   attrbool(@on_event),
+        },
+      ) do
+        block&.call
+      end
+    end
+
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/sleep_controller.rb.erb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Sleeps for the given amount of milliseconds.
+  # Useful in controller sequences to delay the execution
+  # of `connect` logic of some other controller.
+  class SleepController < Controller
+    self.controller_name = 'sleep'
+
+    #: (timeout: Integer) -> void
+    def initialize(timeout:)
+      @timeout = timeout
+    end
+
+    # @override
+    #: ?{ -> void } -> void
+    def view_template(&block)
+      div(
+        data: {
+          controller: self.class.controller_name,
+          timeout:    @timeout.to_s,
+        },
+      ) do
+        block&.call
+      end
+    end
+
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components.rb.erb

@@ -0,0 +1,7 @@
+# typed: true
+# frozen_string_literal: true
+
+# Contains all components of the app
+module Components
+  extend Phlex::Kit
+end

data/lib/generators/phlex/stimulus/install/templates/app/javascript/application.ts.erb

@@ -0,0 +1,5 @@
+// Entry point for the build script in your package.json
+
+// uncomment if you use turbo
+// import "@hotwired/turbo-rails"
+import "./controllers"

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/application.ts.erb

@@ -0,0 +1,10 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(window as any).Stimulus   = application
+
+export { application }

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/chain_controller.ts.erb

@@ -0,0 +1,32 @@
+import { addEventPromise } from "../utils/misc"
+import { application } from "./application"
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Takes the names of controllers that will be connected
+ * in a particular order.
+ * It waits for the logic of `connect` to finish before
+ * connecting another controller.
+**/
+class ChainController extends Controller<HTMLElement> {
+  controllerChain!: string
+
+  async connect() {
+    let dataset = this.element.dataset
+    this.controllerChain = dataset.controllerChain!
+
+    let i = 0
+    for (let controllerName of this.controllerChain.split(' ')) {
+      let controllerTemplate = this.element.querySelector(`template.${controllerName}-template-${i}`) as HTMLTemplateElement
+      let controllerElement = document.importNode(controllerTemplate.content, true)
+      let readyPromise = addEventPromise(this.element, `${controllerName}:ready`)
+
+      this.element.appendChild(controllerElement)
+      await readyPromise
+
+      i++
+    }
+  }
+}
+
+application.register("chain", ChainController)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/chainable_controller.ts.erb

@@ -0,0 +1,44 @@
+import { Controller } from "@hotwired/stimulus"
+import { MakeControllerWithTargetsFactory } from "./typed_controller"
+
+/**
+ * An abstract class for Stimulus controllers that can be chained
+ * using the `ChainController`.
+ */
+export abstract class ChainableController<ElementType extends Element> extends Controller<ElementType> {
+  async connect() {
+    await this.init()
+    this.dispatch("ready")
+  }
+
+  /**
+   * The `connect` logic in a chainable controller
+   * should be defined under `init`
+   */
+  abstract init(): Promise<void>
+}
+
+/**
+ * An abstract class for Stimulus controllers that can be chained
+ * using the `ChainController` and supports fully typed targets.
+ *
+ * In order to use it specify the `Element` type and
+ * a record of target definitions.
+ *
+ * ```
+ *  class MyController extends TypedController<
+ *    HTMLFormElement,
+ *    {
+ *      input: HTMLInputElement,
+ *      submitButton: HTMLElement,
+ *    }
+ *  >() {
+ *    static targets = [ "input", "submitButton" ]
+ *
+ *    connect() {
+ *      console.log("Hello!")
+ *    }
+ *  }
+ * ```
+ **/
+export const TypedChainableController = MakeControllerWithTargetsFactory(ChainableController)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/classlist_controller.ts.erb

@@ -0,0 +1,30 @@
+import { application } from "./application"
+import { TypedController } from "./typed_controller"
+
+/**
+ * Adds or removes classes in HTML elements.
+ **/
+class ClasslistController extends TypedController<HTMLElement, { subject: HTMLDivElement }>() {
+  static targets = [ "subject" ]
+
+  classList!: string[]
+
+  connect() {
+    let dataset = this.element.dataset
+    this.classList = dataset.classList!.split(" ")
+  }
+
+  add() {
+    for (let subject of this.subjectTargets) {
+      subject.classList.add(...this.classList)
+    }
+  }
+
+  remove() {
+    for (let subject of this.subjectTargets) {
+      subject.classList.remove(...this.classList)
+    }
+  }
+}
+
+application.register("classlist", ClasslistController)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/index.ts.erb

@@ -0,0 +1,4 @@
+// import all your controllers here
+import "./log_controller"
+import "./sleep_controller"
+import "./classlist_controller"

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/log_controller.ts.erb

@@ -0,0 +1,25 @@
+import { application } from "./application"
+import { ChainableController } from "./chainable_controller"
+
+/**
+ * Performs a `console.log` after connecting.
+ * Mainly used in development and for debugging.
+ **/
+class LogController extends ChainableController<HTMLElement> {
+  message!: string
+
+  async init() {
+    let dataset = this.element.dataset
+    this.message = dataset.message!
+    let onEvent = dataset.onEvent
+    if (onEvent) return
+
+    this.log()
+  }
+
+  log() {
+    console.log(this.message)
+  }
+}
+
+application.register("log", LogController)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/sleep_controller.ts.erb

@@ -0,0 +1,19 @@
+import { sleep } from "../utils/misc"
+import { application } from "./application"
+import { ChainableController } from "./chainable_controller"
+
+/**
+ * Sleeps for the given amount of milliseconds.
+ * Useful in controller sequences to delay the execution
+ * of `connect` logic of some other controller.
+ **/
+class SleepController extends ChainableController<HTMLElement> {
+  async init() {
+    let dataset = this.element.dataset
+    let timeout = Number(dataset.timeout)
+
+    await sleep(timeout)
+  }
+}
+
+application.register("sleep", SleepController)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/controllers/typed_controller.ts.erb

@@ -0,0 +1,53 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { Controller } from "@hotwired/stimulus"
+
+type TargetDefinitions = Record<string, HTMLElement>
+
+type StimulusTargetProps<T extends TargetDefinitions> = {
+  [K in keyof T as `${K & string}Target`]: T[K]
+} & {
+  [K in keyof T as `${K & string}Targets`]: T[K][]
+} & {
+  [K in keyof T as `has${Capitalize<K & string>}Target`]: boolean
+}
+
+type AbstractStimulusControllerConstructor = abstract new (...args: any[]) => Controller<any>
+
+export function MakeControllerWithTargetsFactory<TBase extends AbstractStimulusControllerConstructor>(Base: TBase) {
+  return function <
+    TElement extends Element,
+    TTargets extends TargetDefinitions = {},
+  >() {
+    type Props = StimulusTargetProps<TTargets>
+
+    return Base as unknown as abstract new (
+      ...args: ConstructorParameters<TBase>
+    ) => Controller<TElement> & Props
+  }
+}
+
+/**
+ * Main factory function for creating base classes
+ * for typed stimulus controllers.
+ *
+ * In order to use it specify the `Element` type and
+ * a record of target definitions.
+ *
+ * ```
+ *  class MyController extends TypedController<
+ *    HTMLFormElement,
+ *    {
+ *      input: HTMLInputElement,
+ *      submitButton: HTMLElement,
+ *    }
+ *  >() {
+ *    static targets = [ "input", "submitButton" ]
+ *
+ *    connect() {
+ *      console.log("Hello!")
+ *    }
+ *  }
+ * ```
+ */
+export const TypedController = MakeControllerWithTargetsFactory(Controller)

data/lib/generators/phlex/stimulus/install/templates/app/javascript/utils/misc.ts.erb

@@ -0,0 +1,37 @@
+// throws an error when the value is null or undefined
+// otherwise returns the value
+export function must<T>(value: T): NonNullable<T> {
+  if (value === undefined || value === null) {
+    throw new Error('value must be defined')
+  }
+
+  return value
+}
+
+/**
+ * Convert a boolean HTML Element attribute to a JS boolean.
+ */
+export function attrbool(value: unknown): boolean {
+  return value === 'true'
+}
+
+export function sleep(timeout: number | undefined): Promise<void> {
+  if (timeout === undefined) return Promise.resolve()
+
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve()
+    }, timeout)
+  })
+}
+
+/**
+ * Registers an event listener on the given target
+ * and returns a promise that gets resolved when
+ * the event was caught by the listener.
+ */
+export function addEventPromise(target: EventTarget, type: string): Promise<Event> {
+  return new Promise((resolve) => {
+    target.addEventListener(type, (event) => resolve(event))
+  })
+}

data/lib/generators/phlex/stimulus/install/templates/app/javascript/utils/template.ts.erb

@@ -0,0 +1,11 @@
+export function cloneTemplate(id: string): DocumentFragment {
+  let errTemplate = document.querySelector(`template#${id}`) as HTMLTemplateElement
+  return document.importNode(errTemplate.content, true)
+}
+
+export function cloneTemplateInto(templateId: string, targetContainerId: string): DocumentFragment {
+  let container = document.getElementById(targetContainerId)!
+  let newNode = cloneTemplate(templateId)
+  container.appendChild(newNode)
+  return newNode
+}

data/lib/phlex/stimulus/components/base.rb

@@ -0,0 +1,81 @@
+# typed: true
+# frozen_string_literal: true
+
+module Phlex::Stimulus
+  module Components
+    # Abstract class for Phlex components that render HTML with better sorbet and stimulus support.
+    #
+    # @abstract
+    class Base < Phlex::HTML
+      #: -> ApplicationController::HelperProxy
+      def h = view_context
+
+      #: -> String
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      # Constructs a Stimulus event hook string
+      # eg.
+      #
+      #     event('click', 'summary#redirect') #=> "click->summary#redirect"
+      #
+      #: (String, String) -> String
+      def event(event_name, full_action_name)
+        "#{event_name}->#{full_action_name}"
+      end
+
+      # Converts a Ruby boolean to a boolean
+      # value in HTML attributes.
+      #
+      # Returns `"true"` for a truthy value, otherwise `nil`.
+      #
+      #: (bool) -> String?
+      def attrbool(val)
+        'true' if val
+      end
+
+      # Output a single newline character.
+      # If a block is given, a space will be output before and after the block.
+      #
+      #: ?{ -> void } -> void
+      def newline(&block)
+        plain "\n"
+        return unless block
+
+        block.call
+        plain "\n"
+      end
+
+      # Merges the given list of class names (with optional nils)
+      # into a single class string separated by spaces.
+      #
+      #: (*String?) -> String
+      def class_list(*args)
+        buff = String.new
+
+        args.each do |arg|
+          next unless arg
+
+          buff << arg << ' '
+        end
+
+        buff.strip
+      end
+
+      #: (Array[String?]) -> String
+      def class_list!(args)
+        class_list(*T.unsafe(args))
+      end
+
+      alias strlist class_list
+      alias strlist! class_list!
+
+      #: (String) -> bool
+      def image_exists?(path)
+        Boolean(h.resolve_asset_path(path))
+      end
+
+    end
+  end
+end