proscenium-ui 0.1.0 → 0.2.0

checksums.yaml

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

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

@@ -0,0 +1,3 @@
+@layer pui {
+  @mixin base from url('./mixin.css');
+}

data/lib/proscenium/ui/dropdown/index.js

@@ -0,0 +1,181 @@
+import WebComponent from '../web_component'
+
+const SUPPORTS_POPOVER =
+  typeof HTMLElement !== 'undefined' && typeof HTMLElement.prototype.showPopover === 'function'
+
+export class Dropdown extends WebComponent {
+  static componentName = 'pui-dropdown'
+  static actions = { click: ['toggle'], keydown: ['onTriggerKey'] }
+
+  #originalParent = null
+  #originalNextSibling = null
+  #cleanupPosition = null
+
+  connectedCallback() {
+    super.connectedCallback()
+
+    this.fui = import('@floating-ui/dom')
+    this.$container?.addEventListener('toggle', this.#onToggle)
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback()
+
+    if (this.$container?.parentNode === document.body) {
+      this.$container.remove()
+    }
+
+    this.$container?.removeEventListener('toggle', this.#onToggle)
+    this.#removeListeners()
+  }
+
+  handleEvent(event) {
+    if (event.type === 'blur' && event.target === globalThis) {
+      this.close()
+    }
+  }
+
+  toggle = () => {
+    this.isOpen ? this.close() : this.open()
+  }
+
+  onTriggerKey = event => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      this.toggle()
+    }
+  }
+
+  #onToggle = event => {
+    if (event.newState !== 'closed' || !this.isOpen) return
+
+    this.close()
+
+    const ae = document.activeElement
+    if (ae === document.body || this.contains(ae)) {
+      this.$trigger.focus()
+    }
+  }
+
+  open() {
+    if (this.isOpen) return
+
+    this.#showContainer()
+    this.dataset.open = true
+    this.$container.dataset.open = true
+    this.$trigger.setAttribute('aria-expanded', 'true')
+    this.#startPositionUpdates()
+    this.#addListeners()
+  }
+
+  close = () => {
+    if (!this.isOpen) return
+
+    delete this.dataset.open
+    delete this.$container.dataset.open
+    this.$trigger.setAttribute('aria-expanded', 'false')
+
+    this.#cleanupPosition?.()
+    this.#cleanupPosition = null
+
+    this.#hideContainer()
+    this.#removeListeners()
+  }
+
+  get isOpen() {
+    return 'open' in this.dataset
+  }
+
+  #showContainer() {
+    if (SUPPORTS_POPOVER) {
+      this.$container.showPopover()
+    } else {
+      this.#originalParent = this.$container.parentNode
+      this.#originalNextSibling = this.$container.nextSibling
+      document.body.append(this.$container)
+    }
+  }
+
+  #hideContainer() {
+    if (SUPPORTS_POPOVER) {
+      this.$container.hidePopover()
+    } else if (this.#originalParent) {
+      this.#originalParent.insertBefore(this.$container, this.#originalNextSibling)
+      this.#originalParent = null
+      this.#originalNextSibling = null
+    }
+  }
+
+  #addListeners() {
+    window.addEventListener('blur', this, { once: true })
+  }
+
+  #removeListeners() {
+    window.removeEventListener('blur', this, { once: true })
+  }
+
+  async #startPositionUpdates() {
+    const { computePosition, offset, flip, shift, arrow, autoUpdate } = await this.fui
+
+    const update = () => {
+      computePosition(this.$trigger, this.$container, {
+        strategy: 'fixed',
+        placement: 'bottom-start',
+        middleware: [offset(6), flip(), shift({ padding: 5 }), arrow({ element: this.$arrow })]
+      }).then(({ x, y, placement, middlewareData }) => {
+        Object.assign(this.$container.style, {
+          left: `${x}px`,
+          top: `${y}px`
+        })
+
+        const { x: arrowX, y: arrowY } = middlewareData.arrow
+        const side = placement.split('-')[0]
+        const staticSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[side]
+        const outerBorders = {
+          bottom: ['borderLeft', 'borderTop'],
+          top: ['borderRight', 'borderBottom'],
+          right: ['borderLeft', 'borderBottom'],
+          left: ['borderTop', 'borderRight']
+        }[side]
+        const border =
+          '1px solid var(--pui-dropdown-border-color, color-mix(in srgb, CanvasText 20%, transparent))'
+
+        Object.assign(this.$arrow.style, {
+          left: arrowX == null ? '' : `${arrowX}px`,
+          top: arrowY == null ? '' : `${arrowY}px`,
+          right: '',
+          bottom: '',
+          borderTop: '',
+          borderRight: '',
+          borderBottom: '',
+          borderLeft: '',
+          [staticSide]: '-4px',
+          [outerBorders[0]]: border,
+          [outerBorders[1]]: border
+        })
+      })
+    }
+
+    const cleanup = autoUpdate(this.$trigger, this.$container, update)
+
+    if (this.isOpen) {
+      this.#cleanupPosition = cleanup
+    } else {
+      cleanup()
+    }
+  }
+
+  get $trigger() {
+    return (this._$trigger ??= this.querySelector('pui-dropdown-trigger'))
+  }
+
+  get $container() {
+    return (this._$container ??= this.querySelector('pui-dropdown-container'))
+  }
+
+  get $arrow() {
+    return (this._$arrow ??= this.$container.querySelector('pui-dropdown-arrow'))
+  }
+}
+
+WebComponent.register(Dropdown)

