stimulants

    0.1.2 • Public • Published

    Stimulants 🍸

    NPM version GitHub license Bundle size

    Basic building blocks for Stimulus controllers.

    Extend your controllers by adding and combining modular behaviors. Work in progress.

    Installation

    npm install stimulants

    Usage

    Add the desired behaviors by applying the use functions on your controllers.

    import { Controller } from 'stimulus'
    import { useDebug, useEvents } from 'stimulants'
    
    export default class extends Controller {
      constructor(...args) {
        super(...args)
        useDebug(this)
        useEvents(this)
      }
    
      connect() {
        this.debug('...')
      }
    
      disconnect() {
        this.emit('custom-event', {})
      }
    }

    Behaviors

    useDebug

    Console log helper prefixed with the controller name, disabled in production.

    this.debug('Lorem ipsum dolor sit amet', 42)
    // console.log output in development:
    // [test-controller] Lorem ipsum dolor sit amet  42

    useEvents

    Emit and receive custom DOM events. Useful for communicating between parent-child controllers.

    The emitting controller's identifier is prepended to the event type for namespacing: typecontroller:type

    All event listeners are removed when the controller is disconnected.

    // Dispatch event from 'child' controller
    
    this.emit('custom-event', { lorem: 'ipsum' })
    
    // Listen for event in 'parent' controller
    
    this.on('child:custom-event', ({ detail }) => {
      console.log(detail)
    })
    
    this.once('child:custom-event', () => {
      console.log('I will only run once')
    })

    useInstances

    Track and access all connected instances of the current controller. Useful for sibling communication between controllers.

    Returns an array of instantiated controller objects. If you need to access the controllers' DOM elements, map over the array to pluck the element property.

    // Get all connected instances
    this.instances.forEach(controller => {
      console.log(controller.identifier)
    })
    
    // Get array of DOM elements
    const elements = this.instances.map(controller => controller.element)

    useAnnouncements

    Adds a live region for announcing updates to screen reader users. Great for partial page visits and dynamically loaded content.

    // Announce first heading inside newly fetched content
    const heading = document.querySelector('h1, h2')
    this.announce(heading.textContent || document.title)

    License

    MIT

    Install

    npm i stimulants

    DownloadsWeekly Downloads

    1

    Version

    0.1.2

    License

    MIT

    Unpacked Size

    42.9 kB

    Total Files

    17

    Last publish

    Collaborators

    • daun