@profoundry-us/loco_motion 0.0.8 → 0.5.0

package/README.md

@@ -6,19 +6,45 @@ ViewComponent, TailwindCSS, DaisyUI and more!
 
 <img src="//loco-motion-docs.profoundry.us/images/loco-chats.png" width="500px" style="border: 1px solid #bbb; padding: 2px; border-radius: 10px;">
 
-_**DISCLAIMER**_
+<!-- omit from toc -->
+## DISCLAIMER / CURRENT STATUS
 
 This project is in active development and many changes occur with every release!
-In particular, new Daisy components are being added frequently and older
-components are being updated with new features meaning the APIs are very likely
-to change!
+
+We've added a very basic / untested version of all DaisyUI 4 components. While
+we originally intended to take some time to flesh out and attempt to use these
+components, with the recent release of Tailwind 4 and DaisyUI 5, we feel our
+time is best spent updating all of the components and dependencies for these
+new releases.
+
+This means that we will **NOT** be making any bug fixes to the current branch
+(0.4.0), and will instead include any bug fixes / improvements into the 0.5.0
+branch which will also upgrade to Tailwind 4 and DaisyUI 5.
+
+ - Current Release **(0.4.0)** - Works with DaisyUI 4 and Tailwind 3
+ - Next Release **(0.5.0)** - Will work with DaisyUI 5 and Tailwind 4
+
+<!-- omit from toc -->
+## Additional Notes
+
+### DataInput Components
+
+Many of the DataInput elements (file input, text input, select dropdown, etc)
+were built rather hastily so that we would have a base version to start from.
+
+However, the new DaisyUI 5 components are implemented in a much cleaner way and
+we didn't want to invest too much time building these out and making them more
+ideal since we're about to change them.
+
+### Hosting / Sites
 
 We expect to settle on and purchase a real domain name in the near future, but
 for the time being, the latest documentation is available at the links below.
 