data/lib/proscenium/ui/dropdown/mixin.css

@@ -0,0 +1,95 @@
+/*
+ * Properties:
+ *
+ *   --pui-dropdown-background: Canvas;
+ *   --pui-dropdown-color: CanvasText;
+ *   --pui-dropdown-border-color: color-mix(in srgb, CanvasText 20%, transparent);
+ *   --pui-dropdown-shadow:
+ *     0 0 15px color-mix(in srgb, CanvasText 10%, transparent),
+ *     0 5px 15px color-mix(in srgb, CanvasText 7%, transparent);
+ *   --pui-dropdown-max-height: min(20em, 70vh);
+ */
+
+@define-mixin base {
+  pui-dropdown-trigger {
+    @mixin trigger;
+  }
+
+  pui-dropdown-container {
+    @mixin container;
+  }
+
+  pui-dropdown-body {
+    @mixin body;
+  }
+
+  pui-dropdown-arrow {
+    @mixin arrow;
+  }
+}
+
+@define-mixin trigger {
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+
+  &:focus-visible {
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
+  }
+}
+
+@define-mixin container {
+  background-color: var(--pui-dropdown-background, Canvas);
+  color: var(--pui-dropdown-color, CanvasText);
+  box-shadow: var(
+    --pui-dropdown-shadow,
+    0 0 15px color-mix(in srgb, CanvasText 10%, transparent),
+    0 5px 15px color-mix(in srgb, CanvasText 7%, transparent)
+  );
+  padding: 6px 0;
+  border-radius: 4px;
+  width: max-content;
+  position: fixed;
+  inset: auto;
+  top: 0;
+  left: 0;
+  margin: 0;
+  display: none;
+  overflow: visible;
+  border: 1px solid
+    var(--pui-dropdown-border-color, color-mix(in srgb, CanvasText 20%, transparent));
+  opacity: 0;
+  transition:
+    opacity 120ms ease,
+    display 120ms allow-discrete,
+    overlay 120ms allow-discrete;
+  z-index: 1000;
+
+  &[data-open] {
+    display: block;
+    opacity: 1;
+  }
+
+  @starting-style {
+    &[data-open] {
+      opacity: 0;
+    }
+  }
+}
+
+@define-mixin body {
+  display: block;
+  max-height: var(--pui-dropdown-max-height, min(20em, 70vh));
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+@define-mixin arrow {
+  position: absolute;
+  background: var(--pui-dropdown-background, Canvas);
+  width: 8px;
+  height: 8px;
+  transform: rotate(45deg);
+  box-sizing: border-box;
+}

data/lib/proscenium/ui/dropdown.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Proscenium::UI
+  class Dropdown < Component
+    register_element :pui_dropdown
+    register_element :pui_dropdown_trigger
+    register_element :pui_dropdown_container
+    register_element :pui_dropdown_body
+    register_element :pui_dropdown_arrow
+
+    def self.source_path
+      (super || superclass.source_path) / '../dropdown/index.rb'
+    end
+
+    def trigger_template
+      raise NotImplementedError,
+            "`#trigger_template` must be implemented in subclasses of #{self.class}"
+    end
+
+    def dropdown_template
+      raise NotImplementedError,
+            "`#dropdown_template` must be implemented in subclasses of #{self.class}"
+    end
+
+    def view_template = base_template
+
+    private
+
+      def host_element = :pui_dropdown
+      def trigger_haspopup = 'true'
+      def container_role = nil
+
+      def base_template
+        container_id = "pui-dd-#{object_id}"
+
+        send(host_element) do
+          pui_dropdown_trigger(
+            tabindex: 0,
+            role: 'button',
+            aria_haspopup: trigger_haspopup,
+            aria_expanded: 'false',
+            aria_controls: container_id,
+            on_click: :toggle,
+            on_keydown: :onTriggerKey,
+            &:trigger_template
+          )
+
+          pui_dropdown_container(id: container_id, role: container_role, popover: :auto) do
+            pui_dropdown_body(&:dropdown_template)
+            pui_dropdown_arrow
+          end
+        end
+      end
+  end
+end

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

@@ -0,0 +1,3 @@
+@layer pui {
+  @mixin base from url('./mixin.css');
+}

data/lib/proscenium/ui/dropdown_menu/index.js

@@ -0,0 +1,96 @@
+import WebComponent from '../web_component'
+import { Dropdown } from '../dropdown/index.js'
+
+const TYPEAHEAD_TIMEOUT = 500
+
+class DropdownMenu extends Dropdown {
+  static componentName = 'pui-dropdown-menu'
+
+  #typeBuffer = ''
+  #typeTimer = null
+
+  connectedCallback() {
+    super.connectedCallback()
+    this.$container?.addEventListener('keydown', this.#onMenuKey)
+    this.$container?.addEventListener('click', this.#onMenuClick)
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback()
+    this.$container?.removeEventListener('keydown', this.#onMenuKey)
+    this.$container?.removeEventListener('click', this.#onMenuClick)
+  }
+
+  open() {
+    if (this.isOpen) return
+    super.open()
+    queueMicrotask(() => {
+      const items = this.#items()
+      if (items.length > 0) items[0].focus()
+    })
+  }
+
+  #onMenuKey = event => {
+    const items = this.#items()
+    if (items.length === 0) return
+
+    const current = items.indexOf(document.activeElement)
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault()
+        this.#focusAt(items, current + 1)
+        break
+      case 'ArrowUp':
+        event.preventDefault()
+        this.#focusAt(items, current - 1)
+        break
+      case 'Home':
+        event.preventDefault()
+        this.#focusAt(items, 0)
+        break
+      case 'End':
+        event.preventDefault()
+        this.#focusAt(items, items.length - 1)
+        break
+      case 'Tab':
+        this.close()
+        break
+      default:
+        if (event.key.length === 1 && /\S/.test(event.key)) {
+          this.#typeahead(event.key.toLowerCase(), items)
+        }
+    }
+  }
+
+  #onMenuClick = event => {
+    const item = event.target.closest('[role="menuitem"]')
+    if (!item || item.getAttribute('aria-disabled') === 'true') return
+    this.close()
+  }
+
+  #focusAt(items, index) {
+    const wrapped = ((index % items.length) + items.length) % items.length
+    items[wrapped].focus()
+  }
+
+  #items() {
+    return Array.from(
+      this.$container.querySelectorAll('[role="menuitem"]:not([aria-disabled="true"])')
+    )
+  }
+
+  #typeahead(char, items) {
+    clearTimeout(this.#typeTimer)
+    this.#typeBuffer += char
+    this.#typeTimer = setTimeout(() => {
+      this.#typeBuffer = ''
+    }, TYPEAHEAD_TIMEOUT)
+
+    const buffer = this.#typeBuffer
+    const match = items.find(item => item.textContent.trim().toLowerCase().startsWith(buffer))
+    if (match) match.focus()
+  }
+}
+
+WebComponent.register(DropdownMenu)

