@stimulus-plumbers/controllers 0.2.0 → 0.2.2

package/README.md

@@ -1,14 +1,6 @@
 # @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
+Accessible Stimulus controllers following WCAG 2.1+ standards.
 
 ## Installation
 
@@ -16,128 +8,78 @@ Stimulus Plumbers controllers for WCAG 2.1+ compliant UI components.
 npm install @stimulus-plumbers/controllers
 ```
 
-## ModalController
+Requires `@hotwired/stimulus` ^2.0.0 or ^3.0.0 as a peer dependency.
 
-Full-featured accessible modal dialog. Supports both native `<dialog>` elements and custom implementations.
+## Usage
 
 ```javascript
 import { Application } from '@hotwired/stimulus';
-import { ModalController } from '@stimulus-plumbers/controllers';
+import { ModalController, DatepickerController, CalendarMonthController } from '@stimulus-plumbers/controllers';
 
 const application = Application.start();
 application.register('modal', ModalController);
+application.register('datepicker', DatepickerController);
+application.register('calendar-month', CalendarMonthController);
 ```
 
+### ModalController
+
 Native `<dialog>` element:
+
 ```html
 <div data-controller="modal">
-  <button data-action="modal#open">Open Modal</button>
-
+  <button data-action="modal#open">Open</button>
   <dialog data-modal-target="modal" aria-labelledby="modal-title">
-    <h2 id="modal-title">Modal Title</h2>
-    <p>Content...</p>
+    <h2 id="modal-title">Title</h2>
     <button data-action="modal#close">Close</button>
   </dialog>
 </div>
 ```
 
-Custom implementation:
+Custom implementation with overlay:
+
 ```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#open">Open</button>
+  <div data-modal-target="overlay" hidden>
+    <div data-modal-target="modal" role="dialog" aria-modal="true" aria-labelledby="modal-title">
+      <h2 id="modal-title">Title</h2>
       <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';
-```
+### DatepickerController
 
-**Example:**
+Date picker backed by a calendar grid. Combines `datepicker` + `popover` controllers; uses `CalendarMonthController` as an outlet.
 
-```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');
-  }
-}
+```html
+<div data-controller="datepicker popover"
+     data-datepicker-calendar-month-outlet="[data-controller~='calendar-month']">
+  <input type="text"  data-datepicker-target="display" data-action="focus->popover#show" />
+  <input type="hidden" data-datepicker-target="input" />
+
+  <div data-popover-target="content" hidden>
+    <button data-datepicker-target="previous">Prev</button>
+    <button data-datepicker-target="month"></button>
+    <button data-datepicker-target="year"></button>
+    <button data-datepicker-target="next">Next</button>
+
+    <div data-controller="calendar-month">
+      <div data-calendar-month-target="daysOfWeek"></div>
+      <div data-calendar-month-target="daysOfMonth"></div>
+    </div>
+  </div>
+</div>
 ```
 
-## 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
+## Other Controllers
 
-Chrome, Firefox, Safari, Edge (last 2 versions)
+- `PopoverController` — show/hide content with optional remote loading
+- `DismisserController` — click-outside dismissal
+- `FlipperController` — element positioning
+- `PannerController` — scroll management
 
 ## License