- - [Docs / Demo (Latest Release)][1]
- - [API Docs (Latest Release)][2]
- - [Docs / Demo (Main Branch / Staging)][3]
+ - [Latest Release][1]
+ - [Main / Staging][3]
+
+### Getting Help
 
 Please reach out by opening an
 [Issue](https://github.com/profoundry-us/loco_motion/issues) if you've found a
@@ -47,6 +73,8 @@ your solution is aligned with our goals.
   - [Install](#install)
   - [Using Components](#using-components)
 - [Developing](#developing)
+  - [Contributing](#contributing)
+  - [Releasing](#releasing)
   - [Tooling](#tooling)
 - [TODO / Next Steps](#todo--next-steps)
 
@@ -731,7 +759,7 @@ gem "loco_motion", github: "profoundry-us/loco_motion", branch: "main", require:
 
 # or
 
-gem "loco_motion-rails", "0.0.7", require: "loco_motion"
+gem "loco_motion-rails", "0.4.0", require: "loco_motion"
 ```
 
 Next add the following lines to the `contents` section of your
@@ -856,6 +884,20 @@ See the `Makefile` for all available commands.
 > make demo-restart
 > ```
 
+### Contributing
+
+If you're interested in contributing to LocoMotion, please check out our
+[CONTRIBUTING guide](docs/dev_guides/CONTRIBUTING.md) which provides detailed
+information about the contribution process, code standards, documentation
+requirements, and testing procedures.
+
+### Releasing
+
+For core team members who need to release new versions of LocoMotion, please
+refer to our [RELEASING guide](docs/dev_guides/RELEASING.md) for step-by-step
+instructions on version updates, building, testing, and publishing both the Ruby
+gem and NPM package.
+
 ### Tooling
 
 For VSCode, you may want to add the following to your settings to get
@@ -919,9 +961,9 @@ the GitHub Discussions feature and let us know!
 - [x] Basic versions of DaisyUI Data Display
 - [x] Basic versions of DaisyUI Navigation
 - [x] Basic versions of DaisyUI Feedback
-- [ ] Basic versions of DaisyUI Data Input
-- [ ] Basic versions of DaisyUI Layout
-- [ ] Basic versions of DaisyUI Mockup
+- [x] Basic versions of DaisyUI Data Input
+- [x] Basic versions of DaisyUI Layout
+- [x] Basic versions of DaisyUI Mockup
 - [x] ~~Get YARD docs rendering with (better) Markdown~~ _**Working for now**_
 - [x] Extract relevant pieces into a yard-loco_motion plugin
 - [x] Publish Gem
@@ -932,9 +974,9 @@ the GitHub Discussions feature and let us know!
 - [ ] Choose, recommend, and document a pagination gem
 - [ ] Discuss caching techniques / setup
 - [x] Create / publish a staging version of the demo site ([Demo Staging][2])
-- [ ] Create / publish a staging version of the docs site
-- [ ] Create / publish a production version of the demo site
-- [ ] Create / publish a production version of the docs site
+- [x] Create / publish a staging version of the docs site
+- [x] Create / publish a production version of the demo site
+- [x] Create / publish a production version of the docs site
 - [x] Update demo site to allow for a different docs site using ENV var
 - [x] Update README to suggest Playwright
 - [ ] Build some have docs / guides / examples for using playwright-ruby-client
@@ -946,6 +988,12 @@ the GitHub Discussions feature and let us know!
 - [ ] See if we can update the Join component to auto-add the `join-item` CSS
       under certain conditions
 - [ ] Add title and description content_for blocks to all examples for SEO purposes
+- [ ] Update to Tailwind 4 and DaisyUI 5
+- [ ] Rename the `Dockerfile` to `Dockerfile.loco` to be more concise
+- [x] See if we can remove all of the `set_loco_parent` calls in favor of using
+      the `lib/loco_motion/patches/view_component/slot_loco_parent_patch.rb`
+- [ ] Make the tooltips documentation button a component and use it for the
+      Labelable concern docs too
 
 [1]: https://loco-motion.profoundry.us/
 [2]: https://loco-motion-demo-staging.profoundry.us/

package/app/components/daisy/actions/theme_controller.js

@@ -0,0 +1,113 @@
+/**
+ * Theme Controller
+ *
+ * A Stimulus controller that manages theme selection and persistence.
+ * It handles theme switching, localStorage persistence, and synchronization
+ * across multiple theme selectors on the same page.
+ */
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  /**
+   * Called when the controller is connected to the DOM.
+   * Sets the initial theme input state and sets up event listeners.
+   */
+  connect() {
+    this.setInput()
+
+    // Setup a custom listener to watch for changes on the page in case the
+    // page has multiple theme selectors
+    this.storageChangeListener = this.storageChanged.bind(this)
+
+    window.addEventListener('localstorage-update', this.storageChangeListener)
+  }
+
+  /**
+   * Called when the controller is disconnected from the DOM.
+   * Removes event listeners to prevent memory leaks.
+   */
+  disconnect() {
+    window.removeEventListener('localstorage-update', this.storageChangeListener)
+  }
+
+  /**
+   * Sets the appropriate radio input as checked based on the current theme.
+   * This ensures the UI reflects the active theme.
+   */
+  setInput() {
+    const theme = this.getCurrentTheme()
+    const input = this.element.querySelector(`input[value='${theme}']`);
+
+    if (input) {
+      input.checked = true;
+    }
+  }
+
+  /**
+   * Clears the user's theme preference from localStorage.
+   * Removes the saved theme and dispatches an event to notify other controllers.
+   *
+   * @param {Event} event - The triggering click event
+   */
+  clearTheme(event) {
+    // If we are passed a themeName parameter, clear all inputs with that theme
+    if (event && event.params && event.params.themeName) {
+      const inputs = document.querySelectorAll(`input[name='${event.params.themeName}']`)
+
+      if (inputs) {
+        inputs.forEach(input => {
+          input.checked = false
+        })
+      }
+    }
+
+    // Remove the savedTheme from local storage
+    localStorage.removeItem("savedTheme")
+
+    // Fire off an update
+    const updateEvent = new CustomEvent('localstorage-update', { detail: { key: 'savedTheme', newValue: null } })
+    window.dispatchEvent(updateEvent)
+  }
+
+  /**
+   * Changes the theme based on user selection.
+   * Updates localStorage and dispatches a custom event to notify other controllers.
+   *
+   * @param {Event} event - The triggering click event
+   */
+  setTheme(event) {
+    const input = event.currentTarget.querySelector('input')
+
+    if (input) {
+      localStorage.setItem("savedTheme", input.value)
+
+      const updateEvent = new CustomEvent('localstorage-update', { detail: { key: 'savedTheme', newValue: input.value } })
+      window.dispatchEvent(updateEvent)
+    }
+
+    event.preventDefault();
+  }
+
+  /**
+   * Retrieves the current theme from localStorage.
+   *
+   * @returns {string} The current theme name
+   */
+  getCurrentTheme() {
+    const savedTheme = localStorage.getItem('savedTheme')
+
+    if (savedTheme) {
+      return savedTheme
+    }
+  }
+
+  /**
+   * Event handler for 'localstorage-update' events.
+   * Updates the input state when theme changes in another controller.
+   *
+   * @param {CustomEvent} event - The storage changed event
+   */
+  storageChanged(event) {
+    this.setInput()
+  }
+}

package/app/components/daisy/data_input/cally_input_controller.js

@@ -0,0 +1,235 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Controller for handling calendar input interactions.
+ * Manages the popover calendar UI and synchronization between input and calendar elements.
+ */
+export default class extends Controller {
+  static targets = ["calendar", "input", "popover"]
+
+  /**
+   * Initializes the controller and sets up event listeners.
+   * Binds all methods to ensure proper 'this' context.
+   *
+   * @returns {void}
+   */
+  connect() {
+
+    // Save the bound functions so we can remove them later
+    this.boundUpdateInput = this.updateInput.bind(this)
+    this.boundUpdateCalendar = this.updateCalendar.bind(this)
+    this.boundOpenCalendar = this.openCalendar.bind(this)
+    this.boundCloseCalendar = this.closeCalendar.bind(this)
+    this.boundHandleKeydown = this.handleKeydown.bind(this)
+    this.boundHandleToggle = this.handleToggle.bind(this)
+
+    // Bind all of our functions
+    this.calendarTarget.addEventListener("change", this.boundUpdateInput)
+    this.calendarTarget.addEventListener("blur", this.boundCloseCalendar)
+
+    this.inputTarget.addEventListener("change", this.boundUpdateCalendar)
+    this.inputTarget.addEventListener("keyup", this.boundUpdateCalendar)
+    this.inputTarget.addEventListener("click", this.boundOpenCalendar)
+    this.inputTarget.addEventListener("keydown", this.boundHandleKeydown)
+
+    this.popoverTarget.addEventListener("toggle", this.boundHandleToggle)
+  }
+
+  /**
+   * Cleans up event listeners when the controller is disconnected.
+   * Prevents memory leaks by removing all bound event handlers.
+   *
+   * @returns {void}
+   */
+  disconnect() {
+    this.calendarTarget.removeEventListener("change", this.boundUpdateInput)
+    this.calendarTarget.removeEventListener("blur", this.boundCloseCalendar)
+
+    this.inputTarget.removeEventListener("change", this.boundUpdateCalendar)
+    this.inputTarget.removeEventListener("keyup", this.boundUpdateCalendar)
+    this.inputTarget.removeEventListener("keydown", this.boundHandleKeydown)
+    this.inputTarget.removeEventListener("click", this.boundOpenCalendar)
+    this.popoverTarget.removeEventListener("toggle", this.boundHandleToggle)
+  }
+
+  /**
+   * Opens the calendar popover.
+   *
+   * @returns {void}
+   */
+  openCalendar() {
+    // Open the popover
+    this.popoverTarget.togglePopover(true)
+  }
+
+  /**
+   * Closes the calendar popover if the blur event is not related to calendar elements.
+   *
+   * @param {FocusEvent} event - The blur event object.
+   *
+   * @returns {void}
+   */
+  closeCalendar(event) {
+    // Don't close if we're still in the calendar elements
+    if (event?.relatedTarget && this.calendarTarget.contains(event.relatedTarget)) {
+      return
+    }
+
+    this.popoverTarget.togglePopover(false)
+  }
+
+  /**
+   * Opens the calendar if it is closed, or closes it if it is open.
+   *
+   * @returns {void}
+   */
+  toggleCalendar() {
+    this.popoverTarget.togglePopover()
+  }
+
+  /**
+   * Handles the popover toggle event.
+   * - When opening: Sets a zero-width space in empty inputs to prevent floating label flicker
+   * - When closing: Clears the single-space input to ensure proper floating label behavior
+   *
+   * @param {Event} event - The toggle event object with newState property
+   * @returns {void}
+   */
+  handleToggle(event) {
+    const hasFloatingLabel = this.inputTarget.parentElement.classList.contains("floating-label")
+    const isOpen = event.newState == 'open'
+
+    if (isOpen) {
+      // Make sure the calendar is visible
+      this.scrollCalendarIntoView()
+    }
+
+    if (hasFloatingLabel) {
+      const ZERO_WIDTH_SPACE = '\u200B'
+
+      if (isOpen) {
+        // Set the input to a zero-width space if it is empty to prevent a floating label
+        // flicker when the calendar loses focus while setting the date
+        if (this.inputTarget.value == null || this.inputTarget.value === '') {
+          this.inputTarget.value = ZERO_WIDTH_SPACE;
+        }
+      } else {
+        // Unset the zero-width space input on close so the floating label works again
+        if (this.inputTarget.value === ZERO_WIDTH_SPACE) {
+          this.inputTarget.value = null
+        }
+      }
+    }
+  }
+
+  /**
+   * Ensures the calendar popover is visible within the viewport.
+   *
+   * If the popover extends beyond the viewport edges, scrolls the window to
+   * bring it into view adding any data-auto-scroll-padding.
+   *
+   * @returns {void}
+   */
+  scrollCalendarIntoView() {
+    const rect = this.popoverTarget.getBoundingClientRect()
+    const autoScrollPadding = parseInt(this.popoverTarget.dataset.autoScrollPadding, 10)
+    const padding = isNaN(autoScrollPadding) ? 0 : autoScrollPadding
+
+    if (rect.bottom > window.innerHeight) {
+      window.scrollBy({ top: rect.bottom - window.innerHeight + padding, behavior: 'smooth' })
+    } else if (rect.top < 0) {
+      window.scrollBy({ top: rect.top - padding, behavior: 'smooth' })
+    }
+  }
+
+  /**
+   * Updates the input value from the calendar and closes the popover.
+   * Synchronizes the input field with the selected date.
+   *
+   * @returns {void}
+   */
+  updateInput() {
+    // Update the input value and close the popover
+    this.inputTarget.value = this.calendarTarget.value
+    this.closeCalendar()
+  }
+
+  /**
+   * Handles keyboard navigation for the calendar input.
+   * - SPACE: Toggles the popover
+   * - ENTER: Closes an open popover
+   * - ARROW DOWN / ARROW UP: Opens the popover and focuses the calendar
+   *
+   * @param {KeyboardEvent} event - The keyboard event object.
+   *
+   * @returns {void}
+   */
+  handleKeydown(event) {
+    const hasModifierKeys = event.ctrlKey || event.shiftKey || event.altKey || event.metaKey;
+    const isOpen = this.popoverTarget.matches(':popover-open')
+
+    //
+    // SPACE - Toggles the popover.
+    //
+    if (event.key === ' ' || event.code === 'Space') {
+      event.preventDefault()
+
+      this.toggleCalendar()
+    }
+
+    //
+    // ENTER - Closes an open popover
+    //
+    else if (isOpen && (event.key === 'Enter' || event.code === 'Enter')) {
+      // Stop the enter key from triggering the form submission
+      event.preventDefault()
+
+      this.closeCalendar()
+    }
+
+    //
+    // ARROW DOWN / ARROW UP - Opens the popover and focuses the calendar
+    //
+    else if ((event.key === 'ArrowDown' || event.code === 'ArrowUp') && !hasModifierKeys) {
+      event.preventDefault()
+
+      // If the calendar is not already open, open it
+      if (!isOpen) {
+        this.openCalendar()
+      }
+
+      // Focus the calendar element
+      this.calendarTarget.focus()
+
+      // Forward the keydown event to the calendar
+      const forwardedEvent = new KeyboardEvent('keydown', {
+        key: event.key,
+        code: event.code,
+        bubbles: true,
+        cancelable: true,
+      })
+
+      // Dispatch the forwarded event to the calendar
+      this.calendarTarget.dispatchEvent(forwardedEvent)
+    }
+  }
+
+  /**
+   * Updates the calendar's value based on the input field.
+   * Only updates if the input contains a valid ISO 8601 date.
+   *
+   * @returns {void}
+   */
+  updateCalendar() {
+    // Only update the calendar if we have a full / valid ISO 8601 date
+    let newDate = this.inputTarget.value
+
+    if (newDate.length !== 10 || new Date(newDate).toString() === "Invalid Date") {
+      return
+    }
+
+    // Set the calendar value and focused-date attributes
+    this.calendarTarget.value = newDate
+    this.calendarTarget.setAttribute('focused-date', newDate)
+  }
+}

package/index.js

@@ -1,3 +1,9 @@
+import CallyInputController from './app/components/daisy/data_input/cally_input_controller';
 import CountdownController from './app/components/daisy/data_display/countdown_controller';
+import ThemeController from './app/components/daisy/actions/theme_controller';
 
-export { CountdownController };
+export {
+  CallyInputController,
+  CountdownController,
+  ThemeController,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/loco_motion",
-  "version": "0.0.8",
+  "version": "0.5.0",
   "description": "Crazy fast Rails development!",
   "main": "index.js",
   "repository": {
@@ -14,6 +14,8 @@
   },
   "files": [
     "index.js",
-    "app/components/daisy/data_display/countdown_controller.js"
+    "app/components/daisy/data_input/cally_input_controller.js",
+    "app/components/daisy/data_display/countdown_controller.js",
+    "app/components/daisy/actions/theme_controller.js"
   ]
 }