data/lib/proscenium/ui/dropdown_menu/mixin.css

@@ -0,0 +1,63 @@
+/*
+ * Properties:
+ *
+ *   --pui-dropdown-menu-item-hover-bg: color-mix(in srgb, CanvasText 8%, transparent);
+ *   --pui-dropdown-menu-item-active-bg: SelectedItem;
+ *   --pui-dropdown-menu-item-active-color: SelectedItemText;
+ *   --pui-dropdown-menu-item-disabled-opacity: 0.5;
+ */
+
+@define-mixin base {
+  pui-dropdown-menu {
+    @mixin host;
+  }
+}
+
+@define-mixin host {
+  [role='menuitem'] {
+    display: block;
+    box-sizing: border-box;
+    padding: 0.4em 0.8em;
+    color: inherit;
+    text-decoration: none;
+    cursor: pointer;
+    background: none;
+    border: none;
+    width: 100%;
+    text-align: inherit;
+    font: inherit;
+
+    &:hover {
+      background-color: var(
+        --pui-dropdown-menu-item-hover-bg,
+        color-mix(in srgb, CanvasText 8%, transparent)
+      );
+    }
+
+    &:focus-visible {
+      outline: none;
+      background-color: var(--pui-dropdown-menu-item-active-bg, SelectedItem);
+      color: var(--pui-dropdown-menu-item-active-color, SelectedItemText);
+    }
+
+    &[aria-disabled='true'] {
+      cursor: default;
+      opacity: var(--pui-dropdown-menu-item-disabled-opacity, 0.5);
+
+      &:hover {
+        background-color: transparent;
+      }
+    }
+
+    @media (pointer: coarse) {
+      padding: 0.7em 1em;
+    }
+  }
+
+  hr {
+    border: 0;
+    border-top: 1px solid
+      var(--pui-dropdown-border-color, color-mix(in srgb, CanvasText 20%, transparent));
+    margin: 0.25em 0;
+  }
+}

