@csedl/hotwire-svelte-helpers 0.1.0

package/.idea/StimulusDropdown-NpmPackage.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/StimulusDropdown-NpmPackage.iml" filepath="$PROJECT_DIR$/.idea/StimulusDropdown-NpmPackage.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/README.md

@@ -0,0 +1,174 @@
+# Stimulus Dropdown
+
+Dropdown with stimulus, based on floating-UI.
+
+**Links:**
+- [Online Demo App](https://stimulus-dropdown.sedlmair.ch/)
+- [Ruby Gem: csedl-stimulus-dropdown](https://gitlab.com/sedl/csedl-stimulus-dropdown)
+- [How we are building a Rails App](https://dev.to/chmich/setup-vite-svelte-inertia-stimulus-bootstrap-foundation-on-rails-7-overview-1bk1)
+
+## Import and config
+
+```javascript
+import {StimulusDropdown} from "@csedl/stimulus-dropdown"
+StimulusDropdown.debug = false
+```
+
+All configurations and their defaults are as follows:
+
+```javascript
+debug: false
+closeButtonSelector: '.close-button'
+dropdownContentSelector: '.content'
+  // when a data-src attribute is added to the panel, the content-tag is replaced by the result of the xhr-response
+tooltipContentSelector: '.content'
+  // same as dropdownContentSelector
+addArrow: true
+  // add element with id #arrow within the panel, on opening
+persistTooltipOnClick: false
+  // clicking on the tooltip-label causes the tooltip-panel to persist open
+  // this may mostly be helpful for development, so you may make it environment-dependent
+```
+
+## Example
+
+There is a [online example app](https://stimulus-dropdown.sedlmair.ch/)
+
+```html
+<div data-controller="csedl-dropdown" data-panel-id="dropdown-panel-3h5k7l4">
+    Button
+</div>
+<div id="dropdown-panel-3h5k7l4" class="hide dropdown-panel-example-class">
+    ... any content
+</div>
+```
+
+## What it does
+
+- When the button is clicked, it toggles the `hide` class on the panel and places the panel using floating-ui.
+- When the panel is open, the `has-open-panel` class is added to the button, otherwise it is removed.
+- Adds functionality to close all panels when clicking outside a panel.
+- When a `data-src` attribute is given to the panel, on opening the panel, it fires a xhr request and replaces the configured  content-tags (see: content-selectors on configs) by the response.
+- This all works with stacked panels too (panel in panel).
+
+## Close on click outside
+
+When a dropdown is open, it closes when clicking outside a panel.
+
+This behaviour can be stopped on:
+
+- The clicked element or its parent elements has the `data-dropdown-persist` (not: `data-dropdown-persist="false"`) attribute.
+- the event has the attribute `event.detail.dataDropdownPersist` set to true.
+
+## Flexibility
+
+The functions of this package are intended to give flexibility on various ways building a dropdown.
+
+- Stimulus Controller with Rails Helper
+  - Example: [Stimulus controller within this package](https://gitlab.com/sedl/csedl-stimulus-dropdown-js/-/blob/main/src/dropdown-controller.js?ref_type=heads)
+- Stimulus with Svelte component
+  - Example: [Stimulus controller on example app](https://gitlab.com/sedl/stimulusfloatingdropdown/-/blob/main/app/frontend/javascript/svelte-dropdown-controller.js?ref_type=heads)
+
+**Important:** When creating or initializing the dropdown, 
+always call the initialize function before attaching a listener to the panel's close event. 
+The initialize function adds a `close` event listener to the panel that executes the `onPanelClose` function. 
+If your custom close function destroys the panel, this has to be done after the `onPanelClose` is fired by the `close` event.
+
+## Requirements
+
+- The class `dropdown-panel-example-class` must be set to `position: absolute;`.
+- The class `hide` must be set to `display: none;`.
+
+## Options
+
+- If there is an element with ID `arrow` inside the dropdown panel, it is treated as described on [floating-ui](https://floating-ui.com/docs/arrow).
+- The `data-placement` attribute on the panel can be used to control positioning, see [floating-ui/placements](https://floating-ui.com/docs/tutorial#placements).
+
+## Events
+
+Events on the button element:
+
+- `place-panel` places the panel, and, if present, the arrow element, by `floating-ui`.
+
+Events the panel element:
+
+- `close` closes the panel.
+- `place-me` like place-panel on the button.
+
+Event Triggers on the button element:
+
+- `before-open-panel`
+- `after-close-panel`
+
+Event Triggers on the panel element:
+
+- `before-open`
+
+## Helpers
+
+If the panels are rendered to a different location than the button (see z-index on [rails-app](https://gitlab.com/sedl/stimulusfloatingdropdown)), within a scrollable (e.g.) container, the button would scroll away from the panel. For such cases, add this both data-attributes to the scrollable element:
+
+```html
+<div data-controller="csedl-place-dropdown-panels" data-on="scroll" data-run-after="500" style="overflow: scroll;">
+    ...
+</div>
+```
+
+Now, on scrolling, it searches for all dropdown-buttons (by class-name `has-open-panel`) and triggers the `place-panel` event there.
+
+**Options**
+
+`data-on` Attribute:
+
+- `scroll` triggered by `scroll` Event of the given element.
+- `resize-observer` triggered by [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) on the given element.
+
+`data-run-after` Attribute:
+
+- Milliseconds as number.
+
+This is only relevant if you have things like `css transition` enabled, so that after the above resize events are fired, subsequent events are needed. It will fire the `place-panel` after the last resize/scroll event within the given time.
+
+**Tip** Turn `console-debug-log` on (see configs) and check how events are working.
+
+**Explanation**
+
+What these helpers mainly do is to find all the dropdowns by the `has-open-panel` class and fire the `place-panel` event. But within the helper, things like performance optimisation are done: it searches once and places the panels multiple times.
+
+## Tooltip
+
+```html
+<span data-controller="csedl-tooltip" data-panel-id="tooltip-123" data-delay="0.2">
+    Text-with-tooltip
+</span>
+<div id="tooltip-123" class="hide tooltip-panel">
+    <div id="arrow"></div>
+    ... any content
+</div>
+```
+
+makes a tooltip.
+
+It adds the class `tooltip-is-visible` to the tooltip label while the tooltip is visible.
+
+`data-src` attribute is working similar to dropdown
+
+## Rails Helpers
+
+There is a corresponding rails gem, on [GitLab](https://gitlab.com/sedl/csedl-stimulus-dropdown)
+
+## Stimulus Usage in stimulus-dropdown
+
+This package uses Stimulus unconventionally to initialize and toggle external dropdown or tooltip panels 
+(via data-panel-id) rather than managing child elements within the controller’s scope, 
+as is typical in Stimulus documentation. 
+
+The same result could be achieved using MutationObserver and plain JavaScript.
+
+Stimulus was chosen because this package is intended for use with Hotwire/Turbo 
+where Stimulus already is installed. It has a modest footprint of just 10 KB. 
+It also holds many configs for MutationObserver, especially for our exact purpose.
+
+**License**
+
+MIT

package/index.js

@@ -0,0 +1,19 @@
+
+import StimulusDropdown from "./src/config.js";
+
+import { Application } from "@hotwired/stimulus"
+window.Stimulus = Application.start()
+
+// initialize dropdowns
+import dc from './src/dropdown-controller'
+Stimulus.register('csedl-dropdown', dc)
+
+// initialize tooltips
+import ttc from './src/tooltip-controller'
+Stimulus.register('csedl-tooltip', ttc)
+
+// initialize place-panel controller
+import ppc from './src/move-panels-controller'
+Stimulus.register('csedl-move-panels', ppc)
+
+export { StimulusDropdown }

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@csedl/hotwire-svelte-helpers",
+  "version": "0.1.0",
+  "description": "Hotwire + Svelte helpers for Rails: Stimulus floating dropdowns/toolips + Svelte global panels/modals + Rails form error mapping + Turbo-friendly utilities. Build together with the rubygem svelte-on-rails and its npm-package.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/sedl/csedl-hotwire-svelte-helpers"
+  },
+  "keywords": [
+    "Stimulus",
+    "Dropdown",
+    "Rails"
+  ],
+  "author": "Christian Sedlmair",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/sedl/csedl-stimulus-dropdown-js/-/issues"
+  },
+  "homepage": "https://gitlab.com/sedl/csedl-stimulus-dropdown-js",
+  "dependencies": {
+    "@floating-ui/dom": ">=1.5.1",
+    "@hotwired/stimulus": ">=3.2.1"
+  }
+}

package/src/config.js

@@ -0,0 +1,114 @@
+import {debugLog} from "./utils.js";
+
+// DEFAULTS
+let _debug = false;
+let _close_button_selector = '.close-button';
+let _dropdown_content_selector = '.content';
+let _tooltip_content_selector = '.content';
+let _add_arrow = true;
+let _persist_tooltip_on_click = false;
+
+let _close_on_click_outside_listener_added = false;
+
+const StimulusDropdown = {
+
+    // debug
+
+    get debug() {
+        return _debug;
+    },
+    set debug(value) {
+        if (typeof value !== "boolean") {
+            throw new Error("Debug value must be true or false");
+        }
+        _debug = value;
+        debugLog('debugging active')
+    },
+
+    // close button selector
+
+    get closeButtonSelector() {
+        return _close_button_selector;
+    },
+    set closeButtonSelector(string) {
+        if (typeof string !== "string") {
+            throw new Error("Close Button Selector must be a string");
+        }
+        _close_button_selector = string;
+        debugLog(`close button selector is: «${string}»`);
+    },
+
+    // content selector
+
+    get dropdownContentSelector() {
+        return _dropdown_content_selector;
+    },
+    set dropdownContentSelector(string) {
+        if (typeof string !== "string") {
+            throw new Error("Content Selector must be a string");
+        }
+        _dropdown_content_selector = string;
+        debugLog(`dropdown content selector is: «${string}»`);
+    },
+
+    // tooltip content selector
+
+    get tooltipContentSelector() {
+        return _tooltip_content_selector;
+    },
+    set tooltipContentSelector(string) {
+        if (typeof string !== "string") {
+            throw new Error("Tooltip Content Selector must be a string");
+        }
+        _tooltip_content_selector = string;
+        debugLog(`tooltip content selector is: «${string}»`);
+    },
+
+    // add arrow
+
+    get addArrow() {
+        return _add_arrow;
+    },
+    set addArrow(boolean) {
+        if (typeof boolean !== "boolean") {
+            throw new Error("Tooltip Content Selector must be a string");
+        }
+        _add_arrow = boolean;
+        debugLog(`add-arrow is set to: «${boolean}»`);
+    },
+
+    // add arrow
+
+    get persistTooltipOnClick() {
+        return _persist_tooltip_on_click;
+    },
+    set persistTooltipOnClick(boolean) {
+        if (typeof boolean !== "boolean") {
+            throw new Error("Tooltip Content Selector must be a string");
+        }
+        _persist_tooltip_on_click = boolean;
+        debugLog(`Persist tooltip on click is set to: «${boolean}»`);
+    },
+
+    // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+    // INTERNAL USE
+    // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    // closeOnClickOutsideListenerAdded
+
+    get closeOnClickOutsideListenerAdded() {
+        return _close_on_click_outside_listener_added;
+    },
+    set closeOnClickOutsideListenerAdded(bool) {
+        if (typeof bool !== "boolean") {
+            throw new Error("closeOnClickOutsideListenerAdded must be a boolean");
+        }
+        _close_on_click_outside_listener_added = bool;
+        debugLog(`closeOnClickOutsideListenerAdded is: «${bool}»`);
+    },
+
+};
+
+window.StimulusDropdown = StimulusDropdown;
+
+export default StimulusDropdown;

package/src/dropdown-controller.js

@@ -0,0 +1,59 @@
+import {Controller} from "@hotwired/stimulus"
+import {initializeDropdown, onPanelOpen} from "./utils.js";
+import {debugLog} from "./utils.js";
+
+export default class extends Controller {
+
+    connect() {
+
+        initializeDropdown(this.element)
+
+        this.element.addEventListener('click', (e) => this.toggle(e))
+
+    }
+
+
+    toggle(e) {
+        if (this.element.getAttribute('data-prevent-default')) {
+            e.preventDefault()
+        }
+        e.stopPropagation()
+        debugLog('toggle panel', e)
+        const target_id = this.element.getAttribute('data-panel-id')
+        const panel = document.getElementById(target_id)
+        if (!panel) {
+            console.error(`Panel-element with ID ${target_id} not found`)
+        } else if (panel.style.display === 'block') {
+            this.close(panel)
+        } else {
+            this.open(e, panel)
+        }
+    }
+
+    open(e, panel) {
+
+        // open the panel
+
+        panel.style.display = 'block';
+        debugLog('opened panel:', panel)
+
+        onPanelOpen(e, this.element)
+
+        panel.addEventListener('close', () => this.close(panel))
+
+    }
+
+    close(panel) {
+
+        // Close actions
+
+        panel.style.display = 'none';
+        debugLog('panel closed:', panel)
+
+    }
+
+
+}
+
+
+

package/src/floating-ui-functions.js

@@ -0,0 +1,106 @@
+import {arrow, computePosition, flip, offset, shift} from "@floating-ui/dom";
+import {debugLog} from "./utils.js";
+
+// Positions a panel relative to its trigger button
+export function positionPanelByButton(button, logContext) {
+    const toggleId = button.getAttribute('data-panel-id')
+    let panel = document.getElementById(toggleId)
+    positionPanel(button, panel)
+    debugLog('panel positioned', logContext)
+}
+
+// Positions a panel using its event listener
+export function positionPanelSelf(panel) {
+    let button = document.querySelector(`[data-panel-id="${panel.id}"]`)
+    positionPanel(button, panel)
+}
+
+// Retrieves all currently open panels within a scope element
+export function getAllOpenPanels(scopeElement) {
+    const buttons = scopeElement.getElementsByClassName('has-open-panel')
+    const elements = []
+
+    for (const button of buttons) {
+        if (button.getAttribute('data-controller') === 'csedl-dropdown') {
+            const getOrSetPanelId = button.getAttribute('data-panel-id')
+            const panel = document.getElementById(getOrSetPanelId)
+            elements.push([button, panel])
+        }
+    }
+
+    debugLog(`FOUND ${elements.length} OPEN DROPDOWNS`)
+
+    return (elements)
+}
+
+// Positions all provided panel-button pairs
+export function positionAllPanels(elements) {
+    for (const el of elements) {
+        positionPanel(el[0], el[1])
+    }
+}
+
+// Positions a single panel relative to its button
+export function positionPanel(button, panel) {
+    let arrowElement = panel.querySelector('#arrow')
+    panel.style.removeProperty('height')
+    panel.style.removeProperty('left')
+    panel.style.removeProperty('top')
+    let placementAttr = panel.getAttribute('data-placement')
+    let placement = (placementAttr ? placementAttr : 'bottom')
+    debugLog(`placement: «${placement}»`)
+
+    computePosition(button, panel, {
+        middleware: [flip(), offset(6), shift({padding: 5}), arrow({element: arrowElement})],
+        placement: placement
+    }).then(({x, y, placement, middlewareData}) => {
+        Object.assign(panel.style, {
+            left: `${x}px`,
+            top: `${y}px`,
+        });
+
+        if (arrowElement) {
+            // ARROW
+            const {x: arrowX, y: arrowY} = middlewareData.arrow;
+            const staticSide = {
+                top: 'bottom',
+                right: 'left',
+                bottom: 'top',
+                left: 'right',
+            }[placement.split('-')[0]];
+            Object.assign(arrowElement.style, {
+                left: arrowX != null ? `${arrowX}px` : '',
+                top: arrowY != null ? `${arrowY}px` : '',
+                right: '',
+                bottom: '',
+                [staticSide]: '-4px',
+            });
+            debugLog(`panel + arrow positioned`)
+        } else {
+            debugLog(`panel positioned`)
+        }
+
+        adjustToWindowBounds(button, panel)
+    });
+}
+
+// Adjusts panel to prevent overflow beyond window boundaries
+function adjustToWindowBounds(button, panel) {
+    if (button.getAttribute('data-constrain-to-window-borders') === 'true') {
+        const rect = panel.getBoundingClientRect();
+
+        if (rect.top < 0) {
+            const newTop = parseFloat(panel.style.top) + Math.abs(rect.top) + 2
+            console.log('constrain top', 'actual top:', panel.style.top, 'absolute top:', rect.top, 'new top:', newTop)
+            panel.style.top = `${newTop}px`
+        }
+
+        const rect2 = panel.getBoundingClientRect();
+
+        if (rect2.bottom > window.innerHeight) {
+            console.log('constrain height')
+            const height = window.innerHeight - rect2.top - 2
+            panel.style.height = `${height}px`
+        }
+    }
+}

package/src/move-panels-controller.js

@@ -0,0 +1,99 @@
+import {Controller} from "@hotwired/stimulus"
+import {positionAllPanels, getAllOpenPanels} from "./floating-ui-functions";
+import {debugLog} from "./utils.js";
+
+export default class extends Controller {
+
+    elements_to_place = null
+
+    connect() {
+        const on = this.element.getAttribute('data-on')
+
+        if (on.includes('scroll')) {
+            this.element.addEventListener('scroll', () => {
+                this.handle_placement('scroll')
+            })
+        }
+
+        if (on.includes('resize-observer')) {
+
+            var resize_observer = new ResizeObserver(entries => {
+                for (let entry of entries) {
+                    this.handle_placement('resize-observer')
+                }
+            });
+
+            resize_observer.observe(this.element)
+        }
+    }
+
+    handle_placement(trigger_label) {
+        if (this.elements_to_place === null) {
+            this.elements_to_place = getAllOpenPanels(this.element)
+            this.element.setAttribute('csedl-place-all-first-done-time', performance.now())
+        }
+
+        if (this.elements_to_place.length === 0) {
+            this.cleanup()
+
+        } else {
+            const c = Number(this.element.getAttribute('csedl-place-all-counter'))
+            this.element.setAttribute('csedl-place-all-counter', c + 1)
+            const first_run = Number(this.element.getAttribute('csedl-place-all-first-done-time'))
+
+            debugLog(`place panels by ${trigger_label} ${c} / ${performance.now() - first_run}ms: x: ${this.element.offsetWidth} y: ${this.element.offsetHeight}`)
+            positionAllPanels(this.elements_to_place)
+            this.element.setAttribute('csedl-place-all-done-time', performance.now())
+            this.setup_run_after_event()
+        }
+    }
+
+    setup_run_after_event() {
+        if (this.element.hasAttribute('data-run-after')) {
+            const run_after_str = this.element.getAttribute('data-run-after')
+            const run_after = Number(run_after_str)
+            if (isNaN(run_after)) {
+                console.error(`the data-run-after attribute must be a valid positive number (integer for milliseconds) but is: «${run_after_str}»`, this.element)
+            } else if (run_after < 0.0) {
+                console.error(`the data-run-after attribute must be a positive number (integer for milliseconds) but is: «${run_after_str}»`, this.element)
+            } else {
+                if (this.element.getAttribute('csedl-run-after-is-active')) {
+                    debugLog('place-panel run-after is already installed (nothing to do)')
+                } else {
+                    this.element.setAttribute('csedl-run-after-is-active', true)
+                    this.element.setAttribute('csedl-place-all-counter', 0)
+                    setTimeout(() => this.handle_placement_after(), 50);
+                    debugLog('place-panel run-after INSTALLED')
+                }
+            }
+        }
+    }
+
+    handle_placement_after() {
+        const run_after = Number(this.element.getAttribute('data-run-after'))
+        const last_run = Number(this.element.getAttribute('csedl-place-all-done-time'))
+        const c = Number(this.element.getAttribute('csedl-place-all-counter'))
+        this.element.setAttribute('csedl-place-all-counter', c + 1)
+        const running_time = performance.now() - last_run
+
+        positionAllPanels(this.elements_to_place)
+        debugLog(`PLACEMENT FOLLOW-UP ${c}: ${running_time}ms / ${run_after}ms`)
+
+        if (running_time < run_after) {
+            setTimeout(() => this.handle_placement_after(), 50);
+
+        } else {
+            this.cleanup()
+        }
+    }
+
+    cleanup() {
+        this.element.removeAttribute('csedl-place-all-done-time')
+        this.element.removeAttribute('csedl-place-all-first-done-time')
+        this.element.removeAttribute('csedl-place-all-counter')
+        this.element.removeAttribute('csedl-run-after-is-active')
+        this.elements_to_place = null
+        debugLog('FINISHED placement follow-up')
+    }
+
+}

package/src/tooltip-controller.js

@@ -0,0 +1,62 @@
+import {Controller} from "@hotwired/stimulus"
+import {positionPanelByButton} from "./floating-ui-functions.js";
+import {debugLog, onPanelOpen} from "./utils.js";
+
+export default class extends Controller {
+
+    opening_timer_id = null
+
+    connect() {
+        const panel_id = this.element.getAttribute('data-panel-id')
+        if (!panel_id) {
+            console.error(`Attribute data-panel-id missing`, this.element)
+        }
+        const delay_sec = parseFloat(this.element.getAttribute('data-delay'))
+        if (!delay_sec) {
+            console.error('missing required attribute: data-delay', this.element)
+        }
+        this.element.addEventListener('mouseenter', (e) => this.start_opening(e, panel_id, delay_sec * 1000))
+        this.element.addEventListener('mouseleave', (e) => this.close(e, panel_id))
+        if (window.StimulusDropdown.persistTooltipOnClick) {
+            this.element.addEventListener('click', (e) => this.toggleByClick(e, panel_id))
+        }
+    }
+
+    start_opening(e, panel_id, delay_ms) {
+        if (this.element.hasAttribute('data-tooltip-click')) { return; }
+        this.opening_timer_id = setTimeout(() => this.open(e, panel_id), delay_ms)
+    }
+
+    toggleByClick(e, panel_id) {
+        const stat = this.element.getAttribute('data-tooltip-click')
+        if (stat === 'open') {
+            debugLog('closing by click')
+            this.element.removeAttribute('data-tooltip-click')
+            this.close(e, panel_id)
+        } else {
+            debugLog('opening by click')
+            this.open(e, panel_id)
+            this.element.setAttribute('data-tooltip-click', 'open')
+        }
+    }
+
+    open(e, panel_id) {
+        this.element.classList.add('tooltip-is-visible')
+        onPanelOpen(e, this.element)
+        this.opening_timer_id = null
+        let panel = document.getElementById(panel_id)
+        panel.style.display = 'block';
+        positionPanelByButton(this.element)
+    }
+
+    close(e, panel_id) {
+        if (this.element.hasAttribute('data-tooltip-click')) { return; }
+        this.element.classList.remove('tooltip-is-visible')
+        if (this.opening_timer_id) {
+            clearTimeout(this.opening_timer_id)
+        }
+        let panel = document.getElementById(panel_id)
+        panel.style.display = 'none';
+    }
+
+}

package/src/utils.js

@@ -0,0 +1,226 @@
+import {positionPanelSelf, positionPanelByButton} from "./floating-ui-functions.js";
+
+// Fetch content from server based on panel's data-src attribute and update content
+export function onPanelOpen(event, button) {
+
+    const panel = findPanel(button);
+
+    debugLog('ON-PANEL-OPEN FUNCTIONS')
+
+    closeOnOutsideClick(event)
+
+    // add arrow
+    if (window.StimulusDropdown.addArrow) {
+        if (!panel.querySelector(':scope > #arrow')) {
+            const arrowTag = document.createElement('div');
+            arrowTag.id = 'arrow';
+            panel.appendChild(arrowTag)
+        }
+    }
+
+    positionPanelByButton(button);
+
+    // Set focus to input element
+    if (panel.hasAttribute('data-set-focus')) {
+        let dataFocus = panel.getAttribute('data-set-focus');
+        let focusElement = panel.querySelector(dataFocus);
+        focusElement.focus();
+    }
+
+    // Set status attribute
+    panel.setAttribute('data-stimulus-dropdown-panel-status', 'open');
+    button.classList.add('has-open-panel');
+
+    // Dispatch events
+    const panelOpenEvent = new CustomEvent('before-open');
+    panel.dispatchEvent(panelOpenEvent);
+
+    const buttonOpenEvent = new CustomEvent('before-open-panel');
+    button.dispatchEvent(buttonOpenEvent);
+
+    // Add listener for closing on outside click
+    if (!window.StimulusDropdown.closeOnClickOutsideListenerAdded) {
+        window.StimulusDropdown.closeOnClickOutsideListenerAdded = true;
+        window.addEventListener('click', closeOnOutsideClick);
+        debugLog('Listener for close panels on click outside added');
+    }
+
+    // fetch content from server
+    const src = panel.getAttribute('data-src');
+    if (src) {
+        let xhr = new XMLHttpRequest();
+        debugLog(`Panel / data-src: «${src}»`);
+        xhr.open('GET', src);
+        xhr.send();
+        xhr.onload = function () {
+            if (xhr.status !== 200) {
+                alert(`Dropdown Controller, GET «${src}», Error ${xhr.status}: ${xhr.statusText}`);
+            } else {
+                const button = document.querySelector(`[data-panel-id="${panel.id}"]`);
+                const ctrl = button.getAttribute('data-controller');
+                const config = window.StimulusDropdown;
+                const contentSelector = config.dropdownContentSelector;
+
+                if (ctrl === 'csedl-dropdown' && contentSelector) {
+                    debugLog(`dropdown / contentSelector: «${contentSelector}»`);
+                    const wrapper = panel.querySelector(contentSelector);
+                    wrapper.innerHTML = xhr.response;
+                } else if (ctrl === 'csedl-tooltip' && contentSelector) {
+                    debugLog(`tooltip / contentSelector: «${contentSelector}»`);
+                    const wrapper = panel.querySelector(config.tooltipContentSelector);
+                    wrapper.innerHTML = xhr.response;
+                } else {
+                    debugLog(`? / contentSelector: «${contentSelector}»`);
+                    panel.innerHTML = xhr.response;
+                    console.error('fallback to replace whole panel');
+                }
+
+                positionPanelByButton(button, `after http-request "${ctrl}"`);
+            }
+        };
+    } else {
+        debugLog('no data-src attribute provided on panel');
+    }
+}
+
+// Handle panel closing
+export function onPanelClose(button) {
+
+    const panel = findPanel(button);
+
+    debugLog('ON-PANEL-CLOSE FUNCTIONS')
+
+    // Update status attributes
+    button.classList.remove('has-open-panel');
+    panel.setAttribute('data-stimulus-dropdown-panel-status', 'closed');
+
+    // Remove outside click listener if no panels are open
+    const openPanels = document.querySelectorAll("[data-stimulus-dropdown-panel-status='open']");
+    debugLog(`panel closed, still open: ${openPanels.length}`);
+    if (window.StimulusDropdown.closeOnClickOutsideListenerAdded && openPanels.length === 0) {
+        window.StimulusDropdown.closeOnClickOutsideListenerAdded = false;
+        window.removeEventListener('click', closeOnOutsideClick);
+        debugLog('Listener for close panels on click outside removed');
+    }
+
+    // Dispatch close event
+    let buttonCloseEvent = new CustomEvent('after-close-panel');
+    button.dispatchEvent(buttonCloseEvent);
+}
+
+// Close panels when clicking outside
+export function closeOnOutsideClick(ev) {
+
+    let btn = ev.target;
+    let parentPanelIds = [];
+
+    const persistElement = ev.target.closest('[data-dropdown-persist]');
+    if (persistElement) {
+        if (persistElement.getAttribute('data-dropdown-persist') !== 'false') {
+            debugLog('closing panel prevented because the target element has attribute "data-dropdown-persist"');
+            return false;
+        }
+    }
+
+    debugLog('closeOnOutsideClick called, event.target:', ev.target);
+
+    while (true) {
+        const parentPanel = btn.closest("[data-stimulus-dropdown-panel-status='open']");
+        if (parentPanel) {
+            parentPanelIds.push(parentPanel.id);
+            btn = document.querySelector(`[data-panel-id="${parentPanel.id}"]`);
+        } else {
+            break;
+        }
+    }
+
+    const openPanels = document.querySelectorAll("[data-stimulus-dropdown-panel-status='open']");
+    for (const panel of openPanels) {
+        if (!parentPanelIds.includes(panel.id)) {
+            const ev = new Event('close');
+            panel.dispatchEvent(ev);
+        }
+    }
+}
+
+// Add panel functionality, including close event listeners
+export function initializeDropdown(button) {
+
+    // find panel
+    const panel_id = button.getAttribute('data-panel-id');
+    if (!panel_id) {
+        throw new Error(`data-panel-id attribute is not defined for given dropdown button`);
+    }
+    const panel = document.getElementById(panel_id);
+    if (!panel) {
+        throw new Error(`panel element not found by ID: «${panel_id}»`);
+    }
+
+    // Add close button functionality
+    const selector = window.StimulusDropdown.closeButtonSelector;
+    const closeButtons = panel.querySelectorAll(selector);
+    for (const btn of closeButtons) {
+        btn.addEventListener('click', () => {
+            const ev = new Event('close');
+            panel.dispatchEvent(ev);
+        });
+    }
+
+    // Add event listeners to panel
+    panel.addEventListener('place-me', () => positionPanelSelf(panel));
+    button.addEventListener('place-panel', () => positionPanelByButton(button))
+    panel.addEventListener('close', () => onPanelClose(button))
+
+    debugLog(`Initialized dropdown, panel-ID: «${panel_id}»`);
+}
+
+// xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+// LOGGER
+// xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+export function debugLog(message, object) {
+    if (window.StimulusDropdown.debug) {
+
+        if (object) {
+            console.log(`[stimulus-dropdown] ${message}`, object);
+
+        } else {
+            console.log(`[stimulus-dropdown] ${message}`);
+        }
+
+    }
+}
+
+// xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+// ADDITIONAL FUNCTIONS
+// utils that are not used for the primary functions of this package itself, but helpful for building associated functions
+// xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+
+// find or add the data-panel-id attribute of a button and return it
+export function getOrSetPanelId(buttonTag) {
+    let id = buttonTag.getAttribute('data-panel-id')
+    if (id) {
+        return (id)
+    } else {
+        id = `dropdown-panel-${generateRandomHex(8)}`
+        buttonTag.setAttribute('data-panel-id', id)
+        return id
+    }
+}
+
+
+function generateRandomHex(n) {
+    if (n <= 0) return '';
+    return Array.from({length: n}, () =>
+        Math.floor(Math.random() * 16).toString(16)
+    ).join('');
+}
+
+function findPanel(button) {
+    const panel = document.getElementById(button.getAttribute('data-panel-id'))
+    if (!panel) {
+        throw new Error(`dropdown button not found by attribute data-panel-id: «${button.getAttribute('data-panel-id')}»`)
+    }
+    return(panel)
+}