@stimulus-plumbers/controllers 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @stimulus-plumbers/controllers
+
+Stimulus Plumbers controllers for WCAG 2.1+ compliant UI components.
+
+## Philosophy
+
+**Use native HTML5 first.** Only use controllers when native elements have limitations.
+
+- ✅ `<details>` for disclosures
+- ✅ `<dialog>` for basic modals
+- ✅ **ModalController** for enhanced modals with accessibility features
+
+## Installation
+
+```bash
+npm install @stimulus-plumbers/controllers
+```
+
+## ModalController
+
+Full-featured accessible modal dialog. Supports both native `<dialog>` elements and custom implementations.
+
+```javascript
+import { Application } from '@hotwired/stimulus';
+import { ModalController } from '@stimulus-plumbers/controllers';
+
+const application = Application.start();
+application.register('modal', ModalController);
+```
+
+Native `<dialog>` element:
+```html
+<div data-controller="modal">
+  <button data-action="modal#open">Open Modal</button>
+
+  <dialog data-modal-target="modal" aria-labelledby="modal-title">
+    <h2 id="modal-title">Modal Title</h2>
+    <p>Content...</p>
+    <button data-action="modal#close">Close</button>
+  </dialog>
+</div>
+```
+
+Custom implementation:
+```html
+<div data-controller="modal">
+  <button data-action="modal#open">Open Modal</button>
+
+  <div data-modal-target="overlay" class="modal-overlay" hidden>
+    <div data-modal-target="modal"
+         role="dialog"
+         aria-modal="true"
+         aria-labelledby="modal-title">
+      <h2 id="modal-title">Modal Title</h2>
+      <p>Content...</p>
+      <button data-action="modal#close">Close</button>
+    </div>
+  </div>
+</div>
+```
+
+**Features:**
+- Focus trap with proper cycling
+- Escape key closes
+- Click outside closes
+- Focus restoration
+- Screen reader announcements
+- Body scroll lock (custom implementation)
+
+**Targets:** `modal`, `overlay` (optional)
+**Actions:** `open()`, `close()`
+
+## Utilities
+
+```javascript
+import {
+  // Focus
+  FocusTrap,
+  FocusRestoration,
+  getFocusableElements,
+  focusFirst,
+
+  // ARIA
+  announce,
+  generateId,
+  ensureId,
+  setExpanded,
+  setPressed,
+  setChecked,
+  setDisabled,
+
+  // Keyboard
+  RovingTabIndex,
+  isKey,
+  isActivationKey,
+  isArrowKey,
+  preventDefault
+} from '@stimulus-plumbers/controllers';
+```
+
+**Example:**
+
+```javascript
+import { FocusTrap, announce } from '@stimulus-plumbers/controllers';
+
+export default class extends Controller {
+  connect() {
+    this.trap = new FocusTrap(this.element);
+  }
+
+  open() {
+    this.trap.activate();
+    announce('Panel opened');
+  }
+}
+```
+
+## Additional Controllers (Experimental)
+
+Available but not exported:
+
+- **CalendarMonthController** - Calendar widget with date navigation
+- **FormFieldController** - Dropdown field management
+- **PopoverController** - Content loading and visibility
+- **VisibilityController** - Show/hide with animations (prefer `<details>`)
+- **DismisserController** - Click-outside dismissal
+- **FlipperController** - Element positioning
+- **PannerController** - Scroll management
+
+## Accessibility
+
+All controllers follow:
+- WCAG 2.1 Level AA
+- WAI-ARIA Authoring Practices
+- Keyboard navigation (Tab, Escape, Arrows)
+- Screen reader compatibility
+
+## Browser Support
+
+Chrome, Firefox, Safari, Edge (last 2 versions)
+
+## License
+
+MIT © Ryan Chang