data/lib/proscenium/ui/dropdown_menu.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Proscenium::UI
+  class DropdownMenu < Dropdown
+    register_element :pui_dropdown_menu
+
+    def self.source_path
+      Pathname(__FILE__).sub_ext('').join('index.rb')
+    end
+
+    def menu_template
+      raise NotImplementedError,
+            "`#menu_template` must be implemented in subclasses of #{self.class}"
+    end
+
+    def dropdown_template
+      menu_template
+    end
+
+    def item(href: nil, disabled: false, **attrs, &)
+      base = { role: 'menuitem', tabindex: -1, **attrs }
+      if disabled
+        span(**base, aria_disabled: 'true', &)
+      elsif href
+        a(href: href, **base, &)
+      else
+        button(type: :button, **base, &)
+      end
+    end
+
+    private
+
+      def host_element = :pui_dropdown_menu
+      def trigger_haspopup = 'menu'
+      def container_role = 'menu'
+  end
+end

data/lib/proscenium/ui/flash/index.js

@@ -1,59 +1,55 @@
-import domMutations from "dom-mutations";
-import { Sourdough, toast } from "sourdough-toast";
-
-export function foo() {
-  console.log("foo");
-}
+import domMutations from 'dom-mutations'
+import { Sourdough, toast } from 'sourdough-toast'
 
 class HueFlash extends HTMLElement {
-  static observedAttributes = ["data-flash-alert", "data-flash-notice"];
+  static observedAttributes = ['data-flash-alert', 'data-flash-notice']
 
   connectedCallback() {
-    this.#initSourdough();
+    this.#initSourdough()
   }
 
   async #initSourdough() {
-    if ("sourdoughBooted" in window) return;
+    if ('sourdoughBooted' in window) return
 
     const sourdough = new Sourdough({
       richColors: true,
-      yPosition: "bottom",
-      xPosition: "center",
-    });
-    sourdough.boot();
-    window.sourdoughBooted = true;
+      yPosition: 'bottom',
+      xPosition: 'center'
+    })
+    sourdough.boot()
+    window.sourdoughBooted = true
 
-    // Watch for changes to htl:flashes meta tag
-    const flashesSelector = "meta[name='rails:flashes']";
+    // Watch for changes to rails:flashes meta tag
+    const flashesSelector = "meta[name='rails:flashes']"
     for await (const mutation of domMutations(document.head, {
       childList: true,
       subtree: true,
-      attributes: true,
+      attributes: true
     })) {
-      let $ele = null;
+      let $ele = null
 
       if (
-        mutation.type === "attributes" &&
-        mutation.target.nodeName == "META" &&
-        mutation.attributeName == "content"
+        mutation.type === 'attributes' &&
+        mutation.target.nodeName == 'META' &&
+        mutation.attributeName == 'content'
       ) {
-        $ele = mutation.target;
-      } else if (mutation.type === "childList") {
+        $ele = mutation.target
+      } else if (mutation.type === 'childList') {
         for (const node of mutation.addedNodes) {
           if (node.matches(flashesSelector)) {
-            $ele = node;
-            break;
+            $ele = node
+            break
           }
         }
       }
 
       if ($ele) {
-        const flashes = JSON.parse($ele.getAttribute("content"));
+        const flashes = JSON.parse($ele.getAttribute('content'))
         for (const [type, message] of Object.entries(flashes)) {
-          if (type === "alert") {
-            toast.error(message);
-          } else if (type === "notice") {
-            toast.success(message);
+          if (type === 'alert') {
+            toast.error(message)
+          } else if (type === 'notice') {
+            toast.success(message)
           }
         }
       }
@@ -61,17 +57,16 @@ class HueFlash extends HTMLElement {
   }
 
   attributeChangedCallback(name, _oldValue, newValue) {
-    this.#initSourdough();
+    this.#initSourdough()
 
-    if (newValue === null) return;
+    if (newValue === null) return
 
-    if (name === "data-flash-alert") {
-      toast.warning(newValue);
-    } else if (name === "data-flash-notice") {
-      toast.success(newValue);
+    if (name === 'data-flash-alert') {
+      toast.warning(newValue)
+    } else if (name === 'data-flash-notice') {
+      toast.success(newValue)
     }
   }
 }
 
-!customElements.get("pui-flash") &&
-  customElements.define("pui-flash", HueFlash);
+!customElements.get('pui-flash') && customElements.define('pui-flash', HueFlash)

data/lib/proscenium/ui/form/fields/select.rb

@@ -161,7 +161,7 @@ module Proscenium::UI::Form::Fields
       def option_text_and_value(option)
         # Options are [text, value] pairs or strings used for both.
         if !option.is_a?(String) && option.respond_to?(:first) && option.respond_to?(:last)
-          option = option.reject { |e| e.is_a?(Hash) } if option.is_a?(Array)
+          option = option.grep_v(Hash) if option.is_a?(Array)
           [option.first, option.last]
         else
           [option, option]

data/lib/proscenium/ui/version.rb

@@ -2,6 +2,6 @@
 
 module Proscenium
   module UI
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

data/lib/proscenium/ui/web_component.js

@@ -0,0 +1,497 @@
+const debug = proscenium.env.RAILS_ENV === 'development'
+
+// Supported action events
+const actionEvents = new Set([
+  'click',
+  'focusin',
+  'keydown',
+  'keyup',
+  'change',
+  'submit',
+  'beforeinput',
+  'input',
+  'dragstart',
+  'dragover',
+  'drop',
+  'dragend'
+])
+
+/**
+ * Extend any component with the ability to register itself as a custom element and listen for
+ * actions defined in the HTML.
+ *
+ * ### Usage
+ *
+ * A basic component can be defined and registered like this, where the required `componentName`
+ * static variable is a unique name for the component:
+ *
+ * ```javascript
+ * Component.register(
+ *   class extends WebComponent {
+ *     static componentName = 'my-component'
+ *   }
+ * )
+ * ```
+ *
+ * Registering a component is required to use it in HTML, and is atomic, so it can be called
+ * multiple times without side effects.
+ *
+ * Finally insert your component into the page, using the `componentName` you gave it earlier:
+ *
+ * ```html
+ * <my-component></my-component>
+ * ```
+ *
+ * ### Actions
+ *
+ * WebComponent provides the ability to define 'actions' that can be triggered by events on the
+ * component. Actions are a convenient way to define events directly in the HTML, without needing to
+ * manually add and remove event listeners.
+ *
+ * Actions are defined as an object with event types as keys and an array of action names as values.
+ * The action names are the names of the methods on the component that will be called when the event
+ * is triggered.
+ *
+ * ```javascript
+ * Component.register(
+ *   class extends WebComponent {
+ *     static componentName = 'my-component'
+ *     static actions = { click: ['doSomething'] }
+ *
+ *     doSomething(event, target) {
+ *       console.log('Hello, world!')
+ *     }
+ *   }
+ * )
+ * ```
+ *
+ * The above component can be used as follows, where `doSomething` will be called when the button is
+ * clicked. The `doSomething` method will receive the event that triggered the action and the target
+ * of the event as arguments.
+ *
+ * ```html
+ * <my-component>
+ *   <button on-click="doSomething">Click me</button>
+ * </my-component>
+ * ```
+ *
+ * See `actionEvents` for the supported event types.
+ *
+ * ### Targets
+ *
+ * All elements with a `data-target` attribute are available via instance properties. For example,
+ * an element with `data-target="menu"` will create `$menuTarget` and `$menuTargets` properties.
+ * Where `$menuTarget` will be the first matching element, and `$menuTargets` will be an array of
+ * all matching elements.
+ *
+ * These properties are created on demand via a Proxy, so they are "live" — they always reflect the
+ * current DOM state. You can override a target property by explicitly setting it on the instance.
+ *
+ * ### Values
+ *
+ * All elements with a `data-value` attribute are available via instance properties. For example, an
+ * element with `data-value="count"` will create a `countValue` property. This property is reactive,
+ * so setting it will update the text content of the element, and changing the text content of the
+ * element will update the property.
+ *
+ * ### Observed Attributes
+ *
+ * Any attributes defined in the static `observedAttributes` array will be observed for changes as
+ * per the custom elements standard, and when they change, a method with the name of the attribute
+ * in camelCase with 'Changed' appended will be called. For example, an attribute of `data-open`
+ * will call the method `dataOpenChanged(oldValue, newValue)` when it changes.
+ */
+class WebComponent extends HTMLElement {
+  /**
+   * Register the component as a defined custom element.
+   *
+   * @param {Class} klass - The class to register as a custom element. If not given, the class this
+   *   method is called on will be registered.
+   * @param {...Function} extendables - Any mixins to apply to the class before registering it.
+   *   Deprecated in favour of `withMixins()` which correctly handles the order of mixins in a class
+   *   hierarchy.
+   * @throws {TypeError} If the static variable `componentName` is not defined.
+   */
+  static register(klass, ...extendables) {
+    function defineCustomElement(klass) {
+      if (klass.componentName === undefined) {
+        throw new TypeError('`componentName` must be defined when extending WebComponent')
+      }
+
+      if (!customElements.get(klass.componentName)) {
+        debug && console.debug(`[WebComponent] Registered: ${klass.componentName}`)
+        customElements.define(klass.componentName, klass)
+      }
+    }
+
+    if (klass === undefined) {
+      defineCustomElement(this)
+    } else {
+      if (extendables.length > 0) {
+        console.warn(
+          'Passing mixins to WebComponent.register()` is deprecated. Please use `WebComponent.withMixins()` instead to ensure correct mixin order.'
+        )
+
+        extendables.forEach(extendable => {
+          klass = extendable(klass)
+        })
+      }
+
+      // If the class being registered has its own observedAttributes, we need to merge them with
+      // the ones from WebComponent. This is because when a class defines its own
+      // observedAttributes, it completely overrides the parent's value, which for some mixins,
+      // means the mixin won't work if the property is not merged.
+      if (Object.getPrototypeOf(klass).observedAttributes) {
+        klass.observedAttributes = [
+          ...klass.observedAttributes,
+          ...Object.getPrototypeOf(klass).observedAttributes
+        ]
+      }
+
+      defineCustomElement(klass)
+    }
+  }
+
+  /**
+   * A helper method for applying mixins to a WebComponent class. Mixins should be functions that
+   * take a class and return a new class that extends it. For example:
+   *
+   * ```javascript
+   * function MyMixin(superClass) {
+   *   return class extends superClass {
+   *     myMethod() {
+   *       console.log('Hello, world!')
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * You can then apply this mixin to a WebComponent class like this:
+   *
+   * ```javascript
+   * class MyComponent extends WebComponent.withMixins(MyMixin) {
+   *   static componentName = 'my-component'
+   * }
+   * ```
+   *
+   * You can apply multiple mixins by passing them as additional arguments to `withMixins()`, and
+   * they will be applied in reverse order. For example:
+   *
+   * ```javascript
+   * class MyComponent extends WebComponent.withMixins(MyMixin1, MyMixin2) {
+   *   static componentName = 'my-component'
+   * }
+   * MyComponent.register()
+   * ```
+   *
+   * @param {...Function} mixins - The mixins to apply to the class.
+   *
+   * @returns {Class} A new class that extends the original class with the mixins applied.
+   */
+  static withMixins(...mixins) {
+    let observedAttributes = []
+    let klass = this
+
+    mixins.reverse().forEach(mixin => {
+      klass = mixin(klass)
+      if (klass.observedAttributes) {
+        observedAttributes = [...observedAttributes, ...klass.observedAttributes]
+      }
+    })
+
+    klass.observedAttributes = observedAttributes
+
+    return klass
+  }
+
+  static actions = []
+
+  #hasActions = new Set()
+
+  componentName = this.constructor.componentName
+
+  constructor() {
+    super()
+    this.actions = this.constructor.actions
+  }
+
+  connectedCallback() {
+    this.#listenForActions()
+    this.#createValues()
+  }
+
+  disconnectedCallback() {
+    this.#unlistenForActions()
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    const callbackName = `${camelCase(name)}Changed`
+    if (callbackName in this) {
+      this[callbackName](oldValue, newValue)
+    }
+  }
+
+  /**
+   * Listen for an event on this component with the name of `eventName`. This accepts the same
+   * arguments as `addEventListener`, but with a few niceties.
+   *
+   * If `eventName` is prefixed with a colon, the component name will be prepended to it. This is
+   * useful for namespacing events to the component. For example, an event name of ':clickOutside'
+   * on a component with name of 'my-component' will be converted to 'my-component:clickOutside'.
+   * All other event names are passed through untouched.
+   *
+   * If `eventName` is prefixed with a caret, it will be listened for on the document instead of the
+   * component, but the callback will still be on the component instance. For example, `^click` will
+   * listen for 'click' events on the document, but call the callback on the component instance.
+   * This is a convenient syntax for listening globally - on the document, while still keeping the
+   * callback logic within the component.
+   *
+   * Any event that contains a colon will be listened for on the `document` instead of the
+   * component, which means you can use this same listen/dispatch API within any component to listen
+   * for events on any other component.
+   *
+   * If `callback` is not provided, the component will listen for the event on itself and call the
+   * `handleEvent` method when the event is triggered (as per the `addEventListener` logic).
+   *
+   * If `callback` is not given as the second argument, you can pass the options object as the
+   * instead. For example: `listen('click', { capture: true })`.
+   *
+   * If `handleEvent` is used, and the event is namespaced to the component, the method with the
+   * same name as the event type will be called. For example, if the event type is
+   * 'my-component:click', the method `onClick` will be called. This avoids you having to define
+   * `handleEvent`, and simply define the methods for each event type.
+   *
+   * @param {String} eventName
+   * @param {Function | Object#handleEvent | Object} callback - The function to call when the event
+   *   is triggered. Defaults to `this`.
+   * @param {Object} options - Options to pass to `addEventListener`
+   */
+  // eslint-disable-next-line no-unused-vars
+  listen(eventName, callback, options = {}) {
+    const listenerArgs = this.#buildEventListenerArguments(...arguments)
+
+    if (listenerArgs[0].startsWith('^')) {
+      listenerArgs[0] = listenerArgs[0].slice(1)
+      document.addEventListener(...listenerArgs)
+    } else if (listenerArgs[0].includes(':')) {
+      document.addEventListener(...listenerArgs)
+    } else {
+      this.addEventListener(...listenerArgs)
+    }
+  }
+
+  /**
+   * Unlisten for an event on this component with the name of `eventName`. This accepts the same
+   * arguments as the `listen()` method above.
+   *
+   * @param {String} eventName
+   * @param {Function | Object#handleEvent | Object} callback - The function to call when the event
+   *   is triggered.
+   * @param {Object} options - Options to pass to `addEventListener`
+   */
+  // eslint-disable-next-line no-unused-vars
+  unlisten(eventName, callback, options = {}) {
+    const listenerArgs = this.#buildEventListenerArguments(...arguments)
+
+    if (listenerArgs[0].startsWith('^')) {
+      listenerArgs[0] = listenerArgs[0].slice(1)
+      document.removeEventListener(...listenerArgs)
+    } else if (listenerArgs[0].includes(':')) {
+      document.removeEventListener(...listenerArgs)
+    } else {
+      this.removeEventListener(...listenerArgs)
+    }
+  }
+
+  /**
+   * Dispatch a custom event on this component. This is a wrapper around the native `dispatchEvent`
+   * method, but with some niceties.
+   *
+   * If `eventName` is prefixed with a colon, the component name will be prepended to it. This is
+   * useful for namespacing events to the component. For example, an event name of ':clickOutside'
+   * on a component with name of 'my-component' will be converted to 'my-component:clickOutside'.
+   * All other event names are passed through untouched.
+   *
+   * If the converted `eventName` is prefixed with the current component name and colon, events will
+   * be dispatched on the component. Eg. `my-component:clickOutside` will be dispatched on the
+   * `my-component` instance.
+   *
+   * @param {String} eventName - The name of the event to dispatch.
+   * @param {Object} options - Options for the event.
+   * @param {boolean} options.cancelable - Whether the event is cancelable.
+   * @param {any} options.detail - The detail to include with the event.
+   *
+   * @returns {CustomEvent} The dispatched event.
+   */
+  dispatch(eventName, { cancelable, detail } = {}) {
+    if (eventName.startsWith(':')) {
+      eventName = this.constructor.componentName + eventName
+    }
+
+    const event = new CustomEvent(eventName, {
+      bubbles: true,
+      composed: true,
+      cancelable,
+      detail
+    })
+
+    if (eventName.startsWith(`${this.constructor.componentName}:`)) {
+      this.dispatchEvent(event)
+    } else {
+      document.dispatchEvent(event)
+    }
+
+    return event
+  }
+
+  /**
+   * Handle an event triggered on this component. This is called automatically when an event is
+   * triggered on the component, and can be overridden to provide custom logic.
+   *
+   * If a function with the same name as the event type exists on the component, it will be called.
+   * For example, if the event type is 'click' or 'my-component:click', the method `onClick` will be
+   * called.
+   *
+   * @param {Event} event - The event that was triggered.
+   *
+   * @returns {boolean} Whether the event was handled. This allows you to override this method while
+   *   still calling the parent method. For example: `super.handleEvent(event) || ...`
+   */
+  handleEvent(event) {
+    let { type } = event
+    if (type.includes(':')) {
+      type = type.slice(type.indexOf(':') + 1)
+    }
+
+    if (this['on' + capitalize(type)]) {
+      this['on' + capitalize(type)](event)
+
+      return true
+    }
+
+    return false
+  }
+
+  $(x) {
+    return this.querySelector(x)
+  }
+
+  $$(x) {
+    return Array.from(this.querySelectorAll(x))
+  }
+
+  // Create reactive value properties
+  #createValues() {
+    this.querySelectorAll('[data-value]').forEach($ele => {
+      const prop = `${$ele.dataset.value}Value`
+      if (!(prop in this)) {
+        Object.defineProperty(this, prop, {
+          get: () => $ele.textContent,
+          set: v => {
+            $ele.textContent = v
+          }
+        })
+      }
+    })
+  }
+
+  #listenForActions() {
+    Object.entries(this.actions).forEach(([type, actions]) => {
+      // Warn if the action type is unknown. See `actionEvents`.
+      if (!actionEvents.has(type)) {
+        console.warn(
+          '%c[WebComponent]%c Unknown action: %o for %o',
+          'font-weight: bold',
+          'font-weight: normal',
+          type,
+          this.constructor.componentName
+        )
+        return
+      }
+
+      // Type is defined, but no actions are given, so ignore.
+      if (actions.length === 0) return
+
+      this.#hasActions.add(type)
+      this.addEventListener(type, this.#handleAction)
+    })
+  }
+
+  #unlistenForActions() {
+    this.#hasActions.forEach(type => {
+      this.removeEventListener(type, this.#handleAction)
+    })
+  }
+
+  #handleAction = event => {
+    if (!Object.keys(this.actions).includes(event.type)) return
+
+    const actionAttr = `on-${event.type}`
+    const target = event.target.closest(`[${actionAttr}]`)
+
+    if (!target) return
+
+    const action = target.getAttribute(actionAttr)
+
+    if (this.actions[event.type].includes(action)) {
+      if (this[action] === undefined) {
+        throw new TypeError(
+          `Function for action '${action}' is not defined in ${this.constructor.name}`
+        )
+      }
+
+      this[action](event, target)
+    }
+  }
+
+  #buildEventListenerArguments(eventName, callback, options) {
+    if (callback === undefined) {
+      callback = this
+    } else if (isPlainObject(callback)) {
+      options = callback
+      callback = this
+    }
+
+    if (eventName.startsWith(':')) {
+      eventName = this.constructor.componentName + eventName
+    }
+
+    return [eventName, callback, options]
+  }
+}
+
+// Proxy the prototype to lazily resolve $<name>Target and $<name>Targets properties from the DOM.
+Object.setPrototypeOf(
+  WebComponent.prototype,
+  new Proxy(Object.getPrototypeOf(WebComponent.prototype), {
+    get(target, prop, receiver) {
+      if (typeof prop === 'string' && !Object.hasOwn(receiver, prop)) {
+        let match
+        if ((match = prop.match(/^\$(.+)Targets$/))) {
+          return receiver.$$(`[data-target="${match[1]}"]`)
+        }
+        if ((match = prop.match(/^\$(.+)Target$/))) {
+          return receiver.$(`[data-target="${match[1]}"]`)
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    }
+  })
+)
+
+function isPlainObject(value) {
+  if (Object.prototype.toString.call(value) !== '[object Object]') return false
+
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === null || prototype === Object.prototype
+}
+
+export function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+export function camelCase(str) {
+  return str.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+}
+
+export default WebComponent

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proscenium-ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Joel Moss
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.1
+        version: 1.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.1
+        version: 1.9.0
 - !ruby/object:Gem::Dependency
   name: phonelib
   requirement: !ruby/object:Gem::Requirement
@@ -105,6 +105,14 @@ files:
 - lib/proscenium/ui/combobox/index.css
 - lib/proscenium/ui/combobox/index.js
 - lib/proscenium/ui/component.rb
+- lib/proscenium/ui/dropdown.rb
+- lib/proscenium/ui/dropdown/index.css
+- lib/proscenium/ui/dropdown/index.js
+- lib/proscenium/ui/dropdown/mixin.css
+- lib/proscenium/ui/dropdown_menu.rb
+- lib/proscenium/ui/dropdown_menu/index.css
+- lib/proscenium/ui/dropdown_menu/index.js
+- lib/proscenium/ui/dropdown_menu/mixin.css
 - lib/proscenium/ui/flash.rb
 - lib/proscenium/ui/flash/index.css
 - lib/proscenium/ui/flash/index.js
@@ -149,6 +157,7 @@ files:
 - lib/proscenium/ui/ujs/data_disable_with.js
 - lib/proscenium/ui/ujs/index.js
 - lib/proscenium/ui/version.rb
+- lib/proscenium/ui/web_component.js
 homepage: https://proscenium.rocks
 licenses:
 - MIT